@everystack/cli 0.4.22 → 0.4.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -41,6 +41,10 @@
       "types": "./src/reconcile.ts",
       "default": "./src/reconcile.ts"
     },
+    "./refresh": {
+      "types": "./src/refresh.ts",
+      "default": "./src/refresh.ts"
+    },
     "./audit/source": {
       "types": "./src/cli/audit-source-api.ts",
       "default": "./src/cli/audit-source-api.ts"

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

@@ -411,6 +411,24 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     info(`${declared.objects.length} declared derived object(s) from the models barrel.`);
   }
 
+  // --only <a,b>: restrict the reconcile to the named identities (surgical). With --rebuild it is
+  // the recovery path for a self-consistent-but-wrong provenance row (a mistaken --rebaseline).
+  const only = flags.only ? flags.only.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+  // An empty/whitespace --only would silently degrade to a FULL reconcile — refuse it, since the
+  // operator clearly meant to scope the run.
+  if (flags.only !== undefined && !only?.length) {
+    fail('--only was given but names no identities — pass full schema.name objects (e.g. --only stats_view.my_mv), or drop the flag for a full reconcile.');
+    process.exit(1);
+  }
+  if (only?.length) {
+    const declaredIds = new Set((declared?.objects ?? []).map((o) => o.identity));
+    const unknown = only.filter((id) => !declaredIds.has(id));
+    if (unknown.length) {
+      warn(`--only names ${unknown.length} identity(ies) not in the declared derived layer: ${unknown.join(', ')} — a full schema.name is expected (e.g. stats_view.college_player_epa_context). They will match nothing.`);
+    }
+    info(`--only: restricting the reconcile to ${only.join(', ')}${flags.rebuild === 'true' ? ' (forced rebuild from source)' : ''}.`);
+  }
+
   const reconcileOptions = {
     apply,
     declared: declared?.objects,
@@ -419,6 +437,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     rebaseline: flags.rebaseline === 'true',
     rebuild: flags.rebuild === 'true',
     overwriteDrift: flags['overwrite-drift'] === 'true',
+    only,
     actor: process.env.USER ?? null,
     gitRef: currentGitRef(),
   };

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

@@ -0,0 +1,97 @@
+/**
+ * `everystack db:refresh` — refresh the declared materialized views on a stage, in dependency
+ * order, WITHOUT a raw database URL on the operator's machine.
+ *
+ *   db:refresh [--stage <name> | --database-url <url> | --direct] [--only a,b] [--list]
+ *
+ * `db:reconcile` deploys the derived-layer DEFINITION credential-free but no-ops when the def is
+ * unchanged — a pure DATA-changed matview refresh had no credential-free path. This is the
+ * data-lane twin: `--stage` runs the whole refresh in the ops Lambda on the operator connection
+ * (the `db:refresh` action), so a least-privileged operator never holds a URL. `--database-url`
+ * / `--direct` refresh over a direct connection (dev). `--list` previews the topo-ordered
+ * matviews without connecting. Plain REFRESH (ACCESS EXCLUSIVE) — CONCURRENTLY is a follow-on.
+ * (GridironDB 2026-07-19.)
+ */
+
+import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { loadDeclaredDerived } from '../declared-derived.js';
+import { executeRefresh, matviewIdentities, type RefreshRun } from '../refresh-execute.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { step, success, fail, info } from '../output.js';
+
+export async function dbRefreshCommand(flags: Record<string, string>): Promise<void> {
+  // The declared matviews, in dependency order (a dependent matview reads its parents' fresh rows).
+  let declared;
+  try {
+    declared = await loadDeclaredDerived(flags.models);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  const only = flags.only ? flags.only.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+  const matviews = matviewIdentities(declared?.objects ?? [], only);
+
+  if (matviews.length === 0) {
+    info(only?.length
+      ? `No declared matviews match --only ${only.join(',')}.`
+      : 'No declared materialized views to refresh (db:refresh operates on defineMaterializedView descriptors).');
+    process.exit(0);
+  }
+
+  // --list: preview the order without connecting anywhere (read-only, no venue needed).
+  if (flags.list === 'true') {
+    info(`${matviews.length} materialized view(s) would refresh, in this order:`);
+    for (const id of matviews) info(`  ${id}`);
+    process.exit(0);
+  }
+
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // Two venues, mirroring the reconcile lane:
+  //  - a deployed stage runs the whole refresh in the ops Lambda on the operator connection
+  //    (the db:refresh action) — no raw URL on the operator's machine, the whole point.
+  //  - a direct URL refreshes locally (dev).
+  let end: (() => Promise<void>) | undefined;
+  try {
+    let run: RefreshRun;
+    if (dbSource.kind === 'url') {
+      step(connectingVia(dbSource));
+      const conn = await createUrlRunner(dbSource.url);
+      end = conn.end;
+      step(`Refreshing ${matviews.length} materialized view(s)...`);
+      run = await executeRefresh(conn.runner, { matviews });
+    } else {
+      step('Resolving deployed config...');
+      const config = await resolveConfig(flags.stage);
+      info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+      step(`Refreshing ${matviews.length} materialized view(s) in the ops Lambda...`);
+      const result: any = await invokeAction(config.region, opsFunction(config), 'db:refresh', { matviews });
+      if (result?.error) {
+        fail(`db:refresh failed: ${result.error}`);
+        if (/Unknown action/i.test(String(result.error))) {
+          info('The deployed handler predates the db:refresh ops action (needs @everystack/server >= 0.4.9). Upgrade the server, or refresh direct: db:refresh --database-url <url>.');
+        }
+        process.exit(1);
+      }
+      run = { refreshed: result.refreshed ?? [], statements: result.statements ?? [], failed: result.failed ?? undefined };
+    }
+
+    for (const id of run.refreshed) success(`refreshed ${id}`);
+    if (run.failed) {
+      fail(`db:refresh stopped at ${run.failed.identity}: ${run.failed.error}`);
+      info(`${run.refreshed.length} of ${matviews.length} refreshed before the failure; fix and re-run (refresh is idempotent).`);
+      process.exit(1);
+    }
+    success(`db:refresh — ${run.refreshed.length} materialized view(s) refreshed.`);
+    process.exit(0);
+  } finally {
+    if (end) await end().catch(() => {});
+  }
+}

package/src/cli/commands/db.ts

@@ -242,6 +242,86 @@ export async function loadServerProvision(importer?: () => Promise<unknown>): Pr
   }
 }
 
+/** The doctor probe's shape (mirrors @everystack/server/db-doctor — runtime-only, same
+ *  peer seam as loadServerProvision). Runners are plain `(sql) => rows`. */
+export interface ServerDoctor {
+  runDoctorProbe(
+    runners: {
+      api: (sql: string) => Promise<any[]>;
+      ops: (sql: string) => Promise<any[]>;
+    },
+    options?: { apiSourceLabel?: string; forceRlsCarveouts?: string[]; functionSchemas?: string[] },
+  ): Promise<{
+    api: { role: string; isSuperuser: boolean; bypassRls: boolean };
+    admin: { role: string; isSuperuser: boolean; bypassRls: boolean };
+    checks: Array<{ name: string; status: string; detail: string; remediation?: string }>;
+    ok: boolean;
+  }>;
+}
+
+/**
+ * Lazily load the doctor probe from the @everystack/server peer — the direct venue's
+ * orchestrator. Same runtime-only seam as loadServerProvision; a missing (or too old)
+ * peer gets the install/upgrade remedy, not a raw ERR_MODULE_NOT_FOUND.
+ */
+export async function loadServerDoctor(importer?: () => Promise<unknown>): Promise<ServerDoctor> {
+  const spec = '@everystack/server/db-doctor';
+  try {
+    return (await (importer ? importer() : import(spec))) as ServerDoctor;
+  } 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(
+        'db:doctor --database-url needs @everystack/server (>= 0.4.9) installed in this app — '
+        + 'it carries the doctor probe:\n  pnpm add @everystack/server',
+      );
+    }
+    throw err;
+  }
+}
+
+/**
+ * Resolve the DIRECT venue for `db:doctor`. Unlike provision (one privileged URL) the
+ * doctor compares TWO connections — the api credential under scrutiny (DATABASE_URL) and
+ * the operator credential carrying the catalog introspection (ADMIN_DATABASE_URL). Explicit
+ * flags win (local dev): `--database-url` names the api connection, `--admin-database-url`
+ * the operator; a lone `--database-url` probes it as both (an honest api==admin report — a
+ * master URL then correctly reads "not least-privilege"). No flags but `--direct` reads BOTH
+ * from the stage secrets (the secret-safe, no-Ops on-ramp — never a URL on argv). No flag and
+ * no --direct returns null: the ops-Lambda venue.
+ */
+export function resolveDoctorVenue(args: {
+  flagApiUrl?: string;
+  flagAdminUrl?: string;
+  direct?: boolean;
+  secrets: Record<string, string>;
+}): { apiUrl: string; adminUrl: string; source: 'flag' | 'secret' } | null {
+  const { flagApiUrl, flagAdminUrl, direct, secrets } = args;
+  // parseFlags encodes a value-less flag as the string 'true' — a URL was expected.
+  if (flagApiUrl === 'true' || flagAdminUrl === 'true') {
+    throw new Error('--database-url / --admin-database-url need a connection string (or use --direct to read the stage secrets).');
+  }
+  if (flagApiUrl || flagAdminUrl) {
+    const apiUrl = flagApiUrl ?? flagAdminUrl!;
+    const adminUrl = flagAdminUrl ?? flagApiUrl!;
+    return { apiUrl, adminUrl, source: 'flag' };
+  }
+  if (direct) {
+    const apiUrl = secrets.DATABASE_URL ?? secrets.DatabaseUrl;
+    const adminUrl = secrets.ADMIN_DATABASE_URL ?? secrets.AdminDatabaseUrl;
+    if (!apiUrl && !adminUrl) {
+      throw new Error(
+        '--direct needs the stage\'s DATABASE_URL and ADMIN_DATABASE_URL secrets (the api + operator connections) — '
+        + 'run `everystack db:provision` first, or pass --database-url <api> [--admin-database-url <ops>].',
+      );
+    }
+    // If one secret is missing, probe the present URL as both (honest degraded report).
+    return { apiUrl: apiUrl ?? adminUrl!, adminUrl: adminUrl ?? apiUrl!, source: 'secret' };
+  }
+  return null;
+}
+
 /**
  * Resolve the DIRECT-venue privileged URL, keeping the master password OFF argv (shell
  * history / ps / CI logs are all leak surfaces, and the whole point of provision is to STOP
@@ -276,6 +356,24 @@ export function declaredSearchPath(schemas: string[]): string[] {
   return nonPublic.length ? [...nonPublic, 'public'] : [];
 }
 
+/**
+ * Every schema the API connection must reach — the union of the TABLE schemas (the models
+ * barrel) and the DERIVED-object schemas (views/matviews declared via
+ * `defineMaterializedView('stats_view.x')`). The derived layer's schema is declared in the
+ * descriptors, NOT the barrel, so a table-only scan structurally misses it — and the
+ * authenticator flip then goes dark on every bare-ref matview read ("relation does not
+ * exist"). Baking the union into DATABASE_URL's search_path keeps those reads resolving.
+ * (GridironDB 2026-07-19: 54 matviews in `stats_view`, absent from the table-only bake.)
+ */
+export function collectDeclaredSchemas(args: {
+  models: Array<{ schema?: string }>;
+  derivedObjects?: Array<{ schema: string }>;
+}): string[] {
+  const schemas = args.models.map((m) => m.schema ?? 'public');
+  for (const o of args.derivedObjects ?? []) schemas.push(o.schema);
+  return schemas;
+}
+
 /**
  * Bake the declared schemas into a postgres URL as `?search_path=…`. A multi-schema app's role
  * defaults to `"$user",public`, so every bare-ref query 404s until a hand ALTER ROLE pin
@@ -460,7 +558,17 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     const { resolveModelsPath } = await import('../models-path.js');
     const { loadModels } = await import('./db-generate.js');
     const models = await loadModels(resolveModelsPath(flags.models));
-    declaredSchemas = models.map((m: any) => m.schema ?? 'public');
+    // Union the DERIVED-object schemas (matviews/views live in schemas the barrel never
+    // names) so the authenticator flip doesn't go dark on bare-ref matview reads.
+    let derivedObjects: Array<{ schema: string }> = [];
+    try {
+      const { loadDeclaredDerived } = await import('../declared-derived.js');
+      const declared = await loadDeclaredDerived(flags.models);
+      if (declared) derivedObjects = declared.objects;
+    } catch {
+      // No derived layer resolvable — the table schemas still bake correctly.
+    }
+    declaredSchemas = collectDeclaredSchemas({ models, derivedObjects });
   } catch {
     // No models resolvable here — leave the URLs schema-agnostic.
   }
@@ -515,7 +623,78 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   info(`Verify:  everystack db:doctor --stage ${flags.stage}`);
 }
 
+/** Render a doctor report — identical output whichever venue produced it. */
+function printDoctorReport(report: any): void {
+  console.log('');
+  info(`api connection (DATABASE_URL):    role=${report.api.role}  superuser=${report.api.isSuperuser}  bypassrls=${report.api.bypassRls}`);
+  info(`operator connection (ADMIN_URL):  role=${report.admin.role}  superuser=${report.admin.isSuperuser}  bypassrls=${report.admin.bypassRls}`);
+  console.log('');
+
+  for (const c of report.checks as Array<{ name: string; status: string; detail: string; remediation?: string }>) {
+    if (c.status === 'pass') success(`${c.name} — ${c.detail}`);
+    else if (c.status === 'warn') warn(`${c.name} — ${c.detail}`);
+    else fail(`${c.name} — ${c.detail}`);
+    if (c.status === 'fail' && c.remediation) info(`    fix: ${c.remediation}`);
+  }
+
+  console.log('');
+  if (report.ok) {
+    success('db:doctor — database is least-privilege and RLS-subject');
+  } else {
+    fail('db:doctor — the api connection is NOT correctly least-privilege (see failures above)');
+  }
+}
+
+/**
+ * The DIRECT venue: connect to both URLs from this process and run the same probe the ops
+ * Lambda would, then render the report. Two postgres.js connections — the api credential
+ * under scrutiny and the operator credential carrying the catalog introspection. The
+ * backups lens is absent here (no pg_dump layer locally), and the app's dbPlugin
+ * forceRlsCarveouts/functionSchemas are unknown to the CLI, so the functions teeth run at
+ * their safe default (unpinned SECDEF warns rather than fails). Returns report.ok.
+ */
+async function runDoctorDirect(apiUrl: string, adminUrl: string, sourceLabel: string): Promise<boolean> {
+  const { runDoctorProbe } = await loadServerDoctor();
+  const { createUrlRunner } = await import('../db-source.js');
+  step('Probing database connections (api + operator)...');
+  const apiConn = await createUrlRunner(apiUrl);
+  const opsConn = await createUrlRunner(adminUrl);
+  try {
+    const report = await runDoctorProbe(
+      { api: apiConn.runner, ops: opsConn.runner },
+      { apiSourceLabel: sourceLabel },
+    );
+    printDoctorReport(report);
+    return report.ok;
+  } finally {
+    await apiConn.end().catch(() => {});
+    await opsConn.end().catch(() => {});
+  }
+}
+
 export async function dbDoctorCommand(flags: Record<string, string>): Promise<void> {
+  // Explicit --database-url / --admin-database-url is a fully LOCAL venue — no AWS, no
+  // stage, no secrets. Resolve and run before touching config (mirrors db:apply's
+  // local-dev --database-url path).
+  if (flags['database-url'] || flags['admin-database-url']) {
+    let venue: { apiUrl: string; adminUrl: string; source: 'flag' | 'secret' } | null;
+    try {
+      venue = resolveDoctorVenue({ flagApiUrl: flags['database-url'], flagAdminUrl: flags['admin-database-url'], secrets: {} });
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+    info('venue: direct connection (explicit --database-url)');
+    let ok = false;
+    try {
+      ok = await runDoctorDirect(venue!.apiUrl, venue!.adminUrl, '--database-url');
+    } catch (err: any) {
+      fail(`db:doctor failed: ${err.message}`);
+      process.exit(1);
+    }
+    process.exit(ok ? 0 : 1);
+  }
+
   step('Resolving deployed config...');
   let config;
   try {
@@ -525,52 +704,84 @@ export async function dbDoctorCommand(flags: Record<string, string>): Promise<vo
     process.exit(1);
   }
 
+  // Load the stage secrets once — the direct venue (--direct, and the no-Ops auto-fallback)
+  // reads DATABASE_URL + ADMIN_DATABASE_URL from here, never from argv.
+  const { loadSstSecrets } = await import('../utils/secrets.js');
+  const { parseAppName } = await import('../discover.js');
+  let stageSecrets: Record<string, string> = {};
+  try {
+    stageSecrets = await loadSstSecrets({ appName: await parseAppName(), stage: flags.stage, region: config.region });
+  } catch {
+    // Secrets unreadable — --direct will error clearly; the ops venue below still works.
+  }
+
+  // --direct: read both connections from the stage secrets and run locally.
+  if (flags.direct) {
+    let venue: { apiUrl: string; adminUrl: string; source: 'flag' | 'secret' } | null;
+    try {
+      venue = resolveDoctorVenue({ direct: true, secrets: stageSecrets });
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+    info(`Region: ${config.region}, venue: direct connection (stage secrets)`);
+    let ok = false;
+    try {
+      ok = await runDoctorDirect(venue!.apiUrl, venue!.adminUrl, 'DATABASE_URL secret');
+    } catch (err: any) {
+      fail(`db:doctor failed: ${err.message}`);
+      process.exit(1);
+    }
+    process.exit(ok ? 0 : 1);
+  }
+
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
   step('Probing database connections (api + operator)...');
 
-  const noOpsHint = () => {
-    // Name the cause, not the internal dispatch: a bring-your-own-DB app has no Ops Lambda, so
-    // db:doctor's action can't be dispatched. It has no direct venue yet — say so plainly.
-    info('This deployed handler has no dbPlugin (no Ops Lambda), so db:doctor has nothing to run against.');
-    info('db:doctor has no --database-url venue yet (unlike db:provision). To verify a bring-your-own database meanwhile, apply grants with `db:reconcile --apply --database-url <url>` and inspect roles/grants with psql. A direct db:doctor venue is on the way.');
+  // A bring-your-own-DB app has no Ops Lambda, so db:doctor's action can't be dispatched.
+  // If the stage secrets carry both URLs, run the direct venue automatically (the no-Ops
+  // on-ramp — mirrors db:provision's auto-fallback); otherwise name the cause and the manual path.
+  const noOpsFallback = async (): Promise<never> => {
+    let venue: { apiUrl: string; adminUrl: string; source: 'flag' | 'secret' } | null = null;
+    try {
+      venue = resolveDoctorVenue({ direct: true, secrets: stageSecrets });
+    } catch {
+      venue = null;
+    }
+    if (venue) {
+      info('No Ops Lambda (the deployed handler has no dbPlugin) — verifying directly over the stage secrets.');
+      let ok = false;
+      try {
+        ok = await runDoctorDirect(venue.apiUrl, venue.adminUrl, 'DATABASE_URL secret');
+      } catch (err: any) {
+        fail(`db:doctor failed: ${err.message}`);
+        process.exit(1);
+      }
+      process.exit(ok ? 0 : 1);
+    }
+    info('This deployed handler has no dbPlugin (no Ops Lambda), so db:doctor has nothing to dispatch to.');
+    info('Set the stage\'s DATABASE_URL + ADMIN_DATABASE_URL secrets and re-run with --direct, or pass --database-url <api> [--admin-database-url <ops>].');
+    process.exit(1);
   };
 
   let report: any;
   try {
     report = await invokeAction(config.region, opsFunction(config), 'db:doctor', {});
   } catch (err: any) {
+    if (/Unknown action/i.test(String(err.message))) return void (await noOpsFallback());
     fail(`db:doctor failed: ${err.message}`);
-    if (/Unknown action/i.test(String(err.message))) noOpsHint();
-    else for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
+    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
     process.exit(1);
   }
 
   if (report?.error) {
+    if (/Unknown action/i.test(String(report.error))) return void (await noOpsFallback());
     fail(`db:doctor failed: ${report.error}`);
-    if (/Unknown action/i.test(String(report.error))) noOpsHint();
     process.exit(1);
   }
 
-  console.log('');
-  info(`api connection (DATABASE_URL):    role=${report.api.role}  superuser=${report.api.isSuperuser}  bypassrls=${report.api.bypassRls}`);
-  info(`operator connection (ADMIN_URL):  role=${report.admin.role}  superuser=${report.admin.isSuperuser}  bypassrls=${report.admin.bypassRls}`);
-  console.log('');
-
-  for (const c of report.checks as Array<{ name: string; status: string; detail: string; remediation?: string }>) {
-    if (c.status === 'pass') success(`${c.name} — ${c.detail}`);
-    else if (c.status === 'warn') warn(`${c.name} — ${c.detail}`);
-    else fail(`${c.name} — ${c.detail}`);
-    if (c.status === 'fail' && c.remediation) info(`    fix: ${c.remediation}`);
-  }
-
-  console.log('');
-  if (report.ok) {
-    success('db:doctor — database is least-privilege and RLS-subject');
-    process.exit(0);
-  } else {
-    fail('db:doctor — the api connection is NOT correctly least-privilege (see failures above)');
-    process.exit(1);
-  }
+  printDoctorReport(report);
+  process.exit(report.ok ? 0 : 1);
 }
 
 export async function dbPsqlCommand(flags: Record<string, string>): Promise<void> {

package/src/cli/derived-plan.ts

@@ -126,6 +126,19 @@ export interface ReconcileOptions {
    * their provenance identity migrates with them.
    */
   renamedTables?: Record<string, string>;
+  /**
+   * Restrict the reconcile to these identities (full `schema.name`) — a surgical run that
+   * considers ONLY the named objects for create/replace/rebuild/drop/prune. Everything else is
+   * left untouched. The dependency cascade still applies: rebuilding a named relation pulls its
+   * live dependents in (they must rebuild with it) or blocks if one has no source.
+   *
+   * Combined with `rebuild`, this is the RECOVERY path for a self-consistent-but-WRONG
+   * provenance row — the state a mistaken `--rebaseline` leaves, where the source hash was
+   * re-recorded against a stale live def so both `srcChanged` and `liveChanged` read false and
+   * every normal verb no-ops. `--rebuild --only <id>` forces that object to rebuild from source
+   * regardless of the hash bookkeeping, then re-records honest provenance from the fresh object.
+   */
+  only?: string[];
 }
 
 const isRelation = (kind: DerivedKind): boolean => kind !== 'function';
@@ -156,6 +169,12 @@ export function planReconcile(
   // Every provenance consumer below reads the POST-MIGRATION view.
   const provRows = [...provById.values()];
 
+  // --only: restrict every primary decision (create/replace/rebuild/drop/prune) to these
+  // identities. The catalog/source/provenance maps above stay FULL so the dependency cascade
+  // can still pull a named relation's dependents in — the restriction is on what the operator
+  // TARGETS, not on what the graph is allowed to see.
+  const only = options.only && options.only.length ? new Set(options.only) : null;
+
   const skipped: string[] = [];
   const drift: DriftFinding[] = [];
   const needsBaseline: string[] = [];
@@ -184,6 +203,10 @@ export function planReconcile(
   const extraWarnings: string[] = [];
 
   for (const src of source.objects) {
+    // --only restricts the primary decisions to the named identities; the rest are left
+    // untouched (they are not skips — they were never in scope, so they get no plan entry).
+    if (only && !only.has(src.identity)) continue;
+
     const liveObj = liveById.get(src.identity);
     const prov = provById.get(src.identity);
 
@@ -193,6 +216,10 @@ export function planReconcile(
     if (src.kind === 'sql') {
       if (!prov) {
         create.set(src.identity, 'new in source (provenance-tracked kind — invisible to the catalog)');
+      } else if (options.rebuild && only) {
+        // Forced recovery: rebuild through the recorded drop even when the source hash matches.
+        sqlDrops.set(src.identity, { dropSql: prov.dropSql ?? src.drop ?? '', reason: 'forced rebuild from source (--rebuild --only)' });
+        create.set(src.identity, 'forced rebuild from source (--rebuild --only, through the recorded drop)');
       } else if (src.hash !== prov.srcHash) {
         sqlDrops.set(src.identity, { dropSql: prov.dropSql ?? src.drop ?? '', reason: 'source changed' });
         create.set(src.identity, 'source changed (rebuilt through the recorded drop)');
@@ -224,6 +251,27 @@ export function planReconcile(
       continue;
     }
 
+    // Forced recovery (--rebuild --only): rebuild this provenanced object from source even when
+    // the hashes show no diff. This is the clean exit from a self-consistent-but-WRONG provenance
+    // row — a mistaken --rebaseline re-records the source hash against the stale live def, so both
+    // srcChanged and liveChanged read false below and every normal verb no-ops. The dependency
+    // cascade recreates any live dependents; the post-batch introspection re-records honest
+    // provenance. Gated on `only` so a bare --rebuild never becomes an implicit rebuild-the-world.
+    if (options.rebuild && only) {
+      // If the live object was genuinely hand-edited (drift), record it before overwriting — the
+      // same audit the --overwrite-drift path keeps, so a forced rebuild never silently erases
+      // what it clobbered.
+      if (liveObj.defHash !== prov.defHash) {
+        drift.push({
+          identity: src.identity,
+          detail: 'live definition differs from what the reconciler applied — rebuilt from source (--rebuild --only overwrote it)',
+        });
+      }
+      if (isRelation(src.kind)) rebuild.set(src.identity, 'forced rebuild from source (--rebuild --only)');
+      else fnReplace.set(src.identity, 'forced replace from source (--rebuild --only)');
+      continue;
+    }
+
     const srcChanged = src.hash !== prov.srcHash;
     const liveChanged = liveObj.defHash !== prov.defHash;
 
@@ -253,12 +301,14 @@ export function planReconcile(
   }
 
   for (const liveObj of live.objects) {
+    if (only && !only.has(liveObj.identity)) continue;
     if (srcById.has(liveObj.identity)) continue;
     if (provById.has(liveObj.identity)) drop.set(liveObj.identity, 'removed from source');
     else unmanaged.push(liveObj.identity);
   }
 
   for (const prov of provRows) {
+    if (only && !only.has(prov.identity)) continue;
     if (srcById.has(prov.identity) || liveById.has(prov.identity)) continue;
     // A removed 'sql' object is invisible to the catalog — pruning would silently orphan
     // it in the database. The recorded drop_sql removes it (the C1 closure); only a

package/src/cli/index.ts

@@ -12,6 +12,7 @@ import { dbAuthzPullCommand, dbAuthzDiffCommand, dbAuthzTestCommand, dbAuthzOwne
 import { dbGenerateCommand } from './commands/db-generate.js';
 import { dbPullCommand } from './commands/db-pull.js';
 import { dbReconcileCommand } from './commands/db-reconcile.js';
+import { dbRefreshCommand } from './commands/db-refresh.js';
 import { dbFingerprintCommand } from './commands/db-fingerprint.js';
 import { dbSyncCommand } from './commands/db-sync.js';
 import { dbDiffCommand } from './commands/db-diff.js';
@@ -203,6 +204,9 @@ async function main() {
     case 'db:reconcile':
       await dbReconcileCommand(flags);
       break;
+    case 'db:refresh':
+      await dbRefreshCommand(flags);
+      break;
     case 'db:fingerprint':
       await dbFingerprintCommand(flags);
       break;
@@ -352,7 +356,7 @@ Usage:
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
   everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)
   everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (works for private RDS)
-  everystack db:doctor         [--stage <name>]  Check the DB is least-privilege + RLS-subject (api vs operator connection)
+  everystack db:doctor         [--stage <name>] [--direct | --database-url <api> [--admin-database-url <ops>]]  Check the DB is least-privilege + RLS-subject (api vs operator connection). No flag = ops-Lambda venue (auto-falls to direct via the stage secrets if the handler has no dbPlugin). --direct = probe both connections from the stage's DATABASE_URL + ADMIN_DATABASE_URL secrets; --database-url = explicit local venue (a lone URL is probed as both)
   everystack db:provision      --stage <name> [--direct | --database-url <url>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB). No flag = ops-Lambda venue (auto-falls to direct via the ADMIN_DATABASE_URL secret if the handler has no dbPlugin). --direct = direct connection reading that secret (master never on argv); --database-url = explicit URL. Declared schemas are baked into the minted DATABASE_URL as search_path
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
   everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
@@ -367,7 +371,8 @@ Usage:
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default. --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
-  everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive.
+  everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).
+  everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url/--direct refresh over a direct connection (dev); --only refreshes a named subset (full identity or bare name); --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   everystack db:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed

package/src/cli/refresh-execute.ts

@@ -0,0 +1,63 @@
+/**
+ * The matview-refresh core — the credential-free stage DATA lane's refresh half.
+ *
+ * `db:reconcile` deploys the derived-layer DEFINITION credential-free (the ops lane), but it
+ * no-ops when a matview's def is unchanged — a pure DATA-changed refresh has no credential-free
+ * path. This is that verb: refresh the declared matviews in dependency order, over whatever
+ * runner the venue supplies. The ops `db:refresh` action loads executeRefresh here and runs it
+ * on the operator connection, so `db:refresh --stage` needs no raw URL on the operator's machine
+ * (GridironDB 2026-07-19, the data-lane twin of the reconcile lane).
+ *
+ * Plain `REFRESH MATERIALIZED VIEW` (ACCESS EXCLUSIVE) — the faithful twin of the direct-connect
+ * data script it replaces. CONCURRENTLY (needs a unique index; doesn't block reads) is a
+ * deliberate follow-on, not a silent default.
+ */
+
+import { quoteQualified } from './pg-ident.js';
+import type { SourceObject } from './derived-source.js';
+
+export type RefreshRunner = (sql: string) => Promise<any[]>;
+
+export interface RefreshRun {
+  /** Identities refreshed, in the order issued. */
+  refreshed: string[];
+  /** The REFRESH statements that ran (one per refreshed matview). */
+  statements: string[];
+  /** Fail-fast: the matview whose refresh threw, stopping the run. Earlier ones already committed. */
+  failed?: { identity: string; error: string };
+}
+
+/**
+ * The declared matview identities in dependency order — the refresh order (a dependent matview
+ * reads its parents' freshly-committed rows, so parents refresh first). `loadDeclaredDerived`
+ * already returns objects in dependency order. `only` filters by full identity (`schema.name`)
+ * or bare name.
+ */
+export function matviewIdentities(objects: SourceObject[], only?: string[]): string[] {
+  const ids = objects.filter((o) => o.kind === 'materialized view').map((o) => o.identity);
+  if (!only?.length) return ids;
+  const want = new Set(only);
+  return ids.filter((id) => want.has(id) || want.has(id.split('.').pop()!));
+}
+
+/**
+ * Refresh the given matview identities in the order supplied. Fail-fast: the first error stops
+ * the run and is reported (earlier refreshes have already committed — each REFRESH is its own
+ * statement, no wrapping transaction, so CONCURRENTLY stays possible later). An empty list is a
+ * clean no-op.
+ */
+export async function executeRefresh(runner: RefreshRunner, opts: { matviews: string[] }): Promise<RefreshRun> {
+  const refreshed: string[] = [];
+  const statements: string[] = [];
+  for (const identity of opts.matviews) {
+    const stmt = `REFRESH MATERIALIZED VIEW ${quoteQualified(identity)}`;
+    try {
+      await runner(stmt);
+      statements.push(stmt);
+      refreshed.push(identity);
+    } catch (err: any) {
+      return { refreshed, statements, failed: { identity, error: err?.message || String(err) } };
+    }
+  }
+  return { refreshed, statements };
+}

package/src/refresh.ts

@@ -0,0 +1,11 @@
+/**
+ * @everystack/cli/refresh — the matview-refresh core, for the ops-Lambda lane.
+ *
+ * db:reconcile deploys the derived-layer DEFINITION credential-free (@everystack/cli/reconcile).
+ * This is the DATA lane's twin: the ops `db:refresh` action loads executeRefresh here and runs it
+ * on the operator connection, so `db:refresh --stage` needs no raw admin URL on the deployer's
+ * machine. The CLI ships the declared matview identities (dependency order); this refreshes them.
+ */
+
+export { executeRefresh, matviewIdentities } from './cli/refresh-execute.js';
+export type { RefreshRun, RefreshRunner } from './cli/refresh-execute.js';