@everystack/cli 0.3.28 → 0.4.0

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

@@ -2,15 +2,15 @@
  * `everystack db:sync` — make the database match your checkout. One verb,
  * both layers, for dev-stage databases (brick 5's core).
  *
- *   db:sync [--database-url <url>] [--models <barrel>] [--sql-dir db/sql]
- *           [--allow-drops] [--overwrite-drift] [--baseline] [--json]
+ *   db:sync [--database-url <url>] [--models <barrel>]
+ *           [--allow-drops] [--overwrite-drift] [--baseline] [--rebaseline] [--json]
  *
  * The edit loop's verb: fingerprint the live base state, apply the state
  * diff (tables + authz, one transaction, verified by re-diff), reconcile
- * the derived layer (functions/views/matviews) against db/sql, and report
- * where the database now is — "at fingerprint X, matching your checkout"
- * when everything converged. Hot-reload for the database; no artifact
- * produced, every act recorded in `everystack.schema_log`.
+ * the derived layer against the declared descriptors, and report where the
+ * database now is — "at fingerprint X, matching your checkout" when
+ * everything converged. Hot-reload for the database; no artifact produced,
+ * every act recorded in `everystack.schema_log`.
  *
  * The verdict is two-tier, honestly: CONVERGED means the state re-diff is
  * empty and the compute layer is clean — that is the exit-0 bar. The
@@ -34,6 +34,8 @@ import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { introspectSchema } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { generateMigrationSql, unmodeledTables } from '../migration-generate.js';
+import type { SequenceDescriptor } from '@everystack/model';
+import type { SourceObject } from '../derived-source.js';
 import {
   applyStateAndVerify,
   classifyGeneratedStatements,
@@ -45,14 +47,15 @@ import {
 import { fingerprintModels } from '../schema-fingerprint.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import type { SourceFile } from '../derived-source.js';
-import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { planBackfills, readBackfillLog } from '../backfill.js';
 import { resolveModelsPath } from '../models-path.js';
 import { executeReconcile, buildReconcileReport, type ReconcileRun } from './db-reconcile.js';
 import { loadModels } from './db-generate.js';
+import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
+import { reportPipelineLastRun } from './pipeline-run.js';
 import { step, success, fail, info, warn } from '../output.js';
 
-const DEFAULT_SQL_DIR = 'db/sql';
 const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 
 // ---------------------------------------------------------------------------
@@ -63,8 +66,17 @@ export interface SyncOptions {
   allowDrops?: boolean;
   overwriteDrift?: boolean;
   baseline?: boolean;
+  /** Re-record provenance for source re-renders over verifiably-untouched live objects
+   *  (the db/sql-era migration) — see ReconcileOptions.rebaseline. */
+  rebaseline?: boolean;
   actor?: string | null;
   gitRef?: string | null;
+  /** Descriptor-compiled derived objects (the declared layer) — the one compute stream. */
+  declared?: SourceObject[];
+  /** Standalone sequences the modules declare (state — created before tables, fingerprinted). */
+  sequences?: SequenceDescriptor[];
+  /** Pending table renames — trigger provenance migrates instead of drop+create. */
+  renamedTables?: Record<string, string>;
   /** Injectable clock for tests. */
   now?: () => number;
 }
@@ -78,7 +90,7 @@ export interface SyncHooks {
 
 export interface SyncRun {
   state: StateSyncOutcome;
-  /** null = no db/sql sources — the compute layer is not declared, skipped. */
+  /** null = no declared derived layer — the compute step is skipped. */
   compute: ReconcileRun | null;
   declaredFingerprint: string;
   fingerprintMatch: boolean;
@@ -99,31 +111,34 @@ export interface SyncRun {
 export async function executeSync(
   runner: QueryRunner,
   models: ModelDescriptor[],
-  sources: SourceFile[] | null,
   options: SyncOptions = {},
   hooks: SyncHooks = {},
 ): Promise<SyncRun> {
   const current = await introspectSchema(runner);
   const liveAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
   const statements = generateMigrationSql(models, current, {
-    allowDrops: options.allowDrops, liveAuthz,
+    allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
   });
   hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
 
   const state = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
-    allowDrops: options.allowDrops,
+    allowDrops: options.allowDrops, sequences: options.sequences,
     actor: options.actor, gitRef: options.gitRef, now: options.now,
   });
   hooks.onStateDone?.(state);
 
-  const compute = sources === null ? null : await executeReconcile(runner, sources, {
+  // The declared derived layer is the one compute stream; nothing declared = skipped.
+  const compute = !options.declared?.length ? null : await executeReconcile(runner, {
     apply: true,
     baseline: options.baseline,
+    rebaseline: options.rebaseline,
     overwriteDrift: options.overwriteDrift,
+    declared: options.declared,
+    renamedTables: options.renamedTables,
     actor: options.actor, gitRef: options.gitRef, now: options.now,
   });
 
-  const declaredFingerprint = fingerprintModels(models).hash;
+  const declaredFingerprint = fingerprintModels(models, { sequences: options.sequences }).hash;
   const stateConverged = state.remaining.length === 0;
   // The compute bar, judged AFTER the apply: no refusal (drift/blocked stop the
   // whole batch) and nothing left unadopted (needsBaseline objects were not
@@ -181,7 +196,7 @@ export function buildSyncReport(run: SyncRun): string[] {
 
   // Compute.
   if (compute === null) {
-    lines.push('· compute: no db/sql directory — derived layer not declared, skipped');
+    lines.push('· compute: no derived layer declared — nothing to reconcile');
   } else {
     lines.push('compute:');
     for (const line of buildReconcileReport(compute.plan)) lines.push(`  ${line}`);
@@ -249,34 +264,55 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
   const modelsPath = resolveModelsPath(flags.models);
   const schemaOut = path.resolve(flags['schema-out'] || DEFAULT_SCHEMA_OUT);
   let models: ModelDescriptor[];
+  // The declared derived layer + sequences + renames — the same stream db:reconcile
+  // consumes. Loaded before the schema write: typed derived relations emit into it.
+  let declaredDb: DeclaredDerived | null = null;
   try {
     step(`Loading models from ${modelsPath}...`);
     models = await loadModels(modelsPath);
+    declaredDb = await loadDeclaredDerived(flags.models);
     info(`${models.length} model(s).`);
     // Same contract as db:generate: the drizzle runtime schema is a derived
     // artifact, refreshed from the models on every run.
     step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-    await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
+    await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: declaredDb?.derived }), 'utf8');
   } catch (err: any) {
     fail(err.message);
     process.exit(1);
   }
 
-  const sqlDir = flags['sql-dir'] || DEFAULT_SQL_DIR;
-  const sources = await readSqlDirIfPresent(sqlDir);
+  // B7 tombstone — db/sql is retired and no longer read; failing beats silently
+  // skipping (skipped files would leave live objects unmanaged).
+  try {
+    if (flags['sql-dir']) {
+      fail(await retiredSqlDirFlagRefusal(flags['sql-dir']));
+      process.exit(1);
+    }
+    const retired = await retiredSqlDirAnywhere(flags.models);
+    if (retired) {
+      fail(retired);
+      process.exit(1);
+    }
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
 
-  step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+  step(connectingVia(dbSource));
   const { runner, end } = await createUrlRunner(dbSource.url);
 
   try {
     const run = await executeSync(
       runner,
       models,
-      sources,
       {
+        declared: declaredDb?.objects,
+        sequences: declaredDb?.sequences,
+        renamedTables: declaredDb?.renamedTables,
         allowDrops: flags['allow-drops'] === 'true',
         overwriteDrift: flags['overwrite-drift'] === 'true',
         baseline: flags.baseline === 'true',
+        rebaseline: flags.rebaseline === 'true',
         actor: process.env.USER ?? null,
         gitRef: currentGitRef(),
       },
@@ -295,7 +331,7 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
           }
         },
         onStateDone: () => {
-          if (sources !== null) step(`Reconciling the derived layer against ${sqlDir}...`);
+          if (declaredDb?.objects.length) step('Reconciling the declared derived layer...');
         },
       },
     );
@@ -343,6 +379,7 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
       if (backfills && backfills.pending > 0) {
         info(`· ${backfills.pending} backfill(s) pending — data jobs run deliberately, never as a sync side effect: everystack db:backfill --apply`);
       }
+      await reportPipelineLastRun(runner);
       console.log('');
       if (!run.converged) {
         fail('NOT converged — fix the findings above and re-run db:sync.');

package/src/cli/commands/deploy.ts

@@ -12,6 +12,7 @@
 
 import { spawn } from 'node:child_process';
 import { step, success, fail, info } from '../output.js';
+import { invalidateCachedConfig } from '../discover.js';
 
 /** The `sst` argv `everystack deploy` runs. Pure, so the mapping is unit-tested. */
 export function buildDeployArgs(flags: Record<string, string>): string[] {
@@ -42,5 +43,8 @@ export async function deployCommand(flags: Record<string, string>): Promise<void
     });
   });
   success(`Deployed stage "${stage}".`);
+  // A deploy can change topology (a new Ops/Worker function, rotated Lambda hashes) that a
+  // stale per-stage cache would shadow — bust it so the next stage command re-discovers live.
+  await invalidateCachedConfig(stage);
   info('Next: `everystack db:migrate --stage ' + stage + '` to apply migrations, `everystack update` to publish the app bundle.');
 }

package/src/cli/commands/pipeline-run.ts

@@ -0,0 +1,269 @@
+/**
+ * `everystack pipeline:run` / `pipeline:list` — reproduce data from committed
+ * source (Phase 3, Brick 2, local-direct).
+ *
+ *   pipeline:run  [--database-url <url>] [--rebuild | --curate]
+ *                 [--only <substr> | --from <id> | --to <id>]
+ *                 [--resume [--run-id <id>]] [--dry-run] [--continue-on-error] [--json]
+ *   pipeline:list [--rebuild | --curate] [--only | --from | --to]
+ *
+ * The orchestrator (topo order, the provenance-lane wall, resume, the memoir)
+ * lives in @everystack/server/pipeline and runs identically here (local, over a
+ * --database-url) and — later, Brick 5 — in the ops Lambda. This command loads
+ * the consumer's pipeline definition (as db:generate loads the models barrel),
+ * builds a transactional runner, and drives runPipeline.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveDbSource, createUrlPipelineRunner, connectingVia, type DbSource } from '../db-source.js';
+import { resolvePipelinePath, PIPELINE_HOMES } from '../pipeline-path.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { currentGitRef } from '../state-apply.js';
+import { step, success, fail, info, warn } from '../output.js';
+import {
+  loadServerPipeline,
+  type Pipeline,
+  type PipelineLane,
+  type RunPipelineOptions,
+  type PipelineRunOutcome,
+} from '../pipeline-loader.js';
+
+/** --rebuild → rebuild, --curate → curate, neither → all. Both is a contradiction. */
+export function pipelineLaneFromFlags(flags: Record<string, string>): PipelineLane {
+  const rebuild = flags.rebuild === 'true';
+  const curate = flags.curate === 'true';
+  if (rebuild && curate) {
+    throw new Error('--rebuild and --curate are mutually exclusive — a run targets one lane, or omit both to run all in order.');
+  }
+  if (rebuild) return 'rebuild';
+  if (curate) return 'curate';
+  return 'all';
+}
+
+/** Map the CLI flags to the orchestrator's run options (pure; runId injected). */
+export function pipelineRunOptions(flags: Record<string, string>, runId: string): RunPipelineOptions {
+  return {
+    runId,
+    lane: pipelineLaneFromFlags(flags),
+    ...(flags.only ? { only: flags.only } : {}),
+    ...(flags.from ? { from: flags.from } : {}),
+    ...(flags.to ? { to: flags.to } : {}),
+    resume: flags.resume === 'true',
+    dryRun: flags['dry-run'] === 'true',
+    continueOnError: flags['continue-on-error'] === 'true',
+    actor: process.env.USER ?? null,
+    gitRef: currentGitRef(),
+  };
+}
+
+/** Load the consumer's pipeline definition — `pipeline` (or default) from the barrel. */
+export async function loadPipeline(pipelinePath: string): Promise<Pipeline> {
+  const abs = path.resolve(pipelinePath);
+  let mod: any;
+  try {
+    mod = await import(pathToFileURL(abs).href);
+  } catch (err: any) {
+    throw new Error(`Could not load the pipeline from ${pipelinePath}: ${err.message}`);
+  }
+  const pipeline = mod.pipeline ?? mod.default;
+  if (!pipeline || !Array.isArray(pipeline.stages)) {
+    throw new Error(`${pipelinePath} must export a \`pipeline\` built with definePipeline (got ${typeof pipeline}).`);
+  }
+  return pipeline;
+}
+
+function renderOutcome(outcome: PipelineRunOutcome, json: boolean, dryRun: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(outcome, null, 2));
+    return;
+  }
+  if (dryRun) {
+    info(`plan — ${outcome.plan.length} stage(s) in run order:`);
+    for (const id of outcome.plan) info(`  · ${id}`);
+    success('dry run — nothing executed.');
+    return;
+  }
+  for (const r of outcome.results) {
+    if (r.outcome === 'applied') info(`  ✓ ${r.stageId}${r.rows != null ? ` (${r.rows} row(s))` : ''}`);
+    else if (r.outcome === 'skipped') info(`  · ${r.stageId} (skipped)`);
+    else if (r.outcome === 'failed') fail(`  ✗ ${r.stageId}: ${r.error}`);
+  }
+  const applied = outcome.results.filter((r) => r.outcome === 'applied').length;
+  if (outcome.failed) fail('pipeline run FAILED — fix the stage and re-run with --resume.');
+  else success(`pipeline run complete — ${applied} stage(s) applied.`);
+}
+
+/**
+ * Surface the pipeline's most recent run — the analog of the pending-backfill
+ * nudge in db:sync / db:plan. Gated on a pipeline existing (non-pipeline
+ * consumers pay nothing) and best-effort (a missing memoir is silent).
+ */
+export async function reportPipelineLastRun(query: (sql: string) => Promise<any[]>): Promise<void> {
+  if (!PIPELINE_HOMES.some((home) => existsSync(home))) return;
+  try {
+    const { readLastRun } = await loadServerPipeline();
+    const last = await readLastRun(query);
+    if (!last) return;
+    if (last.failed > 0) {
+      warn(`pipeline: last run left ${last.failed} stage(s) failed (${last.failedStages.join(', ')}) — resume: everystack pipeline:run --resume`);
+    } else {
+      info(`· pipeline: last run applied ${last.applied} stage(s)${last.at ? ` at ${last.at}` : ''}.`);
+    }
+  } catch {
+    // Visibility is best-effort — never let it break the schema verb.
+  }
+}
+
+/**
+ * pipeline:run --stage: the orchestrator runs in the ops Lambda, credential-free.
+ * The Lambda owns the bundled pipeline (registered via dbPlugin, like `seed`);
+ * the CLI passes only the run options and renders the outcome. Resume with no
+ * explicit run id is resolved Lambda-side against everystack.pipeline_log.
+ */
+async function pipelineRunViaStage(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  const { region } = config;
+  const fn = opsFunction(config);
+
+  const resume = flags.resume === 'true';
+  const dryRun = flags['dry-run'] === 'true';
+  const options: RunPipelineOptions = {
+    // Fresh runs get a client-minted id; resume with no --run-id is resolved
+    // in the Lambda (it reads the latest run on the stage).
+    runId: flags['run-id'] ?? (resume ? '' : randomUUID()),
+    lane: pipelineLaneFromFlags(flags),
+    ...(flags.only ? { only: flags.only } : {}),
+    ...(flags.from ? { from: flags.from } : {}),
+    ...(flags.to ? { to: flags.to } : {}),
+    resume,
+    dryRun,
+    continueOnError: flags['continue-on-error'] === 'true',
+    actor: process.env.USER ?? null,
+    gitRef: currentGitRef(),
+  };
+  // Drop an empty runId so the Lambda's resume resolution kicks in.
+  const payload: Record<string, unknown> = { ...options };
+  if (!payload.runId) delete payload.runId;
+
+  step('Running the pipeline in the ops Lambda (credential-free — no database URL held)...');
+  const outcome: any = await invokeAction(region, fn, 'pipeline:run', payload);
+  if (outcome?.error) {
+    fail(`pipeline:run failed: ${outcome.error}`);
+    process.exit(1);
+  }
+  renderOutcome(outcome as PipelineRunOutcome, flags.json === 'true', dryRun);
+  if (outcome.failed) process.exit(1);
+}
+
+export async function pipelineRunCommand(flags: Record<string, string>): Promise<void> {
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  // Validate the lane before anything.
+  try {
+    pipelineLaneFromFlags(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // Deployed stage: the orchestrator runs credential-free in the ops Lambda —
+  // no URL held here. The Lambda owns the bundled pipeline; we pass options only.
+  if (dbSource.kind === 'stage') {
+    await pipelineRunViaStage(flags);
+    return;
+  }
+
+  const pipelinePath = resolvePipelinePath(flags.pipeline);
+  let pipeline: Pipeline;
+  try {
+    step(`Loading pipeline from ${pipelinePath}...`);
+    pipeline = await loadPipeline(pipelinePath);
+    info(`${pipeline.stages.length} stage(s).`);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  step(connectingVia(dbSource));
+  const runner = await createUrlPipelineRunner(dbSource.url);
+  try {
+    const { runPipeline, latestRunId } = await loadServerPipeline();
+
+    let runId = flags['run-id'];
+    const resume = flags.resume === 'true';
+    if (!runId) {
+      if (resume) {
+        const latest = await latestRunId(runner.query);
+        if (!latest) {
+          fail('nothing to resume — this pipeline has not run against this database yet.');
+          process.exit(1);
+        }
+        runId = latest;
+        info(`resuming run ${runId.slice(0, 8)}.`);
+      } else {
+        runId = randomUUID();
+      }
+    }
+
+    const options = pipelineRunOptions(flags, runId);
+    if (options.dryRun) info('dry run — computing the plan, executing nothing.');
+    const outcome = await runPipeline(runner, pipeline, options);
+    renderOutcome(outcome, flags.json === 'true', options.dryRun === true);
+    if (outcome.failed) process.exit(1);
+  } catch (err: any) {
+    fail(`pipeline:run failed: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await runner.end();
+  }
+}
+
+export async function pipelineListCommand(flags: Record<string, string>): Promise<void> {
+  const pipelinePath = resolvePipelinePath(flags.pipeline);
+  let pipeline: Pipeline;
+  try {
+    pipeline = await loadPipeline(pipelinePath);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  let lane: PipelineLane;
+  try {
+    lane = pipelineLaneFromFlags(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const { topoSortStages, selectStages } = await loadServerPipeline();
+  let selected;
+  try {
+    const ordered = topoSortStages(pipeline.stages);
+    selected = selectStages(ordered, {
+      lane,
+      ...(flags.only ? { only: flags.only } : {}),
+      ...(flags.from ? { from: flags.from } : {}),
+      ...(flags.to ? { to: flags.to } : {}),
+    });
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`${selected.length} stage(s) in run order:`);
+  for (const s of selected) {
+    const edges = [...(s.dependsOn ?? []), ...(s.after ?? [])];
+    info(`  ${s.id}  [${s.lane}]${edges.length ? `  ← ${edges.join(', ')}` : ''}${s.heavy ? '  (heavy)' : ''}`);
+  }
+}

package/src/cli/db-build.ts

@@ -12,7 +12,8 @@
 
 import type { ModelDescriptor } from '@everystack/model';
 import type { TableContract, QueryRunner } from './authz-contract.js';
-import type { SourceFile } from './derived-source.js';
+import type { SourceObject } from './derived-source.js';
+import type { SequenceDescriptor } from '@everystack/model';
 import { compileDeclaredState } from './declared-diff.js';
 import { createUrlRunner } from './db-source.js';
 import { executeSync, buildSyncReport } from './commands/db-sync.js';
@@ -88,7 +89,10 @@ export interface BuildResult {
 }
 
 export interface BuildOptions {
-  sources?: SourceFile[] | null;
+  /** Descriptor-compiled derived objects (the declared layer). */
+  declared?: SourceObject[];
+  /** Standalone sequences (state — created before tables, in the fingerprint bar). */
+  sequences?: SequenceDescriptor[];
   actor?: string | null;
   gitRef?: string | null;
 }
@@ -106,7 +110,9 @@ export async function buildIntoDatabase(
   const { runner, end } = await createUrlRunner(url);
   try {
     const createdRoles = await ensureContractRoles(runner, models);
-    const run = await executeSync(runner, models, options.sources ?? null, {
+    const run = await executeSync(runner, models, {
+      declared: options.declared,
+      sequences: options.sequences,
       actor: options.actor ?? 'db-build',
       gitRef: options.gitRef ?? null,
     });

package/src/cli/db-source.ts

@@ -10,10 +10,14 @@
  *   the target schema exists only on a local Postgres (migrations applied locally, no
  *   interim deploy), there is no Lambda to ask.
  *
- * Precedence is explicit-over-ambient: `--database-url` beats an explicit `--stage`,
- * which beats an inherited `DATABASE_URL`, which beats the default stage. An explicit
- * `--stage` deliberately wins over the env var so a shell with DATABASE_URL exported
- * still introspects the stage you named.
+ * Precedence is explicit-over-ambient: `--database-url` beats an explicit `--stage`, which beats
+ * an inherited env URL, which beats the default stage. An explicit `--stage` deliberately wins
+ * over the env var so a shell with a URL exported still introspects the stage you named.
+ *
+ * Between the two env credentials, `ADMIN_DATABASE_URL` (the migrator/owner) wins over
+ * `DATABASE_URL` (the least-privilege authenticator). These verbs run DDL — the authenticator
+ * can't — so the CLI's direct path is an operator path. Mirrors the server's
+ * `getAdminDatabaseUrl() ?? getDatabaseUrl()`.
  *
  * The driver is loaded lazily: `postgres` ships with @everystack/server (every deployed
  * consumer has it hoisted), so the deployed path never pays the import and a missing
@@ -23,7 +27,7 @@
 import type { QueryRunner } from './authz-contract.js';
 
 export type DbSource =
-  | { kind: 'url'; url: string; from: 'flag' | 'env' }
+  | { kind: 'url'; url: string; from: 'flag' | 'env' | 'admin-env' }
   | { kind: 'stage' };
 
 /** Decide which path serves this invocation. Pure; env injectable for tests. */
@@ -36,16 +40,26 @@ export function resolveDbSource(
     // parseFlags encodes a value-less flag as 'true'
     if (flagUrl === 'true') {
       throw new Error(
-        '--database-url needs a connection string (or omit the flag and set DATABASE_URL in the environment).',
+        '--database-url needs a connection string (or omit the flag and set ADMIN_DATABASE_URL / DATABASE_URL in the environment).',
       );
     }
     return { kind: 'url', url: flagUrl, from: 'flag' };
   }
   if (flags.stage) return { kind: 'stage' };
+  // Operator/schema verbs run DDL; prefer the admin (migrator/owner) credential over the
+  // least-privilege authenticator, which cannot. Mirrors getAdminDatabaseUrl() ?? getDatabaseUrl().
+  if (env.ADMIN_DATABASE_URL) return { kind: 'url', url: env.ADMIN_DATABASE_URL, from: 'admin-env' };
   if (env.DATABASE_URL) return { kind: 'url', url: env.DATABASE_URL, from: 'env' };
   return { kind: 'stage' };
 }
 
+/** The "Connecting via …" line, honest about which credential source was chosen. */
+export function connectingVia(source: Extract<DbSource, { kind: 'url' }>): string {
+  if (source.from === 'flag') return 'Connecting via --database-url...';
+  if (source.from === 'admin-env') return 'Connecting via ADMIN_DATABASE_URL...';
+  return 'Connecting via DATABASE_URL...';
+}
+
 export interface UrlRunner {
   runner: QueryRunner;
   /** Close the client so the process can exit cleanly. */
@@ -69,9 +83,71 @@ export async function createUrlRunner(
     );
   }
   const postgres = mod.default ?? mod;
-  const sql = postgres(url, { max: 1, onnotice: () => {} });
+  // max_lifetime: null — the driver's default recycles a connection after a random 30–60
+  // minutes, resolving the in-flight query and THEN killing the session. Under reconcile's
+  // BEGIN-across-calls transaction that is a silent session swap mid-batch (the reconcile
+  // apply path also pins the backend pid and refuses bookkeeping if it moved).
+  const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => {}, ...sslDefaults(url) });
   return {
     runner: async (query: string) => Array.from(await sql.unsafe(query)),
     end: () => sql.end({ timeout: 5 }),
   };
 }
+
+export interface UrlPipelineRunner {
+  query: (sql: string) => Promise<any[]>;
+  transaction: <T>(fn: (tx: (sql: string) => Promise<any[]>) => Promise<T>) => Promise<T>;
+  /** Close the client so the process can exit cleanly. */
+  end: () => Promise<void>;
+}
+
+/**
+ * A pipeline runner over a direct postgres.js connection — the local-direct
+ * path for `pipeline:run`. Unlike the introspection runner it carries a real
+ * `transaction` (postgres.js `sql.begin`), so each stage's writes and its
+ * memoir row commit or roll back together.
+ */
+export async function createUrlPipelineRunner(
+  url: string,
+  load: () => Promise<any> = () => import('postgres'),
+): Promise<UrlPipelineRunner> {
+  let mod: any;
+  try {
+    mod = await load();
+  } catch {
+    throw new Error(
+      'The direct-connection path needs the "postgres" driver. It ships with @everystack/server; in a project without it: pnpm add -D postgres',
+    );
+  }
+  const postgres = mod.default ?? mod;
+  const sql = postgres(url, { max: 1, onnotice: () => {}, ...sslDefaults(url) });
+  return {
+    query: async (query: string) => Array.from(await sql.unsafe(query)),
+    transaction: async (fn) =>
+      sql.begin((tx: any) => fn(async (query: string) => Array.from(await tx.unsafe(query)))),
+    end: () => sql.end({ timeout: 5 }),
+  };
+}
+
+/**
+ * Managed Postgres (RDS / Supabase / Neon) requires TLS — a direct connection without it
+ * is rejected with pg_hba "no encryption". Default `ssl: 'require'` for remote hosts so the
+ * direct-connection path just works, and leave local dev DBs plaintext (they don't serve TLS).
+ * An explicit `?sslmode=` in the URL always wins — postgres.js parses it — so we never override
+ * the operator's choice; we only fill the gap when they said nothing.
+ */
+export function sslDefaults(url: string): { ssl?: 'require' } {
+  let host = '';
+  let hasSslMode = false;
+  try {
+    const u = new URL(url);
+    host = u.hostname;
+    hasSslMode = u.searchParams.has('sslmode');
+  } catch {
+    return {};
+  }
+  const isLocal =
+    host === 'localhost' || host === '127.0.0.1' || host === '::1' || host.endsWith('.local');
+  if (isLocal || hasSslMode) return {};
+  return { ssl: 'require' };
+}