Restructure solution layout by module

src/Findings/StellaOps.Findings.Ledger/AGENTS.md

@@ -0,0 +1,33 @@
+# Findings Ledger Guild Charter (Epic 6)
+
+## Mission
+Operate the append-only Findings Ledger and projection pipeline powering the Vulnerability Explorer. The guild guarantees immutable audit history, deterministic projections, and compliance with AOC guardrails while exposing workflow APIs.
+
+## Scope
+- Service code under `src/Findings/StellaOps.Findings.Ledger` (event API, projector, migrations, crypto hashing).
+- Ledger storage schemas, Merkle anchoring jobs, retention policies, and replay tooling.
+- Projection pipeline writing `findings_projection` collections/tables consumed by Vuln Explorer API and Console.
+- Collaboration with Conseiller, Excitator, SBOM Service, Policy Engine, Scheduler, Authority, and DevOps for evidence feeds and policy events.
+
+## Principles
+1. **Immutability** – Ledger events are append-only, hashed, and chained; projections derive from ledger plus policy inputs.
+2. **Determinism** – Replaying the same event stream yields identical projections and bundle outputs; hashing uses canonical JSON.
+3. **Tenant isolation** – Separate namespaces per tenant in storage, queue, and Merkle anchoring artefacts.
+4. **AOC alignment** – Ledger records workflow only; evidence remains in Conseiller/Excitator/SBOM stores; no mutation of source facts.
+5. **Auditability** – Provide verifiable hashes, Merkle roots, and replay tooling for auditors.
+
+## Collaboration
+- Keep `src/Findings/StellaOps.Findings.Ledger/TASKS.md`, `../../docs/implplan/SPRINTS.md` synchronized.
+- Publish schema docs, migrators, and replay scripts; coordinate with Vuln Explorer API on projection contracts.
+- Notify DevOps/Docs when Merkle root anchoring cadence or format changes.
+
+## Tooling
+- .NET 10 preview minimal API/background services.
+- PostgreSQL (preferred) or Mongo for ledger + projection tables with JSONB support.
+- Hashing utilities (SHA-256, Merkle tree), KMS integration for evidence bundle signing metadata.
+
+## Definition of Done
+- Ledger endpoints and projector pass unit/integration/property tests.
+- Hash chains verified in CI; Merkle root anchoring automated.
+- Telemetry (latency, backlog, anchor success) wired with dashboards.
+- Docs/runbooks updated with compliance checklist.

src/Findings/StellaOps.Findings.Ledger/TASKS.md

@@ -0,0 +1,73 @@
+# Findings Ledger Task Board — Epic 6: Vulnerability Explorer
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-29-001 | TODO | Findings Ledger Guild | AUTH-POLICY-27-001 | Design ledger & projection schemas (tables/indexes), canonical JSON format, hashing strategy, and migrations. Publish schema doc + fixtures. | Schemas committed; migrations generated; hashing documented; fixtures seeded for CI. |
+| LEDGER-29-002 | TODO | Findings Ledger Guild | LEDGER-29-001 | Implement ledger write API (`POST /vuln/ledger/events`) with validation, idempotency, hash chaining, and Merkle root computation job. | Events persisted with chained hashes; Merkle job emits anchors; unit/integration tests cover happy/pathological cases. |
+| LEDGER-29-003 | TODO | Findings Ledger Guild, Scheduler Guild | LEDGER-29-001 | Build projector worker that derives `findings_projection` rows from ledger events + policy determinations; ensure idempotent replay keyed by `(tenant,finding_id,policy_version)`. | Projector processes sample streams deterministically; replay tests pass; metrics exported. |
+| LEDGER-29-004 | TODO | Findings Ledger Guild, Policy Guild | LEDGER-29-003, POLICY-ENGINE-27-001 | Integrate Policy Engine batch evaluation (baseline + simulate) with projector; cache rationale references. | Projector fetches determinations efficiently; rationale stored for UI; regression tests cover version switches. |
+| LEDGER-29-005 | TODO | Findings Ledger Guild | LEDGER-29-003 | Implement workflow mutation handlers (assign, comment, accept-risk, target-fix, verify-fix, reopen) producing ledger events with validation and attachments metadata. | API endpoints enforce business rules; attachments metadata stored; tests cover state machine transitions. |
+| LEDGER-29-006 | TODO | Findings Ledger Guild, Security Guild | LEDGER-29-002 | Integrate attachment encryption (KMS envelope), signed URL issuance, CSRF protection hooks for Console. | Attachments encrypted and accessible via signed URLs; security tests verify expiry + scope. |
+| LEDGER-29-007 | TODO | Findings Ledger Guild, Observability Guild | LEDGER-29-002..005 | Instrument metrics (`ledger_write_latency`, `projection_lag_seconds`, `ledger_events_total`), structured logs, and Merkle anchoring alerts; publish dashboards. | Metrics/traces emitted; dashboards live; alert thresholds documented. |
+| LEDGER-29-008 | TODO | Findings Ledger Guild, QA Guild | LEDGER-29-002..005 | Develop unit/property/integration tests, replay/restore tooling, determinism harness, and load tests at 5M findings/tenant. | CI suite green; load tests documented; determinism harness proves stable projections. |
+| LEDGER-29-009 | TODO | Findings Ledger Guild, DevOps Guild | LEDGER-29-002..008 | Provide deployment manifests (Helm/Compose), backup/restore guidance, Merkle anchor externalization (optional), and offline kit instructions. | Deployment docs merged; smoke deploy validated; backup/restore scripts recorded; offline kit includes seed data. |
+
+## Export Center
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-EXPORT-35-001 | TODO | Findings Ledger Guild | LEDGER-29-003, EXPORT-SVC-35-002 | Provide paginated streaming endpoints for advisories, VEX, SBOMs, and findings aligned with export filters, including deterministic ordering and provenance metadata. | Streaming APIs deployed; integration tests with exporter planner; metrics/logs instrumented; docs updated. |
+
+## Orchestrator Dashboard
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-34-101 | TODO | Findings Ledger Guild | ORCH-SVC-34-002, LEDGER-29-002 | Link orchestrator run ledger exports into Findings Ledger provenance chain, index by artifact hash, and expose audit queries. | Ledger ingestion job consumes orchestrator exports; provenance queries return artifact chain; tests cover multi-tenant isolation; docs updated. |
+
+## CLI Parity & Task Packs
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-PACKS-42-001 | TODO | Findings Ledger Guild | LEDGER-29-003, TASKRUN-41-001 | Provide snapshot/time-travel APIs and digestable exports for task pack simulation and CLI offline mode. | Snapshot API deployed; simulation validated; docs updated; imposed rule noted. |
+
+## Authority-Backed Scopes & Tenancy (Epic 14)
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-TEN-48-001 | TODO | Findings Ledger Guild | AUTH-TEN-47-001 | Partition ledger tables by tenant/project, enable RLS, update queries/events, and stamp audit metadata. | Ledger queries respect tenant context; RLS tests pass; events include tenant metadata. |
+
+## Observability & Forensics (Epic 15)
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-OBS-50-001 | TODO | Findings Ledger Guild, Observability Guild | TELEMETRY-OBS-50-001, TELEMETRY-OBS-50-002 | Integrate telemetry core within ledger writer/projector services, emitting structured logs and trace spans for ledger append, projector replay, and query APIs with tenant context. | Telemetry present for append + replay flows; integration tests assert trace propagation; log schema validated. |
+| LEDGER-OBS-51-001 | TODO | Findings Ledger Guild, DevOps Guild | LEDGER-OBS-50-001, TELEMETRY-OBS-51-001 | Publish metrics for ledger latency, projector lag, event throughput, and policy evaluation linkage. Define SLOs (ledger append P95 < 1s, replay lag < 30s) with burn-rate alerts and dashboards. | Metrics surfaced in dashboards; SLO alerts configured/tested; documentation updated. |
+| LEDGER-OBS-52-001 | TODO | Findings Ledger Guild | LEDGER-29-002, TIMELINE-OBS-52-002 | Emit timeline events for ledger writes and projector commits (`ledger.event.appended`, `ledger.projection.updated`) with trace ID, policy version, evidence bundle reference placeholders. | Timeline events validated with fixtures; duplicates suppressed; docs note schema. |
+| LEDGER-OBS-53-001 | TODO | Findings Ledger Guild, Evidence Locker Guild | LEDGER-OBS-52-001, EVID-OBS-53-002 | Persist evidence bundle references (evaluation/job capsules) alongside ledger entries, exposing lookup API linking findings to evidence manifests and timeline. | Evidence references stored/retrievable; API returns deterministic payload; integration tests pass. |
+| LEDGER-OBS-54-001 | TODO | Findings Ledger Guild, Provenance Guild | LEDGER-OBS-53-001, PROV-OBS-54-001 | Verify attestation references for ledger-derived exports; expose `/ledger/attestations` endpoint returning DSSE verification state and chain-of-custody summary. | Endpoint returns verification results; negative cases handled; docs updated. |
+| LEDGER-OBS-55-001 | TODO | Findings Ledger Guild, DevOps Guild | LEDGER-OBS-51-001, DEVOPS-OBS-55-001 | Enhance incident mode to record additional replay diagnostics (lag traces, conflict snapshots) and extend retention while active. Emit activation events to timeline + notifier. | Incident mode captures diagnostics; retention adjustments revert post-incident; timeline/notifications validated. |
+
+## Air-Gapped Mode (Epic 16)
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-AIRGAP-56-001 | TODO | Findings Ledger Guild | AIRGAP-IMP-57-001, CONCELIER-AIRGAP-56-002 | Record bundle provenance (`bundle_id`, `merkle_root`, `time_anchor`) on ledger events for advisories/VEX/policies imported via Mirror Bundles. | Ledger entries include bundle metadata; queries expose provenance; tests cover import + replay. |
+| LEDGER-AIRGAP-56-002 | TODO | Findings Ledger Guild, AirGap Time Guild | LEDGER-AIRGAP-56-001, AIRGAP-TIME-58-001 | Surface staleness metrics for findings and block risk-critical exports when stale beyond thresholds; provide remediation messaging. | Staleness thresholds enforced; exports blocked when stale; notifications triggered. |
+| LEDGER-AIRGAP-57-001 | TODO | Findings Ledger Guild, Evidence Locker Guild | LEDGER-AIRGAP-56-001, EVID-OBS-54-001 | Link findings evidence snapshots to portable evidence bundles and ensure cross-enclave verification works. | Evidence references validated; portable bundles verify across environments; integration tests updated. |
+| LEDGER-AIRGAP-58-001 | TODO | Findings Ledger Guild, AirGap Controller Guild | LEDGER-AIRGAP-56-001, AIRGAP-CTL-56-002 | Emit timeline events for bundle import impacts (new findings, remediation changes) with sealed-mode context. | Timeline events emitted with bundle IDs; duplicates suppressed; docs updated. |
+
+## SDKs & OpenAPI (Epic 17)
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-OAS-61-001 | TODO | Findings Ledger Guild, API Contracts Guild | OAS-61-001 | Expand Findings Ledger OAS to include projections, evidence lookups, and filter parameters with examples. | Spec covers all ledger endpoints; lint/compat checks pass. |
+| LEDGER-OAS-61-002 | TODO | Findings Ledger Guild | LEDGER-OAS-61-001 | Implement `/.well-known/openapi` endpoint and ensure version metadata matches release. | Discovery endpoint live; contract tests added. |
+| LEDGER-OAS-62-001 | TODO | Findings Ledger Guild, SDK Generator Guild | LEDGER-OAS-61-001, SDKGEN-63-001 | Provide SDK test cases for findings pagination, filtering, evidence links; ensure typed models expose provenance. | SDK smoke tests cover ledger flows; documentation embeds examples. |
+| LEDGER-OAS-63-001 | TODO | Findings Ledger Guild, API Governance Guild | APIGOV-63-001 | Support deprecation headers and Notifications for retiring finding endpoints. | Headers emitted; notifications validated; docs updated. |
+
+## Risk Profiles (Epic 18)
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-RISK-66-001 | TODO | Findings Ledger Guild, Risk Engine Guild | RISK-ENGINE-66-001 | Add schema migrations for `risk_score`, `risk_severity`, `profile_version`, `explanation_id`, and supporting indexes. | Migrations applied; indexes created; schema docs updated. |
+| LEDGER-RISK-66-002 | TODO | Findings Ledger Guild | LEDGER-RISK-66-001 | Implement deterministic upsert of scoring results keyed by finding hash/profile version with history audit. | Upsert path tested; duplicate suppression verified; audit records stored. |
+| LEDGER-RISK-67-001 | TODO | Findings Ledger Guild, Risk Engine Guild | LEDGER-RISK-66-002, RISK-ENGINE-68-001 | Expose query APIs for scored findings with score/severity filters, pagination, and explainability links. | API documented; contract tests pass; latency within targets. |
+| LEDGER-RISK-68-001 | TODO | Findings Ledger Guild, Export Guild | LEDGER-RISK-66-002 | Enable export of scored findings and simulation results via Export Center integration. | Export job functional; CLI/Console consume bundle; verification tests pass. |
+| LEDGER-RISK-69-001 | TODO | Findings Ledger Guild, Observability Guild | LEDGER-RISK-66-001 | Emit metrics/dashboards for scoring latency, result freshness, severity distribution, provider gaps. | Dashboards live; alerts configured; documentation updated. |
+
+## Attestor Console (Epic 19)
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| LEDGER-ATTEST-73-001 | TODO | Findings Ledger Guild, Attestor Service Guild | ATTESTOR-73-002 | Persist pointers from findings to verification reports and attestation envelopes for explainability. | Ledger schema extended; queries return linked evidence; tests cover joins. |
+| LEDGER-ATTEST-73-002 | TODO | Findings Ledger Guild | LEDGER-ATTEST-73-001 | Enable search/filter in findings projections by verification result and attestation status. | API filters by verification result; UI integration ready; tests updated. |