@kedge/cli 0.0.0-stage → 0.10.0

package/src/compose.ts

@@ -0,0 +1,637 @@
+// `kedge generate`'s composer (K11, D-036). Wrangler applies every migration
+// file it hasn't recorded, even one numbered below files already applied
+// (research/15), so filenames can't keep two stores in the same order. The
+// lock owns it: core first, then plugins in config order, then local, and
+// every new file is numbered after every file already in the lock. An
+// applied entry is never edited, removed or re-ordered; the composer refuses
+// rather than writes when one would be.
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  acquireSql,
+  addFieldSql,
+  BREAK,
+  checkoutTracksShaInput,
+  columnsOf,
+  createEntitySql,
+  type EffectOperation,
+  ENTITY_COLUMNS,
+  ENTITY_LIMITS,
+  type EntityDefinition,
+  effectiveMax,
+  entityDeclInput,
+  entityTriggerNames,
+  entityTriggersSql,
+  type FactTable,
+  factGuardSql,
+  factTables,
+  generatedObjectNames,
+  installSql,
+  lintSql,
+  markedMigrationSql,
+  operationContract,
+  overlappingName,
+  type PluginInstance,
+  type PortDefinition,
+  permissionsOf,
+  registrationKinds,
+  sortIndexSql,
+  statementTexts,
+  subscriptionSql,
+  type TrackLock,
+  type TzTable,
+  trackLock,
+  trackLockProblems,
+  tracksShaInput,
+  UTC_TZ,
+  unreachableStates,
+} from "@kedge/core";
+import { byCodePoint } from "./order";
+import { collect, lintPlugin } from "./plugin-lint";
+import { verifyWithSqlite } from "./sqlite-verify";
+import { tzMigrationSql, tzModule } from "./tz";
+
+export interface LockEntry {
+  /** The composed file's name, `NNNN_<tag>.sql`. */
+  file: string;
+  /** Where it came from: `core:<file>`, `plugin:<name>:<id>`, `plugin:<name>:install`, `plugin:<name>:generated:<sha>`, `local:<file>`. */
+  source: string;
+  sha256: string;
+}
+export interface Lock {
+  version: 1;
+  entries: LockEntry[];
+  plugins: Record<
+    string,
+    {
+      installationId: string;
+      /** The current generation's content hash and the objects it installed, to drop when it's replaced. */
+      generatedSha256: string;
+      generatedObjects: string[];
+      /** Every fact table the plugin ever declared: its guards stay while its facts do. */
+      factTables?: FactTable[];
+      /** How many generations have been composed; each new one is a new source, even if its content repeats an older one. */
+      generation: number;
+      /** The plugin has declared subscribers at some generation: removing the last one still retires its rows (p0.6a §2.2). */
+      subscribed?: boolean;
+      /**
+       * Every subscriber and timer id it has declared, canonical, with its
+       * kind: one may vanish only by `retired` (code r10), and never changes
+       * kind (code r11), since a delivery is dispatched by the kind it was
+       * stored under.
+       */
+      registrations?: Record<string, "subscriber" | "timer">;
+      /** P0.7 (§3.1): each track's subject, states with their terminal flags, transition names and read permission. */
+      tracks?: Record<string, TrackLock>;
+      /** P0.7 (§4.3): each entity's physical columns and what decides its rows and readers. */
+      entities?: Record<string, EntityLock>;
+    }
+  >;
+  /** P0.7 (§3.3): the store-wide checkout-track fingerprint last composed, and how many times it changed. */
+  checkoutTracks?: { sha: string | null; generation: number };
+  /** The store's pinned zone and rules version (p0.4 §4): fixed once composed. */
+  timezone?: { zone: string; version: string };
+  /**
+   * Each effect operation version's contract hash, by `<port>.<operation>@<version>`
+   * (p0.6a §4.2): a locked version's contract never changes, and no locked
+   * version leaves the config, since a record admitted under it is recovered
+   * by its own `call` and `observe`.
+   */
+  contracts?: Record<string, string>;
+}
+
+/** What `kedge generate` remembers of an entity (p0.7 §4.3). */
+export interface EntityLock {
+  /** How many entity sources were composed for it: its table, then each set of added fields. */
+  generation: number;
+  order: EntityDefinition["order"];
+  read: string;
+  /** Every physical column the table has, generated ones included. */
+  columns: string[];
+  fields: Record<
+    string,
+    {
+      type: string;
+      required: boolean;
+      class: string;
+      max: number | null;
+      options: string[];
+      scope: string | null;
+      sort: boolean;
+    }
+  >;
+}
+
+const fieldLock = (f: EntityDefinition["fields"][string]) => ({
+  type: f.type,
+  required: Boolean(f.required),
+  class: f.type === "staff" ? "pii" : (f.class ?? "public"),
+  max: f.max ?? null,
+  options: [...(f.options ?? [])],
+  scope: f.scope ?? null,
+  sort: Boolean(f.sort),
+});
+
+/**
+ * An entity's evolution (p0.7 §4.3): the refusals, and the SQL a changed
+ * declaration composes (a new table, or added nullable columns and indexes).
+ */
+function entityChange(
+  plugin: string,
+  name: string,
+  def: EntityDefinition,
+  was: EntityLock | undefined,
+): { problems: string[]; sql: string[]; lock: EntityLock } {
+  const problems: string[] = [];
+  const at = `${plugin}: entity "${name}"`;
+  const fields = Object.fromEntries(Object.entries(def.fields).map(([n, f]) => [n, fieldLock(f)]));
+  const columns = [...ENTITY_COLUMNS, ...Object.entries(def.fields).flatMap(([n, f]) => columnsOf(n, f))];
+  const read = permissionsOf(plugin, name, def).read;
+  if (!was) {
+    return {
+      problems,
+      sql: createEntitySql(plugin, name, def),
+      lock: { generation: 1, order: def.order, read, columns, fields },
+    };
+  }
+  if (def.order !== was.order) problems.push(`${at}: order changed from ${was.order}; rows already attach as it said`);
+  if (read !== was.read)
+    problems.push(
+      `${at}: its read permission changed; an older Worker would still read under the old one (P0.8's cutover)`,
+    );
+  const sql: string[] = [];
+  for (const [n, f] of Object.entries(was.fields)) {
+    const now = fields[n];
+    const f2 = `${at} field "${n}"`;
+    if (!now) {
+      problems.push(`${f2} was removed; its data stays: keep it declared, or write a reviewed migration`);
+      continue;
+    }
+    if (now.type !== f.type) problems.push(`${f2} changed type from ${f.type} to ${now.type}`);
+    if (now.required !== f.required)
+      problems.push(`${f2} changed required; stored rows or older readers depend on it (P0.8's cutover)`);
+    if (now.class !== f.class)
+      problems.push(
+        `${f2} changed class from ${f.class}; an older Worker would still project it (P0.8's cutover; or a new field)`,
+      );
+    if (now.scope !== f.scope) problems.push(`${f2} changed its scope mapping; older readers would still scope by it`);
+    // An absent max is its type's default, so declaring one below it narrows too (codex code r1).
+    const maxBefore = effectiveMax(f);
+    const maxNow = effectiveMax(now);
+    if (maxBefore !== null && maxNow !== null && maxNow < maxBefore) problems.push(`${f2}: max can only rise`);
+    for (const o of f.options)
+      if (!now.options.includes(o)) problems.push(`${f2}: option "${o}" was removed; options may only be added`);
+    if (now.sort && !f.sort) sql.push(sortIndexSql(plugin, name, n));
+  }
+  for (const [n, f] of Object.entries(def.fields)) {
+    if (Object.hasOwn(was.fields, n)) continue;
+    if (f.required)
+      problems.push(`${at} field "${n}" is new and required; stored rows have no value (make it optional)`);
+    sql.push(...addFieldSql(plugin, name, n, f));
+    if (f.sort) sql.push(sortIndexSql(plugin, name, n));
+  }
+  const union = new Set([...was.columns, ...columns]);
+  if (union.size > ENTITY_LIMITS.COLUMNS_MAX)
+    problems.push(
+      `${at}: ${union.size} physical columns with those already in the table, over ${ENTITY_LIMITS.COLUMNS_MAX}`,
+    );
+  return {
+    problems,
+    sql,
+    lock: { generation: was.generation + (sql.length ? 1 : 0), order: def.order, read, columns: [...union], fields },
+  };
+}
+
+export class ComposeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ComposeError";
+  }
+}
+
+const sha = (s: string) => createHash("sha256").update(s).digest("hex");
+const sqlFiles = (dir: string) =>
+  existsSync(dir)
+    ? readdirSync(dir)
+        .filter((f) => f.endsWith(".sql"))
+        .sort((a, b) => Number.parseInt(a, 10) - Number.parseInt(b, 10) || byCodePoint(a, b))
+    : [];
+/** Statements re-joined with the separator every migration runner splits on. */
+const normalize = (sql: string) =>
+  statementTexts(sql)
+    .map((s) => `${s};`)
+    .join(BREAK);
+
+interface Source {
+  source: string;
+  tag: string;
+  sql: string;
+}
+
+export interface ComposeInput {
+  /** @kedge/db's migrations, applied in their own order. */
+  coreDir: string;
+  /** The merchant's plugins, in kedge.config.ts order. */
+  // biome-ignore lint/suspicious/noExplicitAny: each plugin brings its own options type
+  plugins: readonly PluginInstance<any>[];
+  /** The merchant's own migrations (`local/`), linted under the local_ prefix. */
+  localDir: string;
+  /** Where wrangler applies from. */
+  outDir: string;
+  lockPath: string;
+  now: number;
+  newInstallationId?: () => string;
+  /** Compute what would be written, and write nothing (`kedge generate --check`). */
+  dryRun?: boolean;
+  /** kedge.config.ts's `timezone`; the store stays on UTC without one (p0.4 §4). */
+  timezone?: string;
+  /** Compiles a zone with this toolchain's IANA data; only called the first time. */
+  compileZone?: (zone: string) => TzTable;
+  /** Where the compiled table goes (src/kedge.tz.ts). */
+  tzPath?: string;
+  /** kedge.config.ts's own ports; each plugin's come with its definition. */
+  ports?: readonly PortDefinition[];
+}
+
+export interface ComposeResult {
+  written: string[];
+  lock: Lock;
+  /**
+   * The lock would differ from the one on disk (code r12): a new contract
+   * version or registration changes it without any migration, and `--check`
+   * must refuse that too, or a version CI let through unlocked could later
+   * change under the records admitted with it.
+   */
+  lockChanged: boolean;
+  /** Things the merchant should know that aren't failures (a newer toolchain's tz data). */
+  notes: string[];
+}
+
+/** Composes, lints and writes the new migration files and the lock. Throws ComposeError and writes nothing on any violation. */
+export function compose(input: ComposeInput): ComposeResult {
+  const lock: Lock = existsSync(input.lockPath)
+    ? (JSON.parse(readFileSync(input.lockPath, "utf8")) as Lock)
+    : { version: 1, entries: [], plugins: {} };
+  const problems: string[] = [];
+  const notes: string[] = [];
+  let tzWrite: { path: string; text: string } | null = null;
+
+  // 1. What the config wants, in order.
+  const desired: Source[] = [];
+  for (const f of sqlFiles(input.coreDir)) {
+    desired.push({
+      source: `core:${f}`,
+      tag: f.replace(/^\d+_/, "").replace(/\.sql$/, ""),
+      sql: readFileSync(join(input.coreDir, f), "utf8"),
+    });
+  }
+  // The store's zone (p0.4 §4), after core (store_time exists) and before
+  // plugins. Fixed at install: a different zone is refused, and a newer
+  // toolchain's rules are reported, never adopted (P2.3 adopts them).
+  let timezone = lock.timezone;
+  if (input.timezone === undefined && !timezone && input.tzPath && !existsSync(input.tzPath)) {
+    // No zone configured: the Worker still gets its table, UTC at the version the database is
+    // seeded with, so `createKedge(config, { tz })` is the same line in every store.
+    tzWrite = { path: input.tzPath, text: tzModule(UTC_TZ) };
+  }
+  if (input.timezone !== undefined) {
+    if (timezone && timezone.zone !== input.timezone) {
+      problems.push(
+        `kedge.config.ts says timezone "${input.timezone}", but this store's zone is fixed at "${timezone.zone}"`,
+      );
+    } else if (!timezone) {
+      if (!input.compileZone || !input.tzPath) problems.push("a timezone needs the zone compiler and src/kedge.tz.ts");
+      else {
+        const tz = input.compileZone(input.timezone);
+        timezone = { zone: tz.zone, version: tz.version };
+        desired.push({
+          source: `core:tz:${tz.zone}:${tz.version}`,
+          tag: `tz_${tz.zone.replace(/[^A-Za-z0-9]+/g, "_").toLowerCase()}`,
+          sql: tzMigrationSql(tz),
+        });
+        tzWrite = { path: input.tzPath, text: tzModule(tz) };
+      }
+    } else {
+      if (input.tzPath && !existsSync(input.tzPath))
+        problems.push(
+          `${input.tzPath} is missing; restore it from version control (it pins ${timezone.zone} at ${timezone.version})`,
+        );
+      const current = process.versions.tz;
+      if (current && current !== timezone.version)
+        notes.push(
+          `this toolchain's tz data is ${current}; the store stays pinned to ${timezone.version} until a rules migration (P2.3)`,
+        );
+    }
+  }
+  const plugins: Lock["plugins"] = { ...lock.plugins };
+  // Names in the lock count too: a plugin removed from config keeps its tables (and its name).
+  for (const instance of input.plugins) {
+    const clash = overlappingName(instance.definition.name, [
+      ...Object.keys(lock.plugins),
+      ...input.plugins.map((i) => i.definition.name),
+    ]);
+    if (clash) problems.push(clash);
+  }
+  for (const instance of input.plugins) {
+    const def = instance.definition;
+    for (const issue of lintPlugin(def, instance.options))
+      problems.push(`${def.name} [${issue.rule}] ${issue.message} (${issue.at})`);
+    for (const m of def.migrations ?? []) {
+      desired.push({
+        source: `plugin:${def.name}:${m.id}`,
+        tag: `plg_${def.name}_${m.id.replace(/^\d+_/, "")}`,
+        sql: normalize(m.sql),
+      });
+    }
+    const known = plugins[def.name];
+    const installationId = known?.installationId ?? (input.newInstallationId ?? randomUUID)();
+    desired.push({
+      source: `plugin:${def.name}:install`,
+      tag: `plg_${def.name}_install`,
+      sql: installSql(def, installationId, input.now),
+    });
+    // Core-owned SQL is compared with what is installed now, not with history:
+    // a declaration removed, or reverted to an earlier version, is a new
+    // generation that drops every object the current one installed.
+    // Guards cover every fact table the plugin ever declared: removing a
+    // declaration doesn't remove the facts already written to it. Dropping
+    // such a table is a retirement concern (plugin-lifecycle.md), and the
+    // regenerated guard then fails its migration loudly.
+    const historical = known?.factTables ?? [];
+    const tables = factTables(def, historical);
+    const subscribed = Boolean(known?.subscribed) || Object.keys(def.subscribers ?? {}).length > 0;
+    // A registration it locked must still be declared, under its id or an
+    // alias, or be retired on purpose (code r10): a rename without its alias
+    // would strand every delivery and timer stored under the old id.
+    const declared = registrationKinds(def);
+    for (const [id, kind] of Object.entries(known?.registrations ?? {})) {
+      const now = Object.hasOwn(declared, id) ? declared[id] : undefined;
+      if (!now && !(def.retired ?? []).includes(id))
+        throw new ComposeError(
+          `${def.name}: registration ${id} is in kedge.lock.json but no longer declared: keep it, alias its new name to it, or list it in \`retired\``,
+        );
+      if (now && now !== kind)
+        throw new ComposeError(
+          `${def.name}: registration ${id} was a ${kind} and is now a ${now}; its stored deliveries would find no handler: declare the ${now} under a new id and retire this one`,
+        );
+    }
+    const registrations = Object.fromEntries(
+      Object.entries({ ...declared, ...(known?.registrations ?? {}) }).sort(([a], [b]) => (a < b ? -1 : 1)),
+    );
+    // P0.7 (§4.3): each entity's table, then its added fields; a removed
+    // entity is refused (its rows stay, P2.12 retires it).
+    const entityLocks: Record<string, EntityLock> = {};
+    for (const name of Object.keys(known?.entities ?? {}))
+      if (!Object.hasOwn(def.entities ?? {}, name))
+        problems.push(
+          `${def.name}: entity "${name}" is in kedge.lock.json but no longer declared; its rows stay (retiring it is P2.12's)`,
+        );
+    for (const [name, e] of Object.entries(def.entities ?? {})) {
+      const was = known?.entities?.[name];
+      const change = entityChange(def.name, name, e, was);
+      problems.push(...change.problems);
+      entityLocks[name] = change.lock;
+      if (change.sql.length)
+        desired.push({
+          source: `plugin:${def.name}:entity:${name}:${change.lock.generation}`,
+          tag: `plg_${def.name}_${name}`,
+          sql: change.sql.join(BREAK),
+        });
+    }
+    // P0.7 (§3.1, §3.3): a locked track keeps what its rows depend on, and
+    // the plugin's tracks fingerprint is set with its generation.
+    for (const problem of trackLockProblems(def.name, known?.tracks ?? {}, def as never)) problems.push(problem);
+    for (const [name, t] of Object.entries(def.tracks ?? {}))
+      for (const state of unreachableStates(t as never))
+        notes.push(`${def.name}: track "${name}" can't reach state "${state}" (kept for its rows, or a typo?)`);
+    const tracksInput = tracksShaInput(def as never);
+    const tracksSql =
+      tracksInput !== null || Object.keys(known?.tracks ?? {}).length
+        ? [
+            markedMigrationSql(`migration:tracks:${def.name}`, [
+              `UPDATE plugin_state SET tracks_sha = ${tracksInput === null ? "NULL" : `'${sha(tracksInput)}'`} WHERE plugin = '${def.name}';`,
+            ]),
+          ]
+        : [];
+    const entitySql = Object.entries(def.entities ?? {}).flatMap(([name, e]) =>
+      entityTriggersSql(def.name, name, e, sha(entityDeclInput(def as never, name, e))),
+    );
+    for (const st of entitySql)
+      if (Buffer.byteLength(st) > ENTITY_LIMITS.GENERATED_SQL_MAX)
+        problems.push(
+          `${def.name}: a generated statement is ${Buffer.byteLength(st)} bytes, over D1's limit (${st.slice(0, 60)}…)`,
+        );
+    const generated = [
+      ...factGuardSql(def, historical),
+      ...acquireSql(def),
+      ...subscriptionSql(def, Boolean(known?.subscribed)),
+      ...tracksSql,
+      ...entitySql,
+    ].join(BREAK);
+    // The hash covers the plugin's migration ids too: a new migration may
+    // rebuild a fact table, and DROP TABLE takes the guards on it with it, so
+    // the guards are recreated after every new plugin migration.
+    const generatedSha = sha(`${(def.migrations ?? []).map((m) => m.id).join(",")}\n${generated}`);
+    const objects = [
+      ...generatedObjectNames(def, historical),
+      ...Object.entries(def.entities ?? {}).flatMap(([name, e]) => entityTriggerNames(def.name, name, e)),
+    ];
+    let generation = known?.generation ?? 0;
+    if (generatedSha !== (known?.generatedSha256 ?? sha("\n"))) {
+      generation++;
+      const drops = (known?.generatedObjects ?? []).map((n) => `DROP TRIGGER IF EXISTS ${n};`);
+      desired.push({
+        source: `plugin:${def.name}:generated:${generation}`,
+        tag: `plg_${def.name}_generated`,
+        sql: [...drops, ...(generated ? [generated] : [])].join(BREAK),
+      });
+    }
+    plugins[def.name] = {
+      installationId,
+      generatedSha256: generatedSha,
+      generatedObjects: objects,
+      generation,
+      factTables: tables,
+      ...(subscribed ? { subscribed } : {}),
+      ...(Object.keys(registrations).length ? { registrations } : {}),
+      ...(Object.keys(entityLocks).length ? { entities: entityLocks } : {}),
+      ...(def.tracks && Object.keys(def.tracks).length
+        ? {
+            tracks: Object.fromEntries(Object.entries(def.tracks).map(([name, t]) => [name, trackLock(t as never)])),
+          }
+        : {}),
+    };
+  }
+  // P0.7 (§3.3): the store-wide checkout-track set. It changes exactly when a
+  // composed migration says so, which fences older Workers' checkouts.
+  const checkoutInput = checkoutTracksShaInput(
+    input.plugins.map((i) => ({ name: i.definition.name, tracks: i.definition.tracks as never })),
+  );
+  const checkoutSha = checkoutInput === null ? null : sha(checkoutInput);
+  let checkoutTracks = lock.checkoutTracks ?? { sha: null, generation: 0 };
+  if (checkoutSha !== checkoutTracks.sha) {
+    checkoutTracks = { sha: checkoutSha, generation: checkoutTracks.generation + 1 };
+    desired.push({
+      source: `core:checkout-tracks:${checkoutTracks.generation}`,
+      tag: "checkout_tracks",
+      sql: markedMigrationSql("migration:checkout-tracks", [
+        `UPDATE checkout_tracks SET sha = ${checkoutSha === null ? "NULL" : `'${checkoutSha}'`} WHERE id = 1;`,
+      ]),
+    });
+  }
+  // P0.4's inventory_level rebuild (0024) drops and recreates the table's
+  // dependents; it can only know core's. The linter already refuses plugin
+  // and local SQL that names a core table or keys to one (K1 rule 2), so this
+  // is the assertion that none slipped through, before a rebuild could break.
+  for (const d of desired) {
+    if (!d.source.startsWith("core:") && /\binventory_level\b/i.test(d.sql))
+      problems.push(
+        `${d.source} names inventory_level, which core rebuilds (p0.4 §3.2); read it through kedge_v1_* views`,
+      );
+  }
+  for (const f of sqlFiles(input.localDir)) {
+    const text = readFileSync(join(input.localDir, f), "utf8");
+    if (/\binventory_level\b/i.test(text))
+      problems.push(`local/${f} names inventory_level, which core rebuilds (p0.4 §3.2)`);
+    for (const issue of lintSql({ kind: "local" }, text, { context: "migration" }))
+      problems.push(`local/${f} [${issue.rule}] ${issue.message} (${issue.at})`);
+    desired.push({ source: `local:${f}`, tag: `local_${f.replace(/^\d+_/, "").replace(/\.sql$/, "")}`, sql: text });
+  }
+
+  // What SQLite itself says each plugin statement touches, against the real schema.
+  if (problems.length === 0) {
+    // The zone's rows are data, not schema a plugin compiles against.
+    const coreSql = desired
+      .filter((d) => d.source.startsWith("core:") && !d.source.startsWith("core:tz:"))
+      .map((d) => d.sql);
+    const verified = verifyWithSqlite({
+      coreSql,
+      plugins: input.plugins.map((i) => ({
+        definition: i.definition,
+        runtime: (() => {
+          try {
+            return collect(i.definition, i.options).filter((r) => r.context !== "acquire");
+          } catch {
+            return []; // lintPlugin already reported a builder that throws on sample input
+          }
+        })(),
+        historicalFacts: lock.plugins[i.definition.name]?.factTables ?? [],
+      })),
+    });
+    for (const v of verified) problems.push(`${v.plugin} [${v.rule}] ${v.message} (${v.at})`);
+  }
+
+  // 2. Every applied entry must still be wanted, unchanged.
+  const bySource = new Map(desired.map((d) => [d.source, d]));
+  // Two sources under one identity would both be written, and the lock would then reject its own inputs.
+  if (bySource.size !== desired.length) {
+    const seen = new Set<string>();
+    for (const d of desired) {
+      if (seen.has(d.source)) problems.push(`${d.source} appears twice; every migration needs its own id`);
+      seen.add(d.source);
+    }
+  }
+  for (const e of lock.entries) {
+    // Generated, install and timezone entries are history: their sources are never
+    // recomputed (a later generation supersedes them), but their files are
+    // verified like any other applied migration.
+    // The pinned zone's migration is history the same way: compiled once, never again.
+    if (
+      !e.source.includes(":generated:") &&
+      // An entity's table and added fields are history: a later declaration supersedes them (p0.7 §4.3).
+      !e.source.includes(":entity:") &&
+      !e.source.endsWith(":install") &&
+      !e.source.startsWith("core:tz:") &&
+      !e.source.startsWith("core:checkout-tracks:")
+    ) {
+      const d = bySource.get(e.source);
+      if (!d) problems.push(`${e.file}: its source ${e.source} is gone; applied migrations are never removed`);
+      else if (sha(d.sql) !== e.sha256)
+        problems.push(`${e.file}: ${e.source} changed after it was composed; add a new migration instead`);
+    }
+    const path = join(input.outDir, e.file);
+    if (!existsSync(path)) problems.push(`${e.file} is in the lock but missing from ${input.outDir}`);
+    else if (sha(readFileSync(path, "utf8")) !== e.sha256)
+      problems.push(`${e.file} was edited; applied migrations are immutable`);
+  }
+  const lockedFiles = new Set(lock.entries.map((e) => e.file));
+  for (const f of sqlFiles(input.outDir)) {
+    if (!lockedFiles.has(f))
+      problems.push(`${f} in ${input.outDir} isn't in kedge.lock.json; migrations there are written by kedge generate`);
+  }
+  const contracts = lockContracts(lock.contracts ?? {}, [
+    ...(input.ports ?? []),
+    ...input.plugins.flatMap((i) => i.definition.ports ?? []),
+  ]);
+  problems.push(...contracts.problems);
+  if (problems.length > 0) throw new ComposeError(problems.join("\n"));
+
+  // 3. New sources, numbered after everything already composed.
+  const done = new Set(lock.entries.map((e) => e.source));
+  let next = lock.entries.reduce((max, e) => Math.max(max, Number.parseInt(e.file, 10) + 1), 0);
+  const written: string[] = [];
+  const entries = [...lock.entries];
+  for (const d of desired) {
+    if (done.has(d.source)) continue;
+    const file = `${String(next++).padStart(4, "0")}_${d.tag}.sql`;
+    entries.push({ file, source: d.source, sha256: sha(d.sql) });
+    written.push(file);
+    if (input.dryRun) continue;
+    if (!existsSync(input.outDir)) mkdirSync(input.outDir, { recursive: true });
+    writeFileSync(join(input.outDir, file), d.sql);
+  }
+  const out: Lock = {
+    version: 1,
+    entries,
+    plugins,
+    ...(timezone ? { timezone } : {}),
+    ...(Object.keys(contracts.locked).length ? { contracts: contracts.locked } : {}),
+    ...(checkoutTracks.generation > 0 ? { checkoutTracks } : {}),
+  };
+  if (tzWrite) written.push(tzWrite.path);
+  if (!input.dryRun) {
+    if (tzWrite) {
+      mkdirSync(dirname(tzWrite.path), { recursive: true });
+      writeFileSync(tzWrite.path, tzWrite.text);
+    }
+    writeFileSync(input.lockPath, `${JSON.stringify(out, null, 2)}\n`);
+  }
+  const before = existsSync(input.lockPath) ? JSON.stringify(lock) : null;
+  return { written, lock: out, notes, lockChanged: before !== JSON.stringify(out) };
+}
+
+/**
+ * The contract lock (p0.6a §4.2): every declared operation version's
+ * contract hashed beside the migrations. A locked version whose contract
+ * changed is refused (a change is a new version), and so is a locked version
+ * the config no longer declares: a record admitted under it would meet no
+ * code that knows how to recover it.
+ */
+function lockContracts(
+  locked: Readonly<Record<string, string>>,
+  ports: readonly PortDefinition[],
+): { locked: Record<string, string>; problems: string[] } {
+  const problems: string[] = [];
+  const out: Record<string, string> = { ...locked };
+  const declared = new Set<string>();
+  for (const port of ports) {
+    for (const [name, op] of Object.entries(port.operations)) {
+      if (op.kind !== "effect") continue;
+      for (const v of [op, ...(op.previous ?? [])] as EffectOperation[]) {
+        const id = `${port.name}.${name}@${v.version}`;
+        const hash = sha(operationContract(port, v));
+        declared.add(id);
+        if (locked[id] !== undefined && locked[id] !== hash)
+          problems.push(
+            `${id}'s contract changed since it was locked; a change is a new version (${name} version ${op.version + 1})`,
+          );
+        else out[id] = hash;
+      }
+    }
+  }
+  for (const id of Object.keys(locked))
+    if (!declared.has(id))
+      problems.push(`${id} is locked but no longer declared; a port keeps every version a record may need`);
+  return { locked: out, problems };
+}