Yichus / Reference / API MCP tools
api_escrow_check
Run AdmissionSolver on a declared EscrowSpec (a State cell) or TableEscrowSpec (a table: one integer per row key, bounds read off another table's row). Pass batch JSON to admit/defer operations; a table spec is admitted against rows. Replay checks the admitted operations only. It does not establish that the handler rejects operations the declaration deferred, so it is not a general proof that the handler enforces the bounds.
Kind: EscrowCheck. Family concurrency: MCP servers list it once api_tools opens that family. Origin: Yichus/Mcp::catalog.
CLI: yichus admit — batch admission against the declared escrow invariants; the CLI reads the batch from a file.
Parameters
sources(required, array) — JSON array of {fileName, source} Bosatsu files including the EscrowSpec or TableEscrowSpec.batch(optional, array) — Optional JSON array of {operation, input, principal?} admission ops; principal is {user_id, roles} for a handler that takes one.rows(optional, object) — Optional JSON world a TableEscrowSpec is admitted against: {table: [row, ...] | {id: row}}, the api_why rows form. An unseeded table is empty.module_name(optional, string) — Optional module name (default ApiAdmission).
Example
Each response was produced by calling this tool with the displayed request when these docs were generated, on files committed to the repository. A violated or refuted verdict is a successful call: the check ran and found what its example shows.
Admit a batch against the ledger's declared account limits
Request
{
"sources": [
{
"fileName": "ledger.bosatsu",
"source": "package Demo/Ledger\n\n# A minimal ledger: integer balances keyed by account id, held in\n# one state cell. Every account must stay non-negative; account D is a\n# credit account with an upper limit, so both interval directions are\n# exercised. The limit functions here are the SAME compiled functions the\n# handler's guard and the spec's declared bounds use — nothing to drift.\n\nexport (\n Transfer(),\n initial_accounts,\n balance_of,\n lower_limit,\n upper_limit,\n within_limits,\n is_even\n)\n\nstruct Transfer(source: String, target: String, amount: Int)\n\ninitial_accounts = empty_Dict(string_Order).add_key(\"A\", 200).add_key(\"B\", 60).add_key(\"C\", 40).add_key(\"D\", 150)\n\ndef balance_of(accounts: Dict[String, Int], key: String) -> Int:\n match get_key(accounts, key):\n case Some(v): v\n case None: 0\n\n# Every balance stays non-negative.\ndef lower_limit(_: String) -> Option[Int]:\n Some(0)\n\n# Account D may not exceed its credit limit.\ndef upper_limit(key: String) -> Option[Int]:\n match key:\n case \"D\": Some(200)\n case _: None\n\ndef gte(a: Int, b: Int) -> Bool:\n match cmp_Int(a, b):\n case LT: False\n case _: True\n\ndef lte(a: Int, b: Int) -> Bool:\n match cmp_Int(a, b):\n case GT: False\n case _: True\n\ndef check_lower(key: String, balance: Int) -> Bool:\n match lower_limit(key):\n case Some(lo): gte(balance, lo)\n case None: True\n\ndef check_upper(key: String, balance: Int) -> Bool:\n match upper_limit(key):\n case Some(hi): lte(balance, hi)\n case None: True\n\ndef within_limits(key: String, balance: Int) -> Bool:\n and(check_lower(key, balance), check_upper(key, balance))\n\n# A legal total predicate that no interval bound can express — the demo's\n# non-monotone policy toggle. Declaring it moves the affected key off the\n# escrow fast path into bounded search.\ndef is_even(v: Int) -> Bool:\n eq_Int(mod_Int(v, 2), 0)\n"
},
{
"fileName": "ledger.spec.bosatsu",
"source": "package Demo/LedgerSpec\n\n# Escrow declaration for the ledger: the `accounts` cell is a keyed family\n# of integers, a transfer is a Dec delta on its source key and an Inc delta\n# on its target key, and the invariants are the domain's own limit\n# functions — the same compiled `lower_limit`/`upper_limit` the handler's\n# guard checks.\n\nfrom Demo/Ledger import Transfer, initial_accounts, balance_of, lower_limit, upper_limit\nfrom Yichus/Spec import EscrowSpec, Delta, Bounds, Dec, Inc\n\nexport (ledger_spec)\n\nexposes (Demo/Ledger, Yichus/Spec)\n\ndef source_key(t: Transfer) -> String:\n Transfer(source, _, _) = t\n source\n\ndef target_key(t: Transfer) -> String:\n Transfer(_, target, _) = t\n target\n\ndef amount_of(t: Transfer) -> Int:\n Transfer(_, _, amount) = t\n amount\n\nledger_spec = EscrowSpec(\n \"accounts\",\n initial_accounts,\n balance_of,\n [\n Delta(\"transfer\", source_key, amount_of, Dec),\n Delta(\"transfer\", target_key, amount_of, Inc)\n ],\n Bounds(lower_limit, upper_limit),\n []\n)\n"
},
{
"fileName": "ledger_handlers.bosatsu",
"source": "package Demo/LedgerHandlers\n\n# The obvious guarded transfer handler: read, apply, check both accounts\n# against the domain limits, write only when legal. No lock, no retry loop\n# — batch admission is derived from the declared escrow spec, and replay\n# verification checks this handler agrees with its declared deltas.\n\nfrom Yichus/IO import pure, flat_map, IO\nfrom Yichus/UI import State, read, write\nfrom Demo/Ledger import Transfer, balance_of, within_limits\n\nexport (transfer)\n\nexposes (Demo/Ledger, Yichus/IO, Yichus/UI)\n\ndef transfer(accounts: State[Dict[String, Int]], t: Transfer) -> IO[Unit]:\n Transfer(source, target, amount) = t\n current <- flat_map(read(accounts))\n debited = current.add_key(source, sub(balance_of(current, source), amount))\n credited = debited.add_key(target, add(balance_of(debited, target), amount))\n match and(within_limits(source, balance_of(credited, source)), within_limits(target, balance_of(credited, target))):\n case True: write(accounts, credited)\n case False: pure(())\n"
}
],
"batch": [
{
"operation": "transfer",
"input": {
"source": "A",
"target": "B",
"amount": 30
}
},
{
"operation": "transfer",
"input": {
"source": "B",
"target": "C",
"amount": 50
}
},
{
"operation": "transfer",
"input": {
"source": "A",
"target": "C",
"amount": 50
}
},
{
"operation": "transfer",
"input": {
"source": "A",
"target": "B",
"amount": 200
}
},
{
"operation": "transfer",
"input": {
"source": "A",
"target": "D",
"amount": 30
}
},
{
"operation": "transfer",
"input": {
"source": "A",
"target": "D",
"amount": 30
}
},
{
"operation": "transfer",
"input": {
"source": "D",
"target": "A",
"amount": 100
}
},
{
"operation": "transfer",
"input": {
"source": "B",
"target": "A",
"amount": 10
}
}
]
}
Response
{
"ok": true,
"tool": "api_escrow_check",
"admission": {
"schemaVersion": "1.0",
"module": "ApiAdmission",
"stateRef": "accounts",
"cell": {
"kind": "state",
"name": "accounts",
"boundTable": null
},
"spec": "Demo/LedgerSpec::ledger_spec",
"specLocation": "ledger.spec:28:15",
"modelBinding": "declared-only+replay-verified",
"searchBound": 8,
"counts": {
"batch": 8,
"admitted": 6,
"deferred": 2,
"inconclusive": 0,
"escrowFastPath": 6,
"witnessSearched": 0
},
"operations": [
{
"index": 0,
"operation": "transfer",
"input": {
"source": "A",
"target": "B",
"amount": 30
},
"verdict": "admitted",
"path": "escrow",
"location": "ledger_handlers:22:16",
"deltas": [
{
"key": "A",
"amount": 30,
"sign": "Dec"
},
{
"key": "B",
"amount": 30,
"sign": "Inc"
}
],
"position": 0
},
{
"index": 1,
"operation": "transfer",
"input": {
"source": "B",
"target": "C",
"amount": 50
},
"verdict": "admitted",
"path": "escrow",
"location": "ledger_handlers:22:16",
"deltas": [
{
"key": "B",
"amount": 50,
"sign": "Dec"
},
{
"key": "C",
"amount": 50,
"sign": "Inc"
}
],
"position": 1
},
{
"index": 2,
"operation": "transfer",
"input": {
"source": "A",
"target": "C",
"amount": 50
},
"verdict": "admitted",
"path": "escrow",
"location": "ledger_handlers:22:16",
"deltas": [
{
"key": "A",
"amount": 50,
"sign": "Dec"
},
{
"key": "C",
"amount": 50,
"sign": "Inc"
}
],
"position": 2
},
{
"index": 3,
"operation": "transfer",
"input": {
"source": "A",
"target": "B",
"amount": 200
},
"verdict": "deferred",
"path": "escrow",
"location": "ledger_handlers:22:16",
"deltas": [
{
"key": "A",
"amount": 200,
"sign": "Dec"
},
{
"key": "B",
"amount": 200,
"sign": "Inc"
}
],
"why": {
"invariant": "lower-bound:A",
"key": "A",
"attempted": -80,
"bound": 0,
"intervalLow": 120,
"intervalHigh": 200,
"consumedBy": [
0,
2
]
}
},
{
"index": 4,
"operation": "transfer",
"input": {
"source": "A",
"target": "D",
"amount": 30
},
"verdict": "admitted",
"path": "escrow",
"location": "ledger_handlers:22:16",
"deltas": [
{
"key": "A",
"amount": 30,
"sign": "Dec"
},
{
"key": "D",
"amount": 30,
"sign": "Inc"
}
],
"position": 3
},
{
"index": 5,
"operation": "transfer",
"input": {
"source": "A",
"target": "D",
"amount": 30
},
"verdict": "deferred",
"path": "escrow",
"location": "ledger_handlers:22:16",
"deltas": [
{
"key": "A",
"amount": 30,
"sign": "Dec"
},
{
"key": "D",
"amount": 30,
"sign": "Inc"
}
],
"why": {
"invariant": "upper-bound:D",
"key": "D",
"attempted": 210,
"bound": 200,
"intervalLow": 150,
"intervalHigh": 180,
"consumedBy": [
4
]
}
},
{
"index": 6,
"operation": "transfer",
"input": {
"source": "D",
"target": "A",
"amount": 100
},
"verdict": "admitted",
"path": "escrow",
"location": "ledger_handlers:22:16",
"deltas": [
{
"key": "D",
"amount": 100,
"sign": "Dec"
},
{
"key": "A",
"amount": 100,
"sign": "Inc"
}
],
"position": 4
},
{
"index": 7,
"operation": "transfer",
"input": {
"source": "B",
"target": "A",
"amount": 10
},
"verdict": "admitted",
"path": "escrow",
"location": "ledger_handlers:22:16",
"deltas": [
{
"key": "B",
"amount": 10,
"sign": "Dec"
},
{
"key": "A",
"amount": 10,
"sign": "Inc"
}
],
"position": 5
}
],
"witnessOrdering": [
0,
1,
2,
4,
6,
7
],
"escrowIntervals": [
{
"key": "A",
"initial": 200,
"low": 90,
"high": 310,
"lower": 0,
"upper": null,
"exact": null
},
{
"key": "B",
"initial": 60,
"low": 0,
"high": 90,
"lower": 0,
"upper": null,
"exact": null
},
{
"key": "C",
"initial": 40,
"low": 40,
"high": 140,
"lower": 0,
"upper": null,
"exact": null
},
{
"key": "D",
"initial": 150,
"low": 50,
"high": 180,
"lower": 0,
"upper": 200,
"exact": null
}
],
"replay": {
"status": "verified",
"note": "replayed 6 operation(s) through compiled handlers; every step matched the declared model",
"divergence": null,
"steps": [
{
"opIndex": 0,
"operation": "transfer",
"values": {
"A": 170,
"B": 90,
"C": 40,
"D": 150
}
},
{
"opIndex": 1,
"operation": "transfer",
"values": {
"A": 170,
"B": 40,
"C": 90,
"D": 150
}
},
{
"opIndex": 2,
"operation": "transfer",
"values": {
"A": 120,
"B": 40,
"C": 140,
"D": 150
}
},
{
"opIndex": 4,
"operation": "transfer",
"values": {
"A": 90,
"B": 40,
"C": 140,
"D": 180
}
},
{
"opIndex": 6,
"operation": "transfer",
"values": {
"A": 190,
"B": 40,
"C": 140,
"D": 80
}
},
{
"opIndex": 7,
"operation": "transfer",
"values": {
"A": 200,
"B": 30,
"C": 140,
"D": 80
}
}
]
}
}
}
Run tools in the browser: api-mcp.html?webmcp=1.
Read the result according to this tool’s scope: static checks, bounded execution checks, and descriptive diagrams answer different questions. A successful call is not a general approval of the program. The safety and permissions guide compares the checks and provides editable ownership, guard, and role examples.