@everystack/cli 0.4.45 → 0.4.46

package/src/cli/model-render.ts

@@ -97,13 +97,24 @@ export const ABILITY_PRESETS: Record<string, string[]> = {
 };
 
 /**
- * A rendered ability that is a PUBLIC read — anon-visible, the only shape the soft-delete
- * guard ever applied to. Matches `defineModel`'s own rule: action `read`, with no `role`,
- * `owner`, or `via` narrowing it. Tested per-ability (never against the whole joined stanza)
- * so one ability's `role:` can never mask another's public read.
+ * A rendered ability that is a PUBLIC read — anon-visible, the shape the soft-delete guard
+ * applies to. Tested per-ability (never against the whole joined stanza) so one ability's
+ * `role:` can never mask another's public read.
+ *
+ * The TEXT form of `isPublicReadAbility` from `@everystack/model`, which is the structured
+ * one `defineModel`'s soft-delete refusal uses. Two representations because this renderer only
+ * ever holds rendered source (derive emits text, not descriptors), one meaning — pinned by a
+ * differential test over the ability matrix, the same way `tableReaches` is pinned against the
+ * grant compiler. They used to disagree: this counted `role: 'anon'`, the refusal did not, and
+ * a table whose authenticated read diverges renders exactly that shape. The refusal now fires
+ * on the anonymous audience however it is spelled, so both surfaces answer alike.
  */
-function isPublicReadAbility(expr: string): boolean {
-  return /^can\('read'/.test(expr.trim()) && !/\b(role|owner|via)\s*:/.test(expr);
+export function isPublicReadAbility(expr: string): boolean {
+  const e = expr.trim();
+  if (!/^can\('read'/.test(e)) return false;
+  if (/\b(owner|via)\s*:/.test(e)) return false;
+  const role = /\brole\s*:\s*'([^']+)'/.exec(e);
+  return !role || role[1] === 'anon';
 }
 
 /**
@@ -156,56 +167,47 @@ function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<stri
  * nobody wrote. The comment says how to get the other one, so the decision is visible in the
  * file rather than buried in a compiler convention.
  */
+/**
+ * `writtenBy`, rendered ONLY when the live table is not FORCEd.
+ *
+ * `writtenBy` is not documentation — it is the sole input to RLS FORCE (`forced: writtenBy ===
+ * 'app'`, the compiler's one use of it), and it defaults to `'app'`. So a pulled model that
+ * omits it silently declares FORCE on every table, and the next plan carries an
+ * `ALTER TABLE … FORCE ROW LEVEL SECURITY` against a table someone deliberately left unforced
+ * — a real change to who bypasses row security, arriving in a plan as though it were adoption.
+ * The reference schema happens to be FORCEd throughout, which is exactly why this went unseen.
+ *
+ * `'worker'` is not a guess about the writer; it is the value whose COMPILED CONSEQUENCE
+ * matches the live bit. The comment says so, because a reader who takes it as a claim about
+ * the application would be misled — and this is a line they must consciously keep or change.
+ */
+function writtenByStanza(table: TableSchema, liveAuthz?: Map<string, TableContract>): string {
+  const live = liveAuthz?.get(table.table);
+  if (!live || live.rls.forced) return '';
+  return `  writtenBy: 'worker', // live reality: RLS is not FORCEd here, and only writtenBy controls that. `
+    + `'app' (the default) would FORCE it — a change to who bypasses row security, not an adoption.\n`;
+}
+
 function softDeleteStanza(table: TableSchema, publicRead: boolean): string {
   const hasColumn = table.columns.some((c) => c.name === 'deleted_at');
   if (!hasColumn || !publicRead) return '';
   return `  softDelete: false, // live reality: no policy filters deleted_at. true excludes soft-deleted rows from public reads.\n`;
 }
 
-/** `format_type` → the `field.*()` factory that produces it (the non-parameterized types). */
-const FIELD_FACTORY: Record<string, string> = {
-  uuid: 'uuid',
-  text: 'text',
-  integer: 'integer',
-  bigint: 'bigint',
-  real: 'real',
-  'double precision': 'doublePrecision',
-  boolean: 'boolean',
-  json: 'json',
-  jsonb: 'jsonb',
-  date: 'date',
-  'timestamp with time zone': 'timestamptz',
-  'timestamp without time zone': 'timestamp',
-  timestamp: 'timestamp',
-};
+// The inverse type map lives with the vocabulary it inverts (`@everystack/model`),
+// where `field.pgType` refuses the spellings a first-class field owns — one
+// definition, two callers, so render and refusal can never disagree.
+import { fieldFactoryCall } from '@everystack/model';
+export { fieldFactoryCall };
 
 /**
- * The full `field.*()` call for a `format_type` string, or null when no field maps it.
- * Handles the parameterized types `format_type` spells out — `numeric(p,s)` and
- * `character varying(n)` — so a pulled column round-trips back to the same DDL. A
- * scale-0 numeric renders as the cleaner `field.numeric(p)` (identical to `(p, 0)`).
+ * The verbatim fallback for a type no first-class field owns: carry the exact
+ * `format_type` spelling with `field.pgType(...)`. An array carries its scalar
+ * plus `.array()` — the factory refuses a bracketed spelling by design.
  */
-export function fieldFactoryCall(type: string): string | null {
-  // An array is its base type + `.array()` — exactly how the compiler emits it
-  // (`format_type` spells arrays `text[]`). An array of an unmapped base stays null.
-  if (type.endsWith('[]')) {
-    const base = fieldFactoryCall(type.slice(0, -2));
-    return base ? `${base}.array()` : null;
-  }
-
-  const direct = FIELD_FACTORY[type];
-  if (direct) return `field.${direct}()`;
-
-  const num = type.match(/^numeric(?:\((\d+),(\d+)\))?$/);
-  if (num) {
-    if (num[1] == null) return 'field.numeric()';
-    return num[2] === '0' ? `field.numeric(${num[1]})` : `field.numeric(${num[1]}, ${num[2]})`;
-  }
-
-  const vc = type.match(/^character varying(?:\((\d+)\))?$/);
-  if (vc) return vc[1] != null ? `field.varchar(${vc[1]})` : 'field.varchar()';
-
-  return null;
+function verbatimFieldCall(type: string): string {
+  if (type.endsWith('[]')) return `${verbatimFieldCall(type.slice(0, -2))}.array()`;
+  return `field.pgType(${tsLiteral(type)})`;
 }
 
 /** `public.image_variants` / `image_variants` → `image_variants` (the bare table name). */
@@ -391,8 +393,11 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
     ?? (enumValues
       ? `field.enum(${tsLiteral(col.type)}, [${enumValues.map(tsLiteral).join(', ')}])`
       : fieldFactoryCall(col.type));
-  let expr = call ?? 'field.text()';
-  let comment = call ? '' : ` // FIXME: column type '${col.type}' has no field mapping`;
+  // No first-class field owns the type → carry it VERBATIM. The column's exact
+  // type is the identity, so the round trip is clean: no coercion, no FIXME, no
+  // plan statement. The note stays — a verbatim type is a fact worth seeing.
+  let expr = call ?? verbatimFieldCall(col.type);
+  let comment = call ? '' : ` // verbatim: no first-class field for '${col.type}' — carried as-is`;
 
   const isPk = table.primaryKey.includes(col.name);
   if (isPk) expr += '.primaryKey()';
@@ -503,9 +508,10 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   // reviewer must resolve about a model (and where the field-report consumer's codemod
   // put it, proving the position is mechanical-edit-friendly).
   const stanza = abilitiesStanza(abilities, table, liveAuthz);
+  const writtenBy = writtenByStanza(table, liveAuthz);
   const softDelete = softDeleteStanza(table, stanza.publicRead);
 
-  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza.text}\n${softDelete}  fields: {\n${fields}\n  },${constraints}\n});`;
+  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza.text}\n${writtenBy}${softDelete}  fields: {\n${fields}\n  },${constraints}\n});`;
 }
 
 /** The `import` lines a rendered body needs — only what it actually uses, so the file reads clean. */

package/src/cli/schema-compile.ts

@@ -124,9 +124,14 @@ function scalarPgType(spec: FieldSpec): string {
     if (!spec.enumName) throw new Error('field bridge: an enum field needs a type name — field.enum(name, values)');
     return spec.enumName;
   }
+  if (spec.type === 'pgType') {
+    // A verbatim type: the declared string IS the canonical `format_type` spelling
+    // (the factory refused anything else), so it round-trips byte-for-byte.
+    if (!spec.pgTypeName) throw new Error('field bridge: a pgType field needs its type name — field.pgType(name)');
+    return spec.pgTypeName;
+  }
   const t = PG_TYPE[spec.type];
   if (!t) {
-    // geometry needs PostGIS — a deliberate follow-up, not a silent wrong column.
     throw new Error(`field bridge: no DDL mapping for field type '${spec.type}' yet`);
   }
   return t;

package/src/cli/schema-diff.ts

@@ -520,7 +520,7 @@ function createIndexChange(table: string, ix: IndexSchema): SchemaChange {
  * the consumer's 31 phantom drop/creates). Plain btree indexes key exactly as before
  * plus a constant tail — both sides compute the same key, so nothing churns.
  */
-function indexKey(ix: IndexSchema): string {
+export function indexKey(ix: IndexSchema): string {
   const entries = ix.columns.map((c) => normalizeCheck(c)).join(',');
   return `${ix.unique ? 'u' : ''}|${entries}|${normalizeCheck(ix.where ?? '')}|${ix.using ?? 'btree'}|${(ix.include ?? []).join(',')}`;
 }

package/src/cli/schema-fingerprint.ts

@@ -52,7 +52,8 @@ import type { SchemaSnapshot, TableSchema } from './schema-introspect.js';
 import type { AuthzContract, TableContract } from './authz-contract.js';
 import { compileTableSchema, compileEnums, compileSequences } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
-import { normalizeDefault, normalizeCheck } from './schema-diff.js';
+import { governedRoleSet } from './authz-reconcile.js';
+import { normalizeDefault, normalizeCheck, indexKey } from './schema-diff.js';
 
 // v2: expression fields (defaults, checks, partial-index WHERE) normalize through
 // the diff's pg-deparse normalizers before hashing, so the model form and the live
@@ -73,7 +74,43 @@ import { normalizeDefault, normalizeCheck } from './schema-diff.js';
 // an ungoverned migrator/ETL role alone and a hash that counts it can never converge.
 // Together these restore the identity the format exists for: fingerprints match exactly when
 // db:generate is a no-op.
-export const FINGERPRINT_VERSION = 4;
+// v5 — a redundant DEFAULT PRECISION is no longer part of a column's identity.
+// `timestamp(6) without time zone` and `timestamp without time zone` are the same type (6 is
+// the family's default), so they now canonicalize to one spelling in
+// `canonicalColumnType`. Two columns that always stored identical values used to hash
+// differently, which meant a schema carrying the explicit spelling could never reach MATCH.
+// Only precision 6 and only the timestamp family: `timestamp(3)` is a real difference.
+// Consequence, and the reason this is a VERSION and not a silent fix: a plan or baseline
+// minted under v4 against such a schema refuses as a FORMAT CHANGE and must be re-minted.
+// No DDL, no data movement — the fingerprint is a content address.
+// v6 — an INDEX'S IDENTITY is the differ's content key, verbatim. The v5 form hashed
+// {columns, unique, where} only, so a GIN and a btree index on the same column hashed
+// EQUAL while `db:generate` emitted a DROP + CREATE — MATCH could lie exactly where it
+// matters for tsvector/geometry (GIN/GiST). The v5 form also hashed indexes as a
+// multiset while the diff dedupes by content, so a physically duplicate index (two
+// identical indexes under different names — a common migration-era artifact) made
+// MATCH unreachable even though the diff was, correctly, a no-op. Both fixed the same
+// way: the canonical index entry is now `indexKey` from schema-diff — access method and
+// INCLUDE in, key entries normalized, names out, duplicates collapsed — ONE definition
+// for "are these the same index", shared by the differ and the hash. Same consequence
+// as every bump: plans/baselines minted under v5 refuse as FORMAT CHANGE and re-mint.
+// v7 — a DEAD policy is not part of the state. A policy governing a privilege none of its
+// roles holds authorizes nothing: Postgres refuses at the GRANT before ever consulting it.
+// The reconciler now leaves such a policy alone (dropping it changes no access, so it was
+// pure churn an adopter had to read and approve), and the canonical form stops counting it —
+// the same choice from the same function, `isPolicyDead`, which also backs the adoption
+// classifier's `dead` class and db:pull's notes. Without both halves the state could not
+// converge on any brownfield database carrying policies whose grants were revoked long ago.
+// Deadness is recomputed against live grants every time and never stored, so a policy
+// RE-ENTERS the state the moment a grant makes it effective.
+// v8 — a SUBSUMED policy is not part of the state either. Permissive policies OR together and
+// a PUBLIC policy applies to every role, so a role-scoped policy whose rule is identical to a
+// PUBLIC one admits no session the other does not: it changes no access, so it is churn, not
+// state. Same treatment and same lockstep as v7's dead policies — `isPolicySubsumed` excludes
+// it from the canonical form AND the reconciler leaves it alone, before and after. Restrictive
+// policies are never subsumed (they AND, so removing one would WIDEN), and the rule must match
+// exactly including the effective WITH CHECK.
+export const FINGERPRINT_VERSION = 8;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -118,11 +155,13 @@ function canonicalTable(table: TableSchema): Record<string, unknown> {
       })),
       (f) => stableStringify(f),
     ),
-    indexes: byKey(
-      // Partial-index WHERE is a predicate too — normalize it the same way as a check.
-      table.indexes.map((i) => ({ columns: i.columns, unique: i.unique, ...(i.where ? { where: normalizeCheck(i.where) } : {}) })),
-      (i) => stableStringify(i),
-    ),
+    // v6: an index's canonical form IS the differ's content key — one definition,
+    // both surfaces. That brings the access method (`using`) and INCLUDE set into
+    // the identity (a GIN and a btree on the same column are different states),
+    // normalizes key entries the way the diff compares them, and DEDUPES: two
+    // physically duplicate indexes are one state, exactly as the diff (which can
+    // neither create nor drop the second copy) already treats them.
+    indexes: [...new Set(table.indexes.map(indexKey))].sort(),
   };
 }
 
@@ -251,6 +290,27 @@ export function fingerprintModels(
   return fingerprintState(snapshot, authzTables, opts.schemas ? { schemas: opts.schemas } : {});
 }
 
+/**
+ * The governed-role set a model checkout implies — THE set every declared-vs-live
+ * comparison must filter the live side through. One derivation, all callers:
+ * db:fingerprint's MATCH, the mint's `to` endpoint, the apply's verify-after and
+ * already-applied checks, and git-descent's declares-test. (v4 introduced the
+ * filter in the canonical layer; a live grant nothing will ever reconcile is not
+ * part of the state the models describe. Leaving a caller unfiltered re-creates
+ * the exact defect v4 fixed: zero statements, MATCH unreachable.)
+ * `extra` is the modules' widened `governedRoles` declaration.
+ */
+export function governedRolesForModels(
+  models: ModelDescriptor[],
+  extra?: readonly string[],
+): ReadonlySet<string> {
+  const declared: AuthzContract = {
+    tables: models.map((m) => compileTableContract(m, {})),
+    functions: [],
+  };
+  return governedRoleSet(declared, extra ?? []);
+}
+
 /** Convenience: the live side, from the two existing introspections. */
 export function fingerprintLive(
   snapshot: SchemaSnapshot,

package/src/cli/schema-introspect.ts

@@ -14,7 +14,7 @@
  */
 
 import { IGNORED_SCHEMAS, coerceBool, type QueryRunner } from './authz-contract.js';
-import { withCanonicalSearchPath } from './search-path.js';
+import { INTROSPECTION_SESSION, type SessionRunner } from './session.js';
 
 // ---------------------------------------------------------------------------
 // The data-layer snapshot — the structured shape both producers target.
@@ -281,6 +281,33 @@ export interface ColumnRow {
   position: unknown;
 }
 
+/**
+ * Drop a precision qualifier that only restates the default.
+ *
+ * `timestamp(6) without time zone` and `timestamp without time zone` are THE SAME TYPE:
+ * 6 is Postgres's default precision for the timestamp family, so a column declared either
+ * way stores identical values with identical semantics. `format_type` still spells the
+ * explicit one with its typmod, because the catalog records that somebody typed it.
+ *
+ * Everything downstream compares these strings — the renderer to pick a `field.*()`, the
+ * differ to decide an ALTER, the fingerprint to content-address the schema. With the two
+ * spellings distinct, a brownfield column declared `timestamp(6)` had NO field mapping, so
+ * db:pull rendered `field.text()` with a FIXME and the next plan proposed rewriting the
+ * column to text — destroying a column to reconcile a difference that does not exist. On a
+ * real adopter's schema that was 18 of 48 destructive statements.
+ *
+ * Normalized HERE, at the single funnel every consumer reads, rather than at each comparison:
+ * three surfaces answering one question separately is how they drift.
+ *
+ * ONLY precision 6, and only for the timestamp family. `timestamp(3)` genuinely truncates to
+ * milliseconds — a real difference that must keep saying so.
+ */
+// The one funnel — a type's canonical spelling is defined ONCE, in the model
+// package, so the field factory (`field.pgType` refusals), this introspection,
+// the renderer, the differ, and the fingerprint can never disagree about it.
+import { canonicalColumnType } from '@everystack/model';
+export { canonicalColumnType };
+
 export function columnRowToDescriptor(row: ColumnRow): { table: string; column: ColumnSchema; position: number } {
   const def = row.default == null ? null : String(row.default);
   return {
@@ -288,7 +315,7 @@ export function columnRowToDescriptor(row: ColumnRow): { table: string; column:
     position: Number(row.position),
     column: {
       name: row.column,
-      type: String(row.type),
+      type: canonicalColumnType(String(row.type)),
       notNull: coerceBool(row.not_null),
       default: def && def.length > 0 ? def : null,
     },
@@ -604,20 +631,20 @@ export function assembleSchema(rows: SchemaRows): SchemaSnapshot {
  * (the ops Lambda `db:query` in production, a fake in tests) and folds the rows with
  * `assembleSchema`. This is the `current` side `db:generate` diffs the compiled Models against.
  */
-export async function introspectSchema(run: QueryRunner): Promise<SchemaSnapshot> {
-  // Pin the canonical search_path: column defaults, CHECK constraints, and index
-  // expressions all deparse relative to it, so an ambient non-default path would
-  // read as false drift. See search-path.ts.
-  return withCanonicalSearchPath(run, async () => {
-    const [columns, constraints, enums, indexes, sequences] = await Promise.all([
-      run(COLUMNS_SQL), run(CONSTRAINTS_SQL), run(ENUMS_SQL), run(INDEXES_SQL), run(SEQUENCES_SQL),
-    ]);
-    return assembleSchema({
-      columns: columns as ColumnRow[],
-      constraints: constraints as ConstraintRow[],
-      enums: enums as EnumRow[],
-      indexes: indexes as IndexRow[],
-      sequences: sequences as SequenceRow[],
-    });
+export async function introspectSchema(session: SessionRunner): Promise<SchemaSnapshot> {
+  // ONE session, so all five queries see one database at one moment, under one pinned
+  // search_path. Column defaults, CHECK constraints and index expressions all deparse
+  // relative to that path — spread across separate connections these five rows can render
+  // the same schema two ways, and a fingerprint minted from the mix describes nothing.
+  const [columns, constraints, enums, indexes, sequences] = await session(
+    [COLUMNS_SQL, CONSTRAINTS_SQL, ENUMS_SQL, INDEXES_SQL, SEQUENCES_SQL],
+    INTROSPECTION_SESSION,
+  );
+  return assembleSchema({
+    columns: columns as ColumnRow[],
+    constraints: constraints as ConstraintRow[],
+    enums: enums as EnumRow[],
+    indexes: indexes as IndexRow[],
+    sequences: sequences as SequenceRow[],
   });
 }

package/src/cli/schema-source.ts

@@ -114,6 +114,15 @@ function baseColumnSource(columnName: string, spec: FieldSpec): { call: string;
       if (!spec.enumName) throw new Error('enum field is missing enumName');
       return { call: `${enumConstName(spec.enumName)}(${n})`, builder: enumConstName(spec.enumName) };
     }
+    case 'pgType': {
+      // A verbatim type: the generated schema carries the exact string via drizzle's
+      // customType — same as the runtime builder in @everystack/model.
+      if (!spec.pgTypeName) throw new Error('pgType field is missing pgTypeName');
+      return {
+        call: `customType<{ data: unknown }>({ dataType: () => ${strLiteral(spec.pgTypeName)} })(${n})`,
+        builder: 'customType',
+      };
+    }
     default: {
       const exhaustive: never = spec.type;
       throw new Error(`Unsupported field type: ${String(exhaustive)}`);

package/src/cli/session.ts

@@ -0,0 +1,184 @@
+/**
+ * SessionRunner — the type that can express "these statements describe ONE moment".
+ *
+ * `QueryRunner` (authz-contract.ts) runs one SQL string and returns rows. It cannot say
+ * that two statements shared a connection, because on the stage lane they do not: each
+ * one is its own ops-Lambda invoke, answered by whichever container is warm. An
+ * introspection built from five of those is a collage, and a fingerprint minted from a
+ * collage describes no database that ever existed.
+ *
+ * So this is a SECOND type, not a widening of the first. A function that takes a
+ * `SessionRunner` cannot be handed a session-less venue — the compiler refuses it. That
+ * is the whole point: the guarantee is in the type, not in a convention or a capability
+ * flag that degrades quietly when the backend cannot honor it.
+ *
+ * Both venues implement it. The stage lane sends the statements to the ops Lambda's
+ * `db:session` action (one invoke, one connection, one transaction); the direct lane runs
+ * them in one postgres.js transaction on its single connection. Same contract, same
+ * ordering, same `SET LOCAL` semantics.
+ */
+
+/** One statement. A bare string is shorthand for `{ sql, allowFailure: false }`. */
+export interface SessionStatement {
+  sql: string;
+  /**
+   * Survive a failure of THIS statement, leaving the other result slots intact — the
+   * venue wraps it in a savepoint. For "this catalog table may not exist yet"
+   * (`derived_provenance`, `backfill_log`, `schema_log`), which is otherwise a
+   * try/catch that can only be written by giving up the session.
+   */
+  allowFailure?: boolean;
+}
+
+export interface SessionOptions {
+  /** Run the transaction READ ONLY. The caller's policy — no venue assumes it. */
+  readOnly?: boolean;
+  /** Isolation level; 'repeatable read' gives every statement one snapshot. */
+  isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable';
+  /**
+   * Pin `search_path` for the transaction. Emitted as `SET LOCAL` inside the session and
+   * CONSUMING NO RESULT SLOT — results stay indexed by statement. Never prepend the pin
+   * as a statement of your own; that shifts every index after it.
+   */
+  searchPath?: string;
+}
+
+/** A statement that failed under `allowFailure`. Occupies its slot; carries the cause. */
+export interface SessionStatementError {
+  everystackSessionError: true;
+  message: string;
+}
+
+/** One slot: the statement's rows, or the marker for an allowed failure. */
+export type SessionResult = any[] | SessionStatementError;
+
+/**
+ * Run N statements on ONE connection in ONE transaction; N result sets, in input order.
+ *
+ * Nothing about a `SessionRunner` is optional or best-effort. A venue that cannot make
+ * the guarantee does not implement the type.
+ */
+export type SessionRunner = (
+  statements: ReadonlyArray<SessionStatement | string>,
+  opts?: SessionOptions,
+) => Promise<SessionResult[]>;
+
+/** The canonical introspection search_path — explicit, override-proof, declared-matching.
+ *
+ * Every expression PostgreSQL deparses on introspection (column defaults, CHECK
+ * constraints, index expressions, generated columns, view bodies, function bodies)
+ * renders its schema qualification RELATIVE to the session `search_path`. The declared
+ * state is always canonical — public bare, non-public qualified — so capturing under
+ * `public` makes the live read comparable to it. It must be an EXPLICIT value: `RESET`
+ * and `SET … TO DEFAULT` inherit an `ALTER DATABASE … SET search_path` override, which
+ * is the very condition this exists to neutralize.
+ */
+export const CANONICAL_SEARCH_PATH = 'public';
+
+/**
+ * The options every catalog introspection reads under: one snapshot, no writes, and the
+ * canonical deparse baseline. One definition, so the three introspections cannot drift
+ * apart in what they mean by "the live state".
+ */
+export const INTROSPECTION_SESSION: SessionOptions = {
+  readOnly: true,
+  isolation: 'repeatable read',
+  searchPath: CANONICAL_SEARCH_PATH,
+};
+
+/**
+ * A `SessionRunner` over a transaction the CALLER already opened.
+ *
+ * Some venues are inside a transaction before they introspect, and must be: the reconcile
+ * apply re-reads the catalog inside its own DDL transaction so provenance records the def
+ * hashes of what the batch actually created, not what it hoped to. Handing those a runner
+ * that opens its own transaction would issue a nested `BEGIN` and — worse — COMMIT the
+ * caller's transaction when it finished.
+ *
+ * So this borrows the open transaction instead of opening one. The session guarantee still
+ * holds, and holds MORE strongly: the statements share the caller's connection and its
+ * transaction by construction, and they can see its uncommitted writes.
+ *
+ * Two consequences, stated rather than hidden:
+ *
+ * - `isolation` and `readOnly` are NOT applied, because `SET TRANSACTION` only takes effect
+ *   before a transaction's first statement. They are already fixed — by the caller, who
+ *   opened the transaction and chose them. This is not a guarantee that degraded; it is the
+ *   same guarantee supplied by the enclosing transaction.
+ * - The `searchPath` pin runs inside a SAVEPOINT that is ALWAYS rolled back. `SET LOCAL`
+ *   lasts to the end of its transaction, so pinning without unwinding would silently
+ *   re-point the rest of the caller's transaction — the reconcile apply deliberately runs
+ *   its creates under a WIDE path, and stealing it back would be a new bug of exactly the
+ *   shape this whole change removes. Rolling back to the savepoint undoes the SET LOCAL and
+ *   costs nothing: every statement here is a read, and its rows are already in hand.
+ */
+export function borrowedSessionRunner(run: (sql: string) => Promise<any[]>): SessionRunner {
+  return async (statements, opts) => {
+    const stmts = statements.map((s) => (typeof s === 'string' ? { sql: s } : s));
+    const results: SessionResult[] = [];
+    const pinned = opts?.searchPath !== undefined;
+    const outer = 'everystack_borrowed_session';
+
+    if (pinned) {
+      await run(`SAVEPOINT ${outer}`);
+      await run(buildSearchPathSql(String(opts!.searchPath)));
+    }
+    try {
+      for (let i = 0; i < stmts.length; i++) {
+        const stmt = stmts[i];
+        if (!stmt.allowFailure) {
+          results.push(await run(stmt.sql));
+          continue;
+        }
+        const inner = `everystack_borrowed_${i}`;
+        await run(`SAVEPOINT ${inner}`);
+        try {
+          results.push(await run(stmt.sql));
+          await run(`RELEASE SAVEPOINT ${inner}`);
+        } catch (err: any) {
+          await run(`ROLLBACK TO SAVEPOINT ${inner}`);
+          results.push({ everystackSessionError: true, message: err?.message || String(err) });
+        }
+      }
+    } finally {
+      // Unconditional: the pin must not outlive this read on ANY path, success or throw.
+      if (pinned) await run(`ROLLBACK TO SAVEPOINT ${outer}`);
+    }
+    return results;
+  };
+}
+
+/** A bare SQL identifier — the only shape a search_path element may take. */
+const PLAIN_IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+/**
+ * `SET LOCAL search_path` for a caller-supplied path, validated as plain identifiers. One
+ * definition for every venue — a path one venue pins and another rejects would be a
+ * difference in what "the live state" means. `$user` is deliberately not accepted: a
+ * role-dependent element would make a canonical capture depend on who read it.
+ */
+export function buildSearchPathSql(searchPath: string): string {
+  const parts = searchPath.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+  if (parts.length === 0) throw new Error('searchPath must name at least one schema');
+  for (const part of parts) {
+    if (!PLAIN_IDENT.test(part)) {
+      throw new Error(
+        `searchPath element ${JSON.stringify(part)} is not a plain identifier — a session pins only bare schema names`,
+      );
+    }
+  }
+  return `SET LOCAL search_path = ${parts.map((p) => `"${p}"`).join(', ')}`;
+}
+
+/** True when a slot carries an allowed statement's failure rather than its rows. */
+export function isSessionError(slot: SessionResult | undefined): slot is SessionStatementError {
+  return (
+    !!slot && !Array.isArray(slot) && (slot as SessionStatementError).everystackSessionError === true
+  );
+}
+
+/** A slot's rows — an allowed failure reads as no rows. Use where absence is the answer. */
+export function rowsOrEmpty(slot: SessionResult | undefined): any[] {
+  if (slot === undefined || isSessionError(slot)) return [];
+  return slot;
+}