# 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.