@everystack/model 0.4.22 → 0.4.23

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,13 @@ 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 } from './dependents';
+export type { DependentActions } 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 { defineModel, defineMaterializedTable, LIFECYCLE_COLUMNS, LIFECYCLE_OWNER_ROLE, EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, DestroyContext, DestroyHook, 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/link.ts

@@ -1,5 +1,8 @@
 import type { ModelDescriptor } from './model';
 import { parseQualified } from './qualified';
+import { assertExternalTargets } from './external';
+import { relationDeleteActions } from './dependents';
+import { hasDisplayOptions, normalizeRelationDisplay } from './relation-display';
 
 /** A failed or conflicting name binding must never become a usable model. */
 export class ModelLinkError extends Error {
@@ -97,11 +100,14 @@ export function linkModels<T extends readonly ModelDescriptor[]>(models: T): T {
   // Resolve everything before changing descriptors, so a typo can be corrected and retried
   // without leaving earlier references bound to a different, incomplete set.
   const replacements: Array<() => void> = [];
+  // What each name reference resolves to in THIS set, before anything is bound.
+  const resolvedNames = new Map<unknown, ModelDescriptor>();
   for (const model of uniqueModels) {
     for (const [key, field] of Object.entries(model.fields)) {
       const target = field.spec.references;
       if (target && isNameReference(target)) {
         const resolved = resolve(target as NameReference<ModelDescriptor>, model, 'field', key);
+        resolvedNames.set(target, resolved);
         if (target.boundTarget) continue;
         const linked = Object.assign(() => resolved, {
           refName: target.refName, refLocation: target.refLocation, boundTarget: resolved,
@@ -113,6 +119,7 @@ export function linkModels<T extends readonly ModelDescriptor[]>(models: T): T {
       const target = relation.target;
       if (isNameReference(target)) {
         const resolved = resolve(target, model, 'relation', key);
+        resolvedNames.set(target, resolved);
         if (target.boundTarget) continue;
         const linked = Object.assign(() => resolved, {
           refName: target.refName, refLocation: target.refLocation, boundTarget: resolved,
@@ -121,6 +128,39 @@ export function linkModels<T extends readonly ModelDescriptor[]>(models: T): T {
       }
     }
   }
+  // An external `{ schema, table }` target naming a table this set models is refused: the
+  // author must use the model. Checked before anything is bound, like every error above.
+  try {
+    assertExternalTargets(uniqueModels);
+  } catch (err) {
+    throw new ModelLinkError(err instanceof Error ? err.message : String(err));
+  }
+  // hasMany `dependent` → the child FK's ON DELETE: checked here, before anything is bound, and
+  // never written into a spec (the compiler derives it per set). Only a relation that declares a
+  // dependent has its target (or its child's FK target) evaluated.
+  try {
+    relationDeleteActions(uniqueModels, (thunk) => resolvedNames.get(thunk) ?? thunk() as ModelDescriptor);
+  } catch (err) {
+    if (err instanceof ModelLinkError) throw err;
+    throw new ModelLinkError(err instanceof Error ? err.message : String(err));
+  }
+  // Display options (orderBy, where; every hasOne) name TARGET fields: checked here, before
+  // anything is bound, and the orderBy normalized once (the target's primary key appended).
+  // Only such a relation has its target evaluated. Display options never reach a dependent.
+  for (const model of uniqueModels) {
+    for (const [key, relation] of Object.entries(model.relations)) {
+      if (relation.kind === 'belongsTo' || !hasDisplayOptions(relation)) continue;
+      let orderBy: ReturnType<typeof normalizeRelationDisplay>;
+      try {
+        const target = resolvedNames.get(relation.target) ?? relation.target();
+        orderBy = normalizeRelationDisplay(modelName(model), key, relation, target);
+      } catch (err) {
+        if (err instanceof ModelLinkError) throw err;
+        throw new ModelLinkError(err instanceof Error ? err.message : String(err));
+      }
+      if (orderBy) replacements.push(() => { relation.orderBy = orderBy; });
+    }
+  }
   for (const replace of replacements) replace();
   return models;
 }

package/src/model.ts

@@ -11,12 +11,13 @@
  * compiler (`compileTableContract`, what `db:generate` emits as RLS + grants).
  */
 
-import type { FieldBuilder } from './field';
+import { field, type FieldBuilder } from './field';
 import { referenceLocation } from './link';
 import type { Ability } from './can';
-import { isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete, sessionlessAudience } from './can';
-import type { Relation } from './relations';
+import { can, isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete, sessionlessAudience } from './can';
+import { assertRelationShape, type Relation } from './relations';
 import { assertCheckNames, type TableConstraint } from './constraints';
+import { lifecycleCascadeHarm } from './dependents';
 import type { RawSql } from './raw-sql';
 import { validateTriggersFor, type TriggerSpec, type DependsOnRef } from './derived';
 import { TABLE_PRIVILEGES, type TablePrivilege } from './privileges';
@@ -26,6 +27,15 @@ import { TABLE_PRIVILEGES, type TablePrivilege } from './privileges';
  * absorb (purge an S3 object on delete, stamp a column on create) — held
  * verbatim and passed through to the handler's `hooks`.
  */
+/** Context for a real removal. Hooks must be idempotent: retries can repeat external effects. */
+export interface DestroyContext {
+  source: 'purge' | 'api';
+  user: Record<string, unknown> | null;
+  client: Record<string, unknown> | null;
+}
+
+export type DestroyHook = (row: Record<string, unknown>, ctx: DestroyContext) => void | Promise<void>;
+
 export interface ModelHooks {
   beforeCreate?: (...args: any[]) => any;
   afterCreate?: (...args: any[]) => any;
@@ -33,6 +43,13 @@ export interface ModelHooks {
   afterUpdate?: (...args: any[]) => any;
   beforeDelete?: (...args: any[]) => any;
   afterDelete?: (...args: any[]) => any;
+  /** Runs after the DELETE statement, before commit. A throw rolls back only the database
+   * delete, never an external effect. No transaction is passed. Must be idempotent.
+   * Treat the row as read-only: it is the same object later serialized into the response. */
+  beforeDestroy?: DestroyHook;
+  /** Runs after commit, best-effort. Cannot undo the removal. Must be idempotent.
+   * Treat the row as read-only: it is the same object later serialized into the response. */
+  afterDestroy?: DestroyHook;
 }
 
 /**
@@ -115,6 +132,14 @@ export interface ModelDefinition {
    * was always explicit; this matches it. Convention may propose it, never enforce it.
    */
   softDelete?: boolean;
+  /**
+   * `lifecycle: true` — a soft delete with a delay. defineModel generates four nullable columns
+   * ({@link LIFECYCLE_COLUMNS}): `deletedAt` timestamptz, `deletedBy` text (no foreign key),
+   * `deletedBatch` uuid, `deletedXid` bigint. The author never declares them, never combines
+   * lifecycle with `softDelete`, and declares a single-column primary key; each is refused here.
+   * `true` is the only value today.
+   */
+  lifecycle?: true;
   /**
    * The Postgres schema the table lives in. Default `'public'`. Package-owned
    * tables declare their own (`'dist'`, `'ops'`, `'auth'`) so one db:generate run
@@ -195,6 +220,8 @@ export interface ModelDescriptor {
   privileges: Record<string, TablePrivilege[]>;
   /** `true` excludes `deleted_at IS NULL` rows from public reads and the data API. Declared, never inferred. */
   softDelete: boolean;
+  /** Present only when declared: `fields` carries the generated {@link LIFECYCLE_COLUMNS}. */
+  lifecycle?: true;
   /** 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`. */
@@ -227,11 +254,194 @@ export interface MaterializedTableMarker {
   comment?: string;
 }
 
+/** The field keys `lifecycle: true` generates, in the order defineModel appends them. */
+export const LIFECYCLE_COLUMNS = ['deletedAt', 'deletedBy', 'deletedBatch', 'deletedXid'] as const;
+
+/** Both spellings of each generated key: an author declaring either collides with the generated column. */
+const LIFECYCLE_RESERVED = [...LIFECYCLE_COLUMNS, 'deleted_at', 'deleted_by', 'deleted_batch', 'deleted_xid'];
+
+/**
+ * The role a lifecycle model grants to its delete machinery. defineModel appends its abilities
+ * to every `lifecycle: true` model, so no author ability may name it, on any model.
+ */
+export const LIFECYCLE_OWNER_ROLE = 'everystack_lifecycle';
+
+/**
+ * The lifecycle role's abilities: read every row (deleted ones included), update only the four
+ * generated columns, delete. No insert, no manage.
+ */
+function lifecycleAbilities(): Ability[] {
+  const role = LIFECYCLE_OWNER_ROLE;
+  return [
+    can('read', { role }),
+    can('update', { role, columns: [...LIFECYCLE_COLUMNS] }),
+    can('delete', { role }),
+  ];
+}
+
+function assertRoleNotReserved(table: string, def: ModelDefinition): void {
+  // A privileges entry is refused too, even an empty list: TABLE_PRIVILEGES includes TRUNCATE
+  // and TRIGGER, which would let the role bypass RLS or attach triggers beside the guards.
+  if (def.privileges && Object.prototype.hasOwnProperty.call(def.privileges, LIFECYCLE_OWNER_ROLE)) {
+    throw new Error(
+      `model '${table}': privileges['${LIFECYCLE_OWNER_ROLE}'] — the role '${LIFECYCLE_OWNER_ROLE}' is reserved for lifecycle; ` +
+        `the compiler grants it automatically on a lifecycle: true model. Remove the entry.`,
+    );
+  }
+  for (const a of def.abilities ?? []) {
+    if (a.condition.role !== LIFECYCLE_OWNER_ROLE) continue;
+    throw new Error(
+      `model '${table}': can('${a.action}', { role: '${LIFECYCLE_OWNER_ROLE}' }) — the role '${LIFECYCLE_OWNER_ROLE}' ` +
+        `is reserved for lifecycle; the compiler grants it automatically on a lifecycle: true model. Remove the ability.`,
+    );
+  }
+}
+
+/** Fresh builders on every call: a descriptor owns its fields, never shares them with another model. */
+function lifecycleFields(): Record<(typeof LIFECYCLE_COLUMNS)[number], FieldBuilder> {
+  return {
+    deletedAt: field.timestamptz().nullable(),
+    deletedBy: field.text().nullable(),
+    deletedBatch: field.uuid().nullable(),
+    deletedXid: field.bigint().nullable(),
+  };
+}
+
+function assertLifecycle(table: string, def: ModelDefinition): void {
+  const value: unknown = def.lifecycle;
+  if (value === undefined) return;
+  if (value === false) {
+    throw new Error(`model '${table}': lifecycle: false is not supported yet. Omit the key for a model without lifecycle.`);
+  }
+  if (value !== true) {
+    throw new Error(`model '${table}': lifecycle: ${JSON.stringify(value)} — the only value is lifecycle: true.`);
+  }
+  if (def.softDelete !== undefined) {
+    throw new Error(
+      `model '${table}': lifecycle replaces softDelete — delete softDelete: ${String(def.softDelete)}. ` +
+        `lifecycle: true already declares what a delete does.`,
+    );
+  }
+  for (const name of LIFECYCLE_RESERVED) {
+    if (name in def.fields) {
+      throw new Error(
+        `model '${table}': field '${name}' — with lifecycle: true the compiler generates this column; delete the declaration.`,
+      );
+    }
+  }
+  // The lifecycle role's policies and the deleted_at read guard are RLS policies; under disabled
+  // row security they filter nothing while reading as though they do.
+  if (def.rls === false) {
+    throw new Error(
+      `model '${table}': lifecycle: true with rls: false — lifecycle hides deleted rows with RLS policies, ` +
+        `and rls: false declares there are none, so the guard would be dead. Either drop rls: false (lifecycle needs RLS) ` +
+        `or drop lifecycle: true.`,
+    );
+  }
+  // A cascade into this table, declared on this table's own foreign key. A parent's
+  // hasMany { dependent: 'cascade' } is checked in relationDeleteActions (allowed from a
+  // lifecycle parent, where it compiles to RESTRICT and the triggers soft-delete the children).
+  const tableName = def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table;
+  for (const [name, f] of Object.entries(def.fields)) {
+    if (f.spec.onDelete !== 'cascade') continue;
+    throw new Error(`model '${tableName}': field '${name}' declares onDelete 'cascade'. ${lifecycleCascadeHarm(`${tableName}.${name}`)}.`);
+  }
+  for (const c of def.constraints ?? []) {
+    if (c.kind !== 'foreignKey' || c.onDelete !== 'cascade') continue;
+    const where = `${tableName}.${c.columns.join(', ')}`;
+    throw new Error(`model '${tableName}': foreignKey(${c.columns.join(', ')}) declares onDelete 'cascade'. ${lifecycleCascadeHarm(where)}.`);
+  }
+  const pk = Object.entries(def.fields).filter(([, f]) => f.spec.isPrimaryKey).length;
+  if (pk !== 1) {
+    throw new Error(
+      `model '${table}': lifecycle needs a single-column primary key — this model declares ${pk === 0 ? 'none' : `${pk} (composite)`}. ` +
+        `Mark exactly one field .primaryKey().`,
+    );
+  }
+  // The generated trigger and function names are `<table>_lifecycle_transition` and `_guard`.
+  // PostgreSQL silently truncates an identifier past 63 bytes, so the declared name would not be the live one.
+  // UTF-8 bytes, as PostgreSQL counts them. TextEncoder rather than Buffer: a model also loads outside Node.
+  const longest = `${table}_lifecycle_transition`;
+  const bytes = new TextEncoder().encode(longest).length;
+  if (bytes > 63) {
+    throw new Error(
+      `model '${table}': lifecycle generates '${longest}' (${bytes} bytes), past PostgreSQL's 63-byte identifier limit. ` +
+        `A lifecycle table name may be at most 42 bytes; shorten the table name.`,
+    );
+  }
+}
+
+/**
+ * Restore runs the table's delete rule inside a SECURITY DEFINER function as the lifecycle role.
+ * Refuse a delete rule whose meaning would change there: a subquery (`via`, or SELECT in
+ * where/sql) runs with that role's privileges, and current_user/session_user name that role or
+ * the login, not the caller. TRUNCATE is refused because it skips the delete triggers.
+ */
+function assertLifecycleRestoreSafe(table: string, def: ModelDefinition): void {
+  if (def.lifecycle !== true) return;
+  const why = 'restore runs the delete rule inside a SECURITY DEFINER function as the lifecycle owner';
+  const abilities = def.abilities ?? [];
+  // A role-less (or authenticated) delete on a model scoped only through `via` compiles to the
+  // via subquery too, though the ability itself names no via.
+  const viaScopedModel = !abilities.some((a) => a.condition.owner) && abilities.some((a) => a.condition.via);
+  for (const a of abilities) {
+    if (a.action !== 'delete' && a.action !== 'manage') continue;
+    // PUBLIC would get EXECUTE on restore, and a branch with no role behind it: anon restores.
+    if (a.condition.role && a.condition.role.toLowerCase() === 'public') {
+      throw new Error(
+        `model '${table}': can('${a.action}', { role: '${a.condition.role}' }) on a lifecycle: true model — ${why}, and ` +
+          `restore is granted to whoever may delete, so every role, anon included, could restore rows. ` +
+          `Use a named role (authenticated, or one of your own) for the delete rule.`,
+      );
+    }
+    const authClass = !a.condition.role || a.condition.role === 'authenticated';
+    if (a.condition.via || (viaScopedModel && authClass)) {
+      const spelled = a.condition.via ? `can('${a.action}', { via: '${a.condition.via}' })` : `can('${a.action}') on a model scoped by via`;
+      throw new Error(
+        `model '${table}': ${spelled} on a lifecycle: true model — ${why}, where a via ` +
+          `subquery would read the parent with that role's privileges. Use owner, or a role with a plain where, for the delete rule.`,
+      );
+    }
+    for (const key of ['where', 'sql'] as const) {
+      const text = (a.condition[key] as { sql?: unknown } | undefined)?.sql;
+      if (typeof text !== 'string') continue;
+      const offender = /\bselect\b/i.test(text)
+        ? 'a subquery (SELECT)'
+        : /\bcurrent_user\b/i.test(text)
+          ? 'current_user'
+          : /\bsession_user\b/i.test(text)
+            ? 'session_user'
+            : null;
+      if (!offender) continue;
+      throw new Error(
+        `model '${table}': can('${a.action}', { ${key} }) uses ${offender} on a lifecycle: true model — ${why}, ` +
+          `where a subquery runs with that role's privileges and current_user/session_user do not name the caller. ` +
+          `Replace it with a predicate on the row's own columns or the request claims.`,
+      );
+    }
+  }
+  for (const [role, privs] of Object.entries(def.privileges ?? {})) {
+    if (!Array.isArray(privs) || !privs.includes('TRUNCATE')) continue;
+    throw new Error(
+      `model '${table}': privileges['${role}'] grants TRUNCATE on a lifecycle: true model — TRUNCATE skips the delete ` +
+        `triggers, so it would erase rows past the soft delete and restore. Remove TRUNCATE from the entry.`,
+    );
+  }
+}
+
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
+  // Refuse first, then inject: the author-declared collisions are checked against what the author wrote.
+  assertRoleNotReserved(table, def);
+  assertLifecycle(table, def);
+  assertLifecycleRestoreSafe(table, def);
+  const lifecycle = def.lifecycle === true;
+  const fields: Record<string, FieldBuilder> = lifecycle ? { ...def.fields, ...lifecycleFields() } : def.fields;
+
   for (const [name, field] of Object.entries(def.fields)) {
     referenceLocation(field.spec.references, `${table}.${name}`);
   }
   for (const [name, relation] of Object.entries(def.relations ?? {})) {
+    assertRelationShape(def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table, name, relation);
     referenceLocation(relation.target, `${table}.${name}`);
   }
   const primaryKey = Object.entries(def.fields)
@@ -282,6 +492,15 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
       }
     }
 
+    // A generated lifecycle column is not an author field, so no author ability may scope by it.
+    // (A column ability's owner is already refused above against the author's fields.)
+    if (lifecycle && a.condition.owner && LIFECYCLE_RESERVED.includes(a.condition.owner)) {
+      throw new Error(
+        `model '${table}': can('${a.action}', { owner: '${a.condition.owner}' }) names '${a.condition.owner}', but no such field exists ` +
+          `among the model's fields — with lifecycle: true the compiler generates it, and an ability cannot scope by it.`,
+      );
+    }
+
     // `owner`/`via` compare a row column to the caller's JWT claim; a no-session audience has
     // none. Truthiness matches the compiler, which treats `owner: ''` as no row scope.
     const rowScope = a.condition.owner ? 'owner' : a.condition.via ? 'via' : null;
@@ -365,6 +584,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
   // literally, so a model keying the column `deleted_at` — the shape a snake_case brownfield
   // schema pulls as — carried a soft-delete column past a guard that never looked at it.
   const softDeleteField = 'deletedAt' in def.fields || 'deleted_at' in def.fields;
+  // A lifecycle model has declared what a delete does; its generated deletedAt is not an author field.
   if (needsSoftDeleteDeclaration({ hasDeletedAtField: softDeleteField, hasPublicRead, grantsDelete }) && def.softDelete === undefined) {
     // DURABILITY FIRST. The old message called this "a visibility decision", which is false
     // for exactly the models that broke: with no public read, `softDelete: true` adds no
@@ -454,15 +674,18 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
 
   return {
     table,
-    fields: def.fields,
-    abilities: def.abilities ?? [],
+    fields,
+    // Appended after every author check above: the internal set may name the generated columns.
+    abilities: lifecycle ? [...(def.abilities ?? []), ...lifecycleAbilities()] : def.abilities ?? [],
     hooks: def.hooks,
     relations: def.relations ?? {},
     primaryKey,
     constraints: def.constraints ?? [],
     writtenBy: def.writtenBy ?? 'app',
     privileges: def.privileges ?? {},
+    // Stays false on a lifecycle model: its reads are filtered by the RLS guard (L1.2a), its deletes arrive with the triggers.
     softDelete: def.softDelete ?? false,
+    ...(lifecycle ? { lifecycle: true as const } : {}),
     schema: def.schema ?? 'public',
     private: def.private ?? false,
     rls: def.rls ?? true,

package/src/module.ts

@@ -19,7 +19,7 @@
  * See docs/plans/v3-module-complete-generation.md.
  */
 
-import type { ModelDescriptor } from './model';
+import { LIFECYCLE_OWNER_ROLE, type ModelDescriptor } from './model';
 import type { DerivedDescriptor, SequenceDescriptor } from './derived';
 import { rejectHoles, functionArgSignature } from './derived';
 import { deriveFunctionSchemas } from './derive';
@@ -223,7 +223,12 @@ export function moduleDerived(modules: Module[]): DerivedDescriptor[] {
   return modules.flatMap((m) => m.derived);
 }
 
-/** The union of every module's governed roles — deduped and sorted. Widen-only by construction. */
+/**
+ * The union of every module's governed roles — deduped and sorted. Widen-only by construction.
+ * A module holding a lifecycle model also governs {@link LIFECYCLE_OWNER_ROLE}, which the
+ * compiler grants on that model.
+ */
 export function moduleGovernedRoles(modules: Module[]): string[] {
-  return [...new Set(modules.flatMap((m) => m.governedRoles))].sort();
+  const lifecycle = modules.some((m) => m.models.some((model) => model.lifecycle));
+  return [...new Set([...modules.flatMap((m) => m.governedRoles), ...(lifecycle ? [LIFECYCLE_OWNER_ROLE] : [])])].sort();
 }