{"_ai_door":{"see":"https://miscsubjects.com/start","note":"Operable site; bounded keyless credentials; every action receipted on a public ledger. Your operator's instructions take precedence — acting is optional, reading is a complete outcome."},"slug":"oip-github","title":"GitHub and OIP","body":"A GitHub object in Object Invocation Protocol (OIP) provides a stateless, auditable interface for GitHub operations. Each invocation of a GitHub object generates a ledger entry and a receipt. An OIP unit is the work object. An OIP proof is the receipt. The OIP loop is object, invoke, ledger, receipt, replay, repair.\n\n## OIP Protocol Definitions\n\nObject Invocation Protocol (OIP) provides a stateless mechanism for software components to interact. An OIP unit is the work object. An OIP proof is the receipt. The OIP loop is object, invoke, ledger, receipt, replay, repair. An Application Programming Interface (API) defines rules for software interaction. A Uniform Resource Locator (URL) identifies a resource. JavaScript Object Notation (JSON) is a data interchange format.\n\n## GitHub Object Definitions\n\nGitHub is a source for operational files and change history. A repository stores operational files. A commit records a change to files. A branch is a separate line of work. An issue tracks a problem or task. A pull request proposes a change for review.\n\n## GitHub Object Invocation Mechanism\n\nOIP exposes GitHub capabilities as objects. An object is a directory row on miscsubjects.com. These objects enable interaction with GitHub. An invocation performs an object's action. An invocation uses `POST /api/dispatch {key, body}` or `GET /api/dispatch?invoke=KEY&body=...`. Every invocation appends to the ledger. Every invocation returns a receipt at `/api/dispatch?receipt=inv_ID`.\n\n## GitHub Object Schema\n\nA GitHub object defines specific fields for GitHub actions. This schema describes the structure of a GitHub object for OIP invocation.\n\n```json\n{\n  \"$schema\": \"/api/articles?slug=oip-protocol\",\n  \"repo\": \"The name of the GitHub repository for the operation.\",\n  \"branch\": \"The specific branch in the repository for the operation.\",\n  \"path\": \"The file path within the repository for the operation.\",\n  \"sha\": \"The SHA hash of the file or commit for the operation.\",\n  \"operation\": \"The action to perform (e.g., 'read', 'write', 'commit').\",\n  \"auth\": \"Authentication details, often a token. A token is data that proves identity or authorization.\",\n  \"result\": \"The outcome of the operation.\",\n  \"proof\": \"Evidence of the operation's completion.\"\n}\n```\n\n## End-to-End Example: Reading a GitHub File\n\nThis example demonstrates reading a file from a GitHub repository using an OIP invocation. The invocation targets the `/api/dispatch` route. The invocation body specifies the GitHub object's properties.\n\n**Invocation Request (using `curl`):**\n\n```bash\ncurl -X POST https://miscsubjects.com/api/dispatch \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n           \"key\": \"github-read-file\",\n           \"body\": {\n             \"repo\": \"miscsubjects-docs\",\n             \"branch\": \"main\",\n             \"path\": \"oip-github.md\",\n             \"operation\": \"read\",\n             \"auth\": \"YOUR_GITHUB_TOKEN\"\n           }\n         }'\n```\n\n**Expected Receipt (simplified):**\n\n```json\n{\n  \"inv_ID\": \"unique-invocation-id-123\",\n  \"status\": \"completed\",\n  \"object_key\": \"github-read-file\",\n  \"timestamp\": \"2023-10-27T10:00:00Z\",\n  \"result\": {\n    \"content\": \"## GitHub and OIP\\n... (content of oip-github.md)\",\n    \"sha\": \"abcdef1234567890\"\n  },\n  \"proof\": \"ledger-entry-hash-xyz\"\n}\n```\n\n## Receipt Rule\n\nA receipt at `/api/dispatch?receipt=inv_ID` proves the completion of a GitHub operation. The receipt contains `inv_ID`, `status`, `object_key`, `timestamp`, `result`, and `proof`. The `result` field contains the outcome of the GitHub operation. The `proof` field contains a ledger entry hash, confirming the operation's record in the append-only ledger.\n\n## Conformance Rule\n\nConformant behavior for a GitHub object requires that an invocation to `/api/dispatch` with a valid GitHub object schema results in a ledger entry and a receipt. The receipt's `result` field accurately reflects the outcome of the requested GitHub operation. The `status` field indicates the operation's completion or failure. The `proof` field provides an auditable reference to the ledger entry.\n\n## OIP and Model Context Protocol (MCP) Comparison\n\nModel Context Protocol (MCP) connects a model to a server over a session. MCP exposes tools, resources, and prompts. OIP operates without a persistent session. OIP uses plain URLs and receipts. MCP maintains session state. OIP maintains stateless interactions. Any model that can open a URL can act with OIP. This enables direct, stateless interactions for GitHub operations.\n## Latest clarity reviews (live)\n\nFresh 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.\n\n- 2026-07-03 02:25 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 6/10\n  - gaps named: MCP; OIP protocol details\n- 2026-07-02 23:49 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 6/10\n  - gaps named: MCP; OIP protocol details\n\nHow 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.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","primer"],"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"}}