@everystack/api 0.4.11 → 0.4.13

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.13] - 2026-10-30
+
+### BREAKING CHANGES
+
+- destroy is one generated SQL function per lifecycle table; purgeExpired is removed
+
+### Fixed
+
+- destroy hooks are refused on a table that is not a lifecycle table
+- a delete before-hook outage answers the fixed 503 again
+
+### Changed
+
+- one delete hook pair; beforeStamp and afterStamp are folded into beforeDelete and afterDelete
+
+### Documentation
+
+- one delete hook pair
+
+## [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

package/README.md

@@ -99,8 +99,10 @@ createHandler(db, schema, {
       afterCreate: async (row, user, client) => { /* notify */ },
       beforeUpdate: async (body, user, client) => body,
       afterUpdate: async (rows, user, client) => {},
-      beforeDelete: async (user, client) => {},
-      afterDelete: async (rows, user, client) => {},
+      // All models; veto from '@everystack/api/handler' rolls back the request:
+      beforeDelete: (row, ctx) => (ctx.user ? undefined : veto('sign in to delete')), // in the transaction; veto -> 409
+      afterDelete: async (rows, ctx) => {},  // after commit, once per request; ctx.batch is null
+      afterRestore: async (rows, ctx) => {}, // after commit, ctx.batch and ctx.counts
     },
   },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "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

@@ -84,7 +84,7 @@ export interface QueryBuilder {
   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 }`. */
+   *  POSTs `{baseUrl}/{table}/restore` with `{ id }`; the data is `{ restored, skipped, batch }`. */
   restore(id: string | number): Promise<ClientResponse<RestoreResult>>;
 }
 
@@ -92,6 +92,9 @@ export interface QueryBuilder {
 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 {

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 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 delete 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
@@ -272,15 +285,6 @@ export interface SoftDeleteConfig {
   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>>;
@@ -290,18 +294,19 @@ export interface HookConfig {
   beforeUpdate?: (body: Record<string, unknown>, user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<Record<string, unknown>>;
   /** Called after UPDATE with all returned rows. Fire-and-forget. */
   afterUpdate?: (rows: Record<string, unknown>[], user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
-  /** Called before DELETE. Throw to abort. */
-  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;
+  /** Inside the transaction, once per matched root row. Return veto(reason) to roll back the
+   * request with 409. Lifecycle rows are pre-images; plain and legacy softDelete rows come from
+   * RETURNING. Throws roll back too. Cascaded children run no hook: guard them with deleteWhen. */
+  beforeDelete?: BeforeLifecycleHook;
+  /** After commit, once per request with its root rows, best-effort. Empty deletes fire nothing.
+   * Each lifecycle row carries its own deletedBatch; ctx.batch is null for a delete request. */
+  afterDelete?: 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. */
@@ -463,6 +468,8 @@ export interface HandlerOptions {
 
 /** 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;
@@ -950,6 +957,30 @@ function declaredTables(options: HandlerOptions): Set<string> {
   return new Set(names.map(toSnakeCase));
 }
 
+/**
+ * Refuse removed and reserved hook names so a guard cannot be silently ignored.
+ * Other unknown hook keys are ignored, as before.
+ */
+function refuseReservedHooks(options: HandlerOptions | undefined): void {
+  for (const [tableName, hook] of Object.entries(options?.hooks ?? {})) {
+    for (const [oldName, replacement] of [['beforeStamp', 'beforeDelete'], ['afterStamp', 'afterDelete']]) {
+      if ((hook as Record<string, unknown> | undefined)?.[oldName] !== undefined) {
+        throw new Error(`[everystack/api] hooks.${tableName}.${oldName} was renamed to ${replacement}; update the hook name`);
+      }
+    }
+    if (!isLifecycleTable(tableName, options)) {
+      for (const name of ['beforeDestroy', 'afterDestroy']) {
+        if ((hook as Record<string, unknown> | undefined)?.[name] !== undefined) {
+          throw new Error(`[everystack/model] hooks.${tableName}.${name} runs only when a lifecycle table is destroyed, and ${tableName} is not a lifecycle table. Use beforeDelete or afterDelete, which run at the DELETE`);
+        }
+      }
+    }
+    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
@@ -1336,6 +1367,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;
@@ -1368,6 +1404,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
@@ -1773,11 +1810,8 @@ 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 deleteTransaction = method === 'DELETE' && !isLifecycleTable(tableName, options)
+        && Boolean(ownEntry(options?.hooks, tableName)?.beforeDelete);
       const deferred: Deferred[] = [];
       let response: Response;
       try {
@@ -1801,7 +1835,10 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           }
 
           return json({ message: `Method ${method} not allowed` }, 405);
-        }, destroyTransaction);
+        }, deleteTransaction);
+      } catch (err) {
+        if (!(err instanceof BeforeHookThrew)) throw err;
+        response = beforeHookFailure(err.thrown, options, { requestId, name: `${tableName}.beforeDelete`, method: 'DELETE' }, deferred);
       } finally {
         // emitFault never throws, so this cannot replace the error in flight.
         for (const item of deferred) if (item.always) await item.run();
@@ -1822,6 +1859,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);
@@ -2706,8 +2753,8 @@ function pickColumns(row: Record<string, unknown>, columns: string[]): Record<st
 
 /**
  * The response for a before-hook that threw. A HandlerError keeps its own status and
- * message. An outage (the hook could not reach the database) answers the fixed 503,
- * like every other outage path. Anything else is a generic 500 so the hook's text
+ * message. Before-hook outages (create, update and delete) answer the fixed 503. Other non-HandlerError
+ * throws answer a generic 500 so the hook's text
  * never reaches the client. A 5xx is a fault and goes to onError; a 4xx HandlerError
  * is a refusal and does not. The fault is queued, not sent: with pgSettings the hook
  * ran inside the transaction, and a slow onError must not hold it open.
@@ -3171,98 +3218,51 @@ async function handleDelete(
 
   const hook = ownEntry(options?.hooks, tableName);
 
-  if (hook?.beforeDelete) {
-    try {
-      await hook.beforeDelete(user, client);
-    } catch (err) {
-      return beforeHookFailure(err, options, { requestId, name: tableName, method: 'DELETE' }, deferred);
-    }
-  }
-
   const conditions = filterResult.conditions;
 
   // 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).
+  const ctx: LifecycleContext = { phase: 'delete', batch: null, user, client };
+  let rows: Record<string, unknown>[];
   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(tableName, table, options);
-    if (sdCol) {
-      // Only soft-delete records that aren't already deleted
-      conditions.push(isNull(sdCol));
-      const colName = options?.softDelete?.column || 'deletedAt';
-      let query: any = db.update(table).set({ [colName]: new Date() });
-
-      if (conditions.length === 1) {
-        query = query.where(conditions[0]);
-      } else {
-        query = query.where(and(...conditions));
-      }
-
-      const rows = await query.returning();
-
-      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);
-    }
-  }
-
-  // Hard delete (no soft-delete configured for this table)
-  let query: any = db.delete(table);
-
-  if (conditions.length === 1) {
-    query = query.where(conditions[0]);
+    const deleted = await lifecycleDelete(db, table, tableName, conditions, options, hook?.beforeDelete
+      ? { run: hook.beforeDelete.bind(hook), ctx } : undefined);
+    rows = deleted.rows;
+    const batchKey = columnPropertyName(table, LIFECYCLE_DELETED_BATCH);
+    if (batchKey) for (const [row, batch] of deleted.batchOf) row[batchKey] = batch;
   } else {
-    query = query.where(and(...conditions));
-  }
-
-  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)));
+    const sdCol = isSoftDeleteTable(tableName, table, options) && getSoftDeleteColumn(tableName, table, options);
+    if (sdCol) conditions.push(isNull(sdCol));
+    const query: any = sdCol
+      ? db.update(table).set({ [options?.softDelete?.column || 'deletedAt']: new Date() })
+      : db.delete(table);
+    rows = await query.where(conditions.length === 1 ? conditions[0] : and(...conditions)).returning();
+    // RETURNING proves the caller's write authority. A veto or throw leaves the caller's
+    // transaction, so the statement rolls back before the response is made.
+    if (hook?.beforeDelete) for (const row of rows) {
+      let verdict: unknown;
+      try { verdict = await hook.beforeDelete(row, ctx); } catch (err) { throw new BeforeHookThrew(err); }
+      if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
     }
   }
-
   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));
+      async () => { await afterDelete.call(hook, rows, ctx); });
   }
-
   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
+ * DELETE on a lifecycle table. The trigger marks each row deleted and cancels its removal, 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.
+ * matches (the pre-image), run beforeDelete 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 current values belongs in deleteWhen, which the trigger
+ * checks on the current row. Under READ COMMITTED a row another request soft-deletes between the read
+ * and the DELETE is still listed (and reaches afterDelete): a false attribution, never a leak.
  */
 async function lifecycleDelete(
   db: DrizzleDb,
@@ -3270,27 +3270,56 @@ async function lifecycleDelete(
   tableName: string,
   conditions: SQL[],
   options?: HandlerOptions,
-): Promise<Record<string, unknown>[]> {
+  beforeDelete?: { run: BeforeLifecycleHook; ctx: LifecycleContext },
+): Promise<{ rows: Record<string, unknown>[]; batchOf: Map<Record<string, unknown>, string> }> {
   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);
+  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 [];
-    await tx.delete(table).where(where);
+    // beforeDelete: once per matched root, before the DELETE, inside this transaction. A veto or a
+    // throw leaves it, so nothing is soft-deleted.
+    if (beforeDelete) {
+      for (const row of matched) {
+        let verdict: unknown;
+        try { verdict = await beforeDelete.run(row, beforeDelete.ctx); } catch (err) { throw new BeforeHookThrew(err); }
+        if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
+      }
+    }
+    // The transition appends one `<JSON key> <batch>` line per soft-deleted 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 lifecycle 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 soft-deleted.
+    // The request filter stays, so a matched row edited out of it meanwhile is not soft-deleted 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(Object.fromEntries(keys.map(key => [key, getTableColumns(table)[key]])))
+      .select({ [key]: keyColumn })
       .from(table)
-      .where(where);
-    const live = new Set(stillLive.map(keyOf));
-    return matched.filter(row => !live.has(keyOf(row)));
+      .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 deleted = matched.filter(row => !live.has(String(row[key])));
+    for (const row of deleted) {
+      const batch = byKey.get(String(row[key]));
+      if (batch) batchOf.set(row, batch);
+    }
+    return deleted;
   });
+  return { rows, batchOf };
 }
 
 /**
@@ -3329,6 +3358,19 @@ async function handleRestore(
       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', 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.

package/src/handler/veto.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 {
+  /** `delete`: a request-level delete. `restore`: a batch came back. `destroy`: physical removal. */
+  phase: 'delete' | 'restore' | 'destroy';
+  /** Request-level deletes use null. Restore and destroy can carry the row's existing batch. */
+  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>;
+
+/** Before commit, once per matched root row; returns nothing or a veto. Cascaded children run no hook: guard them with deleteWhen. */
+export type BeforeLifecycleHook = (row: Record<string, unknown>, ctx: LifecycleContext) => void | HookVeto | Promise<void | HookVeto>;
+
+/** After commit, once per request with the root rows. Best-effort; cascaded children run no hook. */
+export type AfterLifecycleHook = (rows: Record<string, unknown>[], ctx: LifecycleContext) => void | Promise<void>;