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

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.