# SBOM Lineage Ledger Guide

## Purpose
- Track historical SBOM versions per artifact with deterministic diffs and lineage edges.
- Support BYOS uploads for SPDX/CycloneDX inputs while preserving audit history.

## Upload workflow
- Endpoint: `POST /sbom/upload` or `POST /api/v1/sbom/upload`.
- Required fields: `artifactRef`, `sbom` (JSON object) or `sbomBase64`.

Example payload:
```json
{
  "artifactRef": "acme/app:1.0",
  "sbom": { "bomFormat": "CycloneDX", "specVersion": "1.6", "components": [] },
  "format": "cyclonedx",
  "source": { "tool": "syft", "version": "1.0.0" }
}
```

## Ledger queries
- `GET /sbom/ledger/history?artifact=...&limit=...&cursor=...`
- `GET /sbom/ledger/point?artifact=...&at=...`
- `GET /sbom/ledger/range?artifact=...&start=...&end=...&limit=...&cursor=...`
- `GET /sbom/ledger/diff?before=...&after=...`
- `GET /sbom/ledger/lineage?artifact=...`

## Lineage semantics
- Versions are chained per artifact; parent references create lineage edges.
- Graph Indexer maps ledger lineage into:
  - `SBOM_VERSION_OF` edges from SBOM to artifact.
  - `SBOM_LINEAGE_*` edges (e.g., `SBOM_LINEAGE_PARENT`).

## Retention policy
- Apply with `POST /internal/sbom/retention/prune`.
- Settings: `SbomService:Ledger:MaxVersionsPerArtifact`, `MaxAgeDays`, `MinVersionsToKeep`.
- Audit is available via `GET /internal/sbom/ledger/audit`.

## Determinism
- Versions are ordered by sequence and UTC timestamps.
- Diffs are ordered by component key for stable output.