@dimina-kit/fs-core 0.2.0-dev.20260710085051 → 0.3.0-dev.6-dev.20260711133419

package/sync/binary-sidecar.ts

@@ -0,0 +1,187 @@
+/**
+ * Binary side-car — the authoritative owner of "binary files live OUTSIDE the
+ * fs-core string ledger". The ledger's write/read surface is a string-content
+ * contract (WAL audit, diff/restore all reason over text), so every host that
+ * meets a binary file needs the same three things this module owns exactly
+ * once:
+ *
+ *  - classification: {@link looksBinary} (a NUL byte in the first 8192 bytes);
+ *  - a unified index: `rel -> { size, sha256 }`, maintained for every entry
+ *    regardless of whether bytes are retained;
+ *  - echo judgement: {@link BinarySidecar.put} compares size+sha256 against
+ *    the prior entry and reports `false` (unchanged) for a re-arrival of the
+ *    same bytes — the exact judgement the sync engine uses to absorb a binary
+ *    file's own write echo.
+ *
+ * Two host shapes, one abstraction:
+ *  - dimina-kit's sync engine (sync-engine.ts) keeps an INDEX-ONLY sidecar —
+ *    it never needs the bytes back, only membership + echo judgement;
+ *  - a host whose ledger snapshot must be re-joined with the binary set
+ *    (qdmp-web-workbench feeding compile/export/disk-mirror) constructs it
+ *    with `retainBytes: true` and uses {@link BinarySidecar.overlay} as the
+ *    ONE place that merges "ledger text + binary side-car" (ledger text wins
+ *    on a path present in both — the ledger is the authority for anything it
+ *    holds).
+ *
+ * Change events (`onChange`) fire on every effective mutation (`put` that
+ * actually changed, `remove` of an existing entry) — `clear()`/`reset()` are
+ * session reseeds (project switch / ledger repopulate) and deliberately do
+ * NOT emit per-entry removals; a subscriber that survives a reseed should
+ * re-read the sidecar wholesale, same as it re-reads the ledger.
+ */
+
+import { sha256hex } from '#worker-lib/wal-codec.js'
+
+const BINARY_SNIFF_BYTES = 8192
+
+/** True when the first {@link BINARY_SNIFF_BYTES} of `bytes` contain a NUL
+ * byte — the classification gate for the whole binary layering. */
+export 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
+}
+
+export interface BinarySidecarEntry {
+  size: number
+  sha256: string
+}
+
+export interface BinarySidecarOptions {
+  /** Keep the actual bytes alongside the index (for hosts that re-join the
+   * binary set with ledger snapshots — see the module doc). Default: index
+   * only. */
+  retainBytes?: boolean
+}
+
+export interface BinarySidecar {
+  /** Record `bytes` for `rel`. Returns `false` when the entry is an echo of
+   * what is already recorded (same size + sha256) — nothing changes and no
+   * event fires — and `true` when the entry was created or updated. */
+  put(rel: string, bytes: Uint8Array): Promise<boolean>
+  /** Remove `rel`. Resolves to whether an entry actually existed. */
+  remove(rel: string): Promise<boolean>
+  has(rel: string): boolean
+  entry(rel: string): BinarySidecarEntry | undefined
+  /** The retained bytes for `rel` — always `undefined` without `retainBytes`. */
+  bytes(rel: string): Uint8Array | undefined
+  keys(): string[]
+  readonly size: number
+  /** Session reseed: drop everything, silently (see the module doc). */
+  clear(): Promise<void>
+  /** Bulk session reseed: replace the whole content with `files` — the reseed
+   * a host's project-open path uses. */
+  reset(files: Record<string, Uint8Array>): Promise<void>
+  /** Snapshot of the retained bytes (`retainBytes` hosts only; empty otherwise). */
+  toRecord(): Record<string, Uint8Array>
+  /** THE merge of "ledger text + binary side-car": entries of `files` win
+   * over sidecar bytes for a path present in both. Requires `retainBytes`. */
+  overlay<T>(files: Record<string, T>): Record<string, T | Uint8Array>
+  /** Subscribe to effective mutations (`bytes === null` = removal). Returns
+   * an unsubscribe function. */
+  onChange(cb: (rel: string, bytes: Uint8Array | null) => void): () => void
+}
+
+export function createBinarySidecar(opts: BinarySidecarOptions = {}): BinarySidecar {
+  const retainBytes = opts.retainBytes === true
+  // `let` (not const): reset() swaps in fully-built replacement maps in one
+  // synchronous step — see its body.
+  let index = new Map<string, BinarySidecarEntry>()
+  let store = new Map<string, Uint8Array>()
+  const changeCbs = new Set<(rel: string, bytes: Uint8Array | null) => void>()
+
+  /**
+   * FIFO serializing every MUTATION (put/remove/clear/reset) in caller order.
+   * Without it, a put whose (async) hashing straddles an in-flight reset()
+   * lands on maps the reset is about to swap away — the mutation silently
+   * vanishes — and two overlapping resets resolve as "last swapper wins"
+   * instead of "last caller wins". Serialized, a mutation issued after
+   * reset() runs after it and lands in the NEW session; one issued before is
+   * superseded by it — nothing races across a session boundary. READS
+   * (has/entry/bytes/keys/overlay/toRecord) stay synchronous against the
+   * currently visible maps: reset's one-step swap keeps them consistent.
+   * The chain swallows step rejections so one failed mutation cannot wedge
+   * the queue.
+   */
+  let mutationTurn: Promise<unknown> = Promise.resolve()
+  function enqueueMutation<T>(fn: () => T | Promise<T>): Promise<T> {
+    const next = mutationTurn.then(fn, fn) as Promise<T>
+    mutationTurn = next.catch(() => {})
+    return next
+  }
+
+  function emit(rel: string, bytes: Uint8Array | null): void {
+    for (const cb of changeCbs) {
+      try {
+        cb(rel, bytes)
+      } catch {
+        // A subscriber's failure is its own — it must not break the mutation
+        // that already happened, nor starve later subscribers.
+      }
+    }
+  }
+
+  return {
+    put(rel, bytes) {
+      return enqueueMutation(async () => {
+        const sha256 = await sha256hex(bytes)
+        const prior = index.get(rel)
+        if (prior && prior.size === bytes.length && prior.sha256 === sha256) return false
+        index.set(rel, { size: bytes.length, sha256 })
+        if (retainBytes) store.set(rel, bytes)
+        emit(rel, bytes)
+        return true
+      })
+    },
+    remove(rel) {
+      return enqueueMutation(() => {
+        const existed = index.delete(rel)
+        store.delete(rel)
+        if (existed) emit(rel, null)
+        return existed
+      })
+    },
+    has: (rel) => index.has(rel),
+    entry: (rel) => index.get(rel),
+    bytes: (rel) => store.get(rel),
+    keys: () => [...index.keys()],
+    get size() {
+      return index.size
+    },
+    clear() {
+      return enqueueMutation(() => {
+        index.clear()
+        store.clear()
+      })
+    },
+    reset(files) {
+      return enqueueMutation(async () => {
+        // Atomic to readers: hashing runs against LOCAL maps and the visible
+        // state is swapped in one synchronous step at the end — a concurrent
+        // overlay()/toRecord()/entry() sees either the old set or the new
+        // set, never an empty or half-built one. Silent by design (see the
+        // module doc): a session reseed fires no per-entry events. Ordering
+        // vs other mutations comes from the mutation FIFO above.
+        const nextIndex = new Map<string, BinarySidecarEntry>()
+        const nextStore = new Map<string, Uint8Array>()
+        for (const [rel, bytes] of Object.entries(files)) {
+          nextIndex.set(rel, { size: bytes.length, sha256: await sha256hex(bytes) })
+          if (retainBytes) nextStore.set(rel, bytes)
+        }
+        index = nextIndex
+        store = nextStore
+      })
+    },
+    toRecord: () => Object.fromEntries(store),
+    overlay(files) {
+      if (!retainBytes) throw new Error('overlay() requires a retainBytes sidecar — an index-only sidecar has no bytes to merge')
+      return { ...Object.fromEntries(store), ...files }
+    },
+    onChange(cb) {
+      changeCbs.add(cb)
+      return () => changeCbs.delete(cb)
+    },
+  }
+}

package/sync/sync-engine-degraded.test.ts

@@ -0,0 +1,309 @@
+/**
+ * Contract tests for `createSyncEngine`'s `onDegraded` reporting: every
+ * silent-fallback path (dead watcher, a transient truth-source read failure,
+ * a ledger write failure while reconciling an inbound change) must surface
+ * through the host-supplied `onDegraded` callback instead of only a
+ * `console.warn`, and a host callback that itself throws must never wedge
+ * the engine's own processing.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { createSyncEngine } from './sync-engine.js'
+import type { SyncClientLike, SyncDegradation } from './sync-engine.js'
+import type { TruthPort } from './truth-port.js'
+
+function makeClient(overrides: Partial<SyncClientLike> = {}): SyncClientLike {
+  return {
+    write: vi.fn().mockResolvedValue(undefined),
+    rm: vi.fn().mockResolvedValue(undefined),
+    read: vi.fn().mockRejectedValue(Object.assign(new Error('not found'), { code: 'not-found' })),
+    ls: vi.fn().mockResolvedValue({ paths: [] }),
+    ...overrides,
+  }
+}
+
+function makePort(overrides: Partial<TruthPort> = {}): TruthPort {
+  return {
+    capabilities: { watch: 'push' },
+    read: vi.fn().mockResolvedValue(new Uint8Array()),
+    write: vi.fn().mockResolvedValue(undefined),
+    delete: vi.fn().mockResolvedValue(undefined),
+    walk: vi.fn().mockResolvedValue(undefined),
+    changes: vi.fn().mockReturnValue(() => {}),
+    ...overrides,
+  }
+}
+
+/** Fake `port.changes`: captures the `onBatch`/`onDead` callbacks `start()`
+ * registers and exposes them as `emitBatch`/`emitDead`, so a test can drive
+ * the engine without a real event stream. */
+function makeWatch(): {
+  changes: TruthPort['changes']
+  stop: ReturnType<typeof vi.fn>
+  emitBatch: (paths: string[]) => void
+  emitDead: () => void
+} {
+  let batchHandler: (paths: string[]) => void = () => {}
+  let deadHandler: () => void = () => {}
+  const stop = vi.fn()
+  const changes: TruthPort['changes'] = (onBatch, onDead) => {
+    batchHandler = onBatch
+    deadHandler = onDead
+    return stop
+  }
+  return {
+    changes,
+    stop,
+    emitBatch: (paths) => batchHandler(paths),
+    emitDead: () => deadHandler(),
+  }
+}
+
+/** Flush the microtask queue enough times for a batch's chained port/ledger
+ * reads+writes to settle before assertions run. */
+const flush = () => new Promise((r) => setTimeout(r, 0))
+
+describe('createSyncEngine — onDegraded: dead watcher', () => {
+  it('reports {kind: "watcher-dead"} exactly once and still disposes the subscription', async () => {
+    const watch = makeWatch()
+    const onDegraded = vi.fn<(d: SyncDegradation) => void>()
+    const port = makePort({ changes: watch.changes })
+    const client = makeClient()
+    const engine = createSyncEngine(client, port, { onDegraded })
+
+    await engine.populateLedger()
+    engine.start()
+    watch.emitDead()
+
+    expect(onDegraded).toHaveBeenCalledTimes(1)
+    expect(onDegraded).toHaveBeenCalledWith({ kind: 'watcher-dead' })
+    // Dispose is the pre-existing contract this test must not regress.
+    expect(watch.stop).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('createSyncEngine — onDegraded: reentrant stop() from the host callback', () => {
+  it('a host calling engine.stop() synchronously from onDegraded never double-disposes the watch subscription', async () => {
+    // The TruthPort `changes` contract does not require the returned dispose
+    // to be idempotent — a custom port may legitimately throw on a second
+    // call. This fake enforces that: the engine must guarantee at most ONE
+    // dispose call per subscription, even when the host reacts to
+    // {kind:'watcher-dead'} by synchronously tearing the engine down.
+    let disposeCalls = 0
+    let deadHandler: () => void = () => {}
+    const changes: TruthPort['changes'] = (_onBatch, onDead) => {
+      deadHandler = onDead
+      return () => {
+        disposeCalls += 1
+        if (disposeCalls > 1) throw new Error('dispose is not idempotent — called twice')
+      }
+    }
+    const port = makePort({ changes })
+    const client = makeClient()
+    const engineRef: { current?: ReturnType<typeof createSyncEngine> } = {}
+    const onDegraded = vi.fn<(d: SyncDegradation) => void>(() => {
+      engineRef.current?.stop()
+    })
+    const engine = createSyncEngine(client, port, { onDegraded })
+    engineRef.current = engine
+
+    await engine.populateLedger()
+    engine.start()
+    expect(() => deadHandler()).not.toThrow()
+
+    expect(onDegraded).toHaveBeenCalledTimes(1)
+    expect(onDegraded).toHaveBeenCalledWith({ kind: 'watcher-dead' })
+    expect(disposeCalls).toBe(1)
+  })
+})
+
+describe('createSyncEngine — onDegraded: onDead fired synchronously during subscription', () => {
+  it('a port firing onDead synchronously during subscription still tears down exactly once, without throwing', async () => {
+    // The TruthPort `changes` contract does not forbid invoking the callbacks
+    // DURING the subscription call itself — a port may discover its watcher
+    // is already dead and fire onDead before returning the dispose function.
+    // The engine must survive that ordering: start() must not throw (the
+    // dispose reference must not be dereferenced before the subscription call
+    // returns it), the host gets a single {kind:'watcher-dead'} degradation,
+    // and the dispose is called exactly once after it exists — never twice,
+    // neither here nor via a later stop().
+    let disposeCalls = 0
+    const changes: TruthPort['changes'] = (_onBatch, onDead) => {
+      onDead()
+      return () => {
+        disposeCalls += 1
+        if (disposeCalls > 1) throw new Error('dispose is not idempotent — called twice')
+      }
+    }
+    const port = makePort({ changes })
+    const client = makeClient()
+    const onDegraded = vi.fn<(d: SyncDegradation) => void>()
+    const engine = createSyncEngine(client, port, { onDegraded })
+
+    await engine.populateLedger()
+    expect(() => engine.start()).not.toThrow()
+
+    expect(onDegraded).toHaveBeenCalledTimes(1)
+    expect(onDegraded).toHaveBeenCalledWith({ kind: 'watcher-dead' })
+    expect(disposeCalls).toBe(1)
+
+    expect(() => engine.stop()).not.toThrow()
+    expect(disposeCalls).toBe(1)
+  })
+})
+
+describe('createSyncEngine — onDegraded: transient truth-read failure', () => {
+  it('reports {kind: "path-sync-failed", stage: "truth-read"} with the original error and skips the path', async () => {
+    const watch = makeWatch()
+    const onDegraded = vi.fn<(d: SyncDegradation) => void>()
+    const readError = new Error('port gone')
+    const port = makePort({ changes: watch.changes, read: vi.fn().mockRejectedValue(readError) })
+    const client = makeClient({ read: vi.fn().mockResolvedValue({ content: 'still here' }) })
+    const engine = createSyncEngine(client, port, { onDegraded })
+
+    await engine.populateLedger()
+    engine.start()
+    watch.emitBatch(['flaky.js'])
+    await flush()
+
+    expect(onDegraded).toHaveBeenCalledWith({
+      kind: 'path-sync-failed',
+      rel: 'flaky.js',
+      stage: 'truth-read',
+      error: readError,
+    })
+    expect(client.rm).not.toHaveBeenCalled()
+    expect(client.write).not.toHaveBeenCalled()
+  })
+})
+
+describe('createSyncEngine — onDegraded: ledger write failure while reconciling', () => {
+  it('reports {kind: "path-sync-failed", stage: "reconcile"} with the original error', async () => {
+    const watch = makeWatch()
+    const onDegraded = vi.fn<(d: SyncDegradation) => void>()
+    const writeError = new Error('ledger write failed')
+    const port = makePort({
+      changes: watch.changes,
+      read: vi.fn().mockResolvedValue(new TextEncoder().encode('new content')),
+    })
+    const client = makeClient({
+      read: vi.fn().mockResolvedValue({ content: 'old content' }),
+      write: vi.fn().mockRejectedValue(writeError),
+    })
+    const engine = createSyncEngine(client, port, { onDegraded })
+
+    await engine.populateLedger()
+    engine.start()
+    watch.emitBatch(['a.js'])
+    await flush()
+
+    expect(onDegraded).toHaveBeenCalledWith({
+      kind: 'path-sync-failed',
+      rel: 'a.js',
+      stage: 'reconcile',
+      error: writeError,
+    })
+  })
+})
+
+describe('createSyncEngine — onDegraded: ledger read failure while confirming a deletion', () => {
+  it('a transient ledger read failure during an inbound delete reports stage "reconcile" and never rms the ledger', async () => {
+    // Inbound delete path: the truth source says not-found, and the engine
+    // then reads the ledger to decide between "remove the record" and
+    // "already absent from both sides". A TRANSIENT ledger read failure
+    // (worker hiccup/timeout — no not-found code) leaves the ledger state
+    // unknown: treating it as "already absent" would silently strand a stale
+    // ledger record with the host none the wiser. The engine must degrade
+    // instead, and must never rm against an unknown ledger state.
+    const watch = makeWatch()
+    const onDegraded = vi.fn<(d: SyncDegradation) => void>()
+    const ledgerError = new Error('worker hiccup')
+    const port = makePort({
+      changes: watch.changes,
+      read: vi.fn().mockRejectedValue(Object.assign(new Error('gone'), { code: 'not-found' })),
+    })
+    const client = makeClient({ read: vi.fn().mockRejectedValue(ledgerError) })
+    const engine = createSyncEngine(client, port, { onDegraded })
+
+    await engine.populateLedger()
+    engine.start()
+    watch.emitBatch(['gone.js'])
+    await flush()
+
+    expect(onDegraded).toHaveBeenCalledWith({
+      kind: 'path-sync-failed',
+      rel: 'gone.js',
+      stage: 'reconcile',
+      error: ledgerError,
+    })
+    expect(client.rm).not.toHaveBeenCalled()
+  })
+
+  it('a genuine both-sides-absent deletion (ledger read rejects not-found) stays silent — no degradation, no rm', async () => {
+    const watch = makeWatch()
+    const onDegraded = vi.fn<(d: SyncDegradation) => void>()
+    const port = makePort({
+      changes: watch.changes,
+      read: vi.fn().mockRejectedValue(Object.assign(new Error('gone'), { code: 'not-found' })),
+    })
+    const client = makeClient({
+      read: vi.fn().mockRejectedValue(Object.assign(new Error('not in ledger'), { code: 'not-found' })),
+    })
+    const engine = createSyncEngine(client, port, { onDegraded })
+
+    await engine.populateLedger()
+    engine.start()
+    watch.emitBatch(['gone.js'])
+    await flush()
+
+    expect(onDegraded).not.toHaveBeenCalled()
+    expect(client.rm).not.toHaveBeenCalled()
+  })
+})
+
+describe('createSyncEngine — onDegraded: a throwing host callback never wedges the engine', () => {
+  it('processes a later, unrelated batch normally after onDegraded itself throws', async () => {
+    const watch = makeWatch()
+    const onDegraded = vi.fn<(d: SyncDegradation) => void>(() => {
+      throw new Error('host callback blew up')
+    })
+    const readError = new Error('port gone')
+    const port = makePort({
+      changes: watch.changes,
+      read: vi
+        .fn()
+        .mockRejectedValueOnce(readError)
+        .mockResolvedValueOnce(new TextEncoder().encode('new content')),
+    })
+    const client = makeClient({ read: vi.fn().mockResolvedValue({ content: 'old content' }) })
+    const engine = createSyncEngine(client, port, { onDegraded })
+
+    await engine.populateLedger()
+    engine.start()
+    watch.emitBatch(['flaky.js'])
+    await flush()
+
+    expect(onDegraded).toHaveBeenCalledTimes(1)
+
+    watch.emitBatch(['b.js'])
+    await flush()
+
+    expect(client.write).toHaveBeenCalledWith('b.js', 'new content', { actor: 'human' })
+  })
+})
+
+describe('createSyncEngine — onDegraded: omitted option', () => {
+  it('a host that never supplies onDegraded still gets today\'s skip/dead-watcher behavior with no crash', async () => {
+    const watch = makeWatch()
+    const port = makePort({ changes: watch.changes, read: vi.fn().mockRejectedValue(new Error('port gone')) })
+    const client = makeClient()
+    const engine = createSyncEngine(client, port)
+
+    await engine.populateLedger()
+    engine.start()
+    watch.emitBatch(['flaky.js'])
+    await flush()
+    watch.emitDead()
+
+    expect(client.write).not.toHaveBeenCalled()
+  })
+})

package/sync/sync-engine.test.ts

@@ -1,11 +1,10 @@
 /**
- * Contract tests for `createSyncEngine` — the engine extracted from
- * dimina-kit workbench's `wal-audit.ts` (devtools-fs-core-feasibility.md
- * §7+§8). These replay, against fake `client`/`port` doubles, the SAME six
- * disk<->editor sync scenarios workbench's `disk-sync.test.ts` covers against
- * `walAuditSource` — the equivalence judge for this extraction: the engine
- * must produce byte-identical observable behavior (ledger writes/rms,
- * `applyToEditor` calls) for the same inputs.
+ * Contract tests for `createSyncEngine`. These replay, against fake
+ * `client`/`port` doubles, the SAME six disk<->editor sync scenarios
+ * workbench's `disk-sync.test.ts` covers against `walAuditSource` — the
+ * cross-package equivalence judge: the engine must produce byte-identical
+ * observable behavior (ledger writes/rms, `applyToEditor` calls) for the
+ * same inputs as the wal-audit layer built on it.
  */
 import { describe, expect, it, vi } from 'vitest'
 import { createSyncEngine } from './sync-engine.js'
@@ -214,17 +213,16 @@ describe('createSyncEngine — populateLedger reconciles ledger residue', () =>
   })
 })
 
-describe('createSyncEngine — pendingWrite is a structural no-op for a push port', () => {
-  it('an in-flight onHumanSave never lets a same-path inbound batch observe a pendingWrite hit', async () => {
+describe('createSyncEngine — ledgerTurn FIFO orders an in-flight save before a same-path inbound batch', () => {
+  it('a same-path inbound batch queued behind a slow onHumanSave still gets content-compared and recorded', async () => {
     // Both onHumanSave and an inbound batch enqueue onto the SAME ledgerTurn
-    // FIFO. Registering pendingWrite happens synchronously when onHumanSave
-    // is called, and it is cleared inside onHumanSave's own queued turn —
-    // strictly before any LATER-queued inbound turn for the same path can
-    // run. This test proves that guarantee: even when onHumanSave's ledger
-    // write is deliberately slow, a same-path inbound batch queued right
-    // after it still falls through to ordinary content comparison (the disk
-    // content differs from the ledger's post-save record), not a
-    // pendingWrite short-circuit.
+    // FIFO, so a later-queued inbound turn for the same path always runs
+    // AFTER the save's ledger write completed. This test proves that
+    // guarantee: even when onHumanSave's ledger write is deliberately slow,
+    // a same-path inbound batch queued right after it is judged by ordinary
+    // content comparison against the post-save ledger record (the disk
+    // content differs, so it must be recorded) — never silently absorbed as
+    // the save's own echo.
     let resolveWrite: () => void = () => {}
     const writeGate = new Promise<void>((resolve) => {
       resolveWrite = resolve
@@ -254,14 +252,12 @@ describe('createSyncEngine — pendingWrite is a structural no-op for a push por
     await savePromise
     await flush()
 
-    // If the inbound turn had observed a pendingWrite hit, it would have
-    // absorbed the batch silently (zero client.write / applyToEditor calls
+    // If the inbound turn had been misjudged as the save's echo, it would
+    // have been absorbed silently (zero client.write / applyToEditor calls
     // for 'a.js' beyond the save itself). Instead it ran AFTER onHumanSave's
-    // turn cleared pendingWrite, fell through to ordinary content
-    // comparison (ledger's mocked, unchanged 'old' record vs. the port's
-    // 'externally new' bytes), and recorded + applied the inbound change —
-    // proving the pendingWrite branch is a structural no-op for this push
-    // port, exactly as it is for the real devtools adapter.
+    // queued turn, was content-compared (ledger's mocked, unchanged 'old'
+    // record vs. the port's 'externally new' bytes), and recorded + applied
+    // the inbound change.
     expect(client.write).toHaveBeenCalledWith('a.js', 'new from human', { actor: 'human' })
     expect(client.write).toHaveBeenCalledWith('a.js', 'externally new', { actor: 'human' })
     expect(applyToEditor).toHaveBeenCalledWith('a.js', new TextEncoder().encode('externally new'))
@@ -400,73 +396,6 @@ describe('createSyncEngine — binary layering: onHumanSave with binary content'
   })
 })
 
-describe('createSyncEngine — consumeInboundEcho (poll host outbound echo suppression)', () => {
-  it('matches the exact text an inbound batch just applied, once — a second consume misses', async () => {
-    const watch = makeWatch()
-    const port = makePort({
-      changes: watch.changes,
-      read: vi.fn().mockResolvedValue(new TextEncoder().encode('from disk')),
-    })
-    const client = makeClient({ read: vi.fn().mockResolvedValue({ content: 'old' }) })
-    const engine = createSyncEngine(client, port)
-
-    await engine.populateLedger()
-    engine.start()
-    watch.emitBatch(['a.js'])
-    await vi.waitFor(() => expect(client.write).toHaveBeenCalledWith('a.js', 'from disk', { actor: 'human' }))
-
-    expect(engine.consumeInboundEcho('a.js', 'from disk')).toBe(true)
-    expect(engine.consumeInboundEcho('a.js', 'from disk')).toBe(false)
-  })
-
-  it('does not match different content, and leaves the record intact for a later correct match', async () => {
-    const watch = makeWatch()
-    const port = makePort({
-      changes: watch.changes,
-      read: vi.fn().mockResolvedValue(new TextEncoder().encode('from disk')),
-    })
-    const client = makeClient({ read: vi.fn().mockResolvedValue({ content: 'old' }) })
-    const engine = createSyncEngine(client, port)
-
-    await engine.populateLedger()
-    engine.start()
-    watch.emitBatch(['a.js'])
-    await vi.waitFor(() => expect(client.write).toHaveBeenCalledWith('a.js', 'from disk', { actor: 'human' }))
-
-    expect(engine.consumeInboundEcho('a.js', 'something else')).toBe(false)
-    expect(engine.consumeInboundEcho('a.js', 'from disk')).toBe(true)
-  })
-
-  it('matches a delete marker only with content === null', async () => {
-    const watch = makeWatch()
-    const port = makePort({
-      changes: watch.changes,
-      read: vi.fn().mockRejectedValue(Object.assign(new Error('gone'), { code: 'not-found' })),
-    })
-    const client = makeClient({ read: vi.fn().mockResolvedValue({ content: 'was here' }) })
-    const engine = createSyncEngine(client, port)
-
-    await engine.populateLedger()
-    engine.start()
-    watch.emitBatch(['gone.js'])
-    await vi.waitFor(() => expect(client.rm).toHaveBeenCalledWith('gone.js', { actor: 'human' }))
-
-    expect(engine.consumeInboundEcho('gone.js', 'not a delete')).toBe(false)
-    expect(engine.consumeInboundEcho('gone.js', null)).toBe(true)
-    expect(engine.consumeInboundEcho('gone.js', null)).toBe(false)
-  })
-
-  it('returns false for a path with no inbound record at all', async () => {
-    const port = makePort()
-    const client = makeClient()
-    const engine = createSyncEngine(client, port)
-
-    await engine.populateLedger()
-
-    expect(engine.consumeInboundEcho('never-touched.js', 'anything')).toBe(false)
-  })
-})
-
 /** Stateful world for contention tests: a truth-source `disk` and a ledger
  * that actually HOLD content, so interleaving tests can assert final-state
  * convergence (ledger == disk) instead of just call counts. `ledgerWrites`