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

one cached store. `kind key value`, one line each.

## §N NAV

rel|path|lens
up|.|-
up|src|code nodes — tokens, spec, fed, lens facades & logic
self|src/state|one idempotent cached store — pace, telemetry, applied rows
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/wave|-
sib|src/review|-
sib|src/slice|-
sib|src/land|-
sib|src/cli|-
sib|src/code|-
sib|src/debt|-
sib|src/assay|-
sib|src/git|-

## §V INVARIANTS

V1: a KEY ⊥ contain the delimiter. `value` MAY (`obs` carries a telemetry line) ∴ the parser splits 3 & a spaced key truncates (B1). escape on write, unescape on read
V2: `set` → `save` → `load` → `get` ! return what was set. a reader & writer that disagree lose data w/ no error (`.:src/fed:V13`)
V3: a CAPPED log ! carry its own ORDER in the key. eviction reads the key & nothing else ∴ a key that ⊥ encode time evicts by accident — & a content hash is the natural key here ∵ it is also the idempotence guard. seq PREFIX, zero-padded, & an UNSEQUENCED key sorts OLDEST (`None` < `Some`, which is true: it was written 1st). a TIMESTAMP is still refused ∵ it changes the file when nothing changed; the dedup is what makes a clock unnecessary — a repeat append is a no-op ∴ the file is byte-identical
V4: the DEFAULT store lives in the git COMMON dir (`<git-common-dir>/sherd-state`), ⊥ the cwd. sherd runs INSIDE consumer repos & a cwd-relative file lands in their worktree, where their `.gitignore` ⊥ lists it & their `.crate` ships it (B3). `SHERD_STATE` still wins; ⊥ a repo → `.sherd-state` as before. the common dir is shared by every worktree ∴ a worktree ⊥ starts cold

## §T TASKS

id|status|task|cites
T2|.|test file(s) over the 2,000 ceiling since `.:T108` gave `src/state` its tree: `tests/state.rs` 2,604. split by subject|`.:V50`,`.:V124`

## §B BUGS

id|date|cause|fix
B1|2026-08-21|`splitn(3, ' ')` ∴ a key w/ a space parses as its FIRST WORD. every loop label has one (`1 red-test`, `2 green`) ∴ the per-label pace model was WRITE-ONLY from day one & every step fell back to `EXPECT_GEN` 13 where the 20B emits ~2,300, mostly reasoning. eta off ~175x ∴ the 4x abort kills step 1 & the loop ⊥ reach step 2 — `.:src/tdd:T13`'s zero, one layer under `.:src/tdd:V29`. FOUND by RUNNING it|V1,V2. keys escaped, round trip asserted
B2|2026-08-24|`trim_kind` kept N by dropping the LEXICALLY lowest keys, & the one real caller (`src/ollama::record_obs_in`) keys by CONTENT HASH ∴ eviction was by hash, ⊥ by age. the retained set was a hash-sampled slice of ALL HISTORY: MEASURED over 700 observations capped @ 200, 62 survivors came from the FIRST 200 & only 63 from the last 200 ∴ day-one telemetry outlived recent runs at equal weight & the pace model stopped learning. the TEST agreed w/ the impl ∵ its fixture keyed `00`..`09`, zero-padded, where lexical order IS age — a fixture no caller produces (`src/tdd:B2`'s shape, in our own suite). the row said only "newest is undefined"; the consequence was ⊥ measured until asked|V3. `push_kind(kind, dedup, value, cap)` — seq-prefixed key, dedup by suffix, evict oldest-first. `trim_kind` DELETED, ⊥ deprecated: `push_kind` supersedes it & a 2nd way to bound a log is the 2-readings defect. 2 defects found while fixing it, both by testing the MIGRATION: `.last()`'s seq restarted @ 0 forever ∵ a legacy bare hash `ff78..` sorts AFTER `00000000-..` (→ MAX over keys), & the same lexical order evicted the NEWEST first (→ order by seq, `None` 1st)
B3|2026-09-28|`default_path()` fell back to `.sherd-state` RELATIVE to the cwd ∴ run inside another repo it wrote into THAT worktree. sherd ignores it, a consumer does ⊥: microlith's `package` gate step failed as the `.crate` would ship the cache, & the gate's own hint (`hk fix -S package`) would have RECORDED it into the published file set. 3 fix-up rounds spent, repo quarantined (pr0d1r2/sherd#62)|V4. `default_path()` resolves the git common dir through `src/git`; the resolution is a pure fn over (env, common dir) & tested on all 3 arms