implementation-observability

# Implementation Observability Observe the semantic runtime without becoming its authority. Read [observability-contract.md](references/observability-contract.md) before defining events, attributes, counters, traces, buffers, disk fallback, diagnostics, or update health. Read the [versioned event wire catalog](references/event-wire-catalog.md) and its [event-wire diagram](assets/event-wire.drawio) when implementing generated internal-event, experiment, authentication-context, or timestamp records. Use [architecture.drawio](assets/architecture.drawio) to trace privacy filtering and sink failure. ## Workflow 1. Start from a canonical semantic event or explicit operational measurement. 2. Classify fields by privacy, cardinality, source, and whether aggregation is sufficient. 3. For local DEBUG diagnostics, prefer maximum safe evidence: stable stage and reason codes, bounded counts, booleans, classifications, correlation IDs, and durations. Never substitute payloads or exact secret-capable configuration merely because DEBUG was requested; attachment bytes, base64, source/storage paths, decoded content, data URLs, and provider bodies remain prohibited. 4. Apply opt-out, essential-traffic, managed-policy, build, and sink kill-switch decisions before routing. 5. Update authoritative local usage/cost counters separately from best-effort exporters. 6. Bound queues, batches, retries, disk persistence, open spans, and shutdown flush. 7. Verify that disabling or breaking every sink does not alter semantic events, permissions, transcript, side effects, or exit status. ## Completion check Satisfy all `OBS-*` rules and scenarios. Test privacy filtering including hostile attachment failures, high-cardinality rejection, duplicate exposure, offline disk fallback, process restart, queue overflow, stale spans, malformed sink response, and shutdown timeout.