@everystack/cli 0.4.57 → 0.4.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.57",
+  "version": "0.4.58",
   "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,12 @@ export async function executeReconcile(
   // renderEnsureObjectSchemas.
   const ensureSchemas = renderEnsureObjectSchemas(parsed.objects);
 
+  // Which phase we are in when something throws. A bookkeeping failure inside the atomic path
+  // rolls the DDL back too, 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".
+  let phase: 'ddl' | '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 +236,30 @@ 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 = 'bookkeeping';
     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]));
 
     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:191 skips on
+    // `prov.kind === 'sql'` but not `src.kind`) gets its freshly recorded row deleted by the guard,
+    // orphaning its provenance for good. Migrating first is what prevents that.
+    // NOT YET PINNED BY A TEST — reverting this reorder leaves the whole suite green. See
+    // issue:db-reconcile-provenance-migrate-is-the-one-unguarded-write-a (G4).
+    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 +278,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',
@@ -287,12 +311,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,8 +329,12 @@ 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 half died. A bookkeeping 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.
  */
-export function explainReconcileError(err: unknown): Error {
+export function explainReconcileError(err: unknown, phase: 'ddl' | 'bookkeeping' = 'ddl', atomic = true): Error {
   const msg = String((err as any)?.message ?? err);
   if (/pg_type_typname_nsp_index|pg_class_relname_nsp_index|already exists/i.test(msg)) {
     return new Error(
@@ -314,6 +344,22 @@ export function explainReconcileError(err: unknown): Error {
       + `it as drift, re-run with --overwrite-drift.`,
     );
   }
+  if (phase === 'bookkeeping') {
+    return new Error(
+      `${msg}\n\nThis failed AFTER the DDL, not in it. The failure came from the post-apply catalog re-read `
+      + `or from the provenance/schema_log write that records what was built`
+      + (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;`,
+    );
+  }
   return err instanceof Error ? err : new Error(msg);
 }
 

package/src/cli/derived-apply.ts

@@ -497,9 +497,30 @@ 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 — verified against PostgreSQL 16. */
 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 {