@lark-apaas/fullstack-cli 1.1.60 → 1.1.61-alpha.20260818172555

package/templates/scripts/cache-generation-preflight.mjs

@@ -0,0 +1,1346 @@
+// Canonical preflight source. Template repositories receive this file verbatim.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function sha256(file) {
+  return crypto
+    .createHash('sha256')
+    .update(fs.readFileSync(file))
+    .digest('hex');
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function runtimeAbiHashes(runtime) {
+  if (
+    typeof runtime?.runtimeAbiHash !== 'string' ||
+    runtime.runtimeAbiHash.length === 0
+  ) {
+    throw new Error('MIAODA_CACHE_RUNTIME_MANIFEST_INVALID');
+  }
+  const compatible = runtime.compatibleRuntimeAbiHashes ?? [];
+  if (
+    !Array.isArray(compatible) ||
+    compatible.some(hash => typeof hash !== 'string' || hash.length === 0)
+  ) {
+    throw new Error('MIAODA_CACHE_RUNTIME_MANIFEST_INVALID');
+  }
+  return new Set([runtime.runtimeAbiHash, ...compatible]);
+}
+
+function listRegularFiles(root, cacheRoot) {
+  const files = [];
+  const visit = directory => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) {
+        throw new Error(`MIAODA_CACHE_GENERATION_SYMLINK_REJECTED: ${file}`);
+      }
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile()) files.push(path.relative(cacheRoot, file));
+    }
+  };
+  visit(root);
+  return files.sort();
+}
+
+const WORKSPACE_SOURCE_ROOTS = ['client', 'server', 'shared', 'src'];
+const WORKSPACE_SOURCE_FILES = [
+  '.env',
+  '.env.development',
+  '.env.development.local',
+  'drizzle.config.ts',
+  'nest-cli.json',
+  'postcss.config.js',
+  'postcss.config.cjs',
+  'postcss.config.mjs',
+  'tailwind.config.ts',
+  'tailwind.config.js',
+  'tailwind.config.cjs',
+  'tailwind.config.mjs',
+  'tsconfig.json',
+  'tsconfig.app.json',
+  'tsconfig.node.json',
+  'vite.config.ts',
+  'vite.config.mts',
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.cjs',
+];
+
+function listWorkspaceSourceFilePaths(projectRoot) {
+  const files = WORKSPACE_SOURCE_ROOTS.flatMap(relativeRoot => {
+    const root = path.join(projectRoot, relativeRoot);
+    return fs.existsSync(root) ? listRegularFiles(root, projectRoot) : [];
+  });
+  for (const relativeFile of WORKSPACE_SOURCE_FILES) {
+    const file = path.join(projectRoot, relativeFile);
+    if (!fs.existsSync(file)) continue;
+    if (fs.lstatSync(file).isSymbolicLink() || !fs.statSync(file).isFile()) {
+      throw new Error(`MIAODA_WORKSPACE_SOURCE_FILE_REJECTED: ${file}`);
+    }
+    files.push(relativeFile);
+  }
+  return [...new Set(files)].sort();
+}
+
+function listWorkspaceSourceFiles(projectRoot) {
+  return listWorkspaceSourceFilePaths(projectRoot).map(relativeFile => {
+    const file = path.join(projectRoot, ...relativeFile.split('/'));
+    return {
+      path: relativeFile.split(path.sep).join('/'),
+      sha256: sha256(file),
+      size: fs.statSync(file).size,
+    };
+  });
+}
+
+function workspaceSourceFileInScope(relativePath, artifactScope) {
+  if (artifactScope === 'all') return true;
+  if (relativePath === 'client' || relativePath.startsWith('client/')) {
+    return artifactScope === 'vite';
+  }
+  if (relativePath === 'server' || relativePath.startsWith('server/')) {
+    return artifactScope === 'server';
+  }
+  // shared/, src/ and root config files may be consumed by either build.
+  return true;
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return value.map(canonicalJson);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalJson(child)])
+    );
+  }
+  return value;
+}
+
+function stableServerMetadataIdentity(serverMetadata) {
+  const availabilityProbe = serverMetadata?.availabilityProbe ?? {};
+  const checks = Array.isArray(availabilityProbe.checks)
+    ? availabilityProbe.checks.map(check => {
+        const { elapsedMs: _elapsedMs, ...stableCheck } = check;
+        return stableCheck;
+      })
+    : availabilityProbe.checks;
+  const {
+    startupMs: _startupMs,
+    stdout: _stdout,
+    stderr: _stderr,
+    ...stableProbe
+  } = availabilityProbe;
+  return canonicalJson({
+    ...serverMetadata,
+    availabilityProbe: { ...stableProbe, checks },
+  });
+}
+
+function jsonIdentity(value) {
+  const content = JSON.stringify(value);
+  return {
+    sha256: crypto.createHash('sha256').update(content).digest('hex'),
+    size: Buffer.byteLength(content),
+  };
+}
+
+function serverDependenciesAreConsumable(serverDependencies) {
+  if (
+    serverDependencies?.schemaVersion !== 1 ||
+    typeof serverDependencies?.sourceEntry !== 'string' ||
+    !serverDependencies.sourceEntry ||
+    !Array.isArray(serverDependencies?.bootstrapModules) ||
+    serverDependencies.bootstrapModules.length === 0 ||
+    !serverDependencies?.transitionCompilerOptions ||
+    typeof serverDependencies.transitionCompilerOptions !== 'object' ||
+    Array.isArray(serverDependencies.transitionCompilerOptions) ||
+    !Array.isArray(serverDependencies?.packages) ||
+    serverDependencies.packages.length === 0 ||
+    !Array.isArray(serverDependencies?.actionPlugins) ||
+    !Array.isArray(serverDependencies?.files) ||
+    serverDependencies.files.length === 0 ||
+    !/^[a-f0-9]{64}$/.test(serverDependencies?.treeSha256 || '') ||
+    serverDependencies.fileCount !== serverDependencies.files.length ||
+    !Number.isSafeInteger(serverDependencies.totalBytes) ||
+    serverDependencies.totalBytes <= 0
+  ) {
+    return false;
+  }
+  const validPackages = packages =>
+    packages.every(
+      pkg =>
+        typeof pkg?.name === 'string' &&
+        pkg.name &&
+        typeof pkg?.version === 'string' &&
+        pkg.version
+    );
+  const paths = new Set();
+  const validFiles = serverDependencies.files.every(file => {
+    if (
+      typeof file?.path !== 'string' ||
+      !file.path ||
+      file.path !== path.posix.normalize(file.path) ||
+      file.path === '.' ||
+      file.path.startsWith('../') ||
+      path.posix.isAbsolute(file.path) ||
+      file.path.includes('\\') ||
+      paths.has(file.path) ||
+      !/^[a-f0-9]{64}$/.test(file?.sha256 || '') ||
+      !Number.isSafeInteger(file?.size) ||
+      file.size < 0
+    ) {
+      return false;
+    }
+    paths.add(file.path);
+    return true;
+  });
+  return (
+    validPackages(serverDependencies.packages) &&
+    validPackages(serverDependencies.actionPlugins) &&
+    validFiles &&
+    crypto
+      .createHash('sha256')
+      .update(JSON.stringify(serverDependencies.files))
+      .digest('hex') === serverDependencies.treeSha256 &&
+    serverDependencies.files.reduce((total, file) => total + file.size, 0) ===
+      serverDependencies.totalBytes
+  );
+}
+
+function compactServerDependencies(serverDependencies) {
+  if (!serverDependencies) return undefined;
+  const { files: _files, ...compact } = serverDependencies;
+  return compact;
+}
+
+function compactServerDependenciesAreConsumable(serverDependencies) {
+  return (
+    serverDependencies?.schemaVersion === 1 &&
+    typeof serverDependencies?.sourceEntry === 'string' &&
+    serverDependencies.sourceEntry.length > 0 &&
+    Array.isArray(serverDependencies?.bootstrapModules) &&
+    serverDependencies.bootstrapModules.length > 0 &&
+    serverDependencies?.transitionCompilerOptions &&
+    typeof serverDependencies.transitionCompilerOptions === 'object' &&
+    !Array.isArray(serverDependencies.transitionCompilerOptions) &&
+    Array.isArray(serverDependencies?.packages) &&
+    serverDependencies.packages.length > 0 &&
+    Array.isArray(serverDependencies?.actionPlugins) &&
+    /^[a-f0-9]{64}$/.test(serverDependencies?.treeSha256 || '') &&
+    Number.isSafeInteger(serverDependencies.fileCount) &&
+    serverDependencies.fileCount > 0 &&
+    Number.isSafeInteger(serverDependencies.totalBytes) &&
+    serverDependencies.totalBytes > 0
+  );
+}
+
+function workspaceBuildInputs(projectRoot) {
+  const packageJsonFile = path.join(projectRoot, 'package.json');
+  const packageJson = fs.existsSync(packageJsonFile)
+    ? readJson(packageJsonFile)
+    : {};
+  return {
+    actionPlugins: canonicalJson(packageJson.actionPlugins ?? {}),
+  };
+}
+
+function packageNameFromOptimizerId(id) {
+  const specifier = id.split(' > ').at(-1) || id;
+  if (
+    !specifier ||
+    specifier.startsWith('.') ||
+    specifier.startsWith('/') ||
+    specifier.startsWith('\0') ||
+    specifier.includes('://')
+  ) {
+    return undefined;
+  }
+  const parts = specifier.split('/');
+  return specifier.startsWith('@')
+    ? parts.length >= 2
+      ? `${parts[0]}/${parts[1]}`
+      : undefined
+    : parts[0];
+}
+
+function isPathInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === '' ||
+    (!relative.startsWith('..') && !path.isAbsolute(relative))
+  );
+}
+
+function optimizerEntryUsesRuntimePackage({
+  projectRoot,
+  runtimeManifestFile,
+  runtime,
+  packageName,
+  entry,
+}) {
+  const variants = runtime.packages?.[packageName];
+  if (!Array.isArray(variants) || variants.length === 0) return false;
+  if (typeof entry?.src !== 'string' || !entry.src) return false;
+
+  const source = path.isAbsolute(entry.src)
+    ? entry.src
+    : path.resolve(projectRoot, entry.src);
+  if (!fs.existsSync(source)) return false;
+  const realSource = fs.realpathSync(source);
+  const runtimeRoot = path.dirname(path.resolve(runtimeManifestFile));
+  return variants.some(variant => {
+    if (typeof variant.relativePath !== 'string' || !variant.relativePath) {
+      return false;
+    }
+    const packageRoot = path.resolve(runtimeRoot, variant.relativePath);
+    if (
+      !isPathInside(runtimeRoot, packageRoot) ||
+      !fs.existsSync(packageRoot)
+    ) {
+      return false;
+    }
+    return isPathInside(fs.realpathSync(packageRoot), realSource);
+  });
+}
+
+function resolveArtifact(cacheRoot, artifact) {
+  if (
+    !artifact?.path ||
+    !artifact?.sha256 ||
+    !Number.isSafeInteger(artifact?.size) ||
+    artifact.size < 0
+  ) {
+    throw new Error('MIAODA_CACHE_GENERATION_ARTIFACT_INVALID');
+  }
+  const file = path.resolve(cacheRoot, artifact.path);
+  if (file !== cacheRoot && !file.startsWith(`${cacheRoot}${path.sep}`)) {
+    throw new Error(`MIAODA_CACHE_GENERATION_PATH_ESCAPE: ${artifact.path}`);
+  }
+  if (
+    !fs.existsSync(file) ||
+    fs.lstatSync(file).isSymbolicLink() ||
+    fs.statSync(file).size !== artifact.size ||
+    sha256(file) !== artifact.sha256
+  ) {
+    throw new Error(`MIAODA_CACHE_GENERATION_SHA_MISMATCH: ${file}`);
+  }
+  const realFile = fs.realpathSync(file);
+  if (!isPathInside(cacheRoot, realFile)) {
+    throw new Error(`MIAODA_CACHE_GENERATION_PATH_ESCAPE: ${artifact.path}`);
+  }
+  return realFile;
+}
+
+function validateClientConfigFiles(projectRoot, appRuntime) {
+  const configFiles = appRuntime.clientDependencyGraph?.configFiles;
+  if (!Array.isArray(configFiles)) {
+    throw new Error('MIAODA_CACHE_CLIENT_CONFIG_FILES_INVALID');
+  }
+  const realProjectRoot = fs.realpathSync(projectRoot);
+  const sealedPaths = new Set();
+  for (const configFile of configFiles) {
+    const relativePath = configFile?.path;
+    if (
+      typeof relativePath !== 'string' ||
+      !relativePath ||
+      relativePath !== path.posix.normalize(relativePath) ||
+      relativePath === '.' ||
+      relativePath.startsWith('../') ||
+      path.posix.isAbsolute(relativePath) ||
+      relativePath.includes('\\') ||
+      sealedPaths.has(relativePath) ||
+      !/^[a-f0-9]{64}$/.test(configFile?.sha256 || '')
+    ) {
+      throw new Error('MIAODA_CACHE_CLIENT_CONFIG_FILES_INVALID');
+    }
+    sealedPaths.add(relativePath);
+    const absolutePath = path.join(projectRoot, ...relativePath.split('/'));
+    let currentPath = projectRoot;
+    for (const segment of relativePath.split('/')) {
+      currentPath = path.join(currentPath, segment);
+      if (
+        !fs.existsSync(currentPath) ||
+        fs.lstatSync(currentPath).isSymbolicLink()
+      ) {
+        throw new Error('MIAODA_CACHE_CLIENT_CONFIG_FILE_MISMATCH');
+      }
+    }
+    if (!fs.statSync(absolutePath).isFile()) {
+      throw new Error('MIAODA_CACHE_CLIENT_CONFIG_FILE_MISMATCH');
+    }
+    const realFile = fs.realpathSync(absolutePath);
+    if (!isPathInside(realProjectRoot, realFile)) {
+      throw new Error('MIAODA_CACHE_CLIENT_CONFIG_FILE_MISMATCH');
+    }
+    const actualHash = crypto
+      .createHash('sha256')
+      .update(fs.readFileSync(realFile))
+      .digest('hex');
+    if (actualHash !== configFile.sha256) {
+      throw new Error('MIAODA_CACHE_CLIENT_CONFIG_FILE_MISMATCH');
+    }
+  }
+  const fixedNames = [
+    'vite.config.ts',
+    'vite.config.mts',
+    'vite.config.js',
+    'vite.config.mjs',
+    'vite.config.cjs',
+    'postcss.config.js',
+    'postcss.config.cjs',
+    'postcss.config.mjs',
+    'tailwind.config.ts',
+    'tailwind.config.js',
+    'tailwind.config.cjs',
+    'tailwind.config.mjs',
+    'tsconfig.json',
+    'tsconfig.app.json',
+    'tsconfig.node.json',
+    '.env',
+    '.env.development',
+    '.env.development.local',
+  ];
+  const currentEntrypoints = fixedNames.filter(name =>
+    fs.existsSync(path.join(projectRoot, name))
+  );
+  const visitPatchFiles = relativeDirectory => {
+    const absoluteDirectory = path.join(projectRoot, relativeDirectory);
+    if (!fs.existsSync(absoluteDirectory)) return;
+    for (const entry of fs.readdirSync(absoluteDirectory, {
+      withFileTypes: true,
+    })) {
+      if (entry.isSymbolicLink()) {
+        throw new Error('MIAODA_CACHE_CLIENT_CONFIG_FILE_MISMATCH');
+      }
+      const child = path.posix.join(relativeDirectory, entry.name);
+      if (entry.isDirectory()) visitPatchFiles(child);
+      else if (entry.isFile()) currentEntrypoints.push(child);
+    }
+  };
+  visitPatchFiles('patches');
+  visitPatchFiles('.yarn/patches');
+  if (currentEntrypoints.some(relativePath => !sealedPaths.has(relativePath))) {
+    throw new Error('MIAODA_CACHE_CLIENT_CONFIG_FILE_SET_MISMATCH');
+  }
+}
+
+function validateClientConfigEnvironment(appRuntime) {
+  for (const [name, expectedHash] of Object.entries(
+    appRuntime.clientDependencyGraph.configEnvironment || {}
+  )) {
+    const actualHash = crypto
+      .createHash('sha256')
+      .update(process.env[name] || '')
+      .digest('hex');
+    if (actualHash !== expectedHash) {
+      throw new Error(
+        `MIAODA_CACHE_CLIENT_CONFIG_ENVIRONMENT_MISMATCH: ${name}`
+      );
+    }
+  }
+}
+
+const VALIDATION_RECEIPT_SCHEMA_VERSION = 3;
+const VALIDATION_RECEIPT_MAX_BYTES = 1024 * 1024;
+const VALIDATION_RECEIPT_MAX_AGE_MS = 5 * 60 * 1000;
+
+function statIdentity(file) {
+  const stat = fs.lstatSync(file, { bigint: true });
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`MIAODA_CACHE_VALIDATION_RECEIPT_FILE_REJECTED: ${file}`);
+  }
+  return {
+    dev: String(stat.dev),
+    ino: String(stat.ino),
+    mode: String(stat.mode),
+    size: String(stat.size),
+    mtimeNs: String(stat.mtimeNs),
+    ctimeNs: String(stat.ctimeNs),
+  };
+}
+
+function receiptFileDescriptor(
+  { projectRoot, cacheRoot, runtimeManifestFile },
+  file
+) {
+  const resolvedFile = path.resolve(file);
+  if (isPathInside(cacheRoot, resolvedFile)) {
+    return { root: 'cache', path: path.relative(cacheRoot, resolvedFile) };
+  }
+  if (isPathInside(projectRoot, resolvedFile)) {
+    return { root: 'project', path: path.relative(projectRoot, resolvedFile) };
+  }
+  if (resolvedFile === runtimeManifestFile) {
+    return { root: 'runtime-manifest', path: '' };
+  }
+  throw new Error(`MIAODA_CACHE_VALIDATION_RECEIPT_PATH_REJECTED: ${file}`);
+}
+
+function resolveReceiptFile(
+  { projectRoot, cacheRoot, runtimeManifestFile },
+  descriptor
+) {
+  let root;
+  if (descriptor?.root === 'cache') root = cacheRoot;
+  else if (descriptor?.root === 'project') root = projectRoot;
+  else if (descriptor?.root === 'runtime-manifest') {
+    if (descriptor.path !== '') {
+      throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+    }
+    return runtimeManifestFile;
+  } else {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+  }
+  if (
+    typeof descriptor.path !== 'string' ||
+    descriptor.path !== path.normalize(descriptor.path) ||
+    descriptor.path === '..' ||
+    descriptor.path.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(descriptor.path)
+  ) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+  }
+  const file = path.resolve(root, descriptor.path);
+  if (!isPathInside(root, file)) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+  }
+  return file;
+}
+
+function receiptId(receiptWithoutId) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(canonicalJson(receiptWithoutId)))
+    .digest('hex');
+}
+
+function compactReceiptGeneration(generation) {
+  return {
+    schemaVersion: generation.schemaVersion,
+    generationId: generation.generationId,
+    runtimeAbiHash: generation.runtimeAbiHash,
+    applicationKind: generation.applicationKind,
+    serverRuntime: generation.serverRuntime,
+    serverRuntimeMode: generation.serverRuntimeMode,
+    artifacts: generation.artifacts,
+  };
+}
+
+function resolveReceiptCacheArtifact(cacheRoot, artifact) {
+  if (typeof artifact?.path !== 'string' || !artifact.path) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+  }
+  const file = path.resolve(cacheRoot, artifact.path);
+  if (!isPathInside(cacheRoot, file)) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_PATH_REJECTED');
+  }
+  const realFile = fs.realpathSync(file);
+  if (!isPathInside(cacheRoot, realFile)) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_PATH_REJECTED');
+  }
+  return realFile;
+}
+
+export function writeCacheGenerationValidationReceipt({
+  validated,
+  receiptFile,
+}) {
+  const artifactScope = validated?.validation?.artifactScope;
+  if (
+    !['all', 'server', 'vite'].includes(artifactScope) ||
+    !validated?.generation?.generationId
+  ) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_SCOPE_REJECTED');
+  }
+  const roots = {
+    projectRoot: fs.realpathSync(validated.projectRoot),
+    cacheRoot: fs.realpathSync(validated.cacheRoot),
+    runtimeManifestFile: fs.realpathSync(validated.runtimeManifestFile),
+  };
+  const controlFiles = new Map();
+  const addControlFile = file => {
+    const resolvedFile = path.resolve(file);
+    controlFiles.set(resolvedFile, true);
+  };
+  addControlFile(validated.generationFile);
+  addControlFile(roots.runtimeManifestFile);
+  for (const file of Object.values(validated.artifacts)) addControlFile(file);
+  const controls = Array.from(controlFiles.keys())
+    .sort((left, right) => left.localeCompare(right))
+    .map(file => ({
+      ...receiptFileDescriptor(roots, file),
+      stat: statIdentity(file),
+    }));
+  const receiptWithoutId = {
+    schemaVersion: VALIDATION_RECEIPT_SCHEMA_VERSION,
+    validatedAtMs: Date.now(),
+    artifactScope,
+    roots,
+    generationId: validated.generation.generationId,
+    controls,
+    validated: {
+      generation: compactReceiptGeneration(validated.generation),
+      runtime: validated.runtime,
+      serverMetadata: validated.serverMetadata,
+      serverDependencies: compactServerDependencies(
+        validated.serverDependencies
+      ),
+      appRuntime: validated.appRuntime,
+    },
+  };
+  const receipt = {
+    ...receiptWithoutId,
+    receiptId: receiptId(receiptWithoutId),
+  };
+  const resolvedReceiptFile = path.resolve(receiptFile);
+  fs.mkdirSync(path.dirname(resolvedReceiptFile), { recursive: true });
+  const temporaryFile = `${resolvedReceiptFile}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporaryFile, `${JSON.stringify(receipt)}\n`, {
+      mode: 0o600,
+      flag: 'wx',
+    });
+    fs.renameSync(temporaryFile, resolvedReceiptFile);
+  } finally {
+    fs.rmSync(temporaryFile, { force: true });
+  }
+  return receipt;
+}
+
+// The image-owned preflight hashes every artifact and source once. Serving
+// runtimes consume this short-lived receipt without walking the workspace or
+// sealed dependency tree again. Only the generation control plane (manifest,
+// runtime ABI metadata and named artifact descriptors) is identity-checked.
+// Publication of a new generation, control-file mutation, or stale/malformed
+// receipt is a cache miss and callers fall back to the original SHA validation.
+export function validateCacheGenerationReceipt({
+  projectRoot,
+  cacheRoot,
+  runtimeManifestFile,
+  receiptFile,
+  validateConfigEnvironment = true,
+  artifactScope = 'all',
+}) {
+  if (!['all', 'server', 'vite'].includes(artifactScope)) {
+    throw new Error('MIAODA_CACHE_VALIDATION_SCOPE_INVALID');
+  }
+  const roots = {
+    projectRoot: fs.realpathSync(path.resolve(projectRoot)),
+    cacheRoot: fs.realpathSync(path.resolve(cacheRoot)),
+    runtimeManifestFile: fs.realpathSync(path.resolve(runtimeManifestFile)),
+  };
+  const resolvedReceiptFile = path.resolve(receiptFile);
+  const receiptStat = fs.lstatSync(resolvedReceiptFile);
+  if (
+    receiptStat.isSymbolicLink() ||
+    !receiptStat.isFile() ||
+    (receiptStat.mode & 0o022) !== 0 ||
+    receiptStat.size > VALIDATION_RECEIPT_MAX_BYTES
+  ) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+  }
+  const receipt = readJson(resolvedReceiptFile);
+  const { receiptId: actualReceiptId, ...receiptWithoutId } = receipt;
+  // Receipts produced before scoped validation existed covered the full
+  // generation. A scoped receipt may only be consumed by the same artifact
+  // runtime; otherwise a server-only check could accidentally authorize Vite
+  // files (or vice versa) that were never validated.
+  const receiptArtifactScope = receipt.artifactScope || 'all';
+  const receiptCoversRequestedScope =
+    receiptArtifactScope === 'all' || receiptArtifactScope === artifactScope;
+  if (
+    receipt.schemaVersion !== VALIDATION_RECEIPT_SCHEMA_VERSION ||
+    !/^[a-f0-9]{64}$/.test(actualReceiptId || '') ||
+    receiptId(receiptWithoutId) !== actualReceiptId ||
+    !Number.isSafeInteger(receipt.validatedAtMs) ||
+    receipt.validatedAtMs > Date.now() + 5_000 ||
+    Date.now() - receipt.validatedAtMs > VALIDATION_RECEIPT_MAX_AGE_MS ||
+    JSON.stringify(receipt.roots) !== JSON.stringify(roots) ||
+    !['all', 'server', 'vite'].includes(receiptArtifactScope) ||
+    !receiptCoversRequestedScope
+  ) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+  }
+  const {
+    generation,
+    runtime,
+    serverMetadata,
+    serverDependencies,
+    appRuntime,
+  } = receipt.validated || {};
+  const applicationKind =
+    generation?.applicationKind === 'frontend-only'
+      ? 'frontend-only'
+      : 'fullstack';
+  if (
+    ![3, 4].includes(generation?.schemaVersion) ||
+    generation.generationId !== receipt.generationId ||
+    !runtimeAbiHashes(runtime).has(generation.runtimeAbiHash)
+  ) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_MISMATCH');
+  }
+  if (artifactScope === 'server' && applicationKind === 'frontend-only') {
+    throw new Error('MIAODA_CACHE_SERVER_ARTIFACT_NOT_AVAILABLE');
+  }
+  if (
+    /^[a-f0-9]{64}$/.test(path.basename(roots.cacheRoot)) &&
+    path.basename(roots.cacheRoot) !== generation.generationId
+  ) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_MISMATCH');
+  }
+  if (
+    !Array.isArray(receipt.controls) ||
+    receipt.controls.length === 0 ||
+    receipt.controls.length > 64
+  ) {
+    throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+  }
+  for (const descriptor of receipt.controls) {
+    const file = resolveReceiptFile(roots, descriptor);
+    if (
+      JSON.stringify(statIdentity(file)) !== JSON.stringify(descriptor.stat)
+    ) {
+      throw new Error(`MIAODA_CACHE_VALIDATION_RECEIPT_FILE_CHANGED: ${file}`);
+    }
+    const realFile = fs.realpathSync(file);
+    const expectedRoot =
+      descriptor.root === 'cache'
+        ? roots.cacheRoot
+        : descriptor.root === 'project'
+          ? roots.projectRoot
+          : path.dirname(roots.runtimeManifestFile);
+    if (
+      descriptor.root !== 'runtime-manifest' &&
+      !isPathInside(expectedRoot, realFile)
+    ) {
+      throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_PATH_REJECTED');
+    }
+  }
+  if (artifactScope !== 'vite' && applicationKind === 'fullstack') {
+    const expectedRuntime = generation.serverRuntime || {};
+    if (
+      String(expectedRuntime.nodeModuleAbi) !== process.versions.modules ||
+      expectedRuntime.platform !== process.platform ||
+      expectedRuntime.arch !== process.arch ||
+      String(expectedRuntime.nodeVersion || '').replace(/^v/, '') !==
+        process.versions.node
+    ) {
+      throw new Error('MIAODA_SERVER_CACHE_ABI_MISMATCH');
+    }
+    if (
+      generation.schemaVersion === 4 &&
+      (generation.serverRuntimeMode !== 'workspace-source-dependencies' ||
+        !compactServerDependenciesAreConsumable(serverDependencies))
+    ) {
+      throw new Error('MIAODA_SERVER_RUNTIME_DEPENDENCIES_REJECTED');
+    }
+  }
+  if (artifactScope !== 'server') {
+    if (
+      appRuntime?.schemaVersion !== 1 ||
+      appRuntime.runtimeAbiHash !== generation.runtimeAbiHash
+    ) {
+      throw new Error('MIAODA_APP_RUNTIME_ABI_MISMATCH');
+    }
+    if (validateConfigEnvironment) validateClientConfigEnvironment(appRuntime);
+  }
+  const shouldResolveArtifact = name =>
+    (applicationKind === 'fullstack' &&
+      artifactScope !== 'vite' &&
+      (generation.schemaVersion === 4
+        ? name === 'serverDependencies'
+        : name === 'serverBundle' ||
+          name === 'serverMetadata' ||
+          name.startsWith('serverRuntimeAsset:'))) ||
+    (artifactScope !== 'server' &&
+      (name === 'appRuntime' || name === 'viteMetadata'));
+  const artifacts = Object.fromEntries(
+    Object.entries(generation.artifacts || {})
+      .filter(([name]) => shouldResolveArtifact(name))
+      .map(([name, artifact]) => [
+        name,
+        resolveReceiptCacheArtifact(roots.cacheRoot, artifact),
+      ])
+  );
+  if (
+    generation.schemaVersion === 4 &&
+    applicationKind === 'fullstack' &&
+    artifactScope !== 'vite'
+  ) {
+    const transitionArtifacts = {
+      serverBundle: path.join(
+        roots.cacheRoot,
+        'server',
+        'bundle',
+        'server.bundle.cjs'
+      ),
+      serverMetadata: path.join(
+        roots.cacheRoot,
+        'server',
+        'bundle',
+        'server.bundle.cjs.meta.json'
+      ),
+    };
+    const receiptControls = new Set(
+      receipt.controls
+        .filter(descriptor => descriptor?.root === 'cache')
+        .map(descriptor => path.resolve(roots.cacheRoot, descriptor.path))
+    );
+    const exists = Object.values(transitionArtifacts).map(file =>
+      fs.existsSync(file)
+    );
+    if (exists.some(Boolean) && !exists.every(Boolean)) {
+      throw new Error('MIAODA_SERVER_TRANSITION_BUNDLE_INCOMPLETE');
+    }
+    if (exists.every(Boolean)) {
+      for (const [name, file] of Object.entries(transitionArtifacts)) {
+        if (!receiptControls.has(file)) {
+          throw new Error('MIAODA_CACHE_VALIDATION_RECEIPT_INVALID');
+        }
+        artifacts[name] = fs.realpathSync(file);
+      }
+    }
+  }
+  return {
+    projectRoot: roots.projectRoot,
+    cacheRoot: roots.cacheRoot,
+    runtimeManifestFile: roots.runtimeManifestFile,
+    generationFile: path.join(roots.cacheRoot, 'generation.json'),
+    generation,
+    runtime,
+    artifacts,
+    serverMetadata:
+      artifactScope === 'vite' || applicationKind === 'frontend-only'
+        ? undefined
+        : serverMetadata,
+    serverDependencies:
+      artifactScope === 'vite' || applicationKind === 'frontend-only'
+        ? undefined
+        : serverDependencies,
+    appRuntime: artifactScope === 'server' ? undefined : appRuntime,
+    // The serving runtime copies the sealed Vite directory as a whole and
+    // never consumes the per-file list. Returning an empty list keeps receipt
+    // consumption independent of projects with thousands of optimized files.
+    viteFiles: [],
+    validation: {
+      artifactScope,
+      validateConfigEnvironment,
+      validatedBy: 'platform-receipt',
+    },
+  };
+}
+
+export function validateCacheGeneration({
+  projectRoot,
+  cacheRoot,
+  runtimeManifestFile,
+  validateConfigEnvironment = true,
+  artifactScope = 'all',
+  validateWorkspaceInputs = true,
+}) {
+  if (!['all', 'server', 'vite'].includes(artifactScope)) {
+    throw new Error('MIAODA_CACHE_VALIDATION_SCOPE_INVALID');
+  }
+  if (!validateWorkspaceInputs && artifactScope !== 'vite') {
+    throw new Error('MIAODA_CACHE_WORKSPACE_INPUT_SKIP_REQUIRES_VITE_SCOPE');
+  }
+  const requestedServerArtifacts =
+    artifactScope === 'all' || artifactScope === 'server';
+  const validateViteArtifacts =
+    artifactScope === 'all' || artifactScope === 'vite';
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  const realProjectRoot = fs.realpathSync(resolvedProjectRoot);
+  const requestedCacheRoot = path.resolve(
+    cacheRoot || path.join(resolvedProjectRoot, '.miaoda-cache', 'current')
+  );
+  const resolvedCacheRoot = fs.existsSync(requestedCacheRoot)
+    ? fs.realpathSync(requestedCacheRoot)
+    : requestedCacheRoot;
+  const cacheRelative = path.relative(realProjectRoot, resolvedCacheRoot);
+  if (
+    cacheRelative === '..' ||
+    cacheRelative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(cacheRelative)
+  ) {
+    throw new Error('MIAODA_CACHE_GENERATION_ROOT_ESCAPE');
+  }
+  const resolvedRuntimeManifest = path.resolve(runtimeManifestFile);
+  const generationFile = path.join(resolvedCacheRoot, 'generation.json');
+  for (const file of [generationFile, resolvedRuntimeManifest]) {
+    if (!fs.existsSync(file)) {
+      throw new Error(`MIAODA_CACHE_BOOTSTRAP_INPUT_MISSING: ${file}`);
+    }
+  }
+  const generation = readJson(generationFile);
+  const runtime = readJson(resolvedRuntimeManifest);
+  if (![3, 4].includes(generation.schemaVersion) || !generation.generationId) {
+    throw new Error('MIAODA_CACHE_GENERATION_SCHEMA_UNSUPPORTED');
+  }
+  if (
+    generation.applicationKind !== undefined &&
+    !['fullstack', 'frontend-only'].includes(generation.applicationKind)
+  ) {
+    throw new Error('MIAODA_CACHE_APPLICATION_KIND_INVALID');
+  }
+  const applicationKind =
+    generation.applicationKind === 'frontend-only'
+      ? 'frontend-only'
+      : 'fullstack';
+  if (artifactScope === 'server' && applicationKind === 'frontend-only') {
+    throw new Error('MIAODA_CACHE_SERVER_ARTIFACT_NOT_AVAILABLE');
+  }
+  const validateServerArtifacts =
+    requestedServerArtifacts && applicationKind === 'fullstack';
+  if (
+    validateServerArtifacts &&
+    generation.schemaVersion === 3 &&
+    (!/^[a-f0-9]{64}$/.test(generation.serverMetadataIdentity?.sha256 || '') ||
+      !Number.isSafeInteger(generation.serverMetadataIdentity?.size) ||
+      generation.serverMetadataIdentity.size < 0)
+  ) {
+    throw new Error('MIAODA_CACHE_SERVER_METADATA_IDENTITY_INVALID');
+  }
+  const { generationId, ...generationIdentity } = generation;
+  const generationIdIdentity =
+    applicationKind === 'fullstack' && generation.schemaVersion === 3
+      ? {
+          ...generationIdentity,
+          artifacts: {
+            ...generationIdentity.artifacts,
+            serverMetadata: {
+              ...generationIdentity.artifacts?.serverMetadata,
+              ...generation.serverMetadataIdentity,
+            },
+          },
+        }
+      : generationIdentity;
+  const expectedGenerationId = crypto
+    .createHash('sha256')
+    .update(JSON.stringify(generationIdIdentity))
+    .digest('hex');
+  if (generationId !== expectedGenerationId) {
+    throw new Error('MIAODA_CACHE_GENERATION_ID_MISMATCH');
+  }
+  if (
+    runtime.schemaVersion !== 1 ||
+    !runtimeAbiHashes(runtime).has(generation.runtimeAbiHash)
+  ) {
+    throw new Error('MIAODA_CACHE_RUNTIME_ABI_MISMATCH');
+  }
+  const shouldResolveArtifact = name =>
+    (validateServerArtifacts &&
+      (generation.schemaVersion === 4
+        ? name === 'serverDependencies'
+        : name === 'serverBundle' ||
+          name === 'serverMetadata' ||
+          name.startsWith('serverRuntimeAsset:'))) ||
+    (validateViteArtifacts &&
+      (name === 'appRuntime' || name === 'viteMetadata'));
+  const artifacts = Object.fromEntries(
+    Object.entries(generation.artifacts || {})
+      .filter(([name]) => shouldResolveArtifact(name))
+      .map(([name, artifact]) => [
+        name,
+        resolveArtifact(resolvedCacheRoot, artifact),
+      ])
+  );
+  const requiredArtifacts = [
+    ...(validateServerArtifacts
+      ? generation.schemaVersion === 4
+        ? ['serverDependencies']
+        : ['serverBundle', 'serverMetadata']
+      : []),
+    ...(validateViteArtifacts ? ['appRuntime', 'viteMetadata'] : []),
+  ];
+  for (const name of requiredArtifacts) {
+    if (!artifacts[name]) {
+      throw new Error(`MIAODA_CACHE_GENERATION_ARTIFACT_MISSING: ${name}`);
+    }
+  }
+  if (
+    (validateViteArtifacts && !Array.isArray(generation.viteFiles)) ||
+    (validateViteArtifacts && generation.viteFiles.length === 0)
+  ) {
+    throw new Error('MIAODA_CACHE_GENERATION_VITE_FILES_MISSING');
+  }
+  if (
+    generation.schemaVersion === 3 &&
+    !Array.isArray(generation.sourceFiles)
+  ) {
+    throw new Error('MIAODA_CACHE_GENERATION_SOURCE_FILES_MISSING');
+  }
+  if (validateWorkspaceInputs && generation.schemaVersion === 3) {
+    const currentSourceFiles = listWorkspaceSourceFiles(
+      resolvedProjectRoot
+    ).filter(file => workspaceSourceFileInScope(file.path, artifactScope));
+    const sealedSourceFiles = generation.sourceFiles.filter(file =>
+      workspaceSourceFileInScope(file.path, artifactScope)
+    );
+    if (
+      JSON.stringify(currentSourceFiles) !== JSON.stringify(sealedSourceFiles)
+    ) {
+      throw new Error('MIAODA_CACHE_GENERATION_SOURCE_FILE_SET_MISMATCH');
+    }
+    if (
+      JSON.stringify(workspaceBuildInputs(resolvedProjectRoot)) !==
+      JSON.stringify(generation.workspaceBuildInputs)
+    ) {
+      throw new Error('MIAODA_CACHE_GENERATION_BUILD_INPUT_MISMATCH');
+    }
+  }
+  let viteFiles = [];
+  let serverMetadata;
+  let serverDependencies;
+  let appRuntime;
+  let viteMetadata;
+  if (validateViteArtifacts) {
+    const viteFilePaths = new Set();
+    viteFiles = generation.viteFiles.map(artifact => {
+      if (viteFilePaths.has(artifact?.path)) {
+        throw new Error(
+          `MIAODA_CACHE_GENERATION_VITE_FILE_DUPLICATE: ${artifact?.path}`
+        );
+      }
+      viteFilePaths.add(artifact?.path);
+      return resolveArtifact(resolvedCacheRoot, artifact);
+    });
+    if (!viteFilePaths.has(generation.artifacts.viteMetadata.path)) {
+      throw new Error('MIAODA_CACHE_GENERATION_VITE_METADATA_UNSEALED');
+    }
+    const actualViteFiles = listRegularFiles(
+      path.join(resolvedCacheRoot, 'vite'),
+      resolvedCacheRoot
+    );
+    const sealedViteFiles = Array.from(viteFilePaths).sort();
+    if (JSON.stringify(actualViteFiles) !== JSON.stringify(sealedViteFiles)) {
+      throw new Error('MIAODA_CACHE_GENERATION_VITE_FILE_SET_MISMATCH');
+    }
+    appRuntime = readJson(artifacts.appRuntime);
+    viteMetadata = readJson(artifacts.viteMetadata);
+  }
+  if (validateServerArtifacts && generation.schemaVersion === 4) {
+    serverDependencies = readJson(artifacts.serverDependencies);
+    if (!serverDependenciesAreConsumable(serverDependencies)) {
+      throw new Error('MIAODA_SERVER_RUNTIME_DEPENDENCIES_REJECTED');
+    }
+    if (generation.serverRuntimeMode !== 'workspace-source-dependencies') {
+      throw new Error('MIAODA_SERVER_RUNTIME_MODE_REJECTED');
+    }
+    if (
+      !Array.isArray(generation.serverFiles) ||
+      generation.serverFiles.length < 2
+    ) {
+      throw new Error('MIAODA_SERVER_RUNTIME_FILES_MISSING');
+    }
+    const sealedServerFiles = generation.serverFiles.map(artifact =>
+      resolveArtifact(resolvedCacheRoot, artifact)
+    );
+    const actualServerFiles = listRegularFiles(
+      path.join(resolvedCacheRoot, 'server'),
+      resolvedCacheRoot
+    );
+    const sealedServerPaths = generation.serverFiles
+      .map(artifact => artifact?.path)
+      .sort();
+    if (
+      JSON.stringify(actualServerFiles) !== JSON.stringify(sealedServerPaths)
+    ) {
+      throw new Error('MIAODA_SERVER_RUNTIME_FILE_SET_MISMATCH');
+    }
+    const dependencyFilePaths = serverDependencies.files.map(
+      file => `server/node_modules/${file.path}`
+    );
+    if (
+      JSON.stringify(dependencyFilePaths.sort()) !==
+      JSON.stringify(
+        sealedServerPaths
+          .filter(file => file.startsWith('server/node_modules/'))
+          .sort()
+      )
+    ) {
+      throw new Error('MIAODA_SERVER_RUNTIME_DEPENDENCY_SET_MISMATCH');
+    }
+    const bundleFile = path.join(
+      resolvedCacheRoot,
+      'server',
+      'bundle',
+      'server.bundle.cjs'
+    );
+    const bundleMetadataFile = `${bundleFile}.meta.json`;
+    const bundleExists = fs.existsSync(bundleFile);
+    const bundleMetadataExists = fs.existsSync(bundleMetadataFile);
+    if (bundleExists !== bundleMetadataExists) {
+      throw new Error('MIAODA_SERVER_TRANSITION_BUNDLE_INCOMPLETE');
+    }
+    if (bundleExists) {
+      const bundleMetadata = readJson(bundleMetadataFile);
+      if (
+        bundleMetadata?.schemaVersion !== 2 ||
+        bundleMetadata?.consumable !== true ||
+        !/^[a-f0-9]{64}$/.test(bundleMetadata?.workspaceSourceSha256 || '') ||
+        sha256(bundleFile) !== bundleMetadata.bundleSha256
+      ) {
+        throw new Error('MIAODA_SERVER_TRANSITION_BUNDLE_REJECTED');
+      }
+      // Schema v4 seals the optional transition bundle through `serverFiles`
+      // instead of the legacy `artifacts.serverBundle` field. Expose the
+      // validated paths under the stable logical names used by the runtime.
+      // Validation receipts will consequently protect these files as controls.
+      artifacts.serverBundle = bundleFile;
+      artifacts.serverMetadata = bundleMetadataFile;
+      serverMetadata = bundleMetadata;
+    }
+    const cachedActionPlugins = Object.fromEntries(
+      serverDependencies.actionPlugins.map(plugin => [
+        plugin.name,
+        plugin.version,
+      ])
+    );
+    if (
+      JSON.stringify(
+        workspaceBuildInputs(resolvedProjectRoot).actionPlugins
+      ) !== JSON.stringify(canonicalJson(cachedActionPlugins))
+    ) {
+      throw new Error('MIAODA_SERVER_RUNTIME_ACTION_PLUGIN_MISMATCH');
+    }
+    if (sealedServerFiles.length !== generation.serverFiles.length) {
+      throw new Error('MIAODA_SERVER_RUNTIME_FILE_SET_MISMATCH');
+    }
+    const expectedRuntime = generation.serverRuntime || {};
+    if (
+      String(expectedRuntime.nodeModuleAbi) !== process.versions.modules ||
+      expectedRuntime.platform !== process.platform ||
+      expectedRuntime.arch !== process.arch ||
+      String(expectedRuntime.nodeVersion || '').replace(/^v/, '') !==
+        process.versions.node
+    ) {
+      throw new Error('MIAODA_SERVER_CACHE_ABI_MISMATCH');
+    }
+  }
+  if (validateServerArtifacts && generation.schemaVersion === 3) {
+    serverMetadata = readJson(artifacts.serverMetadata);
+    if (
+      JSON.stringify(
+        jsonIdentity(stableServerMetadataIdentity(serverMetadata))
+      ) !== JSON.stringify(generation.serverMetadataIdentity)
+    ) {
+      throw new Error('MIAODA_CACHE_SERVER_METADATA_IDENTITY_MISMATCH');
+    }
+    const expectedRuntime = generation.serverRuntime || {};
+    const expectedNodeVersion = String(
+      expectedRuntime.nodeVersion || ''
+    ).replace(/^v/, '');
+    const requiredProbeChecks = [
+      'isolated-node-modules',
+      'runtime-assets',
+      'http-readiness',
+      'business-api',
+      'process-alive',
+      'module-resolution',
+    ];
+    const probeChecks = serverMetadata.availabilityProbe?.checks;
+    const probeCheckNames = Array.isArray(probeChecks)
+      ? probeChecks.map(check => check?.name)
+      : [];
+    if (
+      serverMetadata.schemaVersion !== 2 ||
+      serverMetadata.consumable !== true ||
+      !Array.isArray(serverMetadata.runtimeAssets) ||
+      !Array.isArray(serverMetadata.externalImports) ||
+      serverMetadata.externalImports.length > 0 ||
+      !Array.isArray(serverMetadata.runtimeAssetWarnings) ||
+      serverMetadata.runtimeAssetWarnings.some(
+        warning =>
+          typeof warning?.kind !== 'string' ||
+          typeof warning?.source !== 'string' ||
+          !/^[a-f0-9]{16}$/.test(warning?.expressionHash || '') ||
+          typeof warning?.message !== 'string'
+      ) ||
+      !Array.isArray(serverMetadata.actionPlugins) ||
+      serverMetadata.actionPlugins.some(
+        plugin =>
+          typeof plugin?.name !== 'string' ||
+          !plugin.name ||
+          typeof plugin?.version !== 'string' ||
+          !plugin.version
+      ) ||
+      !Array.isArray(serverMetadata.dynamicImportWarnings) ||
+      serverMetadata.dynamicImportWarnings.some(
+        warning =>
+          typeof warning?.kind !== 'string' ||
+          typeof warning?.source !== 'string' ||
+          !/^[a-f0-9]{16}$/.test(warning?.expressionHash || '') ||
+          typeof warning?.message !== 'string'
+      ) ||
+      serverMetadata.bundleSha256 !==
+        generation.artifacts.serverBundle.sha256 ||
+      serverMetadata.availabilityProbe?.success !== true ||
+      serverMetadata.availabilityProbe?.nodeModulesPresent !== false ||
+      !Array.isArray(probeChecks) ||
+      probeChecks.some(
+        check => typeof check?.name !== 'string' || check?.success !== true
+      ) ||
+      new Set(probeCheckNames).size !== probeCheckNames.length ||
+      requiredProbeChecks.some(name => !probeCheckNames.includes(name)) ||
+      (serverMetadata.actionPlugins.length > 0 &&
+        !probeCheckNames.includes('action-plugin-registry'))
+    ) {
+      throw new Error('MIAODA_SERVER_CACHE_METADATA_REJECTED');
+    }
+    const expectedRuntimeAssetKeys = [];
+    const runtimeAssetPaths = new Set();
+    for (const asset of serverMetadata.runtimeAssets) {
+      const assetPath = asset?.path;
+      if (
+        typeof assetPath !== 'string' ||
+        !assetPath ||
+        assetPath !== path.posix.normalize(assetPath) ||
+        assetPath === '.' ||
+        assetPath.startsWith('../') ||
+        path.posix.isAbsolute(assetPath) ||
+        assetPath.includes('\\') ||
+        runtimeAssetPaths.has(assetPath)
+      ) {
+        throw new Error('MIAODA_SERVER_CACHE_RUNTIME_ASSET_REJECTED');
+      }
+      runtimeAssetPaths.add(assetPath);
+      const key = `serverRuntimeAsset:${assetPath}`;
+      const generationArtifact = generation.artifacts[key];
+      if (
+        !generationArtifact ||
+        generationArtifact.path !== path.posix.join('server', assetPath) ||
+        generationArtifact.sha256 !== asset.sha256 ||
+        generationArtifact.size !== asset.size ||
+        !artifacts[key]
+      ) {
+        throw new Error('MIAODA_SERVER_CACHE_RUNTIME_ASSET_REJECTED');
+      }
+      expectedRuntimeAssetKeys.push(key);
+    }
+    const sealedRuntimeAssetKeys = Object.keys(generation.artifacts)
+      .filter(key => key.startsWith('serverRuntimeAsset:'))
+      .sort();
+    if (
+      JSON.stringify(expectedRuntimeAssetKeys.sort()) !==
+      JSON.stringify(sealedRuntimeAssetKeys)
+    ) {
+      throw new Error('MIAODA_SERVER_CACHE_RUNTIME_ASSET_SET_MISMATCH');
+    }
+    const sealedServerFiles = Object.values(generation.artifacts)
+      .map(artifact => artifact?.path)
+      .filter(
+        artifactPath =>
+          typeof artifactPath === 'string' && artifactPath.startsWith('server/')
+      )
+      .sort();
+    const actualServerFiles = listRegularFiles(
+      path.join(resolvedCacheRoot, 'server'),
+      resolvedCacheRoot
+    );
+    if (
+      JSON.stringify(actualServerFiles) !== JSON.stringify(sealedServerFiles)
+    ) {
+      throw new Error('MIAODA_SERVER_CACHE_FILE_SET_MISMATCH');
+    }
+    if (
+      expectedRuntime.nodeModuleAbi !== process.versions.modules ||
+      expectedRuntime.platform !== process.platform ||
+      expectedRuntime.arch !== process.arch ||
+      expectedNodeVersion !== process.versions.node
+    ) {
+      throw new Error('MIAODA_SERVER_CACHE_ABI_MISMATCH');
+    }
+  }
+  if (
+    (validateViteArtifacts && appRuntime.schemaVersion !== 1) ||
+    (validateViteArtifacts &&
+      appRuntime.runtimeAbiHash !== generation.runtimeAbiHash)
+  ) {
+    throw new Error('MIAODA_APP_RUNTIME_ABI_MISMATCH');
+  }
+  if (validateViteArtifacts) {
+    validateClientConfigFiles(resolvedProjectRoot, appRuntime);
+  }
+  if (
+    (validateViteArtifacts &&
+      !/^[a-f0-9]{64}$/.test(appRuntime.clientDependencyGraphHash || '')) ||
+    (validateViteArtifacts &&
+      (appRuntime.clientDependencyGraph?.schemaVersion !== 1 ||
+        appRuntime.clientDependencyGraph?.runtimeAbiHash !==
+          generation.runtimeAbiHash))
+  ) {
+    throw new Error('MIAODA_CLIENT_DEPENDENCY_GRAPH_INVALID');
+  }
+  if (validateViteArtifacts && validateConfigEnvironment) {
+    validateClientConfigEnvironment(appRuntime);
+  }
+  if (validateViteArtifacts) {
+    const optimizedDependencies = new Set(
+      Object.keys(viteMetadata.optimized || {})
+    );
+    const missingViteDependencies = Array.from(
+      new Set(appRuntime.optimizeDependencies || [])
+    ).filter(specifier => !optimizedDependencies.has(specifier));
+    if (missingViteDependencies.length > 0) {
+      throw new Error(
+        `MIAODA_VITE_CACHE_DEPENDENCY_COVERAGE_MISSING: ${missingViteDependencies.join(', ')}`
+      );
+    }
+    const graphPackageNames = new Set(
+      (appRuntime.clientDependencyGraph?.entries || [])
+        .map(entry => packageNameFromOptimizerId(entry.specifier || ''))
+        .filter(Boolean)
+    );
+    const optimizerEntries = [
+      ...Object.entries(viteMetadata.optimized || {}),
+      ...Object.entries(viteMetadata.discovered || {}),
+    ];
+    const uncoveredOptimizerPackages = Array.from(
+      new Set(
+        optimizerEntries.flatMap(([id, entry]) => {
+          const name = packageNameFromOptimizerId(id);
+          if (!name || graphPackageNames.has(name)) return [];
+          return optimizerEntryUsesRuntimePackage({
+            projectRoot: resolvedProjectRoot,
+            runtimeManifestFile: resolvedRuntimeManifest,
+            runtime,
+            packageName: name,
+            entry,
+          })
+            ? []
+            : [name];
+        })
+      )
+    ).sort();
+    if (uncoveredOptimizerPackages.length > 0) {
+      throw new Error(
+        `MIAODA_VITE_OPTIMIZER_GRAPH_TOOLCHAIN_COVERAGE_MISSING: ${uncoveredOptimizerPackages.join(', ')}`
+      );
+    }
+  }
+  return {
+    projectRoot: resolvedProjectRoot,
+    cacheRoot: resolvedCacheRoot,
+    runtimeManifestFile: resolvedRuntimeManifest,
+    generationFile,
+    generation,
+    runtime,
+    artifacts,
+    serverMetadata,
+    serverDependencies,
+    appRuntime,
+    viteFiles,
+    validation: {
+      artifactScope,
+      validateConfigEnvironment,
+      validateWorkspaceInputs,
+      validatedBy: 'full-sha',
+    },
+  };
+}