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

Audience: developers implementing sealed-mode guardrails in StellaOps.Telemetry.Core, and operators running Stella Ops in air-gapped sites.
Status: preparation contract for the sealed-mode helpers — read alongside the implementation in src/Telemetry/.

Objective

Define the behavior and configuration for telemetry when Sealed=true: guarantee no external egress while preserving deterministic local traces and metrics for offline 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 at 10% in sealed mode unless the CLI incident toggle raises it (see the CLI incident toggle contract); ceiling 100% with the 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.

Scrubbing contract (TELEMETRY-OBS-51-002) — sealed mode forces these redaction rules on.
CLI incident toggle contract (CLI-OBS-12-001) — the only sanctioned way to lift the sealed sampling ceiling.
Telemetry standards — the platform-wide offline/air-gap posture.

Provenance

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