@everystack/model 0.4.14 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "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

@@ -138,6 +138,80 @@ export function isPublicReadAbility(ability: Ability): boolean {
     && (!ability.condition.role || ability.condition.role === 'anon');
 }
 
+/**
+ * Does this ability hand out DELETE?
+ *
+ * `manage` is "all actions" and compiles to the admin-bypass ALL policy, so it carries DELETE
+ * even though nothing spells it. Counting only the literal `delete` verb would leave the
+ * soft-delete hazard one grant over — which is exactly the shape `@everystack/auth`'s own
+ * user model has: `deletedAt`, no public read, no `can('delete')`, and an admin `manage` that
+ * can still destroy the row.
+ */
+export function isDeleteAbility(ability: Ability): boolean {
+  return ability.action === 'delete' || ability.action === 'manage';
+}
+
+/**
+ * Does a `privileges` map hand out DELETE?
+ *
+ * The second spelling of a reachable DELETE, and the one that slipped the first version of
+ * this rule. `can()` decides a grant AND a policy together; `privileges` is the key for a
+ * grant that has no policy — which is exactly what `db:pull` renders when it finds a live
+ * DELETE grant no policy covers. On a `rls: false` table that grant is unrestricted, so the
+ * table can be destroyed row by row without a single `can('delete')` in the model.
+ *
+ * Takes the map rather than a descriptor because both callers already hold one in the same
+ * shape (a model's `privileges`, and `db:pull`'s `DerivedAbilities.privileges`), so unlike the
+ * ability axis this one needs no second representation and cannot drift at all.
+ */
+export function privilegesGrantDelete(privileges: Record<string, readonly string[]> | undefined): boolean {
+  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/constraints.ts

@@ -19,13 +19,13 @@ export type TableConstraint =
   /** `CHECK (<predicate>)` — a raw SQL predicate, typically spanning columns. */
   | { kind: 'check'; predicate: string }
   /** A standalone index — `CREATE [UNIQUE] INDEX [USING <method>] … (keys) [INCLUDE (cols)] [WHERE <predicate>]`. */
-  | { kind: 'index'; columns: string[]; isUnique: boolean; predicate?: string; method?: string; includeColumns?: string[]; rawPositions?: boolean[] }
+  | { kind: 'index'; columns: string[]; isUnique: boolean; predicate?: string; method?: string; includeColumns?: string[]; rawPositions?: boolean[]; indexName?: string }
   /**
    * A multi-column `FOREIGN KEY (a, b) REFERENCES other (x, y)` — the composite a column-scoped
    * `.references()` can't carry. Local field keys, a model thunk for the target, and the target's
    * field keys; optional `onDelete`/`onUpdate` referential actions.
    */
-  | { kind: 'foreignKey'; columns: string[]; references: () => unknown; refColumns: string[]; onDelete?: ReferentialAction; onUpdate?: ReferentialAction };
+  | { kind: 'foreignKey'; columns: string[]; references: () => unknown; refColumns: string[]; onDelete?: ReferentialAction; onUpdate?: ReferentialAction; constraintName?: string };
 
 /** A composite unique constraint over the given field keys: `unique('authorId', 'slug')`. */
 export function unique(...columns: string[]): TableConstraint {
@@ -47,7 +47,7 @@ export function foreignKey(
   columns: string[],
   references: () => unknown,
   refColumns: string[],
-  opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction },
+  opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string },
 ): TableConstraint {
   return {
     kind: 'foreignKey',
@@ -56,6 +56,8 @@ export function foreignKey(
     refColumns,
     ...(opts?.onDelete ? { onDelete: opts.onDelete } : {}),
     ...(opts?.onUpdate ? { onUpdate: opts.onUpdate } : {}),
+    // The generated name is the FALLBACK; an adopted database keeps the name it arrived with.
+    ...(opts?.name !== undefined ? { constraintName: assertConstraintName(opts.name, 'foreign key') } : {}),
   };
 }
 
@@ -114,6 +116,50 @@ export class IndexBuilder {
     this.includeColumns = columns;
     return this;
   }
+
+  /**
+   * The index's NAME, when it has to be a specific one.
+   *
+   * Undeclared, the compiler generates `<table>_<cols>_index`, which is fine for a greenfield
+   * model and wrong for an adopted database. A brownfield schema arrives with names its previous
+   * tooling chose — a Rails app's `index_contents_on_destination_id` becomes
+   * `contents_destination_id_index` on a rebuild — and on one consumer's database ~200 indexes
+   * renamed that way. Counts and definitions matched, so nothing failed loudly; what broke was
+   * everything that names an index: a planner regression test, runbooks, `pg_stat_user_indexes`
+   * history, REINDEX scripts.
+   *
+   * So the generated name is the FALLBACK, never the default. `db:pull` emits this whenever the
+   * live name is not the one the generator would have produced.
+   */
+  name(indexName: string): this {
+    this.indexName = assertConstraintName(indexName, 'index');
+    return this;
+  }
+
+  /** The declared name, when {@link IndexBuilder.name} set one. */
+  indexName?: string;
+}
+
+/**
+ * An unquoted PostgreSQL identifier. A declared object name reaches `CREATE INDEX`,
+ * `ALTER INDEX … RENAME TO` and `ALTER TABLE … RENAME CONSTRAINT` by interpolation, none of
+ * which takes a parameter — so it is validated at DECLARATION, far from the SQL, and never
+ * trusted at the point of emission. Same rule, and the same reason, as a function's owner.
+ */
+const INDEX_NAME = /^[a-z_][a-z0-9_$]*$/;
+
+/**
+ * Validate a declared SQL object name, returning it. ONE implementation, shared by every
+ * surface that lets a model name a database object — an index, a foreign key constraint —
+ * because two copies of a validation rule is how one of them ends up laxer than the other.
+ */
+export function assertConstraintName(name: string, what = 'constraint'): string {
+  if (!INDEX_NAME.test(name)) {
+    throw new Error(
+      `${what} name '${name}' is not a bare lowercase identifier (${INDEX_NAME}). It is interpolated into DDL that takes no parameters, so it is refused here rather than built into SQL.`,
+    );
+  }
+  return name;
 }
 
 export function index(...entries: Array<string | RawSql>): IndexBuilder {

package/src/derived.ts

@@ -348,8 +348,49 @@ export interface FunctionDefinition {
   language: 'sql' | 'plpgsql';
   /** Default `'invoker'` (the safe one). `'definer'` REQUIRES a pinned searchPath. */
   security?: 'invoker' | 'definer';
-  /** An ARRAY of schemas, not a comma string. */
-  searchPath?: string[];
+  /**
+   * The role that OWNS the function — a privilege boundary, not a cosmetic attribute.
+   *
+   * A `SECURITY DEFINER` function executes with its owner's rights. Undeclared, the owner is
+   * whoever ran the build, so a database built by an RDS master runs every definer function
+   * as the master, and `db:fingerprint` still reports MATCH. Declare it and the boundary
+   * becomes part of the state the fingerprint and `db:check` can see.
+   *
+   * Also load-bearing for the deliberate case: a function owned by a narrow role — one whose
+   * RLS policy folds to a constant so an index can drive the lookup, granted to nobody —
+   * loses that barrier entirely the moment it is owned by someone else.
+   *
+   * Two things the DATABASE requires of whoever applies this, both measured on PG16:
+   * the applying role must be able to `SET ROLE` to the owner, and the owner must hold
+   * `CREATE` on the function's schema. Membership can be granted as
+   * `GRANT <owner> TO <builder> WITH INHERIT FALSE, SET TRUE` — that satisfies the first
+   * without the builder inheriting any of the owner's privileges.
+   *
+   * Defaults to undefined: the function is owned by whoever creates it (PostgreSQL's own
+   * behaviour, unchanged). `db:check` warns for a definer function with no declared owner.
+   */
+  owner?: string;
+  /**
+   * An ARRAY of schemas, not a comma string — or the sentinel `'unpinned'`.
+   *
+   * `'unpinned'` says the function has NO `SET search_path`, and it is how a brownfield
+   * function gets declared truthfully. It exists because the alternative was worse: `db:pull`
+   * used to INVENT `['pg_catalog']` for any definer function whose live `proconfig` was empty,
+   * and a build from those models then applied the invented pin for real, so functions that
+   * had always resolved `public` stopped resolving it. Sign-up and password change died on a
+   * database built from the consumer's own models, with every gate green beforehand.
+   *
+   * An unpinned SECURITY DEFINER function is a latent vulnerability that WORKS. An invented pin
+   * is an outage that passes every check. Worse, fabrication corrodes fingerprint, plan and
+   * apply, all of which rest on the model telling the truth. So the parser records what is
+   * there, and the opinion lives in the linter: `db:check` reports every unpinned definer
+   * function and can SUGGEST a pin from what the body references. It never applies one.
+   *
+   * The sentinel is explicit on purpose. `null` would blur with `undefined` across
+   * serialization and read as a mistake; OMITTING it on a definer function still throws,
+   * exactly as it always has. Strictness by explicitness, never by provenance.
+   */
+  searchPath?: string[] | 'unpinned';
   /** Default `'volatile'` (PostgreSQL's own). `immutable` enables expression indexes. */
   volatility?: 'immutable' | 'stable' | 'volatile';
   dependsOn?: DependsOnRef[];
@@ -386,7 +427,10 @@ export interface FunctionDescriptor {
   returns: string | SetofReturn;
   language: 'sql' | 'plpgsql';
   security: 'invoker' | 'definer';
-  searchPath?: string[];
+  /** The declared owning role — see {@link FunctionDefinition.owner}. */
+  owner?: string;
+  /** See {@link FunctionDefinition.searchPath}. `'unpinned'` = no `SET search_path`, declared. */
+  searchPath?: string[] | 'unpinned';
   volatility: 'immutable' | 'stable' | 'volatile';
   dependsOn: DependsOnRef[];
   abilities: Ability[];
@@ -396,12 +440,45 @@ export interface FunctionDescriptor {
   body: string;
 }
 
+/**
+ * An unquoted PostgreSQL role name. The owner is interpolated into `SET ROLE` and
+ * `ALTER … OWNER TO`, neither of which takes a parameter, so it is validated HERE — at
+ * declaration time, far from the SQL — rather than trusted at the point of emission.
+ * Same rule as @everystack/server's withRole.
+ */
+const OWNER_ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * Refuse an owner that is not a bare lowercase role name. ONE implementation across
+ * defineFunction, defineView and defineMaterializedView — the owner is interpolated into
+ * `SET ROLE` / `ALTER … OWNER TO`, and three copies of that gate is how one of them ends up
+ * missing it.
+ */
+function assertOwnerRole(kind: string, name: string, owner: string | undefined): void {
+  if (owner === undefined || OWNER_ROLE_NAME.test(owner)) return;
+  throw new Error(
+    `${kind} '${name}': owner '${owner}' is not a bare lowercase role name (${OWNER_ROLE_NAME}). The owner is interpolated into SET ROLE / ALTER ... OWNER TO, which take no parameters — a quoted, mixed-case or generated name is refused here rather than built into SQL.`,
+  );
+}
+
 export function defineFunction(name: string, def: FunctionDefinition): FunctionDescriptor {
   rejectHoles(`function '${name}'`, 'dependsOn', def.dependsOn);
   const security = def.security ?? 'invoker';
+  assertOwnerRole('function', name, def.owner);
+  // The sentinel is the ONLY string this takes. A typo would otherwise read as "unpinned" and
+  // silently strip a real pin — the exact class of silent security change this feature exists
+  // to stop, arriving through the door marked "honesty".
+  if (typeof def.searchPath === 'string' && def.searchPath !== 'unpinned') {
+    throw new Error(
+      `function '${name}': searchPath must be an array of schemas, or the sentinel 'unpinned' — got '${def.searchPath}'.`,
+    );
+  }
+  // OMISSION still throws. `searchPath: 'unpinned'` is an ANSWER — "this function has no
+  // SET search_path, and I am saying so" — while leaving it out is silence, which is what the
+  // landmine looks like. Strictness by explicitness, never by provenance.
   if (security === 'definer' && (!def.searchPath || def.searchPath.length === 0)) {
     throw new Error(
-      `function '${name}': SECURITY DEFINER without a pinned searchPath is the classic landmine — pin searchPath: ['pg_catalog'] (plus the schemas the body needs), or use security: 'invoker'.`,
+      `function '${name}': SECURITY DEFINER without a pinned searchPath is the classic landmine — pin searchPath: ['pg_catalog'] (plus the schemas the body needs), declare searchPath: 'unpinned' if the live function genuinely has none, or use security: 'invoker'.`,
     );
   }
   const args = def.args ?? [];
@@ -443,6 +520,7 @@ export function defineFunction(name: string, def: FunctionDefinition): FunctionD
     returns: def.returns,
     language: def.language,
     security,
+    ...(def.owner ? { owner: def.owner } : {}),
     ...(def.searchPath ? { searchPath: def.searchPath } : {}),
     volatility: def.volatility ?? 'volatile',
     dependsOn: def.dependsOn ?? [],
@@ -465,6 +543,28 @@ export interface ViewDefinition {
    * the body must seal what it exposes).
    */
   securityInvoker: boolean;
+  /**
+   * The role that OWNS the relation — a privilege boundary whenever the view is not
+   * `securityInvoker`.
+   *
+   * A `security_invoker = false` view executes with its OWNER's rights: the body reads through
+   * the owner's grants and the owner's RLS, and the reader needs only a grant on the view. That
+   * is the whole sealed-slice pattern, and it means the owner IS the security boundary, exactly
+   * as it is for a `SECURITY DEFINER` function.
+   *
+   * Undeclared, the owner is whoever ran the build. An `admin`-owned view rebuilt by a migrator
+   * becomes migrator-owned: `admin` can no longer read through it, the slice now reads with the
+   * migrator's rights instead, and `db:fingerprint` still reports MATCH. Measured on a
+   * consumer's `public.users_self`.
+   *
+   * Two things the DATABASE requires of whoever applies this, the same pair `defineFunction`
+   * documents: the applying role must be able to `SET ROLE` to the owner, and the owner must
+   * hold `CREATE` on the relation's schema. `GRANT <owner> TO <builder> WITH INHERIT FALSE,
+   * SET TRUE` satisfies the first without the builder inheriting the owner's privileges.
+   *
+   * Defaults to undefined: owned by whoever creates it (PostgreSQL's own behaviour, unchanged).
+   */
+  owner?: string;
   abilities?: Ability[];
   /** Grants that EXIST, recorded rather than chosen — see {@link validateRelationPrivileges}. */
   privileges?: Record<string, string[]>;
@@ -494,6 +594,8 @@ export interface ViewDescriptor {
   kind: 'view';
   name: string;
   securityInvoker: boolean;
+  /** The declared owning role — see {@link ViewDefinition.owner}. */
+  owner?: string;
   abilities: Ability[];
   privileges: Record<string, string[]>;
   dependsOn: DependsOnRef[];
@@ -516,10 +618,12 @@ export function defineView(name: string, def: ViewDefinition): ViewDescriptor {
   validatePrivateContradiction('view', name, def.private, def.abilities);
   validateRelationFields('view', name, def.fields, def.private);
   validateTriggersFor('view', name, def.triggers ?? []);
+  assertOwnerRole('view', name, def.owner);
   return {
     kind: 'view',
     name,
     securityInvoker: def.securityInvoker,
+    ...(def.owner ? { owner: def.owner } : {}),
     abilities: def.abilities ?? [],
     privileges,
     dependsOn: def.dependsOn ?? [],
@@ -536,6 +640,14 @@ export function defineView(name: string, def: ViewDefinition): ViewDescriptor {
 // ---------------------------------------------------------------------------
 
 export interface MaterializedViewDefinition {
+  /**
+   * The role that OWNS the materialized view — see {@link ViewDefinition.owner}.
+   *
+   * A matview has no `security_invoker`: its contents are computed at REFRESH time with the
+   * owner's rights, always. So the owner decides what the stored rows can contain, and a
+   * rebuild that changes it silently changes what a refresh is able to see.
+   */
+  owner?: string;
   abilities?: Ability[];
   /** Grants that EXIST, recorded rather than chosen — see {@link validateRelationPrivileges}. */
   privileges?: Record<string, string[]>;
@@ -555,6 +667,8 @@ export interface MaterializedViewDefinition {
 export interface MaterializedViewDescriptor {
   kind: 'materialized view';
   name: string;
+  /** The declared owning role — see {@link ViewDefinition.owner}. */
+  owner?: string;
   abilities: Ability[];
   privileges: Record<string, string[]>;
   dependsOn: DependsOnRef[];
@@ -579,9 +693,11 @@ export function defineMaterializedView(name: string, def: MaterializedViewDefini
       `materialized view '${name}': REFRESH CONCURRENTLY requires a unique, non-partial index — declare indexes: [index('...').unique()].`,
     );
   }
+  assertOwnerRole('materialized view', name, def.owner);
   return {
     kind: 'materialized view',
     name,
+    ...(def.owner ? { owner: def.owner } : {}),
     abilities: def.abilities ?? [],
     privileges,
     dependsOn: def.dependsOn ?? [],

package/src/drizzle.ts

@@ -68,6 +68,13 @@ function getEnum(spec: FieldSpec): ReturnType<typeof pgEnum> {
   return e;
 }
 
+/**
+ * Field types whose drizzle builder carries `generatedAlwaysAsIdentity` — the integer family
+ * (`PgIntColumnBaseBuilder`). `pgType` can also be an identity column in Postgres (`smallint`),
+ * but it compiles to `customType`, which has no identity builder.
+ */
+const INTEGER_IDENTITY_TYPES = new Set<FieldSpec['type']>(['integer', 'bigint']);
+
 /** Map a field's Postgres type to a drizzle pg-core column builder (no modifiers yet). */
 function baseColumn(columnName: string, spec: FieldSpec): PgColumnBuilderBase {
   switch (spec.type) {
@@ -143,7 +150,14 @@ export function toDrizzleTable(model: ModelDescriptor): PgTableWithColumns<any>
     let col: any = baseColumn(columnName, spec);
 
     if (spec.isArray) col = col.array();
-    if (spec.isNotNull) col = col.notNull();
+    // Identity comes FIRST and stands in for notNull: drizzle's builder sets notNull AND
+    // hasDefault, and hasDefault is what makes the column optional on insert. Only the integer
+    // family carries the builder, so a `pgType` identity column keeps plain `.notNull()` — the
+    // DDL still declares the identity, only the runtime type is less precise.
+    const identity = INTEGER_IDENTITY_TYPES.has(spec.type) ? spec.identity : undefined;
+    if (identity === 'always') col = col.generatedAlwaysAsIdentity();
+    else if (identity === 'byDefault') col = col.generatedByDefaultAsIdentity();
+    else if (spec.isNotNull) col = col.notNull();
     if (spec.isUnique) col = col.unique();
 
     if (spec.defaultKind === 'now') col = col.defaultNow();

package/src/field.ts

@@ -13,6 +13,7 @@
 
 import type { RawSql } from './raw-sql';
 import { pgTypeRefusal } from './pg-type';
+import { assertConstraintName } from './constraints';
 
 export type FieldType =
   | 'text'
@@ -82,6 +83,27 @@ export interface FieldSpec {
   onDelete?: ReferentialAction;
   /** `ON UPDATE` action for the FK. Omitted (or `'no action'`) is the Postgres default. */
   onUpdate?: ReferentialAction;
+  /**
+   * The FK CONSTRAINT's name, when it has to be a specific one.
+   *
+   * Undeclared, the compiler generates `<table>_<cols>_<target>_<refcols>_fk`. An adopted
+   * database arrives with its previous tooling's names — a Rails app's `fk_rails_9a1b2c3d4e` —
+   * and rebuilding under ours renames every one of them. Measured: the differ keys a foreign key
+   * on its CONTENT with no name at all, so that rename produced zero changes and every gate
+   * stayed green. Same defect as index names, one object over.
+   */
+  constraintName?: string;
+  /**
+   * `GENERATED ALWAYS AS IDENTITY` / `GENERATED BY DEFAULT AS IDENTITY`.
+   *
+   * The SQL-standard replacement for `serial`, and a DIFFERENT mechanism: serial is sugar for a
+   * default drawing on an owned sequence, identity lives on the column itself (`attidentity`) and
+   * has no default at all. `ALWAYS` additionally refuses a client-supplied value unless the write
+   * says `OVERRIDING SYSTEM VALUE` — that refusal is the point, so it is declared, not inferred.
+   *
+   * Postgres makes an identity column NOT NULL, so the builder sets that too.
+   */
+  identity?: 'always' | 'byDefault';
   default?: unknown;
   defaultKind?: DefaultKind;
   /** A Zod schema, stored verbatim. Consumed by the field bridge (Phase 4); inert today. */
@@ -96,6 +118,16 @@ export interface FieldSpec {
   renamedFrom?: string;
 }
 
+/**
+ * The field types an identity column may sit on.
+ *
+ * Postgres restricts `GENERATED … AS IDENTITY` to the integer family. `pgType` is included
+ * because that is how the vocabulary carries a `smallint` — a real identity type this factory
+ * has no first-class call for — and the exact string is the author's word about the type; a
+ * wrong one fails at CREATE TABLE with Postgres's own message.
+ */
+const IDENTITY_TYPES = new Set<FieldType>(['integer', 'bigint', 'pgType']);
+
 /**
  * Fluent, mutable builder. Every modifier returns `this` so declarations chain:
  * `field.text().notNull().private()`. The accumulated {@link FieldSpec} is read
@@ -179,10 +211,46 @@ export class FieldBuilder {
    * `onDelete`/`onUpdate` referential actions are column-scoped, so they live here, not on
    * the table — `field.uuid().references(() => User, { onDelete: 'cascade' })`.
    */
-  references(target: () => unknown, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction }): this {
+  references(target: () => unknown, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string }): this {
     this.spec.references = target;
     if (opts?.onDelete) this.spec.onDelete = opts.onDelete;
     if (opts?.onUpdate) this.spec.onUpdate = opts.onUpdate;
+    if (opts?.name !== undefined) this.spec.constraintName = assertConstraintName(opts.name, 'foreign key');
+    return this;
+  }
+
+  /**
+   * `GENERATED ALWAYS AS IDENTITY` — Postgres supplies the value and REFUSES a client-supplied
+   * one (a write must say `OVERRIDING SYSTEM VALUE` to get past it). The strict form, and the
+   * right default for a surrogate key nothing outside the database should choose.
+   */
+  generatedAlwaysAsIdentity(): this {
+    return this.setIdentity('always');
+  }
+
+  /**
+   * `GENERATED BY DEFAULT AS IDENTITY` — Postgres supplies the value when the write omits the
+   * column, and accepts an explicit one when it does not. The permissive form; it is what a
+   * `serial` column behaves like, spelled the standard way.
+   */
+  generatedByDefaultAsIdentity(): this {
+    return this.setIdentity('byDefault');
+  }
+
+  private setIdentity(kind: 'always' | 'byDefault'): this {
+    // Postgres allows identity only on an integer type. `serial` is the other sequence-backed
+    // mechanism, not a second one to stack — a column has one auto-value or none. Refused at
+    // DECLARATION so the error names the call, rather than surfacing as a CREATE TABLE failure
+    // several commands later.
+    if (this.spec.type === 'serial' || this.spec.type === 'bigserial') {
+      throw new Error(`field.${this.spec.type}() is already sequence-backed — use field.${this.spec.type === 'serial' ? 'integer' : 'bigint'}().${kind === 'always' ? 'generatedAlwaysAsIdentity' : 'generatedByDefaultAsIdentity'}() instead of both`);
+    }
+    if (!IDENTITY_TYPES.has(this.spec.type)) {
+      throw new Error(`GENERATED … AS IDENTITY is only valid on an integer column; field.${this.spec.type}() is not one`);
+    }
+    this.spec.identity = kind;
+    // Postgres makes an identity column NOT NULL whether or not anyone wrote it.
+    this.spec.isNotNull = true;
     return this;
   }
 

package/src/index.ts

@@ -20,7 +20,8 @@ export type { TableConstraint } from './constraints';
 export { sql } from './raw-sql';
 export type { RawSql } from './raw-sql';
 
-export { can, isColumnAbility, isPublicReadAbility } from './can';
+export { can, isColumnAbility, isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete } from './can';
+export type { SoftDeleteFacts } from './can';
 export type { Ability, AbilityCondition, Action } from './can';
 
 export { belongsTo, hasMany } from './relations';

package/src/model.ts

@@ -13,7 +13,7 @@
 
 import type { FieldBuilder } from './field';
 import type { Ability } from './can';
-import { isPublicReadAbility } from './can';
+import { isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete } from './can';
 import type { Relation } from './relations';
 import type { TableConstraint } from './constraints';
 import type { RawSql } from './raw-sql';
@@ -125,9 +125,27 @@ export interface ModelDefinition {
    */
   privileges?: Record<string, TablePrivilege[]>;
   /**
-   * `true` excludes soft-deleted rows (`deleted_at IS NULL`) from the public read policies
-   * and from the generic data API. **Required — not inferred — on any model that has a
-   * `deletedAt` field and a public read.**
+   * 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 purge 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,
@@ -345,9 +363,12 @@ 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 (a
-  // `deletedAt` field plus a public read), it must be declared. `softDelete: true` is what the
-  // inference used to do.
+  // 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
@@ -356,15 +377,31 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
   // 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;
-  if (softDeleteField && hasPublicRead && def.softDelete === undefined) {
+  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 a public read, so it must declare softDelete. `
-        + `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. This is a visibility decision, so it is declared, not guessed.`,
+      `model '${table}': has a 'deletedAt' field and ${why}${visibility} `
+        + `What a DELETE destroys is declared, not guessed — add softDelete: true or softDelete: false.`,
     );
   }