feat(lane-graphs): add an interpreter, so the graphs are not prose wearing a schema - #113
Merged
MajorLift merged 1 commit intoAug 7, 2026
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #107 — targets
jongsun/add/lane-graphs, notmain.What
The three
.graph.jsonspecs name anexecutorand 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,runandexpectfields 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:
passmust name its evidence — a pass with an empty evidence field is a claim about a run, which is refused everywhere else in this packageabsentis a first-class outcome, reported rather than silently droppedStructural validation refuses a graph missing a
baselineor aprediction, those being the shape of every vacuous run: a treatment applied to nothing, or a result compared to no stated expectation.Usage
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
absent)UNANSWERED baselinepasswith empty evidencenode --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 measuringprintf. Worth recording, given what this script is for.