@everystack/cli 0.3.0 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -65,7 +65,7 @@
     "node-forge": "1.4.0",
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
-    "@everystack/model": "0.3.0"
+    "@everystack/model": "0.3.3"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",

package/src/cli/authz-compile.ts

@@ -75,6 +75,22 @@ function softDeleteGuard(sqlColumn: string): string {
   return `(${sqlColumn} IS NULL)`;
 }
 
+/**
+ * The transitive-owner (`via:`) predicate, in deparser normal form — a parent
+ * subquery that scopes the child to rows whose FK points at a parent the caller
+ * owns. The exact whitespace (3 spaces before FROM, 2 before WHERE, the newlines)
+ * is what `pg_get_expr` emits and the contract stores, so it is reproduced byte
+ * for byte; the inner owner predicate reuses {@link ownerPredicate} (table-qualified):
+ *
+ *   (upload_id IN ( SELECT uploads.id
+ *      FROM uploads
+ *     WHERE (uploads.user_id = ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))))
+ */
+function viaPredicate(v: ViaRef): string {
+  const parentOwner = ownerPredicate(`${v.parentTable}.${v.parentOwner.sqlColumn}`, v.parentOwner.type, v.parentOwner.claim);
+  return `(${v.fkColumn} IN ( SELECT ${v.parentTable}.${v.parentPk}\n   FROM ${v.parentTable}\n  WHERE ${parentOwner}))`;
+}
+
 // ---------------------------------------------------------------------------
 // Ability classification.
 // ---------------------------------------------------------------------------
@@ -96,10 +112,18 @@ interface OwnerRef {
 export function modelOwner(model: ModelDescriptor, opts: CompileOptions = {}): { table: string; ownerColumn: string; claim: string } | null {
   const owner = resolveOwner(model);
   if (!owner) return null;
-  const schema = opts.schema ?? 'public';
+  const schema = resolveSchema(model, opts);
   return { table: `${schema}.${model.table}`, ownerColumn: owner.sqlColumn, claim: owner.claim };
 }
 
+/**
+ * The schema a model's table lives in. The model's own `schema` wins (a 'dist'
+ * model is dist in any run), then the generate call's default, then 'public'.
+ */
+function resolveSchema(model: ModelDescriptor, opts: CompileOptions): string {
+  return model.schema ?? opts.schema ?? 'public';
+}
+
 /** Resolve the owner column (SQL name + type + claim) from the first owner ability. */
 function resolveOwner(model: ModelDescriptor): OwnerRef | null {
   const ownerAbility = model.abilities.find((a) => a.condition.owner);
@@ -112,11 +136,79 @@ function resolveOwner(model: ModelDescriptor): OwnerRef | null {
   };
 }
 
+interface ViaRef {
+  /** The child's FK column, snake_cased (e.g. `upload_id`). */
+  fkColumn: string;
+  /** The referenced parent table (e.g. `uploads`). */
+  parentTable: string;
+  /** The parent's primary-key column, snake_cased (e.g. `id`). */
+  parentPk: string;
+  /** The parent's resolved owner — the predicate scopes the subquery on this. */
+  parentOwner: OwnerRef;
+}
+
+/**
+ * Resolve the transitive-owner spec from the first `via:` ability. The named field
+ * must carry `.references()`; the compiler follows that thunk to the parent
+ * descriptor and resolves the parent's own `owner` ability. Throws a clear error
+ * when the field has no FK or the parent declares no owner — a `via:` that cannot
+ * reach an owner is a model bug, not a silently-empty policy.
+ */
+function resolveVia(model: ModelDescriptor): ViaRef | null {
+  const viaAbility = model.abilities.find((a) => a.condition.via);
+  if (!viaAbility) return null;
+  const fieldKey = viaAbility.condition.via!;
+  const ref = model.fields[fieldKey]?.spec.references;
+  if (!ref) {
+    throw new Error(`via: '${fieldKey}' on '${model.table}' must name a field declared with .references()`);
+  }
+  const parent = ref() as ModelDescriptor;
+  const parentOwner = resolveOwner(parent);
+  if (!parentOwner) {
+    throw new Error(`via: parent model '${parent.table}' (from '${model.table}.${fieldKey}') declares no owner ability`);
+  }
+  return {
+    fkColumn: toSnakeCase(fieldKey),
+    parentTable: parent.table,
+    parentPk: toSnakeCase(parent.primaryKey[0] ?? 'id'),
+    parentOwner,
+  };
+}
+
 /** The conventional soft-delete column SQL name, when the model has one. */
 function softDeleteColumn(model: ModelDescriptor): string | null {
   return 'deletedAt' in model.fields ? 'deleted_at' : null;
 }
 
+/**
+ * A column-scoped self read — `can('read', { owner, columns })`. It compiles to a COLUMN
+ * grant (`GRANT SELECT (cols)`) plus a `<table>_select_self` policy, NOT a table grant and
+ * NOT a `_select_own` policy: the row is scoped by the owner predicate, the fields by the
+ * column list (`auth.users` → id/email/role to the owner, never the password hash). It is
+ * excluded from the table-grant and owner-read paths so the two never double-emit.
+ */
+function isColumnRead(a: Ability): boolean {
+  return a.action === 'read' && Boolean(a.condition.owner) && Boolean(a.condition.columns?.length);
+}
+
+/**
+ * Column grants from the column-scoped read abilities: the read role (`authenticated`, since
+ * the ability is owner-scoped, not role-gated) gets `SELECT (cols)`. Field keys are snake_cased
+ * to SQL columns and sorted, matching the introspected contract. Returns undefined when no
+ * ability declares columns — an introspected contract omits the key rather than carry an empty
+ * object, so the compiled one must too (or the round-trip diff would false-fire).
+ */
+function compileColumnGrants(abilities: readonly Ability[]): Record<string, Record<string, string[]>> | undefined {
+  const out: Record<string, Record<string, string[]>> = {};
+  for (const a of abilities) {
+    if (!isColumnRead(a)) continue;
+    const role = a.condition.role ?? 'authenticated';
+    const cols = [...a.condition.columns!].map(toSnakeCase).sort();
+    (out[role] ??= {}).SELECT = cols;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Compile.
 // ---------------------------------------------------------------------------
@@ -127,20 +219,34 @@ function softDeleteColumn(model: ModelDescriptor): string | null {
  * output is byte-comparable with an introspected contract.
  */
 export function compileTableContract(model: ModelDescriptor, opts: CompileOptions = {}): TableContract {
-  const schema = opts.schema ?? 'public';
+  const schema = resolveSchema(model, opts);
   const table = `${schema}.${model.table}`;
   const owner = resolveOwner(model);
+  const via = resolveVia(model);
   const sdCol = softDeleteColumn(model);
-  const ownerPred = owner ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim) : null;
+  // The row-scoping predicate: a direct owner column, else a transitive `via:`
+  // parent subquery. Both drive the same owner-gated policies (select/insert/
+  // update/delete_own); only the predicate text differs.
+  const rowPred = owner
+    ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim)
+    : via
+      ? viaPredicate(via)
+      : null;
   const sdGuard = sdCol ? softDeleteGuard(sdCol) : null;
 
+  // A "row-scoped" condition is either a direct owner or a transitive via.
+  const rowScoped = (a: Ability): boolean => Boolean(a.condition.owner || a.condition.via);
+
   const abilities = model.abilities;
   const hasAdminManage = abilities.some((a) => a.action === 'manage' && a.condition.role === 'admin');
-  const hasPublicRead = abilities.some((a) => a.action === 'read' && !a.condition.role && !a.condition.owner);
-  const hasOwnerRead = abilities.some((a) => a.action === 'read' && a.condition.owner);
+  const hasPublicRead = abilities.some((a) => a.action === 'read' && !a.condition.role && !rowScoped(a));
+  // A column-scoped read is row-scoped but emits a self policy + column grant, not the
+  // full-row owner read — so it is excluded here and handled by its own branch.
+  const hasOwnerRead = abilities.some((a) => a.action === 'read' && rowScoped(a) && !isColumnRead(a));
+  const hasColumnRead = abilities.some(isColumnRead);
   const canCreate = abilities.some((a) => a.action === 'create');
-  const hasUpdateOwner = abilities.some((a) => a.action === 'update' && a.condition.owner);
-  const hasDeleteOwner = abilities.some((a) => a.action === 'delete' && a.condition.owner);
+  const hasUpdateOwner = abilities.some((a) => a.action === 'update' && rowScoped(a));
+  const hasDeleteOwner = abilities.some((a) => a.action === 'delete' && rowScoped(a));
 
   const t = model.table;
   const policies: PolicyContract[] = [];
@@ -161,51 +267,97 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     policy(`${t}_select_anon`, 'SELECT', ['anon'], anonUsing, null);
 
     let authedUsing = anonUsing;
-    if (sdGuard && ownerPred) authedUsing = `(${sdGuard} OR ${ownerPred})`;
-    else if (ownerPred && !sdGuard) authedUsing = ownerPred;
+    if (sdGuard && rowPred) authedUsing = `(${sdGuard} OR ${rowPred})`;
+    else if (rowPred && !sdGuard) authedUsing = rowPred;
     policy(`${t}_select_authenticated`, 'SELECT', ['authenticated'], authedUsing, null);
-  } else if (hasOwnerRead && ownerPred) {
-    // owner-only read — no anon visibility; you see only your own rows.
-    policy(`${t}_select_own`, 'SELECT', ['authenticated'], ownerPred, null);
+  } else if (hasOwnerRead && rowPred) {
+    // owner-scoped read — no anon visibility; you see only the rows you own
+    // (directly, or transitively through a `via:` parent).
+    policy(`${t}_select_own`, 'SELECT', ['authenticated'], rowPred, null);
+  } else if (hasColumnRead && rowPred) {
+    // column-scoped self read — `authenticated` reads only its OWN row, and only the
+    // granted columns (the GRANT scopes fields; this policy scopes rows). Named
+    // `_select_self`, distinct from the full-row `_select_own`.
+    policy(`${t}_select_self`, 'SELECT', ['authenticated'], rowPred, null);
   }
 
   // owner-gated writes. INSERT checks ownership (you can only create rows you own);
-  // UPDATE gates + checks; DELETE gates.
-  if (ownerPred) {
-    if (canCreate) policy(`${t}_insert_own`, 'INSERT', ['authenticated'], null, ownerPred);
-    if (hasUpdateOwner) policy(`${t}_update_own`, 'UPDATE', ['authenticated'], ownerPred, ownerPred);
-    if (hasDeleteOwner) policy(`${t}_delete_own`, 'DELETE', ['authenticated'], ownerPred, null);
+  // UPDATE gates + checks; DELETE gates. `rowPred` is the direct-owner or `via:` predicate.
+  if (rowPred) {
+    if (canCreate) policy(`${t}_insert_own`, 'INSERT', ['authenticated'], null, rowPred);
+    if (hasUpdateOwner) policy(`${t}_update_own`, 'UPDATE', ['authenticated'], rowPred, rowPred);
+    if (hasDeleteOwner) policy(`${t}_delete_own`, 'DELETE', ['authenticated'], rowPred, null);
   }
 
   policies.sort((a, b) => a.name.localeCompare(b.name));
 
   return {
     table,
-    rls: { enabled: true, forced: true },
-    grants: compileGrants(hasAdminManage),
+    // The FORCE axiom: FORCE iff the write principal is subject to its own RLS
+    // policies. 'app' writes through its policies -> FORCE; 'worker'/'functions'
+    // write on the owner connection and bypass RLS -> ENABLE-not-FORCE (on RDS the
+    // owner is not a superuser, so a FORCEd table would block the owner's own writes).
+    rls: { enabled: true, forced: model.writtenBy === 'app' },
+    grants: compileGrants(abilities),
+    ...(compileColumnGrants(abilities) ? { columnGrants: compileColumnGrants(abilities) } : {}),
     policies,
   };
 }
 
+/** The four DML privileges, sorted — the expansion of a `manage` ability. */
+const CRUD = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+
+/** The SQL privilege a single CRUD verb grants. `manage` expands to all of CRUD. */
+const VERB: Record<Exclude<Ability['action'], 'manage'>, string> = {
+  read: 'SELECT',
+  create: 'INSERT',
+  update: 'UPDATE',
+  delete: 'DELETE',
+};
+
+/** The privileges an ability's action grants (a single verb, or all of CRUD for `manage`). */
+function verbsFor(action: Ability['action']): string[] {
+  return action === 'manage' ? [...CRUD] : [VERB[action]];
+}
+
 /**
- * The grant tier for a public app table. everystack's model is coarse grants +
- * fine-grained RLS: anon may read, authenticated may CRUD, admin may CRUD — and
- * RLS (the policies above) is what actually restricts which rows. So the grants
- * are uniform across app tables, not derived per-ability (profiles has no create
- * ability yet is granted INSERT; uploads is owner-only yet grants anon SELECT).
+ * Precise grants — derive each role's privilege set from the abilities, not a
+ * uniform tier. everystack's model is coarse grants + fine-grained RLS: the grant
+ * is the gate (which roles may touch the table at all), RLS restricts which rows.
+ * A role gets a privilege iff some ability grants that verb to it:
+ *
+ *   - `can(action, { role })`            -> that role gets the verb(s)
+ *   - public/owner/via ability (no role) -> `authenticated` gets the verb(s)
+ *   - a *public* read (no role, no owner/via) -> `anon` also gets SELECT
  *
- * A precise, least-exposure grant set (drop the anon SELECT on an owner-only
- * table) is a deliberate future refinement — it would tighten the live DB, which
- * the diff would surface and reconcile would apply. Today this reproduces the
- * deployed grants so the contract round-trips.
+ * No ability for a role means no grant for that role: an ability-less (internal)
+ * table grants nothing, an owner-only table grants no anon SELECT, an admin-managed
+ * table grants admin CRUD only. Deterministic: roles and privilege lists sorted,
+ * so the output is byte-comparable with an introspected contract.
  */
-function compileGrants(hasAdminManage: boolean): Record<string, string[]> {
-  const crud = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
-  return {
-    anon: ['SELECT'],
-    authenticated: [...crud],
-    ...(hasAdminManage ? { admin: [...crud] } : {}),
+function compileGrants(abilities: readonly Ability[]): Record<string, string[]> {
+  const grants: Record<string, Set<string>> = {};
+  const add = (role: string, verbs: string[]): void => {
+    const set = (grants[role] ??= new Set<string>());
+    for (const v of verbs) set.add(v);
   };
+  for (const a of abilities) {
+    // A column-scoped read grants `SELECT (cols)` (a column grant), not a table-level
+    // privilege — emitted by compileColumnGrants, skipped here so it never leaks a
+    // whole-table grant that would defeat the column scoping.
+    if (isColumnRead(a)) continue;
+    const verbs = verbsFor(a.action);
+    if (a.condition.role) {
+      add(a.condition.role, verbs);
+    } else {
+      add('authenticated', verbs);
+      // A public read (no role, not owner/via-scoped) is anon-visible.
+      if (a.action === 'read' && !a.condition.owner && !a.condition.via) add('anon', ['SELECT']);
+    }
+  }
+  const out: Record<string, string[]> = {};
+  for (const role of Object.keys(grants).sort()) out[role] = [...grants[role]].sort();
+  return out;
 }
 
 // Kept exported for callers that want just the privilege set for a role tier.

package/src/cli/authz-owner-probe.ts

@@ -34,6 +34,13 @@ export interface OwnerProbe {
   claim?: string;
   /** App role to assume. Default `authenticated`. */
   role?: string;
+  /**
+   * The table has an intended PUBLIC read (a `can('read')` with no owner/role/via — anon /
+   * authenticated may SELECT every row). Reader isolation is then NOT expected (a Twitter-clone's
+   * posts/profiles/likes/follows are public), so a visible other-owner row is by design, not an
+   * IDOR. Writer isolation is still enforced — the rows are owner-WRITE even when public-read.
+   */
+  publicRead?: boolean;
 }
 
 export type OwnerCheck = 'discover' | 'read-own' | 'read-other' | 'write-other';
@@ -49,7 +56,7 @@ export interface OwnerProbeResult {
 }
 
 export interface OwnerFinding {
-  severity: 'read-leak' | 'write-leak' | 'vacuous' | 'unprobed';
+  severity: 'read-leak' | 'write-leak' | 'vacuous' | 'unprobed' | 'public-read';
   table: string;
   detail: string;
 }
@@ -164,8 +171,12 @@ export function toOwnerProbeResult(row: any): OwnerProbeResult {
  *   - unprobed   — fewer than two distinct owners in the table; isolation can't be tested (a
  *                  warning, not a verdict — seed a second owner's row, or accept the gap).
  * A correctly-isolated table with two owners produces zero findings.
+ *
+ * `publicReadTables` names tables with an intended public read: their reader-isolation check is
+ * informational (`public-read`), not a leak — but writer isolation is still enforced, so a
+ * write-leak on a public-read table is still a failure.
  */
-export function evaluateOwnerProbe(results: OwnerProbeResult[]): OwnerFinding[] {
+export function evaluateOwnerProbe(results: OwnerProbeResult[], publicReadTables: Set<string> = new Set()): OwnerFinding[] {
   const findings: OwnerFinding[] = [];
   const byTable = new Map<string, Map<OwnerCheck, OwnerProbeResult>>();
   for (const r of results) {
@@ -181,6 +192,7 @@ export function evaluateOwnerProbe(results: OwnerProbeResult[]): OwnerFinding[]
     const own = checks.get('read-own');
     const other = checks.get('read-other');
     const write = checks.get('write-other');
+    const publicRead = publicReadTables.has(table);
 
     if (own && own.outcome !== 'visible') {
       findings.push({ severity: 'vacuous', table,
@@ -188,8 +200,14 @@ export function evaluateOwnerProbe(results: OwnerProbeResult[]): OwnerFinding[]
       continue; // the other checks are meaningless while the owner can't see own rows
     }
     if (other && other.outcome === 'visible') {
-      findings.push({ severity: 'read-leak', table,
-        detail: `as the owner, ${other.rows} of another user's row(s) in ${table} were visible — RLS does not isolate readers (IDOR read)` });
+      // A public-read table is SUPPOSED to expose every row — that is not an IDOR. Report it as
+      // informational so the operator sees it was recognized, not a leak. Owner-private tables
+      // (no public read) still fail here.
+      findings.push(publicRead
+        ? { severity: 'public-read', table,
+            detail: `${table} has an intended public read — reader isolation not applicable (the ${other.rows} other-owner row(s) are public by design); writer isolation still enforced` }
+        : { severity: 'read-leak', table,
+            detail: `as the owner, ${other.rows} of another user's row(s) in ${table} were visible — RLS does not isolate readers (IDOR read)` });
     }
     if (write && write.outcome === 'visible') {
       findings.push({ severity: 'write-leak', table,

package/src/cli/authz-reconcile.ts

@@ -84,6 +84,7 @@ export function emitReconcileSql(declared: AuthzContract, live: AuthzContract):
     reconcileRls(table, d, l, sql);
     reconcilePolicies(table, d, l, sql);
     reconcileGrants(table, d, l, sql);
+    reconcileColumnGrants(table, d, l, sql);
   }
 
   return sql;
@@ -125,3 +126,27 @@ function reconcileGrants(table: string, d: TableContract, l: TableContract | und
     if (toGrant.length) out.push(`GRANT ${toGrant.join(', ')} ON ${table} TO ${target};`);
   }
 }
+
+/**
+ * Reconcile column-scoped grants — `GRANT SELECT (cols) ON t TO role`. The grantee/privilege
+ * grid is reconciled per (grantee, privilege): add the columns declared-but-not-live, revoke
+ * those live-but-not-declared. This is how `auth.users` exposes id/email/role (and only those)
+ * to `authenticated` without a whole-table grant. Columns are sorted, so a re-pull is a no-op.
+ */
+function reconcileColumnGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
+  const dcg = d.columnGrants ?? {};
+  const lcg = l?.columnGrants ?? {};
+  for (const grantee of [...new Set([...Object.keys(dcg), ...Object.keys(lcg)])].sort()) {
+    const target = grantee.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : grantee;
+    const dPriv = dcg[grantee] ?? {};
+    const lPriv = lcg[grantee] ?? {};
+    for (const priv of [...new Set([...Object.keys(dPriv), ...Object.keys(lPriv)])].sort()) {
+      const declared = new Set(dPriv[priv] ?? []);
+      const live = new Set(lPriv[priv] ?? []);
+      const toRevoke = [...live].filter((c) => !declared.has(c)).sort();
+      const toGrant = [...declared].filter((c) => !live.has(c)).sort();
+      if (toRevoke.length) out.push(`REVOKE ${priv} (${toRevoke.join(', ')}) ON ${table} FROM ${target};`);
+      if (toGrant.length) out.push(`GRANT ${priv} (${toGrant.join(', ')}) ON ${table} TO ${target};`);
+    }
+  }
+}

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

@@ -243,14 +243,20 @@ export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promis
   const schema = flags.schema || 'public';
 
   let probes: OwnerProbe[];
+  let publicReadTables = new Set<string>();
   let rows: any[];
   try {
     step(`Loading models from ${modelsPath}...`);
     const models = await loadModels(modelsPath);
-    probes = models
-      .map((m) => modelOwner(m, { schema }))
-      .filter((o): o is NonNullable<typeof o> => o !== null)
-      .map((o) => ({ table: o.table, ownerColumn: o.ownerColumn, claim: o.claim }));
+    const ownerModels = models
+      .map((m) => ({ m, owner: modelOwner(m, { schema }) }))
+      .filter((x): x is { m: (typeof models)[number]; owner: NonNullable<typeof x.owner> } => x.owner !== null);
+    // A table with a public read (`can('read')`, no owner/role/via) is intentionally not
+    // reader-isolated — flag it so the probe reports its cross-owner reads as expected, not IDOR.
+    const isPublicRead = (m: (typeof models)[number]): boolean =>
+      m.abilities.some((a) => a.action === 'read' && !a.condition.role && !a.condition.owner && !a.condition.via);
+    publicReadTables = new Set(ownerModels.filter(({ m }) => isPublicRead(m)).map(({ owner }) => owner.table));
+    probes = ownerModels.map(({ owner }) => ({ table: owner.table, ownerColumn: owner.ownerColumn, claim: owner.claim }));
     info(`${probes.length} owner-scoped model(s).`);
     if (probes.length === 0) {
       success('db:authz:owner — no owner-scoped models (no `can({ owner })`); nothing to probe.');
@@ -272,14 +278,16 @@ export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promis
     process.exit(1);
   }
 
-  const findings = evaluateOwnerProbe(rows.map(toOwnerProbeResult));
+  const findings = evaluateOwnerProbe(rows.map(toOwnerProbeResult), publicReadTables);
   const leaks = findings.filter((f) => f.severity === 'read-leak' || f.severity === 'write-leak');
   const vacuous = findings.filter((f) => f.severity === 'vacuous');
   const unprobed = findings.filter((f) => f.severity === 'unprobed');
+  const publicReads = findings.filter((f) => f.severity === 'public-read');
 
   console.log('');
   for (const f of leaks) fail(`[LEAK]    ${f.detail}`);
   for (const f of vacuous) fail(`[VACUOUS] ${f.detail}`);
+  for (const f of publicReads) info(`[public]   ${f.detail}`);
   for (const f of unprobed) info(`[unprobed] ${f.detail}`);
   console.log('');
 

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

@@ -20,8 +20,10 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import type { ModelDescriptor } from '@everystack/model';
+import type { ModelDescriptor, Module } from '@everystack/model';
 import { introspectSchema } from '../schema-introspect.js';
+import { compileDrizzleSource } from '../schema-source.js';
+import { compileModuleMigration } from '../migration-compile.js';
 import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, HELD_DROP_PREFIX, type Journal } from '../migration-generate.js';
 import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { FUNCTIONS_SQL, catalogFunctionToDescriptor } from '../security-catalog.js';
@@ -31,6 +33,7 @@ import { step, success, fail, info, warn } from '../output.js';
 
 const DEFAULT_MODELS = 'models/index.ts';
 const DEFAULT_MIGRATIONS = 'drizzle';
+const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 
 /** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
 function lambdaRunner(region: string, fn: string): QueryRunner {
@@ -61,12 +64,82 @@ async function loadModels(modelsPath: string): Promise<ModelDescriptor[]> {
   return models;
 }
 
+/**
+ * Import the app's barrel and return its `modules` array — the greenfield (`--init`) input. A
+ * Module carries the package's extensions + functions on top of its models, so it can emit the
+ * 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[]> {
+  const abs = path.resolve(modelsPath);
+  let mod: any;
+  try {
+    mod = await import(pathToFileURL(abs).href);
+  } catch (err: any) {
+    throw new Error(`Could not load modules from ${modelsPath}: ${err.message}`);
+  }
+  if (Array.isArray(mod.modules)) return mod.modules;
+  const models = mod.models ?? mod.default;
+  if (Array.isArray(models)) return [{ models, extensions: [], functions: [] }];
+  throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
+}
+
+/**
+ * `db:generate --init` — the greenfield generator. Compiles the app's Modules into ONE
+ * complete migration (extensions + schema + authz + package functions/triggers) with NO live
+ * database — the model IS the source. Writes it as the next migration in a (typically empty)
+ * `drizzle/`. Roles are excluded by design (they are `db:provision`). Use it to (re)initialize
+ * a clean migration history: clear `drizzle/`, then `db:generate --init`.
+ */
+async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaOut: string, name: string): Promise<void> {
+  step(`Loading modules from ${modelsPath}...`);
+  const modules = await loadModules(modelsPath);
+  const models = modules.flatMap((m) => m.models);
+  info(`${modules.length} module(s), ${models.length} model(s).`);
+
+  step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
+  await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
+
+  const statements = compileModuleMigration(modules);
+
+  const journalPath = path.join(migrationsDir, 'meta', '_journal.json');
+  let journal: Journal;
+  try {
+    journal = JSON.parse(await fs.readFile(journalPath, 'utf8'));
+  } catch {
+    journal = { version: '7', dialect: 'postgresql', entries: [] };
+  }
+  const { filename, journal: nextJournal } = planMigrationFile(journal, name, Date.now());
+  const filePath = path.join(migrationsDir, filename);
+  await fs.mkdir(path.join(migrationsDir, 'meta'), { recursive: true });
+  await fs.writeFile(filePath, formatMigrationFile(statements), 'utf8');
+  await fs.writeFile(journalPath, JSON.stringify(nextJournal, null, 2) + '\n', 'utf8');
+
+  console.log('');
+  success(`Wrote ${path.relative(process.cwd(), filePath)} (${statements.length} statement(s)) — the complete greenfield migration.`);
+  warn('Roles are NOT in this migration — run `everystack db:provision` (the role chain) before `db:migrate`.');
+  process.exit(0);
+}
+
 export async function dbGenerateCommand(flags: Record<string, string>): Promise<void> {
   const modelsPath = flags.models || DEFAULT_MODELS;
   const migrationsDir = path.resolve(flags.dir || DEFAULT_MIGRATIONS);
+  const schemaOut = path.resolve(flags['schema-out'] || DEFAULT_SCHEMA_OUT);
   const name = flags.name || 'generated';
   const allowDrops = flags['allow-drops'] === 'true';
 
+  // --init: greenfield, no live DB — the model emits the whole migration (extensions + schema +
+  // authz + package functions). The brownfield path below introspects the deployed DB and diffs.
+  if (flags.init === 'true') {
+    try {
+      await dbGenerateInit(modelsPath, migrationsDir, schemaOut, flags.name || 'init');
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
   let models: ModelDescriptor[];
   let current;
   let liveAuthz;
@@ -74,6 +147,11 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     step(`Loading models from ${modelsPath}...`);
     models = await loadModels(modelsPath);
     info(`${models.length} model(s).`);
+    // The drizzle runtime schema is a derived artifact — refresh it from the models
+    // every run (it needs no DB), so a relation-only change with no DDL diff still
+    // updates it. The drift-guard test asserts this file matches the models.
+    step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
+    await fs.writeFile(schemaOut, compileDrizzleSource(models), 'utf8');
     step('Resolving deployed config...');
     const config = await resolveConfig(flags.stage);
     info(`Region: ${config.region}, Function: ${opsFunction(config)}`);

package/src/cli/migration-compile.ts

@@ -19,9 +19,9 @@
  * lands with whole-DB introspection. The emission is identical either way.
  */
 
-import type { ModelDescriptor } from '@everystack/model';
+import type { ModelDescriptor, Module } from '@everystack/model';
 import type { AuthzContract, TableContract } from './authz-contract.js';
-import { compileCreateTable, compileEnums, foreignKeySql, modelConstraintSpecs, type CompileTableOptions } from './schema-compile.js';
+import { compileCreateTable, compileEnums, foreignKeySql, modelConstraintSpecs, qualifiedTable, type CompileTableOptions } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
 import { emitReconcileSql } from './authz-reconcile.js';
 import { emitSchemaSql, type SchemaChange } from './schema-diff.js';
@@ -38,8 +38,36 @@ function emptyTable(table: string): TableContract {
  */
 export function compileMigration(models: ModelDescriptor[], opts: CompileTableOptions = {}): string[] {
   const sql: string[] = [];
+  const schemaOf = (m: ModelDescriptor): string => m.schema ?? 'public';
 
-  // 0. Enum types — `CREATE TYPE … AS ENUM`, before any table/column references them.
+  // 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();
+  sql.push(...schemas.map((s) => `CREATE SCHEMA IF NOT EXISTS "${s}";`));
+
+  // The authz contracts — computed once, used for the schema USAGE grants here and the
+  // table-level reconcile below.
+  const contracts = models.map((m) => compileTableContract(m));
+
+  // 0a-bis. Schema USAGE — a role can't reach a table in a non-public schema without USAGE on
+  //   it, so a table/column grant there is dead without this. Derived from the grants: every
+  //   role that holds any privilege on a table in a non-public schema gets USAGE on that schema
+  //   (public USAGE is granted to PUBLIC by default, so it is never emitted). This replaces the
+  //   hand-written `GRANT USAGE ON SCHEMA auth/ops/dist …` the old bootstrap carried.
+  for (const schema of schemas) {
+    const roles = new Set<string>();
+    for (const c of contracts) {
+      if (!c.table.startsWith(`${schema}.`)) continue;
+      for (const r of Object.keys(c.grants)) roles.add(r);
+      for (const r of Object.keys(c.columnGrants ?? {})) roles.add(r);
+    }
+    if (roles.size) {
+      const targets = [...roles].sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
+      sql.push(`GRANT USAGE ON SCHEMA "${schema}" TO ${targets};`);
+    }
+  }
+
+  // 0b. Enum types — `CREATE TYPE … AS ENUM`, before any table/column references them.
   const enumCreates: SchemaChange[] = compileEnums(models).map((e) => ({ kind: 'createType', name: e.name, values: e.values }));
   sql.push(...emitSchemaSql(enumCreates));
 
@@ -49,11 +77,12 @@ export function compileMigration(models: ModelDescriptor[], opts: CompileTableOp
   // 2. Foreign keys — after every table exists.
   for (const model of models) sql.push(...foreignKeySql(model));
 
-  // 2b. Standalone indexes — after the columns they cover exist.
+  // 2b. Standalone indexes — after the columns they cover exist. The ON clause is the
+  //     schema-qualified table, so a non-public index targets the right table.
   const indexCreates: SchemaChange[] = [];
   for (const model of models) {
     for (const ix of modelConstraintSpecs(model).indexes) {
-      indexCreates.push({ kind: 'createIndex', table: `"${model.table}"`, name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) });
+      indexCreates.push({ kind: 'createIndex', table: qualifiedTable(model), name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) });
     }
   }
   sql.push(...emitSchemaSql(indexCreates));
@@ -61,9 +90,44 @@ export function compileMigration(models: ModelDescriptor[], opts: CompileTableOp
   // 3. Authz — RLS + policies + grants, after the columns they reference. Reuse
   //    the reconcile emitter against the empty baseline: every policy/grant is a
   //    pure creation, in the same dependency-correct order reconcile already uses.
-  const desired: AuthzContract = { tables: models.map((m) => compileTableContract(m)), functions: [] };
-  const baseline: AuthzContract = { tables: models.map((m) => emptyTable(`public.${m.table}`)), functions: [] };
+  //    The baseline keys on each model's resolved schema, so a non-public table
+  //    diffs against its own empty state, not a phantom public one.
+  const desired: AuthzContract = { tables: contracts, functions: [] };
+  const baseline: AuthzContract = { tables: models.map((m) => emptyTable(`${schemaOf(m)}.${m.table}`)), functions: [] };
   sql.push(...emitReconcileSql(desired, baseline));
 
   return sql;
 }
+
+/**
+ * Compile a set of Modules into one COMPLETE greenfield migration — the whole deploy, no
+ * hand-written bootstrap left:
+ *
+ *   1. CREATE EXTENSION (deduped, sorted)        — the bootstrap a package's SQL needs
+ *   2. compileMigration(flattened models)        — schemas, tables, FKs, indexes, RLS, authz
+ *   3. package functions/triggers (each thunk)   — imperative package SQL, AFTER the tables
+ *
+ * Roles are NOT emitted — they are cluster-global (`db:provision`), and the GRANTs in step 2
+ * assume they exist (as the dogfood pre-creates them). `compileMigration` is left untouched as
+ * the schema+authz core the contract round-trips through; the functions are emitted verbatim
+ * here, outside that round-trip (they are imperative, package-owned — not modeled).
+ */
+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.
+  sql.push(...compileMigration(modules.flatMap((m) => m.models), opts));
+
+  // 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.
+  for (const fn of modules.flatMap((m) => m.functions)) {
+    const text = fn().trim();
+    if (text) sql.push(text);
+  }
+
+  return sql;
+}

package/src/cli/migration-generate.ts

@@ -86,6 +86,9 @@ export function unmodeledTables(models: ModelDescriptor[], current: SchemaSnapsh
  */
 export function generateMigrationSql(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
   const schema = opts.schema ?? 'public';
+  // A table's schema comes from the model first (package tables live in dist/ops/auth),
+  // then the call default — so one run spans schemas.
+  const schemaOf = (m: ModelDescriptor): string => m.schema ?? schema;
   const desiredEnums = compileEnums(models);
   const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema })), enums: desiredEnums };
   const declaredTables = new Set(desired.tables.map((t) => t.table));
@@ -99,7 +102,7 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   const renames = compileRenames(models, { schema });
   const changes = diffSchema(desired, scopedCurrent, renames);
 
-  const modelByTable = new Map(models.map((m) => [`${schema}.${m.table}`, m]));
+  const modelByTable = new Map(models.map((m) => [`${schemaOf(m)}.${m.table}`, m]));
   const emitted = emitSchemaSql(changes, {
     createTable: (change) => {
       const model = modelByTable.get(change.table);

package/src/cli/model-api.ts

@@ -18,6 +18,7 @@
 export * from './schema-compile.js';
 export * from './schema-introspect.js';
 export * from './schema-diff.js';
+export * from './schema-source.js';
 export * from './model-render.js';
 export * from './migration-compile.js';
 export * from './migration-generate.js';

package/src/cli/schema-compile.ts

@@ -40,6 +40,7 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
   const checks: CheckConstraint[] = [];
   const indexes: IndexSchema[] = [];
   let checkIndex = 0;
+  const usedIndexNames = new Set<string>();
   for (const con of model.constraints) {
     if (con.kind === 'unique') {
       const cols = con.columns.map(toSnakeCase);
@@ -48,8 +49,16 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
       checks.push({ name: `${model.table}_check_${checkIndex++}`, expr: con.predicate });
     } else if (con.kind === 'index') {
       const cols = con.columns.map(toSnakeCase);
+      // Disambiguate multiple indexes over the same columns — e.g. a full index plus a
+      // partial one (`familyId` and `familyId WHERE status='active'`): the name must be
+      // unique within the table for CREATE to succeed. The diff matches indexes by content
+      // (columns + uniqueness + predicate), never by name, so the suffix never affects the
+      // round-trip. Declaration order is deterministic, so the name is stable across calls.
+      let name = `${model.table}_${cols.join('_')}_index`;
+      for (let n = 2; usedIndexNames.has(name); n++) name = `${model.table}_${cols.join('_')}_index_${n}`;
+      usedIndexNames.add(name);
       indexes.push({
-        name: `${model.table}_${cols.join('_')}_index`,
+        name,
         columns: cols,
         unique: con.isUnique,
         ...(con.predicate ? { where: con.predicate } : {}),
@@ -77,6 +86,12 @@ const PG_TYPE: Record<string, string> = {
 };
 
 function pgType(spec: FieldSpec): string {
+  // An array is the base type with `[]` appended — `text` → `text[]`, exactly as
+  // `format_type` spells it.
+  return spec.isArray ? `${scalarPgType(spec)}[]` : scalarPgType(spec);
+}
+
+function scalarPgType(spec: FieldSpec): string {
   // Parameterized types build their own canonical string — exactly as `format_type`
   // spells it (no space after the comma; `varchar` is `character varying`; a
   // precision-only numeric carries scale 0), so an unchanged column round-trips clean.
@@ -132,7 +147,7 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
     out.push({
       name: `${model.table}_${col}_${target.table}_${targetPk}_fk`,
       columns: [col],
-      refTable: target.table,
+      refTable: refTableName(target),
       refColumns: [targetPk],
       ...refActions(field.spec),
     });
@@ -146,7 +161,7 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
     out.push({
       name: `${model.table}_${cols.join('_')}_${target.table}_${refCols.join('_')}_fk`,
       columns: cols,
-      refTable: target.table,
+      refTable: refTableName(target),
       refColumns: refCols,
       ...refActions(con),
     });
@@ -155,6 +170,22 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
   return out;
 }
 
+/**
+ * The referenced table's name as the FK should carry it — schema-qualified for a non-public
+ * target (`auth.users`), bare for a public one (`uploads`). A cross-schema FK (auth → auth, or
+ * public → auth) must name the schema, and `pg_get_constraintdef` deparses it qualified when the
+ * target schema is off the search_path — so the desired side must match, or an unchanged auth FK
+ * would read as drift. public stays bare because it is on the search_path (the proven output).
+ */
+function refTableName(target: ModelDescriptor): string {
+  return target.schema && target.schema !== 'public' ? `${target.schema}.${target.table}` : target.table;
+}
+
+/** Quote each dot-separated part of a (possibly schema-qualified) name: `auth.users` → `"auth"."users"`. */
+function quoteParts(name: string): string {
+  return name.split('.').map((p) => `"${p}"`).join('.');
+}
+
 /** The ` ON DELETE … ON UPDATE …` clause for a FK, or '' when both are the default. */
 function refActionSql(fk: { onDelete?: string; onUpdate?: string }): string {
   let s = '';
@@ -168,11 +199,22 @@ function defaultExpr(spec: FieldSpec): string | null {
   switch (spec.defaultKind) {
     case 'now': return 'now()';
     case 'random': return 'gen_random_uuid()';
-    case 'value': return literal(spec.default);
+    case 'value':
+      return spec.isArray && Array.isArray(spec.default) ? arrayLiteral(spec.default) : literal(spec.default);
     default: return null;
   }
 }
 
+/**
+ * A Postgres array literal for a default — `[]` → `'{}'`, `['a','b']` → `'{"a","b"}'`.
+ * The introspected form carries a `::type[]` cast (`'{}'::text[]`) that `normalizeDefault`
+ * strips, so the bare literal round-trips.
+ */
+function arrayLiteral(arr: unknown[]): string {
+  const elems = arr.map((v) => (typeof v === 'string' ? `"${v.replace(/"/g, '\\"')}"` : String(v)));
+  return `'{${elems.join(',')}}'`;
+}
+
 function literal(value: unknown): string {
   if (typeof value === 'string') return `'${value.replace(/'/g, "''")}'`;
   if (typeof value === 'boolean') return value ? 'true' : 'false';
@@ -278,6 +320,18 @@ export interface CompileTableOptions {
   indent?: string;
 }
 
+/**
+ * A model's table as a quoted SQL name — schema-qualified only for a non-public
+ * schema. Drizzle leaves `public` tables bare (`"posts"`), and the example's
+ * brownfield DDL matches that, so a public model stays unqualified; a package
+ * table in its own schema becomes `"dist"."blobs"`.
+ */
+export function qualifiedTable(model: ModelDescriptor): string {
+  return model.schema && model.schema !== 'public'
+    ? `"${model.schema}"."${model.table}"`
+    : `"${model.table}"`;
+}
+
 /**
  * `CREATE TABLE` for a model's fields. Single-column primary keys are inline;
  * composite keys and uniques become table constraints, named the way drizzle
@@ -322,7 +376,7 @@ export function compileCreateTable(model: ModelDescriptor, opts: CompileTableOpt
     lines.push(`${indent}CONSTRAINT "${ck.name}" CHECK (${ck.expr})`);
   }
 
-  return `CREATE TABLE "${model.table}" (\n${lines.join(',\n')}\n);`;
+  return `CREATE TABLE ${qualifiedTable(model)} (\n${lines.join(',\n')}\n);`;
 }
 
 /**
@@ -337,7 +391,7 @@ export function compileCreateTable(model: ModelDescriptor, opts: CompileTableOpt
  * helpers, so they never disagree.)
  */
 export function compileTableSchema(model: ModelDescriptor, opts: { schema?: string } = {}): TableSchema {
-  const schema = opts.schema ?? 'public';
+  const schema = model.schema ?? opts.schema ?? 'public';
   const entries = Object.entries(model.fields);
 
   const columns = entries.map(([name, field]) => ({
@@ -410,9 +464,12 @@ export function foreignKeySql(model: ModelDescriptor): string[] {
   return modelForeignKeys(model).map((fk) => {
     const cols = fk.columns.map((c) => `"${c}"`).join(', ');
     const refCols = fk.refColumns.map((c) => `"${c}"`).join(', ');
+    // Both sides are schema-qualified for a non-public table — `ALTER TABLE "auth"."identities"`
+    // and `REFERENCES "auth"."users"` — so a cross-schema FK targets the right table. public
+    // stays bare-but-quoted (`"uploads"`), preserving the proven output.
     return (
-      `ALTER TABLE "${model.table}" ADD CONSTRAINT "${fk.name}" ` +
-      `FOREIGN KEY (${cols}) REFERENCES "${fk.refTable}"(${refCols})${refActionSql(fk)};`
+      `ALTER TABLE ${qualifiedTable(model)} ADD CONSTRAINT "${fk.name}" ` +
+      `FOREIGN KEY (${cols}) REFERENCES ${quoteParts(fk.refTable)}(${refCols})${refActionSql(fk)};`
     );
   });
 }
@@ -425,9 +482,9 @@ export function foreignKeySql(model: ModelDescriptor): string[] {
  * this map to turn a drop+add into a `RENAME COLUMN`.
  */
 export function compileRenames(models: ModelDescriptor[], opts: { schema?: string } = {}): RenameMap {
-  const schema = opts.schema ?? 'public';
   const map: RenameMap = {};
   for (const model of models) {
+    const schema = model.schema ?? opts.schema ?? 'public';
     for (const [name, field] of Object.entries(model.fields)) {
       const from = field.spec.renamedFrom;
       if (!from) continue;

package/src/cli/schema-diff.ts

@@ -509,7 +509,10 @@ function addConstraintSql(table: string, c: ConstraintSpec): string {
     case 'unique': return `${head} UNIQUE (${colList(c.columns)});`;
     case 'check': return `${head} CHECK ${wrapOnce(c.expr)};`;
     case 'foreignKey': {
-      let s = `${head} FOREIGN KEY (${colList(c.columns)}) REFERENCES ${quote(c.refTable)}(${colList(c.refColumns)})`;
+      // refTable may be schema-qualified (`auth.users`) for a cross-schema FK — quote each part,
+      // not the whole string, or `"auth.users"` reads as one identifier.
+      const refTable = c.refTable.split('.').map(quote).join('.');
+      let s = `${head} FOREIGN KEY (${colList(c.columns)}) REFERENCES ${refTable}(${colList(c.refColumns)})`;
       if (c.onDelete) s += ` ON DELETE ${c.onDelete.toUpperCase()}`;
       if (c.onUpdate) s += ` ON UPDATE ${c.onUpdate.toUpperCase()}`;
       return `${s};`;

package/src/cli/schema-source.ts

@@ -0,0 +1,416 @@
+/**
+ * `compileDrizzleSource` — the typed-runtime-table slice of the one generator.
+ *
+ * The sibling of `compileTableSchema` (SQL DDL) and `compileTableContract` (RLS):
+ * those compile a {@link ModelDescriptor} to a migration target; this compiles it
+ * to drizzle-orm TypeScript SOURCE TEXT. The emitted `schema.generated.ts`, when
+ * imported, yields the SAME runtime table `toDrizzleTable(model)` builds — but as
+ * literal, fully-typed declarations, so the SSR loaders keep their precise column
+ * types (`toDrizzleTable`'s loop-built table infers `<any>`; literal source does
+ * not). One hand-authored source (`models/*.ts`), the drizzle schema a generated,
+ * drift-guarded artifact.
+ *
+ * The column mapping mirrors `toDrizzleTable` exactly, expressed as text. The two
+ * documented divergences from a hand-written schema (see docs/plans/model-drizzle-codegen.md):
+ *
+ *  - Cross-schema FKs (e.g. `profiles.id → auth.users.id`) are OMITTED — the model
+ *    can't express a reference to a non-Model table, so neither can the emitter.
+ *  - `relationName` strings are synthesized deterministically (the `Relation` type
+ *    carries no name); only the pairing of a belongsTo with its inverse hasMany
+ *    matters, which the synthesis guarantees.
+ *
+ * Pure and deterministic: imports sorted, declarations in model order, relation
+ * keys in declared order — re-running on the same models is byte-identical.
+ *
+ * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
+ */
+
+import type { ModelDescriptor, FieldSpec } from '@everystack/model';
+
+/** `author_id` is the SQL identifier; `authorId` the field key. The single snake-case rule. */
+function toSnakeCase(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
+/** `image_variants` → `imageVariants` (a snake table name to its camelCase drizzle export var). */
+function toCamelCase(name: string): string {
+  return name.replace(/_([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** A JS/TS string literal — single-quoted, the example's style. */
+function strLiteral(value: string): string {
+  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+/** A `.default(<v>)` argument literal for a value default (the JSON forms drizzle accepts). */
+function defaultValueLiteral(value: unknown): string {
+  if (typeof value === 'string') return strLiteral(value);
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (value === null) return 'null';
+  if (typeof value === 'number') return String(value);
+  // Arrays / objects: a JSON literal is valid TS for jsonb defaults.
+  return JSON.stringify(value);
+}
+
+/**
+ * The drizzle pg-core column builder *call* for a field — `text('bio')`,
+ * `timestamp('created_at', { withTimezone: true })`, `uuid('id')` — exactly the
+ * type + args `toDrizzleTable`'s `baseColumn` produces, as source text. Returns
+ * the call and the builder name it used (so the import set can be collected).
+ */
+function baseColumnSource(columnName: string, spec: FieldSpec): { call: string; builder: string } {
+  const n = strLiteral(columnName);
+  switch (spec.type) {
+    case 'text':
+      return { call: `text(${n})`, builder: 'text' };
+    case 'uuid':
+      return { call: `uuid(${n})`, builder: 'uuid' };
+    case 'integer':
+      return { call: `integer(${n})`, builder: 'integer' };
+    case 'bigint':
+      return { call: `bigint(${n}, { mode: 'number' })`, builder: 'bigint' };
+    case 'bigserial':
+      return { call: `bigserial(${n}, { mode: 'number' })`, builder: 'bigserial' };
+    case 'boolean':
+      return { call: `boolean(${n})`, builder: 'boolean' };
+    case 'timestamptz':
+      return { call: `timestamp(${n}, { withTimezone: true })`, builder: 'timestamp' };
+    case 'timestamp':
+      return { call: `timestamp(${n})`, builder: 'timestamp' };
+    case 'date':
+      return { call: `date(${n})`, builder: 'date' };
+    case 'numeric':
+      return spec.precision !== undefined
+        ? { call: `numeric(${n}, { precision: ${spec.precision}, scale: ${spec.scale} })`, builder: 'numeric' }
+        : { call: `numeric(${n})`, builder: 'numeric' };
+    case 'varchar':
+      return spec.length !== undefined
+        ? { call: `varchar(${n}, { length: ${spec.length} })`, builder: 'varchar' }
+        : { call: `varchar(${n})`, builder: 'varchar' };
+    case 'jsonb':
+      return { call: `jsonb(${n})`, builder: 'jsonb' };
+    case 'enum': {
+      if (!spec.enumName) throw new Error('enum field is missing enumName');
+      return { call: `${enumConstName(spec.enumName)}(${n})`, builder: enumConstName(spec.enumName) };
+    }
+    default: {
+      const exhaustive: never = spec.type;
+      throw new Error(`Unsupported field type: ${String(exhaustive)}`);
+    }
+  }
+}
+
+/** The hoisted const name for an enum type. `status` → `statusEnum`. */
+function enumConstName(enumName: string): string {
+  return `${toCamelCase(enumName)}Enum`;
+}
+
+/** The single primary-key field key for a model (FK targets reference its column). */
+function primaryKeyKey(model: ModelDescriptor): string {
+  const pk = model.primaryKey[0];
+  if (!pk) throw new Error(`Referenced model "${model.table}" has no primary key`);
+  return pk;
+}
+
+/** A model's `field key → snake column name` map (for relation `fields:`/`references:` text). */
+function columnKeys(model: ModelDescriptor): Map<string, string> {
+  const m = new Map<string, string>();
+  for (const key of Object.keys(model.fields)) m.set(key, toSnakeCase(key));
+  return m;
+}
+
+/**
+ * The modifier chain for a column, in `toDrizzleTable` order: notNull, unique,
+ * default, primaryKey (single-PK only), references. Cross-schema references are
+ * impossible to model, so only in-set targets are emitted. `usedBuilders` collects
+ * the table-extra/import builders the references clause needs (none today).
+ */
+function columnModifiers(
+  spec: FieldSpec,
+  isComposite: boolean,
+  modelsByDescriptor: Map<ModelDescriptor, { camel: string }>,
+): string {
+  let s = '';
+  if (spec.isArray) s += '.array()';
+  if (spec.isNotNull) s += '.notNull()';
+  if (spec.isUnique) s += '.unique()';
+
+  if (spec.defaultKind === 'now') s += '.defaultNow()';
+  else if (spec.defaultKind === 'random') s += '.defaultRandom()';
+  else if (spec.defaultKind === 'value') s += `.default(${defaultValueLiteral(spec.default)})`;
+
+  if (spec.isPrimaryKey && !isComposite) s += '.primaryKey()';
+
+  if (spec.references) {
+    const target = (spec.references as () => ModelDescriptor)();
+    const entry = modelsByDescriptor.get(target);
+    if (entry) {
+      const parentPk = primaryKeyKey(target);
+      const opts: string[] = [];
+      if (spec.onDelete) opts.push(`onDelete: ${strLiteral(spec.onDelete)}`);
+      if (spec.onUpdate) opts.push(`onUpdate: ${strLiteral(spec.onUpdate)}`);
+      const optsText = opts.length ? `, { ${opts.join(', ')} }` : '';
+      s += `.references(() => ${entry.camel}.${parentPk}${optsText})`;
+    }
+    // A reference to a model OUTSIDE the emitted set (a cross-schema FK) is omitted —
+    // the runtime + relations never needed it; the DB constraint stays unmanaged.
+  }
+
+  return s;
+}
+
+/** An unordered table-pair key, so `(follows, profiles)` and `(profiles, follows)` collide. */
+function pairKey(a: string, b: string): string {
+  return a < b ? `${a}\x00${b}` : `${b}\x00${a}`;
+}
+
+/**
+ * A relation that needs a `relationName` carries one keyed by `(childTable,
+ * fkColumnKey)` — the same string on the belongsTo (child) and the inverse hasMany
+ * (parent), so drizzle pairs them. Derived from the model's OWN relation graph:
+ * a belongsTo names `(thisTable, column)`; a hasMany names `(targetTable, column)`
+ * — both resolve to the child table holding the FK and the FK column key, so the
+ * two sides agree without coordination.
+ */
+interface RelationNaming {
+  /** All synthesized names, keyed by `(childTable, fkColumnKey)`. */
+  needsName: Set<string>;
+}
+
+function relationPairId(childTable: string, fkColumnKey: string): string {
+  return `${childTable}\x00${fkColumnKey}`;
+}
+
+function synthesizedName(childTable: string, fkColumnKey: string): string {
+  return `${childTable}_${toSnakeCase(fkColumnKey)}`;
+}
+
+/**
+ * Decide which relations need a `relationName`: only pairs of tables connected by
+ * MORE than one relation. Counts every relation (both sides) per unordered table
+ * pair; a pair counted more than once flags every relation between those two tables.
+ */
+function planRelationNames(models: ModelDescriptor[]): RelationNaming {
+  // Ambiguity is per DISTINCT FK column connecting a table pair — NOT per relation
+  // declaration. profiles<->posts is one FK (author_id) declared from both sides
+  // (belongsTo + its inverse hasMany): drizzle pairs them by table, no name needed.
+  // profiles<->follows is TWO FKs (follower_id, following_id): drizzle cannot tell
+  // which hasMany pairs which belongsTo, so every relation on that pair needs a name.
+  //
+  // Each relation resolves to a (childTable, fkColumnKey) — the child table holds the
+  // FK column. Count distinct such pairs per unordered table pair.
+  const fkColumnsByPair = new Map<string, Set<string>>();
+  for (const model of models) {
+    for (const rel of Object.values(model.relations)) {
+      const other = rel.target().table;
+      const childTable = rel.kind === 'belongsTo' ? model.table : other;
+      const k = pairKey(model.table, other);
+      let set = fkColumnsByPair.get(k);
+      if (!set) {
+        set = new Set<string>();
+        fkColumnsByPair.set(k, set);
+      }
+      set.add(relationPairId(childTable, rel.column));
+    }
+  }
+
+  const needsName = new Set<string>();
+  for (const model of models) {
+    for (const rel of Object.values(model.relations)) {
+      const other = rel.target().table;
+      const k = pairKey(model.table, other);
+      // Ambiguous when more than one distinct FK column connects the two tables.
+      if ((fkColumnsByPair.get(k)?.size ?? 0) <= 1) continue;
+      const childTable = rel.kind === 'belongsTo' ? model.table : other;
+      needsName.add(relationPairId(childTable, rel.column));
+    }
+  }
+  return { needsName };
+}
+
+/** The `relationName: '…'` fragment for a relation, or '' when the pair is unambiguous. */
+function relationNameFragment(
+  model: ModelDescriptor,
+  rel: { kind: 'belongsTo' | 'hasMany'; column: string; target: () => ModelDescriptor },
+  naming: RelationNaming,
+): string {
+  const other = rel.target().table;
+  const childTable = rel.kind === 'belongsTo' ? model.table : other;
+  const id = relationPairId(childTable, rel.column);
+  if (!naming.needsName.has(id)) return '';
+  return `, relationName: ${strLiteral(synthesizedName(childTable, rel.column))}`;
+}
+
+export interface CompileDrizzleSourceOptions {
+  /** Reserved for parity with the DDL compiler's `schema` option. Unused in the emit. */
+  schema?: string;
+}
+
+/**
+ * Emit the full text of a `schema.generated.ts` from a set of Models: hoisted
+ * `pgEnum`s, one `pgTable` per model (columns + table-extras), then a
+ * `relations()` block per model that declares any. The output is what an app's
+ * hand-written `db/schema.ts` is replaced by — fully-typed, derived, drift-guarded.
+ */
+export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: CompileDrizzleSourceOptions = {}): string {
+  // A private model is package-owned — its drizzle runtime table ships with the
+  // package (e.g. @everystack/storage/schema), so it never appears in the app's
+  // generated schema. (The migration generator still emits its SQL + authz.) The
+  // command and the drift guard both call this, so filtering here keeps them in sync.
+  const models = allModels.filter((m) => !m.private);
+
+  const modelsByDescriptor = new Map<ModelDescriptor, { camel: string }>();
+  for (const model of models) modelsByDescriptor.set(model, { camel: toCamelCase(model.table) });
+
+  // --- Collect enums (deduped by name, sorted) -----------------------------
+  const enumsByName = new Map<string, readonly string[]>();
+  for (const model of models) {
+    for (const f of Object.values(model.fields)) {
+      const { type, enumName, enumValues } = f.spec;
+      if (type !== 'enum' || !enumName) continue;
+      const values = enumValues ?? [];
+      const existing = enumsByName.get(enumName);
+      if (existing && existing.join(',') !== values.join(',')) {
+        throw new Error(`enum '${enumName}' is declared with conflicting values: [${existing}] vs [${values}]`);
+      }
+      if (!existing) enumsByName.set(enumName, values);
+    }
+  }
+  const enumNames = [...enumsByName.keys()].sort((a, b) => a.localeCompare(b));
+
+  // --- Track which pg-core builders + drizzle-orm symbols are used ----------
+  const pgCoreBuilders = new Set<string>();
+  pgCoreBuilders.add('pgTable');
+  if (enumNames.length) pgCoreBuilders.add('pgEnum');
+
+  const relationNaming = planRelationNames(models);
+  const anyRelations = models.some((m) => Object.keys(m.relations).length > 0);
+
+  // --- Emit each table -------------------------------------------------------
+  const tableBlocks: string[] = [];
+  for (const model of models) {
+    const camel = toCamelCase(model.table);
+    const isComposite = model.primaryKey.length > 1;
+
+    const colLines: string[] = [];
+    for (const [key, builder] of Object.entries(model.fields)) {
+      const spec = builder.spec;
+      const { call, builder: pgBuilder } = baseColumnSource(toSnakeCase(key), spec);
+      pgCoreBuilders.add(pgBuilder);
+      const mods = columnModifiers(spec, isComposite, modelsByDescriptor);
+      colLines.push(`  ${key}: ${call}${mods},`);
+    }
+
+    // Table-extras: composite PK, then table-level unique/check constraints.
+    const extras: string[] = [];
+    if (isComposite) {
+      pgCoreBuilders.add('primaryKey');
+      const cols = model.primaryKey.map((k) => `t.${k}`).join(', ');
+      extras.push(`  primaryKey({ columns: [${cols}] }),`);
+    }
+    for (const con of model.constraints) {
+      if (con.kind === 'unique') {
+        pgCoreBuilders.add('unique');
+        const cols = con.columns.map((k) => `t.${k}`).join(', ');
+        extras.push(`  unique().on(${cols}),`);
+      } else if (con.kind === 'check') {
+        pgCoreBuilders.add('check');
+        pgCoreBuilders.add('sql'); // imported from 'drizzle-orm', handled below
+        extras.push(`  check(${strLiteral(`${model.table}_check`)}, sql.raw(${strLiteral(con.predicate)})),`);
+      }
+      // 'index' / 'foreignKey' table constraints are not materialized on the runtime
+      // drizzle table object (mirrors toDrizzleTable), so they are omitted here.
+    }
+
+    const cols = `{\n${colLines.join('\n')}\n}`;
+    let block: string;
+    if (extras.length) {
+      block = `export const ${camel} = pgTable(${strLiteral(model.table)}, ${cols}, (t) => [\n${extras.join('\n')}\n]);`;
+    } else {
+      block = `export const ${camel} = pgTable(${strLiteral(model.table)}, ${cols});`;
+    }
+    tableBlocks.push(block);
+  }
+
+  // --- Emit relations() blocks ----------------------------------------------
+  const relationBlocks: string[] = [];
+  for (const model of models) {
+    const relEntries = Object.entries(model.relations);
+    if (relEntries.length === 0) continue;
+    const camel = toCamelCase(model.table);
+
+    const usesOne = relEntries.some(([, r]) => r.kind === 'belongsTo');
+    const usesMany = relEntries.some(([, r]) => r.kind === 'hasMany');
+    const helpers = [usesOne ? 'one' : null, usesMany ? 'many' : null].filter(Boolean).join(', ');
+
+    const lines: string[] = [];
+    for (const [key, rel] of relEntries) {
+      const target = rel.target();
+      const targetCamel = toCamelCase(target.table);
+      const nameFrag = relationNameFragment(model, rel, relationNaming);
+      if (rel.kind === 'belongsTo') {
+        // belongsTo(() => Target, column, references?) -> one(...)
+        const thisCol = rel.column; // FK FIELD KEY on this model
+        const targetPk = rel.references ?? primaryKeyKey(target);
+        lines.push(
+          `  ${key}: one(${targetCamel}, { fields: [${camel}.${thisCol}], references: [${targetCamel}.${targetPk}]${nameFrag} }),`,
+        );
+      } else {
+        // hasMany(() => Target, column, references?) -> many(...)
+        if (nameFrag) {
+          lines.push(`  ${key}: many(${targetCamel}, {${nameFrag.replace(/^, /, ' ')} }),`);
+        } else {
+          lines.push(`  ${key}: many(${targetCamel}),`);
+        }
+      }
+    }
+
+    relationBlocks.push(
+      `export const ${camel}Relations = relations(${camel}, ({ ${helpers} }) => ({\n${lines.join('\n')}\n}));`,
+    );
+  }
+
+  // --- Header ----------------------------------------------------------------
+  const header = [
+    '// GENERATED by `everystack db:generate` from models/. Do not edit.',
+    '//',
+    '// Cross-schema foreign keys (e.g. profiles.id -> auth.users.id) are intentionally',
+    '// omitted: a Model cannot reference a table outside the model set, so the runtime',
+    '// table and its relations() never carry that FK. The DB constraint stays untouched.',
+  ].join('\n');
+
+  // --- Imports ---------------------------------------------------------------
+  // pg-core: sorted, enum consts are not imports (they're declared below), `sql`
+  // comes from 'drizzle-orm', not pg-core — strip both from the pg-core set.
+  const enumConsts = new Set(enumNames.map(enumConstName));
+  const usesSqlRaw = pgCoreBuilders.has('sql');
+  const pgCoreNames = [...pgCoreBuilders].filter((b) => !enumConsts.has(b) && b !== 'sql').sort((a, b) => a.localeCompare(b));
+
+  const importLines: string[] = [];
+  importLines.push(`import { ${pgCoreNames.join(', ')} } from 'drizzle-orm/pg-core';`);
+
+  const drizzleOrmNames: string[] = [];
+  if (anyRelations) drizzleOrmNames.push('relations');
+  if (usesSqlRaw) drizzleOrmNames.push('sql');
+  drizzleOrmNames.sort((a, b) => a.localeCompare(b));
+  if (drizzleOrmNames.length) {
+    importLines.push(`import { ${drizzleOrmNames.join(', ')} } from 'drizzle-orm';`);
+  }
+
+  // --- Enum declarations -----------------------------------------------------
+  const enumDecls = enumNames.map((name) => {
+    const values = enumsByName.get(name) ?? [];
+    const valsText = values.map((v) => strLiteral(v)).join(', ');
+    return `export const ${enumConstName(name)} = pgEnum(${strLiteral(name)}, [${valsText}]);`;
+  });
+
+  // --- Assemble --------------------------------------------------------------
+  const sections: string[] = [];
+  sections.push(header);
+  sections.push(importLines.join('\n'));
+  if (enumDecls.length) sections.push(enumDecls.join('\n'));
+  for (const block of tableBlocks) sections.push(block);
+  for (const block of relationBlocks) sections.push(block);
+
+  return sections.join('\n\n') + '\n';
+}