@everystack/cli 0.4.46 → 0.4.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.46",
+  "version": "0.4.47",
   "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-apply.ts

@@ -331,13 +331,29 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       fail(`This plan is DESTRUCTIVE — ${plan.destructive} statement(s) lose data (${shape}). Explicit confirmation is required, always: re-run with --confirm.`);
       process.exit(1);
     }
-    // A DIRECT apply is operator-attested: the operator holds the URL, so the safety net is a backup
-    // they took and NAME here. (The credential-free path — db:apply --plan … --stage <name>, WITHOUT
-    // --direct — auto-resolves and verifies the stage's latest backup server-side; a direct/bare
-    // connection has no ops Lambda to verify against, so the ref is required and attested.)
+    // A DIRECT apply is operator-attested: the safety net is a backup the operator took and
+    // NAMES here, because this lane has no ops Lambda verifying one server-side.
+    //
+    // This used to end by offering "or drop --direct and let the credential-free --stage apply
+    // auto-verify your latest backup". THAT ADVICE CANNOT BE FOLLOWED. Auto-verification is
+    // real, but only for NON-destructive stage applies — and every plan reaching this block is
+    // destructive, so dropping --direct lands on the outright refusal above (the `--stage`
+    // destructive gate). It sent operators from a lane that works to one that refuses, and the
+    // refusal's own text then pointed them at --database-url. Two wrong signposts in a row are
+    // how a consumer ended up printing a privileged DSN to do something --direct already did.
+    //
+    // For a destructive plan there is exactly one remedy: take a safety point and name it.
     if (!flags['snapshot-ref']) {
-      const takeIt = `everystack db:backup${flags.stage ? ` --stage ${flags.stage}` : ''}`;
-      fail(`This plan is DESTRUCTIVE (${shape}) over a direct connection — the apply does not snapshot for you. Take a safety point (${takeIt}) and name it: --snapshot-ref <id>. Or drop --direct and let the credential-free --stage apply auto-verify your latest backup.`);
+      const stageArg = flags.stage ? ` --stage ${flags.stage}` : '';
+      const takeIt = `everystack db:backup${stageArg}`;
+      const lane = flags.stage
+        ? `${stageArg.trim()} --direct`
+        : '--database-url <url>';
+      fail(
+        `This plan is DESTRUCTIVE (${shape}) over a direct connection — the apply does not snapshot for you. `
+        + `Take a safety point (${takeIt}) and name it: everystack db:apply --plan ${planPath} ${lane} --confirm --snapshot-ref <id>. `
+        + 'A destructive plan always requires an attested --snapshot-ref; there is no lane that takes one for you.',
+      );
       process.exit(1);
     }
     if (flags.stage) {

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

@@ -87,7 +87,7 @@ async function runBackfillViaStage(
   if (res?.error) {
     fail(`db:backfill failed: ${res.error}`);
     if (/Unknown action/i.test(String(res.error))) {
-      info('The deployed handler predates the db:backfill ops action. Upgrade @everystack/server, or run direct: db:backfill --apply --database-url <url> (or --stage --direct).');
+      info('The deployed handler predates the db:backfill ops action. Upgrade @everystack/server, or run credential-free over the direct lane: db:backfill --apply --stage ' + (flags.stage ?? '<stage>') + ' --direct. (--database-url <url> is the local venue — against a deployed stage it puts a privileged connection string on argv.)');
     }
     process.exit(1);
   }

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

@@ -31,7 +31,18 @@ async function readStdin(): Promise<string> {
   return Buffer.concat(chunks).toString('utf8');
 }
 
-/** The app schemas the digest guard covers on the direct path (--schemas a,b; default public). */
+/**
+ * The schemas argument the digest query still ACCEPTS but no longer scopes by.
+ *
+ * `--schemas` never reached the stage path at all — the ops invoke sent only `{ sql, actor,
+ * stage }`, so a consumer who passed `--schemas auth,public` had it silently dropped and the
+ * server fell back to its own `options.schemas ?? ['public']`. Their 21 `auth.*` functions were
+ * outside the projection and the guard stayed silent on 43 schema statements.
+ *
+ * Rather than plumb the flag through, the digest now covers EVERY non-system schema
+ * (exec-digest.ts): a guard that can be scoped can be scoped to blindness. This is kept so the
+ * call sites read unchanged, and `--schemas` is now a documented no-op rather than a silent one.
+ */
 function directSchemas(flags: Record<string, string>): string[] {
   if (flags.schemas && flags.schemas !== 'true') {
     return flags.schemas.split(',').map((s) => s.trim()).filter(Boolean);
@@ -39,6 +50,13 @@ function directSchemas(flags: Record<string, string>): string[] {
   return ['public'];
 }
 
+/** Say it, rather than accept a flag that does nothing. */
+function noteSchemasIsNoLongerNeeded(flags: Record<string, string>): void {
+  if (flags.schemas && flags.schemas !== 'true') {
+    info('--schemas is no longer needed and no longer narrows anything: the DML-only guard now covers every non-system schema. (It used to default to `public`, which is how a file of auth.* functions once passed it.)');
+  }
+}
+
 function reportOk(res: { rowsAffected?: number[] }): void {
   const rows = res.rowsAffected ?? [];
   const total = rows.reduce((a, b) => a + b, 0);
@@ -70,6 +88,7 @@ export async function dbExecCommand(flags: Record<string, string>, file?: string
 
   const source = resolveDbSource(flags);
   const actor = process.env.USER ?? null;
+  noteSchemasIsNoLongerNeeded(flags);
 
   // --- Stage venue: ship the SQL to the ops Lambda's db:exec action (operator holds no URL). ---
   if (source.kind === 'stage') {

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

@@ -2,7 +2,7 @@
  * `everystack db:plan` — mint a verified edge against a target database
  * (brick 4's mint surface; the review artifact of the deploy boundary).
  *
- *   db:plan [--stage <name> | --database-url <url>] [--models <barrel>]
+ *   db:plan [--stage <name> [--direct] | --database-url <url>] [--models <barrel>]
  *           [--allow-drops] [--out db.plan.json | --out -]
  *
  * Minting asks the TARGET its fingerprint (no repo-side release pointer to
@@ -17,12 +17,27 @@
  * them (committing plans would rebuild the tape). Minting is read-only, so
  * it works over the ops Lambda (--stage) as well as a direct connection.
  *
- * On the STAGE lane the read is not atomic: every catalog query is its own
- * Lambda invoke, so one introspection can be assembled from several containers
- * holding connections to different databases, and the minted `from` would then
- * describe no real state. That lane reads TWICE and refuses a disagreement.
- * Agreement is a non-detection, not a verification — see
- * stage-read-consistency.ts. The direct lane reads once, over one session.
+ * THREE VENUES, and the difference is what the resulting fingerprint is worth:
+ *
+ *   --stage <name>            the ops Lambda. A full read is two invokes (state, then authz),
+ *                             answerable by two containers at two moments, so the minted `from`
+ *                             can describe no single real state. This lane reads TWICE and
+ *                             refuses a disagreement — a DETECTOR, never a verification
+ *                             (stage-read-consistency.ts). Agreement proves nothing.
+ *   --stage <name> --direct   the stage's OPERATOR connection, resolved from its IAM-gated ops
+ *                             Lambda and held in memory only. One real connection, one session,
+ *                             read ONCE — a fingerprint that describes one database at one
+ *                             moment. The credential never reaches argv.
+ *   --database-url <url>      a LOCAL connection. Same read guarantee as --direct, but against a
+ *                             deployed stage it forces a privileged DSN onto the command line.
+ *
+ * `--direct` EXISTED FOR db:apply AND NOT FOR db:plan, WHICH INVERTED THE COST OF SAFETY. The
+ * only lane that can verify a fingerprint was the only lane that made the operator print their
+ * credential, so verifying a plan cost them their secret hygiene — and the destructive refusal
+ * then recommended exactly that. A consumer's operator put it plainly: "every command that
+ * requires ARN is a risk of exposure. A major purpose of everystack is to PREVENT this." The
+ * resolution is shared with db:apply, db:reconcile, db:backfill, db:refresh and db:swap
+ * (direct-venue.ts) — db:plan was the verb that never adopted it.
  */
 
 import fs from 'node:fs/promises';
@@ -43,6 +58,7 @@ import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '
 import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import { resolveModelsPath } from '../models-path.js';
 import { resolveConfig, opsFunction } from '../config.js';
+import { resolveOperatorUrlViaStage } from '../direct-venue.js';
 import { lambdaQueryRunner, lambdaSessionRunner } from '../aws.js';
 import { loadModels } from './db-generate.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
@@ -98,6 +114,22 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // `--stage --direct`: resolve the stage's OPERATOR connection from its IAM-gated ops Lambda
+  // and mint over it. The URL lives in this process's memory only — never printed, never
+  // written, never on argv. From here it IS a url source, so the single-read path below picks
+  // it up and `connectingVia` reports the operator credential honestly.
+  if (dbSource.kind === 'stage' && flags.direct === 'true') {
+    try {
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(flags.stage);
+      info(`operator credential resolved (${op.source}) — minting CLI-side over one connection.`);
+      dbSource = { kind: 'url', url: op.url, from: 'operator' };
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
   let runner: QueryRunner;
 
   let session: SessionRunner;

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

@@ -480,7 +480,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
       if (result?.error) {
         fail(`db:reconcile failed: ${result.error}`);
         if (/Unknown action/i.test(String(result.error))) {
-          info('The deployed handler predates the db:reconcile ops action (needs @everystack/server >= 0.4.8). Upgrade the server, or apply direct: db:reconcile --apply --database-url <url>.');
+          info('The deployed handler predates the db:reconcile ops action (needs @everystack/server >= 0.4.8). Upgrade the server, or apply credential-free over the direct lane: db:reconcile --apply --stage ' + (flags.stage ?? '<stage>') + ' --direct. (--database-url <url> is the local venue — against a deployed stage it puts a privileged connection string on argv.)');
         } else if (/timed out|timeout|task timed out/i.test(String(result.error))) {
           info('A large derived rebuild (dozens of objects) can exceed the ops-Lambda 900-second clock. Re-run credential-free with an unbounded clock: db:reconcile --apply --stage ' + (flags.stage ?? '<stage>') + ' --direct.');
         }

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

@@ -8,15 +8,26 @@
  * unchanged — a pure DATA-changed matview refresh had no credential-free path. This is the
  * data-lane twin: `--stage` runs the whole refresh in the ops Lambda on the operator connection
  * (the `db:refresh` action), so a least-privileged operator never holds a URL. `--database-url`
- * / `--direct` refresh over a direct connection (dev). `--list` previews the topo-ordered
- * matviews without connecting. Plain REFRESH (ACCESS EXCLUSIVE) — CONCURRENTLY is a follow-on.
- * (consumer field report 2026-07-19.)
+ * refreshes over a local connection (dev). `--stage <name> --direct` resolves the stage's
+ * operator credential from its ops Lambda and refreshes CLI-side on an UNBOUNDED clock — the
+ * lane for a matview set that exceeds the ops-Lambda 900-second limit. `--list` previews the
+ * topo-ordered matviews without connecting. Plain REFRESH (ACCESS EXCLUSIVE) — CONCURRENTLY is
+ * a follow-on. (consumer field report 2026-07-19.)
+ *
+ * `--direct` WAS ADVERTISED HERE AND IN `everystack --help` WITHOUT BEING WIRED. `resolveDbSource`
+ * does not know the flag — each command wires it — so `db:refresh --direct` fell through to the
+ * stage branch and `resolveConfig(undefined)` picked the DEFAULT stage. An operator asking for a
+ * direct dev refresh could refresh a deployed stage's matviews instead, believing the flag had
+ * scoped them locally. A documented flag that silently does nothing is the same class as the
+ * refusal that recommended `--database-url`: the tool's own words sending the operator somewhere
+ * they did not choose.
  */
 
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
 import { executeRefresh, matviewIdentities, type RefreshRun } from '../refresh-execute.js';
 import { resolveConfig, opsFunction } from '../config.js';
+import { resolveOperatorUrlViaStage } from '../direct-venue.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info } from '../output.js';
 
@@ -57,9 +68,26 @@ export async function dbRefreshCommand(flags: Record<string, string>): Promise<v
     process.exit(1);
   }
 
-  // Two venues, mirroring the reconcile lane:
+  // `--stage --direct` (the shared direct venue): resolve the stage's OPERATOR connection from
+  // its ops Lambda and refresh CLI-side on an unbounded clock. The URL lives in this process's
+  // memory only — never printed, never written, never on argv. Same resolution db:apply,
+  // db:reconcile, db:backfill and db:swap use.
+  if (dbSource.kind === 'stage' && flags.direct === 'true') {
+    try {
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(flags.stage);
+      info(`operator credential resolved (${op.source}) — refreshing CLI-side, unbounded clock.`);
+      dbSource = { kind: 'url', url: op.url, from: 'operator' };
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
+  // Three venues, mirroring the reconcile lane:
   //  - a deployed stage runs the whole refresh in the ops Lambda on the operator connection
   //    (the db:refresh action) — no raw URL on the operator's machine, the whole point.
+  //  - --stage --direct resolves that same operator credential and runs CLI-side, unbounded.
   //  - a direct URL refreshes locally (dev).
   let end: (() => Promise<void>) | undefined;
   try {
@@ -79,7 +107,7 @@ export async function dbRefreshCommand(flags: Record<string, string>): Promise<v
       if (result?.error) {
         fail(`db:refresh failed: ${result.error}`);
         if (/Unknown action/i.test(String(result.error))) {
-          info('The deployed handler predates the db:refresh ops action (needs @everystack/server >= 0.4.9). Upgrade the server, or refresh direct: db:refresh --database-url <url>.');
+          info('The deployed handler predates the db:refresh ops action (needs @everystack/server >= 0.4.9). Upgrade the server, or refresh credential-free over the direct lane: db:refresh --stage ' + (flags.stage ?? '<stage>') + ' --direct. (--database-url <url> is the local venue — against a deployed stage it puts a privileged connection string on argv.)');
         }
         process.exit(1);
       }

package/src/cli/commands/db.ts

@@ -610,7 +610,8 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
         fail(`db:provision failed: ${err.message}`);
         if (/Unknown action/i.test(String(err.message))) {
           info('The deployed handler has no dbPlugin (no Ops Lambda), and no ADMIN_DATABASE_URL secret is set.');
-          info('Provision directly: everystack db:provision --stage <stage> --database-url <master-url> (once), or set the ADMIN_DATABASE_URL secret and use --direct.');
+          info('Preferred: set the secret once — everystack secrets set ADMIN_DATABASE_URL <url> --stage <stage> — then everystack db:provision --stage <stage> --direct reads it internally and the credential never reaches argv.');
+          info('Bootstrap fallback, when no secret exists yet: everystack db:provision --stage <stage> --database-url <master-url>. This puts the master credential on the command line (shell history, ps, CI logs) — do it once, then use --direct.');
         }
         for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
         process.exit(1);

package/src/cli/exec-digest.ts

@@ -24,24 +24,63 @@
 import { escapeLiteral } from './derived-apply.js';
 
 /**
- * Build the digest query for `schemas`. Returns SQL selecting a single `digest` column (md5 hex,
- * or md5('') for an empty catalog). The schemas are embedded as a quoted `text[]` literal — they
- * come from the deploy's declared schema set, never user input, but they are escaped regardless.
+ * Build the digest query. Returns SQL selecting a single `digest` column (md5 hex, or md5('')
+ * for an empty catalog).
+ *
+ * `schemas` IS ACCEPTED AND NO LONGER SCOPES THE DIGEST. It was the design error that made this
+ * guard fail in the field: a consumer ran 21 `CREATE OR REPLACE FUNCTION` in `auth` through
+ * db:exec and the guard stayed silent, because the deploy's schema set was `['public']` and the
+ * functions were simply outside the projection. **A guard that can be scoped can be scoped to
+ * blindness**, and the question db:exec asks is not "did the app's schemas move?" but "did the
+ * schema move AT ALL?". So the projection now covers every non-system schema, and no
+ * configuration — or missing configuration — can narrow it.
+ *
+ * The parameter stays in the signature deliberately: `@everystack/server` calls this through
+ * `@everystack/cli/exec`, so removing it would break every deployed ops Lambda that has not
+ * upgraded in lockstep. An old server passing `['public']` now gets full coverage.
+ *
+ * System schemas are excluded because they move for reasons that are not the caller's doing:
+ * `pg_toast` gains relations as tables acquire toastable columns, `pg_temp_*` appears and
+ * vanishes with sessions, and `pg_catalog`/`information_schema` are not the caller's to change.
  */
 export function catalogDigestQuery(schemas: string[]): string {
   if (schemas.length === 0) {
     throw new Error('catalogDigestQuery needs at least one schema to digest — pass the app schemas.');
   }
-  const arr = `ARRAY[${schemas.map(escapeLiteral).join(', ')}]::text[]`;
+  // Retained so the argument is not silently meaningless to a reader diffing this file: the
+  // value is validated exactly as before, then deliberately not used as a filter.
+  void schemas.map(escapeLiteral);
+  // A predicate, not an array: `= ANY(array_agg(nspname))` compares name to name[] and
+  // PostgreSQL has no such operator. Every branch below aliases pg_namespace as `n`.
+  const NS = `n.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+      AND n.nspname NOT LIKE 'pg_temp%' AND n.nspname NOT LIKE 'pg_toast_temp%'`;
   return `
 SELECT md5(coalesce(string_agg(line, E'\\n' ORDER BY line), '')) AS digest
 FROM (
   -- Relations: kind + persistence ONLY, never the volatile planner-stats columns (row-count,
   -- page-count, freeze-horizon) — those move under INSERT/UPDATE/DELETE and autovacuum, and
   -- would make the digest lie about pure DML.
-  SELECT format('rel:%s.%s:%s:%s', n.nspname, c.relname, c.relkind, c.relpersistence) AS line
+  -- relacl carries the GRANTs, and relrowsecurity/relforcerowsecurity the RLS posture. Both
+  -- were missing, so GRANT SELECT ON t TO anon, and ALTER TABLE t ENABLE ROW LEVEL SECURITY,
+  -- passed a gate advertising "rejects ANY schema change". A lane that cannot change the schema
+  -- but CAN change who may read it is not a DML-only lane. None of the three move under DML.
+  SELECT format('rel:%s.%s:%s:%s:%s:%s:%s', n.nspname, c.relname, c.relkind, c.relpersistence,
+                coalesce(c.relacl::text, ''), c.relrowsecurity, c.relforcerowsecurity) AS line
     FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
-    WHERE n.nspname = ANY(${arr}) AND c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f')
+    WHERE ${NS} AND c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f')
+  UNION ALL
+  -- Row policies: a CREATE/ALTER/DROP POLICY rewrites who sees which rows and touches no other
+  -- catalog this projection reads, so without this it was invisible.
+  SELECT format('pol:%s.%s.%s:%s:%s:%s:%s:%s', n.nspname, c.relname, pol.polname, pol.polcmd,
+                pol.polpermissive,
+                coalesce((SELECT string_agg(r.rolname, ',' ORDER BY r.rolname)
+                          FROM pg_roles r WHERE r.oid = ANY(pol.polroles)), 'PUBLIC'),
+                coalesce(pg_get_expr(pol.polqual, pol.polrelid), ''),
+                coalesce(pg_get_expr(pol.polwithcheck, pol.polrelid), ''))
+    FROM pg_policy pol
+    JOIN pg_class c ON c.oid = pol.polrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE ${NS}
   UNION ALL
   -- Columns: number, type, typmod, not-null — the shape ALTER TABLE moves, DML never.
   SELECT format('att:%s.%s.%s:%s:%s:%s:%s',
@@ -49,31 +88,34 @@ FROM (
     FROM pg_attribute a
     JOIN pg_class c ON c.oid = a.attrelid
     JOIN pg_namespace n ON n.oid = c.relnamespace
-    WHERE n.nspname = ANY(${arr}) AND a.attnum > 0 AND NOT a.attisdropped
+    WHERE ${NS} AND a.attnum > 0 AND NOT a.attisdropped
   UNION ALL
   -- Constraints: the full textual definition (PK/FK/unique/check predicate).
   SELECT format('con:%s.%s:%s', n.nspname, con.conname, pg_get_constraintdef(con.oid))
     FROM pg_constraint con JOIN pg_namespace n ON n.oid = con.connamespace
-    WHERE n.nspname = ANY(${arr})
+    WHERE ${NS}
   UNION ALL
   -- Indexes: the full textual definition (columns, uniqueness, partial WHERE).
   SELECT format('idx:%s.%s:%s', n.nspname, ic.relname, pg_get_indexdef(i.indexrelid))
     FROM pg_index i
     JOIN pg_class ic ON ic.oid = i.indexrelid
     JOIN pg_namespace n ON n.oid = ic.relnamespace
-    WHERE n.nspname = ANY(${arr})
+    WHERE ${NS}
   UNION ALL
-  -- Routines: name + arg types + a hash of the body. CREATE/REPLACE/DROP FUNCTION all move it.
-  SELECT format('proc:%s.%s:%s:%s', n.nspname, p.proname, p.proargtypes::text, md5(coalesce(p.prosrc, '')))
+  -- Routines: name + arg types + a hash of the body, PLUS proacl (the EXECUTE grants) and
+  -- prosecdef. A REVOKE that leaves a SECURITY DEFINER function PUBLIC-executable, or a GRANT
+  -- that opens one, is a privilege change and must trip the guard like any other.
+  SELECT format('proc:%s.%s:%s:%s:%s:%s', n.nspname, p.proname, p.proargtypes::text,
+                md5(coalesce(p.prosrc, '')), coalesce(p.proacl::text, ''), p.prosecdef)
     FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
-    WHERE n.nspname = ANY(${arr})
+    WHERE ${NS}
   UNION ALL
   -- Types: kind + ordered enum labels. CREATE TYPE / ALTER TYPE ADD VALUE move it.
   SELECT format('type:%s.%s:%s:%s', n.nspname, t.typname, t.typtype,
                 coalesce((SELECT string_agg(e.enumlabel, ',' ORDER BY e.enumsortorder)
                           FROM pg_enum e WHERE e.enumtypid = t.oid), ''))
     FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace
-    WHERE n.nspname = ANY(${arr})
+    WHERE ${NS}
 ) s
 `.trim();
 }

package/src/cli/index.ts

@@ -363,10 +363,10 @@ Usage:
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).
-  everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--verify-nonempty] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url/--direct refresh over a direct connection (dev); --only refreshes a named subset (full identity or bare name); --verify-nonempty gates on populated-but-zero-rows matviews (the dark-panel check — a scoped EXISTS on just what was refreshed, so a promotion script gets the gate with no read authority) and FAILS naming any empty; --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.
+  everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--verify-nonempty] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url refreshes over a local connection (dev); --stage <name> --direct resolves the stage's operator connection from its ops Lambda (credential never on argv) and refreshes CLI-side on an UNBOUNDED clock, for a matview set that exceeds the ops-Lambda 900s limit; --only refreshes a named subset (full identity or bare name); --verify-nonempty gates on populated-but-zero-rows matviews (the dark-panel check — a scoped EXISTS on just what was refreshed, so a promotion script gets the gate with no read authority) and FAILS naming any empty; --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
-  everystack db:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed
+  everystack db:plan           [--stage <name> [--direct] | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line)
   everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + an attested --snapshot-ref + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
   everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
   everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only

package/src/cli/stage-read-consistency.ts

@@ -89,17 +89,34 @@ export function inconsistentContainersNotDetected(): string {
  * The refusal a DESTRUCTIVE plan gets on the stage lane, before anything runs.
  * The double read cannot lift this: a detector that can miss is not a basis for
  * dropping data. The destructive ceremony lives on the direct lane.
+ *
+ * THE WAY OUT IS `--stage <name> --direct`, AND SAYING SO IS THE POINT OF THIS
+ * MESSAGE. It used to end by recommending `--database-url <url>` while calling it
+ * "a direct connection" — which is true of the connection and catastrophic as
+ * advice: `--database-url` is the ONE lane that puts a privileged DSN on argv, and
+ * from there into shell history, `ps`/`/proc/<pid>/cmdline`, scrollback, screen
+ * shares and CI logs. `--stage --direct` has identical trust properties (one real
+ * connection, one session) and resolves the credential through the stage's IAM-gated
+ * ops Lambda into process memory, where it is never printed or written.
+ *
+ * A consumer read this message, did what it said, and their operator objected:
+ * "every command that requires ARN is a risk of exposure. A major purpose of
+ * everystack is to PREVENT this." The capability they needed already existed. The
+ * refusal pointed away from it. Keep `--stage --direct` first, and keep
+ * `--database-url` marked as the LOCAL venue it is.
  */
 export function stageDestructiveRefusal(
   shape: string,
   planPath: string,
   stage: string | undefined,
 ): string {
-  const takeIt = `everystack db:backup${stage ? ` --stage ${stage}` : ''}`;
+  const stageArg = stage ? ` --stage ${stage}` : ' --stage <name>';
+  const takeIt = `everystack db:backup${stageArg}`;
   return [
     `REFUSED (stage lane, DESTRUCTIVE plan — ${shape}): the stage lane cannot guarantee read consistency.`,
     'A full read is two ops-Lambda invokes (state, then authz), so the fingerprint the concurrency lock gates on can still be assembled from two containers at two moments. A plan that loses data may not ride a read that cannot be verified.',
-    `Run destructive applies over a direct connection with the full ceremony: ${takeIt}, then everystack db:apply --plan ${planPath} --database-url <url> --confirm --snapshot-ref <id>.`,
+    `Use the direct lane, which reads over ONE connection and never puts a credential on argv — it resolves the operator connection from the stage itself: ${takeIt}, then everystack db:apply --plan ${planPath}${stageArg} --direct --confirm --snapshot-ref <id>.`,
+    '(--database-url is the LOCAL-development venue. Against a deployed stage it forces a privileged connection string onto the command line — shell history, ps, scrollback, CI logs — and buys nothing --direct does not already give you.)',
   ].join(' ');
 }