# Sealed-mode telemetry helpers (TELEMETRY-OBS-56-001 prep)

## Objective
Define behavior and configuration for telemetry when `Sealed=true`, ensuring no external egress while preserving deterministic local traces/metrics for audits.

## Requirements
- Disable external OTLP/exporters automatically when sealed; fallback to in-memory or file OTLP (`telemetry-sealed.otlp`) with bounded size (default 10 MB, ring buffer).
- Add tag `sealed=true` to all spans/metrics/logs; suppress exemplars.
- Force scrubbing: treat `Scrub.Sealed=true` regardless of default settings.
- Sampling: cap to 10% max in sealed mode unless CLI incident toggle raises it (see CLI-OBS-12-001 contract); ceiling 100% with explicit override `Telemetry:Sealed:MaxSamplingPercent`.
- Clock source: require monotonic clock for duration; emit warning if system clock skew detected >500ms.

## Configuration keys
- `Telemetry:Sealed:Enabled` (bool) — driven by host; when true activate sealed behavior.
- `Telemetry:Sealed:Exporter` (enum `memory|file`) — default `file`.
- `Telemetry:Sealed:FilePath` (string) — default `./logs/telemetry-sealed.otlp`.
- `Telemetry:Sealed:MaxBytes` (int) — default 10_485_760 (10 MB).
- `Telemetry:Sealed:MaxSamplingPercent` (int) — default 10.
- Derived flag `Telemetry:Sealed:EffectiveIncidentMode` (read-only) exposes if incident-mode override lifted sampling ceiling.

## File exporter format
- OTLP binary, append-only, deterministic ordering by enqueue time.
- Rotate when exceeding `MaxBytes` using suffix `.1`, `.2` capped to 3 files; oldest dropped.
- Permissions 0600 by default; fail-start if path is world-readable.

## Validation tests to implement with 56-001
- Unit: sealed mode forces exporter swap and tags `sealed=true`, `scrubbed=true`.
- Unit: sampling capped at max percent unless incident override set.
- Unit: file exporter rotates deterministically and enforces 0600 perms.
- Integration: sealed + incident mode together still block external exporters and honor scrub rules.

## Provenance
- Authored 2025-11-20 to satisfy PREP-TELEMETRY-OBS-56-001 and unblock implementation.