Skip to content

feat(lane-graphs): add an interpreter, so the graphs are not prose wearing a schema - #113

Merged
MajorLift merged 1 commit into
MetaMask:jongsun/add/lane-graphsfrom
MajorLift:feat/lane-graph-executor
Aug 7, 2026
Merged

feat(lane-graphs): add an interpreter, so the graphs are not prose wearing a schema#113
MajorLift merged 1 commit into
MetaMask:jongsun/add/lane-graphsfrom
MajorLift:feat/lane-graph-executor

Conversation

@MajorLift

Copy link
Copy Markdown
Contributor

Stacked on #107 — targets jongsun/add/lane-graphs, not main.

What

The three .graph.json specs name an executor and nothing parses them. A run can skip a node and still describe itself as having followed the graph, because nothing holds the description to the file — which is the failure this package is about, one level up.

What it does and does not do

Worth being exact about, since overstating it would reproduce that failure.

The check, run and expect fields are natural language. No interpreter evaluates them and this one does not pretend to — a node's verdict is supplied by whoever ran it. Routing stays judgement, as the skill's own contract says.

What is mechanised is the part that was actually being skipped:

  • every node must carry a verdict
  • a pass must name its evidence — a pass with an empty evidence field is a claim about a run, which is refused everywhere else in this package
  • absent is a first-class outcome, reported rather than silently dropped
  • a ledger entry naming no node in the graph is an error, not ignored
  • a graph with an unanswered node cannot report complete

Structural validation refuses a graph missing a baseline or a prediction, those being the shape of every vacuous run: a treatment applied to nothing, or a result compared to no stated expectation.

Usage

graph-run.mjs <graph.json>                    validate structure
graph-run.mjs <graph.json> --scaffold         emit a blank ledger
graph-run.mjs <graph.json> --ledger <l.json>  check a filled-in ledger

Exit 0 = valid / every node answered and passing. Exit 1 = a node failed, is unanswered, or the ledger does not match the graph. Exit 2 = usage or parse error.

Controls

case exit
all three graphs, structure only 0
blank ledger (every node absent) 1
fully answered with evidence 0
one node silently removed 1 — UNANSWERED baseline
pass with empty evidence 1
ledger entry naming no graph node 1

node --test test/*.test.mjs — 61/61.

One note on those controls: an earlier version of them reported three false passes, because echo "$(printf ...) exit=$?" resets $? via the command substitution before it is read. The controls were measuring printf. Worth recording, given what this script is for.

…aring a schema

The three .graph.json specs name an `executor` and nothing parses them. A run
could skip a node and still describe itself as having followed the graph,
because nothing held the description to the file — which is the failure the
whole package is about, one level up.

What this can and cannot do is worth being exact about, since overstating it
would reproduce that failure. The check, run and expect fields are natural
language; no interpreter evaluates them and this one does not pretend to. A
node's verdict is supplied by whoever ran it.

What is mechanised is the part that was actually being skipped:

  - every node must carry a verdict
  - a pass must name its evidence, because a pass with an empty evidence field
    is a claim about a run, which is refused everywhere else in this package
  - `absent` is a first-class outcome, reported rather than silently dropped
  - a ledger entry naming no node in the graph is an error, not ignored
  - a graph with an unanswered node cannot report complete

Structural validation refuses a graph missing a baseline or a prediction,
those being the shape of every vacuous run: a treatment applied to nothing, or
a result compared to no stated expectation.

  graph-run.mjs <graph.json>                    validate structure
  graph-run.mjs <graph.json> --scaffold         emit a blank ledger
  graph-run.mjs <graph.json> --ledger <l.json>  check a filled-in ledger

Controls: all three graphs validate; blank ledger exit 1; fully answered exit
0; one node silently removed exit 1; pass with empty evidence exit 1; unknown
ledger entry exit 1.
@MajorLift
MajorLift merged commit 65079f6 into MetaMask:jongsun/add/lane-graphs Aug 7, 2026
28 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant