@everystack/cli 0.4.82 → 0.4.83

package/src/cli/derived-render.ts

@@ -13,13 +13,35 @@
  * checklist effect, on purpose — never a silent drop.
  */
 
+import path from 'node:path';
 import type { DerivedCatalog, LiveObject } from './derived-introspect';
 import type { ColumnSchema, SequenceSchema, TableSchema } from './schema-introspect';
 import { parseIndexDefinition } from './schema-introspect';
-import { modelImportPath, renderFieldLines } from './model-render';
+import { modelImportPath, modelFileName, renderFieldLines } from './model-render';
 import { splitFunctionIdentity } from './pg-argtypes';
 import { GOVERNED_VOCABULARY, KNOWN_ROLES } from './authz-derive';
 
+/**
+ * One rendered object's own lines, plus what it depends on — the unit `--derived-out <dir>`
+ * splits by. Purely additive alongside `block` (Step 1 of the directory split): `block` stays
+ * exactly `records.flatMap(r => r.lines).join('\n')` mixed with the pre-loop sequence spacer,
+ * so the single-file path is byte-identical to before this existed.
+ */
+export interface DerivedRecord {
+  /** Live catalog identity (`public.active_posts`, `auth.sign_jwt(text)`, …) — a synthetic
+   *  `sequence:<name>` for a standalone sequence, which the catalog does not carry. */
+  identity: string;
+  varName: string;
+  kind: LiveObject['kind'] | 'sequence';
+  schema: string;
+  /** This object's own rendered lines, exactly as they appear in `block`. */
+  lines: string[];
+  /** Qualified tables (knownTables keys) this record's dependsOn/execute/on needs imported. */
+  modelRefs: string[];
+  /** Other records' identities this record's dependsOn/execute/on needs imported. */
+  derivedRefs: string[];
+}
+
 export interface DerivedRenderResult {
   /** The source block: `export const … = defineView(…)` etc., dependency-ordered. */
   block: string;
@@ -37,6 +59,12 @@ export interface DerivedRenderResult {
   modelRefs: string[];
   /** Everything skipped or flagged — mirrored as FIXME comments in the block. */
   warnings: string[];
+  /** Per-object records, emission order — what `--derived-out <dir>` partitions by kind
+   *  and schema. `records.flatMap(r => r.lines)` reproduces `block`'s content exactly.
+   *  Optional so a hand-built fixture typed as `DerivedRenderResult` elsewhere in the
+   *  codebase (there is no reason to fake a directory split) does not need updating —
+   *  `renderDerivedSource` always populates it; `renderDerivedDirectory` requires it. */
+  records?: DerivedRecord[];
 }
 
 export interface DerivedRenderOptions {
@@ -375,11 +403,15 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
   const materializedTableNames: string[] = [];
   const used = new Set<string>();
   const need = (sym: string): void => { used.add(sym); };
+  // Step 1 of the directory split: accumulated ALONGSIDE `lines`, never instead of it — every
+  // push below still goes through `lines` first, so `block` is built exactly as it always was.
+  const records: DerivedRecord[] = [];
 
   // -- sequences (state layer — they precede the compute in the module) -------
 
   const sequenceNames: string[] = [];
   for (const seq of opts.sequences ?? []) {
+    const linesStart = lines.length;
     const varName = toCamelCase(seq.name.replace(/\./g, '_'));
     const props: string[] = [];
     if (seq.as !== 'bigint') props.push(`as: ${tsString(seq.as)}`);
@@ -388,6 +420,15 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     lines.push(`export const ${varName} = defineSequence(${tsString(seq.name)}${props.length ? `, { ${props.join(', ')} }` : ''});`);
     need('defineSequence');
     sequenceNames.push(varName);
+    records.push({
+      identity: `sequence:${seq.name}`,
+      varName,
+      kind: 'sequence',
+      schema: seq.name.includes('.') ? seq.name.split('.')[0] : 'public',
+      lines: lines.slice(linesStart),
+      modelRefs: [],
+      derivedRefs: [],
+    });
   }
   if (sequenceNames.length) lines.push('');
 
@@ -447,9 +488,14 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
   // -- per-object rendering ----------------------------------------------------
 
   const modelRefs = new Set<string>();
-  const depsFor = (identity: string): { refs: string[]; fixmes: string[] } => {
+  const depsFor = (identity: string): { refs: string[]; fixmes: string[]; identRefs: { model: string[]; derived: string[] } } => {
     const refs: string[] = [];
     const fixmes: string[] = [];
+    // Identity-level split, alongside the resolved-var-name `refs` above — what
+    // `--derived-out <dir>` needs to know which FILE a dependency lives in, since a var
+    // name alone doesn't say whether it came from a model or another derived object.
+    const modelIdents: string[] = [];
+    const derivedIdents: string[] = [];
     const seen = new Set<string>();
     for (const e of catalog.edges) {
       if (e.dependent !== identity || seen.has(e.referenced)) continue;
@@ -459,278 +505,302 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       if (model) {
         refs.push(model);
         modelRefs.add(e.referenced);
-      } else if (derived) refs.push(derived);
-      else fixmes.push(`// FIXME: dependsOn ${e.referenced} — not in the pulled set; declare it by hand.`);
+        modelIdents.push(e.referenced);
+      } else if (derived) {
+        refs.push(derived);
+        derivedIdents.push(e.referenced);
+      } else fixmes.push(`// FIXME: dependsOn ${e.referenced} — not in the pulled set; declare it by hand.`);
     }
-    return { refs: refs.sort(), fixmes };
+    return { refs: refs.sort(), fixmes, identRefs: { model: modelIdents.sort(), derived: derivedIdents.sort() } };
   };
 
   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') {
-      // The live ACL splits in two: the part `can('read')` can SAY (plain SELECT to named
-      // app roles) becomes abilities, and everything else is RECORDED as `privileges`.
-      //
-      // This used to skip the object outright — definition and all — whenever any grant
-      // was inexpressible, which on a real brownfield schema is every relation it has:
-      // three roles hold the blanket DELETE/INSERT/REFERENCES/SELECT/TRIGGER/TRUNCATE/
-      // UPDATE that `GRANT ALL ON ALL TABLES IN SCHEMA` leaves behind, and PUBLIC holds
-      // SELECT on a few. The adopter got a FIXME instead of their view.
-      //
-      // Recording is also what makes rendering SAFE, and it is why the silent-REVOKE
-      // question that blocked this no longer needs an answer: emitting the view with only
-      // the abilities we can express would leave the write grants undeclared, so the next
-      // generate would plan a REVOKE for each — a silent skip traded for a silent revoke.
-      // Declared == live means nothing is planned at all.
-      const { abilities, privileges, foreign } = splitRelationGrants(o.grants ?? {});
-      if (foreign.length) {
-        warnings.push(
-          `${o.identity}: grants exist for ${foreign.join(', ')} — recorded as \`privileges\`, not declared as ` +
-          'abilities. Abilities name the roles the model governs (anon/authenticated/admin); a grantee outside ' +
-          'that vocabulary is fact, not an intended audience. Recorded rather than dropped because a derived ' +
-          'object REVOKES any live grantee the declaration omits.',
-        )
-      }
-      const writeGrants = Object.values(privileges).some((ps) =>
-        ps.some((p) => p === 'INSERT' || p === 'UPDATE' || p === 'DELETE'),
-      );
-      if (writeGrants) {
-        // 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 grantText = Object.entries(privileges).map(([r, p]) => `${r}: ${p.join('/')}`).join(', ');
-        warnings.push(
-          `${o.identity}: write privileges (${grantText}) recorded as \`privileges\` — the object is declared and nothing will be revoked. ` +
-          '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, then revoke and re-pull.',
+    const { refs, fixmes, identRefs } = depsFor(o.identity);
+    // What the RECORD claims this object references — normally exactly the edges `dependsOn`
+    // renders. The defineSql fallback is the exception and it has to be said here: that branch
+    // renders NO dependsOn at all, so a record still carrying the edges would make
+    // renderDerivedDirectory emit `import { X } from './views'` into a split file whose
+    // generated code never names X. An unused import in generated code is a hard compile
+    // error under a consumer's `noUnusedLocals`.
+    let recordRefs: { model: string[]; derived: string[] } = identRefs;
+    const linesStart = lines.length;
+    try {
+      if (o.kind === 'view' || o.kind === 'materialized view') {
+        // The live ACL splits in two: the part `can('read')` can SAY (plain SELECT to named
+        // app roles) becomes abilities, and everything else is RECORDED as `privileges`.
+        //
+        // This used to skip the object outright — definition and all — whenever any grant
+        // was inexpressible, which on a real brownfield schema is every relation it has:
+        // three roles hold the blanket DELETE/INSERT/REFERENCES/SELECT/TRIGGER/TRUNCATE/
+        // UPDATE that `GRANT ALL ON ALL TABLES IN SCHEMA` leaves behind, and PUBLIC holds
+        // SELECT on a few. The adopter got a FIXME instead of their view.
+        //
+        // Recording is also what makes rendering SAFE, and it is why the silent-REVOKE
+        // question that blocked this no longer needs an answer: emitting the view with only
+        // the abilities we can express would leave the write grants undeclared, so the next
+        // generate would plan a REVOKE for each — a silent skip traded for a silent revoke.
+        // Declared == live means nothing is planned at all.
+        const { abilities, privileges, foreign } = splitRelationGrants(o.grants ?? {});
+        if (foreign.length) {
+          warnings.push(
+            `${o.identity}: grants exist for ${foreign.join(', ')} — recorded as \`privileges\`, not declared as ` +
+            'abilities. Abilities name the roles the model governs (anon/authenticated/admin); a grantee outside ' +
+            'that vocabulary is fact, not an intended audience. Recorded rather than dropped because a derived ' +
+            'object REVOKES any live grantee the declaration omits.',
+          )
+        }
+        const writeGrants = Object.values(privileges).some((ps) =>
+          ps.some((p) => p === 'INSERT' || p === 'UPDATE' || p === 'DELETE'),
         );
-      }
+        if (writeGrants) {
+          // 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 grantText = Object.entries(privileges).map(([r, p]) => `${r}: ${p.join('/')}`).join(', ');
+          warnings.push(
+            `${o.identity}: write privileges (${grantText}) recorded as \`privileges\` — the object is declared and nothing will be revoked. ` +
+            '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, then revoke and re-pull.',
+          );
+        }
 
-      // --matviews-as-tables (the gap-B consumer flip): the matview renders as a
-      // defineMaterializedTable MODEL — introspected fields, index constraints on field
-      // keys, the defining query as metadata. Same topo slot (its dependents still
-      // reference it by variable); the name lands in materializedTableNames, not names.
-      if (o.kind === 'materialized view' && opts.matviewsAsTables) {
-        const cols = opts.matviewsAsTables.columns.get(o.identity);
-        if (!cols || cols.length === 0) {
-          warnings.push(`${o.identity}: no live columns found for the table render — rendered as defineMaterializedView; re-pull or flip it by hand.`);
-        } else {
-          if (o.populated === false) {
-            warnings.push(`${o.identity}: the live matview is UNPOPULATED — rendered anyway (a materialized table's contents are pipeline-owned).`);
+        // --matviews-as-tables (the gap-B consumer flip): the matview renders as a
+        // defineMaterializedTable MODEL — introspected fields, index constraints on field
+        // keys, the defining query as metadata. Same topo slot (its dependents still
+        // reference it by variable); the name lands in materializedTableNames, not names.
+        if (o.kind === 'materialized view' && opts.matviewsAsTables) {
+          const cols = opts.matviewsAsTables.columns.get(o.identity);
+          if (!cols || cols.length === 0) {
+            warnings.push(`${o.identity}: no live columns found for the table render — rendered as defineMaterializedView; re-pull or flip it by hand.`);
+          } else {
+            if (o.populated === false) {
+              warnings.push(`${o.identity}: the live matview is UNPOPULATED — rendered anyway (a materialized table's contents are pipeline-owned).`);
+            }
+            const shape: TableSchema = {
+              table: o.identity, columns: cols,
+              primaryKey: [], uniques: [], checks: [], foreignKeys: [], indexes: [],
+            };
+            // Field lines align with `cols` by index — append the --suggest-keys comment in place.
+            const suggested = new Set(opts.matviewsAsTables.keyCandidates?.get(o.identity) ?? []);
+            const fieldLines = renderFieldLines(shape, new Set(), opts.matviewsAsTables.enums ?? new Map())
+              .map((line, i) => suggested.has(cols[i].name)
+                ? `${line} // PK candidate: non-null + all-distinct across live rows — add .primaryKey() if this is the natural key`
+                : line);
+            const builders = o.indexes.map((def) => {
+              const b = renderTableIndexBuilder(def);
+              if (b === null) warnings.push(`${o.identity}: index not renderable: ${def}`);
+              return b;
+            }).filter((b): b is string => b !== null);
+            if (builders.length) need('index');
+            if (abilities.length) need('can');
+            need('defineMaterializedTable');
+            need('field');
+            need('sql');
+            // MODEL naming idiom: bare table + a schema prop. The derived layer's
+            // qualified-first-arg spelling must NOT leak here — defineModel stores the
+            // table name verbatim, so 'stats.x' would become a dot-containing identifier
+            // in public and 3-part-qualify (public.stats.x) downstream.
+            lines.push(
+              ...fixmes,
+              `export const ${varName} = defineMaterializedTable(${tsString(o.name)}, {`,
+              // Same split as the relation path: a model carries `privileges` too, so the
+              // inexpressible grants are recorded rather than dropped on this branch either.
+              ...(abilities.length ? [`  abilities: [${abilities.join(', ')}],`]
+                : Object.keys(privileges).length ? [] : ['  private: true,']),
+              ...(Object.keys(privileges).length
+                ? [`  privileges: { ${Object.keys(privileges).sort().map((g) => `${tsKey(g)}: [${privileges[g].map(tsString).join(', ')}]`).join(', ')} },`]
+                : []),
+              ...(o.schema !== 'public' ? [`  schema: ${tsString(o.schema)},`] : []),
+              '  fields: {',
+              ...fieldLines,
+              '  },',
+              ...(builders.length ? [`  constraints: [${builders.join(', ')}],`] : []),
+              ...(refs.length ? [`  dependsOn: [${refs.join(', ')}],`] : []),
+              ...(o.comment ? [`  comment: ${tsString(o.comment)},`] : []),
+              `  as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`,
+              '});',
+              '',
+            );
+            materializedTableNames.push(varName);
+            continue;
           }
-          const shape: TableSchema = {
-            table: o.identity, columns: cols,
-            primaryKey: [], uniques: [], checks: [], foreignKeys: [], indexes: [],
-          };
-          // Field lines align with `cols` by index — append the --suggest-keys comment in place.
-          const suggested = new Set(opts.matviewsAsTables.keyCandidates?.get(o.identity) ?? []);
-          const fieldLines = renderFieldLines(shape, new Set(), opts.matviewsAsTables.enums ?? new Map())
-            .map((line, i) => suggested.has(cols[i].name)
-              ? `${line} // PK candidate: non-null + all-distinct across live rows — add .primaryKey() if this is the natural key`
-              : line);
+        }
+
+        const props: string[] = [];
+        const hasPrivileges = Object.keys(privileges).length > 0;
+        if (o.kind === 'view') props.push(`securityInvoker: ${o.securityInvoker === true},`);
+        // A15 — the owner, through the SAME discriminator functions use. Elevated exactly when
+        // the relation runs as its owner: a view that is not securityInvoker, and a matview
+        // always (its rows are computed at REFRESH time with the owner's rights, no exceptions).
+        const relationOwnership = renderedOwner(
+          o,
+          o.kind === 'materialized view' ? MATVIEW_RIGHTS
+            : o.securityInvoker === false ? DEFINER_VIEW_RIGHTS
+              : null,
+        );
+        if (relationOwnership.prop) props.push(relationOwnership.prop);
+        if (relationOwnership.fixme) fixmes.push(relationOwnership.fixme);
+        // The FIXME lands in the file, at the declaration, which is where the operator acts on
+        // it. The stderr WARNING is deliberately NOT raised for relations: `SECURITY DEFINER` is
+        // opt-in and rare, so echoing those is signal, but `security_invoker = false` is
+        // PostgreSQL's DEFAULT for views — on any real database nearly every view and every
+        // matview qualifies, and promoting all of them would bury the function findings the
+        // channel exists for. Same judgement the function branch already makes for its plain
+        // case, applied where the base rate is inverted.
+        // `private: true` means "declared dark, no grants" — it contradicts a recorded
+        // grant, and the model refuses the pair. A relation whose only reach is recorded
+        // (PUBLIC SELECT, or a write grant) is not dark; it just has no CHOSEN audience.
+        if (abilities.length === 0 && !hasPrivileges) props.push('private: true,');
+        else if (abilities.length) {
+          props.push(`abilities: [${abilities.join(', ')}],`);
+          need('can');
+        }
+        if (hasPrivileges) {
+          const entries = Object.keys(privileges).sort()
+            .map((g) => `${tsKey(g)}: [${privileges[g].map(tsString).join(', ')}]`);
+          props.push(`privileges: { ${entries.join(', ')} },`);
+        }
+        if (refs.length) props.push(`dependsOn: [${refs.join(', ')}],`);
+        if (o.kind === 'materialized view') {
           const builders = o.indexes.map((def) => {
-            const b = renderTableIndexBuilder(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) need('index');
-          if (abilities.length) need('can');
-          need('defineMaterializedTable');
-          need('field');
-          need('sql');
-          // MODEL naming idiom: bare table + a schema prop. The derived layer's
-          // qualified-first-arg spelling must NOT leak here — defineModel stores the
-          // table name verbatim, so 'stats.x' would become a dot-containing identifier
-          // in public and 3-part-qualify (public.stats.x) downstream.
-          lines.push(
-            ...fixmes,
-            `export const ${varName} = defineMaterializedTable(${tsString(o.name)}, {`,
-            // Same split as the relation path: a model carries `privileges` too, so the
-            // inexpressible grants are recorded rather than dropped on this branch either.
-            ...(abilities.length ? [`  abilities: [${abilities.join(', ')}],`]
-              : Object.keys(privileges).length ? [] : ['  private: true,']),
-            ...(Object.keys(privileges).length
-              ? [`  privileges: { ${Object.keys(privileges).sort().map((g) => `${tsKey(g)}: [${privileges[g].map(tsString).join(', ')}]`).join(', ')} },`]
-              : []),
-            ...(o.schema !== 'public' ? [`  schema: ${tsString(o.schema)},`] : []),
-            '  fields: {',
-            ...fieldLines,
-            '  },',
-            ...(builders.length ? [`  constraints: [${builders.join(', ')}],`] : []),
-            ...(refs.length ? [`  dependsOn: [${refs.join(', ')}],`] : []),
-            ...(o.comment ? [`  comment: ${tsString(o.comment)},`] : []),
-            `  as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`,
-            '});',
-            '',
-          );
-          materializedTableNames.push(varName);
-          continue;
+          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;
+      const ownership = renderedFunctionOwner(o, f?.secdef === true);
+
+      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.`);
+        // Nothing below renders `dependsOn`, so the record declares no refs — see recordRefs.
+        recordRefs = { model: [], derived: [] };
+        // 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})` : '');
+        // A defineSql object cannot carry an owner. Where the pull observed a CHOSEN owner that
+        // is real fidelity loss, so it is said out loud on both surfaces — never dropped. An
+        // ambient owner needs no note here: there is nothing to declare and nothing was lost.
+        if (ownership.prop) {
+          const why = `${o.identity}: owned by '${o.owner}', but defineSql cannot declare an owner — the build will create it as the connecting role. Move it into defineFunction's vocabulary, or set the owner by hand after the build.`;
+          warnings.push(why);
+          lines.push(`// FIXME: ${why}`);
+        }
+        lines.push(
+          `// FIXME: ${o.identity} — signature beyond defineFunction's v1 vocabulary; kept verbatim as defineSql.`,
+          `export const ${varName} = defineSql(${tsString(sqlName)}, {`,
+          `  kind: 'function',`,
+          `  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(/;$/, ''))}\`,`,
+          '});',
+          '',
+        );
+        need('defineSql');
+        need('sql');
+        names.push(varName);
+        continue;
       }
 
       const props: string[] = [];
-      const hasPrivileges = Object.keys(privileges).length > 0;
-      if (o.kind === 'view') props.push(`securityInvoker: ${o.securityInvoker === true},`);
-      // A15 — the owner, through the SAME discriminator functions use. Elevated exactly when
-      // the relation runs as its owner: a view that is not securityInvoker, and a matview
-      // always (its rows are computed at REFRESH time with the owner's rights, no exceptions).
-      const relationOwnership = renderedOwner(
-        o,
-        o.kind === 'materialized view' ? MATVIEW_RIGHTS
-          : o.securityInvoker === false ? DEFINER_VIEW_RIGHTS
-            : null,
-      );
-      if (relationOwnership.prop) props.push(relationOwnership.prop);
-      if (relationOwnership.fixme) fixmes.push(relationOwnership.fixme);
-      // The FIXME lands in the file, at the declaration, which is where the operator acts on
-      // it. The stderr WARNING is deliberately NOT raised for relations: `SECURITY DEFINER` is
-      // opt-in and rare, so echoing those is signal, but `security_invoker = false` is
-      // PostgreSQL's DEFAULT for views — on any real database nearly every view and every
-      // matview qualifies, and promoting all of them would bury the function findings the
-      // channel exists for. Same judgement the function branch already makes for its plain
-      // case, applied where the base rate is inverted.
-      // `private: true` means "declared dark, no grants" — it contradicts a recorded
-      // grant, and the model refuses the pair. A relation whose only reach is recorded
-      // (PUBLIC SELECT, or a write grant) is not dark; it just has no CHOSEN audience.
-      if (abilities.length === 0 && !hasPrivileges) props.push('private: true,');
-      else if (abilities.length) {
-        props.push(`abilities: [${abilities.join(', ')}],`);
-        need('can');
+      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');
       }
-      if (hasPrivileges) {
-        const entries = Object.keys(privileges).sort()
-          .map((g) => `${tsKey(g)}: [${privileges[g].map(tsString).join(', ')}]`);
-        props.push(`privileges: { ${entries.join(', ')} },`);
+      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',`);
+      // THE PIN IS READ, NEVER INVENTED.
+      //
+      // This used to render `searchPath: ['pg_catalog']` for any definer function whose live
+      // proconfig was empty. A build from those models then applied the invented pin for real, so
+      // functions that had always resolved `public` stopped resolving it — sign-up and password
+      // change died on a database built from the consumer's own models, with every gate green.
+      // 34 of their 34 pinned-in-the-model functions were unpinned in the database.
+      //
+      // A live pin renders as the array. No live pin on a definer function renders the explicit
+      // `'unpinned'` sentinel — an ANSWER, not silence, so `defineFunction` still throws for the
+      // author who simply forgot. No live pin on an invoker function renders nothing, which
+      // already means exactly that.
+      if (f.searchPath) {
+        const searchPathParts = f.searchPath.split(',').map((s) => s.trim().replace(/^"|"$/g, '')).filter(Boolean);
+        props.push(`searchPath: [${searchPathParts.map(tsString).join(', ')}],`);
+      } else if (f.secdef) {
+        props.push(`searchPath: 'unpinned',`);
       }
-      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',`);
+      // Ownership sits beside security because it IS the other half of it: `security: 'definer'`
+      // says the function runs as its owner, and this says who that is.
+      if (ownership.prop) props.push(ownership.prop);
+      if (ownership.fixme) fixmes.push(ownership.fixme);
+      if (ownership.warning) warnings.push(ownership.warning);
+      if (roleGrants.length) {
+        props.push(`abilities: [${roleGrants.map((r) => `can('execute', { role: ${tsString(r)} })`).join(', ')}],`);
+        need('can');
       }
+      // A live PUBLIC EXECUTE is RECORDED, not converted into an ability. Rendering it as
+      // can('execute', { role: … }) would invent an audience the database never named, and
+      // dropping it silently would make the descriptor plan a REVOKE on adoption. Both are
+      // the adopter's database being changed to suit our vocabulary.
+      if (publicExec) props.push(`privileges: { PUBLIC: ['EXECUTE'] },`);
+      if (refs.length) props.push(`dependsOn: [${refs.join(', ')}],`);
       if (o.comment) props.push(`comment: ${tsString(o.comment)},`);
-      props.push(`as: sql\`${tsTemplate(o.definition.trim().replace(/;$/, ''))}\`,`);
-      need(o.kind === 'view' ? 'defineView' : 'defineMaterializedView');
+      props.push(`body: sql\`${tsTemplate(f.src.trim())}\`,`);
+      need('defineFunction');
       need('sql');
       lines.push(
         ...fixmes,
-        `export const ${varName} = ${o.kind === 'view' ? 'defineView' : 'defineMaterializedView'}(${tsString(declaredName(o))}, {`,
+        // Not a FIXME any more — `privileges: { PUBLIC: ['EXECUTE'] }` above says it, and
+        // adopting the descriptor no longer applies a revoke. It is still worth a look on a
+        // SECURITY DEFINER function, which is what db:check now WARNs about.
+        ...(publicExec && f.secdef
+          ? [`// NOTE: ${o.identity} is SECURITY DEFINER and live-granted EXECUTE to PUBLIC — recorded, not chosen. Narrow it to can('execute', { role }) once you know the intended callers.`]
+          : []),
+        `export const ${varName} = defineFunction(${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;
-    const ownership = renderedFunctionOwner(o, f?.secdef === true);
-
-    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})` : '');
-      // A defineSql object cannot carry an owner. Where the pull observed a CHOSEN owner that
-      // is real fidelity loss, so it is said out loud on both surfaces — never dropped. An
-      // ambient owner needs no note here: there is nothing to declare and nothing was lost.
-      if (ownership.prop) {
-        const why = `${o.identity}: owned by '${o.owner}', but defineSql cannot declare an owner — the build will create it as the connecting role. Move it into defineFunction's vocabulary, or set the owner by hand after the build.`;
-        warnings.push(why);
-        lines.push(`// FIXME: ${why}`);
-      }
-      lines.push(
-        `// FIXME: ${o.identity} — signature beyond defineFunction's v1 vocabulary; kept verbatim as defineSql.`,
-        `export const ${varName} = defineSql(${tsString(sqlName)}, {`,
-        `  kind: 'function',`,
-        `  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(/;$/, ''))}\`,`,
-        '});',
-        '',
-      );
-      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',`);
-    // THE PIN IS READ, NEVER INVENTED.
-    //
-    // This used to render `searchPath: ['pg_catalog']` for any definer function whose live
-    // proconfig was empty. A build from those models then applied the invented pin for real, so
-    // functions that had always resolved `public` stopped resolving it — sign-up and password
-    // change died on a database built from the consumer's own models, with every gate green.
-    // 34 of their 34 pinned-in-the-model functions were unpinned in the database.
-    //
-    // A live pin renders as the array. No live pin on a definer function renders the explicit
-    // `'unpinned'` sentinel — an ANSWER, not silence, so `defineFunction` still throws for the
-    // author who simply forgot. No live pin on an invoker function renders nothing, which
-    // already means exactly that.
-    if (f.searchPath) {
-      const path = f.searchPath.split(',').map((s) => s.trim().replace(/^"|"$/g, '')).filter(Boolean);
-      props.push(`searchPath: [${path.map(tsString).join(', ')}],`);
-    } else if (f.secdef) {
-      props.push(`searchPath: 'unpinned',`);
-    }
-    // Ownership sits beside security because it IS the other half of it: `security: 'definer'`
-    // says the function runs as its owner, and this says who that is.
-    if (ownership.prop) props.push(ownership.prop);
-    if (ownership.fixme) fixmes.push(ownership.fixme);
-    if (ownership.warning) warnings.push(ownership.warning);
-    if (roleGrants.length) {
-      props.push(`abilities: [${roleGrants.map((r) => `can('execute', { role: ${tsString(r)} })`).join(', ')}],`);
-      need('can');
+    } finally {
+      records.push({
+        identity: o.identity,
+        varName,
+        kind: o.kind,
+        schema: o.schema,
+        lines: lines.slice(linesStart),
+        modelRefs: recordRefs.model,
+        derivedRefs: recordRefs.derived,
+      });
     }
-    // A live PUBLIC EXECUTE is RECORDED, not converted into an ability. Rendering it as
-    // can('execute', { role: … }) would invent an audience the database never named, and
-    // dropping it silently would make the descriptor plan a REVOKE on adoption. Both are
-    // the adopter's database being changed to suit our vocabulary.
-    if (publicExec) props.push(`privileges: { PUBLIC: ['EXECUTE'] },`);
-    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,
-      // Not a FIXME any more — `privileges: { PUBLIC: ['EXECUTE'] }` above says it, and
-      // adopting the descriptor no longer applies a revoke. It is still worth a look on a
-      // SECURITY DEFINER function, which is what db:check now WARNs about.
-      ...(publicExec && f.secdef
-        ? [`// NOTE: ${o.identity} is SECURITY DEFINER and live-granted EXECUTE to PUBLIC — recorded, not chosen. Narrow it to can('execute', { role }) once you know the intended callers.`]
-        : []),
-      `export const ${varName} = defineFunction(${tsString(declaredName(o))}, {`,
-      ...props.map((p) => `  ${p}`),
-      '});',
-      '',
-    );
-    names.push(varName);
   }
 
   // -- trigger bindings, last -------------------------------------------------
@@ -765,6 +835,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     // Registered only once the binding actually renders — an import emitted for a skipped
     // trigger would be an unused name in generated code.
     if (modelVar) modelRefs.add(owner);
+    const linesStart = lines.length;
     // A trigger's name collides freely: with its OWN function (`update_users_tsvector` is
     // both, on the reference schema) and with a same-named trigger on another table
     // (trigger names are unique per table, not per schema). Either collision emits two
@@ -794,6 +865,15 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       '',
     );
     names.push(varName);
+    records.push({
+      identity: o.identity,
+      varName,
+      kind: 'trigger',
+      schema: o.schema,
+      lines: lines.slice(linesStart),
+      modelRefs: modelVar ? [owner] : [],
+      derivedRefs: [...(modelVar ? [] : [owner]), `${o.trg.functionIdentity}()`],
+    });
   }
 
   return {
@@ -804,6 +884,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     imports: [...used].sort(),
     modelRefs: [...modelRefs].sort(),
     warnings,
+    records,
   };
 }
 
@@ -845,3 +926,208 @@ export function renderDerivedFile(result: DerivedRenderResult, knownTables: Map<
   }
   return lines.join('\n') + '\n';
 }
+
+export interface RenderedDerivedFile {
+  /** File name relative to the derived directory (`views.ts`, `functions-auth.ts`,
+   *  `triggers.ts`, `index.ts` last). */
+  file: string;
+  source: string;
+}
+
+/** Which split file a record belongs to. Views and matviews (including a --matviews-as-tables
+ *  flip, which is still rendered FROM a view/matview object) share one file — the plan's
+ *  stated shape names only views/functions/triggers, so a matview is a kind of view here.
+ *  Sequences have no file of their own: they carry no refs, so declaring them directly in the
+ *  barrel needs no import wiring — the same reason a single-file pull keeps them inline. */
+function derivedBucket(kind: DerivedRecord['kind'], schema: string): string {
+  if (kind === 'view' || kind === 'materialized view') return 'views';
+  if (kind === 'trigger') return 'triggers';
+  if (kind === 'sequence') return 'index';
+  return `functions-${schema}`;
+}
+
+function derivedBucketFile(bucket: string): string {
+  return `${bucket.replace(/_/g, '-')}.ts`;
+}
+
+/** The `@everystack/model` symbols one split file's own text needs — the same regex-scan
+ *  idiom `importHeader` (model-render.ts) uses per model file, so each split file imports
+ *  only what it actually calls rather than the whole render's global symbol set. */
+function derivedFileSymbols(body: string): string[] {
+  const symbols: string[] = [];
+  const add = (s: string): void => { if (!symbols.includes(s)) symbols.push(s); };
+  if (/\bdefineView\(/.test(body)) add('defineView');
+  if (/\bdefineMaterializedView\(/.test(body)) add('defineMaterializedView');
+  if (/\bdefineMaterializedTable\(/.test(body)) { add('defineMaterializedTable'); add('field'); }
+  if (/\bdefineFunction\(/.test(body)) add('defineFunction');
+  if (/\bdefineSql\(/.test(body)) add('defineSql');
+  if (/\bdefineTrigger\(/.test(body)) add('defineTrigger');
+  if (/\barg\(/.test(body)) add('arg');
+  if (/\bindex\(/.test(body)) add('index');
+  if (/\bcan\(/.test(body)) add('can');
+  if (/\bsql`/.test(body)) add('sql');
+  return symbols.sort();
+}
+
+/**
+ * DFS cycle detection over the split-file dependency graph. Returns the cycle as a list of
+ * bucket names (`a -> b -> a`) or null. Small graph (views/triggers/one-per-schema functions),
+ * so a plain recursive DFS with a color map is plenty — no need for Tarjan here.
+ */
+function findFileCycle(graph: Map<string, Set<string>>): string[] | null {
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map<string, number>();
+  const nodes = new Set<string>([...graph.keys(), ...[...graph.values()].flatMap((s) => [...s])]);
+  for (const n of nodes) color.set(n, WHITE);
+  const stack: string[] = [];
+  const visit = (n: string): string[] | null => {
+    color.set(n, GRAY);
+    stack.push(n);
+    for (const next of graph.get(n) ?? []) {
+      if (color.get(next) === GRAY) return [...stack.slice(stack.indexOf(next)), next];
+      if (color.get(next) === WHITE) {
+        const found = visit(next);
+        if (found) return found;
+      }
+    }
+    stack.pop();
+    color.set(n, BLACK);
+    return null;
+  };
+  for (const n of [...nodes].sort()) {
+    if (color.get(n) === WHITE) {
+      const found = visit(n);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * The `--derived-out <dir>` case: split by kind and schema instead of one monolith — a full
+ * pull otherwise renders a single multi-thousand-line file that killed a consumer's
+ * hand-maintained `derived.ts` once already (docs/derived-objects.md).
+ *
+ * The import graph between split files is the RENDERED-ref graph (dependsOn/execute/on), not
+ * the catalog graph: `pg_depend` cannot see inside a plpgsql body, so most function→function
+ * calls never become an edge here in the first place — the risk this function guards against
+ * is real but narrow (a view's `dependsOn` naming a function, or vice versa). A cycle between
+ * split files is FATAL at import time (the same TDZ `ReferenceError` that kept trigger
+ * bindings off models), so it is detected and refused here, before anything is written —
+ * never shipped as a barrel nobody can import.
+ *
+ * Model imports are resolved against the PARENT of `derivedDir` — the same co-location
+ * convention the single-file `--derived-out db/models/derived.ts` already relies on
+ * (`renderDerivedFile`'s model imports assume the derived file sits beside the model files).
+ * For the directory form that convention becomes: `db/models/derived/` sits inside
+ * `db/models/`, so `path.dirname(derivedDir)` IS the models directory.
+ */
+export function renderDerivedDirectory(
+  result: DerivedRenderResult,
+  knownTables: Map<string, string>,
+  derivedDir: string,
+): RenderedDerivedFile[] {
+  const records = result.records ?? [];
+  const byIdentity = new Map(records.map((r) => [r.identity, r]));
+  const bucketOf = (r: DerivedRecord): string => derivedBucket(r.kind, r.schema);
+
+  // The file-level dependency graph — self-references (same bucket) don't count, and nothing
+  // ever targets 'index' (sequences carry no refs, so nothing resolves TO one).
+  const fileDeps = new Map<string, Set<string>>();
+  for (const r of records) {
+    const from = bucketOf(r);
+    if (from === 'index') continue;
+    for (const ref of r.derivedRefs) {
+      const target = byIdentity.get(ref);
+      if (!target) continue;
+      const to = bucketOf(target);
+      if (to === from) continue;
+      if (!fileDeps.has(from)) fileDeps.set(from, new Set());
+      fileDeps.get(from)!.add(to);
+    }
+  }
+  const cycle = findFileCycle(fileDeps);
+  if (cycle) {
+    throw new Error(
+      `--derived-out <dir>: ${cycle.map(derivedBucketFile).join(' -> ')} would import each other — a cycle ` +
+      'between descriptor modules is fatal at import time (TDZ). Use --derived-out <file.ts> for this schema instead.',
+    );
+  }
+
+  const buckets = new Map<string, DerivedRecord[]>();
+  for (const r of records) {
+    const b = bucketOf(r);
+    if (!buckets.has(b)) buckets.set(b, []);
+    buckets.get(b)!.push(r);
+  }
+
+  const modelsDir = path.dirname(derivedDir);
+  const modelImportFor = (table: string): string => {
+    const target = path.join(modelsDir, modelFileName(table)).replace(/\.ts$/, '');
+    const rel = path.relative(derivedDir, target).split(path.sep).join('/');
+    return rel.startsWith('.') ? rel : `./${rel}`;
+  };
+
+  const files: RenderedDerivedFile[] = [];
+  const contentBuckets = [...buckets.keys()].filter((b) => b !== 'index').sort();
+  for (const bucket of contentBuckets) {
+    const recs = buckets.get(bucket)!;
+    const body = recs.map((r) => r.lines.join('\n')).join('\n');
+    const modelTables = [...new Set(recs.flatMap((r) => r.modelRefs))].sort();
+    const modelImports = modelTables.map((t) => `import { ${knownTables.get(t)!} } from '${modelImportFor(t)}';`);
+    // Cross-file derived imports, grouped by the OTHER bucket they come from.
+    const crossVarsByBucket = new Map<string, Set<string>>();
+    for (const r of recs) {
+      for (const ref of r.derivedRefs) {
+        const target = byIdentity.get(ref);
+        if (!target) continue;
+        const tb = bucketOf(target);
+        if (tb === bucket || tb === 'index') continue;
+        if (!crossVarsByBucket.has(tb)) crossVarsByBucket.set(tb, new Set());
+        crossVarsByBucket.get(tb)!.add(target.varName);
+      }
+    }
+    const crossImports = [...crossVarsByBucket.keys()].sort().map((tb) =>
+      `import { ${[...crossVarsByBucket.get(tb)!].sort().join(', ')} } from './${derivedBucketFile(tb).replace(/\.ts$/, '')}';`);
+    const symbols = derivedFileSymbols(body);
+    const header = [
+      ...(symbols.length ? [`import { ${symbols.join(', ')} } from '@everystack/model';`] : []),
+      ...modelImports,
+      ...crossImports,
+    ].join('\n');
+    files.push({ file: derivedBucketFile(bucket), source: `${header ? header + '\n\n' : ''}${body}\n` });
+  }
+
+  // index.ts — the derived barrel. Sequences declare INLINE (they carry no refs, so nothing
+  // to import for them); everything else is imported from its split file purely to re-export
+  // through `sequences`/`materializedTables`/`derived`, exactly what renderDerivedFile exports
+  // for the single-file case.
+  const seqRecords = buckets.get('index') ?? [];
+  const indexLines: string[] = [
+    '// Derived layer barrel (views, functions, triggers, sequences) — rendered by',
+    '// `everystack db:pull --derived-out <dir>`. Bodies are the catalog\'s canonical deparse (they',
+    '// never match an authored spelling byte-for-byte); commit, wire this directory on your',
+    '// module — defineModule({ models, sequences, derived }) — then adopt with',
+    '// `db:reconcile --apply --baseline` (or --rebaseline over db/sql-era provenance).',
+    '// docs/derived-objects.md.',
+  ];
+  if (seqRecords.length) indexLines.push(`import { defineSequence } from '@everystack/model';`);
+  for (const bucket of contentBuckets) {
+    const vars = buckets.get(bucket)!.map((r) => r.varName);
+    if (vars.length) indexLines.push(`import { ${vars.join(', ')} } from './${derivedBucketFile(bucket).replace(/\.ts$/, '')}';`);
+  }
+  indexLines.push('');
+  for (const r of seqRecords) indexLines.push(...r.lines, '');
+  if (result.sequenceNames.length) {
+    indexLines.push(`export const sequences = [\n${result.sequenceNames.map((n) => `  ${n},`).join('\n')}\n];`);
+  }
+  if (result.materializedTableNames.length) {
+    indexLines.push(`export const materializedTables = [\n${result.materializedTableNames.map((n) => `  ${n},`).join('\n')}\n];`);
+  }
+  if (result.names.length) {
+    indexLines.push(`export const derived = [\n${result.names.map((n) => `  ${n},`).join('\n')}\n];`);
+  }
+  files.push({ file: 'index.ts', source: indexLines.join('\n') + '\n' });
+
+  return files;
+}