--- id: RMGR-WP-0011 type: workplan title: "SBOM Nexus production client and explicit preview semantics" domain: infotech repo: repo-manager status: active owner: codex topic_slug: infotech quality_dor: DoR-Ok created: "2026-08-22" updated: "2026-08-22" parent_workplan: SBOM-WP-0002 related: - CUST-WP-0062 - CUST-WP-0064 - RMGR-WP-0008 state_hub_workstream_id: "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 ```task 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 ```task 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 ```task 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 ```task id: RMGR-WP-0011-T04 status: progress 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/` 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`. ## 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.