sbom-nexus/docs/state-hub-sbom-extraction-review.md

# State Hub SBOM extraction review

**Reviewed:** 2026-08-22

**Coordination:** `CUST-WP-0062-T01`, `STATE-WP-0079`, `RMGR-WP-0008`,
`ACTIVITY-WP-0030`

## Outcome

The SBOM capability is a coherent product embedded in State Hub, with a newer
derived-scanner copy in Repo Manager and an already-prepared Activity Core
consumer contract. The target ownership is:

- **SBOM Nexus:** scanning, ingest, snapshots, entries, history, reports,
  freshness, catch-up, import/export;
- **Repo Manager:** repository identity, active status, and checkout/path
  representation; invoke Nexus rather than retain a second scanner;
- **State Hub:** temporary compatibility façade and repository freshness
  projection only;
- **Activity Core:** recurrence and the at-most-N side effect;
- **dashboard/MCP/CLI callers:** retarget to Nexus or the temporary façade.

This corrects a timing overlap in the retirement work: `RMGR-WP-0008` built a
good repository-derived scanner before `CUST-WP-0062` established the dedicated
Nexus. That scanner is the best extraction source, but Repo Manager is not the
durable SBOM product owner.

## Current behavior

State Hub stores an immutable snapshot container and entries keyed to a managed
repository. Manual ingest creates a snapshot, stores entries, and updates
`ManagedRepo.last_sbom_at`. Reads return snapshot history, snapshot detail,
latest entries per repository, a repository view, and a licence grouping with a
simple copyleft-family signal.

Its ingest script recursively recognizes eight source families and posts the
merged result to the API. MCP, the `statehub` CLI, Make targets, onboarding,
repository health, summary caches, and dashboard pages depend on these routes.

Repo Manager subsequently improved the derivation step with source-path and
SHA-256 provenance, Git revision, canonical generation time, structured parser
errors, and direct-production copyleft findings. Its snapshot schema is
`repo-manager.sbom-snapshot.v1`.

Activity Core already contains a disabled/test-double consumer for the desired
Nexus endpoint. It expects `GET /sbom/catch-up?limit=N`, defaults to 3, bounds N
to 1..25, and requires the Nexus to return an ordered `repos` list plus fleet
counts. The old weekly task-flood definition is disabled.

## Artifact and caller disposition

| Existing surface | Location | Disposition | Target/action |
| --- | --- | --- | --- |
| `SBOMSnapshot` model/table | `state-hub/api/models/sbom_snapshot.py`, migrations | move/import | Nexus snapshot store; retain legacy id/timestamp/source provenance |
| `SBOMEntry` model/table and ecosystem enum | `state-hub/api/models/sbom_entry.py`, migrations | move/import | Nexus entries; retain compatibility field names |
| manual ingest | `POST /sbom/ingest/` | move + proxy | Implement compat route in Nexus; State Hub proxies during cutover |
| snapshot list/detail | `GET /sbom/snapshots/*` | move + proxy | Nexus owns history and response contract |
| latest entry filters | `GET /sbom/` | move + proxy | Nexus owns current projections |
| repository view | `GET /sbom/{slug}` | move + proxy | Nexus owns inventory; join/sync minimal repo projection |
| licence report | `GET /sbom/report/licences/` | move + proxy | Nexus owns qualified signal and later SPDX policy integration |
| parser/detection script | `state-hub/scripts/ingest_sbom.py` | move, then retire | Extract improved Repo Manager variant into independent Nexus scanner |
| derived scanner | `repo-manager/src/repo_manager/sbom.py` | move/replace | Make Nexus the implementation; Repo Manager becomes caller/adapter |
| scanner CLI | `rmgr sbom scan`, `licence-report` | retarget | Preserve CLI UX by calling Nexus/local Nexus library during transition |
| State Hub Make target | `make ingest-sbom` | retarget | Invoke Nexus CLI/API; retain temporary alias with deprecation notice |
| `statehub ingest-sbom` | `custodian_cli.py` | retarget | Invoke Nexus, not State Hub-local script |
| tool capture script/prompt | `scripts/capture_sbom_tools.py`, `prompts/sbom-capture-agent.md` | move later | Nexus operator workflow; keep reviewed manifest as repository authority |
| MCP resources | `state://sbom/*` | retarget/proxy | Fetch Nexus; later publish Nexus-native MCP if useful |
| MCP ingest/report tools | `ingest_sbom_tool`, `get_licence_report` | retarget | Call Nexus contracts |
| dashboard SBOM page/data loader | `dashboard/src/sbom.md`, `data/sbom.json.py` | retarget | Read Nexus or façade; no new dashboard in extraction release |
| repo/dashboard coverage cards | repos/overview pages | projection | Consume Nexus freshness projection |
| `ManagedRepo.last_sbom_at`, `sbom_source` | State Hub repo model | strangle/projection | Keep compatible fields, written/synchronized from Nexus during cutover |
| summary cache revision | `api/services/summary_cache.py` | adapt | Revision from Nexus projection/event, not local SBOM tables |
| State summary licence scan | `api/routers/state.py` | adapt | Consume Nexus report/projection |
| DoI criterion C8 | `api/doi_engine.py`, `policies/repo-doi.md` | retarget | Query precise Nexus attempt/success state |
| edge cache `/sbom/` | `api/edge/read_cache.py` | retire/retarget | Cache façade only while compatibility route exists |
| repo registration optional ingest | `scripts/register_project.sh` and onboarding docs | retarget | Register projection then invoke Nexus ingest |
| repository synchronization view | `dashboard/src/repo-sync.md` | retarget | Use Nexus status |
| Activity Core bulk status resolver | old `repo_sbom_status` | retire | Replace with one Nexus catch-up query |
| daily bounded consumer | `activity_core/context_resolvers/sbom_nexus.py` | retain/activate later | Contract is accepted input for Nexus implementation |
| weekly task flood | `weekly-sbom-staleness` | retire | Keep disabled; no one-task-per-stale-repo behavior |
| historical State Hub rows | 22 snapshots/18 repos in RMGR evidence | import + retain | Import history; reconcile counts; delete only after retention gate |

## Extracted source coverage

The first Nexus scanner preserves the proven coverage common to State Hub and
Repo Manager:

| Source | Ecosystem | Important behavior |
| --- | --- | --- |
| `uv.lock` | Python | all locked packages |
| `requirements.txt` | Python | declared lines marked direct |
| `package-lock.json` | Node | package metadata, dev/direct hints, licence when present |
| `yarn.lock` | Node | locked package/version extraction |
| `Cargo.lock` | Rust | all locked packages |
| `go.sum` + `go.mod` | Go | deduplicated modules; direct hint from `go.mod` |
| `.terraform.lock.hcl` | Terraform | provider/version entries |
| `ansible/requirements.y[a]ml` | Ansible | collections and roles under `ansible` directories |
| root `sbom-tools.yaml` | Tool/declared | reviewed escape hatch including licence and direct/dev flags |

Excluded directories remain `.git`, VCS metadata, virtual environments,
`node_modules`, caches, distribution/build outputs, Rust `target`, tox, and
nox environments.

## Contract differences and improvements

1. Nexus records `last_attempt_at` separately from `last_success_at`. State
   Hub's single `last_sbom_at` cannot truthfully express a skipped scan.
2. Every attempt has a terminal status. `no-checkout` and `no-manifest` are
   successful control-loop outcomes but not successful inventories.
3. Parser errors are stored with the snapshot; they are not silently reduced to
   empty entries.
4. Source paths, digests, and Git revision are retained from the Repo Manager
   implementation.
5. Copyleft substring matching remains compatibility triage. It is explicitly
   not an SPDX expression evaluator or legal conclusion.
6. Catch-up uses last attempt for queue fairness and last success for inventory
   truth. Consumers can display both rather than infer one from the other.

## Historical migration requirements

The migration must enumerate State Hub snapshots by repository and oldest
first, fetch each snapshot detail, upsert the repository projection, and insert
the snapshot with its legacy UUID and timestamp. It must be idempotent on the
legacy UUID and compare:

- repository count;
- snapshot count per repository and total;
- entry count per snapshot and total;
- earliest/latest timestamps;
- sampled current-repository views;
- licence group and direct-production copyleft counts.

Fresh repository scans do not replace imported history. They become later
snapshots based on current source evidence.

## Cutover gates

- Nexus production store, migrations, backup, and restore evidence exist.
- Historical import reconciles before State Hub deletion is considered.
- State Hub compatibility tests pass through the façade.
- Repo Manager no longer presents its scanner as independent SBOM authority.
- Dashboard, MCP, CLI, DoI, summary, and onboarding callers are inventoried and
  retargeted.
- Activity Core's ingest side effect is integrated but remains bounded by the
  resolver's effective limit.
- Two production daily fires record at most N terminal outcomes and zero spawned
  per-repository tasks.
- Weekly fleet task-flood behavior remains disabled.

## Review conclusion

Extraction is feasible without changing supported ecosystems. The principal
risk is not parser migration; it is authority and history cutover across three
temporarily overlapping implementations. The first Nexus slice therefore pins
the compatibility and catch-up contracts, while production ownership remains a
separate gated task requiring State Hub and Repo Manager adapter changes.