@everystack/server 0.4.38 → 0.4.39

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@everystack/server` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.39] - 2026-10-23
+
+### BREAKING CHANGES
+
+- lifecycle: { deleteWhen } refuses deleting a row its predicate does not allow
+- one lifecycle hook API: (rows, ctx), veto(reason), beforeStamp
+- deleteWhen spliced on its own lines; a deleted reader is not granted deleted_by
+
 ## [0.4.38] - 2026-10-23
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.38",
+  "version": "0.4.39",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -197,11 +197,11 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.102",
+    "@everystack/cli": "0.4.103",
     "@everystack/auth": "0.4.9"
   },
   "dependencies": {
-    "@everystack/model": "0.4.23"
+    "@everystack/model": "0.4.24"
   },
   "scripts": {
     "test": "jest",

package/src/purge.ts

@@ -2,12 +2,21 @@
 import { randomUUID } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import { sql, type SQL } from 'drizzle-orm';
-import type { ModelDescriptor, DestroyContext } from '@everystack/model';
+import { isVeto, type ModelDescriptor, type DestroyContext } from '@everystack/model';
 import type { SessionTx } from './db-session';
 import { unsupportedPurgeGraphs } from './purge-graph';
 export { ENSURE_PURGE_LOG_SQL } from './purge-log';
+export { veto, isVeto } from '@everystack/model';
+export type { HookVeto, LifecycleContext, DestroyContext, DestroyHook } from '@everystack/model';
 
 /** A destroy hook failed after physical removal committed. */
+/** A row lifecycle: { deleteWhen } no longer allows: kept, recorded, never cooled down. */
+const PROTECTED_BY_DELETE_WHEN = 'protected by deleteWhen';
+/** beforeDestroy returned veto(reason): the row is kept with a `skipped` receipt `held: <reason>`, never cooled down. */
+const HELD = 'held: ';
+/** Thrown inside the removal savepoint to roll it back when beforeDestroy vetoes. */
+class HeldByHook extends Error {}
+
 export interface PurgeHookFault {
   kind: 'hook';
   name: string;
@@ -47,7 +56,9 @@ export interface PurgeResult {
 
 type Row = Record<string, unknown>;
 type Receipt = { model: ModelDescriptor; row: Row; outcome: 'purged' | 'skipped' | 'failed'; hook: 'ran' | 'none' | 'failed'; detail?: string };
-const context: DestroyContext = Object.freeze({ source: 'purge', user: null, client: null });
+const contextFor = (row: Row): DestroyContext => Object.freeze({
+  phase: 'destroy', source: 'purge', batch: typeof row.deleted_batch === 'string' ? row.deleted_batch : null, user: null, client: null,
+});
 const param = (value: unknown): unknown => value instanceof Date ? value.toISOString() : typeof value === 'bigint' ? value.toString() : value;
 const snake = (name: string): string => name.replace(/[A-Z]/g, c => '_' + c.toLowerCase());
 const label = (m: ModelDescriptor): string => `${m.schema}.${m.table}`;
@@ -145,8 +156,10 @@ async function appendReceipt(tx: SessionTx, runId: string, now: Date, receipt: R
  * Purge expired lifecycle rows, children first, in one transaction per selected row.
  * The executor is the existing ops Drizzle database (execute/transaction); its caller
  * must read the selected tables and purge_log, and SET ROLE to everystack_lifecycle. Hooks run outside
- * that role after DELETE and immediate constraint checks; a hook throw rolls back the
- * removal. A successful hook can repeat if commit fails, so it must be idempotent. A skipped row appends another
+ * that role after DELETE and immediate constraint checks, with `{ phase: 'destroy', source: 'purge',
+ * batch: <the row's deleted_batch> }`. A hook throw rolls back the removal (failed receipt, retry
+ * cooldown). A returned `veto(reason)` rolls it back too, as a decision: a `skipped` receipt with
+ * detail `held: <reason>`, no cooldown, so the next run asks again. A successful hook can repeat if commit fails, so it must be idempotent. A skipped row appends another
  * skipped receipt on each retry. Plain children with ON DELETE CASCADE are removed by
  * referential integrity; they receive neither a destroy hook nor a purge receipt.
  * The receipt's hook status describes beforeDestroy. afterDestroy is best-effort after
@@ -198,6 +211,8 @@ export async function purgeExpired(exec: SessionTx, models: ModelDescriptor[], o
         SELECT 1 FROM everystack.purge_log AS receipt
         WHERE receipt."table" = ${name} AND ${cooldownKeyMatches(model)}
           AND receipt.outcome IN ('skipped', 'failed') AND receipt.purged_at > ${retryCutoff.toISOString()}
+          AND receipt.detail IS DISTINCT FROM ${PROTECTED_BY_DELETE_WHEN}
+          AND NOT (receipt.outcome = 'skipped' AND coalesce(receipt.detail, '') LIKE ${HELD + '%'})
       )` : sql``;
       const page = rowsOf(await exec.execute(sql`SELECT * FROM ${table(model)}
         WHERE deleted_at <= ${cutoff.toISOString()} ${cooldown} ${cursorValues ? sql`AND (${tuple}) > (${cursorValues})` : sql``}
@@ -220,6 +235,7 @@ export async function purgeExpired(exec: SessionTx, models: ModelDescriptor[], o
         let beforeRan = false;
         let skippedReason: string | undefined;
         let failureReason: string | undefined;
+        let held: string | undefined;
         const removed = await exec.transaction(async tx => {
           const [isolation] = rowsOf(await tx.execute(sql`SHOW transaction_isolation`));
           if (isolation?.transaction_isolation !== 'read committed') throw new Error('purge requires READ COMMITTED');
@@ -235,6 +251,8 @@ export async function purgeExpired(exec: SessionTx, models: ModelDescriptor[], o
                 SELECT 1 FROM everystack.purge_log AS receipt
                 WHERE receipt."table" = ${name} AND ${cooldownKeyMatches(model)}
                   AND receipt.outcome IN ('skipped', 'failed') AND receipt.purged_at > ${retryCutoff.toISOString()}
+                  AND receipt.detail IS DISTINCT FROM ${PROTECTED_BY_DELETE_WHEN}
+                  AND NOT (receipt.outcome = 'skipped' AND coalesce(receipt.detail, '') LIKE ${HELD + '%'})
               )`));
             if (cooling.length) { skippedReason = 'retry cooldown'; return false; }
           }
@@ -255,19 +273,39 @@ export async function purgeExpired(exec: SessionTx, models: ModelDescriptor[], o
               const caller = model.hooks?.beforeDestroy
                 ? rowsOf(await work.execute(sql`SELECT current_user AS role`))[0] : undefined;
               await work.execute(sql`SET LOCAL ROLE everystack_lifecycle`);
-              const deleted = rowsOf(await work.execute(sql`DELETE FROM ${table(model)} WHERE ${keyWhere(model, row)} RETURNING ${sql.join(model.primaryKey.map(column), sql`, `)}`));
+              // lifecycle: { deleteWhen } — a drift guard, not the main gate: the stamp already passed the
+              // guard trigger, but the predicate's columns may have changed since. A row it no longer
+              // allows stays, with a `skipped` receipt that sets no retry cooldown (the next run looks again).
+              // On lines of its own: a trailing `--` comment in the predicate must not hide RETURNING.
+              const guard = model.deleteWhen !== undefined ? sql` AND (\n${sql.raw(model.deleteWhen)}\n)` : sql``;
+              const deleted = rowsOf(await work.execute(sql`DELETE FROM ${table(model)} WHERE ${keyWhere(model, row)}${guard} RETURNING ${sql.join(model.primaryKey.map(column), sql`, `)}`));
+              if (model.deleteWhen !== undefined && deleted.length === 0) {
+                skippedReason = PROTECTED_BY_DELETE_WHEN;
+                await appendReceipt(work, result.runId, now, { model, row, outcome: 'skipped', hook: 'none', detail: skippedReason });
+                return false;
+              }
               if (deleted.length !== 1 || keyOf(model, deleted[0]) !== keyOf(model, row)) throw new Error('purge DELETE did not return the locked key');
               // Refuse deferred constraints before invoking a hook with external effects.
               await work.execute(sql`SET CONSTRAINTS ALL IMMEDIATE`);
               if (caller) await work.execute(sql`SET LOCAL ROLE ${sql.identifier(String(caller.role))}`);
               if (model.hooks?.beforeDestroy) {
-                try { await model.hooks.beforeDestroy(hookRow(model, row), context); beforeRan = true; }
-                catch (error) { beforeFailed = true; throw error; }
+                try {
+                  const verdict = await model.hooks.beforeDestroy(hookRow(model, row), contextFor(row));
+                  beforeRan = true;
+                  if (isVeto(verdict)) held = HELD + verdict.reason;
+                } catch (error) { beforeFailed = true; throw error; }
+                // A veto rolls back the removal like a throw, but it is a decision, not a failure.
+                if (held !== undefined) throw new HeldByHook(held);
               }
               await appendReceipt(work, result.runId, now, { model, row, outcome: 'purged', hook: beforeRan ? 'ran' : 'none' });
               return true;
             });
           } catch (error) {
+            if (error instanceof HeldByHook) {
+              skippedReason = held;
+              await appendReceipt(tx, result.runId, now, { model, row, outcome: 'skipped', hook: 'ran', detail: held });
+              return false;
+            }
             failureReason = error instanceof Error ? error.message : String(error);
             await appendReceipt(tx, result.runId, now, { model, row, outcome: 'failed', hook: beforeFailed ? 'failed' : beforeRan ? 'ran' : 'none', detail: failureReason });
             return false;
@@ -292,7 +330,7 @@ export async function purgeExpired(exec: SessionTx, models: ModelDescriptor[], o
         purged++; counts.purged++;
         if (!model.hooks?.beforeDestroy && !model.hooks?.afterDestroy && !result.noHook.includes(name)) result.noHook.push(name);
         if (model.hooks?.afterDestroy) {
-          try { await model.hooks.afterDestroy(hookRow(model, selected!), context); }
+          try { await model.hooks.afterDestroy(hookRow(model, selected!), contextFor(selected!)); }
           catch (error) {
             // Formatting an arbitrary rejection must not lose a committed outcome.
             let message = 'unreadable error';