@everystack/model 0.4.22 → 0.4.24

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

@@ -1,3 +1,4 @@
+import { dependentWhereRefusal } from './dependents';
 /**
  * `defineModel` — Layer 2. One call colocates everything about a table: its
  * fields, its authorization (`abilities`), its mutation hooks, and its relations.
@@ -11,16 +12,20 @@
  * 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';
 
+import type { AfterLifecycleHook, BeforeLifecycleHook, DestroyHook } from './lifecycle-hooks';
+export type { AfterLifecycleHook, BeforeLifecycleHook, DestroyContext, DestroyHook, HookVeto, LifecycleContext } from './lifecycle-hooks';
+
 /**
  * Per-table mutation hooks. Imperative function bodies the framework cannot
  * absorb (purge an S3 object on delete, stamp a column on create) — held
@@ -33,6 +38,22 @@ 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;
+  /** Lifecycle tables: before the API DELETE stamps, once per matched root row, inside its transaction.
+   * Return `veto(reason)` to refuse the whole request (409). Cascaded children run no hook: guard them with `deleteWhen`. */
+  beforeStamp?: BeforeLifecycleHook;
+  /** Lifecycle tables: after a stamping DELETE commits, once per batch, with that batch's root rows. Best-effort. */
+  afterStamp?: AfterLifecycleHook;
+  /** Lifecycle tables: after `POST {table}/restore` commits, with `[{ <key>: id }]`, the batch and the counts. Best-effort. */
+  afterRestore?: AfterLifecycleHook;
+  /** Reserved for a future release; createHandler refuses it. */
+  beforeRestore?: never;
 }
 
 /**
@@ -115,6 +136,18 @@ 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.
+   *
+   * `{ deleteWhen: sql\`<predicate>\` }` is lifecycle too, with a guard: a row may be stamped
+   * deleted only when the predicate is TRUE for it (FALSE or NULL refuses, SQLSTATE 23514), whether
+   * the delete is the row's own or a parent's cascade. Bare column names, like a policy predicate.
+   * Purge keeps the row (a `skipped` receipt) when the predicate no longer holds. `{}` is `true`.
+   */
+  lifecycle?: true | LifecycleOptions;
   /**
    * 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 +228,11 @@ 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}. Always
+   *  `true` on the descriptor, whichever form the definition used. */
+  lifecycle?: true;
+  /** `lifecycle: { deleteWhen }`'s predicate text. Absent when there is no guard. */
+  deleteWhen?: string;
   /** 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,12 +265,224 @@ 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(),
+  };
+}
+
+/** `lifecycle: { … }` options. */
+export interface LifecycleOptions {
+  /** A row may be stamped deleted only when this is TRUE for it; FALSE or NULL refuses. */
+  deleteWhen?: RawSql;
+}
+
+/** True for `lifecycle: true` and for `lifecycle: { … }` (validated by assertLifecycle). */
+function isLifecycle(def: ModelDefinition): boolean {
+  return def.lifecycle === true || (typeof def.lifecycle === 'object' && def.lifecycle !== null);
+}
+
+/** The guard predicate text, or undefined. Call after assertLifecycle. */
+function deleteWhenOf(def: ModelDefinition): string | undefined {
+  const value = def.lifecycle;
+  return typeof value === 'object' && value !== null && value.deleteWhen !== undefined ? value.deleteWhen.sql : undefined;
+}
+
+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 (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const unknown = Object.keys(value).filter((k) => k !== 'deleteWhen');
+    if (unknown.length > 0) {
+      throw new Error(`model '${table}': lifecycle: { ${unknown.join(', ')} } — the only key is deleteWhen (lifecycle: { deleteWhen: sql\`…\` }).`);
+    }
+    const when = (value as { deleteWhen?: unknown }).deleteWhen;
+    if (when !== undefined && !(typeof when === 'object' && when !== null && typeof (when as RawSql).sql === 'string' && (when as RawSql).sql.trim() !== '')) {
+      throw new Error(`model '${table}': lifecycle: { deleteWhen } — deleteWhen must be sql\`…\`, a non-empty predicate over this table's columns.`);
+    }
+  } else if (value !== true) {
+    throw new Error(`model '${table}': lifecycle: ${JSON.stringify(value)} — the only values are lifecycle: true and lifecycle: { deleteWhen: sql\`…\` }.`);
+  }
+  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 (!isLifecycle(def)) 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 = isLifecycle(def);
+  const deleteWhen = deleteWhenOf(def);
+  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 filtered = lifecycle ? dependentWhereRefusal(def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table, name, relation) : undefined;
+    if (filtered) throw new Error(filtered);
   }
   const primaryKey = Object.entries(def.fields)
     .filter(([, f]) => f.spec.isPrimaryKey)
@@ -243,6 +493,28 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
       throw new Error(`model '${table}': can('execute') is a function ability — declare it on the defineFunction it gates.`);
     }
 
+    if (a.condition.deleted !== undefined) {
+      if (a.action !== 'read') {
+        throw new Error(`model '${table}': deleted applies only to can('read'), not can('${a.action}').`);
+      }
+      if (a.condition.deleted !== 'include' && a.condition.deleted !== 'only') {
+        throw new Error(`model '${table}': can('read', { deleted: ${JSON.stringify(a.condition.deleted)} }) — deleted must be 'include' or 'only'.`);
+      }
+      if (!lifecycle) {
+        throw new Error(`model '${table}': can('read', { deleted }) — deleted applies only to a lifecycle model; this model has no deleted rows to include.`);
+      }
+      if (!a.condition.role) {
+        throw new Error(`model '${table}': can('read', { deleted }) — deleted needs a role: it changes that role's own read policy. Name the role that may see deleted rows.`);
+      }
+      // A public tier is every caller of the API, and db:pull could not fold the table back.
+      if (['anon', 'authenticated', 'public'].includes(a.condition.role.toLowerCase())) {
+        throw new Error(
+          `model '${table}': can('read', { role: '${a.condition.role}', deleted }) — deleted rows are for a named internal role, ` +
+            `never a public tier (anon, authenticated, public). Name the role that searches or restores, such as 'support_role'.`,
+        );
+      }
+    }
+
     // A column list is authorization, not a selection hint. If it reaches a table-grant path
     // unnoticed, Postgres receives a whole-table privilege. Admit only the shapes the column
     // compiler understands, and reject an empty list because it is indistinguishable from no
@@ -274,7 +546,9 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
         );
       }
       for (const column of a.condition.columns) {
-        if (!(column in def.fields)) {
+        // deletedAt is visible to every reader of a lifecycle model, so a column read may list it.
+        // deletedBy, deletedBatch and deletedXid are hidden by design and stay refused.
+        if (!(column in def.fields) && !(lifecycle && a.action === 'read' && column === 'deletedAt')) {
           throw new Error(
             `model '${table}': columns names '${column}', but no such field exists. Column abilities use model field keys.`,
           );
@@ -282,6 +556,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 +648,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 +738,19 @@ 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 } : {}),
+    ...(deleteWhen !== undefined ? { deleteWhen } : {}),
     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();
 }

package/src/relation-display.ts

@@ -0,0 +1,48 @@
+/**
+ * The link-time half of the relation display options: the checks and the orderBy normalization
+ * that need the resolved TARGET model. A leaf: it imports only types, so linkModels can use it
+ * without an import cycle through relations.ts (which imports referenceThunk from link.ts).
+ */
+
+import type { ModelDescriptor } from './model';
+import type { Relation, RelationOrder } from './relations';
+
+/** True when linkModels must evaluate this relation's target to normalize its display options. */
+export function hasDisplayOptions(rel: Relation): boolean {
+  return rel.kind === 'hasOne' || rel.orderBy !== undefined || rel.where !== undefined;
+}
+
+const nameOf = (m: ModelDescriptor): string => (!m.schema || m.schema === 'public' ? m.table : `${m.schema}.${m.table}`);
+
+/**
+ * The normalized orderBy of a hasMany or hasOne against its resolved TARGET, or undefined when
+ * there is none (a hasMany with no orderBy keeps today's order: none is added). Pure: linkModels
+ * writes the result, once every reference in the set has resolved.
+ *
+ * Every orderBy and where field must be a field of the target. The target's primary key is
+ * appended, ascending, for each key column the orderBy does not list, so the order is total. A
+ * hasOne with no orderBy is ordered by that key. Idempotent: a normalized orderBy lists the key.
+ */
+export function normalizeRelationDisplay(model: string, name: string, rel: Relation, target: ModelDescriptor): RelationOrder[] | undefined {
+  const at = `model '${model}': relation '${name}'`;
+  for (const key of Object.keys(rel.where ?? {})) {
+    if (!Object.prototype.hasOwnProperty.call(target.fields, key)) {
+      throw new Error(`${at}: where field '${key}' is not a field of model '${nameOf(target)}'`);
+    }
+  }
+  if (rel.orderBy === undefined && rel.kind !== 'hasOne') return undefined;
+  const declared = rel.orderBy ?? [];
+  for (const term of declared) {
+    if (!Object.prototype.hasOwnProperty.call(target.fields, term.field)) {
+      throw new Error(`${at}: orderBy field '${term.field}' is not a field of model '${nameOf(target)}'`);
+    }
+  }
+  if (target.primaryKey.length === 0) {
+    throw new Error(`${at}: model '${nameOf(target)}' has no primary key to break orderBy ties; declare one`);
+  }
+  const listed = new Set(declared.map((t) => t.field));
+  return [
+    ...declared.map((t) => ({ field: t.field, order: t.order })),
+    ...target.primaryKey.filter((k) => !listed.has(k)).map((k) => ({ field: k, order: 'asc' as const })),
+  ];
+}