@metaobjectsdev/cli 1.0.0-rc.4 → 1.0.0-rc.6

package/src/lib/args.ts

@@ -19,22 +19,25 @@ export interface InitFlags {
   configOnly: boolean;
 }
 
+/** The flag table `parseInitArgs` parses. Exported so the help text can be gated against it. */
+export const INIT_OPTIONS = {
+  force: { type: "boolean", default: false },
+  quiet: { type: "boolean", default: false },
+  "print-only": { type: "boolean", default: false },
+  "refresh-docs": { type: "boolean", default: false },
+  d1: { type: "boolean", default: false },
+  server: { type: "string", multiple: true },
+  client: { type: "string", multiple: true },
+  "no-skills": { type: "boolean", default: false },
+  "no-wire-root": { type: "boolean", default: false },
+  "docs-only": { type: "boolean", default: false },
+  "config-only": { type: "boolean", default: false },
+} as const;
+
 export function parseInitArgs(argv: string[]): InitFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      force: { type: "boolean", default: false },
-      quiet: { type: "boolean", default: false },
-      "print-only": { type: "boolean", default: false },
-      "refresh-docs": { type: "boolean", default: false },
-      d1: { type: "boolean", default: false },
-      server: { type: "string", multiple: true },
-      client: { type: "string", multiple: true },
-      "no-skills": { type: "boolean", default: false },
-      "no-wire-root": { type: "boolean", default: false },
-      "docs-only": { type: "boolean", default: false },
-      "config-only": { type: "boolean", default: false },
-    },
+    options: INIT_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -65,16 +68,19 @@ export interface AgentDocsFlags {
   wireRoot: boolean;
 }
 
+/** The flag table `parseAgentDocsArgs` parses. Exported so the help text can be gated against it. */
+export const AGENT_DOCS_OPTIONS = {
+  server: { type: "string", multiple: true },
+  client: { type: "string", multiple: true },
+  out: { type: "string" },
+  "no-skills": { type: "boolean", default: false },
+  "no-wire-root": { type: "boolean", default: false },
+} as const;
+
 export function parseAgentDocsArgs(argv: string[]): AgentDocsFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      server: { type: "string", multiple: true },
-      client: { type: "string", multiple: true },
-      out: { type: "string" },
-      "no-skills": { type: "boolean", default: false },
-      "no-wire-root": { type: "boolean", default: false },
-    },
+    options: AGENT_DOCS_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -94,10 +100,10 @@ export function parseAgentDocsArgs(argv: string[]): AgentDocsFlags {
 export interface GenFlags {
   dryRun: boolean;
   entities: string[];
-  /** First-time-on-existing-file behavior. Default: write-if-different
-   *  (existing content becomes the canonical baseline). "fresh" → overwrite
-   *  and re-baseline. */
-  baseline: "default" | "fresh";
+  /** First-time-on-existing-file behavior. Default: refuse a file that cannot be
+   *  proved to be ours. "adopt" → record the file as the merge base and write
+   *  nothing. "fresh" → overwrite from fresh output and re-baseline. */
+  baseline: "default" | "fresh" | "adopt";
   /** ADR-0021 D3 — print the stable-name generator registry and exit without
    *  running codegen. */
   list: boolean;
@@ -111,29 +117,37 @@ export interface GenFlags {
   limit: number;
 }
 
+/** The flag table `parseGenArgs` parses. Exported so the help text can be gated against it. */
+export const GEN_OPTIONS = {
+  "dry-run": { type: "boolean", default: false },
+  "baseline": { type: "string" },
+  "list": { type: "boolean", default: false },
+  "no-antipatterns": { type: "boolean", default: false },
+  "limit": { type: "string" },
+} as const;
+
 export function parseGenArgs(argv: string[]): GenFlags {
   const { values, positionals } = parseArgs({
     args: argv,
-    options: {
-      "dry-run": { type: "boolean", default: false },
-      "baseline": { type: "string" },
-      "list": { type: "boolean", default: false },
-      "no-antipatterns": { type: "boolean", default: false },
-      "limit": { type: "string" },
-    },
+    options: GEN_OPTIONS,
     strict: true,
     allowPositionals: true,
   });
   const baselineRaw = values.baseline as string | undefined;
-  if (baselineRaw !== undefined && baselineRaw !== "default" && baselineRaw !== "fresh") {
+  if (
+    baselineRaw !== undefined &&
+    baselineRaw !== "default" &&
+    baselineRaw !== "fresh" &&
+    baselineRaw !== "adopt"
+  ) {
     throw new Error(
-      `invalid --baseline '${baselineRaw}'; expected 'default' or 'fresh'`,
+      `invalid --baseline '${baselineRaw}'; expected 'default', 'adopt' or 'fresh'`,
     );
   }
   return {
     dryRun: !!values["dry-run"],
     entities: positionals,
-    baseline: (baselineRaw as "default" | "fresh" | undefined) ?? "default",
+    baseline: (baselineRaw as "default" | "fresh" | "adopt" | undefined) ?? "default",
     list: !!values.list,
     noAntipatterns: !!values["no-antipatterns"],
     // Throws on a bad value; the command layer reports it and exits 2, exactly as
@@ -150,12 +164,15 @@ export interface ExportFlags {
   out: string | undefined;
 }
 
+/** The flag table `parseExportArgs` parses. Exported so the help text can be gated against it. */
+export const EXPORT_OPTIONS = {
+  out: { type: "string" },
+} as const;
+
 export function parseExportArgs(argv: string[]): ExportFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      out: { type: "string" },
-    },
+    options: EXPORT_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -251,7 +268,7 @@ export interface VerifyFlags {
   // command layer applies the bare-verify default (= --templates) when none are.
   /** Run the template/prompt {{field}}↔payload drift gate. */
   templates: boolean;
-  /** Run the codegen-drift gate (regenerate-to-temp and diff committed output). */
+  /** Run the codegen-drift gate: is the GENERATED contribution of each file current? */
   codegen: boolean;
   /**
    * Run the docs-drift gate: regenerate the `meta docs` surfaces into a temp dir and diff
@@ -260,8 +277,9 @@ export interface VerifyFlags {
    * A SEPARATE subverb rather than part of `--codegen`, because they check different
    * trees under different ownership rules: `--codegen` regenerates `outDir`/`targets` and
    * must respect the hand edits `meta gen` preserves, while the docs tree has no merge,
-   * no manifest, and lives in a directory (`./docs` by default) full of hand-written
-   * files it does not own. Folding them together would have to pick one of those rules
+   * no manifest, and lives in a directory the adopter chose (`./docs/generated` by
+   * default) that may hold hand-written files it does not own. Folding them together
+   * would have to pick one of those rules
    * for both.
    */
   docs: boolean;
@@ -297,36 +315,74 @@ export interface VerifyFlags {
    */
   lax: boolean;
   /**
-   * How many advisory lines TEXT output prints per SECTION before truncating
-   * (`DEFAULT_ADVISORY_LIMIT`, or Infinity for `--limit all`). Per-section, never
-   * shared across them — the reason the two caps were separate in the first place
-   * is that one shared budget lets the authoring lint push every gate warning off
-   * the end. It never applies to a structured payload, which carries everything.
+   * How many advisory lines TEXT output prints per printed LIST before truncating
+   * (`DEFAULT_ADVISORY_LIMIT`, or Infinity for `--limit all`). Never shared across
+   * lists — one shared budget lets the biggest list push every other finding off the
+   * end. It never applies to a structured payload, which carries everything.
+   *
+   * Per LIST, not per section, and the distinction is real rather than pedantic: the
+   * anti-pattern tier prints TWO separately-headed lists (the hand-rolling findings and
+   * the F52 missing-`baseUrl` findings) while being ONE section everywhere else — one
+   * structured list keyed by `rule`, one `--no-antipatterns` muting both. So that
+   * section's text output can reach a MULTIPLE of the cap. Deliberate: a project with 200
+   * money-float sites would otherwise never see its `baseUrl` advisory, which is the one
+   * that silently drops the API prefix from every generated hook, and starving the small
+   * list is the worse failure. Pinned in advisory-structured-output.test.ts.
    */
   limit: number;
 }
 
+/** The flag table `parseVerifyArgs` parses. Exported so the help text can be gated against it. */
+export const VERIFY_OPTIONS = {
+  prompts: { type: "string" },
+  db: { type: "string" },
+  dialect: { type: "string" },
+  allow: { type: "string", multiple: true },
+  "skip-schema": { type: "boolean", default: false },
+  templates: { type: "boolean", default: false },
+  codegen: { type: "boolean", default: false },
+  docs: { type: "boolean", default: false },
+  replay: { type: "boolean", default: false },
+  "replay-snapshot": { type: "boolean", default: false },
+  "no-antipatterns": { type: "boolean", default: false },
+  "no-requirement-lint": { type: "boolean", default: false },
+  lax: { type: "boolean", default: false },
+  "d1": { type: "string" },
+  "remote": { type: "boolean", default: false },
+  "limit": { type: "string" },
+} as const;
+
+/**
+ * The `--allow` tokens for one invocation, from EVERY occurrence of the flag.
+ *
+ * `--allow` is comma-separated, and repeating it is the natural reading (it is what
+ * `--server` does). It used to take the LAST occurrence only, so
+ * `--allow drop-fk --allow drop-view` silently discarded `drop-fk` and then printed
+ * "re-run with --allow drop-fk to apply" seven times — an instruction the user had just
+ * followed. Both spellings, and any mixture of them, now mean the union.
+ *
+ * Duplicates collapse: asking for the same permission twice is one permission.
+ */
+function parseAllowTokens(raw: string | string[] | undefined): AllowToken[] {
+  const occurrences = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw];
+  const seen = new Set<string>();
+  for (const occurrence of occurrences) {
+    for (const tok of occurrence.split(",").map((t) => t.trim()).filter((t) => t.length > 0)) {
+      if (!ALLOW_TOKENS.includes(tok as AllowToken)) {
+        throw new Error(
+          `invalid --allow token '${tok}'; expected one of: ${ALLOW_TOKENS.join(", ")}`,
+        );
+      }
+      seen.add(tok);
+    }
+  }
+  return [...seen] as AllowToken[];
+}
+
 export function parseVerifyArgs(argv: string[]): VerifyFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      prompts: { type: "string" },
-      db: { type: "string" },
-      dialect: { type: "string" },
-      allow: { type: "string" },
-      "skip-schema": { type: "boolean", default: false },
-      templates: { type: "boolean", default: false },
-      codegen: { type: "boolean", default: false },
-      docs: { type: "boolean", default: false },
-      replay: { type: "boolean", default: false },
-      "replay-snapshot": { type: "boolean", default: false },
-      "no-antipatterns": { type: "boolean", default: false },
-      "no-requirement-lint": { type: "boolean", default: false },
-      lax: { type: "boolean", default: false },
-      "d1": { type: "string" },
-      "remote": { type: "boolean", default: false },
-      "limit": { type: "string" },
-    },
+    options: VERIFY_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -336,17 +392,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     throw new Error(`invalid --dialect '${dialect}'; expected: ${DIALECTS.join(", ")}`);
   }
 
-  const allowRaw = (values.allow as string | undefined) ?? "";
-  const allowTokens = allowRaw.length === 0
-    ? []
-    : allowRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  for (const tok of allowTokens) {
-    if (!ALLOW_TOKENS.includes(tok as AllowToken)) {
-      throw new Error(
-        `invalid --allow token '${tok}'; expected one of: ${ALLOW_TOKENS.join(", ")}`,
-      );
-    }
-  }
+  const allowTokens = parseAllowTokens(values.allow as string | string[] | undefined);
 
   const templates = !!values.templates;
   const codegen = !!values.codegen;
@@ -395,13 +441,16 @@ export interface PromptSnapshotFlags {
   prompts: string | undefined;
 }
 
+/** The flag table `parsePromptSnapshotArgs` parses. Exported so the help text can be gated against it. */
+export const PROMPT_SNAPSHOT_OPTIONS = {
+  check: { type: "boolean", default: false },
+  prompts: { type: "string" },
+} as const;
+
 export function parsePromptSnapshotArgs(argv: string[]): PromptSnapshotFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      check: { type: "boolean", default: false },
-      prompts: { type: "string" },
-    },
+    options: PROMPT_SNAPSHOT_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -447,25 +496,28 @@ export interface MigrateFlags {
   applyPending: boolean;
 }
 
+/** The flag table `parseMigrateArgs` parses. Exported so the help text can be gated against it. */
+export const MIGRATE_OPTIONS = {
+  "db": { type: "string" },
+  "dialect": { type: "string" },
+  "migration-format": { type: "string" },
+  "out-dir": { type: "string" },
+  "slug": { type: "string" },
+  "allow": { type: "string", multiple: true },
+  "on-ambiguous": { type: "string" },
+  "dry-run": { type: "boolean", default: false },
+  "from-db": { type: "boolean", default: false },
+  "d1": { type: "string" },
+  "remote": { type: "boolean", default: false },
+  "apply": { type: "boolean", default: false },
+  "rollback": { type: "string" },
+  "yes": { type: "boolean", default: false },
+} as const;
+
 export function parseMigrateArgs(argv: string[]): MigrateFlags {
   const { values, positionals } = parseArgs({
     args: argv,
-    options: {
-      "db": { type: "string" },
-      "dialect": { type: "string" },
-      "migration-format": { type: "string" },
-      "out-dir": { type: "string" },
-      "slug": { type: "string" },
-      "allow": { type: "string" },
-      "on-ambiguous": { type: "string" },
-      "dry-run": { type: "boolean", default: false },
-      "from-db": { type: "boolean", default: false },
-      "d1": { type: "string" },
-      "remote": { type: "boolean", default: false },
-      "apply": { type: "boolean", default: false },
-      "rollback": { type: "string" },
-      "yes": { type: "boolean", default: false },
-    },
+    options: MIGRATE_OPTIONS,
     strict: true,
     allowPositionals: true,
   });
@@ -497,17 +549,7 @@ export function parseMigrateArgs(argv: string[]): MigrateFlags {
     throw new Error(`invalid --on-ambiguous '${onAmb}'; expected: ${ON_AMBIGUOUS.join(", ")}`);
   }
 
-  const allowRaw = (values.allow as string | undefined) ?? "";
-  const allowTokens = allowRaw.length === 0
-    ? []
-    : allowRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  for (const tok of allowTokens) {
-    if (!ALLOW_TOKENS.includes(tok as AllowToken)) {
-      throw new Error(
-        `invalid --allow token '${tok}'; expected one of: ${ALLOW_TOKENS.join(", ")}`,
-      );
-    }
-  }
+  const allowTokens = parseAllowTokens(values.allow as string | string[] | undefined);
 
   return {
     db: values.db as string | undefined,
@@ -541,13 +583,16 @@ export interface EjectFlags {
   force: boolean;
 }
 
+/** The flag table `parseEjectArgs` parses. Exported so the help text can be gated against it. */
+export const EJECT_OPTIONS = {
+  "list": { type: "boolean", default: false },
+  "force": { type: "boolean", default: false },
+} as const;
+
 export function parseEjectArgs(argv: string[]): EjectFlags {
   const { values, positionals } = parseArgs({
     args: argv,
-    options: {
-      "list": { type: "boolean", default: false },
-      "force": { type: "boolean", default: false },
-    },
+    options: EJECT_OPTIONS,
     strict: true,
     allowPositionals: true,
   });

package/src/lib/base-url-advisory.ts

@@ -0,0 +1,173 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { relPosix } from "./rel-posix.js";
+
+/**
+ * F52 — a provider mounted with no `baseUrl` on a project whose `apiPrefix` is not empty.
+ *
+ * 1.0 moved `$apiPrefix` out of the entity descriptor: a browser's base URL is a
+ * DEPLOYMENT fact, so the provider supplies it at runtime. The migration note argues the
+ * rename is safe because `<EntityFetcherProvider value={…}>` no longer typechecks — and
+ * that is true for the adopter who leaves `value` alone. It says nothing about the
+ * adopter who reads the note, renames `value` → `fetcher`, and stops: `baseUrl` is
+ * OPTIONAL with default `""`, so that tree compiles clean and every generated hook has
+ * quietly lost its `/api` segment. Nothing at the type level can see it, and on the
+ * estate where this was found nothing else could either — `vite build` transpiles without
+ * typechecking, so `build`, 150 tests and every `meta verify` gate were green over a
+ * storefront and an admin app whose entire generated CRUD surface would have 404'd.
+ *
+ * So this is the only gate that can catch it, and it is a WARNING: `baseUrl` is genuinely
+ * optional, a project may serve its API at the origin root, and a prefix can legitimately
+ * come from somewhere this scan cannot read. It never touches an exit code.
+ *
+ * It fires ONLY when `apiPrefix` is non-empty — the `meta init` scaffold sets `""`, which
+ * is exactly why the trap is easy to ship: the default-configured project is the one the
+ * design was reasoned about.
+ */
+export interface BaseUrlFinding {
+  file: string;
+  line: number;
+  /** The provider construct found without a base. */
+  construct: string;
+  message: string;
+}
+
+const IGNORE_SEGMENTS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".turbo", ".output",
+  "coverage", ".metaobjects", ".wrangler",
+]);
+const SCAN_EXT = /\.(?:ts|tsx|js|jsx|mjs)$/;
+const SKIP_FILE = /(?:\.d\.ts$|\.test\.|\.spec\.)/;
+
+/**
+ * The two ways a base is supplied, one per client tier.
+ *
+ * Matched across the WHOLE opening construct rather than a single line, because a JSX
+ * provider is nearly always written multi-line — a per-line rule (which is what the
+ * anti-pattern scan uses) would miss the formatting every real codebase has.
+ */
+const PROVIDERS: readonly { construct: string; open: RegExp; kind: "jsx" | "call" }[] = [
+  { construct: "<EntityFetcherProvider>", open: /<EntityFetcherProvider\b/g, kind: "jsx" },
+  { construct: "provideEntityFetcher()", open: /provideEntityFetcher\s*\(/g, kind: "call" },
+];
+
+/**
+ * The text of the opening construct that begins at `start`.
+ *
+ * JSX: up to the `>` that closes the opening TAG. Call this a one-file tokenizer rather
+ * than a bracket count, because a bracket count is what the first version was and it was
+ * wrong in both directions:
+ *
+ *   <EntityFetcherProvider title="a > b" fetcher={f} baseUrl="/api">
+ *       → the `>` inside the STRING ended the tag before `baseUrl`, warning about a
+ *         correct provider.
+ *   <EntityFetcherProvider fetcher={mk(")")}>
+ *       → the unbalanced `)` inside a string meant depth never returned to 0, so the
+ *         4000-char cap swallowed an unrelated `baseUrl` later in the file and SUPPRESSED
+ *         a real finding.
+ *
+ * So string literals (all three quote styles, with escapes), line comments and block
+ * comments are skipped rather than counted. A regex literal is deliberately NOT handled —
+ * telling `/` division from a regex needs real parsing, and a regex inside a JSX opening
+ * tag is vanishingly rare next to the cost of getting it wrong.
+ *
+ * Call: to the `)` balancing the argument list, so a nested object or arrow does not end
+ * it early.
+ *
+ * Both bail after a generous cap rather than scanning a whole minified file when a
+ * construct is unterminated.
+ */
+function constructText(src: string, start: number, kind: "jsx" | "call"): string {
+  const limit = Math.min(src.length, start + 4000);
+  let depth = 0;
+  for (let i = start; i < limit; i++) {
+    const c = src[i]!;
+
+    // --- skip what is not code -------------------------------------------------
+    if (c === '"' || c === "'" || c === "`") {
+      i++;
+      while (i < limit && src[i] !== c) { if (src[i] === "\\") i++; i++; }
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "/") {
+      while (i < limit && src[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "*") {
+      i += 2;
+      while (i < limit && !(src[i] === "*" && src[i + 1] === "/")) i++;
+      i++;
+      continue;
+    }
+
+    // --- code ------------------------------------------------------------------
+    if (kind === "jsx" && c === ">" && depth === 0) return src.slice(start, i + 1);
+    if (c === "{" || c === "(" || c === "[") depth++;
+    else if (c === "}" || c === ")" || c === "]") {
+      if (kind === "call" && depth === 1 && c === ")") return src.slice(start, i + 1);
+      depth--;
+    }
+  }
+  return src.slice(start, limit);
+}
+
+function scanFile(rel: string, src: string, apiPrefix: string): BaseUrlFinding[] {
+  const out: BaseUrlFinding[] = [];
+  for (const { construct, open, kind } of PROVIDERS) {
+    open.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = open.exec(src)) !== null) {
+      const text = constructText(src, m.index, kind);
+      if (/\bbaseUrl\b/.test(text)) continue;
+      const line = src.slice(0, m.index).split("\n").length;
+      out.push({
+        file: rel, line, construct,
+        message:
+          `${rel}:${line} — ${construct} is mounted with no baseUrl, but this project's ` +
+          `apiPrefix is "${apiPrefix}". Every generated hook fetches a path RELATIVE to ` +
+          `baseUrl, which defaults to "", so those requests go to the origin root and miss ` +
+          `"${apiPrefix}". Pass baseUrl (a literal, or your build's env var). If the API ` +
+          `really is served at the root here, this is a false positive — ignore it.`,
+      });
+    }
+  }
+  return out;
+}
+
+function walk(dir: string, root: string, acc: BaseUrlFinding[], apiPrefix: string): void {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (IGNORE_SEGMENTS.has(e.name)) continue;
+    const abs = join(dir, e.name);
+    // Symlinked directories are NOT followed — same as the anti-pattern scan beside it.
+    //
+    // The first version did follow them, with a comment claiming it "never re-enters
+    // one". There was no visited set, so `src/loop -> <root>` produced 41 findings for a
+    // single file (`src/loop/src/loop/…`), terminating only because Linux's 40-symlink
+    // ELOOP limit made readdirSync throw into the catch below. It also meant a link
+    // pointing outside the project — a monorepo sibling, a linked package — got walked on
+    // every `meta verify`. A provider reachable only through a symlink is reachable
+    // through its real path too, so following them buys nothing and the duplicates
+    // inflate the count the header prints.
+    if (e.isDirectory()) { walk(abs, root, acc, apiPrefix); continue; }
+    if (!SCAN_EXT.test(e.name) || SKIP_FILE.test(e.name)) continue;
+    let src: string;
+    try { src = readFileSync(abs, "utf8"); } catch { continue; }
+    if (!src.includes("EntityFetcher")) continue;
+    acc.push(...scanFile(relPosix(root, abs), src, apiPrefix));
+  }
+}
+
+/**
+ * Scan a project tree for providers mounted without a base.
+ *
+ * Returns [] when `apiPrefix` is empty — there is nothing to lose then, and warning would
+ * fire on every scaffolded project.
+ */
+export function scanForMissingBaseUrl(root: string, apiPrefix: string): BaseUrlFinding[] {
+  if (apiPrefix === "") return [];
+  const acc: BaseUrlFinding[] = [];
+  walk(root, root, acc, apiPrefix);
+  return acc;
+}

package/src/lib/codegen-drift.ts

@@ -44,6 +44,7 @@ import {
   contentHash,
   readGeneratedHash,
   listGeneratedPaths,
+  NAMES_FILE_SUFFIX,
 } from "@metaobjectsdev/codegen-ts";
 import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 import type { MetaData } from "@metaobjectsdev/metadata";
@@ -59,6 +60,14 @@ export interface CodegenDriftResult {
   driftedFiles: string[];
   /** Human-readable, one-line-per-file drift summary. */
   lines: string[];
+  /**
+   * The subset of `driftedFiles` convicted for being a HAND-EDITED names artifact,
+   * sorted. Reported rather than left to the caller to re-derive, because the remedy
+   * differs in kind: `meta gen` MERGES a hand edit and exits 0, so prescribing it for
+   * one of these is an unbreakable loop — the same loop the hand-edit exemption exists
+   * to end. Two doors asking one question must not answer it twice.
+   */
+  handEditedNames: string[];
   /** Set when the gate could not run (e.g. no outDir to compare against). */
   error?: string;
 }
@@ -128,6 +137,7 @@ export async function computeCodegenDrift(
       clean: false,
       driftedFiles: [],
       lines: [],
+      handEditedNames: [],
       error:
         "verify --codegen: no outDir configured — cannot locate the committed " +
         "generated output to diff against. Set 'outDir' (and/or per-target " +
@@ -196,6 +206,7 @@ export async function computeCodegenDrift(
     // Diff each committed outDir against its temp mirror.
     const driftedFiles = new Set<string>();
     const lines: string[] = [];
+    const handEditedNames = new Set<string>();
 
     // Whether we have any record of what we wrote here. With records, the orphan
     // branch below can scope itself to our own output; with none, it cannot tell
@@ -232,21 +243,53 @@ export async function computeCodegenDrift(
         } else {
           const a = readFileSync(join(committed, rel), "utf8");
           const b = readFileSync(join(fresh, rel), "utf8");
-          // Not `a !== b` alone: that convicts the hand edit `meta gen` preserved.
-          // The question this gate can honestly answer is "is the GENERATED
-          // contribution current?", and the recorded hash answers exactly it.
-          // FAILS CLOSED, matching `isPristineGenerated`: with no recorded hash
-          // nothing is proven, so the old byte verdict stands.
-          if (a !== b && readGeneratedHash(projectGenStateDir, relKey) !== contentHash(b)) {
-            driftedFiles.add(relKey);
-            lines.push(`~ ${relKey} (committed content differs from a fresh regen)`);
+          if (a !== b) {
+            // A `<Entity>Names` artifact is the ONE generated file where a hand edit is
+            // itself the defect, so the exemption below does not reach it. RULED: if you
+            // want a constant of your own, put it in a file of your own.
+            //
+            // The exemption exists because `meta gen` MERGES a hand edit and reports
+            // "merged", so convicting it printed a remedy that could not work — gen
+            // merges again and the next verify fails identically. A names artifact is not
+            // that shape. It is a module of physical database names, every value a string:
+            // no compiler can see a wrong one, no test reads it, and the whole point of
+            // the artifact is that a name is spelled ONCE per run and referenced. So an
+            // edited one silently renames a column for every consumer of it, while the
+            // gate reports "generated output is in sync with the metadata" — the exact
+            // failure the artifact was added to prevent, committed inside the artifact.
+            //
+            // Keyed on the suffix the emitter and the reference template both spell from
+            // one constant. An adopter who owns the generator and RENAMES the artifact
+            // opts out of this — stated rather than hidden; the gate cannot recognise a
+            // file shape it was never told about.
+            if (rel.endsWith(NAMES_FILE_SUFFIX)) {
+              driftedFiles.add(relKey);
+              handEditedNames.add(relKey);
+              lines.push(
+                `~ ${relKey} (hand-edited; a names artifact must match a fresh regen exactly — ` +
+                  `put constants of your own in a file of your own)`,
+              );
+            } else if (readGeneratedHash(projectGenStateDir, relKey) !== contentHash(b)) {
+              // Not `a !== b` alone: that convicts the hand edit `meta gen` preserved.
+              // The question this gate can honestly answer is "is the GENERATED
+              // contribution current?", and the recorded hash answers exactly it.
+              // FAILS CLOSED, matching `isPristineGenerated`: with no recorded hash
+              // nothing is proven, so the old byte verdict stands.
+              driftedFiles.add(relKey);
+              lines.push(`~ ${relKey} (committed content differs from a fresh regen)`);
+            }
           }
         }
       }
     }
 
     const sorted = [...driftedFiles].sort();
-    return { clean: sorted.length === 0, driftedFiles: sorted, lines };
+    return {
+      clean: sorted.length === 0,
+      driftedFiles: sorted,
+      lines,
+      handEditedNames: [...handEditedNames].sort(),
+    };
   } finally {
     rmSync(tempRoot, { recursive: true, force: true });
   }