@mandujs/core 0.53.3 → 0.54.1

package/src/bundler/vendor-cache.ts

@@ -1,526 +1,526 @@
-/**
- * Phase 7.2 — Tier 2 vendor shim disk cache (Agent A / S2).
- *
- * # Why this exists
- *
- * `buildVendorShims` produces four small-but-deterministic JS bundles:
- *   - `_vendor-react.js` / `_vendor-react-dom.js` / `_vendor-react-refresh.js`
- *     / `_fast-refresh-runtime.js` (+ two JSX runtimes).
- *
- * The inputs are the upstream npm versions of `react` / `react-dom` /
- * `react-refresh` plus the shim source strings we hard-code in `build.ts`.
- * If none of those change, re-running Bun.build yields byte-identical output
- * — but it still costs ~100-160 ms (Windows) because `Bun.build` has to parse
- * and resolve each shim fresh every boot.
- *
- * Cold-start breakdown (`docs/bun/phase-7-1-diagnostics/cold-start-breakdown.md`
- * §3.B and §5 Tier 2) attributes ~80-120 ms of the 910 ms tmpdir cold start
- * to these rebuilds. Cache hit on warm workflow eliminates that cost.
- *
- * # Design
- *
- * - **Single atomic manifest** at `.mandu/vendor-cache/vendor-cache.json`.
- *   Any mismatch → *every* cached output is treated as invalid and
- *   `buildVendorShims` runs its full parallel build path. We do not support
- *   per-entry invalidation because the outputs always move together (they
- *   share the same React version).
- *
- * - **Five-part hash input** (order-preserved):
- *     1. `Bun.version` (runtime semantics may change between minor bumps)
- *     2. resolved `react/package.json.version`
- *     3. resolved `react-dom/package.json.version`
- *     4. resolved `react-refresh/package.json.version`
- *     5. `@mandujs/core/package.json.version` (shim source evolves with Mandu)
- *
- *   Any of the five differing triggers a cold path. See the §6 risk section
- *   of `docs/bun/phase-7-2-team-plan.md`.
- *
- * - **SHA-256 per entry** for tamper detection. If an output file was
- *   truncated / edited / corrupted, the cached-hit path refuses to use it
- *   and falls through to the full rebuild. `size` is a cheaper first-pass
- *   check so we avoid hashing every byte for the common case.
- *
- * - **NO concurrency**: dev servers are single-process, so write-after-read
- *   races don't happen. Two concurrent `mandu dev` invocations on the same
- *   project WILL step on each other — this is the same story as the pre-
- *   existing `.mandu/dev-cache/ssr` directory used by the SSR bundled
- *   importer, which is also single-writer.
- *
- * - **Gitignored location**: `.mandu/` is already in the starter's
- *   `.gitignore`, so branch switches preserve the cache but a hard clean
- *   (`git clean -fdx`) triggers a rebuild — intentional because hard-cleaned
- *   trees should not trust stale artifacts.
- *
- * # Error handling
- *
- * Every I/O path swallows errors by falling back to miss:
- *   - manifest read fails → miss "no-manifest"
- *   - JSON parse fails → miss "no-manifest" (treat as absent)
- *   - any `fs.stat` / hash mismatch → miss "missing-entry" / "hash-mismatch"
- *
- * The writer is best-effort: if writing the manifest or a cached entry
- * fails, we log via perf (opt-in) but never block the build. Next boot
- * will either find a complete cache or hit a miss and rebuild.
- *
- * References:
- *   docs/bun/phase-7-2-team-plan.md §2.2
- *   docs/bun/phase-7-1-diagnostics/cold-start-breakdown.md §§3.B, 5
- *   packages/core/src/bundler/vendor-cache-types.ts (the contract)
- */
-
-import fs from "fs/promises";
-import path from "path";
-import { createHash } from "node:crypto";
-import {
-  type VendorCacheManifest,
-  type VendorCacheResult,
-  type VendorCacheEntry,
-  VENDOR_CACHE_DIR,
-  VENDOR_CACHE_FILENAME,
-  VENDOR_CACHE_MAX_BYTES,
-} from "./vendor-cache-types";
-
-// ============================================
-// Public API
-// ============================================
-
-/**
- * Input to {@link readVendorCache} and {@link writeVendorCache}. Callers
- * resolve these versions once (at the start of `buildVendorShims`) and
- * pass them to both functions so the hash input is stable.
- */
-export interface VendorCacheKeyInput {
-  bunVersion: string;
-  reactVersion: string;
-  reactDomVersion: string;
-  reactRefreshVersion: string;
-  manduCoreVersion: string;
-}
-
-/**
- * Logical id → on-disk filename map. Must stay in lock-step with
- * `buildVendorShims` in `build.ts`: any new shim added there needs its
- * logical id registered here so the cache knows which file to
- * preserve/restore.
- */
-export const VENDOR_SHIM_FILES: Record<string, string> = {
-  "react": "_react.js",
-  "react-dom": "_react-dom.js",
-  "react-dom-client": "_react-dom-client.js",
-  "jsx-runtime": "_jsx-runtime.js",
-  "jsx-dev-runtime": "_jsx-dev-runtime.js",
-  "react-refresh-runtime": "_vendor-react-refresh.js",
-  "fast-refresh-glue": "_fast-refresh-runtime.js",
-} as const;
-
-/** Keys of {@link VENDOR_SHIM_FILES}. */
-export type VendorShimId = keyof typeof VENDOR_SHIM_FILES;
-
-// ============================================
-// Read path
-// ============================================
-
-/**
- * Try to load the vendor cache for `rootDir`. Returns `hit` only when:
- *   1. The manifest file exists and parses cleanly.
- *   2. Every version field matches the requested inputs.
- *   3. Every entry's file exists, has the recorded size, and hashes back
- *      to the stored SHA-256.
- *
- * All other cases return a typed `miss` so the caller can decide what to
- * log (perf markers fire here so a diagnostic pass doesn't need to read
- * the result type).
- *
- * The manifest is consulted at boot only — no lazy / partial reads. A
- * "size" field > {@link VENDOR_CACHE_MAX_BYTES} is treated as a miss so
- * pathological disk corruption can't feed a nonsensical 10 GB file into
- * a hash round-trip.
- */
-export async function readVendorCache(
-  rootDir: string,
-  keys: VendorCacheKeyInput,
-): Promise<VendorCacheResult> {
-  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
-  const manifestPath = path.join(cacheDir, VENDOR_CACHE_FILENAME);
-
-  let rawManifest: string;
-  try {
-    rawManifest = await fs.readFile(manifestPath, "utf-8");
-  } catch {
-    return { kind: "miss", reason: "no-manifest" };
-  }
-
-  let manifest: VendorCacheManifest;
-  try {
-    manifest = JSON.parse(rawManifest) as VendorCacheManifest;
-  } catch {
-    // Corrupt / partial write — treat as absent.
-    return { kind: "miss", reason: "no-manifest" };
-  }
-
-  // Format version — reject unknown schemas (future-proofing).
-  if (manifest.version !== 1) {
-    return { kind: "miss", reason: "format-version" };
-  }
-
-  // Version comparison — any mismatch invalidates everything.
-  const versionCheck = compareVersions(manifest, keys);
-  if (versionCheck !== null) {
-    return {
-      kind: "miss",
-      reason: "version-mismatch",
-      mismatchedField: versionCheck,
-    };
-  }
-
-  // Size check (cheap) before hash check (expensive).
-  for (const [logicalId, entry] of Object.entries(manifest.entries)) {
-    const entryPath = path.join(cacheDir, entry.path);
-    let stat;
-    try {
-      stat = await fs.stat(entryPath);
-    } catch {
-      return { kind: "miss", reason: "missing-entry" };
-    }
-
-    if (stat.size !== entry.size) {
-      return { kind: "miss", reason: "size-mismatch" };
-    }
-
-    if (stat.size > VENDOR_CACHE_MAX_BYTES) {
-      // Pathological — refuse to read.
-      return { kind: "miss", reason: "size-mismatch" };
-    }
-
-    // Hash check — full read. Entries are small (~25 KB total today).
-    let buf;
-    try {
-      buf = await fs.readFile(entryPath);
-    } catch {
-      return { kind: "miss", reason: "missing-entry" };
-    }
-
-    const actualHash = sha256(buf);
-    if (actualHash !== entry.hash) {
-      return { kind: "miss", reason: "hash-mismatch" };
-    }
-
-    // Swallow unused loop variable to satisfy no-unused-vars.
-    void logicalId;
-  }
-
-  return { kind: "hit", manifest };
-}
-
-// ============================================
-// Write path
-// ============================================
-
-/**
- * Input for {@link writeVendorCache} — one entry per shim produced by
- * `buildVendorShims`. The `absPath` points at the freshly-built file in
- * `.mandu/client/` which we copy into the cache dir to avoid depending on
- * downstream `buildClientBundles` side-effects.
- */
-export interface VendorCacheWriteEntry {
-  logicalId: string;
-  /** Absolute path to the built shim in `.mandu/client/`. */
-  absPath: string;
-}
-
-/**
- * Persist the freshly-built shims + manifest to `.mandu/vendor-cache/`.
- *
- * - Creates the cache dir if missing.
- * - Copies each entry's file by bytes (not a symlink — Windows junction
- *   semantics differ between filesystems, and a hard-copy sidesteps the
- *   "rebuild deletes the original" GC hazard).
- * - Writes the manifest LAST so a crashed write leaves the cache in a
- *   safe state (missing-entry on next read → miss).
- *
- * Best-effort: returns `false` on any write failure but does not throw,
- * so the build continues even if the disk is read-only.
- */
-export async function writeVendorCache(
-  rootDir: string,
-  keys: VendorCacheKeyInput,
-  entries: VendorCacheWriteEntry[],
-): Promise<boolean> {
-  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
-
-  try {
-    await fs.mkdir(cacheDir, { recursive: true });
-  } catch {
-    return false;
-  }
-
-  const manifestEntries: Record<string, VendorCacheEntry> = {};
-
-  for (const entry of entries) {
-    let buf: Buffer;
-    try {
-      buf = await fs.readFile(entry.absPath);
-    } catch {
-      // Source file missing (build must have failed earlier) — skip
-      // this entry. An incomplete cache manifest is still safe because
-      // the read path checks every referenced entry.
-      continue;
-    }
-
-    if (buf.byteLength > VENDOR_CACHE_MAX_BYTES) {
-      continue;
-    }
-
-    const fileName = path.basename(entry.absPath);
-    const destPath = path.join(cacheDir, fileName);
-
-    try {
-      await fs.writeFile(destPath, buf);
-    } catch {
-      continue;
-    }
-
-    manifestEntries[entry.logicalId] = {
-      path: fileName,
-      size: buf.byteLength,
-      hash: sha256(buf),
-    };
-  }
-
-  // Nothing to cache → skip writing a stub manifest (would cause miss on
-  // next boot). Callers should interpret this as a best-effort success.
-  if (Object.keys(manifestEntries).length === 0) {
-    return false;
-  }
-
-  const manifest: VendorCacheManifest = {
-    version: 1,
-    bunVersion: keys.bunVersion,
-    reactVersion: keys.reactVersion,
-    reactDomVersion: keys.reactDomVersion,
-    reactRefreshVersion: keys.reactRefreshVersion,
-    manduCoreVersion: keys.manduCoreVersion,
-    entries: manifestEntries,
-    generatedAt: new Date().toISOString(),
-  };
-
-  try {
-    await fs.writeFile(
-      path.join(cacheDir, VENDOR_CACHE_FILENAME),
-      JSON.stringify(manifest, null, 2),
-    );
-  } catch {
-    return false;
-  }
-
-  return true;
-}
-
-// ============================================
-// Restore path — used on cache hit to re-populate `.mandu/client/`
-// ============================================
-
-/**
- * Copy every manifest-referenced file from the cache dir into `outDir`
- * (`.mandu/client/`). Returns the list of absolute output paths, in the
- * same order as the manifest's `entries` object iteration.
- *
- * Called on cache hit from `buildVendorShims` — skips re-running the
- * Bun.build calls entirely. If a copy fails (partial disk read, for
- * instance) the caller should fall back to rebuild — we return `null`
- * from this function in that case to make the degraded path explicit.
- */
-export async function restoreVendorCache(
-  rootDir: string,
-  manifest: VendorCacheManifest,
-  outDir: string,
-): Promise<Map<string, string> | null> {
-  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
-
-  try {
-    await fs.mkdir(outDir, { recursive: true });
-  } catch {
-    return null;
-  }
-
-  const result = new Map<string, string>();
-  for (const [logicalId, entry] of Object.entries(manifest.entries)) {
-    const src = path.join(cacheDir, entry.path);
-    const dst = path.join(outDir, path.basename(entry.path));
-    try {
-      const buf = await fs.readFile(src);
-      // Phase 7.2.R3 M-02 — TOCTOU hardening. `readVendorCache` already
-      // verified SHA-256/size, but an attacker with filesystem write
-      // access could swap `_vendor-*.js` between the read and this
-      // copy. Re-hash the buffer we are about to copy — if it diverges
-      // from the manifest entry, bail out and force rebuild instead of
-      // shipping attacker-controlled JS into `.mandu/client/`.
-      const actualSize = buf.byteLength;
-      if (actualSize !== entry.size) return null;
-      const actualHash = createHash("sha256").update(buf).digest("hex");
-      if (actualHash !== entry.hash) return null;
-      await fs.writeFile(dst, buf);
-      result.set(logicalId, dst);
-    } catch {
-      // Any partial failure invalidates the restore — caller rebuilds.
-      return null;
-    }
-  }
-
-  return result;
-}
-
-// ============================================
-// Key resolution — package.json probing
-// ============================================
-
-/**
- * Resolve the key input from a project root. Reads the requested npm
- * packages' `package.json` via Node resolution from `rootDir`, with a
- * fallback lookup through Bun's resolution if the standard path does
- * not apply (eg. monorepo hoisting).
- *
- * We do NOT use `require.resolve` — it isn't available under pure ESM
- * in Bun. Instead we read `node_modules/<name>/package.json` directly
- * and walk up the tree if needed.
- *
- * The `manduCoreVersion` is sourced from our own package.json at build
- * time (it's read through `import.meta.url`). This guards against the
- * project's own React/React-DOM being rebuilt against a newer Mandu
- * shim source.
- */
-export async function resolveVendorCacheKeys(
-  rootDir: string,
-): Promise<VendorCacheKeyInput> {
-  const bunVersion = typeof Bun !== "undefined" ? Bun.version : "0.0.0";
-
-  const [reactVersion, reactDomVersion, reactRefreshVersion, manduCoreVersion] =
-    await Promise.all([
-      resolvePackageVersion(rootDir, "react"),
-      resolvePackageVersion(rootDir, "react-dom"),
-      resolvePackageVersion(rootDir, "react-refresh"),
-      resolveManduCoreVersion(rootDir),
-    ]);
-
-  return {
-    bunVersion,
-    reactVersion,
-    reactDomVersion,
-    reactRefreshVersion,
-    manduCoreVersion,
-  };
-}
-
-/**
- * Walk up from `rootDir` looking for
- * `node_modules/<pkg>/package.json`, return its `version` field. Falls
- * back to `"unknown"` if nothing is found — intentional so missing a
- * dependency (eg. `react-refresh` in pure-SSR projects) doesn't
- * throw. A stable `"unknown"` value still permits cache reuse as long
- * as the project isn't mutated.
- */
-async function resolvePackageVersion(
-  rootDir: string,
-  pkgName: string,
-): Promise<string> {
-  let current = path.resolve(rootDir);
-  const { root } = path.parse(current);
-
-  // Cap the walk at 10 levels to avoid pathological symlink loops.
-  for (let i = 0; i < 10; i++) {
-    const candidate = path.join(
-      current,
-      "node_modules",
-      pkgName,
-      "package.json",
-    );
-    try {
-      const raw = await fs.readFile(candidate, "utf-8");
-      const parsed = JSON.parse(raw) as { version?: string };
-      if (typeof parsed.version === "string" && parsed.version.length > 0) {
-        return parsed.version;
-      }
-      return "unknown";
-    } catch {
-      // Not here — keep walking.
-    }
-
-    if (current === root) break;
-    const next = path.dirname(current);
-    if (next === current) break;
-    current = next;
-  }
-
-  return "unknown";
-}
-
-/**
- * Resolve `@mandujs/core` own version from the repo relative to this
- * source file. We can't reuse `resolvePackageVersion(rootDir, "@mandujs/core")`
- * because during local dev the core is linked through `workspace:*` and
- * doesn't exist in `<project>/node_modules` — it lives in the monorepo's
- * `packages/core/package.json`.
- */
-async function resolveManduCoreVersion(rootDir: string): Promise<string> {
-  // Try the project's own node_modules first (published install path).
-  const published = await resolvePackageVersion(rootDir, "@mandujs/core");
-  if (published !== "unknown") {
-    return published;
-  }
-
-  // Fallback: walk up from this source file. `import.meta.dir` is the
-  // directory containing this module. `<dir>/../../package.json` is
-  // `packages/core/package.json` in the monorepo layout.
-  try {
-    const corePackagePath = path.resolve(import.meta.dir, "..", "..", "package.json");
-    const raw = await fs.readFile(corePackagePath, "utf-8");
-    const parsed = JSON.parse(raw) as { version?: string; name?: string };
-    if (
-      parsed.name === "@mandujs/core" &&
-      typeof parsed.version === "string"
-    ) {
-      return parsed.version;
-    }
-  } catch {
-    // Fall through.
-  }
-
-  return "unknown";
-}
-
-// ============================================
-// Internal helpers
-// ============================================
-
-/**
- * Compare the manifest's version fields against the requested input.
- * Returns `null` on match, or the mismatched field name on miss. The
- * field names are restricted to the keys actually gated by the cache
- * key — `generatedAt` is NOT part of the hash input.
- */
-function compareVersions(
-  manifest: VendorCacheManifest,
-  keys: VendorCacheKeyInput,
-):
-  | null
-  | "bunVersion"
-  | "reactVersion"
-  | "reactDomVersion"
-  | "reactRefreshVersion"
-  | "manduCoreVersion" {
-  if (manifest.bunVersion !== keys.bunVersion) return "bunVersion";
-  if (manifest.reactVersion !== keys.reactVersion) return "reactVersion";
-  if (manifest.reactDomVersion !== keys.reactDomVersion) return "reactDomVersion";
-  if (manifest.reactRefreshVersion !== keys.reactRefreshVersion)
-    return "reactRefreshVersion";
-  if (manifest.manduCoreVersion !== keys.manduCoreVersion)
-    return "manduCoreVersion";
-  return null;
-}
-
-/** SHA-256 of a buffer, returned as a hex string. */
-function sha256(buf: Buffer | Uint8Array): string {
-  const h = createHash("sha256");
-  h.update(buf);
-  return h.digest("hex");
-}
+/**
+ * Phase 7.2 — Tier 2 vendor shim disk cache (Agent A / S2).
+ *
+ * # Why this exists
+ *
+ * `buildVendorShims` produces four small-but-deterministic JS bundles:
+ *   - `_vendor-react.js` / `_vendor-react-dom.js` / `_vendor-react-refresh.js`
+ *     / `_fast-refresh-runtime.js` (+ two JSX runtimes).
+ *
+ * The inputs are the upstream npm versions of `react` / `react-dom` /
+ * `react-refresh` plus the shim source strings we hard-code in `build.ts`.
+ * If none of those change, re-running Bun.build yields byte-identical output
+ * — but it still costs ~100-160 ms (Windows) because `Bun.build` has to parse
+ * and resolve each shim fresh every boot.
+ *
+ * Cold-start breakdown (`docs/bun/phase-7-1-diagnostics/cold-start-breakdown.md`
+ * §3.B and §5 Tier 2) attributes ~80-120 ms of the 910 ms tmpdir cold start
+ * to these rebuilds. Cache hit on warm workflow eliminates that cost.
+ *
+ * # Design
+ *
+ * - **Single atomic manifest** at `.mandu/vendor-cache/vendor-cache.json`.
+ *   Any mismatch → *every* cached output is treated as invalid and
+ *   `buildVendorShims` runs its full parallel build path. We do not support
+ *   per-entry invalidation because the outputs always move together (they
+ *   share the same React version).
+ *
+ * - **Five-part hash input** (order-preserved):
+ *     1. `Bun.version` (runtime semantics may change between minor bumps)
+ *     2. resolved `react/package.json.version`
+ *     3. resolved `react-dom/package.json.version`
+ *     4. resolved `react-refresh/package.json.version`
+ *     5. `@mandujs/core/package.json.version` (shim source evolves with Mandu)
+ *
+ *   Any of the five differing triggers a cold path. See the §6 risk section
+ *   of `docs/bun/phase-7-2-team-plan.md`.
+ *
+ * - **SHA-256 per entry** for tamper detection. If an output file was
+ *   truncated / edited / corrupted, the cached-hit path refuses to use it
+ *   and falls through to the full rebuild. `size` is a cheaper first-pass
+ *   check so we avoid hashing every byte for the common case.
+ *
+ * - **NO concurrency**: dev servers are single-process, so write-after-read
+ *   races don't happen. Two concurrent `mandu dev` invocations on the same
+ *   project WILL step on each other — this is the same story as the pre-
+ *   existing `.mandu/dev-cache/ssr` directory used by the SSR bundled
+ *   importer, which is also single-writer.
+ *
+ * - **Gitignored location**: `.mandu/` is already in the starter's
+ *   `.gitignore`, so branch switches preserve the cache but a hard clean
+ *   (`git clean -fdx`) triggers a rebuild — intentional because hard-cleaned
+ *   trees should not trust stale artifacts.
+ *
+ * # Error handling
+ *
+ * Every I/O path swallows errors by falling back to miss:
+ *   - manifest read fails → miss "no-manifest"
+ *   - JSON parse fails → miss "no-manifest" (treat as absent)
+ *   - any `fs.stat` / hash mismatch → miss "missing-entry" / "hash-mismatch"
+ *
+ * The writer is best-effort: if writing the manifest or a cached entry
+ * fails, we log via perf (opt-in) but never block the build. Next boot
+ * will either find a complete cache or hit a miss and rebuild.
+ *
+ * References:
+ *   docs/bun/phase-7-2-team-plan.md §2.2
+ *   docs/bun/phase-7-1-diagnostics/cold-start-breakdown.md §§3.B, 5
+ *   packages/core/src/bundler/vendor-cache-types.ts (the contract)
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import { createHash } from "node:crypto";
+import {
+  type VendorCacheManifest,
+  type VendorCacheResult,
+  type VendorCacheEntry,
+  VENDOR_CACHE_DIR,
+  VENDOR_CACHE_FILENAME,
+  VENDOR_CACHE_MAX_BYTES,
+} from "./vendor-cache-types";
+
+// ============================================
+// Public API
+// ============================================
+
+/**
+ * Input to {@link readVendorCache} and {@link writeVendorCache}. Callers
+ * resolve these versions once (at the start of `buildVendorShims`) and
+ * pass them to both functions so the hash input is stable.
+ */
+export interface VendorCacheKeyInput {
+  bunVersion: string;
+  reactVersion: string;
+  reactDomVersion: string;
+  reactRefreshVersion: string;
+  manduCoreVersion: string;
+}
+
+/**
+ * Logical id → on-disk filename map. Must stay in lock-step with
+ * `buildVendorShims` in `build.ts`: any new shim added there needs its
+ * logical id registered here so the cache knows which file to
+ * preserve/restore.
+ */
+export const VENDOR_SHIM_FILES: Record<string, string> = {
+  "react": "_react.js",
+  "react-dom": "_react-dom.js",
+  "react-dom-client": "_react-dom-client.js",
+  "jsx-runtime": "_jsx-runtime.js",
+  "jsx-dev-runtime": "_jsx-dev-runtime.js",
+  "react-refresh-runtime": "_vendor-react-refresh.js",
+  "fast-refresh-glue": "_fast-refresh-runtime.js",
+} as const;
+
+/** Keys of {@link VENDOR_SHIM_FILES}. */
+export type VendorShimId = keyof typeof VENDOR_SHIM_FILES;
+
+// ============================================
+// Read path
+// ============================================
+
+/**
+ * Try to load the vendor cache for `rootDir`. Returns `hit` only when:
+ *   1. The manifest file exists and parses cleanly.
+ *   2. Every version field matches the requested inputs.
+ *   3. Every entry's file exists, has the recorded size, and hashes back
+ *      to the stored SHA-256.
+ *
+ * All other cases return a typed `miss` so the caller can decide what to
+ * log (perf markers fire here so a diagnostic pass doesn't need to read
+ * the result type).
+ *
+ * The manifest is consulted at boot only — no lazy / partial reads. A
+ * "size" field > {@link VENDOR_CACHE_MAX_BYTES} is treated as a miss so
+ * pathological disk corruption can't feed a nonsensical 10 GB file into
+ * a hash round-trip.
+ */
+export async function readVendorCache(
+  rootDir: string,
+  keys: VendorCacheKeyInput,
+): Promise<VendorCacheResult> {
+  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
+  const manifestPath = path.join(cacheDir, VENDOR_CACHE_FILENAME);
+
+  let rawManifest: string;
+  try {
+    rawManifest = await fs.readFile(manifestPath, "utf-8");
+  } catch {
+    return { kind: "miss", reason: "no-manifest" };
+  }
+
+  let manifest: VendorCacheManifest;
+  try {
+    manifest = JSON.parse(rawManifest) as VendorCacheManifest;
+  } catch {
+    // Corrupt / partial write — treat as absent.
+    return { kind: "miss", reason: "no-manifest" };
+  }
+
+  // Format version — reject unknown schemas (future-proofing).
+  if (manifest.version !== 1) {
+    return { kind: "miss", reason: "format-version" };
+  }
+
+  // Version comparison — any mismatch invalidates everything.
+  const versionCheck = compareVersions(manifest, keys);
+  if (versionCheck !== null) {
+    return {
+      kind: "miss",
+      reason: "version-mismatch",
+      mismatchedField: versionCheck,
+    };
+  }
+
+  // Size check (cheap) before hash check (expensive).
+  for (const [logicalId, entry] of Object.entries(manifest.entries)) {
+    const entryPath = path.join(cacheDir, entry.path);
+    let stat;
+    try {
+      stat = await fs.stat(entryPath);
+    } catch {
+      return { kind: "miss", reason: "missing-entry" };
+    }
+
+    if (stat.size !== entry.size) {
+      return { kind: "miss", reason: "size-mismatch" };
+    }
+
+    if (stat.size > VENDOR_CACHE_MAX_BYTES) {
+      // Pathological — refuse to read.
+      return { kind: "miss", reason: "size-mismatch" };
+    }
+
+    // Hash check — full read. Entries are small (~25 KB total today).
+    let buf;
+    try {
+      buf = await fs.readFile(entryPath);
+    } catch {
+      return { kind: "miss", reason: "missing-entry" };
+    }
+
+    const actualHash = sha256(buf);
+    if (actualHash !== entry.hash) {
+      return { kind: "miss", reason: "hash-mismatch" };
+    }
+
+    // Swallow unused loop variable to satisfy no-unused-vars.
+    void logicalId;
+  }
+
+  return { kind: "hit", manifest };
+}
+
+// ============================================
+// Write path
+// ============================================
+
+/**
+ * Input for {@link writeVendorCache} — one entry per shim produced by
+ * `buildVendorShims`. The `absPath` points at the freshly-built file in
+ * `.mandu/client/` which we copy into the cache dir to avoid depending on
+ * downstream `buildClientBundles` side-effects.
+ */
+export interface VendorCacheWriteEntry {
+  logicalId: string;
+  /** Absolute path to the built shim in `.mandu/client/`. */
+  absPath: string;
+}
+
+/**
+ * Persist the freshly-built shims + manifest to `.mandu/vendor-cache/`.
+ *
+ * - Creates the cache dir if missing.
+ * - Copies each entry's file by bytes (not a symlink — Windows junction
+ *   semantics differ between filesystems, and a hard-copy sidesteps the
+ *   "rebuild deletes the original" GC hazard).
+ * - Writes the manifest LAST so a crashed write leaves the cache in a
+ *   safe state (missing-entry on next read → miss).
+ *
+ * Best-effort: returns `false` on any write failure but does not throw,
+ * so the build continues even if the disk is read-only.
+ */
+export async function writeVendorCache(
+  rootDir: string,
+  keys: VendorCacheKeyInput,
+  entries: VendorCacheWriteEntry[],
+): Promise<boolean> {
+  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
+
+  try {
+    await fs.mkdir(cacheDir, { recursive: true });
+  } catch {
+    return false;
+  }
+
+  const manifestEntries: Record<string, VendorCacheEntry> = {};
+
+  for (const entry of entries) {
+    let buf: Buffer;
+    try {
+      buf = await fs.readFile(entry.absPath);
+    } catch {
+      // Source file missing (build must have failed earlier) — skip
+      // this entry. An incomplete cache manifest is still safe because
+      // the read path checks every referenced entry.
+      continue;
+    }
+
+    if (buf.byteLength > VENDOR_CACHE_MAX_BYTES) {
+      continue;
+    }
+
+    const fileName = path.basename(entry.absPath);
+    const destPath = path.join(cacheDir, fileName);
+
+    try {
+      await fs.writeFile(destPath, buf);
+    } catch {
+      continue;
+    }
+
+    manifestEntries[entry.logicalId] = {
+      path: fileName,
+      size: buf.byteLength,
+      hash: sha256(buf),
+    };
+  }
+
+  // Nothing to cache → skip writing a stub manifest (would cause miss on
+  // next boot). Callers should interpret this as a best-effort success.
+  if (Object.keys(manifestEntries).length === 0) {
+    return false;
+  }
+
+  const manifest: VendorCacheManifest = {
+    version: 1,
+    bunVersion: keys.bunVersion,
+    reactVersion: keys.reactVersion,
+    reactDomVersion: keys.reactDomVersion,
+    reactRefreshVersion: keys.reactRefreshVersion,
+    manduCoreVersion: keys.manduCoreVersion,
+    entries: manifestEntries,
+    generatedAt: new Date().toISOString(),
+  };
+
+  try {
+    await fs.writeFile(
+      path.join(cacheDir, VENDOR_CACHE_FILENAME),
+      JSON.stringify(manifest, null, 2),
+    );
+  } catch {
+    return false;
+  }
+
+  return true;
+}
+
+// ============================================
+// Restore path — used on cache hit to re-populate `.mandu/client/`
+// ============================================
+
+/**
+ * Copy every manifest-referenced file from the cache dir into `outDir`
+ * (`.mandu/client/`). Returns the list of absolute output paths, in the
+ * same order as the manifest's `entries` object iteration.
+ *
+ * Called on cache hit from `buildVendorShims` — skips re-running the
+ * Bun.build calls entirely. If a copy fails (partial disk read, for
+ * instance) the caller should fall back to rebuild — we return `null`
+ * from this function in that case to make the degraded path explicit.
+ */
+export async function restoreVendorCache(
+  rootDir: string,
+  manifest: VendorCacheManifest,
+  outDir: string,
+): Promise<Map<string, string> | null> {
+  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
+
+  try {
+    await fs.mkdir(outDir, { recursive: true });
+  } catch {
+    return null;
+  }
+
+  const result = new Map<string, string>();
+  for (const [logicalId, entry] of Object.entries(manifest.entries)) {
+    const src = path.join(cacheDir, entry.path);
+    const dst = path.join(outDir, path.basename(entry.path));
+    try {
+      const buf = await fs.readFile(src);
+      // Phase 7.2.R3 M-02 — TOCTOU hardening. `readVendorCache` already
+      // verified SHA-256/size, but an attacker with filesystem write
+      // access could swap `_vendor-*.js` between the read and this
+      // copy. Re-hash the buffer we are about to copy — if it diverges
+      // from the manifest entry, bail out and force rebuild instead of
+      // shipping attacker-controlled JS into `.mandu/client/`.
+      const actualSize = buf.byteLength;
+      if (actualSize !== entry.size) return null;
+      const actualHash = createHash("sha256").update(buf).digest("hex");
+      if (actualHash !== entry.hash) return null;
+      await fs.writeFile(dst, buf);
+      result.set(logicalId, dst);
+    } catch {
+      // Any partial failure invalidates the restore — caller rebuilds.
+      return null;
+    }
+  }
+
+  return result;
+}
+
+// ============================================
+// Key resolution — package.json probing
+// ============================================
+
+/**
+ * Resolve the key input from a project root. Reads the requested npm
+ * packages' `package.json` via Node resolution from `rootDir`, with a
+ * fallback lookup through Bun's resolution if the standard path does
+ * not apply (eg. monorepo hoisting).
+ *
+ * We do NOT use `require.resolve` — it isn't available under pure ESM
+ * in Bun. Instead we read `node_modules/<name>/package.json` directly
+ * and walk up the tree if needed.
+ *
+ * The `manduCoreVersion` is sourced from our own package.json at build
+ * time (it's read through `import.meta.url`). This guards against the
+ * project's own React/React-DOM being rebuilt against a newer Mandu
+ * shim source.
+ */
+export async function resolveVendorCacheKeys(
+  rootDir: string,
+): Promise<VendorCacheKeyInput> {
+  const bunVersion = typeof Bun !== "undefined" ? Bun.version : "0.0.0";
+
+  const [reactVersion, reactDomVersion, reactRefreshVersion, manduCoreVersion] =
+    await Promise.all([
+      resolvePackageVersion(rootDir, "react"),
+      resolvePackageVersion(rootDir, "react-dom"),
+      resolvePackageVersion(rootDir, "react-refresh"),
+      resolveManduCoreVersion(rootDir),
+    ]);
+
+  return {
+    bunVersion,
+    reactVersion,
+    reactDomVersion,
+    reactRefreshVersion,
+    manduCoreVersion,
+  };
+}
+
+/**
+ * Walk up from `rootDir` looking for
+ * `node_modules/<pkg>/package.json`, return its `version` field. Falls
+ * back to `"unknown"` if nothing is found — intentional so missing a
+ * dependency (eg. `react-refresh` in pure-SSR projects) doesn't
+ * throw. A stable `"unknown"` value still permits cache reuse as long
+ * as the project isn't mutated.
+ */
+async function resolvePackageVersion(
+  rootDir: string,
+  pkgName: string,
+): Promise<string> {
+  let current = path.resolve(rootDir);
+  const { root } = path.parse(current);
+
+  // Cap the walk at 10 levels to avoid pathological symlink loops.
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(
+      current,
+      "node_modules",
+      pkgName,
+      "package.json",
+    );
+    try {
+      const raw = await fs.readFile(candidate, "utf-8");
+      const parsed = JSON.parse(raw) as { version?: string };
+      if (typeof parsed.version === "string" && parsed.version.length > 0) {
+        return parsed.version;
+      }
+      return "unknown";
+    } catch {
+      // Not here — keep walking.
+    }
+
+    if (current === root) break;
+    const next = path.dirname(current);
+    if (next === current) break;
+    current = next;
+  }
+
+  return "unknown";
+}
+
+/**
+ * Resolve `@mandujs/core` own version from the repo relative to this
+ * source file. We can't reuse `resolvePackageVersion(rootDir, "@mandujs/core")`
+ * because during local dev the core is linked through `workspace:*` and
+ * doesn't exist in `<project>/node_modules` — it lives in the monorepo's
+ * `packages/core/package.json`.
+ */
+async function resolveManduCoreVersion(rootDir: string): Promise<string> {
+  // Try the project's own node_modules first (published install path).
+  const published = await resolvePackageVersion(rootDir, "@mandujs/core");
+  if (published !== "unknown") {
+    return published;
+  }
+
+  // Fallback: walk up from this source file. `import.meta.dir` is the
+  // directory containing this module. `<dir>/../../package.json` is
+  // `packages/core/package.json` in the monorepo layout.
+  try {
+    const corePackagePath = path.resolve(import.meta.dir, "..", "..", "package.json");
+    const raw = await fs.readFile(corePackagePath, "utf-8");
+    const parsed = JSON.parse(raw) as { version?: string; name?: string };
+    if (
+      parsed.name === "@mandujs/core" &&
+      typeof parsed.version === "string"
+    ) {
+      return parsed.version;
+    }
+  } catch {
+    // Fall through.
+  }
+
+  return "unknown";
+}
+
+// ============================================
+// Internal helpers
+// ============================================
+
+/**
+ * Compare the manifest's version fields against the requested input.
+ * Returns `null` on match, or the mismatched field name on miss. The
+ * field names are restricted to the keys actually gated by the cache
+ * key — `generatedAt` is NOT part of the hash input.
+ */
+function compareVersions(
+  manifest: VendorCacheManifest,
+  keys: VendorCacheKeyInput,
+):
+  | null
+  | "bunVersion"
+  | "reactVersion"
+  | "reactDomVersion"
+  | "reactRefreshVersion"
+  | "manduCoreVersion" {
+  if (manifest.bunVersion !== keys.bunVersion) return "bunVersion";
+  if (manifest.reactVersion !== keys.reactVersion) return "reactVersion";
+  if (manifest.reactDomVersion !== keys.reactDomVersion) return "reactDomVersion";
+  if (manifest.reactRefreshVersion !== keys.reactRefreshVersion)
+    return "reactRefreshVersion";
+  if (manifest.manduCoreVersion !== keys.manduCoreVersion)
+    return "manduCoreVersion";
+  return null;
+}
+
+/** SHA-256 of a buffer, returned as a hex string. */
+function sha256(buf: Buffer | Uint8Array): string {
+  const h = createHash("sha256");
+  h.update(buf);
+  return h.digest("hex");
+}