turbine-orm 0.57.0 → 0.58.0

package/dist/cjs/cli/index.js

@@ -83,6 +83,7 @@ const index_advisor_js_1 = require("../index-advisor.js");
 const index_stats_js_1 = require("../index-stats.js");
 const introspect_js_1 = require("../introspect.js");
 const plan_divergence_js_1 = require("../plan-divergence.js");
+const plan_flip_probe_js_1 = require("../plan-flip-probe.js");
 const schema_js_1 = require("../schema.js");
 const schema_sql_js_1 = require("../schema-sql.js");
 const config_js_1 = require("./config.js");
@@ -2383,9 +2384,18 @@ async function cmdDoctor(args, config) {
     // trustworthy stats_reset age because they normalize write counters by it;
     // this check reads no counter, only pg_stats, whose freshness is ANALYZE. A
     // cluster with a NULL stats_reset (the default) must still get the check.
-    const divergence = divergenceOn && snapshot.available
+    const scored = divergenceOn && snapshot.available
         ? (0, plan_divergence_js_1.findPlanDivergence)(schema, snapshot)
         : { findings: [], notices: [], candidatesConsidered: 0, consideredIndexed: 0, consideredUnindexed: 0 };
+    // Statistics can say how bad a flip WOULD be; only the planner can say whether
+    // it is reachable. The `unindexed-filter` branch shipped in 0.57 without that
+    // question answered and was right 6 times in 13 on a real schema, so every one
+    // of its findings is now put to a plan-only EXPLAIN. Nothing is executed, and a
+    // probe that fails keeps its finding rather than dropping it.
+    const flipProbe = divergenceOn && scored.findings.some(plan_flip_probe_js_1.needsFlipProbe)
+        ? await (0, plan_flip_probe_js_1.probePlanFlips)({ connectionString: url, schema: config.schema, findings: scored.findings })
+        : (0, plan_flip_probe_js_1.emptyFlipProbeResult)();
+    const divergence = (0, plan_flip_probe_js_1.applyFlipVerdicts)(scored, flipProbe);
     if (jsonMode) {
         spinner?.stop();
         console.log(JSON.stringify(buildDoctorJson({ schema, findings, invalid, snapshot, usable, heat, subtract, divergence, args }), null, 2));
@@ -2479,6 +2489,12 @@ function buildDoctorJson(ctx) {
         considered: ctx.divergence.candidatesConsidered,
         indexed: ctx.divergence.consideredIndexed,
         unindexed: ctx.divergence.consideredUnindexed,
+        // Whether the unindexed findings above were put to the planner, and how many
+        // it refuted. `flipProbed: false` means they are statistics-only and carry
+        // 0.57's precision, so a consumer can tell a verified list from an unverified
+        // one instead of inferring it from the count.
+        flipProbed: ctx.divergence.flipProbed === true,
+        flipRefuted: ctx.divergence.flipRefuted ?? 0,
     };
     return out;
 }
@@ -2801,6 +2817,19 @@ function renderDivergenceGates(divergence) {
     console.log(`  ${(0, ui_js_1.dim)(`${divergence.candidatesConsidered} column(s) were scored (${divergence.consideredIndexed} indexed, ${divergence.consideredUnindexed} unindexed). That population is relation-probe`)}`);
     console.log(`  ${(0, ui_js_1.dim)('and leading-index columns only: a filter column that is neither is not covered. Skip this')}`);
     console.log(`  ${(0, ui_js_1.dim)('section with --no-plan-divergence.')}`);
+    // Say whether the unindexed findings were verified, and what verification
+    // removed. Statistics can only say how bad a flip would be; a plan-only EXPLAIN
+    // says whether the planner can reach it at all.
+    if (divergence.flipProbed === true) {
+        const refuted = divergence.flipRefuted ?? 0;
+        const wereRefuted = refuted === 1 ? '1 was refuted' : `${refuted} were refuted`;
+        console.log(`  ${(0, ui_js_1.dim)(`Every unindexed finding was put to the planner (EXPLAIN, nothing executed); ${wereRefuted}`)}`);
+        console.log(`  ${(0, ui_js_1.dim)('because the generic plan keeps the same sequential scan, so no flip is reachable.')}`);
+    }
+    else if (divergence.consideredUnindexed > 0) {
+        console.log(`  ${(0, ui_js_1.dim)('Unindexed findings are UNVERIFIED here: the planner probe did not run, so some may name a')}`);
+        console.log(`  ${(0, ui_js_1.dim)('divergence the planner would never choose.')}`);
+    }
 }
 /** Round to a whole number and group it, for the divergence report's estimates. */
 function divInt(n) {

package/dist/cjs/plan-divergence.d.ts

@@ -424,6 +424,21 @@ export interface PlanDivergenceReport {
      */
     consideredIndexed: number;
     consideredUnindexed: number;
+    /**
+     * True when every `unindexed-filter` finding was put to the planner via
+     * `plan-flip-probe.ts` rather than reported on statistics alone.
+     *
+     * Absent or false means the findings below are UNVERIFIED: the probe was
+     * skipped, the engine is not Postgres, or the connection refused it.
+     */
+    flipProbed?: boolean;
+    /**
+     * How many candidate findings the planner refuted, i.e. columns where the
+     * generic plan keeps the same sequential scan the good plan uses so there is
+     * no divergence to reach. Reported because a check that silently discards two
+     * thirds of what it found should say so.
+     */
+    flipRefuted?: number;
 }
 /** A (table, column) pair whose distribution statistics the collector should read. */
 export interface DivergenceCandidate {

package/dist/cjs/plan-flip-probe.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Plan-flip probe: does the generic plan actually differ from the good one?
+ *
+ * ## Why this exists
+ *
+ * `plan-divergence.ts` scores a column from statistics alone and answers "IF the
+ * cached plan flips, how bad is it". Its `unindexed-filter` branch (0.57) shipped
+ * without an answer to the prior question, "CAN it flip at all", and that turned
+ * out to be the majority case: on a real 118-model schema the branch produced 39
+ * findings of which a measured sample was right 6 times in 13.
+ *
+ * Every false positive had one signature: **the generic plan kept the same
+ * sequential scan the custom plan chose.** There was no flip to be had, so the
+ * amplification the finding printed described a plan the planner would never
+ * pick.
+ *
+ * ## Why this is a probe and not another rule
+ *
+ * The obvious gate is arithmetic: require the generic row estimate
+ * (`rows / n_distinct`) to exceed the assumed LIMIT, on the reasoning that
+ * Postgres discounts an ordered index walk by `min(1, limit / estimate)` and an
+ * estimate at or below the limit earns no discount at all.
+ *
+ * That rule is wrong, and it was measured wrong before it was written down here.
+ * The real limit fraction for a BOUND limit is `ceil(0.1 x estimate) / estimate`,
+ * which pins to 0.1 for estimates of 10 or more but RISES to `1/estimate` below
+ * that, and the plan is then chosen by comparing that fraction of the full index
+ * scan against a seq scan plus sort. On a 247-page fixture the flip boundary sits
+ * between estimates 3 and 4, not at the limit of 20:
+ *
+ * ```txt
+ * generic estimate   2    3       4        10       20       500
+ * generic plan      seq  seq   index    index    index     index
+ * buffers           250  250  20,074   20,074   19,071       765
+ * ```
+ *
+ * Estimates 4 through 20 are full-table walks that an estimate-versus-limit gate
+ * would discard. The boundary is also not a fixed number: it is a cost
+ * comparison, so it moves with the table. Reproducing the same estimate on a
+ * 1976-page table and on an 89-page narrow table put the flip in a different
+ * place each time.
+ *
+ * So the honest gate is not a better formula, it is a measurement. `EXPLAIN`
+ * WITHOUT `ANALYZE` executes nothing, returns in microseconds, and asks the
+ * planner the exact question the rule was trying to predict. This module runs it.
+ *
+ * ## What it asks, and why only half the pair
+ *
+ * It plans ONE statement, under `force_generic_plan` only:
+ *
+ * ```sql
+ * PREPARE p AS SELECT * FROM t WHERE col = $1 ORDER BY ord LIMIT $2;
+ * EXPLAIN (FORMAT JSON) EXECUTE p(NULL, 20);
+ * ```
+ *
+ * The custom plan is not needed. The finding's whole claim is that a promoted
+ * generic plan abandons the seq scan for an ordered index walk, so if the generic
+ * plan IS a seq scan on the target table, the claim is refuted no matter what the
+ * custom plan does. Asking one question instead of two halves the work and
+ * removes the need for a representative rare value, which statistics do not
+ * carry.
+ *
+ * `NULL` is a safe argument precisely because the plan is generic: a generic plan
+ * is built without looking at the value, which is the property the whole check is
+ * about. The LIMIT is bound as `$2` rather than inlined because that is the shape
+ * Turbine emits, and an inlined limit takes a different code path in the planner.
+ *
+ * ## Failure is never a silent drop
+ *
+ * A probe that errors, times out, or returns an unparseable plan yields
+ * `'unknown'` and the finding SURVIVES with a note. A diagnostic that deletes
+ * findings when the database is uncooperative would be worse than one that
+ * over-reports, because the failure would be invisible in exactly the
+ * environments (restricted roles, non-Postgres engines) where a human is least
+ * able to check.
+ *
+ * @module
+ */
+import type { PlanDivergenceFinding, PlanDivergenceReport } from './plan-divergence.js';
+/**
+ * The planner's answer for one finding.
+ *
+ * - `'flip-reachable'`, the generic plan is NOT a plain seq scan of the target
+ *   table, so the divergence the finding describes is one the planner can
+ *   actually choose.
+ * - `'no-flip'`, the generic plan sequentially scans the target table, the same
+ *   access the good plan uses. Nothing to diverge to.
+ * - `'unknown'`, the probe did not produce an answer. The finding is kept.
+ */
+export type FlipVerdict = 'flip-reachable' | 'no-flip' | 'unknown';
+/** Outcome of a probe pass, keyed by {@link flipProbeKey}. */
+export interface FlipProbeResult {
+    /** True when the probe pass ran at all (Postgres, connection succeeded). */
+    available: boolean;
+    verdicts: Record<string, FlipVerdict>;
+    notices: string[];
+}
+/** An empty result, which keeps every finding. Used when probing is off. */
+export declare function emptyFlipProbeResult(): FlipProbeResult;
+/**
+ * Map key for a (table, column) pair.
+ *
+ * `\u0000` as the separator, written as the ESCAPE and never as a raw byte: a
+ * literal NUL in a source file makes `grep` treat the whole file as binary, which
+ * is how four of them survived a release in `cli/index.ts`.
+ */
+export declare function flipProbeKey(table: string, column: string): string;
+/**
+ * Which findings are worth probing.
+ *
+ * `unindexed-filter` only. The `sparse-value` branch already requires an index
+ * that serves the equality, and its 0.56 calibration was 6 of 6 on the schema
+ * that later produced 6 of 13 here, so there is no measured precision problem to
+ * spend a round trip on.
+ */
+export declare function needsFlipProbe(finding: PlanDivergenceFinding): boolean;
+/**
+ * The SQL for one probe. Pure, so the exact text is unit-testable without a
+ * database.
+ *
+ * Every identifier goes through {@link quoteIdent}; the only values in the
+ * statement are `$1` and `$2`, bound at EXECUTE. `name` is generated by the
+ * caller as `tpf_<index>` and is never caller-controlled text.
+ */
+export declare function buildFlipProbeSql(finding: PlanDivergenceFinding, name: string, searchSchema?: string): {
+    prepare: string;
+    explain: string;
+    deallocate: string;
+};
+/**
+ * Read a verdict out of one `EXPLAIN (FORMAT JSON)` payload.
+ *
+ * Exported for unit tests: the plan shapes this has to classify are exactly the
+ * ones that are tedious to produce live.
+ *
+ * The rule is deliberately narrow. Only a `Seq Scan` ON THE TARGET TABLE refutes
+ * a finding. A seq scan of some other relation in a more complex plan says
+ * nothing about this column, and anything that is not a plain sequential scan of
+ * the target (index scan, bitmap heap scan, index-only scan) leaves the flip
+ * reachable.
+ */
+export declare function verdictFromPlanJson(payload: unknown, table: string): FlipVerdict;
+export interface ProbePlanFlipsOptions {
+    connectionString: string;
+    schema?: string;
+    findings: PlanDivergenceFinding[];
+    statementTimeoutMs?: number;
+}
+/**
+ * Ask the planner, once per candidate finding, whether the flip is reachable.
+ *
+ * Runs inside a single `BEGIN READ ONLY` that is always rolled back. Nothing is
+ * executed: `EXPLAIN` without `ANALYZE` plans and discards. Each probe is
+ * INDIVIDUALLY optional, the same contract `collectStatsSnapshot` uses, so one
+ * unprobeable column degrades that column's verdict to `'unknown'` and never the
+ * pass.
+ */
+export declare function probePlanFlips(options: ProbePlanFlipsOptions): Promise<FlipProbeResult>;
+/**
+ * Drop the findings the planner refuted, and record how many.
+ *
+ * Pure. `'unknown'` and a missing verdict both KEEP the finding: see the failure
+ * contract in the module header.
+ */
+export declare function applyFlipVerdicts(report: PlanDivergenceReport, probe: FlipProbeResult): PlanDivergenceReport;

package/dist/cjs/plan-flip-probe.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * Plan-flip probe: does the generic plan actually differ from the good one?
+ *
+ * ## Why this exists
+ *
+ * `plan-divergence.ts` scores a column from statistics alone and answers "IF the
+ * cached plan flips, how bad is it". Its `unindexed-filter` branch (0.57) shipped
+ * without an answer to the prior question, "CAN it flip at all", and that turned
+ * out to be the majority case: on a real 118-model schema the branch produced 39
+ * findings of which a measured sample was right 6 times in 13.
+ *
+ * Every false positive had one signature: **the generic plan kept the same
+ * sequential scan the custom plan chose.** There was no flip to be had, so the
+ * amplification the finding printed described a plan the planner would never
+ * pick.
+ *
+ * ## Why this is a probe and not another rule
+ *
+ * The obvious gate is arithmetic: require the generic row estimate
+ * (`rows / n_distinct`) to exceed the assumed LIMIT, on the reasoning that
+ * Postgres discounts an ordered index walk by `min(1, limit / estimate)` and an
+ * estimate at or below the limit earns no discount at all.
+ *
+ * That rule is wrong, and it was measured wrong before it was written down here.
+ * The real limit fraction for a BOUND limit is `ceil(0.1 x estimate) / estimate`,
+ * which pins to 0.1 for estimates of 10 or more but RISES to `1/estimate` below
+ * that, and the plan is then chosen by comparing that fraction of the full index
+ * scan against a seq scan plus sort. On a 247-page fixture the flip boundary sits
+ * between estimates 3 and 4, not at the limit of 20:
+ *
+ * ```txt
+ * generic estimate   2    3       4        10       20       500
+ * generic plan      seq  seq   index    index    index     index
+ * buffers           250  250  20,074   20,074   19,071       765
+ * ```
+ *
+ * Estimates 4 through 20 are full-table walks that an estimate-versus-limit gate
+ * would discard. The boundary is also not a fixed number: it is a cost
+ * comparison, so it moves with the table. Reproducing the same estimate on a
+ * 1976-page table and on an 89-page narrow table put the flip in a different
+ * place each time.
+ *
+ * So the honest gate is not a better formula, it is a measurement. `EXPLAIN`
+ * WITHOUT `ANALYZE` executes nothing, returns in microseconds, and asks the
+ * planner the exact question the rule was trying to predict. This module runs it.
+ *
+ * ## What it asks, and why only half the pair
+ *
+ * It plans ONE statement, under `force_generic_plan` only:
+ *
+ * ```sql
+ * PREPARE p AS SELECT * FROM t WHERE col = $1 ORDER BY ord LIMIT $2;
+ * EXPLAIN (FORMAT JSON) EXECUTE p(NULL, 20);
+ * ```
+ *
+ * The custom plan is not needed. The finding's whole claim is that a promoted
+ * generic plan abandons the seq scan for an ordered index walk, so if the generic
+ * plan IS a seq scan on the target table, the claim is refuted no matter what the
+ * custom plan does. Asking one question instead of two halves the work and
+ * removes the need for a representative rare value, which statistics do not
+ * carry.
+ *
+ * `NULL` is a safe argument precisely because the plan is generic: a generic plan
+ * is built without looking at the value, which is the property the whole check is
+ * about. The LIMIT is bound as `$2` rather than inlined because that is the shape
+ * Turbine emits, and an inlined limit takes a different code path in the planner.
+ *
+ * ## Failure is never a silent drop
+ *
+ * A probe that errors, times out, or returns an unparseable plan yields
+ * `'unknown'` and the finding SURVIVES with a note. A diagnostic that deletes
+ * findings when the database is uncooperative would be worse than one that
+ * over-reports, because the failure would be invisible in exactly the
+ * environments (restricted roles, non-Postgres engines) where a human is least
+ * able to check.
+ *
+ * @module
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyFlipProbeResult = emptyFlipProbeResult;
+exports.flipProbeKey = flipProbeKey;
+exports.needsFlipProbe = needsFlipProbe;
+exports.buildFlipProbeSql = buildFlipProbeSql;
+exports.verdictFromPlanJson = verdictFromPlanJson;
+exports.probePlanFlips = probePlanFlips;
+exports.applyFlipVerdicts = applyFlipVerdicts;
+const utils_js_1 = require("./query/utils.js");
+/** An empty result, which keeps every finding. Used when probing is off. */
+function emptyFlipProbeResult() {
+    return { available: false, verdicts: {}, notices: [] };
+}
+/**
+ * Map key for a (table, column) pair.
+ *
+ * `\u0000` as the separator, written as the ESCAPE and never as a raw byte: a
+ * literal NUL in a source file makes `grep` treat the whole file as binary, which
+ * is how four of them survived a release in `cli/index.ts`.
+ */
+function flipProbeKey(table, column) {
+    return `${table}\u0000${column}`;
+}
+/**
+ * Which findings are worth probing.
+ *
+ * `unindexed-filter` only. The `sparse-value` branch already requires an index
+ * that serves the equality, and its 0.56 calibration was 6 of 6 on the schema
+ * that later produced 6 of 13 here, so there is no measured precision problem to
+ * spend a round trip on.
+ */
+function needsFlipProbe(finding) {
+    return finding.branch === 'unindexed-filter';
+}
+/**
+ * The SQL for one probe. Pure, so the exact text is unit-testable without a
+ * database.
+ *
+ * Every identifier goes through {@link quoteIdent}; the only values in the
+ * statement are `$1` and `$2`, bound at EXECUTE. `name` is generated by the
+ * caller as `tpf_<index>` and is never caller-controlled text.
+ */
+function buildFlipProbeSql(finding, name, searchSchema) {
+    const rel = searchSchema ? `${(0, utils_js_1.quoteIdent)(searchSchema)}.${(0, utils_js_1.quoteIdent)(finding.table)}` : (0, utils_js_1.quoteIdent)(finding.table);
+    // No declared parameter types: Postgres infers both from context, which avoids
+    // maintaining a second pg-type mapping that could disagree with the column's
+    // real type and turn a diagnostic into an error.
+    const prepare = `PREPARE ${name} AS SELECT * FROM ${rel} ` +
+        `WHERE ${(0, utils_js_1.quoteIdent)(finding.column)} = $1 ` +
+        `ORDER BY ${(0, utils_js_1.quoteIdent)(finding.orderColumn)} LIMIT $2`;
+    return {
+        prepare,
+        explain: `EXPLAIN (FORMAT JSON) EXECUTE ${name}(NULL, ${Number(finding.assumedLimit)})`,
+        deallocate: `DEALLOCATE ${name}`,
+    };
+}
+function* walkPlan(node) {
+    yield node;
+    for (const child of node.Plans ?? [])
+        yield* walkPlan(child);
+}
+/**
+ * Read a verdict out of one `EXPLAIN (FORMAT JSON)` payload.
+ *
+ * Exported for unit tests: the plan shapes this has to classify are exactly the
+ * ones that are tedious to produce live.
+ *
+ * The rule is deliberately narrow. Only a `Seq Scan` ON THE TARGET TABLE refutes
+ * a finding. A seq scan of some other relation in a more complex plan says
+ * nothing about this column, and anything that is not a plain sequential scan of
+ * the target (index scan, bitmap heap scan, index-only scan) leaves the flip
+ * reachable.
+ */
+function verdictFromPlanJson(payload, table) {
+    const root = Array.isArray(payload) ? payload[0] : undefined;
+    const plan = root?.Plan;
+    if (!plan)
+        return 'unknown';
+    for (const node of walkPlan(plan)) {
+        if (node['Relation Name'] !== table)
+            continue;
+        const type = node['Node Type'];
+        if (type === undefined)
+            continue;
+        return type === 'Seq Scan' ? 'no-flip' : 'flip-reachable';
+    }
+    // The target table is not in the plan at all, which should not happen for a
+    // statement that selects from it. Treated as unknown rather than as a refutation.
+    return 'unknown';
+}
+/**
+ * Ask the planner, once per candidate finding, whether the flip is reachable.
+ *
+ * Runs inside a single `BEGIN READ ONLY` that is always rolled back. Nothing is
+ * executed: `EXPLAIN` without `ANALYZE` plans and discards. Each probe is
+ * INDIVIDUALLY optional, the same contract `collectStatsSnapshot` uses, so one
+ * unprobeable column degrades that column's verdict to `'unknown'` and never the
+ * pass.
+ */
+async function probePlanFlips(options) {
+    const targets = options.findings.filter(needsFlipProbe);
+    const result = { available: false, verdicts: {}, notices: [] };
+    if (targets.length === 0) {
+        result.available = true;
+        return result;
+    }
+    const { Client } = (await Promise.resolve().then(() => __importStar(require('pg')))).default;
+    const client = new Client({ connectionString: options.connectionString });
+    try {
+        await client.connect();
+        await client.query(`SET statement_timeout = ${Number(options.statementTimeoutMs ?? 5000)}`);
+        // READ ONLY is belt-and-braces: EXPLAIN without ANALYZE cannot write, and the
+        // transaction is rolled back regardless. It costs nothing and makes the
+        // read-only intent checkable from a server-side log.
+        await client.query('BEGIN READ ONLY');
+        result.available = true;
+        for (let i = 0; i < targets.length; i++) {
+            const finding = targets[i];
+            const key = flipProbeKey(finding.table, finding.column);
+            const name = `tpf_${i}`;
+            const sql = buildFlipProbeSql(finding, name, options.schema);
+            try {
+                // A failed probe must not poison the surrounding transaction for the
+                // probes after it, so each one gets its own savepoint.
+                await client.query(`SAVEPOINT ${name}`);
+                await client.query(sql.prepare);
+                await client.query('SET LOCAL plan_cache_mode = force_generic_plan');
+                const res = await client.query(sql.explain);
+                const row = res.rows[0];
+                const payload = row ? Object.values(row)[0] : undefined;
+                result.verdicts[key] =
+                    typeof payload === 'string'
+                        ? verdictFromPlanJson(JSON.parse(payload), finding.table)
+                        : verdictFromPlanJson(payload, finding.table);
+                await client.query(sql.deallocate);
+                await client.query(`RELEASE SAVEPOINT ${name}`);
+            }
+            catch (err) {
+                result.verdicts[key] = 'unknown';
+                result.notices.push(`flip probe on ${finding.table}.${finding.column} was inconclusive (${err instanceof Error ? err.message.split('\n')[0] : String(err)}); the finding is kept`);
+                try {
+                    await client.query(`ROLLBACK TO SAVEPOINT ${name}`);
+                }
+                catch {
+                    // The transaction itself is gone; the remaining probes will each record
+                    // their own notice and the pass still returns what it has.
+                }
+            }
+        }
+    }
+    catch (err) {
+        result.notices.push(`plan-flip probing unavailable (${err instanceof Error ? err.message.split('\n')[0] : String(err)}); findings are reported unverified`);
+    }
+    finally {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            // Nothing to roll back.
+        }
+        await client.end().catch(() => { });
+    }
+    return result;
+}
+/**
+ * Drop the findings the planner refuted, and record how many.
+ *
+ * Pure. `'unknown'` and a missing verdict both KEEP the finding: see the failure
+ * contract in the module header.
+ */
+function applyFlipVerdicts(report, probe) {
+    if (!probe.available)
+        return report;
+    let refuted = 0;
+    const findings = report.findings.filter((f) => {
+        if (!needsFlipProbe(f))
+            return true;
+        const verdict = probe.verdicts[flipProbeKey(f.table, f.column)];
+        if (verdict === 'no-flip') {
+            refuted++;
+            return false;
+        }
+        return true;
+    });
+    return {
+        ...report,
+        findings,
+        flipProbed: true,
+        flipRefuted: refuted,
+        notices: [...report.notices, ...probe.notices.map((n) => ({ table: '', column: '', reason: n }))],
+    };
+}

package/dist/cli/index.js

@@ -33,6 +33,7 @@ import { buildCreateIndexSql, buildDropIndexSql, collectDoctorProbeIndexNames, c
 import { auditDoctorIndexes, collectStatsSnapshot, collectTableHeat, findInvalidIndexes, findRedundantIndexes, findUnusedIndexes, formatBytes, isSnapshotUsable, STATS_THRESHOLDS, scoreMissingIndex, } from '../index-stats.js';
 import { introspect } from '../introspect.js';
 import { collectDivergenceCandidateColumns, collectDivergenceOrderColumns, findPlanDivergence, PLAN_DIVERGENCE_THRESHOLDS, } from '../plan-divergence.js';
+import { applyFlipVerdicts, emptyFlipProbeResult, needsFlipProbe, probePlanFlips } from '../plan-flip-probe.js';
 import { snakeToCamel } from '../schema.js';
 import { DestructivePushRefusal, schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, DEFAULT_INIT_SEED_FILE, findConfigFile, loadConfigResult, looksLikeSchemaFilePath, resolveConfig, resolveSeedFile, unwrapModuleDefault, } from './config.js';
@@ -2333,9 +2334,18 @@ async function cmdDoctor(args, config) {
     // trustworthy stats_reset age because they normalize write counters by it;
     // this check reads no counter, only pg_stats, whose freshness is ANALYZE. A
     // cluster with a NULL stats_reset (the default) must still get the check.
-    const divergence = divergenceOn && snapshot.available
+    const scored = divergenceOn && snapshot.available
         ? findPlanDivergence(schema, snapshot)
         : { findings: [], notices: [], candidatesConsidered: 0, consideredIndexed: 0, consideredUnindexed: 0 };
+    // Statistics can say how bad a flip WOULD be; only the planner can say whether
+    // it is reachable. The `unindexed-filter` branch shipped in 0.57 without that
+    // question answered and was right 6 times in 13 on a real schema, so every one
+    // of its findings is now put to a plan-only EXPLAIN. Nothing is executed, and a
+    // probe that fails keeps its finding rather than dropping it.
+    const flipProbe = divergenceOn && scored.findings.some(needsFlipProbe)
+        ? await probePlanFlips({ connectionString: url, schema: config.schema, findings: scored.findings })
+        : emptyFlipProbeResult();
+    const divergence = applyFlipVerdicts(scored, flipProbe);
     if (jsonMode) {
         spinner?.stop();
         console.log(JSON.stringify(buildDoctorJson({ schema, findings, invalid, snapshot, usable, heat, subtract, divergence, args }), null, 2));
@@ -2429,6 +2439,12 @@ function buildDoctorJson(ctx) {
         considered: ctx.divergence.candidatesConsidered,
         indexed: ctx.divergence.consideredIndexed,
         unindexed: ctx.divergence.consideredUnindexed,
+        // Whether the unindexed findings above were put to the planner, and how many
+        // it refuted. `flipProbed: false` means they are statistics-only and carry
+        // 0.57's precision, so a consumer can tell a verified list from an unverified
+        // one instead of inferring it from the count.
+        flipProbed: ctx.divergence.flipProbed === true,
+        flipRefuted: ctx.divergence.flipRefuted ?? 0,
     };
     return out;
 }
@@ -2751,6 +2767,19 @@ function renderDivergenceGates(divergence) {
     console.log(`  ${dim(`${divergence.candidatesConsidered} column(s) were scored (${divergence.consideredIndexed} indexed, ${divergence.consideredUnindexed} unindexed). That population is relation-probe`)}`);
     console.log(`  ${dim('and leading-index columns only: a filter column that is neither is not covered. Skip this')}`);
     console.log(`  ${dim('section with --no-plan-divergence.')}`);
+    // Say whether the unindexed findings were verified, and what verification
+    // removed. Statistics can only say how bad a flip would be; a plan-only EXPLAIN
+    // says whether the planner can reach it at all.
+    if (divergence.flipProbed === true) {
+        const refuted = divergence.flipRefuted ?? 0;
+        const wereRefuted = refuted === 1 ? '1 was refuted' : `${refuted} were refuted`;
+        console.log(`  ${dim(`Every unindexed finding was put to the planner (EXPLAIN, nothing executed); ${wereRefuted}`)}`);
+        console.log(`  ${dim('because the generic plan keeps the same sequential scan, so no flip is reachable.')}`);
+    }
+    else if (divergence.consideredUnindexed > 0) {
+        console.log(`  ${dim('Unindexed findings are UNVERIFIED here: the planner probe did not run, so some may name a')}`);
+        console.log(`  ${dim('divergence the planner would never choose.')}`);
+    }
 }
 /** Round to a whole number and group it, for the divergence report's estimates. */
 function divInt(n) {

package/dist/plan-divergence.d.ts

@@ -424,6 +424,21 @@ export interface PlanDivergenceReport {
      */
     consideredIndexed: number;
     consideredUnindexed: number;
+    /**
+     * True when every `unindexed-filter` finding was put to the planner via
+     * `plan-flip-probe.ts` rather than reported on statistics alone.
+     *
+     * Absent or false means the findings below are UNVERIFIED: the probe was
+     * skipped, the engine is not Postgres, or the connection refused it.
+     */
+    flipProbed?: boolean;
+    /**
+     * How many candidate findings the planner refuted, i.e. columns where the
+     * generic plan keeps the same sequential scan the good plan uses so there is
+     * no divergence to reach. Reported because a check that silently discards two
+     * thirds of what it found should say so.
+     */
+    flipRefuted?: number;
 }
 /** A (table, column) pair whose distribution statistics the collector should read. */
 export interface DivergenceCandidate {

package/dist/plan-flip-probe.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Plan-flip probe: does the generic plan actually differ from the good one?
+ *
+ * ## Why this exists
+ *
+ * `plan-divergence.ts` scores a column from statistics alone and answers "IF the
+ * cached plan flips, how bad is it". Its `unindexed-filter` branch (0.57) shipped
+ * without an answer to the prior question, "CAN it flip at all", and that turned
+ * out to be the majority case: on a real 118-model schema the branch produced 39
+ * findings of which a measured sample was right 6 times in 13.
+ *
+ * Every false positive had one signature: **the generic plan kept the same
+ * sequential scan the custom plan chose.** There was no flip to be had, so the
+ * amplification the finding printed described a plan the planner would never
+ * pick.
+ *
+ * ## Why this is a probe and not another rule
+ *
+ * The obvious gate is arithmetic: require the generic row estimate
+ * (`rows / n_distinct`) to exceed the assumed LIMIT, on the reasoning that
+ * Postgres discounts an ordered index walk by `min(1, limit / estimate)` and an
+ * estimate at or below the limit earns no discount at all.
+ *
+ * That rule is wrong, and it was measured wrong before it was written down here.
+ * The real limit fraction for a BOUND limit is `ceil(0.1 x estimate) / estimate`,
+ * which pins to 0.1 for estimates of 10 or more but RISES to `1/estimate` below
+ * that, and the plan is then chosen by comparing that fraction of the full index
+ * scan against a seq scan plus sort. On a 247-page fixture the flip boundary sits
+ * between estimates 3 and 4, not at the limit of 20:
+ *
+ * ```txt
+ * generic estimate   2    3       4        10       20       500
+ * generic plan      seq  seq   index    index    index     index
+ * buffers           250  250  20,074   20,074   19,071       765
+ * ```
+ *
+ * Estimates 4 through 20 are full-table walks that an estimate-versus-limit gate
+ * would discard. The boundary is also not a fixed number: it is a cost
+ * comparison, so it moves with the table. Reproducing the same estimate on a
+ * 1976-page table and on an 89-page narrow table put the flip in a different
+ * place each time.
+ *
+ * So the honest gate is not a better formula, it is a measurement. `EXPLAIN`
+ * WITHOUT `ANALYZE` executes nothing, returns in microseconds, and asks the
+ * planner the exact question the rule was trying to predict. This module runs it.
+ *
+ * ## What it asks, and why only half the pair
+ *
+ * It plans ONE statement, under `force_generic_plan` only:
+ *
+ * ```sql
+ * PREPARE p AS SELECT * FROM t WHERE col = $1 ORDER BY ord LIMIT $2;
+ * EXPLAIN (FORMAT JSON) EXECUTE p(NULL, 20);
+ * ```
+ *
+ * The custom plan is not needed. The finding's whole claim is that a promoted
+ * generic plan abandons the seq scan for an ordered index walk, so if the generic
+ * plan IS a seq scan on the target table, the claim is refuted no matter what the
+ * custom plan does. Asking one question instead of two halves the work and
+ * removes the need for a representative rare value, which statistics do not
+ * carry.
+ *
+ * `NULL` is a safe argument precisely because the plan is generic: a generic plan
+ * is built without looking at the value, which is the property the whole check is
+ * about. The LIMIT is bound as `$2` rather than inlined because that is the shape
+ * Turbine emits, and an inlined limit takes a different code path in the planner.
+ *
+ * ## Failure is never a silent drop
+ *
+ * A probe that errors, times out, or returns an unparseable plan yields
+ * `'unknown'` and the finding SURVIVES with a note. A diagnostic that deletes
+ * findings when the database is uncooperative would be worse than one that
+ * over-reports, because the failure would be invisible in exactly the
+ * environments (restricted roles, non-Postgres engines) where a human is least
+ * able to check.
+ *
+ * @module
+ */
+import type { PlanDivergenceFinding, PlanDivergenceReport } from './plan-divergence.js';
+/**
+ * The planner's answer for one finding.
+ *
+ * - `'flip-reachable'`, the generic plan is NOT a plain seq scan of the target
+ *   table, so the divergence the finding describes is one the planner can
+ *   actually choose.
+ * - `'no-flip'`, the generic plan sequentially scans the target table, the same
+ *   access the good plan uses. Nothing to diverge to.
+ * - `'unknown'`, the probe did not produce an answer. The finding is kept.
+ */
+export type FlipVerdict = 'flip-reachable' | 'no-flip' | 'unknown';
+/** Outcome of a probe pass, keyed by {@link flipProbeKey}. */
+export interface FlipProbeResult {
+    /** True when the probe pass ran at all (Postgres, connection succeeded). */
+    available: boolean;
+    verdicts: Record<string, FlipVerdict>;
+    notices: string[];
+}
+/** An empty result, which keeps every finding. Used when probing is off. */
+export declare function emptyFlipProbeResult(): FlipProbeResult;
+/**
+ * Map key for a (table, column) pair.
+ *
+ * `\u0000` as the separator, written as the ESCAPE and never as a raw byte: a
+ * literal NUL in a source file makes `grep` treat the whole file as binary, which
+ * is how four of them survived a release in `cli/index.ts`.
+ */
+export declare function flipProbeKey(table: string, column: string): string;
+/**
+ * Which findings are worth probing.
+ *
+ * `unindexed-filter` only. The `sparse-value` branch already requires an index
+ * that serves the equality, and its 0.56 calibration was 6 of 6 on the schema
+ * that later produced 6 of 13 here, so there is no measured precision problem to
+ * spend a round trip on.
+ */
+export declare function needsFlipProbe(finding: PlanDivergenceFinding): boolean;
+/**
+ * The SQL for one probe. Pure, so the exact text is unit-testable without a
+ * database.
+ *
+ * Every identifier goes through {@link quoteIdent}; the only values in the
+ * statement are `$1` and `$2`, bound at EXECUTE. `name` is generated by the
+ * caller as `tpf_<index>` and is never caller-controlled text.
+ */
+export declare function buildFlipProbeSql(finding: PlanDivergenceFinding, name: string, searchSchema?: string): {
+    prepare: string;
+    explain: string;
+    deallocate: string;
+};
+/**
+ * Read a verdict out of one `EXPLAIN (FORMAT JSON)` payload.
+ *
+ * Exported for unit tests: the plan shapes this has to classify are exactly the
+ * ones that are tedious to produce live.
+ *
+ * The rule is deliberately narrow. Only a `Seq Scan` ON THE TARGET TABLE refutes
+ * a finding. A seq scan of some other relation in a more complex plan says
+ * nothing about this column, and anything that is not a plain sequential scan of
+ * the target (index scan, bitmap heap scan, index-only scan) leaves the flip
+ * reachable.
+ */
+export declare function verdictFromPlanJson(payload: unknown, table: string): FlipVerdict;
+export interface ProbePlanFlipsOptions {
+    connectionString: string;
+    schema?: string;
+    findings: PlanDivergenceFinding[];
+    statementTimeoutMs?: number;
+}
+/**
+ * Ask the planner, once per candidate finding, whether the flip is reachable.
+ *
+ * Runs inside a single `BEGIN READ ONLY` that is always rolled back. Nothing is
+ * executed: `EXPLAIN` without `ANALYZE` plans and discards. Each probe is
+ * INDIVIDUALLY optional, the same contract `collectStatsSnapshot` uses, so one
+ * unprobeable column degrades that column's verdict to `'unknown'` and never the
+ * pass.
+ */
+export declare function probePlanFlips(options: ProbePlanFlipsOptions): Promise<FlipProbeResult>;
+/**
+ * Drop the findings the planner refuted, and record how many.
+ *
+ * Pure. `'unknown'` and a missing verdict both KEEP the finding: see the failure
+ * contract in the module header.
+ */
+export declare function applyFlipVerdicts(report: PlanDivergenceReport, probe: FlipProbeResult): PlanDivergenceReport;

package/dist/plan-flip-probe.js

@@ -0,0 +1,262 @@
+/**
+ * Plan-flip probe: does the generic plan actually differ from the good one?
+ *
+ * ## Why this exists
+ *
+ * `plan-divergence.ts` scores a column from statistics alone and answers "IF the
+ * cached plan flips, how bad is it". Its `unindexed-filter` branch (0.57) shipped
+ * without an answer to the prior question, "CAN it flip at all", and that turned
+ * out to be the majority case: on a real 118-model schema the branch produced 39
+ * findings of which a measured sample was right 6 times in 13.
+ *
+ * Every false positive had one signature: **the generic plan kept the same
+ * sequential scan the custom plan chose.** There was no flip to be had, so the
+ * amplification the finding printed described a plan the planner would never
+ * pick.
+ *
+ * ## Why this is a probe and not another rule
+ *
+ * The obvious gate is arithmetic: require the generic row estimate
+ * (`rows / n_distinct`) to exceed the assumed LIMIT, on the reasoning that
+ * Postgres discounts an ordered index walk by `min(1, limit / estimate)` and an
+ * estimate at or below the limit earns no discount at all.
+ *
+ * That rule is wrong, and it was measured wrong before it was written down here.
+ * The real limit fraction for a BOUND limit is `ceil(0.1 x estimate) / estimate`,
+ * which pins to 0.1 for estimates of 10 or more but RISES to `1/estimate` below
+ * that, and the plan is then chosen by comparing that fraction of the full index
+ * scan against a seq scan plus sort. On a 247-page fixture the flip boundary sits
+ * between estimates 3 and 4, not at the limit of 20:
+ *
+ * ```txt
+ * generic estimate   2    3       4        10       20       500
+ * generic plan      seq  seq   index    index    index     index
+ * buffers           250  250  20,074   20,074   19,071       765
+ * ```
+ *
+ * Estimates 4 through 20 are full-table walks that an estimate-versus-limit gate
+ * would discard. The boundary is also not a fixed number: it is a cost
+ * comparison, so it moves with the table. Reproducing the same estimate on a
+ * 1976-page table and on an 89-page narrow table put the flip in a different
+ * place each time.
+ *
+ * So the honest gate is not a better formula, it is a measurement. `EXPLAIN`
+ * WITHOUT `ANALYZE` executes nothing, returns in microseconds, and asks the
+ * planner the exact question the rule was trying to predict. This module runs it.
+ *
+ * ## What it asks, and why only half the pair
+ *
+ * It plans ONE statement, under `force_generic_plan` only:
+ *
+ * ```sql
+ * PREPARE p AS SELECT * FROM t WHERE col = $1 ORDER BY ord LIMIT $2;
+ * EXPLAIN (FORMAT JSON) EXECUTE p(NULL, 20);
+ * ```
+ *
+ * The custom plan is not needed. The finding's whole claim is that a promoted
+ * generic plan abandons the seq scan for an ordered index walk, so if the generic
+ * plan IS a seq scan on the target table, the claim is refuted no matter what the
+ * custom plan does. Asking one question instead of two halves the work and
+ * removes the need for a representative rare value, which statistics do not
+ * carry.
+ *
+ * `NULL` is a safe argument precisely because the plan is generic: a generic plan
+ * is built without looking at the value, which is the property the whole check is
+ * about. The LIMIT is bound as `$2` rather than inlined because that is the shape
+ * Turbine emits, and an inlined limit takes a different code path in the planner.
+ *
+ * ## Failure is never a silent drop
+ *
+ * A probe that errors, times out, or returns an unparseable plan yields
+ * `'unknown'` and the finding SURVIVES with a note. A diagnostic that deletes
+ * findings when the database is uncooperative would be worse than one that
+ * over-reports, because the failure would be invisible in exactly the
+ * environments (restricted roles, non-Postgres engines) where a human is least
+ * able to check.
+ *
+ * @module
+ */
+import { quoteIdent } from './query/utils.js';
+/** An empty result, which keeps every finding. Used when probing is off. */
+export function emptyFlipProbeResult() {
+    return { available: false, verdicts: {}, notices: [] };
+}
+/**
+ * Map key for a (table, column) pair.
+ *
+ * `\u0000` as the separator, written as the ESCAPE and never as a raw byte: a
+ * literal NUL in a source file makes `grep` treat the whole file as binary, which
+ * is how four of them survived a release in `cli/index.ts`.
+ */
+export function flipProbeKey(table, column) {
+    return `${table}\u0000${column}`;
+}
+/**
+ * Which findings are worth probing.
+ *
+ * `unindexed-filter` only. The `sparse-value` branch already requires an index
+ * that serves the equality, and its 0.56 calibration was 6 of 6 on the schema
+ * that later produced 6 of 13 here, so there is no measured precision problem to
+ * spend a round trip on.
+ */
+export function needsFlipProbe(finding) {
+    return finding.branch === 'unindexed-filter';
+}
+/**
+ * The SQL for one probe. Pure, so the exact text is unit-testable without a
+ * database.
+ *
+ * Every identifier goes through {@link quoteIdent}; the only values in the
+ * statement are `$1` and `$2`, bound at EXECUTE. `name` is generated by the
+ * caller as `tpf_<index>` and is never caller-controlled text.
+ */
+export function buildFlipProbeSql(finding, name, searchSchema) {
+    const rel = searchSchema ? `${quoteIdent(searchSchema)}.${quoteIdent(finding.table)}` : quoteIdent(finding.table);
+    // No declared parameter types: Postgres infers both from context, which avoids
+    // maintaining a second pg-type mapping that could disagree with the column's
+    // real type and turn a diagnostic into an error.
+    const prepare = `PREPARE ${name} AS SELECT * FROM ${rel} ` +
+        `WHERE ${quoteIdent(finding.column)} = $1 ` +
+        `ORDER BY ${quoteIdent(finding.orderColumn)} LIMIT $2`;
+    return {
+        prepare,
+        explain: `EXPLAIN (FORMAT JSON) EXECUTE ${name}(NULL, ${Number(finding.assumedLimit)})`,
+        deallocate: `DEALLOCATE ${name}`,
+    };
+}
+function* walkPlan(node) {
+    yield node;
+    for (const child of node.Plans ?? [])
+        yield* walkPlan(child);
+}
+/**
+ * Read a verdict out of one `EXPLAIN (FORMAT JSON)` payload.
+ *
+ * Exported for unit tests: the plan shapes this has to classify are exactly the
+ * ones that are tedious to produce live.
+ *
+ * The rule is deliberately narrow. Only a `Seq Scan` ON THE TARGET TABLE refutes
+ * a finding. A seq scan of some other relation in a more complex plan says
+ * nothing about this column, and anything that is not a plain sequential scan of
+ * the target (index scan, bitmap heap scan, index-only scan) leaves the flip
+ * reachable.
+ */
+export function verdictFromPlanJson(payload, table) {
+    const root = Array.isArray(payload) ? payload[0] : undefined;
+    const plan = root?.Plan;
+    if (!plan)
+        return 'unknown';
+    for (const node of walkPlan(plan)) {
+        if (node['Relation Name'] !== table)
+            continue;
+        const type = node['Node Type'];
+        if (type === undefined)
+            continue;
+        return type === 'Seq Scan' ? 'no-flip' : 'flip-reachable';
+    }
+    // The target table is not in the plan at all, which should not happen for a
+    // statement that selects from it. Treated as unknown rather than as a refutation.
+    return 'unknown';
+}
+/**
+ * Ask the planner, once per candidate finding, whether the flip is reachable.
+ *
+ * Runs inside a single `BEGIN READ ONLY` that is always rolled back. Nothing is
+ * executed: `EXPLAIN` without `ANALYZE` plans and discards. Each probe is
+ * INDIVIDUALLY optional, the same contract `collectStatsSnapshot` uses, so one
+ * unprobeable column degrades that column's verdict to `'unknown'` and never the
+ * pass.
+ */
+export async function probePlanFlips(options) {
+    const targets = options.findings.filter(needsFlipProbe);
+    const result = { available: false, verdicts: {}, notices: [] };
+    if (targets.length === 0) {
+        result.available = true;
+        return result;
+    }
+    const { Client } = (await import('pg')).default;
+    const client = new Client({ connectionString: options.connectionString });
+    try {
+        await client.connect();
+        await client.query(`SET statement_timeout = ${Number(options.statementTimeoutMs ?? 5000)}`);
+        // READ ONLY is belt-and-braces: EXPLAIN without ANALYZE cannot write, and the
+        // transaction is rolled back regardless. It costs nothing and makes the
+        // read-only intent checkable from a server-side log.
+        await client.query('BEGIN READ ONLY');
+        result.available = true;
+        for (let i = 0; i < targets.length; i++) {
+            const finding = targets[i];
+            const key = flipProbeKey(finding.table, finding.column);
+            const name = `tpf_${i}`;
+            const sql = buildFlipProbeSql(finding, name, options.schema);
+            try {
+                // A failed probe must not poison the surrounding transaction for the
+                // probes after it, so each one gets its own savepoint.
+                await client.query(`SAVEPOINT ${name}`);
+                await client.query(sql.prepare);
+                await client.query('SET LOCAL plan_cache_mode = force_generic_plan');
+                const res = await client.query(sql.explain);
+                const row = res.rows[0];
+                const payload = row ? Object.values(row)[0] : undefined;
+                result.verdicts[key] =
+                    typeof payload === 'string'
+                        ? verdictFromPlanJson(JSON.parse(payload), finding.table)
+                        : verdictFromPlanJson(payload, finding.table);
+                await client.query(sql.deallocate);
+                await client.query(`RELEASE SAVEPOINT ${name}`);
+            }
+            catch (err) {
+                result.verdicts[key] = 'unknown';
+                result.notices.push(`flip probe on ${finding.table}.${finding.column} was inconclusive (${err instanceof Error ? err.message.split('\n')[0] : String(err)}); the finding is kept`);
+                try {
+                    await client.query(`ROLLBACK TO SAVEPOINT ${name}`);
+                }
+                catch {
+                    // The transaction itself is gone; the remaining probes will each record
+                    // their own notice and the pass still returns what it has.
+                }
+            }
+        }
+    }
+    catch (err) {
+        result.notices.push(`plan-flip probing unavailable (${err instanceof Error ? err.message.split('\n')[0] : String(err)}); findings are reported unverified`);
+    }
+    finally {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            // Nothing to roll back.
+        }
+        await client.end().catch(() => { });
+    }
+    return result;
+}
+/**
+ * Drop the findings the planner refuted, and record how many.
+ *
+ * Pure. `'unknown'` and a missing verdict both KEEP the finding: see the failure
+ * contract in the module header.
+ */
+export function applyFlipVerdicts(report, probe) {
+    if (!probe.available)
+        return report;
+    let refuted = 0;
+    const findings = report.findings.filter((f) => {
+        if (!needsFlipProbe(f))
+            return true;
+        const verdict = probe.verdicts[flipProbeKey(f.table, f.column)];
+        if (verdict === 'no-flip') {
+            refuted++;
+            return false;
+        }
+        return true;
+    });
+    return {
+        ...report,
+        findings,
+        flipProbed: true,
+        flipRefuted: refuted,
+        notices: [...report.notices, ...probe.notices.map((n) => ({ table: '', column: '', reason: n }))],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",