OIP (Object Invocation Protocol) Specification

OIP Overview

OIP defines a protocol for invoking discrete work objects. A work object performs a specific task. OIP provides a standardized mechanism for interaction with server-side capabilities. OIP ensures transparency and verifiability for every operation. The OIP unit is the work object. The OIP proof is the receipt. The OIP loop is object, invoke, ledger, receipt, replay, repair.

Protocol Foundations

OIP defines message formats. Every party knows the exact shape of every message. OIP maintains invariants. Rules always hold, regardless of the invoking party. OIP provides a conformance test. The conformance test verifies implementation adherence to OIP rules.

OIP Invocation and Proof

An invocation triggers a work object. POST /api/dispatch {key, body} invokes an object. GET /api/dispatch?invoke=KEY&body=... also invokes an object. Every invocation appends to the ledger. Every invocation returns a receipt. The receipt proves the invocation. The /api/dispatch?receipt=inv_ID route retrieves a receipt.

Run the Conformance Proof

OIP conformance is verifiable. The GET /api/dispatch?conformance=1&format=markdown route executes all 14 clauses of this specification. The execution involves real invocations, real receipts, and real denials. The route returns PASS or FAIL per clause. A CONFORMANT verdict establishes OIP as a protocol, comparable to HTTP or MCP (Model Context Protocol). A failing clause identifies the specific non-conformant behavior.

curl 'https://miscsubjects.com/api/dispatch?conformance=1&format=markdown'

OIP Message Formats

Invocation Request

An OIP invocation request specifies the target object and its parameters. The key identifies the work object. The body provides invocation parameters.

POST https://miscsubjects.com/api/dispatch
Content-Type: application/json

{
  "key": "NOW",
  "body": ""
}

GET https://miscsubjects.com/api/dispatch?invoke=NOW&body=&share=<TOKEN>

Invocation Receipt

Every invocation returns an OIP envelope. The envelope contains the result, invocation details, and proof status. The invocation_id uniquely identifies the invocation. The links.receipt provides the URL for the full receipt. The proof.ok status indicates successful execution.

{
  "result": "The current time is 2023-10-27T10:00:00Z.",
  "ran": true,
  "invocation": {
    "invocation_id": "inv_abc123",
    "object_id": "NOW",
    "links": {
      "receipt": {
        "href": "https://miscsubjects.com/api/dispatch?receipt=inv_abc123",
        "title": "View full invocation receipt"
      }
    }
  },
  "proof": {
    "ok": true,
    "confirm": {
      "href": "https://miscsubjects.com/api/dispatch?confirm=inv_abc123",
      "title": "Confirm invocation proof"
    },
    "say_to_user": "✓ Done via NOW. Proof: inv_abc123"
  }
}

End-to-End Example

This example demonstrates invoking the NOW object and retrieving its receipt.

1. Invoke the NOW object:

`bash curl -X POST 'https://miscsubjects.com/api/dispatch' \ -H 'Content-Type: application/json' \ -d '{"key": "NOW", "body": ""}' ` This command returns an OIP envelope including an invocation_id, for example, inv_def456.

1. Retrieve the receipt:

`bash curl 'https://miscsubjects.com/api/dispatch?receipt=inv_def456' ` This command returns the full request, response, and execution trace for inv_def456.

Receipt Rule

An OIP receipt provides an immutable record of an invocation. The receipt includes the full request, the full response, the actor, and the execution trace. The /api/dispatch?receipt=inv_ID route retrieves a receipt. A receipt serves as verifiable evidence of an object's execution.

Conformance Rule

OIP conformance is verifiable. The GET /api/dispatch?conformance=1 route executes all specification clauses. A PASS verdict indicates conformance. A FAIL verdict identifies the non-conformant clause. This mechanism provides a live, objective assessment of OIP implementation adherence.

OIP Security Measures

OIP implements capability scoping. A capability token grants permission for specific object invocations. OIP enforces public documentation. Public documentation requires zero credentials. Object invocation always requires a scoped capability token. This separation ensures secure access control. The share=<TOKEN> parameter in GET invocations demonstrates token usage. An API (Application Programming Interface) key or CLI (Command Line Interface) token provides the necessary authorization for POST invocations.

OIP Error Handling and Debugging

OIP provides repair lineage. A failed invocation generates a receipt. The receipt includes diagnostic information. A subsequent repair invocation links to the original failed invocation via replay_of. OIP implements fail-closed behavior. An unknown object invocation returns ran:false. The response includes nearest-key suggestions. This prevents ambiguous success states. Failures are annotated, never deleted, ensuring a complete audit trail.

OIP and MCP Comparison

OIP provides the invocation mechanism for work objects. MCP (Model Context Protocol) establishes a session between a model and a server. An MCP session exposes tools, resources, and prompts. OIP enables the invocation of these tools and resources within an MCP session. OIP focuses on discrete object execution. MCP focuses on contextual interaction. OIP provides the underlying execution primitive for tools utilized by an MCP agent.

The 14 Conformance Clauses

C1. Self-describing manifest: OIP defines a self-describing manifest. The GET /api/dispatch route returns the OIP version and an endpoint map. This mechanism enables API discovery. C2. Object self-description: OIP specifies object self-description. The GET /api/dispatch?key=KEY route returns the object's full contract. This contract defines the object's capabilities and parameters. C3. Plain-language discovery: OIP supports plain-language discovery. The GET /api/dispatch?ask=plain words route returns the best object with a runnable call. This mechanism facilitates human-readable object identification. C4. Invocation envelope: OIP specifies an invocation envelope. Every call returns an invocation_id, a receipt link, and an ok:true proof status for successful execution. This provides immediate feedback and traceability. C5. Receipt forensics: OIP provides receipt forensics. The GET /api/dispatch?receipt=inv_ID route returns the full request, full response, and a story line for the invocation. This enables detailed post-hoc analysis. C6. Replay: OIP supports replay. A POST {replay:inv_ID} invocation re-runs the recorded call. The new invocation links to the original via replay_of. This mechanism facilitates re-execution and verification. C7. Repair lineage: OIP provides repair lineage. A failed call is repairable. Both the original and repair receipts link to each other. Failures are annotated, never deleted. This ensures a complete audit trail for problem resolution. C8. Fail closed: OIP implements fail-closed behavior. Unknown objects return ran:false with nearest-key suggestions. The system never returns a 200 OK status that indicates success for an unknown object. This prevents ambiguous or incorrect execution. C9. Append-only ledger: OIP maintains an append-only ledger. Every invocation lands in the ledger with its request, response, actor, and trace. This ensures immutability and a complete history of operations. C10. Idempotency: OIP ensures idempotency. An identical call inside the dedup window returns the original receipt. The system performs no second execution. This prevents redundant operations. C11. Capability scoping: OIP implements capability scoping. A row-scoped token fires its one permitted object. The system denies access everywhere else. This enforces fine-grained access control. C12. Public documentation plane: OIP defines a public documentation plane. Documentation requires zero credentials. Actions always require scoped credentials. This separates information access from execution privileges. C13. Clarity recursion: OIP implements clarity recursion. Models score every article via /api/articles. Failures trigger machine revisions. Gaps become new machine-written articles. This ensures continuous documentation improvement. C14. Human/machine duality: OIP specifies human/machine duality. Every article is one object with two synchronized faces: a human-readable page at /a/<slug> and a machine-readable JSON bundle via /api/articles?slug=<slug>. This supports diverse consumption methods.

Latest clarity reviews (live)

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

• 2026-07-03 02:16 · model gemini/gemini-2.5-flash · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 7/10
• 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

- gaps named: Detailed MCP comparison; OIP security measures; Error handling and debugging

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