run402 4.45.1 → 4.47.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");
@@ -599,19 +620,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;
         }
@@ -936,9 +956,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 +990,95 @@ 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);
+                const refState = await this.openCarrier("ref_state", head.ref_state, gitvaultPaths.refState(head.ref_state.object_id), writerKey, { epoch: head.epoch, k_repo: kRepo });
+                const roots = await this.openCarrier("retention_roots", 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,6 +1086,7 @@ 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" }]);
@@ -964,7 +1095,7 @@ export class GitvaultVault {
                 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,23 +1103,116 @@ 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);
+                const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.head(prevGen) });
+                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,
+        };
     }
     async readHead(generation, expectedSha256) {
         const bytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.head(generation) });
@@ -1003,14 +1227,24 @@ export class GitvaultVault {
             fail("CHAIN_BROKEN", `pinned head ${generation} no longer hashes to the pin`, "reading pinned gitvault head", { generation });
         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) {
+    /**
+     * Decrypt one encrypted carrier object by its receipt; any failure is
+     * `CHAIN_UNUSABLE`. `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.
+     */
+    async openCarrier(kind, receipt, path, writerKey, keyOverride) {
+        const epoch = keyOverride?.epoch ?? this.epoch();
+        const kRepo = keyOverride?.k_repo ?? this.kRepo();
         const frame = await this.transport.getObject({ repo_id: this.repoId, path });
         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" }]);
@@ -1027,23 +1261,32 @@ export class GitvaultVault {
      * {@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.
+        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) ──
     /**
@@ -1805,20 +2048,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;
@@ -2346,6 +2584,20 @@ export class GitvaultVault {
                 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,13 +2606,13 @@ 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) });
                 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 });
@@ -2371,7 +2623,7 @@ export class GitvaultVault {
                 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 });
+                const plain = openFrame({ k_obj: deriveObjectKey(kRepoForEpoch(h.epoch), this.repoId, h.epoch, "wal_pack", w.object_id), repo_id: this.repoId, object_kind: "wal_pack", object_id: w.object_id, epoch: h.epoch, frame, expected_ciphertext_sha256: w.ciphertext_sha256 });
                 await hardenedGit(targetRepoDir, ["index-pack", "--stdin", "--strict"], { input: plain });
             }
         }