stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Repair release investigation workspace contracts

Browse Source
This commit is contained in:
master
2026-03-09 23:19:42 +02:00
parent 3ecafc49a3
commit 359fafa9da
20 changed files with 1806 additions and 284 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/modules/sbom-service/architecture.md
View File

@@ -50,6 +50,9 @@ Operational rules:
- `GET /sbom/ledger/range` – query versions within a time range.
- `GET /sbom/ledger/diff` – component/version/license diff between two versions.
- `GET /sbom/ledger/lineage` – parent/child lineage edges for an artifact chain.
- `GET /api/v1/lineage/compare?a=...&b=...&tenant=...` – canonical release-investigation comparison endpoint returning normalized component, VEX, and reachability deltas for deploy-diff.
- `POST /api/change-traces/build` – compatibility endpoint that materializes a release-investigation change trace from `fromDigest`, `toDigest`, and tenant context.
- `GET /api/change-traces/{traceId}` – stateless compatibility read endpoint; rehydrates the change trace from an encoded trace id and the current lineage compare result.
- `GET /console/sboms` – Console catalog with filters (artifact, license, scope, asset tags), cursor pagination, evaluation metadata, immutable JSON projection for drawer views.
- `GET /components/lookup?purl=...` – component neighborhood for global search/Graph overlays; returns caches hints + tenant enforcement.
- `POST /entrypoints` / `GET /entrypoints` – manage entrypoint/service node overrides feeding Cartographer relevance; deterministic defaults when unset.
@@ -88,6 +91,11 @@ Operational rules:
- Current implementation uses an in-memory event store/publisher (with clock abstraction) plus `/internal/sbom/events` + `/internal/sbom/events/backfill` to validate envelopes until the PostgreSQL-backed outbox is wired.
- Entrypoint/service node overrides are exposed via `/entrypoints` (tenant-scoped) and should be mirrored into Cartographer relevance jobs when the outbox lands.
## 5.1) Release Investigation Compatibility
- The Releases workspace consumes lineage compare as the source of truth for A/B deploy comparison.
- `/api/change-traces/*` exists as a compatibility layer for the web change-trace viewer and gateway routing. It does not persist trace documents; trace ids encode the tenant, digest pair, and byte-diff mode, and the service deterministically rebuilds the document on read.
- When no lineage comparison exists for the selected digests, the service returns `404` so the web workspace can surface an explicit recovery state instead of pretending data exists.
## 6) Determinism & offline posture
- Stable ordering for projections and paths; timestamps in UTC ISO-8601; hash inputs canonicalised.
- Add-only evolution for schemas; LNM v1 fixtures published alongside API docs and replayable tests.