{"slug":"oip-ledger-receipts","title":"Ledger, receipts, replay, repair","body":"## What the ledger is\n\nThe ledger is the build's permanent record of what happened. Append-only means rows are added and never edited or deleted. A mistake stays in place; a later row annotates it and points back at it. There are two ledger tables, both in D1 (Cloudflare's SQL database).\n\n## The events table — every payload, in and out\n\nOne row per thing that happened: an inbound text, an LLM call, a webhook, a deploy, a review. The columns that matter: `id`, `ts` (timestamp), `source`, `key` (which object), `actor` (who), `action`, `status`, `trace_id` (groups one conversation turn), `request_json` (the COMPLETE request sent, Authorization redacted), `response_json` (the COMPLETE raw response). Oversized payloads overflow to R2 file storage with `r2_request_key` / `r2_response_key` pointers — nothing is truncated away.\n\n## The invocations table — one row per object call\n\nEvery dispatch call lands here: `invocation_id` (inv_...), object key, actor fingerprint, input, result, cost, material yield, and lineage columns `replay_of`, `repairs`, `repaired_by`.\n\n## What a receipt actually looks like\n\n```\ncurl 'https://miscsubjects.com/api/dispatch?receipt=inv_ID&share=<TOKEN>'\n```\n\n```json\n{\n  \"story\": \"capability cap_95e5... (\\\"text Cyrus\\\"), minted ..., invoked SEND_BY_CHANNEL\n            with \\\"blooio|+1415...|Woof\\\" -> {status:202, message_id:ft7-...} at ...\",\n  \"asked\": \"blooio|+14155480666|Woof\",\n  \"request_full\": { \"...the exact payload sent to the provider...\" },\n  \"response_full\": { \"...the exact raw provider reply...\" },\n  \"authorized_by\": { \"fingerprint\": \"cap_...\", \"scope\": \"row:SEND_BY_CHANNEL\",\n                     \"expires_at\": \"...\", \"revoked\": false },\n  \"delivery\": { \"status\": \"delivered\", \"message_id\": \"ft7-...\" },\n  \"lineage\": { \"replay_of\": null, \"repairs\": null, \"repaired_by\": null },\n  \"verbs\": { \"replay\": \"POST {replay:inv_ID}\", \"repair\": \"POST {key,body,repairs:inv_ID}\" }\n}\n```\n\nThe `story` line is the one-sentence forensic narrative. `authorized_by` is token provenance — which capability acted, when it was minted, when it dies. Anyone can check the public one-liner without a token: `?confirm=inv_ID`.\n\n## Replay and repair\n\nReplay re-runs the recorded request exactly: `POST /api/dispatch {\"replay\":\"inv_ID\"}` — the new receipt carries `replay_of`. Repair runs a corrected call linked to the failure: `POST {\"key\":\"NOW\",\"body\":\"\",\"repairs\":\"inv_FAILED\"}` — and the FAILED receipt reads back `repaired_by` pointing at the fix. Both directions are written. History stays honest.\n\n## The audit rules chain\n\nOwner rules (identity, preferences, bans) live in a separate hash-chained append-only store: each entry hashes the previous one, so tampering breaks the chain. Verify it live: `curl https://miscsubjects.com/api/rules/verify`.\n\n## Read the ledgers yourself\n\n```\ncurl -H 'x-terminal-key: <KEY>' 'https://miscsubjects.com/api/invocations?limit=10'\ncurl -H 'x-terminal-key: <KEY>' 'https://miscsubjects.com/api/events/<EVENT_ID>'\n```\n## Latest clarity reviews (live)\n\nFresh models are sent this article's bundle and asked two separate questions: how clear is the machine JSON, and how clear is the English body. Scores are 0 to 10. The full history is in the append-only ledger.\n\n- 2026-07-03 02:24 · model `gemini/gemini-2.5-flash` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 5/10\n  - gaps named: Capability Tokens; Dispatch Mechanism; Source Ledger (distinct from events/invocations tables); Audit Rules Chain (detailed explanation)\n- 2026-07-03 02:23 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 7/10\n  - gaps named: Detailed explanation of MCP; Comparison of OIP with other protocols\n- 2026-07-02 23:23 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 8/10 · English 7/10 · zero-context human 6/10\n  - gaps named: Detailed explanation of MCP; Comparison of OIP with other protocols\n\nHow the loop self-corrects: a failing review queues a model revision of this article (a new append-only version). A missing concept named by a reviewer queues a brand-new machine-written article, which then enters the same review cycle.","hero":null,"images":[],"style":{"accent":"#16324f","measure":860},"tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","primer"],"model":null,"ledger":null,"embeds":[],"widgets":[{"type":"stat","value":1,"label":"OIP primer"},{"type":"note","title":"Zero-context rule","text":"A reader should understand the protocol unit, object contract, invocation route, receipt schema, and repair path from this page plus its machine bundle."},{"type":"note","title":"Machine-native rule","text":"The JSON is the executable map: object, routes, inputs, proof loop, ledger, and next article to open."}],"home":false,"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"reviews":[],"extra":{"oip_virtual":true,"oip_type":"primer","count":1,"metric":"OIP primer","primer":"oip-ledger-receipts"},"register":"oip_protocol","status":"published","revisions":0,"contributions":[],"provenance":[{"action":"generate","model":"system/oip_articles","ts":"2026-07-03T00:30:00-07:00","hash":"virtual-oip","tokens_in":0,"tokens_out":0}],"energy":{"passes":1,"tokens_in":0,"tokens_out":0,"tokens_total":0,"cost_usd":0,"models":{"system/oip_articles":1},"head":"virtual-oip"},"posted_at":"2026-07-02T00:00:00.000Z","created_at":"2026-07-02T00:00:00.000Z","updated_at":"2026-07-03T00:30:00-07:00"}