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

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.