@everystack/cli 0.4.56 → 0.4.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.56",
+  "version": "0.4.57",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -109,7 +109,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.15"
+    "@everystack/model": "0.4.16"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",
@@ -159,7 +159,8 @@
     "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
     "react": "19.2.0",
-    "ts-jest": "29.4.9"
+    "ts-jest": "29.4.9",
+    "@everystack/server": "0.4.20"
   },
   "scripts": {
     "test": "jest",

package/src/cli/authz-derive.ts

@@ -260,6 +260,44 @@ function effective(contract: TableContract, role: string, priv: string): boolean
   return policiesFor(contract, role, priv).some((p) => p.permissive);
 }
 
+/** The four CRUD privileges, in the order the deriver reports them. */
+const CRUD_PRIVS = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'] as const;
+
+/**
+ * Classify every (role, privilege) surface ONCE: may pull render it as an ABILITY, or must it
+ * be transcribed as a grant?
+ *
+ * A DIFFERENT question from {@link effective}, and conflating them is what broke the RLS-off
+ * shape. `effective` answers "does this grant reach rows?" — with RLS off the honest answer is
+ * YES, unrestricted. But the RENDERER is asking whether it may say `can(...)`, and an ability
+ * compiles to a policy. On a table with row security disabled, rendering one makes the model
+ * propose `ALTER TABLE … ENABLE ROW LEVEL SECURITY` plus `CREATE POLICY …` against a database
+ * that has neither, and REVOKE whatever privilege the ability has no room for — three changes
+ * emitted by a command that only READ the database. That is the G1 class (a manufactured
+ * policy) reached from the adoption side, and the round-trip gate refuses it.
+ *
+ * So with RLS OFF nothing is an ability; the grants are still declared, through `privileges`,
+ * which is precisely what the governed-role path already did. That asymmetry — foreign roles
+ * transcribed, vocabulary roles turned into abilities — WAS the bug; there is one rule now.
+ *
+ * Computed as one pass returning a tag per surface, rather than a predicate each site calls,
+ * so a future ability-emitting site cannot quietly skip the question (Fable, 2026-08-11).
+ *
+ * Lives here, in the pull/derive direction only. The COMPILER must never consult it: compile
+ * turns declarations into SQL and has no business knowing how they were rendered.
+ */
+function classifyAbilitySurfaces(contract: TableContract): ReadonlySet<string> {
+  const surfaces = new Set<string>();
+  // Grants-only table: every surface is a grant, none is an ability.
+  if (!contract.rls.enabled) return surfaces;
+  for (const role of Object.keys(contract.grants)) {
+    for (const priv of CRUD_PRIVS) {
+      if (effective(contract, role, priv)) surfaces.add(`${role}:${priv}`);
+    }
+  }
+  return surfaces;
+}
+
 /** A sql`…` fragment literal, or null when the predicate is vacuous. */
 function sqlFragment(pred: string | null): string | null {
   if (!pred) return null;
@@ -339,6 +377,9 @@ export function deriveAbilities(
   opts: { governRoles?: ReadonlySet<string> } = {},
 ): DerivedAbilities {
   const govern = opts.governRoles ?? new Set<string>();
+  /** One classification pass; every ability-vs-grant decision below reads this tag. */
+  const abilitySurfaces = classifyAbilitySurfaces(contract);
+  const isAbilitySurface = (role: string, priv: string): boolean => abilitySurfaces.has(`${role}:${priv}`);
   const abilities: string[] = [];
   const notes: string[] = [];
   const table = contract.table;
@@ -365,7 +406,7 @@ export function deriveAbilities(
   // non-owner, and RLS binds non-owners whenever `enabled` is true. `forced` is irrelevant here.
   const CRUD = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'];
   const adminGrants = CRUD.filter((p) => granted(contract, 'admin', p));
-  const adminLive = adminGrants.filter((p) => effective(contract, 'admin', p));
+  const adminLive = adminGrants.filter((p) => isAbilitySurface('admin', p));
   const adminDead = adminGrants.filter((p) => !adminLive.includes(p));
 
   if (adminLive.length === CRUD.length) {
@@ -402,7 +443,7 @@ export function deriveAbilities(
   // declared (so the plan does not REVOKE a live privilege) and never rendered as an ability
   // (so the plan does not CREATE the policy the database is missing).
   for (const role of ['authenticated', 'anon']) {
-    const dead = CRUD.filter((p) => granted(contract, role, p) && !effective(contract, role, p));
+    const dead = CRUD.filter((p) => granted(contract, role, p) && !isAbilitySurface(role, p));
     if (!dead.length) continue;
     deadGrants[role] = dead;
     notes.push(`${role} holds ${dead.join(', ')} but no policy covers ${role} —`);
@@ -444,8 +485,8 @@ export function deriveAbilities(
   // `effective`, not `granted`: a SELECT grant with no policy behind it renders can('read'),
   // which compiles to CREATE POLICY … USING (true) — manufacturing a policy the database does
   // not have. Same defect as the admin branch above; the round-trip gate found it here.
-  const anonRead = effective(contract, 'anon', 'SELECT');
-  const authedRead = effective(contract, 'authenticated', 'SELECT');
+  const anonRead = isAbilitySurface('anon', 'SELECT');
+  const authedRead = isAbilitySurface('authenticated', 'SELECT');
 
   if (anonRead) {
     // Public read. If the live policy narrows it (a soft-delete guard, a published flag),
@@ -569,7 +610,7 @@ export function deriveAbilities(
   // --- writes --------------------------------------------------------------------------
   for (const [command, action] of Object.entries(DML)) {
     if (action === 'read') continue;
-    if (!effective(contract, 'authenticated', command)) continue;
+    if (!isAbilitySurface('authenticated', command)) continue;
 
     const pol = policiesFor(contract, 'authenticated', command).find((p) => p.command !== 'ALL')
       ?? policiesFor(contract, 'authenticated', command)[0];

package/src/cli/commands/db-apply.ts

@@ -75,6 +75,10 @@ export function descentVerdictForApply(verdict: DescentVerdict): { ok: true } |
       return { ok: true };
     case 'diverged':
     case 'drift':
+    // `indeterminate` refuses like the others, and must: the search was not exhaustive, so
+    // the fast-forward rule is unproven. Its REASON is the difference — it points at this
+    // run, not at the database. Never fold it into `drift`.
+    case 'indeterminate':
       return { ok: false, reason: verdict.reason };
   }
 }
@@ -178,6 +182,12 @@ async function applyPlanViaStage(
         case 'diverged':
         case 'drift':
           break; // the reason travels to the action's refusal + the memoir
+        case 'indeterminate':
+          // Said out loud here because the operator's next move is "run it again", not
+          // "reconcile your models" — and a refusal that reads like drift sends them the
+          // wrong way. The reason still travels to the refusal.
+          warn(`descent: ${verdict.unevaluated.length} historical tree(s) could not be extracted — the search was not exhaustive.`);
+          break;
       }
       descentVerdict = descentVerdictForApply(verdict);
     }
@@ -437,6 +447,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
               return { ok: true };
             case 'diverged':
             case 'drift':
+            case 'indeterminate':
               return { ok: false, reason: verdict.reason };
           }
         },

package/src/cli/commands/db-plan.ts

@@ -279,9 +279,26 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     // work — say so on the review surface, where a human still reads it.
     if (plan.statements.length > 0) {
       const verdict = await verifyDescent(modelsPath, { snapshot, contract }, {});
-      if (verdict.status === 'diverged' || verdict.status === 'drift') {
-        warn(`descent: ${verdict.reason}`);
-        warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
+      // A switch, not an `if (diverged || drift)`. That form silently ignored every verdict
+      // it did not name, so `indeterminate` would have minted a plan with no warning at all
+      // and then been refused at apply time with no hint of why. Exhaustive here means a new
+      // verdict cannot be forgotten.
+      switch (verdict.status) {
+        case 'ok':
+        case 'fresh-target':
+        case 'no-git':
+          break;
+        case 'diverged':
+        case 'drift':
+          warn(`descent: ${verdict.reason}`);
+          warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
+          break;
+        case 'indeterminate':
+          // NOT "rebase first" — nothing is wrong with the checkout or the database. The
+          // search failed, so the rule is unproven either way.
+          warn(`descent: ${verdict.reason}`);
+          warn('db:apply from this checkout will refuse this plan until that search completes — re-mint and try again.');
+          break;
       }
     }
 

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/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

@@ -21,6 +21,10 @@ 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
@@ -127,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) {
@@ -144,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 });
@@ -159,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 {
@@ -171,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),
+  };
 }
 
 /**
@@ -210,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`),
@@ -594,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