@everystack/model 0.4.6 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "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/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/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();
+}