Local development protocol

Status: Development. This page describes request shapes in the local facade source at the paused checkpoint of 19 September 2026. The whole-project build failed in that facade at this checkpoint. These are development examples, not a verified runnable or production API.

Scope of the interface

The facade identifies itself as rural-development/0 and uses JSON-RPC-style request/response envelopes. It is separate from the intended MCP interface. Its caller supplies a trusted local administrator context; it is not an unauthenticated public service.

Request identity, branch identity, expected head and current version context are explicit. Large counters are represented as decimal strings in the interface direction so clients need not round them through a binary floating-point number.

Inspect status

Illustrative development request:

{"jsonrpc":"2.0","id":1,"method":"status","params":{}}

The source intends to return store identity, sequence, current authorization/catalog versions, branch/receipt counts and recovery status. A status value should describe the actual open store; it must not substitute for authenticating the caller.

Express a mutation

This example illustrates a new task in main branch 1, assuming its expected head is 0 and current versions are both 1:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "transact",
  "params": {
    "request_id": "00000000000000000000000000000001",
    "authorization_epoch": "1",
    "catalog_version": "1",
    "branch_id": "1",
    "expected_head": "0",
    "mutations": [
      {"create": {"key": "task:review", "value": {"title": "Review launch", "status": "open"}}}
    ]
  }
}

Use a stable request identity for retries of the same intent. Do not copy the sample identity into unrelated operations. A changed branch head or stale current context can reject a new request; a verified matching retry returns its historical receipt.

Read in an explicit world

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "get",
  "params": {
    "branch_id": "1",
    "authorization_epoch": "1",
    "catalog_version": "1",
    "key": "task:review"
  }
}

The developing facade also contains bounded scan and branch operations. A scan continuation needs its expected snapshot head; continuing over silently changed data is not an acceptable pagination contract.

What this page does not freeze

Method coverage, transport startup, exact error mapping, schema enforcement and the complete client lifecycle remain under development. Examples have not been accepted as end-to-end executable requests in the current checkout.

Consult development setup for the current build limitation, and Oracle and MCP for the separate AI-facing direction.