@everystack/model 0.4.11 → 0.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/derived.ts

@@ -17,6 +17,7 @@
 import type { RawSql } from './raw-sql';
 import type { Ability } from './can';
 import type { ModelDescriptor } from './model';
+import { TABLE_PRIVILEGES } from './model';
 import type { IndexBuilder } from './constraints';
 import type { FieldBuilder } from './field';
 
@@ -130,10 +131,14 @@ export interface TriggerSpec {
 }
 
 /**
- * A trigger on the model (or view) it is declared on. Deps are free: the table dep is
- * the declaration site; the function dep is `execute:`. Target-specific legality
- * (INSTEAD OF needs a view; views take no BEFORE/AFTER row triggers) is enforced where
- * the trigger attaches — defineModel / defineView.
+ * A trigger on the model (or view) it is declared on.
+ *
+ * @deprecated Use {@link defineTrigger} and put the binding in the `derived` array. A
+ * trigger depends on BOTH a table and a function, so declaring it ON the table forces the
+ * base layer to import the compute layer — which `db:pull --derived-out` cannot render at
+ * all, because the generated derived module already imports the models (the cycle is fatal,
+ * not stylistic). `trigger()` keeps working and compiles to the identical object; it will
+ * be removed in the next major.
  */
 export function trigger(name: string, def: TriggerDefinition): TriggerSpec {
   if (def.execute == null) {
@@ -167,6 +172,87 @@ export function trigger(name: string, def: TriggerDefinition): TriggerSpec {
   };
 }
 
+/**
+ * Grants that EXIST on a relation, recorded without claiming anyone intended them.
+ *
+ * The same key, and the same rule, as tables and functions: **abilities are opinion,
+ * privileges are fact.** `can('read')` declares an intended audience; this records what
+ * the database actually holds — the blanket
+ * DELETE/INSERT/REFERENCES/SELECT/TRIGGER/TRUNCATE/UPDATE that `GRANT ALL ON ALL TABLES IN
+ * SCHEMA` hands out, or a `SELECT` to `PUBLIC`. Neither is expressible as a read ability,
+ * and without a way to say them `db:pull` had to skip the whole object, body included.
+ *
+ * Recording them is also what makes the object safe to render: declared == live, so
+ * `db:generate` plans nothing. Rendering only the expressible half would plan a REVOKE of
+ * the rest, which turns a silent skip into a silent revoke.
+ */
+function validateRelationPrivileges(
+  kindWord: string,
+  name: string,
+  privileges: Record<string, string[]> | undefined,
+): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const [grantee, privs] of Object.entries(privileges ?? {})) {
+    if (privs.length === 0) {
+      throw new Error(`${kindWord} '${name}': privileges for '${grantee}' is empty — remove the key, or name the privileges.`);
+    }
+    for (const p of privs) {
+      if (!(TABLE_PRIVILEGES as readonly string[]).includes(p.toUpperCase())) {
+        throw new Error(
+          `${kindWord} '${name}': '${p}' is not a relation privilege — one of ${TABLE_PRIVILEGES.join(', ')}. ` +
+          `(EXECUTE belongs on a function.)`,
+        );
+      }
+    }
+    out[grantee] = privs.map((p) => p.toUpperCase());
+  }
+  return out;
+}
+
+/** What a standalone binding names as its target. A view is a legal trigger target too. */
+export type TriggerTarget = ModelDescriptor | ViewDescriptor;
+
+export interface StandaloneTriggerDefinition extends TriggerDefinition {
+  /** The table or view the trigger rides. A binding is a property of neither endpoint. */
+  on: TriggerTarget;
+}
+
+export interface TriggerDescriptor extends TriggerSpec {
+  kind: 'trigger';
+  on: TriggerTarget;
+}
+
+/**
+ * A trigger binding, declared standing on its own rather than hanging off its table.
+ *
+ * **Why standalone.** A trigger depends on BOTH a table and a function, so its declaration
+ * site must be downstream of both. Models are the base layer; the derived layer points at
+ * models and never the reverse. Declaring the binding on the model inverts that, and
+ * `db:pull --derived-out` makes the inversion fatal rather than merely untidy — the
+ * generated derived module imports the model files for view `dependsOn`, so a binding on
+ * the model closes the loop and the module graph dies with
+ * `ReferenceError: Cannot access 'X' before initialization`.
+ *
+ * It also matches PostgreSQL's own grammar — `CREATE TRIGGER` is a standalone statement
+ * naming its table and its function — and it matches reality: bindings and functions are
+ * many-to-one (one real schema has 18 bindings over 11 functions, one of them in a
+ * different schema from the tables it serves), so the binding belongs to neither endpoint.
+ *
+ * Goes in the `derived` array: `defineModule({ models, derived: [touchFn, rowsTouch] })`.
+ */
+export function defineTrigger(name: string, def: StandaloneTriggerDefinition): TriggerDescriptor {
+  if (def.on == null) {
+    throw new Error(`trigger '${name}': on is ${def.on === undefined ? 'undefined' : 'null'} — renamed or missing import?`);
+  }
+  const spec = trigger(name, def);
+  // A standalone descriptor knows its own target, so it enforces target legality itself.
+  // The attached form could not: the target was only known at the attach site.
+  const isView = 'kind' in def.on && def.on.kind === 'view';
+  const owner = isView ? (def.on as ViewDescriptor).name : `${(def.on as ModelDescriptor).schema}.${(def.on as ModelDescriptor).table}`;
+  validateTriggersFor(isView ? 'view' : 'table', owner, [spec]);
+  return { ...spec, kind: 'trigger', on: def.on };
+}
+
 /** The legality rules that depend on the trigger's TARGET (table vs view). */
 export function validateTriggersFor(target: 'table' | 'view', owner: string, triggers: TriggerSpec[]): void {
   rejectHoles(`${target} '${owner}'`, 'triggers', triggers);
@@ -267,8 +353,28 @@ export interface FunctionDefinition {
   /** Default `'volatile'` (PostgreSQL's own). `immutable` enables expression indexes. */
   volatility?: 'immutable' | 'stable' | 'volatile';
   dependsOn?: DependsOnRef[];
-  /** Execute authz only, role REQUIRED — `PUBLIC` is always revoked by the compiler. */
+  /** Execute authz only, role REQUIRED — the INTENDED audience. */
   abilities?: Ability[];
+  /**
+   * EXECUTE grants that EXIST, recorded without claiming anyone intended them —
+   * `privileges: { PUBLIC: ['EXECUTE'] }`.
+   *
+   * **Abilities are opinion; privileges are fact.** `can('execute', { role })` declares an
+   * audience and compiles a grant to serve it. This key says only "the database has this
+   * grant", which is what `db:pull` needs to render a live function faithfully.
+   *
+   * The state that forced it: PostgreSQL grants every new function EXECUTE to PUBLIC, and a
+   * brownfield schema is full of ones nobody revoked. Without a spelling for that, a pull
+   * had to either invent a role — a GRANT the database never had, while silently revoking
+   * the live PUBLIC one — or leave the function undeclarable, which is a permanent
+   * `db:fingerprint` MISMATCH. Declaring a `PUBLIC` key also suppresses the compiler's
+   * otherwise-unconditional `REVOKE ALL … FROM PUBLIC`, so the pull round-trips to zero
+   * statements instead of planning a revoke the adopter never asked for.
+   *
+   * It is still usually a finding: `db:check` WARNs that a SECURITY DEFINER function is
+   * PUBLIC-executable. Opinion lives in the linter, never in the parser.
+   */
+  privileges?: Record<string, string[]>;
   comment?: string;
   body: RawSql;
 }
@@ -284,6 +390,8 @@ export interface FunctionDescriptor {
   volatility: 'immutable' | 'stable' | 'volatile';
   dependsOn: DependsOnRef[];
   abilities: Ability[];
+  /** Recorded EXECUTE grants — see {@link FunctionDefinition.privileges}. */
+  privileges: Record<string, string[]>;
   comment?: string;
   body: string;
 }
@@ -312,6 +420,22 @@ export function defineFunction(name: string, def: FunctionDefinition): FunctionD
       );
     }
   }
+  // EXECUTE is the only privilege a function has, so the map is a one-member enum today.
+  // The table's shape is kept anyway: one shape across object kinds beats a bespoke
+  // boolean that has to grow a second member later.
+  const privileges: Record<string, string[]> = {};
+  for (const [grantee, privs] of Object.entries(def.privileges ?? {})) {
+    if (privs.length === 0) {
+      throw new Error(`function '${name}': privileges for '${grantee}' is empty — remove the key, or say ['EXECUTE'].`);
+    }
+    for (const p of privs) {
+      if (p.toUpperCase() !== 'EXECUTE') {
+        throw new Error(`function '${name}': '${p}' is not a function privilege — EXECUTE is the only one. (Table privileges live on the model.)`);
+      }
+    }
+    privileges[grantee] = privs.map((p) => p.toUpperCase());
+  }
+
   return {
     kind: 'function',
     name,
@@ -323,6 +447,7 @@ export function defineFunction(name: string, def: FunctionDefinition): FunctionD
     volatility: def.volatility ?? 'volatile',
     dependsOn: def.dependsOn ?? [],
     abilities: def.abilities ?? [],
+    privileges,
     ...(def.comment ? { comment: def.comment } : {}),
     body: def.body.sql,
   };
@@ -341,6 +466,8 @@ export interface ViewDefinition {
    */
   securityInvoker: boolean;
   abilities?: Ability[];
+  /** Grants that EXIST, recorded rather than chosen — see {@link validateRelationPrivileges}. */
+  privileges?: Record<string, string[]>;
   dependsOn?: DependsOnRef[];
   /** `INSTEAD OF` row triggers, or BEFORE/AFTER statement-level. */
   triggers?: TriggerSpec[];
@@ -368,6 +495,7 @@ export interface ViewDescriptor {
   name: string;
   securityInvoker: boolean;
   abilities: Ability[];
+  privileges: Record<string, string[]>;
   dependsOn: DependsOnRef[];
   triggers: TriggerSpec[];
   comment?: string;
@@ -378,6 +506,7 @@ export interface ViewDescriptor {
 
 export function defineView(name: string, def: ViewDefinition): ViewDescriptor {
   rejectHoles(`view '${name}'`, 'dependsOn', def.dependsOn);
+  const privileges = validateRelationPrivileges('view', name, def.privileges);
   if (typeof def.securityInvoker !== 'boolean') {
     throw new Error(
       `view '${name}': securityInvoker is a required decision — true (readers' own RLS applies through the view) or false (definer semantics: the sealed-slice pattern; the body must not leak).`,
@@ -392,6 +521,7 @@ export function defineView(name: string, def: ViewDefinition): ViewDescriptor {
     name,
     securityInvoker: def.securityInvoker,
     abilities: def.abilities ?? [],
+    privileges,
     dependsOn: def.dependsOn ?? [],
     triggers: def.triggers ?? [],
     ...(def.comment ? { comment: def.comment } : {}),
@@ -407,6 +537,8 @@ export function defineView(name: string, def: ViewDefinition): ViewDescriptor {
 
 export interface MaterializedViewDefinition {
   abilities?: Ability[];
+  /** Grants that EXIST, recorded rather than chosen — see {@link validateRelationPrivileges}. */
+  privileges?: Record<string, string[]>;
   dependsOn?: DependsOnRef[];
   indexes?: IndexBuilder[];
   /** `'concurrently'` — compile-gated on a declared unique, non-partial index (PG requires it). */
@@ -424,6 +556,7 @@ export interface MaterializedViewDescriptor {
   kind: 'materialized view';
   name: string;
   abilities: Ability[];
+  privileges: Record<string, string[]>;
   dependsOn: DependsOnRef[];
   indexes: IndexBuilder[];
   refresh?: 'concurrently';
@@ -436,6 +569,7 @@ export interface MaterializedViewDescriptor {
 
 export function defineMaterializedView(name: string, def: MaterializedViewDefinition): MaterializedViewDescriptor {
   rejectHoles(`materialized view '${name}'`, 'dependsOn', def.dependsOn);
+  const privileges = validateRelationPrivileges('materialized view', name, def.privileges);
   validateRelationAbilities('materialized view', name, def.abilities ?? []);
   validatePrivateContradiction('materialized view', name, def.private, def.abilities);
   validateRelationFields('materialized view', name, def.fields, def.private);
@@ -449,6 +583,7 @@ export function defineMaterializedView(name: string, def: MaterializedViewDefini
     kind: 'materialized view',
     name,
     abilities: def.abilities ?? [],
+    privileges,
     dependsOn: def.dependsOn ?? [],
     indexes,
     ...(def.refresh ? { refresh: def.refresh } : {}),
@@ -560,4 +695,5 @@ export function defineSql(name: string, def: SqlDefinition): SqlDescriptor {
 }
 
 /** Everything the derived (compute) stream carries — sequences are state and NOT here. */
-export type DerivedDescriptor = ViewDescriptor | MaterializedViewDescriptor | FunctionDescriptor | SqlDescriptor;
+export type DerivedDescriptor =
+  ViewDescriptor | MaterializedViewDescriptor | FunctionDescriptor | SqlDescriptor | TriggerDescriptor;

package/src/index.ts

@@ -12,6 +12,8 @@ export type { FieldSpec, FieldType, DefaultKind, ReferentialAction } from './fie
 
 export { canonicalColumnType, fieldFactoryCall, pgTypeRefusal } from './pg-type';
 
+export { parseQualified } from './qualified';
+
 export { unique, check, index, foreignKey, IndexBuilder } from './constraints';
 export type { TableConstraint } from './constraints';
 
@@ -24,20 +26,21 @@ export type { Ability, AbilityCondition, Action } from './can';
 export { belongsTo, hasMany } from './relations';
 export type { Relation } from './relations';
 
-export { defineModel, defineMaterializedTable, EXTRA_PRIVILEGES } from './model';
-export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, ExtraPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
+export { defineModel, defineMaterializedTable, EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, ExtraPrivilege, TablePrivilege, DmlPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
 export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
 export type { Module, ModuleDefinition } from './module';
 
 export {
   defineView, defineMaterializedView, defineFunction, defineSql, defineSequence,
-  trigger, arg, setof, validateTriggersFor, SIMPLE_DROP_KINDS,
+  trigger, defineTrigger, arg, setof, validateTriggersFor, SIMPLE_DROP_KINDS,
   normalizeArgType, functionArgSignature,
 } from './derived';
 export type {
   DerivedDescriptor, ViewDescriptor, MaterializedViewDescriptor, FunctionDescriptor,
   SqlDescriptor, SequenceDescriptor, TriggerSpec, TriggerDefinition, TriggerTiming,
+  TriggerDescriptor, StandaloneTriggerDefinition, TriggerTarget,
   TriggerEvent, ArgSpec, SetofReturn, DependsOnRef, ViewDefinition,
   MaterializedViewDefinition, FunctionDefinition, SqlDefinition, SequenceDefinition,
 } from './derived';

package/src/model.ts

@@ -68,6 +68,35 @@ export type ExtraPrivilege = 'REFERENCES' | 'TRIGGER' | 'TRUNCATE';
 /** The declarable privilege set — the one definition; the CLI's classifier reads it too. */
 export const EXTRA_PRIVILEGES: readonly ExtraPrivilege[] = ['REFERENCES', 'TRIGGER', 'TRUNCATE'];
 
+/** The four CRUD privileges. Normally they arrive via `can()`, which decides the policy too. */
+export const DML_PRIVILEGES = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'] as const;
+export type DmlPrivilege = (typeof DML_PRIVILEGES)[number];
+
+/**
+ * Every table privilege this language can spell.
+ *
+ * The DML four used to be REFUSED here, so that a grant could never be declared without the
+ * policy that gates it. That invariant was already vacuous for any database being adopted: a
+ * live table can hold `GRANT SELECT TO admin` with no policy covering admin, and refusing to
+ * say it did not make it not so — it only made the database unspellable.
+ *
+ * That matters because `db:fingerprint` compares the LIVE schema against the MODELS. A state
+ * the language cannot express is a permanent MISMATCH, so adopting such a database required
+ * mutating it first, which inverts who is the source of truth during adoption.
+ *
+ * The rule this settles (Fable, 2026-08-06): **expressibility is total over the fingerprint's
+ * domain; opinion lives in the linter, never in the parser.** Declaring a naked DML grant is
+ * still a mistake in hand-authored code — `db:check` says so, as an ERROR on a table without
+ * RLS (where it is an unrestricted table-wide privilege) and a WARNING on a table with RLS
+ * (where it is dead until someone adds a broad policy or disables RLS). It is no longer a
+ * parse error, because `db:pull` has to be able to render what is actually there.
+ *
+ * Policies still come ONLY from `can()`. This key can never mint row access by itself.
+ */
+export type TablePrivilege = ExtraPrivilege | DmlPrivilege;
+
+export const TABLE_PRIVILEGES: readonly TablePrivilege[] = [...EXTRA_PRIVILEGES, ...DML_PRIVILEGES];
+
 export interface ModelDefinition {
   fields: Record<string, FieldBuilder>;
   abilities?: Ability[];
@@ -81,17 +110,20 @@ export interface ModelDefinition {
    * Privileges a role holds on this table BEYOND the CRUD an ability compiles to —
    * `privileges: { admin: ['REFERENCES', 'TRIGGER', 'TRUNCATE'] }`.
    *
-   * Only {@link ExtraPrivilege} values are accepted. The four DML privileges are NOT
-   * declarable here on purpose: `SELECT`/`INSERT`/`UPDATE`/`DELETE` come from `can()`, which
-   * decides the grant and the RLS policy together. A grant declared without its policy is a
-   * privilege with no row gate — the exact shape `db:pull` refuses to render.
+   * The DML four are accepted but are almost never what you want by hand: `SELECT`/`INSERT`/
+   * `UPDATE`/`DELETE` normally come from `can()`, which decides the grant and the RLS policy
+   * together. Declared here they compile to a GRANT with no policy beside it. `db:check` flags
+   * that — an ERROR on a table without RLS, where it is an unrestricted table-wide privilege;
+   * a WARNING on a table with RLS, where it is dead until a broad policy appears or RLS is
+   * disabled. They are spellable because `db:pull` must be able to render a live database that
+   * is already in that shape; see {@link TablePrivilege}.
    *
    * ADDITIVE, never subtractive: these are unioned with what the abilities grant, so this key
    * can widen a role's privileges and can never narrow them. Naming a role here GOVERNS it —
    * same rule as `can(…, { role })` — so a role that appears only in this map has its other
    * privileges reconciled everywhere, not just on this table.
    */
-  privileges?: Record<string, ExtraPrivilege[]>;
+  privileges?: Record<string, TablePrivilege[]>;
   /**
    * `true` excludes soft-deleted rows (`deleted_at IS NULL`) from the public read policies
    * and from the generic data API. **Required — not inferred — on any model that has a
@@ -166,7 +198,7 @@ export interface ModelDescriptor {
   /** The resolved write principal (default `'app'`) — drives RLS posture. See {@link WrittenBy}. */
   writtenBy: WrittenBy;
   /** Beyond-CRUD privileges per role, unioned with what the abilities grant. See {@link ModelDefinition.privileges}. */
-  privileges: Record<string, ExtraPrivilege[]>;
+  privileges: Record<string, TablePrivilege[]>;
   /** `true` excludes `deleted_at IS NULL` rows from public reads and the data API. Declared, never inferred. */
   softDelete: boolean;
   /** The resolved Postgres schema (default `'public'`). Package tables live in their own. */
@@ -317,22 +349,22 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     );
   }
 
-  // A privilege outside the beyond-CRUD set is refused rather than passed through. The DML
-  // four are the dangerous ones: declared here they would compile to a GRANT with no policy
-  // beside it, which is a privilege nobody row-gated. They come from can(), where the grant
-  // and the policy are decided in one place.
+  // A privilege outside the table-privilege vocabulary is still refused — that is a typo, not a
+  // state a database can hold. The DML four ARE accepted now: they used to throw here so that a
+  // grant could never be declared without its policy, but that invariant was vacuous for any
+  // database being adopted (a live table can hold a policy-less grant whether or not we can
+  // spell it) and it made such a database a permanent fingerprint MISMATCH. Expressibility is
+  // total over the fingerprint's domain; the opinion moved to db:check, which flags a naked DML
+  // grant as an ERROR on a non-RLS table and a WARNING on an RLS one. See TablePrivilege.
   for (const [role, privs] of Object.entries(def.privileges ?? {})) {
     if (!Array.isArray(privs)) {
-      throw new Error(`model '${table}': privileges['${role}'] must be an array of ${EXTRA_PRIVILEGES.join(' | ')}.`);
+      throw new Error(`model '${table}': privileges['${role}'] must be an array of ${TABLE_PRIVILEGES.join(' | ')}.`);
     }
     for (const p of privs) {
-      if (EXTRA_PRIVILEGES.includes(p)) continue;
-      const dml = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'].includes(String(p).toUpperCase());
+      if (TABLE_PRIVILEGES.includes(p)) continue;
       throw new Error(
-        `model '${table}': privileges['${role}'] contains '${p}', which is not one of ${EXTRA_PRIVILEGES.join(', ')}. `
-          + (dml
-            ? `Declare ${String(p).toUpperCase()} with can() — that is what decides the row policy beside the grant. A grant declared here would have no policy.`
-            : `This key names only the table privileges can() has no verb for.`),
+        `model '${table}': privileges['${role}'] contains '${p}', which is not a table privilege. `
+          + `Expected one of ${TABLE_PRIVILEGES.join(', ')}.`,
       );
     }
   }
@@ -398,7 +430,7 @@ export interface MaterializedTableDefinition {
   private?: boolean;
   renamedFrom?: string;
   /** Beyond-CRUD privileges per role. See {@link ModelDefinition.privileges}. */
-  privileges?: Record<string, ExtraPrivilege[]>;
+  privileges?: Record<string, TablePrivilege[]>;
 }
 
 export function defineMaterializedTable(table: string, def: MaterializedTableDefinition): ModelDescriptor {

package/src/module.ts

@@ -22,6 +22,8 @@
 import type { ModelDescriptor } from './model';
 import type { DerivedDescriptor, SequenceDescriptor } from './derived';
 import { rejectHoles, functionArgSignature } from './derived';
+import { deriveFunctionSchemas } from './derive';
+import { parseQualified } from './qualified';
 
 export interface ModuleDefinition {
   /** The package's Models (schema + authz). */
@@ -114,6 +116,7 @@ export function defineModule(def: ModuleDefinition): Module {
     }
     seen.add(identity);
   }
+  assertFunctionsAreDeclared(def);
   return {
     models: def.models ?? [],
     extensions: def.extensions ?? [],
@@ -124,6 +127,75 @@ export function defineModule(def: ModuleDefinition): Module {
   };
 }
 
+/**
+ * `writtenBy: 'functions'` is a PROMISE that functions do the writing. This is where the
+ * promise gets checked.
+ *
+ * The defect it closes, found 2026-08-04: `@everystack/auth` declared seven models
+ * `writtenBy: 'functions'` and shipped 21 SECURITY DEFINER functions — through the deprecated
+ * `functions` thunk, which exactly ONE command reads (`db:generate --init`). `db:reconcile`
+ * reads `derived`, and `derived` was empty. So a brownfield adopter installed the tables, got
+ * ENABLE-not-FORCE RLS on the strength of `writtenBy: 'functions'`, installed none of the
+ * functions that were supposed to be the only writers, and every gate reported clean. The
+ * declaration and the thing it depends on were checked by nobody.
+ *
+ * The check is per-MODULE, not across the composed set: a module that owns a
+ * functions-written model owns the functions that write it, and firing here can name the
+ * module at fault. Across modules the error arrives after everything is flattened and can
+ * only say that something, somewhere, is missing.
+ *
+ * A thunk downgrades the error to a warning rather than satisfying the check — the thunk lane
+ * does install, just on one command, so a consumer still on it is degraded and not broken.
+ */
+function assertFunctionsAreDeclared(def: ModuleDefinition): void {
+  const models = def.models ?? [];
+  const owed = deriveFunctionSchemas(models);
+  const declared = new Set(
+    (def.derived ?? [])
+      .filter((d) => (d.kind === 'sql' ? d.objectKind : d.kind) === 'function')
+      .map((d) => parseQualified(d.name).schema),
+  );
+  const missing = owed.filter((schema) => !declared.has(schema));
+
+  if (missing.length === 0) {
+    if (def.functions) {
+      console.warn(
+        'defineModule: the `functions` thunk is deprecated and only `db:generate --init` reads it — '
+        + '`db:reconcile` reads `derived`, so anything declared there alone never reaches a brownfield '
+        + 'database. Move it to `derived: [defineFunction(…)]`.',
+      );
+    }
+    return;
+  }
+
+  const blame = missing
+    .map((schema) => {
+      const tables = models
+        .filter((m) => m.writtenBy === 'functions' && m.schema === schema)
+        .map((m) => `${m.schema}.${m.table}`)
+        .sort();
+      return `schema '${schema}' (${tables.join(', ')})`;
+    })
+    .join('; ');
+
+  if (def.functions) {
+    console.warn(
+      `defineModule: ${blame} declares writtenBy: 'functions' but every function is in the deprecated `
+      + '`functions` thunk, which only `db:generate --init` reads. `db:reconcile` reads `derived`, so a '
+      + 'brownfield database gets the tables and none of their writers. Move them to '
+      + '`derived: [defineFunction(…)]`.',
+    );
+    return;
+  }
+
+  throw new Error(
+    `defineModule: ${blame} declares writtenBy: 'functions' but the module declares no function in `
+    + `that schema. writtenBy: 'functions' is what turns RLS FORCE off, so the tables ship writable `
+    + `only by functions that do not exist. Declare them as \`derived: [defineFunction('${missing[0]}.…', …)]\`, `
+    + `or change writtenBy if functions are not the writer.`,
+  );
+}
+
 /** The flattened model list across modules — for everything that still takes a model array
  *  (handler-config derivation, FORCE carveouts, the drift guard). */
 export function moduleModels(modules: Module[]): ModelDescriptor[] {

package/src/qualified.ts

@@ -0,0 +1,34 @@
+/**
+ * Splitting a declared name into `{ schema, name }`.
+ *
+ * This lives in `@everystack/model` because the names it parses are MODEL vocabulary: a
+ * descriptor declares `defineFunction('auth.sign_in_session', …)` and a model declares its
+ * `schema` separately, so anything that has to line those two up — the composition guard here,
+ * every emitter and the reconciler in `@everystack/cli` — must agree on where the dot is. The
+ * cli re-exports this from `derived-source.ts`, so there is ONE definition and its callers
+ * cannot drift apart. (Same reasoning as `fieldFactoryCall`: the parser belongs with the
+ * vocabulary it parses, not with the first consumer that needed it.)
+ *
+ * `public` is the unqualified default because that is what PostgreSQL resolves a bare name to
+ * under the default `search_path` — the parse must match the server, not a convention.
+ */
+
+/** Strip quotes from an identifier and split an optionally schema-qualified name. */
+export function parseQualified(raw: string): { schema: string; name: string } {
+  const parts: string[] = [];
+  let current = '';
+  let quoted = false;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch === '"') {
+      if (quoted && raw[i + 1] === '"') { current += '"'; i++; continue; }
+      quoted = !quoted;
+      continue;
+    }
+    if (ch === '.' && !quoted) { parts.push(current); current = ''; continue; }
+    current += ch;
+  }
+  parts.push(current);
+  if (parts.length >= 2) return { schema: parts[0], name: parts.slice(1).join('.') };
+  return { schema: 'public', name: parts[0] };
+}