@kedge/cli 0.0.0-stage → 0.10.0

package/src/n1.ts

@@ -0,0 +1,217 @@
+// Which pending migrations the previous Worker survives (docs/proposals/p0.8-cli-agent-kit.md §6.2).
+// Rollback doesn't change "resources connected to your Worker", so every file
+// an ordinary deploy applies must leave the running code working: by proof
+// (core's release suites, a plugin generation's design) or by a statement
+// someone wrote. Shape alone proves little: adding a column breaks a
+// positional INSERT, and an expression index can throw on an old write.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PluginInstance } from "@kedge/core";
+import { statementTexts } from "@kedge/core";
+import { CUTOVER_MIGRATIONS } from "@kedge/db";
+import type { Lock, LockEntry } from "./compose";
+import type { Manifest } from "./manifest";
+import { schemaOf } from "./schema";
+
+export type Mode = "n1" | "cutover";
+
+export interface Classified {
+  file: string;
+  source: string;
+  mode: Mode;
+  /** Why it's N−1: proof, design, shape, or the statement's text. */
+  because: string;
+}
+
+export class NotN1 extends Error {
+  constructor(readonly problems: string[]) {
+    super(`pending migrations the running Worker may not survive:\n  ${problems.join("\n  ")}`);
+    this.name = "NotN1";
+  }
+}
+
+const strip = (s: string) =>
+  s
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+/** A name as SQLite resolves it: unquoted, and case-blind, so `local_Cache` is `local_cache` (codex code r19). */
+const unquote = (n: string) => n.replace(/^["`[]|["`\]]$/g, "").toLowerCase();
+const NAME = String.raw`(?:"[^"]+"|\x60[^\x60]+\x60|\[[^\]]+\]|[A-Za-z_][\w$]*)`;
+
+/** A plain column in an index: a name, maybe a direction or collation. No expression. */
+const plainColumn = (c: string) =>
+  new RegExp(String.raw`^${NAME}(\s+COLLATE\s+\w+)?(\s+(ASC|DESC))?$`, "i").test(c.trim());
+
+/** The object one statement creates, by kind and name, if it creates one. */
+function createdBy(t: string): string | null {
+  const m = new RegExp(
+    String.raw`^CREATE\s+(?:TEMP\s+|TEMPORARY\s+)?(?:UNIQUE\s+)?(TABLE|INDEX|TRIGGER|VIEW)\s+(?:IF\s+NOT\s+EXISTS\s+)?(${NAME})`,
+    "i",
+  ).exec(strip(t));
+  return m ? `${(m[1] as string).toUpperCase()}:${unquote(m[2] as string)}` : null;
+}
+
+/** Objects a file creates, by kind and name. */
+function created(texts: readonly string[]): Set<string> {
+  return new Set(texts.map(createdBy).filter((k): k is string => k !== null));
+}
+
+/**
+ * Judges a file's statements in the order they run. A drop may take only what an earlier
+ * statement of the same file created and that didn't exist before the file: `DROP x; CREATE x`
+ * would otherwise pass as "its own new table" and destroy a live one (codex code r2).
+ */
+function judgeFile(
+  texts: readonly string[],
+  before: ReadonlySet<string>,
+  mayDrop: (kind: string, name: string) => boolean,
+): ReturnType<typeof judge>[] {
+  const own = new Set<string>();
+  return texts.map((t) => {
+    const j = judge(t, own, mayDrop);
+    const made = createdBy(t);
+    if (made && !before.has(made)) own.add(made);
+    const dropped = /^DROP\s+(TABLE|INDEX|TRIGGER|VIEW)\s+(?:IF\s+EXISTS\s+)?(\S+)/i.exec(strip(t));
+    if (dropped) own.delete(`${(dropped[1] as string).toUpperCase()}:${unquote(dropped[2] as string)}`);
+    return j;
+  });
+}
+
+/** Every object that exists before `file` runs, by kind and name: the lock's earlier files applied in order. */
+function existingBefore(input: ClassifyInput, file: string): Set<string> {
+  const pending = new Set(input.pending.map((p) => p.file));
+  const texts: string[] = [];
+  for (const e of input.lock.entries) {
+    if (e.file === file) break;
+    texts.push(pending.has(e.file) ? input.text(e.file) : readFileSync(join(input.cwd, "migrations", e.file), "utf8"));
+  }
+  const schema = schemaOf(texts);
+  schema.db.close();
+  return new Set(
+    schema.objects.filter((o) => o.type !== "constraint").map((o) => `${o.type.toUpperCase()}:${o.name.toLowerCase()}`),
+  );
+}
+
+/** What one plugin or local statement is, for the shape rule and the drop rule. */
+function judge(
+  stmt: string,
+  own: Set<string>,
+  mayDrop: (kind: string, name: string) => boolean,
+): { ok: boolean; drop?: string; why: string } {
+  const s = strip(stmt);
+  if (/^CREATE\s+(?:TEMP\s+|TEMPORARY\s+)?TABLE\b/i.test(s)) return { ok: true, why: "CREATE TABLE" };
+  const idx = new RegExp(
+    String.raw`^CREATE\s+(UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?${NAME}\s+ON\s+${NAME}\s*\((.*)\)\s*(WHERE\b.*)?$`,
+    "i",
+  ).exec(s);
+  if (idx) {
+    if (idx[1]) return { ok: false, why: "a unique index can refuse the running Worker's inserts" };
+    if (idx[3]) return { ok: false, why: "a partial index's predicate can throw on the running Worker's writes" };
+    if (!(idx[2] as string).split(",").every(plainColumn))
+      return { ok: false, why: "an expression index can throw on the running Worker's writes" };
+    return { ok: true, why: "a plain non-unique index" };
+  }
+  const drop = new RegExp(String.raw`^DROP\s+(TABLE|INDEX|TRIGGER|VIEW)\s+(?:IF\s+EXISTS\s+)?(${NAME})`, "i").exec(s);
+  if (drop) {
+    const kind = (drop[1] as string).toUpperCase();
+    const name = unquote(drop[2] as string);
+    if (own.has(`${kind}:${name}`) || mayDrop(kind, name)) return { ok: true, why: "drops what it may" };
+    return { ok: false, drop: `${kind} ${name}`, why: "drops something that exists before this file" };
+  }
+  if (/^ALTER\s+TABLE\b.*\b(RENAME|DROP\s+COLUMN)\b/i.test(s)) {
+    const t = new RegExp(String.raw`^ALTER\s+TABLE\s+(${NAME})`, "i").exec(s);
+    const name = unquote((t?.[1] as string) ?? "");
+    if (own.has(`TABLE:${name}`)) return { ok: true, why: "renames or drops within its own new table" };
+    return { ok: false, drop: `TABLE ${name}`, why: "renames or drops part of something that exists before this file" };
+  }
+  if (/^ALTER\s+TABLE\b.*\bADD\b/i.test(s))
+    return { ok: false, why: "a new column breaks the running Worker's positional INSERT" };
+  return { ok: false, why: `"${s.slice(0, 60)}" isn't a shape the running Worker can't trip` };
+}
+
+export interface ClassifyInput {
+  cwd: string;
+  lock: Lock;
+  pending: readonly LockEntry[];
+  manifest: Manifest | null;
+  // biome-ignore lint/suspicious/noExplicitAny: each plugin brings its own options type
+  plugins: readonly PluginInstance<any>[];
+  /** Each file's text, from the staged bytes the deploy applies (§6.2). */
+  text: (file: string) => string;
+}
+
+/** Classifies each pending file, or throws NotN1 naming each one that isn't. */
+export function classify(input: ClassifyInput): Classified[] {
+  const out: Classified[] = [];
+  const problems: string[] = [];
+  const cutovers = new Set(CUTOVER_MIGRATIONS);
+  for (const e of input.pending) {
+    const text = input.text(e.file);
+    if (e.source.startsWith("core:0")) {
+      const f = e.source.slice("core:".length);
+      const mode = input.manifest?.migrations[f]?.mode ?? (cutovers.has(f) ? "cutover" : "n1");
+      out.push({
+        file: e.file,
+        source: e.source,
+        mode,
+        because:
+          mode === "cutover" ? "core marks it a cutover" : "core's release suites ran the previous release over it",
+      });
+      continue;
+    }
+    if (e.source.startsWith("core:")) {
+      // The pinned timezone's rules and the checkout-track fingerprint: core's generated files, N−1 by design.
+      out.push({ file: e.file, source: e.source, mode: "n1", because: "core generates it N−1 (p0.4 §4, p0.7 §6)" });
+      continue;
+    }
+    const [kind, plugin, ...rest] = e.source.split(":");
+    const id = rest.join(":");
+    const texts = statementTexts(text);
+    const before = existingBefore(input, e.file);
+    if (kind === "plugin" && (id.startsWith("generated:") || id.startsWith("entity:") || id === "install")) {
+      // The composer replacing what it owns: drops only of this plugin's earlier generated objects.
+      const earlier = new Set<string>();
+      for (const prior of input.lock.entries) {
+        if (prior.file === e.file) break;
+        if (prior.source.startsWith(`plugin:${plugin}:`))
+          for (const o of created(statementTexts(readFileSync(join(input.cwd, "migrations", prior.file), "utf8"))))
+            earlier.add(o);
+      }
+      const bad = judgeFile(texts, before, (k, n) => earlier.has(`${k}:${n}`)).filter((j) => j.drop);
+      if (bad.length) problems.push(`${e.file} (${e.source}): ${bad.map((b) => `${b.drop}: ${b.why}`).join("; ")}`);
+      else
+        out.push({
+          file: e.file,
+          source: e.source,
+          mode: "n1",
+          because: "a plugin generation: an older Worker's writes are fenced as PLUGIN_UPGRADING (p0.7 §6)",
+        });
+      continue;
+    }
+    const judged = judgeFile(texts, before, () => false);
+    const drops = judged.filter((j) => j.drop);
+    if (drops.length) {
+      problems.push(
+        `${e.file} (${e.source}): ${drops.map((d) => `${d.drop}: ${d.why}; only core's cutovers may, behind the fence`).join("; ")}`,
+      );
+      continue;
+    }
+    const statement =
+      /--\s*kedge:n-1\s+(\S.*)/.exec(text)?.[1]?.trim() ??
+      (kind === "plugin"
+        ? input.plugins.find((p) => p.definition.name === plugin)?.definition.migrations?.find((m) => m.id === id)?.n1
+        : undefined);
+    const shaped = judged.filter((j) => !j.ok);
+    if (shaped.length === 0)
+      out.push({ file: e.file, source: e.source, mode: "n1", because: "shape: only new tables and plain indexes" });
+    else if (statement) out.push({ file: e.file, source: e.source, mode: "n1", because: `stated: ${statement}` });
+    else
+      problems.push(
+        `${e.file} (${e.source}): ${[...new Set(shaped.map((j) => j.why))].join("; ")}. If the running Worker survives it, say why in the file: -- kedge:n-1 <why>`,
+      );
+  }
+  if (problems.length) throw new NotN1(problems);
+  return out;
+}

package/src/ops.ts

@@ -0,0 +1,373 @@
+// The operations database (docs/proposals/p0.8-cli-agent-kit.md §3.1): a
+// second D1 database per store, `<store>-ops`, that no Worker binds. It holds
+// what a lost CI runner can't lose and a restore of the store can't rewind:
+// who is running what on the store's production resources and on each preview
+// (one operation per scope), every control-plane call before it's sent and
+// its outcome, the deployment manifests, the hashes of applied migrations,
+// the store's own resources, and the preview registry.
+//
+// Exclusion is a primary key and compare-and-set updates, read back with
+// RETURNING, so of two callers one wins and a paused one finds its claim gone
+// at its next step. Nothing here takes over on a timer: elapsed time doesn't
+// prove a paused job is gone.
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import type { Row } from "./cf";
+
+export type Query = (sql: string, params?: readonly unknown[]) => Promise<Row[]>;
+
+export const OPS_SCHEMA = [
+  `CREATE TABLE IF NOT EXISTS kedge_ops_meta (id INTEGER PRIMARY KEY CHECK (id = 1), store TEXT NOT NULL, created_at INTEGER NOT NULL)`,
+  // The store's choices made once (p0.10 §7: its jurisdiction), each written once and never changed.
+  `CREATE TABLE IF NOT EXISTS ops_setting (name TEXT PRIMARY KEY, value TEXT NOT NULL, created_at INTEGER NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS operation (
+    scope TEXT PRIMARY KEY, op_id TEXT NOT NULL UNIQUE, kind TEXT NOT NULL, plan TEXT NOT NULL, step TEXT NOT NULL,
+    progress TEXT NOT NULL DEFAULT '{}',
+    executor TEXT, executor_label TEXT, heartbeat_at INTEGER NOT NULL, started_at INTEGER NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS operation_log (
+    op_id TEXT PRIMARY KEY, scope TEXT NOT NULL, kind TEXT NOT NULL, plans TEXT NOT NULL, outcome TEXT NOT NULL,
+    started_at INTEGER NOT NULL, ended_at INTEGER NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS intent (
+    id TEXT PRIMARY KEY, op_id TEXT NOT NULL, scope TEXT NOT NULL, step TEXT NOT NULL, kind TEXT NOT NULL,
+    tag TEXT NOT NULL, detail TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('open', 'done', 'failed', 'unknown', 'not_executed')),
+    created_at INTEGER NOT NULL, closed_at INTEGER, resolved_by TEXT)`,
+  `CREATE INDEX IF NOT EXISTS intent_scope_state ON intent (scope, state)`,
+  `CREATE TABLE IF NOT EXISTS deployment (
+    id TEXT PRIMARY KEY, seq INTEGER NOT NULL UNIQUE, op_id TEXT NOT NULL, mode TEXT NOT NULL,
+    before_half TEXT NOT NULL, after_half TEXT, created_at INTEGER NOT NULL, completed_at INTEGER)`,
+  `CREATE TABLE IF NOT EXISTS applied (file TEXT PRIMARY KEY, sha256 TEXT NOT NULL, applied_at INTEGER NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS resource (
+    kind TEXT NOT NULL, name TEXT NOT NULL, id TEXT, state TEXT NOT NULL, created_at INTEGER NOT NULL,
+    PRIMARY KEY (kind, name))`,
+  `CREATE TABLE IF NOT EXISTS preview (
+    identity TEXT PRIMARY KEY, nonce TEXT NOT NULL, worker TEXT NOT NULL, database_name TEXT NOT NULL,
+    database_id TEXT, queue_name TEXT NOT NULL, queue_id TEXT, classes TEXT NOT NULL DEFAULT '[]', consumer_id TEXT,
+    state TEXT NOT NULL CHECK (state IN ('creating', 'bootstrapped', 'destroying', 'destroyed')),
+    credentials TEXT, applied TEXT NOT NULL DEFAULT '{}', lost_create INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
+  // A destroyed generation whose create lost its answer, kept by its own names when the identity
+  // is reused, so the sweep still finds what a late create leaves for its 7 days (§3.1, codex code r2).
+  `CREATE TABLE IF NOT EXISTS preview_tombstone (
+    worker TEXT PRIMARY KEY, identity TEXT NOT NULL, database_name TEXT NOT NULL, queue_name TEXT NOT NULL,
+    classes TEXT NOT NULL DEFAULT '[]', destroyed_at INTEGER NOT NULL)`,
+];
+
+export class OperationHeld extends Error {
+  constructor(readonly held: OperationRow) {
+    super(
+      `${held.scope} is held by operation ${held.op_id} (${held.kind}, at "${held.step}", ${held.executor ? `run by ${held.executor_label ?? held.executor}` : "stopped"}, since ${new Date(held.started_at).toISOString()})`,
+    );
+    this.name = "OperationHeld";
+  }
+}
+
+export class LostOwnership extends Error {
+  constructor(scope: string, step: string) {
+    super(
+      `${scope}: this process no longer holds its operation (at "${step}"); another took it over or it ended. Stopping.`,
+    );
+    this.name = "LostOwnership";
+  }
+}
+
+export interface OperationRow {
+  scope: string;
+  op_id: string;
+  kind: string;
+  plan: string;
+  step: string;
+  /** What the operation has learned so far (ids, versions), so a resume continues from it. */
+  progress: string;
+  executor: string | null;
+  executor_label: string | null;
+  heartbeat_at: number;
+  started_at: number;
+}
+
+export interface IntentRow {
+  id: string;
+  op_id: string;
+  scope: string;
+  step: string;
+  kind: string;
+  tag: string;
+  detail: string;
+  state: "open" | "done" | "failed" | "unknown" | "not_executed";
+  created_at: number;
+  closed_at: number | null;
+  resolved_by: string | null;
+}
+
+export interface DeploymentRow {
+  id: string;
+  seq: number;
+  op_id: string;
+  mode: string;
+  before_half: string;
+  after_half: string | null;
+  created_at: number;
+  completed_at: number | null;
+}
+
+/** Who this process is, for a refusal to name: the host and, in CI, the run. */
+export function executorLabel(env: NodeJS.ProcessEnv = process.env): string {
+  const run = env.GITHUB_RUN_ID
+    ? ` (GitHub run ${env.GITHUB_RUN_ID}${env.GITHUB_RUN_ATTEMPT ? `/${env.GITHUB_RUN_ATTEMPT}` : ""})`
+    : "";
+  return `${hostname()}:${process.pid}${run}`;
+}
+
+export class OpsStore {
+  /** This process's identity: a random id, never reused. */
+  readonly executor = `ex_${randomUUID().replaceAll("-", "")}`;
+  constructor(
+    private readonly q: Query,
+    private readonly now: () => number = Date.now,
+    readonly label: string = executorLabel(),
+  ) {}
+
+  async init(store: string): Promise<void> {
+    for (const s of OPS_SCHEMA) await this.q(s);
+    await this.q("INSERT INTO kedge_ops_meta (id, store, created_at) VALUES (1, ?, ?) ON CONFLICT (id) DO NOTHING", [
+      store,
+      this.now(),
+    ]);
+    const [meta] = await this.q("SELECT store FROM kedge_ops_meta WHERE id = 1");
+    if (meta?.store !== store)
+      throw new Error(`this operations database belongs to ${String(meta?.store)}, not ${store}`);
+  }
+
+  /** A setting written once; the value already recorded wins, and is what this answers. */
+  async settle(name: string, value: string): Promise<string> {
+    await this.q("INSERT INTO ops_setting (name, value, created_at) VALUES (?, ?, ?) ON CONFLICT (name) DO NOTHING", [
+      name,
+      value,
+      this.now(),
+    ]);
+    const [r] = await this.q("SELECT value FROM ops_setting WHERE name = ?", [name]);
+    return String(r?.value);
+  }
+
+  async setting(name: string): Promise<string | null> {
+    const [r] = await this.q("SELECT value FROM ops_setting WHERE name = ?", [name]);
+    return r ? String(r.value) : null;
+  }
+
+  // ---- operations --------------------------------------------------------------------------------------
+  async current(scope: string): Promise<OperationRow | null> {
+    return ((await this.q("SELECT * FROM operation WHERE scope = ?", [scope]))[0] as OperationRow | undefined) ?? null;
+  }
+
+  /** Starts an operation, or refuses naming the one that holds the scope. */
+  async start(scope: string, kind: string, plan: unknown, step: string): Promise<string> {
+    const opId = `op_${randomUUID().replaceAll("-", "").slice(0, 20)}`;
+    const t = this.now();
+    const won = await this.q(
+      `INSERT INTO operation (scope, op_id, kind, plan, step, executor, executor_label, heartbeat_at, started_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (scope) DO NOTHING RETURNING op_id`,
+      [scope, opId, kind, JSON.stringify(plan), step, this.executor, this.label, t, t],
+    );
+    if (won.length === 1) return opId;
+    const held = await this.current(scope);
+    if (!held) throw new Error(`${scope}: the operation vanished while starting; run again`);
+    throw new OperationHeld(held);
+  }
+
+  /** Records the step about to run, and what's been learned; refuses unless this process still holds the operation. */
+  async step(scope: string, opId: string, step: string, progress?: unknown): Promise<void> {
+    const ok = await this.q(
+      `UPDATE operation SET step = ?, heartbeat_at = ?${progress === undefined ? "" : ", progress = ?"}
+       WHERE scope = ? AND op_id = ? AND executor = ? RETURNING op_id`,
+      [step, this.now(), ...(progress === undefined ? [] : [JSON.stringify(progress)]), scope, opId, this.executor],
+    );
+    if (ok.length !== 1) throw new LostOwnership(scope, step);
+  }
+
+  /** A clean stop: the operation stays, with nobody running it, for a resume. */
+  async stop(scope: string, opId: string): Promise<void> {
+    await this.q("UPDATE intent SET state = 'unknown' WHERE scope = ? AND op_id = ? AND state = 'open'", [scope, opId]);
+    await this.q(
+      "UPDATE operation SET executor = NULL, executor_label = NULL WHERE scope = ? AND op_id = ? AND executor = ?",
+      [scope, opId, this.executor],
+    );
+  }
+
+  /** Claims a stopped operation: of two resumes one wins, and a running one can't be resumed. */
+  async resume(scope: string, opId: string): Promise<OperationRow> {
+    const ok = await this.q(
+      "UPDATE operation SET executor = ?, executor_label = ?, heartbeat_at = ? WHERE scope = ? AND op_id = ? AND executor IS NULL RETURNING *",
+      [this.executor, this.label, this.now(), scope, opId],
+    );
+    if (ok.length === 1) return ok[0] as unknown as OperationRow;
+    const held = await this.current(scope);
+    if (!held || held.op_id !== opId) throw new Error(`${scope} has no operation ${opId}`);
+    throw new OperationHeld(held);
+  }
+
+  /**
+   * Takes over an operation whose executor is set, on someone's word that it
+   * was cancelled (--confirm-stopped). Its open intents become unknown: a call
+   * it had sent may still land, so the caller reconciles before acting.
+   */
+  async takeOver(scope: string, opId: string, observed: string | null): Promise<OperationRow> {
+    // From the executor the caller saw, and only from it: two runners recovering the same dead
+    // one can't both win, and the loser stops before it sends anything (codex code r8).
+    const ok = await this.q(
+      `UPDATE operation SET executor = ?, executor_label = ?, heartbeat_at = ?
+         WHERE scope = ? AND op_id = ? AND executor IS ? RETURNING *`,
+      [this.executor, this.label, this.now(), scope, opId, observed],
+    );
+    if (ok.length !== 1) {
+      const held = await this.current(scope);
+      if (!held || held.op_id !== opId) throw new Error(`${scope} has no operation ${opId}`);
+      throw new OperationHeld(held);
+    }
+    await this.q("UPDATE intent SET state = 'unknown' WHERE scope = ? AND op_id = ? AND state = 'open'", [scope, opId]);
+    return ok[0] as unknown as OperationRow;
+  }
+
+  /** A new plan under the same operation; the old one stays in its history (§6.2's --supersede). */
+  async supersede(scope: string, opId: string, plan: unknown, progress?: unknown): Promise<void> {
+    // The plan and what its progress may keep, in one statement: a crash between two writes would
+    // pair a new plan with the old plan's uploaded version (codex code r5).
+    const ok = await this.q(
+      `UPDATE operation SET plan = ?, heartbeat_at = ?${progress === undefined ? "" : ", progress = ?"}
+         WHERE scope = ? AND op_id = ? AND executor = ? RETURNING plan`,
+      [
+        JSON.stringify(plan),
+        this.now(),
+        ...(progress === undefined ? [] : [JSON.stringify(progress)]),
+        scope,
+        opId,
+        this.executor,
+      ],
+    );
+    if (ok.length !== 1) throw new LostOwnership(scope, "supersede");
+  }
+
+  /**
+   * Ends the operation, logged with every plan it ran under. Two requests, so each is safe to
+   * repeat: the log row is written only by the owner and only once, and a finish whose release
+   * was lost after its log landed releases on the next try instead of failing on the log's key
+   * and holding the store for good (codex code r1).
+   */
+  async finish(scope: string, opId: string, outcome: string, plans: readonly unknown[]): Promise<void> {
+    const row = await this.current(scope);
+    if (!row || row.op_id !== opId || row.executor !== this.executor) throw new LostOwnership(scope, "finish");
+    await this.q(
+      `INSERT INTO operation_log (op_id, scope, kind, plans, outcome, started_at, ended_at)
+         SELECT op_id, scope, kind, ?, ?, started_at, ? FROM operation WHERE scope = ? AND op_id = ? AND executor = ?
+         ON CONFLICT (op_id) DO NOTHING`,
+      [JSON.stringify(plans), outcome, this.now(), scope, opId, this.executor],
+    );
+    await this.q("DELETE FROM operation WHERE scope = ? AND op_id = ? AND executor = ?", [scope, opId, this.executor]);
+  }
+
+  // ---- intents (§3.1) ------------------------------------------------------------------------------------
+  async openIntent(
+    scope: string,
+    opId: string,
+    step: string,
+    kind: string,
+    tag: string,
+    detail: unknown,
+  ): Promise<string> {
+    const id = `int_${randomUUID().replaceAll("-", "").slice(0, 20)}`;
+    // Recorded only by the operation's current executor: a runner that lost it sends nothing.
+    const ok = await this.q(
+      `INSERT INTO intent (id, op_id, scope, step, kind, tag, detail, state, created_at)
+         SELECT ?, ?, ?, ?, ?, ?, ?, 'open', ? WHERE EXISTS
+           (SELECT 1 FROM operation WHERE scope = ? AND op_id = ? AND executor = ?) RETURNING id`,
+      [id, opId, scope, step, kind, tag, JSON.stringify(detail), this.now(), scope, opId, this.executor],
+    );
+    if (ok.length !== 1) throw new LostOwnership(scope, step);
+    return id;
+  }
+
+  async closeIntent(
+    id: string,
+    state: "done" | "failed" | "unknown" | "not_executed",
+    resolvedBy: string,
+  ): Promise<void> {
+    await this.q("UPDATE intent SET state = ?, closed_at = ?, resolved_by = ? WHERE id = ?", [
+      state,
+      this.now(),
+      resolvedBy,
+      id,
+    ]);
+  }
+
+  /** Calls whose outcome nobody knows: nothing in the scope runs while one exists. */
+  async unresolved(scope: string): Promise<IntentRow[]> {
+    return (await this.q("SELECT * FROM intent WHERE scope = ? AND state IN ('open', 'unknown') ORDER BY created_at", [
+      scope,
+    ])) as unknown as IntentRow[];
+  }
+
+  async intents(scope: string, opId?: string): Promise<IntentRow[]> {
+    return (await this.q(`SELECT * FROM intent WHERE scope = ?${opId ? " AND op_id = ?" : ""} ORDER BY created_at`, [
+      scope,
+      ...(opId ? [opId] : []),
+    ])) as unknown as IntentRow[];
+  }
+
+  async intent(id: string): Promise<IntentRow | null> {
+    return ((await this.q("SELECT * FROM intent WHERE id = ?", [id]))[0] as IntentRow | undefined) ?? null;
+  }
+
+  // ---- deployments (§6.5) ----------------------------------------------------------------------------------
+  async deployments(): Promise<DeploymentRow[]> {
+    return (await this.q("SELECT * FROM deployment ORDER BY seq DESC")) as unknown as DeploymentRow[];
+  }
+
+  async addDeployment(opId: string, mode: string, before: unknown): Promise<string> {
+    const id = `dep_${randomUUID().replaceAll("-", "").slice(0, 20)}`;
+    await this.q(
+      `INSERT INTO deployment (id, seq, op_id, mode, before_half, created_at)
+       VALUES (?, (SELECT COALESCE(MAX(seq), 0) + 1 FROM deployment), ?, ?, ?, ?)`,
+      [id, opId, mode, JSON.stringify(before), this.now()],
+    );
+    return id;
+  }
+
+  async completeDeployment(id: string, after: unknown): Promise<void> {
+    await this.q("UPDATE deployment SET after_half = ?, completed_at = ? WHERE id = ?", [
+      JSON.stringify(after),
+      this.now(),
+      id,
+    ]);
+  }
+
+  // ---- applied migrations' hashes (§6.1) --------------------------------------------------------------------
+  async appliedHashes(): Promise<Map<string, string>> {
+    return new Map((await this.q("SELECT file, sha256 FROM applied")).map((r) => [String(r.file), String(r.sha256)]));
+  }
+
+  async recordApplied(file: string, sha256: string): Promise<void> {
+    await this.q("INSERT INTO applied (file, sha256, applied_at) VALUES (?, ?, ?) ON CONFLICT (file) DO NOTHING", [
+      file,
+      sha256,
+      this.now(),
+    ]);
+  }
+
+  // ---- the store's own resources (§6.1) ------------------------------------------------------------------
+  async resource(kind: string, name: string): Promise<{ id: string | null; state: string } | null> {
+    const [r] = await this.q("SELECT id, state FROM resource WHERE kind = ? AND name = ?", [kind, name]);
+    return r ? { id: (r.id as string | null) ?? null, state: String(r.state) } : null;
+  }
+
+  /** Recorded before the resource is used (a Worker before its first upload). */
+  async recordResource(kind: string, name: string, id: string | null, state: string): Promise<void> {
+    await this.q(
+      `INSERT INTO resource (kind, name, id, state, created_at) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT (kind, name) DO UPDATE SET id = COALESCE(excluded.id, resource.id), state = excluded.state`,
+      [kind, name, id, state, this.now()],
+    );
+  }
+
+  query(sql: string, params?: readonly unknown[]): Promise<Row[]> {
+    return this.q(sql, params);
+  }
+}

package/src/order.ts

@@ -0,0 +1,7 @@
+/**
+ * Strings in code-point order. `localeCompare` follows the machine's ICU locale,
+ * which orders `_` differently under C.UTF-8 than under en_US, so a generated
+ * file or a hash sorted with it differs between two machines and `generate
+ * --check` fails on the one that didn't write it.
+ */
+export const byCodePoint = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);

package/src/output.ts

@@ -0,0 +1,35 @@
+// `--json` (p0.10 §5): stdout carries one object when the command ends, and
+// nothing else, so an agent parses it whole. Progress still reaches a person,
+// on stderr: console.log is pointed there for the command's run, and every
+// child the CLI starts (Wrangler, the store's checks and scenarios) writes its
+// stdout there too, since a child's line on stdout would break the object.
+import type { StdioOptions } from "node:child_process";
+
+let reserved = false;
+
+/** Runs `work` with stdout reserved for `emit` when `on`; nested runs keep the outer setting. */
+export async function withJsonOutput<T>(on: boolean, work: () => Promise<T>): Promise<T> {
+  if (!on || reserved) return work();
+  const log = console.log;
+  const info = console.info;
+  reserved = true;
+  console.log = console.error;
+  console.info = console.error;
+  try {
+    return await work();
+  } finally {
+    reserved = false;
+    console.log = log;
+    console.info = info;
+  }
+}
+
+/** The command's one result object. */
+export function emit(result: Record<string, unknown>): void {
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+/** A child's stdio: inherited, except that its stdout goes to stderr while stdout is reserved. */
+export function childStdio(): StdioOptions {
+  return reserved ? ["inherit", 2, "inherit"] : "inherit";
+}