@everystack/api 0.4.9 → 0.4.11

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [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
+
+- an aggregate inside an embed (author(count())) answers 400 instead of being dropped, on every verb including writes that carry such a select
+- a nested embed on the join path (drizzleRelations) answers 400 instead of being dropped, on every verb including writes that carry such a select; the batch path now keeps nested embeds and accepts snake_case embed column names
+
+### Fixed
+
+- table-keyed option maps are read by own key, so a table named constructor reads no prototype value
+
 ## [0.4.9] - 2026-10-18
 
 ### BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "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,15 @@ 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 }`. */
+  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;
 }
 
 export interface Client {
@@ -270,6 +279,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

@@ -216,7 +216,11 @@ export interface AuthConfig {
   /** Ordered role hierarchy, lowest to highest privilege.
    *  Used by RPC role gating. Default: ['public', 'authenticated', 'admin'] */
   roleHierarchy?: string[];
-  /** Field in the user payload containing the role string. Used by RPC role gating. Default: 'role' */
+  /** Field in the user payload containing the role string. Default: 'role'
+   *  `roleField` must hold one string. A missing, non-string or array value is treated as
+   *  no role and fails every gate; if your tokens carry several roles, collapse them to one
+   *  in `auth.verifyToken` before the payload reaches the handler, so the RPC, ownership,
+   *  restore (`PATCH ?deleted=`) gates and your `pgSettings` all read the same value. */
   roleField?: string;
 }
 
@@ -229,6 +233,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 {
@@ -241,10 +259,28 @@ 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[];
+}
+
+/** Context for a real removal. External effects must be idempotent across retries. */
+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 HookConfig {
   /** Called before INSERT. Can modify the body (e.g., inject userId). Throw to abort. */
   beforeCreate?: (body: Record<string, unknown>, user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<Record<string, unknown>>;
@@ -258,6 +294,14 @@ 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. 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;
 }
 
 /** Cache-Control header configuration for different response categories. */
@@ -339,7 +383,8 @@ export interface HandlerOptions {
   drizzleRelations?: Record<string, unknown>;
   /** Compute PostgreSQL session variables from the authenticated user.
    *  When provided, queries are wrapped in a transaction with set_config() calls
-   *  so RLS policies can reference the user context. */
+   *  so RLS policies can reference the user context.
+   *  Read the same field `roleField` names. Do not derive the database role from a different claim. */
   pgSettings?: (user: Record<string, unknown> | null, client?: Record<string, unknown> | null) => Record<string, string>;
   /** Per-table lifecycle hooks for mutations. */
   hooks?: Record<string, HookConfig>;
@@ -361,6 +406,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[]>;
@@ -410,8 +461,16 @@ 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';
+
+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);
 }
@@ -429,11 +488,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);
 }
 
 /**
@@ -452,17 +529,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)`);
         }
@@ -587,11 +665,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;
@@ -637,7 +715,7 @@ function stripProtectedFields(
   tableName: string,
   options?: HandlerOptions,
 ): unknown {
-  const fields = options?.protectedFields?.[tableName];
+  const fields = ownEntry(options?.protectedFields, tableName);
   if (!fields || fields.length === 0) return body;
   if (Array.isArray(body)) return body.map(row => stripProtectedFields(row, tableName, options));
   if (body === null || typeof body !== 'object') {
@@ -655,7 +733,7 @@ function stripHiddenColumns(
   tableName: string,
   options?: HandlerOptions,
 ): unknown {
-  const columns = options?.hiddenColumns?.[tableName];
+  const columns = ownEntry(options?.hiddenColumns, tableName);
   if (!columns || columns.length === 0) return data;
 
   const strip = (row: Record<string, unknown>): Record<string, unknown> => {
@@ -835,6 +913,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) } : {}),
@@ -846,6 +925,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) } : {}),
         },
       }
       : {}),
@@ -865,6 +945,7 @@ 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));
 }
@@ -917,6 +998,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);
@@ -928,7 +1014,7 @@ function validateSoftDeleteRestore(schema: Schema, options: HandlerOptions | und
     const sameColumn = (field: string): boolean => (table
       ? getColumn(table, field) !== null && getColumn(table, field) === getColumn(table, colName)
       : toSnakeCase(field) === toSnakeCase(colName));
-    if (roles.length > 0 && (options?.protectedFields?.[tableName] ?? []).some(sameColumn)) {
+    if (roles.length > 0 && (ownEntry(options?.protectedFields, tableName) ?? []).some(sameColumn)) {
       throw new Error(
         `[everystack/api] softDelete.restore.${tableName}: the soft-delete column "${colName}" is in protectedFields.${tableName}, so every restore body is stripped to {}. Remove it from protectedFields.${tableName} or remove the restore entry.`,
       );
@@ -942,7 +1028,7 @@ function validateSoftDeleteRestore(schema: Schema, options: HandlerOptions | und
  * non-string role claim is not a member.
  */
 function mayRestore(tableName: string, options: HandlerOptions | undefined, user: Record<string, unknown> | null): boolean {
-  const roles = options?.softDelete?.restore?.[tableName];
+  const roles = ownEntry(options?.softDelete?.restore, tableName);
   if (!roles?.length || !user) return false;
   const role = readRoleClaim(user, options?.auth?.roleField ?? 'role');
   return role !== '' && roles.includes(role);
@@ -984,8 +1070,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)) {
@@ -1017,6 +1243,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' },
@@ -1128,15 +1375,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) {
@@ -1207,8 +1457,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);
     }
@@ -1263,6 +1514,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
@@ -1411,8 +1663,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
@@ -1453,15 +1721,22 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
 
       // A part with parentheses is an aggregate or a declared embed. Anything
       // else cannot be honored, so refuse it rather than drop it from the rows.
+      // An aggregate inside an embed cannot be honored either, nor can a nested
+      // embed on the JOIN path: its `with` clause is one level deep.
       const tableRelations = ownEntry(options?.relations, tableName);
       if (!queryError) {
+        const joinPath = relationalQueryAvailable(routedDb, tableName, options);
         for (const selectParam of url.searchParams.getAll('select')) {
-          const { undeclared } = parseSelectParam(selectParam, tableRelations, options?.relations);
+          const { undeclared, embedAggregate, nestedEmbed } = parseSelectParam(selectParam, tableRelations, options?.relations);
           if (undeclared !== undefined) {
             queryError = undeclaredSelectPartMessage(undeclared);
             queryErrorEchoesInput = true;
             break;
           }
+          if (embedAggregate || (nestedEmbed && joinPath)) {
+            queryError = 'Invalid query';
+            break;
+          }
         }
       }
 
@@ -1498,6 +1773,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 {
@@ -1521,7 +1801,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();
@@ -1551,7 +1831,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,
         });
       }
@@ -1568,6 +1848,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;
     }
@@ -1583,12 +1864,21 @@ function columnPropertyName(table: DrizzleTable | undefined, name: string): stri
     ?? columns.find(([, value]) => (value as DrizzleColumn).name === name)?.[0];
 }
 
+/**
+ * A read with embeds takes the JOIN path when this holds. The pre-DB refusal of
+ * a nested embed and handleGet both ask it, so the two cannot disagree.
+ */
+function relationalQueryAvailable(db: DrizzleDb, tableName: string, options?: HandlerOptions): boolean {
+  return Boolean(ownEntry(options?.relations, tableName) && options?.drizzleRelations && (db as any).query?.[tableName]);
+}
+
 /** Build each relation's projection before Drizzle reads its values. */
 function buildWithClause(
   embeds: EmbedRequest[],
   tableRelations: Record<string, RelationConfig>,
   schema: Schema,
   options?: HandlerOptions,
+  params?: URLSearchParams,
 ): Record<string, any> | undefined | null | 'unresolvedHiddenColumns' {
   if (embeds.length === 0) return undefined;
 
@@ -1600,7 +1890,7 @@ function buildWithClause(
     if (!relation) continue;
     hasEmbedded = true;
     const table = schema[relation.table];
-    const names = new Set(options?.hiddenColumns?.[relation.table] ?? []);
+    const names = new Set(ownEntry(options?.hiddenColumns, relation.table) ?? []);
     const hidden = new Set(table ? Object.keys(getTableColumns(table)).filter(name => names.has(name)) : []);
     const config: Record<string, any> = {};
     if (embed.columns !== null) {
@@ -1614,6 +1904,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;
   }
 
@@ -1766,7 +2063,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);
@@ -1829,10 +2126,7 @@ async function handleGet(
 
   // Detect if Drizzle relational query (JOINs) should be used
   const tableRelations = ownEntry(options?.relations, tableName);
-  const useRelationalQuery = embeds.length > 0
-    && tableRelations
-    && options?.drizzleRelations
-    && (db as any).query?.[tableName];
+  const useRelationalQuery = embeds.length > 0 && relationalQueryAvailable(db, tableName, options);
 
   let rows: unknown[];
   const isHidden = (column: string): boolean => isHiddenColumn(schema, tableName, column, options);
@@ -1847,10 +2141,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);
     }
@@ -1865,6 +2169,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);
@@ -1910,11 +2218,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) {
@@ -1922,7 +2232,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];
         }
@@ -1983,7 +2293,7 @@ function parseSelectParam(
   selectParam: string | null,
   tableRelations?: Record<string, RelationConfig>,
   allRelations?: Record<string, Record<string, RelationConfig>>,
-): { columns: string[] | null; embeds: EmbedRequest[]; aggregates: AggregateField[]; undeclared?: string } {
+): { columns: string[] | null; embeds: EmbedRequest[]; aggregates: AggregateField[]; undeclared?: string; embedAggregate?: true; nestedEmbed?: true } {
   if (!selectParam) {
     return { columns: null, embeds: [], aggregates: [] };
   }
@@ -1995,6 +2305,11 @@ function parseSelectParam(
   // The first part with parentheses that is neither an aggregate nor a declared
   // embed, at any depth. The caller refuses the select; it is never a column.
   let undeclared: string | undefined;
+  // Aggregates exist at the top level only. One inside an embed, at any depth,
+  // cannot be honored, so the caller refuses the select.
+  let embedAggregate = false;
+  // An embed inside an embed, at any depth. The JOIN path cannot honour one yet.
+  let nestedEmbed = false;
 
   // Parse: split on commas, but respect parentheses
   const parts = splitSelectParam(selectParam);
@@ -2019,6 +2334,8 @@ function parseSelectParam(
       const targetRelations = ownEntry(allRelations, targetTableName);
       const inner = parseSelectParam(innerSelect, targetRelations, allRelations);
       undeclared ??= inner.undeclared;
+      if (inner.aggregates.length > 0 || inner.embedAggregate) embedAggregate = true;
+      if (inner.embeds.length > 0) nestedEmbed = true;
       embeds.push({
         name,
         columns: inner.columns,
@@ -2038,6 +2355,8 @@ function parseSelectParam(
     embeds,
     aggregates,
     ...(undeclared === undefined ? {} : { undeclared }),
+    ...(embedAggregate ? { embedAggregate: true as const } : {}),
+    ...(nestedEmbed ? { nestedEmbed: true as const } : {}),
   };
 }
 
@@ -2172,6 +2491,47 @@ function requestUsesHiddenColumn(
   return false;
 }
 
+/** The relation an embed names, when its target table and key exist. resolveEmbeds skips any other. */
+function resolveEmbedTarget(
+  schema: Schema,
+  tableRelations: Record<string, RelationConfig> | undefined,
+  name: string,
+): { relationConfig: RelationConfig; targetTable: DrizzleTable; targetColumn: DrizzleColumn } | null {
+  const relationConfig = ownEntry(tableRelations, name);
+  if (!relationConfig) return null;
+  const targetTable = schema[relationConfig.table];
+  if (!targetTable) return null;
+  const targetColumn = getColumn(targetTable, relationConfig.to);
+  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.
  */
@@ -2182,6 +2542,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;
@@ -2190,21 +2551,50 @@ async function resolveEmbeds(
   const result = rows.map(r => ({ ...r }));
 
   for (const embed of embeds) {
-    const relationConfig = tableRelations[embed.name];
-    if (!relationConfig) continue;
-
-    const targetTable = schema[relationConfig.table];
-    if (!targetTable) continue;
+    const target = resolveEmbedTarget(schema, tableRelations, embed.name);
+    if (!target) continue;
+    const { relationConfig, targetTable, targetColumn } = target;
+
+    // Rows are keyed by schema property, so pick by property name, as
+    // buildWithClause does. A nested embed is kept only when it resolves: an
+    // unresolved one is skipped below, and its name may be a real column.
+    const nestedRelations = ownEntry(options.relations, relationConfig.table);
+    const picked = embed.columns && [
+      ...embed.columns.map(name => columnPropertyName(targetTable, name)).filter((name): name is string => name !== undefined),
+      ...embed.embeds.filter(nested => resolveEmbedTarget(schema, nestedRelations, nested.name)).map(nested => nested.name),
+    ];
+
+    // The soft-delete guard for the target table
+    const deletedGuard = embedSoftDeleteCondition(relationConfig.table, targetTable, options, params);
+
+    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;
+      }
 
-    const targetColumn = getColumn(targetTable, relationConfig.to);
-    if (!targetColumn) 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,
+      );
 
-    // Build soft-delete filter for the target table
-    const targetSdCol = isSoftDeleteTable(relationConfig.table, targetTable, options)
-      ? getSoftDeleteColumn(targetTable, options)
-      : null;
+      if (embed.embeds.length > 0) {
+        relatedRows = await resolveEmbeds(db, schema, relationConfig.table, relatedRows, embed.embeds, options, params);
+      }
 
-    if (relationConfig.many) {
+      // 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
@@ -2220,27 +2610,32 @@ 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);
-        row[embed.name] = embed.columns
-          ? matched.map(r => pickColumns(r, embed.columns!))
-          : matched;
+        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 {
       // Many-to-one: source.from is the FK, target.to is the PK
@@ -2259,23 +2654,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
@@ -2285,7 +2680,7 @@ async function resolveEmbeds(
           row[embed.name] = null;
         } else {
           const related = index.get(fkVal) || null;
-          row[embed.name] = related && embed.columns ? pickColumns(related, embed.columns) : related;
+          row[embed.name] = related && picked ? pickColumns(related, picked) : related;
         }
       }
     }
@@ -2294,6 +2689,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) {
@@ -2371,10 +2771,10 @@ function sanitizeWriteBody(
   at: { requestId?: string; name: string; method: string },
   deferred: Deferred[],
 ): { body: unknown; changed: string[] } | { refusal: Response } {
-  const columns = options?.sanitizeColumns?.[tableName];
+  const columns = ownEntry(options?.sanitizeColumns, tableName);
   if (!columns?.length) return { body, changed: [] };
   const keys = [...new Set(columns.map(name => columnPropertyName(table, name)!))];
-  const hidden = new Set((options?.hiddenColumns?.[tableName] ?? []).map(name => columnPropertyName(table, name)));
+  const hidden = new Set((ownEntry(options?.hiddenColumns, tableName) ?? []).map(name => columnPropertyName(table, name)));
   const refuse = (message: string, column: string): { refusal: Response } => {
     const fault: HandlerFault = {
       ...at, kind: 'rest', status: 500, table: sqlNameOf(table)!, column, message,
@@ -2456,7 +2856,7 @@ async function handlePost(
     throw err;
   }
 
-  const hook = options?.hooks?.[tableName];
+  const hook = ownEntry(options?.hooks, tableName);
 
   if (hook?.beforeCreate) {
     try {
@@ -2509,6 +2909,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();
@@ -2533,7 +2939,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')) {
@@ -2550,7 +2956,7 @@ async function handlePatch(
 
   // With the ownership backstop lifted, an unfiltered PATCH would write every row the
   // role's RLS allows. Refuse it, the same filter test DELETE applies to every caller.
-  const ownership = options?.rowOwnership?.[tableName];
+  const ownership = ownEntry(options?.rowOwnership, tableName);
   if (user && options && ownership && isOwnershipExempt(ownership, user, options)
     && buildsNoFilter(table, params)) {
     return json({ message: 'PATCH requires at least one filter when the ownership backstop is lifted for your role' }, 400);
@@ -2574,7 +2980,7 @@ async function handlePatch(
     return sanitizeError(filterResult.error, 400, options);
   }
 
-  const hook = options?.hooks?.[tableName];
+  const hook = ownEntry(options?.hooks, tableName);
 
   if (hook?.beforeUpdate) {
     try {
@@ -2666,7 +3072,7 @@ function unbackedExemptionRefusal(
   settings: Record<string, string> | undefined,
 ): string | null {
   if (method !== 'PATCH' && method !== 'DELETE') return null;
-  const ownership = options?.rowOwnership?.[tableName];
+  const ownership = ownEntry(options?.rowOwnership, tableName);
   if (!options || !ownership || !user || !isOwnershipExempt(ownership, user, options)) return null;
   if (settings?.['role']) return null;
   const message = `rowOwnership.${tableName}.exceptRoles: pgSettings returned no role for this request, so SET LOCAL ROLE did not run and no RLS policy backs the exemption. Write refused.`;
@@ -2714,7 +3120,7 @@ function ownershipScope(
   options: HandlerOptions | undefined,
   user: Record<string, unknown> | null,
 ): OwnershipScope {
-  const ownership = options?.rowOwnership?.[tableName];
+  const ownership = ownEntry(options?.rowOwnership, tableName);
   if (!options || !ownership) return { condition: null };
   if (!user) {
     return { refusal: json({ message: 'Unauthorized: this table requires an authenticated owner' }, 401) };
@@ -2763,7 +3169,7 @@ async function handleDelete(
     return sanitizeError(filterResult.error, 400, options);
   }
 
-  const hook = options?.hooks?.[tableName];
+  const hook = ownEntry(options?.hooks, tableName);
 
   if (hook?.beforeDelete) {
     try {
@@ -2778,9 +3184,20 @@ 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)) {
+    const rows = await lifecycleDelete(db, table, tableName, conditions, options);
+    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));
+    }
+    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));
@@ -2814,7 +3231,21 @@ 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.
+  const ctx: DestroyContext = { source: 'api', user, client };
+  for (const row of rows) {
+    if (hook?.beforeDestroy) await hook.beforeDestroy(row, ctx);
+  }
+  if (hook?.afterDestroy) {
+    const { afterDestroy } = hook;
+    for (const row of rows) {
+      deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDestroy`, method: 'DELETE' },
+        () => Promise.resolve(afterDestroy.call(hook, row, ctx)));
+    }
+  }
 
   if (hook?.afterDelete && rows.length > 0) {
     const { afterDelete } = hook;
@@ -2825,6 +3256,122 @@ 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), DELETE with the same conditions, then drop every row still live: RLS
+ * refused its delete. What is left is the pre-image of the rows this request soft-deleted.
+ * 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, since the caller could read it.
+ */
+async function lifecycleDelete(
+  db: DrizzleDb,
+  table: DrizzleTable,
+  tableName: string,
+  conditions: SQL[],
+  options?: HandlerOptions,
+): Promise<Record<string, unknown>[]> {
+  const sdCol = getSoftDeleteColumn(tableName, table, options);
+  const keys = primaryKeyColumns(table)
+    .map(column => columnPropertyName(table, column.name))
+    .filter((key): key is string => key !== undefined);
+  if (!sdCol || keys.length === 0) {
+    throw new Error(`[everystack/api] softDelete.lifecycle.${tableName}: the table needs a ${LIFECYCLE_DELETED_AT} column and a primary key`);
+  }
+  const where = and(...conditions, isNull(sdCol))!;
+  const keyOf = (row: Record<string, unknown>): string => JSON.stringify(keys.map(key => row[key]));
+  return db.transaction(async (tx: DrizzleDb) => {
+    const matched: Record<string, unknown>[] = await tx.select().from(table).where(where);
+    if (matched.length === 0) return [];
+    await tx.delete(table).where(where);
+    const stillLive: Record<string, unknown>[] = await tx
+      .select(Object.fromEntries(keys.map(key => [key, getTableColumns(table)[key]])))
+      .from(table)
+      .where(where);
+    const live = new Set(stillLive.map(keyOf));
+    return matched.filter(row => !live.has(keyOf(row)));
+  });
+}
+
+/**
+ * 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;
+    });
+    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 }>;