@everystack/model 0.3.6 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.3.6",
+  "version": "0.4.1",
   "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/can.ts

@@ -9,8 +9,8 @@
  * Default-deny is the model's contract: no matching `can()` means denied.
  */
 
-/** CanCan verbs. `manage` is "all actions". */
-export type Action = 'read' | 'create' | 'update' | 'delete' | 'manage';
+/** CanCan verbs. `manage` is "all actions". `execute` is FUNCTION-only (rejected on tables/relations). */
+export type Action = 'read' | 'create' | 'update' | 'delete' | 'manage' | 'execute';
 
 export interface AbilityCondition {
   /** Role-gated: policy `TO <role>` + grant. */

package/src/constraints.ts

@@ -18,8 +18,8 @@ export type TableConstraint =
   | { kind: 'unique'; columns: string[] }
   /** `CHECK (<predicate>)` — a raw SQL predicate, typically spanning columns. */
   | { kind: 'check'; predicate: string }
-  /** A standalone index — `CREATE [UNIQUE] INDEX … (cols) [WHERE <predicate>]`. */
-  | { kind: 'index'; columns: string[]; isUnique: boolean; predicate?: string }
+  /** A standalone index — `CREATE [UNIQUE] INDEX [USING <method>] … (keys) [INCLUDE (cols)] [WHERE <predicate>]`. */
+  | { kind: 'index'; columns: string[]; isUnique: boolean; predicate?: string; method?: string; includeColumns?: string[]; rawPositions?: boolean[] }
   /**
    * A multi-column `FOREIGN KEY (a, b) REFERENCES other (x, y)` — the composite a column-scoped
    * `.references()` can't carry. Local field keys, a model thunk for the target, and the target's
@@ -60,8 +60,16 @@ export function foreignKey(
 }
 
 /**
- * A standalone index over the given field keys, chainable: `index('authorId')`,
- * `index('authorId').unique()`, `index('slug').where(sql\`deleted_at IS NULL\`)` (partial).
+ * A standalone index over the given keys, chainable: `index('authorId')`,
+ * `index('authorId').unique()`, `index('slug').where(sql\`deleted_at IS NULL\`)` (partial),
+ * `index('tags').using('gin')`, `index(sql\`lower(email)\`)` (expression).
+ *
+ * Entries are field keys (strings — the compiler snake_cases them) or raw `sql\`\`` for
+ * anything richer: an expression (`lower(email)`), a direction (`created_at DESC`), an
+ * opclass (`title gin_trgm_ops`). Raw entries pass to SQL verbatim — they are written in
+ * SQL column names, not field keys — and are part of the index's content identity, so a
+ * pulled expression index round-trips instead of churning (Brick E).
+ *
  * Indexes that merely back a primary key or unique constraint are NOT declared here — those
  * come from `.primaryKey()` / `.unique()` / the `unique(...)` constraint.
  */
@@ -69,7 +77,19 @@ export class IndexBuilder {
   readonly kind = 'index' as const;
   isUnique = false;
   predicate?: string;
-  constructor(readonly columns: string[]) {}
+  /** Access method (`'gin'`, `'gist'`, `'hash'`, `'brin'`, `'spgist'`); omitted = btree. */
+  method?: string;
+  /** `INCLUDE (…)` covering columns — field keys, snake_cased by the compiler. */
+  includeColumns?: string[];
+  /** The key texts, in order — field keys for plain entries, verbatim SQL for raw ones. */
+  readonly columns: string[];
+  /** Which positions are raw `sql\`\`` (never snake_cased, never quoted). */
+  readonly rawPositions: boolean[];
+
+  constructor(entries: Array<string | RawSql>) {
+    this.columns = entries.map((e) => (typeof e === 'string' ? e : e.sql));
+    this.rawPositions = entries.map((e) => typeof e !== 'string');
+  }
 
   /** Make it a UNIQUE index. */
   unique(): this {
@@ -82,8 +102,20 @@ export class IndexBuilder {
     this.predicate = predicate.sql;
     return this;
   }
+
+  /** The access method: `index('tags').using('gin')`. Omitted = btree (never spelled). */
+  using(method: string): this {
+    this.method = method.toLowerCase();
+    return this;
+  }
+
+  /** Covering columns: `index('authorId').include('title')` → `INCLUDE ("title")`. */
+  include(...columns: string[]): this {
+    this.includeColumns = columns;
+    return this;
+  }
 }
 
-export function index(...columns: string[]): IndexBuilder {
-  return new IndexBuilder(columns);
+export function index(...entries: Array<string | RawSql>): IndexBuilder {
+  return new IndexBuilder(entries);
 }

package/src/derived.ts

@@ -0,0 +1,515 @@
+/**
+ * The declarative derived layer — views, materialized views, functions, sequences,
+ * triggers, and the gate-tight escape hatch. The `defineModel` philosophy extended to
+ * every object the database holds (docs/plans/read-model-everywhere.md).
+ *
+ * The boundary rule, uniform with models: STRUCTURE DECLARED (identity, deps, authz,
+ * security posture, indexes, signatures, trigger events), EXPRESSIONS AS sql`` (the
+ * SELECT, the function body, a WHEN predicate). No query DSL; no string mini-grammars
+ * in declared properties.
+ *
+ * Every rejection here is a define-time (author-time) error whose message carries its
+ * fix — the earliest gate there is. Lifecycle note: these descriptors are COMPUTE
+ * (deployed by db:reconcile, never migrated) — except `defineSequence`, which is STATE
+ * (a sequence holds a counter value; it migrates with the base schema).
+ */
+
+import type { RawSql } from './raw-sql';
+import type { Ability } from './can';
+import type { ModelDescriptor } from './model';
+import type { IndexBuilder } from './constraints';
+import type { FieldBuilder } from './field';
+
+// ---------------------------------------------------------------------------
+// Shared shapes
+// ---------------------------------------------------------------------------
+
+/** Anything a derived object can declare a dependency on — order derives from these refs. */
+export type DependsOnRef = ModelDescriptor | DerivedDescriptor;
+
+/**
+ * The loud undefined gate. A missing named import under CJS interop evaluates to
+ * `undefined` and, unchecked, dies layers later as `'table' in undefined` with no
+ * context. Every ref list rejects the hole HERE, naming the owner, the list, the
+ * index, and the likely cause.
+ */
+export function rejectHoles(context: string, listName: string, list: readonly unknown[] | undefined): void {
+  if (!list) return;
+  list.forEach((entry, i) => {
+    if (entry == null) {
+      throw new Error(`${context}: ${listName}[${i}] is ${entry === undefined ? 'undefined' : 'null'} — renamed or missing import?`);
+    }
+  });
+}
+
+/**
+ * Relations (views/matviews) carry read-only authz in v1; functions carry execute.
+ * The row-scoped condition keys (`owner`, `via`, `where`, `sql`) are meaningless on
+ * a relation — rows are filtered by the body or the underlying RLS — and rejected.
+ */
+function validateRelationAbilities(kind: string, name: string, abilities: Ability[]): void {
+  for (const a of abilities) {
+    if (a.action !== 'read') {
+      throw new Error(
+        `${kind} '${name}': can('${a.action}') is not a relation ability — views and matviews are read surfaces in v1. Write through the table (INSTEAD-OF write-throughs are future work).`,
+      );
+    }
+    if (a.condition.owner || a.condition.via || a.condition.where || a.condition.sql) {
+      throw new Error(
+        `${kind} '${name}': row conditions cannot attach to a relation — a matview cannot carry policies and a view's rows are filtered by its body or the underlying RLS. Filter in the body, or use securityInvoker: true over the RLS'd table.`,
+      );
+    }
+  }
+}
+
+function validatePrivateContradiction(kind: string, name: string, priv: boolean | undefined, abilities: Ability[] | undefined): void {
+  if (priv && abilities?.length) {
+    throw new Error(`${kind} '${name}': private: true declares it dark — it cannot also declare abilities. Drop one.`);
+  }
+}
+
+/**
+ * A relation's `fields` declare its OUTPUT SHAPE — type + nullability + array, nothing
+ * else. Everything table-structural on a field builder (keys, FKs, defaults, write-surface
+ * markers, migration hints) is meaningless on a column a body computes, and rejected with
+ * the fix. The declared shape is a runtime-typing annotation: it never changes the CREATE
+ * statement, the content hash, or the reconcile plan — only the generated drizzle source.
+ */
+function validateRelationFields(kind: string, name: string, fields: Record<string, FieldBuilder> | undefined, priv: boolean | undefined): void {
+  if (!fields) return;
+  if (priv) {
+    throw new Error(
+      `${kind} '${name}': private: true declares it dark — typed fields declare a read surface no role can reach. Drop one.`,
+    );
+  }
+  for (const [key, builder] of Object.entries(fields)) {
+    const at = `${kind} '${name}', fields.${key}`;
+    const s = builder.spec;
+    if (s.isPrimaryKey) throw new Error(`${at}: .primaryKey() is table structure — a relation column carries type, nullability, and array only.`);
+    if (s.isUnique) throw new Error(`${at}: .unique() is a table constraint — enforce it on the base table (or a matview index).`);
+    if (s.references) throw new Error(`${at}: .references() is a table FK — declare it on the base table; the body carries the join.`);
+    if (s.defaultKind) throw new Error(`${at}: defaults are meaningless on a relation column — the body computes every value.`);
+    if (s.isDeprecated) throw new Error(`${at}: .deprecated() is the table contract phase — remove the column from the body instead.`);
+    if (s.isPrivate) throw new Error(`${at}: .private() hides a table column from the API — a relation exposes only what its body selects; drop the column from the body.`);
+    if (s.isReadonly) throw new Error(`${at}: .readonly() marks a write surface — relations are read-only already.`);
+    if (s.renamedFrom) throw new Error(`${at}: .renamedFrom() is a migration hint — relations rebuild from their body, they don't migrate.`);
+    if (s.validation) throw new Error(`${at}: .validate() shapes the write surface — relations take no writes.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Triggers — pure structure; a trigger has no body at all
+// ---------------------------------------------------------------------------
+
+export type TriggerTiming = 'before' | 'after' | 'insteadOf';
+export type TriggerEvent = 'insert' | 'update' | 'delete' | 'truncate';
+
+/** Canonical event order — events are deduped and sorted so the SAME trigger always hashes the same. */
+const EVENT_ORDER: TriggerEvent[] = ['insert', 'update', 'delete', 'truncate'];
+
+export interface TriggerDefinition {
+  timing: TriggerTiming;
+  events: TriggerEvent[];
+  forEach: 'row' | 'statement';
+  /** `UPDATE OF (columns)` — only with an `update` event. */
+  of?: string[];
+  /** The SQL `WHEN` predicate — an expression, stays raw. */
+  condition?: RawSql;
+  /** The trigger function — a shared, standalone {@link defineFunction} returning `trigger`. */
+  execute: FunctionDescriptor;
+}
+
+export interface TriggerSpec {
+  name: string;
+  timing: TriggerTiming;
+  events: TriggerEvent[];
+  forEach: 'row' | 'statement';
+  of?: string[];
+  condition?: string;
+  execute: FunctionDescriptor;
+}
+
+/**
+ * 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.
+ */
+export function trigger(name: string, def: TriggerDefinition): TriggerSpec {
+  if (def.execute == null) {
+    throw new Error(`trigger '${name}': execute is ${def.execute === undefined ? 'undefined' : 'null'} — renamed or missing import?`);
+  }
+  const events = EVENT_ORDER.filter((e) => def.events.includes(e));
+  if (events.length === 0) throw new Error(`trigger '${name}': declare at least one event.`);
+  if (def.of && !events.includes('update')) {
+    throw new Error(`trigger '${name}': of: (UPDATE OF columns) requires an update event.`);
+  }
+  if (events.includes('truncate')) {
+    if (def.forEach === 'row') throw new Error(`trigger '${name}': truncate is statement-only — forEach: 'statement'.`);
+    if (def.condition) throw new Error(`trigger '${name}': truncate takes no condition (WHEN).`);
+  }
+  if (def.timing === 'insteadOf') {
+    if (def.forEach !== 'row') throw new Error(`trigger '${name}': INSTEAD OF must be forEach: 'row'.`);
+    if (def.condition) throw new Error(`trigger '${name}': INSTEAD OF takes no condition (WHEN).`);
+    if (def.of) throw new Error(`trigger '${name}': INSTEAD OF takes no of: (UPDATE OF columns).`);
+  }
+  if (def.execute.returns !== 'trigger') {
+    throw new Error(`trigger '${name}': execute must be a function with returns: 'trigger' — '${def.execute.name}' returns '${String(typeof def.execute.returns === 'string' ? def.execute.returns : 'setof')}'.`);
+  }
+  return {
+    name,
+    timing: def.timing,
+    events,
+    forEach: def.forEach,
+    ...(def.of ? { of: def.of } : {}),
+    ...(def.condition ? { condition: def.condition.sql } : {}),
+    execute: def.execute,
+  };
+}
+
+/** 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);
+  for (const t of triggers) {
+    if (target === 'table' && t.timing === 'insteadOf') {
+      throw new Error(`table '${owner}', trigger '${t.name}': INSTEAD OF is a view trigger — attach it to the defineView it rewrites.`);
+    }
+    if (target === 'view' && t.timing !== 'insteadOf' && t.forEach === 'row') {
+      throw new Error(`view '${owner}', trigger '${t.name}': views take INSTEAD OF row triggers or BEFORE/AFTER statement-level triggers — never BEFORE/AFTER row.`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Functions — signature structured, body raw
+// ---------------------------------------------------------------------------
+
+export interface ArgSpec {
+  name: string;
+  type: string;
+  /** A raw SQL default for the argument. */
+  default?: string;
+}
+
+/** One positional argument. An ARRAY of these is the signature — never object key order. */
+export function arg(name: string, type: string, opts?: { default?: RawSql }): ArgSpec {
+  return { name, type, ...(opts?.default ? { default: opts.default.sql } : {}) };
+}
+
+/** `returns: setof(posts)` — a descriptor ref, so a typo is a TS error and the dep comes free. */
+export interface SetofReturn {
+  setof: ModelDescriptor | ViewDescriptor | MaterializedViewDescriptor;
+}
+
+export function setof(ref: SetofReturn['setof']): SetofReturn {
+  if (ref == null) {
+    throw new Error(`setof(): ref is ${ref === undefined ? 'undefined' : 'null'} — renamed or missing import?`);
+  }
+  return { setof: ref };
+}
+
+export interface FunctionDefinition {
+  args?: ArgSpec[];
+  returns: string | SetofReturn;
+  language: 'sql' | 'plpgsql';
+  /** Default `'invoker'` (the safe one). `'definer'` REQUIRES a pinned searchPath. */
+  security?: 'invoker' | 'definer';
+  /** An ARRAY of schemas, not a comma string. */
+  searchPath?: string[];
+  /** 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. */
+  abilities?: Ability[];
+  comment?: string;
+  body: RawSql;
+}
+
+export interface FunctionDescriptor {
+  kind: 'function';
+  name: string;
+  args: ArgSpec[];
+  returns: string | SetofReturn;
+  language: 'sql' | 'plpgsql';
+  security: 'invoker' | 'definer';
+  searchPath?: string[];
+  volatility: 'immutable' | 'stable' | 'volatile';
+  dependsOn: DependsOnRef[];
+  abilities: Ability[];
+  comment?: string;
+  body: string;
+}
+
+export function defineFunction(name: string, def: FunctionDefinition): FunctionDescriptor {
+  rejectHoles(`function '${name}'`, 'dependsOn', def.dependsOn);
+  const security = def.security ?? 'invoker';
+  if (security === 'definer' && (!def.searchPath || def.searchPath.length === 0)) {
+    throw new Error(
+      `function '${name}': SECURITY DEFINER without a pinned searchPath is the classic landmine — pin searchPath: ['pg_catalog'] (plus the schemas the body needs), or use security: 'invoker'.`,
+    );
+  }
+  const args = def.args ?? [];
+  const seen = new Set<string>();
+  for (const a of args) {
+    if (seen.has(a.name)) throw new Error(`function '${name}': duplicate argument '${a.name}'.`);
+    seen.add(a.name);
+  }
+  for (const a of def.abilities ?? []) {
+    if (a.action !== 'execute') {
+      throw new Error(`function '${name}': can('${a.action}') is not a function ability — functions carry can('execute', { role }) only.`);
+    }
+    if (!a.condition.role) {
+      throw new Error(
+        `function '${name}': bare can('execute') has no safe default audience — declare { role: 'authenticated' }, or { role: 'anon' } for public-callable.`,
+      );
+    }
+  }
+  return {
+    kind: 'function',
+    name,
+    args,
+    returns: def.returns,
+    language: def.language,
+    security,
+    ...(def.searchPath ? { searchPath: def.searchPath } : {}),
+    volatility: def.volatility ?? 'volatile',
+    dependsOn: def.dependsOn ?? [],
+    abilities: def.abilities ?? [],
+    ...(def.comment ? { comment: def.comment } : {}),
+    body: def.body.sql,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Views — securityInvoker is the forced decision
+// ---------------------------------------------------------------------------
+
+export interface ViewDefinition {
+  /**
+   * REQUIRED, no default — the one decision that distinguishes the two legitimate
+   * shapes: `true` = readers' own RLS/grants apply through the view; `false` =
+   * definer semantics, the "safe slice" pattern (view grant WITHOUT table grant —
+   * the body must seal what it exposes).
+   */
+  securityInvoker: boolean;
+  abilities?: Ability[];
+  dependsOn?: DependsOnRef[];
+  /** `INSTEAD OF` row triggers, or BEFORE/AFTER statement-level. */
+  triggers?: TriggerSpec[];
+  comment?: string;
+  /** Declared dark — intentionally no grants; satisfies the read-gap gate honestly. */
+  private?: boolean;
+  /**
+   * The declared output shape — same `field.*` builders as models, type/nullability/array
+   * only. Opt-in: declaring fields emits a typed `pgView(...).existing()` into
+   * `schema.generated.ts` (typed SSR reads); omitting them leaves the relation out of the
+   * generated drizzle schema. Never touches the CREATE statement or the content hash.
+   *
+   * CONTRACT: each field key binds the snake_case column of that name (`displayName` →
+   * `display_name`) — the SELECT must emit that output column, aliasing where needed
+   * (`count(*) AS n`). Fields are author-declared, not introspected: a wrong NAME fails
+   * every read of the relation loudly (drizzle selects all declared columns), but a
+   * wrong type or nullability mistypes reads SILENTLY. Keep them truthful.
+   */
+  fields?: Record<string, FieldBuilder>;
+  as: RawSql;
+}
+
+export interface ViewDescriptor {
+  kind: 'view';
+  name: string;
+  securityInvoker: boolean;
+  abilities: Ability[];
+  dependsOn: DependsOnRef[];
+  triggers: TriggerSpec[];
+  comment?: string;
+  private: boolean;
+  fields?: Record<string, FieldBuilder>;
+  as: string;
+}
+
+export function defineView(name: string, def: ViewDefinition): ViewDescriptor {
+  rejectHoles(`view '${name}'`, 'dependsOn', def.dependsOn);
+  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).`,
+    );
+  }
+  validateRelationAbilities('view', name, def.abilities ?? []);
+  validatePrivateContradiction('view', name, def.private, def.abilities);
+  validateRelationFields('view', name, def.fields, def.private);
+  validateTriggersFor('view', name, def.triggers ?? []);
+  return {
+    kind: 'view',
+    name,
+    securityInvoker: def.securityInvoker,
+    abilities: def.abilities ?? [],
+    dependsOn: def.dependsOn ?? [],
+    triggers: def.triggers ?? [],
+    ...(def.comment ? { comment: def.comment } : {}),
+    private: def.private ?? false,
+    ...(def.fields ? { fields: def.fields } : {}),
+    as: def.as.sql,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Materialized views — grants-only authz; refresh/populate declare the HOW
+// ---------------------------------------------------------------------------
+
+export interface MaterializedViewDefinition {
+  abilities?: Ability[];
+  dependsOn?: DependsOnRef[];
+  indexes?: IndexBuilder[];
+  /** `'concurrently'` — compile-gated on a declared unique, non-partial index (PG requires it). */
+  refresh?: 'concurrently';
+  /** `'deferred'` — create WITH NO DATA, refresh outside the creation lock. */
+  populate?: 'deferred';
+  comment?: string;
+  private?: boolean;
+  /** The declared output shape — see {@link ViewDefinition.fields}. */
+  fields?: Record<string, FieldBuilder>;
+  as: RawSql;
+}
+
+export interface MaterializedViewDescriptor {
+  kind: 'materialized view';
+  name: string;
+  abilities: Ability[];
+  dependsOn: DependsOnRef[];
+  indexes: IndexBuilder[];
+  refresh?: 'concurrently';
+  populate?: 'deferred';
+  comment?: string;
+  private: boolean;
+  fields?: Record<string, FieldBuilder>;
+  as: string;
+}
+
+export function defineMaterializedView(name: string, def: MaterializedViewDefinition): MaterializedViewDescriptor {
+  rejectHoles(`materialized view '${name}'`, 'dependsOn', def.dependsOn);
+  validateRelationAbilities('materialized view', name, def.abilities ?? []);
+  validatePrivateContradiction('materialized view', name, def.private, def.abilities);
+  validateRelationFields('materialized view', name, def.fields, def.private);
+  const indexes = def.indexes ?? [];
+  if (def.refresh === 'concurrently' && !indexes.some((ix) => ix.isUnique && !ix.predicate)) {
+    throw new Error(
+      `materialized view '${name}': REFRESH CONCURRENTLY requires a unique, non-partial index — declare indexes: [index('...').unique()].`,
+    );
+  }
+  return {
+    kind: 'materialized view',
+    name,
+    abilities: def.abilities ?? [],
+    dependsOn: def.dependsOn ?? [],
+    indexes,
+    ...(def.refresh ? { refresh: def.refresh } : {}),
+    ...(def.populate ? { populate: def.populate } : {}),
+    ...(def.comment ? { comment: def.comment } : {}),
+    private: def.private ?? false,
+    ...(def.fields ? { fields: def.fields } : {}),
+    as: def.as.sql,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Sequences — STATE, not compute (a sequence holds a counter value)
+// ---------------------------------------------------------------------------
+
+export interface SequenceDefinition {
+  as?: 'integer' | 'bigint';
+  start?: number;
+  increment?: number;
+}
+
+export interface SequenceDescriptor {
+  kind: 'sequence';
+  name: string;
+  as: 'integer' | 'bigint';
+  start?: number;
+  increment?: number;
+}
+
+/**
+ * A standalone sequence — one not owned by any serial column (those stay implicit).
+ * Declared on the module (`defineModule({ sequences })`), compiled into the MIGRATION
+ * stream before tables, fingerprinted with the base schema — the `extensions`
+ * precedent. This is what a `field.defaultSql(sql\`nextval('...')\`)` draws from when
+ * the sequence has no serial owner.
+ */
+export function defineSequence(name: string, def: SequenceDefinition = {}): SequenceDescriptor {
+  return {
+    kind: 'sequence',
+    name,
+    as: def.as ?? 'bigint',
+    ...(def.start != null ? { start: def.start } : {}),
+    ...(def.increment != null ? { increment: def.increment } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The escape hatch — declared, hashed, ordered, and gate-tight
+// ---------------------------------------------------------------------------
+
+/** Kinds whose DROP is derivable from the name alone (`DROP <KIND> IF EXISTS <name>`). */
+export const SIMPLE_DROP_KINDS = new Set(['domain', 'collation', 'event trigger']);
+
+const CREATES_RELATION_RE = /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?(MATERIALIZED\s+VIEW|VIEW)\b/i;
+
+export interface SqlDefinition {
+  /** The PostgreSQL object kind (`'aggregate'`, `'domain'`, `'statement'`, …). REQUIRED. */
+  kind: string;
+  dependsOn?: DependsOnRef[];
+  as: RawSql;
+  /** REQUIRED unless the kind's DROP is derivable from the name ({@link SIMPLE_DROP_KINDS}). */
+  drop?: RawSql;
+}
+
+export interface SqlDescriptor {
+  kind: 'sql';
+  /** The declared PostgreSQL object kind (the descriptor discriminant stays 'sql'). */
+  objectKind: string;
+  name: string;
+  dependsOn: DependsOnRef[];
+  as: string;
+  drop?: string;
+}
+
+/**
+ * The generic declared object — for anything the structured vocabulary doesn't cover
+ * yet (aggregates, operators, event triggers). Still declared, content-hashed, and
+ * dependency-ordered like everything else. The relation refusal below is a guard
+ * against the ACCIDENTAL `CREATE VIEW` landing in the escape hatch — it is not an
+ * analyzer, and determined SQL has other ways to create readable state. Authored SQL
+ * here is trusted (the same boundary as a raw db/sql file before it), and the B2/B4
+ * gates skip 'sql'-kind objects: what this hatch declares is on its author.
+ */
+export function defineSql(name: string, def: SqlDefinition): SqlDescriptor {
+  rejectHoles(`sql '${name}'`, 'dependsOn', def.dependsOn);
+  if (!def.kind || !def.kind.trim()) {
+    throw new Error(`defineSql '${name}': kind is required — the reconciler drops and joins objects by kind.`);
+  }
+  const m = def.as.sql.match(CREATES_RELATION_RE);
+  if (m) {
+    const suggested = /MATERIALIZED/i.test(m[1]) ? 'defineMaterializedView' : 'defineView';
+    throw new Error(
+      `defineSql '${name}': the escape hatch cannot create a ${m[1].toLowerCase()} — relations carry the read model. Use ${suggested}.`,
+    );
+  }
+  if (!def.drop && !SIMPLE_DROP_KINDS.has(def.kind.trim().toLowerCase())) {
+    throw new Error(
+      `defineSql '${name}': kind '${def.kind}' has no derivable DROP — declare drop: sql\`DROP ...\` so the reconciler can remove what it created.`,
+    );
+  }
+  return {
+    kind: 'sql',
+    objectKind: def.kind.trim().toLowerCase(),
+    name,
+    dependsOn: def.dependsOn ?? [],
+    as: def.as.sql,
+    ...(def.drop ? { drop: def.drop.sql } : {}),
+  };
+}
+
+/** Everything the derived (compute) stream carries — sequences are state and NOT here. */
+export type DerivedDescriptor = ViewDescriptor | MaterializedViewDescriptor | FunctionDescriptor | SqlDescriptor;

package/src/drizzle.ts

@@ -138,6 +138,7 @@ export function toDrizzleTable(model: ModelDescriptor): PgTableWithColumns<any>
     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);
+    else if (spec.defaultKind === 'sql') col = col.default(sql.raw(String(spec.default)));
 
     // Single-column PK lives on the column; composite PKs are emitted table-level below.
     if (spec.isPrimaryKey && !isComposite) col = col.primaryKey();

package/src/field.ts

@@ -11,6 +11,8 @@
  * See docs/plans/v3-model-api.md.
  */
 
+import type { RawSql } from './raw-sql';
+
 export type FieldType =
   | 'text'
   | 'uuid'
@@ -29,7 +31,7 @@ export type FieldType =
   | 'jsonb'
   | 'enum';
 
-export type DefaultKind = 'value' | 'now' | 'random';
+export type DefaultKind = 'value' | 'now' | 'random' | 'sql';
 
 /** A foreign-key referential action (`ON DELETE` / `ON UPDATE`). `'no action'` is the default. */
 export type ReferentialAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
@@ -188,6 +190,20 @@ export class FieldBuilder {
     return this;
   }
 
+  /**
+   * A raw SQL default — the escape hatch for expressions no builder maps: a
+   * foreign/shared sequence (`nextval('contracts_id_seq')`), an interval
+   * arithmetic (`now() + interval '7 days'`). Stored verbatim behind the
+   * `sql\`\`` brand — the same author-controlled trust boundary as `check()`.
+   * A `nextval` default here is never the `serial` shorthand: serial would
+   * mint a NEW sequence; this declares a draw from an existing one.
+   */
+  defaultSql(expression: RawSql): this {
+    this.spec.default = expression.sql;
+    this.spec.defaultKind = 'sql';
+    return this;
+  }
+
   /** Attach a Zod schema. Stored now, compiled to CHECK + runtime validation in Phase 4. */
   validate(schema: unknown): this {
     this.spec.validation = schema;

package/src/index.ts

@@ -25,8 +25,19 @@ export type { Relation } from './relations';
 export { defineModel } from './model';
 export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy } from './model';
 
-export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql } from './module';
+export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived } from './module';
 export type { Module, ModuleDefinition } from './module';
 
+export {
+  defineView, defineMaterializedView, defineFunction, defineSql, defineSequence,
+  trigger, arg, setof, validateTriggersFor, SIMPLE_DROP_KINDS,
+} from './derived';
+export type {
+  DerivedDescriptor, ViewDescriptor, MaterializedViewDescriptor, FunctionDescriptor,
+  SqlDescriptor, SequenceDescriptor, TriggerSpec, TriggerDefinition, TriggerTiming,
+  TriggerEvent, ArgSpec, SetofReturn, DependsOnRef, ViewDefinition,
+  MaterializedViewDefinition, FunctionDefinition, SqlDefinition, SequenceDefinition,
+} from './derived';
+
 export { deriveHandlerConfig, deriveForceRlsCarveouts, deriveFunctionSchemas } from './derive';
 export type { DerivedHandlerConfig, RelationConfig } from './derive';

package/src/model.ts

@@ -15,6 +15,7 @@ import type { FieldBuilder } from './field';
 import type { Ability } from './can';
 import type { Relation } from './relations';
 import type { TableConstraint } from './constraints';
+import { validateTriggersFor, type TriggerSpec } from './derived';
 
 /**
  * Per-table mutation hooks. Imperative function bodies the framework cannot
@@ -80,6 +81,14 @@ export interface ModelDefinition {
    * just not exposed. Named `private` to avoid colliding with `schema: 'public'`.
    */
   private?: boolean;
+  /**
+   * Triggers on this table — declared HERE because a trigger is existentially bound
+   * to its table and the table's owner must see what runs on every write (owner
+   * consent, visible in the model). Lifecycle note: declaration home ≠ lifecycle —
+   * triggers are COMPUTE, compiled into the derived stream (db:reconcile), never
+   * migrations; the base-schema fingerprint excludes this key.
+   */
+  triggers?: TriggerSpec[];
 }
 
 export interface ModelDescriptor {
@@ -101,6 +110,8 @@ export interface ModelDescriptor {
   private: boolean;
   /** One-shot rename hint: this table used to be named `renamedFrom` (same schema). */
   renamedFrom?: string;
+  /** Triggers on this table (compute — reconciled, never migrated; excluded from the base fingerprint). */
+  triggers: TriggerSpec[];
 }
 
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
@@ -108,6 +119,13 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     .filter(([, f]) => f.spec.isPrimaryKey)
     .map(([name]) => name);
 
+  for (const a of def.abilities ?? []) {
+    if (a.action === 'execute') {
+      throw new Error(`model '${table}': can('execute') is a function ability — declare it on the defineFunction it gates.`);
+    }
+  }
+  validateTriggersFor('table', table, def.triggers ?? []);
+
   return {
     table,
     fields: def.fields,
@@ -120,5 +138,6 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     schema: def.schema ?? 'public',
     private: def.private ?? false,
     ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),
+    triggers: def.triggers ?? [],
   };
 }

package/src/module.ts

@@ -20,16 +20,34 @@
  */
 
 import type { ModelDescriptor } from './model';
+import type { DerivedDescriptor, SequenceDescriptor } from './derived';
+import { rejectHoles } from './derived';
 
 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[];
+  /**
+   * Standalone sequences (not owned by any serial column) — STATE, compiled into the
+   * migration stream before tables and fingerprinted with the base schema (the
+   * `extensions` precedent). What a `field.defaultSql(sql\`nextval('…')\`)` draws from
+   * when no serial column owns the sequence.
+   */
+  sequences?: SequenceDescriptor[];
+  /**
+   * The module's derived (compute) objects — views, materialized views, functions, and
+   * `defineSql` escape-hatch objects. Declared, content-hashed, dependency-ordered;
+   * deployed by `db:reconcile`, never migrated. Supersedes the `functions` thunk.
+   */
+  derived?: DerivedDescriptor[];
   /**
    * 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.
+   *
+   * @deprecated Transitional — declare `derived: [defineFunction(…), …]` instead:
+   * descriptors are hashed, ordered, and gate-checked; the thunk sees none of that.
    */
   functions?: () => string;
 }
@@ -38,15 +56,39 @@ export interface ModuleDefinition {
 export interface Module {
   models: ModelDescriptor[];
   extensions: string[];
+  /** Standalone sequences — state layer (migrated, fingerprinted). */
+  sequences: SequenceDescriptor[];
+  /** Derived (compute) objects — reconciled, never migrated. */
+  derived: DerivedDescriptor[];
   /** 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 {
+  // The loud undefined gate — a missing import composes as a hole; name it here,
+  // at the module boundary, before any list is flattened or iterated.
+  rejectHoles('defineModule', 'models', def.models);
+  rejectHoles('defineModule', 'derived', def.derived);
+  rejectHoles('defineModule', 'sequences', def.sequences);
+  // Derived identity is one name per kind: `DROP FUNCTION` renders no argument list, so
+  // v1 rejects function overloads outright, and same-name relations collide in the
+  // catalog anyway — caught here, at composition, before any SQL exists.
+  const seen = new Set<string>();
+  for (const d of def.derived ?? []) {
+    const identity = `${d.kind === 'sql' ? d.objectKind : d.kind}:${d.name}`;
+    if (seen.has(identity)) {
+      throw new Error(
+        `defineModule: two derived declarations of '${d.name}' (${identity}) — one ${d.kind} per name (function overloads are v1-rejected; rename, or collapse to one signature with arg defaults).`,
+      );
+    }
+    seen.add(identity);
+  }
   return {
     models: def.models ?? [],
     extensions: def.extensions ?? [],
+    sequences: def.sequences ?? [],
+    derived: def.derived ?? [],
     functions: def.functions ? [def.functions] : [],
   };
 }
@@ -66,3 +108,13 @@ export function moduleExtensions(modules: Module[]): string[] {
 export function moduleFunctionSql(modules: Module[]): string[] {
   return modules.flatMap((m) => m.functions).map((fn) => fn());
 }
+
+/** The flattened standalone-sequence list across modules — the state-layer pre-table phase. */
+export function moduleSequences(modules: Module[]): SequenceDescriptor[] {
+  return modules.flatMap((m) => m.sequences);
+}
+
+/** The flattened derived-object list across modules — what the reconcile compiler consumes. */
+export function moduleDerived(modules: Module[]): DerivedDescriptor[] {
+  return modules.flatMap((m) => m.derived);
+}