okmodel 0.9.0 → 0.9.1

package/dist/tooling/cli.js

@@ -1,7 +1,7 @@
 import"../shared/12z7aznj.js";
 import"../shared/n442h54c.js";
 import"../shared/fk9vef30.js";
-import"../shared/dd5pmnky.js";
+import"../shared/jvxcp1qk.js";
 import {
   formatFindings,
   hasError,
@@ -11,10 +11,10 @@ import {
   planProject,
   checkProject,
   exportProject
-} from "../shared/2zdxkt7b.js";
+} from "../shared/wp7y8q3y.js";
 import {
   sessionFailure
-} from "../shared/6nae0spm.js";
+} from "../shared/bdekbvmt.js";
 import {
   OkmError2
 } from "../shared/52szzakm.js";
@@ -65,7 +65,7 @@ async function run(argv, io) {
     return;
   }
   if (command === "check") {
-    const findings = await checkProject(cwd, invoke(splitFlags(rest)));
+    const findings = await checkProject(cwd, invoke(splitFlags(rest, "check")));
     const warnings = formatFindings(findings);
     if (warnings.length > 0)
       stdout(warnings);
@@ -74,7 +74,7 @@ async function run(argv, io) {
     return;
   }
   if (command === "generate") {
-    const parsed = splitFlags(rest);
+    const parsed = splitFlags(rest, "generate");
     const written = await generateProject(cwd, parsed.name ?? "migration", parsed.flags);
     stdout(written === undefined ? `no changes
 ` : `${written.path}
@@ -84,17 +84,17 @@ async function run(argv, io) {
     return;
   }
   if (command === "dev") {
-    const { devProject } = await import("../shared/8qzkd9f3.js");
+    const { devProject } = await import("../shared/ak61ye1f.js");
     stdout(await devProject(cwd));
     return;
   }
   if (command === "push") {
-    const { pushProject } = await import("../shared/n306gqkd.js");
-    stdout(await pushProject(cwd, invoke(splitFlags(rest))));
+    const { pushProject } = await import("../shared/6vfvsdkt.js");
+    stdout(await pushProject(cwd, invoke(splitFlags(rest, "push"))));
     return;
   }
   if (command === "pull") {
-    const { pullProject } = await import("../shared/7ba5h6pb.js");
+    const { pullProject } = await import("../shared/esy4dyxe.js");
     stdout((await pullProject(cwd, rest)).text);
     return;
   }
@@ -105,14 +105,20 @@ async function run(argv, io) {
         fix: { summary: "Use okm import drizzle <path>." }
       });
     }
-    const { importDrizzle } = await import("../shared/n5whk3mt.js");
+    const { importDrizzle } = await import("../shared/8gdbty5v.js");
     stdout((await importDrizzle(cwd, rest.slice(1))).text);
     return;
   }
   if (command === "migrate") {
     const sub = rest[0];
     const migrateArgs = rest.slice(1);
-    const parsed = splitFlags(sub === "plan" ? migrateArgs.filter((arg) => arg !== "--json") : migrateArgs);
+    const commandKey = sub === "plan" ? "migrate plan" : sub === "apply" ? "migrate apply" : sub === "status" ? "migrate status" : sub === "check" ? "migrate check" : undefined;
+    if (commandKey === undefined) {
+      throw new OkmError2("invalid", `Unknown command migrate ${sub ?? ""}.`, {
+        fix: { summary: "Use okm migrate plan, apply, status, or check." }
+      });
+    }
+    const parsed = splitFlags(sub === "plan" ? migrateArgs.filter((arg) => arg !== "--json") : migrateArgs, commandKey);
     if (sub === "plan") {
       if (parsed.name === undefined) {
         throw new OkmError2("invalid", "okm migrate plan needs a name.");
@@ -129,36 +135,35 @@ async function run(argv, io) {
       return;
     }
     if (sub === "apply") {
-      const { applyProject } = await import("../shared/n306gqkd.js");
+      const { applyProject } = await import("../shared/6vfvsdkt.js");
       stdout(await applyProject(cwd, invoke(parsed), stdout));
       return;
     }
     if (sub === "status") {
-      const { statusProject } = await import("../shared/mgaq2sd3.js");
+      const { statusProject } = await import("../shared/kzgrcy8s.js");
       stdout(await statusProject(cwd, invoke(parsed)));
       return;
     }
     if (sub === "check") {
-      const { checkMigrations } = await import("../shared/qvwwp1mp.js");
-      const provision = parsed.flags.includes("--provision") || rest.slice(1).includes("--provision");
-      stdout(await checkMigrations(cwd, invoke(parsed), { provision }));
+      const { checkMigrations } = await import("../shared/rw4tpcd0.js");
+      stdout(await checkMigrations(cwd, invoke(parsed), { provision: parsed.provision }));
       return;
     }
   }
   if (command === "seed") {
-    const parsed = splitFlags(rest);
+    const parsed = splitFlags(rest, "seed");
     if (parsed.name === undefined) {
       throw new OkmError2("invalid", "okm seed needs a file.", {
         fix: { summary: "Pass okm seed <file>." }
       });
     }
-    const { seedProject } = await import("../shared/ss2kv2rs.js");
+    const { seedProject } = await import("../shared/8v7vzpgt.js");
     stdout(await seedProject(cwd, parsed.name, invoke(parsed)));
     return;
   }
   if (command === "doctor") {
-    const parsed = splitFlags(rest);
-    const { doctorProject } = await import("../shared/yvabyg9k.js");
+    const parsed = splitFlags(rest, "doctor");
+    const { doctorProject } = await import("../shared/3vvpcphd.js");
     stdout(await doctorProject(cwd, parsed.name, invoke(parsed)));
     return;
   }
@@ -178,14 +183,14 @@ async function run(argv, io) {
     const sub = rest[0];
     if (sub === "scaffold" || sub === "test") {
       const parsed = extInvocation(rest.slice(1));
-      const { extScaffold, extTest } = await import("../shared/stfa9xcw.js");
+      const { extScaffold, extTest } = await import("../shared/py2zrrm6.js");
       const text = sub === "scaffold" ? await extScaffold(cwd, requireName(parsed, "okm ext scaffold <name>"), parsed.flags, parsed.out) : await extTest(cwd, requireName(parsed, "okm ext test <file>"), parsed.flags);
       stdout(text);
       return;
     }
     if (sub === "list" || sub === "check") {
-      const { extProject } = await import("../shared/stfa9xcw.js");
-      stdout(await extProject(cwd, sub, invoke(splitFlags(rest.slice(1)))));
+      const { extProject } = await import("../shared/py2zrrm6.js");
+      stdout(await extProject(cwd, sub, invoke(splitFlags(rest.slice(1), "ext"))));
       return;
     }
     throw new OkmError2("invalid", `Unknown command ext ${sub ?? ""}.`, {
@@ -221,7 +226,7 @@ function extInvocation(args) {
     }
     rest.push(arg);
   }
-  const parsed = splitFlags(rest);
+  const parsed = splitFlags(rest, "ext");
   return { name: parsed.name, out, flags: invoke(parsed) };
 }
 function invoke(parsed) {
@@ -233,55 +238,90 @@ function invoke(parsed) {
     ...parsed.statementTimeoutMs !== undefined ? { statementTimeoutMs: parsed.statementTimeoutMs } : {}
   };
 }
-function splitFlags(args) {
+var COMMAND_FLAGS = {
+  check: ["--target", "--allow-pooler", "--lock-timeout", "--statement-timeout"],
+  generate: ["--replace"],
+  push: ["--target", "--allow-protected", "--allow-pooler"],
+  seed: ["--target", "--allow-protected", "--allow-pooler"],
+  doctor: ["--target"],
+  ext: ["--target", "--allow-pooler", "--out"],
+  "migrate plan": ["--target", "--allow-protected", "--replace", "--json"],
+  "migrate apply": [
+    "--target",
+    "--allow-protected",
+    "--allow-pooler",
+    "--lock-timeout",
+    "--statement-timeout"
+  ],
+  "migrate status": ["--target"],
+  "migrate check": [
+    "--target",
+    "--allow-protected",
+    "--allow-pooler",
+    "--provision",
+    "--lock-timeout",
+    "--statement-timeout"
+  ]
+};
+function splitFlags(args, command) {
+  const allowed = new Set(COMMAND_FLAGS[command]);
   const flags = [];
   const positionals = [];
   let target;
   let allowProtected = false;
   let allowPooler = false;
+  let provision = false;
   let lockTimeoutMs;
   let statementTimeoutMs;
   for (let index = 0;index < args.length; index += 1) {
     const arg = args[index] ?? "";
-    if (arg === "--replace") {
-      const value = args[index + 1];
-      if (value === undefined) {
+    if (arg === "--replace" || arg.startsWith("--replace=")) {
+      refuseUnknown(command, "--replace", allowed);
+      const value = arg === "--replace" ? args[index + 1] : arg.slice("--replace=".length);
+      if (value === undefined || value.length === 0 || arg === "--replace" && value.startsWith("--")) {
         throw new OkmError2("OKM1541", "--replace needs table.column.old=new.", {
           fix: { summary: "Pass --replace <table>.<column>.<old>=<new>." }
         });
       }
       flags.push(value);
-      index += 1;
-      continue;
-    }
-    if (arg.startsWith("--replace=")) {
-      flags.push(arg.slice("--replace=".length));
+      if (arg === "--replace")
+        index += 1;
       continue;
     }
     if (arg === "--allow-protected") {
+      refuseUnknown(command, arg, allowed);
       allowProtected = true;
       continue;
     }
     if (arg === "--allow-pooler") {
+      refuseUnknown(command, arg, allowed);
       allowPooler = true;
       continue;
     }
-    if (arg === "--target") {
-      const value = args[index + 1];
-      if (value === undefined || value.startsWith("--")) {
+    if (arg === "--provision") {
+      refuseUnknown(command, arg, allowed);
+      provision = true;
+      continue;
+    }
+    if (arg === "--json") {
+      refuseUnknown(command, arg, allowed);
+      continue;
+    }
+    if (arg === "--target" || arg.startsWith("--target=")) {
+      refuseUnknown(command, "--target", allowed);
+      const value = arg === "--target" ? args[index + 1] : arg.slice("--target=".length);
+      if (value === undefined || value.length === 0 || arg === "--target" && value.startsWith("--")) {
         throw new OkmError2("OKM1853", "--target needs a name.", {
           fix: { summary: "Pass --target <name>." }
         });
       }
       target = value;
-      index += 1;
-      continue;
-    }
-    if (arg.startsWith("--target=")) {
-      target = arg.slice("--target=".length);
+      if (arg === "--target")
+        index += 1;
       continue;
     }
     if (arg === "--lock-timeout" || arg === "--statement-timeout") {
+      refuseUnknown(command, arg, allowed);
       const value = numberFlag(arg, args[index + 1]);
       if (arg === "--lock-timeout")
         lockTimeoutMs = value;
@@ -290,6 +330,13 @@ function splitFlags(args) {
       index += 1;
       continue;
     }
+    if (arg.startsWith("-")) {
+      throw new OkmError2("invalid", `Unknown flag ${arg}.`, {
+        fix: {
+          summary: `Use okm ${command} --help for the flags this command accepts.`
+        }
+      });
+    }
     positionals.push(arg);
   }
   return {
@@ -298,15 +345,25 @@ function splitFlags(args) {
     target,
     allowProtected,
     allowPooler,
+    provision,
     lockTimeoutMs,
     statementTimeoutMs
   };
 }
+function refuseUnknown(command, flag, allowed) {
+  if (allowed.has(flag))
+    return;
+  throw new OkmError2("invalid", `Unknown flag ${flag}.`, {
+    fix: {
+      summary: `Use okm ${command} --help for the flags this command accepts.`
+    }
+  });
+}
 var COMMANDS = [
   ["build", "Write the schema build."],
   ["catalog export", "Write the catalog snapshot."],
   ["check", "Lint the schema and compare it with one target."],
-  ["dev", "Watch the schema and reload."],
+  ["dev", "Open a PGlite database in .okm/dev-db, or name a target called dev."],
   ["doctor [code]", "Print a target report, or one error code."],
   ["driver test <driver>", "Run conformance against one driver."],
   ["ext list", "List extensions the server can install."],
@@ -343,10 +400,31 @@ function commandHelp(argv) {
 
 ${commandsTable()}`;
   }
-  return `${found[0]}
-${found[1]}
+  const flags = flagsForHelp(found[0]);
+  const lines = [found[0], found[1]];
+  if (flags.length > 0) {
+    lines.push("", "Flags:");
+    for (const flag of flags)
+      lines.push(`  ${flag}`);
+  }
+  return `${lines.join(`
+`)}
 `;
 }
+function flagsForHelp(commandLine) {
+  const key = helpCommandKey(commandLine);
+  if (key === undefined)
+    return [];
+  return COMMAND_FLAGS[key];
+}
+function helpCommandKey(commandLine) {
+  const name = commandLine.replace(/\s+\[.*?\]/g, "").replace(/\s+<.*?>/g, "").trim();
+  if (name in COMMAND_FLAGS)
+    return name;
+  if (name.startsWith("ext "))
+    return "ext";
+  return;
+}
 function numberFlag(flag, value) {
   const parsed = value === undefined ? Number.NaN : Number(value);
   if (!Number.isFinite(parsed) || parsed < 0) {

package/dist/tooling/driver-run.js

@@ -45,7 +45,7 @@ import {
   jsonb,
   quote,
   primaryUrl
-} from "./shared/hfq3n3bd.js";
+} from "./shared/2jdn09e2.js";
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
@@ -352,8 +352,7 @@ function registerDriverSuite(suite) {
       try {
         const setting = await scalar(second, "SELECT current_setting('okm.p13', true)");
         expect(setting).not.toBe("yes");
-        expect(await scalar(second, "SELECT pg_backend_pid()::text")).toBe(pid);
-        expect(await scalar(second, "SELECT count(*)::text FROM pg_locks WHERE locktype = 'advisory' AND pid = pg_backend_pid()")).toBe("0");
+        expect(await scalar(second, `SELECT count(*)::text FROM pg_locks WHERE locktype = 'advisory' AND pid = ${pid}`)).toBe("0");
       } finally {
         await second.release();
       }
@@ -444,9 +443,28 @@ async function using(open, fn) {
   try {
     await fn(pool);
   } finally {
+    await dropOkmTables(pool);
     await pool.close();
   }
 }
+async function dropOkmTables(pool) {
+  try {
+    await pool.execute(`
+      do $$
+      declare
+        r record;
+      begin
+        for r in
+          select tablename
+          from pg_tables
+          where schemaname = current_schema()
+            and tablename like 'okm\\_%' escape '\\'
+        loop
+          execute format('drop table if exists %I cascade', r.tablename);
+        end loop;
+      end $$`);
+  } catch {}
+}
 function tableName() {
   return `okm_${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -614,9 +632,28 @@ async function using2(open, fn) {
   try {
     await fn(pool);
   } finally {
+    await dropOkmTables2(pool);
     await pool.close();
   }
 }
+async function dropOkmTables2(pool) {
+  try {
+    await pool.execute(`
+      do $$
+      declare
+        r record;
+      begin
+        for r in
+          select tablename
+          from pg_tables
+          where schemaname = current_schema()
+            and tablename like 'okm\\_%' escape '\\'
+        loop
+          execute format('drop table if exists %I cascade', r.tablename);
+        end loop;
+      end $$`);
+  } catch {}
+}
 async function mapped(pending) {
   try {
     await pending;
@@ -887,29 +924,29 @@ function readTenancy(value) {
 }
 
 // src/dialects/pg/filters.ts
-function openFilters(table, relations, spec, hiddenFields) {
+function openFilters(table, relations, spec, isHidden) {
   const allow = spec.allow ?? {};
   const sort = spec.sort ?? [];
   for (const field of Object.keys(allow))
-    deny(hiddenFields, table, field);
+    deny(isHidden, table, field);
   for (const field of sort)
-    deny(hiddenFields, table, field);
+    deny(isHidden, table, field);
   const nested = spec.relations;
   if (nested !== undefined) {
     for (const name of Object.keys(nested)) {
       const target = relationTable(relations, name);
       for (const field of nested[name] ?? [])
-        deny(hiddenFields, target, field);
+        deny(isHidden, target, field);
     }
   }
   return {
     parse(query) {
-      return import("./shared/zs9aymcp.js").then((mod) => mod.parseQuery(allow, sort, query, nested));
+      return import("./shared/f4gep0nk.js").then((mod) => mod.parseQuery(allow, sort, query, nested));
     }
   };
 }
-function deny(hiddenFields, table, field) {
-  if (!hiddenFields.has(`${table}.${field}`))
+function deny(isHidden, table, field) {
+  if (!isHidden(table, field))
     return;
   throw new OkmError("OKM1123", `Field ${table}.${field} is hidden.`, {
     fix: {
@@ -962,7 +999,8 @@ function table2(name, columns, options) {
     name,
     columns,
     filters(spec) {
-      return openFilters(name, options?.relations, spec, hiddenFields);
+      const ownHidden = hiddenColumnFields(columns);
+      return openFilters(name, options?.relations, spec, (tableName, field) => tableName === name ? ownHidden.has(field) : hiddenFields.has(`${tableName}.${field}`));
     },
     ...options !== undefined ? { options } : {},
     ...source !== undefined ? { source } : {}
@@ -1026,11 +1064,23 @@ function rejectLater(options, known, later, where) {
   }
 }
 var hiddenFields = new Set;
-function remember(name, columns) {
+function hiddenColumnFields(columns) {
+  const fields = new Set;
   for (const field of Object.keys(columns)) {
     const column = columns[field];
     if (column?.state?.hidden === true)
-      hiddenFields.add(`${name}.${field}`);
+      fields.add(field);
+  }
+  return fields;
+}
+function remember(name, columns) {
+  const prefix = `${name}.`;
+  for (const key of hiddenFields) {
+    if (key.startsWith(prefix))
+      hiddenFields.delete(key);
+  }
+  for (const field of hiddenColumnFields(columns)) {
+    hiddenFields.add(`${name}.${field}`);
   }
 }
 
@@ -4305,7 +4355,7 @@ function skipped(test, reason) {
   return skipFor(test, reason, (name) => `${name} (${reason})`);
 }
 async function openSuiteAdmin(url) {
-  const { openPostgres } = await import("./shared/wezxf3h8.js");
+  const { openPostgres } = await import("./shared/gefmpwsa.js");
   return openPostgres(url);
 }
 async function failure2(promise) {
@@ -4338,14 +4388,45 @@ function barrier(parties) {
 }
 
 // packages/harness/src/driver-run.ts
+var MIN_BUN = "1.4.0";
 async function executeDriverTest(argv) {
   process.env.TZ = "UTC";
+  refuseOldBun();
   const parsed = parseArgs(argv);
   const target = await loadTarget(parsed.driver, parsed.url);
   const rows = await runTarget(target);
   const failed = rows.filter((row) => row.result === "fail").length;
   return { text: render(target.name, rows), failed };
 }
+function refuseOldBun() {
+  if (typeof Bun === "undefined")
+    return;
+  const version = typeof Bun.version === "string" ? Bun.version : "";
+  if (bunAtLeast(version, MIN_BUN))
+    return;
+  throw new Error(`okm driver test needs Bun >=${MIN_BUN} (package.json engines.bun). This process is ${version === "" ? "Bun (unknown version)" : `Bun ${version}`}.`);
+}
+function bunAtLeast(version, minimum) {
+  const left = parseSemver(version);
+  const right = parseSemver(minimum);
+  if (left === undefined || right === undefined)
+    return false;
+  for (let index = 0;index < 3; index += 1) {
+    const a = left[index] ?? 0;
+    const b = right[index] ?? 0;
+    if (a > b)
+      return true;
+    if (a < b)
+      return false;
+  }
+  return true;
+}
+function parseSemver(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value.trim());
+  if (match === null)
+    return;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
 if (__require.main == __require.module) {
   executeDriverTest(process.argv.slice(2)).then((report) => {
     process.stdout.write(report.text);
@@ -4403,8 +4484,8 @@ async function loadTarget(driver, url) {
 }
 async function firstParty(driver, url) {
   if (driver === "pglite") {
-    const adapter = await import("./shared/s6qha57m.js");
-    const runtime = await import("./shared/5p8km5jb.js");
+    const adapter = await import("./shared/19msgrsc.js");
+    const runtime = await import("./shared/p6tjv97k.js");
     return {
       name: "pglite",
       capabilities: adapter.capabilities,
@@ -4419,8 +4500,8 @@ async function firstParty(driver, url) {
   if (url === undefined)
     throw new Error(`okm driver test ${driver} needs --url or DATABASE_URL.`);
   if (driver === "postgresjs") {
-    const adapter = await import("./shared/mw5npye0.js");
-    const runtime = await import("./shared/nxq95eb6.js");
+    const adapter = await import("./shared/d8q00vxg.js");
+    const runtime = await import("./shared/y4gq9rbe.js");
     return networked("postgres.js", adapter.capabilities, true, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4429,8 +4510,8 @@ async function firstParty(driver, url) {
     }), (pool, options) => runtime.connect(pool, options));
   }
   if (driver === "pg") {
-    const adapter = await import("./shared/a4pzghha.js");
-    const runtime = await import("./shared/v6j1ep6w.js");
+    const adapter = await import("./shared/jm30k2ca.js");
+    const runtime = await import("./shared/2qrte2ct.js");
     return networked("node-postgres", adapter.capabilities, true, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4439,8 +4520,8 @@ async function firstParty(driver, url) {
     }), (pool, options) => runtime.connect(pool, options));
   }
   if (driver === "neon") {
-    const adapter = await import("./shared/68tf18v4.js");
-    const runtime = await import("./shared/9sfbtwsk.js");
+    const adapter = await import("./shared/0v9ptnxp.js");
+    const runtime = await import("./shared/jgzt69pa.js");
     return networked("neon", adapter.capabilities, false, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4451,8 +4532,8 @@ async function firstParty(driver, url) {
   if (typeof Bun === "undefined" || typeof Bun.SQL !== "function") {
     throw new Error("bun runs only under Bun.");
   }
-  const adapter = await import("./shared/m3xt8b1h.js");
-  const runtime = await import("./shared/1800eymw.js");
+  const adapter = await import("./shared/ryc5sa58.js");
+  const runtime = await import("./shared/0yhf1db4.js");
   return networked("bun.sql", adapter.capabilities, false, url, (config) => adapter.open({
     url: config.url ?? url,
     max: config.max,
@@ -4650,5 +4731,7 @@ function render(driver, rows) {
 `;
 }
 export {
+  MIN_BUN,
+  bunAtLeast,
   executeDriverTest
 };

package/dist/tooling/github/comment.d.ts

@@ -10,10 +10,14 @@ import { type PlanDocument } from "../migrate/plan-json.js";
  * A later push updates the comment whose body contains this marker.
  */
 export declare const PLAN_COMMENT_MARKER = "<!-- okmodel-migrate-plan -->";
+/** Default login that posts the Action comment with `GITHUB_TOKEN`. */
+export declare const PLAN_COMMENT_BOT = "github-actions[bot]";
 /** A comment the sticky update may replace. */
 export type StickyComment = {
     readonly id: number;
     readonly body: string;
+    /** GitHub login of the comment author. */
+    readonly author: string;
 };
 /**
  * Renders the plan comment.
@@ -38,13 +42,15 @@ export declare function renderPlanComment(plan: PlanDocument): string;
  */
 export declare function planCommentBody(text: string | undefined, checkStatus: string, planStatus: string): string;
 /**
- * The comment to update, when one already carries the marker.
+ * The comment to update, when one already carries the marker and an allowed author.
  *
  * The first match wins. A missing match means the caller creates a comment.
+ * A marker on another author's comment is ignored so the Action never edits it.
  *
  * @param comments - Comments already on the pull request
+ * @param authors - Logins allowed to own the sticky comment. Default is the Actions bot
  * @returns The id to update, or `undefined` to create one
  */
-export declare function stickyCommentTarget(comments: readonly StickyComment[]): {
+export declare function stickyCommentTarget(comments: readonly StickyComment[], authors?: readonly string[]): {
     readonly updateId: number;
 } | undefined;

package/dist/tooling/migrate/apply.d.ts

@@ -93,6 +93,20 @@ export type ApplyRequest = {
         readonly reference: readonly ReferenceTable[];
         readonly only?: boolean;
     };
+    /**
+     * Catalog hash `okm_meta` must record when this run finishes.
+     *
+     * When the plan (or pending units) leave the database matching the schema
+     * but `okm_meta` still holds an older hash — for example an external table
+     * gained a column and the dependent exported a new snapshot — the runner
+     * re-stamps `okm_meta` and `okm_history` under a fresh id. File apply only
+     * enables that path when `defineConfig({ external })` is set; a foreign or
+     * legacy hash without external snapshots is left for connect or the pre-D208
+     * restamp.
+     */
+    readonly headHash?: string;
+    /** When true, an empty apply may re-stamp `okm_meta` to {@link headHash}. */
+    readonly restampHead?: boolean;
 };
 /** Migrations that ran at least one step in this invocation. */
 export type ApplyReport = {
@@ -147,8 +161,9 @@ export declare function applyProject(cwd: string, flags: InvokeFlags, write?: (t
 /**
  * Prototype sync. Blocked on a protected target.
  *
- * A target named production is not special. Protection is the `protected`
- * flag (spec §19.8). The plan's statements run as one migration.
+ * Plans from the live catalog on the target (not the last migration file),
+ * applies under a fresh `push-<n>` id from `okm_history`, and re-stamps
+ * `okm_meta` when the schema hash moved with no DDL (B-29, B-21).
  *
  * @param cwd - Project directory
  * @param flags - Target and protection flags