@dimina-kit/fs-core 0.2.0-dev.20260711062001 → 0.3.0-dev.6-dev.20260711140249

package/sync/sync-engine.ts

@@ -1,7 +1,7 @@
 /**
- * Sync arbitration engine — the memfs<->disk synchronization core factored
- * out of dimina-kit's workbench `wal-audit.ts` (see
- * devtools-fs-core-feasibility.md §7+§8). A host wires a `client` (the
+ * Sync arbitration engine — the memfs<->disk synchronization core shared by
+ * every host that pairs an fs-core ledger with an external truth source.
+ * A host wires a `client` (the
  * fs-core ledger: write/rm/read/ls) and a `TruthPort` (its external truth
  * source — devtools' `/__fs` bridge + SSE watch, or a future FSA
  * local-directory adapter) and gets back an engine that keeps the ledger,
@@ -10,54 +10,43 @@
  * host's own audit-turn surface talks to `client` directly for that (see
  * wal-audit.ts).
  *
- * Echo judgement (both directions):
+ * Echo judgement (both directions, content comparison against the ledger's
+ * own record):
  *  - Outbound (`onHumanSave`): before recording, compare the saved text
  *    against the ledger's current record for that path — identical content
  *    is a no-op (the ledger already reflects it), skipping a redundant
- *    write.
- *  - Inbound (`changes` batches, via `handleInboundPath`): first check
- *    `pendingWrite` — an entry there was registered by an `onHumanSave` still
- *    in flight for the same path, and its presence means this inbound
- *    notification is that write's own echo, absorbed with no ledger write
- *    and no editor refresh. This check is a structural no-op for a 'push'
- *    port (devtools' SSE): registration and clearing both happen inside the
- *    SAME `ledgerTurn` FIFO slot as the write they guard (see
- *    `onHumanSave`), so by the time any later-queued inbound turn for that
- *    path runs, the entry is already gone — the branch exists for a future
- *    'poll' host whose change detection runs OUTSIDE this FIFO (e.g. an
- *    mtime/size sweep) and can therefore observe the entry while the write
- *    is still in flight. When `pendingWrite` misses, the engine falls back
- *    to today's content comparison (truth-source bytes vs. the ledger's own
- *    record) — the only judgement a push host ever actually exercises.
+ *    write. The onHumanSave accounting step and inbound batches run through
+ *    the same `ledgerTurn` FIFO, so an inbound notification for a path whose
+ *    save is still in flight always observes the completed ledger write and
+ *    absorbs itself via that same comparison.
+ *  - Inbound (`changes` batches, via `handleInboundPath`): truth-source
+ *    bytes equal to the ledger's record are the echo of our own last write —
+ *    dropped with no ledger write and no editor refresh.
+ * This engine serves 'push' ports only (the port notifies; the host's
+ * outbound writes go through `onHumanSave`). A future 'poll' host whose
+ * outbound scan runs outside this module must own its own one-shot echo
+ * suppression — see the README's「两套磁盘机制的划界」section for the
+ * invariants such an adapter has to satisfy.
  *
- * Inbound-echo consumption (`consumeInboundEcho`, `inboundApplied`): a 'poll'
- * host (e.g. the web local-directory adapter) drives its OWN outbound path
- * OUTSIDE this module — it reads the ledger and writes the truth source
- * directly, not through `onHumanSave` — so a change this engine just applied
- * INBOUND (disk -> ledger, via `handleInboundPath`) can race that host's
- * outbound scan and get echoed straight back to disk before the poll
- * baseline ever settles. `inboundApplied` (`rel -> {kind:'text'|'binary'|
- * 'delete', ...}`) records exactly what `handleInboundPath` just applied,
- * overwriting any prior entry for the same path; `consumeInboundEcho(rel,
- * content)` lets such a host check "is this outbound write about to re-emit
- * an inbound change I haven't published yet?" immediately BEFORE writing to
- * the truth source, consuming (clearing) the record on a match so it is a
- * one-shot suppression, not a standing content cache. A miss (different
- * content, or no record at all) returns false and leaves any existing record
- * untouched — it is not this call's echo to consume.
+ * Degradation is loud (`onDegraded`): a dead watcher and a path that failed
+ * to sync (truth-source read failure, or a ledger write/rm failure while
+ * reconciling) are surfaced to the host through {@link SyncDegradation} in
+ * addition to the console warning — silently skipping them would let the
+ * ledger drift with no operator-visible signal.
  *
- * Binary layering (v1): the first 8192 bytes of a file are sniffed for a NUL
- * byte to classify it binary. A binary file never reaches the fs-core
- * ledger (`client.write`/`read`) — it is tracked only in the in-memory
- * `binaryIndex` (`rel -> { size, sha256 }`), and echo judgement for it is
- * size+hash equality instead of a ledger content compare. What/why this is
- * narrower than the text path: binary changes get NO WAL audit and NO
- * rollback (the audit turn surface — `diff`/`restore` — is a string-content
- * contract; v1 does not support an agent writing binary inside a turn), and
- * `binaryIndex` is session-scoped — it is cleared and rebuilt from scratch on
- * every `populateLedger()`, exactly like the ledger's own text reconciliation.
+ * Binary layering: classification (NUL sniff), the `rel -> {size, sha256}`
+ * index, and echo judgement (size+hash equality instead of a ledger content
+ * compare) are all owned by ./binary-sidecar.ts — see that module's doc; this
+ * engine holds an INDEX-ONLY sidecar. A binary file never reaches the fs-core
+ * ledger (`client.write`/`read`). What/why this is narrower than the text
+ * path: binary changes get NO WAL audit and NO rollback (the audit turn
+ * surface — `diff`/`restore` — is a string-content contract; the engine does
+ * not support an agent writing binary inside a turn), and the sidecar is
+ * session-scoped — cleared and rebuilt from scratch on every
+ * `populateLedger()`, exactly like the ledger's own text reconciliation.
  */
 
+import { createBinarySidecar, looksBinary } from './binary-sidecar.js'
 import type { TruthPort } from './truth-port.js'
 
 export type { TruthPort, TruthPortCapabilities } from './truth-port.js'
@@ -77,6 +66,20 @@ export interface SyncClientLike {
   ls(): Promise<{ paths: string[] }>
 }
 
+/**
+ * A host-visible sync degradation (see the module doc's "Degradation is
+ * loud" paragraph):
+ *  - `watcher-dead`: the port's change subscription died — from now on the
+ *    ledger only reflects the open-time mirror plus already-processed
+ *    batches.
+ *  - `path-sync-failed`: one path failed to reconcile and was skipped;
+ *    `stage` says where — `truth-read` (the truth source's read rejected
+ *    transiently) or `reconcile` (the ledger write/rm itself failed).
+ */
+export type SyncDegradation =
+  | { kind: 'watcher-dead' }
+  | { kind: 'path-sync-failed'; rel: string; stage: 'truth-read' | 'reconcile'; error: unknown }
+
 export interface SyncEngineOptions {
   /**
    * Host seam: push an inbound change into the live editor buffer.
@@ -84,6 +87,12 @@ export interface SyncEngineOptions {
    * records the change but the editor buffer is left untouched.
    */
   applyToEditor?: (rel: string, bytes: Uint8Array | null) => Promise<void>
+  /**
+   * Host seam: surface a {@link SyncDegradation}. Called in addition to the
+   * console warning, never instead of it; a throwing callback is the host's
+   * own bug and never breaks the engine.
+   */
+  onDegraded?: (degradation: SyncDegradation) => void
 }
 
 export interface SyncEngine {
@@ -105,47 +114,12 @@ export interface SyncEngine {
    * route it to the session-scoped `binaryIndex` instead of the ledger.
    */
   onHumanSave(rel: string, content: string | Uint8Array): Promise<void>
-  /**
-   * One-shot check for a 'poll' host's own outbound path (see this module's
-   * "Inbound-echo consumption" doc): call this BEFORE writing `content` (the
-   * decoded text, raw bytes, or `null` for a delete) for `rel` out to the
-   * truth source. Returns `true` when it exactly matches what
-   * `handleInboundPath` just applied FROM that same truth source — that
-   * write would be a pure echo, so the caller should skip it — and clears
-   * the record so it cannot match again (one-shot, not a standing cache).
-   * Returns `false` on any mismatch or when there is no record at all,
-   * leaving any existing record untouched.
-   */
-  consumeInboundEcho(rel: string, content: string | Uint8Array | null): boolean
   /** Subscribe to `port.changes` and start reconciling inbound batches. */
   start(): void
   /** Tear down the `port.changes` subscription. Idempotent. */
   stop(): void
 }
 
-const BINARY_SNIFF_BYTES = 8192
-
-/** True when the first `BINARY_SNIFF_BYTES` of `bytes` contain a NUL byte. */
-function looksBinary(bytes: Uint8Array): boolean {
-  const len = Math.min(bytes.length, BINARY_SNIFF_BYTES)
-  for (let i = 0; i < len; i++) {
-    if (bytes[i] === 0) return true
-  }
-  return false
-}
-
-async function sha256hex(bytes: Uint8Array): Promise<string> {
-  const digest = await crypto.subtle.digest('SHA-256', bytes as BufferSource)
-  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('')
-}
-
-/** Byte-for-byte equality — used by `consumeInboundEcho`'s binary-content match. */
-function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
-  if (a.length !== b.length) return false
-  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
-  return true
-}
-
 /**
  * True when `error` denotes "path does not exist" per the TruthPort error
  * contract (see truth-port.ts): `error.code === 'not-found'` or
@@ -157,11 +131,6 @@ function isNotFoundError(error: unknown): boolean {
   return Boolean(e) && (e!.code === 'not-found' || e!.status === 404)
 }
 
-type InboundApplied =
-  | { kind: 'text'; text: string }
-  | { kind: 'binary'; bytes: Uint8Array }
-  | { kind: 'delete' }
-
 export function createSyncEngine(
   client: SyncClientLike,
   port: TruthPort,
@@ -170,30 +139,22 @@ export function createSyncEngine(
   const decoder = new TextDecoder()
   const applyToEditor = opts.applyToEditor
 
-  /**
-   * Paths with an `onHumanSave` write in flight — see the module doc's
-   * "Echo judgement" section. Registered synchronously when `onHumanSave` is
-   * called and cleared unconditionally (`finally`) once that write's own
-   * ledgerTurn slot finishes, success or failure.
-   */
-  const pendingWrite = new Set<string>()
+  /** Surface a degradation to the host — a throwing callback is the host's
+   * own bug and must not break the reconciliation that reported it. */
+  function degrade(degradation: SyncDegradation): void {
+    try {
+      opts.onDegraded?.(degradation)
+    } catch (e) {
+      console.warn('[fs-core/sync] onDegraded callback threw', e)
+    }
+  }
 
   /**
    * Binary files never enter the fs-core ledger — see the module doc's
-   * "Binary layering" section. Session-scoped: rebuilt from scratch on every
-   * `populateLedger()`.
-   */
-  const binaryIndex = new Map<string, { size: number; sha256: string }>()
-
-  /**
-   * `rel -> { kind: 'text', text } | { kind: 'binary', bytes } | { kind: 'delete' }`
-   * — see the module doc's "Inbound-echo consumption" section. Written by
-   * `handleInboundPath` immediately after it actually applies an inbound
-   * change (ledger write/rm, or a binary/delete index update); consumed
-   * (checked + cleared on a match) by `consumeInboundEcho`. Session-scoped,
-   * same as `binaryIndex` — cleared on every `populateLedger()`.
+   * "Binary layering" section. Index-only (this engine never needs the bytes
+   * back); session-scoped: rebuilt from scratch on every `populateLedger()`.
    */
-  const inboundApplied = new Map<string, InboundApplied>()
+  const binaryIndex = createBinarySidecar()
 
   /**
    * FIFO queue serializing every compare-then-record against the ledger
@@ -217,13 +178,12 @@ export function createSyncEngine(
    * same persisted ledger identity) and are removed so the ledger ends up
    * exactly matching the walked tree. */
   async function seedFromDisk(): Promise<void> {
-    binaryIndex.clear()
-    inboundApplied.clear()
+    await binaryIndex.clear()
     const seen = new Set<string>()
     await port.walk(async (rel, bytes) => {
       seen.add(rel)
       if (looksBinary(bytes)) {
-        binaryIndex.set(rel, { size: bytes.length, sha256: await sha256hex(bytes) })
+        await binaryIndex.put(rel, bytes)
         return // binary never enters the ledger
       }
       await client.write(rel, decoder.decode(bytes), { actor: 'human' })
@@ -238,27 +198,23 @@ export function createSyncEngine(
   }
 
   /**
-   * Process one inbound path. `pendingWrite` is checked first (see module
-   * doc); a miss falls back to content comparison: identical content is the
-   * echo of our own last write and is dropped with no ledger write and no
-   * `applyToEditor` call. A `port.read` rejection classified as not-found
+   * Process one inbound path via content comparison: identical content is
+   * the echo of our own last write and is dropped with no ledger write and
+   * no `applyToEditor` call. A `port.read` rejection classified as not-found
    * (see truth-port.ts) is a deletion; any other rejection
-   * ("unavailable") is transient and skips the path entirely — inferring a
-   * deletion from it would rm the ledger record and close the file in the
-   * editor while it still exists at the truth source.
+   * ("unavailable") is transient and skips the path entirely (surfaced as a
+   * `truth-read` degradation) — inferring a deletion from it would rm the
+   * ledger record and close the file in the editor while it still exists at
+   * the truth source.
    */
   async function handleInboundPath(rel: string): Promise<void> {
-    if (pendingWrite.has(rel)) {
-      pendingWrite.delete(rel)
-      return
-    }
-
     let bytes: Uint8Array | null
     try {
       bytes = await port.read(rel)
     } catch (e) {
       if (!isNotFoundError(e)) {
         console.warn('[fs-core/sync] transient port read failure, skipping', rel, e)
+        degrade({ kind: 'path-sync-failed', rel, stage: 'truth-read', error: e })
         return
       }
       bytes = null
@@ -269,30 +225,35 @@ export function createSyncEngine(
       // ledger (it never took the client.write path), so removal here is
       // index-only — no client.rm.
       if (binaryIndex.has(rel)) {
-        binaryIndex.delete(rel)
-        inboundApplied.set(rel, { kind: 'delete' })
+        await binaryIndex.remove(rel)
         await applyToEditor?.(rel, null)
         return
       }
       let ledgerContent: string | undefined
       try {
         ledgerContent = (await client.read(rel)).content
-      } catch {
+      } catch (e) {
+        if (!isNotFoundError(e)) {
+          // A transient ledger read failure is NOT "already absent" — rm'ing
+          // (or silently skipping) on unknown ledger state would either drop
+          // a record we could not confirm or leave it stale with no signal.
+          // Skip the path and surface it; the next change event retries.
+          console.warn('[fs-core/sync] ledger read failed while confirming a deletion, skipping', rel, e)
+          degrade({ kind: 'path-sync-failed', rel, stage: 'reconcile', error: e })
+          return
+        }
         ledgerContent = undefined
       }
       if (ledgerContent === undefined) return // already absent from both sides
       await client.rm(rel, { actor: 'human' })
-      inboundApplied.set(rel, { kind: 'delete' })
       await applyToEditor?.(rel, null)
       return
     }
 
     if (looksBinary(bytes)) {
-      const prior = binaryIndex.get(rel)
-      const sha256 = await sha256hex(bytes)
-      if (prior && prior.size === bytes.length && prior.sha256 === sha256) return // echo: same bytes already indexed
-      binaryIndex.set(rel, { size: bytes.length, sha256 })
-      inboundApplied.set(rel, { kind: 'binary', bytes })
+      // Echo judgement is the sidecar's put(): `false` = same size+sha256
+      // already indexed, i.e. the echo of our own last write.
+      if (!(await binaryIndex.put(rel, bytes))) return
       await applyToEditor?.(rel, bytes)
       return
     }
@@ -312,39 +273,16 @@ export function createSyncEngine(
     if (ledgerContent !== undefined && text === ledgerContent) return // echo of our own write
 
     await client.write(rel, text, { actor: 'human' })
-    inboundApplied.set(rel, { kind: 'text', text })
     await applyToEditor?.(rel, bytes)
   }
 
-  /**
-   * One-shot check for a 'poll' host's own outbound path: "is `content` (the
-   * bytes/text about to be written to the truth source for `rel`, or `null`
-   * for a delete) exactly what `handleInboundPath` just applied FROM that
-   * same truth source?" A match means writing it back out would be a pure
-   * echo — the host should skip the write entirely — and the record is
-   * cleared (consumed) so it cannot match again. See the module doc's
-   * "Inbound-echo consumption" section for why a push host (devtools) never
-   * needs this: its outbound path goes through `onHumanSave`/`pendingWrite`
-   * instead.
-   */
-  function consumeInboundEcho(rel: string, content: string | Uint8Array | null): boolean {
-    const entry = inboundApplied.get(rel)
-    if (!entry) return false
-    let matches: boolean
-    if (content === null) matches = entry.kind === 'delete'
-    else if (typeof content === 'string') matches = entry.kind === 'text' && entry.text === content
-    else matches = entry.kind === 'binary' && bytesEqual(entry.bytes, content)
-    if (matches) inboundApplied.delete(rel)
-    return matches
-  }
-
   /**
    * A batch is trusted as-is: the port adapter (see truth-port.ts's
    * `changes` doc) is responsible for turning a watcher's coalesced/lossy
    * events into the actual set of paths worth re-examining BEFORE calling
-   * this engine — devtools' adapter (wal-audit.ts +
-   * wal-audit-watch-expand.ts) does that via a stat-level disk compare
-   * against a session index, so paths arriving here have already earned
+   * this engine — devtools' adapter (dimina-kit workbench's wal-audit.ts +
+   * this package's ./watch-expander.ts) does that via a stat-level disk
+   * compare against a session index, so paths arriving here have already earned
    * their re-examination and no further expansion happens at this layer.
    */
   async function handleBatch(paths: string[]): Promise<void> {
@@ -356,6 +294,7 @@ export function createSyncEngine(
         await enqueueLedgerTurn(() => handleInboundPath(rel))
       } catch (e) {
         console.warn('[fs-core/sync] disk sync failed for', rel, e)
+        degrade({ kind: 'path-sync-failed', rel, stage: 'reconcile', error: e })
       }
     }
   }
@@ -385,10 +324,27 @@ export function createSyncEngine(
   /** Subscribe to `port.changes`. `active` gates BOTH callbacks so a
    * late/duplicate event delivered after `onDead` (or after a fresh
    * `start()` superseded this subscription) is a guaranteed no-op, not just
-   * best-effort. */
+   * best-effort. The subscription is torn down through `disposeOnce`: the
+   * TruthPort contract does not require an idempotent dispose, and a host's
+   * `onDegraded` callback may synchronously call `engine.stop()` — without
+   * the guard that re-enters the same dispose a second time. */
   function start(): void {
     let active = true
-    const dispose = port.changes(
+    let disposed = false
+    // "dispose requested" and "dispose implementation available" are split:
+    // a port may fire onDead synchronously DURING the changes() call, before
+    // its dispose function even exists — the request is recorded via
+    // `disposed` and the implementation is invoked right after the
+    // subscription call returns it (see below). Declared-then-assigned (not
+    // `const`) precisely so that a during-subscription disposeOnce() reads
+    // `undefined` instead of hitting a temporal dead zone.
+    let disposeImpl: (() => void) | undefined = undefined
+    function disposeOnce(): void {
+      if (disposed) return
+      disposed = true
+      disposeImpl?.()
+    }
+    disposeImpl = port.changes(
       (paths) => {
         if (!active) return
         enqueueInboundBatch(paths)
@@ -397,12 +353,16 @@ export function createSyncEngine(
         if (!active) return
         active = false
         console.warn('[fs-core/sync] watcher died — reverting to open-time mirror only')
-        dispose()
+        disposeOnce()
+        degrade({ kind: 'watcher-dead' })
       },
     )
+    // Dispose was requested during subscription (synchronous onDead): the
+    // implementation exists now — honor the request exactly once.
+    if (disposed) disposeImpl()
     stopWatching = () => {
       active = false
-      dispose()
+      disposeOnce()
     }
   }
 
@@ -412,12 +372,11 @@ export function createSyncEngine(
   }
 
   /**
-   * Outbound accounting for a human save: registers `rel` in `pendingWrite`
-   * for the duration of the ledger compare-then-write (see module doc),
-   * skips the ledger write when the saved text already matches the ledger's
-   * record, and runs inside the same `ledgerTurn` FIFO as inbound batches so
-   * the two can never interleave. Errors propagate to the caller — a host's
-   * onSave wrapper decides whether a ledger-write failure should be
+   * Outbound accounting for a human save: skips the ledger write when the
+   * saved text already matches the ledger's record, and runs inside the same
+   * `ledgerTurn` FIFO as inbound batches so the two can never interleave
+   * (see module doc's "Echo judgement"). Errors propagate to the caller — a
+   * host's onSave wrapper decides whether a ledger-write failure should be
    * swallowed (best-effort accounting must never unwind a save that already
    * landed at the truth source).
    *
@@ -428,31 +387,25 @@ export function createSyncEngine(
    * entirely and only updates `binaryIndex`.
    */
   async function onHumanSave(rel: string, content: string | Uint8Array): Promise<void> {
-    pendingWrite.add(rel)
-    try {
-      if (content instanceof Uint8Array && looksBinary(content)) {
-        await enqueueLedgerTurn(async () => {
-          binaryIndex.set(rel, { size: content.length, sha256: await sha256hex(content) })
-        })
-        return
-      }
-      const text = typeof content === 'string' ? content : decoder.decode(content)
+    if (content instanceof Uint8Array && looksBinary(content)) {
       await enqueueLedgerTurn(async () => {
-        const unchanged = await client
-          .read(rel)
-          .then((r) => r.content === text)
-          .catch(() => false)
-        if (!unchanged) await client.write(rel, text, { actor: 'human' })
+        await binaryIndex.put(rel, content)
       })
-    } finally {
-      pendingWrite.delete(rel)
+      return
     }
+    const text = typeof content === 'string' ? content : decoder.decode(content)
+    await enqueueLedgerTurn(async () => {
+      const unchanged = await client
+        .read(rel)
+        .then((r) => r.content === text)
+        .catch(() => false)
+      if (!unchanged) await client.write(rel, text, { actor: 'human' })
+    })
   }
 
   return {
     populateLedger: seedFromDisk,
     onHumanSave,
-    consumeInboundEcho,
     start,
     stop,
   }

package/sync/truth-port.ts

@@ -64,9 +64,9 @@ export interface TruthPort {
    * that scope against a session index, and report every path whose stat
    * actually moved, plus ledger paths in scope that vanished from disk).
    * `handleBatch` in sync-engine.ts takes `onBatch`'s paths at face value
-   * and does no further expansion — see devtools' adapter
-   * (dimina-kit workbench's wal-audit.ts + wal-audit-watch-expand.ts) for a
-   * concrete implementation of this contract.
+   * and does no further expansion — ./watch-expander.ts is the optional
+   * helper implementing exactly that recovery; see devtools' adapter
+   * (dimina-kit workbench's wal-audit.ts) for a concrete assembly.
    */
   changes(onBatch: (paths: string[]) => void, onDead: () => void): () => void
 }

package/sync/watch-expander.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Unit tests for the watch-batch expander's stat-diff contract, against a
+ * fake stat-capable readdir. The full black-box behavior (through a real
+ * TruthPort assembly) stays covered by dimina-kit workbench's
+ * wal-audit-disk-stat-expansion.test.ts — these pin the module's own
+ * algorithmic promises at the fs-core boundary.
+ */
+import { describe, expect, it } from 'vitest'
+import { createWatchExpander } from './watch-expander.js'
+import type { WatchExpanderEntry } from './watch-expander.js'
+
+/** In-memory tree: rel -> {size, mtimeMs}. Directories are implied by their
+ * children's paths, same as a real filesystem listing would show them. */
+function makeDisk(files: Record<string, { size: number; mtimeMs: number }>) {
+  const readdir = async (rel: string): Promise<WatchExpanderEntry[]> => {
+    const prefix = rel === '.' || rel === '' ? '' : `${rel}/`
+    const names = new Map<string, WatchExpanderEntry>()
+    let matchedScope = prefix === ''
+    for (const [p, stat] of Object.entries(files)) {
+      if (!p.startsWith(prefix)) continue
+      matchedScope = true
+      const rest = p.slice(prefix.length)
+      const slash = rest.indexOf('/')
+      if (slash === -1) names.set(rest, [rest, 1, stat.size, stat.mtimeMs])
+      else names.set(rest.slice(0, slash), [rest.slice(0, slash), 2])
+    }
+    // A path that is neither a file nor an ancestor of one does not exist —
+    // and listing a FILE path is an error too, like a real readdir(file).
+    if (!matchedScope || rel in files) throw new Error(`ENOTDIR/ENOENT: ${rel}`)
+    return [...names.values()]
+  }
+  return { files, readdir }
+}
+
+describe('createWatchExpander', () => {
+  it('reports only the stat-changed file for a coalesced directory event (after warm-up)', async () => {
+    const disk = makeDisk({
+      'src/a.txt': { size: 3, mtimeMs: 100 },
+      'src/b.txt': { size: 3, mtimeMs: 100 },
+      'src/c.txt': { size: 3, mtimeMs: 100 },
+    })
+    const ex = createWatchExpander(disk.readdir)
+    await ex.warmFromDisk()
+    disk.files['src/b.txt'] = { size: 4, mtimeMs: 200 }
+    const out = await ex.expandWatchBatch(['src'], ['src/a.txt', 'src/b.txt', 'src/c.txt'])
+    expect(out).toEqual(['src/b.txt'])
+  })
+
+  it('recovers a coalesced deletion: ledger paths missing from the listed scope are reported', async () => {
+    const disk = makeDisk({ 'src/a.txt': { size: 3, mtimeMs: 100 } })
+    const ex = createWatchExpander(disk.readdir)
+    await ex.warmFromDisk()
+    // rm -rf took b.txt and c.txt; the watcher only named the directory.
+    const out = await ex.expandWatchBatch(['src'], ['src/a.txt', 'src/b.txt', 'src/c.txt'])
+    expect(out.sort()).toEqual(['src/b.txt', 'src/c.txt'])
+  })
+
+  it("expands the '.' overflow rescan against the whole tree + whole ledger", async () => {
+    const disk = makeDisk({ 'kept.txt': { size: 1, mtimeMs: 1 }, 'new.txt': { size: 1, mtimeMs: 1 } })
+    const ex = createWatchExpander(disk.readdir)
+    // warm only knows kept.txt
+    delete disk.files['new.txt']
+    await ex.warmFromDisk()
+    disk.files['new.txt'] = { size: 1, mtimeMs: 1 }
+    const out = await ex.expandWatchBatch(['.'], ['kept.txt', 'gone.txt'])
+    expect(out.sort()).toEqual(['gone.txt', 'new.txt'])
+  })
+
+  it('always reports a point-named plain file (content can change without a stat move)', async () => {
+    const disk = makeDisk({ 'a.txt': { size: 3, mtimeMs: 100 } })
+    const ex = createWatchExpander(disk.readdir)
+    await ex.warmFromDisk()
+    // stat unchanged — the file itself must still be reported.
+    const out = await ex.expandWatchBatch(['a.txt'], ['a.txt'])
+    expect(out).toEqual(['a.txt'])
+  })
+
+  it('excludes a point-named live directory UNLESS the ledger still records that exact path', async () => {
+    const disk = makeDisk({ 'src/a.txt': { size: 3, mtimeMs: 100 } })
+    const ex = createWatchExpander(disk.readdir)
+    await ex.warmFromDisk()
+    expect(await ex.expandWatchBatch(['src'], ['src/a.txt'])).toEqual([])
+    // Same-named file→directory replacement: a stale ledger FILE record at
+    // 'src' must be reported so the engine's read can retire it.
+    expect(await ex.expandWatchBatch(['src'], ['src', 'src/a.txt'])).toEqual(['src'])
+  })
+
+  it('resetIndex() forgets the session index: every disk file reports again', async () => {
+    const disk = makeDisk({ 'src/a.txt': { size: 3, mtimeMs: 100 } })
+    const ex = createWatchExpander(disk.readdir)
+    await ex.warmFromDisk()
+    expect(await ex.expandWatchBatch(['src'], ['src/a.txt'])).toEqual([])
+    ex.resetIndex()
+    expect(await ex.expandWatchBatch(['src'], ['src/a.txt'])).toEqual(['src/a.txt'])
+  })
+})