Guide

Explorer

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.

1

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.

2

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), or pure (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 a guard-only branch condition, or is it detached entirely?
Argument influence
For each function argument: does it flow through as data, or is it only used as a guard?
3

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"])
Explorer reports facts; the query defines policy. Reference queries ship in eval/queries/.
4

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
5

Run the six Explorer sample programs

Each sample is in the playground; pick one and click Analyze.

FileWhat 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