What is the receipt loop?

The OIP Receipt Loop Defines Object Invocation Integrity

The 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.

Object: The Unit of Work

An 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.

Invoke: Initiating Object Execution

Invocation 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.

Ledger: The Immutable Record

The 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.

Receipt: The Proof of Invocation

A 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.

Replay: Verifying and Reproducing Operations

Replay 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.

Repair: Correcting Divergence

Repair 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.

End-to-End Example: Creating an Article Object

This example demonstrates the OIP receipt loop for creating an article on miscsubjects.com.

1. Object: An article object, defined by its schema for content and metadata, is the target for creation. The article object is a work object.
2. 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.

`bash curl -X POST https://miscsubjects.com/api/dispatch \ -H "Content-Type: application/json" \ -d '{"key":"article.create","body":{"title":"My New Article","content":"This is the content of my new article."}}' `

1. 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.
2. 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.
3. 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.
4. 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.

Receipt Rule: Invocation ID Uniqueness

Each 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.

Conformance Rule: Deterministic Replay

A 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.