git.stella-ops.org/docs/modules/policy/contracts/spine-versioning-plan.md

SBOM/VEX Spine Versioning Plan (SP1)

Purpose

Establish versioned spine API/DTO schemas with migration rules, determinism guarantees, and DSSE-backed manifests, covering SP1–SP10 gaps from the 31-Nov-2025 findings advisory.

Scope

• Spine APIs and DTOs shared by Scanner, Policy, Authority, and Graph.
• Manifest/signing layers for spine bundles (online + offline).
• Pagination/performance envelopes and Unknowns workflow.

Deliverables (SP tasks)

• SP1: Versioned schemas + header/version negotiation rules; deprecation timetable.
• SP2: Evidence requirements per predicate/edge (reachability proof, package identity, build metadata) with MUST/SHOULD fields.
• SP3: Unknowns registry contract (states, SLA, surfacing rules, expiry/decay).
• SP4: DSSE-signed spine manifest listing hashes for all artifacts; Rekor/mirror policy hooks.
• SP5: Deterministic diff rules + fixtures (ordered deltas, canonical sorting, hash expectations).
• SP6: Feed snapshot freshness/staleness thresholds and validation steps.
• SP7: Stage-by-stage DSSE requirements, Rekor/mirror policy matrices (online/offline).
• SP8: Policy lattice version field and embedding rules in spine objects.
• SP9: Pagination/ordering/perf budgets (stable sort keys, default page size limits, deterministic cursors).
• SP10: Crosswalk mappings SBOM ↔ VEX ↔ graph ↔ policy (table + sample payloads).

Acceptance/verification artifacts

• Adapter CSV: docs/modules/policy/fixtures/spine-adapters/v2-to-v1.csv (hashes in hashes.txt).
• Crosswalk table: docs/modules/policy/fixtures/spine-crosswalk/crosswalk.csv (hashes in hashes.txt).
• Manifest signing proof: DSSE envelope must reference adapter + crosswalk hashes to anchor deterministic migrations.

Migration & Determinism

• Version headers and DTO version fields must be required; rejects if missing or downgraded without declared adapter.
• Canonical JSON ordering for manifests; hashes computed over canonical form (UTF-8, no BOM).
• Pagination uses deterministic primary/secondary sort keys; cursors are opaque, HMAC-free, reproducible from sort key + last id.

Versioning mechanics (v0.1)

• Header: X-Spine-Version: v1 (required). DTO field mirror: schemaVersion (string, semver).
• Deprecation window: N-1 supported for 90 days; adapters required to downgrade v2→v1 (CSV in docs/modules/policy/fixtures/spine-adapters/).
• Hashing: canonical JSON, sorted properties, UTF-8 no BOM, normalized decimals (4dp), timestamps UTC ISO-8601.
• Hash anchors (2025-12-03): v2-to-v1.csv BLAKE3=f259a807fae1cac90c4d52223924d808eb52a4ab2cb0d314ab2d651bfdad4273 SHA256=f5f067bd7814bd65213610a5ae4a35ce98e70a990ca1eb86d275a8abd3659a1a.

Evidence minima per edge (SP2, draft)

• reachability: state, confidence, score, method, evidenceRef (hash or URI), runtimeEvidence flag (bool).
• package_identity: purl, name, version, supplier, hashes[] (at least SHA256).
• build_metadata: buildId, sourceRepo, sourceRef, buildInvokerHash, provenanceHash (DSSE).
• Ordering: edges sorted by subjectPurl, predicate, createdAt for determinism; missing evidenceRef is invalid.

Unknowns workflow (SP3, draft)

• States: unknown, under_review, resolved, expired.
• SLA: auto-review escalation after 7 days; decay to expired at 30 days unless refreshed.
• Surfacing: APIs must include unknowns.count and list endpoint with deterministic pagination; optional policy lattice flag to penalize unknowns.
• Determinism: cursors encode the last subjectPurl + createdAt; no random salts.

Signing (SP4/SP7)

• Manifest structure: list of artifacts (type, id, hash, version, uri), signed using DSSE/ED25519 by default; Rekor optional online, mirrored checkpoints offline.
• Stage policy: compile → ingest → materialize → export; each stage produces DSSE, carries prior stage hash for chain-of-custody.
• Rekor/mirror matrix: online → Rekor+transparency required; offline → mirror checkpoints and DSSE only. PQ dual-sign optional but recorded in manifest metadata.

Pagination/perf budgets (SP9)

• Default page size 200; max 500; stable sort: tenant asc, subjectPurl asc, advisoryId asc, createdAt asc.
• Cursors: base64-encoded tuple of sort keys; must round-trip deterministically.
• Perf budget: p95 response ≤250ms for page=200 on cached dataset; timeouts return deterministic error spine_timeout.
• Rate limits: 600 rpm per tenant; 429 payload includes retry-after seconds and last stable cursor.

Crosswalk (SP10)

• Provide table mapping: SBOM component ↔ spine node ↔ graph node ↔ policy evaluation input; include sample payloads in docs/modules/policy/fixtures/spine-crosswalk/.
• Hash anchors (2025-12-03): crosswalk.csv BLAKE3=41926241c6d60bb856ceb4498e70381cdf54217435740f5fdf31ff8964044d78 SHA256=1e6644cdc00097b7e959e75f522335326b8f48fe1d05060d1c06ba660aac22a3.

Decisions (2025-12-03)

• Evidence minima above are binding for SP2; missing hashes are fatal validation errors.
• Unknowns decay schedule adopted as written; extension requires policy-lattice approval.
• Stage DSSE is mandatory at every boundary; Rekor optional offline but checkpoints must be mirrored with manifest hash list.
• Pagination budgets and rate limits frozen until next version bump; adapters must preserve ordering when downgrading.

Signing & Offline

• DSSE envelope mandatory for spine manifest; Rekor entry optional online, mirrored checkpoints for offline kits.
• Mirror bundles carry: manifest hash list, time-anchor digest, toolkit hashes, version map for adapters.

Open Items

• Finalize evidence minima per predicate with Signals/Reachability guild once runtime schema lands.
• Confirm lattice versioning alignment with policy engine release cadence.

Links

• Sprint: docs/implplan/SPRINT_0186_0001_0001_record_deterministic_execution.md (SP1–SP10)
• Advisory: docs/product-advisories/31-Nov-2025 FINDINGS.md