@everystack/cli 0.3.31 → 0.4.0

package/src/cli/db-source.ts

@@ -83,7 +83,11 @@ export async function createUrlRunner(
     );
   }
   const postgres = mod.default ?? mod;
-  const sql = postgres(url, { max: 1, onnotice: () => {}, ...sslDefaults(url) });
+  // max_lifetime: null — the driver's default recycles a connection after a random 30–60
+  // minutes, resolving the in-flight query and THEN killing the session. Under reconcile's
+  // BEGIN-across-calls transaction that is a silent session swap mid-batch (the reconcile
+  // apply path also pins the backend pid and refuses bookkeeping if it moved).
+  const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => {}, ...sslDefaults(url) });
   return {
     runner: async (query: string) => Array.from(await sql.unsafe(query)),
     end: () => sql.end({ timeout: 5 }),

package/src/cli/declared-derived.ts

@@ -0,0 +1,136 @@
+/**
+ * The declared-DB loader — one call that turns the models barrel into everything the
+ * verbs consume beyond the models themselves: the descriptor-compiled derived layer
+ * (views/matviews/functions/triggers/escape-hatch objects, topologically ordered), the
+ * standalone sequences (state), and the pending table renames (so trigger provenance
+ * migrates instead of drop+create-ing). This is the B3 seam: the same loader feeds
+ * db:reconcile, db:sync, db:check, and db:generate — descriptors are live everywhere
+ * or nowhere.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import type { Module, SequenceDescriptor, DerivedDescriptor } from '@everystack/model';
+import { compileDerived } from './derived-compile.js';
+import { compileTableRenames } from './schema-compile.js';
+import type { SourceObject } from './derived-source.js';
+import { resolveModelsPath } from './models-path.js';
+
+export interface DeclaredDerived {
+  /** Descriptor-compiled derived objects, in dependency order. */
+  objects: SourceObject[];
+  /** The raw descriptors — the B2 gates (db:check) read abilities, not compiled SQL. */
+  derived: DerivedDescriptor[];
+  /** Standalone sequences (state layer — created before tables, fingerprinted). */
+  sequences: SequenceDescriptor[];
+  /** Pending table renames (`new qualified` → `old qualified`) from the models' markers. */
+  renamedTables: Record<string, string>;
+}
+
+/** Barrel → normalized Module list (a bare `models` export wraps into one module). */
+export async function loadModulesFrom(modelsPath: string): Promise<Module[]> {
+  const abs = path.resolve(modelsPath);
+  let mod: any;
+  try {
+    mod = await import(pathToFileURL(abs).href);
+  } catch (err: any) {
+    throw new Error(`Could not load modules from ${modelsPath}: ${err.message}`);
+  }
+  if (Array.isArray(mod.modules)) return mod.modules;
+  const models = mod.models ?? mod.default;
+  if (Array.isArray(models)) return [{ models, extensions: [], sequences: [], derived: [], functions: [] }];
+  throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
+}
+
+/**
+ * B7 — db/sql is RETIRED; descriptors are the single home. A project still carrying
+ * `.sql` files in db/sql gets this message from every verb that used to read the
+ * directory: a hard failure carrying the migration path, never a silent skip (silence
+ * would leave those objects unmanaged and, later, honestly-dropped). An empty leftover
+ * directory or non-.sql stragglers are harmless — only actual `.sql` files trip it.
+ */
+export async function retiredSqlDir(dir: string = 'db/sql'): Promise<string | null> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(path.resolve(dir));
+  } catch (err: any) {
+    // A missing directory has nothing to say. Anything else (EACCES, EIO) must NOT
+    // silently disarm the tombstone — an unreadable db/sql could still hold live sources.
+    if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') return null;
+    throw new Error(`could not inspect ${dir} for retired db/sql sources: ${err?.message ?? err}`);
+  }
+  const files = entries.filter((f) => f.endsWith('.sql')).sort();
+  if (files.length === 0) return null;
+  return (
+    `${dir} is retired — the derived layer is DECLARED as descriptors, and this directory is no longer read. ` +
+    `${files.length} file(s) still present: ${files.join(', ')}. ` +
+    `Migrate: declare each object with defineView / defineMaterializedView / defineFunction / defineSql on your module ` +
+    `(or run \`everystack db:pull\` against the live database to render them), delete this directory, commit, then run ` +
+    `\`db:reconcile --apply --rebaseline\` once — it verifies each live object is untouched since the last reconcile ` +
+    `and re-records the re-rendered source, no rebuild (objects the reconciler never touched want --baseline instead; ` +
+    `the flags compose). See docs/derived-objects.md.`
+  );
+}
+
+/**
+ * The detector, anchored to BOTH homes a checkout can carry: the CWD's `db/sql` (the
+ * classic layout) and the resolved models home's sibling `sql/` directory (monorepos
+ * running verbs from the repo root with `--models apps/x/db/models/index.ts` — the
+ * red-team's CWD-anchoring finding). First message wins; probes are deduped.
+ */
+export async function retiredSqlDirAnywhere(modelsFlag?: string): Promise<string | null> {
+  const probes = new Map<string, string>(); // resolved → display
+  const add = (dir: string): void => { probes.set(path.resolve(dir), dir); };
+  add('db/sql');
+  add(path.join(path.dirname(path.dirname(resolveModelsPath(modelsFlag))), 'sql'));
+  for (const dir of probes.values()) {
+    const message = await retiredSqlDir(dir);
+    if (message) return message;
+  }
+  return null;
+}
+
+/**
+ * The `--sql-dir` refusal — never a dead end. The flag is retired, but the directory it
+ * points at may still hold live db/sql-era sources the default probes would never see;
+ * the refusal carries THAT directory's state and migration path, so dropping the flag
+ * doesn't strand the files (the red-team's dead-end-refusal finding).
+ */
+export async function retiredSqlDirFlagRefusal(sqlDirFlag: string): Promise<string> {
+  const head =
+    '--sql-dir is retired — the derived layer is DECLARED as descriptors ' +
+    '(defineView/defineMaterializedView/defineFunction/defineSql on your module) and no raw-SQL directory is read. Remove the flag.';
+  let theirs: string | null;
+  try {
+    theirs = await retiredSqlDir(sqlDirFlag);
+  } catch (err: any) {
+    return `${head}\n${err?.message ?? err}`;
+  }
+  return theirs
+    ? `${head}\n${theirs}`
+    : `${head} (${sqlDirFlag} carries no .sql files — nothing left to migrate.)`;
+}
+
+/**
+ * Load the declared derived layer + sequences + renames from the models barrel.
+ * Returns null when no barrel exists (a models-less V1 project) — the verbs then
+ * run with no derived layer at all.
+ */
+export async function loadDeclaredDerived(modelsFlag?: string): Promise<DeclaredDerived | null> {
+  const modelsPath = resolveModelsPath(modelsFlag);
+  try {
+    await fs.access(path.resolve(modelsPath));
+  } catch {
+    return null;
+  }
+  const modules = await loadModulesFrom(modelsPath);
+  const models = modules.flatMap((m) => m.models);
+  const derived = modules.flatMap((m) => m.derived);
+  return {
+    objects: compileDerived(models, derived),
+    derived,
+    sequences: modules.flatMap((m) => m.sequences),
+    renamedTables: compileTableRenames(models, {}),
+  };
+}

package/src/cli/derived-apply.ts

@@ -34,6 +34,12 @@ export const ENSURE_RECONCILER_SQL: string[] = [
   def_hash text NOT NULL,
   applied_at timestamptz NOT NULL DEFAULT now()
 )`,
+  // Provenance records how to REMOVE what it recorded (the C1 closure): a 'sql'-kind
+  // object never joins the live catalog, so its recorded drop_sql is the only way a
+  // removal can drop it instead of silently orphaning it. Idempotent — legacy
+  // databases upgrade in place; their old rows (relations/functions) never need these.
+  `ALTER TABLE everystack.derived_provenance ADD COLUMN IF NOT EXISTS kind text`,
+  `ALTER TABLE everystack.derived_provenance ADD COLUMN IF NOT EXISTS drop_sql text`,
   `CREATE TABLE IF NOT EXISTS everystack.schema_log (
   id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
   applied_at timestamptz NOT NULL DEFAULT now(),
@@ -56,6 +62,15 @@ export interface RenderedReconcile {
   record: string[];
   /** Identities whose provenance rows must be deleted (drops + prunes). */
   remove: string[];
+  /** Provenance identity migrations (a table rename carried its triggers — same object, new identity). */
+  migrate: Array<{ from: string; to: string }>;
+}
+
+/** The structural trigger drop — `DROP TRIGGER … ON <table>`, never derivable from a
+ *  plain identity (the red-team's C4). Shared by the plan (drop actions) and the
+ *  command (recording drop_sql at provenance time). */
+export function triggerDropSql(name: string, table: string): string {
+  return `DROP TRIGGER IF EXISTS "${name}" ON ${table}`;
 }
 
 const DROP_KEYWORD: Record<string, string> = {
@@ -96,7 +111,10 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]):
   for (const action of plan.actions) {
     switch (action.action) {
       case 'drop': {
-        statements.push(`DROP ${DROP_KEYWORD[action.kind]} IF EXISTS ${quoteQualified(action.identity)}`);
+        // The new kinds carry their drop on the action (triggers: composed from structure;
+        // 'sql' objects: the recorded/declared drop_sql) — the legacy kinds keep the
+        // keyword rendering they always had.
+        statements.push(action.dropSql ?? `DROP ${DROP_KEYWORD[action.kind]} IF EXISTS ${quoteQualified(action.identity)}`);
         // A rebuild's drop is followed by its create; only a true removal loses provenance.
         if (!plan.actions.some((a) => a.action === 'create' && a.identity === action.identity)) {
           remove.push(action.identity);
@@ -125,6 +143,12 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]):
         record.push(action.identity);
         break;
       }
+      // A re-render of an untouched live object: no DDL — the upsert re-records the new
+      // source hash against the live def hash the post-batch introspection reads.
+      case 'rebaseline': {
+        record.push(action.identity);
+        break;
+      }
       case 'prune': {
         remove.push(action.identity);
         break;
@@ -132,13 +156,23 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]):
     }
   }
 
-  return { statements, record, remove };
+  // Grant convergence rides the same batch, after every object exists. Idempotent
+  // REVOKE/GRANT — no provenance to record (ACLs are not in any hash).
+  for (const r of plan.regrants) statements.push(...r.statements);
+
+  return { statements, record, remove, migrate: [...plan.migrations] };
+}
+
+export function renderProvenanceUpsert(identity: string, srcHash: string, defHash: string, kind?: string, dropSql?: string): string {
+  return `INSERT INTO everystack.derived_provenance (identity, src_hash, def_hash, kind, drop_sql, applied_at)
+VALUES (${escapeLiteral(identity)}, ${escapeLiteral(srcHash)}, ${escapeLiteral(defHash)}, ${nullable(kind)}, ${nullable(dropSql)}, now())
+ON CONFLICT (identity) DO UPDATE SET src_hash = EXCLUDED.src_hash, def_hash = EXCLUDED.def_hash, kind = EXCLUDED.kind, drop_sql = EXCLUDED.drop_sql, applied_at = now()`;
 }
 
-export function renderProvenanceUpsert(identity: string, srcHash: string, defHash: string): string {
-  return `INSERT INTO everystack.derived_provenance (identity, src_hash, def_hash, applied_at)
-VALUES (${escapeLiteral(identity)}, ${escapeLiteral(srcHash)}, ${escapeLiteral(defHash)}, now())
-ON CONFLICT (identity) DO UPDATE SET src_hash = EXCLUDED.src_hash, def_hash = EXCLUDED.def_hash, applied_at = now()`;
+/** A table rename carried its triggers along — same object, new identity; the provenance
+ *  row migrates instead of the object drop+create-ing. */
+export function renderProvenanceMigrate(from: string, to: string): string {
+  return `UPDATE everystack.derived_provenance SET identity = ${escapeLiteral(to)} WHERE identity = ${escapeLiteral(from)}`;
 }
 
 export function renderProvenanceDelete(identity: string): string {

package/src/cli/derived-compile.ts

@@ -0,0 +1,327 @@
+/**
+ * The descriptor compiler — the declarative derived layer's front-end to the reconciler
+ * (Brick B1b of docs/plans/read-model-everywhere.md).
+ *
+ * defineView / defineMaterializedView / defineFunction / defineSql / trigger() render to
+ * the SAME `SourceObject` shape (and content hash) the retired db/sql parser produced
+ * (`hashSourceContent`) — so an object authored either way is ONE object, and the
+ * db/sql-era → descriptor migration reconciled as a no-op instead of a full rebuild. The
+ * reconciler core (content-hash identity, provenance, cascade, baseline) is reused
+ * untouched; the edges the NEW kinds need (trigger drops, explicit-drop objects) land
+ * with the plan/apply extensions (B1c).
+ *
+ * Ordering is a topological sort over DECLARED `dependsOn` refs (plus the deps that come
+ * free: a trigger's `execute:` function, its declaration-site relation; a function's
+ * `setof(ref)` return). Ties break by identity sort — never by declaration or import
+ * order, so the plan is stable under refactors. Model (table) refs are state-layer:
+ * always created before any compute, so they impose no edge here.
+ */
+
+import type {
+  ModelDescriptor, DerivedDescriptor, ViewDescriptor, MaterializedViewDescriptor,
+  FunctionDescriptor, SqlDescriptor, TriggerSpec, Ability, SetofReturn, DependsOnRef,
+} from '@everystack/model';
+import { hashSourceContent, parseQualified, DECLARED_SOURCE_FILE, type Attachment, type SourceObject } from './derived-source.js';
+import { findInvokerReachabilityGaps } from './derived-lint.js';
+
+/** The provenance marker for descriptor-compiled objects (SourceObject.file). */
+const DECLARED = DECLARED_SOURCE_FILE;
+
+/** `public.x` renders bare (authored style — hash parity with hand-written sources); other schemas qualify. */
+function renderName(schema: string, name: string): string {
+  return schema === 'public' ? name : `${schema}.${name}`;
+}
+
+/** The declared name of a dependable ref, for rendering (`SETOF posts`) and identity. */
+function refName(ref: SetofReturn['setof']): string {
+  if ('table' in ref) return renderName(ref.schema, ref.table);
+  return ref.name;
+}
+
+// ---------------------------------------------------------------------------
+// Grants — the same audience semantics as tables
+// ---------------------------------------------------------------------------
+
+/** Relation read grants: bare read → anon + authenticated (the table precedent);
+ *  `{ role }` narrows; `{ columns }` scopes the SELECT to a column list. */
+function relationGrants(target: string, abilities: readonly Ability[]): Attachment[] {
+  const out: Attachment[] = [];
+  for (const a of abilities) {
+    const roles = a.condition.role ? a.condition.role : 'anon, authenticated';
+    const cols = a.condition.columns?.length
+      ? ` (${a.condition.columns.map((c) => `"${c}"`).join(', ')})`
+      : '';
+    out.push({ kind: 'grant', sql: `GRANT SELECT${cols} ON ${target} TO ${roles}` });
+  }
+  return out;
+}
+
+/** Function authz: `REVOKE ALL … FROM PUBLIC` UNCONDITIONALLY (PostgreSQL grants EXECUTE
+ *  to PUBLIC by default — the silent-open inverse of the RLS trap), then the declared
+ *  `can('execute', { role })` grants. */
+function functionGrants(signature: string, abilities: readonly Ability[]): Attachment[] {
+  const out: Attachment[] = [{ kind: 'grant', sql: `REVOKE ALL ON FUNCTION ${signature} FROM PUBLIC` }];
+  for (const a of abilities) {
+    out.push({ kind: 'grant', sql: `GRANT EXECUTE ON FUNCTION ${signature} TO ${a.condition.role}` });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Renderers — one CREATE (no trailing semicolon) + attachments per descriptor
+// ---------------------------------------------------------------------------
+
+function escapeLiteral(s: string): string {
+  return s.replace(/'/g, "''");
+}
+
+function commentAttachment(kindWord: string, target: string, comment: string | undefined): Attachment[] {
+  return comment ? [{ kind: 'comment', sql: `COMMENT ON ${kindWord} ${target} IS '${escapeLiteral(comment)}'` }] : [];
+}
+
+function renderView(v: ViewDescriptor): { sql: string; attachments: Attachment[] } {
+  const { schema, name } = parseQualified(v.name);
+  const target = renderName(schema, name);
+  // security_invoker only when true — false is PostgreSQL's default, and emitting the
+  // default would break hash parity with hand-authored sources.
+  const invoker = v.securityInvoker ? ' WITH (security_invoker = true)' : '';
+  return {
+    sql: `CREATE VIEW ${target}${invoker} AS\n${v.as}`,
+    attachments: [
+      ...commentAttachment('VIEW', target, v.comment),
+      ...relationGrants(target, v.abilities),
+    ],
+  };
+}
+
+function renderMaterializedView(mv: MaterializedViewDescriptor): { sql: string; attachments: Attachment[] } {
+  const { schema, name } = parseQualified(mv.name);
+  const target = renderName(schema, name);
+  // populate: 'deferred' → WITH NO DATA; the existing rebuild machinery (derived-apply's
+  // objectSql) appends the REFRESH after creation — outside the AS-SELECT populate lock.
+  const noData = mv.populate === 'deferred' ? '\nWITH NO DATA' : '';
+  const indexes: Attachment[] = mv.indexes.map((ix) => {
+    // Same vocabulary and rendering rules as table indexes (Brick E): plain entries
+    // quote, raw entries (expressions/DESC/opclass) pass verbatim, names sanitize.
+    const nameParts = ix.columns.map((c) => c.replace(/\W+/g, '_').replace(/^_+|_+$/g, ''));
+    const idxName = `${name}_${nameParts.join('_')}_index`;
+    const cols = ix.columns
+      .map((c, i) => (ix.rawPositions?.[i] ? c : `"${c}"`))
+      .join(', ');
+    const unique = ix.isUnique ? 'UNIQUE ' : '';
+    const using = ix.method ? ` USING ${ix.method}` : '';
+    const include = ix.includeColumns?.length ? ` INCLUDE (${ix.includeColumns.map((c) => `"${c}"`).join(', ')})` : '';
+    const where = ix.predicate ? ` WHERE ${ix.predicate}` : '';
+    return { kind: 'index', sql: `CREATE ${unique}INDEX ${idxName} ON ${target}${using} (${cols})${include}${where}` };
+  });
+  return {
+    sql: `CREATE MATERIALIZED VIEW ${target} AS\n${mv.as}${noData}`,
+    attachments: [
+      ...indexes,
+      ...commentAttachment('MATERIALIZED VIEW', target, mv.comment),
+      ...relationGrants(target, mv.abilities),
+    ],
+  };
+}
+
+/** A dollar-quote tag the body cannot collide with. */
+function dollarTag(body: string): string {
+  let tag = '$fn$';
+  for (let n = 1; body.includes(tag); n++) tag = `$fn${n}$`;
+  return tag;
+}
+
+/** `name(text, integer)` — the signature GRANT/COMMENT statements reference. */
+function functionSignature(target: string, fn: FunctionDescriptor): string {
+  return `${target}(${fn.args.map((a) => a.type).join(', ')})`;
+}
+
+function renderFunction(fn: FunctionDescriptor): { sql: string; attachments: Attachment[] } {
+  const { schema, name } = parseQualified(fn.name);
+  const target = renderName(schema, name);
+  const args = fn.args
+    .map((a) => `${a.name} ${a.type}${a.default != null ? ` DEFAULT ${a.default}` : ''}`)
+    .join(', ');
+  const returns = typeof fn.returns === 'string' ? fn.returns : `SETOF ${refName(fn.returns.setof)}`;
+  const volatility = fn.volatility === 'volatile' ? '' : ` ${fn.volatility.toUpperCase()}`;
+  const security = fn.security === 'definer'
+    ? ` SECURITY DEFINER SET search_path = ${(fn.searchPath ?? []).join(', ')}`
+    : '';
+  const tag = dollarTag(fn.body);
+  const signature = functionSignature(target, fn);
+  return {
+    sql:
+      `CREATE FUNCTION ${target}(${args})\n` +
+      `RETURNS ${returns}\n` +
+      `LANGUAGE ${fn.language}${volatility}${security}\n` +
+      `AS ${tag}\n${fn.body}\n${tag}`,
+    attachments: [
+      ...commentAttachment('FUNCTION', signature, fn.comment),
+      ...functionGrants(signature, fn.abilities),
+    ],
+  };
+}
+
+const TIMING_SQL = { before: 'BEFORE', after: 'AFTER', insteadOf: 'INSTEAD OF' } as const;
+
+function renderTrigger(ownerSchema: string, ownerName: string, t: TriggerSpec): { sql: string; table: string } {
+  const table = renderName(ownerSchema, ownerName);
+  const events = t.events
+    .map((e) => (e === 'update' && t.of?.length ? `UPDATE OF ${t.of.map((c) => `"${c}"`).join(', ')}` : e.toUpperCase()))
+    .join(' OR ');
+  const when = t.condition ? ` WHEN (${t.condition})` : '';
+  const fnTarget = renderName(...(([q]) => [q.schema, q.name] as const)([parseQualified(t.execute.name)]));
+  return {
+    sql: `CREATE TRIGGER ${t.name} ${TIMING_SQL[t.timing]} ${events} ON ${table} FOR EACH ${t.forEach.toUpperCase()}${when} EXECUTE FUNCTION ${fnTarget}()`,
+    table,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The compiler — descriptors (+ model/view triggers) → topologically ordered SourceObjects
+// ---------------------------------------------------------------------------
+
+interface Node {
+  identity: string;
+  deps: string[];
+  build: (seq: number) => SourceObject;
+}
+
+function derivedIdentity(d: DerivedDescriptor): string {
+  const { schema, name } = parseQualified(d.name);
+  return `${schema}.${name}`;
+}
+
+function make(kind: SourceObject['kind'], rawName: string, sql: string, attachments: Attachment[], extra: Partial<SourceObject> = {}): (seq: number) => SourceObject {
+  const { schema, name } = parseQualified(rawName);
+  return (seq) => ({
+    kind, schema, name,
+    identity: extra.identity ?? `${schema}.${name}`,
+    sql, attachments,
+    hash: hashSourceContent(sql, attachments),
+    file: DECLARED, seq,
+    ...extra,
+  });
+}
+
+/**
+ * Compile the declared derived layer: every descriptor plus every trigger declared on the
+ * models and views, in dependency order. A trigger's `execute:` function must itself be in
+ * the derived set — a trigger cannot draw on a function nothing declares.
+ */
+export function compileDerived(models: readonly ModelDescriptor[], derived: readonly DerivedDescriptor[]): SourceObject[] {
+  // Invoker-view reachability is a COMPILE fail (B2): a granted-but-unreadable view is
+  // structurally broken — every verb that consumes descriptors refuses, not just db:check.
+  const unreachable = findInvokerReachabilityGaps(derived);
+  if (unreachable.length > 0) {
+    throw new Error(unreachable.map((g) => g.message).join('\n'));
+  }
+
+  const identities = new Set(derived.map(derivedIdentity));
+  const nodes: Node[] = [];
+
+  const depIdentities = (refs: readonly unknown[]): string[] =>
+    refs
+      .filter((r): r is DerivedDescriptor => typeof r === 'object' && r != null && !('table' in (r as object)))
+      .map((r) => derivedIdentity(r))
+      .filter((id) => identities.has(id));
+
+  // The DECLARED dependency set, verbatim: every ref (models included, in-set or not) as
+  // an identity — what B4's dependency drift verifies against the live catalog's edges.
+  // Distinct from the topo `deps` above, which keep only in-set derived identities.
+  const declaredIdentities = (refs: readonly DependsOnRef[]): string[] =>
+    [...new Set(refs.map((r) => ('table' in r ? `${r.schema}.${r.table}` : derivedIdentity(r))))].sort();
+
+  for (const d of derived) {
+    const identity = derivedIdentity(d);
+    switch (d.kind) {
+      case 'view': {
+        const { sql, attachments } = renderView(d);
+        nodes.push({ identity, deps: depIdentities(d.dependsOn), build: make('view', d.name, sql, attachments, { declaredDeps: declaredIdentities(d.dependsOn) }) });
+        break;
+      }
+      case 'materialized view': {
+        const { sql, attachments } = renderMaterializedView(d);
+        nodes.push({ identity, deps: depIdentities(d.dependsOn), build: make('materialized view', d.name, sql, attachments, { declaredDeps: declaredIdentities(d.dependsOn) }) });
+        break;
+      }
+      case 'function': {
+        const { sql, attachments } = renderFunction(d);
+        const setofDep = typeof d.returns === 'string' ? [] : depIdentities([d.returns.setof]);
+        nodes.push({ identity, deps: [...depIdentities(d.dependsOn), ...setofDep], build: make('function', d.name, sql, attachments) });
+        break;
+      }
+      case 'sql': {
+        // The drop is ALWAYS present on the compiled object — explicit from the descriptor,
+        // or derived for the simple (name-only DROP) kinds — so provenance always records
+        // how to remove it (removal never orphans; the C1 closure).
+        const q = parseQualified(d.name);
+        const drop = d.drop ?? `DROP ${d.objectKind.toUpperCase()} IF EXISTS ${renderName(q.schema, q.name)}`;
+        nodes.push({
+          identity,
+          deps: depIdentities(d.dependsOn),
+          build: make('sql', d.name, d.as, [], { objectKind: d.objectKind, drop }),
+        });
+        break;
+      }
+    }
+  }
+
+  // Triggers declared on models and on views — the deps come free (execute fn; the
+  // declaration-site view when it is itself derived). The function MUST be declared.
+  const triggerOwners: Array<{ schema: string; name: string; ownerIdentity: string | null; triggers: TriggerSpec[] }> = [
+    ...models.map((m) => ({ schema: m.schema, name: m.table, ownerIdentity: null, triggers: m.triggers })),
+    ...derived.filter((d): d is ViewDescriptor => d.kind === 'view').map((v) => {
+      const q = parseQualified(v.name);
+      return { schema: q.schema, name: q.name, ownerIdentity: `${q.schema}.${q.name}`, triggers: v.triggers };
+    }),
+  ];
+  for (const owner of triggerOwners) {
+    for (const t of owner.triggers) {
+      const fnIdentity = derivedIdentity(t.execute);
+      if (!identities.has(fnIdentity)) {
+        throw new Error(
+          `trigger '${t.name}' on ${owner.schema}.${owner.name}: its execute function '${t.execute.name}' is not in the derived set — declare it in defineModule({ derived: [...] }).`,
+        );
+      }
+      const { sql, table } = renderTrigger(owner.schema, owner.name, t);
+      const identity = `${owner.schema}.${owner.name}.${t.name}`;
+      nodes.push({
+        identity,
+        deps: [fnIdentity, ...(owner.ownerIdentity ? [owner.ownerIdentity] : [])],
+        build: make('trigger', `${owner.schema}.${t.name}`, sql, [], { identity, table }),
+      });
+    }
+  }
+
+  // Kahn's algorithm with a sorted ready-set: deterministic under any declaration order,
+  // ties broken by identity — never by import order. A cycle is a compile error.
+  const byIdentity = new Map(nodes.map((n) => [n.identity, n]));
+  const indegree = new Map(nodes.map((n) => [n.identity, 0]));
+  const dependents = new Map<string, string[]>();
+  for (const n of nodes) {
+    for (const dep of n.deps) {
+      indegree.set(n.identity, (indegree.get(n.identity) ?? 0) + 1);
+      dependents.set(dep, [...(dependents.get(dep) ?? []), n.identity]);
+    }
+  }
+  const ready = nodes.filter((n) => (indegree.get(n.identity) ?? 0) === 0).map((n) => n.identity).sort();
+  const ordered: SourceObject[] = [];
+  while (ready.length) {
+    const id = ready.shift()!;
+    ordered.push(byIdentity.get(id)!.build(ordered.length));
+    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();
+      }
+    }
+  }
+  if (ordered.length !== nodes.length) {
+    const stuck = nodes.filter((n) => !ordered.some((o) => o.identity === n.identity)).map((n) => n.identity).sort();
+    throw new Error(`derived dependency cycle among: ${stuck.join(', ')} — a view cannot (transitively) depend on itself; PostgreSQL would refuse it too.`);
+  }
+  return ordered;
+}

package/src/cli/derived-grants.ts

@@ -0,0 +1,96 @@
+/**
+ * derived-grants — the grant half of B4's live drift
+ * (docs/plans/read-model-everywhere.md, "B4 — live drift + doctor").
+ *
+ * Content hashes see SOURCE changes; a hand-run GRANT/REVOKE on the live database touches
+ * no hash and used to be invisible. This module closes it with two pure pieces:
+ *
+ *   - `parseGrantAttachments`: the declared grants, read back out of the object's own
+ *     grant attachments. The grammar is OURS — the descriptor compiler emits
+ *     every one of these statements — so the parse is narrow and total, never a general
+ *     SQL parser. A `REVOKE ALL … FROM PUBLIC` declares PUBLIC as explicitly EMPTY, so a
+ *     live default ACL (PostgreSQL grants functions EXECUTE to PUBLIC out of the box)
+ *     diffs to the revoke.
+ *   - `diffObjectGrants`: the reconcileGrants pattern from the table path — per grantee,
+ *     revoke what live has that the source doesn't declare, grant what the source
+ *     declares that live lacks. The declared source is authoritative for authz; grants
+ *     converge without drift ceremony (rebuilds lose hand-edits, REVOKE/GRANT loses
+ *     nothing but the drift itself).
+ *
+ * Column-scoped grants (`GRANT SELECT ("a", "b") …`) live in `pg_attribute.attacl`, which
+ * this drift pass does not introspect yet — an object carrying one is marked
+ * `hasColumnGrants` and its grant drift is skipped LOUDLY (the plan warns), never
+ * silently half-diffed.
+ */
+
+import type { Attachment } from './derived-source.js';
+
+export interface ParsedGrants {
+  /** grantee → sorted privileges. PUBLIC present-with-[] means explicitly revoked. */
+  grants: Record<string, string[]>;
+  /** The `ON …` target as our statements spell it (`leaderboard`, `FUNCTION f(text)`). */
+  target: string | null;
+  /** A column-scoped grant is present — attacl is not introspected; skip drift, loudly. */
+  hasColumnGrants: boolean;
+}
+
+// Our two emitters' shapes, nothing more:
+//   GRANT SELECT[ ("c1", "c2")] ON <target> TO r1[, r2…]
+//   GRANT EXECUTE ON FUNCTION <sig> TO r
+//   REVOKE ALL ON FUNCTION <sig> FROM PUBLIC
+const GRANT_RE = /^GRANT\s+([A-Z]+)\s*(\([^)]*\))?\s+ON\s+(.+?)\s+TO\s+(.+)$/i;
+const REVOKE_PUBLIC_RE = /^REVOKE\s+ALL\s+ON\s+(.+?)\s+FROM\s+PUBLIC$/i;
+
+/** The declared grant contract, read back from an object's own grant attachments. */
+export function parseGrantAttachments(attachments: readonly Attachment[]): ParsedGrants {
+  const grants: Record<string, Set<string>> = {};
+  let target: string | null = null;
+  let hasColumnGrants = false;
+
+  for (const a of attachments) {
+    if (a.kind !== 'grant') continue;
+    const revoke = a.sql.match(REVOKE_PUBLIC_RE);
+    if (revoke) {
+      target ??= revoke[1].trim();
+      grants.PUBLIC ??= new Set();
+      continue;
+    }
+    const grant = a.sql.match(GRANT_RE);
+    if (!grant) continue;
+    const [, privilege, columns, onTarget, roleList] = grant;
+    if (columns) {
+      hasColumnGrants = true;
+      continue; // attacl territory — declared, applied at create, not drift-checked yet
+    }
+    target ??= onTarget.trim();
+    for (const role of roleList.split(',').map((r) => r.trim()).filter(Boolean)) {
+      (grants[role] ??= new Set()).add(privilege.toUpperCase());
+    }
+  }
+
+  const out: Record<string, string[]> = {};
+  for (const role of Object.keys(grants).sort()) out[role] = [...grants[role]].sort();
+  return { grants: out, target, hasColumnGrants };
+}
+
+/**
+ * The idempotent REVOKE/GRANT delta between the declared contract and the live ACLs —
+ * the table path's reconcileGrants, per derived object. Empty when they match.
+ */
+export function diffObjectGrants(
+  target: string,
+  declared: Record<string, string[]>,
+  live: Record<string, string[]>,
+): string[] {
+  const out: string[] = [];
+  const grantees = new Set([...Object.keys(declared), ...Object.keys(live)]);
+  for (const grantee of [...grantees].sort()) {
+    const want = new Set(declared[grantee] ?? []);
+    const have = new Set(live[grantee] ?? []);
+    const toRevoke = [...have].filter((p) => !want.has(p)).sort();
+    const toGrant = [...want].filter((p) => !have.has(p)).sort();
+    if (toRevoke.length) out.push(`REVOKE ${toRevoke.join(', ')} ON ${target} FROM ${grantee}`);
+    if (toGrant.length) out.push(`GRANT ${toGrant.join(', ')} ON ${target} TO ${grantee}`);
+  }
+  return out;
+}