Antler

In development

Early access

Docs

Signed reports

A report is a signed object of purpose report (log.md) whose payload is one JSON document. The server issues three kinds: the coverage report (what was recorded in a window, and what was not), the recall report (what a recall achieved, device by device) and the credential report (which credentials agents touched). Each names its format in its first member, format.

Vectors: 12-report-coverage-v1, 13-report-coverage-v2, 14-report-recall-v1, 15-report-recall-v2, 16-report-credential-v1, 26-report-coverage-v3.

Checking any report

  1. Verify the signed object with a pinned report key. A report on its own carries no keys: the verifier is given the workspace's published keys (its well-known keys document, or a bundle's manifest) and pins among them.
  2. Decode the payload strictly by its format. An unknown format is invalid.
  3. Apply the format's rules (below): totals recomputed from rows, fixed sentences compared word for word, the content hash recomputed.
  4. When the report has a checkpoint, verify the note (log.md) and check every proof in proofs against its root; proofs without a checkpoint are invalid.
  5. Every record the report cites must have a proof in proofs (by record_hash). A cited record without one leaves the report unproven: its content checks, but nothing shows that record is in the log. (For a credential report this is stricter: see below.)

A report is valid when all of this holds with a pinned key. Without a pinned key only steps 2 to 5 run and the result is at best unproven.

Versions and the content hash

Every report has, among its first members:

MemberMeaning
version1 for the first issue, one more for each re-issue
prevThe SHA-256 of the previous version's signed payload; absent on version 1
content_sha256The content hash
generated_atWhen this version was made

A report is issued again only when its evidence changed. The content hash says whether it did: it is the SHA-256 of the payload's bytes with these top-level members changed and every other byte left as it is:

A verifier recomputes it and requires it to equal content_sha256. (A coverage or recall report with an empty content_sha256 is accepted without this check; a credential report always carries one.)

The fixed sentences

Reports state their limits in fixed sentences, which a verifier compares word for word. They are published in sentences.json:

The coverage report

Formats antler-coverage-report-v1, antler-coverage-report-v2 and antler-coverage-report-v3. Members, in order:

MemberTypeMeaning
format, version, prev, content_sha256As above
scope{kind, id}What is covered: an organization, team, person, device or agent
from, tostringThe first and last UTC day covered
provisionalbooleanWhether the window holds days not yet settled
generated_atstringAs above
sessionslistOne row per session (below)
person_dayslistOne row per person, vendor and day of vendor reconciliation (below)
declared_gapslist{device_id, seq, reason, record_hash, count}: each declared gap, naming its record
exclusionslist of stringsThe fixed sentences
checkpointstringA signed checkpoint note
proofslistInclusion proofs in that checkpoint
totalsobjectComputed from the rows (below)
levels, level_counts, unrecorded_agents, ratiosSecond and third formats (below)
second_source, hook_missesThird format only (below)

A session row: session_id, device_id, agent, account_type, transcript_tool_uses, hooked_tool_uses, states (a map from coverage state to a count), problems (optional), chain_intact, status (complete, partial or another value, counted as unknown), reasons (optional), log_only (optional), report_hash (optional), agent_version (optional, third format only).

A person-day row: email_hash, day, vendor, vendor_sessions, recorded_sessions, unrecorded_sessions, vendor_edit_write, recorded_edit_write, unrecorded_edit_write, vendor_tokens, recorded_tokens, settled.

Rules:

The second format

antler-coverage-report-v2 adds:

level_counts and ratios are required, and levels is not empty.

The third format

antler-coverage-report-v3 carries every member of the second format, under the second format's rules, and adds agent_version to a session row (the agent version the session's records name) and two members, both required.

second_source compares the vendor's own record of the organization's accounts with the devices' records, session by session. Its members, in order:

MemberTypeMeaning
feedslist{feed, product}: each connected vendor feed that lists sessions by id, and the agent whose sessions it lists
sessionslistOne row per session (below)
vendor_sessionsnumberThe sessions the vendor's record lists
lineslist{status, sessions, sentence}: the six counted lines
not_comparablelist{reason, sessions, sentence}: the not comparable line, by reason
callsobject{vendor, matched, unrecorded, unlisted, sentence}: the tool-call counts
limitslist of stringsWhat the second source is and is not

A second-source session row: session_id, agent, device_id (optional: the device that recorded the session), feed (optional: the feed whose record lists it), status, reason (optional), calls_compared, vendor_calls, matched_calls, unrecorded_calls, unlisted_calls, unrecorded_call_ids (optional).

Every session is on exactly one line. The statuses, in the order of lines, with what a row of each must hold:

statusA row has
recorded_fullyfeed, device_id, calls_compared true and unrecorded_calls 0
recorded_partlyfeed, device_id, calls_compared true and unrecorded_calls above 0
session_matchedfeed, device_id and calls_compared false
not_recordedfeed, no device_id, matched_calls 0 and unlisted_calls 0
not_in_vendor_recorddevice_id, no feed and calls_compared false
not_comparablea reason of sentences.json, no feed and calls_compared false

Rules:

hook_misses is {rows, sentence}. sentence is hook_miss_sentence word for word. Each row is {agent, agent_version, source, sessions, calls, missed, rate}, where rate is missed of calls as a percentage with one decimal and a % sign, or the not_available text when calls is 0. source is one of:

The rows are sorted by agent, then agent_version, then source.

The recall report

Formats antler-recall-report-v1 and antler-recall-report-v2. Members, in order:

MemberTypeMeaning
format, version, prev, content_sha256As above
recall_id, creator, reason, created_atstringThe recall
policy_versionintegerThe policy version the recall was published in
target_set_sha256stringThe SHA-256 of the target device ids, sorted and joined by line feeds
targetslist of stringsThe frozen target devices
ruleobjectThe recall's rule, as the policy carries it
deviceslistOne row per target device (below)
appearedlist of stringsDevices outside the frozen set where the target was seen later; optional
vendor{status, days}The vendor side: status is seen, pending, none_seen or not_checked; days a list of {day, email_hash, sessions, settled}
exclusionslist of stringsThe fixed sentences
checkpoint, proofsAs in a coverage report
device_statusstringpartial, unproven or effective
unprovenlist of stringsThe devices that make it unproven; optional
uncertainbooleanOptional
generated_atstringAs above
second-format membersBelow

A record reference is {seq, hash, ts}. A device row: device_id, ack (the record that acknowledged the recall; absent when the device did not), last_match_before, first_denied_after (record references, optional), violations (a list of {record, explanation, match}), last_heartbeat, old_settings_sessions, status, and the second format's members.

Rules of the first format:

The second format

antler-recall-report-v2 adds, after generated_at: kind, extra_rules, credential, scope, sensor_floor, acknowledged_effect, server_chain, revoked, not_targeted, appeared_rows, use_status, claim, detection. A row adds through, checked, committed, kid, evaluator, exposures, exposures_more, possible_use, possible_use_more, unprovable.

Rules:

A verifier given the bundle a recall report rests on can go further and recompute each row from the device's chain. That check is part of antler-verify --recall and is outside this version of the specification: a report that passes the rules above is consistent with itself and with the log, and says what the server found.

The credential report

Format antler-credential-report-v1. Members, in order:

MemberTypeMeaning
format, version, prev, content_sha256As above
workspacestringThe workspace
kidstringThe id of its current redaction key
scope{from, to, filters}The UTC days covered and the ledger filters, by name
generated_atstringAs above
rowslistOne row per credential (below)
totalsobjectComputed from the rows (below)
detection, notes, exclusionslists of stringsThe fixed sentences
checkpoint, proofsAs in a coverage report

A row, in order: kid, tag, external_id, possibly_merged, type, kind, id_hash, label, inventory, first, last (each {device_id, seq, hash, ts}), touches (a map from how the credential was touched to a count), agents, devices, people, accounts (a map from account type to a count), dests, after_untrusted, model_context, recall ({id, status}).

Rules: