{"slug":"oip-spec","title":"The OIP specification — and the proof it is a protocol","body":"## What makes something a protocol\n\nA protocol is three things. One: defined message formats — every party knows the exact shape of every message. Two: invariants — rules that always hold, no matter who is calling. Three: a conformance test — a way to check that an implementation follows the rules.\n\nOIP (Object Invocation Protocol) has all three. The third one runs live. You do not have to take anyone's word for it.\n\n## Run the proof yourself\n\n```\ncurl 'https://miscsubjects.com/api/dispatch?conformance=1&format=markdown'\n```\n\nThat command executes all 14 clauses of this specification against the production build — real invocations, real receipts, real denials — and returns PASS or FAIL per clause. If the verdict says CONFORMANT, this is a protocol by the same standard HTTP and MCP are protocols. If a clause fails, the output names exactly which one.\n\n## The message formats\n\nInvoke an object (two equivalent forms):\n\n```\nPOST https://miscsubjects.com/api/dispatch\n{\"key\": \"NOW\", \"body\": \"\"}\n\nGET https://miscsubjects.com/api/dispatch?invoke=NOW&body=&share=<TOKEN>\n```\n\nEvery invocation returns the OIP envelope. The important fields:\n\n```json\n{\n  \"result\": \"...\",\n  \"ran\": true,\n  \"invocation\": {\n    \"invocation_id\": \"inv_abc123\",\n    \"object_id\": \"NOW\",\n    \"links\": { \"receipt\": \"https://miscsubjects.com/api/dispatch?receipt=inv_abc123\" }\n  },\n  \"proof\": {\n    \"ok\": true,\n    \"confirm\": \"https://miscsubjects.com/api/dispatch?confirm=inv_abc123\",\n    \"say_to_user\": \"\\u2713 Done via NOW. Proof: ...\"\n  }\n}\n```\n\n## The 14 conformance clauses\n\nC1 Self-describing manifest — `GET /api/dispatch` returns version + endpoint map.\nC2 Object self-description — `?key=KEY` returns the object's full contract.\nC3 Plain-language discovery — `?ask=plain words` returns the best object with a runnable call.\nC4 Invocation envelope — every call returns invocation_id + receipt link + honest proof.ok.\nC5 Receipt forensics — `?receipt=inv_ID` returns full request, full response, and a story line.\nC6 Replay — `POST {replay:inv_ID}` re-runs the recorded call, linked via replay_of.\nC7 Repair lineage — a failed call is repairable; both receipts link to each other. Failures are annotated, never deleted.\nC8 Fail closed — unknown objects return ran:false with nearest-key suggestions, never a 200 that reads as success.\nC9 Append-only ledger — every invocation lands in the ledger with request, response, actor, trace.\nC10 Idempotency — an identical call inside the dedup window returns the original receipt and performs no second execution.\nC11 Capability scoping — a row-scoped token fires its one object and is denied everywhere else.\nC12 Public documentation plane — docs need zero credentials; actions always need scoped ones.\nC13 Clarity recursion — the docs test themselves: models score every article, failures get machine revisions, gaps become new machine-written articles.\nC14 Human/machine duality — every article is one object with two synchronized faces: a human page and a machine bundle.\n\n## Why this ends the argument\n\n\"Is this a protocol?\" resolves as a test with a URL. Any model or person runs one curl and reads the verdict. A dissent names the failing clause.\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:16 · model `gemini/gemini-2.5-flash` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 7/10\n- 2026-07-03 02:15 · 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 MCP comparison; OIP security measures; Error handling and debugging\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-spec"},"register":"oip_protocol","status":"published","revisions":0,"contributions":[],"provenance":[{"action":"generate","model":"system/oip_articles","ts":"2026-07-03T00:21:14-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:21:14-07:00"}