@everystack/model 0.4.6 → 0.4.8

package/package.json

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

@@ -25,7 +25,7 @@ export type { Relation } from './relations';
 export { defineModel, defineMaterializedTable } from './model';
 export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
-export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived } from './module';
+export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
 export type { Module, ModuleDefinition } from './module';
 
 export {

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 } : {}),

package/src/module.ts

@@ -41,6 +41,28 @@ export interface ModuleDefinition {
    * deployed by `db:reconcile`, never migrated. Supersedes the `functions` thunk.
    */
   derived?: DerivedDescriptor[];
+  /**
+   * Roles this module's authz GOVERNS, beyond the ones its models already name.
+   *
+   * The reconciler treats declared authz as authoritative over the roles it governs and
+   * leaves every other grantee alone. Without that, a live role the model vocabulary
+   * cannot express — a migrator, an ETL account, a BI reader that predates everystack —
+   * has every privilege REVOKED the first time a plan is applied, because the reconciler
+   * unions declared ∪ live grantees and finds no declaration. On the first brownfield
+   * schema this was measured against, that was 32 revokes that would have broken the
+   * adopter's deploy pipeline mid-deploy.
+   *
+   * This list only ever WIDENS the governed set: `PUBLIC` and the fixed vocabulary
+   * (`anon`, `authenticated`, `admin`) plus every role the models name are always
+   * governed, and naming them here changes nothing. You cannot use this to stop the
+   * reconciler governing a role your models grant to — that would be a way to hide a
+   * grant from the very thing that audits it.
+   *
+   * An ungoverned grantee is NOT ignored: every plan, check and dry-run enumerates it by
+   * name with its exact privileges, and a grantee that is not in the stage's adoption
+   * baseline fails the gate. Exempt from reconciliation, never exempt from the report.
+   */
+  governedRoles?: string[];
   /**
    * 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
@@ -60,6 +82,8 @@ export interface Module {
   sequences: SequenceDescriptor[];
   /** Derived (compute) objects — reconciled, never migrated. */
   derived: DerivedDescriptor[];
+  /** Roles this module's authz governs beyond the ones its models name. Widen-only. */
+  governedRoles: string[];
   /** Function-SQL thunks, normalized to an array so composing modules just concatenates. */
   functions: Array<() => string>;
 }
@@ -95,6 +119,7 @@ export function defineModule(def: ModuleDefinition): Module {
     extensions: def.extensions ?? [],
     sequences: def.sequences ?? [],
     derived: def.derived ?? [],
+    governedRoles: [...new Set(def.governedRoles ?? [])].sort(),
     functions: def.functions ? [def.functions] : [],
   };
 }
@@ -124,3 +149,8 @@ export function moduleSequences(modules: Module[]): SequenceDescriptor[] {
 export function moduleDerived(modules: Module[]): DerivedDescriptor[] {
   return modules.flatMap((m) => m.derived);
 }
+
+/** The union of every module's governed roles — deduped and sorted. Widen-only by construction. */
+export function moduleGovernedRoles(modules: Module[]): string[] {
+  return [...new Set(modules.flatMap((m) => m.governedRoles))].sort();
+}