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

---
id: RMGR-WP-0011
type: workplan
title: "SBOM Nexus production client and explicit preview semantics"
domain: infotech
repo: repo-manager
status: finished
owner: codex
topic_slug: infotech
quality_dor: DoR-Ok
created: "2026-08-22"
updated: "2026-08-31"
quality_dod: DoD-Ok
quality_dod_at: "2026-08-31"
quality_dod_by: codex
quality_dod_note: >-
  Contract, failure semantics, explicit preview mode, controlled source
  projection, and live authoritative Nexus reads are evidenced; durable SBOM
  ownership remains solely with SBOM Nexus.
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: 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

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