The single span surface for mailglass_inbound (D-45-01).

Mirrors Mailglass.Webhook.Telemetry: every inbound :telemetry.span/3 call lives here so the extended NoPiiInTelemetry check (enabled for inbound in Plan 01) has exactly ONE module to audit, plus the four call sites. Callers MUST NOT reach for :telemetry.span/3 directly — use the named helpers below.

Events emitted

Event-name convention note (D-49-17 deviation): the CONTEXT named the rate-limit event [:mailglass_inbound, :rate_limit, :stop] and the prune event [:mailglass_inbound, :prune, :stop] (3 final segments). The locked [root, domain, resource, action] 4-segment telemetry convention (TelemetryEventConvention, enforced at lint time) requires 4 final segments, so these ship as [:mailglass_inbound, :ingress, :rate_limit, *] (rate-limit is an ingress-path event, beside :suppression_flag) and [:mailglass_inbound, :prune, :sweep, *]. Same resource name, convention-compliant.

Every helper is a full :start/:stop/:exception span via :telemetry.span/3. There is no single-emit (fire-and-forget) helper here — inbound emits via spans only. :telemetry.span/3 supplies :duration in its :stop measurements automatically; callers MUST NOT hand-compute latency into metadata.

Per-request stop metadata enrichment

Each helper accepts a zero-arity function returning either:

• result — bare value; stop metadata equals the metadata argument passed at call time (before the outcome is known).
• {result, stop_metadata} — tuple; stop metadata is the returned map. Used by the call sites to attach the classified :status, :operation, :outcome, :mailbox onto the :stop event after the inner function returns. Start metadata is always the metadata argument at call time.

Whitelist discipline (D-45-03)

The ONLY allowed metadata keys across all spans:

provider, tenant_id, status, latency, byte_size, mailbox, candidate_count,
outcome, source, operation, record_type,
bucket, limit, retry_after, flagged,
records_deleted, evidence_deleted, fresh_runs_deleted, replay_runs_deleted

The Phase-49 additions (bucket, limit, retry_after, flagged + the per-table prune counts) are all counts/types/statuses — never PII (D-49-17/23/29). The rate-limit + suppression-flag spans carry the bucket TYPE and a boolean flag, never the recipient/sender value.

NEVER include in any metadata map:

:to, :from, :cc, :bcc, :subject, :body, :html_body, :headers,
:recipient, :sender, :email

NoPiiInTelemetry (extended to inbound in Plan 01) lints THIS module plus every caller against the forbidden-key set.

Handler isolation (TELE-05)

:telemetry.span/3 wraps each attached handler in a try/catch. A handler that raises is detached automatically and [:telemetry, :handler, :failure] is emitted — the caller's inbound pipeline is unaffected. mailglass_inbound does not add a parallel try/rescue around business code (that would duplicate or, worse, swallow the meta-event operators rely on). TELE-05 comes for free from routing every span through :telemetry.span/3.