work

docs/modules/concelier/api/evidence-batch.md

@@ -0,0 +1,73 @@
+# Concelier Evidence Batch API (draft v1)  
+  
+Path: `POST /v1/evidence/batch`  
+Auth: same as other advisory read endpoints; requires tenant header `X-Stella-Tenant`.  
+Purpose: allow graph/UI/export clients to fetch observations and linksets for a set of components (purls/aliases) in one round-trip, without derived judgments.  
+  
+## Request  
+```json
+{
+  "items": [
+    {
+      "componentId": "component-a",
+      "purls": ["pkg:maven/org.example/app@1.0.0"],
+      "aliases": ["CVE-2025-0001"]
+    }
+  ],
+  "observationLimit": 50,
+  "linksetLimit": 50
+}
+```
+  
+Field rules:  
+- `items` is required and must be non-empty.  
+- Each item must supply at least one identifier (`purls` or `aliases`).  
+- `observationLimit` and `linksetLimit` default to 50, max 200; values ≤0 are ignored.  
+  
+## Response  
+```json
+{
+  "items": [
+    {
+      "componentId": "component-a",
+      "observations": [
+        {
+          "id": "obs:123",
+          "tenant": "demo",
+          "aliases": ["CVE-2025-0001"],
+          "purls": ["pkg:maven/org.example/app@1.0.0"],
+          "source": "nvd",
+          "asOf": "2025-11-25T12:00:00Z"
+        }
+      ],
+      "linksets": [
+        {
+          "advisoryId": "CVE-2025-0001",
+          "source": "nvd",
+          "normalized": {
+            "purls": ["pkg:maven/org.example/app@1.0.0"]
+          },
+          "createdAt": "2025-11-25T12:00:00Z"
+        }
+      ],
+      "hasMore": false,
+      "retrievedAt": "2025-11-25T12:00:01Z"
+    }
+  ]
+}
+```
+  
+Determinism:  
+- Results ordered by provider ordering returned from storage; clients must not assume stable sort keys beyond the documented arrays.  
+- `retrievedAt` is server UTC ISO-8601.  
+- `hasMore` is true if either observations or linksets were truncated by the supplied limits.  
+  
+Notes:  
+- No derived severity/weights are added; payloads mirror stored observations/linksets.  
+- For empty matches, the endpoint returns empty `observations` and `linksets` with `hasMore=false`.  
+  
+Fixtures:  
+- Sample request/response above; further fixtures can be generated from `docs/samples/lnm/` data once LNM v1 fixtures are refreshed.  
+  
+Changelog:  
+- 2025-11-25: initial draft and implementation aligned with `/v1/evidence/batch` endpoint.  

docs/modules/concelier/implementation_plan.md

@@ -56,12 +56,18 @@
 - **Unit**: guard rejection paths, provenance enforcement, idempotent insertions, linkset determinism.
 - **Property**: fuzz upstream payloads to guarantee no forbidden fields emerge.
 - **Integration**: batch ingest (50k advisories, mixed VEX fixtures), verifying zero guard violations and consistent supersedes.
-- **Contract**: Policy Engine consumers verify raw-only reads; Export Center consumes canonical datasets.
-- **End-to-end**: ingest/verify flow with CLI + Console actions to confirm observability and guard reporting.
-
-## Definition of done
-- Validators deployed and verified in staging/offline environments.
-- Runtime guards, CLI/Console workflows, and CI linting all active.
-- Observability dashboards and runbooks updated; metrics visible.
-- Documentation updates merged; Offline Kit instructions published.
-- ./TASKS.md reflects status transitions; cross-module dependencies acknowledged in ../../TASKS.md.
+- **Contract**: Policy Engine consumers verify raw-only reads; Export Center consumes canonical datasets.
+- **End-to-end**: ingest/verify flow with CLI + Console actions to confirm observability and guard reporting.
+
+## Definition of done
+- Validators deployed and verified in staging/offline environments.
+- Runtime guards, CLI/Console workflows, and CI linting all active.
+- Observability dashboards and runbooks updated; metrics visible.
+- Documentation updates merged; Offline Kit instructions published.
+- ./TASKS.md reflects status transitions; cross-module dependencies acknowledged in ../../TASKS.md.
+
+## Readiness checkpoints (2025-11-25)
+- Sprint 110 attestation chain validated: `/internal/attestations/verify` endpoint and evidence bundle tests green (`TestResults/concelier-attestation/web.trx`, `core.trx`).
+- Link-Not-Merge cache + console consumption docs frozen (see `operations/lnm-cache-plan.md`, `operations/console-lnm-consumption.md`); cache headers remain deterministic.
+- Observation events transport reviewed; backlog guardrails and NATS/air-gap guidance updated in `operations/observation-events.md`.
+- Next gating dependency: TaskRunner contract drop (sprint 0157 blockers) before wiring approvals/pack ingest flows into Concelier.

docs/modules/concelier/operations/observation-events.md

@@ -29,3 +29,9 @@ Defaults: disabled, transport `mongo`; subject/stream as above.
 ## Testing
 - Without NATS: leave `enabled=false`; app continues writing outbox only.
 - With NATS: run a local `nats-server -js` and set `enabled=true transport=nats`. Verify published messages on subject via `nats sub concelier.advisory.observation.updated.v1`.
+
+## 2025-11-25 demo review notes
+- Verified attestation demo emits `StellaOps.Concelier.Advisory.Observations` meter with counters `events_published_total` and gauges `outbox_backlog`. Ensure these metrics are scraped with tenant labels.
+- Backlog guard: alert if `outbox_backlog > 500` for 10m while `transport=nats`; recommended SLO is P95 publish latency < 2s.
+- When transport disabled for air-gap runs, confirm background worker remains paused (`enabled=false`) to avoid noisy retries; resume only after mirror bundles restored.
+- TRX from `/internal/attestations/verify` suite lives at `TestResults/concelier-attestation/web.trx` for current demo build; keep alongside dashboards for reproducibility.