@everystack/cli 0.4.49 → 0.4.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.49",
+  "version": "0.4.51",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/authz-derive.ts

@@ -64,8 +64,10 @@ const DML: Record<string, 'read' | 'create' | 'update' | 'delete'> = {
   DELETE: 'delete',
 };
 
-/** The roles the compiler itself emits policies for; anything else is app-specific. */
-const KNOWN_ROLES = new Set(['anon', 'authenticated', 'admin']);
+/** The roles the compiler itself emits policies for; anything else is app-specific.
+ *  Exported so the DERIVED renderer applies the identical rule — the views path once had
+ *  its own idea of which grantees to render, and the two disagreed inside one pull. */
+export const KNOWN_ROLES = new Set(['anon', 'authenticated', 'admin']);
 
 /**
  * The grantees a rendered model GOVERNS — the three vocabulary roles plus PUBLIC, which is
@@ -75,7 +77,7 @@ const KNOWN_ROLES = new Set(['anon', 'authenticated', 'admin']);
  * an ungoverned grantee alone, so there is no REVOKE to prevent, and naming the role in a model
  * would GOVERN it — turning a rendering decision into an access decision for every table.
  */
-const GOVERNED_VOCABULARY = new Set([...KNOWN_ROLES, 'PUBLIC', 'public']);
+export const GOVERNED_VOCABULARY = new Set([...KNOWN_ROLES, 'PUBLIC', 'public']);
 
 /** The beyond-CRUD privileges a governed role holds live — what `can()` cannot say. */
 function deriveExtraPrivileges(contract: TableContract): Record<string, string[]> {

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

@@ -37,7 +37,8 @@ import { compileDrizzleSource } from '../schema-source.js';
 import { currentGitRef } from '../state-apply.js';
 import { createDatabase, dropDatabase, buildIntoDatabase, withDatabase } from '../db-build.js';
 import { resolveModelsPath } from '../models-path.js';
-import { loadModels } from './db-generate.js';
+import { loadModels, loadModules } from './db-generate.js';
+import { findUnexportedModels, scanModelDirectory, type ModelFileScan } from '../model-barrel-lint.js';
 import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import type { SequenceDescriptor } from '@everystack/model';
 import type { SourceObject } from '../derived-source.js';
@@ -67,6 +68,10 @@ export interface CheckFinding {
 
 export interface StaticCheckInput {
   modelsPath: string;
+  /** Barrel siblings and what each declares — the "on disk but ungoverned" scan. */
+  modelFileScans?: ModelFileScan[];
+  /** The module's extensions — the bootstrap the from-scratch compose needs. */
+  extensions?: string[];
   /** null = the barrel did not load — the gate's first failure. */
   models: ModelDescriptor[] | null;
   modelsError?: string;
@@ -104,6 +109,17 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
   }
   findings.push({ level: 'ok', area: 'models', message: `${input.models.length} model(s) loaded from ${input.modelsPath}` });
 
+  // A file on disk the barrel never exported is outside governance while looking declared.
+  // FAIL, not warn: it is absent from the fingerprint, so nothing downstream will ever
+  // notice, and the only other signal is a model COUNT nobody can compare against.
+  const barrelGaps = findUnexportedModels(
+    input.modelFileScans ?? [],
+    new Set(input.models.map((m) => `${m.schema}.${m.table}`)),
+  );
+  for (const gap of barrelGaps) {
+    findings.push({ level: 'fail', area: 'models', message: gap.message });
+  }
+
   // The semantic merge conflict git can't see: two branches declaring the
   // same table both merge cleanly — the merged state must still compose.
   const seen = new Map<string, number>();
@@ -144,7 +160,7 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
 
   try {
     compileDeclaredState(input.models);
-    const statements = compileMigration(input.models, { sequences: input.sequences });
+    const statements = compileMigration(input.models, { sequences: input.sequences, extensions: input.extensions });
     findings.push({ level: 'ok', area: 'compose', message: `declared state composes — ${statements.length} statement(s) from scratch` });
   } catch (err: any) {
     findings.push({ level: 'fail', area: 'compose', message: `the merged declared state does NOT compose: ${err.message}` });
@@ -281,7 +297,7 @@ export interface EphemeralComposeResult {
 export async function executeEphemeralCompose(
   adminUrl: string,
   models: ModelDescriptor[],
-  opts: { actor?: string | null; gitRef?: string | null; declared?: SourceObject[]; sequences?: SequenceDescriptor[] } = {},
+  opts: { actor?: string | null; gitRef?: string | null; declared?: SourceObject[]; sequences?: SequenceDescriptor[]; extensions?: string[] } = {},
 ): Promise<EphemeralComposeResult> {
   const database = `escheck_${process.pid}_${Date.now()}`;
   await createDatabase(adminUrl, database);
@@ -289,6 +305,7 @@ export async function executeEphemeralCompose(
     const built = await buildIntoDatabase(withDatabase(adminUrl, database), models, {
       declared: opts.declared,
       sequences: opts.sequences,
+      extensions: opts.extensions,
       actor: opts.actor ?? 'db:check',
       gitRef: opts.gitRef ?? null,
     });
@@ -315,6 +332,19 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
     modelsError = err.message;
   }
 
+  // Only meaningful once the barrel itself loaded — otherwise every sibling reads as
+  // ungoverned and the real error is buried under the noise.
+  const modelFileScans = models ? await scanModelDirectory(modelsPath) : [];
+
+  // The module carries the extensions; `models` alone cannot. Without them the from-scratch
+  // compose builds a schema whose column types do not exist.
+  let extensions: string[] = [];
+  if (models) {
+    try {
+      extensions = [...new Set((await loadModules(modelsPath)).flatMap((m) => m.extensions ?? []))];
+    } catch { /* a models-only barrel has no modules export — nothing to bootstrap */ }
+  }
+
   const artifactPath = flags['schema-out'] || DEFAULT_SCHEMA_OUT;
   let artifactSource: string | null = null;
   try {
@@ -349,7 +379,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
   } catch { /* no baseline — see above */ }
 
   const findings = runStaticChecks({
-    modelsPath, models, modelsError, artifactPath, artifactSource, sqlDirRetired,
+    modelsPath, models, modelsError, modelFileScans, extensions, artifactPath, artifactSource, sqlDirRetired,
     sequences: declaredDb?.sequences, derived: declaredDb?.derived, derivedError,
     moduleModels: declaredDb?.models ?? null,
     baselineSource,
@@ -374,6 +404,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
         gitRef: currentGitRef(),
         declared: declaredDb?.objects,
         sequences: declaredDb?.sequences,
+        extensions,
       });
       for (const line of ephemeral.report) info(`  ${line}`);
     } catch (err: any) {

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

@@ -72,7 +72,7 @@ export async function loadModels(modelsPath: string): Promise<ModelDescriptor[]>
  * COMPLETE migration. Falls back to wrapping a bare `models` array in one module (an app on the
  * older models-only barrel still gets a schema+authz init, just no package functions).
  */
-async function loadModules(modelsPath: string): Promise<Module[]> {
+export async function loadModules(modelsPath: string): Promise<Module[]> {
   const abs = path.resolve(modelsPath);
   let mod: any;
   try {

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

@@ -221,6 +221,22 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       }
     }
 
+    // The class rides on the ARTIFACT, not only the terminal — a reviewer reading
+    // db.plan.json had the aggregate and no way to reach the statements behind it, so
+    // `unclassified: 5` was unreadable by the only person positioned to catch what it meant.
+    //
+    // Attached HERE, before the plan is serialized AND before planHash is taken, because
+    // both must see the same object. It used to be assigned after the write, onto an
+    // instance nobody read again: the artifact carried no adoption at all, and the summary
+    // counted statements the file could not show. Hashing after attaching also keeps the
+    // ref db:plan prints equal to the one db:apply computes for that file — `planHash` is
+    // sha256 over the WHOLE plan, so a field added later silently changes the identity.
+    //
+    // Re-DERIVED from live every mint, never stored across mints: a recorded claim about
+    // what the models fail to capture goes stale the moment someone closes the gap.
+    const adoption = classifyAdoption(declaredAuthz, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles) });
+    plan.adoption = adoption.statements;
+
     const body = JSON.stringify(plan, null, 2) + '\n';
     if (out === '-') {
       console.log(body);
@@ -238,16 +254,11 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     // fail to capture goes stale the moment someone closes the gap, and a stale note is worse
     // than none. `capability` is the count that says "this plan removes something the model
     // cannot express" — the operator reading this is the last one who can catch it.
-    const adoption = classifyAdoption(declaredAuthz, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles) });
     const adoptionTotal = Object.values(adoption.counts).reduce((a, b) => a + b, 0);
     if (adoptionTotal > 0) {
       info(`${adoptionTotal} authorization statement(s), by why they exist:`);
       for (const line of renderAdoptionReport(adoption.counts, adoption.statements)) info(line);
     }
-    // The class rides on the ARTIFACT too, not only the terminal. A reviewer reading
-    // db.plan.json had the aggregate and no way to reach the statements behind it, so
-    // `unclassified: 5` was unreadable by the only person positioned to catch what it meant.
-    plan.adoption = adoption.statements;
 
     // WHO owns the tables this plan authorizes, and does that owner obey the policies it
     // is about to write? Re-derived live every mint, never stored — the owner is a fact

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

@@ -2,7 +2,7 @@
  * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
  *
  *   db:pull [--stage <name>] [--database-url <url>] [--schema public] [--out <dir | file.ts>]
- *           [--derived-out <file.ts>] [--abilities public-read]
+ *           [--derived-out <file.ts>] [--abilities live|public-read]
  *
  * `--stage` and `--database-url` COMPOSE: the URL picks the connection, the stage names the
  * baseline entry (`db/authz-baseline.json` is per-stage — a local adoption pulls with
@@ -108,7 +108,12 @@ export function derivedImportSpecifier(out: string, derivedOut: string): string
 }
 
 export async function dbPullCommand(flags: Record<string, string>): Promise<void> {
-  const schema = flags.schema || 'public';
+  // A LIST: `--schema public,auth,metrics`. One value still works. Without this there was
+  // no way to adopt a multi-schema database — `--out <dir>` regenerates the barrel, so a
+  // second pull replaced the first schema's models rather than joining them.
+  const schemas = (flags.schema || 'public').split(',').map((s) => s.trim()).filter(Boolean);
+  if (schemas.length === 0) fail('--schema needs at least one schema name.');
+  const schema = schemas.length === 1 ? schemas[0] : schemas;
 
   // --derived-out: the brownfield splice, first-class. A consumer with an existing
   // hand-maintained barrel wants the derived layer as its own file — not codemodded
@@ -167,7 +172,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       runner = lambdaQueryRunner(config.region, opsFunction(config));
       session = lambdaSessionRunner(config.region, opsFunction(config));
     }
-    note(`Introspecting live database (schema: ${schema})...`);
+    note(`Introspecting live database (schema: ${schemas.join(", ")})...`);
     current = await introspectSchema(session);
     // The derived layer rides the same pull (B5) — views/matviews/functions/sequences
     // render as descriptors; adoption is pull → commit → --baseline → clean reconcile.
@@ -358,7 +363,21 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   const flagged = (source.match(/\/\/ (FIXME|TODO|composite|CHECK|FK →|verbatim:)/g) ?? []).length;
   if (flagged) caution(`${flagged} inline comment(s) flag things to review (verbatim types, checks, cross-schema FKs).`);
   if (abilities === 'commented') {
-    note(`Each model scaffolds its authz decision as comments — author them (db:check fails until every model declares), or stamp the common case: db:pull --abilities public-read.`);
+    // `live` FIRST, and named. It is the mode brownfield adoption needs — derive the authz
+    // from grants and policies the database already has — and it was advertised nowhere:
+    // not in the usage line, not in --help, not here. The only place an operator met the
+    // word was the error text for an unknown preset, so the discovery path for the right
+    // flag was to guess a wrong one. A consumer and their agent both walked past it in one
+    // session, and it cost a misdiagnosis plus a needless overwrite of 30 model files.
+    //
+    // `public-read` is deliberately no longer the headline: on an existing database it
+    // stamps can('read') on EVERY table, which on a real schema means public read of
+    // credit_cards, transactions, emails and users.
+    note(
+      `Each model scaffolds its authz decision as comments — db:check fails until every model declares. `
+      + `For an EXISTING database, re-pull with --abilities live to derive them from the grants and policies `
+      + `already there. --abilities public-read stamps public-read/admin-write on every table — greenfield only.`,
+    );
   } else {
     note(`Stamped '${abilities}' abilities into every model — review the generated stanzas; they are code, not defaults.`);
   }

package/src/cli/db-build.ts

@@ -17,6 +17,7 @@ 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';
+import { executeReconcile } from './commands/db-reconcile.js';
 
 const SAFE_NAME = /^[a-z_][a-z0-9_$]*$/;
 
@@ -93,6 +94,10 @@ export interface BuildOptions {
   declared?: SourceObject[];
   /** Standalone sequences (state — created before tables, in the fingerprint bar). */
   sequences?: SequenceDescriptor[];
+  /** Extensions the declared state needs. Applied BEFORE anything else — a column typed
+   *  `hstore` cannot be created until the type exists, and the sync path is a DIFF, which
+   *  has no bootstrap phase of its own. `IF NOT EXISTS`, so re-running is free. */
+  extensions?: string[];
   actor?: string | null;
   gitRef?: string | null;
 }
@@ -109,7 +114,62 @@ export async function buildIntoDatabase(
 ): Promise<BuildResult> {
   const { runner, session, end } = await createUrlRunner(url);
   try {
+    // Bootstrap FIRST: roles and tables both come after the types they use exist.
+    for (const ext of [...new Set(options.extensions ?? [])].sort()) {
+      await runner(`CREATE EXTENSION IF NOT EXISTS "${ext}"`);
+    }
+    // Schemas, for the same reason. This path is a DIFF (executeSync), and a diff has no
+    // bootstrap phase: `compileMigration` emits CREATE SCHEMA for every non-public schema a
+    // model lives in, but nothing on the sync path did — so a multi-schema declared state
+    // failed with `schema "auth" does not exist` before a single table was created. Taken
+    // from the MODELS and from the declared derived objects, because a schema can hold only
+    // functions (an `auth` of nothing but SECURITY DEFINER functions is a real shape).
+    const modelSchemas = models.map((m) => m.schema ?? 'public');
+    const derivedSchemas = (options.declared ?? []).map((o) => o.schema);
+    for (const schema of [...new Set([...modelSchemas, ...derivedSchemas])].filter((s) => s && s !== 'public').sort()) {
+      await runner(`CREATE SCHEMA IF NOT EXISTS "${schema}"`);
+    }
     const createdRoles = await ensureContractRoles(runner, models);
+
+    // FUNCTIONS BEFORE STATE. An RLS policy's predicate is resolved when the policy is
+    // created, so `USING (user_id = auth.user_id())` cannot be created before
+    // `auth.user_id()` exists — and the sync path applies state (tables, RLS, policies)
+    // before the derived layer. On a real brownfield schema that is not an edge case: 18 of
+    // one consumer's policies call an `auth.*` function, so the from-scratch build failed
+    // with `function auth.user_id() does not exist` before any of them could be created.
+    //
+    // Only FUNCTIONS move: views and triggers depend on TABLES, so the layers genuinely
+    // interleave and "derived before state" would just fail the other way round.
+    //
+    // `check_function_bodies = off` for this window — the pg_dump restore idiom. A
+    // SQL-language function whose body reads a table that does not exist yet is a forward
+    // reference, not an error; plpgsql bodies are never validated at creation, so only the
+    // SQL-language ones need it. MEASURED, not assumed: dropping this SET puts the reference
+    // brownfield schema straight back to failing, so the escape is load-bearing.
+    //
+    // It is a BARE set, not SET LOCAL, and that is deliberate: reconcile opens its own
+    // transaction, so this pass has none to scope to. It is safe under the rule the repo's
+    // own guard documents — `createUrlRunner` gives this command a dedicated max:1
+    // connection it owns for the run and closes in a finally, never a pooled or shared one.
+    // RESET in a finally so the window closes even on failure.
+    //
+    // Provenance is recorded by this pass, so executeSync's own reconcile below sees the
+    // functions already managed and unchanged, and plans nothing for them.
+    const declaredFunctions = (options.declared ?? []).filter((o) => o.kind === 'function');
+    if (declaredFunctions.length > 0) {
+      await runner('SET check_function_bodies = off');
+      try {
+        const pre = await executeReconcile(runner, session, {
+          declared: declaredFunctions,
+          apply: true,
+          actor: options.actor ?? 'db-build',
+          gitRef: options.gitRef ?? null,
+        });
+        if (pre.refusal) throw new Error(`could not create declared functions first: ${pre.refusal}`);
+      } finally {
+        await runner('RESET check_function_bodies');
+      }
+    }
     const run = await executeSync(runner, session, models, {
       declared: options.declared,
       sequences: options.sequences,

package/src/cli/derived-lint.ts

@@ -32,6 +32,7 @@ import type {
   FunctionDescriptor, DependsOnRef,
 } from '@everystack/model';
 import { parseQualified } from './derived-source.js';
+import { GOVERNED_VOCABULARY } from './authz-derive.js';
 
 export interface DerivedAuthzGap {
   /** `schema.name` of the descriptor that fails the gate. */
@@ -60,6 +61,10 @@ function isModelRef(ref: DependsOnRef): ref is ModelDescriptor {
  * as zero-reach, which bricked every invoker view over a private table.
  */
 export function tableReaches(m: ModelDescriptor, role: string): boolean {
+  // A recorded grant is reach too. PUBLIC SELECT is held by every role; a named grantee
+  // reaches itself. See grantsPublic — this is the half the gate kept forgetting.
+  if (grantsPublic(m.privileges, 'SELECT')) return true;
+  if (privilegeRoles(m.privileges, 'SELECT').includes(role)) return true;
   for (const a of m.abilities) {
     if (isColumnAbility(a)) {
       // Only the READ half reaches: a column-scoped update compiles to `UPDATE (cols)`
@@ -79,6 +84,30 @@ export function tableReaches(m: ModelDescriptor, role: string): boolean {
   return false;
 }
 
+/**
+ * REACH comes from abilities AND from recorded privileges. Forgetting the second half is a
+ * bug this repo has now made three times — the 63-byte ACL truncation, the SECDEF caller
+ * gate, and this one — always the same shape: a fact recorded as `privileges` falls out of
+ * a downstream read and lands in neither set.
+ *
+ * `PUBLIC` is the case that matters. `GRANT … TO PUBLIC` is held by EVERY role, so a
+ * dependency carrying one is reachable by all of them, and a live PUBLIC grant is exactly
+ * what `db:pull` RECORDS rather than inventing an audience for. Reading abilities alone
+ * made a faithful pull fail to COMPILE, with no hand-edit available to fix it.
+ */
+function grantsPublic(privileges: Record<string, string[]> | undefined, privilege: string): boolean {
+  return Object.entries(privileges ?? {}).some(
+    ([grantee, privs]) => grantee.toUpperCase() === 'PUBLIC' && privs.some((p) => p.toUpperCase() === privilege),
+  );
+}
+
+/** Grantees a recorded privilege names directly — reach for that role, nobody else. */
+function privilegeRoles(privileges: Record<string, string[]> | undefined, privilege: string): string[] {
+  return Object.entries(privileges ?? {})
+    .filter(([, privs]) => privs.some((p) => p.toUpperCase() === privilege))
+    .map(([grantee]) => grantee);
+}
+
 /** The roles a relation's grants reach — bare read is anon + authenticated (the table precedent). */
 function relationRoles(d: ViewDescriptor | MaterializedViewDescriptor): Set<string> {
   const roles = new Set<string>();
@@ -89,12 +118,15 @@ function relationRoles(d: ViewDescriptor | MaterializedViewDescriptor): Set<stri
       roles.add('authenticated');
     }
   }
+  for (const r of privilegeRoles(d.privileges, 'SELECT')) roles.add(r);
   return roles;
 }
 
 function functionRoles(fn: FunctionDescriptor): Set<string> {
   // define-time already rejected bare can('execute') — every ability carries a role.
-  return new Set(fn.abilities.map((a) => a.condition.role!));
+  const roles = new Set(fn.abilities.map((a) => a.condition.role!));
+  for (const r of privilegeRoles(fn.privileges, 'EXECUTE')) roles.add(r);
+  return roles;
 }
 
 // ---------------------------------------------------------------------------
@@ -262,7 +294,7 @@ function findUnreachable(role: string, refs: readonly DependsOnRef[], seen: Set<
     }
     switch (ref.kind) {
       case 'view': {
-        if (ref.private || !relationRoles(ref).has(role)) return identityOf(ref);
+        if (ref.private || (!relationRoles(ref).has(role) && !grantsPublic(ref.privileges, 'SELECT'))) return identityOf(ref);
         // An invoker dep re-checks the caller one level down; a definer dep reads as its owner.
         if (ref.securityInvoker) {
           const deeper = findUnreachable(role, ref.dependsOn, seen);
@@ -272,11 +304,11 @@ function findUnreachable(role: string, refs: readonly DependsOnRef[], seen: Set<
       }
       case 'materialized view':
         // A matview is its own snapshot: SELECT on the matview is the whole requirement.
-        if (ref.private || !relationRoles(ref).has(role)) return identityOf(ref);
+        if (ref.private || (!relationRoles(ref).has(role) && !grantsPublic(ref.privileges, 'SELECT'))) return identityOf(ref);
         break;
       case 'function':
         // The body calls it with the caller's rights — EXECUTE is part of reach.
-        if (!functionRoles(ref).has(role)) return identityOf(ref);
+        if (!functionRoles(ref).has(role) && !grantsPublic(ref.privileges, 'EXECUTE')) return identityOf(ref);
         break;
       case 'sql':
         break; // opaque — never a false positive
@@ -296,7 +328,12 @@ export function findInvokerReachabilityGaps(derived: readonly DerivedDescriptor[
   for (const d of derived) {
     if (d.kind !== 'view' || !d.securityInvoker || d.private || d.abilities.length === 0) continue;
     const identity = identityOf(d);
-    for (const role of [...relationRoles(d)].sort()) {
+    // Only roles the declared world can SATISFY. A grantee outside the compiler's
+    // vocabulary is recorded fact on the view AND on the table (the tables path never
+    // renders one as an ability), so table-side reach for it is not expressible — checking
+    // it is a demand no model can ever meet. Their reach is adopted via authz-baseline,
+    // outside this gate. PUBLIC is governed and stays checked.
+    for (const role of [...relationRoles(d)].filter((r) => GOVERNED_VOCABULARY.has(r)).sort()) {
       const unreachable = findUnreachable(role, d.dependsOn, new Set());
       if (unreachable) {
         gaps.push({

package/src/cli/derived-render.ts

@@ -16,8 +16,9 @@
 import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
 import type { ColumnSchema, SequenceSchema, TableSchema } from './schema-introspect.js';
 import { parseIndexDefinition } from './schema-introspect.js';
-import { modelFileName, renderFieldLines } from './model-render.js';
+import { modelImportPath, renderFieldLines } from './model-render.js';
 import { splitFunctionIdentity } from './pg-argtypes.js';
+import { GOVERNED_VOCABULARY, KNOWN_ROLES } from './authz-derive.js';
 
 export interface DerivedRenderResult {
   /** The source block: `export const … = defineView(…)` etc., dependency-ordered. */
@@ -100,12 +101,28 @@ function tsString(s: string): string {
  */
 function splitRelationGrants(
   grants: Record<string, string[]>,
-): { abilities: string[]; privileges: Record<string, string[]> } {
+): { abilities: string[]; privileges: Record<string, string[]>; foreign: string[] } {
   const readRoles = new Set<string>();
   const privileges: Record<string, string[]> = {};
+  const foreign: string[] = [];
   for (const [grantee, privs] of Object.entries(grants)) {
     const selectOnly = privs.length === 1 && privs[0] === 'SELECT';
-    if (selectOnly && grantee.toUpperCase() !== 'PUBLIC') readRoles.add(grantee);
+    // ABILITIES are limited to the compiler's own vocabulary (authz-derive's KNOWN_ROLES).
+    // A foreign grantee is FACT, not opinion, so it is RECORDED — never declared as an
+    // intended audience. The views path used to render any select-only grantee as an
+    // ability, so one pull could declare a role as an ABILITY on a view while the table
+    // recorded it as a foreign grantee, and the reachability gate then demanded table-side
+    // reach the tables path will never render. The contract contradicted itself.
+    //
+    // RECORDED, not dropped — and that is the part the obvious fix gets wrong. On a TABLE,
+    // "not rendered" is safe because the table reconciler leaves an ungoverned grantee
+    // alone. On a DERIVED object there is no such carve-out: diffObjectGrants unions the
+    // declared and live grantees, so a grantee we omit is a grantee we REVOKE. Measured:
+    // declared {anon,authenticated} against live +outbound_migrator plans
+    // `REVOKE SELECT, UPDATE ON public.v FROM outbound_migrator`. Dropping them would
+    // reintroduce the silent revoke this whole branch exists to prevent.
+    if (!GOVERNED_VOCABULARY.has(grantee)) foreign.push(grantee);
+    if (selectOnly && KNOWN_ROLES.has(grantee)) readRoles.add(grantee);
     else privileges[grantee] = [...privs].sort();
   }
   const abilities: string[] = [];
@@ -115,7 +132,7 @@ function splitRelationGrants(
     readRoles.delete('authenticated');
   }
   for (const role of [...readRoles].sort()) abilities.push(`can('read', { role: ${tsString(role)} })`);
-  return { abilities, privileges };
+  return { abilities, privileges, foreign: foreign.sort() };
 }
 
 /**
@@ -363,7 +380,15 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       // the abilities we can express would leave the write grants undeclared, so the next
       // generate would plan a REVOKE for each — a silent skip traded for a silent revoke.
       // Declared == live means nothing is planned at all.
-      const { abilities, privileges } = splitRelationGrants(o.grants ?? {});
+      const { abilities, privileges, foreign } = splitRelationGrants(o.grants ?? {});
+      if (foreign.length) {
+        warnings.push(
+          `${o.identity}: grants exist for ${foreign.join(', ')} — recorded as \`privileges\`, not declared as ` +
+          'abilities. Abilities name the roles the model governs (anon/authenticated/admin); a grantee outside ' +
+          'that vocabulary is fact, not an intended audience. Recorded rather than dropped because a derived ' +
+          'object REVOKES any live grantee the declaration omits.',
+        )
+      }
       const writeGrants = Object.values(privileges).some((ps) =>
         ps.some((p) => p === 'INSERT' || p === 'UPDATE' || p === 'DELETE'),
       );
@@ -651,7 +676,7 @@ export function renderDerivedFile(result: DerivedRenderResult, knownTables: Map<
     lines.push(`import { ${result.imports.join(', ')} } from '@everystack/model';`);
   }
   const refs = result.modelRefs
-    .map((table) => ({ varName: knownTables.get(table)!, path: `./${modelFileName(table).replace(/\.ts$/, '')}` }))
+    .map((table) => ({ varName: knownTables.get(table)!, path: modelImportPath(table) }))
     .sort((a, b) => a.path.localeCompare(b.path));
   for (const ref of refs) lines.push(`import { ${ref.varName} } from '${ref.path}';`);
   lines.push('', result.block, '');

package/src/cli/index.ts

@@ -359,7 +359,7 @@ Usage:
   everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
   everystack db:swap           --schema <name> --from <artifact.dump | artifact-id> [--stage <name> --direct | --database-url <url>] --confirm [--fingerprint <hash>] [--snapshot physical|logical|none] [--snapshot-ref <id>] [--rebuild-derived] [--dump-build <file.json>]  Land a schema artifact atomically: fingerprint gate → pre-flight refusals → CONFIRMED snapshot → restore into <schema>_incoming (COPY-safe rewrite) → build the paired derived layer → one txn (drop+rename+recreate app→schema FKs, re-apply authz + schema USAGE) → assertions → drop retiring. Refresh-free; app.* untouched; the derived layer is never absent. DESTRUCTIVE. The venue is EXPLICIT — DATABASE_URL in the env is refused, and --stage requires --direct (a multi-GB restore exceeds the ops-Lambda 900s clock). The rollback point defaults to a PHYSICAL RDS snapshot on a stage that exposes databaseInstanceId (no locks, no pg_dump contending with the restore) and a WAITED logical db:backup otherwise; a bare --database-url refuses without --snapshot-ref <id> or --snapshot none. docs/schema-swap.md
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
-  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
+  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities live|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 live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are 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] [--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).

package/src/cli/migration-compile.ts

@@ -38,10 +38,21 @@ function emptyTable(table: string): TableContract {
  * schema). Tables, then foreign keys, then authz — the order a fresh database must
  * apply them in.
  */
-export function compileMigration(models: ModelDescriptor[], opts: CompileTableOptions & { sequences?: SequenceDescriptor[] } = {}): string[] {
+export function compileMigration(
+  models: ModelDescriptor[],
+  opts: CompileTableOptions & { sequences?: SequenceDescriptor[]; extensions?: string[] } = {},
+): string[] {
   const sql: string[] = [];
   const schemaOf = (m: ModelDescriptor): string => m.schema ?? 'public';
 
+  // 0. Extensions — the BOOTSTRAP, before any table that might use one of their types.
+  //    compileModuleMigration has always emitted these; compileMigration had no way to,
+  //    so db:check's from-scratch ring compiled a state whose column types did not exist
+  //    and failed with `type "hstore" does not exist` on an otherwise clean schema.
+  //    Deduped + sorted, quoted so a hyphenated name (`uuid-ossp`) stays valid.
+  const extensions = [...new Set(opts.extensions ?? [])].sort();
+  sql.push(...extensions.map((e) => `CREATE EXTENSION IF NOT EXISTS "${e}";`));
+
   // 0a. Non-public schemas — `CREATE SCHEMA` for each distinct one a model lives in,
   //     before any table is created in it. public is the implicit default, never emitted.
   const schemas = [...new Set(models.map(schemaOf))].filter((s) => s !== 'public').sort();
@@ -137,12 +148,14 @@ export function compileMigration(models: ModelDescriptor[], opts: CompileTableOp
 export function compileModuleMigration(modules: Module[], opts: CompileTableOptions = {}): string[] {
   const sql: string[] = [];
 
-  // 1. Extensions — deduped + sorted, quoted so a hyphenated name (`uuid-ossp`) is valid.
-  const extensions = [...new Set(modules.flatMap((m) => m.extensions))].sort();
-  sql.push(...extensions.map((e) => `CREATE EXTENSION IF NOT EXISTS "${e}";`));
-
-  // 2. Schema + authz for every modeled table (plus the modules' standalone sequences).
-  sql.push(...compileMigration(modules.flatMap((m) => m.models), { ...opts, sequences: modules.flatMap((m) => m.sequences) }));
+  // 1+2. Extensions (the bootstrap) then schema + authz for every modeled table, plus the
+  //       modules' standalone sequences. compileMigration owns the extension emission now, so
+  //       the two entry points cannot disagree about the order or the quoting.
+  sql.push(...compileMigration(modules.flatMap((m) => m.models), {
+    ...opts,
+    sequences: modules.flatMap((m) => m.sequences),
+    extensions: modules.flatMap((m) => m.extensions),
+  }));
 
   // 3. Package SQL — functions + triggers, after the tables they reference. Each thunk's
   //    output is a self-contained multi-statement block applied as one unit.

package/src/cli/model-barrel-lint.ts

@@ -0,0 +1,115 @@
+/**
+ * model-barrel-lint — the file that is on disk and outside governance.
+ *
+ * Every verb reads the BARREL: `db:check`, `db:plan` and `db:fingerprint` all call
+ * `loadModels(modelsPath)` and see exactly what it exports. So a model file sitting in
+ * `db/models/` that `index.ts` never imports does not exist as far as any of them is
+ * concerned — it is absent from the fingerprint, absent from the plan, and absent from the
+ * check — while looking entirely declared to a human reading the directory.
+ *
+ * That is the failure the declared-state model exists to prevent: a table quietly outside
+ * governance, with a file that says otherwise. It is also silent by construction, because
+ * the only signal is a COUNT ("30 model(s)") that matches nothing the reader can compare it
+ * to. A consumer lost an hour to it and drew a false stage-drift conclusion from the
+ * resulting one-statement plan.
+ *
+ * The scan is deliberately shallow: the barrel's OWN directory, non-recursive. A models
+ * directory is a flat directory of models by convention, and walking deeper would start
+ * flagging fixtures and generated output.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ModelDescriptor } from '@everystack/model';
+
+/** One file's declared tables, as read off its own exports. */
+export interface ModelFileScan {
+  /** Basename, relative to the barrel's directory — what the operator has to go open. */
+  file: string;
+  /** Qualified tables (`schema.table`) the file declares, in any order. */
+  tables: string[];
+}
+
+export interface UnexportedModelGap {
+  file: string;
+  /** The declared tables no verb can see, sorted. */
+  tables: string[];
+  message: string;
+}
+
+/**
+ * Files declaring a table the barrel never exported. Pure — the caller does the reading, so
+ * the rule is testable without a filesystem.
+ *
+ * Findings are per FILE, because the file is the unit that gets fixed (add it to the
+ * barrel, or delete it). Everything is sorted: import order is not a contract, and a lint
+ * whose output reorders between runs is one nobody can diff.
+ */
+export function findUnexportedModels(
+  scans: readonly ModelFileScan[],
+  loadedTables: ReadonlySet<string>,
+): UnexportedModelGap[] {
+  const gaps: UnexportedModelGap[] = [];
+  for (const scan of scans) {
+    const missing = scan.tables.filter((t) => !loadedTables.has(t)).sort();
+    if (missing.length === 0) continue;
+    gaps.push({
+      file: scan.file,
+      tables: missing,
+      message:
+        `${scan.file} declares ${missing.join(', ')} but the barrel does not export it — so no verb can see it. ` +
+        `db:check, db:plan and db:fingerprint all read the barrel, which means the table is outside governance ` +
+        `while the file makes it look declared. Export it from the barrel, or delete the file.`,
+    });
+  }
+  return gaps.sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/** A qualified table identity, matching the form the loaded models are keyed by. */
+export function modelIdentity(m: ModelDescriptor): string {
+  return `${m.schema}.${m.table}`;
+}
+
+/**
+ * Read the barrel's sibling files and report what each one declares.
+ *
+ * Import failures are SKIPPED, not raised: a sibling that does not compile is a different
+ * problem with its own error path, and a lint that turns an unrelated broken file into a
+ * governance finding would send the operator to the wrong place. A file exporting no model
+ * simply scans as zero tables.
+ */
+export async function scanModelDirectory(modelsPath: string): Promise<ModelFileScan[]> {
+  const abs = path.resolve(modelsPath);
+  const dir = path.dirname(abs);
+  const barrel = path.basename(abs);
+
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return []; // Not a directory-shaped barrel (a single-module app); nothing to scan.
+  }
+
+  const scans: ModelFileScan[] = [];
+  for (const entry of entries.sort()) {
+    if (entry === barrel) continue;
+    if (!entry.endsWith('.ts') || entry.endsWith('.d.ts')) continue;
+    let mod: Record<string, unknown>;
+    try {
+      mod = (await import(pathToFileURL(path.join(dir, entry)).href)) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    const tables = Object.values(mod)
+      .filter((v): v is ModelDescriptor => (
+        typeof v === 'object' && v !== null
+        && typeof (v as ModelDescriptor).table === 'string'
+        && typeof (v as ModelDescriptor).schema === 'string'
+        && Array.isArray((v as ModelDescriptor).abilities)
+      ))
+      .map(modelIdentity);
+    scans.push({ file: entry, tables: [...new Set(tables)] });
+  }
+  return scans;
+}

package/src/cli/model-render.ts

@@ -61,7 +61,8 @@ export function checkToValidate(expr: string): { column: string; zod: string } |
 
 export interface RenderOptions {
   /** Only pull tables in this Postgres schema (others are framework-managed). Default: `public`. */
-  schema?: string;
+  /** One schema, or several — a database is not always one schema. Default `'public'`. */
+  schema?: string | string[];
   /**
    * The read-model scaffold. Default `'commented'`: every model carries the authz decision
    * as a commented stanza (same guidance as the db:check gate — the model fails the gate
@@ -241,8 +242,25 @@ const INFRASTRUCTURE_TABLES = new Set([
  * database can carry `public.__drizzle_migrations` — the journal is tooling state,
  * never an app model. Exported so the command shell counts the same set it writes.
  */
-export function pullableTables(snapshot: SchemaSnapshot, schema: string): TableSchema[] {
-  return snapshot.tables.filter((t) => t.table.startsWith(`${schema}.`) && !INFRASTRUCTURE_TABLES.has(bareName(t.table)));
+export function pullableTables(snapshot: SchemaSnapshot, schema: string | string[]): TableSchema[] {
+  // A LIST, because a database is not one schema. `--schema` took a single value and
+  // `--out <dir>` regenerates the barrel, so pulling a second schema overwrote the first —
+  // there was no way to land a multi-schema database in one declared state at all.
+  //
+  // Matched on the exact prefix, never `startsWith(schema)` alone: `pub` must not match
+  // `public.users`.
+  const schemas = new Set(Array.isArray(schema) ? schema : [schema]);
+  return snapshot.tables.filter((t) => {
+    const dot = t.table.indexOf('.');
+    const owner = dot === -1 ? 'public' : t.table.slice(0, dot);
+    return schemas.has(owner) && !INFRASTRUCTURE_TABLES.has(bareName(t.table));
+  });
+}
+
+/** The schema a qualified (or bare) table lives in — bare means public. */
+function schemaOf(table: string): string {
+  const dot = table.indexOf('.');
+  return dot === -1 ? 'public' : table.slice(0, dot);
 }
 
 /**
@@ -258,7 +276,14 @@ export function pullableTables(snapshot: SchemaSnapshot, schema: string): TableS
 export function modelVarName(table: string): string {
   const bare = bareName(table);
   const singular = bare.endsWith('s') ? bare.slice(0, -1) : bare;
-  return singular.split('_').filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+  const pascal = (word: string): string =>
+    word.split('_').filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+  // Non-public schemas are QUALIFIED, so `public.users` and `auth.users` can live in one
+  // barrel. Public stays bare, so an existing single-schema barrel does not churn and
+  // nothing renames when a second schema arrives. Same rule the derived renderer already
+  // uses for its own symbols.
+  const owner = schemaOf(table);
+  return owner === 'public' ? pascal(singular) : pascal(owner) + pascal(singular);
 }
 
 /**
@@ -511,7 +536,15 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   const writtenBy = writtenByStanza(table, liveAuthz);
   const softDelete = softDeleteStanza(table, stanza.publicRead);
 
-  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza.text}\n${writtenBy}${softDelete}  fields: {\n${fields}\n  },${constraints}\n});`;
+  // A non-public table carries `schema:` — defineModel stores the name VERBATIM, so the
+  // qualification cannot ride in the first argument (that would make the table literally
+  // named `metrics.impressions`). Without it a multi-schema pull rendered
+  // `defineModel('impressions')`, which declares `public.impressions`, and the matview that
+  // selects FROM metrics.impressions then failed to build. Same idiom the derived renderer
+  // already uses for defineMaterializedTable.
+  const owner = schemaOf(table.table);
+  const schemaProp = owner === 'public' ? '' : `  schema: '${owner}',\n`;
+  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza.text}\n${schemaProp}${writtenBy}${softDelete}  fields: {\n${fields}\n  },${constraints}\n});`;
 }
 
 /** The `import` lines a rendered body needs — only what it actually uses, so the file reads clean. */
@@ -548,6 +581,7 @@ function moduleFooter(
   derived?: DerivedRenderResult,
   multiline = false,
   external?: ExternalDerived,
+  extensions?: string[],
 ): string {
   // A materialized table (--matviews-as-tables) is a MODEL — its block rides the derived
   // render (topo-ordered with the objects around it) but its name belongs in `models`.
@@ -570,6 +604,22 @@ function moduleFooter(
     if (!external) parts.push(`export const derived = [${derived!.names.join(', ')}];`);
     keys.push('derived');
   }
+  // Extensions are the BOOTSTRAP half of a declared state: `field.pgType('hstore')` compiles
+  // to a column whose type does not exist unless something ran CREATE EXTENSION first.
+  // `defineModule` has always accepted the key and migration-compile has always emitted
+  // `CREATE EXTENSION IF NOT EXISTS` from it — the renderer was the only missing link, and a
+  // consumer found it when db:check's from-scratch ring failed with `type "hstore" does not
+  // exist` on a state that was otherwise clean.
+  //
+  // ALL installed extensions, not only those reachable from a declared column type: an
+  // adopter's `pg_stat_statements` and `unaccent` reach no column, and a from-scratch
+  // database without them is not their database.
+  if (extensions?.length) {
+    // Sorted HERE, not just at the introspection: the renderer owns byte-stability, and a
+    // caller passing an unsorted list must not produce a diff against an identical database.
+    parts.push(`export const extensions = [${[...extensions].sort().map((e) => `'${e}'`).join(', ')}];`);
+    keys.push('extensions');
+  }
   parts.push(`export const appModule = defineModule({ ${keys.join(', ')} });`);
   parts.push(`export const modules = [appModule];`);
   return parts.join('\n\n');
@@ -611,7 +661,7 @@ export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions
 
   // Module composition is the norm: the pulled barrel exports `modules` alongside `models`,
   // so a fresh brownfield project lands on the same shape the framework composes.
-  const footer = moduleFooter(tables.map((t) => modelVarName(t.table)), opts.derived);
+  const footer = moduleFooter(tables.map((t) => modelVarName(t.table)), opts.derived, false, undefined, snapshot.extensions);
 
   const header = importHeader([...blocks, footer].join('\n\n'), opts.derived?.imports ?? []);
 
@@ -626,8 +676,18 @@ export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions
  * NAMING CONTRACT — changing this rule is a BREAKING CHANGE: index.ts and cross-file
  * FK imports reference these paths. Pinned by naming-contract.test.ts.
  */
+/** The import specifier a barrel (or a sibling file) uses for a model — the FILENAME rule
+ *  minus the extension. Derived from modelFileName so the two can never disagree; they did,
+ *  and a multi-schema pull emitted `import … from './refresh-tokens'` next to a file called
+ *  `auth-refresh-tokens.ts`. */
+export function modelImportPath(table: string): string {
+  return `./${modelFileName(table).replace(/\.ts$/, '')}`;
+}
+
 export function modelFileName(table: string): string {
-  return `${bareName(table).replace(/_/g, '-')}.ts`;
+  const owner = schemaOf(table);
+  const bare = bareName(table).replace(/_/g, '-');
+  return owner === 'public' ? `${bare}.ts` : `${owner.replace(/_/g, '-')}-${bare}.ts`;
 }
 
 /** The bare tables (other than itself) a table's rendered FKs reference within the pulled set. */
@@ -664,7 +724,7 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   const files: RenderedModelFile[] = tables.map((t) => {
     const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz);
     const crossImports = referencedTables(t, known).map(
-      (target) => `import { ${modelVarName(target)} } from './${bareName(target).replace(/_/g, '-')}';`,
+      (target) => `import { ${modelVarName(target)} } from '${modelImportPath(target)}';`,
     );
     const header = [importHeader(block), ...crossImports].join('\n');
     return { file: modelFileName(t.table), source: `${header}\n\n${block}\n` };
@@ -683,13 +743,13 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
       // The --derived-out layer, imported rather than re-declared — the barrel must WIRE it
       // or db:plan silently compares against models only.
       ...(extNames.length ? [`import { ${extNames.join(', ')} } from '${ext!.specifier}';`] : []),
-      ...names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`),
+      ...names.map((n, i) => `import { ${n} } from '${modelImportPath(tables[i].table)}';`),
     ].join('\n'),
     `export {\n${names.map((n) => `  ${n},`).join('\n')}\n};`,
     // Re-exported so the barrel remains the one place that describes the database.
     ...(extNames.length ? [`export { ${extNames.join(', ')} };`] : []),
     ...(opts.derived?.block ? [opts.derived.block] : []),
-    moduleFooter(names, opts.derived, true, ext),
+    moduleFooter(names, opts.derived, true, ext, snapshot.extensions),
   ].join('\n\n');
   files.push({ file: 'index.ts', source: index + '\n' });
 

package/src/cli/schema-introspect.ts

@@ -105,6 +105,8 @@ export interface SchemaSnapshot {
   enums?: EnumType[];
   /** Standalone sequences (serial-owned ones excluded). Absent/empty when none. */
   sequences?: SequenceSchema[];
+  /** Installed extensions, `plpgsql` excluded. Absent when the read predates this. */
+  extensions?: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -216,6 +218,27 @@ ORDER BY n.nspname, t.typname;
  * has an 'a'/'i' pg_depend link to its column and stays represented BY that column).
  * These hold state, so they are base-schema: migrated, diffed, fingerprinted.
  */
+/**
+ * Installed extensions — the bootstrap a declared state needs before anything else.
+ *
+ * Database-wide, not per-schema: `pg_extension` has no schema filter worth applying, and an
+ * extension installed into `public` is just as required by a model in `auth`. So this read
+ * ignores `--schema` deliberately.
+ *
+ * `plpgsql` is excluded because PostgreSQL installs it into every database by default —
+ * emitting `CREATE EXTENSION IF NOT EXISTS plpgsql` is noise, not bootstrap.
+ *
+ * Without this, a declared state that renders `field.pgType('hstore')` compiles to a CREATE
+ * TABLE whose type does not exist, and `db:check`'s from-scratch ring fails with
+ * `type "hstore" does not exist` — the state describes a database it cannot build.
+ */
+export const EXTENSIONS_SQL = `
+SELECT extname AS name
+FROM pg_extension
+WHERE extname <> 'plpgsql'
+ORDER BY extname;
+`.trim();
+
 export const SEQUENCES_SQL = `
 SELECT
   n.nspname AS schema,
@@ -540,6 +563,7 @@ export interface SchemaRows {
   enums?: EnumRow[];
   indexes?: IndexRow[];
   sequences?: SequenceRow[];
+  extensions?: ExtensionRow[];
 }
 
 /**
@@ -618,10 +642,18 @@ export function assembleSchema(rows: SchemaRows): SchemaSnapshot {
     .map(sequenceRowToDescriptor)
     .sort((a, b) => a.name.localeCompare(b.name));
 
+  // ABSENT vs EMPTY matters: a caller that did not run the extensions query leaves the key
+  // off entirely, and the renderer must not read that as "this database has none" and emit
+  // an empty list that later looks authoritative.
+  const extensions = rows.extensions === undefined
+    ? undefined
+    : rows.extensions.map((r) => r.name).sort();
+
   return {
     tables: [...tables.values()].sort((a, b) => a.table.localeCompare(b.table)),
     enums,
     ...(sequences.length ? { sequences } : {}),
+    ...(extensions !== undefined ? { extensions } : {}),
   };
 }
 
@@ -631,13 +663,15 @@ export function assembleSchema(rows: SchemaRows): SchemaSnapshot {
  * (the ops Lambda `db:query` in production, a fake in tests) and folds the rows with
  * `assembleSchema`. This is the `current` side `db:generate` diffs the compiled Models against.
  */
+export interface ExtensionRow { name: string }
+
 export async function introspectSchema(session: SessionRunner): Promise<SchemaSnapshot> {
   // ONE session, so all five queries see one database at one moment, under one pinned
   // search_path. Column defaults, CHECK constraints and index expressions all deparse
   // relative to that path — spread across separate connections these five rows can render
   // the same schema two ways, and a fingerprint minted from the mix describes nothing.
-  const [columns, constraints, enums, indexes, sequences] = await session(
-    [COLUMNS_SQL, CONSTRAINTS_SQL, ENUMS_SQL, INDEXES_SQL, SEQUENCES_SQL],
+  const [columns, constraints, enums, indexes, sequences, extensions] = await session(
+    [COLUMNS_SQL, CONSTRAINTS_SQL, ENUMS_SQL, INDEXES_SQL, SEQUENCES_SQL, EXTENSIONS_SQL],
     INTROSPECTION_SESSION,
   );
   return assembleSchema({
@@ -646,5 +680,6 @@ export async function introspectSchema(session: SessionRunner): Promise<SchemaSn
     enums: enums as EnumRow[],
     indexes: indexes as IndexRow[],
     sequences: sequences as SequenceRow[],
+    extensions: extensions as ExtensionRow[],
   });
 }

package/src/plugin.ts

@@ -9,17 +9,35 @@
 
 import type { StorageAdapter } from './storage/index';
 
-/** Minimal plugin context (compatible with @everystack/server/plugin PluginContext) */
+/**
+ * These types MIRROR @everystack/server/plugin. They are not imported from it, and that
+ * is deliberate: server imports `@everystack/cli/apply`, `/reconcile`, `/exec` and more,
+ * so a type import in the other direction closes a package cycle. Both packages ship
+ * TypeScript source, so a type-only import still drags the whole module graph in.
+ *
+ * The copy going stale is what broke a consumer: server made `publishJob` optional and
+ * gave it an options argument, nothing here compared the two declarations, and `Plugin`
+ * is contravariant in `ctx` — so cli's `Plugin` silently stopped being assignable to
+ * server's and the TS2322 landed in their build instead of ours.
+ *
+ * **The link is `__tests__/cli/plugin-type-compat.test.ts`**, which imports BOTH and
+ * asserts assignability at compile time. The test can cross the boundary because it is
+ * not part of either package's published graph. Drift now fails there, in this repo, on
+ * the commit that causes it. If you change a shape below, that test is the gate.
+ */
+
+/** Mirrors @everystack/server/plugin PluginContext. `publishJob` is OPTIONAL (a lean app
+ *  with no @everystack/jobs never sets it) and takes an options argument. */
 interface PluginContext {
   db: any;
   schema: Record<string, any>;
   verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
   environment: string;
-  publishJob: (type: string, payload: unknown) => Promise<string>;
+  publishJob?: (type: string, payload: unknown, options?: { schedulable?: boolean; runAt?: Date }) => Promise<string>;
   [key: string]: unknown;
 }
 
-/** Minimal route type (compatible with @everystack/server Route) */
+/** Mirrors @everystack/server Route. */
 interface Route {
   path: string;
   method?: string;
@@ -27,10 +45,10 @@ interface Route {
   handler: (req: Request) => Promise<Response>;
 }
 
-/** Action handler type (compatible with @everystack/server/plugin ActionHandler) */
+/** Mirrors @everystack/server/plugin ActionHandler. */
 type ActionHandler = (payload: unknown, ctx: PluginContext) => Promise<unknown>;
 
-/** Plugin factory function */
+/** Mirrors @everystack/server/plugin Plugin. */
 type Plugin = (ctx: PluginContext) => Promise<{
   routes?: Route[];
   actions?: Record<string, ActionHandler>;