@everystack/model 0.4.23 → 0.4.25

package/src/model.ts

@@ -1,3 +1,4 @@
+import { dependentWhereRefusal } from './dependents';
 /**
  * `defineModel` — Layer 2. One call colocates everything about a table: its
  * fields, its authorization (`abilities`), its mutation hooks, and its relations.
@@ -22,34 +23,34 @@ import type { RawSql } from './raw-sql';
 import { validateTriggersFor, type TriggerSpec, type DependsOnRef } from './derived';
 import { TABLE_PRIVILEGES, type TablePrivilege } from './privileges';
 
+import { assertDeleteHookNames, assertDestroyHooks, type AfterLifecycleHook, type BeforeLifecycleHook, type DestroyHook } from './lifecycle-hooks';
+export type { AfterLifecycleHook, BeforeLifecycleHook, DestroyContext, DestroyHook, HookVeto, LifecycleContext } from './lifecycle-hooks';
+
 /**
  * Per-table mutation hooks. Imperative function bodies the framework cannot
- * absorb (purge an S3 object on delete, stamp a column on create) — held
+ * absorb (remove a stored object after destroy, set a column on create) — held
  * verbatim and passed through to the handler's `hooks`.
  */
-/** Context for a real removal. Hooks must be idempotent: retries can repeat external effects. */
-export interface DestroyContext {
-  source: 'purge' | 'api';
-  user: Record<string, unknown> | null;
-  client: Record<string, unknown> | null;
-}
-
-export type DestroyHook = (row: Record<string, unknown>, ctx: DestroyContext) => void | Promise<void>;
-
 export interface ModelHooks {
   beforeCreate?: (...args: any[]) => any;
   afterCreate?: (...args: any[]) => any;
   beforeUpdate?: (...args: any[]) => any;
   afterUpdate?: (...args: any[]) => any;
-  beforeDelete?: (...args: any[]) => any;
-  afterDelete?: (...args: any[]) => any;
-  /** Runs after the DELETE statement, before commit. A throw rolls back only the database
-   * delete, never an external effect. No transaction is passed. Must be idempotent.
-   * Treat the row as read-only: it is the same object later serialized into the response. */
+  /** Before commit, once per matched root. Cascaded children run no hook; use deleteWhen. */
+  beforeDelete?: BeforeLifecycleHook;
+  /** After commit, once per request with the root rows. Best-effort. */
+  afterDelete?: AfterLifecycleHook;
+  /** Before an SQL destroy attempt, per candidate root. A veto or throw holds that root.
+   * The row may survive the attempt; do nothing irreversible here. No transaction is passed.
+   * Hooks may repeat after a failed commit. Treat the database row as read-only. */
   beforeDestroy?: DestroyHook;
-  /** Runs after commit, best-effort. Cannot undo the removal. Must be idempotent.
-   * Treat the row as read-only: it is the same object later serialized into the response. */
+  /** After commit, only for removed roots; FK cascade children run no hook. Best-effort:
+   * a crash can lose the call. Cannot undo removal. Treat the database row as read-only. */
   afterDestroy?: DestroyHook;
+  /** Lifecycle tables: after `POST {table}/restore` commits, with `[{ <key>: id }]`, the batch and the counts. Best-effort. */
+  afterRestore?: AfterLifecycleHook;
+  /** Reserved for a future release; createHandler refuses it. */
+  beforeRestore?: never;
 }
 
 /**
@@ -119,7 +120,7 @@ export interface ModelDefinition {
    *
    * The guard used to ask only about the public read, which is the visibility axis. That let a
    * model with an owner-scoped read and a `delete` ability default to `false` and begin
-   * destroying rows — with an S3 purge job keyed on `deleted_at IS NOT NULL`, that orphaned
+   * destroying rows — with an S3 cleanup job keyed on `deleted_at IS NOT NULL`, that orphaned
    * every file it should have cleaned up. On those models the flag adds no policy at all, so
    * visibility was never the axis that mattered.
    *
@@ -137,9 +138,13 @@ export interface ModelDefinition {
    * ({@link LIFECYCLE_COLUMNS}): `deletedAt` timestamptz, `deletedBy` text (no foreign key),
    * `deletedBatch` uuid, `deletedXid` bigint. The author never declares them, never combines
    * lifecycle with `softDelete`, and declares a single-column primary key; each is refused here.
-   * `true` is the only value today.
+   *
+   * `{ deleteWhen: sql\`<predicate>\` }` is lifecycle too, with a guard: a row may be marked
+   * deleted only when the predicate is TRUE for it (FALSE or NULL refuses, SQLSTATE 23514), whether
+   * the delete is the row's own or a parent's cascade. Bare column names, like a policy predicate.
+   * Destroy does not re-check this predicate after deletion. `{}` is `true`.
    */
-  lifecycle?: true;
+  lifecycle?: true | LifecycleOptions;
   /**
    * The Postgres schema the table lives in. Default `'public'`. Package-owned
    * tables declare their own (`'dist'`, `'ops'`, `'auth'`) so one db:generate run
@@ -220,8 +225,11 @@ export interface ModelDescriptor {
   privileges: Record<string, TablePrivilege[]>;
   /** `true` excludes `deleted_at IS NULL` rows from public reads and the data API. Declared, never inferred. */
   softDelete: boolean;
-  /** Present only when declared: `fields` carries the generated {@link LIFECYCLE_COLUMNS}. */
+  /** Present only when declared: `fields` carries the generated {@link LIFECYCLE_COLUMNS}. Always
+   *  `true` on the descriptor, whichever form the definition used. */
   lifecycle?: true;
+  /** `lifecycle: { deleteWhen }`'s predicate text. Absent when there is no guard. */
+  deleteWhen?: string;
   /** The resolved Postgres schema (default `'public'`). Package tables live in their own. */
   schema: string;
   /** `true` removes the table from the generic data API (not in `exposedTables`). Default `false`. */
@@ -307,14 +315,40 @@ function lifecycleFields(): Record<(typeof LIFECYCLE_COLUMNS)[number], FieldBuil
   };
 }
 
+/** `lifecycle: { … }` options. */
+export interface LifecycleOptions {
+  /** A row may be marked deleted only when this is TRUE for it; FALSE or NULL refuses. */
+  deleteWhen?: RawSql;
+}
+
+/** True for `lifecycle: true` and for `lifecycle: { … }` (validated by assertLifecycle). */
+function isLifecycle(def: ModelDefinition): boolean {
+  return def.lifecycle === true || (typeof def.lifecycle === 'object' && def.lifecycle !== null);
+}
+
+/** The guard predicate text, or undefined. Call after assertLifecycle. */
+function deleteWhenOf(def: ModelDefinition): string | undefined {
+  const value = def.lifecycle;
+  return typeof value === 'object' && value !== null && value.deleteWhen !== undefined ? value.deleteWhen.sql : undefined;
+}
+
 function assertLifecycle(table: string, def: ModelDefinition): void {
   const value: unknown = def.lifecycle;
   if (value === undefined) return;
   if (value === false) {
     throw new Error(`model '${table}': lifecycle: false is not supported yet. Omit the key for a model without lifecycle.`);
   }
-  if (value !== true) {
-    throw new Error(`model '${table}': lifecycle: ${JSON.stringify(value)} — the only value is lifecycle: true.`);
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const unknown = Object.keys(value).filter((k) => k !== 'deleteWhen');
+    if (unknown.length > 0) {
+      throw new Error(`model '${table}': lifecycle: { ${unknown.join(', ')} } — the only key is deleteWhen (lifecycle: { deleteWhen: sql\`…\` }).`);
+    }
+    const when = (value as { deleteWhen?: unknown }).deleteWhen;
+    if (when !== undefined && !(typeof when === 'object' && when !== null && typeof (when as RawSql).sql === 'string' && (when as RawSql).sql.trim() !== '')) {
+      throw new Error(`model '${table}': lifecycle: { deleteWhen } — deleteWhen must be sql\`…\`, a non-empty predicate over this table's columns.`);
+    }
+  } else if (value !== true) {
+    throw new Error(`model '${table}': lifecycle: ${JSON.stringify(value)} — the only values are lifecycle: true and lifecycle: { deleteWhen: sql\`…\` }.`);
   }
   if (def.softDelete !== undefined) {
     throw new Error(
@@ -340,7 +374,7 @@ function assertLifecycle(table: string, def: ModelDefinition): void {
   }
   // A cascade into this table, declared on this table's own foreign key. A parent's
   // hasMany { dependent: 'cascade' } is checked in relationDeleteActions (allowed from a
-  // lifecycle parent, where it compiles to RESTRICT and the triggers soft-delete the children).
+  // lifecycle parent: the triggers soft-delete the children, and destroy follows the real CASCADE).
   const tableName = def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table;
   for (const [name, f] of Object.entries(def.fields)) {
     if (f.spec.onDelete !== 'cascade') continue;
@@ -358,6 +392,10 @@ function assertLifecycle(table: string, def: ModelDefinition): void {
         `Mark exactly one field .primaryKey().`,
     );
   }
+  const [key, keyField] = Object.entries(def.fields).find(([, f]) => f.spec.isPrimaryKey)!;
+  if (keyField.spec.isArray) {
+    throw new Error(`model '${tableName}': lifecycle needs a primary key PostgreSQL can list in a key array; ${key} is an array type`);
+  }
   // The generated trigger and function names are `<table>_lifecycle_transition` and `_guard`.
   // PostgreSQL silently truncates an identifier past 63 bytes, so the declared name would not be the live one.
   // UTF-8 bytes, as PostgreSQL counts them. TextEncoder rather than Buffer: a model also loads outside Node.
@@ -375,10 +413,12 @@ function assertLifecycle(table: string, def: ModelDefinition): void {
  * Restore runs the table's delete rule inside a SECURITY DEFINER function as the lifecycle role.
  * Refuse a delete rule whose meaning would change there: a subquery (`via`, or SELECT in
  * where/sql) runs with that role's privileges, and current_user/session_user name that role or
- * the login, not the caller. TRUNCATE is refused because it skips the delete triggers.
+ * the login, not the caller. TRUNCATE is refused because it skips the delete triggers; TRIGGER
+ * because its holder can create triggers on the table; REFERENCES because its holder can
+ * add a foreign key that blocks or cascades a destroy.
  */
 function assertLifecycleRestoreSafe(table: string, def: ModelDefinition): void {
-  if (def.lifecycle !== true) return;
+  if (!isLifecycle(def)) return;
   const why = 'restore runs the delete rule inside a SECURITY DEFINER function as the lifecycle owner';
   const abilities = def.abilities ?? [];
   // A role-less (or authenticated) delete on a model scoped only through `via` compiles to the
@@ -427,14 +467,31 @@ function assertLifecycleRestoreSafe(table: string, def: ModelDefinition): void {
         `triggers, so it would erase rows past the soft delete and restore. Remove TRUNCATE from the entry.`,
     );
   }
+  const beyondDelete: Record<string, string> = {
+    TRIGGER: 'TRIGGER lets the holder create triggers on the table, so its own code would run inside every delete and destroy',
+    REFERENCES: 'REFERENCES lets the holder add a foreign key that blocks or cascades a destroy',
+  };
+  for (const [role, privs] of Object.entries(def.privileges ?? {})) {
+    if (!Array.isArray(privs)) continue;
+    for (const priv of ['TRIGGER', 'REFERENCES'] as const) {
+      if (!privs.includes(priv)) continue;
+      throw new Error(
+        `model '${table}': privileges['${role}'] grants ${priv} on a lifecycle: true model — ${beyondDelete[priv]}. ` +
+          `Remove ${priv} from the entry.`,
+      );
+    }
+  }
 }
 
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
+  assertDeleteHookNames(table, def.hooks);
+  assertDestroyHooks(table, def.hooks, isLifecycle(def));
   // Refuse first, then inject: the author-declared collisions are checked against what the author wrote.
   assertRoleNotReserved(table, def);
   assertLifecycle(table, def);
   assertLifecycleRestoreSafe(table, def);
-  const lifecycle = def.lifecycle === true;
+  const lifecycle = isLifecycle(def);
+  const deleteWhen = deleteWhenOf(def);
   const fields: Record<string, FieldBuilder> = lifecycle ? { ...def.fields, ...lifecycleFields() } : def.fields;
 
   for (const [name, field] of Object.entries(def.fields)) {
@@ -443,6 +500,8 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
   for (const [name, relation] of Object.entries(def.relations ?? {})) {
     assertRelationShape(def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table, name, relation);
     referenceLocation(relation.target, `${table}.${name}`);
+    const filtered = lifecycle ? dependentWhereRefusal(def.schema && def.schema !== 'public' ? `${def.schema}.${table}` : table, name, relation) : undefined;
+    if (filtered) throw new Error(filtered);
   }
   const primaryKey = Object.entries(def.fields)
     .filter(([, f]) => f.spec.isPrimaryKey)
@@ -453,6 +512,28 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
       throw new Error(`model '${table}': can('execute') is a function ability — declare it on the defineFunction it gates.`);
     }
 
+    if (a.condition.deleted !== undefined) {
+      if (a.action !== 'read') {
+        throw new Error(`model '${table}': deleted applies only to can('read'), not can('${a.action}').`);
+      }
+      if (a.condition.deleted !== 'include' && a.condition.deleted !== 'only') {
+        throw new Error(`model '${table}': can('read', { deleted: ${JSON.stringify(a.condition.deleted)} }) — deleted must be 'include' or 'only'.`);
+      }
+      if (!lifecycle) {
+        throw new Error(`model '${table}': can('read', { deleted }) — deleted applies only to a lifecycle model; this model has no deleted rows to include.`);
+      }
+      if (!a.condition.role) {
+        throw new Error(`model '${table}': can('read', { deleted }) — deleted needs a role: it changes that role's own read policy. Name the role that may see deleted rows.`);
+      }
+      // A public tier is every caller of the API, and db:pull could not fold the table back.
+      if (['anon', 'authenticated', 'public'].includes(a.condition.role.toLowerCase())) {
+        throw new Error(
+          `model '${table}': can('read', { role: '${a.condition.role}', deleted }) — deleted rows are for a named internal role, ` +
+            `never a public tier (anon, authenticated, public). Name the role that searches or restores, such as 'support_role'.`,
+        );
+      }
+    }
+
     // A column list is authorization, not a selection hint. If it reaches a table-grant path
     // unnoticed, Postgres receives a whole-table privilege. Admit only the shapes the column
     // compiler understands, and reject an empty list because it is indistinguishable from no
@@ -484,7 +565,9 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
         );
       }
       for (const column of a.condition.columns) {
-        if (!(column in def.fields)) {
+        // deletedAt is visible to every reader of a lifecycle model, so a column read may list it.
+        // deletedBy, deletedBatch and deletedXid are hidden by design and stay refused.
+        if (!(column in def.fields) && !(lifecycle && a.action === 'read' && column === 'deletedAt')) {
           throw new Error(
             `model '${table}': columns names '${column}', but no such field exists. Column abilities use model field keys.`,
           );
@@ -686,6 +769,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     // Stays false on a lifecycle model: its reads are filtered by the RLS guard (L1.2a), its deletes arrive with the triggers.
     softDelete: def.softDelete ?? false,
     ...(lifecycle ? { lifecycle: true as const } : {}),
+    ...(deleteWhen !== undefined ? { deleteWhen } : {}),
     schema: def.schema ?? 'public',
     private: def.private ?? false,
     rls: def.rls ?? true,

package/src/pg-type.ts

@@ -1,3 +1,5 @@
+import type { FieldSpec } from './field';
+
 /**
  * pg-type — the ONE definition of a column type's spelling.
  *
@@ -95,3 +97,67 @@ export function pgTypeRefusal(typeName: string): string | null {
   }
   return null;
 }
+
+/**
+ * Postgres type for a field, with the precision drizzle-kit would emit — in
+ * `format_type`'s vocabulary, because this feeds the IR that diffs against
+ * introspection. A serial field's *column type* is integer/bigint (`serial` is
+ * DDL shorthand, not a type — `format_type` never reports it); the sequence
+ * default is carried separately (see compileTableSchema), and the DDL renderers
+ * spell the shorthand (see SERIAL_DDL).
+ */
+const PG_TYPE: Record<string, string> = {
+  text: 'text',
+  uuid: 'uuid',
+  integer: 'integer',
+  boolean: 'boolean',
+  json: 'json',
+  jsonb: 'jsonb',
+  bigint: 'bigint',
+  serial: 'integer',
+  bigserial: 'bigint',
+  real: 'real',
+  doublePrecision: 'double precision',
+  timestamptz: 'timestamp with time zone',
+  // `format_type` canonicalizes a bare `timestamp` column to this spelling, and
+  // introspection compares against it — so the compiler must emit the same, or an
+  // unchanged `timestamp` column round-trips to a spurious ALTER COLUMN TYPE.
+  timestamp: 'timestamp without time zone',
+  date: 'date',
+};
+
+export function pgType(spec: FieldSpec): string {
+  // An array is the base type with `[]` appended — `text` → `text[]`, exactly as
+  // `format_type` spells it.
+  return spec.isArray ? `${scalarPgType(spec)}[]` : scalarPgType(spec);
+}
+
+function scalarPgType(spec: FieldSpec): string {
+  // Parameterized types build their own canonical string — exactly as `format_type`
+  // spells it (no space after the comma; `varchar` is `character varying`; a
+  // precision-only numeric carries scale 0), so an unchanged column round-trips clean.
+  if (spec.type === 'numeric') {
+    if (spec.precision != null) return `numeric(${spec.precision},${spec.scale ?? 0})`;
+    return 'numeric';
+  }
+  if (spec.type === 'varchar') {
+    return spec.length != null ? `character varying(${spec.length})` : 'character varying';
+  }
+  if (spec.type === 'enum') {
+    // The column's type is the enum's own type name; `format_type` reports the same bare
+    // name, so it round-trips. The `CREATE TYPE` is emitted separately, before the table.
+    if (!spec.enumName) throw new Error('field bridge: an enum field needs a type name — field.enum(name, values)');
+    return spec.enumName;
+  }
+  if (spec.type === 'pgType') {
+    // A verbatim type: the declared string IS the canonical `format_type` spelling
+    // (the factory refused anything else), so it round-trips byte-for-byte.
+    if (!spec.pgTypeName) throw new Error('field bridge: a pgType field needs its type name — field.pgType(name)');
+    return spec.pgTypeName;
+  }
+  const t = PG_TYPE[spec.type];
+  if (!t) {
+    throw new Error(`field bridge: no DDL mapping for field type '${spec.type}' yet`);
+  }
+  return t;
+}

package/src/wire.ts

@@ -46,8 +46,10 @@
  *
  * v1 — the first version. Shapes as they stood when the guard was introduced.
  * v2 — ProvisionWirePayload gains `lifecycleRole` (provision the reserved lifecycle role).
+ * v3 — ReconcileWirePayload gains `applicationRoles` (the lifecycle catalog check's roles). A v2
+ *      CLI's payload carries none, and a reconcile of lifecycle-owned objects refuses without them.
  */
-export const MODEL_WIRE_CONTRACT = 2;
+export const MODEL_WIRE_CONTRACT = 3;
 
 /**
  * Every Model-derived wire payload carries this. The server refuses a payload whose `modelContract`
@@ -237,6 +239,12 @@ export interface ReconcileWirePayload extends ModelWireEnvelope {
   rebuild?: boolean;
   overwriteDrift?: boolean;
   only?: string[];
+  /**
+   * The application roles the Models' compiled contracts name (catalogInputsFromModels in the
+   * CLI): the lifecycle catalog check's one input the declared layer cannot supply. Absent while a
+   * declared object is lifecycle-owned = the reconcile refuses (fail closed).
+   */
+  applicationRoles?: string[];
   actor?: string | null;
   gitRef?: string | null;
 }