run402 4.46.0 → 4.48.0

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

@@ -37,7 +37,7 @@ import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { LocalError, isRun402Error } from "../errors.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, openFrame, openKeyEnvelope, parseGitvaultStrict, pinManifestLedgerId, randomBytes, sealFrame, sealKeyEnvelope, sha256Hex, signGitvaultObject, storedBytes, storedBytesSha256, toBase64url, verifyGitvaultObject, } from "../namespaces/gitvault.crypto.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, openKeyEnvelope, 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 { crossProfileGitvaultHint } from "./gitvault-profile-scan.js";
 import { GITVAULT_DEPLOY_REF, hardenedGit, hasObject, isAncestor } from "./gitvault-snapshot.js";
@@ -452,8 +452,18 @@ export function checkChainLink(input) {
         fail("CHAIN_BROKEN", `head generation ${h.generation} ≠ expected ${input.expected_generation} (generation must equal newest+1)`, "verifying head chain", { got: h.generation, expected: input.expected_generation });
     if (h.prev_sha256 !== input.prev_sha256)
         fail("CHAIN_BROKEN", `head ${h.generation}: prev_sha256 does not name the predecessor's stored bytes`, "verifying head chain", { prev_sha256: h.prev_sha256, expected: input.prev_sha256 });
-    if (h.epoch !== GITVAULT_GENESIS_EPOCH)
-        fail("CHAIN_BROKEN", `head ${h.generation}: epoch ${h.epoch} breaks the V0 pin`, "verifying head chain");
+    // D194, rev 42 (relaxed by D193): epoch continuity — a head's `epoch`
+    // equals its predecessor's UNLESS THIS head admits a `rotate_epoch`
+    // transition, in which case it equals `nextEpoch(predecessor.epoch)`
+    // exactly (increment-by-one, no skip). Pure and keyless: this checks only
+    // the head's own signed `epoch` FIELD against the predecessor's, never
+    // opens any envelope — decrypting under the resulting epoch is a separate,
+    // keyed step (`GitvaultVault`'s rotation-envelope open, `openEpochRotationForRecipient`).
+    const isRotation = h.transition !== null && h.transition.kind === "rotate_epoch";
+    const permittedEpoch = isRotation ? nextEpoch(input.prev_epoch) : input.prev_epoch;
+    if (h.epoch !== permittedEpoch) {
+        fail("CHAIN_BROKEN", `head ${h.generation}: epoch ${h.epoch} does not match the expected ${permittedEpoch} (${isRotation ? "post-rotation increment of the predecessor's epoch" : "predecessor continuity — only an admitted rotate_epoch transition may advance the epoch"})`, "verifying head chain", { generation: h.generation, got: h.epoch, expected: permittedEpoch, prev_epoch: input.prev_epoch, is_rotation: isRotation });
+    }
     if (h.writer_key_id !== input.writer_key_id)
         fail("CHAIN_BROKEN", `head ${h.generation}: writer_key_id ${h.writer_key_id} is not the registered writer`, "verifying head chain");
     if (!verifyGitvaultObject(h, input.writer_public_key))
@@ -469,12 +479,23 @@ export function checkChainLink(input) {
 }
 /**
  * The transition fail-closed rule: a V0 client that encounters an ADMITTED
- * non-null transition stops advancing — read-only at the materialized pin,
- * no publish past it, `UPGRADE_REQUIRED`. Unknown kinds are a parse reject.
+ * transition kind it cannot validate stops advancing — read-only at the
+ * materialized pin, no publish past it, `UPGRADE_REQUIRED`. Unknown kinds
+ * are a parse reject.
+ *
+ * `rotate_epoch` is EXEMPT from this rule as of rev 42 (D193: "epoch
+ * rotation is ACTIVATED") — `checkChainLink`'s own D194 epoch-continuity
+ * check already validates its structural admissibility, and
+ * {@link parseRotateEpochPayload} / the caller's own envelope-open step
+ * (`GitvaultVault.verifyToNewest`) handle it fully. The other three kinds
+ * (`add_envelope`, `add_writer_key`, `transfer_binding`) remain genuinely
+ * unactivated and stay fail-closed exactly as before.
  */
 export function assertNoTransition(head) {
     if (head.transition === null)
         return;
+    if (head.transition.kind === "rotate_epoch")
+        return;
     const kinds = ["add_envelope", "rotate_epoch", "add_writer_key", "transfer_binding"];
     if (!kinds.includes(head.transition.kind))
         fail("CHAIN_BROKEN", `head ${head.generation}: unknown transition kind ${String(head.transition.kind)} (closed enum)`, "verifying head chain");
@@ -538,6 +559,33 @@ export function gitvaultLedgerId(read) {
 }
 function b64(bytes) { return Buffer.from(bytes).toString("base64"); }
 function b64u(bytes) { return Buffer.from(bytes).toString("base64url"); }
+/**
+ * Independent reads/PUTs within one gitvault step run at this concurrency
+ * (design D2) — "browser-era origin etiquette", well within what S3/the
+ * gateway tolerate, and it keeps in-flight memory bounded by ~6×frame size.
+ * Chain-ordered steps (the head-chain walk, admission, readback) never call
+ * this — they stay strictly sequential.
+ */
+export const GITVAULT_TRANSPORT_CONCURRENCY = 6;
+/**
+ * Run `fn` over `items` with at most `limit` in flight at once, preserving
+ * result order regardless of completion order. A plain worker-pool: `limit`
+ * workers each pull the next unclaimed index until the queue is empty.
+ */
+export async function mapBounded(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.max(0, Math.min(limit, items.length)) }, () => worker()));
+    return results;
+}
 /**
  * The `fetch`-backed transport over the SDK kernel. Presigned PUTs carry
  * `If-None-Match: *` (create-only — the bucket policy demands it) and the
@@ -599,19 +647,18 @@ export function createGitvaultHttpTransport(client, options = {}) {
                 return null;
             if (isRun402Error(e) && e.code === "RESOURCE_NOT_FOUND")
                 return null;
-            // A known live gateway gap (confirmed 2026-08-27 against
-            // src_c78d2f710a8f49d22f9c66faf2a915cd): `POST …/object-reads`
-            // validates every null-idScalar (path-addressed) object_kind against
-            // key_envelope's `{epoch, recipient_fingerprint}` shape, never having
-            // been generalized for the SECOND path-addressed kind D197 shipped —
-            // `recipient_pin_manifest`'s real `{pin_manifest_version}` fields —
-            // so a genuine read always 400s `"epoch must be 16 hex"`. This is a
-            // read-back of a manifest neither uploaded nor cached by THIS
-            // keystore (a cache hit in `readPinManifestObject` never reaches
-            // here at all) — re-thrown with an attribution that names the gap
-            // instead of leaving a caller to read this as a client validation bug.
-            if (ref.read.object_kind === "recipient_pin_manifest" && isRun402Error(e) && e.code === "VALIDATION_FAILED") {
-                throw new LocalError(`the gateway's object-reads route does not yet accept recipient_pin_manifest reads by pin_manifest_version (its null-idScalar branch is still hardcoded to key_envelope's epoch/recipient_fingerprint shape) — this vault's pin manifest at ${path} cannot be read back over the network by a keystore that did not itself just publish it`, "reading gitvault object", { code: "GITVAULT_PIN_MANIFEST_READ_UNSUPPORTED", details: { path, pin_manifest_version: ref.read.pin_manifest_version }, cause: e });
+            // The gateway accepts `{object_kind: "recipient_pin_manifest",
+            // pin_manifest_version}` reads (fixed 2026-08-28; before that its
+            // null-idScalar validation was hardcoded to key_envelope's
+            // `{epoch, recipient_fingerprint}` shape and 400'd every such read
+            // with "epoch must be 16 hex"). A VALIDATION_FAILED here therefore
+            // indicates a genuinely malformed request and propagates as-is —
+            // EXCEPT the pre-fix epoch-shape complaint, which a fixed gateway can
+            // never emit for this kind: that signature can only mean an unfixed
+            // (older/staging) gateway behind RUN402_API_BASE, so name it rather
+            // than letting it read as a client validation bug.
+            if (ref.read.object_kind === "recipient_pin_manifest" && isRun402Error(e) && e.code === "VALIDATION_FAILED" && /epoch must be 16 hex/.test(e.message ?? "")) {
+                throw new LocalError(`this gateway predates the 2026-08-28 fix that made object-reads accept recipient_pin_manifest reads by pin_manifest_version (its null-idScalar branch rejected them with key_envelope's epoch-shape complaint) — this vault's pin manifest at ${path} cannot be read back over the network from it by a keystore that did not itself just publish the manifest`, "reading gitvault object", { code: "GITVAULT_PIN_MANIFEST_READ_UNSUPPORTED", details: { path, pin_manifest_version: ref.read.pin_manifest_version }, cause: e });
             }
             throw e;
         }
@@ -625,6 +672,49 @@ export function createGitvaultHttpTransport(client, options = {}) {
             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 N independent objects (gitvault-client-round-trips
+     * design D2): ONE `object-reads` POST naming every path, then the GETs
+     * with bounded concurrency ({@link GITVAULT_TRANSPORT_CONCURRENCY}).
+     * Every path must be `object-reads`-addressed (a "carrier": ref_state,
+     * retention_roots, a WAL/checkpoint pack, …) — a generation-addressed
+     * head/admission path has no place in a batch built for materialize/
+     * 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) {
+        if (paths.length === 0)
+            return [];
+        const refs = paths.map((path) => {
+            const ref = gitvaultWireRefForPath(path);
+            if (!ref || ref.kind !== "object")
+                fail("GITVAULT_OBJECT_READ_FAILED", `${path} is not a batch-readable carrier object`, "reading gitvault objects", { path });
+            return ref.read;
+        });
+        let presigned;
+        try {
+            presigned = await client.request(`${base(repoId)}/object-reads`, { method: "POST", body: { objects: refs }, context: "resolving gitvault objects" });
+        }
+        catch (e) {
+            if (isRun402Error(e) && e.status === 404)
+                return paths.map(() => null);
+            if (isRun402Error(e) && e.code === "RESOURCE_NOT_FOUND")
+                return paths.map(() => null);
+            throw e;
+        }
+        const byLedgerId = new Map(presigned.reads.map((r) => [gitvaultLedgerId(r), r]));
+        const targets = refs.map((r) => byLedgerId.get(gitvaultLedgerId(r)) ?? null);
+        return mapBounded(targets, GITVAULT_TRANSPORT_CONCURRENCY, async (target, i) => {
+            if (!target)
+                return null;
+            const r = await client.fetch(target.url, { method: "GET" });
+            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());
+        });
+    }
     async function upload(repoId, objects, resourceBinding) {
         if (objects.length === 0)
             return [];
@@ -638,8 +728,9 @@ export function createGitvaultHttpTransport(client, options = {}) {
             context: "opening gitvault upload session",
         });
         const issued = new Map(session.objects.map((u) => [gitvaultLedgerId(u), u]));
-        for (let i = 0; i < objects.length; i++) {
-            const o = objects[i];
+        // 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) => {
             const id = gitvaultLedgerId(entries[i]);
             const target = issued.get(id);
             if (!target)
@@ -660,11 +751,11 @@ export function createGitvaultHttpTransport(client, options = {}) {
                 const existing = await getObjectBytes(repoId, o.path);
                 if (!existing || sha256Hex(existing) !== o.sha256)
                     fail("GITVAULT_OBJECT_EXISTS_DIFFERENT", `${o.path} already exists with different bytes`, "uploading gitvault objects", { path: o.path });
-                continue;
+                return;
             }
             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 receipts = new Map(fin.receipts.map((r) => [gitvaultLedgerId(r), r]));
         return objects.map((o, i) => {
@@ -693,7 +784,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
             throw e;
         }
     }
-    return {
+    const transport = {
         // ── creation (5.3) ──
         async allocate(request) {
             // The route wraps the signed allocation object under `allocation` and
@@ -707,6 +798,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
             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),
         async admitGenesis(request) {
             try {
                 const r = await admit(request.repo_id, GITVAULT_GENESIS_GENERATION, request.stored_bytes, request.stored_bytes_sha256, { allocation_generation: request.allocation_generation });
@@ -828,6 +920,80 @@ export function createGitvaultHttpTransport(client, options = {}) {
             }
         },
     };
+    return process.env.RUN402_GITVAULT_TRACE === "1" ? traceGitvaultTransport(transport) : transport;
+}
+/**
+ * `RUN402_GITVAULT_TRACE=1` (design D7) — one stderr line per real
+ * transport operation (op kind, a path/object-count shape when the request
+ * carries one, byte count when the result carries one, duration) plus a
+ * session summary at process exit (total ops, total time spent in this
+ * transport, wall-clock since the transport was created). Debug-only:
+ * stderr only — never stdout, so it can never contaminate the
+ * `git-remote-run402` protocol stream, the same discipline the helper's
+ * own `note()` follows — and not a canonical surface: it is NOT what the
+ * client-surface spec's counted budgets measure (that is
+ * `GitvaultOpCounter`, a test-only instrument over the SAME operation
+ * shapes). The client-side env var carries no gateway env-registry policy.
+ */
+function traceGitvaultTransport(inner) {
+    let opCount = 0;
+    let totalMs = 0;
+    const sessionStart = Date.now();
+    process.on("exit", () => {
+        if (opCount === 0)
+            return;
+        process.stderr.write(`gitvault-trace: session summary — ${opCount} op(s), ${totalMs.toFixed(1)}ms in transport, ${Date.now() - sessionStart}ms wall-clock\n`);
+    });
+    const describeRequest = (arg) => {
+        if (!arg || typeof arg !== "object")
+            return "";
+        const a = arg;
+        if (typeof a.path === "string")
+            return ` path=${a.path}`;
+        if (Array.isArray(a.paths))
+            return ` paths=${a.paths.length}`;
+        if (Array.isArray(a.objects))
+            return ` objects=${a.objects.length}`;
+        if (typeof a.generation === "string")
+            return ` gen=${a.generation}`;
+        if (typeof a.repo_id === "string")
+            return ` repo=${a.repo_id}`;
+        return "";
+    };
+    const describeResult = (result) => {
+        if (result instanceof Uint8Array)
+            return ` bytes=${result.length}`;
+        if (Array.isArray(result)) {
+            const total = result.reduce((sum, v) => sum + (v instanceof Uint8Array ? v.length : 0), 0);
+            return total > 0 ? ` bytes=${total}` : "";
+        }
+        return "";
+    };
+    return new Proxy(inner, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function" || typeof prop !== "string")
+                return value;
+            return async (...args) => {
+                const start = Date.now();
+                try {
+                    const result = await Reflect.apply(value, target, args);
+                    const elapsed = Date.now() - start;
+                    opCount += 1;
+                    totalMs += elapsed;
+                    process.stderr.write(`gitvault-trace: ${prop}${describeRequest(args[0])}${describeResult(result)} ${elapsed}ms\n`);
+                    return result;
+                }
+                catch (e) {
+                    const elapsed = Date.now() - start;
+                    opCount += 1;
+                    totalMs += elapsed;
+                    process.stderr.write(`gitvault-trace: ${prop}${describeRequest(args[0])} FAILED ${elapsed}ms\n`);
+                    throw e;
+                }
+            };
+        },
+    });
 }
 // ─── Storage paths (§3) ──────────────────────────────────────────────────────
 export const gitvaultPaths = {
@@ -855,6 +1021,39 @@ export const gitvaultPaths = {
     /** `recipient-pins/<pin_manifest_version>.json` (D197, rev 42) — version-addressed, plaintext-structured, writer-signed. */
     pinManifest: (pinManifestVersion) => `recipient-pins/${pinManifestVersion}.json`,
 };
+// ─── Incremental restore marker (gitvault-client-round-trips design D5) ──────
+//
+// `restored_through` — the newest generation whose WAL packs this TARGET
+// DIRECTORY has fully applied — is local git state, same store as the
+// id-pin (`git config --local`), scoped to the directory `restoreObjectsInto`
+// actually wrote into (never `process.cwd()`, and never scoped to `repo_id`:
+// a re-pointed remote's marker simply fails its `head_sha256` comparison and
+// falls back to wholesale, safely, since that comparison is a content hash).
+const GITVAULT_RESTORE_MARKER_GENERATION_KEY = "r402.restoredThrough";
+const GITVAULT_RESTORE_MARKER_SHA256_KEY = "r402.restoredThroughSha256";
+async function readLocalGitConfigValue(dir, key) {
+    try {
+        const out = (await hardenedGit(dir, ["config", "--local", "--get", key])).text().trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        // Absent key or not a repository at all — either way, "nothing marked" is the correct read.
+        return null;
+    }
+}
+/** Read this target directory's `restored_through` marker, or `null` when nothing was ever restored into it. */
+export async function readGitvaultRestoreMarker(targetRepoDir) {
+    const generation = await readLocalGitConfigValue(targetRepoDir, GITVAULT_RESTORE_MARKER_GENERATION_KEY);
+    const head_sha256 = await readLocalGitConfigValue(targetRepoDir, GITVAULT_RESTORE_MARKER_SHA256_KEY);
+    if (!generation || !head_sha256)
+        return null;
+    return { generation, head_sha256 };
+}
+/** Advance the marker — called only after a restore's coverage verification succeeds. */
+async function writeGitvaultRestoreMarker(targetRepoDir, generation, headSha256) {
+    await hardenedGit(targetRepoDir, ["config", "--local", GITVAULT_RESTORE_MARKER_GENERATION_KEY, generation]);
+    await hardenedGit(targetRepoDir, ["config", "--local", GITVAULT_RESTORE_MARKER_SHA256_KEY, headSha256]);
+}
 /** A transport-agnostic view of git ops the publication needs (the local repository). */
 export class GitvaultVault {
     keystore;
@@ -912,7 +1111,16 @@ export class GitvaultVault {
         if (this.genesisCache)
             return this.genesisCache;
         const repo = this.repoFile();
-        const bytes = await this.transport.getGenesis({ repo_id: this.repoId });
+        // Design D3: genesis is one small, immutable object per vault — cached
+        // forever beside the keystore's per-repo state, re-verified against the
+        // pinned `genesis_sha256` on every use exactly like a network read.
+        const cached = this.keystore.readCachedGenesis(this.repoId);
+        let bytes = cached && sha256Hex(cached.bytes) === repo.genesis_sha256 ? cached.bytes : null;
+        if (!bytes) {
+            bytes = await this.transport.getGenesis({ repo_id: this.repoId });
+            if (bytes && sha256Hex(bytes) === repo.genesis_sha256)
+                this.keystore.writeCachedGenesis(this.repoId, repo.genesis_sha256, bytes);
+        }
         if (!bytes)
             fail("CHAIN_BROKEN", "the vault has no admitted genesis", "reading gitvault genesis", { repo_id: this.repoId });
         const sha256 = sha256Hex(bytes);
@@ -936,9 +1144,33 @@ export class GitvaultVault {
      * retry restarts from the ORIGINAL pin rather than resuming — the honest
      * consequence of asking for a no-write audit and then walking off the end
      * of one call's budget.
+     *
+     * The chain walk itself (`checkChainLink`, `assertNoTransition`, collecting
+     * `rotations[]`) is ALWAYS keyless — an admitted `rotate_epoch` transition
+     * never stops it (D193, rev 42), so `generation`/`head` here are the
+     * genuinely chain-verified newest, independent of whether this principal
+     * can decrypt anything past a rotation it cannot open.
+     *
+     * `options.decryptValidate` (default `false`, Part C — `repos fsck`'s
+     * decrypt-validation pass): additionally opens every `rotate_epoch`
+     * envelope needed and decrypts each walked generation's OWN
+     * `ref_state`/`retention_roots` as it goes — the "main object" restoration
+     * needs per generation — persisting newly-opened epoch keys via
+     * `keystore.recordEpochRotation` exactly like an ordinary rotation
+     * producer/consumer would, and counting each decrypt attempt as an EXTRA
+     * unit against the same `this.budget` (decryption is the expensive step).
+     * `options.strict` (default `true`) throws immediately, fail-closed, on the
+     * first `GITVAULT_EPOCH_NOT_OPENABLE` / AEAD failure it hits — the ordinary
+     * `materialize()` read path's behavior. `strict: false` (fsck's tolerant
+     * mode) instead records `decrypt.failure` and stops attempting further
+     * decrypts while the pure chain walk keeps going — this is exactly what
+     * makes `chain_verified_to` (this call's `generation`) and `decryptable_to`
+     * (`decrypt.decryptable_to_generation`) able to differ honestly.
      */
     async verifyToNewest(options = {}) {
         const persist = options.persist ?? true;
+        const decryptValidate = options.decryptValidate ?? false;
+        const strict = options.strict ?? true;
         const { genesis, sha256: genesisSha } = await this.genesis();
         const writerKey = genesis.creator_signing_pubkey;
         const writerKeyId = genesis.writer_key_id;
@@ -946,9 +1178,97 @@ export class GitvaultVault {
         let pin = repo.verified_prefix ?? repo.head_pin ?? { generation: GITVAULT_GENESIS_GENERATION, head_sha256: genesisSha, pinned_at: formatGitvaultTimestamp(this.now()) };
         let lastHead = pin.generation === GITVAULT_GENESIS_GENERATION ? null : await this.readHead(pin.generation, pin.head_sha256);
         const anchor = pin.generation;
+        let prevEpoch = lastHead?.epoch ?? GITVAULT_GENESIS_EPOCH;
         let progress = { after_generation: anchor, last_generation: anchor, delivered: 0 };
         let request = { after_generation: anchor, limit: String(GITVAULT_MAX_HEADS_PER_LISTING_PAGE) };
         let verified = 0;
+        const rotations = [];
+        // ── decrypt-validation state (opt-in) ──
+        const identity = decryptValidate ? this.keystore.readIdentity() : null;
+        const ownKeypair = identity ? this.keystore.encryptionKeypair(identity) : null;
+        const epochKeys = { ...(repo.epoch_keys ?? { [repo.epoch]: repo.k_repo_hex }) };
+        let decryptPin = repo.materialized_pin ?? null;
+        let decryptedRefState = null;
+        let decryptedRoots = null;
+        let decryptFailure = null;
+        let decryptFailureError = null;
+        const persistMaterializedIfAny = () => {
+            if (persist && decryptValidate && decryptPin)
+                this.keystore.updateRepo(this.repoId, { materialized_pin: decryptPin });
+        };
+        /**
+         * Open (if needed) `headPin`'s own rotation envelope and decrypt its
+         * `ref_state`/`retention_roots`. Shared by the per-head inline call below
+         * AND the post-loop catch-up call: a call with NOTHING new to walk (this
+         * repo's chain-verified pin is already at the newest generation) never
+         * enters the loop body at all, so the newest head's own decrypt still
+         * needs to run once, using whatever `epoch_keys` the keystore already
+         * persisted from an EARLIER call's rotation-envelope open.
+         *
+         * NEVER throws — a decrypt failure is recorded on the enclosing
+         * `decryptFailure`/`decryptFailureError` and this returns `false`. This
+         * is deliberate: chain verification (this call's OWN `generation`/
+         * `head_pin`, "highest_authenticated") is independent of decrypt
+         * capability and must walk the FULL chain regardless — exactly the
+         * existing "authenticated-but-undecryptable ⇒ CHAIN_UNUSABLE, read-only
+         * at the materialized pin" split this file's own header already
+         * documents. `strict` is enforced ONCE, at the very end of
+         * `verifyToNewest`, after the complete chain walk has run.
+         */
+        const tryDecrypt = async (head, headPin, pendingRotations) => {
+            verified += 1; // decryption is the expensive step — counted separately against the same budget
+            // Tracks whichever rotation is currently being opened — the failure
+            // report below names THAT rotation's own generation/epoch/rotation_id,
+            // never `head`'s (which, in the backward catch-up call, can be a much
+            // LATER, ordinary-push generation entirely unrelated to which epoch
+            // actually failed to open).
+            let current = { generation: head.generation, epoch: head.epoch, rotation_id: null };
+            try {
+                for (const rot of pendingRotations) {
+                    if (epochKeys[rot.epoch])
+                        continue;
+                    current = { generation: rot.generation, epoch: rot.epoch, rotation_id: rot.payload.rotation_id };
+                    if (!identity || !ownKeypair) {
+                        fail("GITVAULT_EPOCH_NOT_OPENABLE", `no local gitvault identity — cannot open epoch ${rot.epoch} (rotation ${rot.payload.rotation_id})`, "opening an epoch-rotation key envelope", { epoch: rot.epoch, rotation_id: rot.payload.rotation_id });
+                    }
+                    const ownFingerprint = ekFingerprint(ownKeypair.public_key);
+                    const kE = await openEpochRotationForRecipient({
+                        repo_id: this.repoId,
+                        payload: rot.payload,
+                        own_fingerprint: ownFingerprint,
+                        own_encryption_keypair: ownKeypair,
+                        writer_signing_public_key: writerKey,
+                        get_envelope_bytes: (path) => this.transport.getObject({ repo_id: this.repoId, path }),
+                        envelope_path: (epoch, fp, rotationId) => gitvaultPaths.envelope(epoch, fp, rotationId),
+                    });
+                    epochKeys[rot.epoch] = bytesToHex(kE);
+                    if (persist)
+                        this.keystore.recordEpochRotation(this.repoId, { new_epoch: rot.epoch, new_k_repo_hex: bytesToHex(kE) });
+                }
+                current = { generation: head.generation, epoch: head.epoch, rotation_id: null };
+                const kRepoHex = epochKeys[head.epoch];
+                if (!kRepoHex) {
+                    fail("GITVAULT_EPOCH_NOT_OPENABLE", `no locally known key for epoch ${head.epoch} at generation ${head.generation}`, "materializing gitvault head", { epoch: head.epoch, generation: head.generation });
+                }
+                const kRepo = hexToBytes(kRepoHex);
+                // Design D2: ref_state + retention_roots both ride `head`, so one
+                // batched presign (or a cache hit) serves both instead of two
+                // independent presign-then-GET round trips.
+                const { refState, roots } = await this.openMaterializeCarriers(head.ref_state, gitvaultPaths.refState(head.ref_state.object_id), head.retention_roots, gitvaultPaths.retentionRoots(head.retention_roots.object_id), writerKey, { epoch: head.epoch, k_repo: kRepo });
+                if (refState.generation !== head.generation || roots.generation !== head.generation)
+                    fail("CHAIN_UNUSABLE", "carrier generation does not match the head", "materializing gitvault head");
+                decryptedRefState = refState;
+                decryptedRoots = roots;
+                decryptPin = { ...headPin };
+                return true;
+            }
+            catch (e) {
+                const code = isRun402Error(e) && e.code ? e.code : "GITVAULT_EPOCH_NOT_OPENABLE";
+                decryptFailure = { generation: current.generation, epoch: current.epoch, rotation_id: current.rotation_id, code, message: e instanceof Error ? e.message : String(e) };
+                decryptFailureError = e;
+                return false;
+            }
+        };
         for (;;) {
             const page = await this.transport.listHeads({ repo_id: this.repoId, ...request });
             progress = verifyHeadsListingPage(page, request, progress, this.repoId);
@@ -956,15 +1276,16 @@ export class GitvaultVault {
                 if (verified >= this.budget) {
                     if (persist)
                         this.keystore.updateRepo(this.repoId, { verified_prefix: pin });
+                    persistMaterializedIfAny();
                     fail("VERIFICATION_BUDGET_EXCEEDED", persist
                         ? `${verified} heads verified this call; the verified prefix (generation ${pin.generation}) is persisted — call again to continue`
                         : `${verified} heads verified this call in no-write mode; nothing was persisted — a retry restarts from the original pin, not generation ${pin.generation}`, "verifying gitvault chain", { verified_through: pin.generation, persisted: persist }, [{ action: persist ? "resume verification from the persisted verified prefix" : "re-run without --no-write to persist and resume incrementally, or re-run this same audit call again from the start" }]);
                 }
-                const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.head(entry.generation) });
+                const bytes = await this.readCachedHeadBytes(entry.generation, entry.stored_bytes_sha256);
                 if (!bytes)
                     fail("CHAIN_BROKEN", `listed head ${entry.generation} is absent from storage`, "verifying gitvault chain", { generation: entry.generation });
                 const head = parseGitvaultStrict(new TextDecoder().decode(bytes));
-                checkChainLink({ head, stored_bytes: bytes, listed_sha256: entry.stored_bytes_sha256, expected_generation: nextGeneration(pin.generation), prev_sha256: pin.head_sha256, repo_id: this.repoId, writer_public_key: writerKey, writer_key_id: writerKeyId });
+                checkChainLink({ head, stored_bytes: bytes, listed_sha256: entry.stored_bytes_sha256, expected_generation: nextGeneration(pin.generation), prev_sha256: pin.head_sha256, repo_id: this.repoId, writer_public_key: writerKey, writer_key_id: writerKeyId, prev_epoch: prevEpoch });
                 try {
                     assertNoTransition(head);
                 }
@@ -972,24 +1293,156 @@ export class GitvaultVault {
                     // fail closed: pin stays BELOW the transition head; the verified prefix is cleared (this is the final state, not a budget pause)
                     if (persist)
                         this.keystore.updateRepo(this.repoId, { head_pin: pin, verified_prefix: null });
+                    persistMaterializedIfAny();
                     throw e;
                 }
+                const isRotation = head.transition !== null && head.transition.kind === "rotate_epoch";
+                let rotationPayload = null;
+                if (isRotation) {
+                    // Pure/keyless (Part A's structural half — D202's join predicate
+                    // needs only this): parses + self-checks the payload, but never
+                    // opens an envelope. Collected regardless of decryptValidate so a
+                    // later `materialize()` call over an already-chain-verified prefix
+                    // can still resolve the epoch keys it needs.
+                    rotationPayload = parseRotateEpochPayload(head);
+                    rotations.push({ generation: head.generation, epoch: head.epoch, payload: rotationPayload });
+                }
+                prevEpoch = head.epoch;
                 pin = { generation: head.generation, head_sha256: entry.stored_bytes_sha256, pinned_at: formatGitvaultTimestamp(this.now()) };
                 lastHead = head;
                 verified += 1;
+                // The chain walk ALWAYS continues below regardless of decrypt
+                // outcome (`tryDecrypt` never throws) — `!decryptFailure` just stops
+                // WASTING further decrypt attempts once one has failed, since every
+                // later generation shares the same unopenable epoch until (if ever)
+                // a LATER rotation this principal CAN open supersedes it.
+                if (decryptValidate && !decryptFailure)
+                    await tryDecrypt(head, pin, rotationPayload ? [{ generation: head.generation, epoch: head.epoch, payload: rotationPayload }] : []);
             }
             // verified prefix persists per page (resumable) — skipped entirely in no-write mode
             if (persist)
                 this.keystore.updateRepo(this.repoId, { verified_prefix: pin });
+            persistMaterializedIfAny();
             const next = nextListingRequest(request, page);
             if (!next)
                 break;
             request = next;
         }
+        // Catch-up: a call with NOTHING new to walk (this repo's chain-verified
+        // pin was already at `pin`/`lastHead` — e.g. an EARLIER, decrypt-blind
+        // `verifyToNewest({})` call already advanced `head_pin` to the newest,
+        // and THIS is the first decrypt-validating call) never entered the loop
+        // body above at all, so any `rotate_epoch` transitions between the
+        // newest and the highest epoch this call's `epochKeys` seed already
+        // covers were NEVER collected — walk BACKWARD via `prev_sha256` (the
+        // same re-read `chainFrom` uses) to find every one of them, stopping the
+        // INSTANT a generation's own epoch is already a known key (nothing
+        // earlier can matter: every generation before it decrypts under a key
+        // already held). Never a silent gap — this is exactly the mechanism
+        // that makes a vault readable end to end even when chain verification
+        // and decrypt-validation happened in genuinely SEPARATE calls.
+        if (decryptValidate && !decryptFailure && lastHead && !decryptedRefState) {
+            const backwardRotations = [];
+            let cur = lastHead;
+            let curPin = pin;
+            while (cur && !epochKeys[cur.epoch]) {
+                if (cur.transition !== null && cur.transition.kind === "rotate_epoch") {
+                    const payload = parseRotateEpochPayload(cur);
+                    backwardRotations.unshift({ generation: cur.generation, epoch: cur.epoch, payload });
+                    if (!rotations.some((r) => r.generation === cur.generation))
+                        rotations.push({ generation: cur.generation, epoch: cur.epoch, payload });
+                }
+                if (cur.generation === "0000000000000001") {
+                    cur = null;
+                    break;
+                }
+                const prevGen = bigIntToGeneration(generationToBigInt(cur.generation) - 1n);
+                // Design D3: this downward walk is rooted in `lastHead`, itself just
+                // chain-verified above (or trusted from an earlier call's own
+                // verification) — the same "freshness already established" argument
+                // {@link readCachedHeadBytes} documents, so a cache hit is safe here too.
+                const bytes = await this.readCachedHeadBytes(prevGen, cur.prev_sha256);
+                if (!bytes || sha256Hex(bytes) !== cur.prev_sha256)
+                    fail("CHAIN_BROKEN", `head ${prevGen} does not match the chain during epoch-key catch-up`, "materializing gitvault head", { generation: prevGen });
+                cur = parseGitvaultStrict(new TextDecoder().decode(bytes));
+                curPin = { generation: prevGen, head_sha256: bytes ? sha256Hex(bytes) : curPin.head_sha256, pinned_at: formatGitvaultTimestamp(this.now()) };
+            }
+            rotations.sort((a, b) => (a.generation < b.generation ? -1 : a.generation > b.generation ? 1 : 0));
+            // `cur` (non-null, non-lastHead) is the BOUNDARY generation whose own
+            // epoch this call already holds a key for — establish `decryptPin`
+            // THERE first (this always succeeds: its epoch is, by the loop's own
+            // stop condition, already in `epochKeys`), so `refs`/`head_target`
+            // reflect a REAL decrypted generation even when every pending rotation
+            // toward `lastHead` then fails. Without this, a keystore that has
+            // never once materialized (no `materialized_pin` yet) reports
+            // `decryptable_to_generation: genesis` on an epoch-open failure, even
+            // though generations well before the failing rotation were genuinely
+            // decryptable all along.
+            if (cur && cur.generation !== lastHead.generation)
+                await tryDecrypt(cur, curPin, []);
+            if (!decryptFailure)
+                await tryDecrypt(lastHead, pin, backwardRotations);
+        }
         if (persist)
             this.keystore.updateRepo(this.repoId, { head_pin: pin, verified_prefix: null });
-        return { generation: pin.generation, head_sha256: pin.head_sha256, head: lastHead, genesis };
+        persistMaterializedIfAny();
+        // `strict` (materialize()'s ordinary, fail-closed read path) is enforced
+        // HERE, once, after the full keyless chain walk has already run to
+        // completion — never mid-walk (see `tryDecrypt`'s own doc comment).
+        if (strict && decryptValidate && decryptFailure)
+            throw decryptFailureError;
+        return {
+            generation: pin.generation,
+            head_sha256: pin.head_sha256,
+            head: lastHead,
+            genesis,
+            rotations,
+            decrypt: decryptValidate
+                ? {
+                    decryptable_to_generation: decryptPin?.generation ?? GITVAULT_GENESIS_GENERATION,
+                    ref_state: decryptedRefState,
+                    retention_roots: decryptedRoots,
+                    epoch_keys_hex: epochKeys,
+                    failure: decryptFailure,
+                }
+                : null,
+        };
+    }
+    /**
+     * Read one NEWLY-LISTED head's raw bytes, trying the local cache first
+     * (design D3), re-verified against `expectedSha256` — the SAME check
+     * network bytes get. Safe to cache-serve ONLY because a caller here
+     * always supplies a hash a FRESH `listHeads` call just reported as
+     * current — the cache never substitutes for that freshness check, it just
+     * avoids re-downloading bytes a live listing already vouched for. A cache
+     * miss or a hash mismatch (never trusted, always falls through) fetches
+     * from the network and, on a match, refreshes the cache entry. Returns
+     * whatever the network returned on a final miss too (including `null`) —
+     * callers keep their own existing absent/mismatch handling unchanged.
+     *
+     * Deliberately NOT used by {@link readHead}: that call verifies the
+     * PINNED generation is STILL held by the server, with no fresh listing
+     * involved — its entire purpose is detecting server-side loss/rollback,
+     * which a cache read can never observe. That call always goes live.
+     */
+    async readCachedHeadBytes(generation, expectedSha256) {
+        const cached = this.keystore.readCachedHead(this.repoId, generation);
+        if (cached && sha256Hex(cached.bytes) === expectedSha256)
+            return cached.bytes;
+        const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.head(generation) });
+        if (bytes && sha256Hex(bytes) === expectedSha256)
+            this.keystore.writeCachedHead(this.repoId, generation, expectedSha256, bytes);
+        return bytes;
     }
+    /**
+     * Confirm the server STILL holds the pinned generation, unchanged —
+     * ALWAYS a live network read (see {@link readCachedHeadBytes}'s doc
+     * comment for why this specific check is not cacheable: it exists to
+     * detect server-side loss, which a cache can never observe). A
+     * successful read still WARMS the cache afterward — later reads of this
+     * SAME generation via the chain walk or restore benefit from it; only
+     * THIS call's own read is exempt.
+     */
     async readHead(generation, expectedSha256) {
         const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.head(generation) });
         // Absent ⇒ the vault no longer holds a generation this client authenticated: a ROLLBACK, not a
@@ -1001,16 +1454,30 @@ export class GitvaultVault {
         }
         if (sha256Hex(bytes) !== expectedSha256)
             fail("CHAIN_BROKEN", `pinned head ${generation} no longer hashes to the pin`, "reading pinned gitvault head", { generation });
+        this.keystore.writeCachedHead(this.repoId, generation, expectedSha256, bytes);
         return parseGitvaultStrict(new TextDecoder().decode(bytes));
     }
-    /** Decrypt one encrypted carrier object by its receipt; any failure is `CHAIN_UNUSABLE`. */
-    async openCarrier(kind, receipt, path, writerKey) {
-        const frame = await this.transport.getObject({ repo_id: this.repoId, path });
+    /**
+     * Decrypt + verify one carrier's already-fetched ciphertext frame; any
+     * failure is `CHAIN_UNUSABLE`. Split out of {@link openCarrier} so a
+     * caller that fetched the frame itself (a cache hit, or one leg of a
+     * batched read) can reuse the same decode + identity/signature checks.
+     *
+     * `keyOverride` supplies the exact `(epoch, k_repo)` this carrier was
+     * sealed under — REQUIRED for any generation that is not necessarily
+     * under `this.epoch()`/`this.kRepo()` (this principal's CURRENT
+     * pointer), which is exactly the case across an epoch rotation; omitted
+     * call sites (checkpoint/prune paths untouched by this fold) keep the
+     * prior CURRENT-pointer behavior unchanged.
+     */
+    decodeCarrierFrame(kind, receipt, frame, writerKey, keyOverride) {
+        const epoch = keyOverride?.epoch ?? this.epoch();
+        const kRepo = keyOverride?.k_repo ?? this.kRepo();
         if (!frame)
             fail("CHAIN_UNUSABLE", `${kind} ${receipt.object_id} is absent from storage`, "materializing gitvault head", { object_id: receipt.object_id }, [{ action: "stay read-only at the materialized pin; run the repair path" }]);
         let plaintext;
         try {
-            plaintext = openFrame({ k_obj: deriveObjectKey(this.kRepo(), this.repoId, this.epoch(), kind, receipt.object_id), repo_id: this.repoId, object_kind: kind, object_id: receipt.object_id, epoch: this.epoch(), frame, expected_ciphertext_sha256: receipt.ciphertext_sha256 });
+            plaintext = openFrame({ k_obj: deriveObjectKey(kRepo, this.repoId, epoch, kind, receipt.object_id), repo_id: this.repoId, object_kind: kind, object_id: receipt.object_id, epoch, frame, expected_ciphertext_sha256: receipt.ciphertext_sha256 });
         }
         catch (e) {
             fail("CHAIN_UNUSABLE", `${kind} ${receipt.object_id} cannot be opened: ${e.message}`, "materializing gitvault head", { object_id: receipt.object_id }, [{ action: "stay read-only at the materialized pin; run the repair path" }]);
@@ -1021,29 +1488,94 @@ export class GitvaultVault {
         }
         return object;
     }
+    /**
+     * Fetch (network) + decrypt one carrier object by its receipt; any
+     * failure is `CHAIN_UNUSABLE`. Design D3: `ref_state`/`retention_roots`
+     * ciphertext is cached beside the keystore's per-repo state, re-verified
+     * against `receipt.ciphertext_sha256` on every use — a hit skips the
+     * network read entirely. `checkpoint_manifest` is never cached (outside
+     * D3's table). The cache write derives its generation tag from the
+     * DECODED object's own `generation` field, so no caller needs to thread
+     * one through by hand.
+     */
+    async openCarrier(kind, receipt, path, writerKey, keyOverride) {
+        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 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);
+        }
+        return object;
+    }
+    /**
+     * `materialize`'s ref_state + retention_roots read, batched (design D2):
+     * cache-check both first, then ONE `getObjects` call (one presigned batch
+     * + concurrent GETs) for whichever missed, instead of two independent
+     * presign-then-GET round trips. Falls through to zero network calls when
+     * both are cache-warm. `keyOverride` is the epoch/k_repo the CARRYING
+     * HEAD sealed both carriers under (D194) — both always share one head, so
+     * one override serves both, unlike the WAL/checkpoint pack loops in
+     * {@link restoreObjectsInto} which span many heads and many epochs.
+     */
+    async openMaterializeCarriers(refStateReceipt, refStatePath, rootsReceipt, rootsPath, writerKey, keyOverride) {
+        const cachedRefState = this.keystore.readCachedCarrier(this.repoId, refStateReceipt.object_id);
+        const cachedRoots = this.keystore.readCachedCarrier(this.repoId, rootsReceipt.object_id);
+        const refStateHit = Boolean(cachedRefState && sha256Hex(cachedRefState.bytes) === refStateReceipt.ciphertext_sha256);
+        const rootsHit = Boolean(cachedRoots && sha256Hex(cachedRoots.bytes) === rootsReceipt.ciphertext_sha256);
+        const missingPaths = [];
+        if (!refStateHit)
+            missingPaths.push(refStatePath);
+        if (!rootsHit)
+            missingPaths.push(rootsPath);
+        const fetched = missingPaths.length > 0 ? await this.transport.getObjects({ repo_id: this.repoId, paths: missingPaths }) : [];
+        let next = 0;
+        const refStateFrame = refStateHit ? cachedRefState.bytes : (fetched[next++] ?? null);
+        const rootsFrame = rootsHit ? cachedRoots.bytes : (fetched[next++] ?? null);
+        const refState = this.decodeCarrierFrame("ref_state", refStateReceipt, refStateFrame, writerKey, keyOverride);
+        const roots = this.decodeCarrierFrame("retention_roots", rootsReceipt, rootsFrame, writerKey, keyOverride);
+        if (!refStateHit && refStateFrame)
+            this.keystore.writeCachedCarrier(this.repoId, refStateReceipt.object_id, refState.generation, refStateReceipt.ciphertext_sha256, refStateFrame);
+        if (!rootsHit && rootsFrame)
+            this.keystore.writeCachedCarrier(this.repoId, rootsReceipt.object_id, roots.generation, rootsReceipt.ciphertext_sha256, rootsFrame);
+        return { refState, roots };
+    }
     /**
      * Verify to newest, then decrypt + apply its carriers — advancing the
      * materialized pin. `options.persist` (default `true`) is forwarded to
      * {@link verifyToNewest} and gates this method's OWN `materialized_pin`
      * write the same way — `repos fsck --no-write` computes and returns the
      * real ref map and generation without moving either local pin.
+     *
+     * Runs `verifyToNewest({..., decryptValidate: true, strict: true})`
+     * internally (Part A: an ordinary read across an admitted `rotate_epoch`
+     * transition now opens the rotation's own envelope and decrypts under the
+     * NEW epoch, chaining through multiple sequential rotations; a keystore
+     * with no envelope for a new epoch fails CLOSED with
+     * `GITVAULT_EPOCH_NOT_OPENABLE`, never a bare `GITVAULT_AEAD_AUTH_FAILURE`)
+     * — `strict: true` means this call throws exactly where the OLD
+     * (pre-fix) `materialize()` silently produced a wrong `k_obj` instead.
      */
     async materialize(options = {}) {
         const persist = options.persist ?? true;
-        const state = await this.verifyToNewest({ persist });
-        const writerKey = state.genesis.creator_signing_pubkey;
+        const state = await this.verifyToNewest({ persist, decryptValidate: true, strict: true });
         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()) } });
-            return { ...state, ref_state: null, retention_roots: null, refs: {}, roots: [], head_target: { kind: "symref", ref: "refs/heads/main" } };
+            return { ...state, ref_state: null, retention_roots: null, refs: {}, roots: [], head_target: { kind: "symref", ref: "refs/heads/main" }, epoch_keys_hex: state.decrypt?.epoch_keys_hex ?? {} };
         }
-        const refState = await this.openCarrier("ref_state", state.head.ref_state, gitvaultPaths.refState(state.head.ref_state.object_id), writerKey);
-        const roots = await this.openCarrier("retention_roots", state.head.retention_roots, gitvaultPaths.retentionRoots(state.head.retention_roots.object_id), writerKey);
+        // `strict: true` guarantees `state.decrypt` is non-null with no failure
+        // and `decryptable_to_generation === state.generation` — it throws
+        // otherwise, so these are never null/mismatched here. `verifyToNewest`'s
+        // own `tryDecrypt` is what actually fetches these now (design D2/D3's
+        // batching + caching moved there with it — see its doc comment) —
+        // `openMaterializeCarriers` no longer has a caller from here.
+        const refState = state.decrypt.ref_state;
+        const roots = state.decrypt.retention_roots;
         if (refState.generation !== state.generation || roots.generation !== state.generation)
             fail("CHAIN_UNUSABLE", "carrier generation does not match the head", "materializing gitvault head");
-        if (persist)
-            this.keystore.updateRepo(this.repoId, { materialized_pin: { generation: state.generation, head_sha256: state.head_sha256, pinned_at: formatGitvaultTimestamp(this.now()) } });
-        return { ...state, ref_state: refState, retention_roots: roots, refs: { ...refState.refs }, roots: roots.roots.map((r) => ({ ...r })), head_target: refState.head_target };
+        return { ...state, ref_state: refState, retention_roots: roots, refs: { ...refState.refs }, roots: roots.roots.map((r) => ({ ...r })), head_target: refState.head_target, epoch_keys_hex: state.decrypt.epoch_keys_hex };
     }
     // ── envelope recipients (gitvault-human-envelopes task 4.1, the ADD-path workaround) ──
     /**
@@ -1595,11 +2127,18 @@ export class GitvaultVault {
             return { outcome: "conflict", generation, winner: admitted.winner };
         return { outcome: "admitted", generation, head, head_sha256: admitted.head_sha256, admission_record_sha256: admitted.admission_record_sha256, capture_receipt: admitted.capture_receipt, form, refs: input.refs };
     }
-    /** The complete push: verify → materialize → evaluate → pack → upload → head → admit (409: re-apply to the winner, retry) → read back → advance pins. */
+    /**
+     * The complete push: verify → materialize → evaluate → pack → upload → head → admit (409: re-apply to the winner, retry) → read back → advance pins.
+     *
+     * `options.base` (design D1), when supplied, is used VERBATIM for the
+     * first attempt instead of a fresh {@link materialize} call — a conflict
+     * retry always re-materializes from storage, exactly as when no base is
+     * supplied.
+     */
     async push(options) {
         let conflicts = 0;
+        let base = options.base ?? (await this.materialize());
         for (;;) {
-            const base = await this.materialize();
             const evaluation = await evaluateRefTransaction(base.refs, options.transaction, { isAncestor: (a, d) => isAncestor(this.git(), a, d), protocol_refs: options.protocol_refs });
             const published = await this.publishGeneration({
                 base, refs: evaluation.refs, dropped: evaluation.dropped, head_target: options.head_target ?? base.head_target,
@@ -1609,7 +2148,8 @@ export class GitvaultVault {
                 conflicts += 1;
                 if (conflicts > this.retries)
                     fail("HEAD_CAS_CONFLICT", `admission lost ${conflicts} races at generation ${published.generation}; giving up`, "publishing gitvault head", { generation: published.generation, winner: published.winner }, [{ action: "verify the attached winner from storage, rebase, retry" }]);
-                continue; // the loop re-verifies from storage (the winner), re-applies the transaction to the winner's map, retries
+                base = await this.materialize(); // re-verify from storage (the winner) before re-applying the transaction
+                continue;
             }
             // `push()` never sets `dry_run`, so this outcome is unreachable here —
             // narrows `published` to `"admitted"` for the return below.
@@ -1639,7 +2179,11 @@ export class GitvaultVault {
      * that case instead of calling this method).
      */
     async planPush(options) {
-        const base = await this.materialize();
+        // Design D1: a caller-supplied base reports against the CALLER's own
+        // observed snapshot instead of materializing a fresh one — same
+        // verbatim-first-attempt contract as `push`, minus the retry loop
+        // (a dry run never re-materializes; there is nothing to retry against).
+        const base = options.base ?? (await this.materialize());
         const evaluation = await evaluateRefTransaction(base.refs, options.transaction, { isAncestor: (a, d) => isAncestor(this.git(), a, d), protocol_refs: options.protocol_refs });
         const headTarget = options.head_target ?? base.head_target;
         const published = await this.publishGeneration({
@@ -1752,10 +2296,18 @@ export class GitvaultVault {
         const result = await this.transport.admitHead({ repo_id: this.repoId, generation: head.generation, stored_bytes: bytes, stored_bytes_sha256: hash });
         if (result.outcome === "conflict")
             return result;
+        // Post-admit readback is a spec-mandated verification obligation, never
+        // a cache lookup — it exists to prove the SERVER stored what was sent,
+        // which only a genuine network read can answer.
         const back = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.head(head.generation) });
         if (!back || sha256Hex(back) !== hash) {
             fail("GITVAULT_HEAD_READBACK_MISMATCH", `the admitted head at generation ${head.generation} read back ${back ? sha256Hex(back) : "absent"} ≠ ${hash}; the push is NOT reported as landed and no pin advances`, "reading back admitted head", { generation: head.generation, expected: hash, observed: back ? sha256Hex(back) : null });
         }
+        // Design D3: the readback just network-confirmed these exact bytes —
+        // warm the cache with them so the NEXT operation (this session's own
+        // `materialize` retry, or a later invocation) can skip re-fetching this
+        // generation's head entirely.
+        this.keystore.writeCachedHead(this.repoId, head.generation, hash, back);
         const pin = { generation: head.generation, head_sha256: hash, pinned_at: formatGitvaultTimestamp(this.now()) };
         this.keystore.updateRepo(this.repoId, { head_pin: pin, materialized_pin: pin, verified_prefix: null });
         return { outcome: "admitted", head_sha256: hash, admission_record_sha256: result.admission_record_sha256, capture_receipt: result.capture_receipt };
@@ -1805,20 +2357,15 @@ export class GitvaultVault {
      * manifest — e.g. one another principal/machine published) falls through
      * to the unchanged network path below.
      *
-     * **Known gap this happens to route around, not fix:** the gateway's
-     * `POST …/object-reads` route does not yet recognize `recipient_pin_manifest`
-     * as a readable `object_kind` at all (`services/gitvault/reads.ts`
-     * `validateReadRequest`'s null-`idScalar` branch is still hardcoded to
-     * `key_envelope`'s `{epoch, recipient_fingerprint}` shape — the ONE other
-     * path-addressed kind, `recipient_pin_manifest`, was never folded in when
-     * D197 shipped it with its own `{pin_manifest_version}` `pathFields`).
-     * Confirmed live 2026-08-27 against `src_c78d2f710a8f49d22f9c66faf2a915cd`:
-     * every read attempt fails `400 VALIDATION_FAILED "objects[0]: epoch must
-     * be 16 hex"`. This cache unblocks the SAME keystore re-reading its OWN
-     * just-published manifest (this ceremony's actual need) but does nothing
-     * for a genuinely fresh keystore/machine reading an EXISTING manifest for
-     * the first time (§4.11's "fresh client... SEEDS its local pin file from
-     * it" onboarding path) — that still needs the gateway fix.
+     * History: this cache originally also routed around a gateway gap —
+     * `POST …/object-reads` rejected every `recipient_pin_manifest` read
+     * (its null-`idScalar` validation was hardcoded to `key_envelope`'s
+     * `{epoch, recipient_fingerprint}` shape, never generalized when D197
+     * shipped the second path-addressed kind), so the network fallback below
+     * always 400'd. That gateway bug is fixed (deployed and live-verified
+     * 2026-08-28): the network path works for any keystore, including
+     * §4.11's fresh-client "SEEDS its local pin file from it" onboarding.
+     * The cache stays purely as the round-trip saver described above.
      */
     async readPinManifestObject(receipt) {
         const known = this.repoFile().known_pin_manifest;
@@ -2323,6 +2870,20 @@ export class GitvaultVault {
      * Pull the newest checkpoint (if any) and every later WAL pack into
      * `targetRepoDir` (an initialized repository), then verify every canonical
      * ref + the HEAD target resolves. Returns the materialized refs.
+     *
+     * Design D5 (gitvault-client-round-trips): incremental above the local
+     * `restored_through` marker (this target directory's own local git
+     * config, read/written by {@link readGitvaultRestoreMarker}/{@link
+     * writeGitvaultRestoreMarker}) — replaying only the WAL packs of
+     * generations above it — WHEN the walk from newest back to the marker is
+     * plain WAL the entire way. The moment that walk crosses a
+     * checkpoint-bearing, repair, or transition head (checked BEFORE
+     * including a head, so the marker-boundary and wholesale-boundary checks
+     * share one pass), this falls back to the ORIGINAL wholesale walk below —
+     * re-fetching any head already visited during the aborted attempt is a
+     * cache hit (design D3), never a second network round trip. Coverage
+     * verification and retained-refs reconciliation run UNCHANGED on both
+     * paths; the marker only advances after they both succeed.
      */
     async restoreObjectsInto(targetRepoDir) {
         const newest = await this.materialize();
@@ -2331,21 +2892,69 @@ export class GitvaultVault {
             return { refs: {}, head_target: newest.head_target, generation: newest.generation, retained_refs };
         }
         const writerKey = newest.genesis.creator_signing_pubkey;
-        // walk back to the newest checkpoint-bearing head
+        const marker = await readGitvaultRestoreMarker(targetRepoDir);
+        // Already up to date locally: no pack fetch, not even a walk — only the
+        // (entirely local) coverage + retained-refs bookkeeping below runs.
+        if (marker && marker.generation === newest.generation && marker.head_sha256 === newest.head_sha256) {
+            for (const t of GitvaultVault.coverageTips(newest.refs, newest.roots, newest.head_target)) {
+                if (!(await hasObject(targetRepoDir, t)))
+                    fail("CHAIN_UNUSABLE", `covered tip ${t} does not resolve after restore`, "restoring gitvault objects", { oid: t });
+            }
+            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 };
+        }
+        // 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
+        // non-plain-WAL head would have to be included, and restart as the
+        // ORIGINAL wholesale walk (stopping at the newest checkpoint, or
+        // genesis) — every head visited in the aborted attempt is a D3 cache
+        // hit on this restart, so abandoning costs no extra round trip.
         const heads = [];
         let cur = newest.head;
+        let incremental = marker !== null;
         while (cur) {
+            // `cur` disqualifies incremental (checked BEFORE including it): abort
+            // and restart as the wholesale walk. Re-visiting heads already fetched
+            // this attempt costs nothing (D3 cache hits).
+            if (incremental && (cur.checkpoint !== null || cur.transition !== null)) {
+                incremental = false;
+                heads.length = 0;
+                cur = newest.head;
+                continue;
+            }
             heads.unshift(cur);
-            if (cur.checkpoint)
-                break;
+            if (!incremental && cur.checkpoint)
+                break; // wholesale stop: the newest checkpoint-bearing head
             if (cur.generation === "0000000000000001")
-                break;
+                break; // genesis — a hard stop either way
+            // Before fetching `cur`'s predecessor, check whether the marker
+            // already names it — a pure LOCAL comparison against bytes this
+            // client already applied last time, no network round trip.
             const prevGen = bigIntToGeneration(generationToBigInt(cur.generation) - 1n);
-            const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.head(prevGen) });
+            if (incremental && cur.prev_sha256 === marker.head_sha256 && prevGen === marker.generation) {
+                cur = null; // the predecessor is the marker's own head — already applied; `heads` already holds everything above it
+                break;
+            }
+            const bytes = await this.readCachedHeadBytes(prevGen, cur.prev_sha256);
             if (!bytes || sha256Hex(bytes) !== cur.prev_sha256)
                 fail("CHAIN_BROKEN", `head ${prevGen} does not match the chain during restore`, "restoring gitvault objects");
             cur = parseGitvaultStrict(new TextDecoder().decode(bytes));
         }
+        // Every object below is decrypted under ITS OWN carrying head's `epoch`
+        // (D194) — a covered span crossing a rotation mixes epochs, so this
+        // NEVER falls back to `this.kRepo()`/`this.epoch()` (this principal's
+        // CURRENT pointer, which is the NEWEST epoch, not necessarily every
+        // historical one a restore spans). `newest.epoch_keys_hex` is the full
+        // 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 first = heads[0];
         if (first.checkpoint) {
             const claimBytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.claimSet(first.checkpoint.claim_set.object_id) });
@@ -2354,26 +2963,42 @@ export class GitvaultVault {
             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);
+            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);
-            for (const p of manifest.packs) {
-                const frame = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.checkpointPack(p.object_id) });
+            // Design D2: every checkpoint pack is independent — one batched
+            // presign for all of them, THEN applied via index-pack strictly in
+            // manifest order (the fetch is concurrent; the local git write is
+            // not, and does not need to be).
+            const frames = await this.transport.getObjects({ repo_id: this.repoId, paths: manifest.packs.map((p) => gitvaultPaths.checkpointPack(p.object_id)) });
+            for (let i = 0; i < manifest.packs.length; i++) {
+                const p = manifest.packs[i];
+                const frame = frames[i] ?? null;
                 if (!frame)
                     fail("CHECKPOINT_INCOMPLETE", `checkpoint pack ${p.object_id} absent`, "restoring gitvault objects");
-                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 });
+                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 });
                 if (sha256Hex(plain) !== p.plaintext_sha256 || String(plain.length) !== p.plaintext_size_bytes)
                     fail("CHECKPOINT_INCOMPLETE", `checkpoint pack ${p.object_id} plaintext mismatch`, "restoring gitvault objects");
                 await hardenedGit(targetRepoDir, ["index-pack", "--stdin", "--strict"], { input: plain });
             }
         }
-        for (const h of heads) {
-            for (const w of h.wal_entries) {
-                const frame = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.wal(w.object_id) });
-                if (!frame)
-                    fail("CHAIN_UNUSABLE", `WAL pack ${w.object_id} absent`, "restoring gitvault objects");
-                const plain = openFrame({ k_obj: deriveObjectKey(this.kRepo(), this.repoId, this.epoch(), "wal_pack", w.object_id), repo_id: this.repoId, object_kind: "wal_pack", object_id: w.object_id, epoch: this.epoch(), frame, expected_ciphertext_sha256: w.ciphertext_sha256 });
-                await hardenedGit(targetRepoDir, ["index-pack", "--stdin", "--strict"], { input: plain });
-            }
+        // Design D2: every WAL pack across every head in this restore's range is
+        // independent — one batched presign for the whole set (this is the
+        // "restore pack set" the design's own D2 prose names alongside
+        // materialize's carriers), fetched concurrently, then applied via
+        // index-pack in the SAME chain order the wholesale path always used
+        // (git's pack application is sequential; the network fetch need not be).
+        // Each entry decrypts under its OWN carrying head's epoch (D194) — the
+        // flattened list keeps that pairing so a rotation-spanning restore never
+        // reuses one head's epoch for another's pack.
+        const walEntries = heads.flatMap((h) => h.wal_entries.map((w) => ({ w, epoch: h.epoch })));
+        const walFrames = await this.transport.getObjects({ repo_id: this.repoId, paths: walEntries.map(({ w }) => gitvaultPaths.wal(w.object_id)) });
+        for (let i = 0; i < walEntries.length; i++) {
+            const { w, epoch } = walEntries[i];
+            const frame = walFrames[i] ?? null;
+            if (!frame)
+                fail("CHAIN_UNUSABLE", `WAL pack ${w.object_id} absent`, "restoring gitvault objects");
+            const plain = openFrame({ k_obj: deriveObjectKey(kRepoForEpoch(epoch), this.repoId, epoch, "wal_pack", w.object_id), repo_id: this.repoId, object_kind: "wal_pack", object_id: w.object_id, epoch, frame, expected_ciphertext_sha256: w.ciphertext_sha256 });
+            await hardenedGit(targetRepoDir, ["index-pack", "--stdin", "--strict"], { input: plain });
         }
         // the §4.7 coverage set — canonical refs ∪ unexpired roots ∪ the HEAD target — must all resolve.
         for (const t of GitvaultVault.coverageTips(newest.refs, newest.roots, newest.head_target)) {
@@ -2385,6 +3010,12 @@ export class GitvaultVault {
         // ref so `git fsck` is silent. Runs AFTER coverage verification so a
         // reconcile never references an object the restore itself failed to land.
         const retained_refs = await reconcileRetainedTipRefs(targetRepoDir, { refs: newest.refs, roots: newest.roots, head_target: newest.head_target });
+        // Design D5: the marker advances ONLY here — after coverage verification
+        // and the retained-refs reconcile both succeeded. An interrupted restore
+        // (a crash or throw anywhere above) leaves the marker unadvanced, so the
+        // next fetch simply repeats this same range; applying an already-applied
+        // WAL pack again is the existing, already-safe wholesale behavior.
+        await writeGitvaultRestoreMarker(targetRepoDir, newest.generation, newest.head_sha256);
         return { refs: newest.refs, head_target: newest.head_target, generation: newest.generation, retained_refs };
     }
 }