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

package/dist/sync/binary-sidecar.js

@@ -0,0 +1,147 @@
+/**
+ * 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) {
+    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 function createBinarySidecar(opts = {}) {
+    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();
+    let store = new Map();
+    const changeCbs = new Set();
+    /**
+     * 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.resolve();
+    function enqueueMutation(fn) {
+        const next = mutationTurn.then(fn, fn);
+        mutationTurn = next.catch(() => { });
+        return next;
+    }
+    function emit(rel, bytes) {
+        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();
+                const nextStore = new Map();
+                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/dist/sync/sync-engine.js

@@ -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,76 +10,42 @@
  * 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.
  */
-const BINARY_SNIFF_BYTES = 8192;
-/** True when the first `BINARY_SNIFF_BYTES` of `bytes` contain a NUL byte. */
-function looksBinary(bytes) {
-    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) {
-    const digest = await crypto.subtle.digest('SHA-256', bytes);
-    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, b) {
-    if (a.length !== b.length)
-        return false;
-    for (let i = 0; i < a.length; i++)
-        if (a[i] !== b[i])
-            return false;
-    return true;
-}
+import { createBinarySidecar, looksBinary } from './binary-sidecar.js';
 /**
  * True when `error` denotes "path does not exist" per the TruthPort error
  * contract (see truth-port.ts): `error.code === 'not-found'` or
@@ -93,28 +59,22 @@ function isNotFoundError(error) {
 export function createSyncEngine(client, port, opts = {}) {
     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();
+    /** 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) {
+        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()`.
+     * "Binary layering" section. Index-only (this engine never needs the bytes
+     * back); session-scoped: rebuilt from scratch on every `populateLedger()`.
      */
-    const binaryIndex = new Map();
-    /**
-     * `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()`.
-     */
-    const inboundApplied = new Map();
+    const binaryIndex = createBinarySidecar();
     /**
      * FIFO queue serializing every compare-then-record against the ledger
      * (inbound change batches AND the onHumanSave accounting step). Without it
@@ -136,13 +96,12 @@ export function createSyncEngine(client, port, opts = {}) {
      * same persisted ledger identity) and are removed so the ledger ends up
      * exactly matching the walked tree. */
     async function seedFromDisk() {
-        binaryIndex.clear();
-        inboundApplied.clear();
+        await binaryIndex.clear();
         const seen = new Set();
         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' });
@@ -157,20 +116,16 @@ export function createSyncEngine(client, port, opts = {}) {
         }
     }
     /**
-     * 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) {
-        if (pendingWrite.has(rel)) {
-            pendingWrite.delete(rel);
-            return;
-        }
         let bytes;
         try {
             bytes = await port.read(rel);
@@ -178,6 +133,7 @@ export function createSyncEngine(client, port, opts = {}) {
         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;
@@ -187,8 +143,7 @@ export function createSyncEngine(client, port, opts = {}) {
             // 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;
             }
@@ -196,23 +151,29 @@ export function createSyncEngine(client, port, opts = {}) {
             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;
         }
@@ -231,42 +192,15 @@ export function createSyncEngine(client, port, opts = {}) {
         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, content) {
-        const entry = inboundApplied.get(rel);
-        if (!entry)
-            return false;
-        let matches;
-        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) {
@@ -279,6 +213,7 @@ export function createSyncEngine(client, port, opts = {}) {
             }
             catch (e) {
                 console.warn('[fs-core/sync] disk sync failed for', rel, e);
+                degrade({ kind: 'path-sync-failed', rel, stage: 'reconcile', error: e });
             }
         }
     }
@@ -309,10 +244,28 @@ export function createSyncEngine(client, port, opts = {}) {
     /** 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() {
         let active = true;
-        const dispose = port.changes((paths) => {
+        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 = undefined;
+        function disposeOnce() {
+            if (disposed)
+                return;
+            disposed = true;
+            disposeImpl?.();
+        }
+        disposeImpl = port.changes((paths) => {
             if (!active)
                 return;
             enqueueInboundBatch(paths);
@@ -321,11 +274,16 @@ export function createSyncEngine(client, port, opts = {}) {
                 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();
         };
     }
     function stop() {
@@ -333,12 +291,11 @@ export function createSyncEngine(client, port, opts = {}) {
         stopWatching = () => { };
     }
     /**
-     * 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).
      *
@@ -349,32 +306,25 @@ export function createSyncEngine(client, port, opts = {}) {
      * entirely and only updates `binaryIndex`.
      */
     async function onHumanSave(rel, content) {
-        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);
             });
+            return;
         }
-        finally {
-            pendingWrite.delete(rel);
-        }
+        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,
     };