@opendatalabs/personal-server-ts-core 1.34.2 → 1.35.0

package/dist/additions/durable.d.ts

@@ -1,14 +1,28 @@
 import { type ByteBudget } from "./budget.js";
 import { type GatewayClient } from "@opendatalabs/vana-sdk/browser";
 import type { StorageAdapter } from "../storage/adapters/interface.js";
+import { type FencedPublicationPort, NeedsFencedPublicationError } from "../publication/publish.js";
 import type { ServerSigner } from "../signing/signer.js";
 import { type VersionToFold } from "./first-added.js";
 import { type AdditionsSummary } from "./summary.js";
-import { type VersionInventoryClient } from "./version-inventory.js";
+import { type VersionInventory, type VersionInventoryClient } from "./version-inventory.js";
 export declare const ADDITIONS_SUMMARY_SCOPE = "vana.system.additions";
 /** The separate hash namespace cannot collide with a literal source suffix. */
 export declare function additionsLedgerScope(scope: string): string;
+export type AdditionsRecoveryCode = "compressed_packet" | "decrypt_failed" | "data_hash_mismatch" | "metadata_hash_mismatch" | "invalid_envelope" | "unsupported_source_data" | "replay_failed" | "checkpoint_search_exhausted" | "budget_exceeded" | "cancelled";
+export interface AdditionsRecoveryDiagnostic {
+    scope: string;
+    version: string;
+    code: AdditionsRecoveryCode;
+}
+/** Fixed operator codes only: never retain payloads or raw exception text. */
+export declare class AdditionsRecoveryError extends Error {
+    readonly code: AdditionsRecoveryCode;
+    constructor(code: AdditionsRecoveryCode, message?: string);
+}
 export interface DurableAdditionsOptions {
+    /** Transient operator observation; never persisted in ledgers or summaries. */
+    onRecoveryDiagnostic?: (event: AdditionsRecoveryDiagnostic) => void;
     ownerAddress: string;
     /** Include chain and Gateway origin. A service instance belongs to one owner/network. */
     network: string;
@@ -17,7 +31,11 @@ export interface DurableAdditionsOptions {
     masterKey: Uint8Array;
     signer: Pick<ServerSigner, "signAddData">;
     gateway: Pick<GatewayClient, "registerDataPoint">;
-    /** Full PS defaults remain unlimited. Bounded hosts must also supply boundedWork. */
+    fencedPublication?: FencedPublicationPort;
+    /** Summaries remain behind; hosts can expose the retryable recovery reason. */
+    onPublicationBlocked?: (error: NeedsFencedPublicationError) => void;
+    /** Full PS source replay defaults remain unlimited; checkpoint discovery is capped.
+     * Bounded hosts must also supply boundedWork. */
     byteBudget?: number;
     /** Host operations must cancel and settle all work before returning on abort.
      * Crypto must enforce a plaintext limit before decompression/allocation.
@@ -56,6 +74,18 @@ export interface DurableAdditionsService {
         signal?: AbortSignal;
     }): Promise<void>;
 }
+/** Reuse only a commitment still visible after the current registry deletion boundary. */
+export declare function findCheckpointRegistration(snapshot: VersionInventory, version: string, commitment: {
+    dataHash: string;
+    metadataHash: string;
+}): {
+    expectedVersion: string;
+    dataHash: string;
+    metadataHash: string;
+    status: string;
+    addedAt: string;
+    isTombstone: boolean;
+} | undefined;
 /**
  * Revalidates commitments, rather than trusting a numeric watermark or a local
  * mutex. Persisted lost/lower-prefix writes are repaired from the next inventory.

package/dist/additions/durable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../../src/additions/durable.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,sBAAsB,EAE5B,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAyB/D,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,sBAAsB,CAAC;IAClC,cAAc,EAAE,cAAc,CAAC;IAC/B,SAAS,EAAE,UAAU,CAAC;IACtB,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;IAC1C,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC;IAClD,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE;QACZ,kFAAkF;QAClF,SAAS,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7D,OAAO,CACL,SAAS,EAAE,UAAU,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,UAAU,CAAC,CAAC;QACvB,OAAO,CACL,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC;YACT,eAAe,EAAE,MAAM,CAAC;YACxB,QAAQ,EAAE,MAAM,CAAC;YACjB,YAAY,EAAE,MAAM,CAAC;SACtB,CAAC,CAAC;KACJ,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,KAAK,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,IAAI,CAAC;KACX,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9B,YAAY,CACV,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,EACrD,KAAK,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GACnD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;+EAC2E;IAC3E,WAAW,CACT,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,WAAW,EAAE,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACpD,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAsED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,uBAAuB,CAymBzB"}
+{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../../src/additions/durable.ts"],"names":[],"mappings":"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"}

package/dist/additions/durable.js

@@ -1,7 +1,9 @@
 import { AdditionsBudget, AdditionsBudgetExceeded as BudgetExceeded, } from "./budget.js";
 import { z } from "zod";
-import { getAddress, keccak256, stringToHex } from "viem";
-import { createDataFileEnvelope, DataFileEnvelopeSchema, decryptWithPassword, deriveScopeKey, encryptWithPassword, } from "@opendatalabs/vana-sdk/browser";
+import { keccak256, stringToHex } from "viem";
+import { createDataFileEnvelope, DataFileEnvelopeSchema, decryptWithPassword, deriveScopeKey, } from "@opendatalabs/vana-sdk/browser";
+import { publishVersion, NeedsFencedPublicationError, } from "../publication/publish.js";
+import { computeDataPointId } from "../sync/data-point-id.js";
 import { foldVersion, extractRecordKeys, readScopeFirstSeenLedger, } from "./first-added.js";
 import { summarizeAdditions, ADDITIONS_SUMMARY_MAX_BYTES, } from "./summary.js";
 import { fingerprintVersionInventory, } from "./version-inventory.js";
@@ -33,14 +35,28 @@ export function additionsLedgerScope(scope) {
         ? literal
         : `vana.system.additions-hash.${keccak256(stringToHex(scope)).slice(2)}`;
 }
+/** Fixed operator codes only: never retain payloads or raw exception text. */
+export class AdditionsRecoveryError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+        this.name = "AdditionsRecoveryError";
+    }
+}
 class InaccessibleLedger extends Error {
 }
+class CheckpointSearchExceeded extends BudgetExceeded {
+}
+const CHECKPOINT_READ_LIMIT = 256;
 class BoundedWorkUnavailable extends Error {
 }
 class ReadBudget extends AdditionsBudget {
     limited;
+    checkpoints;
     constructor(options, parent) {
         super(options.byteBudget, options.timeBudgetMs, options.signal, parent);
+        this.checkpoints = parent?.checkpoints ?? { reads: 0, rejected: new Map() };
         this.limited =
             options.byteBudget !== undefined || options.timeBudgetMs !== undefined;
     }
@@ -81,6 +97,33 @@ function sameInventory(a, b) {
 function settled(slot) {
     return slot.status === "confirmed" || slot.status === "finalized";
 }
+function eligible(slot) {
+    return (!slot.isTombstone &&
+        ["confirmed", "finalized", "pending", "submitting"].includes(slot.status));
+}
+function sourceWindow(snapshot) {
+    const end = BigInt(snapshot.head?.expectedVersion ?? "0");
+    const rows = snapshot.versions.filter((slot) => BigInt(slot.expectedVersion) <= end);
+    const after = BigInt(rows.filter((slot) => slot.isTombstone && settled(slot)).at(-1)
+        ?.expectedVersion ?? "0");
+    return {
+        end,
+        after,
+        relevant: rows.filter((slot) => BigInt(slot.expectedVersion) > after),
+    };
+}
+/** Reuse only a commitment still visible after the current registry deletion boundary. */
+export function findCheckpointRegistration(snapshot, version, commitment) {
+    if (!snapshot.head || snapshot.head.deletedAt !== null)
+        return undefined;
+    const { end, after } = sourceWindow(snapshot);
+    if (BigInt(version) > end || BigInt(version) <= after)
+        return undefined;
+    return snapshot.versions.find((row) => row.expectedVersion === version &&
+        eligible(row) &&
+        row.dataHash.toLowerCase() === commitment.dataHash.toLowerCase() &&
+        row.metadataHash.toLowerCase() === commitment.metadataHash.toLowerCase());
+}
 function sourceData(data) {
     if (data === null || typeof data !== "object" || Array.isArray(data))
         return null;
@@ -105,14 +148,31 @@ export function createDurableAdditions(options) {
         if (!budget.limited)
             budget.check(encrypted.byteLength);
         const password = hex(deriveScopeKey(options.masterKey, scope));
-        const plaintext = budget.limited && options.boundedWork
-            ? await options.boundedWork.decrypt(encrypted, password, budget)
-            : await decryptWithPassword(encrypted, password);
+        let plaintext;
+        try {
+            plaintext =
+                budget.limited && options.boundedWork
+                    ? await options.boundedWork.decrypt(encrypted, password, budget)
+                    : await decryptWithPassword(encrypted, password);
+        }
+        catch (error) {
+            if (error instanceof AdditionsRecoveryError ||
+                error instanceof BudgetExceeded ||
+                budget.signal?.aborted)
+                throw error;
+            throw new AdditionsRecoveryError("decrypt_failed");
+        }
         budget.check(plaintext.byteLength);
         if (keccak256(plaintext).toLowerCase() !== slot.dataHash.toLowerCase())
-            throw new Error("Additions content commitment mismatch");
+            throw new AdditionsRecoveryError("data_hash_mismatch", "Additions content commitment mismatch");
         budget.check(plaintext.byteLength * 3);
-        const envelope = DataFileEnvelopeSchema.parse(JSON.parse(new TextDecoder().decode(plaintext)));
+        let envelope;
+        try {
+            envelope = DataFileEnvelopeSchema.parse(JSON.parse(new TextDecoder().decode(plaintext)));
+        }
+        catch {
+            throw new AdditionsRecoveryError("invalid_envelope");
+        }
         const metadataHash = keccak256(stringToHex(JSON.stringify({
             scope,
             collectedAt: envelope.collectedAt,
@@ -121,7 +181,7 @@ export function createDurableAdditions(options) {
         if (envelope.scope !== scope ||
             !Number.isFinite(Date.parse(envelope.collectedAt)) ||
             metadataHash.toLowerCase() !== slot.metadataHash.toLowerCase())
-            throw new Error("Additions metadata commitment mismatch");
+            throw new AdditionsRecoveryError("metadata_hash_mismatch", "Additions metadata commitment mismatch");
         budget.check();
         return envelope;
     }
@@ -132,27 +192,61 @@ export function createDurableAdditions(options) {
         const head = snapshot.head;
         if (!head || head.deletedAt !== null)
             return null;
-        const slot = snapshot.versions.find((row) => row.expectedVersion === head.expectedVersion &&
-            !row.isTombstone &&
-            row.dataHash === head.dataHash &&
-            row.metadataHash === head.metadataHash);
+        const slot = findCheckpointRegistration(snapshot, head.expectedVersion, head);
         if (!slot)
             throw new Error("Additions head missing from inventory");
         return { snapshot, envelope: await readEnvelope(scope, slot, budget) };
     }
-    async function readDocument(scope, budget) {
+    async function readDocument(scope, budget, source, search) {
+        const { relevant, after } = sourceWindow(source);
         const systemScope = additionsLedgerScope(scope);
         const snapshot = await inventory.list(systemScope, budget.readOptions);
         if (!snapshot.head || snapshot.head.deletedAt !== null)
             return null;
-        const boundary = snapshot.versions.filter((row) => row.isTombstone).at(-1)
-            ?.expectedVersion ?? "0";
+        // Same visibility as source recovery: only settled tombstones at or below the head delete history.
+        const boundary = snapshot.versions
+            .filter((row) => row.isTombstone &&
+            settled(row) &&
+            BigInt(row.expectedVersion) <=
+                BigInt(snapshot.head.expectedVersion))
+            .at(-1)?.expectedVersion ?? "0";
         let inaccessible = false;
-        for (const slot of [...snapshot.versions].reverse()) {
+        const sourceFingerprint = fingerprintVersionInventory(source);
+        for (let index = snapshot.versions.length - 1; index >= 0; index--) {
+            budget.check();
+            const slot = snapshot.versions[index];
             if (BigInt(slot.expectedVersion) <= BigInt(boundary) ||
                 BigInt(slot.expectedVersion) > BigInt(snapshot.head.expectedVersion) ||
-                slot.isTombstone)
+                (search && BigInt(slot.expectedVersion) >= BigInt(search.before)) ||
+                !eligible(slot))
+                continue;
+            const identity = JSON.stringify([
+                systemScope,
+                slot.expectedVersion,
+                slot.dataHash.toLowerCase(),
+                slot.metadataHash.toLowerCase(),
+                sourceFingerprint,
+            ]);
+            const rejected = budget.checkpoints.rejected.get(identity);
+            if (rejected !== undefined) {
+                inaccessible ||= rejected === "inaccessible";
                 continue;
+            }
+            if (budget.checkpoints.reads >= CHECKPOINT_READ_LIMIT) {
+                try {
+                    options.onRecoveryDiagnostic?.({
+                        scope,
+                        version: slot.expectedVersion,
+                        code: "checkpoint_search_exhausted",
+                    });
+                }
+                catch {
+                    /* Observation cannot alter recovery. */
+                }
+                throw new CheckpointSearchExceeded("Retained checkpoint search exhausted");
+            }
+            budget.check(identity.length * 2 + 64);
+            budget.checkpoints.reads++;
             let envelope;
             try {
                 envelope = await readEnvelope(systemScope, slot, budget);
@@ -161,25 +255,38 @@ export function createDurableAdditions(options) {
                 if (error instanceof BudgetExceeded || budget.signal?.aborted)
                     throw error;
                 inaccessible = true;
+                budget.checkpoints.rejected.set(identity, "inaccessible");
                 continue;
             }
             const parsed = documentSchema.safeParse(envelope.data);
             if (!parsed.success ||
                 parsed.data.owner !== owner ||
                 parsed.data.network !== options.network ||
-                parsed.data.scope !== scope)
+                parsed.data.scope !== scope) {
+                budget.checkpoints.rejected.set(identity, "invalid");
                 continue;
+            }
             const ledger = parsed.data.ledger === null
                 ? null
                 : readScopeFirstSeenLedger(parsed.data.ledger);
-            if (parsed.data.ledger !== null && (!ledger || ledger.scope !== scope))
+            if (parsed.data.ledger !== null && (!ledger || ledger.scope !== scope)) {
+                budget.checkpoints.rejected.set(identity, "invalid");
+                continue;
+            }
+            const candidate = { ...parsed.data, ledger };
+            if (candidate.slots.length > relevant.length ||
+                !candidate.slots.every((row, i) => eligible(relevant[i]) && sameCommitment(row, relevant[i])) ||
+                candidate.through !==
+                    (candidate.slots.at(-1)?.expectedVersion ?? String(after))) {
+                budget.checkpoints.rejected.set(identity, "invalid");
+                continue;
+            }
+            if (search && candidate.slots.length <= search.longerThan)
                 continue;
             return {
-                ...parsed.data,
-                ledger,
-                ...(slot.expectedVersion !== snapshot.head.expectedVersion
-                    ? { repairHead: true }
-                    : {}),
+                document: candidate,
+                publicationVersion: slot.expectedVersion,
+                repairHead: slot.expectedVersion !== snapshot.head.expectedVersion,
             };
         }
         if (inaccessible)
@@ -194,9 +301,7 @@ export function createDurableAdditions(options) {
             const proof = await options.boundedWork.publish(scope, data, budget);
             budget.check();
             const check = await inventory.list(scope, budget.readOptions);
-            const slot = check.versions.find((row) => row.expectedVersion === proof.expectedVersion &&
-                row.dataHash === proof.dataHash &&
-                row.metadataHash === proof.metadataHash);
+            const slot = findCheckpointRegistration(check, proof.expectedVersion, proof);
             if (!slot)
                 throw new Error("Bounded checkpoint registration was replaced");
             const envelope = await readEnvelope(scope, slot, budget);
@@ -207,38 +312,34 @@ export function createDurableAdditions(options) {
             return;
         }
         const snapshot = await inventory.list(scope, budget.readOptions);
-        const version = BigInt(snapshot.versions.at(-1)?.expectedVersion ?? "0") + 1n;
-        const envelope = createDataFileEnvelope(scope, new Date().toISOString(), data);
-        const plaintext = new TextEncoder().encode(JSON.stringify(envelope));
-        const encrypted = await encryptWithPassword(plaintext, hex(deriveScopeKey(options.masterKey, scope)));
-        const dataHash = keccak256(plaintext);
-        const metadataHash = keccak256(stringToHex(JSON.stringify({
-            scope,
-            collectedAt: envelope.collectedAt,
-            sizeBytes: encrypted.byteLength,
-        })));
-        await storageAdapter.upload(`${scope}/${version}`, encrypted);
-        const signature = await options.signer.signAddData({
-            ownerAddress: getAddress(owner),
-            scope,
-            dataHash,
-            metadataHash,
-            expectedVersion: version,
-        });
-        await options.gateway.registerDataPoint({
+        const toHead = (state) => state.head
+            ? {
+                ...state.head,
+                id: computeDataPointId(owner, scope),
+            }
+            : null;
+        const proof = await publishVersion({
             ownerAddress: owner,
-            scope,
-            dataHash,
-            metadataHash,
-            expectedVersion: String(version),
-            signature,
+            envelope: createDataFileEnvelope(scope, new Date().toISOString(), data),
+            preferredVersion: BigInt(snapshot.versions.at(-1)?.expectedVersion ?? "0") + 1n,
+            masterKey: options.masterKey,
+            storageAdapter,
+            signer: options.signer,
+            gateway: options.gateway,
+            fencedPublication: options.fencedPublication,
+            head: toHead(snapshot),
+            readHead: async () => toHead(await inventory.list(scope, budget.readOptions)),
+            // Rebuilding an explicitly deleted system document is a deliberate re-add.
+            acknowledgedDeletionVersion: snapshot.head?.deletedAt
+                ? BigInt(snapshot.head.expectedVersion)
+                : undefined,
+        }).catch((error) => {
+            if (error instanceof NeedsFencedPublicationError)
+                options.onPublicationBlocked?.(error);
+            throw error;
         });
-        // A concurrent upload can replace the bytes at this shared version key
-        // independently of registration. Never claim durability without checking.
         const check = await inventory.list(scope, budget.readOptions);
-        const registered = check.versions.find((slot) => slot.expectedVersion === String(version) &&
-            slot.dataHash === dataHash &&
-            slot.metadataHash === metadataHash);
+        const registered = findCheckpointRegistration(check, String(proof.version), proof);
         if (!registered)
             throw new Error("Concurrent additions publication replaced the registration");
         await readEnvelope(scope, registered, budget);
@@ -273,28 +374,19 @@ export function createDurableAdditions(options) {
                             : "complete",
             };
         }
-        const end = BigInt(head.expectedVersion);
-        const rows = snapshot.versions.filter((slot) => BigInt(slot.expectedVersion) <= end);
-        const boundary = rows
-            .filter((slot) => slot.isTombstone && settled(slot))
-            .at(-1);
-        const after = BigInt(boundary?.expectedVersion ?? "0");
-        const relevant = rows.filter((slot) => BigInt(slot.expectedVersion) > after);
-        let existing = null;
+        const { end, after, relevant } = sourceWindow(snapshot);
+        let checkpoint = null;
         let inaccessibleExisting = false;
         try {
-            existing = await readDocument(scope, budget);
+            checkpoint = await readDocument(scope, budget, snapshot);
         }
         catch (error) {
             if (error instanceof BudgetExceeded || budget.signal?.aborted)
                 throw error;
             inaccessibleExisting = true;
         }
-        const prefixValid = existing !== null &&
-            existing.slots.length <= relevant.length &&
-            existing.slots.every((slot, i) => sameCommitment(slot, relevant[i])) &&
-            existing.through ===
-                (existing.slots.at(-1)?.expectedVersion ?? String(after));
+        let existing = checkpoint?.document ?? null;
+        const prefixValid = existing !== null;
         let ledger = prefixValid ? existing.ledger : null;
         const folded = prefixValid ? relevant.slice(0, existing.slots.length) : [];
         let currentTotal = prefixValid ? existing.currentTotal : 0;
@@ -309,6 +401,7 @@ export function createDurableAdditions(options) {
                 coverage = "partial";
             expected = BigInt(slot.expectedVersion) + 1n;
         }
+        const sourceCoverage = coverage;
         const checkpointBytes = (candidate, count) => 128 * 1024 +
             128 *
                 new TextEncoder().encode(JSON.stringify({
@@ -320,23 +413,20 @@ export function createDurableAdditions(options) {
                     through,
                     currentTotal,
                 })).byteLength;
-        for (const slot of relevant.slice(folded.length)) {
+        while (folded.length < relevant.length) {
+            const slot = relevant[folded.length];
+            let unitBudget = budget;
             try {
                 // Keep publication capacity in the same owner-wide allowance. Exhaustion
                 // of the child leaves the already-folded prefix publishable.
-                const unitBudget = budget.limited
+                unitBudget = budget.limited
                     ? budget.excluding(checkpointBytes(ledger, folded.length))
                     : budget;
                 unitBudget.check();
                 if (BigInt(slot.expectedVersion) !== BigInt(through) + 1n)
                     coverage = "partial";
                 // Mutable slots are provisional; failed/unknown slots cannot advance the prefix.
-                if (slot.status === "failed" ||
-                    !["confirmed", "finalized", "pending", "submitting"].includes(slot.status)) {
-                    coverage = "partial";
-                    break;
-                }
-                if (slot.isTombstone) {
+                if (!eligible(slot)) {
                     coverage = "partial";
                     break;
                 }
@@ -362,14 +452,14 @@ export function createDurableAdditions(options) {
                     metadata === slot.metadataHash) {
                     const data = sourceData(inMemory.data.data);
                     if (!data)
-                        throw new Error("Unsupported source envelope");
+                        throw new AdditionsRecoveryError("unsupported_source_data");
                     version = { scope, collectedAt: inMemory.data.collectedAt, data };
                 }
                 else {
                     const envelope = await readEnvelope(scope, slot, unitBudget);
                     const data = sourceData(envelope.data);
                     if (!data)
-                        throw new Error("Unsupported source envelope");
+                        throw new AdditionsRecoveryError("unsupported_source_data");
                     version = { scope, collectedAt: envelope.collectedAt, data };
                 }
                 const hadBaseline = ledger !== null && ledger.baseline !== null;
@@ -391,8 +481,61 @@ export function createDurableAdditions(options) {
                 through = slot.expectedVersion;
             }
             catch (error) {
+                // Normal advancement needs one checkpoint, not the complete publication
+                // history. Search older evidence only when replay cannot advance, keeping
+                // the bytes reserved for publishing our best verified source prefix.
+                if (checkpoint && !budget.signal?.aborted) {
+                    const searchBudget = budget.limited
+                        ? budget.excluding(checkpointBytes(ledger, folded.length))
+                        : budget;
+                    try {
+                        const fallback = await readDocument(scope, searchBudget, snapshot, {
+                            before: checkpoint.publicationVersion,
+                            longerThan: folded.length,
+                        });
+                        if (fallback) {
+                            checkpoint = fallback;
+                            existing = fallback.document;
+                            ledger = existing.ledger;
+                            currentTotal = existing.currentTotal;
+                            through = existing.through;
+                            folded.splice(0, folded.length, ...relevant.slice(0, existing.slots.length));
+                            coverage = sourceCoverage;
+                            continue;
+                        }
+                    }
+                    catch (failure) {
+                        // Keep the verified prefix and its publication reserve, but expose
+                        // a bounded search that could not finish as retryable coverage.
+                        if (failure instanceof BudgetExceeded)
+                            error = failure;
+                        else if (searchBudget.signal?.aborted)
+                            error = new BudgetExceeded("Checkpoint fallback allowance exhausted");
+                    }
+                }
+                try {
+                    options.onRecoveryDiagnostic?.({
+                        scope,
+                        version: slot.expectedVersion,
+                        code: error instanceof BudgetExceeded ||
+                            (unitBudget.signal?.aborted &&
+                                unitBudget.signal.reason instanceof DOMException &&
+                                unitBudget.signal.reason.name === "TimeoutError")
+                            ? "budget_exceeded"
+                            : budget.signal?.aborted
+                                ? "cancelled"
+                                : error instanceof AdditionsRecoveryError
+                                    ? error.code
+                                    : "replay_failed",
+                    });
+                }
+                catch {
+                    /* Observation cannot alter recovery. */
+                }
                 coverage =
-                    error instanceof BudgetExceeded || budget.signal?.aborted
+                    error instanceof BudgetExceeded ||
+                        budget.signal?.aborted ||
+                        unitBudget.signal?.aborted
                         ? "behind"
                         : "partial";
                 break;
@@ -428,7 +571,8 @@ export function createDurableAdditions(options) {
         if (((!existing && !inaccessibleExisting) ||
             prefixValid ||
             coverage === "complete") &&
-            JSON.stringify(document) !== JSON.stringify(existing)) {
+            (checkpoint?.repairHead ||
+                JSON.stringify(document) !== JSON.stringify(existing))) {
             // A write failure affects durability, never hides the verified in-memory result.
             try {
                 await publish(additionsLedgerScope(scope), { ...document }, budget);
@@ -558,11 +702,10 @@ export function createDurableAdditions(options) {
                 if (proof &&
                     keccak256(new TextEncoder().encode(JSON.stringify(proof.envelope))) !== head.dataHash)
                     return;
-                const previous = await readDocument(version.scope, budget);
-                const boundary = snapshot.versions
-                    .filter((slot) => slot.isTombstone && settled(slot))
-                    .at(-1)?.expectedVersion ?? "0";
-                const startsFresh = BigInt(head.expectedVersion) === BigInt(boundary) + 1n;
+                const previous = (await readDocument(version.scope, budget, snapshot))
+                    ?.document;
+                const { after } = sourceWindow(snapshot);
+                const startsFresh = BigInt(head.expectedVersion) === after + 1n;
                 if (!startsFresh &&
                     (!previous ||
                         BigInt(previous.through) + 1n !== BigInt(head.expectedVersion)))
@@ -576,9 +719,15 @@ export function createDurableAdditions(options) {
                 /* Next reader retries. */
             }
         },
-        async deleteScope(scope) {
+        async deleteScope(scope, deletion) {
+            deletion?.signal?.throwIfAborted();
+            options.signal?.throwIfAborted();
             if (isSystemScope(scope))
                 return;
+            // Lite owns a separate bounded registry/journal deleter. This core host
+            // only has ordinary cleanup and must not silently use it for durableOnly.
+            if (deletion?.durableOnly)
+                throw new Error("Bounded additions deletion is unavailable");
             if (!options.deleteSystemScope)
                 throw new Error("Durable additions deletion is unavailable");
             await options.deleteSystemScope(additionsLedgerScope(scope));