trajectories 0.0.0 → 0.1.2

package/docs/research/ledger/docs/research/2026-09-13-search-quality.md

@@ -0,0 +1,105 @@
+# Search-quality: zero-hit widening and an evidence-bearing envelope, 2026-09-13
+
+## Outcome
+
+Multi-word Ledger searches without boolean operators are exact-phrase FTS5
+matches, so any query whose words are not adjacent — the normal case for
+vague recall — returned zero. The escaped-term conjunction retry fired only
+on FTS syntax errors, never on zero hits, and reported nothing.
+`totalHits` was `hits.length` (bounded by `limit`) presented as an exact
+count, and robot mode emitted bare hit lines with no envelope at all.
+
+This cycle adds a gated prefix-OR widening for zero-hit lexical queries and
+a `search_meta` envelope that makes counts, engines, fallbacks, and widening
+refusals agent-readable. Live-store proof: four real vague queries derived
+from actual record content went 0 → 10 hits (2–7 sessions each) while
+adjacent-phrase and quoted queries stayed byte-identical.
+
+## Evidence chain
+
+- Defects verified on merged main `2b08be4`:
+  `packages/core/src/db.ts` `buildFtsExpression` (phrase-wrapping),
+  `queryLexical` catch path (syntax-error-only retry), `totalHits`
+  accounting in all three engines, and `cli.ts` `handleQuery` robot payload.
+- Round-2 Confer research pinned Cass's exact mechanics (patterns only,
+  rider license honored — no Cass code or engine reuse):
+  the widening gate composition, the `*term*` shape, strictly-more
+  acceptance, `ImplicitWildcard` tagging with quality factor 0.6, and the
+  envelope vocabulary
+  (`cass@c7cd1ad3ff7ee5d4323b9c840dcfcda683881e36`, see
+  [confer round 2](../../confer/2026-09-13-round-2/cass.md)).
+- Divergences from Cass, deliberate: Ledger triggers only on 0 hits (its
+  default multi-word semantics IS the phrase, so sparse-but-nonzero results
+  are correct matches, not a failure); FTS5 rejects `*term*` (verified
+  locally — `unknown special query`), so the widened shape is a quoted
+  prefix OR-join `("tok"* OR "tok"*)`; refusal reasons ship in the payload
+  where Cass buries them in tracing logs.
+
+## Design
+
+- Gates (all must hold, evaluated only after a 0-hit primary): no quote
+  anywhere in the query (phrase intent), no boolean operators, no user
+  wildcard; tokens ≤16 chars (over-long tokens are dropped, the remainder
+  still widens), ≥3 alphanumeric chars per widenable token (a quoted empty
+  phrase with `*` is not a no-op in FTS5 and can match unrelated records);
+  case-insensitive dedupe, ≤16 terms; corpus under
+  `LEDGER_WIDEN_MAX_RECORDS` (default 10,000, strict decimal parse, 0
+  disables, read per query). Adoption requires strictly more hits than
+  zero; every adopted hit is tagged `match_type: "implicit_wildcard"`.
+- Envelope: `QueryResult.meta` carries `count_precision`
+  (`exact`/`all_matches_returned` when hits < limit,
+  `lower_bound`/`limit_bounded` at the boundary), engine `elapsed_ms`,
+  `search_mode`/`requested_search_mode` (equal today; the pair exists so a
+  future fallback cannot misreport), `fallback_reason` for the syntax-error
+  conjunction retry (now surfaced, including through hybrid), and the
+  `widened` report with `skip_reason` on refusal. Robot mode emits one
+  `search_meta` JSONL line before the hits; `--json` becomes
+  `{search_meta, hits}`; human output changes only when widening or
+  fallback fired (stderr note + `[widened]` header suffix).
+- Hybrid widens its lexical leg only; adopted hits keep
+  `implicit_wildcard` through RRF fusion, and the hybrid envelope forwards
+  the lexical leg's `fallback_reason` and `widened`. Semantic never widens.
+
+## Verification (independent verifier; scripts were throwaway under /tmp)
+
+- Stability: changed tree 405/407 three times; a full-repo copy on the fast
+  volume 406/407 three times; base `2b08be4` worktree 371/372 three times.
+  The only constant failure is the pre-existing `native-cursor`
+  classification failure (issue #18); the semantic CLI-spawn timeout is a
+  `/Volumes/dev` volume artifact (base code: 0.74 s from /tmp, 29.2 s from
+  `/Volumes/dev`). Typecheck and build clean.
+- Live capability: four real vague queries ("worktree premortem fix",
+  "fair use throttle", "rebase token passthrough", …) went 0 → 10 hits on
+  the 901-session/156,801-record production store with correct envelopes;
+  an adjacent-phrase query and a quoted query were byte-identical before
+  and after; a syntax-error query reports `fallback_reason`.
+- Overhead: 200 nonzero-hit queries — median 0.116 ms both sides (the
+  widening probe provably never runs; 0 `getRecordCount` calls
+  instrumented). Zero-hit queries pay the probe and, when under-ceiling
+  widening succeeds, the rerun: +0.53 ms median on a 2,400-record fixture.
+  On the 157k live store the default ceiling refuses (visible
+  `corpus_over_ceiling`, ~9 ms probe); raising it costs 0.14–1.5 s per
+  widened query — the documented price of opting a large store in.
+- Adversarial round (before verify): 4,000-query FTS5 metacharacter fuzz —
+  0 throws, 0 envelope malformations, 0 column-filter leaks; happy-path
+  invariance 15/16 byte-identical human outputs and 72/72 identical robot
+  payloads (the one difference: a legitimately widened zero-hit query);
+  ingest-staging's 13 content-absence assertions moved to quoted phrases —
+  reviewed as contract-preserving, not suppression.
+
+## Boundaries
+
+- Widened results are OR-of-prefixes: recall-oriented, precision-low. The
+  `match_type` tag and the envelope are the contract for consumers that
+  care; ranking inside a widened set is bm25 over the OR expression.
+- The default 10k ceiling means large stores refuse widening until an
+  operator opts in. A future FTS5 prefix index (`prefix=` on the virtual
+  table) could make widening cheap at scale; recorded as follow-up.
+- `widened_query_failed` is defensive and not expected reachable (every
+  token is quoted+escaped; the 4,000-query fuzz never hit it).
+- The ceiling counts the whole corpus, not the `--source`-filtered slice —
+  a filtered search cannot dodge the cost guard; documented.
+- `--robot --json` changed shape (array → object). No in-repo consumer
+  parses it (wrapper scripts are passthrough); flagged as the one external
+  breaking vector in the PR description.
+- No Cass code reused; no new dependencies; schema untouched.

package/docs/research/ledger/docs/research/2026-09-13-source-coverage.md

@@ -0,0 +1,64 @@
+# Durable source coverage, 2026-09-13
+
+## Outcome
+
+Cycle 7's scan outcomes were dropped on every floor (`sync.ts` and
+`watch.ts` destructured `sessions` only; `buildStore` logged them only
+under `--verbose`), so the answer to "which sources are persistently
+missing or failing?" evaporated with each pass. This cycle records them
+durably: schema v12 adds `source_coverage` — one last-write-wins row per
+source (`source` PK, root, status, discovered, detail, `first_seen_at`,
+`updated_at`) — written by a single shared upsert from exactly the three
+lease-holding passes (sync `runSync`, `buildStore`, watch drain), and
+read by `ledger status`, which now carries a `coverage` block: the robot
+array (sorted, `first_seen_at` internal) and a human count line
+("N/M sources listable, K missing") with one line per non-missing
+anomaly. `scan` stays ephemeral by design (no lease, no handle). This
+closes the "visible coverage reporting / expose unsupported-failed-
+pending sources" gap named in round 1.
+
+## Evidence chain
+
+[Confer round 9](../../confer/2026-09-13-round-9/README.md): AgentsView's
+`raw_coverage` per-source rows (the transplantable shape) and its
+version-in-key anti-pattern; Obelisk's proven failure mode — durable
+markers with zero production readers — which is why the status reader
+ships in the same change, and its write-last-in-transaction marker rule;
+letta-code's last-write-wins outcome slot and its stale-success
+qualifier (a post-pass transition must write); Cass's
+persist-only-non-derivable-truth rule; the harness's single-choke-point
+writer. Ops context this round: recovered a wedged sync that held the
+lease 75× past its `--wall-ms` budget (#35); the live store migrated to
+v11 with widening verified live.
+
+## Verification (combined adversarial + independent round)
+
+- Lease safety: all three write points record under the writer lease
+  (probed — an external lease holder leaves rows and store mtime
+  byte-identical); no fourth write path exists; the scan path is
+  handle-free. Upsert: two processes × 60 rounds — zero errors, zero
+  duplicates, `first_seen_at` pinned, detail clearing verified,
+  spinning readers never observed partial sets.
+- Contract: robot keys exactly `{source, root, status, discovered,
+  detail, updated_at}` sorted; human math (N/M, K missing; missing
+  counted, never listed); pre-v12 → `null` with the unknown line; empty
+  table → `[]` with the none line; reads never rewrite rows.
+- Migration: a genuine v11 store (built with archived v11 code) lands at
+  v12 with an empty table, all data and FTS behavior preserved; the
+  v1…v11 fixture chain all migrates; `CREATE_TABLES_SQL` is the whole
+  v12 migration (equal-version re-runs restore a hand-dropped table).
+- Mutations: 7/7 killed (each record-call removal, first_seen
+  re-stamping, detail retention, the text filter, and the
+  record-after-nothing-new ordering).
+- Suite: 532 pass / 0 fail across 36 files (reproduced on a
+  byte-identical clone); typecheck/build clean. Live v11 store:
+  `status` returns `coverage: null` read-only, bytes unchanged.
+
+## Boundaries
+
+- Coverage reflects the last pass that scanned each source; a source not
+  scanned this pass keeps its prior row (stale `updated_at` is the
+  signal). No TTL, no notification semantics, no counters — the row is
+  state, not history.
+- `first_seen_at` is internal (not published).
+- #35 (wall-budget enforcement) remains open as its own bug.

package/docs/research/ledger/docs/research/2026-09-13-sync-wall-budget.md

@@ -0,0 +1,82 @@
+# Enforcing the sync wall budget across worker waits, 2026-09-13
+
+## Outcome
+
+The sync pass's `--wall-ms` budget was consulted only at admission
+gates; the worker-wave `Promise.all` had no timeout, and
+`spawnJsonChild`'s kill timer never settled the awaited promise — a hung
+child stdout drain hung the parent forever. Observed live: a wedged
+holder at zero CPU kept the writer lease for 75× its 120 s budget and
+blocked every write until manually killed (issue #35). This cycle makes
+the wall real:
+
+- `spawnJsonChild` settles on timeout — the SIGTERM → 250 ms grace →
+  SIGKILL sequence is raced against the reply drain, the stopped flag
+  (timer or abort) decides status, and the `finally` awaits the stop so
+  no child outlives the call.
+- The wave await is raced against the remaining absolute wall; on
+  expiry the wave's children are killed, settled siblings keep their
+  real results (only still-pending invocations count as timed_out),
+  reservations are charged, and the pass proceeds through normal
+  control flow to a truthful summary — the deadline signal never lives
+  in the cleanup path, so an abort cannot inherit the wedge, and the
+  `finally` releases the lease.
+- `SyncSummary.outcome` gains `wall_budget_exceeded`; precedence is
+  complete → `pending_pressure` → `wall_budget_exceeded` → … (pressure
+  outranks the wall: it is the stronger do-not-spin signal). Interrupted
+  rows stay durably queued without backoff — the next pass completes
+  them (pinned by test).
+
+## Evidence chain
+
+[Confer round 10](../../confer/2026-09-13-round-10/README.md): Cass's
+stall-vs-slow fault pair (PARK dies at the wall; PAGE_SLEEP — slow but
+progressing within budget — is work, not a wedge) and typed compact
+abort reporting; the harness's single-absolute-deadline rule clamped
+into every wait; letta-code's outer group-kill layer that cannot be
+defeated by a wedged child and its keep-the-deadline-out-of-the-abort
+discipline; AgentsView's capture-finalization deadline shape (declared,
+armed once, named outcome) and its bounded-drain fail-closed rule;
+Obelisk's confirmed absence (budget-gates-admission is the shared blind
+spot) and its progress-watermark insight (deferred — the worker budget
+already bounds each child).
+
+## Verification (combined adversarial + independent round)
+
+- **The wedge is fixed**: real parked child with a never-closing stdout
+  — spawn settles at deadline+grace with typed `timed_out`, child
+  reaped, descendant (if any) force-settled; the PARK pass ends at the
+  wall (~+500 ms reap) with `wall_budget_exceeded`, truthful counts, no
+  orphans, lease released, second pass completes the interrupted
+  session; PAGE_SLEEP (4×250 ms silent work under a 1.5 s wall)
+  completes normally.
+- **Deadline math**: per-wave clamps from one absolute deadline; the
+  worker-vs-wall boundary holds at equality; no zero/negative timeouts;
+  maintenance still bounded. A wall spent before admission reports the
+  boundary without starting work.
+- **Truthfulness**: settled-sibling partitioning verified (A replies,
+  B parked → completed 1, timed_out 1); outcome precedence including
+  the pressure-outranks-wall case; the adjacency fix keeps
+  `sessionBudgetLimited` honest when an earlier exhaustion zeroed the
+  selection.
+- **Hygiene**: every race timer cleared on both outcomes; prompt
+  process exit in all probes and the real CLI; mutations 5/5 caught
+  (settle-on-timeout, wave race, outcome branch, adjacency, clamp
+  boundary).
+- **Invariance**: full suite 541 pass / 0 fail across 36 files;
+  baseline-vs-current CLI summaries byte-identical (minus timing) on
+  normal passes; hermetic real-CLI syncs converge to `complete`.
+- Documented truths: a stopped wave costs the kill grace plus reap, so
+  a pass can end up to ~500 ms past the wall; the kill is pid-scoped
+  (a pipe-holding descendant would live on as its own process — none
+  exists today); a reply inside the ~2 ms clock band counts as a
+  report, not a stop.
+
+## Boundaries
+
+- Progress-watermark stall detection inside workers remains deferred
+  (per-worker budgets bound each child today).
+- Watcher drain deadlines are a separate surface, unchanged.
+- The launchd `ExitTimeOut` SIGTERM path still orphans worker children
+  (pre-existing); with the wall enforced, the daemon no longer wedges,
+  which removes the observed exposure.

package/docs/research/ledger/docs/research/2026-09-13-typed-read-gate.md

@@ -0,0 +1,81 @@
+# Typed read gate for foreign and incomplete stores, 2026-09-13
+
+## Outcome
+
+Both read gates (`TrajectoryReader`'s `openReadOnlyStore` and
+`readStoreStatus`) recognized an initialized store by `sessions`-table
+presence alone. A foreign SQLite file with only that table passed the gate
+and died per-verb with raw SQLite errors (`no such table: records`,
+`no such column: updated_at`) — reproduced on main `3469076` for `status`,
+`search`, `recent`, and `emit-pi`. This cycle replaces both gates with one
+shared classifier (`schema-gate.ts`): absent/zero-byte →
+`STORE_NOT_INITIALIZED`, not-a-database/corrupt-open → `STORE_UNREADABLE`,
+too-new → `SCHEMA_MISMATCH`, sessions present but required pairs missing →
+new `STORE_SCHEMA_INCOMPLETE` naming the first gap in sorted order with a
+single-sourced remedy line. A plain table named `records_fts` no longer
+passes (the FTS5 shadow table `records_fts_data` is the witness). The
+three `applyEmbeddingProvider` calls the reader split made dead were
+removed, and their live `--embedding` validation was restored as a shared
+parse-time `assertKnownEmbedding` (a bogus value fails every verb).
+Closes #27.
+
+## Evidence chain
+
+[Confer round 6](../../confer/2026-09-13-round-6/README.md): AgentsView's
+required-schema diff and error shape (MIT — the `:memory:` replay does not
+port to Ledger's branch-dependent DDL; the creator/expectation invariant
+was adapted as the migration-fixture derivation test), Obelisk's
+(table, column) pair-list probe (AGPL — patterns only) and the four-outcome
+ladder analysis, the harness's observed-vs-expected message wording,
+letta-code's empty-vs-invalid distinction (zero-byte = not initialized,
+never unreadable), and trajectory's finding that a valid SQLite file
+lacking expected tables escapes as a raw driver error there too.
+
+## Design
+
+- `REQUIRED_READ_SCHEMA`: 44 pairs — records (19 columns),
+  records_embeddings (5), sessions (16), plus presence-only pairs for
+  `records_fts` and its FTS5 shadow `records_fts_data` (a same-named plain
+  table is the #27 failure shape one level down; AgentsView's by-name
+  index check has exactly that hole and was noted, not copied).
+- One classifier, single open, no TOCTOU (the `ok` state carries the very
+  handle the caller queries); every refusal path closes the handle.
+- Determinism: the reported gap is the sorted-first missing pair — stable
+  across processes, locales, and physical column orders.
+- One gate, documented: stores missing only row-contract columns refuse
+  all four read verbs even where some verbs could serve — the documented
+  trade for one consistent verdict.
+
+## Verification (combined adversarial + independent rounds)
+
+- Classifier: 0 fd leaks across all states and both callers; boundary
+  ladder stable (missing/zero-byte/garbage/truncated/directory/symlink/
+  WAL-sidecar-missing/VIEW-named-sessions/version-vs-shape ordering);
+  double-close safety; determinism across 5 locales × 5 processes.
+- Required list: every pair touched by read-path SQL (7 are row-contract
+  columns, documented); real historical DDL re-materialized per commit
+  confirms v1 → `records_embeddings` gap, v3/v4-identity →
+  `sessions.agent_nickname` gap, v4-parentage…v10 → ok — matching the
+  derived fixtures exactly; the live 901-session store classifies ok and
+  serves with store bytes unchanged.
+- Mutation checks both directions: removing a load-bearing pair kills the
+  derivation test; adding a bogus column kills 24 tests.
+- Suite: 466 pass / 1 fail of 467 — the pre-existing native-cursor #18;
+  the semantic spawn-timeout flake is environmental (baseline-identical;
+  ~13× slower from this checkout's volume). Typecheck/build clean.
+- Fixes from the adversarial round before verification: `--embedding`
+  validation restored at parse time (it was live validation, not dead
+  code — the audit caught the removed calls' real function); the FTS
+  shadow-table witness; sidecar wording made precise (SQLite may recreate
+  `-shm` on a zero-frame WAL store — engine behavior, documented, gate
+  deliberately not tightened); fixture fidelity hardened (pre-v6 variants
+  drop `content_hash_version`) so the derivation test cannot drift from
+  real stores; shape-not-integrity scope documented.
+
+## Boundaries
+
+- The gate checks shape, not integrity: damaged pages still surface
+  per-verb `RUNTIME_ERROR` (unchanged from baseline).
+- `STORE_UNREADABLE` wording differs between reader and status (baseline
+  wording preserved; single-sourcing holds for the new code only).
+- Index/column-shape validation inside FTS remains out of scope.

package/docs/research/ledger/docs/research/2026-09-13-writer-lease.md

@@ -0,0 +1,84 @@
+# Participating-writer lease between CLI verbs and the daemon, 2026-09-13
+
+## Outcome
+
+Ledger's only write arbitration was `busy_timeout=15000` — a CLI `sync`
+colliding with the 15-minute scheduled daemon (or any writer) blocked
+silently for up to 15 seconds, and nothing prevented interleaved writers.
+This cycle adds a hard writer lease: a sibling lock database
+(`<db>-write.lock`) taken with a held `BEGIN IMMEDIATE` before any store
+connection opens, with typed, actionable refusals replacing silent
+blocking.
+
+- Mutating verbs acquire before `new TrajectoryDb` (whose constructor
+  writes DDL): foreground `build`/`sync` wait 250 ms then fail typed
+  `WRITER_BUSY` naming the holder; the scheduled daemon
+  (`LEDGER_SCHEDULER=1`, set by both ops installers) soft-skips the pass
+  with a reason and exit 0; `watch` takes the lease per drain
+  (refcounted across overlapping drains) and skips the tick on busy,
+  opening the store lazily so an idle or skipped watcher touches nothing.
+- Sync worker children are authorized by invocation, not environment: the
+  private verbs pass an explicit option, and the child refuses typed unless
+  the lease label's pid is its `process.ppid` — an ambient
+  `LEDGER_SYNC_WORKER=1` can never bypass a held lease.
+- Release is fd teardown (process death frees it; no TTL, no reaper, no
+  pid-liveness checks — which letta-code round 3 shows are zombie-broken on
+  darwin). The label uses `INSERT OR REPLACE` and a self-conditional
+  (own-pid) delete so a releaser can never erase a successor's name. A
+  corrupt lock database is quarantine-renamed and retried once, never
+  unlinked in place (inode-split rule).
+
+## Evidence chain
+
+All mechanisms are independently specified in
+[confer round 3](../../confer/2026-09-13-round-3/README.md) with pinned
+citations: Obelisk's TTL-free sibling-lock lease and read-policy ladder
+(AGPL — patterns only), AgentsView's two-layer gate, worker env-marker
+transport, and error-string discipline (MIT), Cass's never-unlink rule,
+metadata-bearing lock, and scheduler-verb soft-skip (rider — patterns
+only), the harness round-3 verdict that grace-then-proceed fences do not
+translate to row-commit writers (claim-then-typed-busy is the correct
+ladder), and the scout map of Ledger's write entry points on `b20664a`
+(daemon = 15-min oneshot sync; constructor-write hazard).
+
+## Verification (adversarial + independent rounds)
+
+- Adversarial round found two reproduced HIGHs (watch lease leak on drain
+  overlap silently disabling the daemon; ambient marker bypassing the
+  lease), a label-integrity bug (`UNIQUE` failure on stale labels — the
+  real cause of nameless refusals), a permanent-wedge on corrupt lock
+  dbs, and store-creation outside the lease by idle watchers — all fixed
+  with mutation-verified negative tests before verification.
+- Independent verification (own probes, real CLI processes): foreign
+  holder → `WRITER_BUSY` naming pid+holder, store not created; scheduler
+  skip → exit 0 with `skipped:{reason,holder}` and a distinct human line,
+  store untouched; SIGKILL holder → next sync completes immediately;
+  ambient marker + foreign lease → refused both as worker verb and as
+  foreground sync; real parented worker completes (132 KB read, cursor
+  advanced); watch under a foreign lease skips and keeps running; live
+  launchd service untouched.
+- Stability: full suite 424 pass / 0 fail across 34 files, three
+  consecutive runs (both known pre-existing failures — native-cursor #18
+  and the semantic volume flake — did not reproduce). Typecheck and build
+  clean.
+- Overhead: 20 interleaved fresh-store sync passes per side — median 494
+  ms lease vs 489 ms baseline (+1.0%, within noise; lease max 510 <
+  baseline max 553); idle-store passes identical; steady-state
+  acquire+release 318 µs median (p99 755 µs); watch drain parity.
+
+## Boundaries
+
+- The lease covers `build`, `sync` (and its authorized children), and
+  `watch` drains. Read verbs (`search`, `recent`, `emit-pi`) still open
+  `TrajectoryDb` — on an existing current-schema store that path takes no
+  write lock (measured 3.4 ms); a fresh-store open performs DDL outside
+  the lease (documented; read-path split is a later cycle).
+- A refused foreground verb has bounded wait semantics only; there is no
+  queueing or fairness between contending foreground writers.
+- The lease label is advisory metadata for error attribution; mutual
+  exclusion rests on SQLite's write lock, always.
+- `commitIngest` already re-reads staged/live state inside its
+  transaction — no TOCTOU change was needed (harness round 3 confirms the
+  shape).
+- No schema change to the store; the lock sidecar holds no user data
+  (deleting it while no writer runs is safe — documented escape hatch).

package/docs/research/ledger/docs/research/2026-09-16-c1-copy-fallback.md

@@ -0,0 +1,227 @@
+# C1: copy-fallback read-only SQLite for native stores, 2026-09-16
+
+## Outcome
+
+A native store held by its own writer no longer costs a coverage row. Before
+this cycle the same fixtures — a 60-composer Cursor `state.vscdb` and the host's
+real 239.1 MiB `opencode.db`, each held by a second connection — produced **zero
+sessions and a `read_error` diagnostic** after ~1.1 s of `busy_timeout`. Now the
+store is read from a private copy: 60/60 and 5/5 sessions, real transcripts, no
+diagnostics, and the ledger store's schema and index shape are untouched.
+
+- `packages/core/src/native/sqlite-ro.ts` (new) — probe → private copy →
+  give-up gradient, plus `nativeDbStamp` / `cachedCopyPath` invalidation.
+- `withReadOnlyDb` moved out of `native/common.ts`; `native/cursor.ts`,
+  `native/opencode.ts`, `parentage.ts` (Hermes and OpenCode parent links) and
+  `normalizer.ts` (Hermes assembly) read every native store through it. Error
+  translation (`NativeInputError` mapping) and `reportNativeError` /
+  `read_error` diagnostics are unchanged.
+- Tests: `tests/native-sqlite-ro.test.ts` (9 cases),
+  `tests/native-sqlite-ro-window.test.ts` (the checkpoint-wrap regression), one
+  held-store case per migrated caller (`parentage.test.ts` ×2,
+  `normalizer.test.ts` ×1), plus two adapter tests re-pinned to the new
+  contract (`native-cursor.test.ts`, `native-opencode.test.ts`).
+- Gates: `bun test` 549 pass / 0 fail · `bun run typecheck` · `bun run build`.
+
+### The gradient
+
+1. **Probe.** Read-only open, `PRAGMA busy_timeout = 1000`, and
+   `SELECT count(*) AS tables FROM sqlite_master`, all inside one deferred
+   transaction, so the caller's read runs on the same snapshot.
+2. **Copy fallback.** Only `SQLITE_BUSY` / `SQLITE_LOCKED` reach it. Copy the
+   database and its sidecars into a private 0700 directory (files 0600), open
+   the copy writable, and read it. The copy is accepted only when the database
+   file's `size:mtime` identity is unchanged from immediately before the
+   database copy to after the last sidecar: a checkpoint can backfill pages into
+   the database *and* restart the wal generation mid-copy, leaving frames and
+   index individually valid while the base is stale. A moved database is
+   discarded and copied once more; a second move gives up. A copy root that is
+   not this uid's at mode 0700 is refused before anything is written.
+3. **Give up.** Copy refused (byte budget, IO, unopenable, root not private) →
+   the direct error surfaces unchanged, i.e. exactly today's
+   retryable-vs-`read_error` classification.
+
+A 512 MiB `MAX_SQLITE_COPY_BYTES` bounds the copy set (database plus every
+sidecar present); the largest live store measured on this host is 239.1 MiB, so
+real stores fit with ~2× headroom while a runaway `-wal` is refused instead of
+copied. Copies are private agent history: they live in
+`$TMPDIR/ledger-native-db/copy-<hash>-<pid>` — created 0700, files 0600, and
+refused outright if that root already exists with weaker permissions — and are
+removed by a process `exit` hook, by supersession when the stamp moves, and —
+after a crash — by a dead-pid sweep before the next copy.
+
+## Ported mechanics (Wake MIT, `iAmCorey/Wake@d9f702b6df0e85` tag v0.6.5 — mechanics with attribution, no code copied)
+
+Pin: `d9f702b6df0e85763f8ab597c09bf4ca6a168db4`, `crates/wake-core/src/adapters/sqlite_ro.rs` (77 lines), MIT License © 2026 Corey Chiu.
+
+| Ledger | Wake pin | What was kept |
+| --- | --- | --- |
+| read-only open + `SELECT count(*) FROM sqlite_master` probe | `sqlite_ro.rs#L20-L28` | probe-first, so a lock is detected *before* the caller's read runs and diagnostics cannot double-fire |
+| copy `db` + `-wal` + `-shm` into a temp dir, read the copy | `sqlite_ro.rs#L31-L45` | same shape: create the dir, copy the database, copy the sidecars that exist, reopen |
+| never `immutable=1` | `sqlite_ro.rs#L16-L19` | an immutable open ignores the `-wal`, which is where a live store keeps its newest sessions |
+| stamp = `max(mtime(db), mtime(-wal))` | `db_cache_stamp`, `sqlite_ro.rs#L68-L76` | `-shm` excluded: its read-marks change on every read and would invalidate per call |
+| temp dir removed with the reader | `TempDirGuard`, `sqlite_ro.rs#L6-L15` | TypeScript has no `Drop`; the `exit` hook plus dead-pid sweep is the equivalent |
+
+Deliberate deviations, each with its reason:
+
+- **`-journal` is copied, and the copy is opened writable.** A rollback-journal
+  writer can leave uncommitted pages in the database file; with the journal
+  present, SQLite rolls the copy back to the committed state instead of
+  reporting in-flight rows as committed. Writable also lets the copy rebuild a
+  `-shm` the source never had.
+- **Sidecar order is `-shm` before `-wal`.** The copied index can then never
+  claim frames the copied `-wal` does not contain. An older consistent snapshot
+  is the safe direction; a short frame read is not.
+- **The copy trigger is lock contention only.** A copy answers concurrency, not
+  unreachable bytes: a store whose `-wal` was deleted out-of-band is not revived
+  by copying it, and reading it at its last checkpoint would publish partial
+  evidence as a whole session (Ledger's "missing evidence remains unknown").
+  `SQLITE_CANTOPEN`/`SQLITE_CORRUPT`/`SQLITE_NOTADB` keep the direct diagnosis.
+- **The stamp invalidates a copy, not just a row cache.** Wake keys row caches
+  by `db_cache_stamp` per query; here the whole sync reuses one private copy, so
+  discovery and all per-session reads of a held store cost one copy (measured
+  below).
+- **The database base is re-checked after the copy.** Frames and the wal index
+  stay individually valid across a checkpoint that backfills pages into the
+  database and restarts the wal generation mid-copy, so the copy would silently
+  lose the pages the checkpoint moved. The database file's `size:mtime`
+  identity, captured before its copy and re-read after the last sidecar, is the
+  narrow witness of exactly that transition; a moved base discards the copy and
+  retries once. (Wake has no equivalent because it never had a checkpoint wrap
+  in the window — it copies the same set with the same window.)
+- **The copy root must be private.** A root that is not this uid's at mode 0700
+  is refused before anything is written; the gradient then gives up to the
+  direct diagnosis. Roots are created at 0700 explicitly rather than inheriting
+  the mode of their parent.
+- **Bounded copy size and crash-safe cleanup** are Ledger additions; Wake's
+  `open_sqlite_ro` has neither bound nor sweep.
+
+### Adversarial review round (2026-09-16, three findings — all fixed)
+
+1. **WAL generation loss on checkpoint-wrap during copy (high).** Reproduced
+   against this module's own order and open semantics: with a `t1` row living
+   only in the `-wal` and a second table `t2`, a checkpoint plus one `t2` insert
+   between the database copy and the `-wal` copy made the copy answer
+   `t1=[]`, `t2=['B']` with no error. Fixed by the database-identity recheck plus
+   one retry above. Regression test:
+   `tests/native-sqlite-ro-window.test.ts` — it runs the module's own source
+   with only its `node:fs` binding redirected to a shim that fires the
+   checkpoint exactly before the `-wal` copy (Bun binds builtins at load time
+   and refuses both plugin and mock overrides), asserts the substitution
+   changed nothing else, and asserts the hook ran. Verified sensitive: with the
+   recheck disabled the test fails with `t1: ["A"]` → `t1: []`; with it, the
+   copy is discarded and retaken and the read is `t1: ["A"], t2: ["B"]`.
+2. **Copy root ownership/mode unverified (medium).** `mkdirSync` silently
+   accepted a pre-existing foreign 0755 root: world-readable transcript copies
+   until the per-file chmod, predictable copy-directory names, a
+   `rmSync`/`mkdirSync` re-creation race, and a sweep that could be steered by a
+   planted dead-pid entry. Fixed by `privateRoot()` (this uid, mode 0700,
+   refusing otherwise) and by creating the root explicitly at 0700 — the old
+   code created it implicitly, and the leaf's mode option does not apply to it.
+   Regression test: "refuses a copy root that is not private instead of writing
+   transcripts there" (root set to 0755 → the direct error surfaces, no copy
+   written, the root's entries are unchanged).
+3. **Citation range (low).** `sqlite_ro.rs#L68-L80` pointed past the 77-line
+   file; corrected to `#L68-L76` here and in the module.
+
+## Position in the program (C1 row, `docs/research/2026-09-16-wake-port-program.md`)
+
+- Failure it fixes: *"A store held by its own CLI costs a coverage row today
+  (`read_error`, `native/common.ts`). Wake's gradient converts locked stores to
+  working reads."*
+- Open-source case: *"'Works on stores while the agent is using them' — first-run
+  experience on any live machine; the #1 operational complaint class for tools
+  like ours."*
+- Ordering: C1 is independent and mechanical, so it runs first; nothing here
+  touches the index shape that C2–C5 will change.
+
+## Measurements
+
+Host: Apple M1, macOS, APFS `/tmp`. Fixtures: 60 composers × 6 bubbles (128 KiB)
+for the adapter passes; a copy of the host's live `opencode.db` (239.1 MiB) for
+the real-store pass. "Before" is the pre-cycle `withReadOnlyDb` body, executed
+from a pristine `git archive HEAD` tree in `/tmp` so both versions ran in the
+same process against the same fixtures.
+
+**OBSERVED**
+
+| measurement | before | after |
+| --- | --- | --- |
+| unlocked store, discovery + 60 session reads (median of 20 passes) | 12.04 ms | 11.94 ms (−0.1 ms, noise) |
+| unlocked store, single read at the module boundary (mean of 400) | 88.6 µs | 91.8 µs (+3.2 µs) |
+| locked store, rollback-journal `BEGIN EXCLUSIVE`, full pass | 0 sessions, `read_error`, 1120 ms | 60 sessions, 0 diagnostics, 1147 ms |
+| locked store, WAL `locking_mode = EXCLUSIVE`, full pass | 0 sessions, `read_error`, 1101 ms | 60 sessions, 0 diagnostics, 1150 ms |
+| real `opencode.db` copy held by an exclusive-locking writer | 0 sessions, `read_error`, 1115 ms | 5 sessions discovered, 3 read (1,078,667 transcript chars), 0 diagnostics, 1192 ms |
+| locked store per-read cost after the first copy | n/a (unreadable) | first read 2.5 ms (copy + open), remaining 59 reads 32.6 ms (0.53 ms median) |
+| transcripts on an unlocked store | 99,060 chars | 99,060 chars (identical) |
+| ledger index size delta | — | N/A: no DDL, no schema/index change; `SCHEMA_VERSION` and every table DDL are untouched by this cycle |
+| copy root / file modes | — | 0700 root (`.../ledger-native-db`), 0600 files; emptied at process exit in CLI runs — the dead-pid sweep covers a hard stop, and the suite removes the root itself because the test runner's teardown skips `exit` hooks |
+
+Reproduction: the harness was throwaway. Build the Cursor-shaped fixture
+(`state.vscdb`, `cursorDiskKV`, 60 composers), hold it with a second connection
+(`BEGIN EXCLUSIVE`, or WAL + `locking_mode = EXCLUSIVE` + a write), and run the
+same discovery + per-session read pass through a pristine pre-cycle tree
+(`git archive HEAD packages/core/src | tar -x -C /tmp/baseline`) and the working
+tree in one process. The real-store pass copies the live store to `/tmp` first
+and locks only the *copy* — the user's store is never locked, and the copy is
+deleted afterwards. Every property above is pinned by
+`tests/native-sqlite-ro.test.ts` and the two re-pinned adapter tests.
+
+**INFERRED** (not directly measured, listed so reviewers can attack them)
+
+- The ~1.1 s still spent on a locked store is the probe's `busy_timeout`
+  grace, kept deliberately: a transient lock (< 1 s) resolves without a copy,
+  and the copy is taken once per stamp instead of once per read.
+- The database-identity recheck closes the checkpoint/restart transition and
+  nothing else: ordinary WAL commits never touch the database file, so a
+  healthy copy is never rejected for writing. A `-wal` identity check would fire
+  on every commit and was rejected for that reason.
+- Residual exposure: a rollback-journal copy taken while the writer commits can
+  still capture a half-written page (there is no wal to validate it), so a
+  copy-derived malformed-row verdict is possible and cannot be separated from
+  genuinely malformed content. The ingest pipeline re-reads a session whenever
+  the source fingerprint moves, so the window is bounded by the next write.
+- Cross-process reuse is deliberately absent (copies are deleted at exit), so a
+  new sync of a still-held store copies again; the alternative leaks private
+  transcripts into `/tmp` across runs.
+- A copy root left at mode 0755 by a pre-check revision of this branch disables
+  the fallback until it is removed or chmodded (`rm -rf $TMPDIR/ledger-native-db`
+  restores it); no released build ever created a non-private root.
+- A recycled pid can keep one orphaned copy directory until that pid dies;
+  bounded by `MAX_SQLITE_COPY_BYTES` per store.
+
+## Cutover audit (2026-09-16, after cloud round 1)
+
+Round 1's medium was that `parentage.ts` and `normalizer.ts` still opened
+native stores directly, so a held Hermes/OpenCode store could keep its parent
+link and its session assembly while the adapter reads succeeded. Both now call
+`withReadOnlyDb` from `native/sqlite-ro.js`; the check below is exhaustive for
+`packages/core/src`:
+
+| opener | target | status |
+| --- | --- | --- |
+| `native/sqlite-ro.ts` (probe, copy) | agent stores | the gradient itself |
+| `native/cursor.ts`, `native/opencode.ts` | Cursor, OpenCode stores | migrated (cycle 1) |
+| `parentage.ts` `extractHermesParentage`, `extractOpenCodeSqliteParentage` | Hermes, OpenCode stores | migrated (round 1 fix) |
+| `normalizer.ts` Hermes branch | Hermes store | migrated (round 1 fix) |
+| `db.ts`, `sync.ts`, `writer-lease.ts`, `schema-gate.ts`, `reader.ts` | the Ledger store and its lease database | out of scope by definition: these are Ledger's own artifacts, not another application's, and the store's write path must keep its own locking |
+
+`node:sqlite`/`DatabaseSync` appears nowhere in `packages/core` (the mentions in
+`confer/` and `lab/` are third-party notes and run artifacts).
+
+Tests, one held-store case per migrated caller: `parentage.test.ts` "reads
+Hermes parent_session_id while the store is held by its writer" and "reads
+OpenCode parent_id while the store is held by its writer" (each asserts
+`SQLITE_BUSY` on the direct route first, then the parent link, then that no
+diagnostic fired), and `normalizer.test.ts` "normalizes a Hermes store held by
+its writer through the copy fallback" (direct route asserted blocked, both
+turns normalized, and the same call reads the parent link, so the case covers
+the parentage migration too).
+
+## Remaining out of scope
+
+- Non-lock recovery failures (WAL store whose `-shm` was deleted out-of-band)
+  stay `read_error`; enabling the copy there needs a decision about publishing
+  checkpoint-only evidence, not a code change.
+- Program doc pins the remaining cycles C2–C10; the consolidated follow-up
+  issue for this cycle's nits is opened by the parent at merge time.