@peerbit/shared-log 13.2.24 → 13.2.26

package/dist/src/native-write-through-block-store.js

@@ -0,0 +1,989 @@
+import { logger as loggerFn } from "@peerbit/logger";
+import { NativeDurableCommitError } from "./errors.js";
+const warn = loggerFn("peerbit:shared-log").newScope("warn");
+const isPromiseLike = (value) => !!value && typeof value.then === "function";
+/**
+ * Write-through block store bridging the native backbone's in-wasm-memory block
+ * store to a durable per-program {@link AnyBlockStore}.
+ *
+ * WHY: when the native backbone is active the log's entry blocks live only in
+ * the native wasm block map (`NativeBackboneBlockStore.persisted() === false`).
+ * On a restart that map is empty, so the native graph cannot reload heads the
+ * durable heads index still lists ("Failed to load entry from head"). This
+ * wrapper mirrors every write into the same durable `blocks` sublevel the
+ * non-native path uses. On a native miss, reads fall through to durable storage
+ * and lazily repopulate the wasm map so the native graph can walk the DAG again.
+ *
+ * The native store stays the authoritative hot store the native graph reads
+ * from: reads hit native first and only fall back to durable (repopulating
+ * native on a hit so subsequent native-graph reads succeed).
+ *
+ * METHOD SURFACE (see #1006): `RemoteBlocks` and the log feature-detect the
+ * optional batch methods (`putMany`/`putKnown`/`putKnownMany`/
+ * `putKnownManyColumns`/`rmMany`). To keep the receive-fusion / columnar fast
+ * paths engaged this wrapper preserves the native store's optional write
+ * methods — including `putKnownManyColumns`, which `AnyBlockStore` does not have
+ * — and delegates each. It adds only local durability/trim coordination hooks
+ * consumed by `RemoteBlocks` and the log; protocol/native-handle capabilities
+ * such as `getBlockResponsePayload`/`getNativeLogBlockStoreHandle` stay absent,
+ * so their optional-chained probes keep the existing fallback behavior.
+ */
+export class NativeBackboneWriteThroughBlockStore {
+    native;
+    durable;
+    constructor(native, durable) {
+        this.native = native;
+        this.durable = durable;
+    }
+    // A durable mirror write that cannot be awaited at its call site (the
+    // columnar putKnownManyColumns fast path must return a synchronous string[]
+    // because RemoteBlocks.putKnownManyColumns treats the result as sync) is
+    // tracked here instead of being silently `void`ed. Its rejection is stored
+    // and re-thrown on the next awaited wrapper method (and on stop()), so a
+    // failed durable write (IO/disk-full) surfaces as an error rather than
+    // vanishing and leaving the block out of durable while native/log report
+    // success. `.catch` also prevents unhandled-rejection noise.
+    pendingDurableWrites = new Set();
+    nativeDurableCommitFailure;
+    stopCompleted = false;
+    nativeDeleteTombstones = new Map();
+    nativeDeleteEpoch = 0;
+    nativeBlockWriteGenerations = new Map();
+    pendingNativeDeleteCleanup = new Map();
+    stagedNativeDeleteCleanups = new Map();
+    nextNativeDeleteCleanupToken = 0;
+    nativeDeleteCleanupRunning;
+    nextNativeCommitOwnershipToken = 0;
+    nativeCommitOwnerships = new Map();
+    nativeCommitOwnershipsByCid = new Map();
+    getNativeDurableCommitFailure() {
+        return this.nativeDurableCommitFailure;
+    }
+    recordNativeDurableCommitFailure(cause, options) {
+        if (this.nativeDurableCommitFailure) {
+            this.nativeDurableCommitFailure.addCommitContext(options);
+            return this.nativeDurableCommitFailure;
+        }
+        this.nativeDurableCommitFailure =
+            cause instanceof NativeDurableCommitError
+                ? cause
+                : new NativeDurableCommitError(cause, options);
+        if (cause instanceof NativeDurableCommitError) {
+            cause.addCommitContext(options);
+        }
+        return this.nativeDurableCommitFailure;
+    }
+    throwIfNativeDurableCommitFailed() {
+        if (this.nativeDurableCommitFailure) {
+            throw this.nativeDurableCommitFailure;
+        }
+    }
+    throwIfDurableWritesFailed() {
+        this.throwIfNativeDurableCommitFailed();
+    }
+    async commitDurableMutation(operation, committedCids, failedCids) {
+        this.throwIfNativeDurableCommitFailed();
+        const committedCidList = [...committedCids];
+        const failedCidList = failedCids ? [...failedCids] : committedCidList;
+        let result;
+        const operationResult = Promise.resolve().then(operation);
+        this.trackAwaitedDurable(operationResult);
+        try {
+            result = await operationResult;
+        }
+        catch (error) {
+            throw this.recordNativeDurableCommitFailure(error, {
+                committedCids: committedCidList,
+                failedCids: failedCidList,
+            });
+        }
+        // A different concurrent native mutation may have poisoned the wrapper
+        // while this durable call was in flight. Include this operation among the
+        // native-applied facts, but not among durable calls that actually failed.
+        if (this.nativeDurableCommitFailure) {
+            this.nativeDurableCommitFailure.addCommitContext({
+                committedCids: committedCidList,
+                failedCids: [],
+            });
+            throw this.nativeDurableCommitFailure;
+        }
+        return result;
+    }
+    beginNativeDelete(cids) {
+        this.nativeDeleteEpoch++;
+        for (const cid of cids) {
+            this.nativeDeleteTombstones.set(cid, (this.nativeDeleteTombstones.get(cid) ?? 0) + 1);
+        }
+    }
+    endNativeDelete(cids) {
+        for (const cid of cids) {
+            const remaining = (this.nativeDeleteTombstones.get(cid) ?? 1) - 1;
+            if (remaining <= 0) {
+                this.nativeDeleteTombstones.delete(cid);
+            }
+            else {
+                this.nativeDeleteTombstones.set(cid, remaining);
+            }
+        }
+    }
+    isNativeDeletePending(cid) {
+        return this.nativeDeleteTombstones.has(cid);
+    }
+    // A CID can be legitimately re-added after a native trim (content addressing
+    // makes the bytes identical, but its liveness is new). Cancel any queued trim
+    // for that CID and advance its generation before the write is exposed. An
+    // already-running cleanup uses the generation/pending map to avoid deleting
+    // the new native value; synchronous columnar writes also chain their durable
+    // mirror behind that cleanup below.
+    noteNativeBlockWrite(cids) {
+        const generations = new Map();
+        for (const cid of new Set(cids)) {
+            const generation = (this.nativeBlockWriteGenerations.get(cid) ?? 0) + 1;
+            this.nativeBlockWriteGenerations.set(cid, generation);
+            generations.set(cid, generation);
+            if (this.pendingNativeDeleteCleanup.delete(cid)) {
+                this.endNativeDelete([cid]);
+            }
+            for (const staged of this.stagedNativeDeleteCleanups.values()) {
+                if (staged.delete(cid)) {
+                    this.endNativeDelete([cid]);
+                }
+            }
+        }
+        return generations;
+    }
+    beginNativeCommitOwnership(generations) {
+        if (generations.size === 0) {
+            return undefined;
+        }
+        const token = {
+            id: ++this.nextNativeCommitOwnershipToken,
+            rows: new Map(),
+        };
+        for (const [cid, generation] of generations) {
+            const owners = this.nativeCommitOwnershipsByCid.get(cid) ?? new Set();
+            const shared = owners.size > 0;
+            for (const ownerId of owners) {
+                const owner = this.nativeCommitOwnerships.get(ownerId);
+                const row = owner?.rows.get(cid);
+                if (row)
+                    row.shared = true;
+            }
+            owners.add(token.id);
+            this.nativeCommitOwnershipsByCid.set(cid, owners);
+            token.rows.set(cid, { generation, shared });
+        }
+        this.nativeCommitOwnerships.set(token.id, token);
+        return token;
+    }
+    releaseNativeCommitOwnership(token) {
+        if (!token ||
+            typeof token !== "object" ||
+            typeof token.id !== "number") {
+            return;
+        }
+        const owned = this.nativeCommitOwnerships.get(token.id);
+        if (owned !== token) {
+            return;
+        }
+        this.nativeCommitOwnerships.delete(owned.id);
+        for (const cid of owned.rows.keys()) {
+            const owners = this.nativeCommitOwnershipsByCid.get(cid);
+            owners?.delete(owned.id);
+            if (owners?.size === 0) {
+                this.nativeCommitOwnershipsByCid.delete(cid);
+            }
+        }
+    }
+    acknowledgeNativeCommitOwnership(token) {
+        this.releaseNativeCommitOwnership(token);
+    }
+    enqueueNativeDeleteCleanup(cids) {
+        for (const cid of new Set(cids)) {
+            if (!this.pendingNativeDeleteCleanup.has(cid)) {
+                this.pendingNativeDeleteCleanup.set(cid, this.nativeBlockWriteGenerations.get(cid) ?? 0);
+                this.beginNativeDelete([cid]);
+            }
+        }
+    }
+    releaseStagedNativeDeleteCleanup(token) {
+        const staged = this.stagedNativeDeleteCleanups.get(token);
+        if (!staged) {
+            return false;
+        }
+        this.stagedNativeDeleteCleanups.delete(token);
+        for (const [cid] of staged) {
+            this.endNativeDelete([cid]);
+        }
+        return true;
+    }
+    discardStagedNativeDeleteCleanups() {
+        for (const token of [...this.stagedNativeDeleteCleanups.keys()]) {
+            this.releaseStagedNativeDeleteCleanup(token);
+        }
+    }
+    // Native commit callbacks call this immediately after the native transaction
+    // returns, before awaiting the new block's durable mirror. This stages read
+    // tombstones only. Durable deletion is promoted later by the exact EntryIndex
+    // consume token, so an unacknowledged/failed append cannot delete the old
+    // durable head that the lower log still publishes.
+    beginNativeDeleteCleanup(cids) {
+        this.throwIfNativeDurableCommitFailed();
+        const uniqueCids = [...new Set(cids)];
+        if (uniqueCids.length === 0) {
+            return undefined;
+        }
+        const token = ++this.nextNativeDeleteCleanupToken;
+        const staged = new Map(uniqueCids.map((cid) => [
+            cid,
+            this.nativeBlockWriteGenerations.get(cid) ?? 0,
+        ]));
+        this.stagedNativeDeleteCleanups.set(token, staged);
+        this.beginNativeDelete(uniqueCids);
+        return token;
+    }
+    cancelNativeDeleteCleanup(cleanupToken) {
+        if (typeof cleanupToken === "number") {
+            this.releaseStagedNativeDeleteCleanup(cleanupToken);
+        }
+    }
+    async waitForNativeDeleteCleanup() {
+        while (this.nativeDeleteCleanupRunning) {
+            await this.nativeDeleteCleanupRunning;
+        }
+    }
+    async waitForTrackedDurableWrites() {
+        while (this.pendingDurableWrites.size > 0) {
+            await Promise.allSettled([...this.pendingDurableWrites]);
+        }
+    }
+    async retryNativeDeleteCleanup(options) {
+        await this.waitForNativeDeleteCleanup();
+        if (this.nativeDurableCommitFailure && !options?.allowPoisoned) {
+            throw this.nativeDurableCommitFailure;
+        }
+        // A synchronous columnar write may already have scheduled its durable
+        // mirror. Let it settle before deleting queued CIDs, but leave any recorded
+        // error for drainDurable() to surface to its owning operation/stop.
+        await this.waitForTrackedDurableWrites();
+        await this.waitForNativeDeleteCleanup();
+        // A tracked mirror or the cleanup we just waited for may have poisoned the
+        // wrapper. Do not begin another durable mutation on the ordinary path after
+        // that asynchronous boundary. stop() alone opts into one cleanup retry so a
+        // transient delete failure can still release its tombstones and resources.
+        if (this.nativeDurableCommitFailure && !options?.allowPoisoned) {
+            throw this.nativeDurableCommitFailure;
+        }
+        if (this.pendingNativeDeleteCleanup.size === 0) {
+            return;
+        }
+        const cleanupEntries = [...this.pendingNativeDeleteCleanup].filter(([cid, generation]) => (this.nativeBlockWriteGenerations.get(cid) ?? 0) === generation);
+        if (cleanupEntries.length === 0) {
+            return;
+        }
+        const cids = cleanupEntries.map(([cid]) => cid);
+        let cleanupFailure;
+        const running = (async () => {
+            let durableRemoved = false;
+            let nativeRemoved = false;
+            try {
+                await this.durable.rmMany(cids);
+                durableRemoved = true;
+            }
+            catch (error) {
+                cleanupFailure = error;
+                // The new entry blocks are already durable at this point and the native
+                // transaction has selected the new graph/index state. Old content-addressed
+                // blocks are therefore harmless unreachable orphans. Keep this cleanup as
+                // retryable debt instead of poisoning/rolling back a fully durable append;
+                // a partial rmMany is safe for the same reason.
+                warn(`Failed durable native-trim cleanup; retaining retry debt: ${String(error)}`);
+            }
+            finally {
+                // A read that began in the native-transaction -> cleanup-hook gap may
+                // have repopulated native. Always repeat the native removal, even when
+                // durable rm failed. Exclude CIDs re-added while durable IO was pending;
+                // their generation change cancelled the queued delete.
+                const stillDeleted = cids.filter((cid) => this.pendingNativeDeleteCleanup.has(cid));
+                try {
+                    if (stillDeleted.length > 0) {
+                        await this.native.rmMany(stillDeleted);
+                    }
+                    nativeRemoved = true;
+                }
+                catch (error) {
+                    cleanupFailure ??= error;
+                    warn(`Failed to repeat native-trim hot block removal: ${String(error)}`);
+                }
+            }
+            if (durableRemoved && nativeRemoved) {
+                for (const [cid, generation] of cleanupEntries) {
+                    if (this.pendingNativeDeleteCleanup.get(cid) === generation) {
+                        this.pendingNativeDeleteCleanup.delete(cid);
+                        this.nativeBlockWriteGenerations.delete(cid);
+                        this.endNativeDelete([cid]);
+                    }
+                }
+            }
+        })();
+        this.nativeDeleteCleanupRunning = running;
+        try {
+            await running;
+        }
+        finally {
+            if (this.nativeDeleteCleanupRunning === running) {
+                this.nativeDeleteCleanupRunning = undefined;
+            }
+        }
+        if (options?.throwOnFailure && cleanupFailure !== undefined) {
+            throw cleanupFailure;
+        }
+    }
+    trackDurable(result, cids) {
+        // The durable store may answer synchronously (an in-memory or already
+        // resolved store); only a real pending promise needs tracking. A sync
+        // success is already durable; a sync throw would have propagated already.
+        if (!isPromiseLike(result)) {
+            return;
+        }
+        const tracked = Promise.resolve(result).then(() => {
+            this.pendingDurableWrites.delete(tracked);
+        }, (error) => {
+            this.pendingDurableWrites.delete(tracked);
+            this.recordNativeDurableCommitFailure(error, {
+                committedCids: cids,
+                failedCids: cids,
+            });
+        });
+        this.pendingDurableWrites.add(tracked);
+    }
+    // Awaited mirror writes surface their own rejection to the append that
+    // created them. Track a non-rejecting settlement companion as well so stop()
+    // and later wrapper operations cannot close/use durable storage while that
+    // append barrier is still in flight.
+    trackAwaitedDurable(result) {
+        const tracked = result.then(() => {
+            this.pendingDurableWrites.delete(tracked);
+        }, () => {
+            this.pendingDurableWrites.delete(tracked);
+        });
+        this.pendingDurableWrites.add(tracked);
+    }
+    // Wait for every tracked (sync-path) durable write to settle, then surface
+    // the first failure. Awaited methods call this so a prior columnar durable
+    // failure propagates as back-pressure to the next caller.
+    async drainDurable() {
+        await this.waitForTrackedDurableWrites();
+        this.throwIfNativeDurableCommitFailed();
+    }
+    // --- lifecycle -------------------------------------------------------
+    // The native store's lifecycle hooks are no-ops; only the durable store
+    // needs starting/stopping. The wasm map is NOT eagerly rehydrated from disk:
+    // entry blocks are pulled back lazily on demand through the read fallback in
+    // getMany()/get() (durable hit -> repopulate the wasm map), which is what the
+    // log's DAG walk (EntryIndex.resolveMany -> store.getMany) exercises. Keeping
+    // the wasm map cold on open is required by the strict-native resident
+    // coordinate-state optimization: a reopened non-replicating native node must
+    // report hasBlock(head) === false and answer a same-signer append from the
+    // persisted coordinate + signer facts without resolving the entry block.
+    async start() {
+        await this.durable.start();
+        this.stopCompleted = false;
+    }
+    async stop() {
+        if (this.stopCompleted) {
+            return;
+        }
+        // Surface any tracked (sync-path) durable write failure and ensure all
+        // mirror writes have settled before the durable store is torn down. Closing
+        // the durable store is unconditional: a prior columnar mirror failure must
+        // not leak the store lifecycle resource.
+        let firstError;
+        let shutdownError;
+        try {
+            await this.drainDurable();
+        }
+        catch (error) {
+            firstError = error;
+        }
+        // Tokens not consumed by EntryIndex belong to native prepares that never
+        // published their lower-log trim. Release their read tombstones, but never
+        // promote them to durable deletion during shutdown.
+        this.discardStagedNativeDeleteCleanups();
+        try {
+            await this.retryNativeDeleteCleanup({ allowPoisoned: true });
+        }
+        catch (error) {
+            firstError ??= error;
+            shutdownError ??= error;
+        }
+        try {
+            await this.durable.stop();
+        }
+        catch (error) {
+            firstError ??= error;
+            shutdownError ??= error;
+        }
+        if (shutdownError === undefined) {
+            // A durable poison belongs to the generation being closed. Report it once
+            // so the owning terminal call observes the failed append, but remember that
+            // every mandatory shutdown stage completed. Conservative content-addressed
+            // trim debt may remain in this retired wrapper after best-effort cleanup; a
+            // fresh generation gets a new wrapper and must not be wedged by that debt.
+            // The exact terminal retry may therefore finish parent bookkeeping without
+            // rethrowing the same latched poison forever.
+            this.stopCompleted = true;
+        }
+        if (firstError !== undefined) {
+            throw firstError;
+        }
+    }
+    status() {
+        return this.durable.status();
+    }
+    waitFor() {
+        return Promise.resolve([]);
+    }
+    // Native commit APIs must keep their block-store callback synchronous. The
+    // lower log calls this barrier after that callback reports committed blocks
+    // and before publishing index/head facts.
+    waitForDurableWrites() {
+        return this.drainDurable();
+    }
+    // Mirror a single already-committed block (present in the wasm map) to the
+    // durable store ONLY. Used by the native commit-only append fast path: the
+    // native prepare commits the entry block into the wasm map and returns no raw
+    // bytes, and the strict-native resident-coordinate path deliberately does NOT
+    // route the block through the log's finishBlocks/putKnown* (that would disturb
+    // the commit-only append path the RCS optimization depends on). Instead the
+    // caller reads the committed bytes back and calls this so the block lands in
+    // durable directly. The caller awaits this method before acknowledging its
+    // append, so a failed write rejects the append that produced the block.
+    async mirrorToDurable(cid, bytes, options) {
+        this.throwIfNativeDurableCommitFailed();
+        // The native commit happened before this call. Mark the CID live before
+        // awaiting anything so a concurrent retry of an older trim cannot remove
+        // the newly committed hot block.
+        let ownership;
+        if (options?.nativeTrimmed !== true) {
+            ownership = this.beginNativeCommitOwnership(this.noteNativeBlockWrite([cid]));
+            await this.waitForNativeDeleteCleanup();
+        }
+        try {
+            await this.drainDurable();
+            if (ownership) {
+                const existed = await this.durable.hasMany([...ownership.rows.keys()]);
+                let index = 0;
+                for (const row of ownership.rows.values()) {
+                    row.durableExistedBefore = existed[index++] === true;
+                }
+            }
+            const result = this.commitDurableMutation(() => this.durable.putKnown(cid, bytes), [cid]);
+            await result;
+            await this.retryNativeDeleteCleanup();
+            this.throwIfNativeDurableCommitFailed();
+            return ownership;
+        }
+        catch (error) {
+            // The caller never receives an ownership token for an indeterminate write.
+            // Release the in-memory claim and preserve any bytes the backend may have
+            // applied before rejecting.
+            this.releaseNativeCommitOwnership(ownership);
+            throw error;
+        }
+    }
+    async mirrorManyToDurable(blocks, options) {
+        this.throwIfNativeDurableCommitFailed();
+        const cids = blocks.map(([cid]) => cid);
+        // Rows trimmed later in the same native batch deliberately remain owned by
+        // that batch's staged cleanup; only mark surviving rows live.
+        const liveCids = cids.filter((cid) => !options?.nativeTrimmedCids?.has(cid));
+        const ownership = this.beginNativeCommitOwnership(this.noteNativeBlockWrite(liveCids));
+        if (liveCids.length > 0) {
+            await this.waitForNativeDeleteCleanup();
+        }
+        try {
+            await this.drainDurable();
+            if (ownership) {
+                const existed = await this.durable.hasMany([...ownership.rows.keys()]);
+                let index = 0;
+                for (const row of ownership.rows.values()) {
+                    row.durableExistedBefore = existed[index++] === true;
+                }
+            }
+            if (blocks.length > 0) {
+                await this.commitDurableMutation(() => this.durable.putKnownMany(blocks), cids);
+            }
+            await this.retryNativeDeleteCleanup();
+            this.throwIfNativeDurableCommitFailed();
+            return ownership;
+        }
+        catch (error) {
+            this.releaseNativeCommitOwnership(ownership);
+            throw error;
+        }
+    }
+    async rollbackFailedNativeCommits(cids, restoreNativeCids = [], ownershipToken) {
+        // This is the sole mutation allowed after poison: it removes a native
+        // transaction that the lower log never published. Do not route through the
+        // guarded rmMany path, and settle the failed mirror before compensating it.
+        await this.waitForTrackedDurableWrites();
+        // A failed replacement never published its trim. Reassert the restored CIDs
+        // as live before any compensation IO so staged/pending delete intents cannot
+        // remove the last acknowledged blocks during stop or reopen.
+        const ownership = ownershipToken && typeof ownershipToken === "object"
+            ? this.nativeCommitOwnerships.get(ownershipToken.id)
+            : undefined;
+        const verifiedOwnership = ownership && ownership === ownershipToken ? ownership : undefined;
+        const restoreSet = new Set(restoreNativeCids);
+        const safeDurableDeletes = verifiedOwnership
+            ? [...new Set(cids)].filter((cid) => {
+                const row = verifiedOwnership.rows.get(cid);
+                const owners = this.nativeCommitOwnershipsByCid.get(cid);
+                return (!restoreSet.has(cid) &&
+                    row?.durableExistedBefore === false &&
+                    row.shared === false &&
+                    (this.nativeBlockWriteGenerations.get(cid) ?? 0) ===
+                        row.generation &&
+                    owners?.size === 1 &&
+                    owners.has(verifiedOwnership.id));
+            })
+            : [];
+        this.noteNativeBlockWrite(restoreNativeCids);
+        let firstError;
+        try {
+            if (safeDurableDeletes.length > 0) {
+                await this.durable.rmMany(safeDurableDeletes);
+            }
+        }
+        catch (error) {
+            firstError = error;
+        }
+        // A native prepare runs before ownership can observe the hot map, so it cannot
+        // prove that a CID was absent there before this operation. Keep native bytes as
+        // unreachable orphans rather than deleting acknowledged/shared/restored data.
+        if (restoreNativeCids.length > 0) {
+            try {
+                const values = await this.durable.getMany(restoreNativeCids);
+                const restore = [];
+                for (let index = 0; index < restoreNativeCids.length; index++) {
+                    const value = values[index];
+                    if (value)
+                        restore.push([restoreNativeCids[index], value]);
+                }
+                if (restore.length > 0) {
+                    this.native.putKnownMany(restore);
+                }
+            }
+            catch (error) {
+                firstError ??= error;
+            }
+        }
+        this.releaseNativeCommitOwnership(ownershipToken);
+        if (firstError !== undefined)
+            throw firstError;
+    }
+    /**
+     * Compensate a native prepare that failed before its durable mirror began.
+     * Durable presence proves a same-CID acknowledged owner; an active ownership
+     * token proves a concurrent mirror. Only an unowned, non-durable hot block is
+     * exclusively attributable to the failed prepare and safe to remove.
+     */
+    async rollbackUnmirroredNativeCommits(cids, restoreNativeCids = []) {
+        const unique = [...new Set(cids)];
+        // Native prepares bypass this wrapper. Any observed wrapper generation is
+        // therefore evidence of a generic/same-CID writer, not of the failed prepare.
+        // Snapshot before the first await and require both absence and stability so a
+        // write starting before or during durable.hasMany cannot lose its hot value to
+        // a stale `false` result.
+        const genericWriteGenerations = new Map(unique.map((cid) => [cid, this.nativeBlockWriteGenerations.get(cid)]));
+        await this.rollbackFailedNativeCommits(cids, restoreNativeCids);
+        const durablePresence = await this.durable.hasMany(unique);
+        const restore = new Set(restoreNativeCids);
+        const safeNativeDeletes = unique.filter((cid, index) => !restore.has(cid) &&
+            durablePresence[index] !== true &&
+            genericWriteGenerations.get(cid) === undefined &&
+            this.nativeBlockWriteGenerations.get(cid) === undefined &&
+            (this.nativeCommitOwnershipsByCid.get(cid)?.size ?? 0) === 0);
+        if (safeNativeDeletes.length > 0) {
+            await this.native.rmMany(safeNativeDeletes);
+        }
+    }
+    // --- writes (apply to BOTH: native first for the hot path, then durable) ---
+    async put(data) {
+        await this.drainDurable();
+        const cid = await this.native.put(data);
+        // The native store computes a raw-codec CID for a `Uint8Array`, storing
+        // the bytes verbatim (raw codec is identity), and stores `block.bytes`
+        // for the pre-CIDed object form. Either way the input bytes match what
+        // native stored, so feed durable the known cid+bytes without recomputing.
+        const value = data instanceof Uint8Array
+            ? data
+            : data.block.bytes;
+        this.noteNativeBlockWrite([cid]);
+        await this.waitForNativeDeleteCleanup();
+        // put() may have yielded while calculating the CID. Restore the hot value
+        // after any older cleanup that was already in flight.
+        this.throwIfNativeDurableCommitFailed();
+        this.native.putKnown(cid, value);
+        await this.commitDurableMutation(() => this.durable.putKnown(cid, value), [cid]);
+        return cid;
+    }
+    async putMany(blocks) {
+        await this.drainDurable();
+        const cids = await this.native.putMany(blocks);
+        const durableBlocks = cids.map((cid, index) => {
+            const block = blocks[index];
+            const value = block instanceof Uint8Array
+                ? block
+                : block.block.bytes;
+            return [cid, value];
+        });
+        this.noteNativeBlockWrite(cids);
+        await this.waitForNativeDeleteCleanup();
+        this.throwIfNativeDurableCommitFailed();
+        this.native.putKnownMany(durableBlocks);
+        await this.commitDurableMutation(() => this.durable.putKnownMany(durableBlocks), cids);
+        return cids;
+    }
+    // Native put is synchronous (the authoritative hot store); the durable mirror
+    // is awaited so the returned promise resolves only after BOTH native and
+    // durable succeed and a durable IO/disk-full failure rejects here instead of
+    // being swallowed. RemoteBlocks.putKnown and the log's putKnownEntryBytesBatch
+    // both await this method, so returning a promise is compatible.
+    async putKnown(cid, bytes) {
+        await this.drainDurable();
+        await this.waitForNativeDeleteCleanup();
+        this.throwIfNativeDurableCommitFailed();
+        const stored = this.native.putKnown(cid, bytes);
+        this.noteNativeBlockWrite([cid]);
+        await this.commitDurableMutation(() => this.durable.putKnown(cid, bytes), [cid]);
+        return stored;
+    }
+    async putKnownMany(blocks) {
+        await this.drainDurable();
+        await this.waitForNativeDeleteCleanup();
+        this.throwIfNativeDurableCommitFailed();
+        const cids = this.native.putKnownMany(blocks);
+        this.noteNativeBlockWrite(cids);
+        await this.commitDurableMutation(() => this.durable.putKnownMany(blocks), cids);
+        return cids;
+    }
+    putKnownManyColumns(cids, bytes) {
+        this.throwIfNativeDurableCommitFailed();
+        if (cids.length !== bytes.length) {
+            throw new Error("Expected equal block column lengths");
+        }
+        const cleanupBarrier = this.nativeDeleteCleanupRunning;
+        const stored = this.native.putKnownManyColumns(cids, bytes);
+        this.noteNativeBlockWrite(cids);
+        // AnyBlockStore has no columnar method; mirror via putKnownMany, which
+        // takes [cid, bytes] tuples and hits the same batched store path.
+        // This method must return a synchronous string[] (RemoteBlocks.putKnownManyColumns
+        // consumes the result synchronously), so the durable write cannot be awaited
+        // inline. Track it instead of `void`ing it so a durable rejection surfaces
+        // on the next awaited wrapper method / stop() rather than being swallowed.
+        const durableBlocks = cids.map((cid, index) => [cid, bytes[index]]);
+        let durableResult;
+        try {
+            durableResult = cleanupBarrier
+                ? cleanupBarrier.then(() => this.durable.putKnownMany(durableBlocks))
+                : this.durable.putKnownMany(durableBlocks);
+        }
+        catch (error) {
+            throw this.recordNativeDurableCommitFailure(error, {
+                committedCids: cids,
+                failedCids: cids,
+            });
+        }
+        this.trackDurable(durableResult, cids);
+        return stored;
+    }
+    // --- reads (native/wasm first; on miss, durable fallback + repopulate) ---
+    // RemoteBlocks.get awaits this single-get, so on a native miss consult the
+    // durable store (like getMany does) and repopulate the native map, rather
+    // than returning undefined and only scheduling a background repopulate. That
+    // avoids a spurious miss (which would otherwise fall through to a remote
+    // read) for a block that is present on disk.
+    async get(cid, _options) {
+        if (this.nativeDurableCommitFailure) {
+            // After poison, durable storage is the last acknowledged authority. Do not
+            // repopulate or otherwise mutate the native store until reopen.
+            return this.isNativeDeletePending(cid)
+                ? undefined
+                : this.durable.get(cid);
+        }
+        const deleteEpoch = this.nativeDeleteEpoch;
+        if (this.isNativeDeletePending(cid)) {
+            return undefined;
+        }
+        const local = this.native.get(cid);
+        if (local != null) {
+            return deleteEpoch === this.nativeDeleteEpoch ? local : this.get(cid);
+        }
+        const durableValue = await this.durable.get(cid);
+        if (this.nativeDurableCommitFailure) {
+            return this.isNativeDeletePending(cid) ? undefined : durableValue;
+        }
+        if (deleteEpoch !== this.nativeDeleteEpoch) {
+            return this.get(cid);
+        }
+        if (durableValue != null) {
+            // Repopulate the native map so the native graph reads it next time.
+            this.native.putKnownManyColumns([cid], [durableValue]);
+            return durableValue;
+        }
+        return undefined;
+    }
+    async getMany(cids) {
+        if (this.nativeDurableCommitFailure) {
+            const values = await this.durable.getMany(cids);
+            for (let index = 0; index < cids.length; index++) {
+                if (this.isNativeDeletePending(cids[index])) {
+                    values[index] = undefined;
+                }
+            }
+            return values;
+        }
+        const deleteEpoch = this.nativeDeleteEpoch;
+        const results = await this.native.getMany(cids);
+        if (deleteEpoch !== this.nativeDeleteEpoch) {
+            return this.getMany(cids);
+        }
+        const missing = [];
+        const missingIndexes = [];
+        for (let i = 0; i < results.length; i++) {
+            if (this.isNativeDeletePending(cids[i])) {
+                results[i] = undefined;
+            }
+            else if (results[i] == null) {
+                missing.push(cids[i]);
+                missingIndexes.push(i);
+            }
+        }
+        if (missing.length === 0) {
+            return results;
+        }
+        const durableValues = await this.durable.getMany(missing);
+        if (this.nativeDurableCommitFailure) {
+            const values = await this.durable.getMany(cids);
+            for (let index = 0; index < cids.length; index++) {
+                if (this.isNativeDeletePending(cids[index])) {
+                    values[index] = undefined;
+                }
+            }
+            return values;
+        }
+        if (deleteEpoch !== this.nativeDeleteEpoch) {
+            return this.getMany(cids);
+        }
+        const repopulateCids = [];
+        const repopulateBytes = [];
+        for (let missingIndex = 0; missingIndex < missingIndexes.length; missingIndex++) {
+            const i = missingIndexes[missingIndex];
+            const value = durableValues[missingIndex];
+            if (value != null) {
+                results[i] = value;
+                repopulateCids.push(cids[i]);
+                repopulateBytes.push(value);
+            }
+        }
+        if (repopulateCids.length > 0) {
+            // Repopulate the native map so the native graph sees these blocks.
+            this.native.putKnownManyColumns(repopulateCids, repopulateBytes);
+        }
+        return results;
+    }
+    async has(cid) {
+        if (this.nativeDurableCommitFailure) {
+            return this.isNativeDeletePending(cid) ? false : this.durable.has(cid);
+        }
+        const deleteEpoch = this.nativeDeleteEpoch;
+        if (this.isNativeDeletePending(cid)) {
+            return false;
+        }
+        if (this.native.has(cid)) {
+            return deleteEpoch === this.nativeDeleteEpoch ? true : this.has(cid);
+        }
+        // Mirror getMany/hasMany: a block absent from the native wasm map may still
+        // be present in the durable store (e.g. persisted on disk but not yet
+        // repopulated into wasm). Consult durable on a native miss so presence
+        // checks agree with the resolves that getMany/hasMany already durable-fall
+        // back on. `Blocks.has` is declared `MaybePromise<boolean>`, so returning a
+        // promise here is contract-compatible.
+        const durableHas = await this.durable.has(cid);
+        return deleteEpoch === this.nativeDeleteEpoch ? durableHas : this.has(cid);
+    }
+    async hasMany(cids) {
+        if (this.nativeDurableCommitFailure) {
+            const values = await this.durable.hasMany(cids);
+            for (let index = 0; index < cids.length; index++) {
+                if (this.isNativeDeletePending(cids[index])) {
+                    values[index] = false;
+                }
+            }
+            return values;
+        }
+        const deleteEpoch = this.nativeDeleteEpoch;
+        const nativeHas = await this.native.hasMany(cids);
+        if (deleteEpoch !== this.nativeDeleteEpoch) {
+            return this.hasMany(cids);
+        }
+        const missing = [];
+        const missingIndexes = [];
+        for (let i = 0; i < nativeHas.length; i++) {
+            if (this.isNativeDeletePending(cids[i])) {
+                nativeHas[i] = false;
+            }
+            else if (!nativeHas[i]) {
+                missing.push(cids[i]);
+                missingIndexes.push(i);
+            }
+        }
+        if (missing.length === 0) {
+            return nativeHas;
+        }
+        const durableHas = await this.durable.hasMany(missing);
+        if (deleteEpoch !== this.nativeDeleteEpoch) {
+            return this.hasMany(cids);
+        }
+        for (let missingIndex = 0; missingIndex < missingIndexes.length; missingIndex++) {
+            nativeHas[missingIndexes[missingIndex]] = durableHas[missingIndex];
+        }
+        return nativeHas;
+    }
+    // --- removes (apply to BOTH) ----------------------------------------
+    // Native rm is synchronous; the durable rm is awaited so the returned promise
+    // resolves only after both succeed and a durable failure rejects here rather
+    // than being swallowed. All rm callers (RemoteBlocks.rm, the log) await it.
+    async rm(cid) {
+        this.throwIfNativeDurableCommitFailed();
+        const writeGeneration = this.nativeBlockWriteGenerations.get(cid);
+        this.beginNativeDelete([cid]);
+        try {
+            await this.drainDurable();
+            this.native.rm(cid);
+            await this.commitDurableMutation(() => this.durable.rm(cid), [cid]);
+            // A durable read that began before the tombstone may have repopulated
+            // native while durable rm was pending. Remove it idempotently again.
+            this.native.rm(cid);
+            if (this.nativeBlockWriteGenerations.get(cid) === writeGeneration &&
+                !this.pendingNativeDeleteCleanup.has(cid)) {
+                this.nativeBlockWriteGenerations.delete(cid);
+            }
+        }
+        finally {
+            this.endNativeDelete([cid]);
+        }
+    }
+    del(cid) {
+        return this.rm(cid);
+    }
+    async rmMany(cids) {
+        this.throwIfNativeDurableCommitFailed();
+        const writeGenerations = new Map(cids.map((cid) => [cid, this.nativeBlockWriteGenerations.get(cid)]));
+        this.beginNativeDelete(cids);
+        try {
+            await this.drainDurable();
+            const removed = await this.native.rmMany(cids);
+            await this.commitDurableMutation(() => this.durable.rmMany(cids), cids);
+            await this.native.rmMany(cids);
+            for (const cid of cids) {
+                if (this.nativeBlockWriteGenerations.get(cid) ===
+                    writeGenerations.get(cid) &&
+                    !this.pendingNativeDeleteCleanup.has(cid)) {
+                    this.nativeBlockWriteGenerations.delete(cid);
+                }
+            }
+            return removed;
+        }
+        finally {
+            this.endNativeDelete(cids);
+        }
+    }
+    // Native trim may already have removed the hot wasm blocks. Queue the durable
+    // copy for cleanup, retaining read tombstones until removal succeeds; a
+    // cleanup failure is retried and never fed into ordinary append rollback.
+    // EntryIndex feature-detects this hook.
+    async rmManyAfterNativeDelete(cids, cleanupToken) {
+        if (this.nativeDurableCommitFailure) {
+            this.cancelNativeDeleteCleanup(cleanupToken);
+            throw this.nativeDurableCommitFailure;
+        }
+        let preannounced = false;
+        if (typeof cleanupToken === "number") {
+            const staged = this.stagedNativeDeleteCleanups.get(cleanupToken);
+            if (staged) {
+                preannounced = true;
+                this.stagedNativeDeleteCleanups.delete(cleanupToken);
+                for (const [cid, generation] of staged) {
+                    if ((this.nativeBlockWriteGenerations.get(cid) ?? 0) !== generation) {
+                        this.endNativeDelete([cid]);
+                        continue;
+                    }
+                    if (this.pendingNativeDeleteCleanup.has(cid)) {
+                        // Another delete already owns a tombstone for this CID.
+                        this.endNativeDelete([cid]);
+                    }
+                    else {
+                        // Transfer the staged tombstone to the now-published cleanup.
+                        this.pendingNativeDeleteCleanup.set(cid, generation);
+                    }
+                }
+            }
+        }
+        if (!preannounced) {
+            this.enqueueNativeDeleteCleanup(cids);
+        }
+        await this.retryNativeDeleteCleanup();
+    }
+    /** Finish committed trim GC before its durable recovery intent is retired. */
+    async completeCommittedNativeDeleteCleanup(cids, options) {
+        this.throwIfNativeDurableCommitFailed();
+        const uniqueCids = [...new Set(cids.filter(Boolean))];
+        if (uniqueCids.length === 0) {
+            return;
+        }
+        // Only restart recovery reconstructs missing debt. On the live path, an
+        // absent row may mean the CID was legitimately re-added after its original
+        // generation-owned trim completed or was cancelled; re-enqueueing it here
+        // would capture the new generation and delete live content.
+        if (options?.reconstructMissing) {
+            this.enqueueNativeDeleteCleanup(uniqueCids);
+        }
+        if (!uniqueCids.some((cid) => this.pendingNativeDeleteCleanup.has(cid))) {
+            return;
+        }
+        await this.retryNativeDeleteCleanup({ throwOnFailure: true });
+        const remaining = uniqueCids.filter((cid) => this.pendingNativeDeleteCleanup.has(cid));
+        if (remaining.length > 0) {
+            throw new Error(`Committed native trim cleanup remains incomplete: ${remaining.join(", ")}`);
+        }
+    }
+    // --- misc ------------------------------------------------------------
+    async *iterator() {
+        if (this.nativeDurableCommitFailure) {
+            for await (const block of this.durable.iterator()) {
+                if (!this.isNativeDeletePending(block[0])) {
+                    yield block;
+                }
+            }
+            return;
+        }
+        yield* this.native.iterator();
+    }
+    async size() {
+        // The hot wasm map is intentionally cold after reopen, so it cannot be the
+        // storage-budget authority. Settle synchronous columnar mirrors first, then
+        // report durable bytes; pending trim cleanup remains conservatively counted
+        // until its durable deletion succeeds.
+        await this.drainDurable();
+        return this.durable.size();
+    }
+    persisted() {
+        // The blocks are now mirrored to a durable store, so report persisted so
+        // callers that gate durable-only behavior on this flag behave correctly.
+        return true;
+    }
+}
+//# sourceMappingURL=native-write-through-block-store.js.map