{"slug":"oip-invocation-lifecycle","title":"OIP Invocation Lifecycle and ID Generation","body":"The OIP (Object Invocation Protocol) invocation lifecycle defines the sequence of object invocation, ledger recording, receipt generation, and replay for repair. The invocation ID is a unique, immutable identifier generated upon successful invocation. The OIP unit is the work object. The OIP proof is the receipt. The OIP loop is object, invoke, ledger, receipt, replay, repair.\n\n## OIP Invocation Definition\nAn 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.\n\n## Invocation Route and ID Generation\nAn 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.\n\n### Invocation Route\n`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.\n\n### Invocation ID Return\nThe `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.\n\n## Ledger Recording\nEvery 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.\n\n## Receipt Proof\nThe 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.\n\n## End-to-End Invocation Example\nThis example demonstrates invoking an OIP object and retrieving its `inv_ID` and subsequent receipt.\n\n### Step 1: Invoke an OIP Object\n```bash\ncurl -X POST https://miscsubjects.com/api/dispatch \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"key\": \"example-object-key\", \"body\": {\"action\": \"create\", \"data\": \"test-payload\"}}'\n```\n\n### Step 2: Receive Invocation ID\nThe immediate response from the invocation includes the `inv_ID`. A conformant response structure includes the `inv_ID` at the top level.\n\n```json\n{\n  \"inv_ID\": \"inv_01HXXXXXXX\",\n  \"status\": \"accepted\",\n  \"message\": \"Invocation accepted and recorded.\"\n}\n```\n\n### Step 3: Retrieve the Invocation Receipt\nUsing the `inv_ID` obtained from the initial invocation, the full receipt is retrieved.\n\n```bash\ncurl \"https://miscsubjects.com/api/dispatch?receipt=inv_01HXXXXXXX\"\n```\n\n### Step 4: Receipt Content\nThe receipt confirms the invocation details.\n\n```json\n{\n  \"inv_ID\": \"inv_01HXXXXXXX\",\n  \"timestamp\": \"2023-10-27T10:00:00Z\",\n  \"object_key\": \"example-object-key\",\n  \"invocation_body\": {\"action\": \"create\", \"data\": \"test-payload\"},\n  \"ledger_entry_hash\": \"sha256-hash-of-ledger-entry\",\n  \"status\": \"completed\",\n  \"result\": {\"operation\": \"success\", \"details\": \"Object processed payload.\"}\n}\n```\n\n## Receipt Rule\nA 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.\n\n## Conformance Rule\nAn 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.","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"}}