OIP Invocation Lifecycle and ID Generation

OIP Invocation Definition

An OIP invocation is the act of requesting an OIP work object to perform its defined operation. The invocation initiates a transaction within the OIP system. An API (Application Programming Interface) provides programmatic access to OIP functions. A CLI (Command Line Interface) provides text-based interaction with OIP functions. REST (Representational State Transfer) defines an architectural style for networked applications, which OIP adheres to for its API. JSON (JavaScript Object Notation) is the data interchange format for OIP invocations and receipts. A URL (Uniform Resource Locator) identifies the network location of OIP resources.

Invocation Route and ID Generation

An OIP invocation occurs via the /api/dispatch route. This route accepts invocation requests and processes them. Upon successful processing of an invocation, the /api/dispatch route generates a unique invocation ID (inv_ID). The inv_ID is a string that uniquely identifies the specific invocation event within the OIP ledger. This inv_ID is returned immediately in the HTTP response body of the initial invocation request.

Invocation Route

POST /api/dispatch {key, body} invokes an object. The key identifies the target OIP work object. The body contains the parameters for the object's operation. Alternatively, GET /api/dispatch?invoke=KEY&body=... invokes an object, where KEY is the object identifier and body contains URL-encoded parameters.

Invocation ID Return

The inv_ID is returned as part of the initial response to the invocation request. This immediate return enables the invoking client to track the specific invocation. The response body includes the inv_ID for subsequent receipt retrieval.

Ledger Recording

Every invocation successfully processed by the /api/dispatch route appends a record to the OIP ledger. The ledger record is indexed by the generated inv_ID. This ledger provides an immutable, auditable history of all OIP invocations. The ledger record contains the invocation request details, the inv_ID, and the timestamp of the invocation.

Receipt Proof

The OIP receipt is the proof of an invocation. The receipt is a structured JSON document that confirms the invocation, its parameters, and its inv_ID. A receipt is retrievable using the inv_ID via the /api/dispatch?receipt=inv_ID route. The receipt confirms the successful recording of the invocation in the ledger.

End-to-End Invocation Example

This example demonstrates invoking an OIP object and retrieving its inv_ID and subsequent receipt.

Step 1: Invoke an OIP Object

curl -X POST https://miscsubjects.com/api/dispatch \
  -H "Content-Type: application/json" \
  -d '{"key": "example-object-key", "body": {"action": "create", "data": "test-payload"}}'

Step 2: Receive Invocation ID

The immediate response from the invocation includes the inv_ID. A conformant response structure includes the inv_ID at the top level.

{
  "inv_ID": "inv_01HXXXXXXX",
  "status": "accepted",
  "message": "Invocation accepted and recorded."
}

Step 3: Retrieve the Invocation Receipt

Using the inv_ID obtained from the initial invocation, the full receipt is retrieved.

curl "https://miscsubjects.com/api/dispatch?receipt=inv_01HXXXXXXX"

Step 4: Receipt Content

The receipt confirms the invocation details.

{
  "inv_ID": "inv_01HXXXXXXX",
  "timestamp": "2023-10-27T10:00:00Z",
  "object_key": "example-object-key",
  "invocation_body": {"action": "create", "data": "test-payload"},
  "ledger_entry_hash": "sha256-hash-of-ledger-entry",
  "status": "completed",
  "result": {"operation": "success", "details": "Object processed payload."}
}

Receipt Rule

A valid OIP invocation receipt is a JSON object containing the inv_ID field, the timestamp of the invocation, the object_key of the invoked object, the invocation_body as submitted, and a ledger_entry_hash proving its record in the ledger. The receipt also includes the status and result of the invocation. The receipt is immutable after generation.

Conformance Rule

An OIP implementation conforms to the invocation lifecycle specification if it generates a unique inv_ID for every successful invocation via /api/dispatch, returns this inv_ID in the immediate response, records the invocation in an immutable ledger indexed by the inv_ID, and provides a mechanism to retrieve a complete receipt for any inv_ID via /api/dispatch?receipt=inv_ID. The Model Context Protocol (MCP) defines how a model connects to a server that exposes tools, resources, and prompts over a session; an MCP session may initiate OIP invocations, where OIP handles the specific object invocation and ledgering, and MCP manages the session context.