@everystack/model 0.3.0 → 0.3.4

package/README.md

@@ -87,7 +87,14 @@ The table-level surface, composed in `constraints: [...]`, for what a column-sco
 
 ## Authorization
 
-`can(action, condition)` declares one rule (default-deny: no matching `can()` means denied). Conditions: `{ owner: 'column' }` (row owner, via the JWT `sub` claim by default — override with `userField`), `{ role: 'admin' }`, or a raw `{ sql: … }` escape hatch. These compile to RLS policies and grants.
+`can(action, condition)` declares one rule (default-deny: no matching `can()` means denied). Conditions:
+
+- `{ owner: 'column' }` — row owner, via the JWT `sub` claim by default (override with `userField`). Also feeds the handler's `rowOwnership` IDOR backstop.
+- `{ role: 'authenticated' }` — role-gated (policy `TO <role>` + grant).
+- `{ where: 'deleted_at IS NULL' }` — a column/scalar predicate, compiled to the policy's `USING` clause.
+- `{ sql: … }` — a verbatim RLS predicate escape hatch.
+
+These compile to RLS policies and grants (via `@everystack/cli`'s `compileTableContract`, what `db:generate` emits). `can('manage', …)` covers all actions.
 
 ## Relations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -14,12 +14,20 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./drizzle": {
+      "types": "./src/drizzle.ts",
+      "default": "./src/drizzle.ts"
     }
   },
   "peerDependencies": {
+    "drizzle-orm": "*",
     "zod": "*"
   },
   "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
@@ -27,6 +35,7 @@
   "devDependencies": {
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
+    "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",

package/src/can.ts

@@ -1,10 +1,10 @@
 /**
  * CanCan-shaped authorization rules. `can(action, condition)` declares one rule.
  *
- * Phase 0 consumes only the `owner` shape (→ the handler's `rowOwnership` IDOR
- * backstop). The full set of condition shapes — `role`, `where`, `sql` — is
- * stored verbatim now and compiled to RLS policies + grants in Phase 1
- * (`compileAbilities`, the inverse of the contract suite's `humanizePredicate`).
+ * The `owner` shape feeds the handler's `rowOwnership` IDOR backstop. The full
+ * set of condition shapes — `role`, `owner`, `via`, `where`, `sql` — is compiled
+ * to RLS policies + grants by `@everystack/cli`'s `compileTableContract` (what
+ * `db:generate` emits), the inverse of the contract suite's `humanizePredicate`.
  *
  * Default-deny is the model's contract: no matching `can()` means denied.
  */
@@ -17,9 +17,26 @@ export interface AbilityCondition {
   role?: string;
   /** Row owner only: the column holding the owner id (`USING (<col> = auth.uid())`). */
   owner?: string;
+  /**
+   * Transitive owner — names a local FK *field* (e.g. `uploadId`) whose `.references()`
+   * target carries the real owner. The compiler follows the reference to the parent's
+   * owner ability and emits a parent-subquery predicate:
+   *   `<fk_col> IN (SELECT id FROM <parent> WHERE <parent_owner_col> = <claim>)`.
+   * Use when a child row is owned through its parent (image_variants → uploads), not
+   * by a column on the child itself. The parent model must declare an `owner` ability.
+   */
+  via?: string;
   /** Field in the JWT claims holding the owner id. Default: `sub`. */
   userField?: string;
-  /** Scalar/column predicate — a sql-tagged expression. Compiled in Phase 1. */
+  /**
+   * Column-scoped exposure for a `read` ability. Names the field keys a role may read
+   * (compiled to a `GRANT SELECT (cols)` column grant, not a table grant) instead of the
+   * whole row — e.g. `can('read', { owner: 'id', columns: ['id', 'email', 'role'] })` on
+   * `auth.users` exposes id/email/role to the owner, never the password hash. Pairs with
+   * `owner` (the self policy scopes the rows; the columns scope the fields).
+   */
+  columns?: string[];
+  /** Scalar/column predicate — a sql-tagged expression compiled to an RLS USING clause. */
   where?: unknown;
   /** Escape hatch: a verbatim RLS predicate, preserved and diffed by normalized text. */
   sql?: unknown;

package/src/constraints.ts

@@ -1,14 +1,13 @@
 /**
  * Table-level constraint builders — the surface for what a column-scoped `field()`
- * can't express: a composite `unique(...)` and a multi-column `check(...)`. They are
- * composed in a `constraints: [...]` array on `defineModel`, the same builder idiom as
- * `field`/`can`, so the Model reads as intent rather than config.
+ * can't express: a composite `unique(...)`, a multi-column `check(...)`, a standalone
+ * `index(...)` (optionally `.unique()`/`.where()`), and a composite `foreignKey(...)`.
+ * They are composed in a `constraints: [...]` array on `defineModel`, the same builder
+ * idiom as `field`/`can`, so the Model reads as intent rather than config.
  *
  * Columns are named by their **field keys** (camelCase, as the model is written); the
  * compiler snake_cases them to SQL identifiers — symmetric with `.references()`. A
  * `check(...)` takes raw `sql\`…\`` because a predicate is, by nature, SQL.
- *
- * (Indexes join this surface in a later increment; the union is open for it.)
  */
 
 import type { RawSql } from './raw-sql';

package/src/derive.ts

@@ -2,10 +2,9 @@
  * `deriveHandlerConfig` — compile a set of models down to the per-table slice of
  * the API handler's options blob.
  *
- * This is the Phase-0 payoff: today the example hand-authors `exposedTables`,
- * `hiddenColumns`, `protectedFields`, `rowOwnership`, `softDelete`, `relations`,
- * and `hooks` as a scattered literal kept in sync with the schema by hand. Those
- * are all *views of the model*, so they derive from it — no drift.
+ * `exposedTables`, `hiddenColumns`, `protectedFields`, `rowOwnership`,
+ * `softDelete`, `relations`, and `hooks` are all *views of the model*, so they
+ * derive from it instead of a hand-maintained literal that drifts from the schema.
  *
  * Scope boundary: only the PER-TABLE surface derives here. App/handler-level
  * options (`auth`, `pgSettings`, `rpc`, `basePath`, `audit`, `maxLimit`,
@@ -54,6 +53,11 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
   const hooks: Record<string, ModelHooks> = {};
 
   for (const model of models) {
+    // A private model is generated (schema + authz) but is not a generic-API
+    // resource — it contributes nothing to the handler config (no exposedTables
+    // entry, no hidden/protected/ownership/relation/hook derivation).
+    if (model.private) continue;
+
     const { table } = model;
     exposedTables.push(table);
 
@@ -128,3 +132,33 @@ function fieldsWhere(
     .filter(([, f]) => pred(f))
     .map(([name]) => name);
 }
+
+/**
+ * The schema-qualified tables that are ENABLE-not-FORCE — every model whose write
+ * principal is not the app (`writtenBy !== 'app'`). These are the FORCE-RLS carveouts
+ * db:doctor must not flag: the worker / SECDEF functions write them as the owner and
+ * need the owner's RLS bypass (on RDS the owner is not a superuser, so FORCE would
+ * block its own writes).
+ *
+ * This replaces the hand-maintained `forceRlsCarveouts` string list in an app's ops
+ * config — the carveout is now read from each table's own `writtenBy` declaration,
+ * so it can't drift from the contract (the bare-name bug that list once caused).
+ * Deterministic: sorted.
+ */
+export function deriveForceRlsCarveouts(models: ModelDescriptor[]): string[] {
+  return models
+    .filter((m) => m.writtenBy !== 'app')
+    .map((m) => `${m.schema}.${m.table}`)
+    .sort();
+}
+
+/**
+ * The distinct schemas that own a `writtenBy: 'functions'` table (e.g. `['auth']`). A
+ * functions-written table is ENABLE-not-FORCE because the package's SECURITY DEFINER
+ * functions write it as the owner — so db:doctor's `functions` teeth assert those schemas'
+ * SECDEF functions exist and pin their search_path. Derived from the same `writtenBy`
+ * declaration as the carveouts, so the two can't disagree. Deterministic: sorted.
+ */
+export function deriveFunctionSchemas(models: ModelDescriptor[]): string[] {
+  return [...new Set(models.filter((m) => m.writtenBy === 'functions').map((m) => m.schema))].sort();
+}

package/src/drizzle.ts

@@ -0,0 +1,213 @@
+/**
+ * `toDrizzleTable` — the runtime bridge. A {@link ModelDescriptor} already owns
+ * everything a hand-written drizzle table carries (column names, types,
+ * nullability, defaults, primary key, foreign keys, table-level constraints), so
+ * this derivation lets a Model *be* the single source for the drizzle-orm table
+ * object. An app's `db/schema.ts` then collapses to derived re-exports.
+ *
+ * Drizzle-only: it imports `drizzle-orm/pg-core`, so it lives under the package's
+ * `./drizzle` subpath and is deliberately NOT re-exported from `src/index.ts` —
+ * the core index stays drizzle-free (drizzle-orm is an optional peer).
+ *
+ * Forward/circular references resolve through a module-level registry: a model is
+ * built at most once, so a parent referenced from a child's FK thunk yields the
+ * *same* table instance every consumer sees.
+ */
+
+import {
+  pgTable,
+  pgSchema,
+  pgEnum,
+  text,
+  uuid,
+  integer,
+  bigint,
+  serial,
+  bigserial,
+  real,
+  doublePrecision,
+  boolean,
+  timestamp,
+  date,
+  numeric,
+  varchar,
+  jsonb,
+  primaryKey,
+  unique,
+  check,
+  type PgColumnBuilderBase,
+  type PgTableWithColumns,
+  type AnyPgColumn,
+} from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+
+import type { ModelDescriptor } from './model';
+import type { FieldSpec } from './field';
+
+/** Built tables, keyed by the {@link ModelDescriptor} object — the FK-sharing + idempotency cache. */
+const tableRegistry = new Map<ModelDescriptor, PgTableWithColumns<any>>();
+
+/** Postgres enum types, keyed by `enumName`, so a type shared across fields/tables is created once. */
+const enumRegistry = new Map<string, ReturnType<typeof pgEnum>>();
+
+/** `authorId` → `author_id`. The single snake-case rule used everywhere a field key becomes a SQL identifier. */
+function snake(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => '_' + c.toLowerCase());
+}
+
+function getEnum(spec: FieldSpec): ReturnType<typeof pgEnum> {
+  const name = spec.enumName;
+  if (!name) throw new Error('enum field is missing enumName');
+  let e = enumRegistry.get(name);
+  if (!e) {
+    e = pgEnum(name, (spec.enumValues ?? []) as [string, ...string[]]);
+    enumRegistry.set(name, e);
+  }
+  return e;
+}
+
+/** Map a field's Postgres type to a drizzle pg-core column builder (no modifiers yet). */
+function baseColumn(columnName: string, spec: FieldSpec): PgColumnBuilderBase {
+  switch (spec.type) {
+    case 'text':
+      return text(columnName);
+    case 'uuid':
+      return uuid(columnName);
+    case 'integer':
+      return integer(columnName);
+    case 'bigint':
+      return bigint(columnName, { mode: 'number' });
+    case 'serial':
+      return serial(columnName);
+    case 'bigserial':
+      return bigserial(columnName, { mode: 'number' });
+    case 'real':
+      return real(columnName);
+    case 'doublePrecision':
+      return doublePrecision(columnName);
+    case 'boolean':
+      return boolean(columnName);
+    case 'timestamptz':
+      return timestamp(columnName, { withTimezone: true });
+    case 'timestamp':
+      return timestamp(columnName);
+    case 'date':
+      return date(columnName);
+    case 'numeric':
+      return spec.precision !== undefined
+        ? numeric(columnName, { precision: spec.precision, scale: spec.scale })
+        : numeric(columnName);
+    case 'varchar':
+      return spec.length !== undefined ? varchar(columnName, { length: spec.length }) : varchar(columnName);
+    case 'jsonb':
+      return jsonb(columnName);
+    case 'enum':
+      return getEnum(spec)(columnName);
+    default: {
+      const exhaustive: never = spec.type;
+      throw new Error(`Unsupported field type: ${String(exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * Derive a runtime drizzle-orm table from a Model. Idempotent and FK-safe: the same
+ * descriptor always yields the same cached table instance, so a parent referenced by a
+ * child's FK thunk and the parent built directly are one object.
+ */
+export function toDrizzleTable(model: ModelDescriptor): PgTableWithColumns<any> {
+  const cached = tableRegistry.get(model);
+  if (cached) return cached;
+
+  const isComposite = model.primaryKey.length > 1;
+
+  const columns: Record<string, PgColumnBuilderBase> = {};
+
+  for (const [key, builder] of Object.entries(model.fields)) {
+    const spec = builder.spec;
+    const columnName = snake(key);
+
+    // Modifier chaining loses the precise builder type per branch; `any` is the
+    // standard drizzle-internal escape hatch (mirrors the field.ts convention).
+    let col: any = baseColumn(columnName, spec);
+
+    if (spec.isArray) col = col.array();
+    if (spec.isNotNull) col = col.notNull();
+    if (spec.isUnique) col = col.unique();
+
+    if (spec.defaultKind === 'now') col = col.defaultNow();
+    else if (spec.defaultKind === 'random') col = col.defaultRandom();
+    else if (spec.defaultKind === 'value') col = col.default(spec.default);
+
+    // Single-column PK lives on the column; composite PKs are emitted table-level below.
+    if (spec.isPrimaryKey && !isComposite) col = col.primaryKey();
+
+    if (spec.references) {
+      const target = spec.references as () => ModelDescriptor;
+      const refOpts: { onDelete?: FieldSpec['onDelete']; onUpdate?: FieldSpec['onUpdate'] } = {};
+      if (spec.onDelete) refOpts.onDelete = spec.onDelete;
+      if (spec.onUpdate) refOpts.onUpdate = spec.onUpdate;
+      // Resolve the parent table lazily — the registry guarantees one shared instance
+      // and lets circular references converge.
+      col = col.references(() => {
+        const parent = toDrizzleTable(target());
+        const parentPkKey = parentPrimaryKeyColumnKey(target());
+        return (parent as any)[parentPkKey];
+      }, refOpts);
+    }
+
+    columns[key] = col;
+  }
+
+  // Second-arg extra-config: composite PK, then table-level constraints.
+  const extraConfig = (table: Record<string, AnyPgColumn>): unknown[] => {
+    const extras: unknown[] = [];
+
+    if (isComposite) {
+      const pkCols = model.primaryKey.map((k) => table[k]) as [AnyPgColumn, ...AnyPgColumn[]];
+      extras.push(primaryKey({ columns: pkCols }));
+    }
+
+    for (const c of model.constraints) {
+      switch (c.kind) {
+        case 'unique': {
+          const uCols = c.columns.map((k) => table[k]) as [AnyPgColumn, ...AnyPgColumn[]];
+          extras.push(unique().on(...uCols));
+          break;
+        }
+        case 'check':
+          extras.push(check(`${model.table}_check`, sql.raw(c.predicate)));
+          break;
+        // 'index' and 'foreignKey' table constraints are compiled at the DDL layer;
+        // they are not needed for the runtime drizzle table object (the FK relationship
+        // for queries comes from column `.references()`), so they are intentionally
+        // not materialized here.
+        default:
+          break;
+      }
+    }
+
+    return extras;
+  };
+
+  // A package table lives in its own schema (dist/ops/auth); an app table stays in
+  // public, where drizzle's pgTable leaves the schema implicit.
+  const table = (model.schema && model.schema !== 'public'
+    ? pgSchema(model.schema).table(model.table, columns as any, extraConfig as any)
+    : pgTable(model.table, columns as any, extraConfig as any)) as PgTableWithColumns<any>;
+  tableRegistry.set(model, table);
+  return table;
+}
+
+/** The drizzle column *key* for a model's (single) primary key — FK targets reference it. */
+function parentPrimaryKeyColumnKey(parent: ModelDescriptor): string {
+  const pk = parent.primaryKey[0];
+  if (!pk) throw new Error(`Referenced model "${parent.table}" has no primary key`);
+  return pk;
+}
+
+/** Test/tooling seam: clear the module caches so a fresh derivation can be observed. */
+export function __resetDrizzleRegistry(): void {
+  tableRegistry.clear();
+  enumRegistry.clear();
+}

package/src/field.ts

@@ -1,22 +1,25 @@
 /**
- * The field descriptor — Layer 1 of the Model, in its Phase-0 form.
+ * The field descriptor — Layer 1 of the Model.
  *
- * Today a `field()` records *intent*: the Postgres type and the exposure /
- * constraint modifiers the handler-config derivation needs (`.private()`,
- * `.readonly()`, primary key, references). It does NOT yet generate DDL or Zod —
- * that is the Zod⊗Postgres bridge (Phase 4), which enriches THIS SAME builder
- * surface without changing how a model is written. A model authored now keeps
- * working when the bridge lands.
+ * A `field()` records the Postgres type and the exposure / constraint modifiers
+ * (`.private()`, `.readonly()`, primary key, references, `.validate()`).
+ * `@everystack/cli` compiles those to column DDL and to the per-table handler
+ * config; `.validate()`'s SQL-expressible refinements become CHECK constraints
+ * (richer Zod refinements stay app-layer). The model just declares — authoring
+ * stays the same as the compile targets grow.
  *
- * See docs/plans/v3-model-implementation.md (Phase 0) and v3-model-api.md.
+ * See docs/plans/v3-model-api.md.
  */
 
 export type FieldType =
   | 'text'
   | 'uuid'
   | 'bigint'
+  | 'serial'
   | 'bigserial'
   | 'integer'
+  | 'real'
+  | 'doublePrecision'
   | 'boolean'
   | 'timestamptz'
   | 'timestamp'
@@ -46,6 +49,8 @@ export interface FieldSpec {
   isPrimaryKey: boolean;
   isNotNull: boolean;
   isUnique: boolean;
+  /** `.array()` — a Postgres array of the base type (`text` → `text[]`). */
+  isArray: boolean;
   /** `.private()` — never serialized into API responses (→ `hiddenColumns`). */
   isPrivate: boolean;
   /** `.readonly()` — never accepted on write (→ `protectedFields`). */
@@ -89,6 +94,7 @@ export class FieldBuilder {
       isPrimaryKey: false,
       isNotNull: false,
       isUnique: false,
+      isArray: false,
       isPrivate: false,
       isReadonly: false,
     };
@@ -115,6 +121,12 @@ export class FieldBuilder {
     return this;
   }
 
+  /** A Postgres array of the base type: `field.text().array()` → `text[]`. */
+  array(): this {
+    this.spec.isArray = true;
+    return this;
+  }
+
   /** Hide from every API response. Compiles to the handler's `hiddenColumns`. */
   private(): this {
     this.spec.isPrivate = true;
@@ -177,8 +189,14 @@ export const field = {
   text: (): FieldBuilder => new FieldBuilder('text'),
   uuid: (): FieldBuilder => new FieldBuilder('uuid'),
   bigint: (): FieldBuilder => new FieldBuilder('bigint'),
-  bigserial: (): FieldBuilder => new FieldBuilder('bigserial'),
+  // A serial column is NOT NULL by Postgres definition, so the builder starts that way.
+  serial: (): FieldBuilder => new FieldBuilder('serial').notNull(),
+  bigserial: (): FieldBuilder => new FieldBuilder('bigserial').notNull(),
   integer: (): FieldBuilder => new FieldBuilder('integer'),
+  /** `real` — single-precision float (float4). */
+  real: (): FieldBuilder => new FieldBuilder('real'),
+  /** `double precision` — double-precision float (float8). */
+  doublePrecision: (): FieldBuilder => new FieldBuilder('doublePrecision'),
   boolean: (): FieldBuilder => new FieldBuilder('boolean'),
   timestamptz: (): FieldBuilder => new FieldBuilder('timestamptz'),
   timestamp: (): FieldBuilder => new FieldBuilder('timestamp'),

package/src/index.ts

@@ -2,8 +2,9 @@
  * @everystack/model — declare a table once; compile it to migrations, RLS, and
  * handler config. See docs/plans/v3-model-architecture.md.
  *
- * Phase 0 ships the declaration surface (`defineModel`, `field`, `can`,
- * `belongsTo`/`hasMany`) and the first compile target: handler-config derivation.
+ * Ships the declaration surface (`defineModel`, `field`, `can`, `belongsTo`/
+ * `hasMany`); `@everystack/cli` compiles models to migrations, RLS + grants, and
+ * handler config (`deriveHandlerConfig`).
  */
 
 export { field, FieldBuilder } from './field';
@@ -22,7 +23,10 @@ export { belongsTo, hasMany } from './relations';
 export type { Relation } from './relations';
 
 export { defineModel } from './model';
-export type { ModelDescriptor, ModelDefinition, ModelHooks } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy } from './model';
 
-export { deriveHandlerConfig } from './derive';
+export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql } from './module';
+export type { Module, ModuleDefinition } from './module';
+
+export { deriveHandlerConfig, deriveForceRlsCarveouts, deriveFunctionSchemas } from './derive';
 export type { DerivedHandlerConfig, RelationConfig } from './derive';

package/src/model.ts

@@ -6,8 +6,9 @@
  * functional `field`/`can` builders, and structurally resists the fat-model trap
  * (a model *declares*; behavior lives in the functions it references).
  *
- * Phase 0 returns a plain descriptor. Later phases read it from two directions —
- * the handler-config derivation (now) and the abilities→contract compiler (Phase 1).
+ * Returns a plain descriptor that `@everystack/cli` reads from two directions —
+ * handler-config derivation (`deriveHandlerConfig`) and the abilities→contract
+ * compiler (`compileTableContract`, what `db:generate` emits as RLS + grants).
  */
 
 import type { FieldBuilder } from './field';
@@ -29,6 +30,24 @@ export interface ModelHooks {
   afterDelete?: (...args: any[]) => any;
 }
 
+/**
+ * Who holds the pen on a table — the write principal. The compiler derives RLS
+ * posture from it via the axiom "FORCE iff the write principal is subject to its
+ * own RLS policies":
+ *
+ *   - `'app'`       — app roles write through their own policies; subject to RLS -> FORCE.
+ *   - `'worker'`    — the worker writes it on the owner connection, bypassing RLS
+ *                     (on RDS the owner is not a superuser, so a FORCEd table would
+ *                     block the owner's own writes) -> ENABLE-not-FORCE.
+ *   - `'functions'` — written only by SECURITY DEFINER functions the package owns,
+ *                     running as owner -> ENABLE-not-FORCE. `db:doctor` additionally
+ *                     asserts those functions exist with a pinned `search_path`.
+ *
+ * Default `'app'`. This also replaces the app's hand-maintained `forceRlsCarveouts`
+ * list: `db:doctor` reads the carveout intent (`writtenBy !== 'app'`) off the contract.
+ */
+export type WrittenBy = 'app' | 'worker' | 'functions';
+
 export interface ModelDefinition {
   fields: Record<string, FieldBuilder>;
   abilities?: Ability[];
@@ -36,6 +55,22 @@ export interface ModelDefinition {
   relations?: Record<string, Relation>;
   /** Table-level constraints the column-scoped `field()` can't express — composite `unique`, multi-column `check`. */
   constraints?: TableConstraint[];
+  /** The write principal — drives RLS posture. Default `'app'`. See {@link WrittenBy}. */
+  writtenBy?: WrittenBy;
+  /**
+   * The Postgres schema the table lives in. Default `'public'`. Package-owned
+   * tables declare their own (`'dist'`, `'ops'`, `'auth'`) so one db:generate run
+   * can span schemas — the model's schema always wins over a generate call's default.
+   */
+  schema?: string;
+  /**
+   * `true` removes the table from the generic data API — `deriveHandlerConfig`
+   * skips it, so it never enters `exposedTables`. Default `false`. Package-owned
+   * operational tables (`dist.blobs`, `ops.runs`, `auth.users`) are reached through
+   * dedicated handlers, not generic CRUD; they are still generated (schema + authz),
+   * just not exposed. Named `private` to avoid colliding with `schema: 'public'`.
+   */
+  private?: boolean;
 }
 
 export interface ModelDescriptor {
@@ -49,6 +84,12 @@ export interface ModelDescriptor {
   primaryKey: string[];
   /** Table-level constraints (composite unique, multi-column check), in declaration order. */
   constraints: TableConstraint[];
+  /** The resolved write principal (default `'app'`) — drives RLS posture. See {@link WrittenBy}. */
+  writtenBy: WrittenBy;
+  /** The resolved Postgres schema (default `'public'`). Package tables live in their own. */
+  schema: string;
+  /** `true` removes the table from the generic data API (not in `exposedTables`). Default `false`. */
+  private: boolean;
 }
 
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
@@ -64,5 +105,8 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     relations: def.relations ?? {},
     primaryKey,
     constraints: def.constraints ?? [],
+    writtenBy: def.writtenBy ?? 'app',
+    schema: def.schema ?? 'public',
+    private: def.private ?? false,
   };
 }

package/src/module.ts

@@ -0,0 +1,68 @@
+/**
+ * `defineModule` — Layer 3. A package owns not just its Models (schema + authz) but its
+ * whole slice of the database: the extensions its SQL needs and the package-owned SQL it
+ * ships (SECURITY DEFINER functions, triggers). A Module bundles the three so the one
+ * generator can emit a COMPLETE migration — no hand-written bootstrap left.
+ *
+ * The split is deliberate:
+ *   - `models`     — declarative schema + authz, round-tripped through the contract (the
+ *                    dogfood proves these).
+ *   - `extensions` — `CREATE EXTENSION IF NOT EXISTS`, emitted first, deduped across modules.
+ *   - `functions`  — imperative package SQL (plpgsql functions, triggers). NOT modeled — it
+ *                    is contributed verbatim and emitted AFTER the tables it references. A
+ *                    thunk, so generation stays lazy (and an app can pass run-specific args,
+ *                    e.g. which tables get event triggers).
+ *
+ * Roles are NOT a Module concern — they are cluster-global and owned by `db:provision`, so a
+ * Module's GRANTs assume the roles already exist (exactly as the dogfood pre-creates them).
+ *
+ * See docs/plans/v3-module-complete-generation.md.
+ */
+
+import type { ModelDescriptor } from './model';
+
+export interface ModuleDefinition {
+  /** The package's Models (schema + authz). */
+  models?: ModelDescriptor[];
+  /** Postgres extensions the module's SQL needs (e.g. `'pgcrypto'`). Emitted once, first. */
+  extensions?: string[];
+  /**
+   * Package-owned SQL emitted after the tables — SECURITY DEFINER functions, triggers, etc.
+   * A thunk so it is generated lazily and can take run-specific input (the app's event-trigger
+   * table list, say). Not part of the declarative contract; emitted verbatim.
+   */
+  functions?: () => string;
+}
+
+/** A normalized package DB slice — what {@link defineModule} produces and the generator composes. */
+export interface Module {
+  models: ModelDescriptor[];
+  extensions: string[];
+  /** Function-SQL thunks, normalized to an array so composing modules just concatenates. */
+  functions: Array<() => string>;
+}
+
+/** Declare a package's database slice. Empty fields default to nothing — a models-only module is fine. */
+export function defineModule(def: ModuleDefinition): Module {
+  return {
+    models: def.models ?? [],
+    extensions: def.extensions ?? [],
+    functions: def.functions ? [def.functions] : [],
+  };
+}
+
+/** 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[] {
+  return modules.flatMap((m) => m.models);
+}
+
+/** The deduped, sorted extension list across modules — emitted as `CREATE EXTENSION` first. */
+export function moduleExtensions(modules: Module[]): string[] {
+  return [...new Set(modules.flatMap((m) => m.extensions))].sort();
+}
+
+/** The package SQL across modules, each thunk invoked — emitted after the tables. */
+export function moduleFunctionSql(modules: Module[]): string[] {
+  return modules.flatMap((m) => m.functions).map((fn) => fn());
+}