feat: harden work-record and SBOM client contracts

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d

docs/repository-registers_v0.1.md

@@ -74,6 +74,10 @@ SBOM Nexus is the sole scanner and snapshot product owner. Repo Manager retains
 these aliases only so existing repository workflows do not break; set
 `SBOM_NEXUS_CLI` when `sbom-nexus` is not on `PATH`. Their JSON includes
 `product_owner: sbom-nexus` and the Nexus `sbom-nexus.snapshot.v1` schema.
+They also carry `repo_manager_context.mode: local-preview` with explicit false
+values for authority, persistence, attempt/success advancement, and snapshot
+history creation. See `docs/sbom-nexus-client-contract_v1.md` for the pinned
+preview and production-service boundary.
 
 Detection covers `uv.lock`, `requirements.txt`, `package-lock.json`,
 `yarn.lock`, `Cargo.lock`, `go.sum`, `.terraform.lock.hcl`, Ansible requirements

docs/sbom-nexus-client-contract_v1.md

@@ -0,0 +1,72 @@
+# SBOM Nexus client contract v1
+
+Repo Manager consumes SBOM Nexus; it does not implement a second scanner,
+snapshot store, freshness model, licence classifier, or catch-up scheduler.
+This contract pins the boundary used by `RMGR-WP-0011`.
+
+## Authority modes
+
+| Mode | Surface | Authoritative | Persisted | Advances Nexus state |
+| --- | --- | --- | --- | --- |
+| Local preview | `rmgr sbom scan|licence-report` → `sbom-nexus scan` | no | no | no |
+| Service operation | configured SBOM Nexus HTTP client | yes | Nexus decides | yes, according to the route outcome |
+
+Every compatibility-command result carries:
+
+```json
+{
+  "repo_manager_context": {
+    "mode": "local-preview",
+    "authoritative": false,
+    "persisted": false,
+    "advances_last_attempt_at": false,
+    "advances_last_success_at": false,
+    "creates_snapshot_history": false
+  }
+}
+```
+
+Writing preview JSON to a file creates optional local evidence only. It does
+not turn the result into an authoritative snapshot or ingest receipt.
+
+## Pinned snapshot envelope
+
+Repo Manager accepts `schema: sbom-nexus.snapshot.v1`. Additive fields are
+compatible. An unknown schema or omission of any of these fields is a contract
+error: `schema`, `ok`, `repo_slug`, `source_revision`, `generated_at`,
+`entry_count`, `entries`, `sources`, `licence_report`, and `errors`.
+
+Repo Manager may project the existing licence-report compatibility shape from
+that envelope. It must not recalculate licence groups or copyleft signals.
+
+## Authoritative service routes
+
+The production client may consume these Nexus-owned routes without depending
+on Nexus tables or migrations:
+
+| Purpose | Route |
+| --- | --- |
+| Upsert repository projection | `PUT /repositories/{repo_slug}` |
+| Read repository projections | `GET /repositories/` |
+| Persist scan outcome | `POST /sbom/{repo_slug}/ingest` |
+| Persist terminal skip outcome | `POST /sbom/{repo_slug}/skip` |
+| Read latest repository SBOM | `GET /sbom/{repo_slug}` |
+| Read immutable snapshot detail | `GET /sbom/snapshots/{snapshot_id}` |
+| Read licence report | `GET /sbom/report/licences/` |
+
+Calls use a bounded timeout and surface deterministic transport, HTTP, and
+contract errors. Credentials enter only through the platform runtime path and
+must never appear in files, command output, or logs.
+
+## Repository source identity and provenance
+
+Repo Manager remains authoritative for repository slug, active state,
+checkout/source identity, and Git revision. An authoritative scan request must
+refer to a controlled source artifact or checkout pinned to that revision. It
+must not infer identity from a path string or repository name, and it must not
+mount a workstation filesystem into the cluster.
+
+`CUST-WP-0064` owns the coordinated source-input topology. Until that topology
+is live, local checkout scans remain previews even when their Git revision is
+known. SBOM Nexus alone records the resulting authoritative snapshot and
+attempt/success history.