@everystack/model 0.4.21 → 0.4.23

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 type { TableConstraint } from './constraints';
+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
@@ -450,17 +670,22 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     );
   }
 
+  assertCheckNames(table, def.constraints ?? []);
+
   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();
 }

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 })),
+  ];
+}

package/src/relations.ts

@@ -4,16 +4,74 @@
  *
  *   belongsTo(() => Author, 'authorId')   // this.authorId → Author.<pk>
  *   hasMany(() => Comment, 'postId')      // this.<pk> → Comment.postId
+ *   hasMany(() => Comment, 'postId', { dependent: 'nullify' })   // delete a post → postId NULL
+ *   hasOne(() => Image, 'postId')         // the first Image whose postId is this.<pk>
  *
  * A table-name target avoids sibling imports; linkModels resolves it against the
  * complete set. Model thunks remain supported for forward references.
+ *
+ * The third argument is a string (the `references` key, as it always was) or an options object
+ * (the ratified F7 API). `dependent` is the parent's word about delete behaviour; it compiles to
+ * the ON DELETE of the CHILD's foreign key (see dependents.ts). `orderBy`, `limit` and `where`
+ * are DISPLAY ONLY: they emit no SQL and never narrow a dependent. Their shape is checked at
+ * defineModel; their field names are TARGET fields, so linkModels checks them and normalizes the
+ * orderBy once (relation-display.ts): the target's primary key is appended as the tie-breaker.
  */
 
 import type { ModelDescriptor } from './model';
 import { referenceThunk } from './link';
 
+/** What deleting a parent row does to its children, through the child's foreign key. */
+export type HasManyDependent = 'restrict' | 'nullify' | 'cascade';
+
+/** One ordering term of a relation's display order. */
+export interface RelationOrder {
+  field: string;
+  order: 'asc' | 'desc';
+}
+
+/** An equality filter on the related rows: field → value. */
+export type RelationWhere = Record<string, string | number | boolean | null>;
+
+export interface BelongsToOptions {
+  /** The key on the target, when it is not the target's primary key. */
+  references?: string;
+}
+
+export interface HasManyOptions {
+  /** The key on this table, when it is not this table's primary key. */
+  references?: string;
+  /**
+   * What a delete of this row does to the target rows, through the target's foreign key on
+   * `column`: `'restrict'` → ON DELETE RESTRICT, `'nullify'` → ON DELETE SET NULL, `'cascade'` →
+   * ON DELETE CASCADE (Rails `delete_all`: the database removes the children and runs none of
+   * their hooks). The target field must declare `.references()` to this model; a dependent never
+   * creates a foreign key.
+   */
+  dependent?: HasManyDependent;
+  /**
+   * Display order: fields of the target. linkModels appends the target's primary key as the
+   * tie-breaker. Without it the order is unchanged (none is added).
+   */
+  orderBy?: RelationOrder[];
+  /** Display limit: a positive integer. */
+  limit?: number;
+  /** Display filter: equality on target fields; `null` means IS NULL. Not access control. */
+  where?: RelationWhere;
+}
+
+/** hasOne is one row: no `limit`, and no `dependent` in v1 (declare it on a hasMany). */
+export interface HasOneOptions {
+  /** The key on this table, when it is not this table's primary key. */
+  references?: string;
+  /** Which row: target fields, then the target's primary key. Default: the primary key ascending. */
+  orderBy?: RelationOrder[];
+  /** Display filter: equality on target fields; `null` means IS NULL. Not access control. */
+  where?: RelationWhere;
+}
+
 export interface Relation {
-  kind: 'belongsTo' | 'hasMany';
+  kind: 'belongsTo' | 'hasMany' | 'hasOne';
   /** Thunk to the related model (forward-reference safe). */
   target: () => ModelDescriptor;
   /**
@@ -28,22 +86,166 @@ export interface Relation {
    * - hasMany:   overrides RelationConfig.from (default: this table's pk)
    */
   references?: string;
+  /** hasMany only. Present only when declared. */
+  dependent?: HasManyDependent;
+  /**
+   * Present only when declared, or on a hasOne. After linkModels it is normalized: it ends with
+   * every primary-key column of the target (a hasOne with none declared is the key ascending).
+   */
+  orderBy?: RelationOrder[];
+  limit?: number;
+  where?: RelationWhere;
+}
+
+type Kind = Relation['kind'];
+
+const OPTION_KEYS: Record<Kind, readonly string[]> = {
+  belongsTo: ['references'],
+  hasMany: ['references', 'dependent', 'orderBy', 'limit', 'where'],
+  hasOne: ['references', 'orderBy', 'where'],
+};
+
+/**
+ * Build a descriptor. A string or absent third argument yields exactly the legacy shape
+ * (`references` always present as a key), so an existing model's descriptor is unchanged. An
+ * options object adds a key only for an option it declares.
+ */
+function relation(kind: Kind, target: (() => ModelDescriptor) | string, column: string, opts: unknown): Relation {
+  const call = `${kind}(…, '${column}')`;
+  if (opts === undefined || typeof opts === 'string') {
+    return { kind, target: referenceThunk(target), column, references: opts };
+  }
+  if (opts === null || typeof opts !== 'object' || Array.isArray(opts)) {
+    throw new Error(`${call}: the third argument is ${opts === null ? 'null' : Array.isArray(opts) ? 'an array' : typeof opts}; pass a references string or an options object`);
+  }
+  const allowed = OPTION_KEYS[kind];
+  for (const key of Object.keys(opts)) {
+    if (allowed.includes(key)) continue;
+    if (kind === 'hasOne' && key === 'dependent') {
+      throw new Error(`${call}: hasOne takes no dependent; declare dependent on a hasMany over the same column`);
+    }
+    if (kind === 'hasOne' && key === 'limit') throw new Error(`${call}: hasOne takes no limit: it is one row`);
+    const hint = key === 'dependent' ? "; dependent is declared on the parent's hasMany" : '';
+    throw new Error(`${call}: unknown option '${key}' (expected ${allowed.join(', ')})${hint}`);
+  }
+  const o = opts as HasManyOptions;
+  if (o.references !== undefined && typeof o.references !== 'string') {
+    throw new Error(`${call}: references must be a string`);
+  }
+  const out: Relation = { kind, target: referenceThunk(target), column, references: o.references };
+  if (o.dependent !== undefined) out.dependent = o.dependent;
+  // Copied, so a later edit to the caller's array or object changes nothing. Shapes are checked
+  // at defineModel (assertRelationShape); a malformed value is kept as given for that message.
+  if (o.orderBy !== undefined) {
+    out.orderBy = Array.isArray(o.orderBy)
+      ? o.orderBy.map((t) => (t !== null && typeof t === 'object' && !Array.isArray(t) ? { ...t } : t))
+      : o.orderBy;
+  }
+  if (o.limit !== undefined) out.limit = o.limit;
+  if (o.where !== undefined) {
+    out.where = o.where !== null && typeof o.where === 'object' && !Array.isArray(o.where) ? { ...o.where } : o.where;
+  }
+  return out;
 }
 
 /** Many-to-one: this row points at one target row via `column`. */
 export function belongsTo(
   target: (() => ModelDescriptor) | string,
   column: string,
-  references?: string,
+  opts?: string | BelongsToOptions,
 ): Relation {
-  return { kind: 'belongsTo', target: referenceThunk(target), column, references };
+  return relation('belongsTo', target, column, opts);
 }
 
 /** One-to-many: target rows point back at this row via `column`. */
 export function hasMany(
   target: (() => ModelDescriptor) | string,
   column: string,
-  references?: string,
+  opts?: string | HasManyOptions,
+): Relation {
+  return relation('hasMany', target, column, opts);
+}
+
+/**
+ * One-to-one from the parent side: the first target row pointing back via `column`, in `orderBy`
+ * (default: the target's primary key ascending). Display only: it compiles no SQL.
+ */
+export function hasOne(
+  target: (() => ModelDescriptor) | string,
+  column: string,
+  opts?: HasOneOptions,
 ): Relation {
-  return { kind: 'hasMany', target: referenceThunk(target), column, references };
+  return relation('hasOne', target, column, opts);
+}
+
+/**
+ * The declaration rules that need no other model, checked by defineModel: an option or kind that
+ * is not implemented yet is refused by name, never silently ignored.
+ */
+export function assertRelationShape(model: string, name: string, rel: Relation): void {
+  const at = `model '${model}': relation '${name}'`;
+  if (rel.kind !== 'belongsTo' && rel.kind !== 'hasMany' && rel.kind !== 'hasOne') {
+    throw new Error(`${at}: unknown relation kind '${String(rel.kind)}' (expected belongsTo, hasMany or hasOne)`);
+  }
+  if (rel.kind === 'belongsTo') {
+    for (const key of ['orderBy', 'limit', 'where'] as const) {
+      if (rel[key] !== undefined) throw new Error(`${at}: ${key} is a hasMany or hasOne option; belongsTo takes none`);
+    }
+  }
+  if (rel.kind === 'hasOne' && rel.limit !== undefined) throw new Error(`${at}: limit is a hasMany option; hasOne is one row`);
+  assertDisplayShape(at, rel);
+  if (rel.dependent === undefined) return;
+  if (rel.kind !== 'hasMany') throw new Error(`${at}: dependent is a hasMany option; ${rel.kind} takes none`);
+  if (rel.dependent !== 'restrict' && rel.dependent !== 'nullify' && rel.dependent !== 'cascade') {
+    throw new Error(`${at}: dependent '${String(rel.dependent)}' is not a dependent value (expected 'restrict', 'nullify' or 'cascade')`);
+  }
+}
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** A value as an error message shows it. */
+const shown = (v: unknown): string => {
+  if (v === undefined || typeof v === 'number') return String(v);
+  if (typeof v === 'string') return `'${v}'`;
+  try { return JSON.stringify(v) ?? String(v); } catch { return String(v); }
+};
+
+/**
+ * The display options' shape, checked at defineModel (no other model needed). Their field names
+ * name TARGET fields, so `normalizeRelationDisplay` (relation-display.ts) checks those once the target is known.
+ */
+function assertDisplayShape(at: string, rel: Relation): void {
+  if (rel.orderBy !== undefined) {
+    const orderBy: unknown = rel.orderBy;
+    if (!Array.isArray(orderBy) || orderBy.length === 0) throw new Error(`${at}: orderBy must be a non-empty array of { field, order }`);
+    const seen = new Set<string>();
+    orderBy.forEach((term: unknown, i) => {
+      if (!isPlainObject(term) || typeof term.field !== 'string' || term.field === ''
+        || Object.keys(term).some((k) => k !== 'field' && k !== 'order')) {
+        throw new Error(`${at}: orderBy[${i}] must be { field: string, order: 'asc' | 'desc' }`);
+      }
+      if (term.order !== 'asc' && term.order !== 'desc') {
+        throw new Error(`${at}: orderBy[${i}].order is ${shown(term.order)}; expected 'asc' or 'desc'`);
+      }
+      if (seen.has(term.field)) throw new Error(`${at}: orderBy lists field '${term.field}' twice`);
+      seen.add(term.field);
+    });
+  }
+  if (rel.limit !== undefined) {
+    const limit: unknown = rel.limit;
+    if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1) {
+      throw new Error(`${at}: limit must be a positive integer, got ${shown(limit)}`);
+    }
+  }
+  if (rel.where !== undefined) {
+    const where: unknown = rel.where;
+    if (!isPlainObject(where) || Object.keys(where).length === 0) {
+      throw new Error(`${at}: where must be a non-empty object of field → value`);
+    }
+    for (const [key, value] of Object.entries(where)) {
+      const ok = value === null || typeof value === 'string' || typeof value === 'boolean'
+        || (typeof value === 'number' && Number.isFinite(value));
+      if (!ok) throw new Error(`${at}: where '${key}' must be a string, a finite number, a boolean or null, got ${shown(value)}`);
+    }
+  }
 }

package/src/wire.ts

@@ -45,8 +45,9 @@
  * accept risks wrong ownership or a wrong derived object on a production database.
  *
  * v1 — the first version. Shapes as they stood when the guard was introduced.
+ * v2 — ProvisionWirePayload gains `lifecycleRole` (provision the reserved lifecycle role).
  */
-export const MODEL_WIRE_CONTRACT = 1;
+export const MODEL_WIRE_CONTRACT = 2;
 
 /**
  * Every Model-derived wire payload carries this. The server refuses a payload whose `modelContract`
@@ -101,6 +102,8 @@ export interface Adoptee {
 export interface ProvisionWirePayload extends ModelWireEnvelope {
   /** The declared schema set, ordered and `public`-trailing — set as the ROLE default search_path. */
   searchPath?: string[];
+  /** The Models declare a `lifecycle: true` model: provision the reserved role everystack_lifecycle. */
+  lifecycleRole?: boolean;
   /** Accepted by the action's payload type; convergence itself runs as db:converge-ownership. */
   declaredOwners?: DeclaredOwner[];
   declaredObjects?: Adoptee[];