feat: add controlled source ingestion and replay

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a02b22-9638-76d2-bbff-b7ea1770b118

docs/operator-guide.md

@@ -42,8 +42,48 @@ curl -X POST http://127.0.0.1:8010/sbom/example/ingest
 ```
 
 The ingest response is terminal: `ingested`, or `skipped` with one of
-`no-checkout`, `no-manifest`, or `ingest-error`. A skip advances queue fairness
-but does not advance `last_success_at`.
+`no-checkout`, `no-manifest`, `ingest-error`, `source-unavailable`, or
+`source-rejected`. A skip advances queue fairness but does not advance
+`last_success_at`.
+
+## Controlled Forgejo source
+
+Production automation uses the contract selected by `CUST-WP-0064`: Repo
+Manager projects a canonical Coulomb repository and full commit SHA, Activity
+Core freezes that `source_ref` with its bounded target set, and Nexus alone
+fetches and scans the source. Example projection:
+
+```json
+{
+  "source_ref": {
+    "kind": "forgejo-archive-v1",
+    "repository": "coulomb/example",
+    "revision": "0123456789abcdef0123456789abcdef01234567",
+    "observed_ref": "refs/heads/main",
+    "observed_at": "2026-08-22T20:00:00Z"
+  }
+}
+```
+
+Enable only after the package has migration `0002`, bounded ephemeral storage,
+and Forgejo/DNS egress:
+
+```sh
+export SBOM_NEXUS_CONTROLLED_SOURCE_ENABLED=true
+export SBOM_NEXUS_FORGEJO_BASE_URL=http://forgejo-gitea-http.forgejo.svc.cluster.local:3000
+export SBOM_NEXUS_SOURCE_TMP=/var/run/sbom-sources
+```
+
+The runtime defaults are one concurrent scan, 120 seconds each for fetch and
+scan, 100 MiB compressed, 512 MiB expanded, and 100,000 archive members. The
+source endpoint accepts no arbitrary URL and requires no credential for public
+Coulomb repositories. Never substitute a Forgejo administrator token.
+
+Automated ingest and skip requests send the same value in `Idempotency-Key`
+and `X-Activity-Core-Operation-ID`. Nexus persists that operation identity in
+the snapshot transaction. A retry with the same request replays the original
+terminal outcome; reuse against a different route, repository, reason, or
+source reference returns HTTP 409.
 
 ## Inspect catch-up