Yichus / Reference / API MCP tools
api_verify
Rerun the available safety checks from the typed IR of the given Bosatsu sources. Reports which properties still hold after edits. Topology is an input: undeclared defaults to multi-instance, where RMW and interleaving findings are violations. When the sources declare a Yichus/Organize AbstractionSpec or GroupSpec, the declared-structure property checks every declared claim the way api_organize's abstractions and layers lenses do: proven when all converge, violated when any declared claim diverges (a generator that does not hold its declared guard responsibility, a member that does not use its generator, or a package that uses a group its GroupSpec does not allow; the claim is named with its location), blocked when a declared generator, member, concept or package is absent or the declarations cannot be evaluated, and a warning when a GroupSpec allows a use the code never makes. Sources with no such declaration get no declared-structure property. operation-coverage checks that the storage checks saw every table operation in the program's own code: blocked names each one they did not (no site was extracted for it, its table is not a literal name or a top-level stored_table value, the primitive is passed or bound as a value instead of called, or it runs inside a helper or a closure a helper returns, where no read-then-write check pairs it with the caller's reads), and rmw-transactions and integrity block with it. Fix one by calling the primitive where it runs, in the handler or the transaction plan, on a table named by a literal or a top-level stored_table value. A warning means the program performs no storage operations. lost-edits checks, across requests, that no save replaces a field of a shared row unchecked: blocked names each route whose save could drop an edit saved since its caller read the row, with its next step (usually a version the request sends, compared with eq_Int and raised with add(version, 1) in the writing transaction); it is the same at every topology, so instances: 1 does not change it. Warnings do not make proven false unless block_on_warnings lists them. Do not deploy unless proven is true.
Kind: Verify. Core: MCP servers list it from the start. Origin: Yichus/Mcp::catalog.
CLI: yichus api verify — the same safety proof over the same sources; the tool's instances and block_on_warnings arguments are the CLI's --instances and --block-on-warning flags.
Parameters
sources(required, array) — JSON array of {fileName, source} Bosatsu files for the API module.instances(optional, string) — Deployment topology: 1 for a single engine instance, many (default) for multiple instances sharing one DB. It changes the read-modify-write and interleaving findings, never lost-edits.block_on_warnings(optional, array) — Optional JSON array of property ids (for example ["rmw-transactions", "integrity"]) or ["all"]. An id must name a property this verdict has; declared-structure exists only when the sources declare a spec; use all to block every warning whatever the program declares. A listed property whose status is warning makes proven false, as a violation would; its own status stays warning, and the verdict's blockedWarnings field names it. An id that names no property of this verdict is refused (ok false, errorKind invalid-arguments). Left out, warnings do not block.
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 notes specimen
Request
{
"sources": [
{
"fileName": "notes-api.bosatsu",
"source": "package Demo/Service/NotesApi\n\n# Owner-scoped notes API. One row per caller, keyed by Principal.user_id.\n# `yichus api verify` / api_access_check prove the scoping from Matchless IR.\n\nfrom Yichus/IO import IO, flat_map\nfrom Yichus/Access import Principal, AccessRule, AccessSpec, OwnerScoped\nfrom Yichus/Data import Db, Table, table, db_read, db_write, db_delete\nfrom Yichus/Service import handler, route, service_def, ReadPerm, WritePerm, DeletePerm\n\nexport (notes_api, access_rules, Note())\nexposes (Yichus/Access, Yichus/Service)\n\nstruct Note(title: String)\n\naccess_rules = AccessSpec([\n AccessRule(\"notes\", OwnerScoped),\n])\n\ndef notes_table(db: Db) -> Table[List[Note]]:\n table(db, \"notes\")\n\ndef list_notes(db: Db, p: Principal) -> IO[List[Note]]:\n Principal(uid, _) = p\n db_read(notes_table(db), uid)\n\ndef put_notes(db: Db, p: Principal, items: List[Note]) -> IO[List[Note]]:\n Principal(uid, _) = p\n db_write(notes_table(db), uid, items)\n\ndef add_note(db: Db, p: Principal, item: Note) -> IO[List[Note]]:\n Principal(uid, _) = p\n items <- flat_map(db_read(notes_table(db), uid))\n db_write(notes_table(db), uid, [item, *items])\n\ndef clear_notes(db: Db, p: Principal) -> IO[Unit]:\n Principal(uid, _) = p\n db_delete(notes_table(db), uid)\n\nnotes_api = service_def(\n \"notes\",\n [\n route(\"/notes\", handler(\"list_notes\", list_notes), [ReadPerm(\"notes\")]),\n route(\"/notes/put\", handler(\"put_notes\", put_notes), [WritePerm(\"notes\")]),\n route(\"/notes/add\", handler(\"add_note\", add_note), [ReadPerm(\"notes\"), WritePerm(\"notes\")]),\n route(\"/notes/clear\", handler(\"clear_notes\", clear_notes), [DeletePerm(\"notes\")]),\n ]\n)\n"
}
],
"instances": "1"
}
Response
{
"proven": true,
"ok": true,
"tool": "api_verify",
"topology": "single-instance",
"verdict": {
"artifactClass": "api-safety-1.0",
"schemaVersion": "api-safety-1.0",
"sources": {
"hash": "246f6f0eb42eff551b73f10f1fb86d539c9cdb5d979e980d5bc67f079d7b77c3",
"files": [
{
"name": "notes_api",
"sha256": "fc78988841dc4584fb3dce5d210bb363af6c7cf40553bdbc3ed1ebde53009d08"
}
]
},
"proven": true,
"properties": [
{
"id": "compiles",
"title": "Parses and type-checks",
"status": "proven",
"details": []
},
{
"id": "access-spec-declared",
"title": "Access rules declared or storage absence established",
"status": "proven",
"details": [
"notes: OwnerScoped"
]
},
{
"id": "access-coverage",
"title": "Every DB operation covered by a declared rule",
"status": "proven",
"details": []
},
{
"id": "operation-coverage",
"title": "Every table operation is seen by the checks",
"status": "proven",
"details": [
"5 table operation(s) in the program's own code, each extracted as an IO site on an established table and attributed to the code that runs it"
]
},
{
"id": "access:notes",
"title": "\"notes\": each user reads and writes only their own rows",
"status": "proven",
"details": [
"Demo/Service/NotesApi::list_notes db_read on \"notes\": key derives from the authenticated Principal (user_id or owner_key)",
"Demo/Service/NotesApi::put_notes db_write on \"notes\": key derives from the authenticated Principal (user_id or owner_key)",
"Demo/Service/NotesApi::add_note db_read on \"notes\": key derives from the authenticated Principal (user_id or owner_key)",
"Demo/Service/NotesApi::add_note db_write on \"notes\": key derives from the authenticated Principal (user_id or owner_key)",
"Demo/Service/NotesApi::clear_notes db_delete on \"notes\": key derives from the authenticated Principal (user_id or owner_key)"
]
},
{
"id": "route-permissions",
"title": "Route permissions match handler effects",
"status": "proven",
"details": [
"/notes -> list_notes: match",
"/notes/put -> put_notes: match",
"/notes/add -> add_note: match",
"/notes/clear -> clear_notes: match"
]
},
{
"id": "route-authority",
"title": "Route authority declarations are enforceable",
"status": "proven",
"details": [
"/notes: authenticated",
"/notes/add: authenticated",
"/notes/clear: authenticated",
"/notes/put: authenticated"
]
},
{
"id": "rmw-transactions",
"title": "Handlers that read then write cannot lose updates within one request",
"status": "warning",
"details": [
"Demo/Service/NotesApi::add_note reads then writes \"notes\"; with multiple instances on one DB, run this handler in a transaction (or a single-writer queue) to avoid lost updates (accepted: instances=1 declared; one instance runs each request's IO plan atomically)"
],
"accepted": "instances=1"
},
{
"id": "lost-edits",
"title": "A save cannot drop an edit saved since its caller read the row",
"status": "proven",
"details": [
"/notes/add (add_note): overwrites only \"notes\" is OwnerScoped with access proven: no other caller writes its rows",
"/notes/put (put_notes): overwrites only \"notes\" is OwnerScoped with access proven: no other caller writes its rows",
"no save replaces a stored field, unchecked, with a value not made from what is stored there, over the 2 route(s) that can write a present row (0 write(s) examined); scope: across requests; a read and a write inside one request are rmw-transactions' finding"
]
},
{
"id": "integrity",
"title": "Interleaving the program's own table operations keeps its invariants",
"status": "warning",
"details": [
"race-free:notes: 6 valid orderings over 'notes' produce differing effect sequences (accepted: instances=1 declared; one instance runs each request's IO plan atomically)"
],
"accepted": "instances=1"
}
],
"errors": []
},
"narrative": "'Parses and type-checks' is proven, where proven means established by a known-good method for every input.\n'Access rules declared or storage absence established' is proven. Details: notes: OwnerScoped.\n'Every DB operation covered by a declared rule' is proven.\n'Every table operation is seen by the checks' is proven. Details: 5 table operation(s) in the program's own code, each extracted as an IO site on an established table and attributed to the code that runs it.\n'\"notes\": each user reads and writes only their own rows' is proven. Details: Demo/Service/NotesApi::list_notes db_read on \"notes\": key derives from the authenticated Principal (user_id or owner_key); Demo/Service/NotesApi::put_notes db_write on \"notes\": key derives from the authenticated Principal (user_id or owner_key); Demo/Service/NotesApi::add_note db_read on \"notes\": key derives from the authenticated Principal (user_id or owner_key); Demo/Service/NotesApi::add_note db_write on \"notes\": key derives from the authenticated Principal (user_id or owner_key); Demo/Service/NotesApi::clear_notes db_delete on \"notes\": key derives from the authenticated Principal (user_id or owner_key).\n'Route permissions match handler effects' is proven. Details: /notes -> list_notes: match; /notes/put -> put_notes: match; /notes/add -> add_note: match; /notes/clear -> clear_notes: match.\n'Route authority declarations are enforceable' is proven. Details: /notes: authenticated; /notes/add: authenticated; /notes/clear: authenticated; /notes/put: authenticated.\n'Handlers that read then write cannot lose updates within one request' is warning, where warning means established only under a disclosed acceptance, which the details name. Details: Demo/Service/NotesApi::add_note reads then writes \"notes\"; with multiple instances on one DB, run this handler in a transaction (or a single-writer queue) to avoid lost updates (accepted: instances=1 declared; one instance runs each request's IO plan atomically).\n'A save cannot drop an edit saved since its caller read the row' is proven. Details: /notes/add (add_note): overwrites only \"notes\" is OwnerScoped with access proven: no other caller writes its rows; /notes/put (put_notes): overwrites only \"notes\" is OwnerScoped with access proven: no other caller writes its rows; no save replaces a stored field, unchecked, with a value not made from what is stored there, over the 2 route(s) that can write a present row (0 write(s) examined); scope: across requests; a read and a write inside one request are rmw-transactions' finding.\n'Interleaving the program's own table operations keeps its invariants' is warning. Details: race-free:notes: 6 valid orderings over 'notes' produce differing effect sequences (accepted: instances=1 declared; one instance runs each request's IO plan atomically)."
}
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.