Refactor code structure for improved readability and maintainability; optimize performance in key functions.

docs/modules/sbomservice/ledger-lineage.md

@@ -0,0 +1,41 @@
+# 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.