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.