@everystack/cli 0.3.31 → 0.4.0

package/src/cli/derived-plan.ts

@@ -1,9 +1,9 @@
 /**
  * derived-plan — the reconciler's pure decision core.
  *
- * Joins the three inputs on identity — source objects (db/sql), the live
+ * Joins the three inputs on identity — source objects (descriptor-compiled), the live
  * catalog, and the provenance claims — and decides, per object: skip, create,
- * replace, refresh, drop, baseline, or prune. Hand-edited live objects are
+ * replace, refresh, drop, baseline, rebaseline, or prune. Hand-edited live objects are
  * DRIFT: reported, never silently overwritten (`overwriteDrift` makes the
  * overwrite explicit, and the drift stays in the report so the operator sees
  * what they overwrote). Never-reconciled matches are `needsBaseline`: the
@@ -24,10 +24,12 @@
  * drift report, not a silent skip.
  */
 
-import type { ParsedSources, SourceObject, DerivedKind } from './derived-source.js';
+import { type ParsedSources, type SourceObject, type DerivedKind } from './derived-source.js';
 import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
+import { triggerDropSql } from './derived-apply.js';
+import { parseGrantAttachments, diffObjectGrants } from './derived-grants.js';
 
-export type ReconcileVerb = 'create' | 'replace' | 'refresh' | 'drop' | 'baseline' | 'prune';
+export type ReconcileVerb = 'create' | 'replace' | 'refresh' | 'drop' | 'baseline' | 'rebaseline' | 'prune';
 
 export interface ReconcileAction {
   action: ReconcileVerb;
@@ -37,6 +39,9 @@ export interface ReconcileAction {
   /** Rebuild-cost signal from the live catalog (matviews). */
   bytes?: number;
   rows?: number;
+  /** Drops for the structural kinds — a trigger's `DROP TRIGGER … ON table`, a 'sql'
+   *  object's recorded/declared drop. Legacy kinds keep the keyword rendering. */
+  dropSql?: string;
 }
 
 export interface DriftFinding {
@@ -44,6 +49,21 @@ export interface DriftFinding {
   detail: string;
 }
 
+/** Grant drift on an up-to-date object — the idempotent REVOKE/GRANT delta that converges it. */
+export interface RegrantFinding {
+  identity: string;
+  statements: string[];
+}
+
+/** Declared `dependsOn` vs the live catalog's actual edges (B4: declared, then verified). */
+export interface DependencyDriftFinding {
+  identity: string;
+  /** Live edges the source never declared — the reachability gate walked past these. */
+  missing: string[];
+  /** Declared refs with no live edge — stale declarations. */
+  stale: string[];
+}
+
 export interface BlockedFinding {
   identity: string;
   reason: string;
@@ -66,6 +86,15 @@ export interface ReconcilePlan {
   warnings: string[];
   /** Sum of live bytes over rebuilt + refreshed matviews — the headline cost estimate. */
   totalRebuildBytes: number;
+  /** Provenance identity migrations — a table rename carried its triggers (same object,
+   *  new identity); the bookkeeping follows instead of drop+create-ing a live trigger. */
+  migrations: Array<{ from: string; to: string }>;
+  /** Grant drift on up-to-date objects: a hand-run GRANT/REVOKE touches no content hash,
+   *  so this is the only place it surfaces. Applied without ceremony — declared authz is
+   *  authoritative, and REVOKE/GRANT loses nothing but the drift itself. */
+  regrants: RegrantFinding[];
+  /** Declared-vs-actual dependency drift — check-fails (fix the declaration), never blocks apply. */
+  dependencyDrift: DependencyDriftFinding[];
 }
 
 export interface ReconcileOptions {
@@ -75,9 +104,28 @@ export interface ReconcileOptions {
   overwriteDrift?: boolean;
   /**
    * Rebuild never-reconciled source↔live matches from source (drop+create) instead of trusting
-   * them via baseline — the guarantee that live == db/sql when first contact can't verify it.
+   * them via baseline — the guarantee that live == source when first contact can't verify it.
    */
   rebuild?: boolean;
+  /**
+   * Re-record provenance for objects whose SOURCE hash changed while the LIVE object is
+   * verifiably untouched (live defHash == provenance defHash) — bookkeeping instead of a
+   * rebuild. The migration verb for a source re-render that produces the same object:
+   * the db/sql-era → descriptor move re-renders every object in the compiler's dialect
+   * (grant attachments on functions, pinned dollar-tags, plain CREATE), so the source
+   * hash changes even when the SQL is semantically identical. The live side is VERIFIED
+   * (defHash proves the object is exactly what the reconciler last applied); the source
+   * side is TRUSTED (a descriptor that actually differs will never deploy — its change
+   * is recorded as applied). Catalog-invisible 'sql'-kind objects are excluded: with no
+   * defHash to verify, they keep their recorded-drop rebuild.
+   */
+  rebaseline?: boolean;
+  /**
+   * Pending table renames (new qualified table → old qualified table, from the models'
+   * `renamedFrom` markers). PostgreSQL carries triggers through ALTER TABLE RENAME, so
+   * their provenance identity migrates with them.
+   */
+  renamedTables?: Record<string, string>;
 }
 
 const isRelation = (kind: DerivedKind): boolean => kind !== 'function';
@@ -91,6 +139,23 @@ export function planReconcile(
   const liveById = new Map(live.objects.map((o) => [o.identity, o]));
   const provById = new Map(live.provenance.map((p) => [p.identity, p]));
 
+  // Rename pre-pass: a pending table rename (renamedFrom) carried its triggers along in
+  // PostgreSQL, so a provenance row recorded under the OLD table is the SAME object as
+  // the source trigger under the NEW one — the bookkeeping migrates; nothing drops.
+  const migrations: Array<{ from: string; to: string }> = [];
+  for (const [newTable, oldTable] of Object.entries(options.renamedTables ?? {})) {
+    for (const prov of [...provById.values()]) {
+      if (prov.kind !== 'trigger' || !prov.identity.startsWith(`${oldTable}.`)) continue;
+      const to = `${newTable}.${prov.identity.slice(oldTable.length + 1)}`;
+      if (!srcById.has(to) || provById.has(to)) continue;
+      provById.delete(prov.identity);
+      provById.set(to, { ...prov, identity: to });
+      migrations.push({ from: prov.identity, to });
+    }
+  }
+  // Every provenance consumer below reads the POST-MIGRATION view.
+  const provRows = [...provById.values()];
+
   const skipped: string[] = [];
   const drift: DriftFinding[] = [];
   const needsBaseline: string[] = [];
@@ -106,16 +171,37 @@ export function planReconcile(
   /** Managed objects the source removed. */
   const drop = new Map<string, string>();
   const baseline: string[] = [];
+  const rebaseline: string[] = [];
   const prune: string[] = [];
 
   // -------------------------------------------------------------------------
   // The decision table.
   // -------------------------------------------------------------------------
 
+  /** identity → { statement, reason } for the provenance-tracked ('sql') kinds — these
+   *  never pass the live-existence filter, so they assemble their own drop actions. */
+  const sqlDrops = new Map<string, { dropSql: string; reason: string }>();
+  const extraWarnings: string[] = [];
+
   for (const src of source.objects) {
     const liveObj = liveById.get(src.identity);
     const prov = provById.get(src.identity);
 
+    // 'sql' objects (aggregates, domains, …) never join the live catalog — PROVENANCE is
+    // the live proxy. The documented contract of the escape hatch: provenance-tracked,
+    // no live drift detection; a change rebuilds through the recorded drop.
+    if (src.kind === 'sql') {
+      if (!prov) {
+        create.set(src.identity, 'new in source (provenance-tracked kind — invisible to the catalog)');
+      } else if (src.hash !== prov.srcHash) {
+        sqlDrops.set(src.identity, { dropSql: prov.dropSql ?? src.drop ?? '', reason: 'source changed' });
+        create.set(src.identity, 'source changed (rebuilt through the recorded drop)');
+      } else {
+        skipped.push(src.identity);
+      }
+      continue;
+    }
+
     if (!liveObj) {
       create.set(src.identity, prov
         ? 'missing from the database (recorded as applied — dropped by hand?)'
@@ -155,7 +241,11 @@ export function planReconcile(
       continue;
     }
     if (srcChanged) {
-      if (isRelation(src.kind)) rebuild.set(src.identity, 'source changed');
+      // The live object is verifiably untouched here (liveChanged was handled above), so
+      // under rebaseline a source re-render is bookkeeping: re-record the source hash,
+      // rebuild nothing, cascade nothing.
+      if (options.rebaseline) rebaseline.push(src.identity);
+      else if (isRelation(src.kind)) rebuild.set(src.identity, 'source changed');
       else fnReplace.set(src.identity, 'source changed');
       continue;
     }
@@ -168,8 +258,68 @@ export function planReconcile(
     else unmanaged.push(liveObj.identity);
   }
 
-  for (const prov of live.provenance) {
-    if (!srcById.has(prov.identity) && !liveById.has(prov.identity)) prune.push(prov.identity);
+  for (const prov of provRows) {
+    if (srcById.has(prov.identity) || liveById.has(prov.identity)) continue;
+    // A removed 'sql' object is invisible to the catalog — pruning would silently orphan
+    // it in the database. The recorded drop_sql removes it (the C1 closure); only a
+    // legacy row with no recorded drop falls back to prune, and says so.
+    if (prov.kind === 'sql') {
+      if (prov.dropSql) {
+        sqlDrops.set(prov.identity, { dropSql: prov.dropSql, reason: 'removed from source (dropped via the recorded drop_sql)' });
+      } else {
+        prune.push(prov.identity);
+        extraWarnings.push(`${prov.identity}: a 'sql'-kind object recorded without drop_sql (legacy row) — bookkeeping pruned; drop the object by hand if it still exists.`);
+      }
+      continue;
+    }
+    prune.push(prov.identity);
+  }
+
+  // -------------------------------------------------------------------------
+  // B4 — live drift the content hashes can't see, over the UP-TO-DATE objects
+  // only: created/replaced objects re-run their attachments, drifted objects
+  // are owned by the drift refusal.
+  // -------------------------------------------------------------------------
+
+  const regrants: RegrantFinding[] = [];
+  const dependencyDrift: DependencyDriftFinding[] = [];
+  // Rebaselined objects join the lens: their live catalog rows are as real as a skip's,
+  // and running the checks NOW means a migration converges (grants ride the same apply)
+  // instead of surfacing on the next plan.
+  const lensSet = new Set([...skipped, ...rebaseline]);
+  for (const src of source.objects) {
+    if (!lensSet.has(src.identity)) continue;
+    if (src.kind === 'trigger' || src.kind === 'sql') continue; // no grants, no rewrite edges
+    const liveObj = liveById.get(src.identity);
+
+    // Grant drift — only when the catalog actually reported ACLs (absent ≠ empty).
+    // Every object is descriptor-compiled (db/sql retired, B7), and the compiler
+    // ALWAYS declares authz — a private relation is declared-empty, not undeclared —
+    // so every up-to-date object is grant-checked.
+    if (liveObj?.grants !== undefined) {
+      const parsed = parseGrantAttachments(src.attachments);
+      if (parsed.hasColumnGrants) {
+        extraWarnings.push(
+          `${src.identity}: column-scoped grants are applied at create but not drift-checked (attacl introspection is future work) — hand edits to them are invisible here.`,
+        );
+      } else {
+        const target = parsed.target ?? (src.kind === 'function' ? `FUNCTION ${src.identity}` : src.identity);
+        const statements = diffObjectGrants(target, parsed.grants, liveObj.grants);
+        if (statements.length > 0) regrants.push({ identity: src.identity, statements });
+      }
+    }
+
+    // Dependency drift — declared, then verified. Only descriptor-home relations carry a
+    // declaration, and only relations have rewrite-rule edges for the catalog to answer with.
+    if (src.declaredDeps !== undefined && (src.kind === 'view' || src.kind === 'materialized view')) {
+      const liveDeps = new Set(live.edges.filter((e) => e.dependent === src.identity).map((e) => e.referenced));
+      const declaredSet = new Set(src.declaredDeps);
+      const missing = [...liveDeps].filter((d) => !declaredSet.has(d)).sort();
+      const stale = [...declaredSet].filter((d) => !liveDeps.has(d)).sort();
+      if (missing.length > 0 || stale.length > 0) {
+        dependencyDrift.push({ identity: src.identity, missing, stale });
+      }
+    }
   }
 
   // -------------------------------------------------------------------------
@@ -260,11 +410,23 @@ export function planReconcile(
     const cost = liveObj?.kind === 'materialized view'
       ? { ...(liveObj.bytes !== undefined ? { bytes: liveObj.bytes } : {}), ...(liveObj.rows !== undefined ? { rows: liveObj.rows } : {}) }
       : {};
-    return { action, identity: id, kind, reason, ...cost };
+    // A trigger's drop needs its table — composed from structure (source or live), never
+    // from the identity string (the red-team's C4: quoting a compound identity mangles it).
+    const structural = action === 'drop' && kind === 'trigger'
+      ? (() => {
+          const o = src ?? liveObj;
+          return o?.table ? { dropSql: triggerDropSql(o.name, o.table) } : {};
+        })()
+      : {};
+    return { action, identity: id, kind, reason, ...cost, ...structural };
   };
 
   const actions: ReconcileAction[] = [
     ...orderDrops(dropSet).map((id) => actionFor(id, 'drop', rebuild.get(id) ?? drop.get(id) ?? '')),
+    // 'sql'-kind drops (rebuilds + removals) — invisible to the live catalog, so they
+    // carry their own statement; ordered with the other drops, before every create.
+    ...[...sqlDrops.entries()].sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([id, d]) => ({ action: 'drop' as const, identity: id, kind: 'sql' as DerivedKind, reason: d.reason, dropSql: d.dropSql })),
     ...[...fnReplace.entries()].sort((a, b) => seqOf(a[0]) - seqOf(b[0]))
       .map(([id, reason]) => actionFor(id, 'replace', reason)),
     ...createSet.sort((a, b) => seqOf(a) - seqOf(b))
@@ -272,6 +434,7 @@ export function planReconcile(
     ...[...refresh.entries()].sort((a, b) => seqOf(a[0]) - seqOf(b[0]))
       .map(([id, reason]) => actionFor(id, 'refresh', reason)),
     ...baseline.sort().map((id) => actionFor(id, 'baseline', 'recording provenance for an existing match (trusted once, explicitly)')),
+    ...rebaseline.sort().map((id) => actionFor(id, 'rebaseline', 'source re-rendered — live verified untouched (defHash match); provenance re-recorded, no rebuild')),
     ...prune.sort().map((id) => ({
       action: 'prune' as const, identity: id, kind: 'view' as DerivedKind,
       reason: 'stale provenance — object gone from both source and database',
@@ -289,7 +452,10 @@ export function planReconcile(
     needsBaseline: needsBaseline.sort(),
     unmanaged: unmanaged.sort(),
     blocked,
-    warnings: [...source.warnings],
+    warnings: [...source.warnings, ...extraWarnings],
     totalRebuildBytes,
+    migrations,
+    regrants: regrants.sort((a, b) => a.identity.localeCompare(b.identity)),
+    dependencyDrift: dependencyDrift.sort((a, b) => a.identity.localeCompare(b.identity)),
   };
 }

package/src/cli/derived-render.ts

@@ -0,0 +1,320 @@
+/**
+ * derived-render — db:pull's derived-layer renderer (B5, read-model-everywhere).
+ *
+ * Live catalog → descriptor source. Bodies are the catalog's canonical deparse — that is
+ * EXPECTED (a pulled body never matches an authored spelling byte-for-byte); the
+ * adoption path is the existing `--baseline`: pull, commit, baseline once, and the next
+ * reconcile is a no-op. Grants render to `abilities` where the standard shapes match;
+ * `dependsOn` renders from the live edge graph, so pulled declarations are born accurate
+ * (B4's dependency drift and B2's reachability gate get real inputs from day one);
+ * matview indexes ride Brick E's parser; standalone sequences become `defineSequence`;
+ * a function the v1 signature vocabulary can't say falls back to `defineSql` carrying
+ * the whole `pg_get_functiondef`. Anything inexpressible is a LOUD FIXME — the adoption
+ * checklist effect, on purpose — never a silent drop.
+ */
+
+import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
+import type { SequenceSchema } from './schema-introspect.js';
+import { parseIndexDefinition } from './schema-introspect.js';
+
+export interface DerivedRenderResult {
+  /** The source block: `export const … = defineView(…)` etc., dependency-ordered. */
+  block: string;
+  /** Rendered derived variable names, emission order — feed `defineModule({ derived })`. */
+  names: string[];
+  /** Rendered sequence variable names — feed `defineModule({ sequences })`. */
+  sequenceNames: string[];
+  /** Model-package symbols the block uses (defineView, can, sql, arg, index, …). */
+  imports: string[];
+  /** Everything skipped or flagged — mirrored as FIXME comments in the block. */
+  warnings: string[];
+}
+
+export interface DerivedRenderOptions {
+  /** Qualified table (`public.posts`) → the model variable name rendered in the barrel. */
+  knownTables: Map<string, string>;
+  /** Standalone sequences from the snapshot (serial-owned stay implicit). */
+  sequences?: SequenceSchema[];
+}
+
+const PLAIN_IDENT = /^[a-z_][a-z0-9_$]*$/;
+
+function toCamelCase(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** Escape a body for a template literal in generated source — it must always parse. */
+function tsTemplate(body: string): string {
+  return body.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+
+function tsString(s: string): string {
+  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+/** The relation grant shapes `abilities` can say. Null = inexpressible (caller FIXMEs). */
+function relationAbilities(grants: Record<string, string[]>): string[] | null {
+  const roles = Object.keys(grants);
+  for (const role of roles) {
+    if (role.toUpperCase() === 'PUBLIC') return null;
+    if (grants[role].some((p) => p !== 'SELECT')) return null;
+  }
+  const set = new Set(roles);
+  const out: string[] = [];
+  if (set.has('anon') && set.has('authenticated')) {
+    out.push(`can('read')`);
+    set.delete('anon');
+    set.delete('authenticated');
+  }
+  for (const role of [...set].sort()) out.push(`can('read', { role: ${tsString(role)} })`);
+  return out;
+}
+
+/** VOLATILITY letters → the descriptor words ('v' is the default, never spelled). */
+const VOLATILITY: Record<string, string> = { i: 'immutable', s: 'stable' };
+
+interface ParsedArg {
+  name: string;
+  type: string;
+  default?: string;
+}
+
+/** Parse `pg_get_function_arguments` output. Null = beyond the v1 vocabulary. */
+function parseArgs(args: string): ParsedArg[] | null {
+  const trimmed = args.trim();
+  if (!trimmed) return [];
+  const out: ParsedArg[] = [];
+  let depth = 0;
+  let start = 0;
+  const entries: string[] = [];
+  for (let i = 0; i < trimmed.length; i++) {
+    if (trimmed[i] === '(') depth++;
+    else if (trimmed[i] === ')') depth--;
+    else if (trimmed[i] === ',' && depth === 0) {
+      entries.push(trimmed.slice(start, i));
+      start = i + 1;
+    }
+  }
+  entries.push(trimmed.slice(start));
+  for (const entry of entries.map((e) => e.trim())) {
+    if (/^(OUT|INOUT|VARIADIC)\b/i.test(entry)) return null;
+    const m = entry.match(/^([a-z_][a-z0-9_$]*)\s+(.+?)(?:\s+DEFAULT\s+(.+))?$/i);
+    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;
+    out.push({ name: m[1], type: m[2], ...(m[3] ? { default: m[3] } : {}) });
+  }
+  return out;
+}
+
+/** One matview index attachment → the Brick E builder chain, or null (FIXME). */
+function renderIndexBuilder(indexdef: string): string | null {
+  const parsed = parseIndexDefinition(indexdef);
+  if (!parsed) return null;
+  const entry = (c: string): string => (PLAIN_IDENT.test(c) ? tsString(c) : `sql\`${tsTemplate(c)}\``);
+  let s = `index(${parsed.columns.map(entry).join(', ')})`;
+  if (parsed.using) s += `.using(${tsString(parsed.using)})`;
+  if (parsed.unique) s += '.unique()';
+  if (parsed.include?.length) s += `.include(${parsed.include.map(tsString).join(', ')})`;
+  if (parsed.where) s += `.where(sql\`${tsTemplate(parsed.where)}\`)`;
+  return s;
+}
+
+export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRenderOptions): DerivedRenderResult {
+  const warnings: string[] = [];
+  const lines: string[] = [];
+  const names: string[] = [];
+  const used = new Set<string>();
+  const need = (sym: string): void => { used.add(sym); };
+
+  // -- sequences (state layer — they precede the compute in the module) -------
+
+  const sequenceNames: string[] = [];
+  for (const seq of opts.sequences ?? []) {
+    const varName = toCamelCase(seq.name.replace(/\./g, '_'));
+    const props: string[] = [];
+    if (seq.as !== 'bigint') props.push(`as: ${tsString(seq.as)}`);
+    if (seq.start != null) props.push(`start: ${seq.start}`);
+    if (seq.increment != null) props.push(`increment: ${seq.increment}`);
+    lines.push(`export const ${varName} = defineSequence(${tsString(seq.name)}${props.length ? `, { ${props.join(', ')} }` : ''});`);
+    need('defineSequence');
+    sequenceNames.push(varName);
+  }
+  if (sequenceNames.length) lines.push('');
+
+  // -- emission order: dependencies first (Kahn over derived→derived edges) ---
+
+  const renderable = catalog.objects.filter((o) => o.kind !== 'trigger');
+  for (const t of catalog.objects.filter((o) => o.kind === 'trigger')) {
+    warnings.push(`${t.identity}: live trigger not rendered — declare it on its model with trigger() (v1 renders relations, functions, and sequences).`);
+  }
+  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.
+  const varOf = new Map(renderable.map((o) =>
+    [o.identity, toCamelCase(o.schema === 'public' ? o.name : `${o.schema}_${o.name}`)]));
+  // 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);
+
+  const indegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+  for (const o of renderable) indegree.set(o.identity, 0);
+  for (const e of catalog.edges) {
+    if (!byIdentity.has(e.dependent) || !byIdentity.has(e.referenced)) continue;
+    indegree.set(e.dependent, (indegree.get(e.dependent) ?? 0) + 1);
+    dependents.set(e.referenced, [...(dependents.get(e.referenced) ?? []), e.dependent]);
+  }
+  const ready = renderable.filter((o) => indegree.get(o.identity) === 0).map((o) => o.identity).sort();
+  const ordered: LiveObject[] = [];
+  while (ready.length) {
+    const id = ready.shift()!;
+    ordered.push(byIdentity.get(id)!);
+    for (const dep of dependents.get(id) ?? []) {
+      const left = (indegree.get(dep) ?? 0) - 1;
+      indegree.set(dep, left);
+      if (left === 0) {
+        ready.push(dep);
+        ready.sort();
+      }
+    }
+  }
+  // A cycle is impossible in a live catalog (PostgreSQL refuses it); anything left over
+  // would mean edge noise — emit it anyway, identity-sorted, rather than dropping it.
+  for (const o of renderable) if (!ordered.includes(o)) ordered.push(o);
+
+  // -- per-object rendering ----------------------------------------------------
+
+  const depsFor = (identity: string): { refs: string[]; fixmes: string[] } => {
+    const refs: string[] = [];
+    const fixmes: string[] = [];
+    const seen = new Set<string>();
+    for (const e of catalog.edges) {
+      if (e.dependent !== identity || seen.has(e.referenced)) continue;
+      seen.add(e.referenced);
+      const model = opts.knownTables.get(e.referenced);
+      const derived = varOf.get(e.referenced);
+      if (model) refs.push(model);
+      else if (derived) refs.push(derived);
+      else fixmes.push(`// FIXME: dependsOn ${e.referenced} — not in the pulled set; declare it by hand.`);
+    }
+    return { refs: refs.sort(), fixmes };
+  };
+
+  for (const o of ordered) {
+    const varName = varOf.get(o.identity)!;
+    const { refs, fixmes } = depsFor(o.identity);
+
+    if (o.kind === 'view' || o.kind === 'materialized view') {
+      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.`);
+        lines.push(`// FIXME: ${o.identity} skipped — live grants (${grantText}) are not expressible as abilities (views are read surfaces).`, '');
+        continue;
+      }
+      const props: string[] = [];
+      if (o.kind === 'view') props.push(`securityInvoker: ${o.securityInvoker === true},`);
+      if (abilities.length === 0) props.push('private: true,');
+      else {
+        props.push(`abilities: [${abilities.join(', ')}],`);
+        need('can');
+      }
+      if (refs.length) props.push(`dependsOn: [${refs.join(', ')}],`);
+      if (o.kind === 'materialized view') {
+        const builders = o.indexes.map((def) => {
+          const b = renderIndexBuilder(def);
+          if (b === null) warnings.push(`${o.identity}: index not renderable: ${def}`);
+          return b;
+        }).filter((b): b is string => b !== null);
+        if (builders.length) {
+          props.push(`indexes: [${builders.join(', ')}],`);
+          need('index');
+        }
+        if (o.populated === false) props.push(`populate: 'deferred',`);
+      }
+      if (o.comment) props.push(`comment: ${tsString(o.comment)},`);
+      props.push(`as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`);
+      need(o.kind === 'view' ? 'defineView' : 'defineMaterializedView');
+      need('sql');
+      lines.push(
+        ...fixmes,
+        `export const ${varName} = ${o.kind === 'view' ? 'defineView' : 'defineMaterializedView'}(${tsString(declaredName(o))}, {`,
+        ...props.map((p) => `  ${p}`),
+        '});',
+        '',
+      );
+      names.push(varName);
+      continue;
+    }
+
+    // Functions.
+    const f = o.fn;
+    const grants = o.grants ?? {};
+    const roleGrants = Object.keys(grants).filter((r) => r.toUpperCase() !== 'PUBLIC').sort();
+    const publicExec = Object.keys(grants).some((r) => r.toUpperCase() === 'PUBLIC');
+    const args = f && (f.language === 'sql' || f.language === 'plpgsql') ? parseArgs(f.args) : null;
+
+    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.`);
+      lines.push(
+        `// FIXME: ${o.identity} — signature beyond defineFunction's v1 vocabulary; kept verbatim as defineSql.`,
+        `export const ${varName} = defineSql(${tsString(declaredName(o))}, {`,
+        `  kind: 'function',`,
+        `  drop: sql\`DROP FUNCTION IF EXISTS ${o.identity.startsWith('public.') ? o.name : o.identity}\`,`,
+        `  as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`,
+        '});',
+        '',
+      );
+      need('defineSql');
+      need('sql');
+      names.push(varName);
+      continue;
+    }
+
+    const props: string[] = [];
+    if (args.length) {
+      const rendered = args.map((a) =>
+        `arg(${tsString(a.name)}, ${tsString(a.type)}${a.default ? `, { default: sql\`${tsTemplate(a.default)}\` }` : ''})`);
+      props.push(`args: [${rendered.join(', ')}],`);
+      need('arg');
+    }
+    props.push(`returns: ${tsString(f.returns)},`);
+    props.push(`language: ${tsString(f.language)},`);
+    if (VOLATILITY[f.volatility]) props.push(`volatility: ${tsString(VOLATILITY[f.volatility])},`);
+    if (f.secdef) {
+      props.push(`security: 'definer',`);
+      const path = (f.searchPath ?? 'pg_catalog').split(',').map((s) => s.trim().replace(/^"|"$/g, '')).filter(Boolean);
+      props.push(`searchPath: [${path.map(tsString).join(', ')}],`);
+    }
+    if (roleGrants.length) {
+      props.push(`abilities: [${roleGrants.map((r) => `can('execute', { role: ${tsString(r)} })`).join(', ')}],`);
+      need('can');
+    }
+    if (refs.length) props.push(`dependsOn: [${refs.join(', ')}],`);
+    if (o.comment) props.push(`comment: ${tsString(o.comment)},`);
+    props.push(`body: sql\`${tsTemplate(f.src.trim())}\`,`);
+    need('defineFunction');
+    need('sql');
+    lines.push(
+      ...fixmes,
+      ...(publicExec
+        ? [`// FIXME: ${o.identity} — live grants EXECUTE to PUBLIC; descriptors ALWAYS revoke PUBLIC. Declare the intended callers (adopting this descriptor applies the revoke).`]
+        : []),
+      `export const ${varName} = defineFunction(${tsString(declaredName(o))}, {`,
+      ...props.map((p) => `  ${p}`),
+      '});',
+      '',
+    );
+    names.push(varName);
+  }
+
+  return {
+    block: lines.join('\n').trimEnd(),
+    names,
+    sequenceNames,
+    imports: [...used].sort(),
+    warnings,
+  };
+}