@everystack/cli 0.4.57 → 0.4.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.57",
+  "version": "0.4.59",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/commands/db-reconcile.ts

@@ -194,6 +194,20 @@ export async function executeReconcile(
   // renderEnsureObjectSchemas.
   const ensureSchemas = renderEnsureObjectSchemas(parsed.objects);
 
+  // Which phase we are in when something throws. Anything after the DDL rolls the DDL back with
+  // it inside the atomic path, so the operator sees no plan output and no applied statements —
+  // indistinguishable from a batch that never started, and the wrong thing to go debugging.
+  // The phase is the difference between "your DDL is bad" and "your DDL was fine".
+  //
+  // THREE phases, not two, because the post-apply work has two halves that fail for different
+  // reasons and are fixed differently. `verify` is everything between the DDL and the write: the
+  // catalog re-read, and the checks that stand between it and recording (a recorded identity with
+  // no source object, an object the catalog cannot see afterwards, a backend pid that moved). The
+  // DDL ran and NO bookkeeping was ever attempted. `bookkeeping` is the single provenance +
+  // schema_log write, plus the COMMIT that seals it. Reporting a re-read failure as `bookkeeping`
+  // sent the operator looking at a write that never happened.
+  let phase: 'ddl' | 'verify' | 'bookkeeping' = 'ddl';
+
   if (atomic) await runner('BEGIN');
   try {
     // The session guard: postgres-js `max: 1` is a pool of one, not a session lease — a
@@ -230,11 +244,67 @@ export async function executeReconcile(
     // the canonical search_path inside a savepoint it always rolls back, so the def hashes are
     // stable regardless of the create-time wide path above — and that wide path survives the read.
     // The unwrapped path has no transaction to borrow, so it takes a session of its own.
+    phase = 'verify';
     const after = await introspectDerived(atomic ? borrowedSessionRunner(runner) : session);
     const liveById = new Map(after.objects.map((o) => [o.identity, o]));
     const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
 
+    // THE ORPHAN CHECK — an outcome assertion, not a plan-shape one. Every identity whose
+    // provenance we are about to DELETE must be gone from the database. The read above is the
+    // real post-DDL catalog, so this asks the only question that matters: after this batch, is
+    // there a live object whose bookkeeping we are about to throw away?
+    //
+    // A live object with no provenance row reads as `unmanaged` — "not in source, never touched"
+    // — so it is never dropped, keeps its grants, and `--check` stays green. Nothing downstream
+    // can tell that state apart from an object that was genuinely never ours, which is why this
+    // has to be caught at the moment the row is lost rather than found afterwards.
+    //
+    // Reachable, and the mechanism is a search_path disagreement, NOT a declared spelling (drop
+    // identities come from the live catalog, never from the declaration). Introspection pins
+    // `search_path = public`, so a public-schema type renders BARE inside a function identity;
+    // the DDL batch omits its own SET when every declared schema is public; and under an ambient
+    // `ALTER DATABASE … SET search_path = app` the rendered `DROP FUNCTION IF EXISTS
+    // public.f(my_enum)` cannot resolve `my_enum`. PostgreSQL answers `NOTICE: type "my_enum"
+    // does not exist, skipping` and drops nothing. IF EXISTS makes that silent.
+    //
+    // A `defineSql` object never trips this — not because it is catalog-invisible (a defineSql
+    // function or procedure is perfectly visible) but because its identity is `schema.name`
+    // while the catalog reports `schema.name(argtypes)`, so the two never join.
+    const orphaned = rendered.remove.filter((identity) => liveById.has(identity));
+    if (orphaned.length > 0) {
+      throw new Error(
+        `refusing to drop provenance for ${orphaned.map((i) => `${i} (${liveById.get(i)!.kind})`).join(', ')}: `
+        + `the object is STILL LIVE after the batch, so its DROP did not remove it. DROP ... IF EXISTS is `
+        + `silent when a name in the target cannot be resolved — check the database's search_path `
+        + `(SHOW search_path; ALTER DATABASE ... SET search_path) against the identity above. Deleting the `
+        + `row anyway would leave the object running with its grants, reported as "unmanaged", and never `
+        + `dropped again.\n\nNo provenance was written. There is no automated recovery for this state yet — `
+        + `the generic guidance below names --baseline and --rebuild, and NEITHER applies here: both act on `
+        + `objects the source still declares, and this one is absent from source. Drop the object by hand `
+        + `once its name resolves, then re-run.`,
+      );
+    }
+
     const bookkeeping: string[] = [];
+    // ORDER MATTERS: migrate, then record, then remove. This ordering is LOAD-BEARING — it is the
+    // fix, not the belt. `renderProvenanceMigrate`'s own guard is the belt (see its docstring).
+    //
+    // A migrate re-keys an EXISTING row (legacy identity → the signature the catalog now reports).
+    // The planner emits it only when the target identity is free — but it reads provenance as it
+    // stood at PLAN time, and this batch is about to write it. The same object routinely does both:
+    // a row old enough to be legacy-keyed is also old enough to predate body_hash, which makes it a
+    // `backfill`, which records. Record first and the upsert INSERTs the very identity the migrate
+    // then tries to UPDATE onto — duplicate key on the primary key, the whole batch rolled back.
+    // Migrating first leaves the row already keyed by its new identity, so the upsert updates it.
+    //
+    // The guard alone would NOT be enough. Under record-first it makes one case actively worse: a
+    // source 'sql'-kind object sharing a legacy function identity (derived-plan.ts skips on
+    // `prov.kind === 'sql'` but not `src.kind` — deliberately, see the DELIBERATELY NOT SKIPPED
+    // note there) gets its freshly recorded row deleted by the guard, orphaning its provenance for
+    // good. Migrating first is what prevents that.
+    // PINNED BY __tests__/integration/provenance-migrate.test.ts — that scenario is the only one
+    // where the two orders diverge, and it is the ONLY test that reverting this reorder turns red.
+    for (const m of rendered.migrate) bookkeeping.push(renderProvenanceMigrate(m.from, m.to));
     for (const identity of rendered.record) {
       const src = srcById.get(identity);
       if (!src) {
@@ -253,7 +323,6 @@ export async function executeReconcile(
       const dropSql = src.kind === 'trigger' && src.table ? triggerDropSql(src.name, src.table) : undefined;
       bookkeeping.push(renderProvenanceUpsert(identity, src.hash, liveObj.defHash, src.kind, dropSql, src.bodyHash));
     }
-    for (const m of rendered.migrate) bookkeeping.push(renderProvenanceMigrate(m.from, m.to));
     for (const identity of rendered.remove) bookkeeping.push(renderProvenanceDelete(identity));
     bookkeeping.push(renderSchemaLogInsert({
       kind: 'compute reconcile',
@@ -275,6 +344,9 @@ export async function executeReconcile(
         );
       }
     }
+    // Everything after the DDL has so far only read and rendered. From here the phase is the
+    // bookkeeping write itself, and the COMMIT that seals it.
+    phase = 'bookkeeping';
     await runner(bookkeeping.join(';\n'));
 
     if (atomic) await runner('COMMIT');
@@ -287,12 +359,14 @@ export async function executeReconcile(
     try {
       await runner(renderSchemaLogInsert({
         kind: 'compute reconcile', sql: rendered.statements.join(';\n'),
-        outcome: `failed: ${String(err?.message ?? err).slice(0, 500)}`,
+        // The `failed: ` prefix is the repo-wide convention (state-apply records the same shape)
+        // and `outcome LIKE 'failed:%'` is what operators query — the phase rides inside it.
+        outcome: `failed: [${phase}] ${String(err?.message ?? err).slice(0, 500)}`,
         actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
         durationMs: now() - started,
       }));
     } catch { /* the memoir is best-effort on failure */ }
-    throw explainReconcileError(err);
+    throw explainReconcileError(err, phase, atomic);
   }
 
   return { plan, applied: true, statements: rendered.statements, ...(ownerMode ? { ownerMode } : {}) };
@@ -303,9 +377,49 @@ export async function executeReconcile(
  * and reality disagree — a partial earlier run, a hand-created object — Postgres answers with a
  * cryptic unique-violation on `pg_type`/`pg_class` instead of anything actionable. Turn that into
  * a message that tells the operator what to do.
+ *
+ * `phase` says WHICH part died. A post-DDL failure rolls the DDL back with it, so the operator's
+ * only evidence is an absence — no plan output, nothing applied — which reads as a batch that never
+ * started. Say plainly that the DDL was fine, or the next person debugs the wrong half. `verify` and
+ * `bookkeeping` are named apart because they fail for different reasons: the first is the catalog
+ * re-read and the checks that stand between it and recording, the second is the provenance/schema_log
+ * write and its COMMIT.
  */
-export function explainReconcileError(err: unknown): Error {
+export function explainReconcileError(err: unknown, phase: 'ddl' | 'verify' | 'bookkeeping' = 'ddl', atomic = true): Error {
   const msg = String((err as any)?.message ?? err);
+  // PHASE FIRST — the order is load-bearing. The name-collision advice below tells the operator to
+  // DROP … CASCADE, which is destructive and simply wrong for a failure that happened after the DDL
+  // (there, the create already succeeded).
+  //
+  // No post-DDL error reaches that text TODAY, and the reason is what to re-check before trusting
+  // this: neither post-DDL phase runs a CREATE. `verify` is SELECTs plus in-process throws;
+  // `bookkeeping` is INSERT/UPDATE/DELETE on two everystack tables. Nothing there can raise 42P07
+  // or 42710. (`already exists` IS a primary message for 42P07 — the regex would match it fine.)
+  // So the ordering is insurance. It stops being insurance the moment a phase gains a CREATE —
+  // moving ENSURE_RECONCILER_SQL, with its CREATE … IF NOT EXISTS, inside the try would do it.
+  if (phase === 'verify' || phase === 'bookkeeping') {
+    return new Error(
+      `${msg}\n\nThis failed AFTER the DDL, not in it. `
+      + (phase === 'verify'
+        ? `The failure came from the verify half: the post-apply catalog re-read, or one of the checks `
+          + `over it — a recorded identity with no source object, an object the catalog cannot see `
+          + `afterwards, or a backend pid that moved. No provenance and no 'applied' schema_log row `
+          + `was written; the bookkeeping write is never reached`
+        : `The failure came from the bookkeeping write that records what was built — the provenance and `
+          + `schema_log statements, or the COMMIT that seals them. The post-apply catalog re-read `
+          + `succeeded, so every recorded object was introspectable when it ran`)
+      + (atomic
+        ? `. That work shares the DDL's transaction, so the transaction rolled EVERYTHING back and nothing is `
+          + `applied — the database is exactly as it was. Resolve the cause and re-run.`
+        : `. This batch could not run in a transaction (CONCURRENTLY/VACUUM), so the DDL IS applied and its `
+          + `provenance is NOT — and a plain re-run will not record it. Objects that are live with no provenance `
+          + `read as first contact, so the next plan reports them under "needs baseline" and applies nothing. `
+          + `Recover with --baseline to adopt them as-is (it records trust WITHOUT verifying live matches source), `
+          + `or with --rebuild to recreate them from source and record honestly.`)
+      + `\n\nThe failed attempt is recorded: SELECT applied_at, outcome FROM everystack.schema_log `
+      + `WHERE outcome LIKE 'failed%' ORDER BY applied_at DESC LIMIT 3;`,
+    );
+  }
   if (/pg_type_typname_nsp_index|pg_class_relname_nsp_index|already exists/i.test(msg)) {
     return new Error(
       `${msg}\n\nreconcile tried to CREATE a derived object whose name already exists — usually a partial `
@@ -339,6 +453,15 @@ export function buildReconcileReport(plan: ReconcilePlan): string[] {
     const cost = a.bytes !== undefined ? `; ${formatBytes(a.bytes)}${a.rows ? `, ~${a.rows} rows` : ''}` : '';
     lines.push(`${VERB_GLYPH[a.action] ?? '?'} ${a.action} ${a.identity} (${a.reason}${cost})`);
   }
+  // Pending identity migrations. Bookkeeping only — no DDL, no object changed — but they ARE a
+  // write, and they were invisible here while also being excluded from `checkFails`. Silence in
+  // both places is how a re-key nobody asked about becomes a surprise.
+  for (const m of plan.migrations) {
+    lines.push(
+      `⇢ re-key ${m.from} → ${m.to} (provenance only — the identity spelling this cli reports; `
+      + `pending until --apply, and it does NOT fail --check)`,
+    );
+  }
   const rebuilt = plan.actions.filter((a) => (a.action === 'create' || a.action === 'refresh') && a.bytes !== undefined);
   if (plan.totalRebuildBytes > 0) {
     lines.push(`estimated rebuild: ${formatBytes(plan.totalRebuildBytes)} across ${rebuilt.length} matview(s)`);
@@ -370,7 +493,16 @@ export function buildReconcileReport(plan: ReconcilePlan): string[] {
  *  Baseline and rebaseline are explicit adoption the operator asked for, not findings; a
  *  backfill is record-only bookkeeping (body_hash arming) — neither is a CI failure. An
  *  UNAPPLIED authz-only grant change still fails here via `regrants` below (the real signal);
- *  an empty regrant delta means live already matches declared, so green is correct. */
+ *  an empty regrant delta means live already matches declared, so green is correct.
+ *
+ *  `plan.migrations` is DELIBERATELY not here, for the backfill's reason. An identity migration
+ *  re-keys a provenance row a cli upgrade under-keyed; it emits no DDL, changes no object, and
+ *  converges in one apply. Failing on it would turn CI red for every consumer on the release that
+ *  introduces the new identity spelling, and the only fix on offer would be "run apply" — a gate
+ *  whose remedy is the thing the gate is supposed to be checking for. The live layer still matches
+ *  the declared source, which is what `--check` asserts. Decided 2026-08-12; reversible by adding
+ *  one clause. Green here is only defensible because the plan report PRINTS every pending
+ *  migration (see buildReconcileReport) — silent in both places would be a write nobody can see. */
 export function checkFails(plan: ReconcilePlan): boolean {
   return plan.actions.some((a) => a.action !== 'baseline' && a.action !== 'rebaseline' && a.action !== 'backfill')
     || plan.drift.length > 0

package/src/cli/commands/db-sync.ts

@@ -88,8 +88,9 @@ export interface SyncOptions {
 }
 
 export interface SyncHooks {
-  /** Fires after the state diff is computed, BEFORE anything executes — the review seam. */
-  onStatePlan?: (statements: string[], classified: ClassifiedStatements) => void;
+  /** Fires after the state diff is computed, BEFORE anything executes — the review seam.
+   *  `pass` is 1, or 2 on the settling pass (see {@link executeSync}). */
+  onStatePlan?: (statements: string[], classified: ClassifiedStatements, pass: number) => void;
   /** Fires after the state layer applied and verified, before the compute reconcile. */
   onStateDone?: (state: StateSyncOutcome) => void;
 }
@@ -114,12 +115,13 @@ export interface SyncRun {
  * compute, then the verdict. Pure orchestration over an injected QueryRunner;
  * the CLI shell below owns flags, files, and exits.
  */
-export async function executeSync(
+async function syncOnce(
   runner: QueryRunner,
   session: SessionRunner,
   models: ModelDescriptor[],
-  options: SyncOptions = {},
-  hooks: SyncHooks = {},
+  options: SyncOptions,
+  hooks: SyncHooks,
+  pass: number,
 ): Promise<SyncRun> {
   const current = await introspectSchema(session);
   const liveAuthz = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
@@ -127,7 +129,7 @@ export async function executeSync(
     allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
     governedRoles: options.governedRoles, extensions: options.extensions,
   });
-  hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
+  hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements), pass);
 
   const state = await applyStateAndVerify(runner, session, models, statements, current, liveAuthz, {
     allowDrops: options.allowDrops, sequences: options.sequences, extensions: options.extensions,
@@ -167,6 +169,92 @@ export async function executeSync(
   };
 }
 
+/**
+ * A sync that SETTLES — at most one extra pass, and the reason it is needed is inherent to
+ * creating things rather than a patch over one bug.
+ *
+ * `syncOnce` is a single diff-and-verify: it reads the live authz contract, computes the delta,
+ * applies it. On a FROM-SCRATCH run some objects the authz layer must grant on do not exist at
+ * read time — most sharply the sequence behind a serial column, which our own CREATE TABLE makes
+ * moments later. The first pass cannot see it, the sequence inheritance rule (A6) has nothing to
+ * grant on, and the run ends with a role that may INSERT into a table but cannot draw its
+ * sequence value. Measured on a consumer's 251-model schema: pass one reported `MATCH` and
+ * `NOT converged` in the same breath, and pass two applied 205 statements, nearly all of them
+ * `GRANT … ON SEQUENCE`.
+ *
+ * `buildIntoDatabase` has carried this second pass since A12, so `db:build`, `db:check`'s
+ * compose ring and `db:template:refresh` always settled. The `db:sync` VERB did not — it ran
+ * once and told the operator to run it again. That put "run db:sync twice" in a consumer's
+ * runbook as folklore, and its exit 1 aborted their documented one-verb from-scratch path
+ * before any data loaded. The retry belongs HERE, where every caller gets it and none has to
+ * know.
+ *
+ * Bounded at exactly one extra pass. The second read sees everything the first one created, so
+ * a third could only differ if the apply were non-convergent — and that is a real failure the
+ * `converged` bar must report, never something to loop away.
+ *
+ * An already-synced database converges on pass one and never pays for the second read.
+ */
+export async function executeSync(
+  runner: QueryRunner,
+  session: SessionRunner,
+  models: ModelDescriptor[],
+  options: SyncOptions = {},
+  hooks: SyncHooks = {},
+): Promise<SyncRun> {
+  const first = await syncOnce(runner, session, models, options, hooks, 1);
+  // The trigger is the STATE bar, not the combined verdict. The cause above is state-layer
+  // only, so a compute refusal or an unadopted object cannot be settled by looking again —
+  // retrying on those would make every brownfield sync pay a second full read (and print its
+  // refusal twice) to reach the same answer.
+  if (first.stateConverged) return first;
+  const second = await syncOnce(runner, session, models, options, hooks, 2);
+  return {
+    ...second,
+    state: mergeStateOutcomes(first.state, second.state),
+    // Report the reconcile that DID the work. The settling pass re-reads the derived layer the
+    // first pass created and correctly finds it managed and unchanged — reporting THAT as the
+    // outcome tells the operator "N up to date" about objects this very command just created,
+    // and hands `--json` a `compute.applied: false` for a successful build. Findings are not
+    // lost either way: a refusal, drift and needsBaseline are recomputed from live state on
+    // every pass, so the second run reports them again.
+    compute: first.compute?.applied && !second.compute?.applied ? first.compute : second.compute,
+  };
+}
+
+/**
+ * Two passes, reported as the one operation the operator ran.
+ *
+ * The split is WORK DONE versus WORK PENDING, and each field belongs to one of them.
+ *
+ * Work done accumulates: `executable` is what actually ran, in the order it ran, and
+ * `fromFingerprint` is where the database ACTUALLY started — take the settling pass's and the
+ * record reads as though the first pass never happened.
+ *
+ * Work pending is whatever is STILL pending at the end, so it comes from the second pass alone.
+ * `heldDrops` and `notices` are regenerated from live state on every pass and are never
+ * executed, so concatenating them counts the same held `DROP TABLE` twice — and a destructive
+ * change reported at 2x is the wrong direction to be wrong in.
+ */
+function mergeStateOutcomes(first: StateSyncOutcome, second: StateSyncOutcome): StateSyncOutcome {
+  return {
+    // `remaining`, `toFingerprint`, `after` and the pending buckets all come from the second
+    // pass through this spread — the END state is the bar.
+    ...second,
+    statements: [...first.statements, ...second.statements],
+    classified: {
+      executable: [...first.classified.executable, ...second.classified.executable],
+      heldDrops: second.classified.heldDrops,
+      notices: second.classified.notices,
+    },
+    applied: first.applied || second.applied,
+    fromFingerprint: first.fromFingerprint,
+    // Two passes that both ran DDL wrote TWO schema_log rows, correctly chained (A→B, B→C).
+    // This carries the later one; `schema_log` itself is the record of the pair, not this field.
+    logId: second.logId ?? first.logId,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Report rendering (pure).
 // ---------------------------------------------------------------------------
@@ -327,9 +415,16 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
         gitRef: currentGitRef(),
       },
       {
-        onStatePlan: (statements, classified) => {
+        onStatePlan: (statements, classified, pass) => {
           if (classified.executable.length > 0) {
-            info(`state plan — ${classified.executable.length} statement(s):`);
+            // The settling pass is named, not hidden — an operator who sees a second plan with
+            // no explanation reads it as the sync failing. It says WHAT it is, never why: on a
+            // fresh database this is the grants for sequences the first pass created, but a
+            // genuinely non-convergent apply lands here too, and labelling that as routine
+            // settling would explain away the one failure this pass exists to surface.
+            info(pass > 1
+              ? `settling pass — ${classified.executable.length} statement(s) still differing after the first pass:`
+              : `state plan — ${classified.executable.length} statement(s):`);
             const { drops, narrowings } = classifyDestructive(classified.executable);
             if (drops.length + narrowings.length > 0) {
               warn(`${drops.length + narrowings.length} DESTRUCTIVE — ${drops.length} drop(s), ${narrowings.length} narrowing type change(s). Dev sync runs them; protected stages gate them (db:plan → db:apply).`);

package/src/cli/db-build.ts

@@ -168,7 +168,17 @@ export async function buildIntoDatabase(
     //
     // Provenance is recorded by this pass, so executeSync's own reconcile below sees the
     // functions already managed and unchanged, and plans nothing for them.
-    const declaredFunctions = (options.declared ?? []).filter((o) => o.kind === 'function');
+    // …and only the functions that CAN go first. A function's return and argument types are
+    // resolved by PostgreSQL when the function is created, and `check_function_bodies` does not
+    // reach them — it relaxes the BODY, which is why a body reading a not-yet-created table is
+    // fine here and `RETURNS SETOF stats_view.x_row` is not. A function whose SIGNATURE names a
+    // relation the declared state has not built yet stays behind and is created by the sync
+    // pass below, after state, in the compiler's dependency order. Measured on a consumer's
+    // declared state: 20 such pairs, `type "…_row" does not exist`, from-scratch only. Their
+    // explicit `dependsOn` could not have helped — this pass dropped the view from the wave, so
+    // no edge could order it back in.
+    const declaredFunctions = (options.declared ?? [])
+      .filter((o) => o.kind === 'function' && !o.signatureDeps?.length);
     if (declaredFunctions.length > 0) {
       await runner('SET check_function_bodies = off');
       try {
@@ -183,34 +193,16 @@ export async function buildIntoDatabase(
         await runner('RESET check_function_bodies');
       }
     }
-    let run = await executeSync(runner, session, models, {
+    // A12's second pass used to live HERE, and that is exactly why `db:sync` never settled: the
+    // from-scratch build got it and the verb an operator runs did not. `executeSync` owns it now
+    // (see its own comment for the sequence-behind-a-serial-column cause), so every caller
+    // settles and none has to know.
+    const run = await executeSync(runner, session, models, {
       declared: options.declared,
       sequences: options.sequences,
       actor: options.actor ?? 'db-build',
       gitRef: options.gitRef ?? null,
     });
-    // A12 — THE SECOND PASS, and it is inherent to building from nothing rather than a patch
-    // over one bug. `executeSync` is a single diff-and-verify: it reads the live authz contract,
-    // computes the delta, applies it. On a FROM-SCRATCH build some objects the authz layer must
-    // grant on do not exist at read time — most sharply the sequence behind a serial column,
-    // which our own CREATE TABLE makes moments later. So the first pass cannot see it, the
-    // sequence inheritance rule (A6) has nothing to grant on, and the build lands with a role
-    // that may INSERT into a table but cannot draw its sequence value.
-    //
-    // Caught by the round-trip oracle (B7), not by A6's own tests: the rule converges perfectly
-    // against an EXISTING database, which is what those tests exercise.
-    //
-    // Bounded at exactly one extra pass. The second read sees everything the first one created,
-    // so a third could only differ if the apply were non-convergent — and that is a real failure
-    // the `converged` bar must report, never something to loop away.
-    if (!run.converged) {
-      run = await executeSync(runner, session, models, {
-        declared: options.declared,
-        sequences: options.sequences,
-        actor: options.actor ?? 'db-build',
-        gitRef: options.gitRef ?? null,
-      });
-    }
     return {
       converged: run.converged,
       fingerprintMatch: run.fingerprintMatch,

package/src/cli/derived-apply.ts

@@ -487,6 +487,14 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[],
   // REVOKE/GRANT — no provenance to record (ACLs are not in any hash).
   for (const r of plan.regrants) statements.push(...r.statements);
 
+  // NOTE — a `remove` entry that is also a migration's TARGET is CORRECT, not a contradiction.
+  // A legacy-keyed function the source has removed migrates onto its signature identity and is
+  // then dropped through it: re-key, drop the object, delete the row. That is the documented path
+  // (the pre-pass reads the LIVE catalog precisely so a removed function drops instead of reading
+  // as unmanaged) and it converges. A guard here refusing that overlap was tried and reverted —
+  // it turned a right answer into a failed apply, and on `db:sync` it threw after the state layer
+  // had already committed. Pinned by "a removed legacy function renders as migrate-then-remove"
+  // in __tests__/cli/derived-apply.test.ts.
   return { statements, record, remove, migrate: [...plan.migrations] };
 }
 
@@ -497,9 +505,40 @@ ON CONFLICT (identity) DO UPDATE SET src_hash = EXCLUDED.src_hash, def_hash = EX
 }
 
 /** A table rename carried its triggers along — same object, new identity; the provenance
- *  row migrates instead of the object drop+create-ing. */
+ *  row migrates instead of the object drop+create-ing. Also re-keys a legacy function row onto
+ *  the signature identity the catalog reports.
+ *
+ *  `identity` is the PRIMARY KEY, so this UPDATE has no `ON CONFLICT` to fall back on: landing on
+ *  an occupied identity aborts the batch. The planner will not emit a migration onto a row it can
+ *  see, and the caller migrates before it records — but neither is a guarantee the statement
+ *  itself carries, so it carries one. Both rows describe the SAME object; the target is the one
+ *  every later run reads and the one this batch's own upsert is about to refresh from the live
+ *  catalog. So the legacy row yields: delete it, keep the target.
+ *
+ *  This guard is the BELT, not the fix. It defends the case ordering cannot reach — a target
+ *  identity already occupied by a pre-existing row — and it makes the migrate idempotent. The fix
+ *  for the reported blocker is the caller's migrate-before-record ordering; do not remove that on
+ *  the strength of this guard, which under record-first would orphan a 'sql'-kind object's
+ *  provenance. See the ORDER MATTERS comment in db-reconcile.ts.
+ *
+ *  Both branches are mutually exclusive under one snapshot, and an unreferenced data-modifying CTE
+ *  still executes exactly once. All three branches (target free / target occupied / nothing to
+ *  migrate) run against a real database in __tests__/integration/provenance-migrate.test.ts.
+ *
+ *  A KIND GUARD WAS TRIED HERE AND REVERTED. It refused the DELETE when the two rows' kinds
+ *  differed, on the theory that a `defineSql` domain and a function can share a name and the
+ *  DELETE would then orphan one of them. The occupied-target branch IS reachable — the ops-Lambda
+ *  apply takes no mutation lease, so a second writer can occupy the target between plan and
+ *  statement — but in that reachable state the two rows are the SAME object: a pre-`kind`-column
+ *  legacy row (kind NULL) and the row the other apply just wrote. Measured on PostgreSQL 16: the
+ *  guard aborted the apply and left two rows, where this statement converges to one. It was
+ *  negative value on precisely the upgrade path it would have shipped to. */
 export function renderProvenanceMigrate(from: string, to: string): string {
-  return `UPDATE everystack.derived_provenance SET identity = ${escapeLiteral(to)} WHERE identity = ${escapeLiteral(from)}`;
+  const fromLit = escapeLiteral(from);
+  const toLit = escapeLiteral(to);
+  return `WITH occupied AS (SELECT 1 FROM everystack.derived_provenance WHERE identity = ${toLit}),
+superseded AS (DELETE FROM everystack.derived_provenance WHERE identity = ${fromLit} AND EXISTS (SELECT 1 FROM occupied))
+UPDATE everystack.derived_provenance SET identity = ${toLit} WHERE identity = ${fromLit} AND NOT EXISTS (SELECT 1 FROM occupied)`;
 }
 
 export function renderProvenanceDelete(identity: string): string {

package/src/cli/derived-compile.ts

@@ -377,6 +377,57 @@ export function compileDerived(models: readonly ModelDescriptor[], derived: read
   const declaredIdentities = (refs: readonly DependsOnRef[]): string[] =>
     [...new Set(refs.map((r) => ('table' in r ? `${r.schema}.${r.table}` : derivedIdentity(r))))].sort();
 
+  // Every RELATION the declared state creates — the tables, views and matviews a function's
+  // signature could name. A function's return and argument types are resolved by PostgreSQL
+  // when the function is created, so `db:build`'s functions-ahead-of-state pass has to know
+  // which functions cannot go first. See SourceObject.signatureDeps.
+  const relationIdentity = (ref: SetofReturn['setof']): string =>
+    'table' in ref ? `${ref.schema}.${ref.table}` : derivedIdentity(ref);
+  const relationIdentities = new Map<string, string>(
+    [
+      ...models.map((m) => `${m.schema}.${m.table}`),
+      ...derived
+        .filter((d) => d.kind === 'view' || d.kind === 'materialized view')
+        .map((d) => derivedIdentity(d)),
+    ].map((id) => [id.toLowerCase(), id]),
+  );
+
+  /**
+   * A type name as written in a signature → the relation identity it names, if it names one.
+   *
+   * The quotes come off, and that is not cosmetic: `db:pull` writes the return type as
+   * `pg_get_function_result` spells it, and PostgreSQL quotes any identifier that needs it
+   * (mixed case, a reserved word, anything non-word). A pulled `SETOF "Stats_View"."x_row"`
+   * that read as no relation at all would go back into the ahead-of-state wave and fail exactly
+   * as before, silently.
+   */
+  const relationNamed = (type: string): string | null => {
+    const bare = type
+      .trim().replace(/^setof\s+/i, '').replace(/(\s*\[\s*\])+$/, '')
+      .split('.').map((part) => part.trim().replace(/^"(.*)"$/s, '$1')).join('.');
+    if (!bare) return null;
+    // A quoted identifier is case-SENSITIVE and an unquoted one folds to lower — but the
+    // declared names this compares against are the plain lowercase ones the model accepts,
+    // so folding both sides is right here and a quoted mixed-case name simply matches nothing.
+    const key = bare.toLowerCase();
+    return relationIdentities.get(key.includes('.') ? key : `public.${key}`) ?? null;
+  };
+
+  const signatureDeps = (fn: FunctionDescriptor): string[] => {
+    const out = new Set<string>();
+    // `setof(ref)` is the typed spelling — the ref IS a relation descriptor, so it always counts.
+    if (typeof fn.returns !== 'string') out.add(relationIdentity(fn.returns.setof));
+    else {
+      const named = relationNamed(fn.returns);
+      if (named) out.add(named);
+    }
+    for (const a of fn.args) {
+      const named = relationNamed(a.type);
+      if (named) out.add(named);
+    }
+    return [...out].sort();
+  };
+
   for (const d of derived) {
     const identity = derivedIdentity(d);
     switch (d.kind) {
@@ -398,7 +449,14 @@ export function compileDerived(models: readonly ModelDescriptor[], derived: read
         // The pin rides STRUCTURALLY as well as inside `sql`, so the differ can compare it
         // against the live catalog directly instead of only against a recorded hash. It is not
         // in the hash (it is already inside `sql`), so carrying it moves nobody's fingerprint.
-        nodes.push({ identity, deps: [...depIdentities(d.dependsOn), ...setofDep], build: make('function', d.name, sql, attachments, { identity, ...(d.owner ? { owner: d.owner } : {}), ...(d.searchPath !== undefined ? { searchPath: d.searchPath } : {}) }) });
+        // The signature is an ORDERING edge as well as a record. `setofDep` covers the typed
+        // `setof(ref)` spelling only; a return or argument type written as a plain string is
+        // the shape `db:pull` renders, and it carries no `dependsOn` of its own — so without
+        // this the function and its view order by identity sort, and whether the build works
+        // comes down to which name happens to sort first.
+        const sigDeps = signatureDeps(d);
+        const sigEdges = sigDeps.filter((id) => identities.has(id));
+        nodes.push({ identity, deps: [...depIdentities(d.dependsOn), ...setofDep, ...sigEdges], build: make('function', d.name, sql, attachments, { identity, ...(sigDeps.length ? { signatureDeps: sigDeps } : {}), ...(d.owner ? { owner: d.owner } : {}), ...(d.searchPath !== undefined ? { searchPath: d.searchPath } : {}) }) });
         break;
       }
       case 'sql': {

package/src/cli/derived-plan.ts

@@ -177,6 +177,18 @@ export function planReconcile(
   // two objects — those baseline honestly), a row a live NON-function already owns (a view
   // and a function can share `schema.name`), and a 'sql'-kind row (its identity is its
   // declared name, not a catalog signature).
+  //
+  // DELIBERATELY NOT SKIPPED: a legacy identity the SOURCE also claims with a different object —
+  // a `defineSql` domain named `pmo_label` alongside a function whose legacy identity is
+  // `public.pmo_label`. The kind read below is the PROVENANCE row's, never the source's, and that
+  // is the intent. Types and functions live in different PostgreSQL catalogs, so both objects are
+  // legal; the collision exists only while the function's row is under-keyed. Migrating is what
+  // VACATES the bare name for the object that legitimately owns it — the run converges in one
+  // apply and the next is a clean no-op (pinned by __tests__/integration/provenance-migrate.test.ts).
+  // Skipping instead would keep the collision and let the domain's upsert overwrite the function's
+  // row; refusing would block a state that is legal, self-healing, and ambiguous for exactly one
+  // apply. Adjudicated 2026-08-12 (issue G7). What this rests on is the caller's
+  // migrate-before-record ordering — see the ORDER MATTERS comment in db-reconcile.ts.
   const liveFnByLegacy = new Map<string, LiveObject[]>();
   for (const o of live.objects) {
     if (o.kind !== 'function') continue;

package/src/cli/derived-source.ts

@@ -96,6 +96,26 @@ export interface SourceObject {
    * "declared, then verified". Absent on kinds whose live edges pg_depend can't see.
    */
   declaredDeps?: string[];
+  /**
+   * kind 'function' only: the relations this function's SIGNATURE names — a `setof(ref)`
+   * return, or an argument/return type spelled as a declared table, view or matview.
+   *
+   * Distinct from `dependsOn`, and the distinction is load-bearing for the from-scratch build.
+   * A body reference is a FORWARD reference the build can defer (`check_function_bodies = off`
+   * is exactly that escape), so a function whose body reads a not-yet-created table still
+   * creates. A SIGNATURE reference is not deferrable: PostgreSQL resolves the return and
+   * argument types when the function is created, so `RETURNS SETOF stats_view.x_row` needs
+   * that view to exist already. `db:build` runs functions ahead of state (an RLS policy's
+   * predicate must resolve the function it calls) and uses this to hold back the ones that
+   * cannot go first; the compiler also orders the function after them.
+   *
+   * RELATIONS only — tables, views, matviews. A signature naming a declared ENUM, domain or
+   * composite type has the same problem and is NOT covered here, so it still fails in the
+   * ahead-of-state pass. Absent/empty means "names no declared relation", never "is safe".
+   *
+   * Not in the hash — it is derived from `sql`, so carrying it moves no fingerprint.
+   */
+  signatureDeps?: string[];
 }
 
 /** The provenance marker descriptor-compiled objects carry in `file` — the compiler