@kedge/cli 0.0.0-stage → 0.10.0

package/src/doctor.ts

@@ -0,0 +1,701 @@
+// `kedge doctor` (docs/proposals/p0.8-cli-agent-kit.md §4): named checks, each
+// with a status and, when it fails, the failure and the fix, offline first.
+// Vendure's doctor is the shape (.reference/vendure/packages/cli/src/commands/doctor/doctor.ts);
+// the checks are what only Kedge has: a lock that owns migration order, an
+// installed core nobody edits, an error map with no gaps, a catalog that
+// claims every trigger, code that reaches the outside only through ports.
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parse } from "@babel/parser";
+import { ExtensionConfigError, Extensions, type KedgeConfig } from "@kedge/core";
+import { INVARIANTS } from "@kedge/testing/invariants";
+import { lintStore } from "./code-lint";
+import { ComposeError, compose, type Lock } from "./compose";
+import { CORE_CODES, catalogProblems, generatedFor, isLocal } from "./invariants";
+import { installedDrift, type Manifest, ownManifest } from "./manifest";
+import { composedTexts, raiseCodes, type Schema, schemaOf } from "./schema";
+import { compileStoreZone } from "./tz";
+import { unitDrift } from "./units";
+import { jsoncToJson, strictlyPublic } from "./worker-config";
+
+export type Status = "pass" | "fail" | "warn" | "skip";
+export interface CheckResult {
+  name: string;
+  status: Status;
+  message?: string;
+  /** Lines under the message: each problem, or each stated exception. */
+  details?: string[];
+  /** A failure only a person can fix (p0.10 §5): doctor then exits 3 with this as its `for you:` line. */
+  handoff?: string;
+}
+
+export interface DoctorInput {
+  cwd: string;
+  /** @kedge/db's migrations directory, where core's come from. */
+  coreDir: string;
+  /** The manifest to compare with; this CLI's own by default. */
+  manifest?: Manifest | null;
+}
+
+type WranglerConfig = {
+  main?: string;
+  d1_databases?: { binding?: string }[];
+  durable_objects?: { bindings?: { name?: string; class_name?: string }[] };
+  migrations?: {
+    tag?: string;
+    new_sqlite_classes?: string[];
+    new_classes?: string[];
+    deleted_classes?: string[];
+    renamed_classes?: { from: string; to: string }[];
+  }[];
+  queues?: { producers?: { binding?: string }[] };
+  observability?: { enabled?: boolean; logs?: { invocation_logs?: boolean } };
+  assets?: { directory?: string; binding?: string; not_found_handling?: string; run_worker_first?: unknown };
+  env?: Record<string, { observability?: WranglerConfig["observability"] }>;
+};
+
+export function readWrangler(cwd: string): { file: string; config: WranglerConfig } | null {
+  for (const f of ["wrangler.jsonc", "wrangler.json"]) {
+    const file = join(cwd, f);
+    if (existsSync(file))
+      return { file, config: JSON.parse(jsoncToJson(readFileSync(file, "utf8"))) as WranglerConfig };
+  }
+  return null;
+}
+
+export async function loadConfig(cwd: string): Promise<KedgeConfig> {
+  return ((await import(pathToFileURL(join(cwd, "kedge.config.ts")).href)) as { default: KedgeConfig }).default;
+}
+
+/** The classes a Worker's DO migrations leave declared, in order. */
+export function declaredClasses(migrations: WranglerConfig["migrations"] = []): string[] {
+  const live = new Set<string>();
+  for (const m of migrations) {
+    for (const c of [...(m.new_sqlite_classes ?? []), ...(m.new_classes ?? [])]) live.add(c);
+    for (const r of m.renamed_classes ?? []) {
+      live.delete(r.from);
+      live.add(r.to);
+    }
+    for (const c of m.deleted_classes ?? []) live.delete(c);
+  }
+  return [...live];
+}
+
+/** What an entry module exports by name; null when an `export *` makes that unknowable statically. */
+export function exportedNames(text: string): Set<string> | null {
+  const ast = parse(text, { sourceType: "module", plugins: ["typescript"] });
+  const names = new Set<string>();
+  for (const n of ast.program.body) {
+    if (n.type === "ExportAllDeclaration") return null;
+    if (n.type !== "ExportNamedDeclaration") continue;
+    for (const s of n.specifiers)
+      if (s.type === "ExportSpecifier")
+        names.add(s.exported.type === "Identifier" ? s.exported.name : s.exported.value);
+    const d = n.declaration;
+    if (d?.type === "ClassDeclaration" && d.id) names.add(d.id.name);
+    if (d?.type === "FunctionDeclaration" && d.id) names.add(d.id.name);
+    if (d?.type === "VariableDeclaration")
+      for (const v of d.declarations) {
+        if (v.id.type === "Identifier") names.add(v.id.name);
+        if (v.id.type === "ObjectPattern")
+          for (const p of v.id.properties)
+            if (p.type === "ObjectProperty" && p.value.type === "Identifier") names.add(p.value.name);
+      }
+  }
+  return names;
+}
+
+const pass = (name: string, message?: string): CheckResult => ({
+  name,
+  status: "pass",
+  ...(message ? { message } : {}),
+});
+const fail = (name: string, message: string, details?: string[]): CheckResult => ({
+  name,
+  status: "fail",
+  message,
+  ...(details?.length ? { details } : {}),
+});
+const skip = (name: string, message: string): CheckResult => ({ name, status: "skip", message });
+
+/** The offline checks (§4.1), in order. */
+export async function doctor(input: DoctorInput): Promise<CheckResult[]> {
+  const { cwd } = input;
+  const manifest = input.manifest === undefined ? ownManifest() : input.manifest;
+  const out: CheckResult[] = [];
+
+  // config: what a Worker would throw at boot.
+  let config: KedgeConfig | null = null;
+  try {
+    config = await loadConfig(cwd);
+    Extensions.resolve(config);
+    out.push(pass("config"));
+  } catch (e) {
+    out.push(
+      fail(
+        "config",
+        e instanceof ExtensionConfigError
+          ? `kedge.config.ts would fail at boot: ${e.message}`
+          : `kedge.config.ts doesn't load: ${(e as Error).message}`,
+      ),
+    );
+  }
+
+  // ports: what each effect does on a retry and which inputs are classified (the display P0.6a deferred).
+  if (config) {
+    const ports = [...(config.ports ?? []), ...(config.plugins ?? []).flatMap((p) => p.definition.ports ?? [])];
+    out.push({
+      ...pass("ports", ports.length ? `${ports.length} port${ports.length === 1 ? "" : "s"}` : "none"),
+      ...(ports.length
+        ? {
+            details: ports.flatMap((p) =>
+              Object.entries(p.operations).map(([name, op]) => {
+                const classified =
+                  op.kind === "effect" ? (op.classified ?? []).map((c) => `${c.field}:${c.scope}`).join(", ") : "";
+                return `${p.name}.${name}: ${op.kind}${op.kind === "effect" ? `, resend ${op.resend.policy}, ${p.deliveryClass}` : ""}${classified ? `, classified ${classified}` : ""}`;
+              }),
+            ),
+          }
+        : {}),
+    });
+  }
+
+  // lock: every composed file is what the lock says, and the lock lists every file.
+  const lockPath = join(cwd, "kedge.lock.json");
+  const lock = existsSync(lockPath) ? (JSON.parse(readFileSync(lockPath, "utf8")) as Lock) : null;
+  if (!lock) out.push(fail("lock", "kedge.lock.json is missing: run kedge generate"));
+  else {
+    const { createHash } = await import("node:crypto");
+    const problems: string[] = [];
+    for (const e of lock.entries) {
+      const path = join(cwd, "migrations", e.file);
+      if (!existsSync(path)) problems.push(`${e.file} is in the lock but not in migrations/`);
+      else if (createHash("sha256").update(readFileSync(path, "utf8")).digest("hex") !== e.sha256)
+        problems.push(`${e.file} was edited: applied migrations are immutable; put a change in a new migration`);
+    }
+    const locked = new Set(lock.entries.map((e) => e.file));
+    const dir = join(cwd, "migrations");
+    for (const f of existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".sql")) : [])
+      if (!locked.has(f))
+        problems.push(
+          `migrations/${f} isn't in kedge.lock.json: migrations/ is written only by kedge generate; yours go in local/`,
+        );
+    out.push(problems.length ? fail("lock", "the composed migrations don't match the lock", problems) : pass("lock"));
+  }
+
+  // plugin-sql: the composer's own rules over every plugin source, as generate runs them.
+  if (config && lock) {
+    try {
+      compose({
+        coreDir: input.coreDir,
+        plugins: config.plugins ?? [],
+        // A preview's own ports are locked like any other's (p0.8 §5.2).
+        ports: [...(config.ports ?? []), ...(config.preview?.ports ?? [])],
+        localDir: join(cwd, "local"),
+        outDir: join(cwd, "migrations"),
+        lockPath,
+        now: Date.now(),
+        dryRun: true,
+        ...(config.timezone ? { timezone: config.timezone } : {}),
+        compileZone: compileStoreZone,
+        tzPath: join(cwd, "src", "kedge.tz.ts"),
+      });
+      out.push(pass("plugin-sql"));
+    } catch (e) {
+      if (!(e instanceof ComposeError)) throw e;
+      out.push(fail("plugin-sql", "kedge generate refuses this config", e.message.split("\n")));
+    }
+  } else out.push(skip("plugin-sql", "needs a config and a lock"));
+
+  // core-migrations: core's composed files are byte for byte what the release shipped.
+  if (!manifest) out.push(skip("core-migrations", "no release manifest (a workspace install)"));
+  else if (lock) {
+    const problems = lock.entries
+      .filter((e) => e.source.startsWith("core:0"))
+      .flatMap((e) => {
+        const f = e.source.slice("core:".length);
+        const want = manifest.migrations[f]?.sha256;
+        return want === undefined
+          ? [`${e.file}: ${f} isn't a migration of Kedge ${manifest.version}`]
+          : want !== e.sha256
+            ? [
+                `${e.file}: differs from Kedge ${manifest.version}'s ${f}; core migrations are never edited (a fork's go in their own namespace, FORKING.md)`,
+              ]
+            : [];
+      });
+    out.push(
+      problems.length
+        ? fail("core-migrations", "core migrations differ from the release", problems)
+        : pass("core-migrations"),
+    );
+  }
+
+  // installed: nothing under node_modules/@kedge was edited, added or removed.
+  if (!manifest) out.push(skip("installed", "no release manifest (a workspace install)"));
+  else {
+    const drift = installedDrift(cwd, manifest);
+    out.push(
+      drift.length
+        ? fail(
+            "installed",
+            `installed Kedge differs from ${manifest.version}: never edit node_modules/@kedge; reinstall, and extend through config, a plugin or kedge eject`,
+            drift.flatMap((d) => [
+              ...d.changed.map((f) => `${d.package}/${f} changed`),
+              ...d.added.map((f) => `${d.package}/${f} added`),
+              ...d.missing.map((f) => `${d.package}/${f} missing`),
+            ]),
+          )
+        : pass("installed"),
+    );
+  }
+
+  // versions: every @kedge package at one version.
+  const kedgeDir = join(cwd, "node_modules", "@kedge");
+  if (existsSync(kedgeDir)) {
+    const versions = new Map<string, string>();
+    for (const p of readdirSync(kedgeDir)) {
+      const pj = join(kedgeDir, p, "package.json");
+      if (existsSync(pj))
+        versions.set(`@kedge/${p}`, (JSON.parse(readFileSync(pj, "utf8")) as { version: string }).version);
+    }
+    const distinct = new Set(versions.values());
+    out.push(
+      distinct.size > 1
+        ? fail(
+            "versions",
+            "@kedge packages are at different versions: upgrade them together (kedge upgrade)",
+            [...versions].map(([n, v]) => `${n} ${v}`),
+          )
+        : pass("versions"),
+    );
+  } else out.push(skip("versions", "no node_modules/@kedge"));
+
+  // error-map, invariants: read from the composed schema.
+  let schema: Schema | null = null;
+  if (lock) {
+    try {
+      schema = schemaOf(composedTexts(cwd, lock));
+    } catch (e) {
+      out.push(fail("error-map", `the composed migrations don't apply to an empty database: ${(e as Error).message}`));
+    }
+  }
+  if (schema && config) {
+    const problems: string[] = [];
+    const plugins = (config.plugins ?? []).map((p) => p.definition);
+    const ownerOf = (name: string) => generatedFor(name, plugins);
+    const local: string[] = [];
+    for (const o of schema.objects) {
+      if (o.name.startsWith("plg_") || ownerOf(o.name)) continue;
+      if (isLocal(o)) {
+        // No map can name a local code, so it reaches shoppers as INTERNAL: said, not failed (codex code r19).
+        for (const c of raiseCodes(o.sql)) if (!(c in CORE_CODES)) local.push(`local RAISE '${c}' in ${o.name}`);
+        continue;
+      }
+      for (const c of raiseCodes(o.sql))
+        if (!(c in CORE_CODES)) problems.push(`core RAISE '${c}' in ${o.name} maps to no error code`);
+    }
+    for (const d of plugins) {
+      const name = d.name;
+      const mapped = new Set(Object.keys(d.errors ?? {}));
+      for (const o of schema.objects.filter(
+        (o) => o.name.startsWith(`plg_${name}_`) || o.table.startsWith(`plg_${name}_`) || ownerOf(o.name) === d,
+      )) {
+        if (o.type === "constraint" && !mapped.has(o.name))
+          problems.push(`${name}'s constraint ${o.name} has no entry in its errors map`);
+        if (o.type === "trigger" || o.type === "view")
+          for (const c of raiseCodes(o.sql))
+            if (!mapped.has(c) && !c.startsWith("KEDGE_") && !(c in CORE_CODES))
+              problems.push(`${name}'s RAISE '${c}' in ${o.name} has no entry in its errors map`);
+      }
+    }
+    out.push(
+      problems.length
+        ? fail("error-map", "a refusal maps to no error code, so a shopper would get INTERNAL", [...new Set(problems)])
+        : local.length
+          ? {
+              name: "error-map",
+              status: "warn",
+              message:
+                "local SQL raises codes no map names, which shoppers get as INTERNAL: a refusal they should read belongs in a plugin's errors map",
+              details: [...new Set(local)],
+            }
+          : pass("error-map"),
+    );
+    const cat = catalogProblems(schema, new Set(INVARIANTS.map((i) => i.name)));
+    out.push(
+      cat.length
+        ? fail(
+            "invariants",
+            "the invariant catalog doesn't match the schema",
+            cat.map((p) => p.message),
+          )
+        : pass("invariants"),
+    );
+  } else if (!out.some((r) => r.name === "error-map")) {
+    out.push(skip("error-map", "needs a config and a lock"));
+    out.push(skip("invariants", "needs a config and a lock"));
+  }
+
+  // code: the store's executable code, through its imports.
+  const w = readWrangler(cwd);
+  const entry = w?.config.main ?? "src/index.ts";
+  const issues = lintStore(cwd, ["kedge.config.ts", entry]);
+  const failing = issues.filter((i) => !i.allowed);
+  const allowed = issues.filter((i) => i.allowed);
+  out.push(
+    failing.length
+      ? fail(
+          "code",
+          "code the lint refuses (p0.8 §4.5)",
+          failing.map((i) => `${i.file}:${i.line} ${i.rule}: ${i.message}`),
+        )
+      : {
+          ...pass(
+            "code",
+            allowed.length ? `${allowed.length} stated exception${allowed.length === 1 ? "" : "s"}` : undefined,
+          ),
+          ...(allowed.length ? { details: allowed.map((i) => `${i.file}:${i.line} ${i.rule}: ${i.allowed}`) } : {}),
+        },
+  );
+
+  // wrangler: the bindings core needs, the webhook flag, every declared class exported.
+  if (!w) out.push(fail("wrangler", "no wrangler.jsonc"));
+  else {
+    const c = w.config;
+    const problems: string[] = [];
+    if (!c.d1_databases?.some((d) => d.binding === "DB")) problems.push("no D1 binding DB");
+    for (const b of ["CART", "CLOCK", "JOURNAL"])
+      if (!c.durable_objects?.bindings?.some((d) => d.name === b)) problems.push(`no Durable Object binding ${b}`);
+    if (!c.queues?.producers?.some((q) => q.binding === "EVENTS")) problems.push("no queue producer EVENTS");
+    const strict = strictlyPublic(cwd);
+    if (strict.problem) problems.push(strict.problem);
+    const entryFile = join(cwd, entry);
+    if (existsSync(entryFile)) {
+      const names = exportedNames(readFileSync(entryFile, "utf8"));
+      if (names)
+        for (const cls of declaredClasses(c.migrations))
+          if (!names.has(cls))
+            problems.push(`${entry} doesn't export ${cls}, which wrangler.jsonc's migrations declare`);
+    } else problems.push(`${entry} doesn't exist`);
+    out.push(
+      problems.length ? fail("wrangler", "wrangler.jsonc isn't what a Kedge Worker needs", problems) : pass("wrangler"),
+    );
+
+    // invocation-logs: Cloudflare's per-request log records the URL, which erasure can't reach.
+    const off = (o: WranglerConfig["observability"]) => o?.logs?.invocation_logs === false;
+    const where = [
+      ...(off(c.observability) ? [] : ["the top level"]),
+      ...Object.entries(c.env ?? {})
+        .filter(([, e]) => e?.observability !== undefined && !off(e.observability))
+        .map(([n]) => `env.${n}`),
+    ];
+    out.push(
+      where.length
+        ? fail(
+            "invocation-logs",
+            `set "observability": { "logs": { "invocation_logs": false } } at ${where.join(", ")}: invocation logs record each request's URL, which can carry a customer's data that erasure can't reach`,
+          )
+        : pass("invocation-logs"),
+    );
+  }
+
+  // admin: the one assets shape research/27 measured (p0.9 §3.2).
+  if (w) out.push(adminCheck(cwd, w.config));
+
+  // unit-drift: each ejected unit against the upstream it was copied from (§7.3).
+  out.push(unitDrift(cwd, manifest, config));
+
+  // tz: the compiled rules are the lock's.
+  const tzFile = join(cwd, "src", "kedge.tz.ts");
+  if (lock && existsSync(tzFile)) {
+    const have = /version:\s*"([^"]+)"/.exec(readFileSync(tzFile, "utf8"))?.[1];
+    const pinned =
+      lock.entries
+        .find((e) => e.source.startsWith("core:tz:"))
+        ?.source.split(":")
+        .at(-1) ?? "utc";
+    out.push(
+      have === pinned
+        ? pass("tz")
+        : fail(
+            "tz",
+            `src/kedge.tz.ts holds rules ${have ?? "(none)"}, but the store is pinned to ${pinned}: restore it from version control or run kedge generate`,
+          ),
+    );
+  } else out.push(skip("tz", "no src/kedge.tz.ts or lock"));
+
+  return out;
+}
+
+const MARK: Record<Status, string> = { pass: "✓", fail: "✗", warn: "!", skip: "-" };
+
+export function formatReport(results: readonly CheckResult[]): string {
+  const lines: string[] = [];
+  for (const r of results) {
+    lines.push(`${MARK[r.status]} ${r.name}${r.message ? `: ${r.message}` : ""}`);
+    for (const d of r.details ?? []) lines.push(`    ${d}`);
+  }
+  const failed = results.filter((r) => r.status === "fail").length;
+  lines.push(failed ? `\n${failed} check${failed === 1 ? "" : "s"} failed` : "\nall checks passed");
+  return lines.join("\n");
+}
+
+// ---- the remote checks (§4.3) --------------------------------------------------------------------------
+
+const FAMILY_SECRET: Record<string, string> = {
+  auth: "KEDGE_AUTH_SECRET_V",
+  pepper: "KEDGE_KEY_PEPPER_V",
+  totp: "KEDGE_TOTP_KEY_V",
+};
+
+/**
+ * Whether the resolved credentials reach the store's account, claiming only
+ * what a read can show (p0.10 §4). A list succeeding proves the token answers
+ * for this account; it doesn't prove a write (Cloudflare's D1 list takes `D1
+ * Read` or `D1 Write`, creating a database only the latter:
+ * https://developers.cloudflare.com/api/resources/d1/subresources/database/methods/list/),
+ * so the writes are named as unverified, never passed. The token itself is never shown.
+ */
+export async function credentialsChecks(input: {
+  cf: import("./cf").Cloudflare;
+  source: string;
+  base: string;
+}): Promise<CheckResult[]> {
+  const { NeedsPerson } = await import("./cf");
+  const where = `from ${input.source}, sent to ${input.base}, account ${input.cf.account}`;
+  const read = await input.cf.readable();
+  const refused = Object.entries(read).filter(([, status]) => status !== null);
+  const out: CheckResult[] = [];
+  if (refused.length === Object.keys(read).length && refused.every(([, s]) => s === 401 || s === 403))
+    out.push(fail("credentials", `the token doesn't answer for this account (${where})`));
+  else if (refused.length)
+    out.push(
+      fail(
+        "credentials",
+        `the token can't list everything a store uses (${where})`,
+        refused.map(([kind, s]) => (s ? `${kind}: Cloudflare answered ${s}` : `${kind}: no answer`)),
+      ),
+    );
+  else
+    out.push(
+      pass(
+        "credentials",
+        `${where}; lists Workers, D1 and Queues. Writes are unverified until the first deploy: Workers Scripts Edit, D1 Edit, Queues Edit`,
+      ),
+    );
+  try {
+    out.push(pass("workers.dev", `${await input.cf.workersSubdomain()}.workers.dev`));
+  } catch (e) {
+    // Any answer is a report: a token that can't read the subdomain fails this check, never the run (codex code r7).
+    // An account without one is the owner's to choose: a handoff, not a technical failure (codex code r9).
+    if (e instanceof NeedsPerson) out.push({ ...fail("workers.dev", e.handoff), handoff: e.handoff });
+    else out.push(fail("workers.dev", (e as Error).message));
+  }
+  return out;
+}
+
+export interface RemoteDoctorInput {
+  cwd: string;
+  cf: import("./cf").Cloudflare;
+  lock: Lock;
+  /** Logpush jobs of the account, or null when the token can't read them. */
+  logpushJobs: () => Promise<{ dataset: string; enabled: boolean; fields: string[] | null }[] | null>;
+  now?: () => number;
+}
+
+/** Checks against the store's own Cloudflare resources; reads only. */
+export async function doctorRemote(input: RemoteDoctorInput): Promise<CheckResult[]> {
+  const { appliedNames, appliedProblems, openOps, SCOPE } = await import("./deploy");
+  const { storeNames } = await import("./store");
+  const now = (input.now ?? Date.now)();
+  const out: CheckResult[] = [];
+  const names = storeNames(input.cwd).names;
+  const opsId = await input.cf.findD1(names.ops);
+  if (!opsId) return [skip("remote", `no ${names.ops}: this store hasn't been deployed with kedge deploy`)];
+  const { ops, jurisdiction } = await openOps(input.cf, names);
+  const db = await ops.resource("d1", names.database);
+
+  // jurisdiction: the store's database is where <store>-ops records the store's data lives (p0.10 §7).
+  if (db?.id) {
+    const actual = await input.cf.d1Jurisdiction(db.id);
+    out.push(
+      actual === jurisdiction
+        ? pass("jurisdiction", jurisdiction)
+        : fail("jurisdiction", `${names.database} is in ${actual}, but the store's jurisdiction is ${jurisdiction}`),
+    );
+  }
+
+  // applied: D1's record is a prefix of the lock, and what ops recorded of each file's bytes still holds.
+  if (db?.id) {
+    const problems = appliedProblems(input.lock, await appliedNames(input.cf, db.id), await ops.appliedHashes());
+    out.push(
+      problems.length ? fail("applied", "the store's migrations don't match the lock", problems) : pass("applied"),
+    );
+  } else out.push(skip("applied", "no database recorded"));
+
+  // serving: the active version, crons and settings are what the latest deployment recorded (§3.1's residue).
+  const rows = (await ops.deployments()).filter((r) => r.after_half);
+  const last = rows[0] ? (JSON.parse(rows[0].after_half as string) as import("./deploy").Half) : null;
+  if (last && (await input.cf.findWorker(names.worker))) {
+    const problems: string[] = [];
+    const active = (await input.cf.deployments(names.worker))[0];
+    const serving = active?.versions.length === 1 ? active.versions[0]?.version_id : null;
+    if (serving !== last.versionId)
+      problems.push(
+        `serves ${serving ?? `a split (${active?.versions.length ?? 0} versions)`}, but the last deployment recorded ${last.versionId}: a late call, or a change outside Kedge`,
+      );
+    const crons = await input.cf.schedules(names.worker);
+    if (last.crons && JSON.stringify(crons) !== JSON.stringify(last.crons))
+      problems.push(`crons are ${JSON.stringify(crons)}, recorded ${JSON.stringify(last.crons)}`);
+    const settings = await input.cf.settings(names.worker);
+    if (last.settings && JSON.stringify(settings) !== JSON.stringify(last.settings))
+      problems.push(`settings are ${JSON.stringify(settings)}, recorded ${JSON.stringify(last.settings)}`);
+    const held = await ops.current(SCOPE);
+    out.push(
+      problems.length
+        ? fail("serving", "what serves isn't what Kedge last deployed", problems)
+        : pass(
+            "serving",
+            held ? `operation ${held.op_id} (${held.kind}) holds the store at "${held.step}"` : undefined,
+          ),
+    );
+    // do-classes: rollback across a class change is blocked (a warning).
+    const planned = (readWrangler(input.cwd)?.config.migrations ?? []) as unknown[];
+    if (JSON.stringify(planned) !== JSON.stringify(last.doMigrations ?? []))
+      out.push({
+        name: "do-classes",
+        status: "warn",
+        message: "this checkout changes Durable Object classes: rollback across the next deploy is blocked",
+      });
+  } else if (last)
+    out.push(
+      fail("serving", `${names.worker} was deployed, and no Worker by that name exists now`, [
+        "an ordinary deploy refuses: it would make new secrets and Durable Objects over the surviving database",
+      ]),
+    );
+  else out.push(skip("serving", "nothing deployed yet"));
+
+  // secrets: core's two, and each keyring family's active and retiring versions, as the database says.
+  if (db?.id && (await input.cf.findWorker(names.worker))) {
+    const have = new Set(await input.cf.secretNames(names.worker));
+    const need = new Set(["CART_TOKEN_SECRET", "ORDER_TOKEN_SECRET"]);
+    for (const r of await input.cf.queryD1(db.id, "SELECT name, active, retiring FROM keyring_setting")) {
+      const prefix = FAMILY_SECRET[String(r.name)];
+      if (!prefix) continue;
+      need.add(`${prefix}${String(r.active)}`);
+      if (r.retiring !== null && r.retiring !== undefined) need.add(`${prefix}${String(r.retiring)}`);
+    }
+    const missing = [...need].filter((s) => !have.has(s));
+    out.push(
+      missing.length
+        ? fail("secrets", "the Worker lacks secrets its database uses: set each with kedge secret put", missing)
+        : pass("secrets"),
+    );
+  } else out.push(skip("secrets", "nothing deployed yet"));
+
+  // logpush: a job that ships request URLs or headers out of erasure's reach.
+  const jobs = await input.logpushJobs().catch(() => null);
+  if (jobs === null) out.push(skip("logpush", "this token can't read Logpush jobs; check them in the dashboard"));
+  else {
+    const settings = (await input.cf.findWorker(names.worker)) ? await input.cf.settings(names.worker) : null;
+    const leaking = jobs.filter(
+      (j) =>
+        j.enabled &&
+        j.dataset === "workers_trace_events" &&
+        (j.fields === null || j.fields.some((f) => /^(Event|Request|URL|Headers)/i.test(f))),
+    );
+    out.push(
+      settings?.logpush && leaking.length
+        ? fail(
+            "logpush",
+            "a Logpush job ships Workers' request URLs or headers, which erasure can't reach: remove those fields",
+          )
+        : pass("logpush"),
+    );
+  }
+
+  // previews: old ones, and lost creates whose names are re-checked for 7 days (§3.1).
+  const previews = await ops.query(
+    "SELECT identity, worker, database_name, database_id, queue_name, state, lost_create, updated_at FROM preview",
+  );
+  const old = previews.filter((p) => p.state !== "destroyed" && now - Number(p.updated_at) > 14 * 86_400_000);
+  const orphans: string[] = [];
+  // A reused identity's earlier generation is in preview_tombstone, re-checked the same 7 days (codex code r6).
+  const tombstones = await ops.query(
+    "SELECT worker, database_name, queue_name FROM preview_tombstone WHERE destroyed_at > ?",
+    [now - 7 * 86_400_000],
+  );
+  for (const p of [
+    ...previews.filter(
+      (p) => p.state === "destroyed" && Number(p.lost_create) === 1 && now - Number(p.updated_at) < 7 * 86_400_000,
+    ),
+    ...tombstones,
+  ]) {
+    if (await input.cf.findWorker(String(p.worker))) orphans.push(`Worker ${String(p.worker)}`);
+    if (await input.cf.findD1(String(p.database_name))) orphans.push(`database ${String(p.database_name)}`);
+    if (await input.cf.findQueue(String(p.queue_name))) orphans.push(`queue ${String(p.queue_name)}`);
+  }
+  // A live preview's database where its store's data lives (p0.10 §7, codex code r13).
+  const misplaced: string[] = [];
+  for (const p of previews.filter((p) => p.state === "bootstrapped" && p.database_id))
+    if ((await input.cf.d1Jurisdiction(String(p.database_id))) !== jurisdiction)
+      misplaced.push(`database ${String(p.database_name)}`);
+  if (misplaced.length)
+    out.push(fail("previews", `a preview's database isn't in the store's jurisdiction, ${jurisdiction}`, misplaced));
+  else if (orphans.length)
+    out.push(
+      fail("previews", "a destroyed preview's late create left resources: kedge preview destroy --sweep", orphans),
+    );
+  else if (old.length)
+    out.push({
+      name: "previews",
+      status: "warn",
+      message: `${old.length} preview${old.length === 1 ? "" : "s"} older than 14 days`,
+      details: old.map((p) => String(p.identity)),
+    });
+  else out.push(pass("previews"));
+  return out;
+}
+
+/**
+ * The admin's assets block (p0.9 §3.2), when present, is exactly the supported
+ * shape: the installed `@kedge/admin`'s dist, bound as `ASSETS`, with no SPA
+ * fallback and no `run_worker_first`. That's a restriction to the one shape
+ * research/27 measured: `single-page-application` answers unmatched requests,
+ * missing chunks included, with HTML; `404-page` and `run_worker_first` aren't
+ * tested under the admin's routes. No block serves no admin: allowed, said.
+ */
+/**
+ * The one supported shape of an `assets` block (p0.9 §2.1), shared by doctor
+ * and preview so neither accepts what the other refuses: the `ASSETS` binding,
+ * no fallback (absent or "none") and no `run_worker_first`.
+ */
+export function assetsShape(a: NonNullable<WranglerConfig["assets"]>): string[] {
+  const problems: string[] = [];
+  if (a.binding !== "ASSETS") problems.push('`assets.binding` must be "ASSETS"');
+  if (a.not_found_handling !== undefined && a.not_found_handling !== "none")
+    problems.push(
+      `\`assets.not_found_handling\` is "${a.not_found_handling}": only "none" (or absent) is supported, since a fallback can answer API paths and missing chunks with HTML`,
+    );
+  if (a.run_worker_first !== undefined)
+    problems.push("`assets.run_worker_first` isn't supported: the admin's routes aren't tested under it");
+  return problems;
+}
+
+export function adminCheck(cwd: string, c: WranglerConfig): CheckResult {
+  const a = c.assets;
+  if (!a) return { name: "admin", status: "warn", message: "no `assets` block: this store serves no admin" };
+  const problems: string[] = [];
+  const installed = join(cwd, "node_modules", "@kedge", "admin", "dist");
+  const dir = a.directory ? resolve(cwd, a.directory) : null;
+  // Compared after links resolve, as pnpm installs through them; a directory that isn't there is just wrong.
+  const same =
+    dir !== null &&
+    (existsSync(installed) && existsSync(dir) ? realpathSync(dir) === realpathSync(installed) : dir === installed);
+  if (!same) problems.push('`assets.directory` must be "./node_modules/@kedge/admin/dist", the installed admin');
+  if (existsSync(installed) && !existsSync(join(installed, "app", "boot.js")))
+    problems.push("the installed @kedge/admin has no built admin (dist/app/boot.js)");
+  problems.push(...assetsShape(a));
+  return problems.length ? fail("admin", "the admin isn't served the supported way", problems) : pass("admin");
+}