run402 4.63.1 → 4.65.0

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

@@ -38,6 +38,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { LocalError, isRun402Error } from "../errors.js";
 import { fetchGitvaultObjectBytes } from "./gitvault-edge-fetch.js";
+import { openGitvaultDestinationBackend } from "./gitvault-mirror-backend.js";
 import { GITVAULT_FORMAT, GITVAULT_GENESIS_EPOCH, GITVAULT_GENESIS_GENERATION, GITVAULT_HEX16_RE, GITVAULT_OID40_RE, GITVAULT_SUITE, attemptKeyCommitment, bytesToHex, checkFreshEpochKeyAgainstPriorKeys, checkHPartition, computeRotationId, computeTargetPartitionDigest, deriveDigestKey, deriveObjectKey, ekFingerprint, epochRotationKeyCommitment, formatGitvaultTimestamp, fromBase64url, hexToBytes, jcs, keyEnvelopeLedgerId, keyedCommitment, newGitvaultId, newHex32, nextEpoch, objectsetContent, openBindingPreimage, openEpochRotationForRecipient, openFrame, parseGitvaultStrict, parseRotateEpochPayload, pinManifestLedgerId, randomBytes, sealFrame, sealKeyEnvelope, sha256Hex, signGitvaultObject, storedBytes, storedBytesSha256, toBase64url, verifyGitvaultObject, } from "../namespaces/gitvault.crypto.js";
 import { GITVAULT_ZERO_SHA256_SENTINEL } from "../namespaces/gitvault.types.js";
 import { gitvaultCheckpointStaleness } from "../namespaces/gitvault.js";
@@ -633,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"); }
 /**
@@ -705,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 });
@@ -741,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
@@ -758,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);
@@ -767,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. */
@@ -802,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);
@@ -834,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);
@@ -907,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)
@@ -924,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
@@ -948,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) {
@@ -961,14 +1080,20 @@ export function createGitvaultHttpTransport(client, options = {}) {
             return { path: o.path, object_id: o.object_id, sha256: r.ciphertext_sha256 ?? r.stored_bytes_sha256 ?? "", size_bytes: r.size_bytes };
         });
     }
-    async function upload(repoId, objects, resourceBinding) {
+    async function upload(repoId, objects, resourceBinding, byo) {
         if (objects.length === 0)
             return [];
         // The manifest is closed-key: `path` is client-local and MUST NOT ride the
         // wire — the control plane derives the bucket key itself and refuses an
         // entry carrying an unexpected member.
         const entries = objects.map((o) => gitvaultManifestEntry(o));
-        if (gitvaultInlineUploadEligible(objects)) {
+        // gitvault-byo-primary-bucket task 3.2: the inline (bytes-in-body) fast
+        // path is NEVER used for a BYO vault, even when the payload is small
+        // enough to be eligible — that transport writes bytes into run402's own
+        // bucket, exactly what the credential model forbids (the gateway
+        // refuses it too, VALIDATION_FAILED, so skipping it here is purely a
+        // wasted-round-trip avoidance, not a correctness dependency).
+        if (!byo && gitvaultInlineUploadEligible(objects)) {
             // gitvault-composite-state-read design D2: every object fits under the
             // caps — one POST, bytes verified + written server-side, and the
             // response IS the finalize response (no session, no PUTs, no separate
@@ -987,6 +1112,14 @@ export function createGitvaultHttpTransport(client, options = {}) {
             context: "opening gitvault upload session",
         });
         const issued = new Map(session.objects.map((u) => [gitvaultLedgerId(u), u]));
+        // gitvault-byo-primary-bucket task 3.2 — one backend, opened ONCE, for
+        // every BYO payload object this session names; `null` `put` never
+        // appears in the session response unless `byo` was supplied (the
+        // gateway only mints `put: null` for a vault whose storage_profile is
+        // "byo", which is exactly when THIS caller must have supplied `byo`
+        // too — see the resolution in `GitvaultVault.uploadAll`).
+        const byoBackend = byo ? openGitvaultDestinationBackend(byo.destination, byo.credential) : null;
+        const byoAttestations = [];
         // Independent create-only PUTs within one session (design D2) — bounded
         // concurrency, same limit as the batched object reads below.
         await mapBounded(objects, GITVAULT_TRANSPORT_CONCURRENCY, async (o, i) => {
@@ -994,6 +1127,36 @@ export function createGitvaultHttpTransport(client, options = {}) {
             const target = issued.get(id);
             if (!target)
                 fail("GITVAULT_UPLOAD_SESSION_INVALID", `the session issued no upload for ${id}`, "uploading gitvault objects", { object_id: id, path: o.path });
+            if (target.put === null) {
+                // BYO payload object (task 2.2's GITVAULT_BYO_PAYLOAD_KINDS
+                // partition, mirrored client-side by the server's own `put: null` +
+                // `key` shape) — the client writes DIRECTLY to its own bucket. No
+                // request to run402 ever carries a customer-bucket credential; no
+                // request to run402 ever carries these bytes either.
+                if (!byoBackend || !target.key) {
+                    fail("GITVAULT_BYO_BUCKET_WRITE_REFUSED", `the session named ${o.path} as a BYO-written object but no BYO write target was resolved`, "uploading gitvault objects", { path: o.path, object_id: id });
+                }
+                let put;
+                try {
+                    put = await byoBackend.putCreateOnly(target.key, o.bytes);
+                }
+                catch (e) {
+                    fail("GITVAULT_BYO_BUCKET_WRITE_REFUSED", `writing ${o.path} to the BYO destination failed: ${e instanceof Error ? e.message : String(e)}`, "uploading gitvault objects", { path: o.path, key: target.key });
+                }
+                if (!put.created) {
+                    // create-only: the key already exists — legal ONLY if it is
+                    // byte-identical (an idempotent retry of THIS SAME write; a
+                    // permanent object id is never legitimately reused for
+                    // different bytes — matches the managed presigned-PUT read-and-
+                    // compare branch below, and the gateway's own attestation rule).
+                    const existing = await byoBackend.get(target.key);
+                    if (!existing || sha256Hex(existing) !== o.sha256) {
+                        fail("GITVAULT_BYO_BUCKET_WRITE_REFUSED", `${o.path} already exists in the BYO destination with different bytes`, "uploading gitvault objects", { path: o.path, key: target.key });
+                    }
+                }
+                byoAttestations.push({ key: target.key, sha256: o.sha256, size_bytes: o.size_bytes, create_only_result: "created" });
+                return;
+            }
             // `If-None-Match: *` (create-only) and the FULL_OBJECT `x-amz-checksum-sha256`
             // are SIGNED INTO the presigned URL, so they must go out exactly as the
             // server issued them — a dropped or altered header is a signature
@@ -1015,7 +1178,13 @@ export function createGitvaultHttpTransport(client, options = {}) {
             if (!r.ok)
                 fail("GITVAULT_UPLOAD_FAILED", `presigned PUT failed (HTTP ${r.status}) for ${o.path}`, "uploading gitvault objects", { path: o.path, status: r.status });
         });
-        const fin = await client.request(`${base(repoId)}/upload-sessions/${encodeURIComponent(session.upload_session_id)}/finalize`, { method: "POST", body: {}, context: "finalizing gitvault upload session" });
+        const fin = await client.request(`${base(repoId)}/upload-sessions/${encodeURIComponent(session.upload_session_id)}/finalize`, {
+            method: "POST",
+            // Only a BYO session ever carries attestations — an ordinary managed
+            // session's finalize body stays `{}`, byte-identical to today.
+            body: byo ? { attestations: byoAttestations } : {},
+            context: "finalizing gitvault upload session",
+        });
         return receiptsFromFinalize(objects, entries, fin);
     }
     async function admit(repoId, generation, bytes, hash, extra = {}) {
@@ -1046,12 +1215,12 @@ export function createGitvaultHttpTransport(client, options = {}) {
             return res.allocation ?? res;
         },
         async putObject(request) {
-            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 }]);
+            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 {
@@ -1075,7 +1244,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
                 qs.set("cursor", request.cursor);
             return client.request(`${base(request.repo_id)}/heads?${qs.toString()}`, { context: "listing gitvault heads" });
         },
-        uploadObjects: ({ repo_id, objects, resource_binding }) => upload(repo_id, objects, resource_binding),
+        uploadObjects: ({ repo_id, objects, resource_binding, byo }) => upload(repo_id, objects, resource_binding, byo),
         admitHead: (r) => admit(r.repo_id, r.generation, r.stored_bytes, r.stored_bytes_sha256),
         // Both routes SHIPPED (`routes/gitvault-admission.ts`). `retention-cutoffs`
         // answers `{ticket, receipt, next_actions}`, which IS
@@ -1100,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" });
@@ -1410,9 +1579,31 @@ 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;
+    /**
+     * gitvault-byo-primary-bucket task 3.2 — this vault's resolved BYO write
+     * target, cached after the first resolution (storage_profile/
+     * byo_destination are immutable-at-allocation in v1, so a single
+     * read-once-per-instance is safe). `undefined` = not yet resolved;
+     * `null` = this machine has no LOCAL BYO write config for this repo
+     * (either an ordinary managed vault, or a BYO vault this machine has not
+     * been configured to write — see {@link resolveByoWriteTarget}).
+     */
+    byoResolution = undefined;
     constructor(options) {
         this.keystore = options.keystore;
         this.transport = options.transport;
@@ -1588,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
@@ -1598,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
@@ -1618,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);
@@ -1750,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);
@@ -1928,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)
@@ -2194,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);
@@ -2224,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);
@@ -2258,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()) } });
@@ -2379,12 +2593,14 @@ export class GitvaultVault {
                 created_at: formatGitvaultTimestamp(this.now()),
             });
             try {
+                const byo = await this.resolveByoWriteTarget();
                 await this.transport.putObject({
                     repo_id: this.repoId,
                     path: gitvaultPaths.envelope(epoch, sealed.receipt.recipient_fingerprint),
                     bytes: sealed.stored_bytes,
                     expected_sha256: sealed.stored_bytes_sha256,
                     expected_size_bytes: sealed.size_bytes,
+                    ...(byo ? { byo } : {}),
                 });
                 wrapped.push({ principal_id: entry.principal_id, ek_fingerprint: entry.ek_fingerprint });
             }
@@ -2657,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 });
         }
@@ -2673,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 });
@@ -2737,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 });
                 }
@@ -2751,8 +2967,27 @@ export class GitvaultVault {
         return out;
     }
     // ── upload with receipt-compare ──
+    /**
+     * gitvault-byo-primary-bucket task 3.2 — resolve (once, cached) this
+     * machine's local BYO write config for THIS vault. `null` when none is
+     * configured locally — either because this is an ordinary managed vault
+     * (the common case; deliberately never confirmed with a network call, so
+     * a managed vault's push pays zero extra round trips), or because this
+     * machine has not been configured to write a BYO vault it nonetheless
+     * belongs to (surfaced downstream as `GITVAULT_BYO_BUCKET_WRITE_REFUSED`
+     * when the session actually names a `put: null` object with no target).
+     */
+    async resolveByoWriteTarget() {
+        if (this.byoResolution !== undefined)
+            return this.byoResolution;
+        const { readByoConfig } = await import("./gitvault-byo-config.js");
+        const local = readByoConfig(this.keystore, this.repoId);
+        this.byoResolution = local ? { destination: local.destination, ...(local.credential ? { credential: local.credential } : {}) } : null;
+        return this.byoResolution;
+    }
     async uploadAll(objects) {
-        const receipts = await this.transport.uploadObjects({ repo_id: this.repoId, objects });
+        const byo = await this.resolveByoWriteTarget();
+        const receipts = await this.transport.uploadObjects({ repo_id: this.repoId, objects, ...(byo ? { byo } : {}) });
         if (receipts.length !== objects.length)
             fail("GITVAULT_RECEIPT_MISMATCH", `${receipts.length} receipts for ${objects.length} objects`, "comparing finalization receipts");
         const mismatches = objects.filter((o, i) => receipts[i].path !== o.path || receipts[i].sha256 !== o.sha256 || receipts[i].size_bytes !== o.size_bytes);
@@ -3078,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 });
         }
@@ -3658,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 };
@@ -3676,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
@@ -3750,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);
@@ -3773,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
@@ -3798,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.
@@ -3835,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();
@@ -3846,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 });
@@ -3918,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() {