@everystack/model 0.4.25 → 0.4.27

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.27] - 2026-11-04
+
+### BREAKING CHANGES
+
+- softDelete is removed; lifecycle is the one soft delete
+- createHandler refuses softDelete; lifecycle tables are the lifecycle option
+
+### Fixed
+
+- a legacy descriptor with softDelete is refused wherever models are linked, derived or compiled
+
+### Documentation
+
+- softDelete is removed; lifecycle is the one soft delete
+
+## [0.4.26] - 2026-10-31
+
+### Added
+
+- declare request roles with defineModule({ roles: { request } })
+
+### Fixed
+
+- a granted definer role is not a request role in the lifecycle check
+
+### Documentation
+
+- say why a granted owner counts, and document roles.request
+- state what an older server skips under the role declaration
+
 ## [0.4.25] - 2026-10-30
 
 ### BREAKING CHANGES

package/README.md

@@ -132,48 +132,15 @@ defineModel('posts', {
 
 ## Soft delete
 
-A `deletedAt` column is a column. `softDelete` is the decision about what it MEANS, and it sits
-on the model beside `fields`:
+Soft delete is `lifecycle: true`: see [Lifecycle](#lifecycle). It is the only soft delete. On a
+model without it, a `deletedAt` field is a plain column and a `DELETE` removes the row.
+
+To keep a `deleted_at` filter on a plain model's read, write it on the ability:
 
 ```typescript
-export const Upload = defineModel('uploads', {
-  fields: {
-    id: field.uuid().primaryKey().defaultRandom(),
-    accountId: field.uuid().notNull().references(() => Account),
-    s3Key: field.text().notNull(),
-    deletedAt: field.timestamptz(),
-  },
-  softDelete: true,
-  abilities: [can('read', { owner: 'accountId' }), can('delete', { owner: 'accountId' })],
-});
+can('read', { role: 'anon', sql: sql`deleted_at IS NULL` })
 ```
 
-It changes two different things, and neither default is safe:
-
-- **Durability, on every model** — `true` makes a `DELETE` mark `deleted_at` instead of removing
-  the row, and hides marked rows from the data API's reads and updates. `false` makes `DELETE`
-  permanent.
-- **Visibility, only where there is a public read** — `true` AND-s `deleted_at IS NULL` into the
-  anon policy. On an owner-scoped or admin-only model the compiled SQL is identical either way,
-  so durability is the axis that matters there.
-
-**`defineModel` refuses to guess** when a model has `deletedAt` AND either a public read or a way
-to DELETE (`can('delete')`, `can('manage')`, or a `privileges` DELETE grant). Omit the line on
-such a model and it throws at import, naming which branch it tripped. Where nothing reads
-publicly and nothing deletes, the flag provably changes neither the SQL nor the handler, so
-nothing is required.
-
-Pick `true` if the row is meant to survive its own deletion — anything with a cleanup or destroy
-job, an audit trail, or rows other tables reference. Pick `false` if `deleted_at` here is
-audit-only and a `DELETE` really should remove the row. It is not cosmetic: a table whose S3
-cleanup job finds work by `deleted_at IS NOT NULL` orphans every file it should have removed if
-the row is hard-deleted instead.
-
-A column named `deleted_at` is not a statement of intent — it is carried for audit, for
-app-layer filtering, for half-finished migrations. This used to be inferred from the field's
-presence, which made the compiler author a security rule nobody wrote. `db:pull` writes the
-flag explicitly for the same reason.
-
 ## Relations
 
 ```typescript
@@ -245,7 +212,7 @@ The foreign key belongs to the child table, so the action lands there: in the pl
 - The relation must join on the primary key (the key a field `.references()` points at). A field covered only by a table-level `foreignKey(...)` declares `onDelete` there.
 - **`'cascade'` deletes the children in the database** (Rails `delete_all`). It runs no hook of the child and no code of yours. A child that must run code when it goes is not a cascade; that is `'destroy'`, which is not available yet. `'cascade'` works over a `NOT NULL` column, and it follows the child's own foreign keys in turn: deleting a thread deletes its replies and their reactions.
 - **A cascade is not checked against the child's own abilities.** PostgreSQL runs the referential action as the owner of the child table, so a role that may delete the parent row removes its children even when it holds no `DELETE` grant on the child and the child's row-level policy would refuse it. Grant `delete` on the parent only to roles that may remove everything below it. `'nullify'` has the same property for `UPDATE`.
-- Any other value (for example `'softDelete'`) is refused by name.
+- Any other value is refused by name.
 - `belongsTo` takes no `dependent`. A `hasMany` with no `dependent` is display only and compiles exactly as before.
 
 `db:pull` renders the action on the child (`.references(() => Post, { onDelete: 'set null' })`) and no `dependent` on the parent; that agrees with a parent that declares one, so pull then plan is empty. A parent rendered `lifecycle: true` is the exception: `db:pull` renders the `dependent` of each key from a lifecycle child on the parent, from the key's `ON DELETE`, and leaves a plain child's key as it is, with a comment: only a lifecycle table may hold a key into a lifecycle table, so that model refuses to compile until you make it `lifecycle: true` or drop the `.references()`.
@@ -274,7 +241,6 @@ The compiler adds nullable `deletedAt` (timestamptz), `deletedBy` (text, no fore
 `deletedBatch` (uuid) and `deletedXid` (bigint). `LIFECYCLE_COLUMNS` names them. They enter the schema plan,
 fingerprint and generated schema. Do not declare these fields yourself, including their snake_case spellings.
 Lifecycle needs a single-column primary key and RLS. Omit `lifecycle` to disable it; `false` is refused.
-Do not combine it with `softDelete`. The boolean remains supported separately; its removal has not shipped.
 
 A DELETE sets these columns and reports zero removed rows. Read roles see only live rows;
 a plain manage role can see deleted rows. The API hides `deletedBy`, `deletedBatch` and `deletedXid` from other roles.
@@ -294,6 +260,11 @@ An explicit field `onDelete: 'cascade'` into a lifecycle table is refused; use t
 running app hooks. `dependent: 'destroy'` has not shipped.
 AFTER DELETE audit triggers are supported; they do not run on a soft deletion.
 
+A trigger function on a lifecycle table must be owned by a role no request can become. The check counts
+every role the models grant to as a request role. If a definer role owns such a function and holds grants,
+declare the request roles: `defineModule({ roles: { request: [...] } })`. `moduleRequestRoles(modules)`
+returns their union. See [docs/lifecycle.md](../../docs/lifecycle.md#owner-definer-and-request-roles).
+
 #### Refusing some deletes: `deleteWhen`
 
 `lifecycle: { deleteWhen: sql\`<predicate>\` }` is lifecycle with a guard: a row may be deleted only when the predicate
@@ -565,7 +536,7 @@ everystack db:pull     --stage dev   # reverse an existing database into model s
 
 ### Handler config
 
-`deriveHandlerConfig(models)` compiles the same Models into the authorization config `createHandler` consumes (exposed tables, hidden/protected columns, relations, row ownership, **`softDelete.tables`**) — so the HTTP handler and the database enforce the *same* declared rules, with no second source of truth.
+`deriveHandlerConfig(models)` compiles the same Models into the authorization config `createHandler` consumes (exposed tables, hidden/protected columns, relations, row ownership, the **`lifecycle`** tables) — so the HTTP handler and the database enforce the *same* declared rules, with no second source of truth.
 
 ```typescript
 import { deriveHandlerConfig } from '@everystack/model';
@@ -573,8 +544,8 @@ const handler = createHandler(db, schema, deriveHandlerConfig(models));
 ```
 
 Do not hand-write the per-table keys beside it. Each one is a view of the models, and a
-hand-kept copy drifts silently: `softDelete.tables` losing two entries is what let a table start
-hard-deleting rows whose S3 objects a destroy job keyed on `deleted_at IS NOT NULL`. Handler-level
+hand-kept copy drifts silently: a soft-delete table list losing two entries is what once let a
+table start hard-deleting rows whose S3 objects a destroy job keyed on `deleted_at IS NOT NULL`. Handler-level
 options that are not per-table — `auth`, `pgSettings`, `rpc`, limits — stay explicit.
 
 ## Programmatic API (`@everystack/cli/model`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/can.ts

@@ -193,50 +193,6 @@ export function privilegesGrantDelete(privileges: Record<string, readonly string
   return Object.values(privileges ?? {}).some((privs) => privs.includes('DELETE'));
 }
 
-/** The three facts the soft-delete rule turns on. See {@link needsSoftDeleteDeclaration}. */
-export interface SoftDeleteFacts {
-  /** A `deletedAt` / `deleted_at` field is present. */
-  hasDeletedAtField: boolean;
-  /** Some ability is a PUBLIC read — see {@link isPublicReadAbility}. */
-  hasPublicRead: boolean;
-  /**
-   * A DELETE can reach this table — via an ability ({@link isDeleteAbility}) or via a
-   * `privileges` grant ({@link privilegesGrantDelete}). The SPELLING of the grant was never
-   * load-bearing; what matters is that rows can be destroyed.
-   */
-  grantsDelete: boolean;
-}
-
-/**
- * THE rule deciding when `softDelete` must be declared rather than defaulted.
- *
- * `softDelete` changes observable behaviour on TWO axes, and the refusal has to cover both:
- *
- *  - **visibility** — on a model with a public read, `true` AND-s `deleted_at IS NULL` into the
- *    anon policy. What a caller with no session can see.
- *  - **durability** — on ANY model that can be deleted from, `true` makes the handler mark
- *    `deleted_at` instead of removing the row. What a DELETE destroys.
- *
- * The guard originally asked only the visibility question, so a model with an owner-scoped
- * read and a `delete` ability sailed past it and silently defaulted to `false`. That is how
- * `uploads` and `image_variants` began hard-deleting rows, orphaning their S3 objects forever
- * — on those models `softDelete: true` adds no policy predicate at all, so visibility was
- * never the axis that mattered.
- *
- * Deliberately NOT "any model with a `deletedAt` field": where nothing reads publicly and
- * nothing deletes, the flag provably changes neither SQL nor handler behaviour, and refusing
- * there would be ceremony charged to every brownfield pull for no hazard.
- *
- * Stated over FACTS, not over a descriptor, because it has two callers holding two
- * representations: `defineModel` has structured {@link Ability} objects, and `db:pull`'s
- * renderer only ever holds rendered source text. Both extract the same three facts and share
- * this one boolean, so the two surfaces cannot drift on the rule itself — the failure that
- * already bit this guard once, when the refusal and the renderer disagreed about `role: 'anon'`.
- */
-export function needsSoftDeleteDeclaration(facts: SoftDeleteFacts): boolean {
-  return facts.hasDeletedAtField && (facts.hasPublicRead || facts.grantsDelete);
-}
-
 /** Declare one authorization rule. */
 export function can(action: Action, condition: AbilityCondition = {}): Ability {
   return { action, condition };

package/src/derive.ts

@@ -3,7 +3,7 @@
  * the API handler's options blob.
  *
  * `exposedTables`, `hiddenColumns`, `protectedFields`, `rowOwnership`,
- * `softDelete`, `relations`, and `hooks` are all *views of the model*, so they
+ * `lifecycle`, `relations`, and `hooks` are all *views of the model*, so they
  * derive from it instead of a hand-maintained literal that drifts from the schema.
  *
  * Scope boundary: only the PER-TABLE surface derives here. App/handler-level
@@ -16,6 +16,7 @@ import type { ModelDescriptor } from './model';
 import type { ModelHooks } from './model';
 import { assertDeleteHookNames, assertDestroyHooks } from './lifecycle-hooks';
 import type { AbilityCondition } from './can';
+import { assertNoLegacySoftDelete } from './legacy-soft-delete';
 import { linkModels } from './link';
 
 /** The handler's RelationConfig shape, mirrored structurally (no @everystack/api dep). */
@@ -39,9 +40,8 @@ export interface DerivedHandlerConfig {
   protectedFields: Record<string, string[]>;
   /** `exceptRoles` is present only when a `can('manage', { role })` exists for the table. */
   rowOwnership: Record<string, { column: string; userField: string; exceptRoles?: string[] }>;
-  /** `lifecycle` (present only when a lifecycle model exists) lists the `lifecycle: true` tables;
-   *  each is also in `tables`, so the read filter applies to it. */
-  softDelete: { tables: string[]; lifecycle?: string[] };
+  /** The `lifecycle: true` tables, present only when a lifecycle model exists. */
+  lifecycle?: string[];
   relations: Record<string, Record<string, RelationConfig>>;
   hooks: Record<string, ModelHooks>;
 }
@@ -57,13 +57,13 @@ function primaryKeyOf(model: ModelDescriptor): string {
 }
 
 export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerConfig {
+  for (const model of models) assertNoLegacySoftDelete(model);
   linkModels(models);
   const exposedTables: string[] = [];
   const hiddenColumns: Record<string, string[]> = {};
   const hiddenColumnsExceptRoles: Record<string, string[]> = {};
   const protectedFields: Record<string, string[]> = {};
   const rowOwnership: DerivedHandlerConfig['rowOwnership'] = {};
-  const softDeleteTables: string[] = [];
   const lifecycleTables: string[] = [];
   const relations: Record<string, Record<string, RelationConfig>> = {};
   const hooks: Record<string, ModelHooks> = {};
@@ -114,13 +114,9 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       if (exceptRoles.length) rowOwnership[table].exceptRoles = exceptRoles;
     }
 
-    // Declared, not inferred — one `softDelete` decision drives both the API filter and the
-    // RLS guard, so the two can never disagree about what a soft-deleted row is.
-    if (model.softDelete) softDeleteTables.push(table);
     // A lifecycle table soft-deletes in the database (its delete trigger); the handler reads it as
     // a soft-delete table and drives that machinery instead of writing deleted_at itself.
     if (model.lifecycle) {
-      softDeleteTables.push(table);
       lifecycleTables.push(table);
       hiddenColumns[table] = [...new Set([...(hiddenColumns[table] ?? []), 'deletedBy', 'deletedBatch', 'deletedXid'])];
       hiddenColumnsExceptRoles[table] = exceptRoles;
@@ -176,7 +172,7 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
     ...(lifecycleTables.length ? { hiddenColumnsExceptRoles } : {}),
     protectedFields,
     rowOwnership,
-    softDelete: { tables: softDeleteTables, ...(lifecycleTables.length ? { lifecycle: lifecycleTables } : {}) },
+    ...(lifecycleTables.length ? { lifecycle: lifecycleTables } : {}),
     relations,
     hooks,
   };

package/src/derived.ts

@@ -461,6 +461,9 @@ export interface FunctionDescriptor {
  * Same rule as @everystack/server's withRole.
  */
 const OWNER_ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+/** The bare role-name rule, for every other place a module names a role (defineModule's roles.request). */
+export const BARE_ROLE_NAME = OWNER_ROLE_NAME;
+export const isBareRoleName = (role: string): boolean => OWNER_ROLE_NAME.test(role);
 
 /**
  * Refuse an owner that is not a bare lowercase role name. ONE implementation across

package/src/index.ts

@@ -23,8 +23,7 @@ export type { TableConstraint } from './constraints';
 export { sql } from './raw-sql';
 export type { RawSql } from './raw-sql';
 
-export { can, isColumnAbility, isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete, sessionlessAudience } from './can';
-export type { SoftDeleteFacts } from './can';
+export { can, isColumnAbility, isPublicReadAbility, isDeleteAbility, privilegesGrantDelete, sessionlessAudience } from './can';
 export type { Ability, AbilityCondition, Action } from './can';
 
 export { belongsTo, hasMany, hasOne } from './relations';
@@ -36,8 +35,8 @@ export { veto, isVeto } from './lifecycle-hooks';
 export { defineModel, defineMaterializedTable, LIFECYCLE_COLUMNS, LIFECYCLE_OWNER_ROLE, EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './model';
 export type { ModelDescriptor, ModelDefinition, ModelHooks, LifecycleOptions, DestroyContext, DestroyHook, LifecycleContext, HookVeto, BeforeLifecycleHook, AfterLifecycleHook, WrittenBy, ExtraPrivilege, TablePrivilege, DmlPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
-export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
-export type { Module, ModuleDefinition } from './module';
+export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles, moduleRequestRoles } from './module';
+export type { Module, ModuleDefinition, ModuleRoles } from './module';
 
 export {
   defineView, defineMaterializedView, defineFunction, defineSql, defineSequence,
@@ -53,6 +52,7 @@ export type {
 } from './derived';
 
 export { deriveHandlerConfig, deriveForceRlsCarveouts, deriveFunctionSchemas } from './derive';
+export { assertNoLegacySoftDelete } from './legacy-soft-delete';
 export type { DerivedHandlerConfig, RelationConfig } from './derive';
 
 export { ENSURE_DESTROY_LOG_SQL, DESTROY_LOG_MARKER_BODIES, DESTROY_LOG_MARKER_LANGUAGES, DESTROY_LOG_MARKER_SEARCH_PATH } from './destroy-log';

package/src/legacy-soft-delete.ts

@@ -0,0 +1,19 @@
+/**
+ * `softDelete` was removed from the model. defineModel refuses the key, but a descriptor built
+ * by an older @everystack/model, or exported by an older published package, never passes
+ * through it and may still carry the key. Compiled silently, its public read would lose the
+ * `deleted_at IS NULL` guard and the handler's DELETE would destroy rows it used to mark.
+ *
+ * So every path that links, derives or compiles models refuses such a descriptor: linkModels,
+ * deriveHandlerConfig and compileTableContract (the security boundary itself). Present with
+ * any value is refused, `false` included: the descriptor is from an older build either way.
+ */
+export function assertNoLegacySoftDelete(model: { table: string; schema?: string }): void {
+  if (!('softDelete' in model)) return;
+  const name = model.schema && model.schema !== 'public' ? `${model.schema}.${model.table}` : model.table;
+  throw new Error(
+    `model '${name}': softDelete was removed: this model was built by an older @everystack/model or comes from an older package; ` +
+      'upgrade it, or use lifecycle: true. ' +
+      "To keep a deleted_at filter on a read, write it on the ability: can('read', { ..., sql: sql`deleted_at IS NULL` }).",
+  );
+}

package/src/link.ts

@@ -1,4 +1,5 @@
 import type { ModelDescriptor } from './model';
+import { assertNoLegacySoftDelete } from './legacy-soft-delete';
 import { parseQualified } from './qualified';
 import { assertExternalTargets } from './external';
 import { relationDeleteActions } from './dependents';
@@ -49,6 +50,7 @@ export function referenceLocation(target: (() => unknown) | undefined, location:
  */
 export function linkModels<T extends readonly ModelDescriptor[]>(models: T): T {
   const uniqueModels = [...new Set(models)];
+  for (const model of uniqueModels) assertNoLegacySoftDelete(model);
   const byName = new Map<string, ModelDescriptor[]>();
   for (const model of uniqueModels) {
     const candidates = byName.get(model.table) ?? [];

package/src/model.ts

@@ -15,7 +15,7 @@ import { dependentWhereRefusal } from './dependents';
 import { field, type FieldBuilder } from './field';
 import { referenceLocation } from './link';
 import type { Ability } from './can';
-import { can, isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete, sessionlessAudience } from './can';
+import { can, sessionlessAudience } from './can';
 import { assertRelationShape, type Relation } from './relations';
 import { assertCheckNames, type TableConstraint } from './constraints';
 import { lifecycleCascadeHarm } from './dependents';
@@ -102,42 +102,18 @@ export interface ModelDefinition {
    */
   privileges?: Record<string, TablePrivilege[]>;
   /**
-   * What a soft delete MEANS on this table. It drives two different machines, and both
-   * consequences are real — a model declaring it should expect all of this:
-   *
-   *  - **The generic data API** (`deriveHandlerConfig` → `createHandler`): `DELETE` becomes
-   *    `UPDATE SET deleted_at = now()` instead of removing the row; and soft-deleted rows are
-   *    then filtered out of GET (for EVERY role, unless `?deleted=include|only`), out of
-   *    embedded relation reads, and out of UPDATE. This half applies to every model, whatever
-   *    its audience.
-   *  - **RLS**: `deleted_at IS NULL` is AND-ed into the PUBLIC read policies. This half applies
-   *    only where there is a public read — on an owner-scoped or admin-only model the compiled
-   *    contract is byte-identical either way (pinned in cli's `public-read-pin.test.ts`).
-   *
-   * **Required — not inferred — on any model with a `deletedAt` field that either has a public
-   * read OR grants DELETE** (`can('delete')`, or `can('manage')`, which is "all actions"). See
-   * {@link needsSoftDeleteDeclaration}, the one rule this and `db:pull` share.
-   *
-   * 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 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.
-   *
-   * It used to be inferred from the field's mere presence. A column named `deleted_at` is
-   * not a statement of visibility intent: it is carried for audit, for app-layer filtering,
-   * for half-finished migrations. Inferring the predicate made the compiler author a
-   * security rule nobody wrote — and because `db:pull` renders `deletedAt` straight from the
-   * live column, a brownfield model acquired it automatically and the FIRST plan narrowed a
-   * policy the adopter had written. `createHandler`'s own `softDelete: { column, tables }`
-   * was always explicit; this matches it. Convention may propose it, never enforce it.
+   * Removed. `lifecycle: true` is the one soft delete. defineModel refuses this key, `true` or
+   * `false`, so an upgrade never compiles quietly into a model whose read lost its
+   * `deleted_at IS NULL` guard or whose DELETE starts destroying rows it used to mark. For a
+   * soft delete, declare `lifecycle: true`; to keep a `deleted_at` filter on a read, write it on
+   * the ability: `can('read', { ..., sql: sql\`deleted_at IS NULL\` })`.
    */
-  softDelete?: boolean;
+  softDelete?: never;
   /**
    * `lifecycle: true` — a soft delete with a delay. defineModel generates four nullable columns
    * ({@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.
+   * `deletedBatch` uuid, `deletedXid` bigint. The author never declares them and declares a
+   * single-column primary key; each is refused here.
    *
    * `{ 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
@@ -223,8 +199,6 @@ export interface ModelDescriptor {
   writtenBy: WrittenBy;
   /** Beyond-CRUD privileges per role, unioned with what the abilities grant. See {@link ModelDefinition.privileges}. */
   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}. Always
    *  `true` on the descriptor, whichever form the definition used. */
   lifecycle?: true;
@@ -350,12 +324,6 @@ function assertLifecycle(table: string, def: ModelDefinition): void {
   } 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(
-      `model '${table}': lifecycle replaces softDelete — delete softDelete: ${String(def.softDelete)}. ` +
-        `lifecycle: true already declares what a delete does.`,
-    );
-  }
   for (const name of LIFECYCLE_RESERVED) {
     if (name in def.fields) {
       throw new Error(
@@ -483,7 +451,22 @@ function assertLifecycleRestoreSafe(table: string, def: ModelDefinition): void {
   }
 }
 
+/**
+ * `softDelete` was removed. Refuse the key, `true` or `false`, rather than ignore it: an ignored
+ * `true` would drop the `deleted_at IS NULL` guard from a public read and turn a marking DELETE
+ * into a destroying one, with nothing in any diff to review.
+ */
+function assertNoSoftDelete(table: string, def: ModelDefinition): void {
+  if (!('softDelete' in def)) return;
+  throw new Error(
+    `model '${table}': softDelete was removed. For a soft delete, use lifecycle: true. ` +
+      "To keep a deleted_at filter on a read, write it on the ability: can('read', { ..., sql: sql`deleted_at IS NULL` }). " +
+      'If it said false, delete the line.',
+  );
+}
+
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
+  assertNoSoftDelete(table, def);
   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.
@@ -643,52 +626,6 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     }
   }
 
-  // The soft-delete guard used to be inferred from the field's presence, which meant a model
-  // could gain — or, once the inference was removed, silently LOSE — a predicate that decides
-  // what anonymous users can see, with nothing in any diff to review. Neither default is safe,
-  // so there is no default: on the exact set of models where the answer changes behaviour, it
-  // must be declared. `softDelete: true` is what the inference used to do.
-  //
-  // That set is NOT "has a public read". It is the union of two axes — see
-  // `needsSoftDeleteDeclaration`, which is the whole rule and is shared with db:pull so the two
-  // surfaces cannot drift on it.
-  // `isPublicReadAbility`, not a local copy: this refusal and db:pull's renderer were asking
-  // the same question — "can a caller with no session see these rows?" — and answering it
-  // differently. The renderer already counted `role: 'anon'`; this refusal did not, so a table
-  // whose authenticated read diverges (rendered as an anon-scoped read) slipped past the very
-  // decision the refusal exists to force. It now fires on the anonymous audience however it is
-  // spelled. Explicit `softDelete: false` remains the one-line answer, and pull writes that
-  // line into every model it renders, so a pulled checkout keeps loading.
-  const hasPublicRead = (def.abilities ?? []).some(isPublicReadAbility);
-  // Either spelling of a reachable DELETE. `privileges` matters most on an `rls: false` table,
-  // where the grant is unrestricted and no policy stands between it and every row.
-  const grantsDelete = (def.abilities ?? []).some(isDeleteAbility) || privilegesGrantDelete(def.privileges);
-  // Both spellings of the field key. The guard used to test `'deletedAt' in def.fields`
-  // literally, so a model keying the column `deleted_at` — the shape a snake_case brownfield
-  // schema pulls as — carried a soft-delete column past a guard that never looked at it.
-  const softDeleteField = 'deletedAt' in def.fields || 'deleted_at' in def.fields;
-  // A lifecycle model has declared what a delete does; its generated deletedAt is not an author field.
-  if (needsSoftDeleteDeclaration({ hasDeletedAtField: softDeleteField, hasPublicRead, grantsDelete }) && def.softDelete === undefined) {
-    // DURABILITY FIRST. The old message called this "a visibility decision", which is false
-    // for exactly the models that broke: with no public read, `softDelete: true` adds no
-    // policy predicate at all. Naming the wrong consequence teaches the wrong fix, so each
-    // axis is stated only when it actually fired.
-    const why = grantsDelete
-      ? `grants DELETE (via can('delete'), can('manage') — which is "all actions" — or a privileges DELETE grant), `
-        + `so it must declare softDelete. `
-        + `This is a durability decision: softDelete: true makes a DELETE mark deleted_at instead of destroying the row; `
-        + `softDelete: false makes DELETE permanent.`
-      : `has a public read, so it must declare softDelete.`;
-    const visibility = hasPublicRead
-      ? ` It is also a visibility decision: softDelete: true excludes soft-deleted rows from the public read policies `
-        + `(what the compiler used to infer from the field's presence); softDelete: false leaves them readable.`
-      : '';
-    throw new Error(
-      `model '${table}': has a 'deletedAt' field and ${why}${visibility} `
-        + `What a DELETE destroys is declared, not guessed — add softDelete: true or softDelete: false.`,
-    );
-  }
-
   // A privilege outside the table-privilege vocabulary is still refused — that is a typo, not a
   // state a database can hold. The DML four ARE accepted now: they used to throw here so that a
   // grant could never be declared without its policy, but that invariant was vacuous for any
@@ -767,7 +704,6 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     writtenBy: def.writtenBy ?? 'app',
     privileges: def.privileges ?? {},
     // 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',

package/src/module.ts

@@ -21,7 +21,7 @@
 
 import { LIFECYCLE_OWNER_ROLE, type ModelDescriptor } from './model';
 import type { DerivedDescriptor, SequenceDescriptor } from './derived';
-import { rejectHoles, functionArgSignature } from './derived';
+import { rejectHoles, functionArgSignature, isBareRoleName, BARE_ROLE_NAME } from './derived';
 import { deriveFunctionSchemas } from './derive';
 import { parseQualified } from './qualified';
 import { linkModels } from './link';
@@ -66,6 +66,20 @@ export interface ModuleDefinition {
    * baseline fails the gate. Exempt from reconciliation, never exempt from the report.
    */
   governedRoles?: string[];
+  /**
+   * What the database's roles are FOR, where the grants alone cannot tell.
+   *
+   * `request` — the roles a request can become: the roles the API sets for anon, signed-in and
+   * admin requests, and the login the application connects as. The lifecycle catalog check treats
+   * every role the models grant to as one a request can be. A least-privilege SECURITY DEFINER
+   * role that does not own the tables must still be granted DML, so without this list it counts
+   * as a request role, and every trigger function it owns on a lifecycle table is refused.
+   * Declared, a declared `owner:` that no request role can reach (and that cannot log in) no
+   * longer counts. Undeclared, the check runs as before.
+   *
+   * Refused: an empty list, `PUBLIC`, and `everystack_lifecycle`.
+   */
+  roles?: ModuleRoles;
   /**
    * Package-owned SQL emitted after the tables — SECURITY DEFINER functions, triggers, etc.
    * A thunk so it is generated lazily and can take run-specific input (the app's event-trigger
@@ -87,10 +101,39 @@ export interface Module {
   derived: DerivedDescriptor[];
   /** Roles this module's authz governs beyond the ones its models name. Widen-only. */
   governedRoles: string[];
+  /** What the roles are for — see {@link ModuleDefinition.roles}. Absent when not declared. */
+  roles?: ModuleRoles;
   /** Function-SQL thunks, normalized to an array so composing modules just concatenates. */
   functions: Array<() => string>;
 }
 
+/** {@link ModuleDefinition.roles}. On a Module, `request` is deduped and sorted. */
+export interface ModuleRoles {
+  /** The roles a request can become. */
+  request?: string[];
+}
+
+/** Validate and normalize `roles.request`: non-empty, real role names, never PUBLIC or the lifecycle role. */
+function normalizeRoles(roles: ModuleRoles): ModuleRoles {
+  if (roles.request === undefined) return {};
+  if (roles.request.length === 0) {
+    throw new Error('defineModule: roles.request is empty. Name every role a request can become (the API\'s request roles and the '
+      + 'login the application connects as), or leave roles.request out; an empty list would treat no role as a request role.');
+  }
+  for (const role of roles.request) {
+    if (role === 'PUBLIC' || role === 'public') {
+      throw new Error(`defineModule: roles.request names '${role}'. PUBLIC is every role, not one a request becomes; name the roles themselves.`);
+    }
+    if (role === LIFECYCLE_OWNER_ROLE) {
+      throw new Error(`defineModule: roles.request names '${role}'. That role is reserved for the lifecycle soft delete; a request must never become it.`);
+    }
+    if (!isBareRoleName(role)) {
+      throw new Error(`defineModule: roles.request names '${role}', which is not a bare lowercase role name (${BARE_ROLE_NAME}).`);
+    }
+  }
+  return { request: [...new Set(roles.request)].sort() };
+}
+
 /** Declare a package's database slice. Empty fields default to nothing — a models-only module is fine. */
 export function defineModule(def: ModuleDefinition): Module {
   // The loud undefined gate — a missing import composes as a hole; name it here,
@@ -124,6 +167,7 @@ export function defineModule(def: ModuleDefinition): Module {
     sequences: def.sequences ?? [],
     derived: def.derived ?? [],
     governedRoles: [...new Set(def.governedRoles ?? [])].sort(),
+    ...(def.roles ? { roles: normalizeRoles(def.roles) } : {}),
     functions: def.functions ? [def.functions] : [],
   };
 }
@@ -232,3 +276,13 @@ export function moduleGovernedRoles(modules: Module[]): string[] {
   const lifecycle = modules.some((m) => m.models.some((model) => model.lifecycle));
   return [...new Set([...modules.flatMap((m) => m.governedRoles), ...(lifecycle ? [LIFECYCLE_OWNER_ROLE] : [])])].sort();
 }
+
+/**
+ * The union of every module's request roles, sorted. Undefined when no module declares any, so a
+ * caller can tell "not declared" (the lifecycle check runs as before) from a declared list.
+ */
+export function moduleRequestRoles(modules: Module[]): string[] | undefined {
+  const declared = modules.filter((m) => m.roles?.request !== undefined);
+  if (declared.length === 0) return undefined;
+  return [...new Set(declared.flatMap((m) => m.roles!.request!))].sort();
+}

package/src/wire.ts

@@ -245,6 +245,19 @@ export interface ReconcileWirePayload extends ModelWireEnvelope {
    * declared object is lifecycle-owned = the reconcile refuses (fail closed).
    */
   applicationRoles?: string[];
+  /**
+   * The roles a request can become (`roles: { request }` on the modules), and every owner a
+   * declared derived object names. The catalog check reads them beside `applicationRoles`, so a
+   * definer role the models grant to is not mistaken for a request role.
+   *
+   * OPTIONAL, and added without a contract bump on purpose: absent (an older CLI), the server
+   * checks exactly as before. An older server ignores them and runs the check from before they
+   * existed: it refuses more, but it skips the live checks on the request roles (missing,
+   * superuser, BYPASSRLS). db:apply's CLI-side gates still run those; `db:reconcile --apply
+   * --stage` has none, so against an older server it does not. See wire-shape.test.ts.
+   */
+  requestRoles?: string[];
+  declaredOwners?: string[];
   actor?: string | null;
   gitRef?: string | null;
 }