Shared conventions for all StellaOps HTTP APIs. Service-specific schemas live under `src/Api/StellaOps.Api.OpenApi` and composed `out/api/stella.yaml`.
## Authentication & tenancy
- **Auth**: Bearer tokens (`Authorization: Bearer <token>`); service accounts must include `aud` for the target service.
- **Tenancy**: Multi-tenant endpoints require `X-Stella-Tenant` (or embedded tenant in token claims). Requests without tenant fail with `403` + `error.code = TENANT_REQUIRED`.
- **Scopes**: Each endpoint documents required scopes; clients must send least-privilege tokens.
Publish a deterministic, offline-friendly API reference site generated from the consolidated OpenAPI (`out/api/stella.yaml`) and integrate it into the developer portal navigation.
## Generation steps
1) Build the consolidated spec:
```bash
pnpm api:build # produces out/api/stella.yaml
pnpm api:lint # optional: spectral lint
pnpm api:compat # optional: compat check vs stella-baseline.yaml
```
2) Generate static reference:
```bash
pnpm api:reference # expected to write to out/api/reference/
```
The command should:
- Use the bundled `out/api/stella.yaml`.
- Produce deterministic HTML/CSS/JS assets (no timestamps in bundles).
- Avoid external CDNs; fonts/assets must be local for air-gap.
3) Verify determinism/offline:
- Compare hashes of `out/api/reference/` across two runs → must match.
- Open `out/api/reference/index.html` without network access.
## Portal integration
- Copy `out/api/reference/` into the developer portal static assets under `/reference/`.
- Add nav link “API Reference” pointing to `/reference/`.
- Ensure CSP allows only self-hosted assets (`default-src 'self'`).
- **Long-lived compatibility**: At least N-1 major versions remain runnable for 12 months; minor versions remain compatible for 6 months after release unless a security fix requires earlier removal.
- **Explicit deprecations**: Every breaking removal/change is preceded by a deprecation window with headers and changelog entries.
- **Deterministic specs**: Generated `out/api/*.yaml` are reproducible from a pinned manifest and committed checksums.
## How versions are expressed
- **Base URL**: `/api/v{major}/...` (e.g., `/api/v1/policy`). Major only; minor/patch controlled via headers.
- **Headers**:
-`X-Stella-Api-Version: <major.minor.patch>` → client-requested minor/patch; server chooses the highest compatible available ≤ requested. If omitted, server serves the latest compatible minor/patch for that major.
-`Deprecation: true` + `Sunset: <rfc7231-date>` returned when an endpoint or field is scheduled for removal.
-`X-Stella-Api-Deprecated-Fields: field1,field2` lists soon-to-be-removed members for the response.
- **Error codes**:
-`error.code = API_VERSION_UNSUPPORTED` when requested major is not served.
-`error.code = API_VERSION_TOO_OLD` when requested minor/patch is below the minimum supported for the major.
## Compatibility rules
- Additive changes (new fields/enums/paths) are allowed within the same major; fields default to `null`/empty and must not change meaning.
- Breaking changes require a new major: field removals/renames, required field additions, behavior changes that alter contracts.
- Enum extensions: existing values remain; new values must be tolerated by clients.
- Pagination/order: sort keys and determinism must be preserved across versions.
## Release & lifecycle
1) Draft OpenAPI in `src/Api/StellaOps.Api.OpenApi` and update `out/api/stella.yaml`.
2) Run `pnpm api:lint` + `pnpm api:compat --baseline stella-baseline.yaml` to ensure no unintended breaks.
3) Publish changelog entry under `out/api/changelog/<yyyyMMdd>-<version>.md` with checksums/signature.
4) Announce deprecations via release notes; include `Deprecation`/`Sunset` headers in affected endpoints for at least 60 days before removal.
5) Sunset execution: remove endpoints/fields only after the sunset date and after the major bump ships.
## Client guidance
- Always send `X-Stella-Api-Version` to lock to a tested minor/patch; pin SDK versions accordingly.
- Handle `Deprecation`/`Sunset` headers by warning users and planning upgrades.
- Prefer server-provided pagination tokens; avoid relying on incidental field order.
## Testing
- Contract tests must cover the lowest and highest supported minor/patch for each major.
- Deterministic fixtures for each version live under `tests/fixtures/api/versioning/`; CI runs `pnpm api:compat` against these fixtures.
This guide explains how to propose, review, and publish API contract changes across StellaOps services. Follow these steps whenever you modify an OpenAPI specification or an externally supported endpoint.
Last updated: 2025-11-25
## 1. Background
## Scope
Guidelines for editing service OpenAPI specs, lint rules, compatibility checks, and release artefacts across StellaOps services.
- Public APIs are defined in `src/Api/StellaOps.Api.OpenApi` (aggregate spec) and per-service OpenAPI documents.
-Compatibility checks run in CI via the API Governance tooling (`StellaOps.Api.Governance`).
-Docs & SDK guilds consume the generated specs to publish references and SDK packages.
## Required tools
-Node.js 20.x + pnpm 9.x
-Spectral CLI (invoked via `pnpm api:lint` in `src/Api/StellaOps.Api.OpenApi`)
-`diff2html` (optional) for human-friendly compat reports
## 2. Workflow
## Workflow (per change)
1) Edit service OAS under `src/Api/StellaOps.Api.OpenApi/services/<service>/*.yaml`.
2) Run lint + compose + compat + changelog from repo root:
- `out/api/compat-report.json` (+ `.html` if generated)
- `out/api/changelog/` (digest + signature for SDK pipeline)
4) Update examples: ensure request/response examples exist for changed endpoints; add to `examples/` directories.
5) Commit changes with notes on breaking/additive results; attach compat report paths.
1.**Design review**– capture the proposed endpoint or schema change in the relevant module’s `TASKS.md` and link to any ADR or design doc.
2.**Spec update**– modify the service-specific OpenAPI file under `src/Api/StellaOps.Api.OpenApi/<service>/`.
3.**Run governance checks**– execute `dotnet test src/Api/StellaOps.Api.Governance.Tests` to validate lint rules, backwards compatibility, and examples.
4.**Regenerate aggregate spec**– run `dotnet run --project src/Api/StellaOps.Api.OpenApi` to update `stella.yaml`.
5.**Update docs**– adjust the corresponding module dossier (`docs/modules/<component>/architecture.md` or guides) to reflect new/changed endpoints.
6.**Notify SDK/Docs guilds**– coordinate SDK regeneration (`src/Sdk/StellaOps.Sdk.Generator`) and release notes.
## Lint rules (Spectral)
- House rules live in `.spectral.yaml` under `src/Api/StellaOps.Api.OpenApi`.
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 0 | OPS-CLEAN-DISK-001 | BLOCKED (2025-11-25) | Free disk space on dev runner (`bin/obj`, TestResults, ops/devops/artifacts/ci-110) to allow builds/tests. | DevOps | Clear workspace storage so orchestrator WebService tests can run. |
| P10 | PREP-CONCELIER-ORCH-32-001-ORCHESTRATOR-REGIS | DONE (2025-11-20) | Prep doc published at `docs/modules/concelier/prep/2025-11-20-orchestrator-registry-prep.md`; ready for implementation wiring. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Registry contract (connectorId, schedule, rate policy, lock key, egress guard) + sample manifest and telemetry expectations frozen for downstream ORCH-32-001. |
| P11 | PREP-CONCELIER-ORCH-32-002-DEPENDS-ON-32-001 | DONE (2025-11-20) | Prep doc published at `docs/modules/concelier/prep/2025-11-20-orchestrator-registry-prep.md`; ready for worker SDK adoption. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Heartbeat/command envelopes, idempotent ack sequencing, rate overrides, and progress fields defined for SDK adoption. |
| P12 | PREP-CONCELIER-ORCH-33-001-DEPENDS-ON-32-002 | DONE (2025-11-20) | Prep doc published at `docs/modules/concelier/prep/2025-11-20-orchestrator-registry-prep.md`; pause/throttle controls defined. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Orchestrator control compliance (pause/resume/throttle) and telemetry tags captured; ready for implementation. |
| 12 | CONCELIER-ORCH-33-001 | BLOCKED (2025-11-25) | Blocked by 32-001/32-002 validation and CI availability. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Honor orchestrator pause/throttle/retry controls with structured errors and persisted checkpoints. |
| 13 | CONCELIER-ORCH-34-001 | BLOCKED (2025-11-25) | Blocked until 32-002/33-001 validated on CI; backfill tests pending. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Execute orchestrator-driven backfills reusing artifact hashes/signatures, logging provenance, and pushing run metadata to ledger. |
| 10 | CONCELIER-ORCH-32-001 | BLOCKED (2025-11-25) | CI build + orchestrator WebService tests blocked by disk-full runner; need clean space/CI (DEVOPS-CONCELIER-CI-24-101) to validate. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Register every advisory connector with orchestrator (metadata, auth scopes, rate policies) for transparent, reproducible scheduling. |
| 11 | CONCELIER-ORCH-32-002 | BLOCKED (2025-11-25) | Blocked on 32-001 and disk exhaustion preventing test runs. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Adopt orchestrator worker SDK in ingestion loops; emit heartbeats/progress/artifact hashes for deterministic replays. |
| 12 | CONCELIER-ORCH-33-001 | BLOCKED (2025-11-25) | Blocked by 32-001/32-002 validation and disk-full test runner. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Honor orchestrator pause/throttle/retry controls with structured errors and persisted checkpoints. |
| 13 | CONCELIER-ORCH-34-001 | BLOCKED (2025-11-25) | Blocked until 32-002/33-001 validated; test runner out of disk space. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Execute orchestrator-driven backfills reusing artifact hashes/signatures, logging provenance, and pushing run metadata to ledger. |
| 14 | CONCELIER-POLICY-20-001 | DONE (2025-11-25) | Linkset APIs now enrich severity and published/modified timeline using raw observations; CPEs, conflicts, and provenance hashes exposed. | Concelier WebService Guild (`src/Concelier/StellaOps.Concelier.WebService`) | Provide batch advisory lookup APIs for Policy Engine (purl/advisory filters, tenant scopes, explain metadata) so policy joins raw evidence without inferred outcomes. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-11-25 | Runner disk is full (“No space left on device”); orchestrator WebService tests cannot be re-run. Free bin/obj/TestResults and `ops/devops/artifacts/ci-110` before continuing ORCH-32/33/34. | Concelier Core |
| 2025-11-25 | Storage.Mongo job-store slice executed locally: `dotnet test src/Concelier/__Tests/StellaOps.Concelier.Storage.Mongo.Tests/StellaOps.Concelier.Storage.Mongo.Tests.csproj -c Debug --no-restore --no-build --filter FullyQualifiedName~MongoJobStore` (3/3 pass). TRX: `ops/devops/artifacts/ci-110/20251125T034529Z/trx/concelier-storage-jobstore.trx`. Broader suite still pending CI. | Concelier Core |
| 2025-11-25 | WebService orchestrator filter run (`dotnet test ...WebService.Tests.csproj --filter FullyQualifiedName~Orchestrator`) produced no matching tests; TRX recorded at `ops/devops/artifacts/ci-110/20251125T040900Z/trx/concelier-web-orch.trx`. Need to add orchestrator WebService tests before closing ORCH-32/33/34. | Concelier Core |
| 2025-11-25 | Attempted to add WebService orchestrator tests with Mongo bypass; repo disk is full (`No space left on device`), preventing further builds/tests. Cleanup of bin/obj/TestResults and ops/devops artifacts required before rerunning orchestrator test slice. | Concelier Core |
| 2025-11-25 | Added observation-backed severity/published/modified projection to `/v1/lnm/linksets*`; updated integration test to assert timeline/published fields. POLICY-20-001 closed. | Implementer |
| 2025-11-25 | Marked CONCELIER-ORCH-32/33/34 chain BLOCKED: local build fails on Aoc.AspNetCore dependency and orchestrator WebService tests are absent; needs CI runner DEVOPS-CONCELIER-CI-24-101 and new tests before proceeding. | Implementer |
| 2025-11-25 | Targeted orchestrator tests (Storage.Mongo) succeeded previously with filter `--filter Orchestrator` but full suite still hangs; CI runner needed for full coverage. | Concelier Core |
@@ -88,6 +91,7 @@
| 2025-11-24 | Marked CONCELIER-POLICY-20-001 BLOCKED: upstream linkset/ingest lacks authoritative severity data and published/modified timestamps; cannot emit full severity/timeline fields until schema and data are supplied. | Concelier Core |
## Decisions & Risks
- Disk space on the dev runner is exhausted (`No space left on device`), blocking `dotnet test` for orchestrator endpoints; free `src/Concelier/**/bin|obj`, stale TestResults, and `ops/devops/artifacts/ci-110` before rerunning ORCH-32/33/34.
- Link-Not-Merge and OpenAPI alignment must precede SDK/examples; otherwise downstream clients will drift from canonical facts.
- Observability/attestation chain (OBS-51…55) risks audit gaps if sequencing slips; each step depends on previous artifacts.
- Orchestrator control compliance is required to prevent evidence loss during throttles/pauses.
@@ -105,6 +109,7 @@
- WebService `/internal/orch/*` endpoints now land registry upserts, heartbeats, and commands into Mongo store; worker consumption and orchestrator authentication scopes still to be validated before closing tasks.
- Build remains blocked by CS8620 nullable mismatch in `LinksetCorrelation.cs` (linkset aggregation); patch applied but nullability config appears to treat warning as error—needs follow-up to clear WebService build.
- ORCH-32/33/34 implementation blocked locally by missing package restore/nullability errors; CI or clean runner required to validate before proceeding with worker SDK wiring.
- Disk space exhausted on dev runner, preventing further test/build execution; must clear `src/Concelier/**/bin|obj`, stale TestResults, and `ops/devops/artifacts/ci-110` before rerunning ORCH test slice.
## Next Checkpoints
- Schedule OpenAPI/SDK review once CONCELIER-OAS-61-001 draft ready (date TBD, gated on Sprint 0113 outputs).
| 2025-11-25 | RISK-ENGINE-67-002 DONE: VEX gate provider added with short-circuit tests; packaged in RiskEngine queue/worker pipeline. | Implementer |
| 2025-11-25 | RISK-ENGINE-67-001 DONE: added CVSS+KEV provider and tests; score formula clamp((cvss/10)+0.2 if KEV). | Implementer |
| 2025-11-25 | RISK-ENGINE-68-001 DONE: risk score worker now persists results via result store abstraction; in-memory store added plus persistence tests; TRX at `TestResults/risk-engine/risk.trx`. | Implementer |
| 2025-11-25 | RISK-ENGINE-67-003 DONE: fix-availability/criticality/exposure provider added with missing-signal default tests; TRX at `TestResults/risk-engine/risk.trx`. | Implementer |
| 2025-11-25 | RISK-ENGINE-68-002 DONE: exposed provider list, job submit/retrieve, and batch simulation APIs; in-memory result store wired; integration tests green at `TestResults/risk-engine/api.trx`. | Implementer |
| 2025-11-25 | Marked VEXLENS-30-002..30-011 BLOCKED because upstream VEXLENS-30-001 remains blocked on normalization schema + issuer directory + API governance specs; mirrored to tasks-all. | Project Mgmt |
| 2025-11-25 | Marked VEXLENS-30-001 BLOCKED pending normalization schema, issuer directory inputs, and API governance guidance; downstream VEXLENS tasks remain TODO and depend on this. | Project Mgmt |
| 2025-11-25 | Removed legacy `SPRINT_129_policy_reasoning.md`, pointed trackers to canonical name, and created `src/VexLens/StellaOps.VexLens/TASKS.md` mirroring VEX Lens tasks; statuses remain TODO pending upstream specs. | Project Mgmt |
| 2025-11-25 | Marked REGISTRY-API-27-001..010 and POLICY-TEN-48-001 BLOCKED; Registry/OpenAPI and tenancy design inputs are absent, so downstream registry work cannot start. | Implementer |
| 2025-11-19 | Normalized to standard template and renamed from `SPRINT_129_policy_reasoning.md` to `SPRINT_0129_0001_0001_policy_reasoning.md`; content preserved. | Implementer |
| 2025-11-25 | Work paused: repository cannot allocate PTY (`No space left on device`); further execution awaits workspace cleanup. | Implementer |
## Decisions & Risks
- Multiple upstream specs missing (Registry API, Risk Engine contracts, VEX consensus schema, issuer directory, API governance, VulnExplorer API); VEXLENS-30-001 blocked until normalization + issuer inputs land; downstream tasks depend on it.
| 2025-11-18 | Marked all AIRGAP controller/importer/time tasks BLOCKED: no project scaffolds exist under src/AirGap; need baseline service skeletons and token format decisions before implementation. | Ops/Docs |
| 2025-11-18 | Normalised sprint to standard template; renamed from SPRINT_510_airgap.md. | Ops/Docs |
| 2025-11-25 | Created module charter `src/AirGap/AGENTS.md`; controller tasks unblocked from AGENTS gap. | Implementer |
| 2025-11-25 | Local environment out of disk space (`No space left on device`); controller tasks moved to BLOCKED until workspace is cleaned. | Implementer |
| 2025-11-25 | Blocked controller chain (tasks 1–5): module-level `src/AirGap/AGENTS.md` missing; cannot proceed per working agreements until charter exists. Added status notes. | Implementer |
## Decisions & Risks
- Seal/unseal + importer rely on release pipeline outputs (trust roots, manifests); delays there delay this sprint.
@@ -80,6 +83,7 @@
- Offline posture: ensure all verification runs without egress; CMK/KMS access must have offline-friendly configs.
- Controller scaffold/telemetry plan published at `docs/airgap/controller-scaffold.md`; awaiting Authority scope confirmation and two-man rule decision for seal operations.
- Repo integrity risk: current git index appears corrupted (phantom deletions across repo). Requires repair before commit/merge to avoid data loss.
- Local execution risk: runner reports “No space left on device”; cannot run builds/tests until workspace is cleaned. Mitigation: purge transient artefacts or expand volume before proceeding.
## Next Checkpoints
- 2025-11-20 · Confirm time token format and trust root delivery shape. Owner: AirGap Time Guild.
- 2025-11-25 · DOCS-ATTEST-75-001/002 delivered: added attestor air-gap guide and AOC attestation invariants; statuses mirrored to tasks-all.
- 2025-11-25 · DOCS-CLI-41-001 delivered: added CLI overview/configuration/output-and-exit-codes guides under `docs/modules/cli/guides/`; status mirrored to tasks-all.
- 2025-11-25 · DOCS-CLI-42-001 delivered: parity matrix plus command guides for policy, sbom, vuln, vex, advisory, export, orchestrator, notify, aoc, auth added under `docs/modules/cli/guides/commands/`; status mirrored to tasks-all.
- 2025-11-25 · DOCS-CLI-OBS-52-001 and DOCS-CLI-FORENSICS-53-001 delivered: added `observability.md` and `forensics.md` under `docs/modules/cli/guides/`; statuses mirrored to tasks-all.
- 2025-11-25 · DOCS-DEVPORT-62-001 delivered: new `docs/devportal/publishing.md` covering build/publish (online/offline), manifests, checksums, deployment targets, and release checklist; status mirrored to tasks-all.
- 2025-11-25 · DOCS-CONTRIB-62-001 delivered: added `docs/contributing/api-contracts.md` with OAS edit workflow, lint/compat/changelog steps, offline bundle guidance, and release checklist; status mirrored to tasks-all.
Summary: Documentation & Process focus on Docs Tasks (phase Md.V).
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
DOCS-INSTALL-44-001 | TODO | Publish `/docs/install/overview.md` and `/docs/install/compose-quickstart.md` with imposed rule line and copy-ready commands. | Docs Guild, Deployment Guild (docs)
DOCS-INSTALL-45-001 | TODO | Publish `/docs/install/helm-prod.md` and `/docs/install/configuration-reference.md` with values tables and imposed rule reminder. Dependencies: DOCS-INSTALL-44-001. | Docs Guild, Deployment Guild (docs)
Summary: Documentation & Process focus on Docs Tasks (phase Md.VI).
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
DOCS-OAS-62-001 | TODO | Stand up `/docs/api/reference/` auto-generated site; integrate with portal nav. Dependencies: DOCS-OAS-61-003. | Docs Guild, Developer Portal Guild (docs)
DOCS-OBS-50-002 | TODO | Author `/docs/observability/telemetry-standards.md` detailing common fields, scrubbing policy, sampling defaults, and redaction override procedure. | Docs Guild, Security Guild (docs)
DEVOPS-REL-17-004 | DONE (2025-11-23) | Release workflow now uploads `out/release/debug` (build-id tree + manifest) as a separate artefact and fails when symbols are missing. | DevOps Guild (ops/devops)
DEVOPS-SDK-63-001 | TODO | Provision registry credentials, signing keys, and secure storage for SDK publishing pipelines. | DevOps Guild, SDK Release Guild (ops/devops)
DEVOPS-SIG-26-001 | TODO | Provision CI/CD pipelines, Helm/Compose manifests for Signals service, including artifact storage and Redis dependencies. | DevOps Guild, Signals Guild (ops/devops)
DEVOPS-SIG-26-002 | TODO | Create dashboards/alerts for reachability scoring latency, cache hit rates, sensor staleness. Dependencies: DEVOPS-SIG-26-001. | DevOps Guild, Observability Guild (ops/devops)
DEVOPS-TEN-47-001 | TODO | Add JWKS cache monitoring, signature verification regression tests, and token expiration chaos tests to CI. | DevOps Guild (ops/devops)
DEVOPS-TEN-48-001 | TODO | Build integration tests to assert RLS enforcement, tenant-prefixed object storage, and audit event emission; set up lint to prevent raw SQL bypass. Dependencies: DEVOPS-TEN-47-001. | DevOps Guild (ops/devops)
- 2025-11-25 · MIRROR-CRT-56-CI-001 completed: CI signing script now emits milestone hash summary, enforces DSSE/TUF/time-anchor steps, and uploads `milestone.json` via `mirror-sign.yml`.
- 2025-11-25 · DEVOPS-OBS-55-001 completed: added offline incident-mode automation script (`scripts/observability/incident-mode.sh`) and runbook (`ops/devops/observability/incident-mode.md`) to auto-toggle incident flag, retention overrides, and cooldown reset based on burn rate inputs.
- 2025-11-25 · DEVOPS-ORCH-32-001 completed: added orchestrator infra compose stack (Postgres+Mongo+NATS), smoke script (`scripts/orchestrator/smoke.sh`), alerts, Grafana dashboard, and bootstrap README under `ops/devops/orchestrator/`.
- 2025-11-25 · DEVOPS-ORCH-33-001 completed: expanded orchestrator Grafana with DLQ/backpressure/error panels and alerts (`ops/devops/orchestrator/alerts.yaml`); dashboard lives at `ops/devops/orchestrator/grafana/orchestrator-overview.json`.
- 2025-11-25 · DEVOPS-POLICY-27-003 completed: cosign key rotation/signing/attestation scripts added (`scripts/policy/rotate-key.sh`, `sign-policy.sh`, `attest-verify.sh`), CI attestation verification stage wired into `.gitea/workflows/policy-simulate.yml`, and runbook recorded at `ops/devops/policy-signing.md`.
- 2025-11-25 · DEVOPS-TEN-47-001 marked BLOCKED: JWKS cache/chaos testing requires runnable Authority instance and tenant fixture; upstream Authority/tenancy harness not present in repo.
- 2025-11-25 · DEVOPS-TEN-48-001 marked BLOCKED: RLS/object-store/audit integration tests depend on TEN-47 harness and tenant-aware data plane not available in this sprint scope.
- 2025-11-25 · DEVOPS-LEDGER-29-009-REL marked BLOCKED: release packaging awaits LEDGER-29-009 dev outputs and manifests not present in repo.
- 2025-11-25 · DEVOPS-LEDGER-TEN-48-001-REL marked BLOCKED: RLS migrations/artefacts depend on ledger tenant partition work not yet delivered.
- 2025-11-25 · DEVOPS-SCANNER-JAVA-21-011-REL marked BLOCKED: Java analyzer plugin artefacts from SCANNER-ANALYZERS-JAVA-21-011 dev are not available to package.
- 2025-11-25 · DEVOPS-RULES-33-001 completed: codified rules anchor in `ops/devops/rules/contracts-anchor.md` and closed review.
- 2025-11-25 · Work paused: host cannot allocate PTY (`No space left on device`); further CI/script execution blocked until disk/pty space is freed.
- 2025-11-25 · Added disk cleanup helper `scripts/devops/cleanup-workspace.sh` (safe defaults, optional bin/obj) to unblock low-space runners; use `DRY_RUN=1` to preview.
- 2025-11-25 · Documented space recovery steps in `ops/devops/README-space.md` (cleanup script, docker prune, nuget cache clear, artefact dirs).
- 2025-11-25 · DEVOPS-SIG-26-001 completed: added Signals Dockerfile/compose stack (`ops/devops/signals/`), Helm values (`helm/signals/values-signals.yaml`), CI workflow (`.gitea/workflows/signals-ci.yml`), and image export helper (`scripts/signals/build.sh`) with Mongo/Redis dependencies and artifact volume.
- 2025-11-25 · DEVOPS-SIG-26-002 completed: added Signals observability pack—alerts (`ops/devops/observability/signals-alerts.yaml`), Grafana dashboard (`ops/devops/observability/grafana/signals-pipeline.json`), and playbook (`ops/devops/observability/signals-playbook.md`) for scoring latency, cache hit rate, ingestion failures, and sensor staleness.
| 2025-11-25 | Relocated remaining ops-track items (EXPORT-OBS-51-001, OBS-51/53-001, TIME-57-001, CLI-AIRGAP-56-001, MIRROR-CRT-56/57/58) to Ops sprints 503/0506 per “no ops in dev sprint” rule; sprint now has zero open TODO/BLOCKED rows. | Project Mgmt |
| 2025-11-25 | Added `tools/run-airgap-bundle-tests.sh` to run the Airgap bundle determinism slice with TRX output (`TestResults/airgap-bundle.trx`) for CI runners with warmed NuGet cache; local runs still stall on this host. | Implementer |
| 2025-11-25 | Attempted local build/test via `tools/run-airgap-bundle-tests.sh`; restore/build stalled and was cancelled (~12s). Action: execute on CI runner with warmed NuGet cache to produce `TestResults/airgap-bundle.trx`. | Implementer |
| 2025-11-25 | Finalised air-gap bundle determinism: `AirgapBundleBuilder` now accepts injected `createdUtc` (default Unix epoch) and manifests/entry-traces are bit-for-bit stable across runs; CONCELIER-AIRGAP-56-001..58-001 dependencies (LNM schema + Evidence Locker contract) closed out. | Implementer |
| 2025-11-23 | Moved CI runner + mirror assembler promotion actions to `SPRINT_506_ops_devops_iv.md`; Sprint 0110 now tracks development deliverables only. | Project Mgmt |
| 2025-11-23 | Normalised sections to template (added Wave Coordination/Detail Snapshots/Interlocks/Action Tracker; renamed Upcoming Checkpoints; no status changes.) | Project Mgmt |
| 2025-11-23 | Implemented graph overlays endpoint `/v1/graph/overlays` with caching + justification toggle; added overlay aggregation tests and linkset overlay cache. Set EXCITITOR-GRAPH-21-002 and EXCITITOR-GRAPH-21-005 to DONE. | Implementer |
| 2025-11-23 | Ran `dotnet test ...StellaOps.Excititor.WebService.Tests --filter GraphOverlayFactoryTests` (TRX: `src/Excititor/__Tests/StellaOps.Excititor.WebService.Tests/TestResults/_DESKTOP-7GHGC2M_2025-11-23_23_18_38.trx`); overlay factory unit test PASS. | Implementer |
| 2025-11-25 | Delivered VEX status summaries and tooltip observation batches (`/v1/graph/status`, `/v1/graph/observations`), updated graph options/docs, and added factory unit tests; set EXCITITOR-GRAPH-24-101/24-102 to DONE. | Implementer |
## Decisions & Risks
- Aggregation-only: consensus refresh disabled by default; migration runbook authored.
- Tenant safety: Authority clients must be tenant-scoped.
- Graph overlays depend on Cartographer contract; currently blocked.
- Environment risk: “No space left on device” prevents normal command execution; repo integrity relies on apply_patch. Clean space before further code changes.
- Graph summaries/tooltips reuse Cartographer overlay contract; keep TTL/limit knobs aligned with overlay cache to avoid divergence.
- Environment risk: “No space left on device” previously blocked commands; continue to monitor runner space before large test runs.
| 1 | EXCITITOR-LNM-21-001 | DONE (2025-11-17) | Collections + indexes created via migration `20251117-observations-linksets`. | Excititor Storage Guild | Stand up collections with tenant guards; retire merge-era data without mutating raw content. |
| 2 | EXCITITOR-LNM-21-002 | DONE (2025-11-17) | Disagreement fields added to linkset domain + Mongo schema/indexes. | Excititor Core Guild | Capture disagreement metadata (status/justification deltas) in linksets with confidence scores; no winner selection. |
| CONCELIER-CONSOLE-23-002 | TODO | | SPRINT_112_concelier_i | Concelier WebService Guild | | Deterministic “new/modified/conflicting” sets referencing linkset IDs and field paths rather than computed verdicts; depends on 23-001. | — | ATLN0102 |
| CONCELIER-CONSOLE-23-003 | TODO | | SPRINT_112_concelier_i | Concelier WebService Guild | | CVE/GHSA/PURL lookups return observation excerpts, provenance anchors, and cache hints so tenants can preview evidence safely; reuse structured field taxonomy from Workstream A. | — | ATLN0102 |
| CONCELIER-CORE-AOC-19-013 | TODO | | SPRINT_112_concelier_i | Concelier Core Guild | src/Concelier/__Libraries/StellaOps.Concelier.Core | Expand smoke/e2e suites so Authority tokens + tenant headers are mandatory for ingest/read paths (including the new provenance endpoint). Must assert no merge-side effects and that provenance anchors always round-trip. | Must reference AOC guardrails from docs | AGCN0101 |
@@ -464,14 +464,14 @@
| CONCELIER-WEB-OBS-54-001 | TODO | | SPRINT_117_concelier_vi | Concelier WebService Guild | src/Concelier/StellaOps.Concelier.WebService | Provide `/attestations/advisories/*` endpoints surfacing DSSE status, verification summary, and provenance chain so CLI/Console can audit trust without hitting databases. Depends on CONCELIER-WEB-OBS-53-001. | Depends on Link-Not-Merge schema (005_ATLN0101) | CNOB0102 |
| CONCELIER-WEB-OBS-55-001 | TODO | | SPRINT_117_concelier_vi | Concelier WebService Guild · DevOps Guild | src/Concelier/StellaOps.Concelier.WebService | Implement incident-mode APIs that coordinate ingest, locker, and orchestrator, capturing activation events + cooldown semantics but leaving evidence untouched. Depends on CONCELIER-WEB-OBS-54-001. | Needs #4 to finalize labels | CNOB0102 |
| DOCS-DETER-70-002 | TODO | | SPRINT_304_docs_tasks_md_iv | Docs Guild · Scanner Guild | docs/modules/scanner/determinism.md | Document the scanner determinism score process (`determinism.json` schema, CI harness, replay instructions) under `/docs/modules/scanner/determinism-score.md` and add a release-notes template entry. Dependencies: SCAN-DETER-186-010, DEVOPS-SCAN-90-004. | Need deterministic suite notes from 137_SCDT0101 | DOSC0101 |
| EXCITITOR-CONN-UBUNTU-01-003 | TODO | | SPRINT_120_excititor_ii | Excititor Guild (Ubuntu connector) | src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Ubuntu.CSAF | DONE (2025-11-09) – Emit Ubuntu signing metadata (GPG fingerprints, issuer trust tier) inside raw provenance artifacts so downstream Policy/VEX Lens consumers can weigh issuers. Connector must remain aggregation-only with no inline weighting. | EXCITITOR-CONN-UBUNTU-01-002 | EXCN0101 |
| EXCITITOR-CONSOLE-23-001 | TODO | | SPRINT_120_excititor_ii | Excititor Guild · Docs Guild | src/Excititor/StellaOps.Excititor.WebService | Expose `/console/vex` endpoints returning grouped VEX statements per advisory/component with status chips, justification metadata, precedence trace pointers, and tenant-scoped filters for Console explorer. Dependencies: EXCITITOR-LNM-21-201, EXCITITOR-LNM-21-202. | DOCN0101 | EXCO0101 |
| EXCITITOR-CONSOLE-23-002 | TODO | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Provide aggregated counts for VEX overrides (new, not_affected, revoked) powering Console dashboard + live status ticker; emit metrics for policy explain integration. Dependencies: EXCITITOR-CONSOLE-23-001, EXCITITOR-LNM-21-203. | EXCITITOR-CONSOLE-23-001 | EXCO0101 |
| EXCITITOR-CONSOLE-23-003 | TODO | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Deliver rapid lookup endpoints of VEX by advisory/component for Console global search; ensure response includes provenance and precedence context; include caching and RBAC. Dependencies: EXCITITOR-CONSOLE-23-001. | EXCITITOR-CONSOLE-23-001 | EXCO0101 |
| EXCITITOR-CONSOLE-23-001 | DONE (2025-11-23) | | SPRINT_120_excititor_ii | Excititor Guild · Docs Guild | src/Excititor/StellaOps.Excititor.WebService | Expose `/console/vex` endpoints returning grouped VEX statements per advisory/component with status chips, justification metadata, precedence trace pointers, and tenant-scoped filters for Console explorer. Dependencies: EXCITITOR-LNM-21-201, EXCITITOR-LNM-21-202. | DOCN0101 | EXCO0101 |
| EXCITITOR-CONSOLE-23-002 | DONE (2025-11-23) | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Provide aggregated counts for VEX overrides (new, not_affected, revoked) powering Console dashboard + live status ticker; emit metrics for policy explain integration. Dependencies: EXCITITOR-CONSOLE-23-001, EXCITITOR-LNM-21-203. | EXCITITOR-CONSOLE-23-001 | EXCO0101 |
| EXCITITOR-CONSOLE-23-003 | DONE (2025-11-23) | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Deliver rapid lookup endpoints of VEX by advisory/component for Console global search; ensure response includes provenance and precedence context; include caching and RBAC. Dependencies: EXCITITOR-CONSOLE-23-001. | EXCITITOR-CONSOLE-23-001 | EXCO0101 |
| EXCITITOR-CORE-AOC-19-002 | TODO | | SPRINT_120_excititor_ii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Implement deterministic extraction of advisory IDs, component PURLs, and references into `linkset`, capturing reconciled-from metadata for traceability. | Link-Not-Merge schema | EXCA0101 |
| EXCITITOR-CORE-AOC-19-003 | TODO | | SPRINT_120_excititor_ii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Enforce `(vendor, upstreamId, contentHash, tenant)` uniqueness, generate supersedes chains, and ensure append-only versioning of raw VEX documents. Dependencies: EXCITITOR-CORE-AOC-19-002. | EXCITITOR-CORE-AOC-19-002 | EXCA0101 |
| EXCITITOR-CORE-AOC-19-004 | TODO | | SPRINT_120_excititor_ii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Excise consensus/merge/severity logic from Excititor ingestion paths, updating exports/tests to rely on Policy Engine materializations instead. Dependencies: EXCITITOR-CORE-AOC-19-003. | EXCITITOR-CORE-AOC-19-003 | EXCA0101 |
@@ -957,16 +957,16 @@
| EXCITITOR-GRAPH-21-001 | TODO | 2025-10-27 | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Provide batched VEX/advisory reference fetches keyed by graph node PURLs so UI inspector can display raw documents and justification metadata. | Link-Not-Merge schema | EXGR0101 |
| EXCITITOR-GRAPH-21-002 | TODO | 2025-10-27 | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Ensure overlay metadata includes VEX justification summaries and document versions for Cartographer overlays; update fixtures/tests. Dependencies: EXCITITOR-GRAPH-21-001. | EXCITITOR-GRAPH-21-001 | EXGR0101 |
| EXCITITOR-GRAPH-21-005 | TODO | 2025-10-27 | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo | Add indexes/materialized views for VEX lookups by PURL/policy to support Cartographer inspector performance; document migrations. Dependencies: EXCITITOR-GRAPH-21-002. | EXCITITOR-GRAPH-21-002 | EXGR0101 |
| EXCITITOR-GRAPH-24-101 | TODO | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Provide endpoints delivering VEX status summaries per component/asset for Vuln Explorer integration. Dependencies: EXCITITOR-GRAPH-21-005. | EXCITITOR-GRAPH-21-002 | EXGR0101 |
| EXCITITOR-LNM-21-001 | TODO | | SPRINT_121_excititor_iii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo | Stand up `vex_observations` and `vex_linksets` collections with shard keys, tenant guards, and migrations that retire any residual merge-era data without mutating raw content. | Link-Not-Merge schema | EXLN0101 |
| EXCITITOR-LNM-21-002 | TODO | | SPRINT_121_excititor_iii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Capture disagreement metadata (status + justification deltas) directly inside linksets with confidence scores so downstream consumers can highlight conflicts without Excititor choosing winners. Depends on EXCITITOR-LNM-21-001. | EXCITITOR-LNM-21-001 | EXLN0101 |
| EXCITITOR-LNM-21-003 | TODO | | SPRINT_121_excititor_iii | Excititor Core + Platform Events Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Emit `vex.linkset.updated` events and describe payload shape (observation ids, confidence, conflict summary) so Policy/Lens/UI can subscribe while Excititor stays aggregation-only. Depends on EXCITITOR-LNM-21-002. | EXCITITOR-LNM-21-002 | EXLN0101 |
| EXCITITOR-LNM-21-201 | TODO | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Ship `/vex/observations` read endpoints with filters for advisory/product/issuer, strict RBAC, and deterministic pagination (no derived verdict fields). Depends on EXCITITOR-LNM-21-003. | EXCITITOR-LNM-21-001 | EXLN0101 |
| EXCITITOR-LNM-21-202 | TODO | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Provide `/vex/linksets` + export endpoints that surface alias mappings, conflict markers, and provenance proofs exactly as stored; errors must map to `ERR_AGG_*`. Depends on EXCITITOR-LNM-21-201. | EXCITITOR-LNM-21-201 | EXLN0101 |
| EXCITITOR-LNM-21-203 | TODO | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Update OpenAPI, SDK smoke tests, and documentation to cover the new observation/linkset endpoints with realistic examples Advisory AI/Lens teams can rely on. Depends on EXCITITOR-LNM-21-202. | EXCITITOR-LNM-21-202 | EXLN0101 |
| EXCITITOR-OBS-51-001 | TODO | | SPRINT_121_excititor_iii | Excititor Core Guild · DevOps Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Publish ingest latency, scope resolution success, conflict rate, and signature verification metrics plus SLO burn alerts so we can prove Excititor meets the AOC “evidence freshness” mission. | Wait for 046_TLTY0101 span schema | EXOB0101 |
| EXCITITOR-OBS-52-001 | TODO | | SPRINT_122_excititor_iv | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Emit `timeline_event` entries for every ingest/linkset change with trace IDs, justification summaries, and evidence hashes so downstream systems can replay the raw facts chronologically. Depends on EXCITITOR-OBS-51-001. | Needs #1 merged for correlation IDs | EXOB0101 |
| EXCITITOR-LNM-21-201 | DONE (2025-11-25) | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Ship `/vex/observations` read endpoints with filters for advisory/product/issuer, strict RBAC, and deterministic pagination (no derived verdict fields). Depends on EXCITITOR-LNM-21-003. | EXCITITOR-LNM-21-001 | EXLN0101 |
| EXCITITOR-LNM-21-202 | DONE (2025-11-25) | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Provide `/vex/linksets` + export endpoints that surface alias mappings, conflict markers, and provenance proofs exactly as stored; errors must map to `ERR_AGG_*`. Depends on EXCITITOR-LNM-21-201. | EXCITITOR-LNM-21-201 | EXLN0101 |
| EXCITITOR-LNM-21-203 | DONE (2025-11-23) | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Update OpenAPI, SDK smoke tests, and documentation to cover the new observation/linkset endpoints with realistic examples Advisory AI/Lens teams can rely on. Depends on EXCITITOR-LNM-21-202. | EXCITITOR-LNM-21-202 | EXLN0101 |
| EXCITITOR-OBS-51-001 | DONE (2025-11-23) | | SPRINT_121_excititor_iii | Excititor Core Guild · DevOps Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Publish ingest latency, scope resolution success, conflict rate, and signature verification metrics plus SLO burn alerts so we can prove Excititor meets the AOC “evidence freshness” mission. | Wait for 046_TLTY0101 span schema | EXOB0101 |
| EXCITITOR-OBS-52-001 | DONE (2025-11-24) | | SPRINT_0119_0001_0006_excititor_vi | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Emit `timeline_event` entries for every ingest/linkset change with trace IDs, justification summaries, and evidence hashes so downstream systems can replay the raw facts chronologically. Depends on EXCITITOR-OBS-51-001. | Needs #1 merged for correlation IDs | EXOB0101 |
| EXCITITOR-OBS-53-001 | TODO | | SPRINT_122_excititor_iv | Excititor Core Guild · Evidence Locker Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Build locker payloads (raw doc, normalization diff, provenance) and Merkle manifests so sealed-mode sites can audit evidence without Excititor reinterpreting it. Depends on EXCITITOR-OBS-52-001. | Blocked on Evidence Locker DSSE hooks (002_ATEL0101) | EXOB0101 |
| EXCITITOR-OBS-54-001 | TODO | | SPRINT_122_excititor_iv | Excititor Core Guild · Provenance Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Attach DSSE attestations to every evidence batch, verify chains via Provenance tooling, and surface attestation IDs on timeline events. Depends on EXCITITOR-OBS-53-001. | Requires provenance schema from 005_ATLN0101 | EXOB0101 |
| EXCITITOR-OPS-0001 | TODO | | SPRINT_333_docs_modules_excititor | Ops Guild · Docs Guild | docs/modules/excititor | Sync outcomes back to ../.. | DOEX0101 runbooks | DOEX0102 |
@@ -975,12 +975,12 @@
| EXCITITOR-POLICY-20-001 | TODO | | SPRINT_122_excititor_iv | WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Provide VEX lookup APIs (PURL/advisory batching, scope filters, tenant enforcement) that Policy Engine uses to join evidence without Excititor performing any verdict logic. Depends on EXCITITOR-AOC-20-004. | DOLN0101 | EXWS0101 |
| EXCITITOR-POLICY-20-002 | TODO | | SPRINT_122_excititor_iv | Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Enhance linksets with scope resolution + version range metadata so Policy/Reachability can reason about applicability while Excititor continues to report only raw context. Depends on EXCITITOR-POLICY-20-001. | | EXWK0101 |
| EXCITITOR-RISK-66-001 | TODO | | SPRINT_122_excititor_iv | Excititor Core Guild · Risk Engine Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Core`) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Publish risk-engine ready feeds (status, justification, provenance) with zero derived severity so gating services can reference Excititor as a source of truth. Depends on EXCITITOR-POLICY-20-002. | CONCELIER-GRAPH-21-001/002 | EXRS0101 |
| EXCITITOR-STORE-AOC-19-001 | TODO | | SPRINT_123_excititor_v | Storage Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo`) | src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo | Ship Mongo JSON Schema + validator tooling (including Offline Kit instructions) so operators can prove Excititor stores only immutable evidence. | Link-Not-Merge schema | EXSM0101 |
| EXCITITOR-STORE-AOC-19-002 | TODO | | SPRINT_123_excititor_v | Storage + DevOps Guilds (`src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo`) | src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo | Create unique indexes, run migrations/backfills, and document rollback steps for the new schema validator. Depends on EXCITITOR-STORE-AOC-19-001. | STORE-AOC-19-001 | EXSM0101 |
| EXCITITOR-VEXLENS-30-001 | TODO | | SPRINT_123_excititor_v | Excititor WebService Guild · VEX Lens Guild | src/Excititor/StellaOps.Excititor.WebService | Ensure every observation exported to VEX Lens carries issuer hints, signature blobs, product tree snippets, and staleness metadata so the lens can compute consensus without calling back into Excititor. | — | PLVL0103 |
| EXCITITOR-VULN-29-001 | TODO | | SPRINT_123_excititor_v | Excititor WebService Guild (`src/Excititor/StellaOps.Excititor.WebService`) | src/Excititor/StellaOps.Excititor.WebService | Canonicalize advisory/product keys (map to `advisory_key`, capture scope metadata) while preserving original identifiers in `links[]`; run backfill + regression tests. | EXWS0101 | EXVN0101 |
| EXCITITOR-VULN-29-002 | TODO | | SPRINT_123_excititor_v | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Provide `/vuln/evidence/vex/{advisory_key}` returning tenant-scoped raw statements, provenance, and attestation references for Vuln Explorer evidence tabs. Depends on EXCITITOR-VULN-29-001. | EXCITITOR-VULN-29-001 | EXVN0101 |
| EXCITITOR-VULN-29-004 | TODO | | SPRINT_123_excititor_v | Excititor WebService + Observability Guilds | src/Excititor/StellaOps.Excititor.WebService | Add metrics/logs for normalization errors, suppression scopes, withdrawn statements, and feed them to Vuln Explorer + Advisory AI dashboards. Depends on EXCITITOR-VULN-29-002. | EXCITITOR-VULN-29-001 | EXVN0101 |
| EXCITITOR-STORE-AOC-19-002 | DONE (2025-11-25) | | SPRINT_0119_0001_0005_excititor_v | Storage + DevOps Guilds (`src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo`) | src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo | Create unique indexes, run migrations/backfills, and document rollback steps for the new schema validator. Depends on EXCITITOR-STORE-AOC-19-001. | EXCITITOR-STORE-AOC-19-001 | EXSM0101 |
| EXCITITOR-VEXLENS-30-001 | BLOCKED (2025-11-25) | Await VEX Lens field list / examples | SPRINT_0119_0001_0005_excititor_v | Excititor WebService Guild · VEX Lens Guild | src/Excititor/StellaOps.Excititor.WebService | Ensure every observation exported to VEX Lens carries issuer hints, signature blobs, product tree snippets, and staleness metadata so the lens can compute consensus without calling back into Excititor. | — | PLVL0103 |
| EXCITITOR-VULN-29-001 | BLOCKED (2025-11-23) | Waiting on advisory_key canonicalization spec | SPRINT_0119_0001_0005_excititor_v | Excititor WebService Guild (`src/Excititor/StellaOps.Excititor.WebService`) | src/Excititor/StellaOps.Excititor.WebService | Canonicalize advisory/product keys (map to `advisory_key`, capture scope metadata) while preserving original identifiers in `links[]`; run backfill + regression tests. | EXWS0101 | EXVN0101 |
| EXCITITOR-VULN-29-002 | BLOCKED (2025-11-23) | Blocked on EXCITITOR-VULN-29-001 | SPRINT_0119_0001_0005_excititor_v | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Provide `/vuln/evidence/vex/{advisory_key}` returning tenant-scoped raw statements, provenance, and attestation references for Vuln Explorer evidence tabs. Depends on EXCITITOR-VULN-29-001. | EXCITITOR-VULN-29-001 | EXVN0101 |
| EXCITITOR-VULN-29-004 | BLOCKED (2025-11-23) | Blocked on EXCITITOR-VULN-29-002 | SPRINT_0119_0001_0005_excititor_v | Excititor WebService + Observability Guilds | src/Excititor/StellaOps.Excititor.WebService | Add metrics/logs for normalization errors, suppression scopes, withdrawn statements, and feed them to Vuln Explorer + Advisory AI dashboards. Depends on EXCITITOR-VULN-29-002. | EXCITITOR-VULN-29-001 | EXVN0101 |
| EXPORT-OBS-52-001 | TODO | | SPRINT_163_exportcenter_ii | Exporter Service Guild | src/ExportCenter/StellaOps.ExportCenter | Publish timeline events for export lifecycle (`export.requested`, `export.built`, `export.distributed`, `export.failed`) embedding manifest hashes and evidence refs. Provide dedupe + retry logic. Dependencies: EXPORT-OBS-51-001. | Requires shared middleware from task #1 | ECOB0101 |
| EXPORT-OBS-53-001 | TODO | | SPRINT_163_exportcenter_ii | Exporter Service Guild · Evidence Locker Guild | src/ExportCenter/StellaOps.ExportCenter | Push export manifests + distribution transcripts to evidence locker bundles, ensuring Merkle root alignment and DSSE pre-sign data available. Dependencies: EXPORT-OBS-52-001. | Blocked on Evidence Locker DSSE API (002_ATEL0101) | ECOB0101 |
| EXPORT-OBS-54-001 | TODO | | SPRINT_163_exportcenter_ii | Exporter Service Guild · Provenance Guild | src/ExportCenter/StellaOps.ExportCenter | Produce DSSE attestations for each export artifact and distribution target, expose verification API `/exports/{id}/attestation`, and integrate with CLI verify path. Dependencies: EXPORT-OBS-53-001. | PROGRAM-STAFF-1001; EXPORT-MIRROR-ORCH-1501 | ECOB0101 |
| CONCELIER-CONSOLE-23-002 | TODO | | SPRINT_112_concelier_i | Concelier WebService Guild | | Deterministic “new/modified/conflicting” sets referencing linkset IDs and field paths rather than computed verdicts; depends on 23-001. | — | ATLN0102 |
| CONCELIER-CONSOLE-23-003 | TODO | | SPRINT_112_concelier_i | Concelier WebService Guild | | CVE/GHSA/PURL lookups return observation excerpts, provenance anchors, and cache hints so tenants can preview evidence safely; reuse structured field taxonomy from Workstream A. | — | ATLN0102 |
| CONCELIER-CORE-AOC-19-013 | TODO | | SPRINT_112_concelier_i | Concelier Core Guild | src/Concelier/__Libraries/StellaOps.Concelier.Core | Expand smoke/e2e suites so Authority tokens + tenant headers are mandatory for ingest/read paths (including the new provenance endpoint). Must assert no merge-side effects and that provenance anchors always round-trip. | Must reference AOC guardrails from docs | AGCN0101 |
@@ -2673,14 +2673,14 @@
| CONCELIER-WEB-OBS-54-001 | TODO | | SPRINT_117_concelier_vi | Concelier WebService Guild | src/Concelier/StellaOps.Concelier.WebService | Provide `/attestations/advisories/*` endpoints surfacing DSSE status, verification summary, and provenance chain so CLI/Console can audit trust without hitting databases. Depends on CONCELIER-WEB-OBS-53-001. | Depends on Link-Not-Merge schema (005_ATLN0101) | CNOB0102 |
| CONCELIER-WEB-OBS-55-001 | TODO | | SPRINT_117_concelier_vi | Concelier WebService Guild · DevOps Guild | src/Concelier/StellaOps.Concelier.WebService | Implement incident-mode APIs that coordinate ingest, locker, and orchestrator, capturing activation events + cooldown semantics but leaving evidence untouched. Depends on CONCELIER-WEB-OBS-54-001. | Needs #4 to finalize labels | CNOB0102 |
| DOCS-DETER-70-002 | TODO | | SPRINT_304_docs_tasks_md_iv | Docs Guild · Scanner Guild | docs/modules/scanner/determinism.md | Document the scanner determinism score process (`determinism.json` schema, CI harness, replay instructions) under `/docs/modules/scanner/determinism-score.md` and add a release-notes template entry. Dependencies: SCAN-DETER-186-010, DEVOPS-SCAN-90-004. | Need deterministic suite notes from 137_SCDT0101 | DOSC0101 |
| EXCITITOR-CONN-UBUNTU-01-003 | TODO | | SPRINT_120_excititor_ii | Excititor Guild (Ubuntu connector) | src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Ubuntu.CSAF | DONE (2025-11-09) – Emit Ubuntu signing metadata (GPG fingerprints, issuer trust tier) inside raw provenance artifacts so downstream Policy/VEX Lens consumers can weigh issuers. Connector must remain aggregation-only with no inline weighting. | EXCITITOR-CONN-UBUNTU-01-002 | EXCN0101 |
| EXCITITOR-CONSOLE-23-001 | TODO | | SPRINT_120_excititor_ii | Excititor Guild · Docs Guild | src/Excititor/StellaOps.Excititor.WebService | Expose `/console/vex` endpoints returning grouped VEX statements per advisory/component with status chips, justification metadata, precedence trace pointers, and tenant-scoped filters for Console explorer. Dependencies: EXCITITOR-LNM-21-201, EXCITITOR-LNM-21-202. | DOCN0101 | EXCO0101 |
| EXCITITOR-CONSOLE-23-002 | TODO | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Provide aggregated counts for VEX overrides (new, not_affected, revoked) powering Console dashboard + live status ticker; emit metrics for policy explain integration. Dependencies: EXCITITOR-CONSOLE-23-001, EXCITITOR-LNM-21-203. | EXCITITOR-CONSOLE-23-001 | EXCO0101 |
| EXCITITOR-CONSOLE-23-003 | TODO | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Deliver rapid lookup endpoints of VEX by advisory/component for Console global search; ensure response includes provenance and precedence context; include caching and RBAC. Dependencies: EXCITITOR-CONSOLE-23-001. | EXCITITOR-CONSOLE-23-001 | EXCO0101 |
| EXCITITOR-CONSOLE-23-001 | DONE (2025-11-23) | | SPRINT_120_excititor_ii | Excititor Guild · Docs Guild | src/Excititor/StellaOps.Excititor.WebService | Expose `/console/vex` endpoints returning grouped VEX statements per advisory/component with status chips, justification metadata, precedence trace pointers, and tenant-scoped filters for Console explorer. Dependencies: EXCITITOR-LNM-21-201, EXCITITOR-LNM-21-202. | DOCN0101 | EXCO0101 |
| EXCITITOR-CONSOLE-23-002 | DONE (2025-11-23) | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Provide aggregated counts for VEX overrides (new, not_affected, revoked) powering Console dashboard + live status ticker; emit metrics for policy explain integration. Dependencies: EXCITITOR-CONSOLE-23-001, EXCITITOR-LNM-21-203. | EXCITITOR-CONSOLE-23-001 | EXCO0101 |
| EXCITITOR-CONSOLE-23-003 | DONE (2025-11-23) | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Deliver rapid lookup endpoints of VEX by advisory/component for Console global search; ensure response includes provenance and precedence context; include caching and RBAC. Dependencies: EXCITITOR-CONSOLE-23-001. | EXCITITOR-CONSOLE-23-001 | EXCO0101 |
| EXCITITOR-CORE-AOC-19-002 | TODO | | SPRINT_120_excititor_ii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Implement deterministic extraction of advisory IDs, component PURLs, and references into `linkset`, capturing reconciled-from metadata for traceability. | Link-Not-Merge schema | EXCA0101 |
| EXCITITOR-CORE-AOC-19-003 | TODO | | SPRINT_120_excititor_ii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Enforce `(vendor, upstreamId, contentHash, tenant)` uniqueness, generate supersedes chains, and ensure append-only versioning of raw VEX documents. Dependencies: EXCITITOR-CORE-AOC-19-002. | EXCITITOR-CORE-AOC-19-002 | EXCA0101 |
| EXCITITOR-CORE-AOC-19-004 | TODO | | SPRINT_120_excititor_ii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Excise consensus/merge/severity logic from Excititor ingestion paths, updating exports/tests to rely on Policy Engine materializations instead. Dependencies: EXCITITOR-CORE-AOC-19-003. | EXCITITOR-CORE-AOC-19-003 | EXCA0101 |
@@ -3173,13 +3174,13 @@
| EXCITITOR-GRAPH-21-001 | TODO | 2025-10-27 | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Provide batched VEX/advisory reference fetches keyed by graph node PURLs so UI inspector can display raw documents and justification metadata. | Link-Not-Merge schema | EXGR0101 |
| EXCITITOR-GRAPH-21-002 | TODO | 2025-10-27 | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Ensure overlay metadata includes VEX justification summaries and document versions for Cartographer overlays; update fixtures/tests. Dependencies: EXCITITOR-GRAPH-21-001. | EXCITITOR-GRAPH-21-001 | EXGR0101 |
| EXCITITOR-GRAPH-21-005 | TODO | 2025-10-27 | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo | Add indexes/materialized views for VEX lookups by PURL/policy to support Cartographer inspector performance; document migrations. Dependencies: EXCITITOR-GRAPH-21-002. | EXCITITOR-GRAPH-21-002 | EXGR0101 |
| EXCITITOR-GRAPH-24-101 | TODO | | SPRINT_120_excititor_ii | Excititor Guild | src/Excititor/StellaOps.Excititor.WebService | Provide endpoints delivering VEX status summaries per component/asset for Vuln Explorer integration. Dependencies: EXCITITOR-GRAPH-21-005. | EXCITITOR-GRAPH-21-002 | EXGR0101 |
| EXCITITOR-LNM-21-001 | TODO | | SPRINT_121_excititor_iii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo | Stand up `vex_observations` and `vex_linksets` collections with shard keys, tenant guards, and migrations that retire any residual merge-era data without mutating raw content. | Link-Not-Merge schema | EXLN0101 |
| EXCITITOR-LNM-21-002 | TODO | | SPRINT_121_excititor_iii | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Capture disagreement metadata (status + justification deltas) directly inside linksets with confidence scores so downstream consumers can highlight conflicts without Excititor choosing winners. Depends on EXCITITOR-LNM-21-001. | EXCITITOR-LNM-21-001 | EXLN0101 |
| EXCITITOR-LNM-21-003 | TODO | | SPRINT_121_excititor_iii | Excititor Core + Platform Events Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Emit `vex.linkset.updated` events and describe payload shape (observation ids, confidence, conflict summary) so Policy/Lens/UI can subscribe while Excititor stays aggregation-only. Depends on EXCITITOR-LNM-21-002. | EXCITITOR-LNM-21-002 | EXLN0101 |
| EXCITITOR-LNM-21-201 | TODO | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Ship `/vex/observations` read endpoints with filters for advisory/product/issuer, strict RBAC, and deterministic pagination (no derived verdict fields). Depends on EXCITITOR-LNM-21-003. | EXCITITOR-LNM-21-001 | EXLN0101 |
| EXCITITOR-LNM-21-202 | TODO | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Provide `/vex/linksets` + export endpoints that surface alias mappings, conflict markers, and provenance proofs exactly as stored; errors must map to `ERR_AGG_*`. Depends on EXCITITOR-LNM-21-201. | EXCITITOR-LNM-21-201 | EXLN0101 |
| EXCITITOR-LNM-21-201 | DONE (2025-11-25) | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Ship `/vex/observations` read endpoints with filters for advisory/product/issuer, strict RBAC, and deterministic pagination (no derived verdict fields). Depends on EXCITITOR-LNM-21-003. | EXCITITOR-LNM-21-001 | EXLN0101 |
| EXCITITOR-LNM-21-202 | DONE (2025-11-25) | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Provide `/vex/linksets` + export endpoints that surface alias mappings, conflict markers, and provenance proofs exactly as stored; errors must map to `ERR_AGG_*`. Depends on EXCITITOR-LNM-21-201. | EXCITITOR-LNM-21-201 | EXLN0101 |
| EXCITITOR-LNM-21-203 | TODO | | SPRINT_121_excititor_iii | Excititor WebService Guild | src/Excititor/StellaOps.Excititor.WebService | Update OpenAPI, SDK smoke tests, and documentation to cover the new observation/linkset endpoints with realistic examples Advisory AI/Lens teams can rely on. Depends on EXCITITOR-LNM-21-202. | EXCITITOR-LNM-21-202 | EXLN0101 |
| EXCITITOR-OBS-51-001 | TODO | | SPRINT_121_excititor_iii | Excititor Core Guild · DevOps Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Publish ingest latency, scope resolution success, conflict rate, and signature verification metrics plus SLO burn alerts so we can prove Excititor meets the AOC “evidence freshness” mission. | Wait for 046_TLTY0101 span schema | EXOB0101 |
| EXCITITOR-OBS-52-001 | TODO | | SPRINT_122_excititor_iv | Excititor Core Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Emit `timeline_event` entries for every ingest/linkset change with trace IDs, justification summaries, and evidence hashes so downstream systems can replay the raw facts chronologically. Depends on EXCITITOR-OBS-51-001. | Needs #1 merged for correlation IDs | EXOB0101 |
@@ -3234,7 +3235,7 @@
| EXPORT-OAS-63 | TODO | | SPRINT_160_export_evidence | Exporter Service Guild · API Governance Guild | | Needs API governance sign-off (049_APIG0101) | Needs API governance sign-off (049_APIG0101) | AGEX0101 |
| EXPORT-OAS-63-001 | TODO | | SPRINT_163_exportcenter_ii | Exporter Service Guild · SDK Guild | src/ExportCenter/StellaOps.ExportCenter | Implement deprecation headers and notifications for legacy export endpoints. Dependencies: EXPORT-OAS-62-001. | Requires #3 schema | AGEX0101 |
| EXPORT-OBS-50-001 | TODO | | SPRINT_163_exportcenter_ii | Exporter Service Guild · Observability Guild | src/ExportCenter/StellaOps.ExportCenter | Adopt telemetry core in exporter service + workers, ensuring spans/logs capture profile id, tenant, artifact counts, distribution type, and trace IDs. | Wait for telemetry schema drop from 046_TLTY0101 | ECOB0101 |
| EXPORT-OBS-52-001 | TODO | | SPRINT_163_exportcenter_ii | Exporter Service Guild | src/ExportCenter/StellaOps.ExportCenter | Publish timeline events for export lifecycle (`export.requested`, `export.built`, `export.distributed`, `export.failed`) embedding manifest hashes and evidence refs. Provide dedupe + retry logic. Dependencies: EXPORT-OBS-51-001. | Requires shared middleware from task #1 | ECOB0101 |
| EXPORT-OBS-53-001 | TODO | | SPRINT_163_exportcenter_ii | Exporter Service Guild · Evidence Locker Guild | src/ExportCenter/StellaOps.ExportCenter | Push export manifests + distribution transcripts to evidence locker bundles, ensuring Merkle root alignment and DSSE pre-sign data available. Dependencies: EXPORT-OBS-52-001. | Blocked on Evidence Locker DSSE API (002_ATEL0101) | ECOB0101 |
| EXPORT-OBS-54-001 | TODO | | SPRINT_163_exportcenter_ii | Exporter Service Guild · Provenance Guild | src/ExportCenter/StellaOps.ExportCenter | Produce DSSE attestations for each export artifact and distribution target, expose verification API `/exports/{id}/attestation`, and integrate with CLI verify path. Dependencies: EXPORT-OBS-53-001. | PROGRAM-STAFF-1001; EXPORT-MIRROR-ORCH-1501 | ECOB0101 |
Mount the bundle directories read-only; keep hashes alongside the payloads for audit.
## Verification flow (offline)
1. Client submits a DSSE envelope to `/api/v1/attestations/verify` with tenant header.
2. Service loads keys from the offline trust bundle; issuer lookup is strictly local.
3. If transparency data is present, the server verifies inclusion against the mirrored checkpoint; otherwise it records `transparency=skipped` in the rationale.
4. Result is returned with deterministic fields: `subject`, `statementDigest`, `verified=true|false`, `transparency=passed|skipped|failed`, `rationale[]`.
## Determinism safeguards
- All hashes are lowercase hex; timestamps are UTC ISO-8601.
- Sorting: multiple statements are ordered by `subject` then `statementDigest`.
- No network retries or clock drift compensation; rely on bundle timestamps.
## Operations checklist
- [ ] Refresh trust bundle hashes before each deploy; compare against signed manifest.
- [ ] Rotate keys by replacing the bundle atomically; restart workers to pick up changes.
- [ ] Record verification results in the delivery ledger for replay/audit.
- Response mirrors overlay summaries but omits justification payloads; includes `sources[]`, `lastEvidenceHash`, `cached`, `cacheAgeMs`. Intended for Vuln Explorer status colouring.
-`$jsonSchema` validator applied to `vex_raw` (migration `20251125-vex-raw-json-schema`) with `validationAction=warn`, `validationLevel=moderate` to surface contract violations without impacting ingestion.
- Schema lives at `docs/modules/excititor/schemas/vex_raw.schema.json` (mirrors Mongo validator fields: digest/id, providerId, format, sourceUri, retrievedAt, optional content/GridFS object id, metadata strings).
- Migration is auto-registered in DI; hosted migration runner applies it on service start. New collections created with the validator if missing.
## How to run (online/offline)
1) Ensure Excititor WebService/Worker starts with Mongo credentials that allow `collMod`.
2) Validator applies automatically via migration runner. To force manually:
3) Offline kit: bundle `docs/modules/excititor/schemas/vex_raw.schema.json` with release artifacts; ops can apply via `mongosh` or `mongo` offline against snapshots.
- Validator keeps `additionalProperties=true` to avoid blocking future fields; required set is minimal to guarantee provenance + content hash presence.
- Action is `warn` to avoid breaking existing feeds; flip to `error` once downstream datasets are clean.
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
Last updated: 2025-11-25 (Docs Tasks Md.V · DOCS-NOTIFY-40-001)
All endpoints require `Authorization: Bearer <token>` and `X-Stella-Tenant` header. Responses use the common error envelope (`docs/api/overview.md`). Paths are rooted at `/api/v1/notify`.
- **Determinism**: channel ids are UUIDv5 seeded by `(tenant, type, endpoint)` when created via manifests; server generates new IDs for ad-hoc API calls.
- **Validation**: endpoints must be on the allowlist; secretRef must exist in Authority; quiet hours use 24h clock UTC.
## Connector rules
- No secrets are stored in Notify DB; only `secretRef` is persisted.
- Per-tenant allowlists control outbound hostnames/ports; defaults block public internet in air-gapped kits.
- Payload signing:
- Slack/Teams: bearer secret in URL (indirect via secretRef) plus optional HMAC header `X-Stella-Signature` for mirror validation.
- Webhook/Pager: HMAC `X-Stella-Signature` (hex) over body with nonce + timestamp; receivers must enforce 5‑minute skew.
## Offline posture
- Offline kits ship default channel manifests under `out/offline/notify/channels/*.json` with placeholder endpoints.
- Operators must replace endpoints and secretRefs before deploy; validation rejects placeholder values.
- Redact fields to `"[redacted]"` and add `redaction.reason` (`secret|pii|tenant_policy`).
- Hash low-cardinality identifiers when needed (`sha256` lowercase hex) and mark `hashed=true`.
- Logs must not contain full request/response bodies; store hashes plus lengths. For NDJSON exports, allow hashes + selected headers only.
## Sampling defaults
- **Traces**: 10% head sampling non-prod; 100% for `status=error|fault` and for spans tagged `audit=true`. Prod default 5% with the same error/audit boost.
- **Logs**: info logs rate-limited per component (default 100/s); warn/error never sampled. Structured JSON only.
- **Metrics**: never sampled; counters/gauges/histograms use deterministic bucket boundaries documented in component specs.
## Redaction override procedure
- Overrides are rare and must be auditable.
- To allow a field temporarily, set `telemetry.redaction.overrides=<comma list>` in service config with change-ticket id; emit `redaction.override=true` tag on affected spans/logs.
- Overrides expire automatically after `telemetry.redaction.override_ttl` (default 24h); services refuse to start with expired overrides.
- All overrides are logged to `telemetry.redaction.audit` channel with actor, ticket, fields, TTL.
## Determinism & offline posture
- No external enrichers; all enrichment data must be preloaded bundles (e.g., service map, tenant metadata).
- Sorting for exports: by `timestamp`, then `workload`, then `operation`.
- Time always UTC; avoid locale-specific formats.
## Validation checklist
- [ ]`traceparent` propagated and present on inbound/outbound.
- Consistent distributed tracing across services (API, workers, CLI).
- Safe for offline/air-gapped deployments.
- Deterministic span data for replay/debug.
## Context propagation
- Use W3C headers: `traceparent` (required), `baggage` (optional key/value pairs).
- Preserve incoming `trace_id` for all downstream calls; create child spans per operation.
- For async work (queues, cron), copy `traceparent` and `baggage` into the message envelope; new span links to the stored context using **links**, not a new parent.
Provide a deterministic, explainable way to pick the *effective* severity for a vulnerability or VEX observation when multiple signals exist (CVSS, KEV, exploit intel, VEX status, asset criticality, policy overrides).
## Inputs
- **Base scores**: CVSS v3/v4 (base + temporal) and ecosystem-native severities (npm/yarn, PyPI, Maven). Missing scores are treated as `null`.
- **Tenant isolation**: Every API call requires `X-Stella-Tenant`; storage and caches are keyed by tenant.
- **Append-only inputs**: Evidence, advisories, and attestations are stored immutably; no in-place edits.
- **Determinism**: Sorting and pagination are stable; timestamps are UTC ISO-8601; hashes are lowercase hex.
- **No consensus**: Components enforce validation/verification only; no severity or policy decisions inside AOC services.
- **Offline-first**: All external data (feeds, keys, checkpoints) must be supplied via bundled inputs; no live fetches when sealed.
## Attestor-specific invariants
- **Trust roots**: Verification keys are loaded exclusively from the bundled trust store; network key discovery is disabled in sealed mode.
- **DSSE only**: Inputs must be DSSE envelopes; detached signatures are rejected with a deterministic error code.
- **Transparency optional, explicit**: If a mirrored checkpoint is provided, inclusion proof is validated; otherwise results record `transparency=skipped` without failing the request.
- **Rationale trail**: Each verification emits a rationale list (e.g., `key.match`, `transparency.included`, `transparency.skipped`) so results are replayable.
- **Immutability**: Verified statements and rationale are recorded append-only in the delivery/verification ledger; retries must not overwrite prior entries.
## Guardrails for implementers
- Never permit unsigned or partially signed payloads to proceed past parsing.
- Reject any outbound HTTP/S fetch during verification when `Attestor__Offline__Enabled=true`.
- Keep secret material out of logs; log statement digests and key ids only.
- Round numeric scores/weights only at the presentation boundary; internal math stays high-precision.
## Audit checklist
- [ ] Tenant header enforced on every endpoint.
- [ ] Trust bundle hash matches the signed manifest on disk.
- [ ] Transparency verification results are captured per request.
- [ ] Ledger entries are append-only and carry rationale + trace ids.
- **Tenant isolation**: every rule/channel/template includes `tenant`; APIs enforce `X-Stella-Tenant`. Mongo collections are filtered by tenant with indexes on `(tenant, id)`.
- **Secrets**: channels reference Authority `secretRef`; secrets never stored in Notify DB. Rotate via Authority and `:refresh-secret`.
- **Outbound allowlist**: restrict hosts/ports per tenant; defaults block public internet in air-gapped kits.
- **Signing**: webhook deliveries include `X-Stella-Signature` HMAC-SHA256 over body+nonce; receivers must reject stale timestamps (>5m) and verify signature.
- **Replay protection**: delivery ledger de-dupes on `(channel, bodyHash)` for 24h; escalation tokens are single-use DSSE-signed.
- **Rate limits/throttles**: per-rule and per-channel throttles; quiet hours for non-critical traffic.
- **Templates sandboxed**: no file/network access; helpers are pure and deterministic.
- **Logging/PII**: payloads redacted based on rule labels; logs avoid full body, store hashes instead.
- **Audit**: all admin actions (create/update/delete channel or rule) logged with actor, trace id, and diff.
## Deployment checklist
- [ ] Authority scopes `notify.viewer|operator|admin` configured; service accounts least-privilege.
- SLOs owned by Orchestrator Guild; reviewed quarterly or when architecture changes.
- Changes must be reflected in runbook and alert rules; update manifests for offline/air-gap monitoring kits.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
StellaOps Bot