run402 4.49.0 → 4.51.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, openEpochRotationForRecipient, openFrame, openKeyEnvelope, parseGitvaultStrict, parseRotateEpochPayload, 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, 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";
@@ -63,6 +63,34 @@ const LIMIT_RE = /^([1-9]|[1-9][0-9]|[1-9][0-9][0-9]|1000)$/;
 function fail(code, message, context, details, nextActions) {
     throw new LocalError(message, context, { code, details, ...(nextActions ? { next_actions: nextActions } : {}) });
 }
+// ─── Reader-provenance strings (D209/D210) ───────────────────────────────────
+/**
+ * Resolved once from this package's own `package.json` — mirrors
+ * `node/index.ts`'s `readSdkPackageVersion`, duplicated locally rather than
+ * imported to avoid a dependency edge from this file (imported by the
+ * cross-runtime `namespaces/gitvault.ts` via a dynamic `import()`, task
+ * 5.0's public crypto surface) back onto the Node CLI/SDK entry module.
+ */
+const GITVAULT_SDK_PACKAGE_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+/**
+ * `run402@<version>/<entrypoint>` — the audit-provenance string named on
+ * `self_open_attestation.reader_entrypoint` (D209) and
+ * `recipient_open_receipt.reader_entrypoint` (D210): "names the client
+ * implementation + entry point that produced the evidence." Never an
+ * authorization input; no wire grammar is promised for it (protocol-v0.md
+ * §4.14, `rotate_epoch_payload.json`'s own field `$comment`).
+ */
+export function gitvaultReaderEntrypoint(entrypoint) {
+    return `run402@${GITVAULT_SDK_PACKAGE_VERSION}/${entrypoint}`;
+}
 // ─── Generations ─────────────────────────────────────────────────────────────
 export function generationToBigInt(generation) {
     if (!GITVAULT_HEX16_RE.test(generation))
@@ -543,6 +571,37 @@ export function gitvaultManifestEntry(object) {
     }
     return entry;
 }
+// ─── Inline upload (gitvault-composite-state-read design D2) ─────────────────
+/** Mirrors the gateway's `GITVAULT_INLINE_UPLOAD_MAX_OBJECT_BYTES` (`services/gitvault/upload-sessions.ts`). */
+export const GITVAULT_INLINE_UPLOAD_MAX_OBJECT_BYTES = 262_144;
+/** Mirrors the gateway's `GITVAULT_INLINE_UPLOAD_MAX_REQUEST_BYTES`. */
+export const GITVAULT_INLINE_UPLOAD_MAX_REQUEST_BYTES = 1_048_576;
+/**
+ * The client-side mirror of the gateway's `isInlineUploadRequest` + per-object/
+ * per-request cap check: every object must fit under the PER-OBJECT cap AND
+ * the batch's total under the PER-REQUEST cap, or the whole batch takes the
+ * presigned session+PUT+finalize shape — no per-object mixing, matching the
+ * server's `VALIDATION_FAILED` refusal on a mixed request. An empty batch is
+ * never "inline" (nothing to send either way; `upload()`'s own early return
+ * already short-circuits before this is consulted, and `putObject` always
+ * wraps exactly one object so it never hits this branch).
+ *
+ * Takes the narrowest shape that satisfies every call site (`GitvaultUploadObject[]`
+ * for `uploadObjects`, a single `{bytes}`-shaped array for `putObject`) so
+ * neither caller needs to fabricate unrelated fields just to ask the
+ * question.
+ */
+export function gitvaultInlineUploadEligible(objects) {
+    if (objects.length === 0)
+        return false;
+    let total = 0;
+    for (const o of objects) {
+        if (o.bytes.length > GITVAULT_INLINE_UPLOAD_MAX_OBJECT_BYTES)
+            return false;
+        total += o.bytes.length;
+    }
+    return total <= GITVAULT_INLINE_UPLOAD_MAX_REQUEST_BYTES;
+}
 /**
  * The stable key both sides agree on, used to pair receipts back to
  * requests — MIRRORS the gateway's `keyEnvelopeLedgerId`/`pinManifestLedgerId`
@@ -715,6 +774,42 @@ export function createGitvaultHttpTransport(client, options = {}) {
             return new Uint8Array(await r.arrayBuffer());
         });
     }
+    /** Resolve ONE `GET …/state` carrier arm to raw bytes — inline decode, or a plain GET on the presigned URL, `null` on a 404 (mirrors {@link getObjectBytes}'s absent reading; both arms indistinguishable after this). */
+    async function resolveVaultStateCarrier(carrier) {
+        if ("inline" in carrier)
+            return fromBase64url(carrier.inline, "carriers.inline");
+        const r = await client.fetch(carrier.presigned_url, { method: "GET" });
+        if (r.status === 404)
+            return null;
+        if (!r.ok)
+            fail("GITVAULT_OBJECT_READ_FAILED", `vault-state carrier GET failed (HTTP ${r.status})`, "reading the gitvault vault state", { status: r.status });
+        return new Uint8Array(await r.arrayBuffer());
+    }
+    /**
+     * `GET …/state` (design D1): one JSON body carrying the vault record, the
+     * newest generation, its head's exact stored bytes, and both carriers —
+     * resolved to raw bytes here, verified nowhere here (see the interface's
+     * own doc comment on {@link GitvaultTransport.getState}).
+     */
+    async function getVaultStateOut(repoId) {
+        const raw = await client.request(`${base(repoId)}/state`, { context: "reading the gitvault vault state" });
+        const head = raw.head ? { stored_bytes: fromBase64url(raw.head.stored_bytes, "head.stored_bytes"), stored_bytes_sha256: raw.head.stored_bytes_sha256 } : null;
+        const carriers = raw.carriers
+            ? { ref_state: await resolveVaultStateCarrier(raw.carriers.ref_state), retention_roots: await resolveVaultStateCarrier(raw.carriers.retention_roots) }
+            : null;
+        return { vault: raw.vault, newest_generation: raw.newest_generation, head, carriers };
+    }
+    /** Pair a `finalize`-shaped response's receipts back onto `objects` by ledger id — shared by the inline and presigned upload paths so neither forks the other's receipt-compare logic. */
+    function receiptsFromFinalize(objects, entries, fin) {
+        const receipts = new Map(fin.receipts.map((r) => [gitvaultLedgerId(r), r]));
+        return objects.map((o, i) => {
+            const id = gitvaultLedgerId(entries[i]);
+            const r = receipts.get(id);
+            if (!r)
+                fail("GITVAULT_RECEIPT_MISSING", `finalize returned no receipt for ${id}`, "finalizing gitvault upload session", { object_id: id, path: o.path });
+            return { path: o.path, object_id: o.object_id, sha256: r.ciphertext_sha256 ?? r.stored_bytes_sha256 ?? "", size_bytes: r.size_bytes };
+        });
+    }
     async function upload(repoId, objects, resourceBinding) {
         if (objects.length === 0)
             return [];
@@ -722,6 +817,19 @@ export function createGitvaultHttpTransport(client, options = {}) {
         // wire — the control plane derives the bucket key itself and refuses an
         // entry carrying an unexpected member.
         const entries = objects.map((o) => gitvaultManifestEntry(o));
+        if (gitvaultInlineUploadEligible(objects)) {
+            // gitvault-composite-state-read design D2: every object fits under the
+            // caps — one POST, bytes verified + written server-side, and the
+            // response IS the finalize response (no session, no PUTs, no separate
+            // finalize call). Same closed-key manifest as the presigned path, plus
+            // each entry's own bytes.
+            const fin = await client.request(`${base(repoId)}/upload-sessions`, {
+                method: "POST",
+                body: { objects: entries.map((entry, i) => ({ ...entry, bytes: b64u(objects[i].bytes) })), ...(resourceBinding ? { resource_binding: resourceBinding } : {}) },
+                context: "uploading gitvault objects inline",
+            });
+            return receiptsFromFinalize(objects, entries, fin);
+        }
         const session = await client.request(`${base(repoId)}/upload-sessions`, {
             method: "POST",
             body: { objects: entries, ...(resourceBinding ? { resource_binding: resourceBinding } : {}) },
@@ -757,14 +865,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
                 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) => {
-            const id = gitvaultLedgerId(entries[i]);
-            const r = receipts.get(id);
-            if (!r)
-                fail("GITVAULT_RECEIPT_MISSING", `finalize returned no receipt for ${id}`, "finalizing gitvault upload session", { object_id: id, path: o.path });
-            return { path: o.path, object_id: o.object_id, sha256: r.ciphertext_sha256 ?? r.stored_bytes_sha256 ?? "", size_bytes: r.size_bytes };
-        });
+        return receiptsFromFinalize(objects, entries, fin);
     }
     async function admit(repoId, generation, bytes, hash, extra = {}) {
         try {
@@ -846,6 +947,7 @@ export function createGitvaultHttpTransport(client, options = {}) {
             return { cleared: r.advisory_cleared ?? r.cleared ?? false };
         },
         getVaultRecord: ({ repo_id }) => client.request(base(repo_id), { context: "reading the gitvault record" }),
+        getState: ({ repo_id }) => getVaultStateOut(repo_id),
         findVaultByProject: ({ project_id }) => client.request(`/gitvault/v1/vaults?project_id=${encodeURIComponent(project_id)}`, { context: "resolving the project's gitvault" }),
         findVaultByRepo: ({ org_slug, repo_name }) => client.request(`/gitvault/v1/vaults?repo=${encodeURIComponent(`${org_slug}/${repo_name}`)}`, { context: "resolving the gitvault by repo address" }),
         listOrgEncryptionKeys: ({ org_id }) => client.request(`/orgs/v1/${encodeURIComponent(org_id)}/encryption-keys`, { context: "reading the org encryption-key directory" }),
@@ -864,6 +966,15 @@ export function createGitvaultHttpTransport(client, options = {}) {
         declareRecipientKeyRevoked: ({ repo_id, principal_id }) => client.request(`${base(repo_id)}/recipients/${encodeURIComponent(principal_id)}/key-revocation`, { method: "POST", body: {}, context: "declaring a gitvault recipient key revoked" }),
         declareEpochSecretExposed: ({ repo_id }) => client.request(`${base(repo_id)}/epoch-secret-exposure`, { method: "POST", body: {}, context: "declaring a gitvault epoch secret exposed" }),
         declareWriterAuthorityUnavailable: ({ repo_id }) => client.request(`${base(repo_id)}/writer-authority/declare-unavailable`, { method: "POST", body: {}, context: "declaring gitvault writer authority unavailable" }),
+        async submitOpenProof({ repo_id, principal_id, ek_fingerprint, chain_verified_to_generation, decryptable_to_generation, reader_entrypoint }) {
+            // requestWithResponse (not request) — the gateway's own status code is
+            // the ONLY signal distinguishing a fresh mint (201) from an idempotent
+            // replay of the tuple's already-committed winner (200); the receipt
+            // BODY is identical either way (routes/gitvault.ts:
+            // `res.status(inserted ? 201 : 200).json(receipt)`).
+            const res = await client.requestWithResponse(`${base(repo_id)}/recipients/${encodeURIComponent(principal_id)}/proof-of-open`, { method: "POST", body: { ek_fingerprint, chain_verified_to_generation, decryptable_to_generation, reader_entrypoint }, context: "submitting a gitvault proof-of-open receipt" });
+            return { receipt: res.body, deduplicated: res.status === 200 };
+        },
         acquireMaintenanceLease: ({ repo_id, base_head_sha256, current_checkpoint_hash, r1_size_bytes, r2_cap_size_bytes, p_before_c1_size_bytes, p_before_c2_size_bytes }) => client.request(`${base(repo_id)}/maintenance-leases`, {
             method: "POST",
             body: {
@@ -1131,6 +1242,130 @@ export class GitvaultVault {
         return this.genesisCache;
     }
     // ── §6.3/6.4 discovery + verification ──
+    /**
+     * gitvault-composite-state-read design D1 — the pin-current fast path
+     * `verifyToNewest` tries FIRST: one `GET …/state` in place of BOTH the
+     * live "server still holds the pin" read {@link readHead} would otherwise
+     * perform AND, when eligible, the `listHeads` walk that would follow it.
+     *
+     * `null` means ineligible — the caller falls straight through to the
+     * UNCHANGED `readHead` + `listHeads` flow, so a `null` here never weakens
+     * verification, it only declines the shortcut:
+     *   - the vault is genuinely more than one generation ahead of `pin`
+     *     (the listing-walk shape this change does not touch, per design D1:
+     *     "a client whose pin is >1 behind newest_generation falls back to
+     *     the existing paginated listing + per-head walk");
+     *   - OR (one-generation-ahead only) the D194 epoch-continuity check the
+     *     ONE new head needs `pin`'s own `.epoch` for, and this call declines
+     *     to fetch `pin`'s own head bytes over the network — the entire point
+     *     of the shortcut — so it needs a LOCAL source for that epoch: either
+     *     `pin` is genesis (a fixed, known epoch), or `pin`'s own head bytes
+     *     are already cache-warm (from an earlier call, or from `admit()`'s
+     *     own post-push cache write). A cold cache here is not a correctness
+     *     problem, only a missed optimization.
+     *
+     * On a non-`null` return, `entries` is exactly what ONE real `listHeads`
+     * page's `heads[]` would have been for this pin (0 items when the pin is
+     * already current, 1 when it is exactly one generation behind — chain
+     * link, gaplessness, and signature all still verified by the UNCHANGED
+     * per-entry loop body {@link verifyToNewest} feeds them through), and
+     * `pinnedHead` is `lastHead`'s INITIAL value: the real, verified head at
+     * `pin.generation` when nothing new needs walking (so it is also the
+     * FINAL value — the loop never runs), or a throwaway placeholder when one
+     * new head is coming (the loop overwrites `lastHead` before anything else
+     * ever reads it again — see `verifyToNewest`'s own `prevEpoch` line,
+     * which is the ONLY thing that reads `lastHead`'s pre-loop value).
+     *
+     * Every byte this method reads from `getState` is cache-WARMED (head +
+     * both carriers, keyed exactly as {@link readCachedHeadBytes}/
+     * {@link openCarrier} already key their own writes) but NEVER trusted
+     * here — every reader downstream re-verifies a cache hit against the hash
+     * it would check network bytes against before using it (this file's own
+     * established cache discipline; see `GitvaultKeystore`'s class doc
+     * comment). A wrong or absent byte this method wrote is therefore just a
+     * cache MISS on the next read, never a verification bypass.
+     */
+    async tryStateFastPath(pin) {
+        const state = await this.transport.getState({ repo_id: this.repoId });
+        // §6.4: the vault's newest generation may never fall below the
+        // authenticated pin — checked here regardless of eligibility below, so
+        // a regressed vault is caught exactly as loudly as it always was, even
+        // when the walk that would otherwise discover it is about to be skipped.
+        checkGenerationRegression(state.newest_generation ?? GITVAULT_GENESIS_GENERATION, pin.generation);
+        // The gateway's own admission ledger advances `newest_generation` to the
+        // GENESIS generation (0) the moment genesis itself is admitted — a vault
+        // between "genesis admitted" and "first ordinary push" reports its own
+        // generation as newest, `null` only for the narrower window before that
+        // (kept here defensively; `state.head`/`state.carriers` are non-null
+        // whenever `newest_generation` is non-null on the real route). EITHER
+        // way, "no ORDINARY head yet" is the same case this file has always
+        // treated specially: genesis is a DIFFERENT stored-object shape
+        // (`vault_genesis` — no `ref_state`/`retention_roots`, {@link
+        // GitvaultVault.genesis} owns verifying it via its OWN cache), so this
+        // path must never parse `state.head` as a {@link GitvaultHead} when it
+        // is actually genesis's bytes.
+        const noOrdinaryHeadYet = state.newest_generation === null || state.newest_generation === GITVAULT_GENESIS_GENERATION;
+        const pinBig = generationToBigInt(pin.generation);
+        const newestBig = noOrdinaryHeadYet ? 0n : generationToBigInt(state.newest_generation);
+        const diff = newestBig - pinBig; // ≥ 0n, guaranteed by the regression check above (which treats `null`/genesis identically to this)
+        if (diff === 0n) {
+            if (noOrdinaryHeadYet)
+                return { entries: [], pinnedHead: null, prevEpoch: GITVAULT_GENESIS_EPOCH }; // matches today's `lastHead = null` for a genesis-only vault
+            if (!state.head)
+                fail("CHAIN_BROKEN", "the vault state reports an admitted generation but carries no head bytes", "verifying gitvault chain", { generation: state.newest_generation });
+            const sha = sha256Hex(state.head.stored_bytes);
+            if (sha !== pin.head_sha256)
+                fail("CHAIN_BROKEN", `pinned head ${pin.generation} no longer hashes to the pin`, "reading pinned gitvault head", { generation: pin.generation });
+            this.keystore.writeCachedHead(this.repoId, pin.generation, sha, state.head.stored_bytes);
+            const head = parseGitvaultStrict(new TextDecoder().decode(state.head.stored_bytes));
+            if (state.carriers)
+                this.warmStateCarrierCache(pin.generation, head, state.carriers);
+            return { entries: [], pinnedHead: head, prevEpoch: head.epoch };
+        }
+        if (diff === 1n) {
+            let prevEpoch;
+            if (pin.generation === GITVAULT_GENESIS_GENERATION) {
+                prevEpoch = GITVAULT_GENESIS_EPOCH;
+            }
+            else {
+                const cached = this.keystore.readCachedHead(this.repoId, pin.generation);
+                if (!cached || sha256Hex(cached.bytes) !== pin.head_sha256)
+                    return null; // cold cache — decline the shortcut, never weaken it
+                prevEpoch = parseGitvaultStrict(new TextDecoder().decode(cached.bytes)).epoch;
+            }
+            if (!state.head)
+                fail("CHAIN_BROKEN", "the vault state reports a newer generation but carries no head bytes", "verifying gitvault chain", { generation: state.newest_generation });
+            const newestGeneration = state.newest_generation;
+            const shaOfBytes = sha256Hex(state.head.stored_bytes);
+            if (shaOfBytes !== state.head.stored_bytes_sha256)
+                fail("CHAIN_BROKEN", `head ${newestGeneration}: stored bytes hash does not match its own declared hash`, "verifying head chain", { generation: newestGeneration });
+            this.keystore.writeCachedHead(this.repoId, newestGeneration, shaOfBytes, state.head.stored_bytes);
+            const head = parseGitvaultStrict(new TextDecoder().decode(state.head.stored_bytes));
+            if (state.carriers)
+                this.warmStateCarrierCache(newestGeneration, head, state.carriers);
+            // `pinnedHead` is a throwaway — see this method's own doc comment: the
+            // ONE loop iteration below overwrites `lastHead` before anything but
+            // `prevEpoch` (already resolved above) ever reads it again.
+            return { entries: [{ generation: newestGeneration, stored_bytes_sha256: shaOfBytes }], pinnedHead: null, prevEpoch };
+        }
+        return null; // more than one generation behind — the existing listHeads walk owns this
+    }
+    /**
+     * Warm the D3 carrier cache from a `GET …/state` response's two carriers,
+     * keyed by the SAME `(object_id, ciphertext_sha256)` the carrying head's
+     * own receipts name — a BLIND write (see {@link tryStateFastPath}'s doc
+     * comment: every reader re-verifies a cache hit before trusting it, so
+     * this is safe by construction). Skips a `null` carrier (absent stored
+     * bytes) entirely rather than caching an absence — the existing
+     * `openCarrier`/`decodeCarrierFrame` machinery already has its own
+     * "frame absent" handling (`CHAIN_UNUSABLE`) via a genuine cache miss.
+     */
+    warmStateCarrierCache(generation, head, carriers) {
+        if (carriers.ref_state)
+            this.keystore.writeCachedCarrier(this.repoId, head.ref_state.object_id, generation, head.ref_state.ciphertext_sha256, carriers.ref_state);
+        if (carriers.retention_roots)
+            this.keystore.writeCachedCarrier(this.repoId, head.retention_roots.object_id, generation, head.retention_roots.ciphertext_sha256, carriers.retention_roots);
+    }
     /**
      * List from the authenticated pin and verify every link upward. Persists
      * the verified prefix after each page, so a `VERIFICATION_BUDGET_EXCEEDED`
@@ -1176,13 +1411,26 @@ export class GitvaultVault {
         const writerKeyId = genesis.writer_key_id;
         const repo = this.repoFile();
         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);
+        // gitvault-composite-state-read design D1: try the pin-current fast path
+        // FIRST — see {@link tryStateFastPath}'s own doc comment. `null` means
+        // ineligible (genuinely more than one generation behind, or the pin's
+        // own epoch could not be resolved without the network read this path
+        // exists to avoid) — the caller falls straight through to the UNCHANGED
+        // readHead + listHeads flow below, byte-identical to before this change.
+        const fastPath = await this.tryStateFastPath(pin);
+        let lastHead = fastPath ? fastPath.pinnedHead : pin.generation === GITVAULT_GENESIS_GENERATION ? null : await this.readHead(pin.generation, pin.head_sha256);
         const anchor = pin.generation;
-        let prevEpoch = lastHead?.epoch ?? GITVAULT_GENESIS_EPOCH;
+        let prevEpoch = fastPath ? fastPath.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 = [];
+        // Consumed by (at most) the FIRST for(;;) iteration below — a listHeads
+        // page this call never had to ask the network for, because the state
+        // read above already proved it (0 entries: pin already current; 1 entry:
+        // exactly the ONE new head, chain-linked from `pin` the SAME way a real
+        // listHeads page's entry would be).
+        let syntheticEntries = fastPath ? fastPath.entries : null;
         // ── decrypt-validation state (opt-in) ──
         const identity = decryptValidate ? this.keystore.readIdentity() : null;
         const ownKeypair = identity ? this.keystore.encryptionKeypair(identity) : null;
@@ -1270,7 +1518,14 @@ export class GitvaultVault {
             }
         };
         for (;;) {
-            const page = await this.transport.listHeads({ repo_id: this.repoId, ...request });
+            // The synthetic page (0 or 1 entries) is only ever valid for the FIRST
+            // iteration — `has_more: false` guarantees `nextListingRequest` ends
+            // the loop right after it is consumed, so clearing it here is purely
+            // defensive (a real second iteration can never see it non-null).
+            const page = syntheticEntries !== null
+                ? { format: GITVAULT_FORMAT, repo_id: this.repoId, after_generation: request.after_generation, heads: syntheticEntries, has_more: false, next_cursor: null, total: null }
+                : await this.transport.listHeads({ repo_id: this.repoId, ...request });
+            syntheticEntries = null;
             progress = verifyHeadsListingPage(page, request, progress, this.repoId);
             for (const entry of page.heads) {
                 if (verified >= this.budget) {
@@ -2552,6 +2807,11 @@ export class GitvaultVault {
             const repo = this.repoFile();
             const currentEpoch = base.head?.epoch ?? this.epoch();
             const newEpoch = nextEpoch(currentEpoch);
+            // Computed here (rather than where it was historically built, just
+            // before the head is signed) because D209's self_open_attestation
+            // needs to name THIS attempt's own admitted generation as
+            // decryptable_to_generation before the head itself is built.
+            const generation = nextGeneration(base.generation);
             // D195's producer obligation: a fresh K_e, checked against EVERY prior
             // epoch key this principal has ever locally held.
             const kE = randomBytes(32);
@@ -2662,13 +2922,78 @@ export class GitvaultVault {
                 await this.uploadAll(envelopeUploads);
             sealedReceipts.sort((a, b) => (a.principal_id < b.principal_id ? -1 : a.principal_id > b.principal_id ? 1 : 0));
             const epochKeyCommitmentValue = epochRotationKeyCommitment(kE, this.repoId, newEpoch, rotationId, included.map((p) => p.ek_fingerprint));
-            const payload = {
+            const payloadBase = {
                 new_epoch: newEpoch, rotation_id: rotationId, reason: options.reason,
                 recipient_state_version: options.recipient_state_version, recipient_revocation_version: options.recipient_revocation_version,
                 pin_manifest_sha256: pinManifest.pinManifestSha256, target_partition_digest: targetPartitionDigest,
                 epoch_key_commitment: epochKeyCommitmentValue, excluded_keyless_principal_ids: excludedKeyless, excluded_unconfirmed_principal_ids: excludedUnconfirmed,
                 recipient_authority_attestation: null, envelopes: sealedReceipts,
             };
+            // D209 (rev 44) — round-trip THIS principal's own new-epoch
+            // key_envelope through the REAL reader entry point
+            // (openEpochRotationForRecipient — the exact unit fsck/verifyToNewest
+            // use to open a rotation) BEFORE submitting, and bake the result into
+            // the payload as `self_open_attestation`. A rev-44 gateway refuses
+            // EPOCH_ROTATION_SELF_OPEN_UNPROVEN on any rotate_epoch admission
+            // that omits this or whose claim disagrees with its own
+            // server-computed writer-in-envelopes biconditional — this call site
+            // is the fix for the exact gap the 2026-08-28 drill found (production
+            // clients could not READ a rotated vault because the reader had never
+            // implemented rotation traversal, while the write side was green on
+            // its own tests). This SUPERSEDES the old post-commit self-check
+            // below (which called openKeyEnvelope directly, bypassing the
+            // membership lookup, the envelope_path callback derivation, and the
+            // reader's own error framing) — moving the round-trip BEFORE
+            // admission means a genuine failure aborts this call before anything
+            // is ever submitted to the gateway, rather than leaving a broken
+            // rotation committed server-side that even its own writer cannot
+            // read back. A round-trip failure THROWS
+            // (openEpochRotationForRecipient's own error framing — e.g.
+            // GITVAULT_EPOCH_NOT_OPENABLE / EPOCH_KEY_COMMITMENT_MISMATCH — never
+            // a bare AEAD failure); this call never emits a false attestation.
+            const identity = this.keystore.readIdentity();
+            const ownKeypair = identity ? this.keystore.encryptionKeypair(identity) : null;
+            const ownFingerprint = ownKeypair ? ekFingerprint(ownKeypair.public_key) : null;
+            const ownIncluded = ownFingerprint ? included.find((p) => p.ek_fingerprint === ownFingerprint) : undefined;
+            let selfOpenAttestation;
+            let selfCheck = "not_a_recipient";
+            if (ownFingerprint && ownKeypair && ownIncluded) {
+                await openEpochRotationForRecipient({
+                    repo_id: this.repoId,
+                    payload: payloadBase,
+                    own_fingerprint: ownFingerprint,
+                    own_encryption_keypair: ownKeypair,
+                    writer_signing_public_key: this.signingKeypair().public_key,
+                    get_envelope_bytes: (path) => this.transport.getObject({ repo_id: this.repoId, path }),
+                    envelope_path: (epoch, fp, rid) => gitvaultPaths.envelope(epoch, fp, rid),
+                });
+                // openEpochRotationForRecipient already recomputes epoch_key_commitment
+                // from the opened plaintext and compares it to payloadBase's own
+                // (HMAC-derived from kE) — an HMAC collision across different keys
+                // is cryptographically infeasible, so its own pass IS the proof
+                // that the opened secret equals kE. No separate byte comparison
+                // needed here (unlike the old post-commit check, which duplicated
+                // this logic by hand instead of trusting the real entry point).
+                selfOpenAttestation = {
+                    outcome: "opened",
+                    chain_verified_to_generation: base.generation,
+                    decryptable_to_generation: generation,
+                    opened_fingerprint: ownFingerprint,
+                    reader_entrypoint: gitvaultReaderEntrypoint("openEpochRotationForRecipient"),
+                };
+                selfCheck = "passed";
+            }
+            else {
+                // The normal agent/CI-writer case (D209's "writer_not_recipient"
+                // branch): the admitting principal has no included pair in
+                // envelopes[] (no local encryption identity at all, or one whose
+                // fingerprint is not among `included`), so no self round-trip is
+                // possible. This is NOT a confidentiality gap — the writer sampled
+                // kE itself — and D210's recipient proof-of-open receipts are the
+                // closure for post-rotation readability on this branch.
+                selfOpenAttestation = { outcome: "writer_not_recipient", chain_verified_to_generation: base.generation };
+            }
+            const payload = { ...payloadBase, self_open_attestation: selfOpenAttestation };
             const payloadBytes = jcs(payload);
             const transition = { kind: "rotate_epoch", payload_format: "base64url-jcs", payload: toBase64url(payloadBytes), payload_sha256: sha256Hex(payloadBytes) };
             // The manifest-publish deadlock fix: fold receipted pending
@@ -2687,7 +3012,9 @@ export class GitvaultVault {
                 ? this.buildPinManifestUpdate(pinManifest, pendingConfirmations.map((p) => ({ principal_id: p.principal_id, ek_fingerprint: p.ek_fingerprint, confirmed_by: "operator_confirmation", receipt: p.receipt })))
                 : null;
             // The new epoch's ref_state/retention_roots — CARRIED FORWARD unchanged, sealed under kE.
-            const generation = nextGeneration(base.generation);
+            // (`generation` itself was computed earlier, at the top of this loop
+            // — D209's self_open_attestation needed to name it as
+            // decryptable_to_generation before the head was even built.)
             const refState = this.buildRefState(generation, base.refs, base.head_target, { k_repo: kE, epoch: newEpoch });
             const rootsObj = this.buildRetentionRoots(generation, base.roots, null, { k_repo: kE, epoch: newEpoch });
             const uploads = [refState.upload, rootsObj.upload];
@@ -2710,39 +3037,13 @@ export class GitvaultVault {
                     fail("HEAD_CAS_CONFLICT", `the rotation lost ${conflicts} races at generation ${generation}; giving up`, "admitting a rotate_epoch head", { generation, winner: admitted.winner });
                 continue;
             }
-            // D200's post-commit self-check: verify THIS principal's own envelope
-            // (when it is itself a recipient) opens to exactly the committed K_e
-            // and reproduces epoch_key_commitment — a per-recipient proof only,
-            // never a global set-coherence claim.
-            let selfCheck = "not_a_recipient";
-            const identity = this.keystore.readIdentity();
-            const ownKeypair = identity ? this.keystore.encryptionKeypair(identity) : null;
-            if (identity && ownKeypair) {
-                const ownFingerprint = ekFingerprint(ownKeypair.public_key);
-                const own = included.find((p) => p.ek_fingerprint === ownFingerprint);
-                const ownPair = own ? sealedReceipts.find((r) => r.principal_id === own.principal_id) : undefined;
-                if (own && ownPair) {
-                    const envelopeBytes = await this.transport.getObject({ repo_id: this.repoId, path: gitvaultPaths.envelope(newEpoch, own.ek_fingerprint, rotationId) });
-                    if (!envelopeBytes || sha256Hex(envelopeBytes) !== ownPair.envelope.stored_bytes_sha256) {
-                        fail("GITVAULT_RECEIPT_MISMATCH", "this principal's own rotation-attempt envelope is absent or altered after commit", "verifying the committed epoch key", { rotation_id: rotationId });
-                    }
-                    const envelopeObj = parseGitvaultStrict(new TextDecoder().decode(envelopeBytes));
-                    // Verification key: this producer's OWN signing key — only the
-                    // vault's single registered writer key can sign a rotate_epoch
-                    // head/descriptor at all (v0 single-writer model), so a rotation
-                    // this call itself drove was necessarily signed by `this.signingKeypair()`.
-                    const recoveredKe = await openKeyEnvelope({ envelope: envelopeObj, recipient: ownKeypair, signer_public_key: this.signingKeypair().public_key });
-                    if (bytesToHex(recoveredKe) !== bytesToHex(kE)) {
-                        fail("GITVAULT_EPOCH_ROTATION_SELF_CHECK_FAILED", "this principal's own opened envelope does not recover the K_e it sealed — refusing to advance the local epoch pointer", "verifying the committed epoch key");
-                    }
-                    const recomputed = epochRotationKeyCommitment(recoveredKe, this.repoId, newEpoch, rotationId, included.map((p) => p.ek_fingerprint));
-                    if (recomputed !== epochKeyCommitmentValue) {
-                        fail("GITVAULT_EPOCH_ROTATION_SELF_CHECK_FAILED", "epoch_key_commitment does not reproduce from this principal's own opened K_e", "verifying the committed epoch key");
-                    }
-                    selfCheck = "passed";
-                }
-            }
-            // Advance the local pointer only after the self-check (when applicable) confirms this principal genuinely holds the committed K_e.
+            // The pre-submission D209 round-trip above already confirmed (when
+            // applicable — `selfCheck === "passed"`) that this principal's own
+            // opened envelope recovers exactly the K_e it sealed and reproduces
+            // epoch_key_commitment, through the real reader entry point. A
+            // genuine self-check failure would have thrown BEFORE this head was
+            // ever built or submitted, so the local pointer advances
+            // unconditionally here.
             this.keystore.recordEpochRotation(this.repoId, { new_epoch: newEpoch, new_k_repo_hex: bytesToHex(kE) });
             // Same local-cache short-circuit as publishPinManifestUpdate's own
             // success path (see readPinManifestObject's doc comment) — the fold