@everystack/cli 0.4.35 → 0.4.36

package/src/cli/swap-pair.ts

@@ -0,0 +1,443 @@
+/**
+ * swap-pair — the paired-schema swap: build the derived layer NEXT TO the incoming base
+ * schema, then rename every pair in one transaction.
+ *
+ * ## Why the obvious fix is wrong
+ *
+ * `db:swap` renames `<schema>` out and `<schema>_incoming` in. A matview over that schema binds
+ * its source by OID, so the rename WELDS it to `<schema>_retiring` — it now reads the retiring
+ * table. The tempting repair is to refresh it afterwards. Verified on PostgreSQL 16, that is
+ * worse than it looks:
+ *
+ *   REFRESH MATERIALIZED VIEW CONCURRENTLY  →  OLD data, and NO error.
+ *
+ * The stored query still resolves to the retiring table, so a CONCURRENTLY refresh cheerfully
+ * repopulates the matview from stale rows and reports success. Silent staleness beats loud
+ * downtime in exactly zero situations. The only correct repair is RECREATION, and the only
+ * recreation with no serving gap is a parallel build swapped in atomically — this module.
+ *
+ * ## The shape
+ *
+ *   1. The artifact restores into `<schema>_incoming`            (already the case)
+ *   2. The declared derived layer is BUILT into `<derived>_incoming`, over `<schema>_incoming`
+ *   3. Every pair renames in ONE transaction
+ *   4. Both retiring schemas drop after verify
+ *
+ * Because the incoming objects are created against the incoming base tables, their OID bindings
+ * are already correct before the rename — and a schema rename does not disturb them. There is no
+ * instant at which a reader sees a half-swapped layer, and no refresh runs at all.
+ *
+ * ## Granularity: whole-schema
+ *
+ * A derived schema is paired WHOLESALE the moment anything in it depends on the swapped schema.
+ * Objects in that schema which do NOT depend on the swap get rebuilt too. That is deliberate:
+ * the alternative (rebuild the dependents, `ALTER … SET SCHEMA` the rest across) has to partition
+ * the dependency graph exactly right, and an object left on the wrong side binds to a retiring
+ * schema — the precise failure this module exists to prevent. Rebuilding a few objects that did
+ * not strictly need it is the cheaper mistake. Object-level pruning is a later optimization that
+ * does not change this contract.
+ *
+ * ## Two wrinkles that are easy to miss
+ *
+ *  - **Derived objects live INSIDE the base schema too.** A function in `analytics` returning
+ *    SETOF a matview in `analytics_view` is reconcile-managed but resident in the schema being
+ *    swapped, and the artifact's TOC filter strips it. It must be rebuilt into
+ *    `<schema>_incoming` alongside the derived schemas, or the swap lands a base schema missing
+ *    its own functions.
+ *  - **The dependency runs BOTH ways.** That same function makes the base schema depend on the
+ *    derived one (pg_proc → pg_type). Build order is the compiled topological order, which
+ *    already crosses schemas correctly; nothing here may re-sort it per schema.
+ */
+
+import type { ModelDescriptor, DerivedDescriptor } from '@everystack/model';
+import { parseQualified } from './derived-source.js';
+import type { SourceObject } from './derived-source.js';
+import { rewriteStatementLineMulti, splitCodeSpans } from './schema-rewrite.js';
+import { parseGrantAttachments } from './derived-grants.js';
+import { derivedSearchPath, renderSetSearchPath, renderProvenanceUpsert, ENSURE_RECONCILER_SQL } from './derived-apply.js';
+import type { LiveObject } from './derived-introspect.js';
+import { compileTableContract } from './authz-compile.js';
+
+const SAFE_SCHEMA = /^[a-z_][a-z0-9_$]*$/;
+
+/** The identity (`schema.name`) a descriptor is known by. */
+function identityOf(d: DerivedDescriptor): string {
+  const { schema, name } = parseQualified(d.name);
+  return `${schema}.${name}`;
+}
+
+/** The schema a descriptor lives in. */
+export function schemaOfDescriptor(d: DerivedDescriptor): string {
+  return parseQualified(d.name).schema;
+}
+
+/**
+ * Every identity a descriptor declares a dependency on — `dependsOn` for all kinds, PLUS the
+ * `returns: setof(...)` target for functions and the owning table for triggers.
+ *
+ * The setof target matters more than it looks: it is the edge that makes a base-schema function
+ * depend on a derived-schema type, and it is recorded by PostgreSQL against the composite TYPE,
+ * so a dependsOn-only walk misses it entirely.
+ */
+export function declaredDepIdentities(d: DerivedDescriptor): string[] {
+  const out = new Set<string>();
+  const add = (ref: unknown): void => {
+    if (!ref || typeof ref !== 'object') return;
+    const r = ref as { table?: string; schema?: string; name?: string };
+    if (typeof r.table === 'string') out.add(`${r.schema ?? 'public'}.${r.table}`);
+    else if (typeof r.name === 'string') out.add(identityOf(ref as DerivedDescriptor));
+  };
+  for (const ref of (d as { dependsOn?: readonly unknown[] }).dependsOn ?? []) add(ref);
+  const returns = (d as { returns?: unknown }).returns;
+  if (returns && typeof returns === 'object' && 'setof' in (returns as object)) {
+    add((returns as { setof: unknown }).setof);
+  }
+  const table = (d as { table?: unknown }).table;
+  if (typeof table === 'string') {
+    const { schema, name } = parseQualified(table);
+    out.add(`${schema}.${name}`);
+  }
+  return [...out];
+}
+
+/**
+ * The derived schemas that must swap ALONGSIDE `schema` — every schema holding a declared
+ * derived object that transitively depends on anything in `schema`.
+ *
+ * `schema` itself is never in the result: its own derived residents are rebuilt into
+ * `<schema>_incoming`, which is a different code path (the artifact already supplies the tables).
+ * The walk is transitive because a view over a matview over the swapped schema is just as welded
+ * to it as the matview is — the direct-only walk was a real bug once.
+ */
+export function pairedDerivedSchemas(
+  models: readonly ModelDescriptor[],
+  derived: readonly DerivedDescriptor[],
+  schema: string,
+): string[] {
+  // Seed: everything the swapped schema physically contains — its models, and any derived
+  // object declared to live in it.
+  const reached = new Set<string>();
+  for (const m of models) {
+    if ((m.schema || 'public') === schema) reached.add(`${schema}.${m.table}`);
+  }
+  for (const d of derived) {
+    if (schemaOfDescriptor(d) === schema) reached.add(identityOf(d));
+  }
+
+  // Fixed point: a descriptor joins the closure once any of its declared deps is in it. Repeat
+  // until nothing new arrives — declaration order is not dependency order.
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const d of derived) {
+      const id = identityOf(d);
+      if (reached.has(id)) continue;
+      if (declaredDepIdentities(d).some((dep) => reached.has(dep))) {
+        reached.add(id);
+        grew = true;
+      }
+    }
+  }
+
+  const schemas = new Set<string>();
+  for (const d of derived) {
+    if (!reached.has(identityOf(d))) continue;
+    const s = schemaOfDescriptor(d);
+    if (s !== schema) schemas.add(s);
+  }
+  return [...schemas].sort();
+}
+
+/**
+ * The schema rename map for a paired swap: every schema in the swap set to its `_incoming` twin.
+ * The base schema is always present; the paired derived schemas follow.
+ */
+export function incomingSchemaMap(schema: string, paired: readonly string[], suffix = '_incoming'): Record<string, string> {
+  const map: Record<string, string> = { [schema]: `${schema}${suffix}` };
+  for (const p of paired) map[p] = `${p}${suffix}`;
+  return map;
+}
+
+/**
+ * The roles that hold ANY declared grant in each schema of the swap set — models' table grants
+ * plus the derived objects' own grant attachments.
+ *
+ * This is what schema-level USAGE has to be re-granted to. A role with SELECT on a table it cannot
+ * reach is not a degraded state, it is an invisible one: PostgreSQL reports a missing schema USAGE
+ * as ABSENCE, not denial —
+ *
+ *   relation "player_gridiron_index" does not exist
+ *
+ * — so the app 500s and the error points at the wrong thing entirely.
+ */
+export function swapSchemaRoles(
+  models: readonly ModelDescriptor[],
+  objects: readonly SourceObject[],
+  schemas: readonly string[],
+): Map<string, string[]> {
+  const byShema = new Map<string, Set<string>>();
+  for (const s of schemas) byShema.set(s, new Set());
+  for (const m of models) {
+    const set = byShema.get(m.schema || 'public');
+    if (!set) continue;
+    const c = compileTableContract(m);
+    for (const r of Object.keys(c.grants)) set.add(r);
+    for (const r of Object.keys(c.columnGrants ?? {})) set.add(r);
+  }
+  for (const o of objects) {
+    const set = byShema.get(o.schema);
+    if (!set) continue;
+    const { grants } = parseGrantAttachments(o.attachments);
+    for (const [role, privileges] of Object.entries(grants)) {
+      if (privileges.length > 0) set.add(role);
+    }
+  }
+  const out = new Map<string, string[]>();
+  for (const [s, roles] of byShema) if (roles.size) out.set(s, [...roles].sort());
+  return out;
+}
+
+/**
+ * `GRANT USAGE ON SCHEMA` for every schema in the swap set, naming the FINAL schemas.
+ *
+ * These run INSIDE the swap transaction, after the renames — the incoming schemas arrive with no
+ * schema-level ACL at all (the base one is restored `--no-privileges`; the derived twins are
+ * freshly created), so without this the swap commits a set of schemas no application role can
+ * enter. Table-level authz was always re-applied; the schema level was simply never considered.
+ */
+export function renderSwapSchemaUsage(
+  models: readonly ModelDescriptor[],
+  objects: readonly SourceObject[],
+  schema: string,
+  paired: readonly string[],
+): string[] {
+  const roles = swapSchemaRoles(models, objects, [schema, ...paired]);
+  const out: string[] = [];
+  for (const s of [schema, ...paired]) {
+    const rs = roles.get(s);
+    if (!rs?.length) continue;
+    const targets = rs.map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : `"${r}"`)).join(', ');
+    out.push(`GRANT USAGE ON SCHEMA "${s}" TO ${targets};`);
+  }
+  return out;
+}
+
+/**
+ * The identities the incoming build is expected to produce, qualified onto the `_incoming`
+ * schemas — what the completeness assertion compares the live catalog against.
+ *
+ * Only CATALOG-VISIBLE kinds count. Triggers carry a compound `schema.table.name` identity and
+ * live in pg_trigger; `sql`-kind escape-hatch objects are invisible to the catalog by definition.
+ * Including either would report a permanent phantom shortfall.
+ */
+export function expectedIncomingObjects(
+  objects: readonly SourceObject[],
+  schema: string,
+  paired: readonly string[],
+  opts: { suffix?: string } = {},
+): string[] {
+  const suffix = opts.suffix ?? '_incoming';
+  const inSet = new Set([schema, ...paired]);
+  const visible = new Set(['view', 'materialized view', 'function']);
+  return objects
+    .filter((o) => inSet.has(o.schema) && visible.has(o.kind))
+    .map((o) => `${o.schema}${suffix}.${o.name}`)
+    .sort();
+}
+
+/**
+ * The `search_path` the incoming build must run under.
+ *
+ * The schema rewrite is TEXTUAL and keys on a schema prefix, so it moves `stats.foo` to
+ * `stats_incoming.foo` and cannot touch a BARE `FROM foo` — there is no prefix to rewrite. A bare
+ * ref resolves against the search_path AT CREATE TIME, so without this the build looks for the
+ * table in the live schemas and fails with `relation "foo" does not exist` on a table the restore
+ * just landed thousands of rows into.
+ *
+ * Bare refs are not an author's mistake to be linted away: `db:pull` generates descriptors from
+ * `pg_get_viewdef`, which renders a reference bare whenever its schema is already on the path. Our
+ * own generator emits them, so the build has to honour them. The reconciler settled this long ago
+ * (derivedSearchPath) and the paired build simply never asked.
+ *
+ * Same function as the reconciler's, with each SWAPPED schema replaced by its `_incoming` twin in
+ * place — so a bare ref resolves to the incoming table exactly as it resolves to the live one
+ * under db:reconcile, and a layer that builds there builds here. Schemas OUTSIDE the swap set keep
+ * their live names: swapping `stats` must leave a bare ref to `curated` pointing at live `curated`.
+ */
+export function incomingSearchPath(
+  objects: readonly SourceObject[],
+  schema: string,
+  paired: readonly string[],
+  opts: { suffix?: string } = {},
+): string[] {
+  const suffix = opts.suffix ?? '_incoming';
+  const map = incomingSchemaMap(schema, paired, suffix);
+  const path = derivedSearchPath([...objects]).map((s) => map[s] ?? s);
+  // A swapped schema the reconciler's path never included (nothing declared a dependency on it)
+  // still holds the artifact's tables. Front of the path, so the twin always wins.
+  for (const s of [schema, ...paired]) {
+    if (!path.includes(map[s])) path.unshift(map[s]);
+  }
+  return path;
+}
+
+/**
+ * Provenance for the objects the paired build created — the bookkeeping that makes the NEXT
+ * db:reconcile a no-op.
+ *
+ * The build creates the derived layer with raw DDL and never told the reconciler. So a swap that
+ * produced a byte-correct layer left every object looking UNRECORDED, and the next reconcile —
+ * run days later, for an unrelated one-line edit — saw the whole layer as drift and rebuilt it,
+ * holding ACCESS EXCLUSIVE the entire time. A consumer measured 331 MB across 55 matviews, and the
+ * rebuild was pure waste: the completeness assertion had already proven the objects correct. They
+ * were rebuilt because the bookkeeping said UNKNOWN, not because anything was wrong.
+ *
+ * The invariant this restores is the one worth stating plainly: a paired swap leaves the database
+ * in the state a reconcile would have left it in, bookkeeping included.
+ *
+ * Recorded at FINAL identities, after the rename — provenance is keyed on where an object lives,
+ * and during the build it lived in `_incoming`. `defHash` must come from the LIVE catalog for the
+ * same reason the reconciler reads it there: it is a hash of PostgreSQL's own deparse, which never
+ * matches the authored text.
+ */
+export function renderPairedProvenance(
+  objects: readonly SourceObject[],
+  live: readonly LiveObject[],
+  schema: string,
+  paired: readonly string[],
+): { statements: string[]; recorded: string[]; unmatched: string[] } {
+  const inSet = new Set([schema, ...paired]);
+  const liveById = new Map(live.map((o) => [o.identity, o]));
+  // Catalog-invisible kinds have no live row by definition and are not a problem — they keep the
+  // reconciler's own record path. Anything else missing IS a problem worth naming.
+  const visible = new Set(['view', 'materialized view', 'function']);
+  const statements: string[] = [...ENSURE_RECONCILER_SQL];
+  const recorded: string[] = [];
+  const unmatched: string[] = [];
+  for (const o of objects) {
+    if (!inSet.has(o.schema)) continue;
+    const l = liveById.get(o.identity);
+    if (!l) {
+      if (visible.has(o.kind)) unmatched.push(o.identity);
+      continue;
+    }
+    statements.push(renderProvenanceUpsert(o.identity, o.hash, l.defHash, o.kind, o.drop, o.bodyHash));
+    recorded.push(o.identity);
+  }
+  // Returning the COUNTS, not just the SQL, so the caller can say what it actually did. The first
+  // version returned a bare string[] and an empty one on zero matches — so a swap that recorded
+  // NOTHING still printed "provenance recorded". Exactly the silent-success shape this whole
+  // feature keeps having to be defended against, reintroduced in the defence itself.
+  return { statements: recorded.length ? statements : [], recorded, unmatched };
+}
+
+export interface PairedBuild {
+  /** Ordered SQL creating the incoming derived layer. Run BEFORE the swap transaction. */
+  statements: string[];
+  /** The derived schemas swapping alongside the base schema. */
+  paired: string[];
+  /** Declared schema → its `_incoming` twin, for every schema in the swap set. */
+  schemaMap: Record<string, string>;
+}
+
+/**
+ * Render the build of the incoming derived layer.
+ *
+ * Takes the ALREADY-COMPILED derived objects (topological order preserved — see the wrinkle
+ * about cross-schema build order) and rewrites every reference in the swap set onto its
+ * `_incoming` twin. An object outside the swap set is skipped: it keeps serving throughout and
+ * must not be duplicated.
+ *
+ * Pure. The caller runs `statements` against the database while the live schemas keep serving.
+ */
+export function renderPairedDerivedBuild(
+  objects: readonly SourceObject[],
+  schema: string,
+  paired: readonly string[],
+  opts: { suffix?: string } = {},
+): PairedBuild {
+  const suffix = opts.suffix ?? '_incoming';
+  for (const s of [schema, ...paired]) {
+    if (!SAFE_SCHEMA.test(s)) {
+      throw new Error(`swap schema ${JSON.stringify(s)} is not a plain lowercase identifier — everystack swaps schemas it can name without quoting games.`);
+    }
+  }
+  const schemaMap = incomingSchemaMap(schema, paired, suffix);
+  const inSet = new Set([schema, ...paired]);
+  // Dollar-quote state carries across lines — a multi-line body must stay literal throughout.
+  const rewrite = (sql: string): string => {
+    let inDollar: string | undefined;
+    return sql.split('\n').map((line) => {
+      const next = splitCodeSpans(line, inDollar).inDollar;
+      const out = rewriteStatementLineMulti(line, schemaMap, inDollar);
+      inDollar = next;
+      return out;
+    }).join('\n');
+  };
+
+  /**
+   * A FUNCTION is not a view, and the difference decides this whole module.
+   *
+   * A view's query is parsed at CREATE time and stored as a rewrite rule holding OIDs, so it must
+   * be built against the incoming tables — rewriting its body is exactly right. A function's body
+   * is stored as TEXT (`prosrc`) and re-resolved BY NAME on every call. Rewrite it and the
+   * function points at `<schema>_incoming` — a schema that stops existing the moment the swap
+   * renames it — and the first call after a successful swap fails with `relation … does not
+   * exist`.
+   *
+   * So a function is split: the header is rewritten (its own name, so it lands in the incoming
+   * schema; its argument and RETURNS types, which ARE OID-bound and must point at the incoming
+   * twins to survive the rename), and the body is left verbatim to resolve against the FINAL
+   * names after the swap. A `SECURITY DEFINER … SET search_path` clause is left alone for the
+   * same reason as the body: it is resolved at call time, not at create time.
+   *
+   * One consequence worth stating: the body is validated at CREATE time against the objects that
+   * are live right now — the OLD ones. A body that only compiles against the new artifact's shape
+   * fails here, before anything is renamed. That is the right place to fail.
+   */
+  const rewriteFunction = (sql: string): string => {
+    const lines = sql.split('\n');
+    const bodyStart = lines.findIndex((l) => /^AS\s+\$[A-Za-z0-9_]*\$\s*$/.test(l.trim()));
+    if (bodyStart === -1) return rewrite(sql); // not the shape we render; rewrite whole, as before
+    const header = lines.slice(0, bodyStart + 1).map((line) =>
+      /\bSET\s+search_path\b/i.test(line) ? line : rewriteStatementLineMulti(line, schemaMap),
+    );
+    return [...header, ...lines.slice(bodyStart + 1)].join('\n');
+  };
+
+  const statements: string[] = [];
+  // The path FIRST — every CREATE below resolves its bare refs against it, and a bare ref is the
+  // majority form in a db:pull-generated descriptor file.
+  const setPath = renderSetSearchPath(incomingSearchPath(objects, schema, paired, { suffix }), false);
+  if (setPath) statements.push(`${setPath};`);
+  // The derived schemas' twins must exist before anything lands in them. The BASE twin is not
+  // created here — the artifact restore already made it, and creating it would mask a restore
+  // that never ran.
+  //
+  // USAGE rides along per schema, exactly as the reconciler's renderEnsureObjectSchemas does. The
+  // first version of this hand-rolled a bare CREATE SCHEMA and skipped the grant, which is how a
+  // successful swap could dark-site an app: the objects were there, correct, and unreachable.
+  const usageByIncoming = swapSchemaRoles([], objects, paired);
+  for (const p of paired) {
+    statements.push(`CREATE SCHEMA IF NOT EXISTS "${p}${suffix}";`);
+    const roles = usageByIncoming.get(p);
+    if (roles?.length) {
+      const targets = roles.map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : `"${r}"`)).join(', ');
+      statements.push(`GRANT USAGE ON SCHEMA "${p}${suffix}" TO ${targets};`);
+    }
+  }
+
+  for (const obj of objects) {
+    if (!inSet.has(obj.schema)) continue;
+    statements.push(`${obj.kind === 'function' ? rewriteFunction(obj.sql) : rewrite(obj.sql)};`);
+    // Attachments (GRANT/COMMENT/CREATE INDEX) name their target, which HAS moved to the incoming
+    // schema — those are rewritten for every kind, functions included.
+    for (const a of obj.attachments) statements.push(`${rewrite(a.sql)};`);
+  }
+
+  // Leave the session as we found it — the swap transaction that follows is fully qualified, but
+  // a lingering path is a trap for anything else sharing this connection.
+  if (setPath) statements.push('RESET search_path;');
+
+  return { statements, paired: [...paired], schemaMap };
+}