@everystack/model 0.4.13 → 0.4.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "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/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/model.ts

@@ -174,6 +174,23 @@ export interface ModelDefinition {
    * just not exposed. Named `private` to avoid colliding with `schema: 'public'`.
    */
   private?: boolean;
+  /**
+   * `rls: false` declares this table's row security OFF — authorization is grants-only,
+   * exactly as a brownfield database holds it (`db:pull` writes this line when the live
+   * table has RLS disabled and no ability renders). Without it the compiler declares RLS
+   * ENABLED, and the first plan after adopting such a table proposes
+   * `ENABLE ROW LEVEL SECURITY` — which, with zero policies, denies every non-owner role
+   * the table it already uses. Declaring the live truth is the fix; forcing the flag on
+   * was a silent lockdown nobody asked for.
+   *
+   * `false` is the only value: RLS-on is the default and has one spelling (omit this key).
+   * Refused with abilities (a policy under disabled RLS is a dead policy — declare
+   * `privileges` for grants-only access) and with `writtenBy: 'app'` (the app principal
+   * writes through its policies; there are none). Turning security OFF on a live table is
+   * a widening: the emitted `DISABLE ROW LEVEL SECURITY` carries the destructive-plan
+   * ceremony.
+   */
+  rls?: false;
   /**
    * Triggers on this table — declared HERE because a trigger is existentially bound
    * to its table and the table's owner must see what runs on every write (owner
@@ -205,6 +222,8 @@ export interface ModelDescriptor {
   schema: string;
   /** `true` removes the table from the generic data API (not in `exposedTables`). Default `false`. */
   private: boolean;
+  /** Row-security posture — `false` = grants-only, no RLS (see {@link ModelDefinition.rls}). Default `true`. */
+  rls: boolean;
   /** One-shot rename hint: this table used to be named `renamedFrom` (same schema). */
   renamedFrom?: string;
   /** One-shot move hint: this table used to live in schema `movedFrom` (same name) — emits SET SCHEMA. */
@@ -369,6 +388,36 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     }
   }
 
+  // `rls: false` is the ONLY spelling — RLS-on is the default and one meaning gets one
+  // spelling, so `rls: true` (redundant today, load-bearing the day the default moves) is
+  // refused rather than accepted as a synonym.
+  if (def.rls !== undefined && def.rls !== false) {
+    throw new Error(
+      `model '${table}': rls: ${JSON.stringify(def.rls)} — RLS enabled is the default; omit the key. ` +
+        `The only declaration is rls: false (grants-only authorization, row security off).`,
+    );
+  }
+  if (def.rls === false) {
+    // An ability compiles to a policy, and a policy under disabled RLS is a dead policy —
+    // it filters nothing while looking like it does. The grants-only spelling is `privileges`.
+    if ((def.abilities ?? []).length) {
+      throw new Error(
+        `model '${table}': rls: false with abilities — an ability compiles to an RLS policy, and a ` +
+          `policy under disabled row security is dead: it filters nothing while reading as though it does. ` +
+          `Either drop rls: false (policies need RLS) or declare grants-only access via privileges.`,
+      );
+    }
+    // `writtenBy: 'app'` means the app writes THROUGH its policies (RLS FORCEd). With RLS
+    // off there are no policies to write through — the combination is a contradiction.
+    if ((def.writtenBy ?? 'app') === 'app') {
+      throw new Error(
+        `model '${table}': rls: false with writtenBy: 'app' (the default) — 'app' writes through RLS ` +
+          `policies, and rls: false declares there are none. Declare writtenBy: 'worker' or 'functions' ` +
+          `(owner-connection writes), which is how a grants-only table is actually written.`,
+      );
+    }
+  }
+
   validateTriggersFor('table', table, def.triggers ?? []);
 
   // A rename and a move in one increment can't be composed from two independent markers
@@ -396,6 +445,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     softDelete: def.softDelete ?? false,
     schema: def.schema ?? 'public',
     private: def.private ?? false,
+    rls: def.rls ?? true,
     ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),
     ...(def.movedFrom ? { movedFrom: def.movedFrom } : {}),
     triggers: def.triggers ?? [],