Records and chains
A record is one thing an agent did, or one thing the sensor or the server noted, written as one line of JSON, hashed, signed by the device that made it and linked to the record before it. A chain is one device's records in order. The server keeps a chain of its own, of administrative actions, signed with the workspace's audit key.
What each member of a record means is the record reference (docs/reference/records.md, and its JSON twin, which the API serves at /w/<ws>/api/v1/schema). This page specifies what a verifier needs: the line, its canonical encoding, its hash and signature, and the chain.
Vectors: 01-canonical-v1, 02-canonical-v2, 03-record-v1, 04-chain-v1, 05-server-chain-v1, 06-chain-v2, 24-canonical-context-v1, 25-chain-context-v1; for hardware anchors, 19-hardware-chain and 20-hardware-chain-copied.
The envelope
Every record, of every schema version, has these members. They are the only ones a verifier of chains must understand.
| Member | Type | Meaning |
|---|---|---|
v | integer | The schema version: 1 or 2 today |
id | string | The record's id, a ULID |
seq | integer | Its position in its chain, from 1, without gaps |
ts | string | When the device made it, by its clock |
device_id | string | The chain it belongs to: d_ and 32 hex digits for a device, server for the server's chain |
event | string | What happened, such as tool.pre |
prev | string | The hash of the record at seq - 1; empty for seq 1 |
hash | string | The record's hash (below) |
sig | string | The signature (below), base64 |
v is the first member of the line and prev, hash, sig the last three, in that order.
A device's id is derived from its key: d_ followed by the first 16 bytes of the SHA-256 of its 32-byte Ed25519 public key, in lower-case hex. A verifier checks that the key it verifies a device chain with derives the chain's device_id. The server chain's id is the fixed string server.
The canonical encoding
The canonical encoding of a record is its line with hash and sig set to the empty string. A record line is always written in this encoding (with hash and sig filled in), so a verifier that holds a line gets the canonical bytes by replacing the values of the last two members with ""; it does not need to parse the record.
The encoding, which a writer must produce and a strict reader may check:
- one JSON object, no space between tokens, no line feed inside;
- members in the order of the record reference, a member left out when empty (the envelope members above are always present,
preveven when empty); - the keys of a map (
extra, and others the reference marks as maps) sorted by their UTF-8 bytes; - in strings:
"and\escaped as\"and\\;<,>and&written<,>and&; U+2028 and U+2029 writtenand; control characters below U+0020 written\b,\f,\n,\r,\tor\u00XXwith lower-case hex; U+007F and every other character written raw, as UTF-8; - invalid UTF-8 in a string replaced by U+FFFD before encoding;
- integers in decimal without a fraction or exponent, to the full range of an unsigned 64-bit number for
seq.
The canonical vectors hold records as a writer might spell them (input_b64), the canonical encoding each must produce (canonical) and that encoding's SHA-256 (sha256).
A line is at most 66,048 bytes (a record of at most 65,536 bytes and its envelope's growth). A reader refuses a longer one.
Hash and signature
hashis the SHA-256 of the canonical encoding, as 64 lower-case hex digits.sigis the Ed25519 signature, by the chain's key, over the 32 bytes of that SHA-256 (the bytes, not their hex), in standard base64.
A verifier of one record: take the line, form the canonical bytes, hash them, compare with hash exactly, and verify sig over the hash bytes with the chain's public key. 03-record-v1 is one line and its key.
A device chain is signed with the device's key. The server chain is signed with the workspace's audit key (05-server-chain-v1).
A chain
Records of one device_id form a chain when, in order:
- the first has
seq1 and an emptyprev; - each next has
seqone more than the one before andprevequal to itshash; - every record's hash and signature check under the one key.
A record whose seq is not greater than the one before is a replay; one whose seq skips is a gap; one whose prev names another hash is a fork. Each makes the chain invalid, with one exception.
Declared gaps
A device that lost records says so in the chain. A record with event coverage.gap and extra.reason lost_range declares records lost; its extra holds, as decimal strings, lost_from_seq, lost_to_seq and prev_seq. It may follow a record it does not link to when all of these hold, where last is the record before it in the file:
- its
seqis greater thanlast.seq; lost_from_seqis at least 1 and at mostlost_to_seq, andlost_to_seqis its ownseq - 1;lost_from_seqis at mostlast.seq + 1(nothing between is missing undeclared);prev_seqislost_to_seqorlost_from_seq - 1;- when the verifier holds the record at
prev_seq, the gap record'sprevis that record'shash(whenprev_seqis 0,previs empty). When it does not hold that record, the link cannot be checked, which a verifier notes.
A verifier lists every declared gap it finds. A coverage.gap record with another extra.reason (such as append_failed, with extra.count) links like any record and is listed too.
Where a chain ends
A chain alone cannot show that its last records were not cut off. Its end is proven by one of:
- an ingest receipt for its last
seqandhash(log.md); - an inclusion proof of its last record in a signed checkpoint (log.md);
- a head hash or last
seqthe verifier was told to expect from elsewhere.
Without one, a chain that otherwise checks is unproven, never valid.
Records of a newer schema
A verifier written for schema versions up to N may meet a line with a larger v. Such a line still ends with "prev":…,"hash":…,"sig":…} and its hash is still the SHA-256 of the line with hash and sig emptied, so the verifier checks its link, hash and signature exactly as above and does not judge what it says. When everything else checks, the result is "written by a newer schema: upgrade to check it", reported as unreadable input (exit code 2), never as tampering; when anything fails, the result is invalid.
Records the server redacted
When a device sent a secret, the server redacts its stored copy of the record. The log still holds the original hash, so the stored line no longer matches its hash.
- In a search export the line is marked
server_redacted: a verifier checks its inclusion proof, notes it, and checks neither its hash nor its signature. - In a bundle the manifest lists the record's
sequnder the chain'sserver_redacted. This version ofantler-verifynotes the list and still checks every line's hash, so a bundle that holds a redacted record is reported invalid at that record, with the note saying why. A reader of such a result compares the failingseqwith the list.
Hardware-anchored heartbeats, version 1
Format name: antler-hardware-anchor-v1. Added on 17 November 2026. Nothing above changes: a record keeps its schema version, its canonical encoding, its hash and its Ed25519 signature, and a chain verifies by the rules above whether or not it carries anchors. A verifier written before this section reads an anchored chain as a chain and reports nothing about anchors.
A device's key is a file on its computer. A device in the hardware-backed mode also holds a second key, an ECDSA key on the curve P-256, which its computer's security chip made and keeps (a TPM 2.0 today). That key signs no record. It signs, in each sensor.heartbeat record of the device, a head of the device's chain: the seq and hash of a record before the heartbeat. The signature travels in the heartbeat's extra, so it is inside a record the device key signed.
A record is hardware-anchored when an anchor that holds covers it. What that shows: the key of that chip signed a head that commits to the record, and such a key cannot be copied to another computer, so a copy of the device's files can sign records but anchor none. What it does not show: that the computer was honest. Whoever fully controls it can ask its own chip to sign. That the key lives in a chip is what the device says; nothing in this format proves it to a third party.
The members
A heartbeat states where the device's key is kept and, in the hardware-backed mode, carries the anchor. Both are members of extra.
Member of extra | Value |
|---|---|
key_protection | hardware when the heartbeat carries an anchor; software when the device key is only a file, or when the chip did not answer. Absent in a heartbeat made before this section |
hw_anchor | The anchor (below). Only on a sensor.heartbeat |
hw_unavailable | With software, on a device that wanted an anchor: why it has none, a token such as no_chip, no_permission, chip_error, unsupported_platform or key_mismatch (the chip does not hold the key the device's files name) |
The anchor
hw_anchor is seven fields joined by colons (0x3A), with no space:
v1:<store>:<key>:<head seq>:<head hash>:<attested>:<signature>
| Field | Form |
|---|---|
| version | The two characters v1 |
| store | The key store, as the device names it: 1 to 32 characters of a to z, 0 to 9 and -; tpm2 for a TPM 2.0 on Linux, cng for the TPM through the Windows platform provider |
| key | The hardware key's public half: the standard base64, with padding, of 65 bytes, the uncompressed point (0x04, then X and Y, 32 bytes each, big-endian) |
| head seq | The head's seq, in decimal without a leading zero; 0 for an anchor that covers no record and only names the key |
| head hash | The head's hash, 64 lower-case hex digits; empty exactly when head seq is 0 |
| attested | The names of the members of this heartbeat's extra the signature covers, joined by commas (0x2C), in strictly ascending order of their bytes, each 1 to 64 characters of a to z, 0 to 9, ., - and _, at most 32 names, never hw_anchor; may be empty |
| signature | The standard base64, with padding, of 64 bytes: the ECDSA signature's r, then s, 32 bytes each, big-endian |
One anchor has one spelling: a reader refuses any other (another version, a missing field, a seq with a leading zero, upper-case hex, names out of order, base64 that is not strict). The whole value is at most 4,096 bytes.
What the hardware key signs
The signed message is these lines, each ended by a line feed (0x0A), as UTF-8 bytes:
antler-hardware-anchor-v1- the heartbeat's
device_id - the heartbeat's
id - the heartbeat's
ts - the anchor's store
- the anchor's key, as its base64 text
- the anchor's head seq, as its text
- the anchor's head hash (an empty line when head seq is
0) - then, for each attested name in the anchor's order,
<name>=<value>, where the value is that member of the heartbeat'sextra
The signature is ECDSA with SHA-256 over those bytes (the chip is given the message's SHA-256), by the anchor's key. Any valid signature is accepted: r and s are each at least 1, and no rule restricts s to the lower half. A real chip's signatures differ on every run; the vectors' were made as RFC 6979 makes them so that the files do not change.
An anchor verifies for a heartbeat when all of these hold:
- the record's
eventissensor.heartbeat; - the anchor parses;
- head seq is less than the heartbeat's
seq; - every attested name is a member of the heartbeat's
extrawith a value that is not empty and holds no line feed; - the signature checks.
The attested names are how the heartbeat's posture is signed by the same key: a device attests key_protection and, among others, disk_encrypted, hooks and sensor_version when the heartbeat carries them. Changing an attested value, or removing it, makes the anchor fail. spool_head_seq and spool_head_hash are never attested: the device sets them after the chip signed, and the head the chip signed is in the anchor itself, at or before the spool head.
What a chain's anchors cover
A verifier that has checked a device chain's records (hash, signature, links) works out coverage by going through them in order:
- The chain's hardware key is the key of the first anchor in the chain that verifies, unless the verifier was given the device's hardware key from elsewhere. An anchor that verifies under another key is not counted: it covers nothing, and the verifier lists it. A second key cannot take a chain over.
- An anchor that does not verify is not counted and is listed.
- **A counted anchor with head seq
0** covers nothing. - A counted anchor's head must be the chain's record: the record with that
seqamong those the verifier read must have thathash. When it has another hash the anchor is not counted and is listed. When the verifier did not read a record with thatseq(the export starts later), the anchor is counted as without head and covers nothing. - A counted anchor whose head is confirmed covers a run of records: the head, and every record before it back to the start of the head's run. A run starts at the first record read, and again at every record whose
previs not thehashof the record read just before it (a declared gap whose link went with the lost records): no later head commits to what came before such a record.
The hardware-anchored records are the union of the covered runs. Every other record is signed by the device key only: the records after the newest confirmed head always are, until a later heartbeat anchors them.
Coverage is a statement about records, never a verdict: anchors that are not counted do not make a chain invalid, and a chain without anchors is as valid as it was. antler-verify prints, for each device chain that says anything about key protection, the anchored runs, the store and the first 12 hex digits of the SHA-256 of the key's 65 bytes, the records after the newest anchored head, and each anchor it did not count.
The vectors
19-hardware-chain is a chain of 13 records with anchors at seq 5 and 10: records 1 to 9 are anchored. 20-hardware-chain-copied continues that chain, after seq 12, the way a copy of the device's files on another computer would: a heartbeat with no anchor, then one anchored by another key. Its records all verify under the device key, and still only records 1 to 9 are anchored. The vector kind hardware-chain is in vectors.md.
The process context and the reach records
Two things a record can say are carried in extra, as keys of schema version 1, so a verifier needs nothing new for them: it hashes the line as written. They are named here because other tools read them.
The process context (antler-process-context-v1) is on the records that ask: session.start, prompt and tool.pre. It is what the operating system said about the programs above the hook when the record was written, whatever the agent's payload claims:
| Key | Value |
|---|---|
proc_exe | The path of the agent's program: the nearest process above the hook that is not a shell or a command wrapper. For an agent that runs on an interpreter, the interpreter. |
proc_signature | embedded, adhoc or none: the code signature that program's file carries, read from the file's own headers (Mach-O, PE). It is not verified. Absent on Linux. |
proc_ancestry | The paths of the programs above the hook, its parent first, separated by a line feed (U+000A), at most 8, each at most 400 bytes. A process whose path the system does not give is listed by its short name. |
proc_ancestry_more | true when there were more programs above the last one listed. |
Paths only, never arguments or environment. A reader takes the keys as a context only when proc_signature, if present, is one of the three values and comes with proc_exe, proc_ancestry has 1 to 8 lines and none empty, and proc_ancestry_more, if present, is true and comes with proc_ancestry.
A reach record (antler-reach-v1) has the event reach.detected: one thing an AI tool on the device can reach, as the sensor's inventory read it from the tool's own configuration and the usual credential stores. It names no agent session and no account. extra.reach_kind is tool_server, plugin or credential; extra.reach_state is present or, on the one record written when the thing is no longer found, gone; extra.reach_baseline is true on the records of a device's first look. A tool server carries reach_transport, reach_command (the program and, for a package runner, what it runs; no other argument), reach_env (the names of its variables) and its hosts in target.hosts. A credential carries reach_via (file, env or tool_server), cred_type, and, when the sensor could name a single credential, cred_tag with redaction_kid: the keyed tag a version 2 record's creds gives the same credential. No record holds a credential's value. The record reference lists every key.