@everystack/cli 0.3.31 → 0.4.1

package/src/cli/derived-render.ts

@@ -0,0 +1,366 @@
+/**
+ * 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';
+import { modelFileName } from './model-render.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[];
+  /** Qualified tables the block references through knownTables — what a standalone
+   *  derived file must import (sorted). */
+  modelRefs: 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_$]*$/;
+
+/**
+ * Derived symbols are camelCase VERBATIM — never singularized (deliberately distinct
+ * from modelVarName's rule; a matview named `nfl_player_honors` is `nflPlayerHonors`).
+ * NAMING CONTRACT — a rename here breaks consumer splices; pinned by
+ * naming-contract.test.ts.
+ */
+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 modelRefs = new Set<string>();
+  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);
+        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.`);
+    }
+    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(),
+    modelRefs: [...modelRefs].sort(),
+    warnings,
+  };
+}
+
+/**
+ * The standalone derived module — `db:pull --derived-out <file>` (the brownfield
+ * splice, first-class). A consumer with an existing hand-maintained barrel wants the
+ * derived layer as its OWN file, not spliced out of a rendered monolith by hand: this
+ * renders exactly the shape their module wires — model-package imports, model-var
+ * imports from the contract kebab files (naming-contract.test.ts), the descriptors,
+ * and the `sequences`/`derived` arrays for `defineModule({ models, sequences, derived })`.
+ */
+export function renderDerivedFile(result: DerivedRenderResult, knownTables: Map<string, string>): string {
+  const lines: string[] = [
+    '// Derived layer (views, materialized views, functions, sequences) — rendered by `everystack db:pull`.',
+    '// Bodies are the catalog\'s canonical deparse (they never match an authored spelling byte-for-byte);',
+    '// commit, wire it 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 (result.imports.length) {
+    lines.push(`import { ${result.imports.join(', ')} } from '@everystack/model';`);
+  }
+  const refs = result.modelRefs
+    .map((table) => ({ varName: knownTables.get(table)!, path: `./${modelFileName(table).replace(/\.ts$/, '')}` }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  for (const ref of refs) lines.push(`import { ${ref.varName} } from '${ref.path}';`);
+  lines.push('', result.block, '');
+  if (result.sequenceNames.length) {
+    lines.push(`export const sequences = [\n${result.sequenceNames.map((n) => `  ${n},`).join('\n')}\n];`);
+  }
+  if (result.names.length) {
+    lines.push(`export const derived = [\n${result.names.map((n) => `  ${n},`).join('\n')}\n];`);
+  }
+  return lines.join('\n') + '\n';
+}

package/src/cli/derived-source.ts

@@ -1,26 +1,32 @@
 /**
  * derived-source — the source side of the derived-object reconciler.
  *
- * Parses an app's ordered db/sql files into structured derived objects
- * (functions, views, materialized views), attaching the statements that ride
- * with an object (its indexes, comments, grants) and hashing each object's
- * normalized content. The reconciler diffs these hashes against the live
- * catalog's provenance to decide what to create, replace, or drop.
+ * The `SourceObject` shape every derived declaration compiles to (identity,
+ * content hash, attachments), plus the SQL infrastructure shared across the
+ * reconciler: the Postgres-aware lexer, statement splitting, hash
+ * normalization, and qualified-name parsing.
+ *
+ * History note: this file once parsed an app's raw `db/sql` files into these
+ * shapes. That parser is retired (B7, read-model-everywhere) — descriptors
+ * (defineView / defineMaterializedView / defineFunction / defineSql, compiled
+ * by derived-compile.ts) are the single home. The content-hash formula is
+ * unchanged, so provenance recorded from db/sql-era objects still matches the
+ * descriptor-compiled hash of the same SQL — the migration reconciles as a
+ * no-op, never a rebuild.
  *
  * Everything here is pure and database-free. The lexer respects Postgres
  * string syntax — single quotes with '' doubling, E-strings with backslash
  * escapes, double-quoted identifiers, tagged dollar quoting, and nested block
  * comments — because a matview body is exactly where naive splitting dies.
- *
- * Identity note: functions are identified by schema-qualified NAME, not full
- * signature. Overloads are rare in app SQL layers; when they appear we warn
- * rather than mis-model them (the honest limitation, revisit if a consumer
- * actually needs overloads).
  */
 
 import { createHash } from 'node:crypto';
 
-export type DerivedKind = 'function' | 'view' | 'materialized view';
+/**
+ * `'trigger'` and `'sql'` carry the extra fields the reconciler edges need (a trigger's
+ * table for `DROP TRIGGER … ON`, a defineSql object's explicit drop).
+ */
+export type DerivedKind = 'function' | 'view' | 'materialized view' | 'trigger' | 'sql';
 
 /** A statement that belongs to an object: its index, comment, or grant. */
 export interface Attachment {
@@ -33,7 +39,8 @@ export interface SourceObject {
   /** Schema name, defaulted to `public` when unqualified. */
   schema: string;
   name: string;
-  /** `schema.name` — the reconciler's join key against the live catalog. */
+  /** `schema.name` — the reconciler's join key against the live catalog.
+   *  (Triggers: `schema.table.name` — compound identity, joined against pg_trigger.) */
   identity: string;
   /** The CREATE statement as authored (no trailing semicolon). */
   sql: string;
@@ -41,17 +48,46 @@ export interface SourceObject {
   attachments: Attachment[];
   /** sha256 of the normalized CREATE + attachments — comment/whitespace edits do not change it. */
   hash: string;
-  /** Source file this object came from. */
+  /** Source file this object came from (descriptors: the declared-models marker). */
   file: string;
   /** Position in the concatenated source — a valid dependency order by convention. */
   seq: number;
+  /** kind 'sql' only: the declared PostgreSQL object kind (`'aggregate'`, …). */
+  objectKind?: string;
+  /** kind 'sql' only: the explicit DROP for kinds whose drop isn't derivable from the name. */
+  drop?: string;
+  /** kind 'trigger' only: the (possibly schema-qualified) table/view the trigger rides. */
+  table?: string;
+  /**
+   * Views/matviews: every declared `dependsOn` ref as an identity (models AND derived),
+   * sorted. B4's dependency drift verifies it against the live catalog's actual edges —
+   * "declared, then verified". Absent on kinds whose live edges pg_depend can't see.
+   */
+  declaredDeps?: string[];
+}
+
+/** The provenance marker descriptor-compiled objects carry in `file` — the compiler
+ *  ALWAYS declares authz (a private relation is declared-empty, not undeclared), so
+ *  B4's grant drift checks every object. */
+export const DECLARED_SOURCE_FILE = 'db/models (declared)';
+
+/** The one content-hash formula. Unchanged since the db/sql era on purpose: provenance
+ *  recorded from parser-era objects still matches the descriptor-compiled hash of the
+ *  same SQL, so the db/sql → descriptor migration reconciles as a no-op. */
+export function hashSourceContent(createSql: string, attachments: Attachment[]): string {
+  const content = [normalizeSql(createSql), ...attachments.map((a) => normalizeSql(a.sql))].join('\n');
+  return createHash('sha256').update(content).digest('hex');
 }
 
+/** A raw file the generic dir readers return (db/backfills, seed lanes). */
 export interface SourceFile {
   file: string;
   sql: string;
 }
 
+/** The reconciler's source-stream input: the declared objects plus any compile-time
+ *  warnings to surface with the plan. (Named for its parser-era producer; the only
+ *  producer now is the descriptor compiler.) */
 export interface ParsedSources {
   objects: SourceObject[];
   /** Statements the reconciler does not manage — surfaced, never silently dropped. */
@@ -242,7 +278,7 @@ export function normalizeSql(sql: string): string {
 // ---------------------------------------------------------------------------
 
 /** Strip quotes from an identifier and split an optionally schema-qualified name. */
-function parseQualified(raw: string): { schema: string; name: string } {
+export function parseQualified(raw: string): { schema: string; name: string } {
   const parts: string[] = [];
   let current = '';
   let quoted = false;
@@ -261,114 +297,6 @@ function parseQualified(raw: string): { schema: string; name: string } {
   return { schema: 'public', name: parts[0] };
 }
 
-const FUNCTION_RE = /^CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+((?:"[^"]*"|[^\s(])+)\s*\(/i;
-const VIEW_RE = /^CREATE\s+(?:OR\s+REPLACE\s+)?VIEW\s+((?:"[^"]*"|[^\s(])+)/i;
-const MATVIEW_RE = /^CREATE\s+MATERIALIZED\s+VIEW\s+(?:IF\s+NOT\s+EXISTS\s+)?((?:"[^"]*"|[^\s(])+)/i;
-const INDEX_RE = /^CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?(?:(?:"[^"]*"|[^\s(])+\s+)?ON\s+(?:ONLY\s+)?((?:"[^"]*"|[^\s(])+)/i;
-const COMMENT_RE = /^COMMENT\s+ON\s+(MATERIALIZED\s+VIEW|VIEW|FUNCTION|COLUMN)\s+((?:"[^"]*"|[^\s(,])+)/i;
-const GRANT_RE = /^GRANT\s+[\s\S]*?\bON\s+(?:TABLE\s+)?((?:"[^"]*"|[^\s(,])+)/i;
-
-/**
- * The first non-comment text of a statement, whitespace collapsed but token
- * boundaries preserved (unlike the aggressive hash form — `VIEW "MyView"` must
- * keep its space for the classification regexes).
- */
-function statementHead(statement: string): string {
-  let out = '';
-  lex(statement, (ch, state) => {
-    if (state === 'line-comment' || state === 'block-comment') return;
-    if (state === 'normal' && /\s/.test(ch)) {
-      if (out.length > 0 && !out.endsWith(' ')) out += ' ';
-      return;
-    }
-    out += ch;
-  });
-  return out.trim().slice(0, 400);
-}
-
-/**
- * Parse ordered source files into derived objects. Attachments (indexes,
- * comments, grants) join the object they target; statements that are neither a
- * derived object nor an attachment become warnings — the reconciler manages
- * the derived layer only, and it says so out loud.
- */
-export function parseSqlSources(files: SourceFile[]): ParsedSources {
-  const objects: SourceObject[] = [];
-  const warnings: string[] = [];
-  const byIdentity = new Map<string, SourceObject>();
-  let seq = 0;
-
-  const identityOf = (raw: string): { schema: string; name: string; identity: string } => {
-    const { schema, name } = parseQualified(raw);
-    return { schema, name, identity: `${schema}.${name}` };
-  };
-
-  for (const { file, sql } of files) {
-    for (const statement of splitSqlStatements(sql)) {
-      const head = statementHead(statement);
-
-      const asObject = (kind: DerivedKind, rawName: string): void => {
-        const { schema, name, identity } = identityOf(rawName);
-        if (byIdentity.has(identity)) {
-          warnings.push(
-            `${file}: duplicate definition for ${identity} — function overloads are not modeled; ` +
-            `the reconciler tracks one definition per name (last one wins).`,
-          );
-        }
-        const obj: SourceObject = {
-          kind, schema, name, identity,
-          sql: statement, attachments: [], hash: '', file, seq: seq++,
-        };
-        byIdentity.set(identity, obj);
-        objects.push(obj);
-      };
-
-      const attach = (kind: Attachment['kind'], rawTarget: string, stripColumn = false): boolean => {
-        let { identity } = identityOf(rawTarget);
-        if (stripColumn) {
-          // COMMENT ON COLUMN schema.obj.col — the owning object is one segment up.
-          const parts = identity.split('.');
-          identity = parts.length > 2 ? parts.slice(0, -1).join('.') : `public.${parts[0]}`;
-        }
-        const target = byIdentity.get(identity);
-        if (!target) return false;
-        target.attachments.push({ kind, sql: statement });
-        return true;
-      };
-
-      let m: RegExpExecArray | null;
-      if ((m = FUNCTION_RE.exec(head))) { asObject('function', m[1]); continue; }
-      if ((m = MATVIEW_RE.exec(head))) { asObject('materialized view', m[1]); continue; }
-      if ((m = VIEW_RE.exec(head))) { asObject('view', m[1]); continue; }
-
-      if ((m = INDEX_RE.exec(head))) {
-        if (!attach('index', m[1])) {
-          warnings.push(`${file}: CREATE INDEX targets ${m[1]}, which is not a derived object in these sources — not managed here (base-table indexes belong to the model layer).`);
-        }
-        continue;
-      }
-      if ((m = COMMENT_RE.exec(head))) {
-        const isColumn = /^COLUMN$/i.test(m[1].replace(/\s+/g, ' ').split(' ')[0]) || /^COLUMN/i.test(m[1]);
-        if (!attach('comment', m[2], isColumn)) {
-          warnings.push(`${file}: COMMENT ON targets ${m[2]}, which is not a derived object in these sources.`);
-        }
-        continue;
-      }
-      if ((m = GRANT_RE.exec(head))) {
-        if (!attach('grant', m[1])) {
-          warnings.push(`${file}: GRANT targets ${m[1]}, which is not a derived object in these sources.`);
-        }
-        continue;
-      }
-
-      warnings.push(`${file}: unmanaged statement (${head.slice(0, 60)}…) — the reconciler manages functions, views, and materialized views; move this to the appropriate layer.`);
-    }
-  }
-
-  for (const obj of objects) {
-    const content = [normalizeSql(obj.sql), ...obj.attachments.map((a) => normalizeSql(a.sql))].join('\n');
-    obj.hash = createHash('sha256').update(content).digest('hex');
-  }
-
-  return { objects, warnings };
-}
+// (The db/sql statement classifier and parseSqlSources lived here until B7 —
+// descriptors are the single home; declared-derived.ts's retiredSqlDir() is the
+// loud tombstone for checkouts still carrying the directory.)

package/src/cli/edge-plan.ts

@@ -29,7 +29,7 @@ import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
 import { generateMigrationSql, unmodeledTables } from './migration-generate.js';
-import { classifyGeneratedStatements, classifyDestructive } from './state-apply.js';
+import { classifyGeneratedStatements, classifyDestructive, renderStatementHistogram } from './state-apply.js';
 import { fingerprintLive, fingerprintState, fingerprintModels, stableStringify } from './schema-fingerprint.js';
 import { compileDeclaredState } from './declared-diff.js';
 import { compileTableRenames } from './schema-compile.js';
@@ -202,6 +202,9 @@ export function buildPlanSummary(plan: EdgePlan): string[] {
     return lines;
   }
   lines.push(`${plan.executable} executable statement(s), ${plan.notices} notice(s)`);
+  // The shape first — a four-digit edge is reviewable as a histogram, not a wall.
+  const histogram = renderStatementHistogram(classifyGeneratedStatements(plan.statements).executable);
+  if (histogram) lines.push(`shape: ${histogram}`);
   if (plan.destructive > 0) {
     const { drops, narrowings } = classifyDestructive(classifyGeneratedStatements(plan.statements).executable);
     lines.push(

package/src/cli/git-descent.ts

@@ -188,10 +188,23 @@ export async function verifyDescent(
     for (const candidate of candidates) {
       const dest = path.join(materializeRoot, candidate.tree);
       let predicted: string;
-      try {
+      // A swallowed error here skips the candidate — and if it was the DECLARING tree, the
+      // verdict silently falls through to 'drift'. Real compile failures are deterministic;
+      // a transient materialize/import failure (fd pressure, module-loader contention under
+      // a parallel test run or a busy CI box) is not — so a failed candidate gets exactly
+      // one retry, from a clean materialization, before it is recorded as a compile failure.
+      const attempt = async (): Promise<string> => {
         if (!fs.existsSync(dest)) materializeTree(candidate.tree, dest, repoRoot);
         const models = await loader(path.join(dest, barrel));
-        predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema });
+        return predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema });
+      };
+      try {
+        try {
+          predicted = await attempt();
+        } catch {
+          fs.rmSync(dest, { recursive: true, force: true });
+          predicted = await attempt();
+        }
       } catch (err: any) {
         compileFailures.push(`${short(candidate.tree)} (at ${short(candidate.commits[0])}): ${err.message}`);
         continue;