Public DocsSDK receipt format · telos/0.1-unsigned
The receipt format, as the SDK makes it.
The telos-receipt SDK writes one receipt per recorded action, with an integrity hash over its payload. This page documents that format, telos/0.1-unsigned, as the published telos-receipt 0.1.1 package produces it. The receipt states its own integrity mode.
Signing: the signatures are in the Record of Trust. Root signed commissioning rows 13 and 15. Row 15 enrolls the TELOS Witness key, and that key signed rows 16 to 19. Row 18 names the purpose file by its hash, and the file’s own header still reads draft. The public checker verifies these offline. Commissioning rows 4 and 5 and code row 1 have no defined signed message and report NOT VERIFIED. A signature ties the signed data to a key. Receipts in this SDK format carry an integrity hash.
The receipt object
The fields. Anything outside payload is metadata and left out of the hash on purpose, so the same payload always gives the same hash.
Scroll horizontally to read all columns.
| Field | Type | What it records |
|---|---|---|
| receipt_version | "telos/0.1-unsigned" | Which format made this receipt: the SDK’s integrity-hash format. |
| kind | string | The record type. action_governed is one recorded action. Other kinds use the same format. |
| agent_id | string | Which agent did the work. A label your team assigns. |
| payload | object | The hashed part. It must be plain, finite JSON. Values with no canonical JSON form are refused when the receipt is made. |
| payload.action_name | string | The action the agent took. |
| payload.action_params_hash | "sha256:<hex>" | SHA-256 of the canonical action arguments. The raw arguments are left out. If the arguments are predictable, assume their hash can reveal them. |
| payload.verdict | enum | The result, from the verdict list below. |
| payload.composite_score | number | Overall score of the action against its purpose. We publish the method. |
| payload.scores | object | The individual scores behind the overall one. |
| payload.pa_id | string | The purpose the deployer set, which the action was checked against. |
| issued_at | iso8601 | When the receipt was made. Not hashed. |
| integrity_hash | "sha256:<hex>" | SHA-256 over the canonical JSON of payload, no key needed. Anyone can recompute it offline. |
| covered_fields | string | Says exactly what the hash covers. |
| signing_status | "unsigned_integrity_hash" | The receipt names its own integrity mode, so no one mistakes the hash for a signature. |
| signature | null | Null in this version. The field is reserved for a signature. |
| engine | string | Which engine made the payload. The v0.1 default label says no engine is connected. |
The verdict vocabulary
The verdicts are public.
For receipt version telos/0.1-unsigned, payload.verdict permits EXECUTE, CLARIFY, SUGGEST, ESCALATE and INERT. These are recorded schema labels, and what they mean comes from the versioned contract of the runtime that emitted them.
A real receipt
Sample action in the SDK format, fixed timestamp, reproducible payload hash. The raw artifact is at sample-receipt.json.
{
"receipt_version": "telos/0.1-unsigned",
"kind": "action_governed",
"agent_id": "demo-agent",
"payload": {
"action_name": "send_customer_email",
"action_params_hash": "sha256:0dabfdde7ab240266e7798c834c13ada37921438e2bbcc3140d6845185ebc29d",
"verdict": "EXECUTE",
"composite_score": 0.92,
"scores": {
"purpose_alignment": 0.94,
"scope_discipline": 0.91,
"risk_review": 0.9
},
"pa_id": "pa::demo::v1"
},
"issued_at": "2026-07-01T12:00:00+00:00",
"integrity_hash": "sha256:5c4eb662d34f9e0a142e138c0697fd6923e630277794b2059845dae5c965217a",
"covered_fields": "payload (canonical JSON, sort_keys, compact separators)",
"signing_status": "unsigned_integrity_hash",
"signature": null,
"engine": "telos v0.1 (unsigned integrity-hash; no governance engine wired)"
}
Canonicalization & verification
The canonical form is Python’s json.dumps(payload, sort_keys=True, separators=(",", ":")) with default ASCII escaping: keys sorted, no insignificant whitespace, non-ASCII characters escaped as \uXXXX. Same payload in, same hash out, on any machine. Values with no canonical JSON form (non-finite floats, non-JSON types, circular references) are refused when the receipt is made.
- Read the receipt’s payload and its integrity_hash.
- Recompute SHA-256 over the canonical JSON bytes of payload.
- Compare. A match means the payload matches the supplied hash. A mismatch means they disagree.
The signing_status field names the format’s integrity mode. Signed evidence is in the Record of Trust. A verified signature ties the covered bytes to a signing key. Developers can run the open verifier against their own receipts.
For agents
Check a receipt against the JSON Schema before you rely on it, and read its signing_status instead of assuming.