@everystack/cli 0.4.82 → 0.4.83

package/src/cli/commands/db.ts

@@ -9,11 +9,26 @@ import { resolveConfig, opsFunction } from '../config';
 import { invokeAction } from '../aws';
 import { step, success, fail, info, warn } from '../output';
 import { opsAdviceLines, IAM_ADVICE } from '../ops-advice';
+import { modelContractPreflight } from '../model-wire-lane';
+import {
+  MODEL_WIRE_CONTRACT,
+  type DeclaredOwner,
+  type Adoptee,
+  type ProvisionWirePayload,
+  type OwnershipWirePayload,
+} from '../../wire';
 
 /** Secret-store keys that may hold the privileged (operator) connection URL,
  *  in precedence order. Names vary by deployment; --secret-name overrides. */
 const ADMIN_URL_KEYS = ['ADMIN_DATABASE_URL', 'AdminDatabaseUrl', 'ADMIN_URL'];
 
+/** Secret-store keys that may hold the SELECT-only (reader) connection URL — the one `db:query`
+ *  runs on. Deliberately NOT `READ_DATABASE_URL`: that key is the read-REPLICA slot, and it carries
+ *  the same least-privilege API role at a different host (getReadDatabaseUrl/createReadDb, and the
+ *  `ReadDatabaseUrl` rotation slot). Reusing it would point app read traffic at a role with no
+ *  app-role membership. Different purpose, different key. */
+const QUERY_URL_KEYS = ['QUERY_DATABASE_URL', 'QueryDatabaseUrl'];
+
 /**
  * Parse a postgres connection URL into psql's PG* environment variables.
  *
@@ -223,12 +238,17 @@ export function buildProvisionSecretPlan(args: {
      *  so its secret must be left untouched. Absent/true = the password was set, write the secret. */
     passwordSet?: boolean;
     adminPasswordSet?: boolean;
+    /** The SELECT-only login db:query connects as. Absent = no reader was requested. */
+    readerRole?: string;
+    /** false = the reader already existed as a live login (additive-only) — leave its secret alone. */
+    readerPasswordSet?: boolean;
   };
   authUrl?: string;
   adminUrl?: string;
+  readerUrl?: string;
   existing: Record<string, string>;
 }): ProvisionSecretPlan {
-  const { result, authUrl, adminUrl, existing } = args;
+  const { result, authUrl, adminUrl, readerUrl, existing } = args;
   const updates: Record<string, string> = {};
   const notes: string[] = [];
   const warnings: string[] = [];
@@ -266,6 +286,19 @@ export function buildProvisionSecretPlan(args: {
     );
   }
 
+  // The SELECT-only reader — only ever touched when one was actually provisioned, so a stage that
+  // never asked for one is byte-identical to before this key existed.
+  if (result.readerRole && readerUrl && result.readerPasswordSet !== false) {
+    updates.QUERY_DATABASE_URL = readerUrl;
+    const prevReaderRole = roleOfUrl(existing.QUERY_DATABASE_URL ?? existing.QueryDatabaseUrl);
+    notes.push(`QUERY_DATABASE_URL: ${prevReaderRole ?? 'unset'} → ${result.readerRole} (db:query runs here — SELECT only)`);
+  } else if (result.readerRole) {
+    // NOT "--rotate to change it": rotation covers the api (authenticator) and ops (migrator) slots
+    // only — there are no A/B pairs for the reader. Say the true remedy instead of a verb that
+    // silently does nothing here.
+    notes.push(`QUERY_DATABASE_URL: '${result.readerRole}' already provisioned — password + secret preserved (--rotate does not cover this slot; to re-mint it, DROP ROLE ${result.readerRole} and re-run db:provision --with-reader)`);
+  }
+
   return { updates, notes, warnings };
 }
 
@@ -306,8 +339,12 @@ export interface ServerProvision {
   runProvision(
     payload: {
       authPassword?: string; adminPassword?: string; searchPath?: string[]; rotationPairs?: boolean;
-      declaredOwners?: Array<{ owner: string; schema: string }>;
-      declaredObjects?: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }>;
+      /** The SELECT-only reader's password. Absent = no reader role is created at all. */
+      readerPassword?: string;
+      /** The SELECT-only login db:query connects as. Default 'reader' server-side. */
+      readerRole?: string;
+      declaredOwners?: DeclaredOwner[];
+      declaredObjects?: Adoptee[];
       confirm?: boolean;
     },
     deps: {
@@ -322,17 +359,21 @@ export interface ServerProvision {
   /** ENACT + ADOPT, run SEPARATELY and AFTER the secret is written (the lockout-safe ordering). */
   convergeOwnership(
     payload: {
-      declaredOwners?: Array<{ owner: string; schema: string }>;
-      declaredObjects?: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }>;
+      declaredOwners?: DeclaredOwner[];
+      declaredObjects?: Adoptee[];
       confirm?: boolean;
       adminRole?: string;
+      /** Present = also converge the reader's read grants over `searchPath`. Absent = skip them. */
+      readerRole?: string;
+      /** The declared schema set the reader's grants are scoped to. */
+      searchPath?: string[];
     },
     deps: {
       execute: (sql: string) => Promise<unknown>;
       query?: (sql: string) => Promise<any[]>;
       master?: { execute: (sql: string) => Promise<unknown>; query: (sql: string) => Promise<any[]> } | null;
     },
-  ): Promise<{ ownerEnactment?: { enacted: number; refusals: string[] }; ownerAdoption?: { reassigned: number; manifest: Array<{ identity: string; kind: string; secdef: boolean; from: string; to: string }>; findings: Array<{ severity: string; identity: string; detail: string }>; refusals: string[] } }>;
+  ): Promise<{ ownerEnactment?: { enacted: number; refusals: string[] }; ownerAdoption?: { reassigned: number; manifest: Array<{ identity: string; kind: string; secdef: boolean; from: string; to: string }>; findings: Array<{ severity: string; identity: string; detail: string }>; refusals: string[]; warnings?: string[] }; readerGrants?: { granted: number; refusals: string[] } }>;
 }
 
 /**
@@ -482,12 +523,12 @@ const ADOPTABLE_KINDS = new Set(['function', 'view', 'materialized view']);
  * them owned by the operator, no convergence needed).
  */
 export function extractDeclaredOwnership(objects: Array<{ kind: string; schema: string; name: string; identity: string; sql: string; owner?: string }>): {
-  declaredOwners: Array<{ owner: string; schema: string }>;
-  declaredObjects: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }>;
+  declaredOwners: DeclaredOwner[];
+  declaredObjects: Adoptee[];
 } {
   const seen = new Set<string>();
-  const declaredOwners: Array<{ owner: string; schema: string }> = [];
-  const declaredObjects: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }> = [];
+  const declaredOwners: DeclaredOwner[] = [];
+  const declaredObjects: Adoptee[] = [];
   for (const o of objects) {
     if (!o.owner) continue;
     const key = `${o.owner}\t${o.schema}`;
@@ -894,8 +935,8 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   let declaredSchemas: string[] = [];
   // Declared ownership (brownfield convergence) — the (owner, schema) pairs to ENACT and the
   // function/view/matview objects to ADOPT, read from the same barrel as the schema set.
-  let declaredOwners: Array<{ owner: string; schema: string }> = [];
-  let declaredObjects: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }> = [];
+  let declaredOwners: DeclaredOwner[] = [];
+  let declaredObjects: Adoptee[] = [];
   try {
     const { resolveModelsPath } = await import('../models-path');
     const { loadModels } = await import('./db-generate');
@@ -920,12 +961,42 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   const confirm = !!flags.confirm;
   const ownershipPayload = { declaredOwners, declaredObjects, confirm };
 
+  /**
+   * The CLI half of the Model-derived wire handshake, for the ops-Lambda venue only (the direct
+   * venue crosses no wire — the CLI runs the provisioning core in-process).
+   *
+   * Both of this command's ops invokes carry Model-derived data — `db:provision`'s declared
+   * `searchPath`, then `db:converge-ownership`'s declared owners and objects — and both go to the
+   * SAME stage, so the shared runner memoizes one `_health` round trip across them.
+   */
+  const preflightModelContract = modelContractPreflight({
+    region: config.region,
+    fn: opsFunction(config),
+    directCommand: `everystack db:provision --stage ${flags.stage ?? '<stage>'} --direct`,
+    // Provision-specific, and worth the extra clause: the operator's likely next question is
+    // "where does --direct get a connection from, and do I have to hand it one?" It does not —
+    // it reads the stage's own secret, so nothing lands on argv.
+    directHint: "it reads that connection from the stage's ADMIN_DATABASE_URL secret, so no credential reaches argv",
+    // This runs before either invoke, so nothing has been written: the refusal prints and exits.
+    onRefusal: 'exit',
+  });
+
   // Generate BOTH login passwords and keep them in memory only — they are written straight
   // into the secret store and are NEVER printed, logged, or returned to a human.
   const { randomBytes } = await import('node:crypto');
   const authPassword = randomBytes(24).toString('hex');
   const adminPassword = randomBytes(24).toString('hex');
 
+  // The SELECT-only reader (the connection db:query runs on) is OPT-IN the first time: it mints a
+  // third credential and its grants take an ACCESS EXCLUSIVE lock on every table in the declared
+  // schemas, neither of which a routine re-provision should do by surprise. It is STICKY afterwards
+  // — a stage that already carries the secret keeps the reader converged on every later run, so a
+  // schema added later does not silently fall out of its reach.
+  const readerSecretExists = QUERY_URL_KEYS.some((k) => stageSecrets[k]);
+  const withReader = !!flags['with-reader'] || readerSecretExists;
+  const readerPassword = withReader ? randomBytes(24).toString('hex') : undefined;
+  const credentials = { authPassword, adminPassword, searchPath, rotationPairs: !!flags['rotation-pairs'], ...(readerPassword ? { readerPassword } : {}) };
+
   // Run the role chain over a direct connection to `url` — shared by the explicit direct venue
   // and the auto-fallback below.
   const provisionDirect = async (url: string): Promise<any> => {
@@ -934,7 +1005,7 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     const { runner, end } = await createUrlRunner(url);
     try {
       // Credentials ONLY — ownership convergence runs separately, AFTER the secret is written.
-      return await runProvision({ authPassword, adminPassword, searchPath, rotationPairs: !!flags['rotation-pairs'] }, {
+      return await runProvision(credentials, {
         execute: async (statement) => runner(statement),
         connection: parseUrlConnection(url),
         // Additive-only: an already-live login role keeps its password (never reset on re-provision).
@@ -973,7 +1044,18 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     conn = parseUrlConnection(directUrl);
   } else {
     try {
-      result = await invokeAction(config.region, opsFunction(config), 'db:provision', { authPassword, adminPassword, searchPath, rotationPairs: !!flags['rotation-pairs'] });
+      await preflightModelContract('db:provision');
+      // The Model-derived half of the payload, pinned against the SHARED declaration so a shape
+      // change here cannot land without the shape pin (and therefore the contract bump) noticing.
+      // The credentials half is generated locally and is not part of the wire contract.
+      const provisionWire = {
+        searchPath,
+        modelContract: MODEL_WIRE_CONTRACT,
+      } satisfies ProvisionWirePayload;
+      result = await invokeAction(config.region, opsFunction(config), 'db:provision', {
+        ...credentials,
+        ...provisionWire,
+      });
     } catch (err: any) {
       // Auto-fallback: no Ops Lambda (Unknown action), but an ADMIN_DATABASE_URL secret exists —
       // provision directly over it. Master never crosses the CLI; the operator sets nothing new.
@@ -1013,6 +1095,12 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
       : (result.adminVerified === true ? 'connectivity verified' : 'connectivity NOT verified');
     success(`Operator login ready: ${result.adminRole} (LOGIN, INHERIT owner) — ${adminMsg}`);
   }
+  if (result.readerRole) {
+    const readerMsg = result.readerPasswordSet === false ? 'existing login preserved' : 'password set';
+    success(`Read-only login ready: ${result.readerRole} (LOGIN, NOINHERIT, no BYPASSRLS, SELECT only) — ${readerMsg}`);
+  } else if (withReader) {
+    warn('No read-only login was created — this @everystack/server predates the SELECT-only reader. Upgrade the server pin and re-run; db:query keeps running on the operator connection until then.');
+  }
 
   // Ownership convergence runs AFTER the secret write (below) — never before. Declared here so the
   // final exit status can see it.
@@ -1026,8 +1114,11 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   // review-then-`--confirm` flow), and nothing converged. Credentials are already saved on both
   // paths by the time this runs, so it can strand nothing.
   const runConvergence = async (): Promise<void> => {
-    if (!declaredOwners.length && !declaredObjects.length) return;
-    const ownerPayload = { ...ownershipPayload, adminRole: result.adminRole };
+    // The reader's read grants ride this same step, for the same reason ADOPT does: they can stall
+    // on a lock, and nothing that can stall may sit between the password swap and the secret write.
+    const readerRole = result.readerRole as string | undefined;
+    if (!declaredOwners.length && !declaredObjects.length && !readerRole) return;
+    const ownerPayload = { ...ownershipPayload, adminRole: result.adminRole, ...(readerRole ? { readerRole, searchPath } : {}) };
     let owned: any = {};
     try {
       if (directUrl) {
@@ -1046,7 +1137,16 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
           await end?.();
         }
       } else {
-        owned = await invokeAction(config.region, opsFunction(config), 'db:converge-ownership', ownerPayload);
+        // Same stage, same handshake — memoized, so this normally costs no extra round trip. It
+        // still stands on its own: this is the invoke that actually REASSIGNS OWNERSHIP from
+        // Model-derived data, so it must never dispatch to an unverified stage.
+        await preflightModelContract('db:converge-ownership');
+        owned = await invokeAction(
+          config.region,
+          opsFunction(config),
+          'db:converge-ownership',
+          { ...ownerPayload, modelContract: MODEL_WIRE_CONTRACT } satisfies OwnershipWirePayload,
+        );
       }
     } catch (err: any) {
       warn(`Ownership convergence failed (credentials are already saved — nothing stranded): ${err.message}`);
@@ -1066,6 +1166,16 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
       for (const f of adopt.findings ?? []) warn(`  audit (${f.severity}): ${f.identity} — ${f.detail}`);
       if (adopt.reassigned) success(`Ownership adoption: ${adopt.reassigned} object(s) reassigned (one transaction).`);
       for (const r of adopt.refusals ?? []) { warn(`Ownership adoption: ${r}`); ownershipIncomplete = true; }
+      // Warnings are the succeeded-but half: the reassignment landed, some cleanup after it did not.
+      // Printed, never counted as incomplete — nothing is left to converge.
+      for (const w of adopt.warnings ?? []) warn(`Ownership adoption: ${w}`);
+    }
+    const reader = owned.readerGrants;
+    if (reader) {
+      if (reader.granted) success(`Read-only grants: ${reader.granted} statement(s) applied for '${result.readerRole}'.`);
+      // A reader that cannot read is a failure, not a warning to skip: db:query would connect and
+      // then fail on every table. Same non-zero exit as an un-converged owner.
+      for (const r of reader.refusals) { warn(`Read-only grants: ${r}`); ownershipIncomplete = true; }
     }
   };
 
@@ -1074,7 +1184,9 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   // store on a no-op re-provision (the footgun that reset a live password then locked the stage out).
   const wroteAuth = result.passwordSet !== false;
   const wroteAdmin = !!result.adminRole && result.adminPasswordSet !== false;
-  if (!wroteAuth && !wroteAdmin) {
+  // A brand-new reader on an already-provisioned stage is NOT a no-op: its secret must be written.
+  const wroteReader = !!result.readerRole && result.readerPasswordSet !== false;
+  if (!wroteAuth && !wroteAdmin && !wroteReader) {
     // Both roles preserved. Only a true no-op if the secrets backing them exist and name them;
     // a role that exists WITH LOGIN but has no matching secret is a half-done prior provision that
     // plain db:provision cannot recover — refuse with the --rotate remedy rather than report success.
@@ -1134,6 +1246,7 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
 
   const authUrl = wroteAuth ? mint(result.loginRole, authPassword) : undefined;
   const adminUrl = wroteAdmin && result.adminRole ? mint(result.adminRole, adminPassword) : undefined;
+  const readerUrl = wroteReader && result.readerRole && readerPassword ? mint(result.readerRole, readerPassword) : undefined;
 
   // Write the secrets directly to the SST secret store — never display them. One blob
   // write updates every key together, so there is no window where the API side is the
@@ -1142,7 +1255,7 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   let plan: ProvisionSecretPlan;
   try {
     const secrets = { ...stageSecrets };
-    plan = buildProvisionSecretPlan({ result, authUrl, adminUrl, existing: secrets });
+    plan = buildProvisionSecretPlan({ result, authUrl, adminUrl, readerUrl, existing: secrets });
     Object.assign(secrets, plan.updates);
     await putSstSecrets(secretsCtx, secrets);
   } catch (err: any) {
@@ -1175,6 +1288,11 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     info('  Ops:  declare `new sst.Secret("AdminDatabaseUrl", "")` and link it to the Ops function —');
     info(`        operator tasks then run as ${result.adminRole}, not the Postgres master.`);
   }
+  if (result.readerRole) {
+    info('  Read: declare `new sst.Secret("QUERY_DATABASE_URL", "")`, link it to the Ops function, and');
+    info('        pass it to dbPlugin as `queryDatabaseUrl` — db:query then runs as the SELECT-only');
+    info(`        role (${result.readerRole}). Until you do, db:query keeps running on the operator connection.`);
+  }
   info(`Verify:  everystack db:doctor --stage ${flags.stage}`);
 
   // Credentials are done; ownership was left un-converged. Exit non-zero so CI and the operator act

package/src/cli/db-source.ts

@@ -196,7 +196,14 @@ export interface UrlProbeRunner {
   end: () => Promise<void>;
 }
 
-/** Thrown to abort the probe transaction; never escapes `probe`. */
+/**
+ * Thrown to abort the probe transaction; never escapes `probe`.
+ *
+ * The server-side twin (`runRolledBack` in `@everystack/server` plugin.ts) aborts the same way
+ * — a private value recognised by IDENTITY — but throws a drizzle `TransactionRollbackError`
+ * instance, because there it runs inside a drizzle transaction. This venue is raw postgres.js
+ * `sql.begin()`: no drizzle, no `TransactionRollbackError`, so the Symbol stays.
+ */
 const PROBE_ROLLBACK = Symbol('authz_probe_rollback');
 
 /**

package/src/cli/derived-catchup.ts

@@ -0,0 +1,154 @@
+/**
+ * The function/view/trigger CATCH-UP, as one call — what `db:apply` runs after a plan lands.
+ *
+ * WHY THIS EXISTS. Applying a plan only ever changed tables, columns and grants. Everything
+ * built ON them — functions, views, materialized views, triggers — was a second command, and a
+ * second command is a thing a person forgets. One consumer deployed half a database that way
+ * (the apply said "success"; the views were a release behind). Then the same split produced two
+ * stages that disagreed about who may read what, to the people building this fix. So the second
+ * command stops being something a human runs: db:apply does it, every time, against the target
+ * it just applied to.
+ *
+ * WHAT IS NOT HERE. No DDL logic. `executeReconcile` (commands/db-reconcile.ts) is THE core that
+ * plans and applies the declared objects — db:check's from-scratch build, db:sync and
+ * db:reconcile --apply already route through it, and so does this. What this module owns is only
+ * the VENUE: run it on the connection the apply is already holding, or credential-free in the
+ * stage's ops Lambda, exactly as `db:reconcile --apply --stage` does.
+ *
+ * FAILURE IS A THROW. Every way the catch-up can fail — a refusal it will not apply over
+ * (drift, a blocked chain), an error from the DDL, an error from the ops Lambda — leaves this
+ * function as an exception. The caller decides what that means for its exit code and its
+ * wording; db:apply's answer is plain-output's one-line partial-failure report.
+ *
+ * ONE EXCEPTION, and the caller chooses it: a stage that speaks a different wire contract. See
+ * `onRefusal` — a caller that has already written asks for a throw, a caller that has not asks
+ * for an exit and lets the refusal print on its own terms. Both callers say which; there is no
+ * default to inherit by forgetting.
+ */
+
+import type { QueryRunner } from './authz-contract';
+import type { SessionRunner } from './session';
+import { executeReconcile, type ReconcileRun } from './commands/db-reconcile';
+import { loadDeclaredDerived, type DeclaredDerived } from './declared-derived';
+import { modelContractPreflight } from './model-wire-lane';
+import { MODEL_WIRE_CONTRACT, type ReconcileWirePayload } from '../wire';
+import { resolveConfig, opsFunction } from './config';
+import { invokeAction } from './aws';
+import { currentGitRef } from './state-apply';
+
+/** Where the catch-up runs. The two lanes db:apply itself already has. */
+export type CatchUpVenue =
+  /** On a connection the caller holds (--database-url, or --stage --direct). */
+  | { kind: 'direct'; runner: QueryRunner; session: SessionRunner }
+  /** Credential-free in the stage's ops Lambda — the operator never holds a URL. */
+  | { kind: 'stage'; stage: string };
+
+export interface CatchUpOptions {
+  /** The --models flag, as given. Resolved by the loader, exactly as every other verb resolves it. */
+  models?: string;
+  /**
+   * Test seam: the declared layer, instead of loading it from the barrel. Jest cannot
+   * dynamic-import a .ts barrel, so a suite that wants the REAL reconcile against a REAL
+   * database hands the descriptors over the way the loader would have.
+   */
+  declared?: DeclaredDerived | null;
+  /** Called once it is known there is something to catch up — never for a checkout that declares none. */
+  onStart?: (declared: number) => void;
+  /**
+   * What a stage's wire-contract refusal does. THE CALLER DECIDES, because only the caller knows
+   * what has already been written.
+   *
+   * REQUIRED, with no default. `'exit'` prints the refusal and exits — the right answer when
+   * nothing has been written yet, because the refusal itself names the skew, says nothing was
+   * sent, and offers the `--direct` venue. `'throw'` hands the caller a `ModelContractError` to
+   * render instead — what
+   * db:apply's POST-plan catch-up needs, where the table and column changes have already committed
+   * and the operator is owed one sentence about that before the process ends.
+   *
+   * Hardcoding either one here is a bug: this function has two callers with opposite
+   * post-conditions, and the one that had written nothing spent a release telling operators to
+   * rerun the command that had just failed.
+   *
+   * It is required rather than defaulted for the same reason. A default is a hardcode that
+   * only LOOKS like a choice: a caller that forgets it inherits the wrong post-condition in
+   * silence, which is exactly the bug above. If a default ever has to come back, it defaults
+   * to `'throw'` — a caller wrongly handed an exception renders a clumsy error, a caller
+   * wrongly handed an exit loses the sentence its operator was owed.
+   */
+  onRefusal: 'exit' | 'throw';
+}
+
+export interface CatchUpOutcome {
+  /** How many function/view/trigger objects the checkout declares. 0 = there was nothing to do. */
+  declared: number;
+  /** The reconcile that ran, or null when nothing was declared. */
+  run: ReconcileRun | null;
+  /** The DDL that actually landed — what the receipt folds into its change list. */
+  statements: string[];
+}
+
+/** Everything a caught-up run needs to say about itself when it refuses or throws. */
+export class CatchUpError extends Error {}
+
+/**
+ * Bring the declared functions, views, matviews and triggers in line with the checkout, on
+ * `venue`. Returns what landed; throws {@link CatchUpError} (or whatever the reconcile threw)
+ * when it did not.
+ */
+export async function catchUpDerived(
+  venue: CatchUpVenue,
+  opts: CatchUpOptions,
+): Promise<CatchUpOutcome> {
+  const declared = opts.declared !== undefined ? opts.declared : await loadDeclaredDerived(opts.models);
+  const objects = declared?.objects ?? [];
+  if (objects.length === 0) return { declared: 0, run: null, statements: [] };
+  opts.onStart?.(objects.length);
+
+  const options = {
+    apply: true,
+    declared: objects,
+    renamedTables: declared?.renamedTables,
+    actor: process.env.USER ?? null,
+    gitRef: currentGitRef(),
+  };
+
+  let run: ReconcileRun;
+  if (venue.kind === 'direct') {
+    run = await executeReconcile(venue.runner, venue.session, options);
+  } else {
+    const config = await resolveConfig(venue.stage);
+    // The ops Lambda CREATES AND REPLACES database objects from these descriptors, so verify the
+    // deployed stage understands their shape before sending them — the same handshake
+    // db:reconcile --apply --stage runs, for the same payload.
+    //
+    // WHO renders a refusal is the CALLER's call, never this function's — see `onRefusal`. A
+    // post-plan catch-up asks to throw, because its operator is owed "your changes are safe"
+    // before the process ends. A catch-up that is the whole command has written nothing, and
+    // asks to exit: print the skew, say nothing was sent, exit.
+    await modelContractPreflight({
+      region: config.region,
+      fn: opsFunction(config),
+      directCommand: `everystack db:apply --stage ${venue.stage} --direct`,
+      onRefusal: opts.onRefusal,
+    })('db:apply');
+    const result: any = await invokeAction(
+      config.region,
+      opsFunction(config),
+      'db:reconcile',
+      { ...options, modelContract: MODEL_WIRE_CONTRACT } satisfies ReconcileWirePayload,
+    );
+    if (result?.error) throw new CatchUpError(String(result.error));
+    run = {
+      plan: result.plan,
+      applied: result.applied,
+      statements: result.statements ?? [],
+      refusal: result.refusal ?? undefined,
+    };
+  }
+
+  // A refusal is not a soft outcome here. db:reconcile prints it and exits 1; the catch-up did
+  // not land, so db:apply must say so and exit the same way.
+  if (run.refusal) throw new CatchUpError(run.refusal);
+
+  return { declared: objects.length, run, statements: run.applied ? (run.statements ?? []) : [] };
+}