run402 4.64.0 → 4.66.0

package/sdk/dist/node/gitvault-publication.js

@@ -634,6 +634,35 @@ export function gitvaultLedgerId(read) {
         return pinManifestLedgerId(read.pin_manifest_version);
     return String(read.object_id);
 }
+/**
+ * `scheme://host` for a URL string, or `null` for anything that fails to
+ * parse (never thrown) — the sole normalizer between a full presigned/edge
+ * URL (path, query, signature, everything) and the bare origin
+ * {@link GitvaultHttpTransportOptions.onObjectStoreOriginObserved} hands a
+ * caller. Deliberately NOT exported: this module is the only place that
+ * observes raw object-store URLs, so the normalizer has exactly one call
+ * site and needs no wider audience.
+ */
+function gitvaultObjectStoreOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/** Dedup, in order, dropping anything that failed to parse. */
+function gitvaultObjectStoreOrigins(urls) {
+    const out = [];
+    for (const u of urls) {
+        if (!u)
+            continue;
+        const origin = gitvaultObjectStoreOrigin(u);
+        if (origin && !out.includes(origin))
+            out.push(origin);
+    }
+    return out;
+}
 function b64(bytes) { return Buffer.from(bytes).toString("base64"); }
 function b64u(bytes) { return Buffer.from(bytes).toString("base64url"); }
 /**
@@ -706,8 +735,45 @@ export function createGitvaultHttpTransport(client, options = {}) {
         }
         return new Uint8Array(await r.arrayBuffer());
     }
+    /**
+     * Resolve ONE `object-reads` presign target to bytes (gitvault-small-
+     * object-inline design D3): consume `inline` when present and EITHER no
+     * `expectedSha256` was supplied OR the decoded bytes hash to it, else
+     * fall through to the ordinary `url`/`edge_url` fetch exactly as before
+     * this change. A lying `inline` is therefore a PLAIN MISS for this one
+     * slot — the fetch below reproduces the URL-only result and failure
+     * envelope byte-for-byte, never a special error. A caller that supplies
+     * no expectation cannot detect a lying `inline` at all, but that is no
+     * new exposure: `inline` is the SAME stored bytes, to the SAME
+     * authorized caller, the entry's own `url` would have served — nothing
+     * here becomes a new source of truth (design D5).
+     *
+     * gitvault-object-host-predial (task 1.2): once the fetch below
+     * COMPLETES (any status — a thrown fetch error is NOT this), reports the
+     * target's origin(s) via `options.onObjectStoreOriginObserved`. Never
+     * fired for the `inline` short-circuit above — no URL was dialed.
+     */
+    async function resolveObjectReadTarget(repoId, target, expectedSha256, path) {
+        if (target.inline !== undefined) {
+            const bytes = fromBase64url(target.inline, "reads[].inline");
+            if (expectedSha256 === undefined || sha256Hex(bytes) === expectedSha256)
+                return bytes;
+        }
+        const r = await fetchGitvaultObjectBytes(client, target);
+        try {
+            options.onObjectStoreOriginObserved?.(repoId, gitvaultObjectStoreOrigins([target.url, target.edge_url]));
+        }
+        catch {
+            /* a caller's own persistence failure must never surface into this read */
+        }
+        if (r.status === 404)
+            return null;
+        if (!r.ok)
+            fail("GITVAULT_OBJECT_READ_FAILED", `object GET failed (HTTP ${r.status}) for ${path}`, "reading gitvault object", { path, status: r.status });
+        return new Uint8Array(await r.arrayBuffer());
+    }
     /** Presign + fetch one object by its ledger identity (`POST …/object-reads`). */
-    async function getObjectBytes(repoId, path) {
+    async function getObjectBytes(repoId, path, expectedSha256) {
         const ref = gitvaultWireRefForPath(path);
         if (!ref)
             fail("GITVAULT_OBJECT_READ_FAILED", `${path} has no control-plane wire identity; it is not a readable vault object`, "reading gitvault object", { path });
@@ -742,12 +808,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
         const target = presigned.reads[0];
         if (!target)
             return null;
-        const r = await fetchGitvaultObjectBytes(client, target);
-        if (r.status === 404)
-            return null;
-        if (!r.ok)
-            fail("GITVAULT_OBJECT_READ_FAILED", `object GET failed (HTTP ${r.status}) for ${path}`, "reading gitvault object", { path, status: r.status });
-        return new Uint8Array(await r.arrayBuffer());
+        return resolveObjectReadTarget(repoId, target, expectedSha256, path);
     }
     /**
      * Presign + fetch N independent objects (gitvault-client-round-trips
@@ -759,7 +820,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
      * restore's carrier and pack reads, so it fails closed rather than
      * silently costing an extra round trip through `getGenerationBytes`.
      */
-    async function getObjectsBytes(repoId, paths) {
+    async function getObjectsBytes(repoId, paths, expected) {
         if (paths.length === 0)
             return [];
         const targets = await presignObjectBatch(repoId, paths);
@@ -768,12 +829,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
         return mapBounded(targets, GITVAULT_TRANSPORT_CONCURRENCY, async (target, i) => {
             if (!target)
                 return null;
-            const r = await fetchGitvaultObjectBytes(client, target);
-            if (r.status === 404)
-                return null;
-            if (!r.ok)
-                fail("GITVAULT_OBJECT_READ_FAILED", `object GET failed (HTTP ${r.status}) for ${paths[i]}`, "reading gitvault object", { path: paths[i], status: r.status });
-            return new Uint8Array(await r.arrayBuffer());
+            return resolveObjectReadTarget(repoId, target, expected?.[i], paths[i]);
         });
     }
     /** The shared presign step of the batched read: ONE `object-reads` POST; `null` means the not-found shapes `getObjects` maps to an all-absent result. */
@@ -803,10 +859,12 @@ export function createGitvaultHttpTransport(client, options = {}) {
      * D2): identical presign + bounded GETs, but each index's promise settles
      * when ITS bytes land. Failure semantics per index match `getObjects`'s
      * per-element behavior (absent → null, a failed GET → the same
-     * GITVAULT_OBJECT_READ_FAILED); every promise is pre-marked handled so an
-     * abandoned tail never becomes an unhandled rejection.
+     * GITVAULT_OBJECT_READ_FAILED), including `expected` (gitvault-small-
+     * object-inline design D3 — see {@link GitvaultTransport.getObjects}'s
+     * doc comment); every promise is pre-marked handled so an abandoned tail
+     * never becomes an unhandled rejection.
      */
-    async function getObjectsSettledBytes(repoId, paths) {
+    async function getObjectsSettledBytes(repoId, paths, expected) {
         if (paths.length === 0)
             return [];
         const targets = await presignObjectBatch(repoId, paths);
@@ -835,14 +893,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
                         deferreds[i].resolve(null);
                         continue;
                     }
-                    const r = await fetchGitvaultObjectBytes(client, target);
-                    if (r.status === 404) {
-                        deferreds[i].resolve(null);
-                        continue;
-                    }
-                    if (!r.ok)
-                        fail("GITVAULT_OBJECT_READ_FAILED", `object GET failed (HTTP ${r.status}) for ${paths[i]}`, "reading gitvault object", { path: paths[i], status: r.status });
-                    deferreds[i].resolve(new Uint8Array(await r.arrayBuffer()));
+                    deferreds[i].resolve(await resolveObjectReadTarget(repoId, target, expected?.[i], paths[i]));
                 }
                 catch (e) {
                     deferreds[i].reject(e);
@@ -908,11 +959,17 @@ export function createGitvaultHttpTransport(client, options = {}) {
             return null;
         }
     }
-    /** Resolve ONE `GET …/state` carrier arm to raw bytes — inline decode, or a plain GET on the presigned URL (preferring its `edge_url` companion, gitvault-read-edge-cache design D5), `null` on a 404 (mirrors {@link getObjectBytes}'s absent reading; both arms indistinguishable after this). */
-    async function resolveVaultStateCarrier(carrier) {
+    /** Resolve ONE `GET …/state` carrier arm to raw bytes — inline decode, or a plain GET on the presigned URL (preferring its `edge_url` companion, gitvault-read-edge-cache design D5), `null` on a 404 (mirrors {@link getObjectBytes}'s absent reading; both arms indistinguishable after this). Origin observation (gitvault-object-host-predial task 1.2) mirrors `resolveObjectReadTarget`'s. */
+    async function resolveVaultStateCarrier(repoId, carrier) {
         if ("inline" in carrier)
             return fromBase64url(carrier.inline, "carriers.inline");
         const r = await fetchGitvaultObjectBytes(client, { url: carrier.presigned_url, edge_url: carrier.edge_url });
+        try {
+            options.onObjectStoreOriginObserved?.(repoId, gitvaultObjectStoreOrigins([carrier.presigned_url, carrier.edge_url]));
+        }
+        catch {
+            /* a caller's own persistence failure must never surface into this read */
+        }
         if (r.status === 404)
             return null;
         if (!r.ok)
@@ -925,11 +982,16 @@ export function createGitvaultHttpTransport(client, options = {}) {
      * resolved to raw bytes here, verified nowhere here (see the interface's
      * own doc comment on {@link GitvaultTransport.getState}).
      */
-    async function getVaultStateOut(repoId, since) {
-        const raw = await client.request(`${base(repoId)}/state${since ? `?since=${encodeURIComponent(since)}` : ""}`, { context: "reading the gitvault vault state" });
+    async function getVaultStateOut(repoId, since, restore) {
+        const qs = [];
+        if (since)
+            qs.push(`since=${encodeURIComponent(since)}`);
+        if (restore)
+            qs.push("restore=1");
+        const raw = await client.request(`${base(repoId)}/state${qs.length > 0 ? `?${qs.join("&")}` : ""}`, { context: "reading the gitvault vault state" });
         const head = raw.head ? { stored_bytes: fromBase64url(raw.head.stored_bytes, "head.stored_bytes"), stored_bytes_sha256: raw.head.stored_bytes_sha256 } : null;
         const carriers = raw.carriers
-            ? { ref_state: await resolveVaultStateCarrier(raw.carriers.ref_state), retention_roots: await resolveVaultStateCarrier(raw.carriers.retention_roots) }
+            ? { ref_state: await resolveVaultStateCarrier(repoId, raw.carriers.ref_state), retention_roots: await resolveVaultStateCarrier(repoId, raw.carriers.retention_roots) }
             : null;
         // Delta decode is deliberately forgiving: a malformed entry is dropped,
         // never thrown — the delta is an accelerator and the ordinary reads own
@@ -949,7 +1011,63 @@ export function createGitvaultHttpTransport(client, options = {}) {
                 delta = null;
             }
         }
-        return { vault: raw.vault, newest_generation: raw.newest_generation, head, carriers, ...(delta ? { delta } : {}) };
+        // Restore-plan decode (gitvault-restore-recipe design D1-D5): the SAME
+        // forgiving posture as `delta` above — ANY structural or resolution
+        // anomaly drops the whole plan, never throws, so a hiccup fetching one
+        // above-cap pack never fails the state read itself (head/carriers/delta
+        // already succeeded by the time this runs). Heads and checkpoint bytes
+        // are a pure base64url decode (the gateway sends them inline ALWAYS —
+        // design D4, no network here); packs reuse `resolveObjectReadTarget`
+        // verbatim (db8d745c) — the SAME self-consistency-gated inline decode
+        // with url/edge_url fallback every `object-reads` consumer gets — under
+        // bounded concurrency, so an all-inline plan costs this call NOTHING
+        // beyond the one `GET …/state` already in flight, and an above-cap plan
+        // pays exactly one GET per uncapped pack (the presign already happened
+        // server-side assembling the plan; no client-side `object-reads` POST).
+        // Decoding is its own function (never throwing `Error` — the public-SDK
+        // plain-`Error` contract — `null`/early-return is the disqualification
+        // signal instead) wrapped in one try/catch for the genuine exceptions
+        // `fromBase64url`/`resolveObjectReadTarget` can still raise.
+        const decodeRestorePlan = async () => {
+            if (!raw.restore_plan || !Array.isArray(raw.restore_plan.heads) || !Array.isArray(raw.restore_plan.packs))
+                return null;
+            try {
+                const rp = raw.restore_plan;
+                const heads = rp.heads
+                    .filter((h) => typeof h?.generation === "string" && typeof h.stored_bytes === "string" && typeof h.stored_bytes_sha256 === "string")
+                    .map((h) => ({ generation: h.generation, stored_bytes: fromBase64url(h.stored_bytes, "restore_plan.heads[].stored_bytes"), stored_bytes_sha256: h.stored_bytes_sha256 }));
+                if (heads.length !== rp.heads.length)
+                    return null; // a malformed head entry disqualifies the whole plan
+                const checkpoint = rp.checkpoint
+                    ? {
+                        claim_set: { object_id: rp.checkpoint.claim_set.object_id, stored_bytes: fromBase64url(rp.checkpoint.claim_set.stored_bytes, "restore_plan.checkpoint.claim_set.stored_bytes") },
+                        manifest: { object_id: rp.checkpoint.manifest.object_id, stored_bytes: fromBase64url(rp.checkpoint.manifest.stored_bytes, "restore_plan.checkpoint.manifest.stored_bytes") },
+                    }
+                    : null;
+                const packEntries = rp.packs.filter((pk) => typeof pk?.object_kind === "string" && typeof pk.object_id === "string");
+                if (packEntries.length !== rp.packs.length)
+                    return null; // a malformed pack entry disqualifies the whole plan
+                const resolved = await mapBounded(packEntries, GITVAULT_TRANSPORT_CONCURRENCY, async (pk) => {
+                    const target = { object_kind: pk.object_kind, object_id: pk.object_id, url: pk.url ?? "", edge_url: pk.edge_url, inline: pk.inline, stored_bytes_sha256: pk.stored_bytes_sha256 ?? "", size_bytes: pk.size_bytes ?? "0", expires_at: pk.expires_at ?? "" };
+                    // Self-consistency only (the same gate `inline` gets everywhere
+                    // else) — real verification against the head/manifest's OWN
+                    // receipt happens later, in `GitvaultVault`, before any byte is
+                    // trusted. A pack the gateway declined to presign (`url` absent,
+                    // `inline` absent) is `null` here and falls back to the ordinary
+                    // object-reads fetch by (object_kind, object_id) in the caller.
+                    if (!target.url && target.inline === undefined)
+                        return null;
+                    return resolveObjectReadTarget(repoId, target, pk.stored_bytes_sha256, `restore_plan:${pk.object_kind}:${pk.object_id}`);
+                });
+                const packs = packEntries.map((pk, i) => ({ object_kind: pk.object_kind, object_id: pk.object_id, bytes: resolved[i] ?? null }));
+                return { boundary_generation: rp.boundary_generation, heads, checkpoint, packs };
+            }
+            catch {
+                return null;
+            }
+        };
+        const restorePlan = await decodeRestorePlan();
+        return { vault: raw.vault, newest_generation: raw.newest_generation, head, carriers, ...(delta ? { delta } : {}), ...(restorePlan ? { restore_plan: restorePlan } : {}) };
     }
     /** Pair a `finalize`-shaped response's receipts back onto `objects` by ledger id — shared by the inline and presigned upload paths so neither forks the other's receipt-compare logic. */
     function receiptsFromFinalize(objects, entries, fin) {
@@ -1100,9 +1218,9 @@ export function createGitvaultHttpTransport(client, options = {}) {
             const [r] = await upload(request.repo_id, [{ path: request.path, object_kind: "key_envelope", object_id: null, bytes: request.bytes, sha256: request.expected_sha256, size_bytes: request.expected_size_bytes }], undefined, request.byo);
             return { stored_bytes_sha256: r.sha256, size_bytes: r.size_bytes };
         },
-        getObject: ({ repo_id, path }) => getObjectBytes(repo_id, path),
-        getObjects: ({ repo_id, paths }) => getObjectsBytes(repo_id, paths),
-        getObjectsSettled: ({ repo_id, paths }) => getObjectsSettledBytes(repo_id, paths),
+        getObject: ({ repo_id, path, expected_sha256 }) => getObjectBytes(repo_id, path, expected_sha256),
+        getObjects: ({ repo_id, paths, expected }) => getObjectsBytes(repo_id, paths, expected),
+        getObjectsSettled: ({ repo_id, paths, expected }) => getObjectsSettledBytes(repo_id, paths, expected),
         getHeads: ({ repo_id, generations }) => getHeadsBytes(repo_id, generations),
         async admitGenesis(request) {
             try {
@@ -1151,7 +1269,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
             return { cleared: r.advisory_cleared ?? r.cleared ?? false };
         },
         getVaultRecord: ({ repo_id }) => client.request(base(repo_id), { context: "reading the gitvault record" }),
-        getState: ({ repo_id, since }) => getVaultStateOut(repo_id, since),
+        getState: ({ repo_id, since, restore }) => getVaultStateOut(repo_id, since, restore),
         openCompactionGrant: ({ repo_id }) => client.request(`${base(repo_id)}/compaction-grant`, { method: "POST", context: "opening the gitvault compaction headroom grant" }),
         closeCompactionGrant: async ({ repo_id }) => {
             const r = await client.request(`${base(repo_id)}/compaction-grant`, { method: "DELETE", context: "closing the gitvault compaction headroom grant" });
@@ -1461,6 +1579,18 @@ export class GitvaultVault {
      * consumed and cleared by the next restore).
      */
     stateDeltaPacks = null;
+    /**
+     * The state read's restore plan (gitvault-restore-recipe design D1-D5),
+     * stashed RAW — never verified at stash time, unlike `stateDeltaPacks`
+     * (whose heads self-check before entering the shared keystore cache): a
+     * plan's heads/checkpoint/packs are only ever verified by {@link
+     * restoreObjectsInto}'s own full obligation set, and a partially-checked
+     * plan sitting here would be a foot-gun for a future caller that forgot
+     * the difference. Consumed and cleared exactly once, by the next
+     * `restoreObjectsInto` call (either its own materialize, or a dedicated
+     * plan-only read it issues when the incremental walk it started aborts).
+     */
+    stateRestorePlan = null;
     retries;
     servicePublicKey;
     genesisCache = null;
@@ -1649,7 +1779,7 @@ export class GitvaultVault {
      * comment). A wrong or absent byte this method wrote is therefore just a
      * cache MISS on the next read, never a verification bypass.
      */
-    async tryStateFastPath(pin, deltaSince) {
+    async tryStateFastPath(pin, deltaSince, restore) {
         // gitvault-delta-fetch: carry the caller's MATERIALIZED position as
         // `since` — a capable gateway answers small spans with the heads +
         // inline WAL packs in this same response; every other gateway/span
@@ -1659,7 +1789,15 @@ export class GitvaultVault {
         // keystore, so pin-as-since would report "current" for a standing clone
         // that is generations behind — exactly the multi-checkout shape the
         // bench runs.
-        const state = await this.transport.getState({ repo_id: this.repoId, since: deltaSince ?? pin.generation });
+        //
+        // `restore` (gitvault-restore-recipe design D2/D6) rides the SAME state
+        // read — never a second round trip — so the caller (`restoreObjectsInto`,
+        // via `materialize`/`verifyToNewest`) declares it only on the wholesale
+        // shape (see that method's own doc comment). This call declining the
+        // shortcut entirely (more than one generation behind `pin`) also means
+        // no plan is ever requested on this attempt — the listing-walk path that
+        // owns catch-up already has its own batched primitives.
+        const state = await this.transport.getState({ repo_id: this.repoId, since: deltaSince ?? pin.generation, restore });
         // §6.4: the vault's newest generation may never fall below the
         // authenticated pin — checked here regardless of eligibility below, so
         // a regressed vault is caught exactly as loudly as it always was, even
@@ -1679,6 +1817,13 @@ export class GitvaultVault {
         // is actually genesis's bytes.
         if (state.delta)
             this.consumeStateDelta(state.delta);
+        // gitvault-restore-recipe: stashed RAW (never verified here — see the
+        // field's own doc comment); a genesis-only response (below) still runs
+        // this line first, but `assembleVaultRestorePlan` never fires server-side
+        // before an ordinary head exists, so `state.restore_plan` is simply
+        // absent in that window — nothing to stash either way.
+        if (state.restore_plan)
+            this.stateRestorePlan = state.restore_plan;
         const noOrdinaryHeadYet = state.newest_generation === null || state.newest_generation === GITVAULT_GENESIS_GENERATION;
         const pinBig = generationToBigInt(pin.generation);
         const newestBig = noOrdinaryHeadYet ? 0n : generationToBigInt(state.newest_generation);
@@ -1811,7 +1956,10 @@ export class GitvaultVault {
         // own epoch could not be resolved without the network read this path
         // exists to avoid) — the caller falls straight through to the UNCHANGED
         // readHead + listHeads flow below, byte-identical to before this change.
-        const fastPath = await this.tryStateFastPath(pin, options.deltaSince);
+        // `options.restore` (gitvault-restore-recipe) rides along unchanged —
+        // declined exactly when the fast path itself is declined, so a caller
+        // more than one generation behind never gets (or needs) a plan here.
+        const fastPath = await this.tryStateFastPath(pin, options.deltaSince, options.restore);
         let lastHead = fastPath ? fastPath.pinnedHead : pin.generation === GITVAULT_GENESIS_GENERATION ? null : await this.readHead(pin.generation, pin.head_sha256);
         const anchor = pin.generation;
         let prevEpoch = fastPath ? fastPath.prevEpoch : (lastHead?.epoch ?? GITVAULT_GENESIS_EPOCH);
@@ -1989,7 +2137,7 @@ export class GitvaultVault {
                             }
                         }
                         if (carriers.length > 1) {
-                            const fetched = await this.transport.getObjects({ repo_id: this.repoId, paths: carriers.map((c) => c.path) });
+                            const fetched = await this.transport.getObjects({ repo_id: this.repoId, paths: carriers.map((c) => c.path), expected: carriers.map((c) => c.sha) });
                             for (let i = 0; i < carriers.length; i++) {
                                 const bytes = fetched[i] ?? null;
                                 if (bytes && sha256Hex(bytes) === carriers[i].sha)
@@ -2255,7 +2403,7 @@ export class GitvaultVault {
         const cacheable = kind === "ref_state" || kind === "retention_roots";
         const cached = cacheable ? this.keystore.readCachedCarrier(this.repoId, receipt.object_id) : null;
         const cacheHit = cached && sha256Hex(cached.bytes) === receipt.ciphertext_sha256;
-        const frame = cacheHit ? cached.bytes : await this.transport.getObject({ repo_id: this.repoId, path });
+        const frame = cacheHit ? cached.bytes : await this.transport.getObject({ repo_id: this.repoId, path, expected_sha256: receipt.ciphertext_sha256 });
         const object = this.decodeCarrierFrame(kind, receipt, frame, writerKey, keyOverride);
         if (cacheable && !cacheHit && frame && typeof object.generation === "string") {
             this.keystore.writeCachedCarrier(this.repoId, receipt.object_id, object.generation, receipt.ciphertext_sha256, frame);
@@ -2285,11 +2433,16 @@ export class GitvaultVault {
         const preRoots = !rootsHit ? (this.walkPrefetch?.get(rootsPath) ?? null) : null;
         const rootsPre = preRoots && sha256Hex(preRoots) === rootsReceipt.ciphertext_sha256 ? preRoots : null;
         const missingPaths = [];
-        if (!refStateHit && !refStatePre)
+        const missingExpected = [];
+        if (!refStateHit && !refStatePre) {
             missingPaths.push(refStatePath);
-        if (!rootsHit && !rootsPre)
+            missingExpected.push(refStateReceipt.ciphertext_sha256);
+        }
+        if (!rootsHit && !rootsPre) {
             missingPaths.push(rootsPath);
-        const fetched = missingPaths.length > 0 ? await this.transport.getObjects({ repo_id: this.repoId, paths: missingPaths }) : [];
+            missingExpected.push(rootsReceipt.ciphertext_sha256);
+        }
+        const fetched = missingPaths.length > 0 ? await this.transport.getObjects({ repo_id: this.repoId, paths: missingPaths, expected: missingExpected }) : [];
         let next = 0;
         const refStateFrame = refStateHit ? cachedRefState.bytes : (refStatePre ?? fetched[next++] ?? null);
         const rootsFrame = rootsHit ? cachedRoots.bytes : (rootsPre ?? fetched[next++] ?? null);
@@ -2319,7 +2472,7 @@ export class GitvaultVault {
      */
     async materialize(options = {}) {
         const persist = options.persist ?? true;
-        const state = await this.verifyToNewest({ persist, decryptValidate: true, strict: true, deltaSince: options.deltaSince });
+        const state = await this.verifyToNewest({ persist, decryptValidate: true, strict: true, deltaSince: options.deltaSince, restore: options.restore });
         if (!state.head) {
             if (persist)
                 this.keystore.updateRepo(this.repoId, { materialized_pin: { generation: state.generation, head_sha256: state.head_sha256, pinned_at: formatGitvaultTimestamp(this.now()) } });
@@ -2720,7 +2873,7 @@ export class GitvaultVault {
             fail("CHECKPOINT_INCOMPLETE", `head ${head.generation} carries no checkpoint to verify`, "verifying a stored checkpoint", { generation: head.generation });
         const { genesis } = await this.genesis();
         const writerKey = genesis.creator_signing_pubkey;
-        const claimBytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.claimSet(block.claim_set.object_id) });
+        const claimBytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.claimSet(block.claim_set.object_id), expected_sha256: block.claim_set.stored_bytes_sha256 });
         if (!claimBytes || sha256Hex(claimBytes) !== block.claim_set.stored_bytes_sha256) {
             fail("CHECKPOINT_INCOMPLETE", `checkpoint claim set ${block.claim_set.object_id} is absent or does not match the head's receipt`, "verifying a stored checkpoint", { object_id: block.claim_set.object_id });
         }
@@ -2736,7 +2889,7 @@ export class GitvaultVault {
         try {
             await hardenedGit(scratch, ["init", "-q", "--bare", "--object-format=sha1", "."]);
             for (const p of manifest.packs) {
-                const frame = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.checkpointPack(p.object_id) });
+                const frame = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.checkpointPack(p.object_id), expected_sha256: p.ciphertext_sha256 });
                 if (!frame)
                     fail("CHECKPOINT_INCOMPLETE", `checkpoint pack ${p.object_id} is absent from storage`, "verifying a stored checkpoint", { object_id: p.object_id });
                 const plain = openFrame({ k_obj: deriveObjectKey(this.kRepo(), this.repoId, this.epoch(), "checkpoint_pack", p.object_id), repo_id: this.repoId, object_kind: "checkpoint_pack", object_id: p.object_id, epoch: this.epoch(), frame, expected_ciphertext_sha256: p.ciphertext_sha256 });
@@ -2800,7 +2953,7 @@ export class GitvaultVault {
                 // Plaintext-structured and stored-bytes-receipted: no decryption, but
                 // the hash and the owner signature are still checked before a single
                 // pack receipt inside it is believed.
-                const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.claimSet(block.claim_set.object_id) });
+                const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.claimSet(block.claim_set.object_id), expected_sha256: block.claim_set.stored_bytes_sha256 });
                 if (!bytes || sha256Hex(bytes) !== block.claim_set.stored_bytes_sha256) {
                     fail("CHECKPOINT_INCOMPLETE", `checkpoint claim set ${block.claim_set.object_id} (generation ${gen}) is absent or altered`, "walking the gitvault chain", { generation: gen, object_id: block.claim_set.object_id });
                 }
@@ -3160,7 +3313,7 @@ export class GitvaultVault {
         if (known && known.pin_manifest_version === receipt.pin_manifest_version && known.stored_bytes_sha256 === receipt.stored_bytes_sha256) {
             return { pinManifestVersion: known.pin_manifest_version, pinManifestSha256: known.stored_bytes_sha256, pinnedFingerprintOf: new Map(known.pins.map((p) => [p.principal_id, p.ek_fingerprint])) };
         }
-        const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.pinManifest(receipt.pin_manifest_version) });
+        const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.pinManifest(receipt.pin_manifest_version), expected_sha256: receipt.stored_bytes_sha256 });
         if (!bytes || sha256Hex(bytes) !== receipt.stored_bytes_sha256) {
             fail("GITVAULT_RECEIPT_MISMATCH", `recipient_pin_manifest ${receipt.pin_manifest_version} is absent or does not match its receipted hash`, "resolving the effective recipient pin manifest", { pin_manifest_version: receipt.pin_manifest_version });
         }
@@ -3740,7 +3893,16 @@ export class GitvaultVault {
         // reuse therefore costs one extra read, never a wrong result.
         const marker = await readGitvaultRestoreMarker(targetRepoDir);
         const markerMatches = (a, b) => a === null ? b === null : b !== null && a.generation === b.generation && a.head_sha256 === b.head_sha256;
-        const newest = reuse && markerMatches(reuse.marker, marker) ? reuse.state : await this.materialize({ ...(marker ? { deltaSince: marker.generation } : {}) });
+        // gitvault-restore-recipe design D2/D6: a marker-absent materialize is,
+        // by construction, the wholesale shape (a fresh target has nothing to
+        // replay incrementally) — declare restore intent here so a capable
+        // gateway's plan rides THIS read rather than a second one. Mirrors the
+        // remote-helper session's own `list`-phase decision (`runList` in
+        // `cli/lib/remote-helper-session.mjs`); this branch only fires when
+        // `reuse` was absent or mismatched (no prior `list` in this session, or
+        // a direct SDK caller), so the PRIMARY clone path never pays for this —
+        // it rides the reused state instead.
+        const newest = reuse && markerMatches(reuse.marker, marker) ? reuse.state : await this.materialize({ ...(marker ? { deltaSince: marker.generation } : { restore: true }) });
         if (!newest.head) {
             const retained_refs = await reconcileRetainedTipRefs(targetRepoDir, { refs: {}, roots: [], head_target: newest.head_target });
             return { refs: {}, head_target: newest.head_target, generation: newest.generation, retained_refs };
@@ -3758,6 +3920,17 @@ export class GitvaultVault {
             const retained_refs = await reconcileRetainedTipRefs(targetRepoDir, { refs: newest.refs, roots: newest.roots, head_target: newest.head_target });
             return { refs: newest.refs, head_target: newest.head_target, generation: newest.generation, retained_refs };
         }
+        // gitvault-restore-recipe (design D1-D6): consume a plan that already
+        // rode this method's OWN materialize() (the `restore: true` request
+        // above, or the reused list-phase read) BEFORE paying for the backward
+        // walk below at all. `tryConsumeRestorePlan` verifies from scratch and
+        // returns `null` on absence or ANY failure — the walk below is the
+        // unconditional fallback, byte-identical to before this change.
+        {
+            const applied = await this.tryConsumeRestorePlan(targetRepoDir, newest, writerKey);
+            if (applied)
+                return applied;
+        }
         // Walk back from newest, trying for an INCREMENTAL boundary at the
         // marker (a pure local prev_sha256 comparison — no fetch needed to
         // CONFIRM the boundary itself); abandon incremental the moment a
@@ -3832,6 +4005,27 @@ export class GitvaultVault {
                 incremental = false;
                 heads.length = 0;
                 cur = newest.head;
+                // gitvault-restore-recipe (design D1/D2, task 2.1's named fallback
+                // shape): the marker WAS present when this method's own materialize()
+                // ran, so `restore` was never declared and no plan rode that read —
+                // fetch one now, dedicated, before falling through to the ordinary
+                // wholesale walk. Best-effort: an older gateway, a network fault, a
+                // disqualification, or a verification failure all just continue the
+                // loop exactly as before this change; nothing here can make the
+                // restore fail that would otherwise have succeeded.
+                if (!this.stateRestorePlan) {
+                    try {
+                        const resp = await this.transport.getState({ repo_id: this.repoId, restore: true });
+                        if (resp.restore_plan)
+                            this.stateRestorePlan = resp.restore_plan;
+                    }
+                    catch {
+                        // fall through to the wholesale walk
+                    }
+                }
+                const applied = await this.tryConsumeRestorePlan(targetRepoDir, newest, writerKey);
+                if (applied)
+                    return applied;
                 continue;
             }
             heads.unshift(cur);
@@ -3855,6 +4049,32 @@ export class GitvaultVault {
                 fail("CHAIN_BROKEN", `head ${prevGen} does not match the chain during restore`, "restoring gitvault objects");
             cur = parseGitvaultStrict(new TextDecoder().decode(bytes));
         }
+        return this.applyRestoreHeads(targetRepoDir, heads, incremental, newest, writerKey, null, null);
+    }
+    /**
+     * The shared restore tail (gitvault-restore-recipe): apply `heads`'
+     * checkpoint (if any) + WAL packs into `targetRepoDir`, verify §4.7
+     * coverage, reconcile retained refs, and advance the marker — IDENTICALLY
+     * whether `heads` came from {@link restoreObjectsInto}'s own backward walk
+     * or a verified restore plan ({@link tryConsumeRestorePlan}). `incremental`
+     * only affects the checkpoint-coverage LEARNING step (an incremental walk
+     * stops at the marker and learns nothing; a plan-derived call always
+     * passes `false` — a plan is the wholesale shape by construction).
+     *
+     * `precheckedCheckpoint`, when non-null, is a claim set + manifest the
+     * caller ALREADY verified (signature, cross-equality — {@link
+     * verifyRestorePlan}) — skips the network fetch + re-verify this method
+     * would otherwise run for `heads[0].checkpoint`. `planPacks`, when
+     * non-null, is a map of pack bytes the caller already has (untrusted —
+     * only used when its OWN hash matches the carrying head's/manifest's
+     * receipt, exactly `stateDeltaPacks`'s discipline), keyed
+     * `${object_kind}:${object_id}` so it covers BOTH WAL and checkpoint
+     * packs (`stateDeltaPacks` never carries checkpoint packs — a delta span
+     * never crosses a checkpoint boundary). Both are `null` on the ordinary
+     * walk path, in which case every line below is byte-identical to the
+     * pre-gitvault-restore-recipe shape.
+     */
+    async applyRestoreHeads(targetRepoDir, heads, incremental, newest, writerKey, precheckedCheckpoint, planPacks) {
         // gitvault-clone-scaling (P3): a WHOLESALE walk just stopped at the
         // newest checkpoint-bearing head, or proved there is none back to
         // genesis — that is first-hand checkpoint coverage, and recording it is
@@ -3880,22 +4100,24 @@ export class GitvaultVault {
         // map `materialize()` just resolved (throwing `GITVAULT_EPOCH_NOT_OPENABLE`
         // fail-closed if any needed epoch could not be opened), so every lookup
         // below is guaranteed present.
-        const kRepoForEpoch = (epoch) => {
-            const hex = newest.epoch_keys_hex[epoch];
-            if (!hex)
-                fail("GITVAULT_EPOCH_NOT_OPENABLE", `no locally known key for epoch ${epoch} while restoring objects`, "restoring gitvault objects", { epoch });
-            return hexToBytes(hex);
-        };
+        const kRepoForEpoch = (epoch) => this.epochKeyFor(newest, epoch);
         const first = heads[0];
         // gitvault-pipelined-restore: per-object settlement when the transport
         // offers it, the `getObjects` barrier otherwise — pipelining is a
         // wall-clock property, never a correctness dependency, so a transport
         // without the method reproduces today's serial-after-barrier behavior
         // exactly (each per-index promise settles when the whole batch does).
-        const settled = async (paths) => {
+        //
+        // `expected` (gitvault-small-object-inline design D3) is index-aligned
+        // with `paths` — every caller below already knows each object's
+        // receipted ciphertext hash BEFORE fetching it, so it rides along here
+        // to let an `object-reads`-backed transport verify (and, on a lying
+        // reply, discard) an `inline` bytes offer per slot. Not required: an
+        // omitted `expected` is byte-identical to before this change.
+        const settled = async (paths, expected) => {
             if (this.transport.getObjectsSettled)
-                return this.transport.getObjectsSettled({ repo_id: this.repoId, paths });
-            const all = this.transport.getObjects({ repo_id: this.repoId, paths });
+                return this.transport.getObjectsSettled({ repo_id: this.repoId, paths, expected });
+            const all = this.transport.getObjects({ repo_id: this.repoId, paths, expected });
             const perIndex = paths.map((_, i) => all.then((frames) => frames[i] ?? null));
             // Mark every derived promise handled — the consumer awaits them in
             // order and stops at the first failure, abandoning the tail.
@@ -3917,7 +4139,12 @@ export class GitvaultVault {
         // skip the network ENTIRELY — but only after hashing to their carrying
         // head's receipt (a lying delta is a plain miss; the ordinary fetch
         // below reproduces the unbatched behavior for that slot). The buffer is
-        // consumed exactly once.
+        // consumed exactly once. gitvault-restore-recipe extends the SAME
+        // short-circuit to `planPacks` (a verified plan's own pack bytes) —
+        // checked SECOND so a delta hit never gets shadowed by a plan hit for
+        // the same slot (the two never coexist in practice, per `getState`'s
+        // mutual-exclusivity between `since` and `restore` on one call, but
+        // checking order stays deterministic either way).
         const deltaPacks = this.stateDeltaPacks;
         this.stateDeltaPacks = null;
         const deltaCovered = new Map();
@@ -3928,31 +4155,62 @@ export class GitvaultVault {
                     deltaCovered.set(i, bytes);
             });
         }
+        if (planPacks) {
+            walEntries.forEach(({ w }, i) => {
+                if (deltaCovered.has(i))
+                    return;
+                const bytes = planPacks.get(`wal_pack:${w.object_id}`);
+                if (bytes && sha256Hex(bytes) === w.ciphertext_sha256)
+                    deltaCovered.set(i, bytes);
+            });
+        }
         const uncovered = walEntries.map((_, i) => i).filter((i) => !deltaCovered.has(i));
         const walFramesP = (async () => {
-            const fetched = uncovered.length > 0 ? await settled(uncovered.map((i) => gitvaultPaths.wal(walEntries[i].w.object_id))) : [];
+            const fetched = uncovered.length > 0 ? await settled(uncovered.map((i) => gitvaultPaths.wal(walEntries[i].w.object_id)), uncovered.map((i) => walEntries[i].w.ciphertext_sha256)) : [];
             return walEntries.map((_, i) => (deltaCovered.has(i) ? Promise.resolve(deltaCovered.get(i)) : fetched[uncovered.indexOf(i)]));
         })();
         void walFramesP.catch(() => { });
         if (first.checkpoint) {
-            const claimBytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.claimSet(first.checkpoint.claim_set.object_id) });
-            if (!claimBytes || sha256Hex(claimBytes) !== first.checkpoint.claim_set.stored_bytes_sha256)
-                fail("CHECKPOINT_INCOMPLETE", "claim set absent or altered", "restoring gitvault objects");
-            const claimSet = parseGitvaultStrict(new TextDecoder().decode(claimBytes));
-            if (!verifyGitvaultObject(claimSet, writerKey))
-                fail("CHECKPOINT_INCOMPLETE", "claim set signature fails", "restoring gitvault objects");
-            const manifest = await this.openCarrier("checkpoint_manifest", claimSet.manifest_receipt, gitvaultPaths.checkpointManifest(claimSet.manifest_receipt.object_id), writerKey, { epoch: first.epoch, k_repo: kRepoForEpoch(first.epoch) });
-            checkClaimSetEquality(claimSet, manifest, first.checkpoint.covers_through_generation);
+            let claimSet;
+            let manifest;
+            if (precheckedCheckpoint) {
+                // gitvault-restore-recipe: already fetched + verified (signature,
+                // cross-equality) by `verifyRestorePlan` against the plan's own
+                // inline bytes — no network read, no re-verify.
+                ({ claimSet, manifest } = precheckedCheckpoint);
+            }
+            else {
+                const claimBytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.claimSet(first.checkpoint.claim_set.object_id), expected_sha256: first.checkpoint.claim_set.stored_bytes_sha256 });
+                if (!claimBytes || sha256Hex(claimBytes) !== first.checkpoint.claim_set.stored_bytes_sha256)
+                    fail("CHECKPOINT_INCOMPLETE", "claim set absent or altered", "restoring gitvault objects");
+                claimSet = parseGitvaultStrict(new TextDecoder().decode(claimBytes));
+                if (!verifyGitvaultObject(claimSet, writerKey))
+                    fail("CHECKPOINT_INCOMPLETE", "claim set signature fails", "restoring gitvault objects");
+                manifest = await this.openCarrier("checkpoint_manifest", claimSet.manifest_receipt, gitvaultPaths.checkpointManifest(claimSet.manifest_receipt.object_id), writerKey, { epoch: first.epoch, k_repo: kRepoForEpoch(first.epoch) });
+                checkClaimSetEquality(claimSet, manifest, first.checkpoint.covers_through_generation);
+            }
             // Design D2 + gitvault-pipelined-restore D1: every checkpoint pack is
             // independent — one batched presign for all of them, applied via
             // index-pack strictly in manifest order, PIPELINED: apply(i) awaits
             // bytes(i), so decrypt/verify/index of an early pack overlaps the
             // later packs' downloads. Per-pack verification (AEAD open + plaintext
-            // hash) still completes before any byte reaches git.
-            const frames = await settled(manifest.packs.map((p) => gitvaultPaths.checkpointPack(p.object_id)));
+            // hash) still completes before any byte reaches git. gitvault-restore-
+            // recipe: a `planPacks` hit skips the fetch for that index entirely —
+            // the SAME short-circuit the WAL loop above runs, extended to the
+            // checkpoint class (never carried by `stateDeltaPacks`).
+            const checkpointCovered = new Map();
+            if (planPacks) {
+                manifest.packs.forEach((p, i) => {
+                    const bytes = planPacks.get(`checkpoint_pack:${p.object_id}`);
+                    if (bytes && sha256Hex(bytes) === p.ciphertext_sha256)
+                        checkpointCovered.set(i, bytes);
+                });
+            }
+            const uncoveredCk = manifest.packs.map((_, i) => i).filter((i) => !checkpointCovered.has(i));
+            const ckFrames = uncoveredCk.length > 0 ? await settled(uncoveredCk.map((i) => gitvaultPaths.checkpointPack(manifest.packs[i].object_id)), uncoveredCk.map((i) => manifest.packs[i].ciphertext_sha256)) : [];
             for (let i = 0; i < manifest.packs.length; i++) {
                 const p = manifest.packs[i];
-                const frame = (await frames[i]) ?? null;
+                const frame = checkpointCovered.has(i) ? checkpointCovered.get(i) : ((await ckFrames[uncoveredCk.indexOf(i)]) ?? null);
                 if (!frame)
                     fail("CHECKPOINT_INCOMPLETE", `checkpoint pack ${p.object_id} absent`, "restoring gitvault objects");
                 const plain = openFrame({ k_obj: deriveObjectKey(kRepoForEpoch(first.epoch), this.repoId, first.epoch, "checkpoint_pack", p.object_id), repo_id: this.repoId, object_kind: "checkpoint_pack", object_id: p.object_id, epoch: first.epoch, frame, expected_ciphertext_sha256: p.ciphertext_sha256 });
@@ -4000,6 +4258,152 @@ export class GitvaultVault {
         await writeGitvaultRestoreMarker(targetRepoDir, newest.generation, newest.head_sha256);
         return { refs: newest.refs, head_target: newest.head_target, generation: newest.generation, retained_refs };
     }
+    /**
+     * `newest.epoch_keys_hex[epoch]`, decoded — the D194 per-carrying-head key
+     * lookup shared by {@link applyRestoreHeads} and {@link verifyRestorePlan}.
+     * `newest.epoch_keys_hex` is the FULL map `materialize()` resolved
+     * (throwing `GITVAULT_EPOCH_NOT_OPENABLE` fail-closed if any needed epoch
+     * could not be opened), so every lookup through this helper is guaranteed
+     * present.
+     */
+    epochKeyFor(newest, epoch) {
+        const hex = newest.epoch_keys_hex[epoch];
+        if (!hex)
+            fail("GITVAULT_EPOCH_NOT_OPENABLE", `no locally known key for epoch ${epoch} while restoring objects`, "restoring gitvault objects", { epoch });
+        return hexToBytes(hex);
+    }
+    /**
+     * Verify a restore plan's heads (self-consistency + backward chain-link +
+     * cross-check against the caller's own already-verified `newest`, plus
+     * genesis/boundary linkage) and, when the boundary carries a checkpoint,
+     * its claim set + manifest (signature, cross-equality) — the SAME
+     * obligations {@link applyRestoreHeads}'s ordinary path runs, against
+     * plan-supplied bytes instead of network-fetched ones (design D5: "the
+     * plan is transport, never trust"). Returns `null` on ANY failure — a
+     * self-inconsistent head, a broken link, a wrong newest, a bad signature,
+     * a cross-equality mismatch, anything the reused `decodeCarrierFrame`/
+     * `checkClaimSetEquality` reject — rather than throwing, so the caller's
+     * fallback to the ordinary walk is unconditional and silent, mirroring
+     * `assembleVaultStateDelta`'s own disqualification posture server-side.
+     *
+     * Heads that verify their OWN chain link (Stage A) are cache-warmed into
+     * {@link walkPrefetch} BEFORE Stage B (the checkpoint) runs, so a
+     * checkpoint failure still leaves the fallback walk with every head this
+     * call already proved — the D3 cache-hit discipline, extended to a failed
+     * plan.
+     */
+    async verifyRestorePlan(plan, newest, writerKey) {
+        // Every disqualification below is a plain `return null` — never `throw
+        // new Error(...)` (the public-SDK plain-`Error` contract) — so a manual
+        // `for` loop replaces `plan.heads.map(...)`: a `.map()` callback can only
+        // fail its OWN element, never abort the whole computation, and this
+        // function's contract is "any bad element disqualifies the WHOLE plan."
+        // The try/catch below still stands, to catch the genuine exceptions
+        // `parseGitvaultStrict`/`decodeCarrierFrame`/`checkClaimSetEquality`/
+        // `verifyGitvaultObject` can raise (a `fail()`-thrown `Run402Error`, or a
+        // strict-parse rejection) — those are real errors, just ones this method
+        // treats as "the plan didn't verify" rather than propagating.
+        try {
+            if (plan.heads.length === 0)
+                return null;
+            const parsed = [];
+            for (const h of plan.heads) {
+                if (sha256Hex(h.stored_bytes) !== h.stored_bytes_sha256)
+                    return null; // self-hash mismatch
+                const head = parseGitvaultStrict(new TextDecoder().decode(h.stored_bytes));
+                if (head.generation !== h.generation)
+                    return null; // generation mismatch
+                parsed.push({ generation: h.generation, bytes: h.stored_bytes, head });
+            }
+            for (let i = 1; i < parsed.length; i++) {
+                if (generationToBigInt(parsed[i].generation) !== generationToBigInt(parsed[i - 1].generation) + 1n)
+                    return null; // span not contiguous
+            }
+            const last = parsed[parsed.length - 1];
+            if (last.generation !== newest.generation || sha256Hex(last.bytes) !== newest.head_sha256)
+                return null; // does not match the caller's own verified newest
+            // Backward chain-link, newest to boundary — the SAME hash-equality
+            // check `applyRestoreHeads`'s own backward walk runs (no signature
+            // re-check here: the chain was already fully verified FORWARD by
+            // `materialize()`/`verifyToNewest()` before this ever runs — see that
+            // method's own doc comment on why its backward walk is a hash-only
+            // re-confirmation, not a re-verification).
+            for (let i = parsed.length - 1; i >= 1; i--) {
+                if (parsed[i].head.prev_sha256 !== sha256Hex(parsed[i - 1].bytes))
+                    return null; // chain link broken
+            }
+            const first = parsed[0];
+            if (plan.boundary_generation === GITVAULT_GENESIS_GENERATION) {
+                if (first.generation !== "0000000000000001")
+                    return null; // genesis boundary mismatch
+                const { sha256: genesisSha } = await this.genesis();
+                if (first.head.prev_sha256 !== genesisSha)
+                    return null; // generation 1 does not link to genesis
+            }
+            else {
+                if (first.generation !== plan.boundary_generation || !first.head.checkpoint)
+                    return null; // boundary does not carry a checkpoint
+            }
+            // Stage A verified — cache-warm every plan head regardless of Stage B's
+            // outcome below (D3: a failed plan still costs the fallback nothing it
+            // already proved).
+            if (!this.walkPrefetch)
+                this.walkPrefetch = new Map();
+            for (const p of parsed)
+                this.walkPrefetch.set(gitvaultPaths.head(p.generation), p.bytes);
+            let checkpoint = null;
+            if (first.head.checkpoint) {
+                if (!plan.checkpoint)
+                    return null; // boundary head carries a checkpoint but the plan carries none
+                const claimReceipt = first.head.checkpoint.claim_set;
+                if (plan.checkpoint.claim_set.object_id !== claimReceipt.object_id)
+                    return null; // claim set id mismatch
+                if (sha256Hex(plan.checkpoint.claim_set.stored_bytes) !== claimReceipt.stored_bytes_sha256)
+                    return null; // claim set hash mismatch
+                const claimSet = parseGitvaultStrict(new TextDecoder().decode(plan.checkpoint.claim_set.stored_bytes));
+                if (!verifyGitvaultObject(claimSet, writerKey))
+                    return null; // claim set signature fails
+                if (claimSet.manifest_receipt.object_id !== plan.checkpoint.manifest.object_id)
+                    return null; // manifest id mismatch
+                // Reuses `decodeCarrierFrame` verbatim — ciphertext hash, AEAD open,
+                // and identity/signature checks all run exactly as they would for a
+                // network-fetched manifest frame; the only difference is where the
+                // ciphertext bytes came from.
+                const manifest = this.decodeCarrierFrame("checkpoint_manifest", claimSet.manifest_receipt, plan.checkpoint.manifest.stored_bytes, writerKey, { epoch: first.head.epoch, k_repo: this.epochKeyFor(newest, first.head.epoch) });
+                checkClaimSetEquality(claimSet, manifest, first.head.checkpoint.covers_through_generation);
+                checkpoint = { claimSet, manifest };
+            }
+            return { heads: parsed.map((p) => p.head), checkpoint };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Consume a stashed restore plan (gitvault-restore-recipe design D1-D6):
+     * verify it ({@link verifyRestorePlan}) and, on success, apply it via the
+     * SAME shared tail the backward walk uses ({@link applyRestoreHeads}) —
+     * `null` on absence or ANY verification failure, the caller's cue to run
+     * (or continue) the ordinary walk. Clears `this.stateRestorePlan`
+     * unconditionally: a plan is single-use whether it verified or not (a
+     * failed plan's USABLE heads already rode into `walkPrefetch` inside
+     * `verifyRestorePlan` itself).
+     */
+    async tryConsumeRestorePlan(targetRepoDir, newest, writerKey) {
+        const plan = this.stateRestorePlan;
+        this.stateRestorePlan = null;
+        if (!plan)
+            return null;
+        const verified = await this.verifyRestorePlan(plan, newest, writerKey);
+        if (!verified)
+            return null;
+        const planPacks = new Map();
+        for (const p of plan.packs) {
+            if (p.bytes)
+                planPacks.set(`${p.object_kind}:${p.object_id}`, p.bytes);
+        }
+        return this.applyRestoreHeads(targetRepoDir, verified.heads, false, newest, writerKey, verified.checkpoint, planPacks);
+    }
     // ── compaction headroom grant (gitvault-checkpoint-cadence design D3) ──
     /** Thin passthrough to the transport — see {@link GitvaultTransport.openCompactionGrant}. */
     async openCompactionGrant() {