@everystack/cli 0.4.38 → 0.4.40

package/src/cli/commands/db-pull.ts

@@ -31,6 +31,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, type ColumnRow, type ColumnSchema } from '../schema-introspect.js';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
+import { introspectContract, type TableContract } from '../authz-contract.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { renderDerivedSource, renderDerivedFile, type DerivedRenderResult } from '../derived-render.js';
 import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
 import type { QueryRunner } from '../authz-contract.js';
@@ -102,8 +104,8 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   // The read-model scaffold: default 'commented' surfaces the authz decision in every
   // model; a preset stamps it. Validated up front so a typo fails before introspection.
   const abilities = flags.abilities || 'commented';
-  if (abilities !== 'commented' && !ABILITY_PRESETS[abilities]) {
-    fail(`Unknown --abilities preset '${abilities}'. Known: ${Object.keys(ABILITY_PRESETS).join(', ')} (omit the flag to scaffold the decision as comments).`);
+  if (abilities !== 'commented' && abilities !== 'live' && !ABILITY_PRESETS[abilities]) {
+    fail(`Unknown --abilities preset '${abilities}'. Known: live, ${Object.keys(ABILITY_PRESETS).join(', ')} (omit the flag to scaffold the decision as comments).`);
     process.exit(1);
   }
 
@@ -123,6 +125,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   }
 
   let current;
+  let liveAuthz: Map<string, TableContract> | undefined;
   let derivedCatalog: DerivedCatalog | undefined;
   let matviewColumns: Map<string, ColumnSchema[]> | undefined;
   let candidatesByIdentity: Map<string, string[]> | undefined;
@@ -143,6 +146,28 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     // The derived layer rides the same pull (B5) — views/matviews/functions/sequences
     // render as descriptors; adoption is pull → commit → --baseline → clean reconcile.
     derivedCatalog = await introspectDerived(runner);
+    // --abilities live: the authz half of the on-ramp. Same connection, one more read —
+    // the grants and policies that already exist become the models' declared abilities,
+    // instead of a human transcribing them by hand.
+    if (abilities === 'live') {
+      note('Introspecting live authorization (grants + policies)...');
+      const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+      liveAuthz = new Map(contract.tables.map((t) => [t.table, t]));
+      detail(`${liveAuthz.size} table(s) carry authorization.`);
+      // Roles outside the model vocabulary (anon/authenticated/admin) are usually ONE
+      // operator account granted across the whole schema. Said once here rather than
+      // repeated in all N models, where it would bury the per-table findings.
+      const unmapped = new Set<string>();
+      for (const t of contract.tables) {
+        for (const r of Object.keys(t.grants)) {
+          if (!['anon', 'authenticated', 'admin', 'PUBLIC', 'public'].includes(r)) unmapped.add(r);
+        }
+      }
+      if (unmapped.size) {
+        note(`Grants exist for ${[...unmapped].sort().join(', ')} — not rendered: abilities name the roles the model knows (anon/authenticated/admin).`);
+        detail(`These are left exactly as they are in the database. Add can(..., { role }) only if you want the models to own them.`);
+      }
+    }
     // --matviews-as-tables: the flip needs real fields — one extra catalog read for the
     // matview columns the derived layer (definition-only) doesn't carry.
     if (matviewsAsTables) {
@@ -235,7 +260,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   if (flags.out && !flags.out.endsWith('.ts')) {
     // A directory: one file per model + index.ts — the default shape for a real app.
     const dir = path.resolve(flags.out);
-    const files = renderModelFiles(current, { schema, abilities, derived: embeddedDerived });
+    const files = renderModelFiles(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));
@@ -252,7 +277,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     source = files.map((f) => f.source).join('\n');
   } else if (flags.out) {
     const outPath = path.resolve(flags.out);
-    source = renderModelSource(current, { schema, abilities, derived: embeddedDerived });
+    source = renderModelSource(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
     try {
       await fs.mkdir(path.dirname(outPath), { recursive: true });
       await fs.writeFile(outPath, source, 'utf8');
@@ -262,7 +287,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${pulled.length} model(s).`);
   } else {
-    source = renderModelSource(current, { schema, abilities, derived: embeddedDerived });
+    source = renderModelSource(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
     process.stdout.write(source);
     ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
   }

package/src/cli/commands/db-swap.ts

@@ -29,6 +29,7 @@ import { loadDeclaredDerived } from '../declared-derived.js';
 import type { SourceObject } from '../derived-source.js';
 import { pairedDerivedSchemas, renderPairedDerivedBuild, renderSwapSchemaUsage, swapSchemaRoles, expectedIncomingObjects, renderPairedProvenance } from '../swap-pair.js';
 import { introspectDerived } from '../derived-introspect.js';
+import { legacyFunctionIdentity } from '../pg-argtypes.js';
 import { createUrlRunner } from '../db-source.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { executeSwap, type SwapVerdict } from '../swap-execute.js';
@@ -637,7 +638,10 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
         artifactFingerprint,
         declaredFingerprint,
         // What db:reconcile can regenerate — the set a dependent must be in to be safe to drop.
-        declaredIdentities: declaredDerivedObjects.map((o) => o.identity),
+        // NAME granularity: both consumers (the paired pre-flight's dependentIdentity, the TOC
+        // filter) read a function as `schema.name` with its argument list stripped, so the
+        // signature half of a derived identity is dropped here rather than never matching.
+        declaredIdentities: declaredDerivedObjects.map((o) => legacyFunctionIdentity(o.identity)),
         rebuildDerived: flags['rebuild-derived'] === 'true',
         paired,
         // Schema-level USAGE, re-applied in the swap transaction and asserted after it commits.
@@ -709,7 +713,8 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
             runner: r,
             log: (m) => info(m),
             warn: (m) => warn(m),
-            declaredIdentities: declaredDerivedObjects.map((o) => o.identity),
+            // Name granularity — the TOC entry's argument list is stripped before the lookup.
+            declaredIdentities: declaredDerivedObjects.map((o) => legacyFunctionIdentity(o.identity)),
           });
         },
         snapshot: () => takePreSwapSnapshot(snapshotPlan, { stage, region, opsFn }),

package/src/cli/commands/db.ts

@@ -721,6 +721,17 @@ function printDoctorReport(report: any): void {
     success('db:doctor — database is least-privilege and RLS-subject');
   } else {
     fail('db:doctor — the api connection is NOT correctly least-privilege (see failures above)');
+    // Probing a local database as your own superuser makes these fail by construction:
+    // the checks describe the credential the API serves with, not the schema. A developer
+    // reading them as defects in their app will go hunting for a bug that is not there.
+    if (report.api?.isSuperuser) {
+      console.log('');
+      info('Note: this probe connected as a SUPERUSER, so least-privilege / not-superuser / fails-closed');
+      info('cannot pass by construction. Those three describe the credential your API serves with —');
+      info('they are only meaningful against the app role (a deployed stage, or a local DATABASE_URL');
+      info('pointing at the least-privilege role from db:provision). The RLS and grant findings above');
+      info('are still real.');
+    }
   }
 }
 

package/src/cli/derived-apply.ts

@@ -17,6 +17,7 @@ import { normalizeSql, parseQualified, type SourceObject } from './derived-sourc
 import type { ReconcilePlan } from './derived-plan.js';
 import { parseGrantAttachments } from './derived-grants.js';
 import { quoteIdent, quoteQualified } from './pg-ident.js';
+import { splitFunctionIdentity } from './pg-argtypes.js';
 
 /** SQL string literal with '' doubling (standard_conforming_strings). */
 export function escapeLiteral(value: string): string {
@@ -84,6 +85,19 @@ const DROP_KEYWORD: Record<string, string> = {
   function: 'FUNCTION',
 };
 
+/**
+ * The DROP target for one identity. A function's identity carries its argument types, and
+ * PostgreSQL NEEDS them: `DROP FUNCTION IF EXISTS api.get_user` against two overloads is
+ * `ERROR: function name "api.get_user" is not unique` — the apply died on it. The types
+ * ride verbatim (they are the catalog's own spelling); only the name parts are quoted.
+ * A legacy identity with no signature keeps the bare rendering it always had.
+ */
+export function dropTarget(kind: string, identity: string): string {
+  if (kind !== 'function') return quoteQualified(identity);
+  const { qualified, args } = splitFunctionIdentity(identity);
+  return args === null ? quoteQualified(qualified) : `${quoteQualified(qualified)}(${args})`;
+}
+
 /** Rewrite `CREATE FUNCTION` to `CREATE OR REPLACE FUNCTION` (replace-in-place). */
 export function ensureOrReplace(sql: string): string {
   return sql.replace(/^(\s*)CREATE\s+FUNCTION/i, '$1CREATE OR REPLACE FUNCTION');
@@ -190,7 +204,7 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]):
         // The new kinds carry their drop on the action (triggers: composed from structure;
         // 'sql' objects: the recorded/declared drop_sql) — the legacy kinds keep the
         // keyword rendering they always had.
-        statements.push(action.dropSql ?? `DROP ${DROP_KEYWORD[action.kind]} IF EXISTS ${quoteQualified(action.identity)}`);
+        statements.push(action.dropSql ?? `DROP ${DROP_KEYWORD[action.kind]} IF EXISTS ${dropTarget(action.kind, action.identity)}`);
         // A rebuild's drop is followed by its create; only a true removal loses provenance.
         if (!plan.actions.some((a) => a.action === 'create' && a.identity === action.identity)) {
           remove.push(action.identity);

package/src/cli/derived-compile.ts

@@ -23,6 +23,7 @@ import type {
 } from '@everystack/model';
 import { hashSourceContent, parseQualified, DECLARED_SOURCE_FILE, type Attachment, type SourceObject } from './derived-source.js';
 import { isPlainGrantAttachment } from './derived-grants.js';
+import { functionIdentity } from './pg-argtypes.js';
 import { findInvokerReachabilityGaps } from './derived-lint.js';
 
 /** The provenance marker for descriptor-compiled objects (SourceObject.file). */
@@ -195,8 +196,17 @@ interface Node {
   build: (seq: number) => SourceObject;
 }
 
+/**
+ * The reconciler's join key. Functions carry their ARGUMENT TYPES — PostgreSQL identifies
+ * a function by name + argtypes, and `schema.name` alone collapsed two overloads onto one
+ * object (one provenance row for two live functions, an ambiguous DROP, duplicate consts
+ * out of db:pull). The declared types are normalized to the catalog's spelling so the
+ * declared identity is the same string the live catalog produces. Everything else keeps
+ * `schema.name` unchanged.
+ */
 function derivedIdentity(d: DerivedDescriptor): string {
   const { schema, name } = parseQualified(d.name);
+  if (d.kind === 'function') return functionIdentity(schema, name, d.args.map((a) => a.type));
   return `${schema}.${name}`;
 }
 
@@ -309,7 +319,7 @@ export function compileDerived(models: readonly ModelDescriptor[], derived: read
       case 'function': {
         const { sql, attachments } = renderFunction(d);
         const setofDep = typeof d.returns === 'string' ? [] : depIdentities([d.returns.setof]);
-        nodes.push({ identity, deps: [...depIdentities(d.dependsOn), ...setofDep], build: make('function', d.name, sql, attachments) });
+        nodes.push({ identity, deps: [...depIdentities(d.dependsOn), ...setofDep], build: make('function', d.name, sql, attachments, { identity }) });
         break;
       }
       case 'sql': {

package/src/cli/derived-introspect.ts

@@ -26,7 +26,8 @@ export interface LiveObject {
   kind: DerivedKind;
   schema: string;
   name: string;
-  /** `schema.name` — join key against source objects and provenance. */
+  /** `schema.name` — join key against source objects and provenance.
+   *  Functions carry their signature: `schema.name(integer, text)`. */
   identity: string;
   /** Canonical definition as the catalog deparses it. */
   definition: string;
@@ -53,6 +54,9 @@ export interface LiveObject {
   fn?: {
     /** pg_get_function_arguments — `'query text, max integer DEFAULT 20'`. */
     args: string;
+    /** The IDENTITY arguments — types only, catalog-spelled (`'integer, text'`).
+     *  What `DROP FUNCTION` needs, and the signature half of `identity`. */
+    identityArgs?: string;
     /** pg_get_function_result — `'integer'`, `'SETOF posts'`, `'trigger'`. */
     returns: string;
     language: string;
@@ -123,15 +127,30 @@ WHERE c.relkind IN ('v', 'm')
 ORDER BY n.nspname, c.relname;
 `.trim();
 
+/**
+ * The catalog's spelling of a function's IDENTITY arguments — `format_type` over
+ * `proargtypes`, the exact list `DROP FUNCTION` wants. Types only, never argument names
+ * (renaming an argument is not a new function) and never defaults. `proargtypes` is the
+ * IN-argument vector, which is precisely what identifies a function.
+ *
+ * Referenced by every function-shaped read below, so a function's identity is the SAME
+ * string wherever it is produced. `<alias>` is substituted with the pg_proc alias in scope.
+ */
+const IDENTITY_ARGS_SQL = (alias: string): string => `
+  (SELECT COALESCE(string_agg(pg_catalog.format_type(t.oid, NULL), ', ' ORDER BY t.ord), '')
+     FROM unnest(${alias}.proargtypes::oid[]) WITH ORDINALITY AS t(oid, ord))`.trim();
+
 /** Plain functions and procedures: the canonical definition (reconcile's def hash) plus
  *  the STRUCTURED fields db:pull renders into defineFunction — args/returns from the
  *  deparse helpers, language, SECDEF, volatility, the pinned search_path, and the raw
  *  body (prosrc). Anything the v1 signature vocabulary can't say falls back to defineSql
- *  with the whole pg_get_functiondef. */
+ *  with the whole pg_get_functiondef. `identity_args` carries the signature half of the
+ *  identity — without it two overloads collapse onto one object. */
 export const DERIVED_FUNCTIONS_SQL = `
 SELECT
   n.nspname AS schema,
   p.proname AS name,
+  ${IDENTITY_ARGS_SQL('p')} AS identity_args,
   pg_get_functiondef(p.oid) AS definition,
   obj_description(p.oid, 'pg_proc') AS comment,
   pg_get_function_arguments(p.oid) AS args,
@@ -151,7 +170,7 @@ WHERE p.prokind IN ('f', 'p')
   AND NOT EXISTS (
     SELECT 1 FROM pg_depend dep WHERE dep.objid = p.oid AND dep.deptype = 'e'
   )
-ORDER BY n.nspname, p.proname;
+ORDER BY n.nspname, p.proname, 3;
 `.trim();
 
 /** Every index on a materialized view, as its canonical CREATE INDEX text. */
@@ -204,7 +223,7 @@ WHERE d.classid = 'pg_rewrite'::regclass
   )
 UNION
 SELECT DISTINCT
-  dn.nspname, dc.relname, rn.nspname, rp.proname
+  dn.nspname, dc.relname, rn.nspname, rp.proname || '(' || ${IDENTITY_ARGS_SQL('rp')} || ')'
 FROM pg_depend d
 JOIN pg_rewrite rw ON rw.oid = d.objid
 JOIN pg_class dc ON dc.oid = rw.ev_class
@@ -234,7 +253,7 @@ UNION
 -- Latent until something UPSTREAM of such a view actually changes, which is why an app can carry
 -- this shape for a long time and only meet it the first time the view has to rebuild.
 SELECT DISTINCT
-  dn.nspname, dp.proname, rn.nspname, rc.relname
+  dn.nspname, dp.proname || '(' || ${IDENTITY_ARGS_SQL('dp')} || ')', rn.nspname, rc.relname
 FROM pg_depend d
 JOIN pg_proc dp ON dp.oid = d.objid
 JOIN pg_namespace dn ON dn.oid = dp.pronamespace
@@ -286,7 +305,7 @@ GROUP BY n.nspname, c.relname, r.rolname
 UNION ALL
 SELECT
   n.nspname,
-  p.proname,
+  p.proname || '(' || ${IDENTITY_ARGS_SQL('p')} || ')',
   'f',
   COALESCE(r.rolname, 'PUBLIC'),
   array_agg(DISTINCT a.privilege_type ORDER BY a.privilege_type)
@@ -301,7 +320,7 @@ WHERE p.prokind IN ('f', 'p')
   AND NOT EXISTS (
     SELECT 1 FROM pg_depend dep WHERE dep.objid = p.oid AND dep.deptype = 'e'
   )
-GROUP BY n.nspname, p.proname, r.rolname
+GROUP BY n.nspname, p.oid, p.proname, r.rolname
 ORDER BY 1, 2, 4;
 `.trim();
 
@@ -349,6 +368,9 @@ export interface RelationRow {
 export interface FunctionRow {
   schema: string;
   name: string;
+  /** `format_type` over proargtypes — the signature half of the identity. Absent on a
+   *  pre-signature caller/fixture, which falls back to the legacy `schema.name` identity. */
+  identity_args?: unknown;
   definition: unknown;
   comment: unknown;
   /** Structured signature fields (B5 pull rendering). Optional — pre-B5 fixtures omit them. */
@@ -485,7 +507,12 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
 
   for (const row of rows.functions) {
     if (IGNORED_SCHEMAS.has(row.schema)) continue;
-    const identity = `${row.schema}.${row.name}`;
+    // Identity is name + argument types — two overloads are two objects. A row without
+    // identity_args predates the signature and keeps the legacy `schema.name`.
+    const identityArgs = row.identity_args == null ? null : String(row.identity_args);
+    const identity = identityArgs === null
+      ? `${row.schema}.${row.name}`
+      : `${row.schema}.${row.name}(${identityArgs})`;
     const definition = String(row.definition ?? '');
     const comment = row.comment == null ? undefined : String(row.comment);
     objects.push({
@@ -497,6 +524,7 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
       ...(row.src !== undefined ? {
         fn: {
           args: String(row.args ?? ''),
+          ...(identityArgs !== null ? { identityArgs } : {}),
           returns: String(row.returns ?? ''),
           language: String(row.language ?? 'sql'),
           secdef: row.secdef === true || row.secdef === 't' || row.secdef === 'true',

package/src/cli/derived-plan.ts

@@ -28,6 +28,7 @@ import { type ParsedSources, type SourceObject, type DerivedKind } from './deriv
 import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
 import { triggerDropSql } from './derived-apply.js';
 import { parseGrantAttachments, diffObjectGrants } from './derived-grants.js';
+import { legacyFunctionIdentity, splitFunctionIdentity } from './pg-argtypes.js';
 
 export type ReconcileVerb = 'create' | 'replace' | 'refresh' | 'drop' | 'baseline' | 'rebaseline' | 'prune' | 'backfill';
 
@@ -166,6 +167,33 @@ export function planReconcile(
       migrations.push({ from: prov.identity, to });
     }
   }
+  // Function provenance predates the signature: a row recorded as `schema.name` claims the
+  // SAME object the catalog now reports as `schema.name(argtypes)`. Re-key it in place —
+  // no forced rebaseline, no rebuild, converged after one apply. Driven off the LIVE
+  // catalog (the ground truth for what exists), so a function the source has since removed
+  // still drops through its provenance instead of reading as unmanaged.
+  //
+  // Skipped where it would be a guess: an overloaded name (one legacy row cannot stand for
+  // two objects — those baseline honestly), a row a live NON-function already owns (a view
+  // and a function can share `schema.name`), and a 'sql'-kind row (its identity is its
+  // declared name, not a catalog signature).
+  const liveFnByLegacy = new Map<string, LiveObject[]>();
+  for (const o of live.objects) {
+    if (o.kind !== 'function') continue;
+    const legacy = legacyFunctionIdentity(o.identity);
+    if (legacy === o.identity) continue; // no signature introspected — nothing to migrate
+    liveFnByLegacy.set(legacy, [...(liveFnByLegacy.get(legacy) ?? []), o]);
+  }
+  for (const [legacy, objs] of liveFnByLegacy) {
+    if (objs.length !== 1 || liveById.has(legacy)) continue;
+    const to = objs[0].identity;
+    const prov = provById.get(legacy);
+    if (!prov || prov.kind === 'sql' || provById.has(to)) continue;
+    provById.delete(legacy);
+    provById.set(to, { ...prov, identity: to });
+    migrations.push({ from: legacy, to });
+  }
+
   // Every provenance consumer below reads the POST-MIGRATION view.
   const provRows = [...provById.values()];
 
@@ -330,6 +358,31 @@ export function planReconcile(
     else unmanaged.push(liveObj.identity);
   }
 
+  // A declared function that joins nothing, sitting next to a live function of the same
+  // name and arity that nothing declares: the two spellings of ONE signature disagree.
+  // normalizeArgType resolves the SQL aliases, but it cannot know that a custom type
+  // outside the search_path prints qualified (`api.my_enum`) while the declaration says
+  // `my_enum`. Name the pair — the rebuild below is correct but would repeat forever.
+  const arityOf = (identity: string): number => {
+    const { args } = splitFunctionIdentity(identity);
+    if (args === null) return -1;
+    return args.trim() === '' ? 0 : args.split(',').length;
+  };
+  for (const src of source.objects) {
+    if (src.kind !== 'function' || liveById.has(src.identity)) continue;
+    const legacy = legacyFunctionIdentity(src.identity);
+    const candidates = live.objects.filter((o) =>
+      o.kind === 'function'
+      && !srcById.has(o.identity)
+      && legacyFunctionIdentity(o.identity) === legacy
+      && arityOf(o.identity) === arityOf(src.identity));
+    if (candidates.length === 1) {
+      extraWarnings.push(
+        `${src.identity}: nothing live matches, but ${candidates[0].identity} matches by name and arity — the declared argument types must be spelled the way the catalog prints them. Until they agree this plans a rebuild on EVERY apply.`,
+      );
+    }
+  }
+
   for (const prov of provRows) {
     if (only && !only.has(prov.identity)) continue;
     if (srcById.has(prov.identity) || liveById.has(prov.identity)) continue;

package/src/cli/derived-render.ts

@@ -17,6 +17,7 @@ import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
 import type { ColumnSchema, SequenceSchema, TableSchema } from './schema-introspect.js';
 import { parseIndexDefinition } from './schema-introspect.js';
 import { modelFileName, renderFieldLines } from './model-render.js';
+import { splitFunctionIdentity } from './pg-argtypes.js';
 
 export interface DerivedRenderResult {
   /** The source block: `export const … = defineView(…)` etc., dependency-ordered. */
@@ -98,6 +99,19 @@ function relationAbilities(grants: Record<string, string[]>): string[] | null {
   return out;
 }
 
+/**
+ * A function identity's argument types as a PascalCase suffix — `(integer, text)` →
+ * `IntegerText`, `(text[])` → `TextArray`, `()` → `Void`. Only ever appended to
+ * disambiguate overloads that would otherwise emit the same `export const`.
+ */
+function argSuffix(identity: string): string {
+  const { args } = splitFunctionIdentity(identity);
+  if (args === null) return '';
+  const words = args.replace(/\[\]/g, ' array ').replace(/[^A-Za-z0-9]+/g, ' ').trim();
+  if (!words) return 'Void';
+  return words.split(/\s+/).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+}
+
 /** VOLATILITY letters → the descriptor words ('v' is the default, never spelled). */
 const VOLATILITY: Record<string, string> = { i: 'immutable', s: 'stable' };
 
@@ -107,6 +121,24 @@ interface ParsedArg {
   default?: string;
 }
 
+/**
+ * The SQL type names that are more than one word, by their FIRST word and the word that
+ * can follow it. An UNNAMED argument of such a type (`timestamp with time zone`) looks
+ * exactly like a named one (`ts timestamptz`) to a "first token is the name" rule, and was
+ * read as an argument called `timestamp` of type `with time zone` — which then rendered as
+ * `arg('timestamp', 'with time zone')`, a signature the catalog has never heard of.
+ * Requiring the CONTINUATION word keeps a genuine argument named `time` (`time integer`)
+ * reading as an argument.
+ */
+const TYPE_CONTINUATIONS: Record<string, RegExp> = {
+  double: /^precision\b/i,
+  character: /^varying\b/i,
+  bit: /^varying\b/i,
+  timestamp: /^with(out)?\b/i,
+  time: /^with(out)?\b/i,
+  national: /^character\b/i,
+};
+
 /** Parse `pg_get_function_arguments` output. Null = beyond the v1 vocabulary. */
 function parseArgs(args: string): ParsedArg[] | null {
   const trimmed = args.trim();
@@ -130,6 +162,11 @@ function parseArgs(args: string): ParsedArg[] | null {
     if (!m || !m[2]) return null;
     // A single token is an UNNAMED arg ('text') — the match would misread type as name.
     if (!/\s/.test(entry.replace(/\s+DEFAULT\s+.+$/i, '')) ) return null;
+    // …and so is a MULTI-WORD type ('timestamp with time zone'), which has a first token
+    // that reads perfectly well as an argument name. defineFunction cannot say an unnamed
+    // argument, so this is a FIXME → defineSql, not a signature invented from the words.
+    const continuation = TYPE_CONTINUATIONS[m[1].toLowerCase()];
+    if (continuation && continuation.test(m[2])) return null;
     out.push({ name: m[1], type: m[2], ...(m[3] ? { default: m[3] } : {}) });
   }
   return out;
@@ -196,13 +233,22 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
   }
   const byIdentity = new Map(renderable.map((o) => [o.identity, o]));
   // Var names carry the schema for non-public objects — two schemas can share a bare name.
+  // OVERLOADS share everything but their argument types, so a bare name would emit two
+  // `export const apiGetUser = …` and the barrel would not compile (it did not — that is
+  // how this whole class surfaced). The argument-type suffix appears ONLY on a collision,
+  // so a schema without overloads renders byte-identically to before.
+  const baseVar = (o: LiveObject): string => toCamelCase(o.schema === 'public' ? o.name : `${o.schema}_${o.name}`);
+  const varCounts = new Map<string, number>();
+  for (const o of renderable) varCounts.set(baseVar(o), (varCounts.get(baseVar(o)) ?? 0) + 1);
   const varOf = new Map(renderable.map((o) =>
-    [o.identity, toCamelCase(o.schema === 'public' ? o.name : `${o.schema}_${o.name}`)]));
+    [o.identity, (varCounts.get(baseVar(o)) ?? 0) > 1 ? baseVar(o) + argSuffix(o.identity) : baseVar(o)]));
   // The name a descriptor DECLARES: bare for public, qualified otherwise. parseQualified
   // round-trips it, so the compiled identity matches the live object it was pulled from —
   // a bare name would compile to public.<name>, baseline would never join, and reconcile
   // would plan duplicate creates in public (the red-team's pull-qualification finding).
-  const declaredName = (o: LiveObject): string => (o.schema === 'public' ? o.name : o.identity);
+  // NEVER the identity for a function — that carries the signature, which the descriptor
+  // derives from its own `args` rather than parsing out of the name.
+  const declaredName = (o: LiveObject): string => (o.schema === 'public' ? o.name : `${o.schema}.${o.name}`);
 
   const indegree = new Map<string, number>();
   const dependents = new Map<string, string[]>();
@@ -259,7 +305,17 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       const abilities = relationAbilities(o.grants ?? {});
       if (abilities === null) {
         const grantText = Object.entries(o.grants ?? {}).map(([r, p]) => `${r}: ${p.join('/')}`).join(', ');
-        warnings.push(`${o.identity}: live grants (${grantText}) are not expressible as relation abilities (read-only, role-shaped) — object skipped; migrate it by hand.`);
+        // A view carrying INSERT/UPDATE/DELETE almost never means someone intended a
+        // writable view — it usually traces to a blanket `GRANT ALL ON ALL TABLES IN
+        // SCHEMA public` in an old migration, which sweeps views up with the tables.
+        // Naming that here saves the diagnosis; an adopter paid for it once already.
+        const writeGrants = Object.values(o.grants ?? {}).some((ps) =>
+          ps.some((p) => p === 'INSERT' || p === 'UPDATE' || p === 'DELETE'),
+        );
+        const hint = writeGrants
+          ? ' Write privileges on a view usually come from a blanket `GRANT ALL ON ALL TABLES IN SCHEMA …` rather than a deliberate writable view — check that first.'
+          : '';
+        warnings.push(`${o.identity}: live grants (${grantText}) are not expressible as relation abilities (read-only, role-shaped) — object skipped; migrate it by hand.${hint}`);
         lines.push(`// FIXME: ${o.identity} skipped — live grants (${grantText}) are not expressible as abilities (views are read surfaces).`, '');
         continue;
       }
@@ -364,11 +420,15 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
 
     if (!f || args === null || (f.language !== 'sql' && f.language !== 'plpgsql')) {
       warnings.push(`${o.identity}: signature beyond the v1 vocabulary (${f ? `language ${f.language}, args '${f.args}'` : 'no structured fields'}) — rendered as defineSql.`);
+      // A defineSql object is identified by its NAME alone, so an overload pair would
+      // collapse to one provenance row here too — the declared name carries the signature
+      // (the drop is explicit, so the name is a label, and a unique one is what it needs).
+      const sqlName = declaredName(o) + (f?.identityArgs !== undefined ? `(${f.identityArgs})` : '');
       lines.push(
         `// FIXME: ${o.identity} — signature beyond defineFunction's v1 vocabulary; kept verbatim as defineSql.`,
-        `export const ${varName} = defineSql(${tsString(declaredName(o))}, {`,
+        `export const ${varName} = defineSql(${tsString(sqlName)}, {`,
         `  kind: 'function',`,
-        `  drop: sql\`DROP FUNCTION IF EXISTS ${o.identity.startsWith('public.') ? o.name : o.identity}\`,`,
+        `  drop: sql\`DROP FUNCTION IF EXISTS ${o.schema === 'public' ? o.name : `${o.schema}.${o.name}`}${f?.identityArgs !== undefined ? `(${f.identityArgs})` : ''}\`,`,
         `  as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`,
         '});',
         '',

package/src/cli/model-render.ts

@@ -17,6 +17,8 @@
 
 import type { SchemaSnapshot, TableSchema, ColumnSchema, CheckConstraint } from './schema-introspect.js';
 import type { DerivedRenderResult } from './derived-render.js';
+import type { TableContract } from './authz-contract.js';
+import { deriveAbilities, renderDerivedAbilities } from './authz-derive.js';
 import { normalizeDefault, normalizeCheck } from './schema-diff.js';
 
 /**
@@ -68,6 +70,14 @@ export interface RenderOptions {
    * as reviewable code. Grants are authored, never inherited; there is no runtime default.
    */
   abilities?: string;
+  /**
+   * Live authorization, keyed by schema-qualified table — supplied when `abilities` is
+   * `'live'`. Each table's stanza is DERIVED from the grants and policies actually in the
+   * database rather than scaffolded or stamped: an ability is emitted only where the grant
+   * and the policy agree, and anything else arrives as a comment naming why. See
+   * authz-derive.ts for the rule (policy presence is not effective privilege).
+   */
+  liveAuthz?: Map<string, TableContract>;
   /** The rendered derived layer (B5) — rides the barrel: block after the models,
    *  sequences/derived arrays on the module wrapper, symbols on the import header. */
   derived?: DerivedRenderResult;
@@ -87,7 +97,18 @@ export const ABILITY_PRESETS: Record<string, string> = {
  * same thing the db:check gate failure says — one voice, two doorways), or a preset
  * stamped uncommented. An unknown preset throws — grants are authored, never guessed.
  */
-function abilitiesStanza(mode: string): string {
+function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<string, TableContract>): string {
+  if (mode === 'live') {
+    const contract = table && liveAuthz?.get(table.table);
+    if (!contract) {
+      return [
+        '  // no live authorization found for this table — nothing was granted, so nothing is',
+        '  // rendered. Author the read model deliberately, or leave it internal:',
+        '  // private: true,',
+      ].join('\n');
+    }
+    return renderDerivedAbilities(deriveAbilities(contract));
+  }
   if (mode === 'commented') {
     return [
       '  // Declare the read model — db:check fails this model until its authz is authored:',
@@ -205,7 +226,13 @@ function renderDefault(expr: string): string | null {
   const str = n.match(/^'([\s\S]*)'$/);
   if (str) return `.default(${JSON.stringify(str[1].replace(/''/g, "'"))})`;
   if (n === 'true' || n === 'false') return `.default(${n})`;
-  if (/^-?\d+(\.\d+)?$/.test(n)) return `.default(${n})`;
+  // A numeric default only survives as a JS number when the number renders back to the
+  // SAME text. `0.0` is the number 0, so `.default(0.0)` stores 0 and compiles to
+  // `DEFAULT 0` against a live `DEFAULT 0.0` — drift on every apply, forever (21 statements
+  // on the first real schema this was measured against). Same for `1.50`, `0.10`, `1e3`.
+  // Where the text cannot round-trip, fall through to `.defaultSql()`, which carries the
+  // live spelling verbatim. The exact-integer and exact-decimal cases are unchanged.
+  if (/^-?\d+(\.\d+)?$/.test(n)) return String(Number(n)) === n ? `.default(${n})` : null;
   return null;
 }
 
@@ -403,7 +430,7 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
 }
 
 /** One `export const X = defineModel(...)` block for a table. */
-export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map(), abilities = 'commented'): string {
+export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map(), abilities = 'commented', liveAuthz?: Map<string, TableContract>): string {
   // A CHECK that reverses to a single field's .validate() is rendered on the field (ergonomic);
   // the rest stay table-level check(). Both round-trip — this only chooses the nicer form.
   const validates = new Map<string, string>();
@@ -420,7 +447,7 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   // The authz decision renders FIRST — before fields — because it is the first thing a
   // reviewer must resolve about a model (and where the field-report consumer's codemod
   // put it, proving the position is mechanical-edit-friendly).
-  const stanza = abilitiesStanza(abilities);
+  const stanza = abilitiesStanza(abilities, table, liveAuthz);
 
   return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza}\n  fields: {\n${fields}\n  },${constraints}\n});`;
 }
@@ -477,7 +504,7 @@ export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions
   const known = new Set(tables.map((t) => bareName(t.table)));
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
-  const blocks = tables.map((t) => renderModelBlock(t, known, enums, opts.abilities ?? 'commented'));
+  const blocks = tables.map((t) => renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz));
   // The derived layer (B5): sequences + views/matviews/functions, after the models they
   // reference, before the module wrapper that composes all three.
   if (opts.derived?.block) blocks.push(opts.derived.block);
@@ -535,7 +562,7 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
   const files: RenderedModelFile[] = tables.map((t) => {
-    const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented');
+    const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz);
     const crossImports = referencedTables(t, known).map(
       (target) => `import { ${modelVarName(target)} } from './${bareName(target).replace(/_/g, '-')}';`,
     );