@everystack/cli 0.4.30 → 0.4.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.30",
+  "version": "0.4.31",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -37,6 +37,10 @@
       "types": "./src/cli/apply-execute.ts",
       "default": "./src/cli/apply-execute.ts"
     },
+    "./db-source": {
+      "types": "./src/cli/db-source.ts",
+      "default": "./src/cli/db-source.ts"
+    },
     "./reconcile": {
       "types": "./src/reconcile.ts",
       "default": "./src/reconcile.ts"
@@ -49,6 +53,10 @@
       "types": "./src/backfill.ts",
       "default": "./src/backfill.ts"
     },
+    "./exec": {
+      "types": "./src/exec.ts",
+      "default": "./src/exec.ts"
+    },
     "./audit/source": {
       "types": "./src/cli/audit-source-api.ts",
       "default": "./src/cli/audit-source-api.ts"

package/src/cli/apply-execute.ts

@@ -62,18 +62,20 @@ export interface ApplyPlanOptions {
    */
   verifyAuthority?: () => Promise<{ ok: true } | { ok: false; reason: string }>;
   /**
-   * Runs after every verification passes and BEFORE the edge executes, only
-   * for destructive plans — the auto-snapshot seam ("losing data should be
-   * hard": confirmed, approved, snapshotted, in that order). A throw here
-   * aborts the apply with nothing executed.
+   * The destructive-apply safety gate (B3): called only for destructive plans, after the lock,
+   * descent, and authority pass and BEFORE the edge executes. The apply NO LONGER takes its own
+   * snapshot — the caller must be covered by a verified backup. Return `ok: false` to refuse (the
+   * refusal is recorded in schema_log, like the others). `planFrom` is handed in so the caller can
+   * assert `backup.fingerprint == planFrom` server-side. Omitted = no gate (bare connections that
+   * attest their own --snapshot-ref keep the ceremony the command shell enforces).
    */
-  beforeDestructive?: () => Promise<void>;
+  verifySnapshot?: (ctx: { planFrom: string }) => Promise<{ ok: true } | { ok: false; reason: string }>;
   /** Injectable clock for tests. */
   now?: () => number;
 }
 
 export interface ApplyPlanResult {
-  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'authority-refused' | 'verify-failed';
+  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'authority-refused' | 'snapshot-refused' | 'verify-failed';
   liveFingerprint: string;
   reason?: string;
   logId?: number;
@@ -110,15 +112,33 @@ async function recordRefusal(
   }
 }
 
+/** The live base-schema fingerprint + the two introspections it's built from. */
+export interface LiveBaseFingerprint {
+  hash: string;
+  snapshot: SchemaSnapshot;
+  contract: AuthzContract;
+}
+
+/**
+ * The live base-schema fingerprint over a runner — the exact value db:plan stamps as plan.from and
+ * the apply's concurrency lock recomputes. Extracted so EVERY producer computes one identical hash:
+ * the apply lock (here), db:fingerprint, and the db:backup Task that stamps its manifest for the
+ * destructive-apply safety gate (backup.fp == plan.from). A second copy would silently drift the
+ * fingerprint chain — the whole point of the gate.
+ */
+export async function liveBaseFingerprint(runner: QueryRunner): Promise<LiveBaseFingerprint> {
+  const snapshot = await introspectSchema(runner);
+  const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract };
+}
+
 /** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
 export async function executeApplyPlan(
   runner: QueryRunner,
   plan: EdgePlan,
   options: ApplyPlanOptions = {},
 ): Promise<ApplyPlanResult> {
-  const before = await introspectSchema(runner);
-  const beforeAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
-  const live = fingerprintLive(before, beforeAuthz).hash;
+  const { hash: live, snapshot: before, contract: beforeAuthz } = await liveBaseFingerprint(runner);
 
   if (live === plan.toFingerprint) {
     return { status: 'already-applied', liveFingerprint: live };
@@ -145,8 +165,12 @@ export async function executeApplyPlan(
     }
   }
 
-  if (plan.destructive > 0 && options.beforeDestructive) {
-    await options.beforeDestructive();
+  if (plan.destructive > 0 && options.verifySnapshot) {
+    const snapshot = await options.verifySnapshot({ planFrom: live });
+    if (!snapshot.ok) {
+      await recordRefusal(runner, plan, live, 'snapshot gate', snapshot.reason, options);
+      return { status: 'snapshot-refused', liveFingerprint: live, reason: snapshot.reason };
+    }
   }
 
   const result = await applyGeneratedStatements(runner, plan.statements, {
@@ -157,9 +181,7 @@ export async function executeApplyPlan(
     now: options.now,
   });
 
-  const after = await introspectSchema(runner);
-  const afterAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
-  const landed = fingerprintLive(after, afterAuthz).hash;
+  const { hash: landed } = await liveBaseFingerprint(runner);
   if (result.logId !== undefined) {
     await runner(renderSchemaLogFingerprintUpdate(result.logId, landed));
   }

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

@@ -38,7 +38,6 @@ import { executeApplyPlan, type ApplyPlanResult } from '../apply-execute.js';
 import { estimateOpsRuntimeFit } from '../ops-fit.js';
 import { resolveOperatorUrlViaStage } from '../direct-venue.js';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
-import { pgDumpPreflightError } from './db-backup.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 // The apply core lives in apply-execute.ts (shared with the ops Lambda's
@@ -90,6 +89,10 @@ function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void {
       fail(`REFUSED (destructive authority): ${result.reason}`);
       process.exit(1);
       break;
+    case 'snapshot-refused':
+      fail(`REFUSED (snapshot gate): ${result.reason}`);
+      process.exit(1);
+      break;
     case 'verify-failed':
       fail(`Verify FAILED: ${result.reason}`);
       process.exit(1);
@@ -120,19 +123,6 @@ async function applyPlanViaStage(
 
   info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
 
-  // A destructive staged apply snapshots via db:backup INSIDE the Lambda, before the DDL. Preflight
-  // that capability HERE so a missing/incompatible pg_dump layer fails fast with the install remedy —
-  // not deep in the ceremony after the authority check, the way it once surfaced mid-apply.
-  if (plan.destructive > 0) {
-    step('Preflighting the pg_dump layer (the destructive apply snapshots before the DDL)...');
-    const probe: any = await invokeAction(region, fn, 'db:backup:probe', {}).catch((err: any) => ({ error: err?.message ?? String(err) }));
-    const remedy = pgDumpPreflightError(probe);
-    if (remedy) {
-      fail(`Cannot take the pre-apply snapshot — the destructive plan was NOT applied.\n${remedy}`);
-      process.exit(1);
-    }
-  }
-
   try {
     // Descent — the fast-forward rule needs the git checkout, so the CLI
     // decides it (the Lambda has no checkout). Read the stage's state read-only
@@ -168,8 +158,9 @@ async function applyPlanViaStage(
 
     // Destructive ceremony — the approver check is against the caller's REAL
     // IAM identity (STS), which the Lambda cannot see, so the CLI resolves it
-    // and checks it against the stage's declared approver set (SSM). The
-    // snapshot itself runs IN the Lambda, before the DDL. --confirm always.
+    // and checks it against the stage's declared approver set (SSM). The safety
+    // net is a VERIFIED backup: the Lambda auto-resolves the stage's newest (or
+    // the id in --snapshot-ref) and refuses unless it covers this plan. --confirm always.
     let authorityVerdict: AuthorityVerdict | undefined;
     if (plan.destructive > 0) {
       const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
@@ -198,6 +189,7 @@ async function applyPlanViaStage(
       gitRef: currentGitRef() ?? plan.gitRef,
       descentVerdict,
       ...(authorityVerdict ? { authorityVerdict } : {}),
+      ...(flags['snapshot-ref'] ? { snapshotRef: flags['snapshot-ref'] } : {}),
       stage: flags.stage,
     });
     if (result?.error) {
@@ -258,8 +250,8 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
 
   // `--stage --direct` (lane 1): resolve the stage's OPERATOR connection from its ops
   // Lambda, then execute CLI-side with an unbounded clock — the same ceremony as the
-  // direct path below (which is stage-aware: approver check + auto-snapshot when --stage
-  // is set), just a longer clock. The operator never holds a URL; it lives in memory only.
+  // direct path below (which is stage-aware: approver check + an attested --snapshot-ref
+  // for destructive plans), just a longer clock. The operator never holds a URL; it lives in memory only.
   if (dbSource.kind === 'stage' && flags.direct === 'true') {
     try {
       step('Resolving the operator connection from the stage (--direct)...');
@@ -292,13 +284,21 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   // set — identity-approved (decision 12).
   const isDestructive = plan.destructive > 0;
   let verifyAuthority: (() => Promise<{ ok: true } | { ok: false; reason: string }>) | undefined;
-  let beforeDestructive: (() => Promise<void>) | undefined;
   if (isDestructive) {
     const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
     if (flags.confirm !== 'true') {
       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.)
+    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.`);
+      process.exit(1);
+    }
     if (flags.stage) {
       const config = await resolveConfig(flags.stage);
       const { parseAppName } = await import('../discover.js');
@@ -316,19 +316,9 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
         }
         return { ok: true };
       };
-      beforeDestructive = async () => {
-        step('Destructive apply — taking a snapshot first (db:backup)...');
-        const result: any = await invokeAction(config.region, opsFunction(config), 'db:backup', { stage: flags.stage });
-        if (result?.error) {
-          throw new Error(`auto-snapshot failed, so the destructive plan was NOT applied: ${result.error}`);
-        }
-        info(`snapshot on record: ${result?.id ?? 'backup complete'} — restore with db:restore --from ${result?.id ?? '<id>'} --confirm.`);
-      };
-    } else if (!flags['snapshot-ref']) {
-      fail(`This plan is DESTRUCTIVE (${shape}) and the target is a bare connection — the apply cannot take the snapshot itself. Take one (db:snapshot / db:backup / pg_dump) and name it: --snapshot-ref <ref>. Or pass --stage and the apply snapshots automatically, with the stage's approver set enforced.`);
-      process.exit(1);
+      warn(`DESTRUCTIVE direct apply — proceeding on ceremony: --confirm + attested snapshot ${flags['snapshot-ref']}.`);
     } else {
-      warn(`DESTRUCTIVE apply over a bare connection — approver gating unavailable (no --stage), proceeding on ceremony: --confirm + snapshot ${flags['snapshot-ref']}.`);
+      warn(`DESTRUCTIVE apply over a bare connection — approver gating unavailable (no --stage), proceeding on ceremony: --confirm + attested snapshot ${flags['snapshot-ref']}.`);
     }
   }
 
@@ -351,7 +341,6 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
       ...(verifyAuthority ? { verifyAuthority } : {}),
-      ...(beforeDestructive ? { beforeDestructive } : {}),
       ...(forceDescent === undefined ? {
         verifyDescent: async (live: LiveState & { fingerprint: string }) => {
           step('Descent: searching git for the commit that declares the target\'s state...');

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

@@ -1,14 +1,15 @@
 /**
  * db:backup family — logical pg_dump/pg_restore backups (the postgres-native, DB-agnostic path).
  *
- * These run server-side in the ops Lambda (the DB is private), so the CLI is a thin invokeAction
- * wrapper. db:backup:probe is the deploy-verification for the pg_dump layer (B1); the
- * dump/list/restore/download commands land in B2/B3. See docs/plans/db-backup-restore.md.
+ * db:backup/db:export run in the ephemeral Task lane (the ops Lambda holds no pg binaries); the CLI
+ * dispatches and polls. db:backups/db:restore/download are thin invokeAction wrappers. The image's
+ * version handshake is the compatibility gate — verify a deploy with `everystack task:probe`.
  */
 
 import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
 import { invokeAction, presignGet } from '../aws.js';
 import { parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard } from '../backup.js';
+import { pollTaskUntilStopped } from '../task-poll.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 function fmtBytes(n?: number): string {
@@ -21,65 +22,10 @@ function fmtBytes(n?: number): string {
 }
 
 /**
- * db:backup:probe — confirm the pg_dump layer is attached to the ops function AND that its major
- * version can dump the live server (pg_dump >= server major; there is no bypass flag). This is how
- * we prove B1 after a deploy before trusting db:backup.
+ * db:backup — pg_dump the stage's DB to S3, in the ephemeral Task lane (the ops Lambda holds no pg
+ * binaries). The CLI dispatches the task and polls until it stops; the task's version handshake is
+ * the compatibility gate (a too-old image fails the run loudly — no separate layer pre-flight).
  */
-export async function dbBackupProbeCommand(flags: Record<string, string>): Promise<void> {
-  step('Resolving deployed config...');
-  let config: CliConfig;
-  try {
-    config = await resolveConfig(flags.stage);
-  } catch (err: any) {
-    fail(err.message);
-    process.exit(1);
-  }
-
-  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
-  step('Probing pg_dump layer + server version...');
-
-  let result: any;
-  try {
-    result = await invokeAction(config.region, opsFunction(config), 'db:backup:probe', {});
-  } catch (err: any) {
-    fail(`Probe failed: ${err.message}`);
-    process.exit(1);
-  }
-
-  if (result?.error) {
-    fail(result.error);
-    info('Install @everystack/pg-tools and redeploy — the layer attaches automatically. For a bring-your-own layer, pass pgDumpLayer(..., { layerArn }) in sst.config.ts.');
-    process.exit(1);
-  }
-
-  info(`pg_dump:  ${result.pgDump} (major ${result.pgDumpMajor})`);
-  info(`server:   ${result.serverVersionNum} (major ${result.serverMajor})`);
-  if (result.compatible) {
-    success('Compatible — pg_dump can back up and restore this server. db:backup is ready.');
-  } else {
-    warn('INCOMPATIBLE — pg_dump is older than the server major; it will refuse to dump (no bypass exists).');
-    warn('Rebuild the layer with a pg_dump >= the server major.');
-    process.exit(1);
-  }
-}
-
-/**
- * Interpret a `db:backup:probe` result into a fail-clean remedy, or `null` when a dump is safe to
- * run. Pre-flighting this before the dump turns a missing or version-incompatible pg_dump layer
- * into a one-line remedy instead of a cryptic runtime crash mid-dump.
- */
-export function pgDumpPreflightError(probe: any): string | null {
-  if (!probe || probe.error) {
-    const detail = probe?.error ?? 'the pg_dump layer probe returned no result';
-    return `${detail}\nInstall @everystack/pg-tools and redeploy — the layer attaches automatically. For a bring-your-own layer, pass pgDumpLayer(..., { layerArn }) in sst.config.ts.`;
-  }
-  if (probe.compatible === false) {
-    return `pg_dump ${probe.pgDump ?? '(unknown)'} (major ${probe.pgDumpMajor}) is older than the server (major ${probe.serverMajor}) — it will refuse to dump (no bypass exists). Rebuild the layer with pg_dump >= ${probe.serverMajor}.`;
-  }
-  return null;
-}
-
-/** db:backup — pg_dump the stage's DB to S3 (runs in the ops Lambda). Prints the new backup id. */
 export async function dbBackupCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
   let config: CliConfig;
@@ -91,38 +37,41 @@ export async function dbBackupCommand(flags: Record<string, string>): Promise<vo
   }
 
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  const fn = opsFunction(config);
 
-  // Pre-flight the pg_dump layer before the dump — a missing/incompatible layer becomes a one-line
-  // remedy here instead of crashing the runtime mid-dump (the probe returns a clean error, never a
-  // crash, when the layer is absent).
-  step('Checking the pg_dump layer...');
-  let probe: any;
+  step('Dispatching the backup task (credential-free, via the ops Lambda)...');
+  let dispatched: any;
   try {
-    probe = await invokeAction(config.region, opsFunction(config), 'db:backup:probe', {});
+    dispatched = await invokeAction(config.region, fn, 'db:backup', { stage: flags.stage, actor: process.env.USER ?? null });
   } catch (err: any) {
-    fail(`Backup pre-flight failed: ${err.message}`);
+    fail(`Backup failed to dispatch: ${err.message}`);
     process.exit(1);
   }
-  const preflightError = pgDumpPreflightError(probe);
-  if (preflightError) {
-    fail(preflightError);
+  if (dispatched?.error) {
+    fail(`Backup failed: ${dispatched.error}`);
     process.exit(1);
   }
+  const { runId, taskArn, id, warning } = dispatched as { runId: string; taskArn: string; id: string; warning?: string };
+  info(`backup ${id} — task ${taskArn}`);
+  info(`run id: ${runId} (everystack.task_log)`);
+  if (warning) info(`note: ${warning}`);
 
   step('Running pg_dump → S3 (this may take a while for large databases)...');
-
-  let result: any;
-  try {
-    result = await invokeAction(config.region, opsFunction(config), 'db:backup', { stage: flags.stage });
-  } catch (err: any) {
-    fail(`Backup failed: ${err.message}`);
+  const poll = await pollTaskUntilStopped(config.region, fn, { runId, taskArn });
+  if (poll.outcome === 'timeout') {
+    fail(`db:backup timed out (last status: ${poll.lastStatus}). Run id ${runId} — reconcile via ECS/everystack.task_log.`);
     process.exit(1);
   }
-  if (result?.error) {
-    fail(`Backup failed: ${result.error}`);
+  if (poll.outcome === 'error') {
+    fail(`task:status failed repeatedly: ${poll.status.error}. The backup may still be running — reconcile run id ${runId}.`);
     process.exit(1);
   }
-  success(`Backup ${result.id} (${fmtBytes(result.bytes)}). Restore with: everystack db:restore --from ${result.id} --confirm`);
+  if (poll.status.exitCode !== 0) {
+    fail(`Backup failed (exit ${poll.status.exitCode ?? 'unknown'})${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}. Read the task logs (CloudWatch).`);
+    process.exit(1);
+  }
+  const bytes = (poll.status.result?.bytes as number | undefined) ?? undefined;
+  success(`Backup ${id} (${fmtBytes(bytes)}). Restore with: everystack db:restore --from ${id} --confirm`);
 }
 
 /** db:backups — list a stage's logical backups. */
@@ -198,16 +147,37 @@ export async function dbRestoreCommand(flags: Record<string, string>): Promise<v
   }
 
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
-  step(`Restoring ${id} into ${toStage} (pg_restore)...`);
-  let result: any;
+  const fn = opsFunction(config);
+
+  step('Dispatching the restore task (credential-free, via the ops Lambda)...');
+  let dispatched: any;
   try {
-    result = await invokeAction(config.region, opsFunction(config), 'db:restore', { id, confirm: true, stage: flags.stage });
+    dispatched = await invokeAction(config.region, fn, 'db:restore', { id, confirm: true, stage: flags.stage, actor: process.env.USER ?? null });
   } catch (err: any) {
-    fail(`Restore failed: ${err.message}`);
+    fail(`Restore failed to dispatch: ${err.message}`);
     process.exit(1);
   }
-  if (result?.error) {
-    fail(`Restore failed: ${result.error}`);
+  if (dispatched?.error) {
+    fail(`Restore failed: ${dispatched.error}`);
+    process.exit(1);
+  }
+  const { runId, taskArn, intentKey, warning } = dispatched as { runId: string; taskArn: string; intentKey: string; warning?: string };
+  info(`restore of ${id} → ${toStage} — task ${taskArn}`);
+  info(`intent: ${intentKey} (durable S3 record — survives the restore)`);
+  if (warning) info(`note: ${warning}`);
+
+  step(`Restoring ${id} into ${toStage} (pg_restore in the Task; this may take a while)...`);
+  const poll = await pollTaskUntilStopped(config.region, fn, { runId, taskArn });
+  if (poll.outcome === 'timeout') {
+    fail(`db:restore timed out (last status: ${poll.lastStatus}). Intent ${intentKey} — reconcile via ECS/the S3 intent.`);
+    process.exit(1);
+  }
+  if (poll.outcome === 'error') {
+    fail(`task:status failed repeatedly: ${poll.status.error}. The restore may still be running — reconcile intent ${intentKey}.`);
+    process.exit(1);
+  }
+  if (poll.status.exitCode !== 0) {
+    fail(`Restore failed (exit ${poll.status.exitCode ?? 'unknown'})${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}. The target DB may be partially restored — check the S3 intent ${intentKey} and the task logs.`);
     process.exit(1);
   }
   success(`Restored ${id} into ${toStage}.`);

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

@@ -0,0 +1,132 @@
+/**
+ * `everystack db:exec <file.sql>` — credential-free write SQL, the daily driver.
+ *
+ *   db:exec seed.sql --stage dev            # run in the ops Lambda (no URL held), DML-only
+ *   db:exec --stage prod some.sql --confirm # prod-tier writes require --confirm
+ *   cat some.sql | db:exec --stage dev      # stdin also works (a `psql < file.sql` replacement)
+ *   db:exec some.sql --database-url <url>   # local-direct (dev), unbounded clock
+ *
+ * The file runs as ONE transaction, DML-only enforced SEMANTICALLY: a catalog digest taken before
+ * vs after the file rejects ANY schema change — however caused (a function, a DO block, dynamic
+ * SQL) — by rolling the whole transaction back. Schema changes go through db:apply / db:reconcile.
+ * Every run is recorded, crash-truthfully, in everystack.exec_log (intent before, outcome after).
+ *
+ * Mirrors db:backfill's two venues: `--stage` ships the SQL to the ops Lambda's db:exec action
+ * (the operator holds no URL); `--database-url` connects directly for local dev.
+ */
+
+import fs from 'node:fs/promises';
+import { resolveDbSource, sslDefaults } from '../db-source.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { isProductionTier } from '../backup.js';
+import { executeExec, assertNoTxnControl } from '../exec-execute.js';
+import { runExecInTx } from '../exec-run.js';
+import { ENSURE_EXEC_LOG_SQL, renderExecIntentInsert, renderExecOutcomeUpdate } from '../exec-log.js';
+import { step, success, fail, info } from '../output.js';
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/** The app schemas the digest guard covers on the direct path (--schemas a,b; default public). */
+function directSchemas(flags: Record<string, string>): string[] {
+  if (flags.schemas && flags.schemas !== 'true') {
+    return flags.schemas.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  return ['public'];
+}
+
+function reportOk(res: { rowsAffected?: number[] }): void {
+  const rows = res.rowsAffected ?? [];
+  const total = rows.reduce((a, b) => a + b, 0);
+  success(`db:exec applied ${rows.length} statement(s), ${total} row(s) affected — recorded in everystack.exec_log.`);
+}
+
+export async function dbExecCommand(flags: Record<string, string>, file?: string): Promise<void> {
+  // Read the SQL: a positional file, `-`/absent for stdin (the `psql < file.sql` replacement).
+  let fileSql: string;
+  try {
+    fileSql = file && file !== '-' ? await fs.readFile(file, 'utf8') : await readStdin();
+  } catch (err: any) {
+    fail(`db:exec: cannot read SQL (${err.message}).`);
+    process.exit(1);
+  }
+  if (!fileSql.trim()) {
+    fail('db:exec: no SQL to run — pass a file or pipe SQL on stdin.');
+    process.exit(1);
+  }
+
+  // Fail fast on a self-transacting file before any invoke/connection (the real DML-only guard is
+  // the catalog digest, server-side; this is the courtesy pre-check).
+  try {
+    assertNoTxnControl(fileSql);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const source = resolveDbSource(flags);
+  const actor = process.env.USER ?? null;
+
+  // --- Stage venue: ship the SQL to the ops Lambda's db:exec action (operator holds no URL). ---
+  if (source.kind === 'stage') {
+    const stage = flags.stage;
+    if (stage && isProductionTier(stage) && flags.confirm !== 'true') {
+      fail(`db:exec writes to production-tier "${stage}" — pass --confirm to proceed.`);
+      process.exit(1);
+    }
+    step('Resolving deployed config...');
+    const config = await resolveConfig(stage);
+    step('Running db:exec in the ops Lambda (credential-free, DML-only, one transaction)...');
+    const res: any = await invokeAction(config.region, opsFunction(config), 'db:exec', {
+      sql: fileSql, actor, stage: stage ?? null,
+    });
+    if (res?.error) {
+      fail(`db:exec failed: ${res.error}`);
+      if (/Unknown action/i.test(String(res.error))) {
+        info('The deployed handler predates the db:exec ops action. Upgrade @everystack/server, or run local: db:exec <file> --database-url <url>.');
+      }
+      process.exit(1);
+    }
+    reportOk(res);
+    return;
+  }
+
+  // --- Direct venue (local dev): the same ceremony, CLI-side, unbounded clock. ---
+  step('Connecting via ' + (source.from === 'flag' ? '--database-url' : source.from) + ' (DML-only, one transaction)...');
+  const postgres = (await import('postgres')).default;
+  const sqlc = postgres(source.url, { max: 1, onnotice: () => {}, ...sslDefaults(source.url) });
+  try {
+    const audit = async (query: string): Promise<any[]> => Array.from(await sqlc.unsafe(query)) as any[];
+    const res = await executeExec({
+      sql: fileSql,
+      actor: actor ?? 'unknown',
+      stage: flags.stage ?? 'local',
+      writeIntent: async (intent) => {
+        for (const ddl of ENSURE_EXEC_LOG_SQL) await audit(ddl);
+        const rows = await audit(renderExecIntentInsert(intent));
+        return String(rows[0].id);
+      },
+      run: () =>
+        sqlc.begin(async (tx: any) => {
+          const txRun = async (stmt: string) => {
+            const r = await tx.unsafe(stmt);
+            return { rows: Array.from(r) as any[], count: (r as any).count ?? 0 };
+          };
+          return runExecInTx(txRun, fileSql, { schemas: directSchemas(flags) });
+        }) as Promise<number[]>,
+      writeOutcome: async (id, outcome) => {
+        await audit(renderExecOutcomeUpdate(id, outcome));
+      },
+    });
+    reportOk(res);
+  } catch (err: any) {
+    fail(`db:exec failed: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await sqlc.end({ timeout: 5 });
+  }
+}

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

@@ -26,9 +26,9 @@ import { fingerprintModels } from '../schema-fingerprint.js';
 import { resolveModelsPath } from '../models-path.js';
 import { loadModels } from './db-generate.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
-import { pgDumpPreflightError } from './db-backup.js';
 import { pgEnvFromUrl } from './db.js';
 import { utcStamp } from '../backup.js';
+import { pollTaskUntilStopped } from '../task-poll.js';
 import { step, success, fail, info } from '../output.js';
 
 const fmtBytes = (b?: number): string =>
@@ -190,30 +190,41 @@ export async function dbExportCommand(flags: Record<string, string>): Promise<vo
     process.exit(1);
   }
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  const fn = opsFunction(config);
 
-  // The dump needs the pg_dump layer — surface a missing/incompatible layer as a one-line remedy
-  // here, not a mid-dump crash (same preflight db:backup runs).
-  step('Checking the pg_dump layer...');
+  // The dump runs in the ephemeral Task lane (the ops Lambda holds no pg binaries). Dispatch the
+  // task and poll; the task's version handshake is the compatibility gate (no separate layer probe).
+  step('Dispatching the export task (credential-free, via the ops Lambda)...');
+  let dispatched: any;
   try {
-    const probe = await invokeAction(config.region, opsFunction(config), 'db:backup:probe', {});
-    const preflightError = pgDumpPreflightError(probe);
-    if (preflightError) { fail(preflightError); process.exit(1); }
+    dispatched = await invokeAction(config.region, fn, 'db:export', { schema, stage: venue.stage, fingerprint, actor: process.env.USER ?? null });
   } catch (err: any) {
-    fail(`Export pre-flight failed: ${err.message}`);
+    fail(`Export failed to dispatch: ${err.message}`);
     process.exit(1);
   }
+  if (dispatched?.error) {
+    fail(`Export failed: ${dispatched.error}`);
+    process.exit(1);
+  }
+  const { runId, taskArn, id, warning } = dispatched as { runId: string; taskArn: string; id: string; warning?: string };
+  info(`artifact ${id} — task ${taskArn}`);
+  info(`run id: ${runId} (everystack.task_log)`);
+  if (warning) info(`note: ${warning}`);
 
   step(`Running pg_dump --schema=${schema} → S3 (this may take a while for large schemas)...`);
-  let result: any;
-  try {
-    result = await invokeAction(config.region, opsFunction(config), 'db:export', { schema, stage: venue.stage, fingerprint });
-  } catch (err: any) {
-    fail(`Export failed: ${err.message}`);
+  const poll = await pollTaskUntilStopped(config.region, fn, { runId, taskArn });
+  if (poll.outcome === 'timeout') {
+    fail(`db:export timed out (last status: ${poll.lastStatus}). Run id ${runId} — reconcile via ECS/everystack.task_log.`);
+    process.exit(1);
+  }
+  if (poll.outcome === 'error') {
+    fail(`task:status failed repeatedly: ${poll.status.error}. The export may still be running — reconcile run id ${runId}.`);
     process.exit(1);
   }
-  if (result?.error) {
-    fail(`Export failed: ${result.error}`);
+  if (poll.status.exitCode !== 0) {
+    fail(`Export failed (exit ${poll.status.exitCode ?? 'unknown'})${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}. Read the task logs (CloudWatch).`);
     process.exit(1);
   }
-  success(`Artifact ${result.id} (${fmtBytes(result.bytes)}, fingerprint ${String(result.fingerprint).slice(0, 12)}). Deploy with: everystack db:swap --schema ${schema} --from ${result.id} --stage <target> --direct --confirm`);
+  const bytes = poll.status.result?.bytes as number | undefined;
+  success(`Artifact ${id} (${fmtBytes(bytes)}, fingerprint ${fingerprint.slice(0, 12)}). Deploy with: everystack db:swap --schema ${schema} --from ${id} --stage <target> --direct --confirm`);
 }