@everystack/model 0.4.22 → 0.4.24

package/src/dependents.ts

@@ -0,0 +1,236 @@
+/**
+ * hasMany `dependent` → the ON DELETE of the CHILD's foreign key.
+ *
+ * `hasMany(() => Comment, 'postId', { dependent: 'nullify' })` on posts says: deleting a post sets
+ * comments.post_id to NULL. The foreign key that does it belongs to comments, so the compiler
+ * gives the child's FK on `postId` the action `set null`, and a plan shows it as an ordinary FK
+ * change.
+ *
+ * The result is a property of the MODEL SET, never of a field spec. `relationDeleteActions(models)`
+ * is a pure function: it returns a map keyed by (child model, field key) and writes nothing. Every
+ * FK reader that holds the set consults it. A field builder shared by two children, or a child
+ * reused in two sets with different parents, therefore compiles per (set, child), and compiling
+ * one set never changes what another compiles to.
+ *
+ * Ratified rules (F7):
+ *  - 'restrict' → 'restrict', 'nullify' → 'set null', 'cascade' → 'cascade'.
+ *  - Lifecycle (P1.2): a lifecycle parent's 'cascade' needs a lifecycle child and compiles to
+ *    'restrict' (the soft-delete cascade runs in triggers). Any other cascade into a lifecycle
+ *    table is refused, and so is a lifecycle parent's 'cascade' or 'restrict' onto a plain child.
+ *  - Neither side wins. Both may declare; agreeing is fine, disagreeing is an error naming both.
+ *  - Matched on (target, column): a child's other FKs to the same parent are untouched.
+ *  - 'nullify' on a NOT NULL child column is an error (the delete would fail).
+ *  - The child must declare `.references()` to this model. A dependent never creates a foreign
+ *    key: the child file must show its own constraint.
+ *
+ * linkModels runs the same checks at load. With no dependent in the set the map is empty and no
+ * thunk is called.
+ */
+
+import type { ReferentialAction } from './field';
+import type { ModelDescriptor } from './model';
+import type { HasManyDependent, Relation } from './relations';
+
+const ACTION: Record<HasManyDependent, ReferentialAction> = { restrict: 'restrict', nullify: 'set null', cascade: 'cascade' };
+
+/** The derived ON DELETE per child model, per field key. Empty when the set declares no dependent. */
+export type DependentActions = ReadonlyMap<ModelDescriptor, ReadonlyMap<string, ReferentialAction>>;
+
+const nameOf = (m: ModelDescriptor): string => (!m.schema || m.schema === 'public' ? m.table : `${m.schema}.${m.table}`);
+
+/**
+ * Why an ON DELETE CASCADE into a lifecycle table is refused, and the fix. One text for every
+ * declaration site (a parent's hasMany, the child's own onDelete), so the reason cannot drift.
+ */
+export function lifecycleCascadeHarm(where: string): string {
+  return (
+    `ON DELETE CASCADE into a lifecycle table is refused. The cascaded delete is turned into a soft delete, `
+    + `so the parent row is removed and ${where} still points at it. `
+    + `Use 'restrict' or 'nullify' (onDelete 'restrict' or 'set null') instead; `
+    + `to soft-delete the children with their parent, make the parent lifecycle: true and declare hasMany { dependent: 'cascade' } on it`
+  );
+}
+
+/**
+ * A lifecycle parent's hasMany with both a `dependent` and `where`: `where` is display only and never
+ * narrows what a delete does, so the pair reads as a filtered cascade or restrict that does not
+ * exist. Refused on a lifecycle parent; a plain parent keeps accepting it (declarations predate this).
+ */
+export function dependentWhereRefusal(parent: string, relation: string, rel: { dependent?: unknown; where?: unknown }): string | undefined {
+  if (rel.dependent === undefined || rel.where === undefined) return undefined;
+  return `model '${parent}': relation '${relation}' declares dependent '${String(rel.dependent)}' with where: where is display only and never narrows a dependent. `
+    + 'Use an unfiltered dependent and a separate display relation, or drop where.';
+}
+
+/**
+ * Validate every dependent in the set and return the actions it implies. Pure: nothing is written.
+ * `targetOf` resolves a thunk; linkModels passes one that knows the names it has resolved but not
+ * yet bound, so an error leaves nothing half-linked.
+ */
+export function relationDeleteActions(
+  models: readonly ModelDescriptor[],
+  targetOf: (thunk: () => unknown) => ModelDescriptor = (thunk) => thunk() as ModelDescriptor,
+): DependentActions {
+  // Keyed by (child, field key); `site`/`dependent` name the relation for a later disagreement.
+  const planned = new Map<ModelDescriptor, Map<string, { onDelete: ReferentialAction; site: string; dependent: string }>>();
+  for (const parent of new Set(models)) {
+    for (const [name, rel] of Object.entries(parent.relations) as Array<[string, Relation]>) {
+      if (rel.dependent === undefined) continue;
+      const dependent = rel.dependent;
+      const site = `model '${nameOf(parent)}': relation '${name}'`;
+      const at = `${site} declares dependent '${dependent}'`;
+      if (rel.kind !== 'hasMany' || !Object.hasOwn(ACTION, dependent)) {
+        // defineModel refuses these shapes; a hand-edited descriptor still never compiles.
+        throw new Error(`${at}, which is not a hasMany 'restrict', 'nullify' or 'cascade'`);
+      }
+      const filtered = parent.lifecycle ? dependentWhereRefusal(nameOf(parent), name, rel) : undefined;
+      if (filtered) throw new Error(filtered);
+      const child = targetOf(rel.target);
+      const where = `${nameOf(child)}.${rel.column}`;
+      const f = child.fields[rel.column];
+      if (!f) throw new Error(`${at}, but model '${nameOf(child)}' has no field '${rel.column}'`);
+      const spec = f.spec;
+
+      if (!spec.references) {
+        if (spec.referencesExternal) {
+          const ext = spec.referencesExternal;
+          throw new Error(
+            `${at}, but ${where} references '${ext.schema}.${ext.table}', not '${nameOf(parent)}': `
+            + `declare .references() on ${where} to this model (dependent never creates a foreign key)`,
+          );
+        }
+        const covering = child.constraints.find((c) => c.kind === 'foreignKey' && c.columns.includes(rel.column));
+        if (covering && covering.kind === 'foreignKey') {
+          throw new Error(
+            `${at}, but ${where} is covered by a table-level foreignKey(${covering.columns.join(', ')}): `
+            + 'dependent applies only to a field .references(); declare onDelete on that foreignKey(...) instead',
+          );
+        }
+        throw new Error(
+          `${at}, but ${where} has no foreign key to '${nameOf(parent)}': `
+          + `declare .references() on ${where} (dependent never creates a foreign key)`,
+        );
+      }
+      const referenced = targetOf(spec.references);
+      if (referenced !== parent) {
+        throw new Error(
+          `${at}, but ${where} references '${nameOf(referenced)}', not '${nameOf(parent)}': `
+          + `declare .references() on ${where} to this model (dependent never creates a foreign key)`,
+        );
+      }
+      const pk = parent.primaryKey[0] ?? 'id';
+      if (rel.references !== undefined && rel.references !== pk) {
+        throw new Error(
+          `${at} with references '${rel.references}', but ${where}'s foreign key points at the primary key '${pk}': `
+          + 'dependent needs the relation to join on that key',
+        );
+      }
+      if (dependent === 'nullify' && spec.isNotNull) {
+        throw new Error(
+          `${at}, but ${where} is NOT NULL: ON DELETE SET NULL would fail on every delete; `
+          + "make the field nullable or use dependent 'restrict'",
+        );
+      }
+
+      if (dependent === 'cascade' && child.lifecycle && !parent.lifecycle) {
+        throw new Error(`${at}, but ${where} is in a lifecycle table: ${lifecycleCascadeHarm(where)}`);
+      }
+      if (dependent === 'cascade' && parent.lifecycle && !child.lifecycle) {
+        throw new Error(
+          `${at}, but ${where} is not in a lifecycle table. Deleting a lifecycle row is a soft delete, so the parent `
+          + `row stays and its foreign key never fires: ${where} would stay live under a deleted parent. `
+          + `Make '${nameOf(child)}' lifecycle: true (its rows are then soft-deleted with the parent), `
+          + `or use dependent 'restrict' or 'nullify'`,
+        );
+      }
+
+      if (dependent === 'restrict' && parent.lifecycle && !child.lifecycle) {
+        throw new Error(
+          `${at}, but ${where} is not in a lifecycle table. Deleting a lifecycle row is a soft delete, so the foreign key `
+          + `never fires; the restrict check runs in a trigger as the lifecycle role, which holds no rights on a plain table. `
+          + `Make '${nameOf(child)}' lifecycle: true, or use dependent 'nullify'`,
+        );
+      }
+
+      // A lifecycle parent soft-deletes its lifecycle 'cascade' children through triggers
+      // (lifecycle-derived.ts), never through the foreign key: its DELETE never removes the row,
+      // and an RI cascade into a lifecycle table would leave the child pointing at a removed
+      // parent once one is purged. So that foreign key is RESTRICT; the relation keeps 'cascade'.
+      const onDelete: ReferentialAction = dependent === 'cascade' && parent.lifecycle ? 'restrict' : ACTION[dependent];
+      const forChild = planned.get(child) ?? new Map();
+      const earlier = forChild.get(rel.column);
+      if (earlier && earlier.onDelete !== onDelete) {
+        throw new Error(
+          `${at} (ON DELETE ${onDelete.toUpperCase()}), but ${earlier.site} declares dependent '${earlier.dependent}' `
+          + `for the same foreign key ${where}: they disagree`,
+        );
+      }
+      if (spec.onDelete !== undefined && spec.onDelete !== onDelete) {
+        throw new Error(
+          `${at} (ON DELETE ${onDelete.toUpperCase()}), but model '${nameOf(child)}': field '${rel.column}' `
+          + `declares onDelete '${spec.onDelete}': they disagree; declare one, or make them agree`,
+        );
+      }
+      if (!earlier) forChild.set(rel.column, { onDelete, site, dependent });
+      planned.set(child, forChild);
+    }
+  }
+  const out = new Map<ModelDescriptor, ReadonlyMap<string, ReferentialAction>>();
+  for (const [child, fields] of planned) out.set(child, new Map([...fields].map(([k, v]) => [k, v.onDelete])));
+  return out;
+}
+
+/**
+ * The child FK columns a lifecycle parent's dependents need indexed, per child model. A property
+ * of the MODEL SET like {@link relationDeleteActions}: pure, nothing written, every reader that
+ * compiles indexes from the set consults it.
+ *
+ * Why: the cascade trigger on a middle table runs one UPDATE on the child per stamped row, the
+ * restrict check counts the child by the FK, and purge's ON DELETE SET NULL ('nullify') runs
+ * PostgreSQL's referential action by the FK, once per removed parent. Without an index each is a
+ * full scan of the child (measured: a 100k-child delete 15.5 s without, 1.4 s with; a 1,000-parent
+ * purge over 600k SET NULL children 21.4 s without, 0.6 s with).
+ *
+ * Rules: only a LIFECYCLE parent's hasMany with a dependent; field keys, one column (a dependent
+ * rides a field `.references()`, never a composite foreignKey); skipped when the child already has
+ * a btree index, unique or primary key whose LEADING column is that one (a partial, hash or
+ * expression index does not serve every row); one entry per column however many edges share it;
+ * column lists sorted for a stable result.
+ */
+export type DependentIndexes = ReadonlyMap<ModelDescriptor, ReadonlyArray<readonly string[]>>;
+
+const leads = (columns: readonly string[], fk: readonly string[]): boolean =>
+  fk.length > 0 && fk.every((c, i) => columns[i] === c);
+
+function servedBy(child: ModelDescriptor, fk: readonly string[]): boolean {
+  if (leads(child.primaryKey, fk)) return true;
+  if (fk.length === 1 && child.fields[fk[0]]?.spec.isUnique) return true;
+  return child.constraints.some((c) => {
+    if (c.kind === 'unique') return leads(c.columns, fk);
+    if (c.kind !== 'index') return false;
+    if (c.predicate !== undefined || (c.method !== undefined && c.method !== 'btree')) return false;
+    if (fk.some((_, i) => c.rawPositions?.[i])) return false;
+    return leads(c.columns, fk);
+  });
+}
+
+export function lifecycleDependentIndexes(
+  models: readonly ModelDescriptor[],
+  targetOf: (thunk: () => unknown) => ModelDescriptor = (thunk) => thunk() as ModelDescriptor,
+): DependentIndexes {
+  const out = new Map<ModelDescriptor, string[][]>();
+  for (const parent of new Set(models)) {
+    if (parent.lifecycle !== true) continue;
+    for (const rel of Object.values(parent.relations) as Relation[]) {
+      if (rel.kind !== 'hasMany' || rel.dependent === undefined) continue;
+      const child = targetOf(rel.target);
+      const fk = [rel.column];
+      if (servedBy(child, fk)) continue;
+      const list = out.get(child) ?? [];
+      if (!list.some((l) => l.join('\u0000') === fk.join('\u0000'))) list.push(fk);
+      out.set(child, list);
+    }
+  }
+  for (const list of out.values()) list.sort((a, b) => a.join('\u0000').localeCompare(b.join('\u0000')));
+  return out;
+}

package/src/derive.ts

@@ -23,15 +23,24 @@ export interface RelationConfig {
   from: string;
   to: string;
   many?: boolean;
+  /** To-one from the parent side: the first target row in `orderBy` order, or null. */
+  hasOne?: true;
+  orderBy?: Array<{ column: string; order: 'asc' | 'desc' }>;
+  limit?: number;
+  where?: Record<string, string | number | boolean | null>;
 }
 
 export interface DerivedHandlerConfig {
   exposedTables: string[];
   hiddenColumns: Record<string, string[]>;
+  /** Plain manage roles that may read lifecycle metadata; private fields stay hidden. */
+  hiddenColumnsExceptRoles?: Record<string, string[]>;
   protectedFields: Record<string, string[]>;
   /** `exceptRoles` is present only when a `can('manage', { role })` exists for the table. */
   rowOwnership: Record<string, { column: string; userField: string; exceptRoles?: string[] }>;
-  softDelete: { tables: string[] };
+  /** `lifecycle` (present only when a lifecycle model exists) lists the `lifecycle: true` tables;
+   *  each is also in `tables`, so the read filter applies to it. */
+  softDelete: { tables: string[]; lifecycle?: string[] };
   relations: Record<string, Record<string, RelationConfig>>;
   hooks: Record<string, ModelHooks>;
 }
@@ -50,9 +59,11 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
   linkModels(models);
   const exposedTables: string[] = [];
   const hiddenColumns: Record<string, string[]> = {};
+  const hiddenColumnsExceptRoles: Record<string, string[]> = {};
   const protectedFields: Record<string, string[]> = {};
   const rowOwnership: DerivedHandlerConfig['rowOwnership'] = {};
   const softDeleteTables: string[] = [];
+  const lifecycleTables: string[] = [];
   const relations: Record<string, Record<string, RelationConfig>> = {};
   const hooks: Record<string, ModelHooks> = {};
 
@@ -79,6 +90,13 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
     // The first owner-shaped ability → the handler's rowOwnership IDOR backstop.
     // (RLS, compiled from the same ability in Phase 1, is the primary enforcement;
     // this is the HTTP-path guard. A model's owner abilities share one column.)
+    const exceptRoles = [
+      ...new Set(
+        model.abilities
+          .filter((a) => a.action === 'manage' && isPlainRole(a.condition))
+          .map((a) => a.condition.role as string),
+      ),
+    ];
     const ownerAbility = model.abilities.find((a) => a.condition.owner);
     if (ownerAbility) {
       rowOwnership[table] = {
@@ -90,19 +108,20 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       // counts: a role-scoped update or delete alone does not lift it, and neither does a
       // manage ability with any other condition, which narrows what RLS lets it write
       // (fail closed: a whitelist of `role`, not a blacklist of the rest).
-      const exceptRoles = [
-        ...new Set(
-          model.abilities
-            .filter((a) => a.action === 'manage' && isPlainRole(a.condition))
-            .map((a) => a.condition.role as string),
-        ),
-      ];
       if (exceptRoles.length) rowOwnership[table].exceptRoles = exceptRoles;
     }
 
     // Declared, not inferred — one `softDelete` decision drives both the API filter and the
     // RLS guard, so the two can never disagree about what a soft-deleted row is.
     if (model.softDelete) softDeleteTables.push(table);
+    // A lifecycle table soft-deletes in the database (its delete trigger); the handler reads it as
+    // a soft-delete table and drives that machinery instead of writing deleted_at itself.
+    if (model.lifecycle) {
+      softDeleteTables.push(table);
+      lifecycleTables.push(table);
+      hiddenColumns[table] = [...new Set([...(hiddenColumns[table] ?? []), 'deletedBy', 'deletedBatch', 'deletedXid'])];
+      hiddenColumnsExceptRoles[table] = exceptRoles;
+    }
 
     if (model.hooks) hooks[table] = model.hooks;
 
@@ -112,7 +131,18 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       for (const name of relationNames) {
         const rel = model.relations[name];
         const target = rel.target();
-        if (rel.kind === 'belongsTo') {
+        if (rel.kind === 'hasOne') {
+          // this.<pk> → target.<column>, one row. linkModels normalized the orderBy: it always
+          // ends with the target's key, so the handler chooses the same row every time.
+          resolved[name] = {
+            table: target.table,
+            from: rel.references ?? primaryKeyOf(model),
+            to: rel.column,
+            hasOne: true,
+            orderBy: (rel.orderBy ?? []).map((t) => ({ column: t.field, order: t.order })),
+          };
+          if (rel.where) resolved[name].where = { ...rel.where };
+        } else if (rel.kind === 'belongsTo') {
           // this.<column> → target.<pk>
           resolved[name] = {
             table: target.table,
@@ -127,18 +157,23 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
             to: rel.column,
             many: true,
           };
+          // Model field names are the schema property names the handler resolves.
+          if (rel.orderBy) resolved[name].orderBy = rel.orderBy.map((t) => ({ column: t.field, order: t.order }));
+          if (rel.limit !== undefined) resolved[name].limit = rel.limit;
+          if (rel.where) resolved[name].where = { ...rel.where };
         }
       }
-      relations[table] = resolved;
+      if (Object.keys(resolved).length) relations[table] = resolved;
     }
   }
 
   return {
     exposedTables,
     hiddenColumns,
+    ...(lifecycleTables.length ? { hiddenColumnsExceptRoles } : {}),
     protectedFields,
     rowOwnership,
-    softDelete: { tables: softDeleteTables },
+    softDelete: { tables: softDeleteTables, ...(lifecycleTables.length ? { lifecycle: lifecycleTables } : {}) },
     relations,
     hooks,
   };

package/src/derived.ts

@@ -88,7 +88,7 @@ function validateRelationFields(kind: string, name: string, fields: Record<strin
     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.references || s.referencesExternal) 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.`);

package/src/drizzle.ts

@@ -170,6 +170,10 @@ export function toDrizzleTable(model: ModelDescriptor): PgTableWithColumns<any>
 
     if (spec.references) {
       const target = spec.references as () => ModelDescriptor;
+      // The CHILD's declared actions only. A parent's hasMany `dependent` is a property of the
+      // model set (relationDeleteActions) and this table is built per model, so it is not here.
+      // The runtime table never emits DDL (the CLI does, from the set), so queries are unaffected.
+      // This is the one place it differs from the generated schema.generated.ts, which carries it.
       const refOpts: { onDelete?: FieldSpec['onDelete']; onUpdate?: FieldSpec['onUpdate'] } = {};
       if (spec.onDelete) refOpts.onDelete = spec.onDelete;
       if (spec.onUpdate) refOpts.onUpdate = spec.onUpdate;

package/src/external.ts

@@ -0,0 +1,119 @@
+/**
+ * An EXTERNAL foreign-key target: a table no model declares, named by its PostgreSQL identity.
+ *
+ * `field.uuid().references({ schema: 'auth', table: 'users', column: 'id' })` is how a model says
+ * "this column points into another system's table" (an auth provider's `auth.users`, a table a
+ * different service owns). Ratified rules:
+ *
+ *  - schema, table and column are all REQUIRED and are three separate identifiers. Nothing is
+ *    parsed for dots: an external FK crosses the governed boundary, so it says exactly where.
+ *  - A string target stays a MODEL name. Only this object form names a table.
+ *  - An object naming a table some model in the set declares is refused: use the model.
+ *  - It is FK state only. It is never a relation (no belongsTo/hasMany, no embedding).
+ *  - It compiles, diffs and fingerprints exactly like a model FK. Nothing downstream of the
+ *    compiler can tell the two apart, so a live FK nothing declares is still visible drift.
+ *
+ * The names are PostgreSQL names, taken verbatim (no snake_casing: there is no model field to
+ * derive them from). They reach DDL quoted, so a name is refused when quoting cannot carry it.
+ */
+
+import type { ModelDescriptor } from './model';
+
+/** A table no model declares: the composite `foreignKey(cols, { schema, table }, refColumns)` target. */
+export interface ExternalTableRef {
+  schema: string;
+  table: string;
+}
+
+/** A column of a table no model declares: the `.references({ schema, table, column })` target. */
+export interface ExternalColumnRef extends ExternalTableRef {
+  column: string;
+}
+
+/** NAMEDATALEN - 1 on a stock PostgreSQL build; a longer name is truncated with only a NOTICE. */
+const MAX_IDENTIFIER_BYTES = 63;
+
+/**
+ * Why a name cannot be an external identifier, or null when it can. The DDL quotes every part
+ * (`"auth"."users"`) without doubling quotes, and the FK IR carries `schema.table` as one dotted
+ * string, so a quote, a dot or a control character cannot be carried safely.
+ */
+export function externalIdentifierRefusal(name: unknown): string | null {
+  if (typeof name !== 'string') return `is ${name === null ? 'null' : typeof name}, not a string`;
+  if (name.length === 0) return 'is empty';
+  if (name.includes('"')) return 'holds a double quote';
+  // A line terminator or other control character: a name holding one could end a comment in
+  // generated source or forge a line in plan output and logs. No real table needs one.
+  if (/[\u0000-\u001f\u007f\u2028\u2029]/.test(name)) return 'holds a control character or line terminator';
+  if (name.includes('.')) return "holds a '.' (a name is one identifier; the schema is its own field)";
+  const bytes = new TextEncoder().encode(name).length;
+  if (bytes > MAX_IDENTIFIER_BYTES) return `is ${bytes} bytes (PostgreSQL identifiers are at most ${MAX_IDENTIFIER_BYTES})`;
+  return null;
+}
+
+/** `auth.users` — how every error and plan line names an external target. */
+export function externalTargetName(ref: ExternalTableRef): string {
+  return `${String(ref.schema)}.${String(ref.table)}`;
+}
+
+function readRef<K extends string>(target: object, keys: readonly K[], call: string): Record<K, string> {
+  const shown = externalTargetName(target as ExternalTableRef);
+  for (const key of Object.keys(target)) {
+    if (!(keys as readonly string[]).includes(key)) {
+      throw new Error(`${call} target ${shown}: unknown key '${key}' (expected ${keys.join(', ')})`);
+    }
+  }
+  const out = {} as Record<K, string>;
+  for (const key of keys) {
+    const value = (target as Record<string, unknown>)[key];
+    if (value === undefined) {
+      throw new Error(`${call} target ${shown}: ${key} is required (an external target names its ${keys.join(', ')}; there is no default)`);
+    }
+    const refusal = externalIdentifierRefusal(value);
+    if (refusal) throw new Error(`${call} target ${shown}: ${key} ${JSON.stringify(value)} ${refusal}`);
+    out[key] = value as string;
+  }
+  return out;
+}
+
+/** Validate and copy a `.references({ schema, table, column })` target. */
+export function externalColumnRef(target: object): ExternalColumnRef {
+  return Object.freeze(readRef(target, ['schema', 'table', 'column'] as const, 'references({ schema, table, column })'));
+}
+
+/** Validate and copy a composite `foreignKey(cols, { schema, table }, refColumns)` target and its columns. */
+export function externalTableRef(target: object, refColumns: readonly string[], call: string): ExternalTableRef {
+  const ref = readRef(target, ['schema', 'table'] as const, call);
+  for (const c of refColumns) {
+    const refusal = externalIdentifierRefusal(c);
+    if (refusal) throw new Error(`${call} target ${externalTargetName(ref)}: reference column ${JSON.stringify(c)} ${refusal}`);
+  }
+  return Object.freeze(ref);
+}
+
+/**
+ * Refuse an external target that a model in this set declares: the author must use the model.
+ * Compared on RESOLVED identities (the model's schema, default `public`, and its table) across
+ * the whole set. Called by linkModels and by every compile entry point that holds the set.
+ */
+export function assertExternalTargets(models: readonly ModelDescriptor[]): void {
+  const declared = new Map<string, ModelDescriptor>();
+  for (const m of models) declared.set(`${m.schema ?? 'public'}\u0000${m.table}`, m);
+  const owner = (m: ModelDescriptor): string => `${m.schema ?? 'public'}.${m.table}`;
+  const check = (m: ModelDescriptor, ref: ExternalTableRef, what: string): void => {
+    const hit = declared.get(`${ref.schema}\u0000${ref.table}`);
+    if (!hit) return;
+    throw new Error(
+      `model '${owner(m)}': ${what} references ${externalTargetName(ref)}, which model '${owner(hit)}' declares: `
+      + `use the model (.references(() => Model) or a model-name string), not the external { schema, table } form`,
+    );
+  };
+  for (const m of models) {
+    for (const [key, f] of Object.entries(m.fields)) {
+      if (f.spec.referencesExternal) check(m, f.spec.referencesExternal, `field '${key}'`);
+    }
+    for (const c of m.constraints) {
+      if (c.kind === 'foreignKey' && c.external) check(m, c.external, `foreignKey(${c.columns.join(', ')})`);
+    }
+  }
+}

package/src/field.ts

@@ -15,6 +15,7 @@ import type { RawSql } from './raw-sql';
 import { pgTypeRefusal } from './pg-type';
 import { assertConstraintName, assertFkValidate } from './constraints';
 import { referenceThunk } from './link';
+import { externalColumnRef, type ExternalColumnRef } from './external';
 
 export type FieldType =
   | 'text'
@@ -80,6 +81,13 @@ export interface FieldSpec {
   isDeprecated: boolean;
   /** `.references(() => Other)` — FK target, a model thunk. Used by relation/ownership work. */
   references?: () => unknown;
+  /**
+   * `.references({ schema, table, column })` — an FK to a table NO model declares (another
+   * system's `auth.users`). Set instead of {@link references}, never with it. FK state only: it is
+   * never a relation, so nothing that follows a model thunk ever sees it. It compiles, diffs and
+   * fingerprints exactly like a model FK. See external.ts.
+   */
+  referencesExternal?: ExternalColumnRef;
   /** `ON DELETE` action for the FK. Omitted (or `'no action'`) is the Postgres default. */
   onDelete?: ReferentialAction;
   /** `ON UPDATE` action for the FK. Omitted (or `'no action'`) is the Postgres default. */
@@ -231,8 +239,12 @@ export class FieldBuilder {
   }
 
   /**
-   * Declare a foreign key. The target is a table name or model thunk. Names are resolved
-   * by linkModels when the complete set is available. Optional
+   * Declare a foreign key. The target is a model thunk or a model NAME (a string is always a
+   * model name, resolved by linkModels when the complete set is available; one that names no
+   * model is an error, never a table). A table no model declares is named as an object:
+   * `.references({ schema: 'auth', table: 'users', column: 'id' })`, all three required, each a
+   * PostgreSQL name taken verbatim. That form is FK state only, never a relation, and is refused
+   * when a model in the set declares the table (use the model). Optional
    * `onDelete`/`onUpdate` referential actions are column-scoped, so they live here, not on
    * the table — `field.uuid().references(() => User, { onDelete: 'cascade' })`.
    *
@@ -242,8 +254,19 @@ export class FieldBuilder {
    * {@link FieldSpec.referencesValidate} for why a fifteen-year-old schema needs to be able
    * to say it.
    */
-  references(target: (() => unknown) | string, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean }): this {
-    this.spec.references = referenceThunk(target);
+  references(target: (() => unknown) | string | ExternalColumnRef, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean }): this {
+    // A second call REPLACES the target, as every other repeated modifier on this builder
+    // overwrites: each branch clears the other slot, so a field never holds both (the compiler
+    // would read one and relations or `via` the other).
+    if (typeof target === 'function' || typeof target === 'string') {
+      this.spec.references = referenceThunk(target);
+      delete this.spec.referencesExternal;
+    } else if (target !== null && typeof target === 'object') {
+      this.spec.referencesExternal = externalColumnRef(target);
+      delete this.spec.references;
+    } else {
+      throw new Error(`references(…): the target is ${target === null ? 'null' : typeof target}; pass a model thunk, a model name, or { schema, table, column }`);
+    }
     if (opts?.onDelete) this.spec.onDelete = opts.onDelete;
     if (opts?.onUpdate) this.spec.onUpdate = opts.onUpdate;
     if (opts?.name !== undefined) this.spec.constraintName = assertConstraintName(opts.name, 'foreign key');

package/src/index.ts

@@ -3,7 +3,7 @@
  * handler config. See docs/plans/v3-model-architecture.md.
  *
  * Ships the declaration surface (`defineModel`, `field`, `can`, `belongsTo`/
- * `hasMany`); `@everystack/cli` compiles models to migrations, RLS + grants, and
+ * `hasMany`/`hasOne`); `@everystack/cli` compiles models to migrations, RLS + grants, and
  * handler config (`deriveHandlerConfig`).
  */
 
@@ -14,6 +14,8 @@ export { canonicalColumnType, fieldFactoryCall, pgTypeRefusal } from './pg-type'
 
 export { parseQualified } from './qualified';
 export { linkModels, ModelLinkError } from './link';
+export { assertExternalTargets, externalTargetName, externalIdentifierRefusal } from './external';
+export type { ExternalTableRef, ExternalColumnRef } from './external';
 
 export { unique, check, index, foreignKey, IndexBuilder, positionalCheckName } from './constraints';
 export type { TableConstraint } from './constraints';
@@ -25,11 +27,14 @@ export { can, isColumnAbility, isPublicReadAbility, isDeleteAbility, needsSoftDe
 export type { SoftDeleteFacts } from './can';
 export type { Ability, AbilityCondition, Action } from './can';
 
-export { belongsTo, hasMany } from './relations';
-export type { Relation } from './relations';
+export { belongsTo, hasMany, hasOne } from './relations';
+export type { Relation, BelongsToOptions, HasManyOptions, HasOneOptions, HasManyDependent, RelationOrder, RelationWhere } from './relations';
+export { relationDeleteActions, lifecycleDependentIndexes } from './dependents';
+export type { DependentActions, DependentIndexes } from './dependents';
 
-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 { veto, isVeto } from './lifecycle-hooks';
+export { defineModel, defineMaterializedTable, LIFECYCLE_COLUMNS, LIFECYCLE_OWNER_ROLE, EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, LifecycleOptions, DestroyContext, DestroyHook, LifecycleContext, HookVeto, BeforeLifecycleHook, AfterLifecycleHook, WrittenBy, ExtraPrivilege, TablePrivilege, DmlPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
 export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
 export type { Module, ModuleDefinition } from './module';

package/src/lifecycle-hooks.ts

@@ -0,0 +1,53 @@
+/**
+ * The lifecycle hook contract, shared by the model, the API handler and purge.
+ * `@everystack/api` carries a structurally identical copy (it has no runtime dependencies);
+ * a veto made by either package is recognized by both.
+ */
+
+const VETO_KIND = 'everystack.hookVeto';
+
+/** What a before hook returns to refuse its operation. Make it with {@link veto}. */
+export interface HookVeto {
+  readonly kind: typeof VETO_KIND;
+  readonly reason: string;
+}
+
+/** Refuse the operation a before hook guards. A throw is a failure; a veto is a decision. */
+export function veto(reason: string): HookVeto {
+  if (typeof reason !== 'string' || reason.trim() === '') throw new TypeError('veto(reason) needs a non-empty reason string');
+  return Object.freeze({ kind: VETO_KIND, reason });
+}
+
+/** True only for a value {@link veto} made (or its twin in `@everystack/api`). */
+export function isVeto(value: unknown): value is HookVeto {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && (value as { kind?: unknown }).kind === VETO_KIND && typeof (value as { reason?: unknown }).reason === 'string';
+}
+
+/** The one context every lifecycle hook receives. */
+export interface LifecycleContext {
+  /** `stamp`: the row was marked deleted. `restore`: a batch came back. `destroy`: physical removal. */
+  phase: 'stamp' | 'restore' | 'destroy';
+  /** `api`: a request through createHandler. `purge`: purgeExpired. */
+  source: 'api' | 'purge';
+  /** The lifecycle batch, or null when there is none to report (before a stamp, a non-lifecycle table, a pre-batch row). Never invented. */
+  batch: string | null;
+  user: Record<string, unknown> | null;
+  client: Record<string, unknown> | null;
+  /** Restore only: what the restore function reported. */
+  counts?: { restored: number; skipped: number };
+}
+
+/** Context for a real removal. Hooks must be idempotent: retries can repeat external effects. */
+export interface DestroyContext extends LifecycleContext {
+  phase: 'destroy';
+}
+
+/** beforeDestroy may return {@link veto}; afterDestroy's return value is ignored. */
+export type DestroyHook = (row: Record<string, unknown>, ctx: DestroyContext) => void | HookVeto | Promise<void | HookVeto>;
+
+/** A before hook of the lifecycle: called once per root row; returns nothing or a veto. */
+export type BeforeLifecycleHook = (row: Record<string, unknown>, ctx: LifecycleContext) => void | HookVeto | Promise<void | HookVeto>;
+
+/** An after hook of the lifecycle: called after commit with the root rows of one batch. Best-effort. */
+export type AfterLifecycleHook = (rows: Record<string, unknown>[], ctx: LifecycleContext) => void | Promise<void>;