repo-manager/workplans/RMGR-WP-0011-sbom-nexus-production-client.md

id	type	title	domain	repo	status	owner	topic_slug	quality_dor	created	updated	quality_dod	quality_dod_at	quality_dod_by	quality_dod_note	parent_workplan	related	state_hub_workstream_id
RMGR-WP-0011	workplan	SBOM Nexus production client and explicit preview semantics	infotech	repo-manager	finished	codex	infotech	DoR-Ok	2026-08-22	2026-08-31	DoD-Ok	2026-08-31	codex	Contract, failure semantics, explicit preview mode, controlled source projection, and live authoritative Nexus reads are evidenced; durable SBOM ownership remains solely with SBOM Nexus.	SBOM-WP-0002	CUST-WP-0062 CUST-WP-0064 RMGR-WP-0008	a6cd9248-e591-51fc-82b0-a0f3799c3939

SBOM Nexus production client and explicit preview semantics

Goal

Complete Repo Manager's caller cutover to SBOM Nexus without reintroducing a second SBOM product. Repo Manager retains repository identity, active status, and checkout-path authority; SBOM Nexus owns sbom-nexus.snapshot.v1, ingest outcomes, licence evaluation, freshness, and immutable history.

RMGR-WP-0008 already removed Repo Manager's duplicate scanner and changed the legacy commands into thin delegates to the Nexus CLI. This workplan addresses the remaining production boundary: distinguish a persisted Nexus operation from a local, non-authoritative preview and provide a configured service client for callers that require authoritative state.

Pin the consumer contract

id: RMGR-WP-0011-T01
status: done
priority: high
state_hub_task_id: "b3b0f4d9-de14-5429-bc4d-a14d014491b0"

Document and test the consumed sbom-nexus.snapshot.v1 fields and the authoritative service routes. Treat additive fields as compatible, reject an unknown schema, and do not couple Repo Manager to Nexus database tables or migration internals.

Result (2026-08-22): docs/sbom-nexus-client-contract_v1.md pins the accepted sbom-nexus.snapshot.v1 envelope and the Nexus-owned repository, ingest/skip, latest-snapshot, immutable-history, and licence-report routes. Additive response fields remain compatible; unknown schemas and missing required fields produce deterministic contract errors. The source handoff now joins CUST-WP-0064: Repo Manager supplies repository identity and revision, while the authoritative scan consumes a controlled revision-pinned source. A workstation filesystem must never be mounted into the cluster.

Add the authoritative Nexus service client

id: RMGR-WP-0011-T02
status: done
priority: high
state_hub_task_id: "280cfa84-1561-5cb9-8943-aa0775c57be6"

Provide an explicitly configured HTTP client for the Nexus repository projection, ingest, latest-snapshot, and licence-report surfaces needed by Repo Manager. Preserve bounded timeouts and actionable failures; credentials, when introduced through the platform path, must never enter files, output, or logs.

Result (2026-08-22): SBOMNexusClient provides the four pinned service operations with explicit SBOM_NEXUS_URL, a configurable 0.1–300 second bound, route-specific success validation, URL-safe slugs, and sanitized deterministic timeout/transport/HTTP/JSON/contract errors. Optional runtime bearer credentials are representation-hidden and never copied into failures.

Mutation calls are not retried implicitly. Ingest accepts a stable Idempotency-Key, and failures state whether the operation may already have committed. Callers may require an exact source revision; a mismatched ingested receipt fails closed while preserving that commit-uncertainty signal. The repository projection parameter is explicitly Nexus-local nexus_checkout_path, subject to the controlled-source boundary in T01.

Make local scanning an explicit preview

id: RMGR-WP-0011-T03
status: done
priority: high
state_hub_task_id: "5cd717de-d696-5676-9abe-f1a701e48e7e"

Keep repository-source scanning usable through the Nexus-owned CLI when the service is unavailable, but mark the result unambiguously as local, non-authoritative, and not persisted. The compatibility aliases must not imply that a preview advanced last_attempt_at, last_success_at, or snapshot history.

Result (2026-08-22): both compatibility aliases now identify every success and error as mode: local-preview, authoritative: false, persisted: false, and explicitly state that no last-attempt, last-success, or snapshot-history state advances. Saving preview JSON remains optional local evidence and cannot be interpreted as an ingest receipt. CLI help, operator documentation, and contract tests carry the same semantics.

Prove cutover and remove ambiguity

id: RMGR-WP-0011-T04
status: done
priority: medium
state_hub_task_id: "81fed060-3431-5d9b-819b-fcc7d629c364"

Add contract, failure, and CLI compatibility tests; update operator docs; and prove by source inspection that Repo Manager has no scanner implementation, snapshot store, freshness evaluation, catch-up policy, or licence classifier. Capture the exact production handoff evidence required by SBOM-WP-0002.

Progress (2026-08-22): contract tests now cover additive preview schemas, unknown schema rejection, all four authoritative routes, bounded configuration, credential redaction, malformed success responses, timeouts, server failures, commit uncertainty, idempotency headers, and revision mismatch. Remaining is the production consumer handoff and final source/ownership inspection after the controlled source-input topology is available.

Controlled-source projection (2026-08-22): Custodian decision c67833d0-62a9-4d14-9d74-4693cc0c497d selected the forgejo-archive-v1 contract. rmgr sbom source-ref now normalizes only the canonical public coulomb/<slug> Forgejo identity, observes the default branch and full SHA through the anonymous Forgejo API, records observed_ref and canonical UTC observed_at, and returns no source reference for missing, private, non-Coulomb, mismatched, or unresolvable sources. Local HEAD and workstation paths never supply the production revision.

The explicit --project --confirm-authoritative path submits checkout_path: null and the structured reference through the T02 client. Projection passes only when Nexus echoes the exact reference, so the current pre-contract service cannot silently discard it. Live read-only proof resolved coulomb/repo-manager@b068e9da421332f99eaa24a811887f9a5d85a478 from refs/heads/main. Remaining T04 work is the Nexus/package/Activity Core implementation and attended production proof owned through CUST-WP-0064.

Done 2026-08-31. CUST-WP-0064 is finished and production Nexus is healthy on the controlled-source implementation. Repo Manager's own source-ref --project --confirm-authoritative command resolved the exact Forgejo main revision, projected it with checkout_path: null, and received the identical source reference from Nexus. Its production client also consumed the latest-snapshot and licence-report routes with explicit authoritative-service context. Source inspection confirms Repo Manager holds no scanner, snapshot store, freshness/catch-up policy, or licence classifier. Evidence: docs/evidence/RMGR-WP-0011-production-client-proof-2026-08-31.md.

Acceptance

• Authoritative mode talks to SBOM Nexus and returns its pinned snapshot contract without local persistence.
• Preview mode is visibly non-authoritative and cannot be mistaken for an ingest receipt.
• Existing rmgr sbom scan|licence-report users receive a documented migration path and deterministic errors.
• Repo Manager remains authoritative only for repository identity and paths; SBOM Nexus remains the sole durable SBOM owner.