Yichus / Reference / API MCP tools
api_protocol_check
Exhaustively explore a protocol-case-1.0 finite domain against compiled transaction handlers. Requests carry instance and delivery identities; serializable transactions are atomic; commit-unknown branches into committed and uncommitted durable states; external dispatch and response are separate transitions. Declare IO[Bool] invariants over immutable before/after views, required reachability witnesses, typed named inputs, times, external results, and budgets. Holds means only the complete declared finite domain; violated includes a sourced schedule; exhausted budgets and unsupported semantics are inconclusive. Adapter conformance, authenticated principals and absence of unlisted writers remain explicit assumptions. Use the same case with yichus protocol --case case.json files.bosatsu. Case schema, selector vocabulary and a runnable example: https://yich.us/reference/api-mcp/analysis-recipes.html#protocol and the full specification at https://yich.us/reference/api-mcp/protocol-specification.txt.
Kind: ProtocolCheck. Family concurrency: MCP servers list it once api_tools opens that family. Origin: Yichus/Mcp::catalog.
CLI: yichus protocol — the same finite protocol case and bounded scheduler; the CLI reads the case from --case.
Parameters
sources(required, array) — JSON array of {fileName, source} Bosatsu handlers and declared invariant functions.case(required, object) — JSON object or encoded JSON string in protocol-case-1.0 format; all domains, assumptions, invariants and bounds are explicit.
Examples
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.
A withdrawal whose acknowledgement always has a durable receipt
Request
{
"sources": [
{
"fileName": "ledger.bosatsu",
"source": "package Ledger/Withdrawal\n\n# The withdrawal ledger behind the savings app.\n#\n# One account row per verified customer, keyed by the identity the\n# bank's login service hands the engine, and one receipt row per\n# withdrawal command. Every movement of money runs inside one\n# serializable transaction: the balance is read, the new balance is\n# written, and the receipt is filed, all or nothing.\n#\n# A withdrawal is an idempotent command. The app may retry a request\n# whose answer it never saw, so the command's key is looked up first\n# and a second delivery of the same key returns the receipt already\n# filed rather than moving the money twice.\n#\n# The receipt is the customer's copy of the movement. It is filed in\n# the ledger and it is handed back in the response, and support reads\n# whichever of the two is in front of them.\n\nfrom Yichus/Access import (\n Principal, AccessRule, AccessSpec, OwnerScoped, owner_key\n)\nfrom Yichus/Data import Db, Table, table, db_read_opt\nfrom Yichus/IO import IO, pure, flat_map\nfrom Yichus/Service import (\n ServiceDef, ReadPerm, WritePerm, CreatePerm, handler, route, service_def\n)\nfrom Yichus/Transaction import (\n Scope, TxTable, Txn, Outcome,\n stored_table, tx_pure, tx_bind, tx_abort, tx_read, tx_write, tx_insert,\n tx_database_time_millis, transaction\n)\n\nexport (\n ledger_api, access_rules,\n Account(), Movement(), Receipt(),\n WithdrawInput(), DepositInput(), StatusInput(),\n LedgerError(), WithdrawalReport(), BalanceReport(),\n command_local_key, receipt_key, validate_withdrawal, validate_deposit,\n move_balance, withdraw_plan, deposit_plan,\n withdraw, deposit, withdrawal_status, account_balance,\n)\nexposes (\n Yichus/Access, Yichus/Data, Yichus/IO, Yichus/Service, Yichus/Transaction\n)\n\n# ---------------------------------------------------------------------------\n# Small total combinators and the key framing.\n# ---------------------------------------------------------------------------\n\ndef int_lt(a: Int, b: Int) -> Bool:\n match cmp_Int(a, b):\n case LT: True\n case _: False\n\ndef int_gt(a: Int, b: Int) -> Bool:\n match cmp_Int(a, b):\n case GT: True\n case _: False\n\ndef is_blank(s: String) -> Bool:\n eq_String(s, \"\")\n\n# Length framing keeps a command's identity injective even when a\n# component contains a colon or looks like another operation's name.\ndef frame(s: String) -> String:\n concat_String([int_to_String(length_String(s)), \":\", s])\n\nsite_id = \"ledger-1\"\n\n# ---------------------------------------------------------------------------\n# Domain records.\n# ---------------------------------------------------------------------------\n\nstruct Account(id: String, owner: String, balance: Int)\n\n# What one movement did to the balance: the figure before it and the\n# figure after it.\nstruct Movement(before: Int, after: Int)\n\nstruct WithdrawInput(idempotency_key: String, amount: Int)\nstruct DepositInput(idempotency_key: String, amount: Int)\nstruct StatusInput(idempotency_key: String)\n\n# The customer's copy of a settled withdrawal.\nstruct Receipt(request: WithdrawInput, balance_after: Int, at: Int)\n\nenum LedgerError:\n InvalidRequest(field: String, reason: String)\n UnknownAccount(account_id: String)\n InsufficientFunds(balance: Int, requested: Int)\n InvalidDatabaseTime(now: Int)\n\nenum WithdrawalReport:\n WithdrawalKnown(receipt: Receipt)\n WithdrawalUnknown\n InvalidStatusKey(reason: LedgerError)\n\nenum BalanceReport:\n BalanceKnown(account: Account)\n BalanceUnknown\n\n# ---------------------------------------------------------------------------\n# Command identity. A key is scoped to this site, to the operation, and\n# to the caller, so two customers may use the same idempotency key and\n# a withdrawal key can never collide with a deposit key.\n# ---------------------------------------------------------------------------\n\ndef command_local_key(input: WithdrawInput) -> String:\n WithdrawInput(idempotency_key, _) = input\n concat_String([frame(site_id), frame(\"withdraw\"), frame(idempotency_key)])\n\ndef receipt_key(principal: Principal, input: WithdrawInput) -> String:\n owner_key(principal, command_local_key(input))\n\ndef status_local_key(input: StatusInput) -> String:\n StatusInput(idempotency_key) = input\n concat_String([frame(site_id), frame(\"withdraw\"), frame(idempotency_key)])\n\n# ---------------------------------------------------------------------------\n# Validation, pure so `why` and a law can see it.\n# ---------------------------------------------------------------------------\n\ndef validate_key(idempotency_key: String) -> Option[LedgerError]:\n if is_blank(idempotency_key):\n Some(InvalidRequest(\"idempotency_key\", \"must not be empty\"))\n else:\n if int_gt(length_String(idempotency_key), 64):\n Some(InvalidRequest(\"idempotency_key\", \"must be at most 64 characters\"))\n else: None\n\ndef validate_withdrawal(input: WithdrawInput) -> Option[LedgerError]:\n WithdrawInput(idempotency_key, amount) = input\n match validate_key(idempotency_key):\n case Some(error): Some(error)\n case None:\n if int_lt(amount, 1): Some(InvalidRequest(\"amount\", \"must be at least one penny\"))\n else:\n if int_gt(amount, 50000000):\n Some(InvalidRequest(\"amount\", \"must be at most five hundred thousand pence\"))\n else: None\n\ndef validate_deposit(input: DepositInput) -> Option[LedgerError]:\n DepositInput(idempotency_key, amount) = input\n match validate_key(idempotency_key):\n case Some(error): Some(error)\n case None:\n if int_lt(amount, 1): Some(InvalidRequest(\"amount\", \"must be at least one penny\"))\n else: None\n\n# ---------------------------------------------------------------------------\n# Storage. Both tables are owner scoped: an account row is keyed by the\n# caller's verified identity and a receipt row by that identity plus\n# the command's own key.\n# ---------------------------------------------------------------------------\n\naccess_rules = AccessSpec([\n AccessRule(\"accounts\", OwnerScoped),\n AccessRule(\"withdrawal_receipts\", OwnerScoped),\n])\n\naccounts_table: TxTable[s, Account] = stored_table(\"accounts\")\n\nreceipts_table: TxTable[s, Receipt] = stored_table(\"withdrawal_receipts\")\n\ndef account_rows(db: Db) -> Table[Account]:\n table(db, \"accounts\")\n\ndef receipt_rows(db: Db) -> Table[Receipt]:\n table(db, \"withdrawal_receipts\")\n\n# ---------------------------------------------------------------------------\n# The one place a balance changes: read the row, refuse a movement that\n# would take it below zero, write the new row, and report what the\n# movement did.\n# ---------------------------------------------------------------------------\n\ndef move_balance[s](\n principal: Principal,\n delta: Int\n) -> Txn[s, LedgerError, Movement]:\n Principal(uid, _) = principal\n row <- tx_bind(tx_read(accounts_table, uid))\n match row:\n case None: tx_abort(UnknownAccount(uid))\n case Some(Account(id, owner, balance)):\n next = add(balance, delta)\n if int_lt(next, 0):\n tx_abort(InsufficientFunds(balance, sub(0, delta)))\n else:\n _ <- tx_bind(tx_write(accounts_table, uid, Account(id, owner, next)))\n tx_pure(Movement(balance, next))\n\n# ---------------------------------------------------------------------------\n# The plans.\n# ---------------------------------------------------------------------------\n\ndef withdraw_plan[s](\n scope: Scope[s],\n principal: Principal,\n input: WithdrawInput\n) -> Txn[s, LedgerError, Receipt]:\n match validate_withdrawal(input):\n case Some(error): tx_abort(error)\n case None:\n key = owner_key(principal, command_local_key(input))\n previous <- tx_bind(tx_read(receipts_table, key))\n match previous:\n case Some(receipt): tx_pure(receipt)\n case None:\n now <- tx_bind(tx_database_time_millis(scope))\n if int_lt(now, 0): tx_abort(InvalidDatabaseTime(now))\n else:\n WithdrawInput(_, amount) = input\n moved <- tx_bind(move_balance(principal, sub(0, amount)))\n Movement(_, after) = moved\n receipt = Receipt(input, after, now)\n _ <- tx_bind(tx_insert(receipts_table, key, receipt))\n # The receipt filed in the ledger and the receipt in the\n # response are one value, so the customer's copy and the\n # bank's copy cannot say different things.\n tx_pure(receipt)\n\ndef deposit_plan[s](\n principal: Principal,\n input: DepositInput\n) -> Txn[s, LedgerError, Movement]:\n match validate_deposit(input):\n case Some(error): tx_abort(error)\n case None:\n DepositInput(_, amount) = input\n move_balance(principal, amount)\n\n# ---------------------------------------------------------------------------\n# Handlers. The engine injects Db and Principal; nothing here\n# constructs a Principal.\n# ---------------------------------------------------------------------------\n\ndef withdraw(\n db: Db,\n principal: Principal,\n input: WithdrawInput\n) -> IO[Outcome[LedgerError, Receipt]]:\n scope <- transaction(db)\n withdraw_plan(scope, principal, input)\n\ndef deposit(\n db: Db,\n principal: Principal,\n input: DepositInput\n) -> IO[Outcome[LedgerError, Movement]]:\n _ <- transaction(db)\n deposit_plan(principal, input)\n\ndef withdrawal_status(\n db: Db,\n principal: Principal,\n input: StatusInput\n) -> IO[WithdrawalReport]:\n StatusInput(idempotency_key) = input\n match validate_key(idempotency_key):\n case Some(error): pure(InvalidStatusKey(error))\n case None:\n row <- flat_map(db_read_opt(\n receipt_rows(db), owner_key(principal, status_local_key(input))))\n match row:\n case None: pure(WithdrawalUnknown)\n case Some(receipt): pure(WithdrawalKnown(receipt))\n\ndef account_balance(db: Db, principal: Principal) -> IO[BalanceReport]:\n Principal(uid, _) = principal\n row <- flat_map(db_read_opt(account_rows(db), uid))\n match row:\n case None: pure(BalanceUnknown)\n case Some(account): pure(BalanceKnown(account))\n\nledger_api: ServiceDef = service_def(\"ledger\", [\n route(\"/withdraw\", handler(\"withdraw\", withdraw), [\n ReadPerm(\"accounts\"),\n WritePerm(\"accounts\"),\n ReadPerm(\"withdrawal_receipts\"),\n CreatePerm(\"withdrawal_receipts\"),\n ]),\n route(\"/deposit\", handler(\"deposit\", deposit), [\n ReadPerm(\"accounts\"),\n WritePerm(\"accounts\"),\n ]),\n route(\"/withdrawals/status\", handler(\"withdrawal_status\", withdrawal_status), [\n ReadPerm(\"withdrawal_receipts\"),\n ]),\n route(\"/balance\", handler(\"account_balance\", account_balance), [\n ReadPerm(\"accounts\"),\n ]),\n])\n"
}
],
"case": {
"schemaVersion": "protocol-case-1.0",
"name": "Duplicate withdrawal deliveries against one account",
"assumptions": [
"serializable-atomic-transactions",
"rollback-on-abort-and-retry-exhaustion",
"commit-unknown-may-commit",
"stable-time-within-attempt",
"no-unmodeled-writers",
"preauthenticated-principals"
],
"initialRows": {
"accounts": {
"alice": {
"id": "alice",
"owner": "alice",
"balance": 50000
}
},
"withdrawal_receipts": {}
},
"initialize": [],
"requests": [
{
"instance": "engine-a",
"delivery": "engine-a",
"call": {
"binding": "Ledger/Withdrawal::withdraw",
"arguments": {
"principal": {
"user_id": "alice",
"roles": []
},
"input": {
"idempotency_key": "w-1",
"amount": 2500
}
}
}
},
{
"instance": "engine-b",
"delivery": "engine-b",
"call": {
"binding": "Ledger/Withdrawal::withdraw",
"arguments": {
"principal": {
"user_id": "alice",
"roles": []
},
"input": {
"idempotency_key": "w-1",
"amount": 2500
}
}
}
}
],
"times": [
1000
],
"externalResults": {},
"invariants": [],
"traceInvariants": [
{
"name": "exact-durable-receipt",
"kind": "return-receipt",
"table": "withdrawal_receipts",
"keyBinding": "Ledger/Withdrawal::receipt_key",
"keyArguments": {
"principal": "request.principal",
"input": "request.input"
},
"resultPath": [
{
"constructor": "Committed"
},
{
"field": "value"
},
{
"field": "balance_after"
}
],
"rowPath": [
{
"field": "balance_after"
}
]
},
{
"name": "receipts-never-rewritten",
"kind": "immutable-rows",
"table": "withdrawal_receipts"
}
],
"witnesses": [
{
"name": "receipt-reachable",
"kind": "table-nonempty",
"table": "withdrawal_receipts"
},
{
"name": "returned",
"kind": "event",
"event": "returned"
}
],
"bounds": {
"maxStates": 100000,
"maxDepth": 20,
"maxFaults": 1,
"maxCrashes": 1,
"maxOperations": 1000
}
}
}
Response
{
"ok": true,
"tool": "api_protocol_check",
"protocol": {
"artifactClass": "protocol-verdict",
"schemaVersion": "protocol-verdict-1.0",
"sources": {
"hash": "39652e8ea9bcd38a370e82a78e33e8f32ae4c93b1122939a305386cf6257ea13",
"files": [
{
"name": "ledger",
"sha256": "d76908ea6e68d0be304d72970205d2b9b24cf3fc9379de97af2ddcf20e7ddef4"
}
]
},
"name": "Duplicate withdrawal deliveries against one account",
"status": "holds",
"proven": false,
"scope": "Exhaustive only over the declared finite requests, times, external results and fault bounds. Adapter conformance and unlisted writers are assumptions, not established by this check.",
"case": {
"schemaVersion": "protocol-case-1.0",
"name": "Duplicate withdrawal deliveries against one account",
"assumptions": [
"serializable-atomic-transactions",
"rollback-on-abort-and-retry-exhaustion",
"commit-unknown-may-commit",
"stable-time-within-attempt",
"no-unmodeled-writers",
"preauthenticated-principals"
],
"initialRows": {
"accounts": {
"alice": {
"id": "alice",
"owner": "alice",
"balance": 50000
}
},
"withdrawal_receipts": {}
},
"initialize": [],
"requests": [
{
"instance": "engine-a",
"delivery": "engine-a",
"call": {
"binding": "Ledger/Withdrawal::withdraw",
"arguments": {
"principal": {
"user_id": "alice",
"roles": []
},
"input": {
"idempotency_key": "w-1",
"amount": 2500
}
}
}
},
{
"instance": "engine-b",
"delivery": "engine-b",
"call": {
"binding": "Ledger/Withdrawal::withdraw",
"arguments": {
"principal": {
"user_id": "alice",
"roles": []
},
"input": {
"idempotency_key": "w-1",
"amount": 2500
}
}
}
}
],
"times": [
1000
],
"externalResults": {},
"invariants": [],
"traceInvariants": [
{
"name": "exact-durable-receipt",
"kind": "return-receipt",
"table": "withdrawal_receipts",
"keyBinding": "Ledger/Withdrawal::receipt_key",
"keyArguments": {
"principal": "request.principal",
"input": "request.input"
},
"resultPath": [
{
"constructor": "Committed"
},
{
"field": "value"
},
{
"field": "balance_after"
}
],
"rowPath": [
{
"field": "balance_after"
}
]
},
{
"name": "receipts-never-rewritten",
"kind": "immutable-rows",
"table": "withdrawal_receipts"
}
],
"witnesses": [
{
"name": "receipt-reachable",
"kind": "table-nonempty",
"table": "withdrawal_receipts"
},
{
"name": "returned",
"kind": "event",
"event": "returned"
}
],
"bounds": {
"maxStates": 100000,
"maxDepth": 20,
"maxFaults": 1,
"maxCrashes": 1,
"maxOperations": 1000
}
},
"states": 995,
"terminalSchedules": 500,
"reached": [
"exact-durable-receipt:receipt-observed",
"receipt-reachable",
"returned"
],
"witnessTracesIncluded": false
},
"allHold": true
}
The near-miss twin: a retried withdrawal loses its receipt
Request
{
"sources": [
{
"fileName": "ledger.bosatsu",
"source": "package Ledger/Withdrawal\n\n# The withdrawal ledger behind the savings app.\n\nfrom Yichus/Access import (\n Principal, AccessRule, AccessSpec, OwnerScoped, owner_key\n)\nfrom Yichus/Data import Db, Table, table, db_read_opt\nfrom Yichus/IO import IO, pure, flat_map\nfrom Yichus/Service import (\n ServiceDef, ReadPerm, WritePerm, handler, route, service_def\n)\nfrom Yichus/Transaction import (\n Scope, TxTable, Txn, Outcome,\n stored_table, tx_pure, tx_bind, tx_abort, tx_read, tx_write,\n tx_database_time_millis, transaction\n)\n\nexport (\n ledger_api, access_rules,\n Account(), Movement(), Receipt(),\n WithdrawInput(), DepositInput(), StatusInput(),\n LedgerError(), WithdrawalReport(), BalanceReport(),\n command_local_key, receipt_key, validate_withdrawal, validate_deposit,\n move_balance, withdraw_plan, deposit_plan,\n withdraw, deposit, withdrawal_status, account_balance,\n)\nexposes (\n Yichus/Access, Yichus/Data, Yichus/IO, Yichus/Service, Yichus/Transaction\n)\n\n# ---------------------------------------------------------------------------\n# Small total combinators and the key framing.\n# ---------------------------------------------------------------------------\n\ndef int_lt(a: Int, b: Int) -> Bool:\n match cmp_Int(a, b):\n case LT: True\n case _: False\n\ndef int_gt(a: Int, b: Int) -> Bool:\n match cmp_Int(a, b):\n case GT: True\n case _: False\n\ndef is_blank(s: String) -> Bool:\n eq_String(s, \"\")\n\n# Length framing keeps a command's identity injective even when a\n# component contains a colon or looks like another operation's name.\ndef frame(s: String) -> String:\n concat_String([int_to_String(length_String(s)), \":\", s])\n\nsite_id = \"ledger-1\"\n\n# ---------------------------------------------------------------------------\n# Domain records.\n# ---------------------------------------------------------------------------\n\nstruct Account(id: String, owner: String, balance: Int)\n\n# What one movement did to the balance: the figure before it and the\n# figure after it.\nstruct Movement(before: Int, after: Int)\n\nstruct WithdrawInput(idempotency_key: String, amount: Int)\nstruct DepositInput(idempotency_key: String, amount: Int)\nstruct StatusInput(idempotency_key: String)\n\n# The customer's copy of a settled withdrawal.\nstruct Receipt(request: WithdrawInput, balance_after: Int, at: Int)\n\nenum LedgerError:\n InvalidRequest(field: String, reason: String)\n UnknownAccount(account_id: String)\n InsufficientFunds(balance: Int, requested: Int)\n InvalidDatabaseTime(now: Int)\n\nenum WithdrawalReport:\n WithdrawalKnown(receipt: Receipt)\n WithdrawalUnknown\n InvalidStatusKey(reason: LedgerError)\n\nenum BalanceReport:\n BalanceKnown(account: Account)\n BalanceUnknown\n\n# ---------------------------------------------------------------------------\n# Command identity. A key is scoped to this site, to the operation, and\n# to the caller, so two customers may use the same idempotency key and\n# a withdrawal key can never collide with a deposit key.\n# ---------------------------------------------------------------------------\n\ndef command_local_key(input: WithdrawInput) -> String:\n WithdrawInput(idempotency_key, _) = input\n concat_String([frame(site_id), frame(\"withdraw\"), frame(idempotency_key)])\n\ndef receipt_key(principal: Principal, input: WithdrawInput) -> String:\n owner_key(principal, command_local_key(input))\n\ndef status_local_key(input: StatusInput) -> String:\n StatusInput(idempotency_key) = input\n concat_String([frame(site_id), frame(\"withdraw\"), frame(idempotency_key)])\n\n# ---------------------------------------------------------------------------\n# Validation, pure so `why` and a law can see it.\n# ---------------------------------------------------------------------------\n\ndef validate_key(idempotency_key: String) -> Option[LedgerError]:\n if is_blank(idempotency_key):\n Some(InvalidRequest(\"idempotency_key\", \"must not be empty\"))\n else:\n if int_gt(length_String(idempotency_key), 64):\n Some(InvalidRequest(\"idempotency_key\", \"must be at most 64 characters\"))\n else: None\n\ndef validate_withdrawal(input: WithdrawInput) -> Option[LedgerError]:\n WithdrawInput(idempotency_key, amount) = input\n match validate_key(idempotency_key):\n case Some(error): Some(error)\n case None:\n if int_lt(amount, 1): Some(InvalidRequest(\"amount\", \"must be at least one penny\"))\n else:\n if int_gt(amount, 50000000):\n Some(InvalidRequest(\"amount\", \"must be at most five hundred thousand pence\"))\n else: None\n\ndef validate_deposit(input: DepositInput) -> Option[LedgerError]:\n DepositInput(idempotency_key, amount) = input\n match validate_key(idempotency_key):\n case Some(error): Some(error)\n case None:\n if int_lt(amount, 1): Some(InvalidRequest(\"amount\", \"must be at least one penny\"))\n else: None\n\n# ---------------------------------------------------------------------------\n# Storage. Both tables are owner scoped: an account row is keyed by the\n# caller's verified identity and a receipt row by that identity plus\n# the command's own key.\n# ---------------------------------------------------------------------------\n\naccess_rules = AccessSpec([\n AccessRule(\"accounts\", OwnerScoped),\n AccessRule(\"withdrawal_receipts\", OwnerScoped),\n])\n\naccounts_table: TxTable[s, Account] = stored_table(\"accounts\")\n\nreceipts_table: TxTable[s, Receipt] = stored_table(\"withdrawal_receipts\")\n\ndef account_rows(db: Db) -> Table[Account]:\n table(db, \"accounts\")\n\ndef receipt_rows(db: Db) -> Table[Receipt]:\n table(db, \"withdrawal_receipts\")\n\n# ---------------------------------------------------------------------------\n# The one place a balance changes: read the row, refuse a movement that\n# would take it below zero, write the new row, and report what the\n# movement did.\n# ---------------------------------------------------------------------------\n\ndef move_balance[s](\n principal: Principal,\n delta: Int\n) -> Txn[s, LedgerError, Movement]:\n Principal(uid, _) = principal\n row <- tx_bind(tx_read(accounts_table, uid))\n match row:\n case None: tx_abort(UnknownAccount(uid))\n case Some(Account(id, owner, balance)):\n next = add(balance, delta)\n if int_lt(next, 0):\n tx_abort(InsufficientFunds(balance, sub(0, delta)))\n else:\n _ <- tx_bind(tx_write(accounts_table, uid, Account(id, owner, next)))\n tx_pure(Movement(balance, next))\n\n# ---------------------------------------------------------------------------\n# The plans.\n# ---------------------------------------------------------------------------\n\ndef withdraw_plan[s](\n scope: Scope[s],\n principal: Principal,\n input: WithdrawInput\n) -> Txn[s, LedgerError, Receipt]:\n match validate_withdrawal(input):\n case Some(error): tx_abort(error)\n case None:\n key = owner_key(principal, command_local_key(input))\n previous <- tx_bind(tx_read(receipts_table, key))\n match previous:\n case Some(receipt): tx_pure(receipt)\n case None:\n now <- tx_bind(tx_database_time_millis(scope))\n if int_lt(now, 0): tx_abort(InvalidDatabaseTime(now))\n else:\n WithdrawInput(_, amount) = input\n moved <- tx_bind(move_balance(principal, sub(0, amount)))\n Movement(_, after) = moved\n receipt = Receipt(input, after, now)\n tx_pure(receipt)\n\ndef deposit_plan[s](\n principal: Principal,\n input: DepositInput\n) -> Txn[s, LedgerError, Movement]:\n match validate_deposit(input):\n case Some(error): tx_abort(error)\n case None:\n DepositInput(_, amount) = input\n move_balance(principal, amount)\n\n# ---------------------------------------------------------------------------\n# Handlers. The engine injects Db and Principal; nothing here\n# constructs a Principal.\n# ---------------------------------------------------------------------------\n\ndef withdraw(\n db: Db,\n principal: Principal,\n input: WithdrawInput\n) -> IO[Outcome[LedgerError, Receipt]]:\n scope <- transaction(db)\n withdraw_plan(scope, principal, input)\n\ndef deposit(\n db: Db,\n principal: Principal,\n input: DepositInput\n) -> IO[Outcome[LedgerError, Movement]]:\n _ <- transaction(db)\n deposit_plan(principal, input)\n\ndef withdrawal_status(\n db: Db,\n principal: Principal,\n input: StatusInput\n) -> IO[WithdrawalReport]:\n StatusInput(idempotency_key) = input\n match validate_key(idempotency_key):\n case Some(error): pure(InvalidStatusKey(error))\n case None:\n row <- flat_map(db_read_opt(\n receipt_rows(db), owner_key(principal, status_local_key(input))))\n match row:\n case None: pure(WithdrawalUnknown)\n case Some(receipt): pure(WithdrawalKnown(receipt))\n\ndef account_balance(db: Db, principal: Principal) -> IO[BalanceReport]:\n Principal(uid, _) = principal\n row <- flat_map(db_read_opt(account_rows(db), uid))\n match row:\n case None: pure(BalanceUnknown)\n case Some(account): pure(BalanceKnown(account))\n\nledger_api: ServiceDef = service_def(\"ledger\", [\n route(\"/withdraw\", handler(\"withdraw\", withdraw), [\n ReadPerm(\"accounts\"),\n WritePerm(\"accounts\"),\n ReadPerm(\"withdrawal_receipts\"),\n ]),\n route(\"/deposit\", handler(\"deposit\", deposit), [\n ReadPerm(\"accounts\"),\n WritePerm(\"accounts\"),\n ]),\n route(\"/withdrawals/status\", handler(\"withdrawal_status\", withdrawal_status), [\n ReadPerm(\"withdrawal_receipts\"),\n ]),\n route(\"/balance\", handler(\"account_balance\", account_balance), [\n ReadPerm(\"accounts\"),\n ]),\n])\n"
}
],
"case": {
"schemaVersion": "protocol-case-1.0",
"name": "Duplicate withdrawal deliveries against one account",
"assumptions": [
"serializable-atomic-transactions",
"rollback-on-abort-and-retry-exhaustion",
"commit-unknown-may-commit",
"stable-time-within-attempt",
"no-unmodeled-writers",
"preauthenticated-principals"
],
"initialRows": {
"accounts": {
"alice": {
"id": "alice",
"owner": "alice",
"balance": 50000
}
},
"withdrawal_receipts": {}
},
"initialize": [],
"requests": [
{
"instance": "engine-a",
"delivery": "engine-a",
"call": {
"binding": "Ledger/Withdrawal::withdraw",
"arguments": {
"principal": {
"user_id": "alice",
"roles": []
},
"input": {
"idempotency_key": "w-1",
"amount": 2500
}
}
}
},
{
"instance": "engine-b",
"delivery": "engine-b",
"call": {
"binding": "Ledger/Withdrawal::withdraw",
"arguments": {
"principal": {
"user_id": "alice",
"roles": []
},
"input": {
"idempotency_key": "w-1",
"amount": 2500
}
}
}
}
],
"times": [
1000
],
"externalResults": {},
"invariants": [],
"traceInvariants": [
{
"name": "exact-durable-receipt",
"kind": "return-receipt",
"table": "withdrawal_receipts",
"keyBinding": "Ledger/Withdrawal::receipt_key",
"keyArguments": {
"principal": "request.principal",
"input": "request.input"
},
"resultPath": [
{
"constructor": "Committed"
},
{
"field": "value"
},
{
"field": "balance_after"
}
],
"rowPath": [
{
"field": "balance_after"
}
]
},
{
"name": "receipts-never-rewritten",
"kind": "immutable-rows",
"table": "withdrawal_receipts"
}
],
"witnesses": [
{
"name": "receipt-reachable",
"kind": "table-nonempty",
"table": "withdrawal_receipts"
},
{
"name": "returned",
"kind": "event",
"event": "returned"
}
],
"bounds": {
"maxStates": 100000,
"maxDepth": 20,
"maxFaults": 1,
"maxCrashes": 1,
"maxOperations": 1000
}
}
}
Response
{
"ok": true,
"tool": "api_protocol_check",
"protocol": {
"artifactClass": "protocol-verdict",
"schemaVersion": "protocol-verdict-1.0",
"sources": {
"hash": "03717ef9c324b7f5f1e88c0eef41d05cfb3acdb97c5568d9f58e8052465f8e00",
"files": [
{
"name": "ledger",
"sha256": "c70ec0b1f96b5899690f83ab4fb1dc621aded78f9adff322525d3bcf50e12854"
}
]
},
"name": "Duplicate withdrawal deliveries against one account",
"status": "violated",
"proven": false,
"scope": "Exhaustive only over the declared finite requests, times, external results and fault bounds. Adapter conformance and unlisted writers are assumptions, not established by this check.",
"case": {
"schemaVersion": "protocol-case-1.0",
"name": "Duplicate withdrawal deliveries against one account",
"assumptions": [
"serializable-atomic-transactions",
"rollback-on-abort-and-retry-exhaustion",
"commit-unknown-may-commit",
"stable-time-within-attempt",
"no-unmodeled-writers",
"preauthenticated-principals"
],
"initialRows": {
"accounts": {
"alice": {
"id": "alice",
"owner": "alice",
"balance": 50000
}
},
"withdrawal_receipts": {}
},
"initialize": [],
"requests": [
{
"instance": "engine-a",
"delivery": "engine-a",
"call": {
"binding": "Ledger/Withdrawal::withdraw",
"arguments": {
"principal": {
"user_id": "alice",
"roles": []
},
"input": {
"idempotency_key": "w-1",
"amount": 2500
}
}
}
},
{
"instance": "engine-b",
"delivery": "engine-b",
"call": {
"binding": "Ledger/Withdrawal::withdraw",
"arguments": {
"principal": {
"user_id": "alice",
"roles": []
},
"input": {
"idempotency_key": "w-1",
"amount": 2500
}
}
}
}
],
"times": [
1000
],
"externalResults": {},
"invariants": [],
"traceInvariants": [
{
"name": "exact-durable-receipt",
"kind": "return-receipt",
"table": "withdrawal_receipts",
"keyBinding": "Ledger/Withdrawal::receipt_key",
"keyArguments": {
"principal": "request.principal",
"input": "request.input"
},
"resultPath": [
{
"constructor": "Committed"
},
{
"field": "value"
},
{
"field": "balance_after"
}
],
"rowPath": [
{
"field": "balance_after"
}
]
},
{
"name": "receipts-never-rewritten",
"kind": "immutable-rows",
"table": "withdrawal_receipts"
}
],
"witnesses": [
{
"name": "receipt-reachable",
"kind": "table-nonempty",
"table": "withdrawal_receipts"
},
{
"name": "returned",
"kind": "event",
"event": "returned"
}
],
"bounds": {
"maxStates": 100000,
"maxDepth": 20,
"maxFaults": 1,
"maxCrashes": 1,
"maxOperations": 1000
}
},
"states": 4,
"terminalSchedules": 0,
"reached": [],
"witnessTracesIncluded": false,
"invariant": "exact-durable-receipt",
"counterexample": [
{
"instance": "engine-a",
"delivery": "engine-a",
"ordinal": 0,
"phase": 0,
"time": 1000,
"kind": "request-started",
"source": null
},
{
"instance": "engine-a",
"delivery": "engine-a",
"ordinal": 1,
"phase": 1,
"time": 1000,
"kind": "committed",
"source": {
"root": "Ledger/Withdrawal::withdraw",
"calls": [],
"source": {
"binding": "Ledger/Withdrawal::withdraw",
"path": [
0
],
"region": {
"start": 7940,
"end": 8005
}
}
},
"writes": [
{
"table": "accounts",
"key": "alice",
"before": {
"id": "alice",
"owner": "alice",
"balance": 50000
},
"after": {
"id": "alice",
"owner": "alice",
"balance": 47500
},
"source": {
"root": "Ledger/Withdrawal::withdraw",
"calls": [
{
"binding": "Ledger/Withdrawal::withdraw",
"path": [
0,
2,
2
],
"region": {
"start": 7967,
"end": 8005
}
},
{
"binding": "Ledger/Withdrawal::withdraw_plan",
"path": [
0,
1,
2,
1,
2,
3,
2,
2,
2,
1,
2,
1,
1
],
"region": {
"start": 7157,
"end": 7196
}
}
],
"source": {
"binding": "Ledger/Withdrawal::move_balance",
"path": [
0,
1,
2,
2,
2,
0,
1,
1,
1,
1,
1,
1,
2,
1
],
"region": {
"start": 6264,
"end": 6319
}
}
}
}
]
},
{
"instance": "engine-a",
"delivery": "engine-a",
"ordinal": 2,
"phase": 1,
"time": 1000,
"kind": "returned",
"source": null,
"value": {
"value": {
"request": {
"idempotency_key": "w-1",
"amount": 2500
},
"balance_after": 47500,
"at": 1000
}
}
}
],
"rowsAfter": {
"accounts": {
"alice": {
"id": "alice",
"owner": "alice",
"balance": 47500
}
},
"withdrawal_receipts": {}
}
},
"allHold": false
}
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.