Provenance

Provenance is the ability to trace a conclusion back to its origins. In zetl, every fact, rule, and conclusion carries metadata recording the source file, line number, and page name where it was defined.

Why it matters

A reasoning system that says “X is true” is only useful if you can ask “why?” and get a concrete answer. Provenance connects the Reasoning Engine’s abstract logic back to the human-readable documents in your vault.

What is tracked

Element	Provenance
Fact	File path, line number, page name
Rule	File path, line number, page name, rule label
Conclusion	Full proof tree of contributing rules and facts

Commands

zetl reason explain <literal> — proof tree with source locations
zetl reason provenance <literal> — cross-referenced with the Link Graph
zetl reason export --format spl — reconstructed Spindle Lisp with provenance comments

Example

Running zetl reason provenance "release-candidate" on this vault traces the conclusion through rules in theories/release-readiness.spl back to facts scattered across the architecture and feature pages.

See also: Reasoning Engine, Reason Commands, Defeasible Reasoning

Backlinks

Linked Pages

Defeasible Reasoning

Defeasible Reasoning

Defeasible reasoning is a form of logic where conclusions can be drawn tentatively and later retracted when stronger evidence appears. This is how most real-world reasoning works — we act on the best information available, knowing new facts might change our minds.

Why it fits knowledge management

Decision documents, architecture records, and project plans all contain reasoning that is provisional. A conclusion like “use Redis” might be well-supported now but defeated by a future license audit. Spindle Lisp lets you express this directly in your notes, and zetl’s Reasoning Engine computes what follows.

Rule types

Type	Syntax	Meaning
Fact	`(given X)`	X is unconditionally true
Strict	`(always name body head)`	If body, then head — no exceptions
Defeasible	`(normally name body head)`	If body, normally head — can be defeated
Defeater	`(except name body head)`	If body, block head — but don’t assert the opposite

Superiority

When two rules conflict, a superiority relation resolves the tie:

(prefer stronger-rule weaker-rule)

Without a declared preference, the conflict remains unresolved — zetl reason conflicts will flag it.

Conclusion types

Tag	Meaning
`+D`	Definitely provable — strict derivation, no defeating possible
`-D`	Definitely not provable
`+d`	Defeasibly provable — inferred, no active defeaters
`-d`	Defeasibly not provable — blocked or no derivation path

In zetl

The Reasoning Engine implements defeasible reasoning via spindle-core. See Reason Commands for the CLI interface and Provenance for how conclusions trace back to source files.

Reason Commands

Reason Commands

zetl reason exposes the Reasoning Engine through eight subcommands. All require --features reason at build time — see Feature Gates.

(given reason-status-done)
(given reason-explain-done)
(given reason-why-not-done)
(given reason-require-done)
(given reason-what-if-done)
(given reason-conflicts-done)
(given reason-export-done)
(given reason-provenance-done)

Commands

`reason status`

What does the vault’s combined Spindle Lisp theory conclude? Filter by polarity (--positive, --negative), strength (--definite, --defeasible), or literal name (--literal "release*").

`reason explain <literal>`

Why does a conclusion hold? Produces a proof tree tracing the derivation through rules back to facts, with full Provenance (file, line, page). Output as JSON, table, natural language, or Graphviz dot.

`reason why-not <literal>`

Why can’t something be proved? Identifies missing facts, blocked rules, or active defeaters.

`reason require <literal>`

What facts would make a goal provable? Abductive reasoning — finds the minimal sets of missing facts. Useful for answering “what would it take to make release-candidate true?”

Reasoning Engine

Reasoning Engine

The reasoning engine takes Spindle Lisp extracted by the Scanner from across the entire vault, merges it into a single theory, and computes conclusions using Defeasible Reasoning. Every conclusion carries full Provenance — you can trace any result back to the exact file and line that contributed to it.

Pipeline

Extract — Scanner finds SPL blocks in Markdown fences and .spl files
Parse — spindle-parser converts SPL text into rule objects
Provenance — source file, line number, and page name are attached to each rule and fact
Combine — all rules and facts are merged into a single theory
Validate — check for undefined labels, duplicate definitions
Reason — spindle-core computes conclusions
Annotate — each conclusion is traced back to its proof sources

(given spindle-core-integrated)
(given four-conclusion-types)

Conclusion types

The engine produces four types of conclusion — see Defeasible Reasoning for details:

Tag	Meaning
`+D`	Definitely provable
`-D`	Definitely not provable
`+d`	Defeasibly provable
`-d`	Defeasibly not provable

Feature gate

The reasoning engine is compiled only when --features reason is enabled — see Feature Gates. Without it, zetl reason prints a clear error rather than failing silently.

See also: Reason Commands, Provenance, Spindle Lisp

Spindle Lisp

Spindle Lisp (SPL) is a domain-specific language for expressing Defeasible Reasoning theories. zetl extracts SPL from fenced code blocks in Markdown and from standalone .spl files.

Syntax reference

Facts

(given bird)
(given (not guilty))

Strict rules

Cannot be defeated. If the body holds, the head must hold.

(always r-penguin-is-bird penguin bird)

Defeasible rules

Can be defeated by stronger evidence. The label is optional.

(normally r-birds-fly bird flies)
(normally bird animal)

Defeaters

Link Graph

zetl builds a directed graph where nodes are pages and edges are Wikilinks. The graph powers all link-based queries: forward links, backlinks, multi-hop traversal, shortest path, and orphan detection.

Data model

Node — a Markdown page, identified by its title (filename without .md)
Edge — a wikilink from one page to another, with optional alias, heading, or block reference

The graph is built by the Scanner and cached by the Cache for incremental re-scans.

(given directed-graph)
(given multi-hop-traversal)

Queries

Command	Description
`links`	Forward links from a page, with configurable depth
`backlinks`	Pages linking to a target, with depth traversal
`path`	Shortest link path between any two pages
`export`	Full graph as JSON

These are exposed through Graph Queries. With the --with-conclusions flag, link results are cross-referenced with the Reasoning Engine to show what each linked page contributes to the vault’s logic.

Library

Built on petgraph, a Rust graph data structure library.

See also: Scanner, Graph Queries, Vault Diagnostics