@everystack/model 0.4.9 → 0.4.11

package/README.md

@@ -96,7 +96,19 @@ The table-level surface, composed in `constraints: [...]`, for what a column-sco
 - `{ where: 'deleted_at IS NULL' }` — a column/scalar predicate, compiled to the policy's `USING` clause.
 - `{ sql: … }` — a verbatim RLS predicate escape hatch.
 
-These compile to RLS policies and grants (via `@everystack/cli`'s `compileTableContract`, what `db:generate` emits). `can('manage', …)` covers all actions.
+These compile to RLS policies and grants (via `@everystack/cli`'s `compileTableContract`, what `db:generate` emits). `can('manage', …)` covers all four DML actions: `SELECT`, `INSERT`, `UPDATE`, `DELETE`.
+
+Exactly those four, and no more. A verb that expanded to "every privilege" would hand out `TRUNCATE`, which no `DELETE` policy filters. The other table privileges are named one at a time:
+
+```typescript
+defineModel('posts', {
+  fields: { … },
+  abilities: [can('read'), can('manage', { role: 'admin' })],
+  privileges: { admin: ['REFERENCES', 'TRIGGER', 'TRUNCATE'] },
+});
+```
+
+`privileges` takes only those three, and it is additive — it widens what a role holds and can never narrow it. DML stays in `can()`, where the grant and the row policy are decided together. `db:pull --abilities live` writes this key from the live grants, so an existing database that grants its admin role all three keeps them.
 
 ## Relations
 

package/package.json

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

@@ -15,6 +15,26 @@ export type Action = 'read' | 'create' | 'update' | 'delete' | 'manage' | 'execu
 export interface AbilityCondition {
   /** Role-gated: policy `TO <role>` + grant. */
   role?: string;
+  /**
+   * The policy's AUDIENCE, decoupled from its grantees. Exactly one value: `'public'`.
+   *
+   * A bare `can('read')` means two things at once — *who holds the privilege* (a GRANT to
+   * anon and to authenticated) and *who the policy names* (`TO anon`, `TO authenticated`).
+   * One knob, two axes. A brownfield schema that wrote the ordinary Postgres idiom — a
+   * single policy `TO PUBLIC` — could not be expressed at all, so the plan proposed dropping
+   * it and creating two role-scoped ones. PUBLIC is an OPEN set and `{anon, authenticated}`
+   * is not, so that is a real narrowing: any other role loses the read.
+   *
+   * `policyRoles: 'public'` emits ONE policy `TO PUBLIC` and leaves the GRANTS exactly as
+   * they are derived today. **It can never add a grantee** — an open audience over a closed
+   * grant set widens nothing, because Postgres checks the GRANT first.
+   *
+   * Only `'public'` is admitted, deliberately. A free-form role list here would be a second
+   * way to spell the `role:` axis and could name a role no grant backs, which reads as access
+   * that does not exist. With the domain restricted to one open set, `policyRoles ⊇ grantees`
+   * holds structurally and there is no inverse case to guard.
+   */
+  policyRoles?: 'public';
   /** Row owner only: the column holding the owner id (`USING (<col> = auth.uid())`). */
   owner?: string;
   /**
@@ -49,11 +69,12 @@ export interface AbilityCondition {
    */
   ownerExpr?: unknown;
   /**
-   * Column-scoped exposure for a `read` ability. Names the field keys a role may read
-   * (compiled to a `GRANT SELECT (cols)` column grant, not a table grant) instead of the
-   * whole row — e.g. `can('read', { owner: 'id', columns: ['id', 'email', 'role'] })` on
-   * `auth.users` exposes id/email/role to the owner, never the password hash. Pairs with
-   * `owner` (the self policy scopes the rows; the columns scope the fields).
+   * Column-scoped exposure for a `read` or `update` ability. Names the field keys a role may
+   * read or update (compiled to `GRANT SELECT|UPDATE (cols)`, never a table grant) instead of
+   * the whole row — e.g. `can('read', { owner: 'id', columns: ['id', 'email', 'role'] })` on
+   * `auth.users` exposes id/email/role to the owner, never the password hash. Every column
+   * ability must name a `role`, an `owner`, or both: the policy scopes rows and the columns
+   * scope fields.
    */
   columns?: string[];
   /** Scalar/column predicate — a sql-tagged expression compiled to an RLS USING clause. */
@@ -85,6 +106,38 @@ export interface Ability {
   condition: AbilityCondition;
 }
 
+/**
+ * Is this an ability whose privilege is scoped to listed columns rather than the
+ * whole table? `defineModel` rejects every malformed near-miss before a descriptor
+ * reaches a compiler, so consumers can use this as the one classification rule.
+ */
+export function isColumnAbility(ability: Ability): boolean {
+  return (ability.action === 'read' || ability.action === 'update')
+    && Array.isArray(ability.condition.columns)
+    && ability.condition.columns.length > 0
+    && Boolean(ability.condition.role || ability.condition.owner);
+}
+
+/**
+ * Is this ability a PUBLIC read — a read path open to a caller with no session?
+ *
+ * The visibility question the soft-delete guard turns on: "what can someone with no session
+ * see?". Both a role-less read and `role: 'anon'` answer it the same way, because `anon` IS
+ * the anonymous role; an `owner` or `via` read answers it differently, because those scope
+ * rows to a session that exists.
+ *
+ * ONE definition, because there were two. `defineModel`'s refusal fired only on a role-less
+ * read while `db:pull`'s renderer already counted `role: 'anon'` — so a table whose
+ * authenticated read diverges (which pull renders as an anon-scoped read) slipped past the
+ * refusal while still being rendered as public. Two surfaces, two answers, one question.
+ */
+export function isPublicReadAbility(ability: Ability): boolean {
+  return ability.action === 'read'
+    && !ability.condition.owner
+    && !ability.condition.via
+    && (!ability.condition.role || ability.condition.role === 'anon');
+}
+
 /** Declare one authorization rule. */
 export function can(action: Action, condition: AbilityCondition = {}): Ability {
   return { action, condition };

package/src/drizzle.ts

@@ -18,6 +18,7 @@ import {
   pgTable,
   pgSchema,
   pgEnum,
+  customType,
   text,
   uuid,
   integer,
@@ -106,6 +107,13 @@ function baseColumn(columnName: string, spec: FieldSpec): PgColumnBuilderBase {
       return json(columnName);
     case 'enum':
       return getEnum(spec)(columnName);
+    case 'pgType': {
+      // A verbatim type: drizzle carries the exact string as the column's SQL
+      // type and the value stays `unknown` — no client-side typing is promised.
+      const typeName = spec.pgTypeName;
+      if (!typeName) throw new Error('pgType field is missing pgTypeName');
+      return customType<{ data: unknown }>({ dataType: () => typeName })(columnName);
+    }
     default: {
       const exhaustive: never = spec.type;
       throw new Error(`Unsupported field type: ${String(exhaustive)}`);

package/src/field.ts

@@ -12,6 +12,7 @@
  */
 
 import type { RawSql } from './raw-sql';
+import { pgTypeRefusal } from './pg-type';
 
 export type FieldType =
   | 'text'
@@ -30,7 +31,8 @@ export type FieldType =
   | 'varchar'
   | 'json'
   | 'jsonb'
-  | 'enum';
+  | 'enum'
+  | 'pgType';
 
 export type DefaultKind = 'value' | 'now' | 'random' | 'sql';
 
@@ -49,6 +51,14 @@ export interface FieldSpec {
   scale?: number;
   /** `varchar(length)` — maximum character length. */
   length?: number;
+  /**
+   * The verbatim Postgres type of a `pgType` field — the exact canonical
+   * `format_type` spelling (`hstore`, `geometry(Geometry,4326)`, `tsvector`).
+   * The string IS the type's identity: introspection, the differ, and the
+   * fingerprint all compare it byte-for-byte, so a pulled column round-trips
+   * with no coercion and no drift.
+   */
+  pgTypeName?: string;
   isPrimaryKey: boolean;
   isNotNull: boolean;
   isUnique: boolean;
@@ -94,7 +104,7 @@ export interface FieldSpec {
 export class FieldBuilder {
   readonly spec: FieldSpec;
 
-  constructor(type: FieldType, extra?: Pick<FieldSpec, 'enumName' | 'enumValues' | 'precision' | 'scale' | 'length'>) {
+  constructor(type: FieldType, extra?: Pick<FieldSpec, 'enumName' | 'enumValues' | 'precision' | 'scale' | 'length' | 'pgTypeName'>) {
     this.spec = {
       type,
       enumName: extra?.enumName,
@@ -102,6 +112,7 @@ export class FieldBuilder {
       precision: extra?.precision,
       scale: extra?.scale,
       length: extra?.length,
+      pgTypeName: extra?.pgTypeName,
       isPrimaryKey: false,
       isNotNull: false,
       isUnique: false,
@@ -252,4 +263,19 @@ export const field = {
   json: (): FieldBuilder => new FieldBuilder('json'),
   /** A Postgres enum. The `name` is the `CREATE TYPE` name and is always explicit, so `db:pull` round-trips it. */
   enum: (name: string, values: readonly string[]): FieldBuilder => new FieldBuilder('enum', { enumName: name, enumValues: values }),
+  /**
+   * A verbatim Postgres type the vocabulary has no first-class field for —
+   * `field.pgType('hstore')`, `field.pgType('geometry(Geometry,4326)')`,
+   * `field.pgType('tsvector')`. The exact string is the column's type, end to
+   * end: DDL emits it verbatim, introspection reports it verbatim, and the
+   * differ/fingerprint compare it byte-for-byte — so an extension-typed column
+   * round-trips with no coercion. The spelling must be canonical and must not
+   * shadow a first-class field (one type, one spelling): non-canonical or
+   * first-class spellings are refused with the correct call named.
+   */
+  pgType: (typeName: string): FieldBuilder => {
+    const refusal = pgTypeRefusal(typeName);
+    if (refusal) throw new Error(refusal);
+    return new FieldBuilder('pgType', { pgTypeName: typeName });
+  },
 } as const;

package/src/index.ts

@@ -10,20 +10,22 @@
 export { field, FieldBuilder } from './field';
 export type { FieldSpec, FieldType, DefaultKind, ReferentialAction } from './field';
 
+export { canonicalColumnType, fieldFactoryCall, pgTypeRefusal } from './pg-type';
+
 export { unique, check, index, foreignKey, IndexBuilder } from './constraints';
 export type { TableConstraint } from './constraints';
 
 export { sql } from './raw-sql';
 export type { RawSql } from './raw-sql';
 
-export { can } from './can';
+export { can, isColumnAbility, isPublicReadAbility } from './can';
 export type { Ability, AbilityCondition, Action } from './can';
 
 export { belongsTo, hasMany } from './relations';
 export type { Relation } from './relations';
 
-export { defineModel, defineMaterializedTable } from './model';
-export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, MaterializedTableMarker, MaterializedTableDefinition } from './model';
+export { defineModel, defineMaterializedTable, EXTRA_PRIVILEGES } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, ExtraPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
 export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
 export type { Module, ModuleDefinition } from './module';

package/src/model.ts

@@ -13,6 +13,7 @@
 
 import type { FieldBuilder } from './field';
 import type { Ability } from './can';
+import { isPublicReadAbility } from './can';
 import type { Relation } from './relations';
 import type { TableConstraint } from './constraints';
 import type { RawSql } from './raw-sql';
@@ -50,6 +51,23 @@ 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'];
+
 export interface ModelDefinition {
   fields: Record<string, FieldBuilder>;
   abilities?: Ability[];
@@ -59,6 +77,21 @@ export interface ModelDefinition {
   constraints?: TableConstraint[];
   /** The write principal — drives RLS posture. Default `'app'`. See {@link WrittenBy}. */
   writtenBy?: WrittenBy;
+  /**
+   * Privileges a role holds on this table BEYOND the CRUD an ability compiles to —
+   * `privileges: { admin: ['REFERENCES', 'TRIGGER', 'TRUNCATE'] }`.
+   *
+   * Only {@link ExtraPrivilege} values are accepted. The four DML privileges are NOT
+   * declarable here on purpose: `SELECT`/`INSERT`/`UPDATE`/`DELETE` come from `can()`, which
+   * decides the grant and the RLS policy together. A grant declared without its policy is a
+   * privilege with no row gate — the exact shape `db:pull` refuses to render.
+   *
+   * ADDITIVE, never subtractive: these are unioned with what the abilities grant, so this key
+   * can widen a role's privileges and can never narrow them. Naming a role here GOVERNS it —
+   * same rule as `can(…, { role })` — so a role that appears only in this map has its other
+   * privileges reconciled everywhere, not just on this table.
+   */
+  privileges?: Record<string, ExtraPrivilege[]>;
   /**
    * `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
@@ -132,6 +165,8 @@ export interface ModelDescriptor {
   constraints: TableConstraint[];
   /** The resolved write principal (default `'app'`) — drives RLS posture. See {@link WrittenBy}. */
   writtenBy: WrittenBy;
+  /** Beyond-CRUD privileges per role, unioned with what the abilities grant. See {@link ModelDefinition.privileges}. */
+  privileges: Record<string, ExtraPrivilege[]>;
   /** `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. */
@@ -173,6 +208,72 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     if (a.action === 'execute') {
       throw new Error(`model '${table}': can('execute') is a function ability — declare it on the defineFunction it gates.`);
     }
+
+    // A column list is authorization, not a selection hint. If it reaches a table-grant path
+    // unnoticed, Postgres receives a whole-table privilege. Admit only the shapes the column
+    // compiler understands, and reject an empty list because it is indistinguishable from no
+    // column scope at all.
+    if (a.condition.columns !== undefined) {
+      if (a.action !== 'read' && a.action !== 'update') {
+        throw new Error(
+          `model '${table}': columns apply only to can('read') or can('update'), not can('${a.action}').`,
+        );
+      }
+      if (!Array.isArray(a.condition.columns) || a.condition.columns.length === 0) {
+        throw new Error(
+          `model '${table}': columns must be a non-empty array on can('${a.action}'); an empty list would erase the column scope.`,
+        );
+      }
+      if (!a.condition.role && !a.condition.owner) {
+        throw new Error(
+          `model '${table}': columns require role and/or owner on can('${a.action}'); otherwise the intended column grant has no declared grantee or row gate.`,
+        );
+      }
+      if (a.condition.policyRoles !== undefined) {
+        throw new Error(
+          `model '${table}': columns cannot use policyRoles. A column ability's policy is TO its declared role (or authenticated for owner-only), never an open audience.`,
+        );
+      }
+      if (a.condition.owner && !(a.condition.owner in def.fields)) {
+        throw new Error(
+          `model '${table}': columns names owner '${a.condition.owner}', but no such field exists.`,
+        );
+      }
+      for (const column of a.condition.columns) {
+        if (!(column in def.fields)) {
+          throw new Error(
+            `model '${table}': columns names '${column}', but no such field exists. Column abilities use model field keys.`,
+          );
+        }
+      }
+    }
+
+    // `policyRoles` decouples the policy's AUDIENCE from its GRANTEES, and it is deliberately
+    // amputated to one open set. Anything else would be a second spelling of the `role:` axis
+    // and could name a role no grant backs — a policy that reads as access which does not
+    // exist. A key that cannot say NO is not a fix, so it says NO here, at authoring time.
+    if (a.condition.policyRoles !== undefined) {
+      if (a.condition.policyRoles !== 'public') {
+        throw new Error(
+          `model '${table}': policyRoles admits exactly one value, 'public' — got ` +
+            `${JSON.stringify(a.condition.policyRoles)}. It exists to express a single policy TO PUBLIC, ` +
+            `the open audience a brownfield schema already wrote. To gate on a named role use role: '<name>', ` +
+            `which sets the grant too.`,
+        );
+      }
+      if (a.action !== 'read') {
+        throw new Error(
+          `model '${table}': policyRoles is a READ audience — can('${a.action}', { policyRoles: 'public' }) would ` +
+            `open a write policy to every role. Declare writes with role:/owner:.`,
+        );
+      }
+      if (a.condition.role) {
+        throw new Error(
+          `model '${table}': policyRoles: 'public' and role: '${a.condition.role}' both name the policy's audience. ` +
+            `Declare one. policyRoles states the audience and leaves the grants alone; role states both.`,
+        );
+      }
+    }
   }
 
   // An array field's value default must be a JS array — `.default([])`, not the
@@ -196,10 +297,19 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
   // 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) {
+  // `isPublicReadAbility`, not a local copy: this refusal and db:pull's renderer were asking
+  // the same question — "can a caller with no session see these rows?" — and answering it
+  // differently. The renderer already counted `role: 'anon'`; this refusal did not, so a table
+  // whose authenticated read diverges (rendered as an anon-scoped read) slipped past the very
+  // decision the refusal exists to force. It now fires on the anonymous audience however it is
+  // spelled. Explicit `softDelete: false` remains the one-line answer, and pull writes that
+  // line into every model it renders, so a pulled checkout keeps loading.
+  const hasPublicRead = (def.abilities ?? []).some(isPublicReadAbility);
+  // Both spellings of the field key. The guard used to test `'deletedAt' in def.fields`
+  // literally, so a model keying the column `deleted_at` — the shape a snake_case brownfield
+  // schema pulls as — carried a soft-delete column past a guard that never looked at it.
+  const softDeleteField = 'deletedAt' in def.fields || 'deleted_at' in def.fields;
+  if (softDeleteField && 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); `
@@ -207,6 +317,26 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     );
   }
 
+  // A privilege outside the beyond-CRUD set is refused rather than passed through. The DML
+  // four are the dangerous ones: declared here they would compile to a GRANT with no policy
+  // beside it, which is a privilege nobody row-gated. They come from can(), where the grant
+  // and the policy are decided in one place.
+  for (const [role, privs] of Object.entries(def.privileges ?? {})) {
+    if (!Array.isArray(privs)) {
+      throw new Error(`model '${table}': privileges['${role}'] must be an array of ${EXTRA_PRIVILEGES.join(' | ')}.`);
+    }
+    for (const p of privs) {
+      if (EXTRA_PRIVILEGES.includes(p)) continue;
+      const dml = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'].includes(String(p).toUpperCase());
+      throw new Error(
+        `model '${table}': privileges['${role}'] contains '${p}', which is not one of ${EXTRA_PRIVILEGES.join(', ')}. `
+          + (dml
+            ? `Declare ${String(p).toUpperCase()} with can() — that is what decides the row policy beside the grant. A grant declared here would have no policy.`
+            : `This key names only the table privileges can() has no verb for.`),
+      );
+    }
+  }
+
   validateTriggersFor('table', table, def.triggers ?? []);
 
   // A rename and a move in one increment can't be composed from two independent markers
@@ -230,6 +360,7 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     primaryKey,
     constraints: def.constraints ?? [],
     writtenBy: def.writtenBy ?? 'app',
+    privileges: def.privileges ?? {},
     softDelete: def.softDelete ?? false,
     schema: def.schema ?? 'public',
     private: def.private ?? false,
@@ -266,6 +397,8 @@ export interface MaterializedTableDefinition {
   writtenBy?: WrittenBy;
   private?: boolean;
   renamedFrom?: string;
+  /** Beyond-CRUD privileges per role. See {@link ModelDefinition.privileges}. */
+  privileges?: Record<string, ExtraPrivilege[]>;
 }
 
 export function defineMaterializedTable(table: string, def: MaterializedTableDefinition): ModelDescriptor {
@@ -282,6 +415,7 @@ export function defineMaterializedTable(table: string, def: MaterializedTableDef
     constraints: def.constraints,
     writtenBy: def.writtenBy ?? 'worker',
     private: def.private,
+    ...(def.privileges ? { privileges: def.privileges } : {}),
     ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),
   });
   model.materialized = {

package/src/pg-type.ts

@@ -0,0 +1,97 @@
+/**
+ * pg-type — the ONE definition of a column type's spelling.
+ *
+ * Three questions, answered here and only here, so every surface (the field
+ * factory, db:pull's renderer, introspection, the differ, the fingerprint)
+ * agrees by construction:
+ *
+ *  1. What is the canonical spelling of a `format_type` string?
+ *     (`canonicalColumnType` — the v5 rule: a redundant default precision is
+ *     not part of a type's identity.)
+ *  2. Which spellings are already owned by a first-class `field.*()` factory?
+ *     (`fieldFactoryCall` — the inverse map db:pull renders with, and the map
+ *     `field.pgType` refuses against, so one type always has one spelling.)
+ *  3. Everything else is carried VERBATIM by `field.pgType(...)` — the type
+ *     string itself is the identity, end to end.
+ */
+
+/**
+ * Canonicalize a `format_type` spelling. Only the redundant default precision,
+ * only the timestamp/time family: `timestamp(6) without time zone` is the same
+ * type as `timestamp without time zone` (6 is the family default), so both
+ * spell the canonical, shorter form. `timestamp(3)` is a real difference and
+ * passes through untouched.
+ */
+export function canonicalColumnType(type: string): string {
+  return type.replace(/^(timestamp|timestamptz|time|timetz)\(6\)(\s|$)/, '$1$2');
+}
+
+/** `format_type` → the `field.*()` factory that produces it (the non-parameterized types). */
+const FIELD_FACTORY: Record<string, string> = {
+  uuid: 'uuid',
+  text: 'text',
+  integer: 'integer',
+  bigint: 'bigint',
+  real: 'real',
+  'double precision': 'doublePrecision',
+  boolean: 'boolean',
+  json: 'json',
+  jsonb: 'jsonb',
+  date: 'date',
+  'timestamp with time zone': 'timestamptz',
+  'timestamp without time zone': 'timestamp',
+  timestamp: 'timestamp',
+};
+
+/**
+ * The full `field.*()` call for a `format_type` string, or null when no
+ * first-class field maps it. Handles the parameterized types `format_type`
+ * spells out — `numeric(p,s)` and `character varying(n)` — so a pulled column
+ * round-trips back to the same DDL. A scale-0 numeric renders as the cleaner
+ * `field.numeric(p)` (identical to `(p, 0)`).
+ */
+export function fieldFactoryCall(type: string): string | null {
+  // An array is its base type + `.array()` — exactly how the compiler emits it
+  // (`format_type` spells arrays `text[]`). An array of an unmapped base stays null.
+  if (type.endsWith('[]')) {
+    const base = fieldFactoryCall(type.slice(0, -2));
+    return base ? `${base}.array()` : null;
+  }
+
+  const direct = FIELD_FACTORY[type];
+  if (direct) return `field.${direct}()`;
+
+  const num = type.match(/^numeric(?:\((\d+),(\d+)\))?$/);
+  if (num) {
+    if (num[1] == null) return 'field.numeric()';
+    return num[2] === '0' ? `field.numeric(${num[1]})` : `field.numeric(${num[1]}, ${num[2]})`;
+  }
+
+  const vc = type.match(/^character varying(?:\((\d+)\))?$/);
+  if (vc) return vc[1] != null ? `field.varchar(${vc[1]})` : 'field.varchar()';
+
+  return null;
+}
+
+/**
+ * Validate the argument of `field.pgType(...)`. Returns the reason the spelling
+ * is refused, or null when it may be carried verbatim. Refusals exist so a type
+ * never has two spellings in the vocabulary — the split-identity family of bugs.
+ */
+export function pgTypeRefusal(typeName: string): string | null {
+  const t = typeName.trim();
+  if (!t) return 'field.pgType() needs a Postgres type name';
+  if (t !== typeName) return `field.pgType('${typeName}'): no surrounding whitespace — write '${t}'`;
+  if (t.endsWith('[]')) {
+    return `field.pgType('${t}'): declare the scalar and add .array() — field.pgType('${t.slice(0, -2)}').array()`;
+  }
+  const canonical = canonicalColumnType(t);
+  if (canonical !== t) {
+    return `field.pgType('${t}'): the canonical spelling is '${canonical}' — a redundant default precision is not part of the type's identity`;
+  }
+  const firstClass = fieldFactoryCall(t);
+  if (firstClass) {
+    return `field.pgType('${t}'): this type is first-class — use ${firstClass}`;
+  }
+  return null;
+}