@everystack/model 0.4.5 → 0.4.7

package/package.json

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

@@ -40,6 +40,24 @@ export interface AbilityCondition {
   where?: unknown;
   /** Escape hatch: a verbatim RLS predicate, preserved and diffed by normalized text. */
   sql?: unknown;
+  /**
+   * The WRITE predicate, when it differs from the read predicate.
+   *
+   * A policy has two halves: `USING` decides which rows you may TARGET, `WITH CHECK`
+   * decides what a row may BECOME. Postgres defaults the second to the first, which is
+   * usually what you want — and is what every other condition here compiles to.
+   *
+   * They differ when a row may be written into a shape its author could not have selected
+   * by, or vice versa. The dangerous direction is a WITH CHECK WEAKER than the USING: if
+   * `USING` says "your own row, and only while it is a draft" but `WITH CHECK` says only
+   * "your own row", the owner can move their own row out of draft — past whatever the
+   * state guard was protecting.
+   *
+   * Declare it when the live policy has one, so the model states the real rule instead of
+   * silently tightening it to the USING clause. Omit it and the read predicate governs
+   * both, unchanged.
+   */
+  check?: unknown;
 }
 
 export interface Ability {

package/src/derived.ts

@@ -196,6 +196,54 @@ export function arg(name: string, type: string, opts?: { default?: RawSql }): Ar
   return { name, type, ...(opts?.default ? { default: opts.default.sql } : {}) };
 }
 
+/** SQL type aliases → the spelling PostgreSQL's `format_type` prints. Base names only. */
+const BASE_TYPE_ALIASES: Record<string, string> = {
+  int: 'integer', int4: 'integer', int2: 'smallint', int8: 'bigint',
+  serial: 'integer', bigserial: 'bigint', smallserial: 'smallint',
+  bool: 'boolean', float4: 'real', float8: 'double precision', float: 'double precision',
+  decimal: 'numeric', varchar: 'character varying', char: 'character', bpchar: 'character',
+  timestamptz: 'timestamp with time zone', timetz: 'time with time zone',
+  timestamp: 'timestamp without time zone', time: 'time without time zone',
+  varbit: 'bit varying',
+};
+
+/**
+ * One declared argument type in the CATALOG's spelling: aliases resolved, typmods
+ * dropped, array dimensionality kept as `[]` per dimension.
+ *
+ * A function's identity in PostgreSQL is name + argument types, so this is what makes a
+ * DECLARED signature comparable to a live one. Typmods go because a function argument
+ * carries none — PostgreSQL discards length/precision on arguments, so `varchar(20)` and
+ * `varchar` are ONE type here. An unrecognized name (a domain, an enum, an extension
+ * type) passes through lowercased; the catalog prints those verbatim too.
+ */
+export function normalizeArgType(raw: string): string {
+  let t = raw.trim().replace(/\s+/g, ' ');
+  if (t === '') return t;
+
+  // Array dimensionality, both spellings: `text[]`, `text[3][3]`, `text ARRAY`, `text ARRAY[4]`.
+  let dims = 0;
+  for (;;) {
+    const arrayKeyword = /\s+array(\s*\[\s*\d*\s*\])?$/i.exec(t);
+    if (arrayKeyword) { dims += 1; t = t.slice(0, arrayKeyword.index).trim(); continue; }
+    const bracket = /\[\s*\d*\s*\]$/.exec(t);
+    if (bracket) { dims += 1; t = t.slice(0, bracket.index).trim(); continue; }
+    break;
+  }
+
+  t = t.replace(/\([^)]*\)/g, ' ').replace(/\s+/g, ' ').trim();
+  // A quoted part ("char", "MyType") keeps its case; everything else folds down.
+  if (!t.includes('"')) t = t.toLowerCase();
+  t = t.replace(/^pg_catalog\./, '');
+
+  return (BASE_TYPE_ALIASES[t] ?? t) + '[]'.repeat(dims);
+}
+
+/** `(integer, text)` — a declared signature in the catalog's spelling, parens included. */
+export function functionArgSignature(args: readonly ArgSpec[]): string {
+  return `(${args.map((a) => normalizeArgType(a.type)).join(', ')})`;
+}
+
 /** `returns: setof(posts)` — a descriptor ref, so a typo is a TS error and the dep comes free. */
 export interface SetofReturn {
   setof: ModelDescriptor | ViewDescriptor | MaterializedViewDescriptor;

package/src/index.ts

@@ -25,12 +25,13 @@ 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 {
   defineView, defineMaterializedView, defineFunction, defineSql, defineSequence,
   trigger, arg, setof, validateTriggersFor, SIMPLE_DROP_KINDS,
+  normalizeArgType, functionArgSignature,
 } from './derived';
 export type {
   DerivedDescriptor, ViewDescriptor, MaterializedViewDescriptor, FunctionDescriptor,

package/src/module.ts

@@ -21,7 +21,7 @@
 
 import type { ModelDescriptor } from './model';
 import type { DerivedDescriptor, SequenceDescriptor } from './derived';
-import { rejectHoles } from './derived';
+import { rejectHoles, functionArgSignature } from './derived';
 
 export interface ModuleDefinition {
   /** The package's Models (schema + authz). */
@@ -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>;
 }
@@ -71,15 +95,21 @@ export function defineModule(def: ModuleDefinition): Module {
   rejectHoles('defineModule', 'models', def.models);
   rejectHoles('defineModule', 'derived', def.derived);
   rejectHoles('defineModule', 'sequences', def.sequences);
-  // Derived identity is one name per kind: `DROP FUNCTION` renders no argument list, so
-  // v1 rejects function overloads outright, and same-name relations collide in the
-  // catalog anyway — caught here, at composition, before any SQL exists.
+  // Derived identity is one name per kind — except FUNCTIONS, which PostgreSQL identifies
+  // by name + argument types. Two same-name relations collide in the catalog and are
+  // caught here, at composition, before any SQL exists; two functions differing in their
+  // signature are two objects and always were. (Overloads used to be rejected outright
+  // because everything downstream keyed on `schema.name` — the drop rendered no argument
+  // list and provenance held one row for two live functions. It carries the signature now.)
   const seen = new Set<string>();
   for (const d of def.derived ?? []) {
-    const identity = `${d.kind === 'sql' ? d.objectKind : d.kind}:${d.name}`;
+    const kind = d.kind === 'sql' ? d.objectKind : d.kind;
+    const signature = d.kind === 'function' ? functionArgSignature(d.args) : '';
+    const identity = `${kind}:${d.name}${signature}`;
     if (seen.has(identity)) {
       throw new Error(
-        `defineModule: two derived declarations of '${d.name}' (${identity}) — one ${d.kind} per name (function overloads are v1-rejected; rename, or collapse to one signature with arg defaults).`,
+        `defineModule: two derived declarations of '${d.name}${signature}' (${identity}) — one ${d.kind} per `
+        + `${d.kind === 'function' ? 'signature (same name, DIFFERENT argument types, is an overload and is fine)' : 'name'}.`,
       );
     }
     seen.add(identity);
@@ -89,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] : [],
   };
 }
@@ -118,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();
+}