@everystack/model 0.4.20 → 0.4.21

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.21] - 2026-10-14
+
+### Added
+
+- apply state prerequisites atomically
+- link table name references through model thunks
+- use table names in the example and gate import cycles
+
+### Fixed
+
+- break the model and auth import cycles; gate new ones
+- link cached placeholder references to their targets
+- reject conflicting name bindings
+- rowOwnership exceptRoles lifts the backstop for manage roles
+- only a plain manage role lifts the rowOwnership backstop
+
+## [Unreleased]
+
+### Added
+
+- apply state prerequisites atomically
+
+## [0.4.20] - 2026-09-26
+
+### BREAKING CHANGES
+
+- defineModel refuses owner or via under a no-session audience
+
+### Fixed
+
+- refuse role: 'anon' combined with owner or via
+
 ## [0.4.19] - 2026-09-16
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.20",
+  "version": "0.4.21",
   "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

@@ -14,6 +14,8 @@
 
 import type { ModelDescriptor } from './model';
 import type { ModelHooks } from './model';
+import type { AbilityCondition } from './can';
+import { linkModels } from './link';
 
 /** The handler's RelationConfig shape, mirrored structurally (no @everystack/api dep). */
 export interface RelationConfig {
@@ -27,7 +29,8 @@ export interface DerivedHandlerConfig {
   exposedTables: string[];
   hiddenColumns: Record<string, string[]>;
   protectedFields: Record<string, string[]>;
-  rowOwnership: Record<string, { column: string; userField: string }>;
+  /** `exceptRoles` is present only when a `can('manage', { role })` exists for the table. */
+  rowOwnership: Record<string, { column: string; userField: string; exceptRoles?: string[] }>;
   softDelete: { tables: string[] };
   relations: Record<string, Record<string, RelationConfig>>;
   hooks: Record<string, ModelHooks>;
@@ -44,10 +47,11 @@ function primaryKeyOf(model: ModelDescriptor): string {
 }
 
 export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerConfig {
+  linkModels(models);
   const exposedTables: string[] = [];
   const hiddenColumns: Record<string, string[]> = {};
   const protectedFields: Record<string, string[]> = {};
-  const rowOwnership: Record<string, { column: string; userField: string }> = {};
+  const rowOwnership: DerivedHandlerConfig['rowOwnership'] = {};
   const softDeleteTables: string[] = [];
   const relations: Record<string, Record<string, RelationConfig>> = {};
   const hooks: Record<string, ModelHooks> = {};
@@ -81,6 +85,19 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
         column: ownerAbility.condition.owner!,
         userField: ownerAbility.condition.userField ?? DEFAULT_USER_FIELD,
       };
+      // A role that may `manage` the table is exempt from the backstop, mirroring the
+      // RLS policy compiled from the same ability. Only a plain `can('manage', { role })`
+      // counts: a role-scoped update or delete alone does not lift it, and neither does a
+      // manage ability with any other condition, which narrows what RLS lets it write
+      // (fail closed: a whitelist of `role`, not a blacklist of the rest).
+      const exceptRoles = [
+        ...new Set(
+          model.abilities
+            .filter((a) => a.action === 'manage' && isPlainRole(a.condition))
+            .map((a) => a.condition.role as string),
+        ),
+      ];
+      if (exceptRoles.length) rowOwnership[table].exceptRoles = exceptRoles;
     }
 
     // Declared, not inferred — one `softDelete` decision drives both the API filter and the
@@ -127,6 +144,12 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
   };
 }
 
+/** True when the condition is exactly `{ role: <string> }`: every other key is absent or undefined. */
+function isPlainRole(condition: AbilityCondition): boolean {
+  return typeof condition.role === 'string'
+    && Object.entries(condition).every(([key, value]) => key === 'role' || value === undefined);
+}
+
 function fieldsWhere(
   model: ModelDescriptor,
   pred: (f: ModelDescriptor['fields'][string]) => boolean,

package/src/derived.ts

@@ -17,7 +17,7 @@
 import type { RawSql } from './raw-sql';
 import type { Ability } from './can';
 import type { ModelDescriptor } from './model';
-import { TABLE_PRIVILEGES } from './model';
+import { TABLE_PRIVILEGES } from './privileges';
 import type { IndexBuilder } from './constraints';
 import type { FieldBuilder } from './field';
 

package/src/field.ts

@@ -14,6 +14,7 @@
 import type { RawSql } from './raw-sql';
 import { pgTypeRefusal } from './pg-type';
 import { assertConstraintName, assertFkValidate } from './constraints';
+import { referenceThunk } from './link';
 
 export type FieldType =
   | 'text'
@@ -230,7 +231,8 @@ export class FieldBuilder {
   }
 
   /**
-   * Declare a foreign key. The target is a model thunk (forward-reference safe). Optional
+   * Declare a foreign key. The target is a table name or model thunk. Names are resolved
+   * by linkModels when the complete set is available. Optional
    * `onDelete`/`onUpdate` referential actions are column-scoped, so they live here, not on
    * the table — `field.uuid().references(() => User, { onDelete: 'cascade' })`.
    *
@@ -240,8 +242,8 @@ export class FieldBuilder {
    * {@link FieldSpec.referencesValidate} for why a fifteen-year-old schema needs to be able
    * to say it.
    */
-  references(target: () => unknown, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean }): this {
-    this.spec.references = target;
+  references(target: (() => unknown) | string, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean }): this {
+    this.spec.references = referenceThunk(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');

package/src/index.ts

@@ -13,6 +13,7 @@ export type { FieldSpec, FieldType, DefaultKind, ReferentialAction } from './fie
 export { canonicalColumnType, fieldFactoryCall, pgTypeRefusal } from './pg-type';
 
 export { parseQualified } from './qualified';
+export { linkModels, ModelLinkError } from './link';
 
 export { unique, check, index, foreignKey, IndexBuilder } from './constraints';
 export type { TableConstraint } from './constraints';

package/src/link.ts

@@ -0,0 +1,126 @@
+import type { ModelDescriptor } from './model';
+import { parseQualified } from './qualified';
+
+/** A failed or conflicting name binding must never become a usable model. */
+export class ModelLinkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ModelLinkError';
+  }
+}
+
+type NameReference<T> = (() => T) & {
+  refName: string;
+  refLocation?: string;
+  boundTarget?: T;
+  linkedTarget?: () => T;
+};
+
+function isNameReference<T>(target: () => T): target is NameReference<T> {
+  return 'refName' in target && typeof target.refName === 'string';
+}
+
+/** Keep descriptors callable until the complete model set is available. */
+export function referenceThunk<T>(target: (() => T) | string): () => T {
+  if (typeof target !== 'string') return target;
+  const placeholder: NameReference<T> = Object.assign((): T => {
+    // Lazy consumers can capture this function before linking (Drizzle caches tables).
+    // They must recover after the caller follows the error's linking instruction.
+    if (placeholder.linkedTarget) return placeholder.linkedTarget();
+    throw new ModelLinkError(
+      `reference '${placeholder.refName}' on '${placeholder.refLocation ?? 'unknown'}' is not linked: export your models through linkModels()`,
+    );
+  }, { refName: target });
+  return placeholder;
+}
+
+/** Called at declaration, where the owning table and field/relation name are known. */
+export function referenceLocation(target: (() => unknown) | undefined, location: string): void {
+  if (target && isNameReference(target)) target.refLocation = location;
+}
+
+/**
+ * Resolve name references against this set only, then replace their placeholders with
+ * bound model thunks that retain their names. Returns the same array; repeated calls preserve thunk identities.
+ * Existing model thunks are never evaluated or replaced.
+ */
+export function linkModels<T extends readonly ModelDescriptor[]>(models: T): T {
+  const uniqueModels = [...new Set(models)];
+  const byName = new Map<string, ModelDescriptor[]>();
+  for (const model of uniqueModels) {
+    const candidates = byName.get(model.table) ?? [];
+    candidates.push(model);
+    byName.set(model.table, candidates);
+  }
+  const modelName = (model: ModelDescriptor): string =>
+    model.schema === 'public' ? model.table : `${model.schema}.${model.table}`;
+
+  // One resolver for fields and relations. Prefixing a schema through the same parser
+  // distinguishes bare names from explicit public names, including quoted dots.
+  function resolve(target: NameReference<ModelDescriptor>, model: ModelDescriptor, kind: string, key: string): ModelDescriptor {
+    const name = target.refName;
+    let parsed: ReturnType<typeof parseQualified>;
+    let qualified: boolean;
+    try {
+      parsed = parseQualified(name);
+      qualified = parseQualified(`public.${name}`).name !== parsed.name;
+    } catch (err) {
+      throw new ModelLinkError(`reference '${name}' on '${target.refLocation ?? 'unknown'}': ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const candidates = (byName.get(parsed.name) ?? [])
+      .filter(candidate => !qualified || candidate.schema === parsed.schema);
+    const context = `model '${modelName(model)}': ${kind} '${key}'`;
+    if (!candidates.length) {
+      if (target.boundTarget) return target.boundTarget;
+      const defined = uniqueModels.map(modelName).sort().join(', ');
+      throw new ModelLinkError(`${context} targets '${name}', which is not a defined model (defined: ${defined})`);
+    }
+    if (candidates.length > 1) {
+      const names = candidates.map(candidate => `${candidate.schema}.${candidate.table}`).sort().join(', ');
+      throw new ModelLinkError(`${context} targets ambiguous model '${name}' (candidates: ${names})`);
+    }
+    const resolved = candidates[0];
+    if (target.boundTarget && target.boundTarget !== resolved) {
+      const previous = target.boundTarget;
+      const oldName = `${previous.schema}.${previous.table}`;
+      const newName = `${resolved.schema}.${resolved.table}`;
+      const difference = oldName === newName
+        ? `a different object for the same table '${oldName}' (models loaded twice)`
+        : `a different table ('${oldName}' instead of '${newName}')`;
+      throw new ModelLinkError(
+        `reference '${name}' on '${target.refLocation ?? 'unknown'}' is already linked to ${difference}; models are shared objects, link them from one set`,
+      );
+    }
+    return resolved;
+  }
+
+  // Resolve everything before changing descriptors, so a typo can be corrected and retried
+  // without leaving earlier references bound to a different, incomplete set.
+  const replacements: Array<() => void> = [];
+  for (const model of uniqueModels) {
+    for (const [key, field] of Object.entries(model.fields)) {
+      const target = field.spec.references;
+      if (target && isNameReference(target)) {
+        const resolved = resolve(target as NameReference<ModelDescriptor>, model, 'field', key);
+        if (target.boundTarget) continue;
+        const linked = Object.assign(() => resolved, {
+          refName: target.refName, refLocation: target.refLocation, boundTarget: resolved,
+        });
+        replacements.push(() => { target.boundTarget = resolved; target.linkedTarget = linked; field.spec.references = linked; });
+      }
+    }
+    for (const [key, relation] of Object.entries(model.relations)) {
+      const target = relation.target;
+      if (isNameReference(target)) {
+        const resolved = resolve(target, model, 'relation', key);
+        if (target.boundTarget) continue;
+        const linked = Object.assign(() => resolved, {
+          refName: target.refName, refLocation: target.refLocation, boundTarget: resolved,
+        });
+        replacements.push(() => { target.boundTarget = resolved; target.linkedTarget = linked; relation.target = linked; });
+      }
+    }
+  }
+  for (const replace of replacements) replace();
+  return models;
+}

package/src/model.ts

@@ -12,12 +12,14 @@
  */
 
 import type { FieldBuilder } from './field';
+import { referenceLocation } from './link';
 import type { Ability } from './can';
 import { isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete, sessionlessAudience } from './can';
 import type { Relation } from './relations';
 import type { TableConstraint } from './constraints';
 import type { RawSql } from './raw-sql';
 import { validateTriggersFor, type TriggerSpec, type DependsOnRef } from './derived';
+import { TABLE_PRIVILEGES, type TablePrivilege } from './privileges';
 
 /**
  * Per-table mutation hooks. Imperative function bodies the framework cannot
@@ -51,51 +53,8 @@ export interface ModelHooks {
  */
 export type WrittenBy = 'app' | 'worker' | 'functions';
 
-/**
- * A table privilege that is NOT one of the four CRUD verbs — the ones `can()` has no word for.
- *
- * `can('manage')` means exactly INSERT/SELECT/UPDATE/DELETE, and that is deliberate: a verb
- * that quietly expanded to "every privilege" would hand out TRUNCATE, which is not a DELETE
- * and is not filtered by a DELETE policy. So these three are named one at a time, by the
- * author, in {@link ModelDefinition.privileges}.
- *
- * Why the vocabulary stops here: a real database routinely grants its admin role REFERENCES,
- * TRIGGER and TRUNCATE, and everystack had no way to SAY that — so the first plan against an
- * existing schema revoked all three on every table. That is our spelling, not their bug.
- */
-export type ExtraPrivilege = 'REFERENCES' | 'TRIGGER' | 'TRUNCATE';
-
-/** The declarable privilege set — the one definition; the CLI's classifier reads it too. */
-export const EXTRA_PRIVILEGES: readonly ExtraPrivilege[] = ['REFERENCES', 'TRIGGER', 'TRUNCATE'];
-
-/** The four CRUD privileges. Normally they arrive via `can()`, which decides the policy too. */
-export const DML_PRIVILEGES = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'] as const;
-export type DmlPrivilege = (typeof DML_PRIVILEGES)[number];
-
-/**
- * Every table privilege this language can spell.
- *
- * The DML four used to be REFUSED here, so that a grant could never be declared without the
- * policy that gates it. That invariant was already vacuous for any database being adopted: a
- * live table can hold `GRANT SELECT TO admin` with no policy covering admin, and refusing to
- * say it did not make it not so — it only made the database unspellable.
- *
- * That matters because `db:fingerprint` compares the LIVE schema against the MODELS. A state
- * the language cannot express is a permanent MISMATCH, so adopting such a database required
- * mutating it first, which inverts who is the source of truth during adoption.
- *
- * The rule this settles (Fable, 2026-08-06): **expressibility is total over the fingerprint's
- * domain; opinion lives in the linter, never in the parser.** Declaring a naked DML grant is
- * still a mistake in hand-authored code — `db:check` says so, as an ERROR on a table without
- * RLS (where it is an unrestricted table-wide privilege) and a WARNING on a table with RLS
- * (where it is dead until someone adds a broad policy or disables RLS). It is no longer a
- * parse error, because `db:pull` has to be able to render what is actually there.
- *
- * Policies still come ONLY from `can()`. This key can never mint row access by itself.
- */
-export type TablePrivilege = ExtraPrivilege | DmlPrivilege;
-
-export const TABLE_PRIVILEGES: readonly TablePrivilege[] = [...EXTRA_PRIVILEGES, ...DML_PRIVILEGES];
+export { EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './privileges';
+export type { ExtraPrivilege, DmlPrivilege, TablePrivilege } from './privileges';
 
 export interface ModelDefinition {
   fields: Record<string, FieldBuilder>;
@@ -269,6 +228,12 @@ export interface MaterializedTableMarker {
 }
 
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
+  for (const [name, field] of Object.entries(def.fields)) {
+    referenceLocation(field.spec.references, `${table}.${name}`);
+  }
+  for (const [name, relation] of Object.entries(def.relations ?? {})) {
+    referenceLocation(relation.target, `${table}.${name}`);
+  }
   const primaryKey = Object.entries(def.fields)
     .filter(([, f]) => f.spec.isPrimaryKey)
     .map(([name]) => name);

package/src/module.ts

@@ -24,6 +24,7 @@ import type { DerivedDescriptor, SequenceDescriptor } from './derived';
 import { rejectHoles, functionArgSignature } from './derived';
 import { deriveFunctionSchemas } from './derive';
 import { parseQualified } from './qualified';
+import { linkModels } from './link';
 
 export interface ModuleDefinition {
   /** The package's Models (schema + authz). */
@@ -199,7 +200,7 @@ function assertFunctionsAreDeclared(def: ModuleDefinition): void {
 /** The flattened model list across modules — for everything that still takes a model array
  *  (handler-config derivation, FORCE carveouts, the drift guard). */
 export function moduleModels(modules: Module[]): ModelDescriptor[] {
-  return modules.flatMap((m) => m.models);
+  return linkModels(modules.flatMap((m) => m.models));
 }
 
 /** The deduped, sorted extension list across modules — emitted as `CREATE EXTENSION` first. */

package/src/privileges.ts

@@ -0,0 +1,45 @@
+/**
+ * A table privilege that is NOT one of the four CRUD verbs — the ones `can()` has no word for.
+ *
+ * `can('manage')` means exactly INSERT/SELECT/UPDATE/DELETE, and that is deliberate: a verb
+ * that quietly expanded to "every privilege" would hand out TRUNCATE, which is not a DELETE
+ * and is not filtered by a DELETE policy. So these three are named one at a time, by the
+ * author, in {@link ModelDefinition.privileges}.
+ *
+ * Why the vocabulary stops here: a real database routinely grants its admin role REFERENCES,
+ * TRIGGER and TRUNCATE, and everystack had no way to SAY that — so the first plan against an
+ * existing schema revoked all three on every table. That is our spelling, not their bug.
+ */
+export type ExtraPrivilege = 'REFERENCES' | 'TRIGGER' | 'TRUNCATE';
+
+/** The declarable privilege set — the one definition; the CLI's classifier reads it too. */
+export const EXTRA_PRIVILEGES: readonly ExtraPrivilege[] = ['REFERENCES', 'TRIGGER', 'TRUNCATE'];
+
+/** The four CRUD privileges. Normally they arrive via `can()`, which decides the policy too. */
+export const DML_PRIVILEGES = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'] as const;
+export type DmlPrivilege = (typeof DML_PRIVILEGES)[number];
+
+/**
+ * Every table privilege this language can spell.
+ *
+ * The DML four used to be REFUSED here, so that a grant could never be declared without the
+ * policy that gates it. That invariant was already vacuous for any database being adopted: a
+ * live table can hold `GRANT SELECT TO admin` with no policy covering admin, and refusing to
+ * say it did not make it not so — it only made the database unspellable.
+ *
+ * That matters because `db:fingerprint` compares the LIVE schema against the MODELS. A state
+ * the language cannot express is a permanent MISMATCH, so adopting such a database required
+ * mutating it first, which inverts who is the source of truth during adoption.
+ *
+ * The rule this settles (Fable, 2026-08-06): **expressibility is total over the fingerprint's
+ * domain; opinion lives in the linter, never in the parser.** Declaring a naked DML grant is
+ * still a mistake in hand-authored code — `db:check` says so, as an ERROR on a table without
+ * RLS (where it is an unrestricted table-wide privilege) and a WARNING on a table with RLS
+ * (where it is dead until someone adds a broad policy or disables RLS). It is no longer a
+ * parse error, because `db:pull` has to be able to render what is actually there.
+ *
+ * Policies still come ONLY from `can()`. This key can never mint row access by itself.
+ */
+export type TablePrivilege = ExtraPrivilege | DmlPrivilege;
+
+export const TABLE_PRIVILEGES: readonly TablePrivilege[] = [...EXTRA_PRIVILEGES, ...DML_PRIVILEGES];

package/src/relations.ts

@@ -5,11 +5,12 @@
  *   belongsTo(() => Author, 'authorId')   // this.authorId → Author.<pk>
  *   hasMany(() => Comment, 'postId')      // this.<pk> → Comment.postId
  *
- * The target is a thunk so models can reference each other regardless of file or
- * declaration order.
+ * A table-name target avoids sibling imports; linkModels resolves it against the
+ * complete set. Model thunks remain supported for forward references.
  */
 
 import type { ModelDescriptor } from './model';
+import { referenceThunk } from './link';
 
 export interface Relation {
   kind: 'belongsTo' | 'hasMany';
@@ -31,18 +32,18 @@ export interface Relation {
 
 /** Many-to-one: this row points at one target row via `column`. */
 export function belongsTo(
-  target: () => ModelDescriptor,
+  target: (() => ModelDescriptor) | string,
   column: string,
   references?: string,
 ): Relation {
-  return { kind: 'belongsTo', target, column, references };
+  return { kind: 'belongsTo', target: referenceThunk(target), column, references };
 }
 
 /** One-to-many: target rows point back at this row via `column`. */
 export function hasMany(
-  target: () => ModelDescriptor,
+  target: (() => ModelDescriptor) | string,
   column: string,
   references?: string,
 ): Relation {
-  return { kind: 'hasMany', target, column, references };
+  return { kind: 'hasMany', target: referenceThunk(target), column, references };
 }

package/src/wire.ts

@@ -143,8 +143,8 @@ export interface DerivedDescriptor {
   /** Schema name, defaulted to `public` when unqualified. */
   schema: string;
   name: string;
-  /** `schema.name` — the reconciler's join key against the live catalog.
-   *  (Triggers: `schema.table.name` — compound identity, joined against pg_trigger.) */
+  /** Functions use `schema.name(argtypes)` — their full PostgreSQL identity and reconciler join
+   *  key. Other objects use `schema.name`; triggers use `schema.table.name` and join pg_trigger. */
   identity: string;
   /** The CREATE statement as authored (no trailing semicolon). */
   sql: string;