Yichus / Reference / API MCP tools
api_obligations
The guided commit-strategy surface: which strategy your discharged obligations license (serialized commit, per-key independence, single-write commit, lattice single-write, bounded witness search), and — when a faster one is one obligation away — one pre-written sentence saying what would make this faster plus one paste-ready law snippet. Discharge is fail-closed on verdict status: only laws with a holds verdict count, and holds is bounded evidence, never proof. The engine does not check that a named law expresses its obligation or that it applies to the deployed handler — those bindings are your assertions, restated in the verdict's unverifiedAssertions field — and the licensed strategy stays advisory until a later phase verifies them. The laws field lists each declared law with its kind, obligation or page-obligation; a program with a FiniteObligation is refused.
Kind: ObligationsCheck. Family concurrency: MCP servers list it once api_tools opens that family. Origin: Yichus/Mcp::catalog.
CLI: yichus obligations — one implementation: both run ApiChecks.obligationsJson with the same seed, runs and shrink budget; `law` runs the seeded checker alone, not the strategy selector.
Parameters
sources(required, array) — JSON array of {fileName, source} Bosatsu files including the laws and the Obligations binding.seed(optional, integer) — Optional run seed; the whole run replays from this one number (default 41).runs(optional, integer) — Optional generated inputs per obligation (default 200).shrink(optional, integer) — Optional shrink budget per counterexample (default 200).
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.
The enrollment fold with no declared obligations: serialized commit, and the next rung
Request
{
"sources": [
{
"fileName": "registration.bosatsu",
"source": "package Demo/Laws/Registration\n\n# The phase-1 driving fixture: a class-registration enrollment fold with\n# the over-enrollment bug, and the suggested floor Obligation against it.\n#\n# The bug, faithfully naive: each registration is checked against the\n# ORIGINAL seat count instead of the running one, so with one seat left in\n# swim-101 both dana and evan pass the check and the count lands at -1.\n# `yichus law` (phase 1) finds this by seeded generation and shrinks the\n# witness to two registrations; the fixed fold checks `acc` instead of\n# `seats`.\n#\n# The witness is a WitnessTodo — the suggester's typed named hole — because\n# the roster carries only remaining seat counts, so \"was anyone enrolled?\"\n# cannot be derived from the result type.\n\nfrom Yichus/Law import (\n Domain, Law, Obligation, WitnessTodo, FoldRun,\n never_below, size_List\n)\n\nexport (Registration(), enroll, seats_after, gen_run, registration_runs, seats_floor)\n\nexposes (Yichus/Law)\n\nstruct Registration(student: String, class_id: String)\n\ndef seat_count(seats: Dict[String, Int], class_id: String) -> Int:\n match get_key(seats, class_id):\n case Some(n): n\n case None: 0\n\ndef positive(n: Int) -> Bool:\n cmp_Int(n, 0) matches GT\n\n# NAIVE: the guard reads `seats` (the opening counts), not `acc` (the\n# running counts). That is the over-enrollment bug this fixture exists to\n# demonstrate.\ndef enroll(seats: Dict[String, Int], regs: List[Registration]) -> Dict[String, Int]:\n def step(acc: Dict[String, Int], reg: Registration) -> Dict[String, Int]:\n Registration(_, class_id) = reg\n match positive(seat_count(seats, class_id)):\n case True: acc.add_key(class_id, sub(seat_count(acc, class_id), 1))\n case False: acc\n regs.foldl_List(seats, step)\n\ndef seats_after(run: FoldRun[Dict[String, Int], Registration]) -> List[Int]:\n FoldRun(initial, ops, _) = run\n roster = enroll(initial, ops)\n ops.map_List(reg -> (\n Registration(_, class_id) = reg\n seat_count(roster, class_id)\n ))\n\ndef describe_reg(reg: Registration) -> String:\n Registration(student, class_id) = reg\n concat_String([\"register(\", student, \" -> \", class_id, \")\"])\n\ndef describe_run(run: FoldRun[Dict[String, Int], Registration]) -> String:\n FoldRun(_, ops, shuffle) = run\n ops_str = match ops.map_List(describe_reg):\n case []: \"no registrations\"\n case [head, *tail]:\n tail.foldl_List(head, (acc, part) -> concat_String([acc, \"; \", part]))\n concat_String([\n \"run of \", int_to_String(size_List(ops)),\n \" registration(s), shuffle \", int_to_String(shuffle),\n \": \", ops_str\n ])\n\n# Seeded generator for runs. Dict is an external type, so the checker's\n# type-driven default generation cannot build one — the Domain carries its\n# own gen, which is the override path a constrained domain always needs.\n# Small bounds keep counterexamples readable; the oversell shape (one seat,\n# two registrations into the same class) is reachable from many seeds.\ndef pick_class(n: Int) -> String:\n match eq_Int(mod_Int(n, 2), 0):\n case True: \"swim-101\"\n case False: \"yoga-201\"\n\ndef gen_run(seed: Int) -> FoldRun[Dict[String, Int], Registration]:\n swim_seats = mod_Int(seed, 3)\n yoga_seats = mod_Int(div(seed, 3), 4)\n op_count = add(1, mod_Int(div(seed, 12), 6))\n base = empty_Dict(string_Order)\n with_swim = base.add_key(\"swim-101\", swim_seats)\n initial = with_swim.add_key(\"yoga-201\", yoga_seats)\n ops = range(op_count).map_List(i ->\n Registration(\n concat_String([\"s\", int_to_String(i)]),\n pick_class(add(seed, i))\n )\n )\n FoldRun(initial, ops, seed)\n\nregistration_runs = Domain(\"registration runs\", describe_run, Some(gen_run), None)\n\nseats_floor = Obligation(\n never_below(\n \"no class's remaining seats go below 0\",\n registration_runs,\n seats_after,\n 0\n ),\n [\n WitnessTodo(\n \"someone is enrolled\",\n \"the roster carries only remaining seat counts; extend it to record enrollments, or write this predicate against what it does expose\"\n )\n ]\n)\n"
}
]
}
Response
{
"ok": true,
"tool": "api_obligations",
"strategy": "serialized-commit",
"strategyDescription": "bounded interleaving exploration; every commit is serialized",
"gating": "advisory: no engine behavior changes with the licensed strategy; a future gating phase must first verify the assertions in unverifiedAssertions",
"licensedBy": "nothing discharged",
"unverifiedAssertions": null,
"declared": false,
"laws": [
{
"binding": "Demo/Laws/Registration::seats_floor",
"kind": "obligation"
}
],
"ladder": [
{
"obligation": "distinct-key-commutativity",
"laws": [],
"verdicts": [],
"discharged": false,
"reason": "no laws declared for this obligation"
},
{
"obligation": "per-op-monotonicity",
"laws": [],
"verdicts": [],
"discharged": false,
"reason": "no laws declared for this obligation"
},
{
"obligation": "declared-lattice",
"laws": [],
"verdicts": [],
"discharged": false,
"reason": "no laws declared for this obligation"
},
{
"obligation": "non-monotone-witness",
"laws": [],
"verdicts": [],
"discharged": false,
"reason": "no laws declared for this obligation"
}
],
"missing": {
"obligation": "distinct-key-commutativity",
"sentence": "Your commit is serialized because I cannot tell that two operations on different keys are independent. Declare and check a distinct-key commutativity law; if it holds, checking explores per-key interleavings instead of every global ordering.",
"snippet": "# 1. declare the law in its own file (api_suggest_properties drafts it\n# from your fold, imports included)\n# 2. name it in this Obligations binding:\nfrom Yichus/Law import Obligations, Discharge, DistinctKeyCommutativity\nobligations = Obligations([\n Discharge(DistinctKeyCommutativity, [\"<law name here>\"]),\n])\n"
}
}
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.