turbine-orm 0.56.0 → 0.58.0

package/README.md

@@ -454,7 +454,7 @@ const db = turbine({
 
 Where a pg-style alias exists (`max`, `idleTimeoutMillis`, `connectionTimeoutMillis`), the explicit Turbine field wins when both are set.
 
-> **`planCacheMode` (Postgres only, opt-in).** PostgreSQL may promote a **named** prepared statement to a generic plan from its sixth execution onward, and a generic plan is costed blind to the bound values. On a predicate whose selectivity swings per value (a `tenant_id` equality on a shared table, where one value matches a handful of rows and another matches most of them), the statement can be locked onto a plan chosen for the average value, and it never reverts. `planCacheMode: 'auto' | 'force_custom_plan' | 'force_generic_plan'` pins the backend's choice; `'force_custom_plan'` re-plans every execution and removes the cliff. It is applied as a connection parameter (`options=-c plan_cache_mode=...`) when Turbine opens a connection, so it is in force for that connection's first statement and for every checkout, `$transaction`, stream and pipeline on it, and it cannot race your first query. Leave it unset (the default) and Turbine sends nothing at all. Reach for it when you have measured a statement getting slower after its fifth execution. **Correction to the 0.54 text, which said `findMany` / `findFirst` bind `LIMIT $n` and are "much less exposed":** that was false. PostgreSQL does not deny the planner a limit fraction for a bound limit, it substitutes a default of 10% of the child node's own row estimate (clamped at one row), and an unknown `OFFSET` triggers the same substitution even when the limit is a constant, which a paginated Turbine read always has. Two things also need saying about the sentence that opens this note. The sixth execution is a ceiling, not a trigger: `auto` promotes only when the generic plan's **estimated** cost is not worse than the average custom cost, so many statements are never promoted at all, and `pg_prepared_statements.generic_plans` is how you tell. And the shape that gets promoted unprompted is the one with **no limit**, not the limited one: measured on a skewed join predicate, an unlimited `count()`-shaped statement promoted under the default `auto` and ran a nested loop at 430x the buffers of the custom plan, while the same predicate under `LIMIT $n` was never promoted across eight executions (its substituted row count made the generic plan look more expensive). A limited `findMany` gives the planner two unknowns instead of one, which is not the same as more damage. `implicitPkOrdering` is **off by default in core**, so a default `findMany` emits no `ORDER BY`; switching it on adds an ordering a generic plan can walk the whole table in. Measure with `plan_cache_mode = force_generic_plan` against `force_custom_plan` rather than reasoning about which shapes ought to be safe; the fixtures and numbers are on the [relations page](https://turbineorm.dev/relations) and in the 0.55.0 changelog. **Two 0.56 corrections to the paragraph above.** First, "neither an ORDER BY nor a limit is required" is true, but it read as if ordering did not matter: on a real multi-tenant schema swept table by table, every divergent shape had an `ORDER BY` and every shape without one measured 1.00x, so it is not necessary in general and is still the strongest single predictor in practice. Second, a custom plan is not automatically the better one: on a reproducible fixture where one dense value's rows are packed at the end of the heap, `LIMIT 20` with no ordering reads 4,262 buffers custom against 71 generic (the default `auto` never promotes there, so it produces the 4,262-buffer plan too). Since 0.56 the per-query read arg **`forceCustomPlan: true`** covers the case a connection-wide setting cannot express, custom on one query and `auto` everywhere else, and `turbine doctor` detects the distribution that admits the flip. Three scope limits: it does nothing on an **external pool** (Turbine never opens those connections, so set the GUC in the driver's own setup; Turbine-owned string `replicas` on that same client DO get it); a Postgres wire-compatible engine without the setting (CockroachDB, YugabyteDB, pre-12 PostgreSQL) refuses the connection parameter itself; and a **connection pooler** may filter startup parameters (PgBouncer's `ignore_startup_parameters`), where `ALTER ROLE ... SET plan_cache_mode = ...` is the way in. Any value outside the three throws `ValidationError` at construction, and a non-Postgres engine throws `UnsupportedFeatureError` (`TURBINE_E017`).
+> **`planCacheMode` (Postgres only, opt-in).** PostgreSQL may promote a **named** prepared statement to a generic plan from its sixth execution onward, and a generic plan is costed blind to the bound values. On a predicate whose selectivity swings per value (a `tenant_id` equality on a shared table, where one value matches a handful of rows and another matches most of them), the statement can be locked onto a plan chosen for the average value, and it never reverts. `planCacheMode: 'auto' | 'force_custom_plan' | 'force_generic_plan'` pins the backend's choice; `'force_custom_plan'` re-plans every execution and removes the cliff. It is applied as a connection parameter (`options=-c plan_cache_mode=...`) when Turbine opens a connection, so it is in force for that connection's first statement and for every checkout, `$transaction`, stream and pipeline on it, and it cannot race your first query. Leave it unset (the default) and Turbine sends nothing at all. Reach for it when you have measured a statement getting slower after its fifth execution. **Correction to the 0.54 text, which said `findMany` / `findFirst` bind `LIMIT $n` and are "much less exposed":** that was false. PostgreSQL does not deny the planner a limit fraction for a bound limit, it substitutes a default of 10% of the child node's own row estimate (clamped at one row), and an unknown `OFFSET` triggers the same substitution even when the limit is a constant, which a paginated Turbine read always has. Two things also need saying about the sentence that opens this note. The sixth execution is a ceiling, not a trigger: `auto` promotes only when the generic plan's **estimated** cost is not worse than the average custom cost, so many statements are never promoted at all, and `pg_prepared_statements.generic_plans` is how you tell. And the shape that gets promoted unprompted is the one with **no limit**, not the limited one: measured on a skewed join predicate, an unlimited `count()`-shaped statement promoted under the default `auto` and ran a nested loop at 430x the buffers of the custom plan, while the same predicate under `LIMIT $n` was never promoted across eight executions (its substituted row count made the generic plan look more expensive). A limited `findMany` gives the planner two unknowns instead of one, which is not the same as more damage. `implicitPkOrdering` is **off by default in core**, so a default `findMany` emits no `ORDER BY`; switching it on adds an ordering a generic plan can walk the whole table in. Measure with `plan_cache_mode = force_generic_plan` against `force_custom_plan` rather than reasoning about which shapes ought to be safe; the fixtures and numbers are on the [relations page](https://turbineorm.dev/relations) and in the 0.55.0 changelog. **Two 0.56 corrections to the paragraph above.** First, "neither an ORDER BY nor a limit is required" is true, but it read as if ordering did not matter: on a real multi-tenant schema swept table by table, every divergent shape had an `ORDER BY` and every shape without one measured 1.00x, so it is not necessary in general and is still the strongest single predictor in practice. Second, a custom plan is not automatically the better one: on a reproducible fixture where one dense value's rows are packed at the end of the heap, `LIMIT 20` with no ordering reads 4,262 buffers custom against 71 generic (the default `auto` never promotes there, so it produces the 4,262-buffer plan too). Since 0.56 the per-query read arg **`forceCustomPlan: true`** covers the case a connection-wide setting cannot express, custom on one query and `auto` everywhere else, and `turbine doctor` detects the distribution that admits the flip. **0.57 correction:** that read arg reached the core client only. Through `turbine-orm/prisma-compat` it was accepted and silently dropped until 0.57.0, so a compat integration that followed this advice got a no-op; confirm at the wire with `pg_prepared_statements` rather than assuming. 0.57 also adds a third divergence mechanism to `doctor`: an **unindexed** filter column, where the good plan is a sequential scan the generic plan will not choose (measured 250 buffers against 20,074 on a 20,000-row / 247-page fixture). Three scope limits: it does nothing on an **external pool** (Turbine never opens those connections, so set the GUC in the driver's own setup; Turbine-owned string `replicas` on that same client DO get it); a Postgres wire-compatible engine without the setting (CockroachDB, YugabyteDB, pre-12 PostgreSQL) refuses the connection parameter itself; and a **connection pooler** may filter startup parameters (PgBouncer's `ignore_startup_parameters`), where `ALTER ROLE ... SET plan_cache_mode = ...` is the way in. Any value outside the three throws `ValidationError` at construction, and a non-Postgres engine throws `UnsupportedFeatureError` (`TURBINE_E017`).
 
 > **`preparedStatements` and connection poolers.** With prepared statements on, Turbine submits queries as `{ name, text, values }` so Postgres caches the parse and plan **per backend connection**. That is a real win against a database you connect to directly, and a hazard behind a transaction-pooling proxy (PgBouncer in `transaction` mode, Supabase's pooler port, some serverless poolers): the named statement is prepared on one backend and your next query may land on another, which fails with `prepared statement "..." does not exist`. Turbine defaults it to `true` only for pools it creates itself and `false` for external pools passed via `pool` / `turbineHttp()`, because serverless drivers are the common case there. If you are pointing a Turbine-owned pool at a transaction pooler, set `preparedStatements: false`. The environment variable `TURBINE_DISABLE_PREPARED=1` turns it off globally without a code change.
 
@@ -1038,6 +1038,21 @@ const prisma = createPrismaCompatClient(db, PRISMA_MAP);
 const users = await prisma.User.findMany({ include: { posts: { take: 5 } } });
 ```
 
+Turbine-only query options (`forceCustomPlan`, `skipGlobalFilters`, `allowFullTableScan`,
+`warnOnUnlimited`, `timeout`, `optimisticLock`, `distinctOn`, …) pass through the compat
+delegates, and an unrecognized query-level key logs a one-time dev warning naming the
+nearest real option instead of being dropped.
+
+> **Correction, 0.57.0.** Before that release the adapter copied a hand-written allowlist
+> of keys, so those options were accepted by the type-checker and silently dropped. That
+> includes `forceCustomPlan`, which 0.56.0 shipped and `turbine doctor` recommended: on
+> prisma-compat it did nothing at all, while working exactly as documented on the core
+> client. Two changes are visible on upgrade even if you change nothing: `skipGlobalFilters`
+> now takes effect where it was inert, and `relationLoadStrategy: 'query'` now maps to
+> Turbine's `'batched'` instead of silently using the join plan. The option surface is now
+> compiler-checked against the core argument interfaces, so a newly added core option fails
+> the build in the adapter rather than being stranded in silence.
+
 ### Capability matrix
 
 Everything is honest about what ports and what doesn't. Features marked **PG-only** throw a typed `UnsupportedFeatureError` (`TURBINE_E017`) on other engines rather than silently degrading.

package/dist/cjs/cli/index.js

@@ -83,6 +83,8 @@ 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");
 const destructive_js_1 = require("./destructive.js");
@@ -2324,8 +2326,14 @@ async function cmdDoctor(args, config) {
     // one-connection snapshot rather than opening a second read.
     const divergenceOn = args.noPlanDivergence !== true;
     const divergenceColumns = divergenceOn ? (0, plan_divergence_js_1.collectDivergenceCandidateColumns)(schema) : [];
+    // The columns a finding could ORDER BY, read alongside the candidates: the
+    // size of an unindexed-filter flip turns on the ORDER column's correlation,
+    // not the filter column's, and reading only the latter is how an earlier
+    // revision printed a statistic about the wrong column.
+    const divergenceOrderColumns = divergenceOn ? (0, plan_divergence_js_1.collectDivergenceOrderColumns)(schema) : [];
     const probedTables = [...new Set(missing.map((m) => m.table))];
     const statsTables = [...new Set([...probedTables, ...divergenceColumns.map((c) => c.table)])];
+    const distributionColumns = [...divergenceColumns, ...divergenceOrderColumns];
     let snapshot;
     try {
         snapshot = await (0, index_stats_js_1.collectStatsSnapshot)({
@@ -2333,7 +2341,7 @@ async function cmdDoctor(args, config) {
             schema: config.schema,
             tables: statsTables,
             columns: probedColumns,
-            distributionColumns: divergenceColumns,
+            distributionColumns,
         });
     }
     catch (err) {
@@ -2376,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 };
+        : { 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));
@@ -2465,6 +2482,20 @@ function buildDoctorJson(ctx) {
     // just because the section was skipped or found nothing.
     out.planDivergence = ctx.divergence.findings;
     out.planDivergenceNotices = ctx.divergence.notices;
+    // How large the scored population was, and how it split. A consumer counting
+    // findings alone cannot tell "considered and clean" from "never looked", and
+    // the unindexed half of that population did not exist before.
+    out.planDivergenceScored = {
+        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;
 }
 async function renderDoctorHuman(ctx) {
@@ -2483,6 +2514,11 @@ async function renderDoctorHuman(ctx) {
         (0, ui_js_1.newline)();
         return;
     }
+    // One column, one place. An unindexed filter column that ALSO diverges is one
+    // problem with one remedy (the index), so the divergence evidence renders as
+    // an extra block on the missing-index finding rather than as a second,
+    // unrelated-looking entry in the cached-plan section.
+    const attached = attachDivergenceToMissingIndexes(findings, divergence);
     if (findings.length > 0) {
         (0, ui_js_1.warn)(`Found ${(0, ui_js_1.bold)(String(findings.length))} unindexed relation probe(s)`);
         (0, ui_js_1.newline)();
@@ -2490,10 +2526,10 @@ async function renderDoctorHuman(ctx) {
         console.log(`  ${(0, ui_js_1.dim)('once per parent row, so an unindexed FK costs a full table scan PER PARENT.')}`);
         (0, ui_js_1.newline)();
         if (usable) {
-            renderTiers(findings, snapshot, args);
+            renderTiers(findings, snapshot, args, attached);
         }
         else {
-            renderTopologyFallback(findings, snapshot);
+            renderTopologyFallback(findings, snapshot, attached);
         }
         // Heat honesty: one line when the workload-heat boost could not be sourced.
         if (!heat.available && heat.notice) {
@@ -2502,7 +2538,7 @@ async function renderDoctorHuman(ctx) {
         }
     }
     renderInvalidIndexes(invalid);
-    renderPlanDivergence(divergence);
+    renderPlanDivergence(divergence, attached);
     if (subtract.unusedRan) {
         renderUnusedIndexes(subtract.unused, subtract.minScans, snapshot);
         renderRedundantIndexes(subtract.redundant);
@@ -2599,8 +2635,96 @@ function renderDoctorAudit(audit, minScans, snapshot) {
     console.log(`  ${(0, ui_js_1.dim)('Consider dropping the ones you confirm are unused. Nothing here is auto-dropped.')}`);
     (0, ui_js_1.newline)();
 }
+function attachDivergenceToMissingIndexes(findings, divergence) {
+    const byColumn = new Map();
+    for (const d of divergence.findings) {
+        if (d.branch !== 'unindexed-filter')
+            continue;
+        byColumn.set(`${d.table}\u0000${d.column}`, d);
+    }
+    const attached = new Map();
+    for (const f of findings) {
+        // Single-column probes only: a composite probe's index is not the thing the
+        // single-column divergence model reasons about.
+        if (f.missing.columns.length !== 1 || f.missing.columns[0] === undefined)
+            continue;
+        const key = `${f.missing.table}\u0000${f.missing.columns[0]}`;
+        const d = byColumn.get(key);
+        if (d)
+            attached.set(key, d);
+    }
+    return attached;
+}
+/** The key a missing-index finding is looked up by in {@link AttachedDivergence}. */
+function attachKey(f) {
+    return `${f.missing.table}\u0000${f.missing.columns[0] ?? ''}`;
+}
+/**
+ * The cached-plan evidence block printed UNDER a missing-index finding.
+ *
+ * It never recommends `forceCustomPlan`: the remedy is the index the same
+ * finding already prints, and recommending a per-query plan-cache override for a
+ * missing index would be advice to paper over a table scan.
+ */
+/**
+ * How big an `unindexed-filter` flip is, and under what condition, as plain
+ * lines both branch-B renderers print.
+ *
+ * The condition is not decoration. The generic plan's cost is one heap fetch per
+ * index entry, so the ratio is the table's rows-per-page when the heap is not in
+ * `orderColumn` order and ~1x when it is: 80x and 1.2x on two fixtures identical
+ * in every scored input. An earlier revision printed the ratio unconditionally
+ * and quoted the FILTER column's correlation next to a sentence about the ORDER
+ * column's physical order, so the one field offered as the reader's escape hatch
+ * was measured on the wrong column.
+ */
+function divergenceAmplificationLines(d) {
+    const amp = divInt(d.worstCaseAmplification ?? 0);
+    const corr = d.orderColumnCorrelation;
+    const corrLabel = corr === null || corr === undefined
+        ? `no pg_stats correlation available for "${d.orderColumn}"`
+        : `correlation ${corr.toFixed(5)} on "${d.orderColumn}"`;
+    if (d.heapNearlyOrdered === true) {
+        return [
+            `The size of that flip turns on the heap's physical order, and THIS heap is in near-exact`,
+            `"${d.orderColumn}" order (${corrLabel}), so consecutive index entries hit the`,
+            `same pinned page: measured ~1x, not the ~${amp}x an unordered heap reads. Most likely this`,
+            `one is not costing you anything today. It is also one sampled statistic away from the`,
+            `much worse reading, so measure rather than assume in either direction.`,
+        ];
+    }
+    return [
+        `That costs ~${amp}x the buffers of the seq scan, because each index entry is its own heap`,
+        `fetch (${corrLabel}). The one shape that reads ~1x instead is a heap`,
+        `in near-exact "${d.orderColumn}" order; two pages of local disorder already reads ~41x.`,
+    ];
+}
+function renderDivergenceEvidence(d) {
+    const tuples = divInt(d.tuplesWalked ?? d.rows);
+    console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.yellow)('cached-plan risk:')} this unindexed filter column can also flip a cached plan.`);
+    console.log(`      ${(0, ui_js_1.dim)(`${divInt(d.rows)} rows in ${divInt(d.pages)} pages, rarest value ~${divInt(d.rarestBucket)} rows, below the assumed LIMIT ${d.assumedLimit}.`)}`);
+    console.log(`      ${(0, ui_js_1.dim)(`Without the index the good plan is a seq scan (${divInt(d.pages)} pages); a promoted generic`)}`);
+    console.log(`      ${(0, ui_js_1.dim)(`plan cannot see the value is rare, keeps the ordered "${d.orderColumn}" walk, and reads`)}`);
+    console.log(`      ${(0, ui_js_1.dim)(`up to ~${tuples} tuples before it fills the LIMIT.`)}`);
+    console.log(`      ${(0, ui_js_1.dim)('Postgres promotes this shape exactly when the workload keeps asking for the rare')}`);
+    console.log(`      ${(0, ui_js_1.dim)('value: that is the case where the custom plan is expensive enough for the generic')}`);
+    console.log(`      ${(0, ui_js_1.dim)('estimate to look cheaper.')}`);
+    for (const line of divergenceAmplificationLines(d))
+        console.log(`      ${(0, ui_js_1.dim)(line)}`);
+    console.log(`      ${(0, ui_js_1.dim)('Adding the index above is the fix. Confirm first if you want to:')}`);
+    for (const line of d.diagnosticSql.split('\n')) {
+        console.log(`        ${(0, ui_js_1.green)(line)}`);
+    }
+    console.log(`      ${(0, ui_js_1.dim)('After adding this index, re-run doctor. This column is expected to reappear as a')}`);
+    console.log(`      ${(0, ui_js_1.dim)('sparse-value finding in the cached-plan section. That later finding is exposure, not')}`);
+    console.log(`      ${(0, ui_js_1.dim)('a regression: the index makes the good plan much cheaper, which is why the ratio it')}`);
+    console.log(`      ${(0, ui_js_1.dim)('quotes is larger, and on a measured fixture it is also what stops Postgres from')}`);
+    console.log(`      ${(0, ui_js_1.dim)('promoting the generic plan at all. Treat the reappearance as the normal end state;')}`);
+    console.log(`      ${(0, ui_js_1.dim)("use the diagnostic block's generic_plans counter to decide whether anything more is")}`);
+    console.log(`      ${(0, ui_js_1.dim)('warranted.')}`);
+}
 /** Cost-aware tiered output: three sections, each finding annotated with its numbers. */
-function renderTiers(findings, snapshot, _args) {
+function renderTiers(findings, snapshot, _args, attached) {
     const ageLabel = snapshot.statsAgeDays !== null ? `${Math.round(snapshot.statsAgeDays)}d` : 'unknown';
     console.log(`  ${(0, ui_js_1.dim)(`Cost triage based on live statistics (stats reset ${ageLabel} ago). Thresholds: tiny < ${index_stats_js_1.STATS_THRESHOLDS.tinyTableRows.toLocaleString()} rows,`)}`);
     console.log(`  ${(0, ui_js_1.dim)(`"real" write rate >= ${index_stats_js_1.STATS_THRESHOLDS.highWritesPerDay.toLocaleString()}/day, "many" indexes >= ${index_stats_js_1.STATS_THRESHOLDS.manyIndexes}.`)}`);
@@ -2619,12 +2743,12 @@ function renderTiers(findings, snapshot, _args) {
         console.log(`  ${(0, ui_js_1.bold)(tierColor[tier](`${TIER_LABEL[tier]} (${inTier.length})`))}`);
         (0, ui_js_1.newline)();
         for (const f of inTier) {
-            renderFinding(f, { concurrently: true, withReasons: true });
+            renderFinding(f, { concurrently: true, withReasons: true, divergence: attached.get(attachKey(f)) });
         }
     }
 }
 /** Degraded output: today's size-sorted topology report when stats are absent/young. */
-function renderTopologyFallback(findings, snapshot) {
+function renderTopologyFallback(findings, snapshot, attached) {
     (0, ui_js_1.warn)('Statistics unavailable or too young to score cost: showing size-sorted topology only.');
     for (const notice of snapshot.notices)
         console.log(`  ${(0, ui_js_1.dim)(`- ${notice}`)}`);
@@ -2634,7 +2758,7 @@ function renderTopologyFallback(findings, snapshot) {
     (0, ui_js_1.newline)();
     const sorted = [...findings].sort((a, b) => (b.score.metrics.rows ?? 0) - (a.score.metrics.rows ?? 0));
     for (const f of sorted) {
-        renderFinding(f, { concurrently: false, withReasons: false });
+        renderFinding(f, { concurrently: false, withReasons: false, divergence: attached.get(attachKey(f)) });
     }
 }
 /** Render one finding: table + columns, probing relations, reasons, and the create SQL. */
@@ -2652,7 +2776,10 @@ function renderFinding(f, opts) {
             console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.dim)(reason)}`);
         }
     }
-    console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.green)(doctorCreateSql(f, { concurrently: opts.concurrently }))}`);
+    const last = opts.divergence ? ui_js_1.symbols.tee : ui_js_1.symbols.teeEnd;
+    console.log(`    ${(0, ui_js_1.dim)(last)} ${(0, ui_js_1.green)(doctorCreateSql(f, { concurrently: opts.concurrently }))}`);
+    if (opts.divergence)
+        renderDivergenceEvidence(opts.divergence);
     (0, ui_js_1.newline)();
 }
 /** The invalid-index report section (a failed CONCURRENTLY build leaves these behind). */
@@ -2668,6 +2795,42 @@ function renderInvalidIndexes(invalid) {
         (0, ui_js_1.newline)();
     }
 }
+/**
+ * The release in which `turbine-orm/prisma-compat` began forwarding Turbine-only
+ * query options (`forceCustomPlan` among them) to the core client.
+ *
+ * Printed rather than assumed, and the sentence stays even after that release:
+ * doctor's audience routinely runs a CLI newer than the library pinned in the
+ * app, and on an older library the option is accepted and silently ignored.
+ */
+const COMPAT_PASSTHROUGH_VERSION = '0.57.0';
+/**
+ * The gates + scored-population footer. Split out because it is printed from two
+ * places: the normal section, and the case where every finding was attached to a
+ * missing-index finding instead.
+ */
+function renderDivergenceGates(divergence) {
+    const t = plan_divergence_js_1.PLAN_DIVERGENCE_THRESHOLDS;
+    console.log(`  ${(0, ui_js_1.dim)(`Gates, indexed column: the wrong plan must walk >= ${t.minWalkPages} pages and >= ${Math.round(t.minWalkFraction * 100)}% of the table.`)}`);
+    console.log(`  ${(0, ui_js_1.dim)(`Gates, unindexed column: the rarest value must hold fewer rows than the limit, and the wrong`)}`);
+    console.log(`  ${(0, ui_js_1.dim)(`plan must walk >= ${t.minGenericTupleWalk.toLocaleString('en-US')} tuples. Assumed LIMIT ${t.assumedLimit} throughout.`)}`);
+    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) {
     if (!Number.isFinite(n))
@@ -2680,8 +2843,26 @@ function divInt(n) {
  * application code (scope the plan-cache mode to the affected reads), and the
  * index that looks like a fix is measured NOT to be one.
  */
-function renderPlanDivergence(divergence) {
-    const { findings, notices } = divergence;
+function renderPlanDivergence(divergence, attached) {
+    const { notices } = divergence;
+    // Anything already rendered as evidence on a missing-index finding is NOT
+    // repeated here: one column, one problem, one remedy.
+    const rendered = new Set(attached.values());
+    const findings = divergence.findings.filter((f) => !rendered.has(f));
+    // Every divergence finding was attached above, so this section has no entries
+    // of its own. The pointer, the gates and the scored population still belong in
+    // the report: they are output of THIS check, and a reader must be able to tell
+    // "considered and clean" from "never looked".
+    //
+    // Printed BEFORE the notices rather than inside an early return: an early
+    // return that also required `notices.length === 0` dropped both blocks
+    // whenever any candidate lacked a pg_stats row, which is the normal reason a
+    // notice exists.
+    if (findings.length === 0 && rendered.size > 0) {
+        console.log(`  ${(0, ui_js_1.dim)(`Cached-plan divergence: ${rendered.size} finding(s), shown with the index findings above.`)}`);
+        renderDivergenceGates(divergence);
+        (0, ui_js_1.newline)();
+    }
     if (findings.length === 0 && notices.length === 0)
         return;
     if (findings.length > 0) {
@@ -2694,16 +2875,39 @@ function renderPlanDivergence(divergence) {
         console.log(`  ${(0, ui_js_1.dim)('land on the other side of a plan boundary from the real value, the plan flips.')}`);
         (0, ui_js_1.newline)();
     }
+    const analyzedLabel = (f) => f.lastAnalyze === null
+        ? 'last ANALYZE unknown'
+        : `last analyzed ${Math.max(0, Math.round((Date.now() - f.lastAnalyze.getTime()) / 86_400_000))}d ago`;
     for (const f of findings) {
+        if (f.branch === 'unindexed-filter') {
+            // Only reached when the column has no missing-index finding to hang this
+            // on (an index that exists but cannot serve the equality: partial,
+            // expression, or non-btree). The remedy is still an index, not a
+            // plan-cache setting, so this entry never suggests forceCustomPlan.
+            console.log(`  ${(0, ui_js_1.yellow)(ui_js_1.symbols.warning)} ${(0, ui_js_1.bold)((0, ui_js_1.cyan)(`${f.table}.${f.column}`))}  ${(0, ui_js_1.gray)('UNINDEXED-FILTER FLIP')}`);
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${divInt(f.rows)} rows in ${divInt(f.pages)} pages, rarest value ~${(0, ui_js_1.bold)(divInt(f.rarestBucket))} rows, below the assumed LIMIT ${f.assumedLimit}`);
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} no index serves ${f.column} = $1, so the good plan is a seq scan (${divInt(f.pages)} pages);`);
+            console.log(`      ${(0, ui_js_1.dim)(`a promoted generic plan keeps the ordered "${f.orderColumn}" walk and reads up to ~${divInt(f.tuplesWalked ?? f.rows)} tuples`)}`);
+            console.log(`      ${(0, ui_js_1.dim)('before it fills the LIMIT.')}`);
+            for (const line of divergenceAmplificationLines(f))
+                console.log(`      ${(0, ui_js_1.dim)(line)}`);
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.dim)(`filter-column correlation ${f.correlation.toFixed(2)}, ${analyzedLabel(f)}`)}`);
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.dim)('the fix is an index that can serve this equality. A partial or expression index')}`);
+            console.log(`      ${(0, ui_js_1.dim)('on the column does not: the planner has no path for the bare predicate. A hash')}`);
+            console.log(`      ${(0, ui_js_1.dim)('index does, and a column served by one is scored by the other rule instead.')}`);
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.dim)('confirm with YOUR values before changing anything:')}`);
+            for (const line of f.diagnosticSql.split('\n')) {
+                console.log(`      ${(0, ui_js_1.green)(line)}`);
+            }
+            (0, ui_js_1.newline)();
+            continue;
+        }
         console.log(`  ${(0, ui_js_1.yellow)(ui_js_1.symbols.warning)} ${(0, ui_js_1.bold)((0, ui_js_1.cyan)(`${f.table}.${f.column}`))}  ${(0, ui_js_1.gray)('SPARSE-VALUE FLIP')}`);
         console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} generic estimate ${(0, ui_js_1.bold)(divInt(f.genericEstimate))} rows ${(0, ui_js_1.dim)(`(${divInt(f.rows)} rows / ${divInt(f.distinctValues)} distinct values)`)}`);
         console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} rarest value bucket ${(0, ui_js_1.bold)(divInt(f.rarestBucket))} rows ${(0, ui_js_1.dim)('(pg_stats most_common_freqs / residual bucket)')}`);
-        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} crossover ${(0, ui_js_1.bold)(divInt(f.crossoverRows))} rows ${(0, ui_js_1.dim)(`(sqrt(limit ${f.assumedLimit} x ${divInt(f.pages)} pages); ${divInt(f.crossoverRowsWide)} at limit ${f.thresholds.wideLimit})`)}`);
-        const analyzed = f.lastAnalyze === null
-            ? 'last ANALYZE unknown'
-            : `last analyzed ${Math.max(0, Math.round((Date.now() - f.lastAnalyze.getTime()) / 86_400_000))}d ago`;
-        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.dim)(`values below the crossover: ${divInt(f.valuesBelowCrossover)} of ${divInt(f.distinctValues)}, correlation ${f.correlation.toFixed(2)}, ${analyzed}`)}`);
-        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} for such a value the generic plan walks ~${(0, ui_js_1.bold)(divInt(f.walkPages))} of ${divInt(f.pages)} pages ${(0, ui_js_1.dim)(`(${Math.round(f.walkFraction * 100)}% of the table)`)}`);
+        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} crossover ${(0, ui_js_1.bold)(divInt(f.crossoverRows ?? 0))} rows ${(0, ui_js_1.dim)(`(sqrt(limit ${f.assumedLimit} x ${divInt(f.pages)} pages); ${divInt(f.crossoverRowsWide ?? 0)} at limit ${f.thresholds.wideLimit})`)}`);
+        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.dim)(`values below the crossover: ${divInt(f.valuesBelowCrossover ?? 0)} of ${divInt(f.distinctValues)}, filter-column correlation ${f.correlation.toFixed(2)}, ${analyzedLabel(f)}`)}`);
+        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} for such a value the generic plan walks ~${(0, ui_js_1.bold)(divInt(f.walkPages ?? 0))} of ${divInt(f.pages)} pages ${(0, ui_js_1.dim)(`(${Math.round((f.walkFraction ?? 0) * 100)}% of the table)`)}`);
         console.log(`      ${(0, ui_js_1.dim)(`for reads shaped WHERE ${f.column} = $1 ORDER BY ${f.orderColumn} LIMIT $n,`)}`);
         console.log(`      ${(0, ui_js_1.dim)("where the custom plan reads only that value's own rows.")}`);
         console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.dim)('No amplification figure is printed, deliberately. This models how many rows a')}`);
@@ -2716,6 +2920,7 @@ function renderPlanDivergence(divergence) {
         (0, ui_js_1.newline)();
     }
     if (findings.length > 0) {
+        const first = findings.find((f) => f.branch === 'sparse-value');
         console.log(`  ${(0, ui_js_1.bold)('What to do, in order:')}`);
         console.log(`    1. Check that this shape is promoted AT ALL. Step 1 of the block above: while`);
         console.log(`       ${(0, ui_js_1.dim)('generic_plans is 0, Postgres is planning with your real values and there is nothing')}`);
@@ -2723,27 +2928,68 @@ function renderPlanDivergence(divergence) {
         console.log(`    2. If it does promote, compare the two plans. Both SETs matter: without them a`);
         console.log(`       ${(0, ui_js_1.dim)('repeated seq scan resumes where the last one stopped and a catastrophic case reads')}`);
         console.log(`       ${(0, ui_js_1.dim)('as harmless.')}`);
-        console.log(`    3. If the flip is real, scope the fix to those reads:`);
-        const first = findings[0];
-        console.log(`       ${(0, ui_js_1.cyan)(`db.${first.table}.findMany({ where: { ${first.columnField}: value }, orderBy: { ${first.orderColumnField}: 'asc' },`)}`);
-        console.log(`       ${(0, ui_js_1.cyan)(`                     limit: 20, forceCustomPlan: true })`)}`);
-        console.log(`       ${(0, ui_js_1.dim)('That withholds the prepared-statement NAME for that one query, so the driver')}`);
-        console.log(`       ${(0, ui_js_1.dim)('re-parses it every execution and it is always planned with the real values. No')}`);
-        console.log(`       ${(0, ui_js_1.dim)('GUC, no SET LOCAL, no transaction, no extra round trip.')}`);
-        console.log(`    4. Do NOT set planCacheMode on the client to fix this. There are measured shapes`);
-        console.log(`       ${(0, ui_js_1.dim)('where a generic plan is dramatically better (an unordered LIMIT over a value whose')}`);
-        console.log(`       ${(0, ui_js_1.dim)('rows are packed at the end of the heap: 4,262 buffers custom vs 71 generic on a')}`);
-        console.log(`       ${(0, ui_js_1.dim)('reproducible fixture). A custom plan is not automatically the better plan.')}`);
-        console.log(`    5. A composite index on (${first.column}, ${first.orderColumn}) makes the GOOD plan better. It`);
-        console.log(`       ${(0, ui_js_1.dim)('does NOT stop the generic plan from choosing the other one, and it can widen the gap.')}`);
-        console.log(`       ${(0, ui_js_1.dim)('Add it for the custom-plan win, not as a fix for this finding.')}`);
+        if (first) {
+            // The OPTION is named first and both call shapes follow, so no step
+            // assumes which client the reader is holding. The compat example uses
+            // Prisma's `take`: printing `limit` there would be a second wrong
+            // instruction, since `limit` is a Turbine spelling compat does not read.
+            console.log(`    3. If the flip is real, scope the fix to those reads with ${(0, ui_js_1.cyan)('forceCustomPlan')}. It`);
+            console.log(`       ${(0, ui_js_1.dim)('withholds the prepared-statement NAME for that one query, so the driver re-parses')}`);
+            console.log(`       ${(0, ui_js_1.dim)('it every execution and it is always planned with the real values. No GUC, no SET')}`);
+            console.log(`       ${(0, ui_js_1.dim)('LOCAL, no transaction, no extra round trip.')}`);
+            // Hanging indent rather than an alignment that pretends to line up: the
+            // call's own width depends on the table name, so a fixed padding column
+            // misaligns on every schema but the one it was written against.
+            const args = `where: { ${first.columnField}: value }, orderBy: { ${first.orderColumnField}: 'asc' },`;
+            // The accessor is the camelCase FIELD spelling, not the raw table name:
+            // TurbineClient and the code generator both define table accessors through
+            // snakeToCamel, so `db.inventory_location` is undefined on every
+            // snake_case schema. The finding's own `columnField` / `orderColumnField`
+            // are already field-space for the same reason.
+            console.log(`       ${(0, ui_js_1.dim)('On the core client:')}`);
+            console.log(`         ${(0, ui_js_1.cyan)(`db.${(0, schema_js_1.snakeToCamel)(first.table)}.findMany({`)}`);
+            console.log(`           ${(0, ui_js_1.cyan)(args)}`);
+            console.log(`           ${(0, ui_js_1.cyan)('limit: 20, forceCustomPlan: true,')}`);
+            console.log(`         ${(0, ui_js_1.cyan)('})')}`);
+            console.log(`       ${(0, ui_js_1.dim)("Through turbine-orm/prisma-compat, the same option on the delegate call (Prisma's")}`);
+            console.log(`       ${(0, ui_js_1.dim)('`take`, not `limit`). The Prisma MODEL name is not knowable from the schema side,')}`);
+            console.log(`       ${(0, ui_js_1.dim)('so substitute your own:')}`);
+            console.log(`         ${(0, ui_js_1.cyan)('compat.<Model>.findMany({')}`);
+            console.log(`           ${(0, ui_js_1.cyan)(args)}`);
+            console.log(`           ${(0, ui_js_1.cyan)('take: 20, forceCustomPlan: true,')}`);
+            console.log(`         ${(0, ui_js_1.cyan)('})')}`);
+            console.log(`       ${(0, ui_js_1.dim)(`The compat passthrough requires turbine >= ${COMPAT_PASSTHROUGH_VERSION}. On an older version the option`)}`);
+            console.log(`       ${(0, ui_js_1.dim)('is accepted and ignored there, so confirm at the wire with the same')}`);
+            console.log(`       ${(0, ui_js_1.dim)('pg_prepared_statements check in step 1 rather than assuming it took effect.')}`);
+            console.log(`    4. Reaching for a database-wide plan_cache_mode is not the fix, whichever client you`);
+            console.log(`       ${(0, ui_js_1.dim)('use. There are measured shapes where a generic plan is dramatically better: an')}`);
+            console.log(`       ${(0, ui_js_1.dim)('unordered LIMIT over a value whose rows are packed at the end of the heap reads')}`);
+            console.log(`       ${(0, ui_js_1.dim)('4,262 buffers under a custom plan against 71 under a generic one. That fixture is')}`);
+            console.log(`       ${(0, ui_js_1.dim)('printed in full at turbineorm.dev/relations, so the number is checkable rather')}`);
+            console.log(`       ${(0, ui_js_1.dim)('than asserted. Pinning every statement')}`);
+            console.log(`       ${(0, ui_js_1.dim)('in one direction trades this finding for its mirror image. That applies equally to')}`);
+            console.log(`       ${(0, ui_js_1.dim)("Turbine's client-level `planCacheMode` and to a SET or ALTER ROLE applied outside")}`);
+            console.log(`       ${(0, ui_js_1.dim)('Turbine.')}`);
+            console.log(`    5. A composite index on (${first.column}, ${first.orderColumn}) makes the GOOD plan better. It`);
+            console.log(`       ${(0, ui_js_1.dim)('does NOT stop the generic plan from choosing the other one, and it can widen the gap.')}`);
+            console.log(`       ${(0, ui_js_1.dim)('Add it for the custom-plan win, not as a fix for this finding.')}`);
+        }
+        // Stated separately because the first remedy genuinely differs by branch: an
+        // UNINDEXED column's flip is fixed by the index, and a per-query plan-cache
+        // override there would only paper over a table scan.
+        if (findings.some((f) => f.branch === 'unindexed-filter')) {
+            console.log(`    ${first ? 6 : 3}. A finding on an UNINDEXED column has a different FIRST remedy: add an index that`);
+            console.log(`       ${(0, ui_js_1.dim)('serves the equality, then re-run doctor and re-score. The index moves the')}`);
+            console.log(`       ${(0, ui_js_1.dim)('divergence in both directions at once (it makes the good plan much cheaper, which')}`);
+            console.log(`       ${(0, ui_js_1.dim)('widens the ratio, and on a measured fixture it also stopped Postgres promoting the')}`);
+            console.log(`       ${(0, ui_js_1.dim)('generic plan at all), so do not assume the finding is closed by adding it.')}`);
+        }
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.dim)('This finding is derived from statistics, not from your traffic: it says the DISTRIBUTION')}`);
-        console.log(`  ${(0, ui_js_1.dim)('admits a damaging flip, not that a query is running one today. It models ONE shape,')}`);
-        console.log(`  ${(0, ui_js_1.dim)('the rare value that loses its bitmap plan. It cannot see where a value physically')}`);
-        console.log(`  ${(0, ui_js_1.dim)('sits in the heap, so a clean report is not evidence of immunity.')}`);
-        console.log(`  ${(0, ui_js_1.dim)(`Gates: the wrong plan must walk >= ${plan_divergence_js_1.PLAN_DIVERGENCE_THRESHOLDS.minWalkPages} pages and >= ${Math.round(plan_divergence_js_1.PLAN_DIVERGENCE_THRESHOLDS.minWalkFraction * 100)}% of the table, at an assumed`)}`);
-        console.log(`  ${(0, ui_js_1.dim)(`LIMIT ${plan_divergence_js_1.PLAN_DIVERGENCE_THRESHOLDS.assumedLimit}. ${divergence.candidatesConsidered} column(s) were scored. Skip this section with --no-plan-divergence.`)}`);
+        console.log(`  ${(0, ui_js_1.dim)('admits a damaging flip, not that a query is running one today. It cannot see where a')}`);
+        console.log(`  ${(0, ui_js_1.dim)('value physically sits in the heap, so a clean report is not evidence of immunity, and')}`);
+        console.log(`  ${(0, ui_js_1.dim)('a column that is neither an FK nor indexed is not in the scored population at all.')}`);
+        renderDivergenceGates(divergence);
         (0, ui_js_1.newline)();
     }
     if (notices.length > 0) {

package/dist/cjs/client.js

@@ -148,50 +148,14 @@ const CONFIG_KEY_SET = new Set(Object.keys(TURBINE_CONFIG_KEYS));
  *     engine factories' first argument. Same story as `schema`.
  */
 const NON_CONFIG_KEYS = new Set(['queryInterfaceFactory', 'schema', 'url']);
-/** camelCase name → its lowercased words (`logQueryParams` → log, query, params). */
-function camelWords(name) {
-    return name
-        .split(/(?=[A-Z])/)
-        .map((w) => w.toLowerCase())
-        .filter(Boolean);
-}
 /**
  * The real config key `key` most likely meant, or null when nothing is close.
  *
- * {@link closestName} (the same helper the unknown-COLUMN message uses) decides
- * first, so both diagnostics rank near-misses identically. It is bounded by edit
- * distance, which covers typos but not the miss this warning exists for: a
- * guessed name that omits a whole word. `logParams` is five edits from
- * `logQueryParams`, past the bound, yet it names the same words in the same
- * order, so a second pass accepts a candidate whose camelCase words CONTAIN the
- * guess's words in order, preferring the one that adds fewest words.
+ * {@link suggestKey} is shared with the prisma-compat query-option warner, so
+ * both diagnostics rank near-misses identically.
  */
 function suggestConfigKey(key) {
-    const direct = (0, utils_js_1.closestName)(key, CONFIG_KEY_SET);
-    if (direct)
-        return direct;
-    const wanted = camelWords(key);
-    if (wanted.length < 2)
-        return null;
-    let best = null;
-    let bestExtra = Number.POSITIVE_INFINITY;
-    for (const candidate of CONFIG_KEY_SET) {
-        const words = camelWords(candidate);
-        if (words.length <= wanted.length)
-            continue;
-        let i = 0;
-        for (const w of words)
-            if (w === wanted[i])
-                i++;
-        if (i !== wanted.length)
-            continue;
-        const extra = words.length - wanted.length;
-        if (extra < bestExtra) {
-            bestExtra = extra;
-            best = candidate;
-        }
-    }
-    return best;
+    return (0, utils_js_1.suggestKey)(key, CONFIG_KEY_SET);
 }
 /**
  * Dev-mode notice for a key on the config object that is not part of the config