sherd 0.6.0

two-axis federation of SPEC.md and source over a dir DAG, for small-context local models
Documentation
# SPEC

## §G GOAL

the SCHEDULE a parallel build follows: the code DAG, the ready set per round, and the 2 numbers that make the case — DEPTH & WIDTH. report-only.

## §N NAV

rel|path|lens
up|.|-
up|src|code nodes — tokens, spec, fed, lens facades & logic
self|src/wave|the SCHEDULE a parallel build follows — code DAG, ready set per round, depth & width
sib|src/tokens|-
sib|src/spec|-
sib|src/split|-
sib|src/fed|-
sib|src/adopt|-
sib|src/lens|-
sib|src/ollama|-
sib|src/tdd|-
sib|src/plan|-
sib|src/review|-
sib|src/state|-
sib|src/slice|-
sib|src/land|-
sib|src/cli|-
sib|src/code|-
sib|src/debt|-
sib|src/assay|-
sib|src/git|-

## §C CONSTRAINTS

- REPORTS, ⊥ runs. WHO writes the code is a named, swappable executor & is ⊥ built here (`.:V117`).
- reads Rust source through `src/code` & the tree through `src/fed`. re-reading either is the 2-readings defect (`src/code:V1`).
- takes the DAG it is HANDED where it can (`src/cli:V6`): `schedule()` is pure & needs no tree, which is why its rules are testable w/o a fixture.

## §I INTERFACES

- lib: `code_deps(&Path) -> Vec<CodeDep>` — per node, the SIBLING nodes its `use crate::` lines name, & those its scripts invoke (V5)
- lib: `unresolved_calls(&Path, &Path) -> Vec<Unresolved>` — script invocations in scope that resolve to no tracked script (V5): node, script, the call as written
- lib: `schedule(&[CodeDep]) -> Schedule` — ready set per round, pure
- lib: `CodeDep.needs` (BLOCKING) · `CodeDep.seam` (type-only) · `Schedule.edges`/`.blocking` — both numbers, ⊥ one (V4)
- lib: `wave(&Path, &Path) -> Schedule` — the schedule a wave over one dir would follow
- lib: `Schedule::depth()` · `Schedule::width()` — rounds, & the most workers ever busy at once
- lib: `edges(&Path, &Path) -> Vec<Edge>` — every edge between 2 DIFFERENT nodes in scope: `from` · `to` · `kind` (blocking | type-only) · `sibling` · `inferred` (V6-V8)
- lib: `cycles(&[CodeDep], &[String]) -> Vec<Vec<String>>` · `wave_with_cycles(&Path, &Path)` — the cycles among the blocked, 1 group each (V9)
- cli: `sherd wave [dir] --format json` → `{rounds, blocked, cycles, edges, unresolved:[{node,file,call}], depth, width}`

## §V INVARIANTS

V1: the CODE dag is ⊥ the FEDERATION dag. code edge = `use crate::` between SIBLING nodes; federation edge = a `§F` row, parent→child ∴ 2 graphs over 1 tree & conflating them ships a schedule nobody can run — `§F` makes co-children read INDEPENDENT when the code makes one wait for the other, & declares parent→child edges the code ⊥ have. a CYCLE in the code dag is legal Rust ∴ NAMED & exit 0, where `.:V4`'s federation cycle is exit 1: 1 word, 2 graphs, 2 verdicts. MOVED here w/ the code it governs, from the rule the planner carried while the scheduler lived there
V2: a dependency LEAVING the scope is DROPPED, ⊥ left unsatisfiable. keeping it reports every scoped node blocked — a cycle report for a tree w/ no cycle
V3: a schedule is STABLE between runs ∴ labels sort. a report whose rounds reorder cannot be diffed, & the 2 numbers are what a reader compares
V4: a TYPE-ONLY import is an EDGE & ⊥ a WAIT. `use crate::lint::Level` names a type a SEAM commit already declared ∴ the importer waits for ⊥ lint's LOGIC, & counting it as blocking UNDERSTATES width exactly when the seam has done its job (B1). an import of the MODULE (`use crate::lint;`) names no item ∴ never type-only, & 1 behavioural reach makes the whole edge blocking — a sibling you ! wait for is ⊥ made safe by also naming its type. BOTH numbers are reported (edges · blocking): 1 of them decided the rounds & a reader cannot see which from `depth` alone
V5: for SHELL code a code edge = a script a node OWNS (`src/fed:V15`) INVOKING a script that lies under a SIBLING node: `source X` · `. X` · `bash X` · `sh X` · `exec X` · `X` @ command position. ⊥ a mention — `echo "run b/x.sh"` names a file & runs nothing. X resolves LEXICALLY: a literal path against the script's dir, then the repo root; `$(dirname "$0")`/`BASH_SOURCE` = the script's dir; `$(git rev-parse --show-toplevel)` = the root; `$VAR/…` = what VAR was ASSIGNED in the same file, when that is 1 of those. what does ⊥ resolve to a tracked script, lexically or by V6, is REPORTED as unresolved, ⊥ dropped silently — a missed edge is a schedule that runs a node before the one it calls, the unsafe direction. a shell edge is always BLOCKING: shell has no type-only reach (V4). a node w/ ⊥ scripts gets the schedule it got before, byte for byte
V6: `$VAR/tail`, VAR NEVER bound by the file & `tail` w/o `$` → INFERRED `root/tail` iff that is a tracked script. a bound VAR that misses stays unresolved
V7: edge `inferred` iff ⊥ call behind it resolved lexically. a lexical call clears it
V8: `edges()` = every call between 2 different nodes; callee = the node OWNING the script (`src/fed:V15`). `sibling` marks the ones that shape rounds (V1)
V9: `cycles` = strongly connected groups of BLOCKING edges among `blocked`, sorted. a node waiting only BEHIND a cycle is in ⊥ group; a self-loop is a group of 1
V10: `X=<…>.sh` | `X=${E:-<…>.sh}` (runner ok) then `"$X"` run → call of that value, resolved per V5/V6. E = env ∴ default runs

## §T TASKS

id|status|task|cites
T1|.|the EXECUTOR half — frozen til rung 0.7 (`.:V117`). it lands HERE, ⊥ in the planner|`.:V123`
T3|.|test file(s) over the 2,000 ceiling since `.:T108` gave `src/wave` its tree: `tests/wave.rs` 2,124. split by subject|`.:V50`,`.:V124`

## §B BUGS

id|date|cause|fix
B1|2026-09-20|`wave` counted EVERY `use crate::` edge as blocking ∴ it reported the PESSIMISTIC shape precisely when a seam commit had made the edges non-blocking — `seam` proposes the vocabulary that frees them & `wave` measured the same rounds anyway, so the 2 verbs told a reader contradicting stories. MEASURED on a consumer repo of 10 nodes (`.:R57`): `wave` reported depth 5 · width 6, rounds `[charset, scan, cli, tokens] → lint → rules → fix → render`, & the repo was in fact built by 7 workers in 1 ROUND w/ 1 integration break. the 5 rounds never happened. the build was preceded by a seam commit declaring every node's public TYPES & nothing else ∴ `use crate::lint::Level` in `rules` is a compile-time reference to a type that ALREADY EXISTS|V4 & `src/code:V5`: `crate_imports()` reads the ITEM half of a `use` line, & an edge whose every item is a public type of the target is counted & ⊥ waited for. both numbers ship in the report. GENERALLY: a scheduler that cannot tell a TYPE reference from a CALL is measuring the language's compile graph, ⊥ the work graph, & the 2 diverge the moment anyone declares an interface first