Repair release investigation workspace contracts

docs/features/checked/web/a-b-deploy-diff-panel.md

@@ -9,6 +9,8 @@ VERIFIED
 ## Description
 Deploy diff UI provides deterministic A/B SBOM comparison with policy-hit context, loading/error states, and inline release action controls.
 
+As of 2026-03-09 the panel is no longer wired to the dead `/api/v1/sbom/diff` route. The canonical comparison source is SbomService lineage compare, and the surrounding Releases workspace now degrades to an actionable `No Comparison Selected` state instead of a hard route failure when no digests are present.
+
 ## Implementation Details
 - **Feature directory**: `src/Web/StellaOps.Web/src/app/features/deploy-diff/`
 - **Route module**: `src/Web/StellaOps.Web/src/app/features/deploy-diff/deploy-diff.routes.ts`
@@ -16,11 +18,16 @@ Deploy diff UI provides deterministic A/B SBOM comparison with policy-hit contex
   - `src/Web/StellaOps.Web/src/app/features/deploy-diff/pages/deploy-diff.page.ts`
   - `src/Web/StellaOps.Web/src/app/features/deploy-diff/components/deploy-diff-panel/deploy-diff-panel.component.ts`
   - `src/Web/StellaOps.Web/src/app/features/deploy-diff/services/deploy-diff.service.ts`
+- **Canonical backend dependency**:
+  - `GET /api/v1/lineage/compare?a=<fromDigest>&b=<toDigest>&tenant=<tenantId>`
 - **Focused tests**:
-  - `src/Web/StellaOps.Web/src/tests/deploy_diff/deploy-diff-panel.component.spec.ts`
+  - `src/Web/StellaOps.Web/src/app/features/deploy-diff/services/deploy-diff.service.spec.ts`
+  - `src/Web/StellaOps.Web/src/app/features/deploy-diff/components/deploy-diff-panel/deploy-diff-panel.component.spec.ts`
+  - `src/Web/StellaOps.Web/src/app/features/deploy-diff/pages/deploy-diff.page.spec.ts`
 
 ## Follow-up Notes
-- Primary shell route map now mounts `/deploy/diff` via `src/Web/StellaOps.Web/src/app/app.routes.ts`, enabling strict end-user Tier 2 replay.
+- Primary Releases shell mounts the canonical workspace at `/releases/investigation/deploy-diff`.
+- Direct shell navigation without digests is a supported workspace state, not an error path.
 
 ## Verification
 - Date: 2026-02-10
@@ -30,18 +37,12 @@ Deploy diff UI provides deterministic A/B SBOM comparison with policy-hit contex
   - `tier1-build-check.json`: pass
   - `tier2-e2e-check.json`: pass
 
-
-
 ## Recheck (run-003)
 - Date (UTC): 2026-02-10
 - Status: VERIFIED (replayed)
 - Tier 1 evidence: Angular build passed and checked-web suite passed 145/145.
 - Tier 2 evidence: docs/qa/feature-checks/runs/web/a-b-deploy-diff-panel/run-003/tier2-e2e-check.json.
 
-
-
-
-
 ## Recheck (run-004)
 - Date (UTC): 2026-02-10
 - Status: VERIFIED (replayed)
@@ -55,3 +56,12 @@ Deploy diff UI provides deterministic A/B SBOM comparison with policy-hit contex
 - Tier 2 evidence: `docs/qa/feature-checks/runs/web/a-b-deploy-diff-panel/run-006/tier2-ui-check.json`
 - Notes: Playwright now covers positive deploy-diff rendering plus missing-parameter and API-error user paths; route is mounted in the primary shell map.
 
+## Recheck (2026-03-09)
+- Status: VERIFIED (lineage compare contract repair)
+- Tier 1 evidence:
+  - `npx ng test --watch=false --ts-config tsconfig.spec.features.json --include=src/app/features/deploy-diff/services/deploy-diff.service.spec.ts --include=src/app/features/deploy-diff/components/deploy-diff-panel/deploy-diff-panel.component.spec.ts --include=src/app/features/deploy-diff/pages/deploy-diff.page.spec.ts`
+- Tier 2 target:
+  - live `https://stella-ops.local/releases/investigation/deploy-diff`
+- Notes:
+  - direct route loads an actionable workspace when digests are missing
+  - loaded comparisons are normalized from lineage compare into the deploy-diff UI model

docs/features/checked/web/release-investigation-routes.md

@@ -15,10 +15,15 @@ Integrated disconnected release-investigation route families (timeline, deploy-d
 ## Canonical URL Contract
 - `/releases/investigation/timeline` - Investigation timeline overview
 - `/releases/investigation/timeline/:correlationId` - Correlated event drill-in
-- `/releases/investigation/deploy-diff` - Deployment diff (query params: from, to)
-- `/releases/investigation/change-trace` - Change trace viewer
+- `/releases/investigation/deploy-diff` - Deployment diff workspace; direct load shows a recovery state when no `from`/`to` digests are present
+- `/releases/investigation/change-trace` - Change trace workspace; direct load shows a recovery state until a comparison or trace id is selected
 - `/releases/investigation/change-trace/:traceId` - Specific trace detail
 
+## Direct-Load Workspace Contract
+- `/releases/investigation/deploy-diff` no longer fails with `Missing Parameters`. Direct navigation now shows `No Comparison Selected` plus recovery actions back to `/releases/deployments` and `/releases/overview`.
+- `/releases/investigation/change-trace` no longer renders an inert `No Change Trace Loaded` shell. Direct navigation now shows `No Comparison Selected` plus recovery actions to `/releases/deployments`, or back to deploy-diff when `from`/`to` digests are already present.
+- Both workspaces preserve tenant/scope query context when it exists and fall back to the canonical `demo-prod` tenant on a fresh shell load.
+
 ## Timeline Decision
 **Bounded-secondary-route** (not absorb-into-run-workspace). The investigation timeline is a correlation-based tool that spans multiple services by correlationId, which is conceptually different from the run workspace's timeline tab showing run execution flow. Mounting it under `/releases/investigation/timeline` avoids URL collision and keeps both capabilities distinct.
 
@@ -30,6 +35,10 @@ Integrated disconnected release-investigation route families (timeline, deploy-d
   - `src/Web/StellaOps.Web/src/app/features/deploy-diff/deploy-diff.routes.ts` - Updated canonical URL reference
   - `src/Web/StellaOps.Web/src/app/features/change-trace/change-trace.routes.ts` - Added breadcrumb, title, sprint ref
 - **Tests**: `src/Web/StellaOps.Web/src/app/routes/releases.routes.spec.ts`
+- **Recheck (2026-03-09)**:
+  - `deploy-diff` is now backed by the live lineage compare contract instead of the dead `/api/v1/sbom/diff` path.
+  - `change-trace` is now backed by the restored `/api/change-traces/build` and `/api/change-traces/{traceId}` compatibility endpoints in SbomService.
+  - Focused verification passed on `src/Web/StellaOps.Web/src/app/features/deploy-diff/pages/deploy-diff.page.spec.ts` and `src/Web/StellaOps.Web/src/app/features/change-trace/change-trace-viewer.component.spec.ts`.
 
 ## Deliberately Excluded Legacy Behaviors
 - The old timeline route at `/timeline` (standalone top-level) is not revived

docs/implplan/SPRINT_20260309_016_SbomService_release_investigation_workspace_contract_repair.md

@@ -0,0 +1,91 @@
+# Sprint 20260309_016 - Release Investigation Workspace Contract Repair
+
+## Topic & Scope
+- Replace the broken release-investigation route contract with a self-sufficient workspace that no longer depends on orphaned query params or dead API paths.
+- Restore canonical behavior for `/releases/investigation/deploy-diff` and `/releases/investigation/change-trace` on a fresh live stack where comparison data may be absent.
+- Keep the repair scoped to release-investigation surfaces, the SbomService compatibility layer they depend on, and the docs that describe the contract.
+- Working directory: `src/SbomService/`.
+- Allowed coordination edits: `src/Web/StellaOps.Web/src/app/features/deploy-diff/`, `src/Web/StellaOps.Web/src/app/features/change-trace/`, `src/Web/StellaOps.Web/scripts/`, `docs/features/checked/web/`, and `docs/modules/sbom-service/`.
+- Expected evidence: focused .NET tests, focused Angular tests, rebuilt `sbomservice` + web bundle, live Playwright recheck artifacts.
+
+## Dependencies & Concurrency
+- Depends on the current `stella-ops.local` compose stack already rebuilt from source on 2026-03-09.
+- Safe to run in parallel with unrelated search/runtime/auth work as long as those edits do not overwrite the touched release-investigation files.
+- Do not modify unrelated dirty files from other agents.
+
+## Documentation Prerequisites
+- `docs/modules/sbom-service/architecture.md`
+- `docs/features/checked/web/release-investigation-routes.md`
+- `docs/features/checked/web/a-b-deploy-diff-panel.md`
+- `docs/qa/feature-checks/FLOW.md`
+
+## Delivery Tracker
+
+### SBOM-RIW-001 - Define canonical workspace/default-context contract
+Status: DONE
+Dependency: none
+Owners: Product Manager, Developer
+Task description:
+- Replace the legacy assumption that the deploy-diff route is only valid when a caller injects `from` and `to` query parameters. The canonical Releases-owned workspace must remain useful when opened directly from the shell on a fresh setup.
+- Decide and document how the investigation pages behave when comparison data is unavailable in the live stack: they must show explicit product states and recovery paths, not placeholder errors.
+
+Completion criteria:
+- [ ] Release-investigation docs describe the new direct-load behavior and the live-data fallback behavior.
+- [ ] The selected contract is reflected consistently in both web and sbomservice implementations.
+
+### SBOM-RIW-002 - Rebase deploy diff on the live lineage compare contract
+Status: DONE
+Dependency: SBOM-RIW-001
+Owners: Developer, Test Automation
+Task description:
+- Remove the dead `/api/v1/sbom/diff` dependency from the deploy-diff feature.
+- Use the live lineage compare capability as the canonical comparison source and normalize it into the deploy-diff UI model.
+- Ensure the direct route either loads a comparison or lands in an explicit, user-actionable empty state instead of `Missing Parameters`.
+
+Completion criteria:
+- [ ] Deploy-diff uses a live contract that exists in sbomservice.
+- [ ] Direct navigation to `/releases/investigation/deploy-diff` no longer renders the legacy missing-parameter failure state.
+- [ ] Focused frontend tests cover both loaded and no-comparison states.
+
+### SBOM-RIW-003 - Restore change trace compatibility API and viewer behavior
+Status: DONE
+Dependency: SBOM-RIW-001
+Owners: Developer, Test Automation
+Task description:
+- Implement the missing `/api/change-traces` compatibility layer in SbomService instead of leaving the gateway to route into a void.
+- Make the change-trace viewer support canonical direct-load behavior and a deterministic empty state when there is no active comparison context.
+
+Completion criteria:
+- [ ] `/api/change-traces/build` and compatible read behavior exist in sbomservice with focused tests.
+- [ ] `/releases/investigation/change-trace` no longer renders the legacy inert empty shell on direct load.
+- [ ] Live Playwright verifies the viewer loads meaningful state and recovery actions.
+
+### SBOM-RIW-004 - Verify live route behavior after rebuild
+Status: DONE
+Dependency: SBOM-RIW-002
+Owners: QA, Test Automation
+Task description:
+- Rebuild the touched targets, redeploy only the changed services, rerun the focused Playwright surfaces, and capture the before/after evidence.
+- Do not mark the iteration done until the live shell confirms the repaired routes and their primary actions.
+
+Completion criteria:
+- [x] Focused .NET and Angular tests pass.
+- [x] `sbomservice` and web assets are rebuilt and redeployed.
+- [x] Live Playwright evidence shows the repaired routes and actions behaving correctly.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-09 | Sprint created after live Playwright confirmed `/releases/investigation/deploy-diff` rendered `Missing Parameters` and `/releases/investigation/change-trace` rendered `No Change Trace Loaded`; live stack inspection showed the mounted routes depended on dead or missing contracts. | Developer |
+| 2026-03-09 | Rebased deploy-diff on lineage compare, restored the `/api/change-traces` compatibility layer, and added focused verification: `dotnet test src/SbomService/StellaOps.SbomService.Tests/StellaOps.SbomService.Tests.csproj -v minimal -- --filter-class StellaOps.SbomService.Tests.ChangeTraceCompatibilityEndpointsTests` passed 3/3; `npx ng test --watch=false --ts-config tsconfig.spec.features.json --include=src/app/features/deploy-diff/services/deploy-diff.service.spec.ts --include=src/app/features/deploy-diff/components/deploy-diff-panel/deploy-diff-panel.component.spec.ts --include=src/app/features/deploy-diff/pages/deploy-diff.page.spec.ts --include=src/app/features/change-trace/change-trace-viewer.component.spec.ts` passed 30/30. | Developer |
+| 2026-03-09 | Rebuilt `sbomservice`, rebuilt and resynced the web bundle into `compose_console-dist`, then reran `node .\\src\\Web\\StellaOps.Web\\scripts\\live-frontdoor-changed-surfaces.mjs`; live frontdoor verification passed for the repaired release-investigation routes and their recovery actions on `https://stella-ops.local`. | Developer |
+
+## Decisions & Risks
+- Decision: release-investigation routes are Releases-owned workspaces with canonical direct-load behavior rather than query-only leaf pages.
+- Risk: the current live stack has empty release/SBOM comparison projections, so the workspace must degrade cleanly when no comparison exists instead of pretending data is present.
+- Risk: other agents have unrelated dirty files in `src/Web/StellaOps.Web/` and platform services; only stage touched release-investigation files for the eventual commit.
+- Contract note: `/api/change-traces/*` is restored as a deterministic compatibility layer over lineage compare, not as a second persistent change-trace store.
+
+## Next Checkpoints
+- Implement the workspace/default-context contract and the SbomService compatibility API in this iteration.
+- Rebuild `sbomservice` and the web bundle, sync the web assets into `compose_console-dist`, rerun the focused Playwright sweep, and commit the scoped repair.

docs/modules/sbom-service/architecture.md

@@ -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.