ADR-012: Changed-Files-Only Reconstruction

Status: Accepted

Context

When computing a graph diff, should zetl check out the full vault at the baseline ref and build a complete graph, or reconstruct only the changed portions?

Decision

Reconstruct via changed files only:

git diff --name-only identifies changed .md files
git show retrieves old content of each changed file
Old content is parsed for wikilinks
Set differences between old and current graphs yield the diff

Rationale

Scales with the size of the change, not the size of the vault
A 50-file change in a 10,000-file vault processes only those 50 files
No temporary checkout needed — works in the current working directory
Memory usage proportional to the change set, not the vault

Trade-offs

Cannot detect changes in files that were renamed (Git detects renames, but the wikilink graph doesn’t track filename history)
Requires the current index to be up to date

Performance

For a 2,000-page vault with 50 changed files, diff completes in under 500ms. See Performance and SPEC-007 Graph Diff.

# Diff against previous commit (default: HEAD~1) zetl -d ./my-vault diff # Diff against a specific ref zetl diff --from main~5 # Diff by date zetl diff --since "2026-02-01" # Filter by change category zetl diff --filter links

Flag

Default

Description

--from <ref>

HEAD~1

Git ref to diff against

--since <datetime>

none

Find closest commit at or before this date

--filter <category>

none

Filter output: pages, links, orphans, dead_links

How it works

zetl uses an efficient reconstruction algorithm (see ADR-012 Changed Files Reconstruction):

git diff --name-only identifies changed .md files between the baseline and HEAD

git show retrieves the old content of each changed file

Old content is parsed for wikilinks

Set differences between old and new graphs yield the diff

This scales with the size of the change, not the size of the vault.

Requirement

REQ-046

Git ref baseline (--from <ref>)

REQ-047

Since-date baseline (--since <date>)

REQ-048

Default baseline (HEAD~1)

REQ-049

Structured diff output

REQ-050

Diff filter by category

REQ-051

Git unavailable error

REQ-052

Efficient reconstruction

Targets

Metric

Target

Measured (10k vault)

Cold-start full scan

< 200 ms

140 ms

Incremental re-index (1 file)

< 50 ms

8 ms

Graph query p99

< 10 ms

4 ms

Search (10k files)

< 2 sec

—

Reasoning (10k rules)

< 500 ms

—

TUI startup

< 200 ms

—

View startup

< 200 ms

—

Scroll frame time

< 16 ms

—

Merkle construction overhead

< 20%

—

Diff (2k pages, 50 changed)

< 500 ms

—

Watch event latency (p95)

< 500 ms

—

Strategies

Incremental parsing

The Scanner only re-parses files whose mtime has advanced since the last run. On typical editing sessions (1–5 changed files), this cuts scan time by 99% compared to a full rebuild. See architecture/Cache.

Merkle-based change detection

BLAKE3 content hashes let zetl skip unchanged files even when mtimes are unreliable (e.g., after git checkout). See Merkle Tree.

Memory layout

The Link Graph is stored as a flat adjacency list rather than a pointer-linked structure. This improves cache-line utilisation during multi-hop traversal.

Index-free search

ADR-012: Changed-Files-Only Reconstruction

Context

Decision

Rationale

Trade-offs

Performance

Backlinks