Guide
Explorer queries over typed Matchless IR
Explorer reads a compiled Bosatsu program as a graph of bindings, IO sites and dependencies, so you can ask where an output's value really comes from. It never runs the program.
Code & run Run the two order functions
Try it in the browser playground.
Literal-root and return-data signals distinguish two dataflows
Both outputs are well typed, but only one comes from a state read.
State read with return-data provenance
counter: IO[State[Int]] = state(0)
def read_counter() -> IO[Int]:
c <- counter.flat_map()
read(c)
current: IO[Int] = read_counter()
return-data: the compiled model contains a potential data path from a state read to the output.
Constant with literal-root provenance
fabricatedTotal = 42
response = fabricatedTotal
literal-root: the output comes entirely from hardcoded constants.
Trace upstream dependencies from an output binding
A trace follows an output back through the bindings it depends on. Each binding carries:
- Role
-
What the binding does:
terminal-io(observable output),state-init(creates a state cell),intermediate-io(reads and feeds downstream), orpure(no IO). - Signal tags
-
Structural flags:
dead-input(a read that never reaches the output),guard-only-arg(argument used only as a branch selector),literal-root(output from constants only). - Read provenance
-
For each state read: does it reach the output as
return-data, only as aguard-onlybranch condition, or is itdetachedentirely? - Argument influence
- For each function argument: does it flow through as data, or is it only used as a guard?
Compile a structural check as a Bosatsu query
A query is a Bosatsu function over the program's facts that returns a label and evidence, so the same check runs on every target.
Query that classifies upstream derivation
package MyCheck
from Yichus/Explorer/Query import (
DeadInput,
ClassifyResult, ProgramData,
classify_result, has_any_io,
terminal_io_without_deps,
bindings_with_signal,
)
def classify(data: ProgramData) -> ClassifyResult:
match has_any_io(data):
case False:
classify_result("pure-computation",
["pure computation, no IO"])
case True:
no_deps = terminal_io_without_deps(data)
match no_deps:
case [_, *_]:
classify_result("no-upstream-derivation",
["output has no upstream derivation"])
case []:
dead = bindings_with_signal(data, DeadInput)
match dead:
case [_, *_]:
classify_result("dead-input-detected",
["reads that never reach the output"])
case []:
classify_result("upstream-derivation-present",
["real upstream derivation"])
eval/queries/.
Explorer operations and their graph questions
Eight operations, each for a different question.
| When you want to… | Use | CLI |
|---|---|---|
| Get a high-level picture | overview |
--overview |
| Navigate the binding graph | explore |
--path --depth |
| See what feeds or depends on a binding | connections |
--connections |
| Find bindings matching a pattern | search |
--search |
| Understand how two bindings relate | path |
--path-from <from> --path-to <to> |
| See the full upstream tree with provenance | trace |
--trace |
| Get raw edges for scripting | trace_flow |
--trace-flow |
| Automate the entire investigation | query |
--query |
Run the six Explorer sample programs
Each sample is in the playground; pick one and click Analyze.
| File | What it demonstrates |
|---|---|
trustworthy-counter.bosatsu |
State reads whose values reach the output |
suspicious-fabrication.bosatsu |
IO is declared while the output remains constant-derived |
dead-inputs.bosatsu |
A state read that never reaches the output, a dead input |
mixed-trust.bosatsu |
A state-read path alongside a constant summary binding |
pure-computation.bosatsu |
No IO sites, only pure arithmetic |
permission-leak-demo.bosatsu |
A secret reaches the export without flowing through the permission gate |
Ask your agent about anything here; it has the detail.
Where this fits
What this is about: Fact Tooling