@treeseed/dsh-chapters 0.1.0

package/docs/provider.md

@@ -0,0 +1,98 @@
+# Knowledge Transport Providers
+
+The sync layer's transport is pluggable (governing record: `knowledge-repo.md` §3.2 extended by
+Amendment 2026-09-21). One project record picks one provider; nothing else knows the difference.
+This file is the contract: what a provider must do, which invariants it inherits, and how each
+backend fills them.
+
+## The seam
+
+`runSync`'s transport surface is exactly six verbs — a provider is those, plus identity:
+
+```ts
+interface SyncProvider extends GitDriver {          // src/provider.ts
+  readonly kind: 'git' | 'treedx'
+  describe(project: ProjectRecord): string          // one honest status line
+  ensureClone(dir, remote, opts?)   // make the mirror exist and reflect the remote
+  initLocal(dir, remote?, opts?)    // offline mirror (§5.3)
+  removeMirror(dir)                 // destroy transport (the store is truth, §3.1)
+  stageAllAndCommit(dir, message, author)  // LOCAL diff workdir-vs-known-baseline
+  pullFastForward(dir, remote, opts?)      // converge; failure classes diverged|network|auth
+  push(dir, remote, opts?)                 // ship the staged delta
+}
+```
+
+Rules a provider must honor (all inherited from the record, restated at the seam):
+
+1. **The mirror directory exists in every mode.** The workspace store is the read path's truth
+   (§3.1); the mirror under `.dsh-knowledge/` is materialized content — search (`loadCorpus`),
+   rules (`collectMirrorRules`), the index build, and the notice layers consume it unchanged.
+   A provider that skips materialization breaks all of them.
+2. **Every failure is a value.** `{ok:false, code}` — the machine-readable classes drive
+   runSync's branching: `network` (degrade to local-only), `diverged` (rebuild the mirror from
+   the store and re-push), `rejected` (pull-and-retry once), `origin-mismatch` (rebuild; never
+   sync into the wrong pool), `auth` (surface the re-link instruction with the detail). Providers
+   branch on status + code, **never on prose** (r35).
+3. **ff-only, append-only.** Divergence is never merge-resolved; it is rebuilt
+   (§5.2). A provider never rewrites remote content.
+4. **Nothing throws into the conversation path**, and no token bytes appear in any `detail`
+   string (§2.1).
+5. **Provider selection is scheme-first, policy-strict.** `treedx+<url>/<repo>` → TreeDX;
+   anything else → git. `knowledgeProvider: 'git'|'treedx'` forces one and REFUSES a
+   contradiction rather than falling back — a wrong pool is a data-privacy failure, not a
+   config convenience (`providerKindFor`).
+
+## Backend truth table
+
+| Verb | git (`gitops.ts`) | TreeDX (`treedx/provider.ts`) |
+|---|---|---|
+| ensureClone | clone (or adopt existing repo + origin sentinel) | resolve repo in the catalog; fetch refs + `paths/list` (no extension filter — the mirror must be faithful) + `files/read`/`blobs/read`; materialize; write `.treedx-state.json` |
+| initLocal | `git init` + origin | state file with `offline: true` (publish/commit/index/search keep working) |
+| stageAllAndCommit | workdir-vs-HEAD content diff → git commit objects | workdir-vs-baseline diff → staged path list in the state file (baseline advances at stage time: restaging identical bytes says 'nothing to commit', the git parity) |
+| pullFastForward | fetch, ancestor checks, ff; non-ff ⇒ `diverged` | head compare vs state. Unmoved ⇒ up to date. Moved, nothing staged ⇒ refetch (ff). Moved with staged work ⇒ `diverged` — a merge could leave derived files (index/, topics/) built against a stale corpus; the rebuild re-derives |
+| push | git push (rejected ⇒ pull-retry) | workspace-create (`refs/heads/main`, one writable lease per branch) → write each staged path (UTF-8 File API; binary via Blob API) → commit. 409 with head unmoved ⇒ `rejected` (lease), bounded retry; 409 after the head moved ⇒ `diverged`; 401 ⇒ `auth` |
+| offline recovery | remote returns → pull diverged → rebuild | `state.offline` + reachable ⇒ `diverged` (same rebuild-from-store path) |
+| origin drift | `.git/DSH-ORIGIN` sentinel | `state.origin` vs the record's remote ⇒ `origin-mismatch` |
+
+## State: `.treedx-state.json` (the TreeDX mirror's `.git/`)
+
+`{origin, head, baseline: {path → sha256}, staged: {message, author, paths} | null, offline, repoId?}`
+— lives inside the mirror, starts with a dot so it never walks into any commit, and is the
+provider's memory across verbs (provider instances stay stateless per call, safe to share).
+
+## Identity and credentials (§2.1/§2.3, one rule for both providers)
+
+`projectKey = UUIDv5(NAMESPACE_OID, "treedx/" + canonicalize(baseUrl/repoName))` for TreeDX;
+the unchanged `canonicalize(remote)` for git. The `treedx/` namespace keeps a service whose URL
+happens to canonicalize like a git remote from stealing another's pool. Credentials ride the
+same DSH-home store (`credentials/<projectKey>`, 0600); for TreeDX the token is ALWAYS required
+(no loopback exemption: TreeDX answers 401, and a service URL without auth is a config bug,
+not a local file).
+
+## What a provider may NOT touch
+
+The workspace store, the registry domain, chapter rendering, redaction, the injection screen
+(`src/injections.ts`), composition, budgets, notice assembly, and the rules-approval gate. The
+approval (§15 amendment: per-machine curation fact) is the trust boundary shared state passes
+through a human on the local machine — a server (TreeDX included, federation included) cannot
+pre-approve anything, because the fact file lives under `edits/<harness-id>/` and the effective
+status is computed locally.
+
+## TreeDX API surface consumed (spikes/treedx/FINDINGS.md carries the pinning)
+
+`GET /health`, `POST /auth/dev-token` (dev), `GET|POST /repos`, `GET /repos/:id/refs`,
+`POST /repos/:id/paths/list`, `POST /repos/:id/files/read`, `POST /repos/:id/blobs/read`,
+`POST /repos/:id/workspaces`, `PUT|DELETE /workspaces/:id/files`, `POST /workspaces/:id/blobs/write`,
+`POST /workspaces/:id/commit`. Server-side search/graph/context (`files/search`, `graph/*`,
+`context/build`) and federation are Phase F: the plugin codes to one ingress URL and federation
+needs no client change.
+
+## Failure semantics summary (§5.3, per backend)
+
+| Condition | git | TreeDX |
+|---|---|---|
+| remote down | offline mirror init; push deferred | offline state; push deferred; pull probes recovery → diverged → rebuild |
+| credential bad/revoked | 401 as network class + detail | `auth` class: status says "re-link the token with /chapters-link", conversation untouched |
+| repo missing | GitHub creates on first push for scoped tokens (config'd) | link command creates it; sync-time absence ⇒ `not_found`, degraded with the name in the detail |
+| oversized file | n/a (packs stream) | File API 413 ⇒ refuse-with-numbers detail (§1.2), never truncate; >1 MiB belongs in multipart (Phase F) |
+| lease busy (two machines at once) | push rejected → pull → retry | create/commit 409 → bounded provider retry → `rejected` → runSync's pull-and-retry |

package/docs/verify.md

@@ -0,0 +1,200 @@
+# Verification
+
+The checklist in `AGENTS.md` is short because it only lists what matters. This is how to actually
+perform each check, with the numbers to record.
+
+## Test Strategy First
+
+Decide the harness in Phase 0, before Phase 1 code. Both reference plugins test their own way:
+`dsh-compact` uses vitest (`vitest.config.ts`, `test/`, `e2e/`), `dsh-session-fork` uses `bun test`
+with `tests/`.
+
+The point of choosing early: several core guarantees are *pure functions* and must be unit-tested, not
+hand-verified on a live profile every time.
+
+| Unit-testable without a running harness | Why it must be automated |
+|---|---|
+| Range validation (ascending, non-overlapping, coverage ≤ ceiling) | A silent gap drops archived history forever |
+| Chapter renderer: event slice → Markdown, including fence-escaping and artifact deferral | Deterministic input/output; the only cheap way to catch a renderer truncating at an embedded ```` ``` ```` |
+| `anchoredBoundaryOf` → archive ceiling | Vendored kernel logic; drift is invisible until a chain is corrupted |
+| TOC assembly from a fixture registry (flat, chronological, back-links) | Proves the DAG flattening without a live session |
+| Preflight budget math and refusal message | The "never truncate" guarantee is one `if` away from being lost |
+
+Kernel-dependent behaviour (durable create, sidebar listing, cache behaviour) cannot be unit-tested and
+needs the live procedure below.
+
+## Live Procedure
+
+Install for every step, after building:
+
+```bash
+tsc -p tsconfig.json
+dsh plugin --profile web add "link:$(pwd)"
+# restart: Ctrl-C, then `dsh web`, then refresh the page
+```
+
+A restart recomposes every session's header, which resets cache state profile-wide. **All cache
+measurements are only meaningful within one process generation** — record the generation (restart) with
+the numbers, or the measurement is unreproducible.
+
+### The Gate Checks
+
+**G1 — The child is smaller than the parent.** *The* regression test for the seeding mistake.
+Record the first-request `usage` of both. Expected: child ≈ system prompt + TOC + note, and **materially
+below** the parent's. A child near the parent's size means it was seeded from the log — invariant 2
+violated. Every other check can pass while this one fails silently, so check it first.
+
+**G2 — The parent's cache is undisturbed.** Continue the parent; record `usage.cacheReadTokens` on the
+step before the continuation and the step after. Expected: both high, no drop.
+
+**G3 — The child builds a stable cache.** Send two messages in the child; `cacheReadTokens` should be
+near-zero on the first and high on the second.
+
+Steps 4, 7, 8 of the `AGENTS.md` list are G1–G3. They are the whole point of the design.
+
+### Correctness Checks
+
+| # | Check | Procedure | Passes when |
+|---|---|---|---|
+| 1 | Installs | `dsh plugin --profile web add "link:$(pwd)"` | no error; note that `add` alone does not activate |
+| 2 | Tools listed | restart, open an agent session | `chapters_segment` and `chapters_continue` in the tool list |
+| 3 | Files written | run a continuation on a 2-topic conversation | chapter files exist under `<store-root>/<root>/chapters/` |
+| 4 | **G1** | see above | child first request materially smaller |
+| 5 | TOC is the first message | open the child | its entire content is the TOC notice; nothing inherited |
+| 6 | Durable and listed | restart `dsh web` | child still in the sidebar, still resumable |
+| 7 | **G2** | see above | parent `cacheReadTokens` unchanged |
+| 8 | **G3** | see above | child cache builds on turn 2 |
+| 9 | Reachability | in the child, ask it to `read` a bullet path | returns real archived text. A **reachability** test, not file-existence — pass `ls` first to see the difference |
+| 10 | Artifact deferral | archive a turn with a large tool result; mark it `inline: false`, then `read` the reference path | artifact written and path resolves; identical results stored once; **and** the same result is still written when inlined (deferral is a copy decision, not a data decision) |
+| 11 | Cumulative TOC | a second continuation | first fork's chapters still listed, by ancestry walk |
+| 12 | Sibling branches | continue an ancestor twice | two correct, non-colliding TOCs, each listing only its own ancestor path |
+| 13 | Registry survives restart | restart, continue again | ancestry and next number resume; no reset to `001` |
+| 14 | Atomicity | kill `dsh web` mid-continuation, restart, retry the same call | no orphan citation, no duplicate numbers, no TOC pointing at a missing file |
+| 15 | Range validation | hand it overlapping ranges and a deliberate gap | refused with the offending range named — not silently archived wrong |
+| 16 | Preflight refusal | force a note large enough to blow the budget | refused **before** any session is created, with token numbers; **no truncation** |
+| 17 | Tamper detection | edit a chapter body on disk, then continue | `⚠ modified since archived` surfaced from the stored hash, not silent trust |
+| 18 | `ctx.fs` absent | run in a configuration without the fs provider | clean refusal with an actionable message, not a crash |
+| 19 | Turn boundary | attempt a continuation with an open turn | ceiling lands on a completed `turn/end`; the in-flight exchange is carried by the handoff note, not by a mid-turn cut |
+| 20 | First-turn behaviour | open a fresh child, wait | confirm whether it acknowledges its own TOC (open question 2). If it does, the notice needs a stay-silent instruction |
+
+### Evidence Map (as of probe round 26/26b, 2026-09-17)
+
+Checks 1-19 were executed mechanically on the `.dshdev2` scratch profile
+(`spikes/probe/lib/round26*.js`, `results-26*.json`): 18 of 20 PASS with durable evidence — including
+[15] overlap refusals naming the range, [16] budget refusals carrying numbers, [17] a tampered chapter
+surfacing `⚠ modified since archived` inside a real child's notice, [14] an idempotent retry reusing
+numbers `[1, 2]` with no duplicate chapters, [13] registry state read back across a process kill, [6]
+continuation children AND fork siblings resuming across boots, [19]/[20] turn-boundary refusal and
+creation-schedules-no-turn. [7][8][9] (cache gates) point at r11/r22/r23 evidence; [10] boot-level rests
+on its L0 tests plus the citation-rule test; [18] is N/A because the store uses node:fs by design.
+**Genuinely human-only:** sidebar/visual resume in a browser, `/compact` observed in a live UI, the
+readability judgment of TOC prose and chapter bodies — plus optionally following one real 40KB tool
+result into an artifact.
+
+## Knowledge Layer — P1 Checklist (record §13)
+
+| # | Check | Passes when | Evidence |
+|---|---|---|---|
+| K1 | Project identity | same repo URL, different spellings → one key; non-git cwd degrades honestly; local-path upstreams key off the resolved path | unit `repo.test.ts` (10) + `sync-local-upstream.test.ts` |
+| K2 | Redaction at the chokepoint | a secret-bearing transcript never lands in a chapter or artifact, same secret → same marker | unit `redact.test.ts` + render chokepoint test; FINDINGS-era |
+| K3 | Turn signatures, live | a completed real turn yields a signature with paths/terms from HUMAN content only | **live probe r35j (K5b)** + L0 `engine-adapter.test.ts` (real Session shape) |
+| K4 | Topic-sequential composition | same-topic adjacent turns merge into one chapter; topic changes split; size cap splits | **live r36: merge proven (score 0.171 < τ, shared primary)**; L0 compose/anchor tests |
+| K5 | Index | shards deterministic; incremental manifest gates commits; rebuild-from-empty == incremental | unit `indexing.test.ts` (7) |
+| K6 | Search | topic>title>summary ranking, budget packing with total-vs-shown honesty, project scoping | unit `search.test.ts`; live r35j (K7: finds through a LOCAL-ONLY mirror) |
+| K7 | Commands context-free | `/chapters-link` (4 modes: view / path / git-URL+token / `treedx+`URL+token), `/chapters-status` render as flow nodes; the model's context is unchanged | durable: `command/run`+`command/done` lifecycle events, no model/usage around them (e2e plane); r35j K2/K8; treedx modes: `link-treedx.test.ts` |
+| K8 | Sync loop, success path | two machines over a REAL git smart-HTTP remote: publish → remote carries layout+index → clone sees it → search crosses | integration `sync-remote.test.ts` + **e2e `knowledge.spec.ts` — suite green 2026-09-18 (4/4, twice — also after the credential-move + three-mode link)**: browser composer link pushes to a live git-http-backend remote, status reaches 'synced', the child TOC carries the Project line + (N msgs), the debounced push lands `collections/`, and machine B searches A's chapters |
+| K9 | Sync loop, degradation | remote down ⇒ local-only mode (mirror+index current, status names it); recovery rebuilds and pushes | `sync-remote.test.ts` degradation arc; **live r35j: link to unreachable remote, search still works, status 'local-only'** |
+| K10 | Triggers fire | push scheduled after each archive (debounced); pull on first turn + pre-fork | **proven by K8's e2e run**: `collections/` reached the remote with no manual sync between fork and poll; L0 `scheduler.test.ts` + first-turn tests |
+| K11 | Notice v2 | `Project:` line + per-chapter `(N msgs)`; legacy records never render a fake zero | r35j (K6, K6b); `notice.test.ts` |
+
+Human-only rows (unchanged): sidebar visual resume, `/compact` observed in a live UI, TOC/chapter
+readability judgment.
+
+## Knowledge Transport Providers (record §15, Amendments 2026-09-21)
+
+| # | Check | Passes when | Evidence |
+|---|---|---|---|
+| T1 | Seam preserves git behavior | provider selection defaults 'git' for every pre-existing record; all K1–K10 evidence still green after the refactor | full suite (276→285) with zero git-mode changes; `provider.test.ts` selection + migration rows |
+| T2 | TreeDX publish/clone/search | machine A syncs (create→workspace→commit), B clones via the provider and `chapters_search` finds A's chapter through the materialized mirror | `treedx-sync.test.ts` (transport grade, stub) + **`treedx-live.test.ts` PROVEN against the real dev-auth container 2026-09-21** (born-head clone, publish→clone→search crossing, bad-token auth detail, head advance/lease reuse, binary blob round-trip) |
+| T3 | Divergence & lease classes | moved head + staged work ⇒ `diverged` ⇒ rebuild-from-store republishes BOTH contributions; busy lease ⇒ bounded retry ⇒ `rejected` ⇒ pull-and-retry; failed push CLOSES its workspace (leases survive ttl otherwise — measured) | `treedx-provider.test.ts` (all three), `treedx-sync.test.ts` (rebuild converge) |
+| T4 | Degradation with numbers | service down / token bad ⇒ `local-only` (offline mirror still publishes, commits, indexes, searches); `auth` detail carries the re-link instruction, never the token | `treedx-sync.test.ts` offline row; `treedx-provider.test.ts` auth row (token-sentinel absence) |
+| T5 | Oversized refusal | a UTF-8 file above the service limit ⇒ refuse with the number, never truncate | `treedx-provider.test.ts` 1 MiB-413 row |
+| T6 | Identity namespaces | `treedx+host/repo` key ≠ a git remote's key for the same canonical string (one pool per transport); stable across spellings (`/api/v1`, trailing slash, case) | `provider.test.ts` identity rows |
+| T7 | Commands surface | `/chapters-link treedx+…` resolve-or-creates the managed repo, stores the token 0600 under the DSH home, records kind+repoId; view/status print provider + head | `link-treedx.test.ts` (5) |
+| T8 | Dead-mirror self-heal | a pre-existing non-empty mirror dir (stale test residue, moved tree, abandoned pool) moves aside as `.stale-<ts>` and the clone proceeds — the old hard refusal made every later sync of an affected workspace a permanent deadlock (the r39 e2e class) | unit `sync.test.ts` self-heal row; `treedx-provider.test.ts` clone row (both providers); e2e boots now run dirty-free |
+| T9 | Body-hash anchor round-trips | the frontmatter anchor hashes EXACTLY what `parseChapterFile` returns as the body (the writer appends `'\n'`; hashing bare `bodyText` made every real chapter look tampered to the enrich guard, which silently refused — host logger). Sanctioned writes preserve body bytes and re-anchor the registry's whole-file hash | unit `enrich-store.test.ts`/`enrich-wire.test.ts`; **the enrich e2e passed 2026-09-23 — the first time the ladder ever wrote through the real UI** |
+| T10 | Host-plane enrichment route | `/chapters-enrich run` resolves a route from the last real tool-bearing session (`noteRoute` persists `enrichment.route`; the host has no live agent) — without it, a fork-only flow could never enrich | `enrich-wire.test.ts` + the passing enrich e2e |
+| T11 | Git-plane auth honesty | a rejected credential (401/403) classifies as `auth`, never `network` — clone/pull/push carry it and the degrade-to-local-only status says `credentials rejected … re-link with /chapters-link`, not the unreachable-ghost (the TreeDX live lesson applied to git) | `git-auth-classification.test.ts` (5) over a REAL smart-HTTP remote with a token gate; classifier unit rows included |
+| T12 | Corpus listing is complete | `paths/list` paginates (limit 100, base64 offset cursor) — `corpusPaths` follows `nextCursor` to the end; a second machine materializes EVERY file past a page boundary | `treedx-sync.test.ts` pagination row (150 files over the paginating stub); the live container (>100 paths) proves it at the real service |
+| T13 | The human entry surface | `/chapters-link` all four modes incl. refusals (no-token non-loopback, junk target), `/chapters-status` renders each fact ONCE (a duplicate-`Provider:` line was caught here), `/chapters-enrich` verbs, legacy workspace-token migration to the DSH home (0600, old file deleted) | `link-git-commands.test.ts` (11), `token-migration.test.ts` (4) |
+| COV | Both coverage ledgers are statement-grade and run | `npm run coverage:ci` — the GATED deterministic ledger (c8 over all unit+integration, `--check-coverage` at 85% statements/branches/functions/lines; enforced in hosted CI, which is GREEN end to end 2026-09-25) — currently **97.98% stmts / 85.61% branch / 93.62% funcs @ 451 tests, zero skips**. `npm run coverage:e2e` — six-project replay under E2E_COVERAGE=1; boots run lib/*.js with REAL source maps (tsconfig `sourceMap`) remapped by c8/v8-to-istanbul; first ledger **80% stmts / 62% branches / 74% funcs** — it corrected the earlier line-range estimate honestly (tools.ts 99% lines → 72% statements). The 2026-09-23 audit then closed most of that gap at the DETERMINISTIC plane: the engine's construction/listeners/degraded-summarize/plot-elicit/finalize-guard paths (`engine-lifecycle.test.ts` — real cordis `Context()`, real base engine, injected llm/tokenMeter fakes: engine.ts 40→91% stmts), every tool wrapper's success/refusal/missing-caller surface (`tools-surface` + `tools-branches` + `tools-deep-branches`), the TreeDX error taxonomy via one-shot stub faults (`treedx-provider-branches`) and parser-shape drift via injected `fetchImpl` (`treedx-parser-branches`), the local-path git transport arms (`gitops-branches`), host-command error arms (`host-command-branches`), and the pure planners (vocabulary/enrich/indexing/search/arrival/archive — `rules-vocab-branches`, `enrich-planner-branches`, `indexing-branches`, `notice-search-rules-branches`, `render-archive-ladder-branches`, `pure-branches`). It also caught one REAL bug on the way: `canonicalizeRemote` carried embedded `user:token@` credentials into the project key (pasting a remote with and without creds forked the pool — now stripped, pinned in `pure-branches.test.ts`). Gotchas pinned in the script header: c8 filters include/exclude BEFORE remapping (`--include=src/**` against lib-path profiles zeroes the report). Neither ledger alone is the claim; the e2e one makes index/render-in-browser paths that no deterministic test can see accountable |
+| H1 | Corpus carries no project instructions | host-injected context (instruction files, runtime snapshot, skill catalog, our own TOC notice — event-level AND `<system-reminder>` spans inside human messages) renders as a countable `⟦omitted:host-injected …⟧` marker, never bytes; conversation survives verbatim and byte-identical | unit `injections.test.ts` (15) + `render.test.ts` rows; integration `corpus-hygiene.test.ts` (archive→sync→remote→pull→search sentinel-absence, and legacy-store-publishes-unchanged anti-migration guard); e2e stays AGENTS-BLIND (tape masking) |
+
+## The Cache Metric, Before You Trust a Number
+
+`usage.inputTokens` is the **uncached delta** and `usage.cacheReadTokens` is the cached prefix, so:
+
+```
+totalPrompt = inputTokens + cacheReadTokens
+hitRate     = cacheReadTokens / totalPrompt          // NOT cacheRead / input
+```
+
+Dividing by the delta yields nonsense like 1721% — which these notes actually did before it was caught.
+For "the parent's cache is undisturbed" (G2), assert **`cacheReadTokens` does not collapse**. Do *not*
+assert that hit percentage stays flat: it falls innocently every time the prompt grows past a cache-block
+boundary while the prefix is fully retained. Measured steady state on this harness: 396,800 cached + 822
+uncached, **99.79%**.
+
+## Engine-Path Checks (Phase 0b delta)
+
+For the `ChaptersCompactionEngine` path (in-place compaction, no new session). Rounds 12/13/17 already
+proved the *mechanism* offline (durable records, zero usage, realm dispatch — see
+[spikes/probe/FINDINGS.md](../spikes/probe/FINDINGS.md) § Phase 0b); these are the product-level checks
+that still need a running chapter engine:
+
+| # | Check | Passes when |
+|---|---|---|
+| E1 | Zero-inference summarization | the `compaction/summary` event carries **no `usage` field** and no provider call appears in the round (proved with a stub at r12/r13; must re-prove with the real TOC `summarize()`) |
+| E2 | Archive honesty after automatic compaction | every `shadowedSeq` of a landed compaction resolves (via durable log + `sourceEventSeqs`) into a written chapter file whose hash matches the registry |
+| E3 | Header cache across a compaction — **CLOSED by r23 (measured, per-machine)** | cloud: `cacheReadTokens` held at **7,424 on both post-replacement turns** while uncached refill fell 13,658 → ~7,000. Local llama.cpp (r28-era probes): reuses NOTHING across a head replacement (0 cached) but steady-state turns cost only the new content. **Never quote one machine's number for the other.** |
+| E2E-TAPE | Acceptance without the GPU | `test:e2e:replay` serves every model turn from `var/model-tape/<project>` (isolated per boot) (proxy smoke: exact + prefix hit, loud 503 miss with journal). Usage fields ride the tape, so the token meter and compaction thresholds fire at identical steps under replay. Tapes are committed test DATA under `tests/fixtures/model-tape/` (the rest of `var/` stays ignored) — CI replays them via `scripts/ci-replay.sh` with no local model; regenerate via `test:e2e:record` (local GPU) when PRODUCT prompts change. The local model remains the distiller and ultimate witness. STATUS 2026-09-23: pipeline current (escape/whitespace classes, volatile rules incl. HOSTPORT-BLIND + derived-count collapses for `(N est tokens)` and host-injected char counts, tool bytes matched out); SIX-project replay chain (suite, fanout, heavy, arrival, enrich, rules). Doc-edit cost is honest, not free: the delimiter mask keeps AGENTS/skill bytes out of ordinary matching, but the harness's own checkpoint summary embeds the doc as model-visible prose in the compaction scenarios, so `heavy`/`fanout` re-record after an AGENTS.md change (finalize docs, THEN distill). The e2e is the integration witness that the deterministic layers cannot replace — it found two real product bugs (the enrich body-hash anchor mismatch and the missing host-plane route) that had been invisible behind the host logger |
+| E9 | P2 enrichment + vocabulary, two-machine grade | `node --test tests/integration/two-machine-enrich.test.ts` + `--project=enrich` tape replay | **green 2026-09-20** — enriched frontmatter/provenance cross the pool byte-exact; B honors A’s aliases and dedupes its own vocab pass; caught+fixed r37 (modifications invisible to commits). Four-project replay chain green, 0 misses |
+| E2E | The fork BUTTON, browser journey | **green (2026-09-19, 7 specs / three projects — suite@0.75-of-32K + heavy@0.5-floor-off + arrival@0.9-floor-500 — on port-keyed throwaway homes)**: specs CREATE their sessions through the UI ('New session' + one real Local-model turn; turn-complete = the session's OWN `turn/end` in its own log — the global registry count false-passed twice and was retired). Fixture-free by design after the R29-era rows aged out of the 90-session sidebar. The suite also caught the 'Internal Testing Notice' focus trap and the re-link origin bug (see FINDINGS). |
+| E10 | P3 rules lifecycle (record §7) | unit (status resolution, budget refusal, golden absent-notice bytes) + transport (three machines over a real pool) + e2e `rules` project replay | proposed everywhere by default; per-machine core facts; verbatim in the child's OWN log after UI approve; overflow refuses with per-rule numbers — **green 2026-09-20 at unit/transport grade** (three machines over a real pool; exit criterion covered); the `rules` browser scenario parked out of the default chain pending the r39 diagnosis — evidence-preservation first |
+| E2E-EDGE | Oversized turn handled gracefully | **green in the heavy project (captures 5.3–13.2m; run 11: 5 crossings, 27.8m; 6.0m suite pass)**: one browser turn reads 700KB range-by-range and crosses the threshold 5×: every mid-turn compaction commits (provider `dsh-chapters`, zero usage), every shadowed seq is chapter-covered, the pre-compaction marker survives in the transcript, the turn completes, and the follow-up turn answers — fork row reappears after settle (observed). The model's plan erosion under heavy trims is the fork's motivation; FINDINGS records it. |
+| E4 | Pruner composition | with `tool-result-pruner` mounted in the realm, a chapter covering a pruned result still renders the ORIGINAL text (follow `sourceEventSeqs` backwards), plus the model's inline override where requested |
+| E5 | Shrink-floor refusal is loud | a region too small to yield a smaller framed TOC fails with `ManualCompactionError code='summary'` and changes no surface (r12 behavior; keep as regression) |
+| E6 | Automatic timing inherits the host's |
+| E7 | Arrival-time artifacting (architecture amendment) | **green 2026-09-19 (9.3m)**: 373KB book / one read → exactly 1 arrival prune at the tail; model answers buried token + chapter count via 5 `chapters_artifact` calls; ZERO compaction events at production 0.9; blob fingerprint in no `request/*` event; cache table in FINDINGS shows prefix intact (cacheRead monotonically 15.7K→24.5K) |
+| E8 | Plot carriage across in-place checkpoints | forward path live (persona discipline — suiteB oversized run carries `PLOT:` blocks through 7 compactions); render→extract round trip pinned in unit (`carried plot survives the checkpoint round-trip`); elicited fallback unit-pinned (capped input/output, degrades to null) — fires only when the agent writes no note | compaction lands at `agent/pre-step`, bracketed `compaction/start.turn` = open turn number (r13/r17 `turn: 2`); never mid-request, never mid-step |
+
+## Bug Reports
+
+Cache and context behaviour are the plugin's core promise, so a report must include:
+
+- parent session id, child session id, root session id, store directory, archive ceiling
+- chapter paths written, and any artifact references
+- `usage.cacheReadTokens` for the parent's steps immediately before and after, plus the child's first two
+  steps — **and the process generation (which restart) each was taken in**
+- **first-request token counts for both sessions** — the single most diagnostic number, since a silently
+  re-seeded child is the most damaging regression
+- the ranges supplied and the refusal text, if a preflight rejected the attempt
+
+## The first real-remote push (manual, one-time per project)
+
+The sync loop is integration-tested against a fake driver that models the git
+semantics it relies on; the wire protocol itself is isomorphic-git's (https only
+— isomorphic-git 1.42 registers no `file://` transport, verified against its
+transport registry). The first push against a real remote is therefore a
+**manual, one-time step per project**:
+
+1. Create a **private** empty repo (record §2.1: per-project, user-created) and a
+   scoped token for it (fine-grained PAT limited to that repo).
+2. In a Chapters session: `/chapters-link https://… <token>`.
+   The token is stored 0600 at `.dsh-chapters/.git-auth/<projectKey>`.
+3. The command reports the sync steps; on `push rejected`, re-run
+   `/chapters-link` (pull-retry) or wait for the next archive event.
+
+If isomorphic-git ever chokes on a specific forge's smart-HTTP, the documented
+fallback is a CLI driver (the `GitDriver` seam in `src/gitops.ts` exists for
+exactly this swap) — the loop's logic is driver-agnostic by design.

package/lib/archive.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Archive writer — the first I/O layer, behind an injected fs so it stays testable without a harness.
+ *
+ * Ordering is the whole design here. Reserve numbers → write artifacts → write chapters → verify read-back
+ * → return records for the registry. A crash must be able to leave an orphan file, but never a registry
+ * entry or an index that points at a file which was not written. See docs/architecture.md § Atomicity.
+ *
+ * Deferral is a copy decision, not a data decision: the artifact is written whether or not the chapter body
+ * also inlines it, so a wrong model judgement costs one `read` and never loses text.
+ */
+import type { RenderedChapter } from './types.ts';
+/** Minimal filesystem seam. `ctx.fs` is OPTIONAL in DSH, so absence must be a clean refusal upstream. */
+export interface ArchiveFs {
+    write(path: string, content: string): Promise<void>;
+    read(path: string): Promise<string | undefined>;
+    exists(path: string): Promise<boolean>;
+}
+/** Number allocation through the registry, never by scanning a directory (races a concurrent sibling). */
+export interface NumberAllocator {
+    reserve(key: string, count: number): Promise<number[]>;
+}
+export interface ChapterRecord {
+    number: number;
+    path: string;
+    title: string;
+    summary: string;
+    startSeq: number;
+    endSeq: number;
+    /** Index topics (deterministic floor; P2 enrichment may relabel). */
+    topics: string[];
+    /** user+assistant message count in the chapter (record §7.3 notice line);
+     * absent for records written before counts existed — never a lying zero.
+     * (`| undefined` for the `exactOptionalPropertyTypes` zod round-trip.) */
+    messages?: number | undefined;
+    /**
+     * The exact surface seqs archived, in surface order. Optional because
+     * continuation-path ranges are numeric-contiguous (start/end suffice), but
+     * engine-path spans replace across the log, where start/end are only span
+     * bounds — the set is the truth about coverage. (`| undefined` so the
+     * zod-inferred type satisfies `exactOptionalPropertyTypes` in store.ts.)
+     */
+    shadowedSeqs?: number[] | undefined;
+    /** Body sha256, used to detect on-disk tampering before the text is ever cited. */
+    sha256: string;
+    estimatedTokens: number;
+    artifacts: Array<{
+        path: string;
+        sha256: string;
+        bytes: number;
+    }>;
+}
+export interface WriteResult {
+    records: ChapterRecord[];
+    artifactPathsWritten: string[];
+    /** Duplicate titles, retried attempts reusing numbers, or content that failed read-back. */
+    warnings: string[];
+}
+/** Filesystem-safe, stable, and never empty. Title is display metadata; the number is the identity. */
+export declare function slugify(title: string): string;
+export declare const chapterFileName: (n: number, title: string) => string;
+/** Idempotency key: the same source session + ceiling reuses reserved numbers instead of duplicating. */
+export declare const attemptKey: (sourceSessionId: string, archiveCeiling: number) => string;
+export interface WriteInput {
+    fs: ArchiveFs;
+    allocator: NumberAllocator;
+    /** Store root, relative to the session workspace so the `read` tool can reach it. */
+    storeRoot: string;
+    /** Directory key — the root of the ancestry tree, not the per-fork id. One dir per tree. */
+    rootSessionId: string;
+    chapters: readonly RenderedChapter[];
+    /** Reuse a prior attempt's allocation when this is a retry of identical work. */
+    attemptId: string;
+}
+export declare function writeArchive(input: WriteInput): Promise<WriteResult>;
+/** Coverage arithmetic: which seqs below the ceiling were NOT archived. Gaps are reported, never silent. */
+export declare function coverage(records: readonly {
+    startSeq: number;
+    endSeq: number;
+}[], archiveCeiling: number, archiveFloor?: number): {
+    covered: number;
+    gaps: Array<{
+        from: number;
+        to: number;
+    }>;
+};
+export type VerifyResult = 'ok' | 'modified' | 'missing';
+/** Called before citing a chapter in an index. Detects accidental drift and single-shot injection. */
+export declare function verifyChapter(fs: ArchiveFs, record: ChapterRecord): Promise<VerifyResult>;

package/lib/archive.js

@@ -0,0 +1,114 @@
+import { sha256 } from "./render.js";
+/** Filesystem-safe, stable, and never empty. Title is display metadata; the number is the identity. */
+export function slugify(title) {
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return slug.length > 0 ? slug.slice(0, 48) : 'chapter';
+}
+export const chapterFileName = (n, title) => `${String(n).padStart(3, '0')}-${slugify(title)}.md`;
+/** Idempotency key: the same source session + ceiling reuses reserved numbers instead of duplicating. */
+export const attemptKey = (sourceSessionId, archiveCeiling) => `${sourceSessionId}@${archiveCeiling}`;
+/** Join without importing path, so the seam stays portable between ctx.fs and node:fs. */
+const join = (...parts) => parts.filter(Boolean).join('/').replace(/\/{2,}/g, '/');
+export async function writeArchive(input) {
+    const { fs, allocator, storeRoot, rootSessionId, chapters } = input;
+    if (chapters.length === 0)
+        throw new Error('writeArchive called with no chapters');
+    const treeDir = join(storeRoot, rootSessionId);
+    const warnings = [];
+    // 1. Reserve BEFORE touching the filesystem, so a crash cannot re-use a number.
+    const numbers = await allocator.reserve(input.attemptId, chapters.length);
+    if (numbers.length !== chapters.length) {
+        throw new Error(`allocator returned ${numbers.length} numbers for ${chapters.length} chapters`);
+    }
+    const records = [];
+    const artifactPathsWritten = [];
+    const seenArtifact = new Map(); // sha256 → path, for subtree dedup
+    const seenFile = new Set();
+    for (let i = 0; i < chapters.length; i++) {
+        const chapter = chapters[i];
+        const number = numbers[i];
+        let fileName = chapterFileName(number, chapter.range.title);
+        if (seenFile.has(fileName)) {
+            // Same title, same number prefix — disambiguate rather than let one chapter overwrite another.
+            fileName = fileName.replace(/\.md$/, `-${number}.md`);
+            warnings.push(`title collision resolved for "${chapter.range.title}" → ${fileName}`);
+        }
+        seenFile.add(fileName);
+        const chapterPath = join(treeDir, 'chapters', fileName);
+        // 2. Artifacts first: the chapter body cites these paths, so they must exist before it does.
+        for (const artifact of chapter.artifacts) {
+            const existing = seenArtifact.get(artifact.sha256);
+            if (existing !== undefined)
+                continue; // identical result in this batch
+            if (await fs.exists(join(treeDir, artifact.path))) { // identical result from an earlier fork
+                seenArtifact.set(artifact.sha256, artifact.path);
+                continue;
+            }
+            await fs.write(join(treeDir, artifact.path), artifact.content);
+            seenArtifact.set(artifact.sha256, artifact.path);
+            artifactPathsWritten.push(join(treeDir, artifact.path));
+        }
+        // 3. The chapter itself.
+        await fs.write(chapterPath, chapter.markdown);
+        // 4. Read-back verification. A file that does not come back byte-identical is not citable.
+        const readBack = await fs.read(chapterPath);
+        if (readBack === undefined) {
+            warnings.push(`read-back failed (missing): ${chapterPath}`);
+            continue;
+        }
+        // Hash the whole file, so verifyChapter() can re-check it with no knowledge of frontmatter layout.
+        const bodyHash = sha256(chapter.markdown);
+        if (readBack !== chapter.markdown) {
+            warnings.push(`read-back mismatch, refusing to cite: ${chapterPath}`);
+            continue;
+        }
+        if (chapter.stats.unrenderedSeqs.length > 0) {
+            warnings.push(`${chapterPath}: ${chapter.stats.unrenderedSeqs.length} event(s) rendered no output (${chapter.stats.unrenderedSeqs.join(', ')})`);
+        }
+        if (chapter.stats.overTarget) {
+            warnings.push(`${chapterPath}: ${chapter.stats.estimatedTokens} tokens over chapterTokenTarget — split at the next boundary, do not clip`);
+        }
+        records.push({
+            number,
+            path: chapterPath,
+            title: chapter.range.title,
+            summary: chapter.range.summary,
+            startSeq: chapter.range.startSeq,
+            endSeq: chapter.range.endSeq,
+            topics: chapter.topics,
+            messages: chapter.stats.messages,
+            sha256: bodyHash,
+            estimatedTokens: chapter.stats.estimatedTokens,
+            artifacts: chapter.artifacts.map((a) => ({ path: join(treeDir, a.path), sha256: a.sha256, bytes: a.bytes })),
+        });
+    }
+    return { records, artifactPathsWritten, warnings };
+}
+/** Coverage arithmetic: which seqs below the ceiling were NOT archived. Gaps are reported, never silent. */
+export function coverage(records, archiveCeiling, archiveFloor = 0) {
+    const sorted = [...records].sort((a, b) => a.startSeq - b.startSeq);
+    const gaps = [];
+    // Start at the floor, not at the first chapter: a set that skips the opening of the conversation is
+    // exactly the silent-history-loss this function exists to catch.
+    let cursor = archiveFloor;
+    let covered = 0;
+    for (const r of sorted) {
+        if (r.startSeq > cursor)
+            gaps.push({ from: cursor, to: r.startSeq - 1 });
+        cursor = Math.max(cursor, r.endSeq + 1);
+        covered += r.endSeq - r.startSeq + 1;
+    }
+    if (cursor <= archiveCeiling)
+        gaps.push({ from: cursor, to: archiveCeiling });
+    return { covered, gaps };
+}
+/** Called before citing a chapter in an index. Detects accidental drift and single-shot injection. */
+export async function verifyChapter(fs, record) {
+    const text = await fs.read(record.path);
+    if (text === undefined)
+        return 'missing';
+    if (sha256(text) !== record.sha256)
+        return 'modified';
+    return 'ok';
+}
+//# sourceMappingURL=archive.js.map

package/lib/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"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"}

package/lib/arrival.d.ts

@@ -0,0 +1,23 @@
+export interface ArrivalSessionShim {
+    surface: {
+        nodes: number[];
+    };
+    eventAt(seq: number): {
+        type: string;
+        data: unknown;
+    } | undefined | null;
+    append(type: string, data: unknown, opts?: unknown): unknown;
+}
+export declare const ARRIVAL_MARKER = "[dsh:artifact";
+export interface ArrivalOpts {
+    cwd: string;
+    storeRoot: string;
+    floorTokens: number;
+    /** message → estimated tokens (host tokenMeter injected; tests use chars/4). */
+    estimate: (message: unknown) => number;
+}
+export interface ArrivalResult {
+    stubbed: number;
+    detail?: string;
+}
+export declare function applyArrivalStubs(session: ArrivalSessionShim, opts: ArrivalOpts): Promise<ArrivalResult>;