{"slug":"oip-receipt-loop","title":"What is the receipt loop?","body":"The OIP (Object Invocation Protocol) receipt loop is the fundamental mechanism for ensuring work object execution, proof, and recovery. The receipt loop comprises the sequence: object, invoke, ledger, receipt, replay, and repair. This loop guarantees the integrity and verifiability of all operations within an OIP system. The OIP unit is the work object, and the OIP proof is the receipt.\n\n## The OIP Receipt Loop Defines Object Invocation Integrity\n\nThe OIP receipt loop is a sequence of operations that ensures the reliable execution and verifiable state of work objects. The loop defines the lifecycle of an invocation, from its initiation to its potential correction. This mechanism provides an auditable trail for every action performed on an OIP system, ensuring transparency and accountability. The OIP loop is object, invoke, ledger, receipt, replay, repair.\n\n## Object: The Unit of Work\n\nAn OIP work object is a self-contained unit of data and associated capabilities that defines a specific task or resource. An object is defined by its schema and key, which dictates its structure and behavior. The object is the subject of an invocation. The `/a/oip-object-model` article defines the OIP object model.\n\n## Invoke: Initiating Object Execution\n\nInvocation is the act of requesting an OIP work object to perform one of its defined capabilities. An invocation transmits a `key` identifying the object and a `body` containing the parameters for the desired operation. An invocation is performed via an API (Application Programming Interface) call or a CLI (Command Line Interface) command. A `POST /api/dispatch {key, body}` request invokes an object. A `GET /api/dispatch?invoke=KEY&body=...` request also invokes an object. The invocation uses a URL (Uniform Resource Locator) to specify the dispatch endpoint. The invocation body is typically formatted as JSON (JavaScript Object Notation), a standard for data interchange.\n\n## Ledger: The Immutable Record\n\nThe ledger is an immutable, append-only record of all OIP invocations. Every invocation appends an entry to the ledger, documenting the object invoked, the parameters provided, and the timestamp of the operation. The ledger provides a chronological and tamper-evident history of all system activity. The `/a/oip-ledger-receipts` article details ledger operations.\n\n## Receipt: The Proof of Invocation\n\nA receipt is a cryptographic proof of an OIP invocation's successful recording in the ledger and its outcome. Upon successful invocation, the OIP system returns a receipt containing a unique `inv_ID` (invocation identifier) and details of the operation. The receipt is retrieved at `/api/dispatch?receipt=inv_ID`. The receipt confirms that the invocation has been processed and recorded. The `/a/oip-ledger-receipts` article defines OIP receipts.\n\n## Replay: Verifying and Reproducing Operations\n\nReplay is the mechanism by which an OIP system or an external observer can re-execute a past invocation using its receipt and the ledger record. Replay verifies the integrity of the original operation and confirms that the system's state is consistent with its recorded history. A replay operation uses the invocation details from a receipt to reconstruct and re-run the object's capability. The Model Context Protocol (MCP) defines how a model connects to a server that exposes tools, resources, and prompts over a session, enabling deterministic replay within a defined context.\n\n## Repair: Correcting Divergence\n\nRepair is the process of identifying and correcting discrepancies or divergences detected during replay. If a replay operation reveals that the current system state or object output differs from the expected outcome recorded in the receipt or implied by the ledger, repair actions are initiated. Repair ensures that the OIP system maintains a consistent and correct state, aligning with the verifiable history provided by the ledger and receipts.\n\n## End-to-End Example: Creating an Article Object\n\nThis example demonstrates the OIP receipt loop for creating an article on miscsubjects.com.\n\n1.  **Object:** An article object, defined by its schema for content and metadata, is the target for creation. The article object is a work object.\n2.  **Invoke:** A user sends a `POST` request to `/api/dispatch` with the article object's `key` and `body` containing the article's title and content. This invocation initiates the article creation.\n    ```bash\n    curl -X POST https://miscsubjects.com/api/dispatch \\\n      -H \"Content-Type: application/json\" \\\n      -d '{\"key\":\"article.create\",\"body\":{\"title\":\"My New Article\",\"content\":\"This is the content of my new article.\"}}'\n    ```\n3.  **Ledger:** The OIP system records this invocation in the ledger, noting the `article.create` key, the provided body, and a timestamp. This entry is immutable.\n4.  **Receipt:** The system returns a receipt, for example: `{\"inv_ID\":\"inv_01HGDXN0YJ2K0P4Q5R6S7T8U9V\"}`. This receipt proves the invocation was recorded. The user can retrieve the full receipt with `GET /api/dispatch?receipt=inv_01HGDXN0YJ2K0P4Q5R6S7T8U9V`.\n5.  **Replay:** To verify the article's creation, an OIP client can use the `inv_ID` from the receipt to query the ledger and potentially re-execute the `article.create` operation in a test environment. This replay confirms the original invocation's parameters and expected outcome, such as the article appearing at `/a/my-new-article`.\n6.  **Repair:** If the replay reveals that the article was not created as expected (e.g., it's missing from `/a/my-new-article` or its content is incorrect), repair actions are initiated. These actions might involve re-invoking the `article.create` object with corrected parameters or investigating system logs for errors, guided by the ledger and receipt.\n\n## Receipt Rule: Invocation ID Uniqueness\n\nEach successful OIP invocation generates a unique `inv_ID` (invocation identifier) within its returned receipt. The receipt at `/api/dispatch?receipt=inv_ID` confirms the unique identifier, which serves as a permanent reference to that specific ledger entry and operation. This uniqueness ensures that every invocation is individually verifiable and traceable.\n\n## Conformance Rule: Deterministic Replay\n\nA conformant OIP implementation, when performing a replay of an invocation using its receipt and the ledger record, produces an identical output or state change as the original invocation, given identical initial conditions. This conformance is proven by comparing the outputs or state changes between the original and replayed invocations, ensuring bit-for-bit equivalence or functional identity in the resulting system state.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","dynamic"],"style":{"accent":"#16324f","measure":860},"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"}],"prov":{"model":"system/oip_articles","action":"generate"}}