prep docs and service updates

docs/modules/sbomservice/architecture.md

@@ -15,8 +15,28 @@
   - `sbom_snapshots` (immutable versions; tenant + artifact + digest + createdAt)
   - `sbom_projections` (materialised views keyed by snapshotId, entrypoint/service node flags)
   - `sbom_assets` (asset metadata, criticality/owner/env/exposure; append-only history)
-  - `sbom_paths` (resolved dependency paths with runtime flags, blast-radius hints)
-  - `sbom_events` (outbox for event delivery + watermark/backfill tracking)
+- `sbom_paths` (resolved dependency paths with runtime flags, blast-radius hints)
+- `sbom_events` (outbox for event delivery + watermark/backfill tracking)
+
+### 2.1) SBOM + provenance spine (Nov 2026)
+
+The service now owns an idempotent spine that converts OCI images into SBOMs and provenance bundles with DSSE and in-toto. The flow is intentionally air-gap ready:
+
+- **Extract** OCI manifest/layers (hash becomes `contentAddress`).
+- **Build SBOM** in CycloneDX 1.6 and/or SPDX 3.0.1; canonicalize JSON before hashing (`sbomHash`).
+- **Sign** outputs as DSSE envelopes; predicate uses in-toto Statement with SLSA Provenance v1.
+- **Publish** attestations optionally to a transparency backend: `rekor`, `local-merkle`, or `null` (no-op). Local Merkle log keeps proofs for later sync when online.
+
+Minimal APIs exposed by SbomService (idempotent by hash):
+
+- `POST /sbom/ingest` `{ imageDigest, sbom, format, dsseSignature? }` → `{ sbomId, status: stored|already_present, sbomHash }` keyed by `contentAddress + sbomHash`.
+- `POST /attest/verify` `{ dsseEnvelope, expectedSubjects[] }` → `{ verified, predicateType, logIndex?, inclusionProof? }` and records attestation when verified.
+
+Operational rules:
+
+- Default media types: `application/vnd.cyclonedx+json`, `application/spdx+json`, `application/dsse+json`, `application/vnd.in-toto+json`.
+- If the same SBOM/attestation arrives again, return HTTP 200 with `"status":"already_present"` and do not create a new version.
+- Offline posture: no external calls required; Rekor publish remains optional and retryable when connectivity is restored.
 
 ## 3) APIs (first wave)
 - `GET /sbom/paths?purl=...&artifact=...&scope=...&env=...` — returns ordered paths with runtime_flag/blast_radius and nearest-safe-version hint; supports `cursor` pagination.