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
- 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.
- Decode the payload strictly by its
format. An unknown format is invalid. - Apply the format's rules (below): totals recomputed from rows, fixed sentences compared word for word, the content hash recomputed.
- When the report has a
checkpoint, verify the note (log.md) and check every proof inproofsagainst its root; proofs without a checkpoint are invalid. - Every record the report cites must have a proof in
proofs(byrecord_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:
| Member | Meaning |
|---|---|
version | 1 for the first issue, one more for each re-issue |
prev | The SHA-256 of the previous version's signed payload; absent on version 1 |
content_sha256 | The content hash |
generated_at | When 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:
versionset to0;prevremoved, with its comma;content_sha256set to"";generated_atset to"";checkpointset to"";proofsset tonull.
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:
exclusions_v1andexclusions: what is not covered. A report'sexclusionsmust hold every sentence of one list its format may quote:exclusions_v1forantler-coverage-report-v1;exclusionsforantler-coverage-report-v2andantler-coverage-report-v3; either for a recall or credential report. Theexclusionslist is the signing release's (see the README's known limits).levels: the four levels of coverage and the sentence that defines each.credential_report_detection,credential_report_notes: the texts a credential report quotes, in order.recall: by kind, the claim and the detection lines a recall report of the second format quotes.second_source,hook_miss_sentence: the texts a coverage report of the third format quotes (below).
The coverage report
Formats antler-coverage-report-v1, antler-coverage-report-v2 and antler-coverage-report-v3. Members, in order:
| Member | Type | Meaning |
|---|---|---|
format, version, prev, content_sha256 | As above | |
scope | {kind, id} | What is covered: an organization, team, person, device or agent |
from, to | string | The first and last UTC day covered |
provisional | boolean | Whether the window holds days not yet settled |
generated_at | string | As above |
sessions | list | One row per session (below) |
person_days | list | One row per person, vendor and day of vendor reconciliation (below) |
declared_gaps | list | {device_id, seq, reason, record_hash, count}: each declared gap, naming its record |
exclusions | list of strings | The fixed sentences |
checkpoint | string | A signed checkpoint note |
proofs | list | Inclusion proofs in that checkpoint |
totals | object | Computed from the rows (below) |
levels, level_counts, unrecorded_agents, ratios | Second and third formats (below) | |
second_source, hook_misses | Third 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:
- In every person-day row,
unrecorded_sessionsismax(0, vendor_sessions - recorded_sessions)andunrecorded_edit_writeismax(0, vendor_edit_write - recorded_edit_write). totalsis recomputed:sessionsis the number of session rows;completeandpartialcount rows bystatus,unknownthe rest;transcript_tool_usesandhooked_tool_usesare the rows' sums;statesis the sum of the rows' maps (a state with count 0 is the same as an absent one);vendor_sessions,recorded_sessions,unrecorded_sessions,vendor_edit_write,recorded_edit_writeandunrecorded_edit_writeare the person-day rows' sums;declared_gapsis the number of gap rows.- The exclusions rule above.
- A report of the first format carries none of the second format's members, and a report of the first or second format none of the third format's,
agent_versionincluded. - The records cited are the
record_hashof each declared gap.
The second format
antler-coverage-report-v2 adds:
levels: a list of{product, surface, os, level, sentence}, the level each agent target reaches. Eachlevelis one of the four insentences.json,sentenceis that level's sentence word for word, and no (product, surface, os) appears twice. The list is not empty.level_counts:{rows, blind, enforced, recorded, detected, blind_total, unchecked_sessions}.rowsis a list of{product, surface, collector, level, account_type, records}withrecordsnot negative andlevelone of enforced, recorded or detected;blinda list of{reason, count}.enforced,recordedanddetectedare the sums ofrecordsover the rows of that level;blind_totalthe sum of the blind counts;unchecked_sessionsthe number of session rows whosereasonshold theunchecked_reasonofsentences.json.unrecorded_agents: a list of{product, detected_devices, hooks_installed_devices, recorded_devices, sentence}withdetected_devicesabove 0,recorded_devicesfrom 0 to belowdetected_devices,hooks_installed_devicesfrom 0 todetected_devices, andsentenceexactly<product>: detected on <N> devices, hooks installed on <H>, recorded on <R>(1 devicewhen N is 1).ratios:{named_records, records, named, people_reported, people_listed, people, devices_reported, devices_listed, devices, label}. Each ofnamed,peopleanddevicesis its part of its whole as a percentage with one decimal and a%sign, or thenot_availabletext ofsentences.jsonwhen the whole is 0; no part exceeds its whole;labelis thedirectory_labeltext.
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:
| Member | Type | Meaning |
|---|---|---|
feeds | list | {feed, product}: each connected vendor feed that lists sessions by id, and the agent whose sessions it lists |
sessions | list | One row per session (below) |
vendor_sessions | number | The sessions the vendor's record lists |
lines | list | {status, sessions, sentence}: the six counted lines |
not_comparable | list | {reason, sessions, sentence}: the not comparable line, by reason |
calls | object | {vendor, matched, unrecorded, unlisted, sentence}: the tool-call counts |
limits | list of strings | What 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:
status | A row has |
|---|---|
recorded_fully | feed, device_id, calls_compared true and unrecorded_calls 0 |
recorded_partly | feed, device_id, calls_compared true and unrecorded_calls above 0 |
session_matched | feed, device_id and calls_compared false |
not_recorded | feed, no device_id, matched_calls 0 and unlisted_calls 0 |
not_in_vendor_record | device_id, no feed and calls_compared false |
not_comparable | a reason of sentences.json, no feed and calls_compared false |
Rules:
- In every row no count is negative;
matched_callsplusunrecorded_callsisvendor_calls; withoutcalls_compared,vendor_callsandunlisted_callsare 0;unrecorded_call_idsholds at most 20 ids and no more thanunrecorded_calls;reasonis present fornot_comparableand for no other status. - No (
agent,session_id) appears twice, and a row'sfeedis one offeeds. linesholds the six statuses ofsecond_source.statusesinsentences.json, in that order, each with the number of rows of its status and its sentence word for word.vendor_sessionsis the sum of the first four lines.not_comparableholds, in the order ofsecond_source.not_comparableinsentences.json, each reason that has a row, with the number of its rows and its sentence word for word. A not comparable session is on no other line: it is never counted as matched.calls.vendor,calls.matched,calls.unrecordedandcalls.unlistedare the rows' sums, andcalls.sentenceissecond_source.callsword for word.limitsissecond_source.limits, word for word and in order. It says which sessions a vendor's record cannot hold.
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:
sessions: computed from the report's own session rows. There is one such row per (agent,agent_version) over the session rows that have anagentand are notlog_only:sessionsis their number,callsthe sum of theirtranscript_tool_uses, andmissedthe sum of theunhookedcount of theirstates. A verifier recomputes these rows and requires them to be equal.compatibility_run: a measurement of the vendor of this software on a pinned version of the agent, comparing hook records with the agent's own session files. A verifier cannot recompute it; it requiresagentandagent_versionto be present, no (agent,agent_version) twice, no negative count,missednot abovecalls, andrateas above.
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:
| Member | Type | Meaning |
|---|---|---|
format, version, prev, content_sha256 | As above | |
recall_id, creator, reason, created_at | string | The recall |
policy_version | integer | The policy version the recall was published in |
target_set_sha256 | string | The SHA-256 of the target device ids, sorted and joined by line feeds |
targets | list of strings | The frozen target devices |
rule | object | The recall's rule, as the policy carries it |
devices | list | One row per target device (below) |
appeared | list of strings | Devices 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} |
exclusions | list of strings | The fixed sentences |
checkpoint, proofs | As in a coverage report | |
device_status | string | partial, unproven or effective |
unproven | list of strings | The devices that make it unproven; optional |
uncertain | boolean | Optional |
generated_at | string | As above |
| second-format members | Below |
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:
- Every target has exactly one device row and no other device has one.
target_set_sha256is the hash oftargets.device_statusis partial when any row has a violation; otherwise unproven when any row has noack, withunprovenlisting those rows' devices in row order; otherwise effective, with nounproven.- The exclusions rule.
- It carries none of the second format's members.
- The records cited are, for every row,
ack,last_match_before,first_denied_afterand each violation's record.
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:
kindis credential, agent or tool.claimanddetectionare that kind's texts insentences.json, word for word.scopeis fleet or exposed. Only a credential recall may be exposed. A fleet recall has nonot_targeted.server_chain, a record reference to the record of the server's chain the device set was read at, is required.- Credential block. A credential recall has
credential:{kid, items, env_scope, types}with a valid redaction key id.itemshas one entry per entry ofrule.when.credential_in, in its order: for an entryid:<hash>, the item'sid_hashis that hash and it has no tag or external id; for a 32-hex tag, the item'stagis it, with no external id and not possibly merged; for a shorter tag, the item has no tag, a 24-hexexternal_idandpossibly_mergedtrue.typesare known credential types, sorted.env_scopeis true exactly whenextra_rulesis not empty, and each extra rule's id beginsrecall.and itswhen.credential_inequals the main rule's. Another kind of recall has nocredentialand noextra_rules. - Devices.
targetshas no repeat andtarget_set_sha256is its hash.revokedlists targets, without repeat. Every target not revoked has exactly one row; no revoked target and no other device has one.appearedis sorted, holds no target and no repeat, andappeared_rowshas one row per appeared device, in that order.not_targetedis sorted, without repeat, and holds no target or appeared device. - A row's status is partial with a violation; otherwise unproven without an
ackor with anyunprovablereason; otherwise effective. The row'sstatusmust be that. - A row's reach. A row with an
ackhas athroughwhoseseqis at least theack's. A row whosecommitted(the newest spool head the device committed to) is pastthrough.seqmust list the reasonnot_uploadedinunprovable. unprovableholds known reasons, without repeat, in this order:sensor_too_old,key_mismatch,hook_posture,ledger_off,issuer_call,not_uploaded,sensor_fault.exposuresis a list of{kind, record, session}withkindone ofoutput,env,unscanned,gap,env_unknown; at most 20 of each kind; sorted by kind in that order, then by the record'sseq.possible_useis a list of at most 50{kind, session, record, actions, env, host, detection}withkindenv_sessionorissuer_call,detectionnot_detectableandactionsat least 1. The_morecounts andcheckedare not negative. A violation'smatchis absent or one ofexact,short_tag,env_ref,env.- The report's status. Over the targets' rows and the appeared rows:
device_statusis partial when any row is partial; otherwise unproven when any row is unproven, withunproventhe sorted devices of those rows; otherwise effective.use_statusisdetectedwhen any row is partial; otherwisepossiblewhen any row has an exposure, a possible use or a_morecount above 0; otherwisenone_detected. - The exclusions rule.
- The records cited are those of the first format over the targets' and the appeared rows, and also each row's
through, each exposure's record, each possible use'srecordandenv, andserver_chain.
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:
| Member | Type | Meaning |
|---|---|---|
format, version, prev, content_sha256 | As above | |
workspace | string | The workspace |
kid | string | The id of its current redaction key |
scope | {from, to, filters} | The UTC days covered and the ledger filters, by name |
generated_at | string | As above |
rows | list | One row per credential (below) |
totals | object | Computed from the rows (below) |
detection, notes, exclusions | lists of strings | The fixed sentences |
checkpoint, proofs | As 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:
detectionandnotesequal the texts ofsentences.json, in order; the exclusions rule;kidis a valid redaction key id (16 lower-case hex digits).- Each row. A valid
kid; a known credentialtypeand akindof that type (the record reference lists both); exactly one oftagandexternal_id. Atagis 32 lower-case hex digits, only on a structured credential type, and notpossibly_merged. Anexternal_idis 24 lower-case hex digits and its row ispossibly_merged.id_hash, when present, is 64 lower-case hex digits.firstandlastare both present or both absent, each with a device and a 64-hex hash.devicesis not empty. Every key oftouchesis a known way and no count is negative; their sum is above 0, andafter_untrustedis from 0 to that sum. No text of the row (label,inventory,dests,agents,people) holds an inline token[REDACTED:<type>:<8 hex>]of a free-form credential type. No credential (kid, with its tag or external id) has two rows. - Totals, recomputed from the rows:
credentialsis the number of rows;touchesthe sum of every row's counts andby_viatheir sum by way (a way with count 0 is the same as an absent one);sentthe rows touched bysent;after_untrustedthe rows withafter_untrustedabove 0 anduntrusted_touchesthe sum of those;personal_or_unknownthe rows with a touch under a personal or unknown account;multi_devicethe rows with more than one device anddevicesthe distinct devices across rows;long_termandshort_livedthe rows of such kinds;in_model_contextthe rows touched byinput,sent,promptoroutput;recalledthe rows with arecall;possibly_mergedthe rows so marked. - Long-term and short-lived kinds. Short-lived: an AWS access key of kind
temporary; a GitHub token of kindapp_installation,user_apporoauth; an Anthropic key of kindoauth; a JWT that is signed. Long-term: an AWS access key of kindlong_term; a GitHub token of kindpatorfine_grained; a PEM private key; an Anthropic key of kindapioradmin; an OpenAI, Stripe, GitLab, npm, PyPI, Hugging Face or Google API key or a Slack webhook; a Slack token of kindbot,user,apporlegacy. - The records cited are each row's
firstandlast. Here a cited record without a proof makes the report invalid, not unproven: the format promises both. A row with neitherfirstnorlast(its touches' records are past retention) leaves the report unproven.