feat: add controlled source ingestion and replay

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

README.md

@@ -31,5 +31,13 @@ development environments; mounted secret files are preferred for production.
 - `POST /sbom/{repo_slug}/ingest`
 - State Hub-compatible `/sbom/` snapshot, entry, repository, and licence routes
 
+Authoritative automation may ingest a controlled `forgejo-archive-v1`
+`source_ref` pinned to a full commit SHA. Nexus constructs the Forgejo URL,
+streams and safely extracts the archive within configured limits, records the
+archive and manifest provenance, and removes the transient directory. It does
+not accept arbitrary source URLs. `Idempotency-Key` is durably enforced on
+repository ingest and skip operations; a matching retry replays the original
+snapshot outcome and conflicting key reuse returns HTTP 409.
+
 See [docs/state-hub-sbom-extraction-review.md](docs/state-hub-sbom-extraction-review.md)
 for the extraction inventory and cutover dispositions.