Yichus / Reference / API MCP tools
api_verify_claims
Check an agent's claims about a program against the program's own facts. Each claim gets a three-valued verdict with the evidence that decided it; absence claims are backed by the agenda's enumeration, so "zero cards in scope" carries the examined count as its evidence. A refuted claim is a successful check that found something -- the call stays ok and the refuted field says so. Use this before reporting a finding, not after. Same job as yichus verify-claims, which reads the claims from a file and turns refutals into a nonzero exit code.
Kind: VerifyClaims. Family proofs: MCP servers list it once api_tools opens that family. Origin: Yichus/Mcp::catalog.
CLI: yichus verify-claims — one implementation: both run ClaimVerifier.verify over the same workspace; the CLI reads the claims from a file and turns refutals into a nonzero exit code, the tool takes them as a parameter and answers refuted; the declared entry packages are --entry on the CLI and entries on the tool.
Parameters
sources(required, array) — JSON array of {fileName, source} Bosatsu files the claims are about.claims(required, object) — JSON object (or encoded JSON string) with a claims array, each claim an object with a kind and that kind's fields, e.g. {"kind": "dead-field", "package": "My/Pkg", "struct": "Order", "field": "memo"}. api_guide section "Checking claims" lists every kind and its fields.entries(optional, array) — Optional JSON array of the program's entry package names, e.g. ["Demo/App"], the unused-export premise as in api_explore's agenda: declared, unused-export cards are drawn and claims about them are decided; absent, they are not drawn and such a claim is not-provable. A name that is not a supplied package fails the call.
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.
Three claims about the pricing module, one of them wrong
Request
{
"sources": [
{
"fileName": "pricing.bosatsu",
"source": "package Demo/Pricing\n\nfrom Yichus/IO import IO, flat_map, pure\nfrom Yichus/UI import State, state, read, write\n\nexport (\n Order(),\n quote,\n shipping_fee,\n surge_bonus,\n order_id,\n order_qty,\n line_total,\n summary,\n fallback_quote,\n pick_quote,\n cell,\n refresh,\n reset\n)\n\nexposes (Yichus/IO, Yichus/UI)\n\n# The pricing module from the fact-tooling page, committed verbatim so\n# every command on that page runs against real, shipped code. It has\n# three real problems on purpose (a faked price, a dead field, a\n# guard that decides nothing) plus a branch that never wins in\n# practice — each one is caught by a different fact.\n\nstruct Order(id: Int, qty: Int, discount_code: Int)\n\ndef quote(o: Order) -> Int:\n _ = o\n 42\n\ndef shipping_fee(subtotal: Int, region: Int) -> Int:\n match cmp_Int(region, 0):\n case GT: add(subtotal, 5)\n case _: add(subtotal, 5)\n\ndef surge_bonus(x: Int) -> Int:\n match cmp_Int(x, 1000):\n case GT: x\n case _: 7\n\ndef order_id(o: Order) -> Int:\n Order(id, _, _) = o\n id\n\ndef order_qty(o: Order) -> Int:\n Order(_, qty, _) = o\n qty\n\ndef line_total(o: Order) -> Int:\n Order(id, qty, _) = o\n add(add(qty, qty), id)\n\ndef summary(o: Order) -> Int:\n quote(o)\n\ndef fallback_quote(x: Int) -> Int:\n add(x, 100)\n\ndef pick_quote(x: Int) -> Int:\n match cmp_Int(x, 999):\n case GT: fallback_quote(x)\n case _: x\n\ncell: IO[State[Int]] = state(0)\n\nrefresh: IO[Int] = (\n c <- cell.flat_map()\n _ <- c.read().flat_map()\n pure(7)\n)\n\nreset: IO[Unit] = (\n c <- cell.flat_map()\n c.write(9)\n)\n"
},
{
"fileName": "report.bosatsu",
"source": "package Demo/Report\n\nfrom Demo/Pricing import Order, quote\n\nexport (report_total)\n\nexposes (Demo/Pricing)\n\n# A consumer package: its call into quote is what the\n# discarded-argument and package-reach facts on the fact-tooling page\n# point at.\n\ndef report_total(o: Order) -> Int:\n quote(o)\n"
}
],
"claims": {
"claims": [
{
"kind": "literal-result",
"package": "Demo/Pricing",
"binding": "quote"
},
{
"kind": "no-detached-read",
"package": "Demo/Report"
},
{
"kind": "dead-field",
"package": "Demo/Pricing",
"struct": "Order",
"field": "qty"
}
]
}
}
Response
{
"ok": true,
"tool": "api_verify_claims",
"refuted": true,
"report": {
"claimCount": 3,
"refutedCount": 1,
"results": [
{
"kind": "literal-result",
"package": "Demo/Pricing",
"binding": "quote",
"status": "supported",
"evidence": "every value the result can take originates in literals"
},
{
"kind": "no-detached-read",
"package": "Demo/Report",
"status": "not-provable",
"evidence": "no read sites in Demo/Report (cell reads, db_read, db_query); zero examined sites is not evidence of a property"
},
{
"kind": "dead-field",
"package": "Demo/Pricing",
"struct": "Order",
"field": "qty",
"status": "refuted",
"evidence": "the field IS read, by: Demo/Pricing/line_total, Demo/Pricing/order_qty"
}
]
}
}
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.