This document describes the Telemetry Record: the per-invocation structured audit artifact that SADAR produces at every trust-boundary crossing. The record is the durable substrate of SADAR's cross-organizational accountability story; it is what Repatriation moves across trust boundaries, what authorized auditors retrieve, and what cryptographic parity binds together with the SCT chain and OTel trace fabric.
This page covers what a Telemetry Record is, the six sections that compose it, the four lifecycle phases that populate those sections, the phase-immutability invariant that governs writes, the Helper API access pattern that mediates all interaction with the record, and the persistence-at-finalize semantics that produce the durable artifact. The full field-level schema lives in the 6. Telemetry Record and Repatriation companion document; this page is the orientation and architectural framing.
Audience: implementers building agents, tools, or orchestrators that participate in SADAR-conformant invocation flows; architects scoping audit infrastructure; and audit/compliance teams evaluating whether the artifact set meets their cross-organizational accountability requirements.
A Telemetry Record is a structured, per-invocation audit artifact issued by the entity that performs the invocation. Exactly one record is produced per invocation. The record conforms to a defined schema (the six sections below); it is built progressively across the four lifecycle phases of the invocation; it is signed and persisted at finalize; and it becomes available for Repatriation and authorized read access only after persistence.
Records live in the issuing entity's local audit store. They are private to that entity by default — not pushed to other organizations as a matter of course. Cross-organizational visibility into a record is achieved through Repatriation (returning selected fields to entitled recipients) rather than through shared audit infrastructure. This isolation is what lets SADAR-conformant audit work across organizational and jurisdictional boundaries: each entity owns its records, each entity controls what it returns, and the discipline of cryptographic parity ensures the records are mutually consistent at every observable point.
Conformance: every entity participating in invocation flows MUST produce a Telemetry Record at each trust boundary it crosses. An entity that does not produce conformant records cannot participate in an audit chain that meets the cross-organizational accountability requirements of §5.1.14.
A Telemetry Record is composed of six sections. Each section captures a coherent view of one aspect of the invocation — what was searched for, what came back, what was selected, what was invoked, what happened, and how risk evolved. The sections are populated in lifecycle order during the invocation's progression through the four phases (covered below); each section becomes immutable when the phase that populate sit ends.
The risk_score_state section is structurally distinct from theother five. The other sections are populated within a single phase and then sealed. risk_score_state is updated at every phase boundary — its value at any given point reflects the cumulative state up to that point — and is finalized only when the Outcome phase completes. The phase-immutability invariant still applies to it: the state a teach phase boundary is sealed and not subsequently rewritten; subsequent updates are appended deltas, not replacements.
A Telemetry Record's lifecycle has four phases. Each phase corresponds to a coherent activity in the invocation flow, has a defined boundary at which it ends, and seals one or more sections of the record at that boundary. The phases run in strict sequence: a record cannot enter Selection before Search ends, cannot enter Invocation before Selection ends, and cannot finalize before Outcome ends.
The lifecycle is driven by the orchestrator — typically searchAndInvoke — which signals phase transitions through Helper API calls. The Helper API enforces phase ordering: an attempt to write to a sealed section, or to start a phase out of order, is rejected with a structured error in the urn:sadar:error:v1 namespace.
Phase-immutability is the central invariant governing writes to a Telemetry Record. It states: once a phase ends, the section or sections sealed at that phase boundary become permanently immutable. Subsequent activity in later phases cannot rewrite them, even if new information would seem to warrant it.
This invariant matters for several reasons. It makes the record tamper-evident: an auditor who retrieves a record can verify that the sealed-at-Search content reflects what the orchestrator observed during Search, not a later revision. It supports concurrent observation: once a phase has sealed, observers can read its content without worrying that it will change underneath them. It enables phase-specific access control: different parties can have different read entitlements to different phases without complex consistency reasoning. And it produces a clean audit semantics: the record's content at finalize is the record's content forever; no edit history, no shadow versions, no eventual consistency to reason about.
If new information is uncovered after a phase has sealed, the right pattern is not to edit the sealed section but to record the new information in a place that does accept it. Most commonly, that place is a follow-on Telemetry Record for a follow-on invocation— a new audit artifact for a new event — rather than a retroactive amendment toan earlier one. The orchestrator's responsibility is to capture what it knows during the phase that section corresponds to; what it learns later belongs in later artifacts.
All interaction with a Telemetry Record passes through the Helper API. Implementations do not write to the record directly; they call Helper API methods that interpret writes in the lifecycle context, validate them against the phase-immutability invariant and the section schema, and apply them to the in-flight record. Reads — for Repatriation, for authorized observation, for audit retrieval — also passthrough the Helper API, which validates the caller's scope and applies field-level entitlement policy.
The Helper API serves three architectural purposes. First, it centralizes audit semantics: implementers don't have to re-implement phase-immutability, schema validation, or cryptographic-parity computation in each agent or tool. Second, it produces a clean integration surface: a SADAR-conformant entity is one that uses the Helper API correctly, regardless of how its internal logic is implemented. Third, it lets the audit substrate evolve without breaking implementers: schema extensions, new section additions, and storage-layer changes can happen at the Helper API layer without requiring every implementer to change their code.
The Helper API surface includes write operations (append-to-current-section, end-current-phase), read operations (read-section, read-record), administrative operations (start-record, finalize-record), and Repatriation operations (return-fields-to-entitled-recipient). Authorization for each operation is governed by the same authentication scopes that govern other SADAR operations —drawn from the urn:sadar:scope:v1 namespace, with target-as-issuer semantics. The full method-by-method specification lives in the 6. Telemetry Record and Repatriation companion document.
Telemetry Records are persisted only at finalize — that is, only when the Outcome phase ends and the orchestrator signals that the record is complete. Before finalize, the record exists in-flight: held by the orchestrator (typically searchAndInvoke) or by whatever audit subsystem is staging the record's progressive construction, but not yet a durable artifact.
Deferred persistence is a deliberate design choice. Persisting at finalize gives several properties that incremental persistence cannot. It produces atomic durability: either the entire record persists (complete, signed, parity-correct) or none of it does, with no partial records cluttering audit stores. It defers cryptographic operations to a single point: parity values can be finalized once all parity-bearing values are known, and the record's signature covers the entire content rather than a sequence of section signatures. And it produces clean failure semantics: an invocation that fails before finalize does not leave a partial record behind. Failure within the lifecycle is itself an outcome — the orchestrator finalizes the record with an outcome section reflecting the failure, and the record is persisted as normal.
The only case in which a Telemetry Record is not persisted is when the orchestrator itself fails before reaching finalize — a process crash, a network failure that prevents finalize from completing, or similar. In that case, the in-flight record is lost. This is a known operational risk; mitigations include orchestrator-level checkpointing and orchestrator-level failover, but they live in the operational domain rather than the spec.
After persistence, the record is available for Repatriation per the policies governing the issuing entity, and for authorized read access via the Helper API. The persisted record is signed and immutable; cryptographic parity binds it to the SCT chain links and OTel trace content for the same invocation. From this point forward, the Telemetry Record is what the audit fabric works with — Repatriation moves it (or selected fields of it) across trust boundaries; auditors retrieve it; cross-artifact reconstruction draws on it. See Observability Overview for how the Telemetry Record composes with the other observability primitives.
This page covers the Telemetry Record itself — what it is, how it is structured, how it is built, how access is mediated, when it is persisted. Several adjacent topics are intentionally out of scope here and live in dedicated documents:
• Observability Overview — the cross-cutting summary of SADAR observability; how the Telemetry Record composes with OTel baggage, Repatriation, and Risk Score.
• Repatriation — the cross-trust-boundary return mechanism for finalized Telemetry Records.
• Risk Score — the synthesized cumulative-risk scalar tracked in the risk_score_state section.
• SADAR Context Token — the SCT chain link the invocation section references; the substrate that cryptographic parity binds to the Telemetry Record.
• 2. Scope §5.1.14 — Observability umbrella; the normative source for Telemetry Record requirements at the spec level.
• 2. Scope §5.1.17 — Cryptographic Parity; the requirement that binds Telemetry Records to SCT chain links and OTel traces.
• 4. SCT Operations — full SCT cryptographic semantics; the chain link the invocation section references.
• 6. Telemetry Record and Repatriation — the full normative content: complete field-level schema, Helper API method specifications, Repatriation protocol.
• 7. searchAndInvoke — the orchestrator that drives the four-phase lifecycle and emits the Helper API calls that build the record.
• 8. Risk Score Specification — the canonical Risk Score inputs, computation, and trust-model contribution; the source of truth for what the risk_score_state section captures.