Implementation Plan: Observability and Evidence

Make execution inspectable and governance-verifiable by unifying telemetry (logs/metrics/traces), evidence capture, and correlation IDs across protocols and domain events, while enforcing privacy and anti-leakage constraints.

Provenance & Traceability

Architectural Decisions (ADRs)

Product Requirements (PRDs)

Software Design Specifications (SDS)

Note: SDS-043 (Risk & Evidence Service) has been superseded by SDS-047 per ADR-031.

Provenance Chain

graph TD
  ADR29[ADR-029: Observability Stack] --> PRD10[PRD-010: AI Governance Runtime]
  PRD10 --> SDS47[SDS-047: GovernedSpeed™ Runtime]
  ADR29 --> SDS30[SDS-030: Semantic Observability Envelope]
  SDS47 -.-> SDS43[SDS-043: SUPERSEDED]

  style SDS43 fill:#ffcccc

Architecture and Design

Design Principles Applied

• Isomorphism: Semantic context (sea.domain, sea.concept, sea.regime_id) is preserved as OTel resource attributes.
• Invariants: PII scrubbing before export; high cardinality blocking (SDS-030, ADR-029).
• Idempotency: Evidence artifacts are content-hash deduped (SDS-047).

Dependency Justification

• No new dependencies for plan completion; align with ADR-029 standard components.

Expected Filetree

1
2
3
4
/
├── docs/specs/shared/adr/029-observability-stack-architecture.md
├── docs/specs/shared/sds/030-semantic-observability.md
└── docs/specs/shared/sds/047-governedspeed-governance-runtime.sds.yaml

Proposed Cycles

Task Breakdown

Wave 1 (Parallel)

• C1A: Finalize the semantic observability envelope (modes, scrubbing, cardinality constraints)
  • Implements: Standard wrapper for telemetry signals with sensitivity handling
  • Satisfies: ADR-029 invariants and SDS-030 constraints
  • Files: docs/specs/shared/sds/030-semantic-observability.md
• C1B: Finalize evidence artifact capture and retrieval surfaces
  • Implements: Evidence hash, submission events, risk snapshots
  • Satisfies: PRD-010 REQ-GS-004 and SDS-047 contracts
  • Files: docs/specs/shared/sds/047-governedspeed-governance-runtime.sds.yaml, schemas/events/governance/evidence/*

Wave 2 (Depends on Wave 1)

• C2A: Standardize correlation ID propagation across inbound requests, domain events, and telemetry
  • Implements: Trace/span correlation and causation chains
  • Satisfies: SDS-030 envelope and ADR-029 observability guarantees
  • Files: docs/specs/shared/sds/030-semantic-observability.md

Validation & Verification

Spec Validation

• Ensure observability envelope forbids PII in exported telemetry by default (scrub or delete)
• Confirm evidence artifacts are defined with tamper-evident hashing (SHA256) per SDS-047

Implementation Validation

• Metrics are OTLP-exported and include governance gauges/counters (PRD-010 REQ-GS-004)
• Logs correlate with traces via trace_id/span_id (ADR-029)
• Evidence bundles can be reconstructed for a governance decision (SDS-047)

Open Questions

1. What is the canonical location/config for the OTel Collector pipeline in this repo (file path + deployment target)? infra/otel/collector-config.yaml
2. Which “semantic context attributes” are mandatory vs optional, and how are they derived (from identity tokens, manifests, or flows)? sea.domain, sea.command, sea.cqrs_kind
3. What retention policy applies to full_fidelity payload mode (and how is it enforced)? 7d hot / 90d cold

Risks & Mitigation

Rollback Strategy

1. Fall back to aggregated payload mode + reduced attribute set while keeping correlation IDs intact.

Related Documents

Linked Specifications

Superseded: SDS-043 (Risk & Evidence Service) has been merged into SDS-047 per ADR-031.