Yichus / Reference / API MCP tools
api_conformance_check
Check declared Yichus/Spec Conformance and WorldConformance bindings by execution: the compiled handler runs in a real seeded world over generated inputs (one table for Conformance; every table, as one of the declared callers, for WorldConformance), and the declared step is compared against the projected world after every operation. Three-valued verdicts (holds is bounded observation, never proof); divergences render through the declaration's own describe and show_input, and name the caller in the world form. Violated and inconclusive both mean not done.
Kind: ConformanceCheck. Family proofs: MCP servers list it once api_tools opens that family. Origin: Yichus/Mcp::catalog.
CLI: yichus conformance — the same conformance check by execution.
Parameters
sources(required, array) — JSON array of {fileName, source} Bosatsu files including the Conformance or WorldConformance bindings.module_name(optional, string) — Optional module name for the verdict artifact (default Conformance).seed(optional, integer) — Optional run seed; the whole run replays from this one number (default 41).trajectories(optional, integer) — Optional fresh-world trajectories per conformance (default 20).ops(optional, integer) — Optional operations per trajectory (default 10).
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 deposit handler that matches its declared model
Request
{
"sources": [
{
"fileName": "ledger.bosatsu",
"source": "package Demo/Conformance/Ledger\n\n# The conformance driving demo: a deposit handler and a declared model of\n# its effect on the ledger table. `deposit` appends an entry per call\n# (db_create generates a fresh id), so the model state is the running\n# total and one operation's step adds its amount. `yichus conformance`\n# (or api_conformance_check) runs the compiled handler in a seeded world\n# over generated amounts and compares the table's projected total against\n# the declared step after every operation.\n\nfrom Yichus/IO import IO\nfrom Yichus/Access import Principal, AccessRule, AccessSpec, OwnerScoped\nfrom Yichus/Data import Db, Table, table, db_create\nfrom Yichus/Service import handler\nfrom Yichus/Spec import Conformance\n\nexport (deposit, ledger_model, access_rules, Entry())\n\nexposes (Yichus/IO, Yichus/Data, Yichus/Spec, Yichus/Access)\n\nstruct Entry(amount: Int)\n\naccess_rules = AccessSpec([\n AccessRule(\"ledger\", OwnerScoped),\n])\n\ndef ledger(db: Db) -> Table[Entry]:\n table(db, \"ledger\")\n\ndef deposit(db: Db, p: Principal, amount: Int) -> IO[Entry]:\n Principal(uid, _) = p\n _ = uid\n db_create(ledger(db), Entry(amount))\n\ndef total(rows: List[Entry]) -> Int:\n rows.foldl_List(0, (acc, e) -> (\n Entry(a) = e\n add(acc, a)\n ))\n\nledger_model = Conformance(\n \"ledger total\",\n \"ledger\",\n [],\n 0,\n int_to_String,\n int_to_String,\n total,\n eq_Int,\n handler(\"deposit\", deposit),\n (t, a) -> add(t, a)\n)\n"
}
]
}
Response
{
"ok": true,
"tool": "api_conformance_check",
"conformance": {
"artifactClass": "conformance-verdict",
"schemaVersion": "conformance-verdict-1.0",
"sources": {
"hash": "bd6f075589bc210cb336a63ab8d0d1fbdcef7c189f2091752d30cfca9cd7287b",
"files": [
{
"name": "ledger",
"sha256": "b44bdfae8e0aa4a8de5b3b21336d231c52d76b212411b0deca10831d27766b94"
}
]
},
"module": "Conformance",
"counts": {
"conformances": 1,
"holds": 1,
"violated": 0,
"inconclusive": 0
},
"conformances": [
{
"binding": "Demo/Conformance/Ledger::ledger_model",
"name": "ledger total",
"form": "Conformance",
"resource": "ledger",
"handler": "deposit (Demo/Conformance/Ledger::deposit)",
"location": "ledger:41:16",
"verdict": "holds",
"detail": "bounded: 200 seeded inputs over 20 trajectories (seed 41); bounded observation, not proof"
}
]
},
"allHold": true
}
The near-miss twin: the declared step drifted from the handler
Request
{
"sources": [
{
"fileName": "ledger-drifted.bosatsu",
"source": "package Demo/Conformance/LedgerDrifted\n\n# The drifted twin of the ledger conformance demo: the handler appends\n# each deposit's amount, but the declared step over-counts by one — the\n# kind of quiet model drift conformance checking exists to catch. The\n# checker reports the divergence at the first operation, rendered in\n# domain terms through the declaration's own describe and show_input.\n\nfrom Yichus/IO import IO\nfrom Yichus/Access import Principal, AccessRule, AccessSpec, OwnerScoped\nfrom Yichus/Data import Db, Table, table, db_create\nfrom Yichus/Service import handler\nfrom Yichus/Spec import Conformance\n\nexport (deposit, ledger_model, access_rules, Entry())\n\nexposes (Yichus/IO, Yichus/Data, Yichus/Spec, Yichus/Access)\n\nstruct Entry(amount: Int)\n\naccess_rules = AccessSpec([\n AccessRule(\"ledger\", OwnerScoped),\n])\n\ndef ledger(db: Db) -> Table[Entry]:\n table(db, \"ledger\")\n\ndef deposit(db: Db, p: Principal, amount: Int) -> IO[Entry]:\n Principal(uid, _) = p\n _ = uid\n db_create(ledger(db), Entry(amount))\n\ndef total(rows: List[Entry]) -> Int:\n rows.foldl_List(0, (acc, e) -> (\n Entry(a) = e\n add(acc, a)\n ))\n\nledger_model = Conformance(\n \"ledger total\",\n \"ledger\",\n [],\n 0,\n int_to_String,\n int_to_String,\n total,\n eq_Int,\n handler(\"deposit\", deposit),\n (t, a) -> add(t, add(a, 1))\n)\n"
}
]
}
Response
{
"ok": true,
"tool": "api_conformance_check",
"conformance": {
"artifactClass": "conformance-verdict",
"schemaVersion": "conformance-verdict-1.0",
"sources": {
"hash": "3cae34200f294ab1e68f9e44448d1e2ab9bdef47d5ffdd0c4e5366bf05b5cdec",
"files": [
{
"name": "ledger_drifted",
"sha256": "5ba10d1f93c57c2bc7e41c07e122639ef93c29995ce470b4270cc0ec12892f1e"
}
]
},
"module": "Conformance",
"counts": {
"conformances": 1,
"holds": 0,
"violated": 1,
"inconclusive": 0
},
"conformances": [
{
"binding": "Demo/Conformance/LedgerDrifted::ledger_model",
"name": "ledger total",
"form": "Conformance",
"resource": "ledger",
"handler": "deposit (Demo/Conformance/LedgerDrifted::deposit)",
"location": "ledger_drifted:39:16",
"verdict": "violated",
"detail": "bounded: 1 seeded inputs (seed 41), divergence at trajectory 0, operation 0",
"input": "-15",
"predicted": "-14",
"actual": "-15"
}
]
},
"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.