@everystack/cli 0.4.55 → 0.4.57

package/src/cli/derived-render.ts

@@ -208,6 +208,110 @@ function parseArgs(args: string): ParsedArg[] | null {
   return out;
 }
 
+/**
+ * The role-name shape `defineFunction` accepts (packages/model derived.ts OWNER_ROLE_NAME).
+ * The owner is interpolated into `SET ROLE` / `ALTER … OWNER TO`, so anything else is refused
+ * at declaration — which means rendering it here would emit source that throws on import.
+ */
+const RENDERABLE_ROLE = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * An object that RUNS AS ITS OWNER, and the sentence that says so.
+ *
+ * Two shapes qualify, and they are the same hazard one object apart: a `SECURITY DEFINER`
+ * function, and a view with `security_invoker = false`. For both, an owner nobody chose is a
+ * live privilege surface, so the FIXME is loud and the warning reaches stderr.
+ */
+export interface ElevatedRights {
+  /** How the object declares it — `'SECURITY DEFINER'`, `'not securityInvoker'`. */
+  posture: string;
+  /** What runs as the owner — `'Every call'`, `'Every read through it'`. */
+  what: string;
+}
+
+export const SECURITY_DEFINER_RIGHTS: ElevatedRights = { posture: 'SECURITY DEFINER', what: 'Every call' };
+export const DEFINER_VIEW_RIGHTS: ElevatedRights = { posture: 'not securityInvoker', what: 'Every read through it' };
+export const MATVIEW_RIGHTS: ElevatedRights = { posture: 'a materialized view', what: 'Every REFRESH' };
+
+/**
+ * What db:pull says about an object's OBSERVED owner: render it, or flag it.
+ *
+ * Ownership is a privilege boundary, so a pulled model that stays silent about it reproduces
+ * the wrong database. But rendering EVERY observed owner is worse than saying nothing: on a
+ * brownfield database most objects are owned by whoever ran the migration, and writing
+ * `owner: 'postgres'` into the models would BLESS that accident — converting an unreviewed
+ * superuser-owned SECURITY DEFINER function into fingerprinted, reproducible design.
+ *
+ * So the discriminator is the AMBIENT BUILD CREDENTIAL, two clauses and no more: the owner is
+ * a superuser, or it is the role this pull connected as. Neither → a deliberately chosen
+ * principal → render it. Either → a FIXME naming the observed owner, loud when the object runs
+ * as its owner. The defect stays visible without being ratified.
+ *
+ * This also settles the portability objection: the roles whose names legitimately differ
+ * between a dev machine, a deployed master and a normalized operator ARE the operator tier —
+ * exactly the tier this declines to render.
+ *
+ * A15 — ONE discriminator for functions AND relations. The rule is identical and the reason is
+ * identical; two copies of it is how the view half ends up subtly different from the function
+ * half, which is the defect this whole plan keeps finding.
+ */
+export function renderedOwner(
+  o: Pick<LiveObject, 'identity' | 'owner' | 'ownerIsSuperuser' | 'ownerIsConnectedRole'>,
+  elevated: ElevatedRights | null,
+): { prop?: string; fixme?: string; warning?: string } {
+  const owner = o.owner;
+  // Not measured. A pre-owner catalog read carries no owner at all, and absent evidence is
+  // not evidence of a problem — say nothing, exactly as before.
+  if (owner === undefined) return {};
+
+  const superuser = o.ownerIsSuperuser;
+  const connected = o.ownerIsConnectedRole;
+  const ambient: string[] = [];
+  if (superuser === true) ambient.push('a superuser');
+  if (connected === true) ambient.push('the role db:pull connected as');
+
+  if (!ambient.length && superuser !== undefined && connected !== undefined) {
+    // A chosen principal. Render it — unless PostgreSQL's name is one defineFunction refuses,
+    // in which case rendering would emit source that throws on import.
+    if (!RENDERABLE_ROLE.test(owner)) {
+      const why = `${o.identity}: owner '${owner}' is not a bare lowercase role name, which is all the model's owner property accepts (it is interpolated into SET ROLE) — ownership NOT declared. Rename the role, or declare the owner by hand.`;
+      return { fixme: `// FIXME: ${why}`, warning: why };
+    }
+    return { prop: `owner: ${tsString(owner)},` };
+  }
+
+  if (!ambient.length) {
+    // Owner known, discriminator not measured. Refuse to classify rather than guess.
+    return {
+      fixme: `// FIXME: ${o.identity} is owned by '${owner}', but this pull could not tell whether that is a chosen principal or the build credential — owner is NOT declared. Add owner: '${owner}' if that role is the intended owner.`,
+    };
+  }
+
+  const because = ambient.join(' and ');
+  // The runs-as-owner case is the one that reaches stderr as well as the file: it is a live
+  // privilege-escalation surface, not a style note. The plain case stays an inline FIXME —
+  // on a brownfield database it is the common shape, and echoing all of it would bury the rest.
+  return elevated
+    ? {
+      fixme: `// FIXME SECURITY: ${o.identity} is ${elevated.posture} and owned by '${owner}' — ${because}. ${elevated.what} runs with that role's privileges. The observed owner is NOT declared, because declaring the build credential would make the accident reproducible; declare the intended owner with owner: '<role>'.`,
+      warning: `${o.identity}: ${elevated.posture}, owned by '${owner}' (${because}) — ${elevated.what.toLowerCase()} runs with that role's privileges. Ownership was NOT declared; declare the intended owner with owner: '<role>'.`,
+    }
+    : {
+      fixme: `// FIXME: ${o.identity} is owned by '${owner}' — ${because}, not a chosen principal, so ownership is NOT declared. Add owner: '<role>' if a specific role should own it.`,
+    };
+}
+
+/**
+ * The A4 spelling, kept so existing callers and tests read unchanged. `renderedOwner` is the
+ * implementation; this is the function-shaped door onto it.
+ */
+export function renderedFunctionOwner(
+  o: Pick<LiveObject, 'identity' | 'owner' | 'ownerIsSuperuser' | 'ownerIsConnectedRole'>,
+  secdef: boolean,
+): { prop?: string; fixme?: string; warning?: string } {
+  return renderedOwner(o, secdef ? SECURITY_DEFINER_RIGHTS : null);
+}
+
 /** One matview index attachment → the Brick E builder chain, or null (FIXME). */
 function renderIndexBuilder(indexdef: string): string | null {
   const parsed = parseIndexDefinition(indexdef);
@@ -469,6 +573,24 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       const props: string[] = [];
       const hasPrivileges = Object.keys(privileges).length > 0;
       if (o.kind === 'view') props.push(`securityInvoker: ${o.securityInvoker === true},`);
+      // A15 — the owner, through the SAME discriminator functions use. Elevated exactly when
+      // the relation runs as its owner: a view that is not securityInvoker, and a matview
+      // always (its rows are computed at REFRESH time with the owner's rights, no exceptions).
+      const relationOwnership = renderedOwner(
+        o,
+        o.kind === 'materialized view' ? MATVIEW_RIGHTS
+          : o.securityInvoker === false ? DEFINER_VIEW_RIGHTS
+            : null,
+      );
+      if (relationOwnership.prop) props.push(relationOwnership.prop);
+      if (relationOwnership.fixme) fixmes.push(relationOwnership.fixme);
+      // The FIXME lands in the file, at the declaration, which is where the operator acts on
+      // it. The stderr WARNING is deliberately NOT raised for relations: `SECURITY DEFINER` is
+      // opt-in and rare, so echoing those is signal, but `security_invoker = false` is
+      // PostgreSQL's DEFAULT for views — on any real database nearly every view and every
+      // matview qualifies, and promoting all of them would bury the function findings the
+      // channel exists for. Same judgement the function branch already makes for its plain
+      // case, applied where the base rate is inverted.
       // `private: true` means "declared dark, no grants" — it contradicts a recorded
       // grant, and the model refuses the pair. A relation whose only reach is recorded
       // (PUBLIC SELECT, or a write grant) is not dark; it just has no CHOSEN audience.
@@ -516,6 +638,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     const roleGrants = Object.keys(grants).filter((r) => r.toUpperCase() !== 'PUBLIC').sort();
     const publicExec = Object.keys(grants).some((r) => r.toUpperCase() === 'PUBLIC');
     const args = f && (f.language === 'sql' || f.language === 'plpgsql') ? parseArgs(f.args) : null;
+    const ownership = renderedFunctionOwner(o, f?.secdef === true);
 
     if (!f || args === null || (f.language !== 'sql' && f.language !== 'plpgsql')) {
       warnings.push(`${o.identity}: signature beyond the v1 vocabulary (${f ? `language ${f.language}, args '${f.args}'` : 'no structured fields'}) — rendered as defineSql.`);
@@ -523,6 +646,14 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       // collapse to one provenance row here too — the declared name carries the signature
       // (the drop is explicit, so the name is a label, and a unique one is what it needs).
       const sqlName = declaredName(o) + (f?.identityArgs !== undefined ? `(${f.identityArgs})` : '');
+      // A defineSql object cannot carry an owner. Where the pull observed a CHOSEN owner that
+      // is real fidelity loss, so it is said out loud on both surfaces — never dropped. An
+      // ambient owner needs no note here: there is nothing to declare and nothing was lost.
+      if (ownership.prop) {
+        const why = `${o.identity}: owned by '${o.owner}', but defineSql cannot declare an owner — the build will create it as the connecting role. Move it into defineFunction's vocabulary, or set the owner by hand after the build.`;
+        warnings.push(why);
+        lines.push(`// FIXME: ${why}`);
+      }
       lines.push(
         `// FIXME: ${o.identity} — signature beyond defineFunction's v1 vocabulary; kept verbatim as defineSql.`,
         `export const ${varName} = defineSql(${tsString(sqlName)}, {`,
@@ -548,11 +679,30 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     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);
+    if (f.secdef) props.push(`security: 'definer',`);
+    // THE PIN IS READ, NEVER INVENTED.
+    //
+    // This used to render `searchPath: ['pg_catalog']` for any definer function whose live
+    // proconfig was empty. A build from those models then applied the invented pin for real, so
+    // functions that had always resolved `public` stopped resolving it — sign-up and password
+    // change died on a database built from the consumer's own models, with every gate green.
+    // 34 of their 34 pinned-in-the-model functions were unpinned in the database.
+    //
+    // A live pin renders as the array. No live pin on a definer function renders the explicit
+    // `'unpinned'` sentinel — an ANSWER, not silence, so `defineFunction` still throws for the
+    // author who simply forgot. No live pin on an invoker function renders nothing, which
+    // already means exactly that.
+    if (f.searchPath) {
+      const path = f.searchPath.split(',').map((s) => s.trim().replace(/^"|"$/g, '')).filter(Boolean);
       props.push(`searchPath: [${path.map(tsString).join(', ')}],`);
+    } else if (f.secdef) {
+      props.push(`searchPath: 'unpinned',`);
     }
+    // Ownership sits beside security because it IS the other half of it: `security: 'definer'`
+    // says the function runs as its owner, and this says who that is.
+    if (ownership.prop) props.push(ownership.prop);
+    if (ownership.fixme) fixmes.push(ownership.fixme);
+    if (ownership.warning) warnings.push(ownership.warning);
     if (roleGrants.length) {
       props.push(`abilities: [${roleGrants.map((r) => `can('execute', { role: ${tsString(r)} })`).join(', ')}],`);
       need('can');

package/src/cli/derived-source.ts

@@ -60,6 +60,30 @@ export interface SourceObject {
   file: string;
   /** Position in the concatenated source — a valid dependency order by convention. */
   seq: number;
+  /**
+   * kind 'function' only: the declared owning role.
+   *
+   * A SECURITY DEFINER function executes with its OWNER's rights, so this is a privilege
+   * boundary. The applier enacts it by running the CREATE under `SET ROLE <owner>` rather
+   * than following it with `ALTER … OWNER TO`: measured on PG16, once ownership has moved the
+   * builder gets "must be owner of function" on the next `CREATE OR REPLACE`, so the
+   * alter-after form works exactly once and breaks every re-run.
+   */
+  owner?: string;
+  /**
+   * kind 'function' only: the declared `SET search_path`, or the sentinel `'unpinned'`.
+   *
+   * It is already inside `sql`, so this is NOT in the hash and changes no fingerprint. It rides
+   * structurally so the differ can compare the declared pin against the LIVE catalog directly
+   * rather than only against a recorded hash. Without that, `--baseline` records a declared pin
+   * the database does not have and every later check reports zero actions, forever: measured,
+   * and it is how a model came to claim `search_path=pg_catalog` about a database with none
+   * while every gate stayed green.
+   *
+   * `undefined` means NOT DECLARED — a parser-era db/sql object, or an invoker function with no
+   * pin. The comparison is skipped there; absent evidence is not evidence.
+   */
+  searchPath?: string[] | 'unpinned';
   /** 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. */
@@ -82,9 +106,15 @@ 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 {
+export function hashSourceContent(createSql: string, attachments: Attachment[], owner?: string): string {
   const content = [normalizeSql(createSql), ...attachments.map((a) => normalizeSql(a.sql))].join('\n');
-  return createHash('sha256').update(content).digest('hex');
+  // Ownership is part of the declared state — a SECURITY DEFINER function that changes owner
+  // changes who it executes as, which is a rebuild, not an authz delta. It is folded in as a
+  // PREFIX only when declared, so every object without an owner hashes byte-identically to
+  // before this existed. That is deliberate: a consumer mid-adoption must not be forced into a
+  // second fingerprint re-mint in a week by a field they do not use.
+  const body = owner ? `-- owner: ${owner}\n${content}` : content;
+  return createHash('sha256').update(body).digest('hex');
 }
 
 /** A raw file the generic dir readers return (db/backfills, seed lanes). */

package/src/cli/git-descent.ts

@@ -49,6 +49,14 @@ export interface DescentOptions {
   /** The Postgres schema the Models default to. Default: `public`. */
   schema?: string;
   loader?: ModelsLoader;
+  /**
+   * How a tree is extracted. Default: {@link materializeTree}.
+   *
+   * Injected for the same reason `loader` is: an in-module call goes through the local
+   * binding, so it cannot be spied on, and extraction failure is a condition that MUST be
+   * covered by a test — it is the one that used to be misreported as database drift.
+   */
+  materialize?: (tree: string, dest: string, cwd: string) => void;
   /**
    * Where historical trees materialize. Default: a fresh temp dir under the
    * repo's node_modules — bare imports (`@everystack/model`) must resolve
@@ -69,7 +77,15 @@ export type DescentVerdict =
   /** The declaring commits exist but none is an ancestor of HEAD — rebase first. */
   | { status: 'diverged'; commits: string[]; tree: string; reason: string }
   /** No committed models state declares the live fingerprint — operator decision. */
-  | { status: 'drift'; scannedTrees: number; compileFailures: string[]; reason: string };
+  | { status: 'drift'; scannedTrees: number; compileFailures: string[]; reason: string }
+  /**
+   * One or more trees could not be EVALUATED at all — extraction or IO failed, so "no tree
+   * declares this state" is not a conclusion we are entitled to draw. Distinct from `drift`
+   * because the operator's next move is different: retry, not `db:pull`.
+   *
+   * `unevaluated` names the trees and why each failed.
+   */
+  | { status: 'indeterminate'; scannedTrees: number; unevaluated: string[]; reason: string };
 
 export interface ModelTreeCandidate {
   /** The models directory's tree oid — the identity of a declared state. */
@@ -134,14 +150,33 @@ export function enumerateModelTrees(modelsDir: string, cwd: string): ModelTreeCa
   return order.map((tree) => ({ tree, commits: byTree.get(tree)! }));
 }
 
-/** Extract a tree into `dest` — `git archive` piped to tar, no shell. */
+/**
+ * Extract a tree into `dest`, via a temporary archive FILE — never a pipe.
+ *
+ * This used to buffer `git archive` into memory (512MB `maxBuffer`) and hand that buffer to
+ * `tar` as `input`. `execFileSync` writes the whole buffer to the child's stdin, so if the
+ * child is not draining it the write fails with **EPIPE** — and under a loaded machine it
+ * does. Measured 2026-08-11 on a full-repo run: `spawnSync tar EPIPE`, recorded against a
+ * historical tree, twice in four runs.
+ *
+ * It failed badly, not loudly: `verifyDescent` recorded it as a COMPILE failure and returned
+ * `drift`, telling the operator their database had been hand-edited. See the `indeterminate`
+ * verdict for that half of the fix; this is the half that stops the failure happening.
+ *
+ * `git archive -o` writes the archive itself and `tar -xf <file>` reads it — two independent
+ * processes, no shared pipe, no backpressure to lose, and no multi-hundred-MB buffer through
+ * the parent. Retrying the pipe harder would only have made it rarer.
+ */
 export function materializeTree(tree: string, dest: string, cwd: string): void {
   fs.mkdirSync(dest, { recursive: true });
-  const archive = execFileSync('git', ['archive', '--format=tar', tree], {
-    cwd,
-    maxBuffer: 512 * 1024 * 1024,
-  });
-  execFileSync('tar', ['-xf', '-', '-C', dest], { input: archive });
+  // Sibling of `dest`, not inside it — a file under `dest` would be extracted over.
+  const archivePath = `${dest}.tar`;
+  try {
+    execFileSync('git', ['archive', '--format=tar', '-o', archivePath, tree], { cwd });
+    execFileSync('tar', ['-xf', archivePath, '-C', dest]);
+  } finally {
+    fs.rmSync(archivePath, { force: true });
+  }
 }
 
 /**
@@ -181,39 +216,60 @@ export async function verifyDescent(
     ?? fs.mkdtempSync(path.join(fs.existsSync(nodeModules) ? nodeModules : os.tmpdir(), '.everystack-descent-'));
   const ownsRoot = !opts.materializeRoot;
   const loader = opts.loader ?? defaultLoader;
+  const materialize = opts.materialize ?? materializeTree;
 
   const compileFailures: string[] = [];
+  const unevaluated: string[] = [];
   const declaringButDiverged: ModelTreeCandidate[] = [];
   try {
     for (const candidate of candidates) {
       const dest = path.join(materializeRoot, candidate.tree);
-      let declares: boolean;
-      // 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 where = `${short(candidate.tree)} (at ${short(candidate.commits[0])})`;
+
+      // TWO KINDS OF FAILURE, and conflating them is what made this path lie.
       //
+      // EXTRACTION failing says nothing about the tree — we never saw it. It was recorded as a
+      // "compile failure" and the verdict fell through to `drift`, which tells an operator
+      // their database was hand-edited. Observed for real: `spawnSync tar EPIPE` under a loaded
+      // machine. Those trees now go to `unevaluated` and produce `indeterminate`.
+      //
+      // COMPILING failing IS a property of the tree — a models file that no longer builds
+      // against today's @everystack/model is genuinely unusable, deterministically, and
+      // skipping it is correct. Those keep `compileFailures` and still allow `drift`.
+      //
+      // Each gets ONE retry from a clean materialization first, because either can also be
+      // transient under load.
+      try {
+        if (!fs.existsSync(dest)) materialize(candidate.tree, dest, repoRoot);
+      } catch {
+        try {
+          fs.rmSync(dest, { recursive: true, force: true });
+          materialize(candidate.tree, dest, repoRoot);
+        } catch (err: any) {
+          unevaluated.push(`${where}: could not extract — ${err.message}`);
+          continue;
+        }
+      }
+
       // The declares-test is GOVERNED on both sides, per candidate: the commit's
       // models define the governed set, and the live hash is filtered through the
       // SAME set as the prediction — comparing a governed prediction against the
       // raw live hash can never match on a brownfield target with foreign roles.
-      const attempt = async (): Promise<boolean> => {
-        if (!fs.existsSync(dest)) materializeTree(candidate.tree, dest, repoRoot);
+      const evaluate = async (): Promise<boolean> => {
         const models = await loader(path.join(dest, barrel));
         const governedRoles = governedRolesForModels(models);
         const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema, governedRoles });
         return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
       };
+      let declares: boolean;
       try {
         try {
-          declares = await attempt();
+          declares = await evaluate();
         } catch {
-          fs.rmSync(dest, { recursive: true, force: true });
-          declares = await attempt();
+          declares = await evaluate();
         }
       } catch (err: any) {
-        compileFailures.push(`${short(candidate.tree)} (at ${short(candidate.commits[0])}): ${err.message}`);
+        compileFailures.push(`${where}: ${err.message}`);
         continue;
       }
       if (!declares) continue;
@@ -254,6 +310,22 @@ export async function verifyDescent(
     };
   }
 
+  // Nothing matched — but if a tree was never evaluated, "nothing matched" is a claim we
+  // cannot make. The unevaluated one could be the declaring tree. Reported BEFORE drift
+  // because drift accuses the database, and this condition is about our own run.
+  if (unevaluated.length > 0) {
+    return {
+      status: 'indeterminate',
+      scannedTrees: candidates.length,
+      unevaluated,
+      reason:
+        `${unevaluated.length} of ${candidates.length} historical tree(s) could not be extracted, ` +
+        'so the search was not exhaustive and one of them may be the commit that declares this state. ' +
+        'This is a fault in THIS run, not evidence about the database — retry, and if it persists ' +
+        `check disk space and open-file limits. Details: ${unevaluated.join('; ')}`,
+    };
+  }
+
   const failureNote = compileFailures.length > 0
     ? ` (${compileFailures.length} historical tree(s) no longer compile and were skipped)`
     : '';

package/src/cli/migration-generate.ts

@@ -76,6 +76,9 @@ export const HELD_DROP_PREFIX = '-- DROP held back';
  */
 function isRemoval(change: SchemaChange, replacedConstraints: Set<string>): boolean {
   if (change.kind === 'dropColumn' || change.kind === 'dropTable' || change.kind === 'dropType' || change.kind === 'dropIndex') return true;
+  // DROP IDENTITY destroys the backing sequence and its counter — a removal, not a change.
+  // ADD/SET GENERATED are not: they create or retune the auto-value and lose nothing.
+  if (change.kind === 'setIdentity' && change.identity == null) return true;
   if (change.kind === 'dropConstraint') return !replacedConstraints.has(`${change.table}::${change.name}`);
   return false;
 }

package/src/cli/model-api.ts

@@ -35,6 +35,30 @@ export * from './authz-owner-probe.js';
 // --- the SECDEF function catalog the contract introspection needs -----------
 export { FUNCTIONS_SQL, catalogFunctionToDescriptor } from './security-catalog.js';
 
+// --- how you HAND a database to the VERIFY calls ---------------------------
+// `introspectSchema` and `introspectContract` take a `SessionRunner`, not a `QueryRunner`:
+// their queries must describe ONE moment, so they run as one transaction on one connection.
+// This barrel exported neither the type nor a way to build one, which left a consumer able
+// to CALL those functions with nothing legitimate to pass them. That gap is not academic —
+// the reference app's own dogfood suite kept passing a `QueryRunner` long after the
+// signature moved, and Postgres reported it as `syntax error at or near ","` (the array of
+// statements stringified) rather than as the type error it was.
+//
+// `sessionRunnerOver(sql)` wraps a postgres.js client whose pool is a SINGLE connection.
+// `INTROSPECTION_SESSION` is the options both introspections expect — read only, repeatable
+// read, canonical `search_path`. Pass it through; do not re-derive it.
+export { sessionRunnerOver } from './db-source.js';
+export {
+  INTROSPECTION_SESSION,
+  borrowedSessionRunner,
+  isSessionError,
+  rowsOrEmpty,
+  type SessionRunner,
+  type SessionStatement,
+  type SessionOptions,
+  type SessionResult,
+} from './session.js';
+
 // --- databases FROM the declared state: ephemeral test DBs + the builder ----
 // `createEphemeralDatabase(adminUrl, models, { sources })` is the packaged
 // create-sync-drop shape for consumer test suites: a fresh database at the

package/src/cli/model-render.ts

@@ -20,6 +20,11 @@ import type { DerivedRenderResult } from './derived-render.js';
 import type { TableContract } from './authz-contract.js';
 import { deriveAbilities, renderDerivedAbilities } from './authz-derive.js';
 import { normalizeDefault, normalizeCheck } from './schema-diff.js';
+import { generatedIndexName, generatedForeignKeyName } from './schema-compile.js';
+// The soft-delete RULE itself — one boolean combination, shared with `defineModel`'s refusal.
+// Only the FACT EXTRACTION is duplicated here (this renderer holds text, not descriptors);
+// the rule is not, so the two surfaces cannot drift on when a declaration is required.
+import { needsSoftDeleteDeclaration, privilegesGrantDelete } from '@everystack/model';
 
 /**
  * Reverse a CHECK predicate back into the `.validate(z…)` that produced it — the inverse of
@@ -126,13 +131,30 @@ export function isPublicReadAbility(expr: string): boolean {
   return !role || role[1] === 'anon';
 }
 
+/**
+ * A rendered ability that hands out DELETE — the TEXT form of `isDeleteAbility` from
+ * `@everystack/model`.
+ *
+ * The second fact the soft-delete rule turns on, and the one the old guard missed entirely.
+ * `manage` counts: it is "all actions" and compiles to the admin-bypass ALL policy, so it
+ * destroys rows exactly as `can('delete')` does.
+ *
+ * Same two-representations situation as its sibling above, for the same reason — this renderer
+ * only ever holds rendered source. The BOOLEAN RULE both facts feed is not duplicated here: it
+ * lives once in `needsSoftDeleteDeclaration`. Only the fact extraction is representation-
+ * specific, and the pin test drives both extractors over one ability matrix.
+ */
+export function isDeleteAbility(expr: string): boolean {
+  return /^can\('(delete|manage)'/.test(expr.trim());
+}
+
 /**
  * The scaffold stanza for one model, plus whether it declares a public read — the renderer
  * needs the second fact to decide the `softDelete` line, and it must come from the STRUCTURED
  * abilities, not a regex over the joined text (a live predicate can span lines and carry its
  * own braces). An unknown preset throws — grants are authored, never guessed.
  */
-function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<string, TableContract>, governRoles?: ReadonlySet<string>): { text: string; publicRead: boolean } {
+function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<string, TableContract>, governRoles?: ReadonlySet<string>): { text: string; publicRead: boolean; grantsDelete: boolean } {
   if (mode === 'live') {
     const contract = table && liveAuthz?.get(table.table);
     if (!contract) {
@@ -143,6 +165,7 @@ function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<stri
           '  // private: true,',
         ].join('\n'),
         publicRead: false,
+        grantsDelete: false,
       };
     }
     const derived = deriveAbilities(contract, { governRoles });
@@ -158,7 +181,13 @@ function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<stri
     if (!derived.abilities.length && !contract.rls.enabled) {
       lines.push(`  rls: false,   // live reality: row security is OFF — authorization here is grants-only.`);
     }
-    return { text: lines.join('\n'), publicRead: derived.abilities.some(isPublicReadAbility) };
+    return {
+      text: lines.join('\n'),
+      publicRead: derived.abilities.some(isPublicReadAbility),
+      // Both spellings. `privileges` is where pull puts a live DELETE grant no policy covers,
+      // which is precisely the shape that can hard-delete on an rls: false table.
+      grantsDelete: derived.abilities.some(isDeleteAbility) || privilegesGrantDelete(derived.privileges),
+    };
   }
   if (mode === 'commented') {
     return {
@@ -170,13 +199,18 @@ function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<stri
       ].join('\n'),
       // Nothing is stamped uncommented, so the model declares no read at all yet.
       publicRead: false,
+      grantsDelete: false,
     };
   }
   const preset = ABILITY_PRESETS[mode];
   if (!preset) {
     throw new Error(`Unknown --abilities preset '${mode}' — known: ${Object.keys(ABILITY_PRESETS).join(', ')} (or omit the flag for the commented scaffold).`);
   }
-  return { text: `  abilities: [${preset.join(', ')}],`, publicRead: preset.some(isPublicReadAbility) };
+  return {
+    text: `  abilities: [${preset.join(', ')}],`,
+    publicRead: preset.some(isPublicReadAbility),
+    grantsDelete: preset.some(isDeleteAbility),
+  };
 }
 
 /**
@@ -209,10 +243,41 @@ function writtenByStanza(table: TableSchema, liveAuthz?: Map<string, TableContra
     + `'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`;
+function softDeleteStanza(table: TableSchema, publicRead: boolean, grantsDelete: boolean): string {
+  const hasDeletedAtField = table.columns.some((c) => c.name === 'deleted_at');
+  if (!needsSoftDeleteDeclaration({ hasDeletedAtField, hasPublicRead: publicRead, grantsDelete })) return '';
+
+  // A PUBLIC read forces `false`, and the constraint is the fingerprint, not a preference:
+  // `true` AND-s `deleted_at IS NULL` into the anon policy, so rendering it would transcribe a
+  // predicate no live policy carries and the pulled checkout would MISMATCH the database it
+  // was pulled from. Live reality is what a pull is for.
+  if (publicRead) {
+    return `  softDelete: false, // live reality: no policy filters deleted_at, so false is what this database does.\n`
+      + `                     // true would AND deleted_at IS NULL into the public read policy — a predicate no live\n`
+      + `                     // policy carries, so it would MISMATCH the database this was pulled from. It would also\n`
+      + `                     // soften DELETE and hide marked rows from the data API. Change it deliberately, with a plan.\n`;
+  }
+
+  // No public read: the flag adds no POLICY (the compiler reads its guard only on the
+  // public-read branch), so either value fingerprints identically and introspection cannot
+  // recover which the app intended — a hard DELETE and a soft one leave the same schema.
+  //
+  // Fingerprint-neutral is NOT behaviour-neutral, and the comment must not imply it is: the
+  // generic data API also FILTERS soft-deleted rows out of reads. On a table where `deleted_at`
+  // is carried for audit rather than for deletion, adopting with `true` quietly drops rows from
+  // every listing — which is the same class of harm as the bug this rule exists to prevent,
+  // pointed the other way. So the comment states the full blast radius and asks the one
+  // question introspection cannot answer.
+  //
+  // `true` and not `false` because the worst cases are not symmetric: `true` hides rows
+  // recoverably (flip the flag; they were never destroyed, and they are still there over raw
+  // SQL), while `false` destroys data on the next DELETE and re-exposes rows the old
+  // application already treated as deleted. Irreversibility loses.
+  return `  softDelete: true, // ADOPTION DECISION — does deleted_at here mean DELETED, or merely audited?\n`
+    + `                    // true: DELETE marks deleted_at instead of destroying the row, AND the data API\n`
+    + `                    //       hides marked rows from reads (every role, unless ?deleted=include|only)\n`
+    + `                    //       and from updates. No RLS policy changes either way — there is no public read.\n`
+    + `                    // false: DELETE is permanent, marked rows stay visible. Set it if deleted_at is audit-only.\n`;
 }
 
 // The inverse type map lives with the vocabulary it inverts (`@everystack/model`),
@@ -459,10 +524,17 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
   let expr = call ?? verbatimFieldCall(col.type);
   let comment = call ? '' : ` // verbatim: no first-class field for '${col.type}' — carried as-is`;
 
+  // The auto-value the database actually holds. Rendered BEFORE .primaryKey()/.notNull() so a
+  // pulled surrogate key reads the way one is authored, and rendered at all because without it
+  // the rebuilt column has no auto-value and every INSERT that omits it fails NOT NULL.
+  if (col.identity) {
+    expr += col.identity === 'always' ? '.generatedAlwaysAsIdentity()' : '.generatedByDefaultAsIdentity()';
+  }
+
   const isPk = table.primaryKey.includes(col.name);
   if (isPk) expr += '.primaryKey()';
-  // A serial field is NOT NULL by construction, so the modifier would be redundant.
-  else if (col.notNull && !serial) expr += '.notNull()';
+  // A serial or identity field is NOT NULL by construction, so the modifier would be redundant.
+  else if (col.notNull && !serial && !col.identity) expr += '.notNull()';
 
   if (table.uniques.some((u) => u.columns.length === 1 && u.columns[0] === col.name)) expr += '.unique()';
 
@@ -473,7 +545,11 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
         fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
         fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
       ].filter(Boolean);
-      const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
+      // A8 — the FK's own name, said only when it is not the one the compiler would generate.
+    if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
+      actions.push(`name: ${tsLiteral(fk.name)}`);
+    }
+    const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
       expr += `.references(() => ${modelVarName(fk.refTable)}${opts})`;
     } else comment += ` // FK → ${fk.refTable} (not in the pulled set)`;
   }
@@ -528,6 +604,15 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
     if (ix.unique) s += '.unique()';
     if (ix.include?.length) s += `.include(${ix.include.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`;
     if (ix.where) s += `.where(sql\`${normalizeCheck(ix.where)}\`)`;
+    // A7 — keep the name the database actually has, but only say it when it is not the one the
+    // compiler would generate anyway. A brownfield schema arrives with its previous tooling's
+    // names (`index_contents_on_destination_id`), and rebuilding under ours renamed ~200 of one
+    // consumer's indexes: counts and definitions matched, so every gate stayed green while a
+    // planner regression test, runbooks and pg_stat_user_indexes history all broke. Declaring
+    // only the divergent ones keeps a greenfield pull clean and an adopted one faithful.
+    if (ix.name && ix.name !== generatedIndexName(bareName(table.table), ix.columns)) {
+      s += `.name(${tsLiteral(ix.name)})`;
+    }
     items.push(s);
   }
   for (const fk of table.foreignKeys) {
@@ -542,6 +627,10 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
       fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
       fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
     ].filter(Boolean);
+    // A8 — the FK's own name, said only when it is not the one the compiler would generate.
+    if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
+      actions.push(`name: ${tsLiteral(fk.name)}`);
+    }
     const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
     items.push(`foreignKey(${cols}, () => ${modelVarName(fk.refTable)}, ${refCols}${opts})`);
   }
@@ -569,7 +658,7 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   // put it, proving the position is mechanical-edit-friendly).
   const stanza = abilitiesStanza(abilities, table, liveAuthz, governRoles);
   const writtenBy = writtenByStanza(table, liveAuthz);
-  const softDelete = softDeleteStanza(table, stanza.publicRead);
+  const softDelete = softDeleteStanza(table, stanza.publicRead, stanza.grantsDelete);
 
   // A non-public table carries `schema:` — defineModel stores the name VERBATIM, so the
   // qualification cannot ride in the first argument (that would make the table literally