Yichus / Reference / API MCP tools
api_law_check
Check declared Yichus/Law obligations. Mode sampled (default) uses seeded generation: holds is bounded observation, never proof. Mode exhaustive checks every value of an accepted finite type or every distinct value of a Bosatsu FiniteObligation list; holds-exhaustive says every value of the type held, and holds-on-listed says only the listed values were checked. A PageObligation names input ids of the data app page in the sources (its .sim.bosatsu config): sampled mode draws its inputs only from what the page's controls can enter and counts them out of the page's cases, and exhaustive mode checks every such case when they fit maximum, answering holds-on-page (every input the page allows, nothing beyond); either way a counterexample is a case the page allows. Unsupported domains, exceeded limits, unfinished witnesses, and worker failures never become a pass. Violated and inconclusive both mean not done. When the program declares routes, reach lists, for each law whose check it could read, the routes that reach what that check calls; a law listed with no routes is one no route of the service calls, and a law left out of reach was not compared.
Kind: LawCheck. Core: MCP servers list it from the start. Origin: Yichus/Mcp::catalog.
CLI: yichus law — sampled and finite exhaustive laws; use `yichus law --mode exhaustive` for a killable JVM worker (generic JVM `call` refuses that mode); MCP and WebMCP run the shared checker in killable workers.
Parameters
sources(required, array) — JSON array of {fileName, source} Bosatsu files including the Obligation bindings.module_name(optional, string) — Optional module name for the verdict artifact (default Laws).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).mode(optional, string) — sampled (default) or exhaustive; exhaustive never falls back to a seeded pass.maximum(optional, integer) — Maximum finite inputs per obligation in exhaustive mode, a page's cases included (default 256, hard cap 4096).
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 law that holds on every sampled input
Request
{
"sources": [
{
"fileName": "lean-bool.bosatsu",
"source": "package Demo/Laws/LeanBool\n\nfrom Yichus/Law import Domain, Law, Obligation, Witness\n\nexport (all_bools)\nexposes (Yichus/Law)\n\ndef show(value: Bool) -> String:\n match value:\n case True: \"true\"\n case False: \"false\"\n\ndef always(value: Bool) -> Bool:\n match value:\n case True: True\n case False: True\n\ndef is_true(value: Bool) -> Bool: value\n\ndomain = Domain(\"both booleans\", show, None, None)\nall_bools = Obligation(\n Law(\"always holds\", domain, always),\n [Witness(\"true exists\", is_true)]\n)\n"
}
]
}
Response
{
"ok": true,
"tool": "api_law_check",
"mode": "sampled",
"method": "sampled",
"runs": 200,
"laws": {
"artifactClass": "law-verdict",
"schemaVersion": "law-verdict-1.0",
"sources": {
"hash": "6d5fa0069b0c2ffdf7c65b1d81c3a10666ee5917a4c1de843fb759809b2e3e81",
"files": [
{
"name": "lean_bool",
"sha256": "f31477d72de6dfaf81a6930aa0ef3bb6d2d565b1b22b892b7230665f817c71c1"
}
]
},
"module": "Laws",
"method": "sampled",
"counts": {
"obligations": 1,
"holds": 1,
"violated": 0,
"inconclusive": 0
},
"obligations": [
{
"binding": "Demo/Laws/LeanBool::all_bools",
"law": "always holds",
"domain": "both booleans",
"location": "lean_bool:21:13",
"verdict": "holds",
"detail": "bounded: 200 seeded inputs (seed 41); bounded observation, not proof",
"method": "sampled",
"runs": 200,
"seed": 41,
"witnesses": [
{
"name": "true exists",
"status": "satisfied"
}
]
}
]
},
"allHold": true
}
An enrollment fold that over-enrolls: the seat floor is violated
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_law_check",
"mode": "sampled",
"method": "sampled",
"runs": 200,
"laws": {
"artifactClass": "law-verdict",
"schemaVersion": "law-verdict-1.0",
"sources": {
"hash": "adeadb799a4e1d2f159a58b1c5789982aa5df4d21a7728ce77915ce6ce427bd4",
"files": [
{
"name": "registration",
"sha256": "21b4100a61b09378bedab10b37af4ee77da6899218e95706fb9e00f6c0afaf24"
}
]
},
"module": "Laws",
"method": "sampled",
"counts": {
"obligations": 1,
"holds": 0,
"violated": 1,
"inconclusive": 0
},
"obligations": [
{
"binding": "Demo/Laws/Registration::seats_floor",
"law": "no class's remaining seats go below 0",
"domain": "registration runs",
"location": "registration:98:15",
"verdict": "violated",
"detail": "bounded: 3 seeded inputs (seed 41), first failure at run 2, shrunk by 8 reduction(s)",
"shrinkBudgetCut": false,
"counterexample": "run of 2 registration(s), shuffle 0: register(s1 -> swim-101); register(s3 -> swim-101)",
"method": "sampled",
"runs": 3,
"seed": 41,
"witnesses": [
{
"name": "someone is enrolled",
"status": "todo",
"why": "the roster carries only remaining seat counts; extend it to record enrollments, or write this predicate against what it does expose"
}
]
}
]
},
"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.