Envelope

Envelope fields

Every record is a JSON object. These members may appear on any record type; each record type adds its own fields.

Field	Type	Req	Meaning
`type`	string	yes	Record type. Core types contain no `/`. Vendor types are `<reverse-dns>/<name>`, for example `dev.zed/agent_switched`.
`seq`	integer	yes	Observation order (see Physical format).
`id`	RecordId	yes	Record ID, unique within the stream.
`ts`	Timestamp	no	When the item occurred, at native precision. Never fabricated.
`tsPrecision`	string	no	`ns`, `us`, `ms`, `s`, `min` or `day`.
`tsSource`	string, open	no	Where `ts` came from: `native`, `container`, `embedded_text` or `recorder`.
`observedAt`	Timestamp	no	When the producer captured the record (capture time, as opposed to occurrence time).
`supersedes`	RecordId	no	The earlier record that this record fully replaces (see Missing data and revisions).
`assembly`	object	no	How the record was assembled from native records (see Missing data and revisions).
`branchesFrom`	object	no	Present only at a real branch point, and only on context-participating records (see Structure).
`turnId`	string	no	Source-defined turn grouping (see Turns and triggers).
`trigger`	object	no	What started the turn, on the turn’s first record only (see Turns and triggers). Not an envelope field on `session` and `compaction` records, which define their own `trigger`.
`inferenceId`	string	no	The model call that produced this record. On an `inference` record it is that record’s entity key.
`copiedFrom`	object	no	This record is a copy of another record, in another session or in this one (see Lineage).
`idSource`	string	no	`native` or `derived`: where the record’s entity key came from (see Identity).
`idScope`	string	no	`capture`: the record’s IDs are positional within this capture.
`capture`	object	no	Capture states for the record’s content-bearing fields (see Missing data and revisions).
`native`	object	no	The source record, embedded or referenced (see below).
`redactions`	array	no	Redactions applied to this record (see Privacy).
`_meta`	object	no	Vendor data under reverse-DNS keys (see Extensibility).

ASR-100 Every record MUST have type (a string), seq (ASR-012) and id (ASR-018). ASR-101 A core record type MUST match ^[a-z][a-z0-9_]*$. A vendor record type MUST be a reverse-DNS name (ASR-056), followed by /, followed by a name matching ^[A-Za-z0-9][A-Za-z0-9_.-]*$. ASR-102 Producers MUST NOT write a core record type that the formatVersion they declare does not define. Undefined core type names are reserved for future versions.

Time

ASR-103 ts MUST describe the record’s own item and MUST come from the source, or, for a recorder, from the time it received the item (with tsSource: "recorder"). A producer MUST NOT copy a timestamp from one item to another, interpolate between items, or substitute the time of conversion. ASR-104 A producer MUST NOT round or truncate a native timestamp. When the source’s precision is coarser than the written form implies (minute- or day-precision values written with zero seconds), the producer MUST set tsPrecision. Microsecond and nanosecond precision MUST be preserved when the source has it. ASR-105 tsPrecision MUST be one of ns, us, ms, s, min, day. When ts did not come from a native per-item timestamp, the producer MUST set tsSource:

native: a timestamp the source stored for this item;
container: the time of a storage container that the source maintains for exactly this item (a row’s or file’s own time);
embedded_text: a time written inside the item’s content (for example a timestamp element in a prompt);
recorder: the time a recorder received the item.

ASR-106 observedAt is the time of capture. Readers MUST NOT use observedAt as the time an item occurred. When tsPrecision is absent, readers MUST NOT assume more precision than the digits written.

Root members

ASR-107 Producers MUST NOT write top-level members other than the envelope fields above, the fields defined for the record’s type in the declared formatVersion (for a vendor record type, the fields its owner documents), and _meta. Vendor data on core record types goes in _meta. ASR-108 Readers and storage tools MUST preserve top-level members they do not recognize in streams whose formatVersion has the same major version as the version they implement and a higher minor version. Validators MUST report an unrecognized top-level member as an error when the stream’s declared version does not define it.

Links to model calls and turns

ASR-109 inferenceId on a record other than inference names the model call that produced it. Resolution follows the reference-resolution table. A missing call produces an availability warning, including when the stream does not claim the usage profile. ASR-110 turnId MUST come from a turn identifier or an explicit turn boundary recorded by the source. Producers MUST NOT synthesize turn IDs from message counts, prompt boundaries or timing.

`native`

native carries or points to the source record, for round-tripping and audit.

{
  "native": {
    "format": "claude-code-jsonl",
    "ref": "native/claude-code/0f3c2a7e.jsonl#L57"
  }
}

Field	Type	Req	Meaning
`format`	string	no	Native format name (as in `producer.source.format`).
`record`	any	one of	The native record embedded verbatim as JSON.
`ref`	string	one of	A locator: a bundle-relative path, optionally followed by `#` and a source-specific position (line, byte offset, row key).
`blob`	BlobRef	one of	The native record’s exact bytes as a blob (for binary rows).

ASR-111 native MUST contain exactly one of record, ref or blob. ASR-112 Readers MUST NOT follow a native.ref outside the bundle, and MUST NOT fetch it from a network location.

Unknown record types

ASR-113 A reader that does not recognize a record type (a vendor type, a core type it does not implement, or a core type from a newer minor version) MUST treat the record as audit-only, MUST NOT fail because of it, and, when storing or rewriting the stream, MUST preserve it unchanged. ASR-114 Vendor record types are always audit-only: they never become context predecessors, never appear in the context view, and MUST NOT carry branchesFrom. ASR-115 idSource MUST be native or derived; idScope MUST be capture. Other values follow the open-enum rules (see Extensibility).

Record type catalog

“Context” is C for context-participating types and A for audit-only types (see Structure). Every type in the catalog is part of the one JSON Schema for this version.

Group	Type	Context	Entity key	Defined in
Session	`session`	A	—	Session records
	`session_info`	A	—	Session records
	`declaration`	A	—	Session records
	`state`	A	—	Session records
Context	`config_change`	A	—	Session records
	`instructions`	A	—	Session records
	`memory_change`	A	—	Session records
Conversation	`message`	C	`messageId`	Messages
	`plan`	A	`planId`	Messages
	`delivery`	A	—	Messages
	`tool_call`	C	`callId`	Tools
	`tool_result`	C	—	Tools
	`permission`	A	`requestId`	Tools
	`input_request`	A	`requestId`	Tools
	`terminal`	A	`terminalId`	Tools
	`hook`	A	—	Tools
Usage	`inference`	A	`inferenceId`	Inference
	`usage_summary`	A	—	Inference
Structure	`rewind`	A	—	Structure
	`compaction`	C	`compactionId`	Structure
	`subagent`	A	—	Lineage
Coding	`file_change`	A	—	Coding
	`vcs`	A	—	Coding
	`workspace_state`	A	—	Coding
	`checkpoint`	A	—	Coding
Missing data	`gap`	A	—	Missing data and revisions
	`tombstone`	A	—	Missing data and revisions

permission and input_request share the entity key requestId. An entity ref requestId=<value> that matches records of both types is ambiguous (ASR-064).

Extension rules in brief

The full rules are in Extensibility. In summary:

Vendor fields go in _meta, under keys of the form <reverse-dns>/<name>. The keys traceparent, tracestate and baggage are reserved for OpenTelemetry trace context.
Vendor record types are <reverse-dns>/<name> and are audit-only.
Vendor enum values start with _. The recommended form is _<reverse-dns>/<name>, as in Agent Client Protocol (ACP) v2.
Every enum is open. Unknown values, fields and types are preserved by storage tools.
No producer adds top-level members outside the specification (ASR-107).
A native fact that has no standard field goes where the agent’s registry entry documents: a _meta key on the nearest record, or a vendor record type (ASR-618).

Introduction

Format

Records

Trust

Extending and conforming

Agent registry

Envelope fields

Time

Root members

Links to model calls and turns

`native`

Unknown record types

Record type catalog

Extension rules in brief

​Envelope fields

​Time

​Root members

​Links to model calls and turns

​native

​Unknown record types

​Record type catalog

​Extension rules in brief

Envelope fields

Time

Root members

Links to model calls and turns

`native`

Unknown record types

Record type catalog

Extension rules in brief