gencow 0.1.231 → 0.1.233

package/bin/gencow.mjs

@@ -38,6 +38,7 @@ import {
   updateEnvLocalUrl,
 } from "../lib/cli-project-runtime.mjs";
 import { createCodegenCommand } from "../lib/codegen-command.mjs";
+import { resolveCliArtifactSourceRevision } from "../lib/deployment-artifact-provenance.mjs";
 import { runCliCommand } from "../lib/cli-command-runner.mjs";
 import { createDoctorCommand } from "../lib/doctor-command.mjs";
 import { maybeCheckCliVersion } from "../lib/cli-version-check.mjs";
@@ -89,8 +90,12 @@ import { failReleaseAttempt, finalizeReleaseAttempt, prepareReleaseAttempt } fro
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI_PACKAGE_JSON = JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf8"));
 const CLI_VERSION = CLI_PACKAGE_JSON.version || "0.0.0";
+const CLI_SOURCE_REVISION = resolveCliArtifactSourceRevision(CLI_VERSION);
 const _drizzleKitCmd = (subcmd, options = {}) => buildDrizzleKitCommand(subcmd, options);
-const generateApiTs = createApiCodegenRuntime({});
+const generateApiTs = createApiCodegenRuntime({
+  cliVersion: CLI_VERSION,
+  sourceRevision: CLI_SOURCE_REVISION,
+});
 const runAddCommand = createAddCommand({
   loadConfig,
   updateComponentReadmeImpl: updateComponentReadme,
@@ -113,6 +118,8 @@ const runAppCommand = createAppCommand({
 const runBackupCommand = createBackupCommand();
 const { login: runLoginCommand, logout: runLogoutCommand, whoami: runWhoamiCommand } = createAuthCommands();
 const runCodegenCommand = createCodegenCommand({
+  cliVersion: CLI_VERSION,
+  sourceRevision: CLI_SOURCE_REVISION,
   loadConfig,
   findServerRoot,
   resolveCoreImport,
@@ -159,6 +166,7 @@ const {
   dbStudio: runDbStudioCommand,
 } = createDbCommands({
   cliVersion: CLI_VERSION,
+  sourceRevision: CLI_SOURCE_REVISION,
   buildEnv,
   cleanupOldBackups,
   drizzleKitCmdImpl: _drizzleKitCmd,
@@ -169,6 +177,7 @@ const {
 });
 const runDevCloudCommand = createDevCloudCommand({
   cliVersion: CLI_VERSION,
+  sourceRevision: CLI_SOURCE_REVISION,
   buildEnvImpl: buildEnv,
   requireCreds,
   loadConfig,
@@ -246,6 +255,7 @@ const runStaticDeployRuntime = createStaticDeployRuntime({
 const runDeployCommand = createDeployCommand({
   buildEnvImpl: buildEnv,
   cliVersion: CLI_VERSION,
+  sourceRevision: CLI_SOURCE_REVISION,
   cwdImpl: () => process.cwd(),
   drizzleKitCmdImpl: _drizzleKitCmd,
   existsSyncImpl: existsSync,
@@ -280,6 +290,8 @@ const runInitCommand = createInitCommand({
   templateFeatureDir: resolve(__dirname, "..", "templateFeature"),
   runCodegenImpl: async (projectDir) => {
     const runProjectCodegen = createCodegenCommand({
+      cliVersion: CLI_VERSION,
+      sourceRevision: CLI_SOURCE_REVISION,
       loadConfig: (opts = {}) => loadConfig({ ...opts, cwd: projectDir }),
       findServerRoot,
       resolveCoreImport,

package/core/index.js

@@ -3016,6 +3016,7 @@ var RESERVED_TENANT_RUNTIME_ENV_KEYS = [
   "GENCOW_PLATFORM_DB",
   "GENCOW_MANAGED_PUBLIC_ORIGINS",
   "PLATFORM_OPENAI_KEY",
+  "PLATFORM_OPENROUTER_KEY",
   "PLATFORM_GOOGLE_KEY",
   "PLATFORM_GOOGLE_CLIENT_ID",
   "PLATFORM_GOOGLE_CLIENT_SECRET",

package/lib/backend-bundle-file-plan.mjs

@@ -25,7 +25,7 @@ function collectFiles(backendRoot, archiveRoot, excludes, directory = backendRoo
       throw new Error(`Bundle entry ${JSON.stringify(entry)} must be a regular file`);
     }
     const relativePath = canonicalPath(relative(backendRoot, path));
-    const archivePath = canonicalPath(`${archiveRoot}/${relativePath}`);
+    const archivePath = canonicalPath(archiveRoot ? `${archiveRoot}/${relativePath}` : relativePath);
     if (!shouldIncludeTarEntry(archivePath, excludes)) continue;
     const bytes = readFileSync(path);
     files.push({ relativePath, archivePath, size: bytes.length, sha256: sha256(bytes) });
@@ -33,6 +33,19 @@ function collectFiles(backendRoot, archiveRoot, excludes, directory = backendRoo
   return files;
 }
 
+export function buildArchivePayloadFilePlan({
+  workspaceRoot,
+  excludes = [],
+  excludedPaths = [".gencow/migration-bundle-manifest.json"],
+}) {
+  const files = collectFiles(workspaceRoot, "", excludes).filter(
+    (file) => !excludedPaths.includes(file.relativePath),
+  );
+  assertUniqueCanonicalPaths(files);
+  const rows = files.map((file) => [file.relativePath, file.size, file.sha256]);
+  return { rows, sha256: sha256(JSON.stringify(rows)) };
+}
+
 function assertUniqueCanonicalPaths(files) {
   const exact = new Set();
   const folded = new Set();

package/lib/cli-dev-runtime.mjs

@@ -146,6 +146,8 @@ export function createApiCodegenRuntime(options = {}) {
     successImpl = success,
     updateComponentReadmeImpl = updateComponentReadme,
     emitAuthSchemaArtifactImpl,
+    cliVersion,
+    sourceRevision,
     warnImpl = warn,
     writeFileSyncImpl = writeFileSync,
   } = options;
@@ -174,6 +176,8 @@ export function createApiCodegenRuntime(options = {}) {
         resolvePathImpl,
         serverPublishDir: resolveCodegenServerPublishDir(cwd, config),
         successImpl,
+        cliVersion,
+        sourceRevision,
       });
       assertToolingRuntimeCapabilities(bundled, ["registryRuntime"], {
         label: "tooling runtime",

package/lib/codegen-command.mjs

@@ -10,6 +10,7 @@ import {
   resolveProjectSelection,
   selectCodegenClient,
 } from "./project-context.mjs";
+import { writeCodegenProvenance } from "./deployment-artifact-provenance.mjs";
 
 export { formatAuthSchemaConflictMessage } from "./auth-schema-provenance-guard.mjs";
 
@@ -193,6 +194,8 @@ export async function runCodegenWithReporting({
   resolvePathImpl = resolve,
   serverPublishDir,
   successImpl,
+  cliVersion,
+  sourceRevision,
 }) {
   const bundled = await (loadCodegenBundleImpl ?? loadCodegenBundleDefault)();
 
@@ -223,6 +226,13 @@ export async function runCodegenWithReporting({
   });
   logCodegenDiagnostics(logImpl, result.diagnostics, diagnosticsColors);
   assertCodegenSucceeded(result);
+  if (cliVersion && sourceRevision) {
+    writeCodegenProvenance({
+      cliVersion,
+      sourceRevision,
+      serverPublishDir: effectiveServerPublishDir,
+    });
+  }
   return { bundled, result };
 }
 
@@ -347,6 +357,8 @@ export function createCodegenCommand(deps) {
         publishDir,
         resolvePathImpl: deps.resolvePathImpl,
         successImpl: deps.successImpl,
+        cliVersion: deps.cliVersion,
+        sourceRevision: deps.sourceRevision,
       });
       deps.successImpl("Codegen completed successfully.");
     } catch (error) {

package/lib/db-command.mjs

@@ -149,6 +149,7 @@ function renderCloudSeedMissingFile({ infoImpl = info, logImpl = log, warnImpl =
 
 export function createDbCommands({
   cliVersion = "0.0.0",
+  sourceRevision,
   buildEnv,
   cleanupOldBackups,
   createInterfaceImpl,
@@ -219,6 +220,7 @@ export function createDbCommands({
     warnImpl,
     writeFileSyncImpl,
     cliVersion,
+    sourceRevision,
   };
   const runDbPush = createDbPushCommand(dbMigrationDependencies);
   const runDbCheck = createDbCheckCommand(dbMigrationDependencies);

package/lib/db-push-command.mjs

@@ -426,6 +426,7 @@ function createDbMigrationCommand(deps, command) {
           cliVersion: deps.cliVersion,
           generatorVersion,
           sourceMode,
+          sourceRevision: deps.sourceRevision,
           schemaSourcePaths,
           cpSyncImpl: deps.cpSyncImpl,
           mkdirSyncImpl: deps.mkdirSyncImpl,
@@ -445,7 +446,9 @@ function createDbMigrationCommand(deps, command) {
         emitFailure(
           error?.code === "MIGRATION_BUNDLE_LOCAL_INTEGRITY_FAILED"
             ? buildLocalBundleIntegrityFailureDiagnostic(clientCorrelationId())
-            : buildClientBundleFailureDiagnostic(clientCorrelationId(), retryCommand),
+            : error?.code === "MIGRATION_BUNDLE_SCHEMA_CHANGE_WITHOUT_FORWARD_MIGRATION"
+              ? buildClientUserFixableDiagnostic(error.code, clientCorrelationId())
+              : buildClientBundleFailureDiagnostic(clientCorrelationId(), retryCommand),
         );
         return;
       }
@@ -482,6 +485,12 @@ function createDbMigrationCommand(deps, command) {
                 "X-Gencow-Environment": envLabel,
                 "X-Gencow-Migration-Operation-ID": receiptId,
                 "X-Gencow-Migration-Bundle-Sha256": stagedBundle.manifest.bundleSha256,
+                ...(stagedBundle.manifest.artifactIdentitySha256
+                  ? {
+                      "X-Gencow-Migration-Artifact-Identity-Sha256":
+                        stagedBundle.manifest.artifactIdentitySha256,
+                    }
+                  : {}),
               },
               body: bundleData,
             },

package/lib/deploy-bundle-staging.mjs

@@ -13,6 +13,7 @@ export const CANONICAL_BUNDLE_BACKEND_ROOT = "gencow";
 
 export async function writeCanonicalDeployBundle({
   cliVersion,
+  sourceRevision,
   cwd,
   backendRoot,
   dependencyAuditManifest,
@@ -122,6 +123,7 @@ export async function writeCanonicalDeployBundle({
       config: canonicalManifestConfig ?? undefined,
       backendExcludes: envExcludes,
       cliVersion,
+      sourceRevision,
       generatorVersion,
       existsSyncImpl,
       mkdirSyncImpl,

package/lib/deploy-codegen-preflight.mjs

@@ -63,6 +63,8 @@ export async function prepareDeployCodegenArtifacts({
   rmSyncImpl,
   runCodegenForDeployImpl = runCodegenWithReporting,
   successImpl,
+  cliVersion,
+  sourceRevision,
 }) {
   const authSchemaPath = resolvePathImpl(cwd, backendRoot, "schema-auth.ts");
   const serverPublishDir = resolveCodegenServerPublishDir(cwd, config);
@@ -109,6 +111,8 @@ export async function prepareDeployCodegenArtifacts({
       publishDir: deployCodegenClientDir,
       serverPublishDir: deployCodegenServerDir,
       successImpl,
+      cliVersion,
+      sourceRevision,
     });
   } catch {
     cleanup();

package/lib/deploy-contract.mjs

@@ -1,8 +1,12 @@
 import { createHash, randomUUID } from "node:crypto";
 
-import { MIGRATION_BUNDLE_CAPABILITY_V1 } from "@gencow/migration-contract";
+import {
+  MIGRATION_ARTIFACT_IDENTITY_CAPABILITY_V2,
+  MIGRATION_BUNDLE_CAPABILITY_V1,
+} from "@gencow/migration-contract";
 
 export const DEPLOY_CLAIM_PROTOCOL_VERSION = 1;
+export const DEPLOY_CLAIM_PROTOCOL_VERSION_V2 = 2;
 const TOP_LEVEL_FIELDS = [
   "protocolVersion",
   "requestId",
@@ -139,10 +143,65 @@ export function canonicalizeDeployClaimV1(input) {
   return claim;
 }
 
+export function canonicalizeDeployClaimV2(input) {
+  requireExactFields(input, TOP_LEVEL_FIELDS, "deploy claim");
+  if (input.protocolVersion !== DEPLOY_CLAIM_PROTOCOL_VERSION_V2) {
+    throw new Error("deploy claim protocolVersion is not supported");
+  }
+  const migrationBundle = requireObject(input.migrationBundle, "deploy claim migrationBundle");
+  requireExactFields(
+    migrationBundle,
+    ["manifestSha256", "requiredCapability", "artifactIdentitySha256"],
+    "deploy claim migrationBundle",
+  );
+  const legacy = canonicalizeDeployClaimV1({
+    ...input,
+    protocolVersion: DEPLOY_CLAIM_PROTOCOL_VERSION,
+    migrationBundle: {
+      manifestSha256: migrationBundle.manifestSha256,
+      requiredCapability:
+        migrationBundle.requiredCapability === MIGRATION_ARTIFACT_IDENTITY_CAPABILITY_V2
+          ? MIGRATION_BUNDLE_CAPABILITY_V1
+          : migrationBundle.requiredCapability,
+    },
+  });
+  const identitySha256 = requireSha256(
+    migrationBundle.artifactIdentitySha256,
+    "migration artifactIdentitySha256",
+    true,
+  );
+  if (
+    legacy.declaredRuntime !== "server" ||
+    identitySha256 === null ||
+    migrationBundle.requiredCapability !== MIGRATION_ARTIFACT_IDENTITY_CAPABILITY_V2
+  ) {
+    throw new Error("deploy claim artifact identity is inconsistent");
+  }
+  return {
+    ...legacy,
+    protocolVersion: DEPLOY_CLAIM_PROTOCOL_VERSION_V2,
+    migrationBundle: {
+      manifestSha256: legacy.migrationBundle.manifestSha256,
+      requiredCapability: identitySha256 ? MIGRATION_ARTIFACT_IDENTITY_CAPABILITY_V2 : "none",
+      artifactIdentitySha256: identitySha256,
+    },
+  };
+}
+
+export function canonicalizeDeployClaim(input) {
+  return input?.protocolVersion === DEPLOY_CLAIM_PROTOCOL_VERSION_V2
+    ? canonicalizeDeployClaimV2(input)
+    : canonicalizeDeployClaimV1(input);
+}
+
 export function encodeDeployClaimV1(input) {
   return Buffer.from(JSON.stringify(canonicalizeDeployClaimV1(input))).toString("base64url");
 }
 
+export function encodeDeployClaimV2(input) {
+  return Buffer.from(JSON.stringify(canonicalizeDeployClaimV2(input))).toString("base64url");
+}
+
 export function hashDeployClaimV1(input) {
   return createHash("sha256")
     .update(JSON.stringify(canonicalizeDeployClaimV1(input)))

package/lib/deploy-package-claim.mjs

@@ -3,9 +3,19 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { list } from "tar";
 
-import { MIGRATION_BUNDLE_CAPABILITY_V1, inspectPnpmDependencyLock } from "@gencow/migration-contract";
+import {
+  MIGRATION_ARTIFACT_IDENTITY_CAPABILITY_V2,
+  MIGRATION_BUNDLE_CAPABILITY_V1,
+  inspectPnpmDependencyLock,
+} from "@gencow/migration-contract";
 
-import { canonicalizeDeployClaimV1, createDeployRequestId, encodeDeployClaimV1 } from "./deploy-contract.mjs";
+import {
+  canonicalizeDeployClaimV1,
+  canonicalizeDeployClaimV2,
+  createDeployRequestId,
+  encodeDeployClaimV1,
+  encodeDeployClaimV2,
+} from "./deploy-contract.mjs";
 import { DEPLOY_LOCKFILE_CANDIDATES, UNSUPPORTED_DEPLOY_LOCKFILES } from "./deploy-lockfile-selection.mjs";
 
 const PACKAGE_MANIFEST = "package.json";
@@ -139,8 +149,19 @@ export async function buildDeployClaimFromArchive({
     assertDeployDependencyLock(packageBytes, lockfile ? selected.get(lockfile[0]) : null);
   }
   const migrationBytes = selected.get(MIGRATION_MANIFEST);
-  const claim = canonicalizeDeployClaimV1({
-    protocolVersion: 1,
+  let artifactIdentitySha256 = null;
+  if (migrationBytes) {
+    try {
+      const manifest = JSON.parse(migrationBytes.toString("utf8"));
+      artifactIdentitySha256 = manifest.artifactIdentitySha256 ?? null;
+    } catch {
+      throw new Error("Migration manifest is not valid JSON");
+    }
+  }
+  const protocolVersion = artifactIdentitySha256 ? 2 : 1;
+  const canonicalize = protocolVersion === 2 ? canonicalizeDeployClaimV2 : canonicalizeDeployClaimV1;
+  const claim = canonicalize({
+    protocolVersion,
     requestId,
     sourceBundleSha256: sha256(bundleBuffer),
     declaredRuntime,
@@ -152,9 +173,17 @@ export async function buildDeployClaimFromArchive({
     },
     migrationBundle: {
       manifestSha256: migrationBytes ? sha256(migrationBytes) : null,
-      requiredCapability: migrationBytes ? MIGRATION_BUNDLE_CAPABILITY_V1 : "none",
+      requiredCapability: migrationBytes
+        ? artifactIdentitySha256
+          ? MIGRATION_ARTIFACT_IDENTITY_CAPABILITY_V2
+          : MIGRATION_BUNDLE_CAPABILITY_V1
+        : "none",
+      ...(protocolVersion === 2 ? { artifactIdentitySha256 } : {}),
     },
     generatedBy: { name: "gencow-cli", version: cliVersion },
   });
-  return { claim, header: encodeDeployClaimV1(claim) };
+  return {
+    claim,
+    header: protocolVersion === 2 ? encodeDeployClaimV2(claim) : encodeDeployClaimV1(claim),
+  };
 }

package/lib/deploy-package-runtime.mjs

@@ -42,6 +42,7 @@ import {
 } from "./deploy-lockfile-selection.mjs";
 import { detectProjectConfigFile, warnProjectConfigSelectionOnce } from "./project-config-selection.mjs";
 import { writeCanonicalDeployBundle } from "./deploy-bundle-staging.mjs";
+import { buildClientUserFixableDiagnostic } from "./migration-client-diagnostic.mjs";
 
 async function loadProjectConfigDefault(options) {
   const { loadConfig } = await import("./cli-project-runtime.mjs");
@@ -112,6 +113,7 @@ export function createDeployPackageRuntime({
   buildEnvImpl,
   buildDeployClaimFromArchiveImpl = buildDeployClaimFromArchive,
   cliVersion = "0.0.0",
+  sourceRevision,
   cwdImpl = () => process.cwd(),
   drizzleKitCmdImpl,
   errorImpl = error,
@@ -212,6 +214,8 @@ export function createDeployPackageRuntime({
         rmSyncImpl,
         runCodegenForDeployImpl,
         successImpl,
+        cliVersion,
+        sourceRevision,
       });
     }
     if (
@@ -461,6 +465,7 @@ export function createDeployPackageRuntime({
     try {
       ({ bundleBackendRoot } = await writeCanonicalDeployBundle({
         cliVersion,
+        sourceRevision,
         cwd,
         backendRoot,
         dependencyAuditManifest,
@@ -484,7 +489,15 @@ export function createDeployPackageRuntime({
         writeFileSyncImpl,
       }));
     } catch (caught) {
-      errorImpl(`Packaging failed: ${caught.message}`);
+      if (caught?.code === "MIGRATION_BUNDLE_SCHEMA_CHANGE_WITHOUT_FORWARD_MIGRATION") {
+        for (const line of renderMigrationDiagnosticLines(
+          buildClientUserFixableDiagnostic(caught.code, `client-${Date.now()}`),
+        )) {
+          errorImpl(line);
+        }
+      } else {
+        errorImpl(`Packaging failed: ${caught.message}`);
+      }
       exitImpl(1);
       cleanupPreparedDeploySource();
       return null;
@@ -624,7 +637,7 @@ export function createDeployPackageRuntime({
           ...(activeDeployClaim
             ? {
                 "X-Gencow-Deploy-Claim": activeDeployClaim.header,
-                "X-Gencow-Deploy-Protocol": "1",
+                "X-Gencow-Deploy-Protocol": String(activeDeployClaim.claim.protocolVersion ?? 1),
                 "X-Gencow-CLI-Version": activeDeployClaim.claim.generatedBy.version,
               }
             : {}),

package/lib/deploy-runtime.mjs

@@ -352,6 +352,7 @@ async function runRollbackDeploy({
 export function createDeployCommand({
   buildEnvImpl,
   cliVersion,
+  sourceRevision,
   createDeployPackageRuntimeImpl = createDeployPackageRuntime,
   createExistingBundleCandidateImpl = createExistingBundleCandidate,
   createInterfaceImpl,
@@ -394,6 +395,7 @@ export function createDeployCommand({
   const packageRuntimeOptions = {
     buildEnvImpl,
     cliVersion,
+    sourceRevision,
     createDeployPackageRuntimeImpl,
     drizzleKitCmdImpl,
     errorImpl,

package/lib/deployment-artifact-provenance.mjs

@@ -0,0 +1,151 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  canonicalizeCodegenArtifactProvenanceV1,
+  compareCanonicalCodegenArtifactPaths,
+  hashGeneratedSchemaArtifacts,
+} from "@gencow/migration-contract/artifact-identity";
+
+const SHA256 = /^[a-f0-9]{64}$/u;
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+export const CODEGEN_PROVENANCE_FILENAME = ".gencow-codegen-provenance.json";
+const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const CLI_IDENTITY_FILES = [
+  "package.json",
+  "bin/gencow.mjs",
+  "lib/codegen-command.mjs",
+  "lib/migration-bundle-manifest.mjs",
+  "lib/backend-bundle-file-plan.mjs",
+  "lib/deployment-artifact-provenance.mjs",
+  "runtime/tooling.mjs",
+];
+
+function normalizeProvenance(value, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).length !== 2 ||
+    typeof value.cliVersion !== "string" ||
+    !VERSION.test(value.cliVersion) ||
+    typeof value.sourceRevision !== "string" ||
+    !SHA256.test(value.sourceRevision)
+  ) {
+    throw new Error(`${label} artifact provenance is invalid`);
+  }
+  return { cliVersion: value.cliVersion, sourceRevision: value.sourceRevision };
+}
+
+export function deriveCliSourceRevision(cliVersion, sourceFiles = []) {
+  if (typeof cliVersion !== "string" || !VERSION.test(cliVersion)) {
+    throw new Error("CLI version is invalid");
+  }
+  const rows = sourceFiles.map(({ path, bytes }) => [
+    String(path).replaceAll("\\", "/").normalize("NFC"),
+    Buffer.byteLength(bytes),
+    createHash("sha256").update(bytes).digest("hex"),
+  ]);
+  rows.sort((left, right) => left[0].localeCompare(right[0]));
+  return createHash("sha256").update(JSON.stringify({ cliVersion, rows })).digest("hex");
+}
+
+export function resolveCliArtifactSourceRevision(cliVersion, options = {}) {
+  const root = options.cliRoot ?? CLI_ROOT;
+  const read = options.readFileSyncImpl ?? readFileSync;
+  return deriveCliSourceRevision(
+    cliVersion,
+    CLI_IDENTITY_FILES.map((path) => ({ path, bytes: read(resolve(root, path)) })),
+  );
+}
+
+function collectGeneratedArtifacts(root, directory = root) {
+  const rows = [];
+  for (const entry of readdirSync(directory).sort()) {
+    if (entry === CODEGEN_PROVENANCE_FILENAME) continue;
+    const path = resolve(directory, entry);
+    const stats = lstatSync(path);
+    if (stats.isDirectory()) {
+      rows.push(...collectGeneratedArtifacts(root, path));
+      continue;
+    }
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+      throw new Error("Generated schema artifact must be a regular file");
+    }
+    const bytes = readFileSync(path);
+    rows.push({
+      path: relative(root, path).replaceAll("\\", "/").normalize("NFC"),
+      size: bytes.length,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+    });
+  }
+  return rows.sort((left, right) => compareCanonicalCodegenArtifactPaths(left.path, right.path));
+}
+
+export function buildCodegenProvenance({ cliVersion, sourceRevision, serverPublishDir }) {
+  const producer = normalizeProvenance({ cliVersion, sourceRevision }, "codegen");
+  const artifacts = collectGeneratedArtifacts(serverPublishDir);
+  return canonicalizeCodegenArtifactProvenanceV1({
+    version: 1,
+    ...producer,
+    generatedSchemaDigest: hashGeneratedSchemaArtifacts(artifacts),
+    artifacts,
+  });
+}
+
+export function writeCodegenProvenance({ cliVersion, sourceRevision, serverPublishDir }) {
+  const provenance = buildCodegenProvenance({ cliVersion, sourceRevision, serverPublishDir });
+  const markerPath = resolve(serverPublishDir, CODEGEN_PROVENANCE_FILENAME);
+  const temporaryPath = resolve(
+    dirname(serverPublishDir),
+    `.${basename(serverPublishDir)}-${CODEGEN_PROVENANCE_FILENAME}.tmp-${process.pid}-${randomUUID()}`,
+  );
+  try {
+    writeFileSync(temporaryPath, `${JSON.stringify(provenance)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(temporaryPath, markerPath);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+  return provenance;
+}
+
+export function readCodegenProvenance(path) {
+  if (!existsSync(path)) return null;
+  const stats = lstatSync(path);
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error("codegen artifact provenance is invalid");
+  }
+  try {
+    return canonicalizeCodegenArtifactProvenanceV1(JSON.parse(readFileSync(path, "utf8")));
+  } catch {
+    throw new Error("codegen artifact provenance is invalid");
+  }
+}
+
+export function verifyCodegenProvenance(path) {
+  const provenance = readCodegenProvenance(path);
+  if (!provenance) return null;
+  const actual = collectGeneratedArtifacts(dirname(path));
+  if (
+    JSON.stringify(actual) !== JSON.stringify(provenance.artifacts) ||
+    hashGeneratedSchemaArtifacts(actual) !== provenance.generatedSchemaDigest
+  ) {
+    const error = new Error("PLATFORM_MIGRATION_ARTIFACT_CONTRACT_MISMATCH");
+    error.code = "PLATFORM_MIGRATION_ARTIFACT_CONTRACT_MISMATCH";
+    throw error;
+  }
+  return provenance;
+}
+
+export function assertMatchingCodegenAndPackagerProvenance(input) {
+  const codegen = normalizeProvenance(input?.codegen, "codegen");
+  const packager = normalizeProvenance(input?.packager, "packager");
+  if (codegen.cliVersion !== packager.cliVersion || codegen.sourceRevision !== packager.sourceRevision) {
+    const error = new Error("PLATFORM_MIGRATION_ARTIFACT_CONTRACT_MISMATCH");
+    error.code = "PLATFORM_MIGRATION_ARTIFACT_CONTRACT_MISMATCH";
+    throw error;
+  }
+  return packager;
+}

package/lib/dev-cloud-bundle.mjs

@@ -96,6 +96,7 @@ export async function createDevCloudDeployBundle({
   envFile,
   functionsDir,
   cliVersion = "0.0.0",
+  sourceRevision,
   generatorVersion = "unknown",
   config,
   auditDependencyVersionsImpl = auditDependencyVersions,
@@ -232,6 +233,7 @@ export async function createDevCloudDeployBundle({
       backendExcludes: envExcludes,
       config: loadedProjectConfig ? canonicalConfig : undefined,
       cliVersion,
+      sourceRevision,
       generatorVersion,
       existsSyncImpl,
       mkdirSyncImpl,