@everystack/cli 0.4.36 → 0.4.39

package/src/cli/db-source.ts

@@ -70,13 +70,10 @@ export interface UrlRunner {
 }
 
 /**
- * A QueryRunner over a direct postgres.js connection. One connection is enough —
- * introspection is a handful of sequential catalog queries.
+ * Load the postgres.js driver, or explain how to get it. Shared by every direct-connection
+ * runner below so the missing-driver instructions can never drift between them.
  */
-export async function createUrlRunner(
-  url: string,
-  load: () => Promise<any> = () => import('postgres'),
-): Promise<UrlRunner> {
+async function loadPostgresDriver(load: () => Promise<any>): Promise<any> {
   let mod: any;
   try {
     mod = await load();
@@ -85,7 +82,18 @@ export async function createUrlRunner(
       'The direct-connection path needs the "postgres" driver. It ships with @everystack/server; in a project without it: pnpm add -D postgres',
     );
   }
-  const postgres = mod.default ?? mod;
+  return mod.default ?? mod;
+}
+
+/**
+ * A QueryRunner over a direct postgres.js connection. One connection is enough —
+ * introspection is a handful of sequential catalog queries.
+ */
+export async function createUrlRunner(
+  url: string,
+  load: () => Promise<any> = () => import('postgres'),
+): Promise<UrlRunner> {
+  const postgres = await loadPostgresDriver(load);
   // max_lifetime: null — the driver's default recycles a connection after a random 30–60
   // minutes, resolving the in-flight query and THEN killing the session. Under reconcile's
   // BEGIN-across-calls transaction that is a silent session swap mid-batch (the reconcile
@@ -114,15 +122,7 @@ export async function createUrlPipelineRunner(
   url: string,
   load: () => Promise<any> = () => import('postgres'),
 ): Promise<UrlPipelineRunner> {
-  let mod: any;
-  try {
-    mod = await load();
-  } catch {
-    throw new Error(
-      'The direct-connection path needs the "postgres" driver. It ships with @everystack/server; in a project without it: pnpm add -D postgres',
-    );
-  }
-  const postgres = mod.default ?? mod;
+  const postgres = await loadPostgresDriver(load);
   const sql = postgres(url, { max: 1, onnotice: () => {}, ...sslDefaults(url) });
   return {
     query: async (query: string) => Array.from(await sql.unsafe(query)),
@@ -132,6 +132,57 @@ export async function createUrlPipelineRunner(
   };
 }
 
+export interface UrlProbeRunner {
+  /** Read-only introspection, for the contract pull/diff. */
+  runner: QueryRunner;
+  /** The self-reverting red-team probe. See `probe` below. */
+  probe: (setup: string, read: string) => Promise<any[]>;
+  /** Close the client so the process can exit cleanly. */
+  end: () => Promise<void>;
+}
+
+/** Thrown to abort the probe transaction; never escapes `probe`. */
+const PROBE_ROLLBACK = Symbol('authz_probe_rollback');
+
+/**
+ * The direct-connection twin of the server's `db:authz:probe` action
+ * (`@everystack/server` plugin.ts) — the local venue for `db:authz:test` / `db:authz:owner`.
+ *
+ * The probe SQL must WRITE to test INSERT/UPDATE/DELETE privileges, so the only thing
+ * standing between a red-team run and a mutated developer database is the rollback. It is
+ * therefore unconditional: the transaction body always throws `PROBE_ROLLBACK` after
+ * reading the outcome rows, so postgres.js aborts it on every path — success included.
+ * There is no code path that commits. `SET ROLE` is transactional (its effect disappears
+ * when the transaction aborts), so the session's role is restored by the same rollback.
+ *
+ * `max: 1` is load-bearing, not tuning: the probe's SET ROLE / savepoint state only makes
+ * sense on the single connection that ran the setup.
+ */
+export async function createUrlProbeRunner(
+  url: string,
+  load: () => Promise<any> = () => import('postgres'),
+): Promise<UrlProbeRunner> {
+  const postgres = await loadPostgresDriver(load);
+  const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => {}, ...sslDefaults(url) });
+  return {
+    runner: async (query: string) => Array.from(await sql.unsafe(query)),
+    probe: async (setup: string, read: string) => {
+      let rows: any[] = [];
+      try {
+        await sql.begin(async (tx: any) => {
+          await tx.unsafe(setup);
+          rows = Array.from(await tx.unsafe(read));
+          throw PROBE_ROLLBACK; // discard every probe write — unconditional
+        });
+      } catch (err: unknown) {
+        if (err !== PROBE_ROLLBACK) throw err;
+      }
+      return rows;
+    },
+    end: () => sql.end({ timeout: 5 }),
+  };
+}
+
 /**
  * Managed Postgres (RDS / Supabase / Neon) requires TLS — a direct connection without it
  * is rejected with pg_hba "no encryption". Default `ssl: 'require'` for remote hosts so the

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/index.ts

@@ -373,7 +373,7 @@ Usage:
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
   everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
-  everystack db:swap           --schema <name> --database-url <url> --from <artifact.dump> [--fingerprint <hash>]  Land a schema artifact atomically: fingerprint gate → restore into <schema>_incoming (COPY-safe rewrite) → one txn (drop+rename+recreate app→schema FKs, re-apply authz) → verify → drop retiring. Refresh-free; app.* untouched. DESTRUCTIVE (--stage/--direct ops venue rides stage-write-lanes)
+  everystack db:swap           --schema <name> --from <artifact.dump | artifact-id> [--stage <name> --direct | --database-url <url>] --confirm [--fingerprint <hash>] [--snapshot physical|logical|none] [--snapshot-ref <id>] [--rebuild-derived] [--dump-build <file.json>]  Land a schema artifact atomically: fingerprint gate → pre-flight refusals → CONFIRMED snapshot → restore into <schema>_incoming (COPY-safe rewrite) → build the paired derived layer → one txn (drop+rename+recreate app→schema FKs, re-apply authz + schema USAGE) → assertions → drop retiring. Refresh-free; app.* untouched; the derived layer is never absent. DESTRUCTIVE. The venue is EXPLICIT — DATABASE_URL in the env is refused, and --stage requires --direct (a multi-GB restore exceeds the ops-Lambda 900s clock). The rollback point defaults to a PHYSICAL RDS snapshot on a stage that exposes databaseInstanceId (no locks, no pg_dump contending with the restore) and a WAITED logical db:backup otherwise; a bare --database-url refuses without --snapshot-ref <id> or --snapshot none. docs/schema-swap.md
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default. --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
@@ -394,10 +394,11 @@ Usage:
   everystack db:template:refresh [--database-url <url>] [--models <barrel>] [--seed "<cmd>"] [--no-seed]  (Re)build the dev template <base>_tpl FROM THE DECLARED STATE (both layers, fingerprint MATCH bar) + seed-as-code (the app's db:seed script, run with DATABASE_URL pointed at the template; --seed overrides). All or nothing: a failed build/seed leaves NO template. Never a data copy
   everystack db:branch         [--list | --drop --confirm | --prune --confirm] [--database-url <url>]  Mint (or find) the current git branch's database from the template (CREATE DATABASE … TEMPLATE — schema, authz, derived layer, and seed rows inherited), print its DATABASE_URL, then db:sync evolves it with the checkout. --list maps every branch DB to its branch; --prune drops the ones whose branch is gone (never guesses: unknown mappings are kept)
   everystack db:fork           --from-stage <src> --stage <target> --confirm [--backup <id>]  Fork one DEPLOYED stage's database into another: back up the source (or reuse --backup <id>), presign the dump (the operator's credentials ARE the cross-stage authorization; expires in 1h), restore into the target via its ops Lambda. Production is never a target (that's db:restore); forking FROM production warns about PII; the branch's schema edge then lands via db:plan → db:apply (descent composes). Teardown: sst remove --stage <target>
-  everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
-  everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
-  everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)
-  everystack db:authz:owner    [--stage <name>] [--models db/models/index.ts]  Red-team owner isolation: two JWT identities per owner-scoped table — catches IDOR (non-zero exit on a leak)
+  everystack db:authz:pull     [--stage <name> | --database-url <url>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
+  everystack db:authz:diff     [--stage <name> | --database-url <url>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
+  everystack db:authz:test     [--stage <name> | --database-url <url>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)
+  everystack db:authz:owner    [--stage <name> | --database-url <url>] [--models db/models/index.ts]  Red-team owner isolation: two JWT identities per owner-scoped table — catches IDOR (non-zero exit on a leak)
+                               All four accept a DIRECT venue (--database-url, or an inherited ADMIN_DATABASE_URL/DATABASE_URL) so a brownfield authz migration can be rehearsed against a local database instead of a deployed stage. Same SQL, same evaluation, same verdict — every run names the venue it judged. The red-team probes WRITE to test INSERT/UPDATE/DELETE privileges and are always rolled back.
   everystack db:authz:report   [--dir authz]  Render the committed contract as a human-readable authorization review (no DB)
   everystack console           --stage <name> [--sandbox]  Interactive REPL on deployed Lambda
   everystack status            [--stage <name>] [--hours <n>]  Platform health: CDN, Lambda, rollup summary

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:',
@@ -403,7 +424,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 +441,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 +498,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 +556,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, '-')}';`,
     );