`api_why`

Evaluate ONE binding on concrete typed inputs and report why the output is what it is. Pick the binding from a diagram or report by its Pkg/Name::binding id. Provide inputs as JSON (missing ones are seeded deterministically); the tool returns the typed inputs and output with named rendering, soundFacts (static dataflow: per-parameter influence that holds for EVERY input), and observed (bounded seeded runs: touched bindings, per-parameter and per-field vary-one-fix-rest differentials). soundFacts and observed are disjoint on purpose: an observed-constant result is NOT independence, and every observed sentence says 'bounded observation, not proof'. IO handlers run against a fresh in-memory world (optionally seeded via rows) and report the table rows after the run; handler differentials rebuild the world from the same seeded rows for every variation (a varied principal's roles against fixed rows flips a gated route).

Kind: Why. Origin: Yichus/Mcp::catalog.

CLI: yichus why — the same why engine; the CLI adds --record and --replay.

Parameters

sources (required, array) — JSON array of {fileName, source} Bosatsu files for the module.
binding (required, string) — The binding to evaluate, as Pkg/Name::binding (the id shown on diagrams and reports).
inputs (optional, object) — Optional JSON object {param: value} of provided inputs. Values use the same JSON encoding api types use; a nullary enum constructor is written {"Ctor": {}} (the form the tool prints), and the bare object of a constructor's fields is read too. Unlisted params are seeded from the seed.
seed (optional, integer) — Optional run seed; the whole run replays byte-identically from this one number (default 41).
observe (optional, boolean) — Optional; false skips the differential runs and returns only the evaluation plus soundFacts (default true).
variations (optional, integer) — Optional variations per differential axis (default 5).
rows (optional, object) — Optional JSON object {table: [row, ...]} seeding the in-memory world for an IO handler run.

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.