@kedge/cli 0.0.0-stage → 0.10.0

package/src/preview.ts

@@ -0,0 +1,1038 @@
+// `kedge preview` (docs/proposals/p0.8-cli-agent-kit.md §5): a separate Worker
+// with its own D1, queue and Durable Objects, no production secrets and
+// capture sinks for every effect. Worker Previews can't run queue consumers
+// or cron ("Queue consumers cannot target a Preview", "Routes and Cron
+// Triggers target production", developers.cloudflare.com/workers/previews/),
+// and Kedge's relay and expiry need both.
+//
+// Two halves. `build` runs the store's code and needs no credentials: it
+// bundles and writes a plan. `apply` holds the credentials and runs none of the
+// store's code: it reads the plan as a tar stream of data, generates the
+// Wrangler config itself from an allowlist, and runs Wrangler from its own
+// directory with a sanitized environment (cf.ts). The eval depends on that split.
+import { spawnSync } from "node:child_process";
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ownerInviteSql } from "@kedge/db";
+import { enrolOwner, type StoreCredentials } from "@kedge/testing/http";
+import { type Cloudflare, type JurisdictionChoice, UnknownOutcome } from "./cf";
+import { seed } from "./commands";
+import type { Lock } from "./compose";
+import { CORE_SECRETS, DeployRefused, openOps, stageAssets } from "./deploy";
+import { assetsShape, declaredClasses, readWrangler } from "./doctor";
+import { LostOwnership, OperationHeld, type OpsStore } from "./ops";
+import { childStdio } from "./output";
+import { hashTree, type StoreNames, sha256, type WranglerJson } from "./store";
+import { readTar, type TarEntry, TarRefused, writeTar } from "./tar";
+
+/** The origin the bootstrap's browser-shaped ceremonies use; the preview's ADMIN_ORIGINS includes it. */
+export const PREVIEW_ORIGIN = "https://kedge-preview.invalid";
+/** What a preview's secret key may do: enough for seeding and a store's scenarios. */
+export const PREVIEW_GRANTS = [
+  "product:read",
+  "product:write",
+  "order:read",
+  "order:write",
+  "order:place",
+  "inventory:read",
+  "inventory:write",
+  "capacity:read",
+  "capacity:write",
+  "tax:read",
+  "policy:read",
+  "settings:read",
+  "customer:read",
+  "plugin:read",
+  "delivery:read",
+  "effect:read",
+  "field:pii",
+  "field:financial",
+];
+const LIMITS = { files: 2_000, fileBytes: 32 * 1024 * 1024, totalBytes: 64 * 1024 * 1024 };
+const NEVER_COPIED = /^(CLOUDFLARE_|KEDGE_PREVIEW_KEY$)/;
+
+/** Keys a preview's Worker config may carry; anything else is a refusal naming it (§5.2). */
+const ALLOWED = new Set([
+  "$schema",
+  "name",
+  "main",
+  "compatibility_date",
+  "compatibility_flags",
+  "observability",
+  "vars",
+  "triggers",
+  "d1_databases",
+  "queues",
+  "durable_objects",
+  "migrations",
+  "workers_dev",
+  "preview_urls",
+  "keep_vars",
+  // The admin's assets (p0.9 §3.4): checked for the one supported shape, and staged from the plan.
+  "assets",
+]);
+
+/** A consumer's settings a preview keeps: batching and retries, nothing that names another queue. */
+const CONSUMER_SETTINGS = new Set([
+  "max_batch_size",
+  "max_batch_timeout",
+  "max_retries",
+  "retry_delay",
+  "max_concurrency",
+]);
+
+export interface PreviewNames {
+  identity: string;
+  slug: string;
+  nonce: string;
+  worker: string;
+  database: string;
+  queue: string;
+}
+
+const WORKER_NAME_MAX = 54;
+
+export function previewNames(store: string, name: string, nonce: string): PreviewNames {
+  const slug =
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .replace(/-{2,}/g, "-") || "preview";
+  // Cloudflare's workers.dev route refuses a Worker name over 54 characters while the script's
+  // previews flag is on, which it is by default with workers_dev (100315, research/26), even
+  // though a Worker with Durable Objects gets no version URLs. The store's name gives way
+  // before the nonce, which is what keeps two previews apart.
+  const room = WORKER_NAME_MAX - "-pv-".length - 1 - nonce.length;
+  const slugPart = slug.slice(0, Math.max(1, room - store.length));
+  const worker = `${store.slice(0, room - slugPart.length)}-pv-${slugPart}-${nonce}`;
+  return { identity: `${store}/${name}`, slug, nonce, worker, database: `${worker}-db`, queue: `${worker}-q` };
+}
+
+/** A preview's local directory: a hash of its identity, never its name (`--name ../../creds` stays inside). */
+export function localDir(cwd: string, identity: string): string {
+  return join(cwd, ".kedge", "previews", createHash("sha256").update(identity).digest("hex").slice(0, 16));
+}
+
+// ---- the Worker's config (§5.2) ----------------------------------------------------------------------
+
+export interface PreviewWorker {
+  worker: string;
+  main: string;
+  database: string;
+  databaseId: string;
+  migrationsDir: string;
+  queue: string;
+  vars?: Record<string, string>;
+  /** The plan's staged admin assets (p0.9 §3.4), when the store serves the admin. */
+  assetsDir?: string;
+}
+
+/** The Durable Object classes the config's migrations leave live, renames and deletions applied: doctor's reading. */
+const classesOf = (config: WranglerJson): string[] =>
+  declaredClasses((config.migrations ?? []) as Parameters<typeof declaredClasses>[0]);
+
+/** Built by allowlist from the store's config; a key this code doesn't know can't carry production through. */
+export function previewConfig(source: WranglerJson, p: PreviewWorker): Record<string, unknown> {
+  const refused = Object.keys(source).filter((k) => !ALLOWED.has(k));
+  if (refused.length)
+    throw new DeployRefused(
+      `wrangler.jsonc has ${refused.map((k) => `"${k}"`).join(", ")}, which a preview can't take yet: a preview never binds production's resources or services, and a binding needs its own preview copy first`,
+    );
+  const classes = classesOf(source);
+  // Every nested binding by allowlist too: a Durable Object binding with `script_name` reaches
+  // another Worker's objects (production's carts), and a consumer's `dead_letter_queue` names a
+  // queue the preview doesn't own (codex code r1).
+  const nested: string[] = [];
+  const dos = (
+    ((source.durable_objects as { bindings?: Record<string, unknown>[] } | undefined)?.bindings ?? []) as Record<
+      string,
+      unknown
+    >[]
+  ).map((b) => {
+    const extra = Object.keys(b).filter((k) => k !== "name" && k !== "class_name");
+    if (extra.length || (!classes.includes(String(b.class_name)) && b.class_name !== "SyntheticProviderDO"))
+      nested.push(
+        `the Durable Object binding ${String(b.name)} (${extra.join(", ") || "a class the store doesn't declare"})`,
+      );
+    return { name: String(b.name), class_name: String(b.class_name) };
+  });
+  const consumers = (source.queues?.consumers ?? []) as Record<string, unknown>[];
+  const consumer = consumers[0];
+  const extraConsumer = Object.keys(consumer ?? {}).filter((k) => k !== "queue" && !CONSUMER_SETTINGS.has(k));
+  if (extraConsumer.length) nested.push(`the queue consumer's ${extraConsumer.join(", ")}`);
+  if (consumers.length > 1 || (source.queues?.producers ?? []).some((q) => q.binding !== "EVENTS"))
+    nested.push("a queue binding other than EVENTS");
+  if ((source.d1_databases ?? []).some((d) => d.binding !== "DB")) nested.push("a D1 binding other than DB");
+  // Only the admin's shape (p0.9 §3.4): a fallback or run_worker_first could answer API paths with HTML.
+  const a = source.assets;
+  if (a && assetsShape(a).length) nested.push(`an \`assets\` block of another shape (${assetsShape(a).join("; ")})`);
+  if (nested.length)
+    throw new DeployRefused(
+      `wrangler.jsonc has ${nested.join("; ")}, which a preview can't take: a preview binds only resources it owns`,
+    );
+  const observability = (source.observability ?? {}) as Record<string, unknown>;
+  const vars = { ...(source.vars ?? {}), ...(p.vars ?? {}) };
+  const origins = new Set(
+    String(vars.ADMIN_ORIGINS ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+  origins.add(PREVIEW_ORIGIN);
+  return {
+    name: p.worker,
+    main: p.main,
+    compatibility_date: source.compatibility_date,
+    compatibility_flags: source.compatibility_flags ?? [],
+    workers_dev: true,
+    observability: {
+      ...observability,
+      logs: { ...((observability.logs as object | undefined) ?? {}), invocation_logs: false },
+    },
+    vars: { ...vars, ADMIN_ORIGINS: [...origins].join(","), KEDGE_ENVIRONMENT: "preview" },
+    triggers: { crons: source.triggers?.crons ?? [] },
+    d1_databases: [
+      { binding: "DB", database_name: p.database, database_id: p.databaseId, migrations_dir: p.migrationsDir },
+    ],
+    queues: {
+      producers: [{ binding: "EVENTS", queue: p.queue }],
+      consumers: [
+        {
+          ...Object.fromEntries(Object.entries(consumer ?? {}).filter(([k]) => CONSUMER_SETTINGS.has(k))),
+          queue: p.queue,
+        },
+      ],
+    },
+    durable_objects: {
+      bindings: [
+        ...dos.filter((b) => b.name !== "SYNTHETIC"),
+        { name: "SYNTHETIC", class_name: "SyntheticProviderDO" },
+      ],
+    },
+    ...(source.assets && p.assetsDir ? { assets: { directory: p.assetsDir, binding: "ASSETS" } } : {}),
+    // A new Worker has no history: one tag makes every class (§5.2).
+    migrations: [
+      { tag: "v1", new_sqlite_classes: [...classes.filter((c) => c !== "SyntheticProviderDO"), "SyntheticProviderDO"] },
+    ],
+  };
+}
+
+/** No production id or name may reach a preview's config. */
+export function sharedWithProduction(production: WranglerJson, preview: Record<string, unknown>): string[] {
+  const prod = new Set<string>();
+  const walk = (v: unknown) => {
+    if (typeof v === "string" && v.length > 3) prod.add(v);
+    else if (Array.isArray(v)) v.forEach(walk);
+    else if (v && typeof v === "object") Object.values(v).forEach(walk);
+  };
+  walk(production.name);
+  for (const d of production.d1_databases ?? []) walk([d.database_name, d.database_id]);
+  for (const q of [...(production.queues?.producers ?? []), ...(production.queues?.consumers ?? [])]) walk(q.queue);
+  const ours = [
+    preview.name,
+    ...((preview.d1_databases as { database_name: string; database_id: string }[]) ?? []).flatMap((d) => [
+      d.database_name,
+      d.database_id,
+    ]),
+    ...((preview.queues as { producers: { queue: string }[] }).producers ?? []).map((q) => q.queue),
+  ].map(String);
+  return ours.filter((v) => prod.has(v) && v !== "00000000-0000-0000-0000-000000000000");
+}
+
+// ---- the plan (§5.3) ------------------------------------------------------------------------------------
+
+export interface PlanFile {
+  version: 1;
+  store: string;
+  name: string;
+  /** The source config, as data; apply keeps only what the allowlist names. */
+  config: WranglerJson;
+  vars: Record<string, string>;
+  modules: Record<string, string>;
+  migrations: Record<string, string>;
+  /** The admin's assets, each file's hash (p0.9 §3.4): validated from the stream like the bundle. */
+  assets?: Record<string, string>;
+  /** Secrets the store's config asks for; only the caller of apply grants them. */
+  secrets: string[];
+}
+
+/** `kedge preview build`: bundles and writes the plan, with no credentials. */
+export function buildPlan(input: {
+  cwd: string;
+  name: string;
+  lock: Lock;
+  vars: Record<string, string>;
+  secrets: readonly string[];
+  bundle: (config: string, outdir: string) => void;
+}): { dir: string; plan: PlanFile } {
+  const w = readWrangler(input.cwd);
+  if (!w) throw new DeployRefused("no wrangler.jsonc");
+  const config = w.config as WranglerJson;
+  const dir = join(localDir(input.cwd, `${config.name}/${input.name}`), "plan");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(join(dir, "migrations"), { recursive: true });
+  const buildConfig = join(dir, "..", "build.wrangler.json");
+  const { build: _, ...rest } = config as WranglerJson & { build?: unknown };
+  // The admin's assets, staged into the plan, and its build in the Worker's code (p0.9 §2.4, §3.4).
+  const admin = stageAssets(input.cwd, config, join(dir, "assets"));
+  writeFileSync(
+    buildConfig,
+    JSON.stringify({
+      ...rest,
+      main: join(input.cwd, String(config.main ?? "src/index.ts")),
+      // The store's own constants kept, the admin's build beside them (it wins its one name).
+      ...(admin
+        ? {
+            assets: { ...config.assets, directory: join(dir, "assets") },
+            define: { ...((config as { define?: Record<string, string> }).define ?? {}), ...admin.define },
+          }
+        : {}),
+    }),
+  );
+  input.bundle(buildConfig, join(dir, "bundle"));
+  rmSync(buildConfig, { force: true });
+  const migrations: Record<string, string> = {};
+  for (const e of input.lock.entries) {
+    const bytes = readFileSync(join(input.cwd, "migrations", e.file));
+    if (sha256(bytes) !== e.sha256)
+      throw new DeployRefused(`${e.file} doesn't match kedge.lock.json; run kedge doctor`);
+    writeFileSync(join(dir, "migrations", e.file), bytes);
+    migrations[e.file] = e.sha256;
+  }
+  const plan: PlanFile = {
+    version: 1,
+    store: String(config.name),
+    name: input.name,
+    config,
+    vars: input.vars,
+    modules: hashTree(join(dir, "bundle")),
+    migrations,
+    ...(admin ? { assets: hashTree(join(dir, "assets")) } : {}),
+    secrets: [...input.secrets],
+  };
+  writeFileSync(join(dir, "plan.json"), JSON.stringify(plan, null, 2));
+  return { dir, plan };
+}
+
+/** The plan directory as one tar stream: what `docker cp <c>:<plan> -` gives the eval's trusted process. */
+export function tarPlan(dir: string): Buffer {
+  const entries: TarEntry[] = [];
+  const walk = (d: string, prefix: string) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      const rel = prefix ? `${prefix}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(p, rel);
+      else if (e.isFile()) entries.push({ path: rel, data: readFileSync(p) });
+    }
+  };
+  walk(dir, "");
+  return writeTar(entries);
+}
+
+/**
+ * Reads a plan from a tar stream into a fresh staging directory: only the
+ * regular files plan.json enumerates, each matching its hash, and nothing
+ * whose name starts with a dot (a hostile `.env` would reach Wrangler).
+ */
+export function stagePlan(stream: Buffer): { dir: string; plan: PlanFile } {
+  const entries = readTar(stream, LIMITS);
+  const planEntry = entries.find((e) => e.path === "plan.json");
+  if (!planEntry) throw new TarRefused("no plan.json");
+  let plan: PlanFile;
+  try {
+    plan = JSON.parse(planEntry.data.toString("utf8")) as PlanFile;
+  } catch {
+    throw new TarRefused("plan.json doesn't parse");
+  }
+  if (plan.version !== 1 || typeof plan.store !== "string" || typeof plan.name !== "string")
+    throw new TarRefused("plan.json isn't a plan");
+  const listed = new Map<string, string>([
+    ...Object.entries(plan.modules ?? {}).map(([p, h]) => [`bundle/${p}`, h] as [string, string]),
+    ...Object.entries(plan.migrations ?? {}).map(([p, h]) => [`migrations/${p}`, h] as [string, string]),
+    ...Object.entries(plan.assets ?? {}).map(([p, h]) => [`assets/${p}`, h] as [string, string]),
+  ]);
+  for (const p of listed.keys())
+    if (p.split("/").some((part) => part.startsWith(".") || part === "") || !/^(bundle|migrations|assets)\//.test(p))
+      throw new TarRefused(`${p} isn't a module, migration or asset a plan may name`);
+  for (const p of Object.keys(plan.migrations))
+    if (!/^\d{4}_[a-z0-9_]+\.sql$/.test(p)) throw new TarRefused(`${p} isn't a migration's name`);
+  for (const e of entries) {
+    if (e.path === "plan.json") continue;
+    const want = listed.get(e.path);
+    if (want === undefined) throw new TarRefused(`${e.path} isn't in plan.json`);
+    if (sha256(e.data) !== want) throw new TarRefused(`${e.path} doesn't match its hash`);
+  }
+  for (const p of listed.keys()) if (!entries.some((e) => e.path === p)) throw new TarRefused(`${p} is missing`);
+  if (!plan.modules["index.js"]) throw new TarRefused("the bundle has no index.js");
+  const dir = mkdtempSync(join(tmpdir(), "kedge-plan-"));
+  for (const e of entries) {
+    const target = join(dir, e.path);
+    mkdirSync(join(target, ".."), { recursive: true });
+    writeFileSync(target, e.data, { flag: "wx" });
+  }
+  return { dir, plan };
+}
+
+// ---- sealed credentials (§5.1) ------------------------------------------------------------------------
+
+const keyOf = (secret: string) => createHash("sha256").update(secret).digest();
+export function seal(secret: string, value: unknown): string {
+  const iv = randomBytes(12);
+  const c = createCipheriv("aes-256-gcm", keyOf(secret), iv);
+  const body = Buffer.concat([c.update(JSON.stringify(value), "utf8"), c.final()]);
+  return Buffer.concat([iv, body, c.getAuthTag()]).toString("base64url");
+}
+export function unseal<T>(secret: string, sealed: string): T {
+  const b = Buffer.from(sealed, "base64url");
+  const d = createDecipheriv("aes-256-gcm", keyOf(secret), b.subarray(0, 12));
+  d.setAuthTag(b.subarray(b.length - 16));
+  return JSON.parse(Buffer.concat([d.update(b.subarray(12, b.length - 16)), d.final()]).toString("utf8")) as T;
+}
+
+// ---- apply (§5.3) ---------------------------------------------------------------------------------------
+
+interface PreviewRow {
+  identity: string;
+  nonce: string;
+  worker: string;
+  database_name: string;
+  database_id: string | null;
+  queue_name: string;
+  queue_id: string | null;
+  classes: string;
+  consumer_id: string | null;
+  state: "creating" | "bootstrapped" | "destroying" | "destroyed";
+  credentials: string | null;
+  applied: string;
+  lost_create: number;
+  updated_at: number;
+}
+
+export interface ApplyInput {
+  cf: Cloudflare;
+  /** The plan's tar stream. */
+  stream: Buffer;
+  /** The store whose ops database records this preview; the plan's own name unless the caller says. */
+  store?: string;
+  /** The preview's name; the plan's unless the caller says. */
+  name?: string;
+  /** Secrets the caller grants from its own environment (--secret-env). */
+  secretEnv?: readonly string[];
+  /** The person's choice, when this preview is the store's first resource (p0.10 §7). */
+  jurisdiction?: JurisdictionChoice;
+  env: NodeJS.ProcessEnv;
+  fresh?: boolean;
+  takeOver?: string;
+  confirmStopped?: boolean;
+  /** HTTP for the bootstrap and seeding; tests replace it. */
+  fetch?: typeof fetch;
+  log?: (s: string) => void;
+  now?: () => number;
+  /** How long to wait for a new Worker's workers.dev route. */
+  readyMs?: number;
+  /** Waits (a TOTP step, a route coming up); tests make it instant. */
+  wait?: (ms: number) => Promise<void>;
+}
+
+export interface Applied {
+  url: string;
+  credentials: StoreCredentials;
+  databaseId: string;
+  worker: string;
+  /** The operation still held; the caller releases it after its scenarios (§5.3). */
+  release: (outcome: string) => Promise<void>;
+}
+
+const opsNames = (store: string): StoreNames => ({
+  worker: store,
+  database: `${store}-db`,
+  databaseId: "",
+  queue: `${store}-events`,
+  ops: `${store}-ops`,
+});
+
+export async function applyPlan(input: ApplyInput): Promise<Applied> {
+  const log = input.log ?? console.log;
+  const { dir: staging, plan } = stagePlan(input.stream);
+  const store = input.store ?? plan.store;
+  const name = input.name ?? plan.name;
+  // A preview before the first deploy makes <store>-ops, so it fixes the store's jurisdiction; it takes its store's.
+  const { ops, jurisdiction } = await openOps(input.cf, opsNames(store), input.now, input.jurisdiction ?? "ask");
+  const scope = `preview:${store}/${name}`;
+  const key = input.env.KEDGE_PREVIEW_KEY;
+  if (!key) throw new DeployRefused("set KEDGE_PREVIEW_KEY: a preview's credentials are sealed under it");
+  let opId: string;
+  const held = await ops.current(scope);
+  if (held) {
+    if (input.takeOver !== held.op_id || (held.executor && !input.confirmStopped)) throw new OperationHeld(held);
+    opId = (await ops.takeOver(scope, held.op_id, held.executor)).op_id;
+  } else opId = await ops.start(scope, "preview", { modules: plan.modules, migrations: plan.migrations }, "start");
+  const release = (outcome: string) => ops.finish(scope, opId, outcome, [{ modules: plan.modules }]);
+  try {
+    const p = new PreviewRun(
+      { ...input, jurisdiction },
+      ops,
+      scope,
+      opId,
+      staging,
+      plan,
+      `${store}/${name}`,
+      store,
+      name,
+      key,
+      log,
+    );
+    const out = await p.run();
+    return { ...out, release };
+  } catch (e) {
+    if (e instanceof LostOwnership) throw e;
+    await ops.finish(scope, opId, `failed: ${(e as Error).name}`, []).catch(() => {});
+    throw e;
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+class PreviewRun {
+  constructor(
+    private readonly input: ApplyInput,
+    private readonly ops: OpsStore,
+    private readonly scope: string,
+    private readonly opId: string,
+    private readonly staging: string,
+    private readonly plan: PlanFile,
+    private readonly identity: string,
+    private readonly store: string,
+    private readonly name: string,
+    private readonly key: string,
+    private readonly log: (s: string) => void,
+  ) {}
+
+  private get cf() {
+    return this.input.cf;
+  }
+
+  private async row(): Promise<PreviewRow | null> {
+    return (
+      ((await this.ops.query("SELECT * FROM preview WHERE identity = ?", [this.identity]))[0] as
+        | PreviewRow
+        | undefined) ?? null
+    );
+  }
+
+  /** A row write, conditional on this process still holding the preview's operation. */
+  private async write(set: string, params: unknown[]): Promise<void> {
+    const ok = await this.ops.query(
+      `UPDATE preview SET ${set}, updated_at = ? WHERE identity = ?
+         AND EXISTS (SELECT 1 FROM operation WHERE scope = ? AND op_id = ? AND executor = ?) RETURNING identity`,
+      [...params, (this.input.now ?? Date.now)(), this.identity, this.scope, this.opId, this.ops.executor],
+    );
+    if (ok.length !== 1) throw new LostOwnership(this.scope, set);
+  }
+
+  private get call(): Recorder {
+    return recorder(this.ops, this.scope, this.opId);
+  }
+
+  async run(): Promise<Omit<Applied, "release">> {
+    let row = await this.row();
+    const classes =
+      (previewConfig(this.plan.config, this.dummy()).migrations as { new_sqlite_classes: string[] }[])[0]
+        ?.new_sqlite_classes ?? [];
+    // A call on this generation that may still land: it's retired, not reused (codex code r7).
+    const uncertain = row
+      ? (await this.ops.intents(this.scope)).filter(
+          (i) => i.tag === row?.worker && (i.state === "open" || i.state === "unknown"),
+        )
+      : [];
+    if (row && row.state !== "destroyed" && uncertain.length) await this.write("lost_create = 1", []);
+    if (row && row.state !== "destroyed") {
+      const applied = JSON.parse(row.applied) as Record<string, string>;
+      const replaced = Object.entries(applied)
+        .filter(([f, h]) => this.plan.migrations[f] !== h)
+        .map(([f]) => f);
+      // Wrangler keeps any secret a deploy doesn't name, so a grant dropped from a plan would stay on the
+      // Worker: a preview holding a secret this apply doesn't grant is made again instead (codex code r18).
+      const granted = new Set([...CORE_SECRETS, ...(this.input.secretEnv ?? [])]);
+      const ungranted =
+        row.state === "bootstrapped" ? (await this.cf.secretNames(row.worker)).filter((n) => !granted.has(n)) : [];
+      const reasons = [
+        ...(this.input.fresh ? ["--fresh"] : []),
+        ...(ungranted.length ? [`it holds secrets this apply doesn't grant (${ungranted.join(", ")})`] : []),
+        ...(uncertain.length ? [`a call on it may still land (${uncertain.map((i) => i.kind).join(", ")})`] : []),
+        ...(row.state !== "bootstrapped" ? [`it was left ${row.state}`] : []),
+        ...(row.state === "bootstrapped" && JSON.stringify(JSON.parse(row.classes)) !== JSON.stringify(classes)
+          ? ["its Durable Object classes changed"]
+          : []),
+        ...(replaced.length ? [`applied migrations changed or vanished (${replaced.join(", ")})`] : []),
+      ];
+      if (reasons.length) {
+        // A bootstrapped preview is only recreated when asked; anything less finished holds nothing of value.
+        if (row.state === "bootstrapped" && !this.input.fresh && !uncertain.length)
+          throw new DeployRefused(
+            `this preview can't be updated in place: ${reasons.join("; ")}. Run with --fresh to recreate it`,
+          );
+        this.log(`recreating ${this.identity}: ${reasons.join("; ")}`);
+        await destroyRow(this.cf, row, this.log, (s, p) => this.write(s, p), this.call);
+        row = await this.row();
+      }
+    }
+    if (!row || row.state === "destroyed") {
+      const nonce = randomBytes(4).toString("hex");
+      const n = previewNames(this.store, this.name, nonce);
+      const now = (this.input.now ?? Date.now)();
+      // The previous generation's names outlive the row's reuse while a late create could still land.
+      if (row?.lost_create)
+        await this.ops.query(
+          `INSERT INTO preview_tombstone (worker, identity, database_name, queue_name, classes, destroyed_at)
+           VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (worker) DO NOTHING`,
+          [row.worker, row.identity, row.database_name, row.queue_name, row.classes, row.updated_at],
+        );
+      // Written before anything is created: the nonce is what makes a name ours (§5.1).
+      await this.ops.query(
+        `INSERT INTO preview (identity, nonce, worker, database_name, queue_name, state, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, 'creating', ?, ?)
+         ON CONFLICT (identity) DO UPDATE SET nonce = excluded.nonce, worker = excluded.worker, database_name = excluded.database_name,
+           queue_name = excluded.queue_name, state = 'creating', database_id = NULL, queue_id = NULL, consumer_id = NULL,
+           credentials = NULL, applied = '{}', classes = '[]', lost_create = 0, updated_at = excluded.updated_at`,
+        [this.identity, nonce, n.worker, n.database, n.queue, now, now],
+      );
+      row = (await this.row()) as PreviewRow;
+    }
+    // Resources: created by their recorded names; a lost answer is found by that exact name.
+    const create = async (kind: "d1" | "queue", nameOf: string, have: string | null) => {
+      if (have) return have;
+      const find = () => (kind === "d1" ? this.cf.findD1(nameOf) : this.cf.findQueue(nameOf));
+      const found = await find();
+      if (found) return found;
+      const id = await this.ops.openIntent(this.scope, this.opId, "create", kind, row.worker, { name: nameOf });
+      try {
+        const j = this.input.jurisdiction ?? "none";
+        const out = await (kind === "d1"
+          ? this.cf.createD1(nameOf, j === "none" ? null : j)
+          : this.cf.createQueue(nameOf));
+        await this.ops.closeIntent(id, "done", "answer");
+        return out;
+      } catch (e) {
+        if (!(e instanceof UnknownOutcome)) {
+          await this.ops.closeIntent(id, "failed", "answer");
+          throw e;
+        }
+        await this.write("lost_create = 1", []);
+        const again = await find();
+        await this.ops.closeIntent(id, again ? "done" : "unknown", again ? "an exact-name lookup found it" : "answer");
+        if (!again) throw e;
+        return again;
+      }
+    };
+    const databaseId = await create("d1", row.database_name, row.database_id);
+    // Recorded, found or made, the preview's database is accepted only where its store's data lives (p0.10 §7):
+    // one replaced outside Kedge would take the preview's writes elsewhere (codex code r13).
+    const where = await this.cf.d1Jurisdiction(databaseId);
+    if (where !== (this.input.jurisdiction ?? "none"))
+      throw new DeployRefused(
+        `${row.database_name} is in jurisdiction ${where}, and this store's is ${this.input.jurisdiction ?? "none"}`,
+      );
+    await this.write("database_id = ?", [databaseId]);
+    const queueId = await create("queue", row.queue_name, row.queue_id);
+    await this.write("queue_id = ?", [queueId]);
+
+    // The config, generated here from the validated plan: every path inside staging.
+    const config = previewConfig(this.plan.config, {
+      worker: row.worker,
+      main: join(this.staging, "bundle", "index.js"),
+      database: row.database_name,
+      databaseId,
+      migrationsDir: join(this.staging, "migrations"),
+      queue: row.queue_name,
+      // The store's jurisdiction, never the plan's: a preview's objects live where its store's do (p0.10 §7).
+      vars: { ...this.plan.vars, KEDGE_JURISDICTION: this.input.jurisdiction ?? "none" },
+      ...(this.plan.assets ? { assetsDir: join(this.staging, "assets") } : {}),
+    });
+    const configFile = join(this.staging, "..", `${row.worker}.wrangler.json`);
+    writeFileSync(configFile, JSON.stringify(config));
+    try {
+      try {
+        await this.call(row.worker, "migrate", "migrate", () =>
+          this.cf.applyMigrations({ config: configFile, database: row.database_name }),
+        );
+      } catch (e) {
+        // Some files may have committed and others not, which the applied registry can't say:
+        // the generation is retired rather than reasoned about (codex code r7).
+        await this.write("state = 'destroying'", []);
+        throw e;
+      }
+      await this.write("applied = ?", [JSON.stringify(this.plan.migrations)]);
+      const first = row.state === "creating";
+      // Core's secrets are generated once, on creation; a granted secret is attached on every apply, so a
+      // new grant or a rotated sandbox key reaches an existing preview (codex code r13). Wrangler keeps any
+      // secret the file doesn't name.
+      const values: Record<string, string> = first
+        ? Object.fromEntries(CORE_SECRETS.map((s) => [s, randomBytes(32).toString("base64url")]))
+        : {};
+      for (const s of this.input.secretEnv ?? []) {
+        if (NEVER_COPIED.test(s)) throw new DeployRefused(`${s} is never copied into a preview`);
+        if (!this.plan.secrets.includes(s))
+          throw new DeployRefused(`${s} isn't a secret the store's config asks a preview for`);
+        const v = this.input.env[s];
+        if (!v) throw new DeployRefused(`--secret-env ${s}, but the environment doesn't hold it`);
+        values[s] = v;
+      }
+      if (!first) {
+        const have = new Set(await this.cf.secretNames(row.worker));
+        const missing = CORE_SECRETS.filter((s) => !have.has(s));
+        if (missing.length)
+          throw new DeployRefused(
+            `the preview lacks ${missing.join(", ")}: a replacement would strand what's stored; run with --fresh`,
+          );
+      }
+      let secretsFile: string | undefined;
+      if (Object.keys(values).length) {
+        secretsFile = join(this.staging, "..", `${row.worker}.secrets.json`);
+        writeFileSync(secretsFile, JSON.stringify(values), { mode: 0o600 });
+        chmodSync(secretsFile, 0o600);
+      }
+      // What this deploy may create is recorded first, so a teardown deletes it even if the answer is lost.
+      await this.write("classes = ?", [JSON.stringify(classes)]);
+      try {
+        await this.call(row.worker, "deploy", "deploy", () =>
+          this.cf.deployWithClasses({
+            config: configFile,
+            message: `kedge preview ${this.identity}`,
+            ...(secretsFile ? { secretsFile } : {}),
+          }),
+        );
+      } catch (e) {
+        // It may still land, on this generation's Worker. So the generation is retired: the next apply
+        // recreates under a new nonce, where a late landing can't replace it, and the sweep removes
+        // what lands on the old name (codex code r4).
+        if (e instanceof UnknownOutcome) await this.write("state = 'destroying', lost_create = 1", []);
+        throw e;
+      } finally {
+        if (secretsFile) rmSync(secretsFile, { force: true });
+      }
+    } finally {
+      rmSync(configFile, { force: true });
+    }
+    const consumer = (await this.cf.consumers(queueId)).find((c) => c.script === row.worker);
+    if (consumer) await this.write("consumer_id = ?", [consumer.id]);
+    const url = `https://${row.worker}.${await this.cf.workersSubdomain()}.workers.dev`;
+
+    let credentials: StoreCredentials;
+    if (row.state === "bootstrapped" && row.credentials)
+      credentials = unseal<StoreCredentials>(this.key, row.credentials);
+    else credentials = await this.bootstrap(url, row, databaseId);
+    return { url, credentials: { ...credentials, url, databaseId }, databaseId, worker: row.worker };
+  }
+
+  private dummy(): PreviewWorker {
+    return { worker: "x", main: "x", database: "x", databaseId: "x", migrationsDir: "x", queue: "x" };
+  }
+
+  /** All or nothing (§5.3): the Owner, the keys, the sample data, then the sealed credentials and the state, last. */
+  private async bootstrap(url: string, row: PreviewRow, databaseId: string): Promise<StoreCredentials> {
+    const f = this.input.fetch ?? fetch;
+    const ready = Date.now() + (this.input.readyMs ?? 120_000);
+    for (;;) {
+      const res = await f(new URL("/health", url)).catch(() => null);
+      if (res?.status === 200) break;
+      // A preview whose port proves no test mode serves nothing (§5.2): say which, rather than time out.
+      const body =
+        res?.status === 503
+          ? ((await res.json().catch(() => null)) as {
+              error?: { code?: string; details?: { port?: string; mode?: string } };
+            } | null)
+          : null;
+      if (body?.error?.code === "PREVIEW_LIVE_CREDENTIALS")
+        throw new DeployRefused(
+          `the preview serves nothing: port ${body.error.details?.port ?? "?"} reports ${body.error.details?.mode ?? "?"} credentials, and a preview runs only with test ones`,
+        );
+      if (Date.now() > ready) throw new DeployRefused(`${url} didn't answer /health`);
+      await (this.input.wait ?? ((ms: number) => new Promise((r) => setTimeout(r, ms))))(3_000);
+    }
+    const email = `owner@${row.worker}.preview.invalid`;
+    const invite = await ownerInviteSql(email, Date.now());
+    await this.cf.executeD1File({ database: row.database_name, databaseId, sql: invite.sql });
+    const { owner, session } = await enrolOwner(url, invite.token, email, PREVIEW_ORIGIN, f, this.input.wait);
+    const bearer = { authorization: `Bearer ${session}`, "content-type": "application/json" };
+    const post = async (path: string, body: unknown) => {
+      const r = await f(new URL(path, url), {
+        method: "POST",
+        headers: { ...bearer, "idempotency-key": `kedge-preview-${randomBytes(8).toString("hex")}` },
+        body: JSON.stringify(body),
+      });
+      const j = (await r.json()) as Record<string, unknown>;
+      if (!r.ok) throw new DeployRefused(`bootstrap: ${path} answered ${r.status} ${JSON.stringify(j.error ?? j)}`);
+      return j;
+    };
+    // The preview origin, so a scenario can sign a customer in: that ceremony needs an allowed Origin.
+    const sf = await post("/admin/storefronts", { name: "Preview", allowed_origins: [PREVIEW_ORIGIN] });
+    const pk = await post(`/admin/storefronts/${String(sf.id)}/keys`, { name: "Preview" });
+    const sk = await post("/admin/api-keys", {
+      name: "Preview scenarios",
+      grants: PREVIEW_GRANTS.map((permission) => ({ permission, row_scope: "all" })),
+    });
+    await seed(url, { authorization: `Bearer ${String(sk.key)}` }, f, this.log);
+    const credentials: StoreCredentials = {
+      url,
+      publishableKey: String(pk.key),
+      secretKey: String(sk.key),
+      owner,
+      adminOrigin: PREVIEW_ORIGIN,
+      storefrontOrigin: PREVIEW_ORIGIN,
+      databaseId,
+    };
+    await this.write("credentials = ?, state = 'bootstrapped'", [seal(this.key, credentials)]);
+    this.log(`bootstrapped ${this.identity}: an Owner, a storefront key, a secret key and sample products`);
+    return credentials;
+  }
+}
+
+/** A mutating call on a generation, as an intent recorded before it's sent and closed by its answer. */
+type Recorder = <T>(worker: string, step: string, kind: string, fn: () => Promise<T>) => Promise<T>;
+
+/**
+ * Every mutating preview call goes through this, like a production deploy's (§3.1): tagged with the
+ * generation's Worker name, so a generation left with an open or unknown call is never reused and is
+ * re-checked by the sweep, whatever killed the run (codex code r7, r14).
+ */
+function recorder(ops: OpsStore, scope: string, opId: string): Recorder {
+  return async (worker, step, kind, fn) => {
+    const id = await ops.openIntent(scope, opId, step, kind, worker, {});
+    try {
+      const out = await fn();
+      await ops.closeIntent(id, "done", "answer");
+      return out;
+    } catch (e) {
+      await ops.closeIntent(id, e instanceof UnknownOutcome ? "unknown" : "failed", "answer");
+      throw e;
+    }
+  };
+}
+
+/** One generation's resources, by recorded id or exact name: what teardown and the sweep remove. */
+interface Generation {
+  identity: string;
+  worker: string;
+  database_name: string;
+  queue_name: string;
+  database_id?: string | null;
+  queue_id?: string | null;
+  classes: string;
+}
+
+/**
+ * Removes one generation in the order Cloudflare needs, and returns what it found: its Durable
+ * Object classes deleted (which removes their storage), its consumer detached (a Worker that
+ * consumes a queue can't be deleted, 10064), then the Worker, the queue and the database. The
+ * sweep uses it too, since a late deploy lands with its bindings (codex code r6).
+ */
+async function removeGeneration(
+  cf: Cloudflare,
+  g: Generation,
+  call: Recorder = (_w, _s, _k, fn) => fn(),
+): Promise<string[]> {
+  const removed: string[] = [];
+  const classes = JSON.parse(g.classes) as string[];
+  if (classes.length && (await cf.findWorker(g.worker))) {
+    const dir = mkdtempSync(join(tmpdir(), "kedge-stub-"));
+    try {
+      // Cloudflare refuses a queue consumer's Worker without queue and scheduled handlers (code 11001).
+      writeFileSync(
+        join(dir, "stub.js"),
+        "export default { fetch() { return new Response('removed', { status: 410 }); }, queue() {}, scheduled() {} };\n",
+      );
+      writeFileSync(
+        join(dir, "wrangler.json"),
+        JSON.stringify({
+          name: g.worker,
+          main: join(dir, "stub.js"),
+          compatibility_date: "2026-10-01",
+          migrations: [
+            { tag: "v1", new_sqlite_classes: classes },
+            { tag: "v2", deleted_classes: classes },
+          ],
+        }),
+      );
+      // A stub that loses its answer could land after teardown and bring the Worker back: recorded (codex code r14).
+      await call(g.worker, "destroy", "deploy", () =>
+        cf.deployWithClasses({ config: join(dir, "wrangler.json"), message: `kedge preview destroy ${g.identity}` }),
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+  // Only a queue still listed: a recorded one a lost answer already deleted would fail its consumer
+  // listing on every retry, and the teardown would never reach the database (codex code r27).
+  const live = await cf.findQueue(g.queue_name);
+  const queue = g.queue_id && g.queue_id !== live ? null : live;
+  if (queue)
+    for (const c of (await cf.consumers(queue)).filter((c) => c.script === g.worker))
+      await cf.deleteConsumer(queue, c.id);
+  if (await cf.findWorker(g.worker)) {
+    await cf.deleteWorker(g.worker);
+    removed.push(`Worker ${g.worker}`);
+  }
+  if (queue) {
+    await cf.deleteQueue(queue);
+    removed.push(`queue ${g.queue_name}`);
+  }
+  const db = g.database_id ?? (await cf.findD1(g.database_name));
+  if (db) {
+    await cf.deleteD1(db);
+    removed.push(`database ${g.database_name}`);
+  }
+  return removed;
+}
+
+/**
+ * Tears a preview down by recorded ids, in the order Cloudflare needs: its
+ * Durable Object classes deleted (which removes their storage), its consumer
+ * detached, then the Worker, the queue and the database; each confirmed gone
+ * by name before the row says so (§5.5). The row stays, `destroyed`.
+ */
+export async function destroyRow(
+  cf: Cloudflare,
+  row: PreviewRow,
+  log: (s: string) => void,
+  write: (set: string, params: unknown[]) => Promise<void>,
+  call?: Recorder,
+): Promise<void> {
+  await write("state = 'destroying'", []);
+  // The class list stays on the row: a tombstone written from it later is what lets the sweep delete
+  // the classes a late deploy makes again (codex code r11).
+  await removeGeneration(cf, row, call);
+  const left = [
+    ...((await cf.findWorker(row.worker)) ? [`Worker ${row.worker}`] : []),
+    ...((await cf.findQueue(row.queue_name)) ? [`queue ${row.queue_name}`] : []),
+    ...((await cf.findD1(row.database_name)) ? [`database ${row.database_name}`] : []),
+  ];
+  if (left.length)
+    throw new DeployRefused(`${row.identity} isn't gone yet: ${left.join(", ")}; run kedge preview destroy again`);
+  await write("state = 'destroyed', database_id = NULL, queue_id = NULL, consumer_id = NULL, credentials = NULL", []);
+  log(`destroyed ${row.identity}`);
+}
+
+export async function destroyPreview(input: {
+  cf: Cloudflare;
+  store: string;
+  name: string;
+  log?: (s: string) => void;
+  takeOver?: string;
+  confirmStopped?: boolean;
+}): Promise<void> {
+  const log = input.log ?? console.log;
+  const { ops } = await openOps(input.cf, opsNames(input.store));
+  const identity = `${input.store}/${input.name}`;
+  const scope = `preview:${identity}`;
+  const held = await ops.current(scope);
+  let opId: string;
+  if (held) {
+    if (input.takeOver !== held.op_id || (held.executor && !input.confirmStopped)) throw new OperationHeld(held);
+    opId = (await ops.takeOver(scope, held.op_id, held.executor)).op_id;
+  } else opId = await ops.start(scope, "destroy", { identity }, "destroy");
+  const row = (await ops.query("SELECT * FROM preview WHERE identity = ?", [identity]))[0] as PreviewRow | undefined;
+  try {
+    // A call on it that may still land keeps its names re-checked by the sweep for 7 days.
+    if (
+      row &&
+      row.state !== "destroyed" &&
+      (await ops.intents(scope)).some((i) => i.tag === row.worker && (i.state === "open" || i.state === "unknown"))
+    ) {
+      await ops.query("UPDATE preview SET lost_create = 1 WHERE identity = ?", [identity]);
+      row.lost_create = 1;
+    }
+    if (!row || row.state === "destroyed") log(`${identity} has nothing to destroy`);
+    else
+      await destroyRow(
+        input.cf,
+        row,
+        log,
+        async (set, params) => {
+          await ops.query(`UPDATE preview SET ${set}, updated_at = ? WHERE identity = ?`, [
+            ...params,
+            Date.now(),
+            identity,
+          ]);
+        },
+        recorder(ops, scope, opId),
+      );
+    await ops.finish(scope, opId, "destroyed", []);
+  } catch (e) {
+    await ops.stop(scope, opId).catch(() => {});
+    throw e;
+  }
+}
+
+/** `preview destroy --sweep`: what a late create left after a destroy, for tombstones of the last 7 days (§3.1). */
+export async function sweepPreviews(input: {
+  cf: Cloudflare;
+  store: string;
+  log?: (s: string) => void;
+  now?: number;
+}): Promise<string[]> {
+  const { ops } = await openOps(input.cf, opsNames(input.store));
+  const now = input.now ?? Date.now();
+  const swept: string[] = [];
+  for (const r of await ops.query(
+    `SELECT identity, worker, database_name, queue_name, classes FROM preview
+       WHERE state = 'destroyed' AND lost_create = 1 AND updated_at > ?1
+     UNION SELECT identity, worker, database_name, queue_name, classes FROM preview_tombstone WHERE destroyed_at > ?1`,
+    [now - 7 * 86_400_000],
+  ))
+    swept.push(...(await removeGeneration(input.cf, r as unknown as Generation)));
+  for (const s of swept) (input.log ?? console.log)(`swept ${s}`);
+  return swept;
+}
+
+/** Whether the store has HTTP scenarios, as deep as the config's `**` looks: one skipped would read as a pass (codex code r27). */
+export function hasScenarios(cwd: string): boolean {
+  const dir = join(cwd, "test", "scenarios");
+  return existsSync(dir) && readdirSync(dir, { recursive: true }).some((f) => String(f).endsWith(".http.ts"));
+}
+
+/** Runs the store's own HTTP scenarios against the preview, under the held operation (§5.3). */
+export function runScenarios(cwd: string, credentials: StoreCredentials, env: NodeJS.ProcessEnv): number {
+  if (!hasScenarios(cwd)) return 0;
+  const tmp = mkdtempSync(join(tmpdir(), "kedge-scn-"));
+  try {
+    const config = join(tmp, "vitest.scenarios.mjs");
+    writeFileSync(
+      config,
+      `export default { test: { root: ${JSON.stringify(cwd)}, include: ["test/scenarios/**/*.http.ts"], environment: "node", testTimeout: 600000, hookTimeout: 600000 } };\n`,
+    );
+    const r = spawnSync(join(cwd, "node_modules", ".bin", "vitest"), ["run", "--config", config], {
+      cwd,
+      stdio: childStdio(),
+      env: { ...env, KEDGE_PREVIEW_CREDENTIALS: JSON.stringify(credentials) },
+    });
+    return r.status ?? 1;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/** The local cache of a preview's credentials, mode 0600, in its hashed directory (gitignored, §5.1). */
+export function cacheCredentials(cwd: string, identity: string, credentials: StoreCredentials): string {
+  const dir = localDir(cwd, identity);
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, "credentials.json");
+  writeFileSync(file, JSON.stringify({ identity, ...credentials }, null, 2), { mode: 0o600 });
+  chmodSync(file, 0o600);
+  return file;
+}
+
+export const copyTree = (from: string, to: string) => cpSync(from, to, { recursive: true });