@everystack/cli 0.4.99 → 0.4.102

package/src/cli/derived-introspect.ts

@@ -85,6 +85,13 @@ export interface LiveObject {
     /** The WHEN predicate as the catalog deparses it. */
     when?: string;
   };
+  /**
+   * Trigger only: `pg_trigger.tgenabled` — `O` (fires on origin, the default every declared
+   * trigger has), `D` disabled, `R` replica-only, `A` always. Read LIVE and compared to `O` by
+   * the plan; it is deliberately NOT in `defHash` (pg_get_triggerdef does not render it), so no
+   * recorded provenance hash changes. Absent means not measured.
+   */
+  enabled?: string;
   /** Live ACLs (grantee → sorted privileges), owner excluded, function defaults expanded.
    *  Absent on triggers (they take no grants) and when the introspection predates B4. */
   grants?: Record<string, string[]>;
@@ -492,7 +499,8 @@ SELECT
   (SELECT array_agg(a.attname::text ORDER BY x.ord)
      FROM unnest(t.tgattr::int2[]) WITH ORDINALITY AS x(attnum, ord)
      JOIN pg_attribute a ON a.attrelid = t.tgrelid AND a.attnum = x.attnum) AS update_of,
-  substring(pg_get_triggerdef(t.oid) from ' WHEN [(](.*)[)] EXECUTE ') AS when_expr
+  substring(pg_get_triggerdef(t.oid) from ' WHEN [(](.*)[)] EXECUTE ') AS when_expr,
+  t.tgenabled::text AS enabled
 FROM pg_trigger t
 JOIN pg_class c ON c.oid = t.tgrelid
 JOIN pg_namespace n ON n.oid = c.relnamespace
@@ -587,6 +595,8 @@ export interface TriggerRow {
   update_of?: unknown;
   /** The WHEN predicate, scraped from pg_get_triggerdef — see DERIVED_TRIGGERS_SQL. */
   when_expr?: unknown;
+  /** `tgenabled` as text (O/D/R/A). Optional: a pre-F2 read has none — not measured. */
+  enabled?: unknown;
 }
 
 export interface GrantAclRow {
@@ -651,13 +661,14 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
   for (const row of rows.grants ?? []) {
     if (IGNORED_SCHEMAS.has(row.schema)) continue;
     const key = `${String(row.kind)}:${row.schema}.${row.name}`;
-    const acc = grantsByKey.get(key) ?? {};
+    // Null prototype: a grantee is a live role name, and '__proto__' is a legal one (see assembleContract).
+    const acc = grantsByKey.get(key) ?? Object.create(null) as Record<string, string[]>;
     acc[row.grantee] = [...new Set([...(acc[row.grantee] ?? []), ...pgTextArray(row.privileges)])].sort();
     grantsByKey.set(key, acc);
   }
   const grantsFor = (kindClass: 'r' | 'f', identity: string): { grants?: Record<string, string[]> } => {
     if (rows.grants === undefined) return {}; // pre-B4 caller — absent, not empty
-    return { grants: grantsByKey.get(`${kindClass}:${identity}`) ?? {} };
+    return { grants: grantsByKey.get(`${kindClass}:${identity}`) ?? Object.create(null) };
   };
 
   const indexesByIdentity = new Map<string, string[]>();
@@ -756,6 +767,7 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
       defHash: computeDefHash(definition, []),
       table: row.schema === 'public' ? row.table : ownerIdentity,
       ownerIdentity,
+      ...(row.enabled != null ? { enabled: String(row.enabled) } : {}),
       ...(row.tgtype != null && row.function_identity != null ? {
         trg: {
           shape: parseTriggerType(Number(row.tgtype)),
@@ -768,6 +780,14 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
     if (relationIdentities.has(ownerIdentity)) {
       triggerEdges.push({ dependent: identity, referenced: ownerIdentity });
     }
+    // The trigger depends on the function it executes: PostgreSQL refuses DROP FUNCTION while
+    // the trigger exists, so a run removing both must drop the trigger first. Trigger functions
+    // take no arguments; a pre-signature function row carries the bare name.
+    if (row.function_identity != null) {
+      const fn = String(row.function_identity);
+      const executes = [`${fn}()`, fn].find((id) => relationIdentities.has(id));
+      if (executes) triggerEdges.push({ dependent: identity, referenced: executes });
+    }
   }
 
   const edges: DependencyEdge[] = [

package/src/cli/derived-plan.ts

@@ -67,6 +67,29 @@ export interface RegrantFinding {
   owner?: string;
 }
 
+/**
+ * A managed trigger whose live `tgenabled` is not `O`, the state every declared trigger has.
+ * `ALTER TABLE … DISABLE TRIGGER` touches no definition and no hash, so this is the only place it
+ * surfaces. Converged like a regrant, without ceremony: `ENABLE TRIGGER` restores the declared
+ * state and loses nothing but the drift itself.
+ */
+export interface ReenableFinding {
+  identity: string;
+  /** The trigger name. */
+  name: string;
+  /** Its table, always `schema.table` — the ALTER TABLE target. */
+  table: string;
+  /** The live tgenabled: D, R or A. */
+  state: string;
+}
+
+/** What a tgenabled value means, in the words the report uses. */
+export const TRIGGER_ENABLED_STATE: Record<string, string> = {
+  D: 'disabled — PostgreSQL never fires it',
+  R: 'enabled for replica only — it does not fire in an ordinary session',
+  A: 'enabled always — it also fires under session_replication_role = replica, where the declared trigger does not',
+};
+
 /** Declared `dependsOn` vs the live catalog's actual edges (B4: declared, then verified). */
 export interface DependencyDriftFinding {
   identity: string;
@@ -107,6 +130,9 @@ export interface ReconcilePlan {
   regrants: RegrantFinding[];
   /** Declared-vs-actual dependency drift — check-fails (fix the declaration), never blocks apply. */
   dependencyDrift: DependencyDriftFinding[];
+  /** Managed triggers that are not enabled as declared. Optional because a plan can arrive over
+   *  the ops-Lambda wire from a stage that predates it; absent reads as none. */
+  reenables?: ReenableFinding[];
 }
 
 export interface ReconcileOptions {
@@ -506,6 +532,7 @@ export function planReconcile(
 
   const regrants: RegrantFinding[] = [];
   const dependencyDrift: DependencyDriftFinding[] = [];
+  const reenables: ReenableFinding[] = [];
   // Rebaselined objects join the lens: their live catalog rows are as real as a skip's,
   // and running the checks NOW means a migration converges (grants ride the same apply)
   // instead of surfacing on the next plan.
@@ -518,9 +545,15 @@ export function planReconcile(
   const lensSet = new Set([...skipped, ...rebaseline, ...backfill, ...baseline]);
   for (const src of source.objects) {
     if (!lensSet.has(src.identity)) continue;
-    if (src.kind === 'trigger' || src.kind === 'sql') continue; // no grants, no rewrite edges
     const liveObj = liveById.get(src.identity);
 
+    // Trigger enabled state — only for a trigger this source declares (internal FK triggers and
+    // unmanaged ones never reach here), and only when the catalog measured it (absent ≠ 'O').
+    if (src.kind === 'trigger' && liveObj?.enabled !== undefined && liveObj.enabled !== 'O' && liveObj.ownerIdentity) {
+      reenables.push({ identity: src.identity, name: liveObj.name, table: liveObj.ownerIdentity, state: liveObj.enabled });
+    }
+    if (src.kind === 'trigger' || src.kind === 'sql') continue; // no grants, no rewrite edges
+
     // Grant drift — only when the catalog actually reported ACLs (absent ≠ empty).
     // Every object is descriptor-compiled (db/sql retired, B7), and the compiler
     // ALWAYS declares authz — a private relation is declared-empty, not undeclared —
@@ -735,5 +768,8 @@ export function planReconcile(
     migrations,
     regrants: regrants.sort((a, b) => a.identity.localeCompare(b.identity)),
     dependencyDrift: dependencyDrift.sort((a, b) => a.identity.localeCompare(b.identity)),
+    // Present only when there is one: an unchanged database's plan (and its --json) stays
+    // byte-identical to what it was before this field existed.
+    ...(reenables.length ? { reenables: reenables.sort((a, b) => a.identity.localeCompare(b.identity)) } : {}),
   };
 }

package/src/cli/derived-render.ts

@@ -20,6 +20,8 @@ import { parseIndexDefinition } from './schema-introspect';
 import { modelImportPath, modelFileName, renderFieldLines } from './model-render';
 import { splitFunctionIdentity } from './pg-argtypes';
 import { GOVERNED_VOCABULARY, KNOWN_ROLES } from './authz-derive';
+import { templateBody, tsString, commentText } from './ts-template';
+import { safeBinding, safeFileStem, liveObject, refuseProtoKey } from './generated-names';
 
 /**
  * One rendered object's own lines, plus what it depends on — the unit `--derived-out <dir>`
@@ -101,21 +103,12 @@ function toCamelCase(name: string): string {
   return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
 }
 
-/** Escape a body for a template literal in generated source — it must always parse. */
-function tsTemplate(body: string): string {
-  return body.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
-}
-
 /** An object key, bare when it is a valid identifier and quoted when it is not — a role
  *  name is a PostgreSQL identifier and may hold characters JavaScript will not take bare. */
 function tsKey(s: string): string {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s) ? s : tsString(s);
 }
 
-function tsString(s: string): string {
-  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-}
-
 /**
  * Split a relation's live ACL into what `abilities` can SAY and what must be RECORDED.
  *
@@ -134,6 +127,9 @@ function splitRelationGrants(
   const privileges: Record<string, string[]> = {};
   const foreign: string[] = [];
   for (const [grantee, privs] of Object.entries(grants)) {
+    // `privileges[grantee] = …` below would set the prototype for a grantee named __proto__.
+    // Introspection keeps such a grant (null-prototype maps), so the pull refuses here, naming it.
+    refuseProtoKey(grantee, liveObject('role', grantee));
     const selectOnly = privs.length === 1 && privs[0] === 'SELECT';
     // ABILITIES are limited to the compiler's own vocabulary (authz-derive's KNOWN_ROLES).
     // A foreign grantee is FACT, not opinion, so it is RECORDED — never declared as an
@@ -303,7 +299,7 @@ export function renderedOwner(
     // in which case rendering would emit source that throws on import.
     if (!RENDERABLE_ROLE.test(owner)) {
       const why = `${o.identity}: owner '${owner}' is not a bare lowercase role name, which is all the model's owner property accepts (it is interpolated into SET ROLE) — ownership NOT declared. Rename the role, or declare the owner by hand.`;
-      return { fixme: `// FIXME: ${why}`, warning: why };
+      return { fixme: `// FIXME: ${commentText(why)}`, warning: why };
     }
     return { prop: `owner: ${tsString(owner)},` };
   }
@@ -311,7 +307,7 @@ export function renderedOwner(
   if (!ambient.length) {
     // Owner known, discriminator not measured. Refuse to classify rather than guess.
     return {
-      fixme: `// FIXME: ${o.identity} is owned by '${owner}', but this pull could not tell whether that is a chosen principal or the build credential — owner is NOT declared. Add owner: '${owner}' if that role is the intended owner.`,
+      fixme: `// ${commentText(`FIXME: ${o.identity} is owned by '${owner}', but this pull could not tell whether that is a chosen principal or the build credential — owner is NOT declared. Add owner: '${owner}' if that role is the intended owner.`)}`,
     };
   }
 
@@ -321,11 +317,11 @@ export function renderedOwner(
   // on a brownfield database it is the common shape, and echoing all of it would bury the rest.
   return elevated
     ? {
-      fixme: `// FIXME SECURITY: ${o.identity} is ${elevated.posture} and owned by '${owner}' — ${because}. ${elevated.what} runs with that role's privileges. The observed owner is NOT declared, because declaring the build credential would make the accident reproducible; declare the intended owner with owner: '<role>'.`,
+      fixme: `// ${commentText(`FIXME SECURITY: ${o.identity} is ${elevated.posture} and owned by '${owner}' — ${because}. ${elevated.what} runs with that role's privileges. The observed owner is NOT declared, because declaring the build credential would make the accident reproducible; declare the intended owner with owner: '<role>'.`)}`,
       warning: `${o.identity}: ${elevated.posture}, owned by '${owner}' (${because}) — ${elevated.what.toLowerCase()} runs with that role's privileges. Ownership was NOT declared; declare the intended owner with owner: '<role>'.`,
     }
     : {
-      fixme: `// FIXME: ${o.identity} is owned by '${owner}' — ${because}, not a chosen principal, so ownership is NOT declared. Add owner: '<role>' if a specific role should own it.`,
+      fixme: `// ${commentText(`FIXME: ${o.identity} is owned by '${owner}' — ${because}, not a chosen principal, so ownership is NOT declared. Add owner: '<role>' if a specific role should own it.`)}`,
     };
 }
 
@@ -344,12 +340,12 @@ export function renderedFunctionOwner(
 function renderIndexBuilder(indexdef: string): string | null {
   const parsed = parseIndexDefinition(indexdef);
   if (!parsed) return null;
-  const entry = (c: string): string => (PLAIN_IDENT.test(c) ? tsString(c) : `sql\`${tsTemplate(c)}\``);
+  const entry = (c: string): string => (PLAIN_IDENT.test(c) ? tsString(c) : `sql\`${templateBody(c)}\``);
   let s = `index(${parsed.columns.map(entry).join(', ')})`;
   if (parsed.using) s += `.using(${tsString(parsed.using)})`;
   if (parsed.unique) s += '.unique()';
   if (parsed.include?.length) s += `.include(${parsed.include.map(tsString).join(', ')})`;
-  if (parsed.where) s += `.where(sql\`${tsTemplate(parsed.where)}\`)`;
+  if (parsed.where) s += `.where(sql\`${templateBody(parsed.where)}\`)`;
   return s;
 }
 
@@ -361,12 +357,12 @@ function renderIndexBuilder(indexdef: string): string | null {
 function renderTableIndexBuilder(indexdef: string): string | null {
   const parsed = parseIndexDefinition(indexdef);
   if (!parsed) return null;
-  const entry = (c: string): string => (PLAIN_IDENT.test(c) ? tsString(toCamelCase(c)) : `sql\`${tsTemplate(c)}\``);
+  const entry = (c: string): string => (PLAIN_IDENT.test(c) ? tsString(toCamelCase(c)) : `sql\`${templateBody(c)}\``);
   let s = `index(${parsed.columns.map(entry).join(', ')})`;
   if (parsed.using) s += `.using(${tsString(parsed.using)})`;
   if (parsed.unique) s += '.unique()';
   if (parsed.include?.length) s += `.include(${parsed.include.map((c) => tsString(toCamelCase(c))).join(', ')})`;
-  if (parsed.where) s += `.where(sql\`${tsTemplate(parsed.where)}\`)`;
+  if (parsed.where) s += `.where(sql\`${templateBody(parsed.where)}\`)`;
   return s;
 }
 
@@ -412,7 +408,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
   const sequenceNames: string[] = [];
   for (const seq of opts.sequences ?? []) {
     const linesStart = lines.length;
-    const varName = toCamelCase(seq.name.replace(/\./g, '_'));
+    const varName = safeBinding(toCamelCase(seq.name.replace(/\./g, '_')), liveObject('sequence', seq.name));
     const props: string[] = [];
     if (seq.as !== 'bigint') props.push(`as: ${tsString(seq.as)}`);
     if (seq.start != null) props.push(`start: ${seq.start}`);
@@ -436,8 +432,9 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
 
   // Triggers are held out of the topological pass and emitted LAST (see the trigger block
   // at the end). A binding needs BOTH its target and its execute function to already
-  // exist, and the catalog records no trigger→function edge, so file order — not the
-  // dependency sort — is what guarantees it.
+  // exist. The catalog does record trigger→function (and trigger→owning view) edges, for
+  // the reconcile drop order, but this pass never sees triggers: file order — not the
+  // dependency sort — is what guarantees it here.
   const renderable = catalog.objects.filter((o) => o.kind !== 'trigger');
   const triggers = catalog.objects.filter((o) => o.kind === 'trigger');
   const byIdentity = new Map(renderable.map((o) => [o.identity, o]));
@@ -450,7 +447,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
   const varCounts = new Map<string, number>();
   for (const o of renderable) varCounts.set(baseVar(o), (varCounts.get(baseVar(o)) ?? 0) + 1);
   const varOf = new Map(renderable.map((o) =>
-    [o.identity, (varCounts.get(baseVar(o)) ?? 0) > 1 ? baseVar(o) + argSuffix(o.identity) : baseVar(o)]));
+    [o.identity, safeBinding((varCounts.get(baseVar(o)) ?? 0) > 1 ? baseVar(o) + argSuffix(o.identity) : baseVar(o), liveObject(o.kind, o.identity))]));
   // The name a descriptor DECLARES: bare for public, qualified otherwise. parseQualified
   // round-trips it, so the compiled identity matches the live object it was pulled from —
   // a bare name would compile to public.<name>, baseline would never join, and reconcile
@@ -509,7 +506,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       } else if (derived) {
         refs.push(derived);
         derivedIdents.push(e.referenced);
-      } else fixmes.push(`// FIXME: dependsOn ${e.referenced} — not in the pulled set; declare it by hand.`);
+      } else fixmes.push(`// FIXME: dependsOn ${commentText(e.referenced)} — not in the pulled set; declare it by hand.`);
     }
     return { refs: refs.sort(), fixmes, identRefs: { model: modelIdents.sort(), derived: derivedIdents.sort() } };
   };
@@ -618,7 +615,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
               ...(builders.length ? [`  constraints: [${builders.join(', ')}],`] : []),
               ...(refs.length ? [`  dependsOn: [${refs.join(', ')}],`] : []),
               ...(o.comment ? [`  comment: ${tsString(o.comment)},`] : []),
-              `  as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`,
+              `  as: sql\`${templateBody(o.definition.trim().replace(/;$/, ''))}\`,`,
               '});',
               '',
             );
@@ -675,7 +672,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
           if (o.populated === false) props.push(`populate: 'deferred',`);
         }
         if (o.comment) props.push(`comment: ${tsString(o.comment)},`);
-        props.push(`as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`);
+        props.push(`as: sql\`${templateBody(o.definition.trim().replace(/;$/, ''))}\`,`);
         need(o.kind === 'view' ? 'defineView' : 'defineMaterializedView');
         need('sql');
         lines.push(
@@ -711,14 +708,14 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
         if (ownership.prop) {
           const why = `${o.identity}: owned by '${o.owner}', but defineSql cannot declare an owner — the build will create it as the connecting role. Move it into defineFunction's vocabulary, or set the owner by hand after the build.`;
           warnings.push(why);
-          lines.push(`// FIXME: ${why}`);
+          lines.push(`// FIXME: ${commentText(why)}`);
         }
         lines.push(
-          `// FIXME: ${o.identity} — signature beyond defineFunction's v1 vocabulary; kept verbatim as defineSql.`,
+          `// FIXME: ${commentText(o.identity)} — signature beyond defineFunction's v1 vocabulary; kept verbatim as defineSql.`,
           `export const ${varName} = defineSql(${tsString(sqlName)}, {`,
           `  kind: 'function',`,
-          `  drop: sql\`DROP FUNCTION IF EXISTS ${o.schema === 'public' ? o.name : `${o.schema}.${o.name}`}${f?.identityArgs !== undefined ? `(${f.identityArgs})` : ''}\`,`,
-          `  as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`,
+          `  drop: sql\`${templateBody(`DROP FUNCTION IF EXISTS ${o.schema === 'public' ? o.name : `${o.schema}.${o.name}`}${f?.identityArgs !== undefined ? `(${f.identityArgs})` : ''}`)}\`,`,
+          `  as: sql\`${templateBody(o.definition.trim().replace(/;$/, ''))}\`,`,
           '});',
           '',
         );
@@ -731,7 +728,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       const props: string[] = [];
       if (args.length) {
         const rendered = args.map((a) =>
-          `arg(${tsString(a.name)}, ${tsString(a.type)}${a.default ? `, { default: sql\`${tsTemplate(a.default)}\` }` : ''})`);
+          `arg(${tsString(a.name)}, ${tsString(a.type)}${a.default ? `, { default: sql\`${templateBody(a.default)}\` }` : ''})`);
         props.push(`args: [${rendered.join(', ')}],`);
         need('arg');
       }
@@ -773,7 +770,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       if (publicExec) props.push(`privileges: { PUBLIC: ['EXECUTE'] },`);
       if (refs.length) props.push(`dependsOn: [${refs.join(', ')}],`);
       if (o.comment) props.push(`comment: ${tsString(o.comment)},`);
-      props.push(`body: sql\`${tsTemplate(f.src.trim())}\`,`);
+      props.push(`body: sql\`${templateBody(f.src.trim())}\`,`);
       need('defineFunction');
       need('sql');
       lines.push(
@@ -782,7 +779,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
         // adopting the descriptor no longer applies a revoke. It is still worth a look on a
         // SECURITY DEFINER function, which is what db:check now WARNs about.
         ...(publicExec && f.secdef
-          ? [`// NOTE: ${o.identity} is SECURITY DEFINER and live-granted EXECUTE to PUBLIC — recorded, not chosen. Narrow it to can('execute', { role }) once you know the intended callers.`]
+          ? [`// NOTE: ${commentText(o.identity)} is SECURITY DEFINER and live-granted EXECUTE to PUBLIC — recorded, not chosen. Narrow it to can('execute', { role }) once you know the intended callers.`]
           : []),
         `export const ${varName} = defineFunction(${tsString(declaredName(o))}, {`,
         ...props.map((p) => `  ${p}`),
@@ -842,18 +839,18 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     // `export const X` — the file does not compile, and `execute: X` would bind the
     // trigger to itself. Suffix only on collision, so an uncontended schema renders
     // byte-identically to a name-per-object scheme.
-    const varName = uniqueVar(
+    const varName = safeBinding(uniqueVar(
       toCamelCase(o.schema === 'public' ? o.name : `${o.schema}_${o.name}`),
       o,
       usedVars,
-    );
+    ), liveObject('trigger', o.identity));
     const props = [
       `on: ${targetVar},`,
       `timing: ${tsString(o.trg.shape.timing)},`,
       `events: [${o.trg.shape.events.map(tsString).join(', ')}],`,
       `forEach: ${tsString(o.trg.shape.forEach)},`,
       ...(o.trg.updateOf?.length ? [`of: [${o.trg.updateOf.map(tsString).join(', ')}],`] : []),
-      ...(o.trg.when ? [`condition: sql\`${tsTemplate(o.trg.when)}\`,`] : []),
+      ...(o.trg.when ? [`condition: sql\`${templateBody(o.trg.when)}\`,`] : []),
       `execute: ${fnVar},`,
     ];
     if (o.trg.when) need('sql');
@@ -943,6 +940,8 @@ function derivedBucket(kind: DerivedRecord['kind'], schema: string): string {
   if (kind === 'view' || kind === 'materialized view') return 'views';
   if (kind === 'trigger') return 'triggers';
   if (kind === 'sequence') return 'index';
+  // The schema names a split FILE, written under the derived directory.
+  safeFileStem(schema.replace(/_/g, '-'), liveObject('schema', schema));
   return `functions-${schema}`;
 }
 

package/src/cli/edge-plan.ts

@@ -30,14 +30,14 @@ import type { OwnerApplyMode } from './derived-apply';
 import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot, TableSchema } from './schema-introspect';
 import type { AuthzContract, SequenceGrantContract, DefaultAclScope } from './authz-contract';
-import { ownSequenceName, foreignKeyContentKey } from './schema-diff';
-import { generateMigrationSql, unmodeledTables } from './migration-generate';
+import { ownSequenceName, foreignKeyContentKey, type SchemaChange } from './schema-diff';
+import { generateMigration, unmodeledTables } from './migration-generate';
 import { compileTableContract } from './authz-compile';
 import { carryUngovernedAuthz, inheritedSequenceGrants, type GrantExemption } from './authz-reconcile';
 import { BASELINE_FILE } from './authz-baseline';
 import { classifyGeneratedStatements, classifyDestructive, partitionStatements, renderStatementHistogram } from './state-apply';
 import { statementHead, statementHeadOrSelf } from './sql-statement';
-import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForModels, stableStringify, compareStoredFingerprint, formatChangedMessage, schemaOf, FINGERPRINT_VERSION, type Fingerprint } from './schema-fingerprint';
+import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForModels, stableStringify, compareStoredFingerprint, formatChangedMessage, schemaOf, divergentSurfaces, FINGERPRINT_VERSION, type Fingerprint } from './schema-fingerprint';
 import { compileDeclaredState } from './declared-diff';
 import { compileTableRenames, compileTableMoves, compileRenames } from './schema-compile';
 
@@ -408,7 +408,7 @@ export function predictLiveState(
   // sets those explicitly and the declared contract already models them.
   const defaultAclFor = (scope: DefaultAclScope | undefined, schema: string): Record<string, string[]> => {
     if (!scope) return {};
-    const out: Record<string, string[]> = {};
+    const out: Record<string, string[]> = Object.create(null); // keyed by a live role name
     for (const key of ['', schema]) {
       for (const [grantee, privileges] of Object.entries(scope[key] ?? {})) {
         if (foreignGrantee(grantee)) out[grantee] = [...new Set([...(out[grantee] ?? []), ...privileges])].sort();
@@ -461,7 +461,7 @@ export function predictLiveState(
       const inherited = inheritedSequenceGrants(d);
       const liveName = liveNameFor(d.table);
       for (const s of liveSeqByTable.get(liveName) ?? []) {
-        const foreign: Record<string, string[]> = {};
+        const foreign: Record<string, string[]> = Object.create(null); // keyed by a live role name
         for (const [role, privileges] of Object.entries(s.grants)) {
           if (foreignGrantee(role)) foreign[role] = privileges;
         }
@@ -540,13 +540,37 @@ export function declaredGranteesOf(models: ModelDescriptor[], opts: { schema?: s
   return grantees;
 }
 
+/**
+ * A change the differ can only hold as a notice, but which the fingerprint SEES — so a plan
+ * that skips it predicts an endpoint its own apply can never reach: the verify after the apply
+ * fails with the rest of the edge already committed, and the next db:plan reads "Up to date" over
+ * a database db:fingerprint calls MISMATCH. The reason, or null for every other change (a notice
+ * the fingerprint does not see — a satisfied rename marker, a rename hint — mints as before).
+ *
+ *   primaryKeyChange   the key is hashed by its columns; without the live key's name the edge
+ *                      has nothing to drop it by.
+ *   enumValuesChanged  the enum's values are hashed; ADD VALUE is all the edge can do in place.
+ */
+function unplannableReason(change: SchemaChange): string | null {
+  switch (change.kind) {
+    case 'primaryKeyChange':
+      return `the primary key of ${change.table} changes (${change.from.join(', ')} → ${change.to.join(', ')}), ` +
+        'but the database read did not name the live key, so the plan has nothing to drop it by';
+    case 'enumValuesChanged':
+      return `enum ${change.name} changes its values ([${change.from.join(', ')}] → [${change.to.join(', ')}]) ` +
+        'in a way ALTER TYPE … ADD VALUE cannot make';
+    default:
+      return null;
+  }
+}
+
 export function mintEdgePlan(
   models: ModelDescriptor[],
   snapshot: SchemaSnapshot,
   contract: AuthzContract,
   opts: MintOptions = {},
 ): EdgePlan {
-  const statements = generateMigrationSql(models, snapshot, {
+  const { statements, changes } = generateMigration(models, snapshot, {
     schema: opts.schema,
     allowDrops: opts.allowDrops,
     liveAuthz: contract,
@@ -571,6 +595,31 @@ export function mintEdgePlan(
   const declaredGrantees = declaredGranteesOf(models, { schema: opts.schema });
   const breakdown = partitionStatements(classified.executable, { declaredGrantees });
   const destructive = breakdown.drops.length + breakdown.narrowings.length + breakdown.strips.length;
+  const governedRoles = governedRolesForModels(models, opts.governedRoles);
+  const from = fingerprintLive(snapshot, contract);
+  const to = predictLiveState(models, snapshot, contract, { schema: opts.schema, governedRoles, carryUngoverned: true });
+
+  // A plan must reach its own endpoint. Two ways it cannot, both refused here — the mint is the
+  // last point that holds the edge and both endpoints together.
+  //
+  //  1. A change held as a notice that the fingerprint sees. The rest of the edge would commit
+  //     and the verify after it would fail. Checked FIRST: it names the precise reason.
+  const unplannable = changes.map(unplannableReason).filter((r): r is string => r !== null);
+  if (unplannable.length > 0) {
+    throw new Error(
+      `the planner cannot express ${unplannable.length} change(s), and the database would not match the models without them: ` +
+      `${unplannable.join('; ')}. Make the change by hand, then re-plan.`,
+    );
+  }
+  //  2. Nothing to run, yet the endpoints differ, whatever the cause. Minted, this is a plan that
+  //     prints "Up to date" over a database db:fingerprint calls MISMATCH.
+  if (classified.executable.length === 0 && from.hash !== to.hash) {
+    const surfaces = divergentSurfaces(to.canonical, from.canonical);
+    throw new Error(
+      `the planner cannot express the difference between this database and the models (${surfaces.join('; ') || 'no surface named'}): ` +
+      'there is no statement to run, but the database would not match the models. Make the change by hand, then re-plan.',
+    );
+  }
 
   // The plan's two endpoints are both FULL live hashes, deliberately:
   //  - `from` is the RAW live hash (everything introspected) — the concurrency lock and the
@@ -580,12 +629,11 @@ export function mintEdgePlan(
   //    empty plan means `from == to`, and db:apply verifies the full landed hash against it.
   // The governed set still rides on the plan — the descent declares-test and db:check use it — but
   // the endpoint itself is full.
-  const governedRoles = governedRolesForModels(models, opts.governedRoles);
   return {
     v: PLAN_VERSION,
-    fromFingerprint: fingerprintLive(snapshot, contract).hash,
+    fromFingerprint: from.hash,
     fpVersion: FINGERPRINT_VERSION,
-    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema, governedRoles, carryUngoverned: true }),
+    toFingerprint: to.hash,
     toFlavor: 'full',
     defaultAclHash: defaultAclHash(contract),
     declaredFingerprint: fingerprintModels(models, { schema: opts.schema }).hash,

package/src/cli/generated-artifacts.ts

@@ -0,0 +1,22 @@
+/**
+ * The generated artifacts db:generate (and db:sync) refresh from the models on every run, before
+ * any database is read: the drizzle runtime schema, and beside it the model map (model-map.ts).
+ * One writer, so every verb that refreshes one refreshes both, and db:check's byte-for-byte gates
+ * judge exactly what was written. Writing them opens no connection.
+ */
+
+import fs from 'node:fs/promises';
+import type { DerivedDescriptor, ModelDescriptor } from '@everystack/model';
+import { compileDrizzleSource } from './schema-source';
+import { modelMapPath, renderModelMap } from './model-map';
+
+export async function writeGeneratedArtifacts(
+  schemaOut: string,
+  models: ModelDescriptor[],
+  derived: DerivedDescriptor[] | undefined,
+): Promise<{ schemaOut: string; modelMapOut: string }> {
+  const modelMapOut = modelMapPath(schemaOut);
+  await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived }), 'utf8');
+  await fs.writeFile(modelMapOut, renderModelMap(models), 'utf8');
+  return { schemaOut, modelMapOut };
+}

package/src/cli/generated-names.ts

@@ -0,0 +1,108 @@
+/**
+ * The one check every db:pull renderer applies where a live PostgreSQL name becomes generated
+ * TypeScript that is NOT a string literal: a variable name, a bare object key, a file name or
+ * an import path.
+ *
+ * A quoted PostgreSQL name can hold any character. camelCase alone turned a view named
+ * `a=process.exit(1),b` into `export const a=process.exit(1),b = defineView(…)`, which ran on
+ * import, and a table named `/../../x` in a schema into a file written outside `--out`. So a
+ * name that cannot become a safe identifier or file name is REFUSED, naming the object and its
+ * live name. It is never renamed here: a rename would separate the generated symbol from the
+ * name it declares, and that is a design decision of its own.
+ *
+ * The live name itself keeps flowing as a string literal (`defineView('name', …)`), escaped by
+ * `tsString` in ts-template.ts.
+ */
+
+import path from 'node:path';
+
+/** A db:pull refusal: a live name has no safe spelling in the generated source. */
+export class UnsafeGeneratedNameError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UnsafeGeneratedNameError';
+  }
+}
+
+/**
+ * The JavaScript IdentifierName grammar without escapes: a Unicode ID_Start (or `$`, `_`), then
+ * ID_Continue (or `$`). Unicode is kept because a name like `café` rendered and worked before.
+ * ZWJ/ZWNJ are left out on purpose: they are legal but invisible.
+ */
+const IDENTIFIER_NAME = /^[\p{ID_Start}$_][\p{ID_Continue}$]*$/u;
+
+/**
+ * Words a binding cannot take in an ES module (strict mode): the reserved words, the strict
+ * future reserved words, and `eval`/`arguments`, which strict mode refuses as a binding.
+ * As an object key every one of these is legal, which is why a column named `class` renders.
+ */
+const RESERVED_BINDINGS = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete',
+  'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import',
+  'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try',
+  'typeof', 'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface',
+  'package', 'private', 'protected', 'public', 'eval', 'arguments',
+]);
+
+/** A file stem: identifier characters and `-`. No `/`, `\`, `.`, so no `..` and no leading dot. */
+const FILE_STEM = /^[\p{ID_Continue}$-]+$/u;
+
+/** `view "public.v"` — how a refusal names the live object. */
+export function liveObject(kind: string, liveName: string): string {
+  return `${kind} ${JSON.stringify(liveName)}`;
+}
+
+function refuse(what: string, role: string, rendered: string, why: string): never {
+  throw new UnsafeGeneratedNameError(
+    `db:pull refuses ${what}: it would render as the TypeScript ${role} ${JSON.stringify(rendered)}, which ${why}. `
+    + 'Nothing was written. Rename it in the database, or pull a schema that does not hold it.',
+  );
+}
+
+/** A generated `export const` / import binding. Returns `rendered` unchanged when it is safe. */
+export function safeBinding(rendered: string, what: string): string {
+  if (!IDENTIFIER_NAME.test(rendered)) refuse(what, 'variable', rendered, 'is not a JavaScript identifier');
+  if (RESERVED_BINDINGS.has(rendered)) refuse(what, 'variable', rendered, 'is a reserved word');
+  return rendered;
+}
+
+/** A generated bare object key. Reserved words are legal keys, so a column named `class` renders. */
+export function safeKey(rendered: string, what: string): string {
+  if (!IDENTIFIER_NAME.test(rendered)) refuse(what, 'object key', rendered, 'is not a JavaScript identifier');
+  refuseProtoKey(rendered, what);
+  return rendered;
+}
+
+/**
+ * `__proto__` written as a key in an object literal, bare or quoted, SETS the object's
+ * prototype instead of adding the entry, so the entry silently vanishes. Every other name
+ * (`constructor`, `prototype`) is an ordinary key in a literal. Used by the renderers that
+ * quote a non-identifier key, too: quoting does not change this.
+ */
+export function refuseProtoKey(rendered: string, what: string): void {
+  if (rendered === '__proto__') refuse(what, 'object key', rendered, 'sets the object prototype instead of adding the entry');
+}
+
+/** A generated file name without its extension, also used as an import specifier. */
+export function safeFileStem(rendered: string, what: string): string {
+  if (!FILE_STEM.test(rendered)) {
+    refuse(what, 'file name', rendered, 'is not a safe file name (letters, digits, _, $ and - only: no path separator, no dot)');
+  }
+  return rendered;
+}
+
+/**
+ * The path a generated file is written to, refused unless it resolves inside `dir`. The file
+ * names are already safe stems; this is the second wall at the write itself, so no future
+ * renderer can write outside the directory the operator named.
+ */
+export function containedPath(dir: string, file: string): string {
+  const root = path.resolve(dir);
+  const target = path.resolve(root, file);
+  if (path.dirname(target) !== root) {
+    throw new UnsafeGeneratedNameError(
+      `db:pull refuses to write ${JSON.stringify(file)}: it resolves to ${target}, outside ${root}. Nothing was written.`,
+    );
+  }
+  return target;
+}