@everystack/server 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -72,6 +72,10 @@
     "./media": {
       "types": "./src/media.ts",
       "default": "./src/media.ts"
+    },
+    "./pipeline": {
+      "types": "./src/pipeline.ts",
+      "default": "./src/pipeline.ts"
     }
   },
   "peerDependencies": {
@@ -139,8 +143,8 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/auth": "0.3.1",
-    "@everystack/cli": "0.3.27"
+    "@everystack/cli": "0.3.31",
+    "@everystack/auth": "0.3.1"
   },
   "scripts": {
     "test": "jest",

package/src/backup-run.ts

@@ -37,8 +37,42 @@ export interface BackupSummary {
   lastModified?: string;
 }
 
+/**
+ * Lazily load an optional-peer AWS SDK client, turning a missing dependency into a one-line
+ * install remedy instead of a raw `ERR_MODULE_NOT_FOUND` deep in the ops Lambda. The `@aws-sdk/*`
+ * clients are optional peers of @everystack/server (a V1 app needs none of them), so a consumer
+ * whose ops function runs db:backup must install them — this names which, not "Cannot find
+ * package". Takes a thunk so the `import()` stays a literal — statically analyzable and typed.
+ */
+export async function importOptionalAws<T>(
+  load: () => Promise<T>,
+  pkg: string,
+  feature: string,
+): Promise<T> {
+  try {
+    return await load();
+  } catch (err: unknown) {
+    const code = (err as { code?: string })?.code;
+    const message = String((err as { message?: string })?.message ?? err);
+    if (
+      code === 'ERR_MODULE_NOT_FOUND' ||
+      code === 'MODULE_NOT_FOUND' ||
+      /Cannot find (package|module)/.test(message)
+    ) {
+      throw new Error(
+        `${feature} needs ${pkg}, which isn't installed (it's an optional peer dependency of @everystack/server). Install it:\n  pnpm add ${pkg}`,
+      );
+    }
+    throw err;
+  }
+}
+
 async function getS3(region?: string): Promise<any> {
-  const { S3Client } = await import('@aws-sdk/client-s3');
+  const { S3Client } = await importOptionalAws(
+    () => import('@aws-sdk/client-s3'),
+    '@aws-sdk/client-s3',
+    'db:backup',
+  );
   return new S3Client(region ? { region } : {});
 }
 
@@ -57,8 +91,16 @@ export async function runBackup(deps: BackupRunDeps, stage: string): Promise<Bac
   const id = backupId(stage, stamp, shortId);
 
   const s3 = await getS3(region);
-  const { Upload } = await import('@aws-sdk/lib-storage');
-  const { DeleteObjectCommand, PutObjectCommand, HeadObjectCommand } = await import('@aws-sdk/client-s3');
+  const { Upload } = await importOptionalAws(
+    () => import('@aws-sdk/lib-storage'),
+    '@aws-sdk/lib-storage',
+    'db:backup',
+  );
+  const { DeleteObjectCommand, PutObjectCommand, HeadObjectCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-s3'),
+    '@aws-sdk/client-s3',
+    'db:backup',
+  );
 
   const child = spawn('pg_dump', pgDumpArgs(), { env, stdio: ['ignore', 'pipe', 'pipe'] });
   let stderr = '';

package/src/pipeline.ts

@@ -0,0 +1,423 @@
+/**
+ * @everystack/server/pipeline — the ingest pipeline framework (Phase 3).
+ *
+ * A pipeline reproduces data from committed source: an ordered set of STAGES,
+ * each a function that reads source and writes rows idempotently. You never
+ * copy data between environments — you re-run the same committed source + the
+ * same stage code and get the same rows ("sync by reproduction").
+ *
+ * everystack owns the HARNESS — the stage contract, the topological order, the
+ * provenance-lane wall (automated/curated/frozen), resume, and the memoir
+ * (everystack.pipeline_log). The consumer owns the STAGES: their
+ * fetch/parse/transform/load code, their source files, their table and column
+ * names, their provenance values. Ingest logic never enters the framework,
+ * exactly as schema and migrations never do.
+ *
+ * A stage is a FUNCTION, not a spawned script, so the same stage runs unchanged
+ * in three places: a local process (`pipeline:run --database-url`), the ops
+ * Lambda (`pipeline:run --stage`, credential-free), or — later — a worker.
+ *
+ * See docs/plans/ingest-pipeline-framework.md.
+ */
+
+/** Read/write SQL against the target, inside whatever transaction the caller holds. */
+export type PipelineQuery = (sql: string) => Promise<any[]>;
+
+/**
+ * The connection the orchestrator drives. `transaction` runs a stage's writes
+ * and its memoir row as one atomic unit; `query` is for the pre-flight ensure
+ * and the best-effort failure record (which must land OUTSIDE the rolled-back
+ * stage transaction).
+ */
+export interface PipelineRunner {
+  query: PipelineQuery;
+  transaction: <T>(fn: (tx: PipelineQuery) => Promise<T>) => Promise<T>;
+}
+
+/** The provenance lane — the wall between the two reproduction audiences. */
+export type StageLane = 'automated' | 'curated' | 'frozen';
+
+/** What a stage reports back for the memoir (both optional — a stage may write nothing). */
+export interface StageResult {
+  /** Rows this stage wrote, for the memoir. */
+  rows?: number;
+  /** Content hash of the source this stage reproduced from — Phase 4's verify reads it. */
+  sourceHash?: string;
+}
+
+/** What a stage receives. The framework builds it; the consumer's run() uses it. */
+export interface StageContext {
+  /** The transactional runner for this stage's writes. */
+  runner: PipelineQuery;
+  /** This stage's provenance tag (`provenance` override, else `${lane}:${id}`). */
+  provenance: string;
+  /** True → compute/preview, write nothing. */
+  dryRun: boolean;
+  /** Emit a progress line. */
+  log: (message: string) => void;
+  /**
+   * The idempotency helper: delete the rows this stage owns before re-inserting.
+   * `DELETE FROM <table> WHERE <column> = <this stage's provenance>`. The stage
+   * owns the actual insert; the framework owns only the provenance-replace shape.
+   */
+  replaceProvenance: (table: string, column: string) => Promise<void>;
+}
+
+export interface Stage {
+  id: string;
+  lane: StageLane;
+  /** Data/topo edges — a dependency runs before its dependent. */
+  dependsOn?: string[];
+  /** Ordering-only edges (run after, but no data dependency). */
+  after?: string[];
+  /** Refuses the ops-Lambda executor — this stage is too big, run it local-direct. */
+  heavy?: boolean;
+  /** Provenance tag for the memoir + the replace helper. Default `${lane}:${id}`. */
+  provenance?: string;
+  run: (ctx: StageContext) => Promise<StageResult | void>;
+}
+
+export interface Pipeline {
+  stages: Stage[];
+}
+
+/** Identity for defineStage — a stage is a plain descriptor. */
+export function defineStage(stage: Stage): Stage {
+  return stage;
+}
+
+/** Compose stages into a pipeline, validating unique ids and resolvable edges. */
+export function definePipeline(stages: Stage[]): Pipeline {
+  const ids = new Set<string>();
+  for (const s of stages) {
+    if (ids.has(s.id)) throw new Error(`pipeline has a duplicate stage id: "${s.id}"`);
+    ids.add(s.id);
+  }
+  for (const s of stages) {
+    for (const dep of [...(s.dependsOn ?? []), ...(s.after ?? [])]) {
+      if (!ids.has(dep)) {
+        throw new Error(`stage "${s.id}" depends on "${dep}", which is not a stage in this pipeline`);
+      }
+    }
+  }
+  return { stages };
+}
+
+/** The provenance tag a stage writes under. */
+export function stageProvenance(stage: Stage): string {
+  return stage.provenance ?? `${stage.lane}:${stage.id}`;
+}
+
+/**
+ * Deterministic topological sort over dependsOn ∪ after edges. Stable: with no
+ * edge between two stages, declared order wins (so a re-run is byte-stable).
+ * Throws on an unknown edge or a cycle (naming a stage on the cycle).
+ */
+export function topoSortStages(stages: Stage[]): Stage[] {
+  const byId = new Map(stages.map((s) => [s.id, s]));
+  const indegree = new Map<string, number>(stages.map((s) => [s.id, 0]));
+  const dependents = new Map<string, string[]>(stages.map((s) => [s.id, []]));
+
+  for (const s of stages) {
+    for (const dep of [...(s.dependsOn ?? []), ...(s.after ?? [])]) {
+      if (!byId.has(dep)) {
+        throw new Error(`stage "${s.id}" depends on unknown stage "${dep}"`);
+      }
+      indegree.set(s.id, (indegree.get(s.id) ?? 0) + 1);
+      dependents.get(dep)!.push(s.id);
+    }
+  }
+
+  // Kahn's algorithm; the ready queue is kept in declared order for stability.
+  const declaredIndex = new Map(stages.map((s, i) => [s.id, i]));
+  const ready = stages.filter((s) => (indegree.get(s.id) ?? 0) === 0).map((s) => s.id);
+  const sorted: Stage[] = [];
+  while (ready.length > 0) {
+    ready.sort((a, b) => declaredIndex.get(a)! - declaredIndex.get(b)!);
+    const id = ready.shift()!;
+    sorted.push(byId.get(id)!);
+    for (const next of dependents.get(id)!) {
+      indegree.set(next, (indegree.get(next) ?? 0) - 1);
+      if (indegree.get(next) === 0) ready.push(next);
+    }
+  }
+
+  if (sorted.length !== stages.length) {
+    const remaining = stages.filter((s) => !sorted.includes(s)).map((s) => s.id);
+    throw new Error(`pipeline has a dependency cycle involving: ${remaining.join(', ')}`);
+  }
+  return sorted;
+}
+
+export interface SelectOptions {
+  /** rebuild → automated + frozen; curate → curated; else all lanes. */
+  lane?: 'rebuild' | 'curate' | 'all';
+  /** Keep stages whose id contains this substring. */
+  only?: string;
+  /** Slice the ordered list from this stage id (inclusive). */
+  from?: string;
+  /** Slice the ordered list to this stage id (inclusive). */
+  to?: string;
+}
+
+const laneKeeps = (lane: SelectOptions['lane'], stageLane: StageLane): boolean => {
+  if (lane === 'rebuild') return stageLane === 'automated' || stageLane === 'frozen';
+  if (lane === 'curate') return stageLane === 'curated';
+  return true;
+};
+
+/** Filter an already-ordered stage list by lane, --only, and --from/--to. */
+export function selectStages(ordered: Stage[], opts: SelectOptions): Stage[] {
+  let selected = ordered;
+  if (opts.from || opts.to) {
+    const start = opts.from ? selected.findIndex((s) => s.id === opts.from) : 0;
+    const endIdx = opts.to ? selected.findIndex((s) => s.id === opts.to) : selected.length - 1;
+    if (start === -1) throw new Error(`--from names no stage: "${opts.from}"`);
+    if (endIdx === -1) throw new Error(`--to names no stage: "${opts.to}"`);
+    selected = selected.slice(start, endIdx + 1);
+  }
+  selected = selected.filter((s) => laneKeeps(opts.lane, s.lane));
+  if (opts.only) selected = selected.filter((s) => s.id.includes(opts.only!));
+  return selected;
+}
+
+// ---------------------------------------------------------------------------
+// The memoir — everystack.pipeline_log (append-only, sibling to backfill_log).
+// ---------------------------------------------------------------------------
+
+export const ENSURE_PIPELINE_SQL: string[] = [
+  'CREATE SCHEMA IF NOT EXISTS everystack',
+  `CREATE TABLE IF NOT EXISTS everystack.pipeline_log (
+    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    applied_at timestamptz NOT NULL DEFAULT now(),
+    run_id text NOT NULL,
+    stage_id text NOT NULL,
+    lane text NOT NULL,
+    source_hash text,
+    rows integer,
+    actor text,
+    git_ref text,
+    duration_ms integer,
+    outcome text NOT NULL
+  )`,
+];
+
+const sqlStr = (v: string | null | undefined): string =>
+  v === null || v === undefined ? 'NULL' : `'${String(v).replace(/'/g, "''")}'`;
+const sqlNum = (v: number | null | undefined): string =>
+  v === null || v === undefined || !Number.isFinite(v) ? 'NULL' : String(Math.trunc(v));
+
+export interface PipelineLogEntry {
+  runId: string;
+  stageId: string;
+  lane: StageLane;
+  sourceHash?: string | null;
+  rows?: number | null;
+  actor?: string | null;
+  gitRef?: string | null;
+  durationMs?: number | null;
+  outcome: 'applied' | 'failed';
+}
+
+export function renderPipelineLogInsert(e: PipelineLogEntry): string {
+  return `INSERT INTO everystack.pipeline_log (run_id, stage_id, lane, source_hash, rows, actor, git_ref, duration_ms, outcome)
+    VALUES (${sqlStr(e.runId)}, ${sqlStr(e.stageId)}, ${sqlStr(e.lane)}, ${sqlStr(e.sourceHash)}, ${sqlNum(e.rows)}, ${sqlStr(e.actor)}, ${sqlStr(e.gitRef)}, ${sqlNum(e.durationMs)}, ${sqlStr(e.outcome)})`;
+}
+
+/**
+ * The most recently touched run_id in the memoir — what `--resume` picks up
+ * with no explicit run id. Null when the pipeline has never run here.
+ */
+export async function latestRunId(query: PipelineQuery): Promise<string | null> {
+  try {
+    const rows = await query('SELECT run_id FROM everystack.pipeline_log ORDER BY id DESC LIMIT 1');
+    return rows.length > 0 ? String(rows[0].run_id) : null;
+  } catch {
+    // No memoir yet (table absent) — nothing to resume.
+    return null;
+  }
+}
+
+/** A one-line summary of a pipeline's most recent run — the visibility surface. */
+export interface PipelineRunSummary {
+  runId: string;
+  /** applied_at of the run's last row (a string as the driver returns it). */
+  at: string | null;
+  /** Stages whose LATEST attempt under this run succeeded. */
+  applied: number;
+  /** Stages whose LATEST attempt failed (an incomplete run — resume). */
+  failed: number;
+  failedStages: string[];
+}
+
+/**
+ * Summarize the most recent run for db:sync / db:plan to surface — the analog
+ * of the pending-backfill nudge. Read-only; null when the pipeline has never
+ * run here (or the memoir table is absent). Counts the LATEST attempt per stage
+ * so a resumed-and-fixed stage reads as applied, not failed.
+ */
+export async function readLastRun(query: PipelineQuery): Promise<PipelineRunSummary | null> {
+  try {
+    const latest = await query('SELECT run_id FROM everystack.pipeline_log ORDER BY id DESC LIMIT 1');
+    if (latest.length === 0) return null;
+    const runId = String(latest[0].run_id);
+    const rows = await query(
+      `SELECT stage_id, outcome, applied_at FROM everystack.pipeline_log WHERE run_id = ${sqlStr(runId)} ORDER BY id`,
+    );
+    const latestByStage = new Map<string, string>();
+    let at: string | null = null;
+    for (const r of rows) {
+      latestByStage.set(String(r.stage_id), String(r.outcome));
+      if (r.applied_at != null) at = String(r.applied_at);
+    }
+    const failedStages = [...latestByStage].filter(([, o]) => o === 'failed').map(([s]) => s);
+    const applied = [...latestByStage.values()].filter((o) => o === 'applied').length;
+    return { runId, at, applied, failed: failedStages.length, failedStages };
+  } catch {
+    return null;
+  }
+}
+
+/** The stage ids that already succeeded under a given run — the resume set. */
+export async function readAppliedStages(query: PipelineQuery, runId: string): Promise<Set<string>> {
+  const rows = await query(
+    `SELECT stage_id FROM everystack.pipeline_log WHERE run_id = ${sqlStr(runId)} AND outcome = 'applied'`,
+  );
+  return new Set(rows.map((r: any) => String(r.stage_id)));
+}
+
+// ---------------------------------------------------------------------------
+// The orchestrator — pure over an injected runner, identical local and ops-routed.
+// ---------------------------------------------------------------------------
+
+export interface RunPipelineOptions extends SelectOptions {
+  /** Groups a multi-stage run for resume; caller supplies it (a uuid). */
+  runId: string;
+  /** Skip stages already applied under runId. */
+  resume?: boolean;
+  /** Print the plan, run nothing. */
+  dryRun?: boolean;
+  /** Keep going past a failed stage (default: fail-fast). */
+  continueOnError?: boolean;
+  actor?: string | null;
+  gitRef?: string | null;
+  /** Injectable clock for tests. */
+  now?: () => number;
+  /** Emit a progress line. */
+  log?: (message: string) => void;
+}
+
+export type StageOutcome = 'applied' | 'skipped' | 'failed' | 'dry-run';
+
+export interface StageRunResult {
+  stageId: string;
+  outcome: StageOutcome;
+  rows?: number;
+  durationMs?: number;
+  error?: string;
+}
+
+export interface PipelineRunOutcome {
+  runId: string;
+  /** The ordered, selected stage ids — the plan. */
+  plan: string[];
+  results: StageRunResult[];
+  failed: boolean;
+}
+
+/**
+ * Reproduce the pipeline against the target: topo-order, filter to the selected
+ * lane/range, then run each stage inside its own transaction — the stage's
+ * writes AND its memoir row commit together. A throw rolls the stage back,
+ * records a best-effort `failed` row outside the transaction, and (unless
+ * continueOnError) stops, marking the rest skipped. dry-run returns the plan and
+ * runs nothing.
+ */
+export async function runPipeline(
+  runner: PipelineRunner,
+  pipeline: Pipeline,
+  options: RunPipelineOptions,
+): Promise<PipelineRunOutcome> {
+  const now = options.now ?? Date.now;
+  const log = options.log ?? (() => {});
+  const ordered = topoSortStages(pipeline.stages);
+  const selected = selectStages(ordered, options);
+  const plan = selected.map((s) => s.id);
+
+  if (options.dryRun) {
+    return {
+      runId: options.runId,
+      plan,
+      results: selected.map((s) => ({ stageId: s.id, outcome: 'dry-run' as const })),
+      failed: false,
+    };
+  }
+
+  await runner.query(ENSURE_PIPELINE_SQL.join(';\n'));
+  const alreadyApplied = options.resume
+    ? await readAppliedStages(runner.query, options.runId)
+    : new Set<string>();
+
+  const results: StageRunResult[] = [];
+  let stopped = false;
+
+  for (const stage of selected) {
+    if (stopped) {
+      results.push({ stageId: stage.id, outcome: 'skipped' });
+      continue;
+    }
+    if (options.resume && alreadyApplied.has(stage.id)) {
+      results.push({ stageId: stage.id, outcome: 'skipped' });
+      continue;
+    }
+
+    const provenance = stageProvenance(stage);
+    const started = now();
+    try {
+      const result = await runner.transaction(async (tx) => {
+        const ctx: StageContext = {
+          runner: tx,
+          provenance,
+          dryRun: false,
+          log,
+          replaceProvenance: async (table, column) => {
+            await tx(`DELETE FROM ${table} WHERE ${column} = ${sqlStr(provenance)}`);
+          },
+        };
+        const r = (await stage.run(ctx)) ?? {};
+        await tx(renderPipelineLogInsert({
+          runId: options.runId,
+          stageId: stage.id,
+          lane: stage.lane,
+          sourceHash: r.sourceHash ?? null,
+          rows: r.rows ?? null,
+          actor: options.actor ?? null,
+          gitRef: options.gitRef ?? null,
+          durationMs: now() - started,
+          outcome: 'applied',
+        }));
+        return r;
+      });
+      results.push({ stageId: stage.id, outcome: 'applied', rows: result.rows, durationMs: now() - started });
+    } catch (err: any) {
+      const message = String(err?.message ?? err);
+      // Best-effort failure memoir, OUTSIDE the rolled-back stage transaction.
+      try {
+        await runner.query(ENSURE_PIPELINE_SQL.join(';\n'));
+        await runner.query(renderPipelineLogInsert({
+          runId: options.runId,
+          stageId: stage.id,
+          lane: stage.lane,
+          durationMs: now() - started,
+          outcome: 'failed',
+        }));
+      } catch {
+        // the memoir is best-effort on failure
+      }
+      results.push({ stageId: stage.id, outcome: 'failed', durationMs: now() - started, error: message });
+      if (!options.continueOnError) stopped = true;
+    }
+  }
+
+  return { runId: options.runId, plan, results, failed: results.some((r) => r.outcome === 'failed') };
+}

package/src/plugin.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Handler, Route, LogSink, ServerCacheConfig } from './index';
+import type { Pipeline } from './pipeline';
 import type {
   APIGatewayProxyEventV2,
   APIGatewayProxyStructuredResultV2,
@@ -490,6 +491,13 @@ export interface DbPluginOptions {
   backupBucket?: string;
   /** AWS region for the backups bucket (defaults to the Lambda's AWS_REGION). */
   backupRegion?: string;
+  /**
+   * The app's ingest pipeline (built with definePipeline). When provided, registers the
+   * credential-free `pipeline:run` action: the orchestrator runs IN this Lambda over the
+   * operator connection, so a deployed stage's small curated overlays reproduce via IAM,
+   * never a held database URL. Stages marked `heavy` are refused here (run them local-direct).
+   */
+  pipeline?: Pipeline;
 }
 
 /**
@@ -508,6 +516,24 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // connection can be least-privilege and RLS-gated.
     const opsDb = ctx.adminDb ?? ctx.db;
 
+    // Resolve the logical-backup dependencies (bucket + operator URL) once —
+    // shared by db:backup/db:backups/db:restore and by db:apply's auto-snapshot
+    // before a destructive staged apply. Returns `{ error }` when unconfigured.
+    const resolveBackupDeps = async (): Promise<
+      { deps: { bucket: string; region?: string; adminUrl: string } } | { error: string }
+    > => {
+      const bucket = options.backupBucket;
+      if (!bucket) {
+        return { error: 'backup storage not configured — pass backupBucket to dbPlugin (e.g. Resource.Backups.name)' };
+      }
+      const { getAdminDatabaseUrl, getMasterDatabaseUrl } = await import('./db');
+      const adminUrl = getAdminDatabaseUrl() ?? getMasterDatabaseUrl();
+      if (!adminUrl) {
+        return { error: 'no operator connection available (ADMIN_DATABASE_URL / Resource.Database)' };
+      }
+      return { deps: { bucket, region: options.backupRegion ?? process.env.AWS_REGION, adminUrl } };
+    };
+
     // --- migrate ---
     actions.migrate = async (_payload, _ctx) => {
       const { runMigrations } = await import('./migrate');
@@ -759,19 +785,6 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // dedicated private backups bucket. Restore is destructive and requires an explicit confirm in
     // the payload (the CLI sets it after the user confirms). See backup-run.ts.
     {
-      const resolveBackupDeps = async () => {
-        const bucket = options.backupBucket;
-        if (!bucket) {
-          return { error: 'backup storage not configured — pass backupBucket to dbPlugin (e.g. Resource.Backups.name)' as string };
-        }
-        const { getAdminDatabaseUrl, getMasterDatabaseUrl } = await import('./db');
-        const adminUrl = getAdminDatabaseUrl() ?? getMasterDatabaseUrl();
-        if (!adminUrl) {
-          return { error: 'no operator connection available (ADMIN_DATABASE_URL / Resource.Database)' as string };
-        }
-        return { deps: { bucket, region: options.backupRegion ?? process.env.AWS_REGION, adminUrl } };
-      };
-
       actions['db:backup'] = async (payload, ctx) => {
         const r = await resolveBackupDeps();
         if ('error' in r) return { error: r.error };
@@ -814,6 +827,123 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       };
     }
 
+    // --- db:apply — the credential-free staged write (Phase 2) ---
+    // The staged half of db:apply: the CLI computes the plan and the
+    // checkout-bound verdicts (the fast-forward/descent rule, the destructive
+    // approver check — neither can be recomputed here: one needs the git
+    // checkout, the other the caller's real IAM identity); THIS action does the
+    // write against the operator connection. Verify the concurrency lock, apply
+    // the DDL in one transaction, stamp everystack.schema_log with the plan_ref,
+    // and verify the target landed on plan.to — the same executeApplyPlan the
+    // direct --database-url path runs, only here the connection never leaves the
+    // Lambda. A destructive plan snapshots first (db:backup), in order.
+    actions['db:apply'] = async (payload, ctx) => {
+      const { plan, actor, gitRef, descentVerdict, authorityVerdict, stage } =
+        (payload ?? {}) as {
+          plan?: any;
+          actor?: string | null;
+          gitRef?: string | null;
+          descentVerdict?: { ok: boolean; reason?: string };
+          authorityVerdict?: { ok: boolean; reason?: string };
+          stage?: string;
+        };
+      if (!plan || typeof plan !== 'object' || !Array.isArray(plan.statements)) {
+        return { error: 'db:apply requires { plan } — a reviewed edge minted by db:plan' };
+      }
+      const { executeApplyPlan, PLAN_VERSION } = await import('@everystack/cli/apply');
+      if (plan.v !== PLAN_VERSION) {
+        return { error: `plan version ${plan.v} is not this server's ${PLAN_VERSION} — re-mint with a matching db:plan` };
+      }
+
+      const { sql } = await import('drizzle-orm');
+      const runner = async (query: string): Promise<any[]> => {
+        const result: any = await opsDb.execute(sql.raw(query));
+        return Array.isArray(result) ? result : result?.rows ?? [];
+      };
+
+      const destructive = Number(plan.destructive) > 0;
+      let snapshotId: string | undefined;
+      try {
+        const result = await executeApplyPlan(runner, plan, {
+          actor: actor ?? null,
+          gitRef: gitRef ?? null,
+          // Descent/authority are decided by the CLI (checkout + caller identity)
+          // and enforced + recorded here, in order, atomic with the lock.
+          ...(descentVerdict
+            ? { verifyDescent: async () => (descentVerdict.ok ? { ok: true as const } : { ok: false as const, reason: descentVerdict.reason ?? 'descent refused' }) }
+            : {}),
+          ...(destructive && authorityVerdict
+            ? { verifyAuthority: async () => (authorityVerdict.ok ? { ok: true as const } : { ok: false as const, reason: authorityVerdict.reason ?? 'authority refused' }) }
+            : {}),
+          // Losing data is hard: the snapshot runs HERE, after the lock/descent/
+          // authority gates pass and before the DDL. It uses the same logical
+          // backup as db:backup, on the operator connection.
+          ...(destructive
+            ? {
+                beforeDestructive: async () => {
+                  const r = await resolveBackupDeps();
+                  if ('error' in r) {
+                    throw new Error(`snapshot before a destructive apply is impossible — ${r.error}`);
+                  }
+                  const { runBackup } = await import('./backup-run');
+                  const backup: any = await runBackup(r.deps, stage ?? ctx.environment ?? 'default');
+                  snapshotId = backup?.id;
+                },
+              }
+            : {}),
+        });
+        return snapshotId ? { ...result, snapshotId } : result;
+      } catch (err: any) {
+        return { error: err?.message || String(err) };
+      }
+    };
+
+    // --- pipeline:run — the credential-free ingest reproduction (Phase 3, Brick 5) ---
+    // The orchestrator runs HERE, in the ops Lambda, over the operator connection: a
+    // deployed stage's small curated overlays reproduce via IAM, never a held URL. The
+    // pipeline definition is the one the app bundled into this Lambda (like `seed`); the
+    // CLI passes only the run options. A `heavy` stage is refused — it belongs local-direct.
+    if (options.pipeline) {
+      const pipeline = options.pipeline;
+      actions['pipeline:run'] = async (payload, _ctx) => {
+        const runOpts: any = { ...((payload ?? {}) as Record<string, unknown>) };
+        const { runPipeline, topoSortStages, selectStages, latestRunId } = await import('./pipeline');
+
+        let selected;
+        try {
+          selected = selectStages(topoSortStages(pipeline.stages), runOpts);
+        } catch (err: any) {
+          return { error: err?.message || String(err) };
+        }
+        const heavy = selected.filter((s) => s.heavy).map((s) => s.id);
+        if (heavy.length > 0) {
+          return { error: `stage(s) ${heavy.join(', ')} are marked heavy — too big for the ops Lambda. Run them local-direct: pipeline:run --database-url <url>.` };
+        }
+
+        const { sql } = await import('drizzle-orm');
+        const asRows = (r: any): any[] => (Array.isArray(r) ? r : r?.rows ?? []);
+        const runner = {
+          query: async (q: string) => asRows(await opsDb.execute(sql.raw(q))),
+          transaction: async <T>(fn: (tx: (q: string) => Promise<any[]>) => Promise<T>): Promise<T> =>
+            opsDb.transaction(async (tx: any) => fn(async (q: string) => asRows(await tx.execute(sql.raw(q))))),
+        };
+
+        // Resume with no explicit run id picks up the latest run on THIS stage.
+        if (runOpts.resume && !runOpts.runId) {
+          const latest = await latestRunId(runner.query);
+          if (!latest) return { error: 'nothing to resume — this pipeline has not run on this stage yet.' };
+          runOpts.runId = latest;
+        }
+        if (!runOpts.runId) return { error: 'pipeline:run requires a runId' };
+
+        try {
+          return await runPipeline(runner, pipeline, runOpts);
+        } catch (err: any) {
+          return { error: err?.message || String(err) };
+        }
+      };
+    }
+
     // --- console ---
     if (options.allowConsole !== false) {
       actions['console:meta'] = async (_payload, ctx) => {