@everystack/model 0.4.7 → 0.4.8

package/package.json

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

@@ -83,8 +83,9 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       };
     }
 
-    // Convention: a `deletedAt` field opts the table into soft-delete.
-    if (SOFT_DELETE_COLUMN in model.fields) softDeleteTables.push(table);
+    // 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);
 
     if (model.hooks) hooks[table] = model.hooks;
 

package/src/model.ts

@@ -59,6 +59,20 @@ export interface ModelDefinition {
   constraints?: TableConstraint[];
   /** The write principal — drives RLS posture. Default `'app'`. See {@link WrittenBy}. */
   writtenBy?: WrittenBy;
+  /**
+   * `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.**
+   *
+   * 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.
+   */
+  softDelete?: boolean;
   /**
    * The Postgres schema the table lives in. Default `'public'`. Package-owned
    * tables declare their own (`'dist'`, `'ops'`, `'auth'`) so one db:generate run
@@ -118,6 +132,8 @@ export interface ModelDescriptor {
   constraints: TableConstraint[];
   /** The resolved write principal (default `'app'`) — drives RLS posture. See {@link WrittenBy}. */
   writtenBy: WrittenBy;
+  /** `true` excludes `deleted_at IS NULL` rows from public reads and the data API. Declared, never inferred. */
+  softDelete: boolean;
   /** The resolved Postgres schema (default `'public'`). Package tables live in their own. */
   schema: string;
   /** `true` removes the table from the generic data API (not in `exposedTables`). Default `false`. */
@@ -174,6 +190,23 @@ 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.
+  const hasPublicRead = (def.abilities ?? []).some(
+    (a) => a.action === 'read' && !a.condition.role && !a.condition.owner && !a.condition.via,
+  );
+  if ('deletedAt' in def.fields && hasPublicRead && def.softDelete === undefined) {
+    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.`,
+    );
+  }
+
   validateTriggersFor('table', table, def.triggers ?? []);
 
   // A rename and a move in one increment can't be composed from two independent markers
@@ -197,6 +230,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     primaryKey,
     constraints: def.constraints ?? [],
     writtenBy: def.writtenBy ?? 'app',
+    softDelete: def.softDelete ?? false,
     schema: def.schema ?? 'public',
     private: def.private ?? false,
     ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),