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

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.