# 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).

## 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.

### 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).

### 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.

### 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.

### 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.

### Crosswalk (SP10)
- Provide table mapping: SBOM component ↔ spine node ↔ graph node ↔ policy evaluation input; include sample payloads in `docs/modules/policy/fixtures/spine-crosswalk/`.

## 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`