# Sprint 0122 · Excititor Ingestion & Evidence (Phase IV)

## Topic & Scope
- Ingestion & Evidence focus on Excititor (phase IV) with policy-facing VEX APIs and risk feeds while staying aggregation-only.
- Maintain deterministic replay (timeline, evidence, attestations) and orchestrator compliance for workers.
- **Working directory:** `src/Excititor` (Core, WebService, Worker).

## Dependencies & Concurrency
- Upstream: Policy Engine API contract (advisory_key schema, batching rules); Risk feed envelope; orchestrator worker SDK (delivered); Evidence Locker manifest format (delivered).
- Concurrency: Policy endpoints and scope/linkset enrichments are interdependent; risk feed depends on policy API outputs.
- Peers: Policy Engine, Risk Engine for contract finalization.

## Documentation Prerequisites
- `docs/modules/excititor/architecture.md`
- `docs/modules/excititor/implementation_plan.md`
- Excititor component `AGENTS.md` (Core, WebService, Worker)
- `docs/ingestion/aggregation-only-contract.md`

## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EXCITITOR-OBS-52-001 | DONE (2025-11-27) | After OBS-51 metrics baseline; schema defined. | Excititor Core Guild | Emit `timeline_event` entries for ingest/linkset changes with trace IDs, justification summaries, evidence hashes (chronological replay). |
| 2 | EXCITITOR-OBS-53-001 | DONE (2025-11-27) | Depends on 52-001; locker format aligned. | Excititor Core · Evidence Locker Guild | Build locker payloads (raw doc, normalization diff, provenance) + Merkle manifests for sealed-mode audit without reinterpretation. |
| 3 | EXCITITOR-OBS-54-001 | DONE (2025-11-27) | Depends on 53-001; provenance tooling integrated. | Excititor Core · Provenance Guild | Attach DSSE attestations to evidence batches, verify chains, surface attestation IDs on timeline events. |
| 4 | EXCITITOR-ORCH-32-001 | DONE (2025-11-27) | Orchestrator worker endpoints available. | Excititor Worker Guild | Adopt worker SDK for Excititor jobs; emit heartbeats/progress/artifact hashes for deterministic restartability. |
| 5 | EXCITITOR-ORCH-33-001 | DONE (2025-11-27) | Depends on 32-001. | Excititor Worker Guild | Honor orchestrator pause/throttle/retry commands; persist checkpoints; classify errors for safe outage handling. |
| 6 | EXCITITOR-POLICY-20-001 | DONE (2025-12-01) | Implemented `/policy/v1/vex/lookup` batching advisory_key + PURL with tenant enforcement; aggregation-only. | Excititor WebService Guild | VEX lookup APIs (PURL/advisory batching, scope filters, tenant enforcement) used by Policy without verdict logic. |
| 7 | EXCITITOR-POLICY-20-002 | DONE (2025-12-01) | Scope metadata persisted in linksets/events; API responses emit stored scope; remaining backfill optional. | Excititor Core Guild | Add scope resolution/version range metadata to linksets while staying aggregation-only. |
| 8 | EXCITITOR-RISK-66-001 | BLOCKED (2025-12-01) | Blocked on 20-002 outputs and Risk feed envelope. | Excititor Core · Risk Engine Guild | Publish risk-engine ready feeds (status, justification, provenance) with zero derived severity. |

## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-03 | Normalised sprint structure; added Decisions/Risks and Next Checkpoints; no status changes. | Planning |
| 2025-11-27 | Marked OBS-52/53/54, ORCH-32/33 DONE after timeline/locker/attestation/orchestrator delivery. | Implementer |
| 2025-12-01 | Normalized sprint file to standard template; set POLICY-20-001/20-002 and RISK-66-001 to BLOCKED pending Policy/Risk contracts (`advisory_key` schema, feed envelope). | Project Mgmt |
| 2025-12-01 | Implemented policy VEX lookup endpoint (`/policy/v1/vex/lookup`) with advisory/PURL batching, canonicalization, and tenant enforcement; marked POLICY-20-001 DONE. | Implementer |
| 2025-12-01 | Persisted canonical scope metadata on linksets/events (core + Mongo mapping), surfaced scope on list/detail APIs from stored scope; fixed policy endpoint tenant resolution/metadata mapping. POLICY-20-002 set to DONE. | Implementer |
| 2025-12-01 | Updated test harness `StubAirgapImportStore` to implement new `IAirgapImportStore` methods; rebuilt WebService tests (policy filter reports no matching tests as PolicyEndpointsTests are excluded from project). | Implementer |
| 2025-12-02 | Stabilized WebService test host with `UseTestServer` + TestHost package; full Excititor WebService test suite passes (all 26 green). Policy endpoints test now runs with test harness overrides (stub signer/attestation) and passes. | Implementer |

## Decisions & Risks
- Excititor remains aggregation-only: policy lookup returns stored scope/linkset metadata without verdicts.
- Risk feed (EXCITITOR-RISK-66-001) blocked pending Risk envelope; avoid emitting partial feeds to prevent contract drift.
- Orchestrator integration delivered; keep feature-flagged until production thresholds validated.

## Next Checkpoints
- Publish Risk feed envelope to unblock EXCITITOR-RISK-66-001.
- Re-run WebService tests after any advisory_key schema changes from Policy.
- Validate timeline/locker/attestation events with latest Evidence Locker manifests to ensure parity.

## Decisions & Risks
- **Decisions**
  - Aggregation-only stance holds for policy/risk APIs; no consensus or severity derivation.
  - Worker orchestration stays feature-flagged; falls back to local mode if orchestrator unavailable.
- **Risks & Mitigations**
  - Policy contract delays block API shape → Keep tasks BLOCKED; proceed once contract lands; reuse Concelier/Vuln canonicalization if applicable.
  - Risk feed envelope unknown → Mirror Risk Engine schema as soon as published; stage behind feature flag.
  - Policy endpoints test harness injects stub signer/attestation services; test is active and passing (no skips remaining).

## Next Checkpoints
- Await Policy/Risk contract publication; unblock POLICY-20-001/002 and RISK-66-001 upon receipt.