sbom-nexus/INTENT.md

# Intent — SBOM Nexus

## Enduring purpose

SBOM Nexus exists to make the software composition of every managed product
knowable, historically traceable, and operationally maintainable.

Its job is not merely to generate an SBOM file. It turns repository and build
evidence into a durable product surface: versioned component inventories,
provenance, licence evaluation, freshness signals, and bounded work queues that
keep coverage improving without flooding people or task systems.

## Problem

Software composition evidence is currently split across repository lockfiles,
an interim Repo Manager scanner, and State Hub tables, routes, scripts, MCP
tools, and dashboards. State Hub is being retired and is the wrong permanent
owner for a supply-chain product. Its fleet-wide freshness automation also
demonstrated the wrong control shape: one weekly evaluation created dozens of
tasks while updating no SBOMs.

Without a dedicated owner, the fleet risks stale inventories, lost history,
inconsistent parser behavior, vague licence findings, and automation that
measures a backlog instead of reducing it.

## Product responsibility

SBOM Nexus is the authoritative service for:

- normalized SBOM snapshots and their immutable history;
- package/component entries and source provenance;
- repository scanning and ingestion of supported evidence formats;
- licence inventory and clearly qualified risk signals;
- SBOM freshness, coverage, and deterministic oldest-first catch-up ranking;
- explicit terminal outcomes for scans that cannot run or find no manifests;
- stable HTTP and operator interfaces for fleet consumers;
- migration of historical State Hub SBOM records without erasing provenance.

## Authority boundaries

| Concern | Authority |
| --- | --- |
| Dependency declarations, lockfiles, reviewed `sbom-tools.yaml`, supplied SPDX/CycloneDX documents | The owning repository or build output |
| Normalized snapshot history, scan attempts, entries, evaluation, freshness, catch-up order | SBOM Nexus |
| Repository identity, classification, active status, and checkout representation | Repo Manager |
| Scheduling and bounded recurring execution | Activity Core |
| Cross-domain work coordination and transitional `last_sbom_at` projection | State Hub during cutover only |
| Large immutable source documents or attestations | Artifact Store when introduced |

Repo Manager may observe dependency sources and invoke SBOM Nexus, but it does
not remain a second SBOM product or historical store. State Hub may proxy Nexus
responses during migration, but it must not regain permanent SBOM ownership.

## Operating principles

1. **Evidence before assertion.** Every component is traceable to a source path,
   source digest, submitted document, and—when available—source revision.
2. **History is append-only.** A new scan creates a snapshot. It does not mutate
   a prior view of the repository.
3. **Absence is explicit.** No checkout, no supported manifest, and parser
   failure are recorded outcomes, not indistinguishable missing data.
4. **Automation reduces queues.** Catch-up selects at most N oldest eligible
   repositories and advances every selected item through success or a recorded
   skip; it never emits a task per stale repository.
5. **Compatibility is temporary and testable.** Existing State Hub callers get
   a pinned compatibility contract while they are retargeted.
6. **Standards are interchange boundaries.** SPDX and CycloneDX import/export
   are first-class targets; the internal model is not presented as either
   standard unless it satisfies that standard.
7. **Risk signals remain qualified.** Licence-family pattern matching is a
   triage signal, not legal advice or a complete SPDX policy engine.
8. **Repository sources remain reconstructable authority.** Derived current
   snapshots can be rebuilt from current source evidence; imported historical
   snapshots retain their original source and timestamps.

## Intended users and outcomes

- Operators can see which repositories have current evidence and safely catch
  up a bounded number each day.
- Developers can scan a checkout locally and understand the exact source and
  parser behind each component.
- Compliance and security consumers can query fleet composition and licence
  signals without coupling to State Hub internals.
- Automation can distinguish successful ingest, empty evidence, unavailable
  checkout, and ingest error, and can report each deterministically.
- Future vulnerability, policy, signing, and attestation capabilities have a
  coherent SBOM history on which to build.

## Success horizon

SBOM Nexus succeeds first when the existing State Hub SBOM surface is served by
this repository with preserved history and the daily oldest-N workflow operates
without task floods. It succeeds durably when SBOM evidence is current by
policy, standard documents can move in and out without information loss, and no
other service acts as a competing SBOM authority.

## Non-goals

- Owning repository lifecycle, workplans, inboxes, or general task management.
- Acting as a package registry, artifact store, or source-code host.
- Claiming that lockfile parsing alone is a complete runtime or deployable SBOM.
- Providing legal conclusions from licence identifiers.
- Building a general vulnerability database in the extraction milestone.
- Scanning an unbounded fleet in one recurring activity.

## Change test

A change belongs here when it improves the capture, preservation, evaluation,
exchange, or operational freshness of software-composition evidence. If it is
primarily about repository control, scheduling, artifact bytes, work
coordination, or authorization, SBOM Nexus should integrate with the owning
component instead of absorbing that responsibility.