Structured Evidence Explanation
SEE is an approach for turning input facts into gated insights with human-readable explanations.
input facts -> rules -> trust gate -> insight + explanation
Each example is a small Node.js program:
examples/input/<name>.json contains the input facts.examples/<name>.js derives the insight and checks the trust gate.examples/output/<name>.md is the reference Markdown output used by npm test.examples/doc/<name>.md explains the example.The trust gate is executable verification. If a required fact is missing, the program fails instead of emitting an unsupported insight.
SEE was largely inspired by Prof. Ruben Verborgh’s essay Inside the Insight Economy.
Run all examples:
npm test
Run one example:
node examples/delfour.js
Generated N3 examples can also refresh their own generated artefacts:
node examples/my_example.js --write # writes examples/output/my_example.md and examples/doc/my_example.md
node examples/my_example.js --doc # prints examples/doc/my_example.md
Compare one output:
node examples/bmi.js > /tmp/bmi.md
diff -u examples/output/bmi.md /tmp/bmi.md
see.js is a small Notation3-to-JavaScript compiler. It parses a supported N3 subset once and writes a specialized Node.js example. The generated examples/<name>.js does the derivation itself: it contains compiled facts, compiled rules, fuses, built-in operations, fixpoint evaluation, and report rendering. It does not parse N3 at runtime and does not shell out to Eyeling or EYE.
Generate the four SEE artefacts from an N3 source:
node see.js generate path/to/example.n3 --name my_example
During generation, see.js writes the specialized runner and input sidecar first, then invokes the generated runner with --write. That generated examples/<name>.js is responsible for producing both examples/output/<name>.md and examples/doc/<name>.md.
Render an N3 source without writing files:
node see.js render path/to/example.n3
Check that the source is inside the supported compiler subset:
node see.js check path/to/example.n3
The compiler currently supports ordinary triples, semicolon/comma property lists, RDF lists, blank nodes, variable predicates, formula-valued conclusions, forward rules, recursive backward rules (<=), top-level log:query, => false fuses, and a broad native builtin registry for Eyeling-style math:, string:, list:, crypto:, time:, and log: predicates. The generated JavaScript covers multi-solution predicates such as list:member, list:in, list:iterate, list:memberAt, and list:map, plus relation-like reverse modes such as math:exponentiation, unary trig/degree relations, list:reverse, and list:append splitting. Offline dereferencing/parsing builtins (log:content, log:semantics, log:semanticsOrError, log:parsedAsN3) fail explicitly in generated SEE examples instead of doing network or parser work at runtime. Unsupported constructs fail rather than jumping directly to a prewritten log:outputString. When no authored log:outputString report is derived, the generated runner still emits a SEE-style report with Insight, Explanation, and Evidence sections instead of dumping the whole graph.
examples/
<name>.js executable example
_see.js shared helper
input/<name>.json input facts
output/<name>.md reference insight and explanation
doc/<name>.md guide
n3/<name>.n3 optional Notation3 source for generated examples
The repository currently contains 25 hand-written SEE examples and 25 generated N3 examples: 22 source-backed generated examples under examples/n3/, plus 3 legacy-named compiler regression snapshots. Generated examples are committed like the originals: each has an executable examples/<name>.js, an input sidecar, a reference output, and a documentation page. npm run generate regenerates the generated examples whose names match files under examples/n3/; the n3_* rows are legacy-named compiler regression snapshots that point at the same N3 sources.
| Example | Idea | Files |
|---|---|---|
| Bayes diagnosis | posterior probability from prior, likelihood, and evidence | doc, js, input, output |
| Bayes therapy | expected-utility ranking from Bayesian posteriors | doc, js, input, output |
| BMI | unit normalization, BMI category, and healthy-weight range | doc, js, input, output |
| Complex matrix stability | spectral-radius check for discrete-time stability | doc, js, input, output |
| Delfour | authorized, minimized shopping insight | doc, js, input, output |
| Digital product passport | component and footprint facts folded into a public passport decision | doc, js, input, output |
| Dijkstra risk path | shortest path with a risk penalty | doc, js, input, output |
| Eco route insight | local route insight without exporting raw logistics data | doc, js, input, output |
| Euler identity certificate | finite numerical certificate for exp(iπ)+1 | doc, js, input, output |
| EV roadtrip planner | fastest route that satisfies cost, time, and reliability limits | doc, js, input, output |
| FFT8 numeric | dominant frequency bins in eight samples | doc, js, input, output |
| Fibonacci | exact big-integer Fibonacci computation | doc, js, input, output |
| Fundamental theorem arithmetic | prime factors checked by reconstruction | doc, js, input, output |
| Genetic knapsack selection | deterministic one-bit mutation search, with local result and exhaustive optimum shown | doc, js, input, output |
| Goldbach 1000 | prime-sum witnesses for even numbers up to 1000 | doc, js, input, output |
| GPS route planning | route choice from duration, cost, belief, and comfort | doc, js, input, output |
| Gray code counter | 4-bit cycle with one-bit transitions | doc, js, input, output |
| Kaprekar 6174 | four-digit chains checked against the 6174 attractor | doc, js, input, output |
| ODRL + DPV risk ranking | policy clauses turned into ranked risks and mitigations | doc, js, input, output |
| Path discovery | bounded airport routes with at most two stopovers | doc, js, input, output |
| 8-Queens | one board plus the count of all 92 solutions | doc, js, input, output |
| RC discharge envelope | decay interval checked against a voltage tolerance | doc, js, input, output |
| School placement audit | assignment checked against route barriers and preferences | doc, js, input, output |
| Sudoku | puzzle solved by search, then checked against row, column, box, clue, and uniqueness constraints | doc, js, input, output |
| Wind turbine envelope | wind-speed intervals classified into energy output | doc, js, input, output |
| Example | Idea | Files |
|---|---|---|
| Annotation | generated from Notation3 by see.js; formula-valued annotation data with log:nameOf and typed literals. |
doc, js, input, output, n3 |
| Backward rule example | generated from Notation3 by see.js; Eyeling backward-rule example with a math:greaterThan guard. |
doc, js, input, output, n3 |
| Backward recursion coverage | generated from Notation3 by see.js; recursive <= ancestor rules compiled into JavaScript goal solving. |
doc, js, input, output, n3 |
| Builtin coverage smoke | generated from Notation3 by see.js; smoke test for compiled math, string, list, crypto, time, and log builtins. |
doc, js, input, output, n3 |
| Collection | generated from Notation3 by see.js; RDF collection/list data with a blank node inside the list. |
doc, js, input, output, n3 |
| Complex numbers | generated from Notation3 by see.js; complex arithmetic rules and formula-valued conclusion. |
doc, js, input, output, n3 |
| Composition of injective functions | generated from Notation3 by see.js; proof-style rules show that the composition of injective functions is injective. |
doc, js, input, output, n3 |
| Dog license example | generated from Notation3 by see.js; log:collectAllIn and math:sum derive that a multi-dog household needs a license. |
doc, js, input, output, n3 |
| Equals test | generated from Notation3 by see.js; N3 = / owl:sameAs shorthand compiled into a normal derivation. |
doc, js, input, output, n3 |
| Equivalence class overlap | generated from Notation3 by see.js; equivalence-relation closure proves overlapping equivalence classes are the same class. |
doc, js, input, output, n3 |
| Euler identity | generated from Notation3 by see.js; exact integer-style certificate for exp(i*pi) + 1 = 0 with log:query projection. |
doc, js, input, output, n3 |
| Existential rule | generated from Notation3 by see.js; rule-head blank nodes compile into deterministic existential witnesses. |
doc, js, input, output, n3 |
| Expression evaluator | generated from Notation3 by see.js; recursive backward rules evaluate (2 * 3) + (10 - 4). |
doc, js, input, output, n3 |
| Family cousins | generated from Notation3 by see.js; family-tree rules derive cousin relationships from parent facts. |
doc, js, input, output, n3 |
| French cities | generated from Notation3 by see.js; RDFS/OWL-style subproperty and transitive-property closure with fail-loud fuses and authored output. |
doc, js, input, output, n3 |
| Good cobbler | generated from Notation3 by see.js; term-logic-style list pattern and formula-valued conclusion. |
doc, js, input, output, n3 |
| Greatest lower bound uniqueness | generated from Notation3 by see.js; partial-order rules prove two greatest lower bounds of the same pair coincide. |
doc, js, input, output, n3 |
| Group inverse uniqueness | generated from Notation3 by see.js; group-law rules derive uniqueness of an inverse element. |
doc, js, input, output, n3 |
| Towers of Hanoi | generated from Notation3 by see.js; recursive backward rules and list append produce the three-disk move sequence. |
doc, js, input, output, n3 |
| Smoke Arithmetic | generated from Notation3 by see.js; arithmetic compiler smoke test deriving 6 × 7 through rules and builtins. |
doc, js, input, output, n3 |
| Socrates inference | generated from Notation3 by see.js; subclass closure with top-level log:query projection. |
doc, js, input, output, n3 |
| Burn the witch | generated from Notation3 by see.js; rule-chain explanation for the witch conclusion. |
doc, js, input, output, n3 |
| Backward recursion coverage | generated from Notation3 by see.js; legacy-named recursive backward-rule compiler regression. |
doc, js, input, output, n3 |
| Builtin coverage smoke | generated from Notation3 by see.js; legacy-named builtin registry compiler regression. |
doc, js, input, output, n3 |
| Smoke Arithmetic | generated from Notation3 by see.js; legacy-named arithmetic compiler smoke test deriving 6 × 7. |
doc, js, input, output, n3 |