tegwick 84952c5212 feat: harden work-record and SBOM client contracts

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

2026-08-22 23:19:36 +02:00

2.9 KiB

Raw Blame History

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
Service operation	configured SBOM Nexus HTTP client	yes	Nexus decides	yes, according to the route outcome

Every compatibility-command result carries:

{
  "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.

2.9 KiB Raw Blame History