@everystack/cli 0.4.85 → 0.4.87

package/src/cli/schema-compile.ts

@@ -187,6 +187,12 @@ function refActions(spec: { onDelete?: string; onUpdate?: string }): { onDelete?
  * disagree. Single-column FKs come from each field's `.references()`; composite FKs come from
  * the table-level `foreignKey([...], () => Other, [...])` constraint. Both name themselves the
  * way drizzle does — `<table>_<cols>_<target>_<refcols>_fk` — so a brownfield FK round-trips.
+ *
+ * `validate: false` on either surface compiles to `notValid: true`. That is the DECLARED half of
+ * a field introspection also sets (see {@link ForeignKey.notValid}): the author is saying this
+ * key's permanent state is installed-and-unproven, so the differ must never emit a `VALIDATE`
+ * for it and the from-scratch build must land it `NOT VALID` — otherwise the declared state and
+ * the state a build of that declaration produces would be two different states.
  */
 export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
   const out: ForeignKey[] = [];
@@ -207,6 +213,7 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
       refTable: refTableName(target),
       refColumns: [targetPk],
       ...refActions(field.spec),
+      ...(field.spec.referencesValidate === false ? { notValid: true } : {}),
     });
   }
 
@@ -222,6 +229,7 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
       refTable: refTableName(target),
       refColumns: refCols,
       ...refActions(con),
+      ...(con.validate === false ? { notValid: true } : {}),
     });
   }
 
@@ -614,6 +622,10 @@ export { sequenceCreateSql } from './schema-diff';
  * are emitted *after* every `CREATE TABLE` (a FK's target table must already exist), so they
  * are separate from the table DDL — which is why FKs are not rendered inline by
  * compileCreateTable. Named the way drizzle names them: `<table>_<cols>_<target>_<refcols>_fk`.
+ *
+ * A key declared `validate: false` is rendered `… NOT VALID` here too. The declared state IS
+ * unproven-against-old-rows, so a migration artifact that installed it validated would build a
+ * database that does not match the models it was generated from.
  */
 export function foreignKeySql(model: ModelDescriptor): string[] {
   return modelForeignKeys(model).map((fk) => {
@@ -624,7 +636,8 @@ export function foreignKeySql(model: ModelDescriptor): string[] {
     // stays bare-but-quoted (`"uploads"`), preserving the proven output.
     return (
       `ALTER TABLE ${qualifiedTable(model)} ADD CONSTRAINT "${fk.name}" ` +
-      `FOREIGN KEY (${cols}) REFERENCES ${quoteParts(fk.refTable)}(${refCols})${refActionSql(fk)};`
+      `FOREIGN KEY (${cols}) REFERENCES ${quoteParts(fk.refTable)}(${refCols})${refActionSql(fk)}`
+      + `${fk.notValid ? ' NOT VALID' : ''};`
     );
   });
 }

package/src/cli/schema-diff.ts

@@ -29,6 +29,7 @@ import type {
   TableSchema,
   ColumnSchema,
   EnumType,
+  ForeignKey,
   IndexSchema,
   SequenceSchema,
 } from './schema-introspect';
@@ -42,9 +43,16 @@ export type ConstraintSpec =
   | { type: 'unique'; name: string; columns: string[] }
   | { type: 'check'; name: string; expr: string }
   | { type: 'foreignKey'; name: string; columns: string[]; refTable: string; refColumns: string[]; onDelete?: string; onUpdate?: string; nameDeclared?: boolean;
-      /** LIVE-SIDE ONLY: the key is installed but unchecked (see {@link ForeignKey.notValid}).
-       *  It is never part of {@link constraintContentKey} — a NOT VALID key IS the declared key,
-       *  one step short — and the emitter ignores it, because an ADD is always emitted NOT VALID. */
+      /**
+       * The key is installed but unchecked — on the LIVE side an observation, on the DESIRED
+       * side the author's `validate: false` (see {@link ForeignKey.notValid}).
+       *
+       * It is never part of {@link constraintContentKey}: a NOT VALID key IS the declared key,
+       * one step short, so validity can never make a key match a DIFFERENT key. What it decides
+       * is the SECOND statement — a desired `notValid` key emits `ADD … NOT VALID` alone, and a
+       * live `notValid` key is finished with a `VALIDATE` only when the desired side asked for
+       * one.
+       */
       notValid?: boolean };
 
 export type SchemaChange =
@@ -512,7 +520,7 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
         addConstraints.push({
           kind: 'addConstraint',
           table: d.table,
-          constraint: { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate },
+          constraint: { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate, ...(fk.notValid ? { notValid: true } : {}) },
         });
       }
       for (const ix of d.indexes) createIndexes.push(createIndexChange(d.table, ix));
@@ -817,10 +825,25 @@ function tableConstraintSpecs(t: TableSchema): ConstraintSpec[] {
  */
 function constraintContentKey(c: ConstraintSpec): string {
   if (c.type === 'unique') return `u|${c.columns.join(',')}`;
-  if (c.type === 'foreignKey') return `f|${c.columns.join(',')}|${c.refTable}|${c.refColumns.join(',')}|${c.onDelete ?? ''}|${c.onUpdate ?? ''}`;
+  if (c.type === 'foreignKey') return foreignKeyContentKey(c);
   return `c|${normalizeCheck(c.expr)}`; // checks take their own predicate-matched path (diffChecks)
 }
 
+/**
+ * A foreign key's content identity — columns, target, target columns, referential actions.
+ * VALIDITY IS NOT IN IT (see {@link ConstraintSpec}), and neither is the name.
+ *
+ * Exported because a second surface asks the same question: the plan's predicted endpoint has to
+ * find the live counterpart of a declared key to carry its validity through. Two spellings of
+ * "are these the same key" is how the differ and the prediction end up disagreeing about whether
+ * an edge changed anything.
+ */
+export function foreignKeyContentKey(
+  fk: Pick<ForeignKey, 'columns' | 'refTable' | 'refColumns' | 'onDelete' | 'onUpdate'>,
+): string {
+  return `f|${fk.columns.join(',')}|${fk.refTable}|${fk.refColumns.join(',')}|${fk.onDelete ?? ''}|${fk.onUpdate ?? ''}`;
+}
+
 /**
  * Diff CHECK constraints by their normalized predicate, not their name: a check with the
  * same predicate is the same check no matter what it's called, so a pulled check (whose DB
@@ -871,13 +894,22 @@ function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: Schema
         renames.push({ kind: 'renameConstraint', table: d.table, from: matched.name, to: des.name });
       }
       // The live key is there but was never checked against the rows already in the table —
-      // the state an interrupted two-step add leaves behind, and the state a hand-run
-      // `ADD CONSTRAINT … NOT VALID` leaves behind. The declared side is a VALIDATED key, so
-      // this is a real difference and the edge finishes it: VALIDATE alone, never a second
+      // what an interrupted two-step add leaves behind, and what a hand-run
+      // `ADD CONSTRAINT … NOT VALID` leaves behind. When the declared side is a VALIDATED key
+      // that is a real difference and the edge finishes it: VALIDATE alone, never a second
       // ADD (which would fail on the name that is already taken). Under the live name, which
       // may not be the declared one — a rename emitted just above lands FIRST, so the
       // validate must speak the name the constraint will have by then.
-      if (matched.type === 'foreignKey' && matched.notValid) {
+      //
+      // …UNLESS the declared side ASKED for NOT VALID (`validate: false`). Then live and
+      // declared agree and there is nothing to emit: validating would be the edge doing the
+      // one thing the author declared it must never do. Note the direction — a live key that
+      // is fully VALID under a `validate: false` declaration also falls through here with no
+      // statement, because `matched.notValid` is absent. That is the accept-either rule: there
+      // is no `ALTER TABLE … INVALIDATE CONSTRAINT`, so a key proven MORE than the model asked
+      // for is not a difference anyone could act on.
+      const desiredNotValid = des.type === 'foreignKey' && des.notValid === true;
+      if (matched.type === 'foreignKey' && matched.notValid && !desiredNotValid) {
         const name = des.type === 'foreignKey' && des.nameDeclared ? des.name : matched.name;
         addConstraints.push({ kind: 'validateConstraint', table: d.table, name });
       }
@@ -985,6 +1017,10 @@ export function validateConstraintSql(table: string, name: string): string {
  * commit), which is why the apply path runs every VALIDATE after the edge's batch commits — see
  * `splitValidations` in state-apply. The text is produced HERE for both `db:diff` (no database)
  * and `db:plan` (against a live one), so the two can never render the same edge differently.
+ *
+ * ONE statement again for a key the model declared `validate: false`: step 1 alone IS the whole
+ * declared state there, so step 2 is not deferred, it does not exist. See
+ * `FieldSpec.referencesValidate` for why a schema needs to be able to say that.
  */
 function addConstraintSql(table: string, c: ConstraintSpec): string[] {
   const head = `ALTER TABLE ${table} ADD CONSTRAINT ${quote(c.name)}`;
@@ -998,7 +1034,8 @@ function addConstraintSql(table: string, c: ConstraintSpec): string[] {
       let s = `${head} FOREIGN KEY (${colList(c.columns)}) REFERENCES ${refTable}(${colList(c.refColumns)})`;
       if (c.onDelete) s += ` ON DELETE ${c.onDelete.toUpperCase()}`;
       if (c.onUpdate) s += ` ON UPDATE ${c.onUpdate.toUpperCase()}`;
-      return [`${s} NOT VALID;`, validateConstraintSql(table, c.name)];
+      const add = `${s} NOT VALID;`;
+      return c.notValid === true ? [add] : [add, validateConstraintSql(table, c.name)];
     }
   }
 }

package/src/cli/schema-fingerprint.ts

@@ -155,6 +155,27 @@ import { fingerprintV12 } from './schema-fingerprint-v12';
 // re-baselined (db:reconcile --rebaseline) — no DDL, the fingerprint is a content address. The
 // v12 canon is frozen in schema-fingerprint-v12 and registered in RETAINED_CANONS so a schema_log
 // row recorded under it still descends.
+//
+// NO v14 FOR `validate: false` — worked out here so the next reader does not ask again.
+// The Model can now DECLARE a foreign key permanently NOT VALID (`references(…, { validate:
+// false })` → `ForeignKey.notValid` on the COMPILED side, which v13 said only introspection ever
+// set). A bump is required when the CANONICAL FORM changes — when the same database would hash
+// differently before and after. Neither half of that happens here:
+//
+//   1. The form is byte-identical. `canonicalTable` below already reads `f.notValid` and already
+//      writes it only when true. No key is added, removed, or normalized differently; the shape
+//      that hashes a live snapshot is untouched.
+//   2. Every hash anyone RECORDED is a live hash. `RETAINED_CANONS`/`fingerprintLiveAtVersion`
+//      recompute from a SchemaSnapshot read out of the database, and this feature does not change
+//      what introspection reports about any existing key. So every schema_log row still descends.
+//
+// What moves is the DECLARED hash of a model that newly writes `validate: false` — which is a
+// state change the author made on purpose, exactly like adding a column. That is the format
+// working, not the format changing. (Deliberately kept in step: the from-scratch build emits
+// `ADD … NOT VALID` for such a key too — schema-diff's `addConstraintSql` and schema-compile's
+// `foreignKeySql` — so building a database FROM that declaration lands on the declared hash
+// rather than one step past it. Without that half the declared side would hash a state no build
+// of it could produce, and `db:check` could never reach MATCH.)
 export const FINGERPRINT_VERSION = 13;
 
 // ---------------------------------------------------------------------------
@@ -198,6 +219,11 @@ function canonicalTable(table: TableSchema): Record<string, unknown> {
     // hashed identically to a validated one, so `db:fingerprint` reported MATCH on a database
     // whose data no constraint had ever been proved against. Written only when true, so every
     // fully-valid database keeps the hash it had.
+    //
+    // The flag now arrives from EITHER side — introspection's observation, or a Model's
+    // `validate: false` (see the FINGERPRINT_VERSION note above for why that needed no bump).
+    // The canonical form does not care which: one bit, one meaning — this key has never been
+    // checked against the rows that were already there.
     foreignKeys: byKey(
       table.foreignKeys.map((f) => ({
         columns: f.columns, refTable: f.refTable, refColumns: f.refColumns,

package/src/cli/schema-introspect.ts

@@ -53,14 +53,27 @@ export interface ForeignKey {
   onDelete?: string;
   onUpdate?: string;
   /**
-   * The constraint exists but has NOT been checked against the rows already in the table
-   * (`convalidated = false`; `pg_get_constraintdef` spells it `… NOT VALID`).
+   * The key is enforced on every new write but has NOT been checked against the rows already
+   * in the table (`convalidated = false`; `pg_get_constraintdef` spells it `… NOT VALID`).
    *
-   * LIVE-SIDE ONLY. A Model declares a foreign key, never a half-installed one, so the
-   * compiled side never sets this — which is exactly what makes it visible as drift: a live
-   * NOT VALID key is a DIFFERENT state from the declared (validated) one. It rides the
-   * canonical fingerprint form for the same reason, so a half-applied key can never report
-   * MATCH. Omitted (not `false`) when the constraint is validated, so every already-recorded
+   * BOTH SIDES SET THIS, and they mean two different things by it:
+   *
+   *   LIVE-OBSERVED      — introspection read `convalidated = false`. It says nothing about
+   *                        WHY: an interrupted two-step add, a hand-run `ADD … NOT VALID`, or
+   *                        a key someone deliberately left unproven years ago.
+   *   DECLARED-INTENTIONAL — the Model said `validate: false` on the reference, which is the
+   *                        author declaring "enforce forward, grandfather legacy" as the
+   *                        PERMANENT state of this key (see `FieldSpec.referencesValidate`).
+   *                        The differ then emits `ADD CONSTRAINT … NOT VALID` and NEVER the
+   *                        paired `VALIDATE`.
+   *
+   * HOW THE TWO MEET. A declared-intentional key is satisfied by EITHER a live NOT VALID key
+   * or a live FULLY-VALID one: PostgreSQL has no "un-validate", so "more proven than you asked
+   * for" is not a difference anybody can act on and must not read as drift. The asymmetry only
+   * runs the other way — a live NOT VALID key under a declaration that did NOT say
+   * `validate: false` IS a real difference, and the edge closes it with a `VALIDATE` alone.
+   *
+   * Omitted (not `false`) when the key is validated, on both sides, so every already-recorded
    * hash for a fully-valid database is untouched.
    */
   notValid?: boolean;

package/src/cli/security-audit.ts

@@ -248,18 +248,30 @@ export function classifySchema(schema: SchemaDescriptor, waivers: Waivers = {}):
 
   if (broad.length > 0) {
     const who = broad.join(', ');
+    // The fix is PER GRANTEE, and the grantees are PARTITIONED — never collapsed into one line.
+    //
+    // `db:provision --confirm` revokes exactly ONE thing: PUBLIC's CREATE on schema `public`
+    // (reviewably — it reports the gap without the flag). Every other (grantee, schema) pair is hand
+    // SQL. So the pointer stands in for PUBLIC's own revoke and for nothing else: a schema where BOTH
+    // PUBLIC and `authenticated` hold CREATE must still name the second revoke, or an operator runs
+    // the one command offered, re-audits, and is still writable with nothing saying why.
+    const isPublicPseudoRole = (g: string) => key === 'public' && g.toLowerCase() === 'public';
+    const fixes = broad.map((g) => (isPublicPseudoRole(g)
+      ? 'REVOKE CREATE ON SCHEMA public FROM PUBLIC — run `everystack db:provision --stage <stage> --confirm`, which does exactly this revoke and verifies it'
+      : `REVOKE CREATE ON SCHEMA ${key} FROM ${g}`));
+    const fix = `${fixes.join('. ')}.`;
     if (schema.unpinnedDefinerFunctions > 0) {
       reasons.push(
         `${who} can CREATE in schema "${key}", which holds ${schema.unpinnedDefinerFunctions} unpinned SECURITY DEFINER function(s) — `
         + `that is a complete search_path hijack chain: plant a shadow object, the unpinned function resolves through it and runs it with the owner's rights. `
-        + `REVOKE CREATE ON SCHEMA ${key} FROM ${who}, and pin those functions.`,
+        + `${fix.replace(/\.$/, '')}, and pin those functions.`,
       );
       severity = 'red';
     } else {
       reasons.push(
         `${who} can CREATE in schema "${key}" — the pre-PG15 default, which PG15 removed. No unpinned SECURITY DEFINER function is here, `
         + `but a writable schema on a search path threatens every privileged session that resolves through it, including the build credential `
-        + `running DDL. REVOKE CREATE ON SCHEMA ${key} FROM ${who}.`,
+        + `running DDL. ${fix}`,
       );
       severity = raise(severity, 'warn');
     }

package/src/cli/state-apply.ts

@@ -393,14 +393,31 @@ export interface StateApplyOptions {
    * run — with none there is no window between the commit and the record to protect.
    */
   readFingerprint?: () => Promise<string>;
+  /**
+   * `VALIDATE CONSTRAINT`s the caller REMOVED from `statements` before calling, because the row
+   * check it ran first already counted the offending rows (see fk-preflight's `withheldValidations`).
+   *
+   * They are pending validations that were never attempted, and they are recorded and reported
+   * exactly like ones that ran and failed — the key is installed, enforced forward and unproven
+   * either way, so giving the operator two vocabularies for one situation would only make them
+   * work out that it is the same situation. Running them instead would take a lock and a full
+   * scan to be told what is already known.
+   */
+  skippedValidations?: readonly PendingValidation[];
 }
 
 /** A `VALIDATE CONSTRAINT` that did not pass — the key is installed but still unproven. */
 export interface PendingValidation {
   /** The exact statement to re-run once the data satisfies the key. */
   sql: string;
-  /** PostgreSQL's message, trimmed for the record. */
+  /** PostgreSQL's message, trimmed for the record — or why the check was never attempted. */
   error: string;
+  /**
+   * The check was WITHHELD, not run: the row preflight had already counted the offending rows.
+   * Set only on that path, so `validationPendingReason` can name the data fix without having to
+   * pattern-match an error string it wrote itself.
+   */
+  skipped?: boolean;
 }
 
 export interface StateApplyResult {
@@ -431,14 +448,76 @@ export interface StateApplyResult {
  * So the row is written as soon as the batch has committed, describing exactly what is true then
  * (the key installed, none of the checks run yet), and amended when the checks are over.
  */
+/** The subset of StateApplyOptions the schema_log memoir writes need — nothing execution-only. */
+type SchemaLogFields = Pick<StateApplyOptions, 'actor' | 'gitRef' | 'planRef' | 'fromFingerprint' | 'fpVersion' | 'dirty'>;
+
+/**
+ * One row per unproven key, carrying the exact statement to re-run. Best-effort, like every
+ * other memoir write: failing to record why a key is pending must not mask that it is. Shared by
+ * both the normal path (checks run here) and the all-withheld early return (no checks run here,
+ * but the withheld ones are just as real a pending state and owe the same rows).
+ */
+async function recordPendingValidations(
+  runner: QueryRunner,
+  pendingValidations: readonly PendingValidation[],
+  options: SchemaLogFields,
+): Promise<void> {
+  for (const pending of pendingValidations) {
+    try {
+      await runner(renderSchemaLogInsert({
+        kind: 'state validate', sql: pending.sql,
+        outcome: `pending: ${pending.error}`,
+        actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
+        fromFingerprint: options.fromFingerprint,
+        fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
+      }));
+    } catch { /* the memoir is best-effort; the row already says what committed */ }
+  }
+}
+
 export async function applyGeneratedStatements(
   runner: QueryRunner,
   statements: string[],
   options: StateApplyOptions = {},
 ): Promise<StateApplyResult> {
   const classified = classifyGeneratedStatements(statements);
+  // Checks the caller withheld before calling. They are outstanding from the first line of this
+  // function: the outcome written before the batch already counts them, and they come back in the
+  // result whether or not any check actually ran here.
+  const skipped: PendingValidation[] = [...(options.skippedValidations ?? [])];
   if (classified.executable.length === 0) {
-    return { applied: false, classified, batchSql: '', pendingValidations: [] };
+    // No DDL to run — but a re-plan against keys a PREVIOUS apply already withheld still owes
+    // the audit trail a row: the promise (docs/cli.md) is every apply lands in schema_log, and
+    // an apply whose only content is "these keys are still unproven" is a real apply, not a
+    // no-op. Without this, re-running db:apply/db:plan against nothing but a withheld VALIDATE
+    // produces a `validation-pending` result the operator sees and a database that remembers
+    // nothing about it.
+    if (skipped.length > 0) {
+      const now = options.now ?? Date.now;
+      const started = now();
+      let logId: number | undefined;
+      // Same annotation the normal path folds in (a honoured lineage waiver, a proven drift
+      // origin) — an all-withheld apply is still the row a LATER apply's fast-forward proof
+      // reads, so it must carry the same note or that proof silently loses the annotation.
+      const note = options.descentNote?.();
+      const outcome = ['applied', note, `no schema change; ${skipped.length} constraint(s) still PENDING validation`]
+        .filter(Boolean).join(' — ');
+      try {
+        await runner(ENSURE_RECONCILER_SQL.join(';\n'));
+        const logRows = await runner(renderSchemaLogInsert({
+          kind: 'state apply', sql: '',
+          outcome,
+          actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
+          fromFingerprint: options.fromFingerprint,
+          fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
+          durationMs: now() - started,
+        }));
+        logId = logRows?.[0]?.id !== undefined ? Number(logRows[0].id) : undefined;
+      } catch { /* the memoir is best-effort — the caller's own result still names the debt */ }
+      await recordPendingValidations(runner, skipped, options);
+      return { applied: false, classified, batchSql: '', pendingValidations: skipped, ...(logId !== undefined ? { logId } : {}) };
+    }
+    return { applied: false, classified, batchSql: '', pendingValidations: skipped };
   }
 
   const now = options.now ?? Date.now;
@@ -499,7 +578,7 @@ export async function applyGeneratedStatements(
   // outcome says exactly that — this row is true at the instant it is written, not a prediction
   // of how the checks will go.
   const logRows = await runner(renderSchemaLogInsert({
-    kind: 'state apply', sql: batchSql, outcome: outcomeWith(validations.length),
+    kind: 'state apply', sql: batchSql, outcome: outcomeWith(validations.length + skipped.length),
     actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
     fromFingerprint: options.fromFingerprint,
     ...(landedAfterBatch ? { toFingerprint: landedAfterBatch } : {}),
@@ -511,7 +590,7 @@ export async function applyGeneratedStatements(
   // Every check is attempted, even after one fails: the operator is owed the COMPLETE list of
   // keys still unproven, not the first one. Each runs on its own, so one failure cannot take a
   // sibling's successful validation down with it.
-  const pendingValidations: PendingValidation[] = [];
+  const pendingValidations: PendingValidation[] = [...skipped];
   for (const statement of validations) {
     try {
       await runner(statement);
@@ -533,19 +612,7 @@ export async function applyGeneratedStatements(
     } catch { /* the memoir is best-effort; the row already says what committed */ }
   }
 
-  // One row per unproven key, carrying the exact statement to re-run. Best-effort, like every
-  // other memoir write: failing to record why a key is pending must not mask that it is.
-  for (const pending of pendingValidations) {
-    try {
-      await runner(renderSchemaLogInsert({
-        kind: 'state validate', sql: pending.sql,
-        outcome: `pending: ${pending.error}`,
-        actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
-        fromFingerprint: options.fromFingerprint,
-        fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
-      }));
-    } catch { /* see above */ }
-  }
+  await recordPendingValidations(runner, pendingValidations, options);
 
   return { applied: true, classified, batchSql, pendingValidations, ...(logId !== undefined ? { logId } : {}) };
 }

package/src/cli/swap-snapshot.ts

@@ -113,7 +113,8 @@ export function decideSnapshotMode(input: SnapshotDecisionInput): SnapshotDecisi
         mode: 'refuse',
         reason: 'A physical snapshot needs the RDS instance id, and this stage does not expose one. '
           + 'Add `databaseInstanceId: database.id` to the outputs return block in sst.config.ts and redeploy '
-          + '(run db:swap from the app directory so .sst/outputs.json is readable), or pass --snapshot logical '
+          + '(run db:swap from the app directory so .sst/outputs.json is readable; it counts only when the last '
+          + '`sst deploy` was THIS stage, otherwise redeploy this stage), or pass --snapshot logical '
           + 'for a pg_dump rollback point instead.',
       };
     }