@everystack/api 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.12] - 2026-10-23
+
+### BREAKING CHANGES
+
+- lifecycle delete and restore hand the batch id to the caller
+- lifecycle: { deleteWhen } refuses deleting a row its predicate does not allow
+- one lifecycle hook API: (rows, ctx), veto(reason), beforeStamp
+
+### Added
+
+- afterStamp and afterRestore hooks hand a lifecycle batch to app code
+
+### Fixed
+
+- a lifecycle DELETE stamps only the rows beforeStamp saw
+
+### Documentation
+
+- afterStamp, afterRestore and the batch in the restore response
+- Extending lifecycle, the phase table, the veto and failure rules
+
+## [0.4.11] - 2026-10-23
+
+### Added
+
+- per-parent embed order, limit and where on both read paths (F10)
+- hasOne one-row embed on both read paths (P2)
+- createHandler refuses a handler relation drizzleRelations does not declare (P3)
+- the handler deletes, hides and restores lifecycle rows through the database (H1, P1.4)
+- profiles, posts, likes and follows are one lifecycle family; account delete and restore use it (P2.1, P2.2)
+- lifecycle columns are hidden from callers that cannot manage the table
+- beforeDestroy and afterDestroy hooks at a real removal
+
+### Fixed
+
+- an unresolved relation no longer returns a same-named column
+- match embedded rows on a hidden child key before stripping it (P2 review)
+- a belongsTo embed matches on a hidden target key before stripping it
+- a beforeDestroy HandlerError renders with its own status
+
 ## [0.4.10] - 2026-10-18
 
 ### BREAKING CHANGES

package/README.md

@@ -101,6 +101,10 @@ createHandler(db, schema, {
       afterUpdate: async (rows, user, client) => {},
       beforeDelete: async (user, client) => {},
       afterDelete: async (rows, user, client) => {},
+      // Lifecycle tables only (see "Extending lifecycle" in docs/handler.md); veto from '@everystack/api/handler':
+      beforeStamp: (row, ctx) => (ctx.user ? undefined : veto('sign in to delete')), // in the transaction; veto -> 409
+      afterStamp: async (rows, ctx) => {},   // after commit, once per batch (ctx.batch)
+      afterRestore: async (rows, ctx) => {}, // after commit, ctx.batch and ctx.counts
     },
   },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/client/index.ts

@@ -83,6 +83,18 @@ export interface QueryBuilder {
   insert(data: Record<string, unknown>): Promise<ClientResponse<unknown>>;
   update(data: Record<string, unknown>): Promise<ClientResponse<unknown[]>>;
   remove(): Promise<ClientResponse<unknown[]>>;
+  /** Lifecycle tables: restore a deleted row and its delete batch, on the table's delete rule.
+   *  POSTs `{baseUrl}/{table}/restore` with `{ id }`; the data is `{ restored, skipped, batch }`. */
+  restore(id: string | number): Promise<ClientResponse<RestoreResult>>;
+}
+
+/** What a lifecycle restore brought back: rows restored, and batch rows left deleted. */
+export interface RestoreResult {
+  restored: number;
+  skipped: number;
+  /** The batch restored; null for a row deleted before batches existed. Absent from a server
+   *  whose restore functions predate it (its next db:apply adds it). */
+  batch?: string | null;
 }
 
 export interface Client {
@@ -270,6 +282,26 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
       const result = await response.json();
       return { data: result, error: null };
     },
+
+    async restore(id: string | number): Promise<ClientResponse<RestoreResult>> {
+      const url = `${options.baseUrl}/${table}/restore`;
+      const headers = await buildHeaders(options);
+      headers['Content-Type'] = 'application/json';
+
+      const { response, retried } = await fetchWithRetry(
+        url,
+        { method: 'POST', headers, body: JSON.stringify({ id }) },
+        options,
+      );
+
+      if (retried) return retried as ClientResponse<RestoreResult>;
+
+      if (!response.ok) {
+        return { data: null, error: await parseError(response) };
+      }
+
+      return { data: (await response.json()) as RestoreResult, error: null };
+    },
   };
 
   return builder;

package/src/handler/index.ts

@@ -28,6 +28,19 @@ type Handler = (request: Request) => Promise<Response>;
 
 export { HandlerError } from './errors';
 import { HandlerError } from './errors';
+export { veto, isVeto } from './veto';
+export type { HookVeto, LifecycleContext, DestroyContext, DestroyHook, BeforeLifecycleHook, AfterLifecycleHook } from './veto';
+import { isVeto, type AfterLifecycleHook, type BeforeLifecycleHook, type DestroyContext, type DestroyHook, type LifecycleContext } from './veto';
+
+/** A before hook returned veto(reason): the request is refused with 409 and its transaction rolls back. */
+class VetoRefusal extends Error {
+  constructor(readonly reason: string) { super(reason); }
+}
+
+/** A lifecycle before hook threw inside its transaction; carried out so the handler can answer as for any before hook. */
+class BeforeHookThrew extends Error {
+  constructor(readonly thrown: unknown) { super('before hook threw'); }
+}
 
 /**
  * A 5xx system fault surfaced to the observability sink. Distinct from a 4xx
@@ -233,6 +246,20 @@ export interface RelationConfig {
   to: string;
   /** If true, this is a one-to-many relation (returns array). Default: false (many-to-one, returns object) */
   many?: boolean;
+  /** To-one from the parent side (returns an object or null): the first target row whose `to`
+   *  equals the parent's `from`, in `orderBy` order. Same column roles as `many`. Not with
+   *  `many` or `limit`. The target must have a primary key. */
+  hasOne?: true;
+  /** Many or hasOne. Display order of each parent's rows, by target column. The target's primary
+   *  key is appended as the tie-breaker (a hasOne with no orderBy is ordered by that key).
+   *  Never read from the request. */
+  orderBy?: Array<{ column: string; order: 'asc' | 'desc' }>;
+  /** Many only. At most this many rows per parent, in `orderBy` order. Unrelated to `?limit=`. */
+  limit?: number;
+  /** Many or hasOne. Equality on target columns (`null` means IS NULL), applied before `limit`
+   *  or the hasOne choice. A display filter the request cannot widen. It is not access control:
+   *  use RLS for that. */
+  where?: Record<string, string | number | boolean | null>;
 }
 
 export interface SoftDeleteConfig {
@@ -245,8 +272,17 @@ export interface SoftDeleteConfig {
    *  default `role`) is in the table's list: exact string match, no hierarchy, no case folding.
    *  Anyone else gets live rows only, as if the param were absent. A restore body must be
    *  exactly `{ <column>: null }`, or 400. Omitted: no one restores through the API.
-   *  This is a backstop. RLS must also keep other roles off deleted rows (docs/handler.md). */
+   *  This is a backstop. RLS must also keep other roles off deleted rows (docs/handler.md).
+   *  A lifecycle table may not appear here: it restores through `POST {table}/restore`. */
   restore?: Record<string, string[]>;
+  /** `lifecycle: true` tables (deriveHandlerConfig emits them), keyed like `tables`. Each is a
+   *  soft-delete table whose column is always `deletedAt`, soft-deleted by the database itself:
+   *  DELETE runs a real SQL DELETE (a trigger stamps the row), reads and embeds hide deleted rows
+   *  for every role unless `?deleted=include|only` (honoured for any role; RLS decides what each
+   *  sees), and `POST {basePath}/{table}/restore {id}` calls `<schema>.<table>_restore(id)` as the
+   *  caller. PATCH with `?deleted=include|only` is refused with 400. `?deleted=only` reaches embeds
+   *  too, so a live parent embedded under a deleted child comes back null. */
+  lifecycle?: string[];
 }
 
 export interface HookConfig {
@@ -262,6 +298,33 @@ export interface HookConfig {
   beforeDelete?: (user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
   /** Called after DELETE with all deleted rows. Fire-and-forget. */
   afterDelete?: (rows: Record<string, unknown>[], user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
+  /** After the hard DELETE statement and before commit, for each returned row. Return
+   * `veto(reason)` to refuse the request (409 `{ message, code: 'vetoed' }`, nothing deleted). A
+   * throw rolls back the database delete only. No transaction is passed; external effects
+   * cannot be undone and must be idempotent. Lifecycle API deletes do not call this.
+   * Treat the row as read-only: it is the same object later serialized into the response. */
+  beforeDestroy?: DestroyHook;
+  /** After a real removal commits, per returned row, best-effort. Must be idempotent.
+   * Treat the row as read-only: it is the same object later serialized into the response. */
+  afterDestroy?: DestroyHook;
+  /** Lifecycle tables only: inside the DELETE's transaction, before the DELETE statement, once per
+   * matched ROOT row (the pre-image), with `{ phase: 'stamp', batch: null }`. Return `veto(reason)` to
+   * refuse the whole request: 409 `{ message: reason, code: 'vetoed' }`, nothing stamped, no after
+   * hooks. A throw is a failure (a HandlerError keeps its status, anything else is 500). Cascaded
+   * children run no hook: guard them with the model's `deleteWhen`. */
+  beforeStamp?: BeforeLifecycleHook;
+  /** Lifecycle tables only: after a DELETE that stamped rows COMMITS, once per batch, with the
+   * stamped root rows of that batch (the pre-image, as the response lists them) and `ctx.batch`. A
+   * DELETE matching several rows stamps one batch per row, so this runs once per row then.
+   * Best-effort like afterDelete: a throw goes to onError and never changes the response. Not
+   * called when nothing was stamped, nor on a table that is not lifecycle. */
+  afterStamp?: AfterLifecycleHook;
+  /** Lifecycle tables only: after `POST {table}/restore` COMMITS, with `[{ <key>: id }]` (the id as
+   * the request sent it), `ctx.batch` and `ctx.counts`. Not called for a row deleted before batches
+   * existed (batch null). Best-effort: a throw goes to onError and never changes the response. */
+  afterRestore?: AfterLifecycleHook;
+  /** Reserved for a future release: createHandler refuses it, so it is never silently ignored. */
+  beforeRestore?: never;
 }
 
 /** Cache-Control header configuration for different response categories. */
@@ -366,6 +429,12 @@ export interface HandlerOptions {
    *  Explicit references in query parameters are refused before database access.
    *  Does not prevent writes to these columns; use protectedFields for that. */
   hiddenColumns?: Record<string, string[]>;
+  /** Exact roles allowed to read deletedBy, deletedBatch and deletedXid on each lifecycle
+   *  table. Other hidden columns remain hidden. Uses auth.roleField (default role), with
+   *  no hierarchy or case folding. Missing/non-string claims never qualify. The claim is compared
+   *  to the model's PostgreSQL role name, so an app whose pgSettings maps claim to role
+   *  differently sees the two diverge: keep the claim values equal to the manage role names. */
+  hiddenColumnsExceptRoles?: Record<string, string[]>;
   /** Per-table list of fields stripped from POST/PATCH request bodies before mutation.
    *  Prevents mass assignment / privilege escalation on sensitive columns. */
   protectedFields?: Record<string, string[]>;
@@ -415,8 +484,18 @@ export interface HandlerOptions {
   onError?: (fault: HandlerFault) => void | Promise<void>;
 }
 
-function getSoftDeleteColumn(table: DrizzleTable, options?: HandlerOptions): DrizzleColumn | null {
+/** The lifecycle machinery's timestamp column: fixed, whatever softDelete.column says. */
+const LIFECYCLE_DELETED_AT = 'deletedAt';
+/** The SQL name of the lifecycle batch column (columnPropertyName maps it to the table's key). */
+const LIFECYCLE_DELETED_BATCH = 'deleted_batch';
+
+function isLifecycleTable(tableName: string, options?: HandlerOptions): boolean {
+  return options?.softDelete?.lifecycle?.includes(tableName) ?? false;
+}
+
+function getSoftDeleteColumn(tableName: string, table: DrizzleTable, options?: HandlerOptions): DrizzleColumn | null {
   if (!options?.softDelete) return null;
+  if (isLifecycleTable(tableName, options)) return getColumn(table, LIFECYCLE_DELETED_AT);
   const colName = options.softDelete.column || 'deletedAt';
   return getColumn(table, colName);
 }
@@ -434,11 +513,29 @@ function softDeleteCondition(sdCol: DrizzleColumn, params: URLSearchParams): SQL
 
 function isSoftDeleteTable(tableName: string, table: DrizzleTable, options?: HandlerOptions): boolean {
   if (!options?.softDelete) return false;
+  if (isLifecycleTable(tableName, options)) return true;
   if (options.softDelete.tables) {
     return options.softDelete.tables.includes(tableName);
   }
   // Auto-detect: table has the soft-delete column
-  return getSoftDeleteColumn(table, options) != null;
+  return getSoftDeleteColumn(tableName, table, options) != null;
+}
+
+/**
+ * The soft-delete guard on an embedded table. Live rows only, except that a lifecycle table
+ * honours the request's ?deleted=include|only like its top-level read: RLS decides what each
+ * role sees. `params` is absent where no request applies (a pre-DB validation pass).
+ */
+function embedSoftDeleteCondition(
+  tableName: string,
+  table: DrizzleTable,
+  options: HandlerOptions | undefined,
+  params: URLSearchParams | undefined,
+): SQL | null {
+  if (!isSoftDeleteTable(tableName, table, options)) return null;
+  const sdCol = getSoftDeleteColumn(tableName, table, options);
+  if (!sdCol) return null;
+  return params && isLifecycleTable(tableName, options) ? softDeleteCondition(sdCol, params) : isNull(sdCol);
 }
 
 /**
@@ -457,17 +554,18 @@ async function executeWithSettings<T>(
   db: DrizzleDb,
   settings: Record<string, string> | undefined,
   fn: (dbOrTx: DrizzleDb) => Promise<T>,
+  forceTransaction = false,
 ): Promise<T> {
-  if (settings && Object.keys(settings).length > 0) {
+  if (forceTransaction || (settings && Object.keys(settings).length > 0)) {
     return db.transaction(async (tx: DrizzleDb) => {
-      const role = settings['role'];
+      const role = settings?.['role'];
       if (role) {
         if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(role)) {
           throw new Error(`Invalid role name: ${role}`);
         }
         await tx.execute(sql.raw(`SET LOCAL ROLE ${role}`));
       }
-      for (const [key, value] of Object.entries(settings)) {
+      for (const [key, value] of Object.entries(settings ?? {})) {
         if (key !== 'role' && value !== undefined && value !== '') {
           await tx.execute(sql`SELECT set_config(${key}, ${value}, true)`);
         }
@@ -592,11 +690,11 @@ async function checkRoleAuth(
 
 /**
  * Determine the Cache-Control header for a GET response.
- * - pgSettings configured → private (per-user data via RLS)
- * - No pgSettings → null (let server package set its default)
+ * - pgSettings or role-dependent column visibility configured → private
+ * - Neither configured → null (let server package set its default)
  */
 function getCacheControl(options?: HandlerOptions): string | null {
-  if (options?.pgSettings) {
+  if (options?.pgSettings || Object.keys(options?.hiddenColumnsExceptRoles ?? {}).length) {
     return options?.cache?.private ?? 'private, no-store';
   }
   return null;
@@ -840,6 +938,7 @@ function expandTableKeyedOptions(
     ...options,
     ...(options.exposedTables ? { exposedTables: expandList(options.exposedTables) } : {}),
     ...(options.hiddenColumns ? { hiddenColumns: expandMap(options.hiddenColumns) } : {}),
+    ...(options.hiddenColumnsExceptRoles ? { hiddenColumnsExceptRoles: expandMap(options.hiddenColumnsExceptRoles) } : {}),
     ...(options.protectedFields ? { protectedFields: expandMap(options.protectedFields) } : {}),
     ...(options.sanitizeColumns ? { sanitizeColumns: expandMap(options.sanitizeColumns) } : {}),
     ...(options.rowOwnership ? { rowOwnership: expandMap(options.rowOwnership) } : {}),
@@ -851,6 +950,7 @@ function expandTableKeyedOptions(
           ...options.softDelete,
           ...(options.softDelete.tables ? { tables: expandList(options.softDelete.tables) } : {}),
           ...(options.softDelete.restore ? { restore: expandMap(options.softDelete.restore) } : {}),
+          ...(options.softDelete.lifecycle ? { lifecycle: expandList(options.softDelete.lifecycle) } : {}),
         },
       }
       : {}),
@@ -870,10 +970,23 @@ function declaredTables(options: HandlerOptions): Set<string> {
     ...Object.keys(options.relations ?? {}),
     ...Object.values(options.relations ?? {}).flatMap(rels => Object.values(rels).map(rel => rel.table)),
     ...(options.softDelete?.tables ?? []),
+    ...(options.softDelete?.lifecycle ?? []),
   ];
   return new Set(names.map(toSnakeCase));
 }
 
+/**
+ * Refuse a hook name reserved for a future release, so adding it later is additive and no one
+ * ships a hook that is silently ignored. Every other unknown hook key is ignored, as before.
+ */
+function refuseReservedHooks(options: HandlerOptions | undefined): void {
+  for (const [tableName, hook] of Object.entries(options?.hooks ?? {})) {
+    if (hook && (hook as { beforeRestore?: unknown }).beforeRestore !== undefined) {
+      throw new Error(`[everystack/api] hooks.${tableName}.beforeRestore is reserved for a future release; remove it`);
+    }
+  }
+}
+
 /**
  * Refuse to start on a rowOwnership config the handler cannot enforce. The owner clause
  * needs a user, so rowOwnership without auth is an error. An entry whose column does not
@@ -922,6 +1035,11 @@ function validateSoftDeleteRestore(schema: Schema, options: HandlerOptions | und
   const colName = softDelete?.column || 'deletedAt';
   for (const [tableName, roles] of Object.entries(softDelete?.restore ?? {})) {
     const table = schema[tableName];
+    if (isLifecycleTable(tableName, options)) {
+      throw new Error(
+        `[everystack/api] softDelete.restore.${tableName}: table "${tableName}" is a lifecycle table. It restores through POST {basePath}/${tableName}/restore, on its delete rule; remove the entry.`,
+      );
+    }
     const isSoftDelete = table
       ? isSoftDeleteTable(tableName, table, options)
       : (softDelete?.tables?.includes(tableName) ?? false);
@@ -989,8 +1107,148 @@ function validateSanitizeColumns(schema: Schema, options: HandlerOptions | undef
   }
 }
 
+/**
+ * With `drizzleRelations`, the JOIN path hands each relation to drizzle's `with` by its handler
+ * name, so drizzle must declare a relation of that name on that table. A mismatch used to fail
+ * inside drizzle at request time; it is refused here instead. A hasOne never goes to `with` (it is
+ * resolved by a windowed query), and a table drizzle does not serve relationally takes the batch
+ * path, so neither is checked.
+ */
+function validateDrizzleRelationNames(db: DrizzleDb, options: HandlerOptions | undefined): void {
+  if (!options?.drizzleRelations) return;
+  const relational = (db as { _?: { schema?: Record<string, { relations?: Record<string, unknown> }> } })._?.schema;
+  if (!relational) return;
+  for (const [tableName, tableRelations] of Object.entries(options.relations ?? {})) {
+    if (!(db as any).query?.[tableName]) continue;
+    const declared = Object.keys(ownEntry(relational, tableName)?.relations ?? {});
+    for (const [name, relation] of Object.entries(tableRelations)) {
+      if (relation.hasOne || declared.includes(name)) continue;
+      throw new Error(
+        `[everystack/api] relations.${tableName}.${name}: drizzleRelations declares no relation "${name}" on "${tableName}" `
+        + `(it has: ${declared.length ? [...declared].sort().join(', ') : 'none'}). The JOIN path would fail at request time. `
+        + 'Declare it in your drizzle relations, rename the handler relation, or leave out drizzleRelations.',
+      );
+    }
+  }
+}
+
+/**
+ * Refuse a relation orderBy, limit, where or hasOne the read paths cannot apply. Only a relation
+ * that declares one is checked. Its target must be in the schema when its source is: derived
+ * configs name every table while a handler serves a few, and an unserved source never embeds.
+ */
+function validateRelationDisplay(schema: Schema, options: HandlerOptions | undefined): void {
+  for (const [tableName, tableRelations] of Object.entries(options?.relations ?? {})) {
+    for (const [name, relation] of Object.entries(tableRelations)) {
+      const { orderBy, limit, where, hasOne } = relation;
+      const prefix = `[everystack/api] relations.${tableName}.${name}:`;
+      if (hasOne !== undefined) {
+        if (hasOne !== true) throw new Error(`${prefix} hasOne must be true`);
+        if (relation.many) throw new Error(`${prefix} a relation is many or hasOne, not both`);
+        if (limit !== undefined) throw new Error(`${prefix} hasOne returns one row: limit is not allowed`);
+      } else if (orderBy === undefined && limit === undefined && where === undefined) {
+        continue;
+      }
+      if (!relation.many && !hasOne) {
+        throw new Error(`${prefix} orderBy and where apply to a many or hasOne relation only, and limit to a many relation only`);
+      }
+      const target = schema[relation.table];
+      if (!target) {
+        if (!schema[tableName]) continue;
+        throw new Error(`${prefix} target table "${relation.table}" is not in the schema`);
+      }
+      // The key is the last tie-breaker. Without one, two runs could choose different rows.
+      if (hasOne && primaryKeyColumns(target).length === 0) {
+        throw new Error(`${prefix} target table "${relation.table}" has no primary key to break ties`);
+      }
+      const resolves = (column: unknown): boolean => typeof column === 'string' && columnPropertyName(target, column) !== undefined;
+      if (orderBy !== undefined) {
+        if (!Array.isArray(orderBy)) throw new Error(`${prefix} orderBy must be an array of { column, order }`);
+        for (const term of orderBy) {
+          if (!resolves(term?.column)) throw new Error(`${prefix} orderBy column "${term?.column}" is not a column of table "${relation.table}"`);
+          if (term.order !== 'asc' && term.order !== 'desc') throw new Error(`${prefix} orderBy order for "${term.column}" must be 'asc' or 'desc'`);
+        }
+      }
+      if (limit !== undefined && !(typeof limit === 'number' && Number.isInteger(limit) && limit > 0)) {
+        throw new Error(`${prefix} limit must be a positive integer`);
+      }
+      if (where !== undefined) {
+        if (where === null || typeof where !== 'object' || Array.isArray(where)) throw new Error(`${prefix} where must be an object of column → value`);
+        for (const [column, value] of Object.entries(where)) {
+          if (!resolves(column)) throw new Error(`${prefix} where column "${column}" is not a column of table "${relation.table}"`);
+          const valid = value === null || typeof value === 'string' || typeof value === 'boolean'
+            || (typeof value === 'number' && Number.isFinite(value));
+          if (!valid) throw new Error(`${prefix} where value for "${column}" must be a string, a finite number, a boolean or null`);
+        }
+      }
+    }
+  }
+}
+
+/** The target's primary-key columns, in declaration order. Empty for a keyless or non-pg table. */
+function primaryKeyColumns(table: DrizzleTable): DrizzleColumn[] {
+  if (!is(table, PgTable)) return [];
+  const config = getTableConfig(table);
+  const columns = Object.values(getTableColumns(table)) as DrizzleColumn[];
+  const byName = new Map(columns.map(c => [c.name, c]));
+  return [
+    ...columns.filter(c => c.primary),
+    ...config.primaryKeys.flatMap(key => key.columns.map(keyColumn => byName.get(keyColumn.name))),
+  ].filter((c): c is DrizzleColumn => c !== undefined);
+}
+
+/**
+ * A relation's row filter and order, over the target table's own column objects (no config
+ * value reaches SQL text). The filter is the soft-delete guard and the declared where. The
+ * order is the declared orderBy then the primary key, or none when no orderBy, limit or hasOne
+ * is declared. validateRelationDisplay has checked every name.
+ */
+function relationDisplay(
+  relation: RelationConfig,
+  targetTable: DrizzleTable,
+  options?: HandlerOptions,
+  params?: URLSearchParams,
+): { conditions: SQL[]; order: SQL[] } {
+  const column = (name: string): DrizzleColumn => getTableColumns(targetTable)[columnPropertyName(targetTable, name)!] as DrizzleColumn;
+  const conditions: SQL[] = [];
+  const deletedGuard = embedSoftDeleteCondition(relation.table, targetTable, options, params);
+  if (deletedGuard) conditions.push(deletedGuard);
+  for (const [name, value] of Object.entries(relation.where ?? {})) {
+    conditions.push(value === null ? isNull(column(name)) : eq(column(name), value));
+  }
+  const order: SQL[] = [];
+  if (relation.orderBy !== undefined || relation.limit !== undefined || relation.hasOne) {
+    const named = new Set<DrizzleColumn>();
+    for (const term of relation.orderBy ?? []) {
+      named.add(column(term.column));
+      order.push(term.order === 'desc' ? desc(column(term.column)) : asc(column(term.column)));
+    }
+    for (const c of primaryKeyColumns(targetTable)) {
+      if (!named.has(c)) { named.add(c); order.push(asc(c)); }
+    }
+  }
+  return { conditions, order };
+}
+
 /** Resolve hidden columns once so every read uses the same column spellings. */
 function resolveHiddenColumns(schema: Schema, options?: HandlerOptions): HandlerOptions | undefined {
+  const rolesByTable = new Map<DrizzleTable, string[]>();
+  const configuredHidden = { ...options?.hiddenColumns };
+  for (const [tableName, roles] of Object.entries(options?.hiddenColumnsExceptRoles ?? {})) {
+    const table = schema[tableName];
+    if (!table || !Array.isArray(roles) || roles.some(role => typeof role !== 'string' || role === '')) {
+      throw new Error(`[everystack/api] hiddenColumnsExceptRoles.${tableName}: expected a known table and an array of role names`);
+    }
+    const previous = rolesByTable.get(table);
+    if (previous && (previous.length !== roles.length || previous.some(role => !roles.includes(role)))) {
+      throw new Error(`[everystack/api] hiddenColumnsExceptRoles.${tableName}: conflicting role exceptions for one table`);
+    }
+    rolesByTable.set(table, roles);
+    if (isLifecycleTable(tableName, options)) {
+      configuredHidden[tableName] = [...new Set([...(configuredHidden[tableName] ?? []), 'deletedBy', 'deletedBatch', 'deletedXid'])];
+    }
+  }
+  if (options?.hiddenColumnsExceptRoles) options = { ...options, hiddenColumns: configuredHidden };
   if (!options?.hiddenColumns) return options;
   const byTable = new Map<DrizzleTable, Set<string>>();
   for (const [tableName, names] of Object.entries(options.hiddenColumns)) {
@@ -1022,6 +1280,27 @@ function resolveHiddenColumns(schema: Schema, options?: HandlerOptions): Handler
   return { ...options, hiddenColumns };
 }
 
+/** Resolve one request's visibility before query validation and every response path. */
+function hiddenColumnsForUser(schema: Schema, options: HandlerOptions | undefined, user: Record<string, unknown> | null): HandlerOptions | undefined {
+  if (!options?.hiddenColumnsExceptRoles || !user) return options;
+  const role = readRoleClaim(user, options.auth?.roleField ?? 'role');
+  if (!role) return options;
+  const hiddenColumns = Object.fromEntries(Object.entries(options.hiddenColumns ?? {}).map(([tableName, columns]) => {
+    const except = ownEntry(options.hiddenColumnsExceptRoles, tableName);
+    if (!isLifecycleTable(tableName, options) || !except?.includes(role)) return [tableName, columns];
+    const table = schema[tableName];
+    const metadata = new Set<string>();
+    for (const name of ['deleted_by', 'deleted_batch', 'deleted_xid']) {
+      const property = columnPropertyName(table, name);
+      if (!property) continue;
+      const column = getTableColumns(table)[property] as DrizzleColumn;
+      for (const spelling of [property, column.name, toSnakeCase(property), toCamelCase(column.name)]) metadata.add(spelling);
+    }
+    return [tableName, columns.filter(column => !metadata.has(column))];
+  }));
+  return { ...options, hiddenColumns };
+}
+
 /** Safe, fixed client messages. Never derive these from PostgreSQL text or detail. */
 const INTEGRITY_ERRORS: Record<string, { status: number; message: string }> = {
   '23514': { status: 422, message: 'Value does not meet a constraint' },
@@ -1094,6 +1373,11 @@ function mapIntegrityError(
     if (constraint !== undefined) body.constraint = constraint;
     if (code === '23502' && typeof fields.column === 'string') body.column = fields.column;
   }
+  // lifecycle: { deleteWhen }'s guard (`<table>_lifecycle_delete_when`): a stable message, never a
+  // row value. An author's constraintMessages entry for the name still wins.
+  if (declared === undefined && code === '23514' && constraint?.endsWith('_lifecycle_delete_when')) {
+    body.message = "Deleting this row is not allowed by its model's deleteWhen.";
+  }
   // A failing trigger or FK action can name a different table than the URL.
   // Missing driver tables (and unknown RPC policies) use every configured list.
   const driverTable = typeof fields.table === 'string' ? fields.table : undefined;
@@ -1126,6 +1410,7 @@ function validateConstraintMessages(options?: HandlerOptions): void {
 }
 
 export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: HandlerOptions): Handler {
+  refuseReservedHooks(rawOptions);
   // The naming seam: URLs, exposedTables, and relation targets historically mixed
   // drizzle export keys (`texturePacks`) with SQL names (`texture_packs`), and any
   // multi-word table failed one gate or the other — both spellings 404'd. Collapse
@@ -1133,15 +1418,18 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
   // apply. The root listing below stays one entry per table (the SQL name).
   const namePairs = tableNamePairs(rawSchema);
   const schema = expandSchema(rawSchema, namePairs);
-  const options = resolveHiddenColumns(schema, expandTableKeyedOptions(rawOptions, namePairs));
-  validateConstraintMessages(options);
+  const configuredOptions = resolveHiddenColumns(schema, expandTableKeyedOptions(rawOptions, namePairs));
+  validateConstraintMessages(configuredOptions);
   validateRowOwnership(schema, rawOptions);
-  validateSoftDeleteRestore(schema, options);
-  validateSanitizeColumns(schema, options);
+  validateSoftDeleteRestore(schema, configuredOptions);
+  validateSanitizeColumns(schema, configuredOptions);
+  validateRelationDisplay(schema, configuredOptions);
+  validateDrizzleRelationNames(db, configuredOptions);
   const tableNames = new Set(Object.keys(schema));
   const canonicalTables = [...new Set(Object.entries(rawSchema).map(([key, value]) => sqlNameOf(value) ?? key))];
 
   return async (request: Request): Promise<Response> => {
+    let options = configuredOptions;
     const url = new URL(request.url);
     let pathname = url.pathname;
     if (options?.basePath) {
@@ -1212,8 +1500,9 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
     // Root path — table listing, always public. One entry per table (SQL name),
     // regardless of how many spellings route to it.
     if (pathSegments.length === 0) {
-      const tables = options?.exposedTables
-        ? canonicalTables.filter(t => options.exposedTables!.includes(t))
+      const exposedTables = options?.exposedTables;
+      const tables = exposedTables
+        ? canonicalTables.filter(t => exposedTables.includes(t))
         : canonicalTables;
       return json({ tables }, 200);
     }
@@ -1268,6 +1557,7 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           return json({ message: 'Authentication required: no auth token provided' }, 401);
         }
 
+        options = hiddenColumnsForUser(schema, options, user);
         const fn = isObjectForm ? entry.fn : entry;
         const body = method === 'POST' ? await request.json().catch(() => ({})) : {};
         // Request-scoped context for the trace-id spine — RPC handlers receive it
@@ -1416,8 +1706,24 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       }
     }
 
+    options = hiddenColumnsForUser(schema, options, user);
     const table = schema[tableName];
 
+    // POST {table}/restore: a lifecycle table's restore. Before the generic routing, which would
+    // read it as POST {table} (an insert). Any other table has no restore endpoint.
+    if (method === 'POST' && pathSegments.length === 2 && pathSegments[1] === 'restore') {
+      if (!isLifecycleTable(tableName, options)) {
+        return sanitizeError(`Table '${tableName}' has no restore endpoint`, 404, options);
+      }
+      const response = await handleRestore(db, table, tableName, request, options, user, client, requestId);
+      await emitAudit(options?.audit, {
+        kind: 'rest', name: tableName, user, client,
+        result: response.status < 400 ? 'allow' : response.status < 500 ? 'deny' : 'error',
+        requestId, operation: 'update', columns: ['id'],
+      });
+      return response;
+    }
+
     // Forensic audit of the non-GET table surface (writes). Capture the query, not
     // the response: the operation, the WHERE predicate, and the body's column NAMES
     // (never values — values can be PII). Unresolved embed policies also record
@@ -1510,6 +1816,11 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       // 2xx; a throw (a failed commit) skips it, since the write did not happen.
       // A retry wrapper around db.transaction must reset `deferred` per attempt,
       // or the hooks of an aborted attempt would run too.
+      const destroyHook = ownEntry(options?.hooks, tableName);
+      const destroyTransaction = method === 'DELETE'
+        && !isLifecycleTable(tableName, options)
+        && !(isSoftDeleteTable(tableName, table, options) && getSoftDeleteColumn(tableName, table, options))
+        && Boolean(destroyHook?.beforeDestroy || destroyHook?.afterDestroy);
       const deferred: Deferred[] = [];
       let response: Response;
       try {
@@ -1533,7 +1844,7 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           }
 
           return json({ message: `Method ${method} not allowed` }, 405);
-        });
+        }, destroyTransaction);
       } finally {
         // emitFault never throws, so this cannot replace the error in flight.
         for (const item of deferred) if (item.always) await item.run();
@@ -1554,6 +1865,16 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       }
       return response;
     } catch (error) {
+      // A before hook's veto: a decision, not a fault. Its transaction has rolled back.
+      if (error instanceof VetoRefusal) {
+        if (isWrite) {
+          await emitAudit(options?.audit, {
+            kind: 'rest', name: tableName, user, client, result: 'deny',
+            requestId, operation: auditOp, filter: auditFilter, columns: auditColumns,
+          });
+        }
+        return json({ message: error.reason, code: 'vetoed' }, 409);
+      }
       const appError = error instanceof HandlerError;
       const unavailable = !appError && isServiceUnavailable(error);
       const integrity = appError || unavailable ? undefined : mapIntegrityError(error, tableName, options);
@@ -1563,7 +1884,7 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       if (isWrite) {
         await emitAudit(options?.audit, {
           kind: 'rest', name: tableName, user, client,
-          result: mapped || permissionDenied ? 'deny' : 'error',
+          result: mapped || permissionDenied || (error instanceof HandlerError && error.status < 500) ? 'deny' : 'error',
           requestId, operation: auditOp, filter: auditFilter, columns: auditColumns,
         });
       }
@@ -1580,6 +1901,7 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           ...describeError(error),
         });
       }
+      if (error instanceof HandlerError && error.status < 500) return json({ message: error.message }, error.status);
       if (unavailable) return serviceUnavailableResponse();
       throw error;
     }
@@ -1609,6 +1931,7 @@ function buildWithClause(
   tableRelations: Record<string, RelationConfig>,
   schema: Schema,
   options?: HandlerOptions,
+  params?: URLSearchParams,
 ): Record<string, any> | undefined | null | 'unresolvedHiddenColumns' {
   if (embeds.length === 0) return undefined;
 
@@ -1634,6 +1957,13 @@ function buildWithClause(
     } else if (hidden.size > 0) {
       config.columns = Object.fromEntries([...hidden].map(name => [name, false]));
     }
+    // Drizzle maps the target's columns to the join alias. The filter runs before the limit.
+    if (table) {
+      const { conditions, order } = relationDisplay(relation, table, options, params);
+      if (conditions.length > 0) config.where = and(...conditions);
+      if (order.length > 0) config.orderBy = order;
+      if (relation.limit !== undefined) config.limit = relation.limit;
+    }
     withClause[embed.name] = Object.keys(config).length > 0 ? config : true;
   }
 
@@ -1786,7 +2116,7 @@ async function handleGet(
 
   // Soft-delete: filter deleted records unless ?deleted=include|only
   if (isSoftDeleteTable(tableName, table, options)) {
-    const sdCol = getSoftDeleteColumn(table, options);
+    const sdCol = getSoftDeleteColumn(tableName, table, options);
     if (sdCol) {
       const condition = softDeleteCondition(sdCol, params);
       if (condition) conditions.push(condition);
@@ -1864,10 +2194,20 @@ async function handleGet(
       offset: offsetVal,
     };
 
+    // A hasOne never enters `with`: Drizzle's one() cannot order, so it cannot choose the row.
+    // It is attached below from one windowed query, keyed on the parent's `from` column.
+    const oneEmbeds = embeds.filter(embed => ownEntry(tableRelations, embed.name)?.hasOne);
     const colSelection = buildColumnsSelection(columns);
-    if (colSelection) queryOptions.columns = colSelection;
+    const addedKeys: string[] = [];
+    if (colSelection) {
+      for (const embed of oneEmbeds) {
+        const from = tableRelations![embed.name].from;
+        if (!colSelection[from]) { colSelection[from] = true; addedKeys.push(from); }
+      }
+      queryOptions.columns = colSelection;
+    }
 
-    const withClause = buildWithClause(embeds, tableRelations!, schema, options);
+    const withClause = buildWithClause(embeds.filter(embed => !oneEmbeds.includes(embed)), tableRelations!, schema, options, params);
     if (withClause === null || withClause === 'unresolvedHiddenColumns') {
       return json({ message: 'Invalid query' }, 400);
     }
@@ -1882,6 +2222,10 @@ async function handleGet(
     if (order.expressions.length > 0) queryOptions.orderBy = order.expressions;
 
     rows = await (db as any).query[tableName].findMany(queryOptions);
+    if (oneEmbeds.length > 0 && rows.length > 0) {
+      rows = await resolveEmbeds(db, schema, tableName, rows as Record<string, unknown>[], oneEmbeds, options!, params);
+      for (const row of rows as Record<string, unknown>[]) for (const key of addedKeys) delete row[key];
+    }
   } else {
     // Batch path — standard select + separate relation queries
     const order = orderParam === null ? { expressions: [] } : buildOrderBy(table, orderParam, true, undefined, isHidden);
@@ -1927,11 +2271,13 @@ async function handleGet(
   // Resolve relation embeds (batch path only — JOIN path already has nested data)
   let responseData: unknown[] = rows as unknown[];
   if (!useRelationalQuery && embeds.length > 0 && rowCount > 0) {
-    responseData = await resolveEmbeds(db, schema, tableName, rows as Record<string, unknown>[], embeds, options!);
+    responseData = await resolveEmbeds(db, schema, tableName, rows as Record<string, unknown>[], embeds, options!, params);
   }
 
   // Apply column selection (batch path only — JOIN path handles via queryOptions.columns)
   if (!useRelationalQuery && columns) {
+    // An embed that did not resolve was skipped above, and its name may be a real column.
+    const resolvedEmbeds = embeds.filter(embed => resolveEmbedTarget(schema, tableRelations, embed.name));
     responseData = (responseData as Record<string, unknown>[]).map(row => {
       const filtered: Record<string, unknown> = {};
       for (const col of columns) {
@@ -1939,7 +2285,7 @@ async function handleGet(
           filtered[col] = row[col];
         }
       }
-      for (const embed of embeds) {
+      for (const embed of resolvedEmbeds) {
         if (embed.name in row) {
           filtered[embed.name] = row[embed.name];
         }
@@ -2212,6 +2558,33 @@ function resolveEmbedTarget(
   return targetColumn ? { relationConfig, targetTable, targetColumn } : null;
 }
 
+/** The per-parent rank a limited embed is cut on. Dropped from every row. */
+const EMBED_RANK = '__everystack_embed_rank';
+
+/**
+ * The first `cap` target rows per parent key, ranked after the filter in `order`. One windowed
+ * query on the request's own connection. Ordered by rank, so each parent's rows stay in order
+ * through the grouping that follows.
+ */
+async function rankedEmbedRows(
+  db: DrizzleDb,
+  targetTable: DrizzleTable,
+  targetColumn: DrizzleColumn,
+  where: SQL | undefined,
+  order: SQL[],
+  cap: number,
+): Promise<Record<string, unknown>[]> {
+  const orderClause = order.length > 0 ? sql` order by ${sql.join(order, sql`, `)}` : sql``;
+  const ranked = db.$with('embed_ranked').as(db.select({
+    ...getTableColumns(targetTable),
+    [EMBED_RANK]: sql<number>`row_number() over (partition by ${targetColumn}${orderClause})`.as(EMBED_RANK),
+  }).from(targetTable).where(where));
+  return (await db.with(ranked).select().from(ranked)
+    .where(sql`${ranked[EMBED_RANK]} <= ${cap}`)
+    .orderBy(ranked[EMBED_RANK]))
+    .map(({ [EMBED_RANK]: _rank, ...row }: Record<string, unknown>) => row);
+}
+
 /**
  * Resolve relation embeds by fetching related rows and nesting them.
  */
@@ -2222,6 +2595,7 @@ async function resolveEmbeds(
   rows: Record<string, unknown>[],
   embeds: EmbedRequest[],
   options: HandlerOptions,
+  params?: URLSearchParams,
 ): Promise<Record<string, unknown>[]> {
   const tableRelations = ownEntry(options.relations, tableName);
   if (!tableRelations) return rows;
@@ -2243,12 +2617,37 @@ async function resolveEmbeds(
       ...embed.embeds.filter(nested => resolveEmbedTarget(schema, nestedRelations, nested.name)).map(nested => nested.name),
     ];
 
-    // Build soft-delete filter for the target table
-    const targetSdCol = isSoftDeleteTable(relationConfig.table, targetTable, options)
-      ? getSoftDeleteColumn(targetTable, options)
-      : null;
+    // The soft-delete guard for the target table
+    const deletedGuard = embedSoftDeleteCondition(relationConfig.table, targetTable, options, params);
 
-    if (relationConfig.many) {
+    if (relationConfig.hasOne) {
+      // One row per parent: source.from is the parent key, target.to the child FK, as for many.
+      const sourceValues = result.map(r => r[relationConfig.from]).filter(v => v != null);
+      if (sourceValues.length === 0) {
+        for (const row of result) row[embed.name] = null;
+        continue;
+      }
+
+      // The database chooses: the declared where and the soft-delete guard first, then the
+      // first row by the declared order with the key last. Never a fetch of every child.
+      const { conditions, order } = relationDisplay(relationConfig, targetTable, options, params);
+      let relatedRows = await rankedEmbedRows(
+        db, targetTable, targetColumn, and(inArray(targetColumn, sourceValues as string[]), ...conditions), order, 1,
+      );
+
+      if (embed.embeds.length > 0) {
+        relatedRows = await resolveEmbeds(db, schema, relationConfig.table, relatedRows, embed.embeds, options, params);
+      }
+
+      // Match on the key, then strip: the key may itself be a hidden column.
+      const index = new Map<unknown, Record<string, unknown>>();
+      for (const r of relatedRows) index.set(r[relationConfig.to], visibleRow(r, relationConfig.table, options));
+      for (const row of result) {
+        const sourceVal = row[relationConfig.from];
+        const related = sourceVal == null ? null : index.get(sourceVal) ?? null;
+        row[embed.name] = related && picked ? pickColumns(related, picked) : related;
+      }
+    } else if (relationConfig.many) {
       // One-to-many: source.from is the PK, target.to is the FK
       // Collect all source PKs
       const sourceValues = result
@@ -2264,24 +2663,31 @@ async function resolveEmbeds(
       }
 
       // Fetch all related rows in one query
-      const embedConditions: any[] = [inArray(targetColumn, sourceValues as string[])];
-      if (targetSdCol) embedConditions.push(isNull(targetSdCol));
-
-      let relatedRows: Record<string, unknown>[] = await db
-        .select()
-        .from(targetTable)
-        .where(embedConditions.length === 1 ? embedConditions[0] : and(...embedConditions));
-      relatedRows = stripHiddenColumns(relatedRows, relationConfig.table, options) as Record<string, unknown>[];
+      const { conditions, order } = relationDisplay(relationConfig, targetTable, options, params);
+      const embedConditions: any[] = [inArray(targetColumn, sourceValues as string[]), ...conditions];
+      const embedWhere = embedConditions.length === 1 ? embedConditions[0] : and(...embedConditions);
+
+      let relatedRows: Record<string, unknown>[];
+      if (relationConfig.limit !== undefined) {
+        // Rank each parent's rows after the filter, then keep the first `limit` per parent.
+        relatedRows = await rankedEmbedRows(db, targetTable, targetColumn, embedWhere, order, relationConfig.limit);
+      } else {
+        const query = db.select().from(targetTable).where(embedWhere);
+        relatedRows = await (order.length > 0 ? query.orderBy(...order) : query);
+      }
 
       // Recursively resolve nested embeds
       if (embed.embeds.length > 0) {
-        relatedRows = await resolveEmbeds(db, schema, relationConfig.table, relatedRows, embed.embeds, options);
+        relatedRows = await resolveEmbeds(db, schema, relationConfig.table, relatedRows, embed.embeds, options, params);
       }
 
-      // Group by FK value and assign to each source row
+      // Group by FK value and assign to each source row. Match on the key, then strip: the key
+      // may itself be a hidden column.
       for (const row of result) {
         const sourceVal = row[relationConfig.from];
-        const matched = relatedRows.filter(r => r[relationConfig.to] === sourceVal);
+        const matched = relatedRows
+          .filter(r => r[relationConfig.to] === sourceVal)
+          .map(r => visibleRow(r, relationConfig.table, options));
         row[embed.name] = picked ? matched.map(r => pickColumns(r, picked)) : matched;
       }
     } else {
@@ -2301,23 +2707,23 @@ async function resolveEmbeds(
 
       // Fetch all referenced rows in one query (batch, no N+1)
       const embedConditions: any[] = [inArray(targetColumn, fkValues as string[])];
-      if (targetSdCol) embedConditions.push(isNull(targetSdCol));
+      if (deletedGuard) embedConditions.push(deletedGuard);
 
       let relatedRows: Record<string, unknown>[] = await db
         .select()
         .from(targetTable)
         .where(embedConditions.length === 1 ? embedConditions[0] : and(...embedConditions));
-      relatedRows = stripHiddenColumns(relatedRows, relationConfig.table, options) as Record<string, unknown>[];
 
       // Recursively resolve nested embeds
       if (embed.embeds.length > 0) {
-        relatedRows = await resolveEmbeds(db, schema, relationConfig.table, relatedRows, embed.embeds, options);
+        relatedRows = await resolveEmbeds(db, schema, relationConfig.table, relatedRows, embed.embeds, options, params);
       }
 
-      // Index by target key for O(1) lookup
+      // Index by target key for O(1) lookup. Match on the key, then strip: the key may itself
+      // be a hidden column.
       const index = new Map<unknown, Record<string, unknown>>();
       for (const r of relatedRows) {
-        index.set(r[relationConfig.to], r);
+        index.set(r[relationConfig.to], visibleRow(r, relationConfig.table, options));
       }
 
       // Assign to each source row
@@ -2336,6 +2742,11 @@ async function resolveEmbeds(
   return result;
 }
 
+/** One embedded row without its table's hidden columns. */
+function visibleRow(row: Record<string, unknown>, tableName: string, options: HandlerOptions): Record<string, unknown> {
+  return stripHiddenColumns(row, tableName, options) as Record<string, unknown>;
+}
+
 function pickColumns(row: Record<string, unknown>, columns: string[]): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   for (const col of columns) {
@@ -2551,6 +2962,12 @@ async function handlePatch(
   const scope = ownershipScope(table, tableName, options, user);
   if ('refusal' in scope) return scope.refusal;
 
+  // A lifecycle row is restored by its own function, on its delete rule, never by a PATCH.
+  const requestedDeleted = params.get('deleted');
+  if (isLifecycleTable(tableName, options) && (requestedDeleted === 'include' || requestedDeleted === 'only')) {
+    return json({ message: `PATCH does not accept ?deleted= on ${tableName}: restore a deleted row with POST ${restorePath(tableName, options)} { "id": <id> }` }, 400);
+  }
+
   let body: Record<string, unknown>;
   try {
     body = await request.json();
@@ -2575,7 +2992,7 @@ async function handlePatch(
 
   // Restore: ?deleted=include|only is honoured only for a role in softDelete.restore for
   // this table. Anyone else is matched to live rows, as if the param were absent.
-  const sdCol = isSoftDeleteTable(tableName, table, options) ? getSoftDeleteColumn(table, options) : null;
+  const sdCol = isSoftDeleteTable(tableName, table, options) ? getSoftDeleteColumn(tableName, table, options) : null;
   const restoring = sdCol !== null && mayRestore(tableName, options, user);
   const deletedMode = params.get('deleted');
   if (restoring && (deletedMode === 'include' || deletedMode === 'only')) {
@@ -2820,9 +3237,43 @@ async function handleDelete(
   // Row ownership: AND WHERE <column> = user[<userField>] for IDOR protection
   if (scope.condition) conditions.push(scope.condition);
 
+  // Lifecycle: a real DELETE, which the table's trigger turns into a stamp (it reports 0 rows).
+  if (isLifecycleTable(tableName, options)) {
+    let stamped: Awaited<ReturnType<typeof lifecycleDelete>>;
+    try {
+      stamped = await lifecycleDelete(db, table, tableName, conditions, options, hook?.beforeStamp
+        ? { run: hook.beforeStamp.bind(hook), ctx: { phase: 'stamp', source: 'api', batch: null, user, client } } : undefined);
+    } catch (err) {
+      // Its transaction has rolled back: nothing was stamped.
+      if (err instanceof BeforeHookThrew) return beforeHookFailure(err.thrown, options, { requestId, name: `${tableName}.beforeStamp`, method: 'DELETE' }, deferred);
+      throw err;
+    }
+    const { rows, batchOf } = stamped;
+    // The pre-image carries deletedBatch NULL; give each root its batch. stripHiddenColumns keeps
+    // it for a plain manage role only.
+    const batchKey = columnPropertyName(table, LIFECYCLE_DELETED_BATCH);
+    if (batchKey) for (const [row, batch] of batchOf) row[batchKey] = batch;
+    if (hook?.afterDelete && rows.length > 0) {
+      const { afterDelete } = hook;
+      deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDelete`, method: 'DELETE' },
+        () => afterDelete.call(hook, rows, user, client));
+    }
+    if (hook?.afterStamp && batchOf.size > 0) {
+      const { afterStamp } = hook;
+      const roots = new Map<string, Record<string, unknown>[]>();
+      for (const [row, batch] of batchOf) roots.set(batch, [...(roots.get(batch) ?? []), row]);
+      for (const [batch, batchRoots] of roots) {
+        const ctx: LifecycleContext = { phase: 'stamp', source: 'api', batch, user, client };
+        deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterStamp`, method: 'DELETE' },
+          async () => { await afterStamp.call(hook, batchRoots, ctx); });
+      }
+    }
+    return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
+  }
+
   // Soft-delete: convert DELETE to UPDATE SET deleted_at = NOW()
   if (isSoftDeleteTable(tableName, table, options)) {
-    const sdCol = getSoftDeleteColumn(table, options);
+    const sdCol = getSoftDeleteColumn(tableName, table, options);
     if (sdCol) {
       // Only soft-delete records that aren't already deleted
       conditions.push(isNull(sdCol));
@@ -2856,7 +3307,24 @@ async function handleDelete(
     query = query.where(and(...conditions));
   }
 
-  const rows = await query.returning();
+  const rows: Record<string, unknown>[] = await query.returning();
+
+  // RETURNING proves DELETE authority, including policies that differ from SELECT.
+  // The dispatcher keeps this statement and beforeDestroy in one caller transaction.
+  // A veto throws out of the caller transaction, so the DELETE rolls back; the dispatcher answers 409.
+  const ctx: DestroyContext = { phase: 'destroy', source: 'api', batch: null, user, client };
+  for (const row of rows) {
+    if (!hook?.beforeDestroy) break;
+    const verdict = await hook.beforeDestroy(row, ctx);
+    if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
+  }
+  if (hook?.afterDestroy) {
+    const { afterDestroy } = hook;
+    for (const row of rows) {
+      deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDestroy`, method: 'DELETE' },
+        async () => { await afterDestroy.call(hook, row, ctx); });
+    }
+  }
 
   if (hook?.afterDelete && rows.length > 0) {
     const { afterDelete } = hook;
@@ -2867,6 +3335,166 @@ async function handleDelete(
   return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
 }
 
+/**
+ * DELETE on a lifecycle table. The trigger stamps each row and cancels its delete, so DELETE
+ * reports 0 rows and RETURNING has nothing. In one transaction: read the live rows the request
+ * matches (the pre-image), run beforeStamp on each, DELETE those keys only (with the same
+ * conditions), then drop every row still live: RLS or the filter refused its delete. What is left is
+ * the pre-image of the rows this request soft-deleted. The read takes no lock, so a hook sees the
+ * row as read; a rule that must hold on the stamped values belongs in deleteWhen, which the trigger
+ * checks on the current row. Under READ COMMITTED a row another request stamps between the read
+ * and the DELETE is still listed (and reaches afterDelete): a false attribution, never a leak.
+ */
+async function lifecycleDelete(
+  db: DrizzleDb,
+  table: DrizzleTable,
+  tableName: string,
+  conditions: SQL[],
+  options?: HandlerOptions,
+  beforeStamp?: { run: BeforeLifecycleHook; ctx: LifecycleContext },
+): Promise<{ rows: Record<string, unknown>[]; batchOf: Map<Record<string, unknown>, string> }> {
+  const sdCol = getSoftDeleteColumn(tableName, table, options);
+  const pk = primaryKeyColumns(table);
+  const key = pk.length === 1 ? columnPropertyName(table, pk[0].name) : undefined;
+  if (!sdCol || key === undefined) {
+    throw new Error(`[everystack/api] softDelete.lifecycle.${tableName}: the table needs a ${LIFECYCLE_DELETED_AT} column and a single-column primary key`);
+  }
+  const keyColumn = getTableColumns(table)[key];
+  const batchOf = new Map<Record<string, unknown>, string>();
+  const rows = await db.transaction(async (tx: DrizzleDb) => {
+    // No row lock: FOR UPDATE needs UPDATE privilege, which a delete-only role does not hold.
+    const matched: Record<string, unknown>[] = await tx.select().from(table).where(and(...conditions, isNull(sdCol)));
+    if (matched.length === 0) return [];
+    // beforeStamp: once per matched root, before the DELETE, inside this transaction. A veto or a
+    // throw leaves it, so nothing is stamped.
+    if (beforeStamp) {
+      for (const row of matched) {
+        let verdict: unknown;
+        try { verdict = await beforeStamp.run(row, beforeStamp.ctx); } catch (err) { throw new BeforeHookThrew(err); }
+        if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
+      }
+    }
+    // The transition appends one `<JSON key> <batch>` line per stamped root to this setting (a
+    // caller that is not a manage role cannot read deleted_batch). Cleared first, so only this
+    // DELETE's lines are read back; informational, the stamp columns stay the truth.
+    await tx.execute(sql`SELECT pg_catalog.set_config('everystack.lifecycle_batch', '', true)`);
+    // Exactly the rows the hook saw: a row that starts to match while a hook runs is not stamped.
+    // The request filter stays, so a matched row edited out of it meanwhile is not stamped either.
+    const matchedKeys = matched.map(row => row[key]);
+    await tx.delete(table).where(and(...conditions, isNull(sdCol), inArray(keyColumn, matchedKeys)));
+    const stillLive: Record<string, unknown>[] = await tx
+      .select({ [key]: keyColumn })
+      .from(table)
+      .where(and(isNull(sdCol), inArray(keyColumn, matchedKeys)));
+    const lines = await tx.execute(sql`SELECT pg_catalog.current_setting('everystack.lifecycle_batch', true) AS v`) as unknown as Array<{ v: string | null }>;
+    const byKey = new Map<string, string>();
+    for (const line of String(lines[0]?.v ?? '').split('\n')) {
+      if (line.length < 38) continue;
+      try { byKey.set(String(JSON.parse(line.slice(0, -37))), line.slice(-36)); } catch { /* not a line the transition wrote */ }
+    }
+    const live = new Set(stillLive.map(row => String(row[key])));
+    const stamped = matched.filter(row => !live.has(String(row[key])));
+    for (const row of stamped) {
+      const batch = byKey.get(String(row[key]));
+      if (batch) batchOf.set(row, batch);
+    }
+    return stamped;
+  });
+  return { rows, batchOf };
+}
+
+/**
+ * POST {table}/restore { id } on a lifecycle table: `<schema>.<table>_restore(id)` inside the
+ * request's pgSettings transaction, so the function sees the caller's role and claims and decides
+ * on the table's delete rule. The id is bound and cast to the key's type, so an author's own
+ * overload of the name is never chosen. 42501 (the function's one refusal) is 403 with its
+ * message; 55000 (not READ COMMITTED) is 409; 22P02 (an id the key type cannot read) is 400.
+ */
+async function handleRestore(
+  db: DrizzleDb,
+  table: DrizzleTable,
+  tableName: string,
+  request: Request,
+  options: HandlerOptions | undefined,
+  user: Record<string, unknown> | null,
+  client: Record<string, unknown> | null,
+  requestId: string | undefined,
+): Promise<Response> {
+  const body: unknown = await request.json().catch(() => undefined);
+  const id = body !== null && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>).id : undefined;
+  if (!(typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id)))) {
+    return json({ message: 'restore requires a JSON body { "id": <id> }' }, 400);
+  }
+  const [key] = primaryKeyColumns(table);
+  const keyType = key ? restoreArgType(key) : null;
+  const name = sqlNameOf(table);
+  if (!keyType || name === null || primaryKeyColumns(table).length !== 1) {
+    const message = `[everystack/api] softDelete.lifecycle.${tableName}: restore needs a table with a single-column primary key of a plain type`;
+    await emitFault(options?.onError, { requestId, kind: 'rest', name: tableName, method: 'POST', status: 500, message });
+    return json({ message: options?.hideSchemaErrors ? 'Internal Server Error' : message }, 500);
+  }
+  const fn = sql`${sql.identifier(getTableConfig(table).schema ?? 'public')}.${sql.identifier(`${name}_restore`)}`;
+  try {
+    const result = await executeWithSettings(db, options?.pgSettings?.(user, client), async (tx) => {
+      const rows = await tx.execute(sql`SELECT ${fn}(CAST(${id} AS ${sql.raw(keyType)})) AS result`);
+      return (rows as unknown as Array<{ result: unknown }>)[0]?.result;
+    });
+    // After the commit (executeWithSettings has returned). Best-effort: never changes the response.
+    const hook = ownEntry(options?.hooks, tableName);
+    const r = result as { restored?: unknown; skipped?: unknown; batch?: unknown } | null;
+    if (hook?.afterRestore && r && typeof r.batch === 'string') {
+      try {
+        await hook.afterRestore([{ [columnPropertyName(table, key.name) ?? key.name]: id }], {
+          phase: 'restore', source: 'api', batch: r.batch, user, client,
+          counts: { restored: Number(r.restored), skipped: Number(r.skipped) },
+        });
+      } catch (err) {
+        await reportHookFault(options?.onError, { requestId, name: `${tableName}.afterRestore`, method: 'POST' }, err);
+      }
+    }
+    return json(result, 200);
+  } catch (error) {
+    // Code and message from the one object that carries the code: a wrapper's message can quote the query.
+    const carrier = pgErrorCarrier(error);
+    const code = carrier && safeRead(carrier, 'code') as string;
+    const text = carrier && safeRead(carrier, 'message');
+    const message = typeof text === 'string' ? text : '';
+    if (code === '42501') return sanitizeError(message || 'Permission denied', 403, options);
+    if (code === '55000') return json({ message, code }, 409);
+    if (code === '22P02') return json({ message: 'Invalid id', code }, 400);
+    if (isServiceUnavailable(error)) return serviceUnavailableResponse();
+    await emitFault(options?.onError, { requestId, kind: 'rest', name: tableName, method: 'POST', status: 500, ...describeError(error) });
+    return json({ message: options?.hideSchemaErrors ? 'Internal Server Error' : 'Restore failed' }, 500);
+  }
+}
+
+/** The first object on the error's cause chain with a string `code` (drivers and wrappers nest it). */
+function pgErrorCarrier(error: unknown): object | undefined {
+  let current: unknown = error;
+  for (let hop = 0; hop <= MAX_CAUSE_HOPS && current !== null && typeof current === 'object'; hop++) {
+    if (typeof safeRead(current, 'code') === 'string') return current;
+    const cause = safeRead(current, 'cause');
+    if (cause === UNREADABLE || cause === current) return undefined;
+    current = cause;
+  }
+  return undefined;
+}
+
+/**
+ * The SQL type the restore id is cast to: the key column's declared type, a serial read as its
+ * integer type. Null for a type text this function will not put in SQL.
+ */
+function restoreArgType(column: DrizzleColumn): string | null {
+  const declared = String((column as { getSQLType?: () => string }).getSQLType?.() ?? '').trim().toLowerCase();
+  const type = ({ serial: 'integer', smallserial: 'smallint', bigserial: 'bigint' } as Record<string, string>)[declared] ?? declared;
+  return /^[a-z][a-z0-9_ ]*(\(\d+(, ?\d+)?\))?$/.test(type) ? type : null;
+}
+
+/** The restore endpoint's path, as a client calls it. */
+function restorePath(tableName: string, options?: HandlerOptions): string {
+  return `${(options?.basePath ?? '').replace(/\/+$/, '')}/${tableName}/restore`;
+}
+
 interface JsonPath {
   baseColumn: string;
   steps: Array<{ key: string; asText: boolean }>;

package/src/handler/veto.ts

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