turbine-orm 0.55.0 → 0.57.0

package/dist/cli/index.js

@@ -14,7 +14,7 @@
  *   turbine migrate status       , Show migration status
  *   turbine seed                 , Run seed file
  *   turbine status               , Show schema summary
- *   turbine doctor                - Cost-aware missing-FK-index triage (--fix, --json, --no-concurrently, --unused, --audit)
+ *   turbine doctor                - Index + cached-plan triage (--fix, --json, --no-concurrently, --unused, --audit, --no-plan-divergence)
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
  *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
@@ -32,6 +32,8 @@ import { generate, generatePrismaMap } from '../generate.js';
 import { buildCreateIndexSql, buildDropIndexSql, collectDoctorProbeIndexNames, collectRelationProbeColumns, findMissingRelationIndexes, } from '../index-advisor.js';
 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 { 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';
 import { DESTRUCTIVE_KIND_LABEL } from './destructive.js';
@@ -142,6 +144,9 @@ export function parseArgs(argv = process.argv.slice(2)) {
                 result.metricsUrl = next;
                 i++;
                 break;
+            case '--no-plan-divergence':
+                result.noPlanDivergence = true;
+                break;
             case '--zod':
                 result.zod = true;
                 break;
@@ -2259,20 +2264,33 @@ async function cmdDoctor(args, config) {
     const missing = findMissingRelationIndexes(schema);
     // Collect live statistics. The collector reads whole-schema indexes (for
     // invalid-index detection) plus per-table stats + probed-column null_frac.
-    const probedTables = [...new Set(missing.map((m) => m.table))];
     const probedColumns = [];
     for (const m of missing) {
         if (m.columns.length === 1 && m.columns[0] !== undefined) {
             probedColumns.push({ table: m.table, column: m.columns[0] });
         }
     }
+    // Plan-divergence candidates are the columns that ARE indexed, so their tables
+    // are usually disjoint from the missing-index set: both lists feed the same
+    // one-connection snapshot rather than opening a second read.
+    const divergenceOn = args.noPlanDivergence !== true;
+    const divergenceColumns = divergenceOn ? 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 ? 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 collectStatsSnapshot({
             connectionString: url,
             schema: config.schema,
-            tables: probedTables,
+            tables: statsTables,
             columns: probedColumns,
+            distributionColumns,
         });
     }
     catch (err) {
@@ -2311,9 +2329,16 @@ async function cmdDoctor(args, config) {
         ? auditDoctorIndexes(snapshot, collectDoctorProbeIndexNames(schema), { minScans, relationProbes })
         : [];
     const subtract = { unusedRan, auditRan, minScans, unused, redundant, audit };
+    // Plan divergence has its OWN freshness gate. The cost tiers require a
+    // 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
+        ? findPlanDivergence(schema, snapshot)
+        : { findings: [], notices: [], candidatesConsidered: 0, consideredIndexed: 0, consideredUnindexed: 0 };
     if (jsonMode) {
         spinner?.stop();
-        console.log(JSON.stringify(buildDoctorJson({ schema, findings, invalid, snapshot, usable, heat, subtract, args }), null, 2));
+        console.log(JSON.stringify(buildDoctorJson({ schema, findings, invalid, snapshot, usable, heat, subtract, divergence, args }), null, 2));
         return;
     }
     await renderDoctorHuman({
@@ -2325,6 +2350,7 @@ async function cmdDoctor(args, config) {
         usable,
         heat,
         subtract,
+        divergence,
         args,
         config,
     });
@@ -2392,13 +2418,25 @@ function buildDoctorJson(ctx) {
     out.redundant = ctx.subtract.unusedRan ? ctx.subtract.redundant : [];
     out.audit = ctx.subtract.auditRan ? ctx.subtract.audit : [];
     out.invalid = ctx.invalid;
+    // Always an array, never absent: a consumer must not have to write `?? []`
+    // 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,
+    };
     return out;
 }
 async function renderDoctorHuman(ctx) {
-    const { spinner, schema, findings, invalid, snapshot, usable, heat, subtract, args, config } = ctx;
+    const { spinner, schema, findings, invalid, snapshot, usable, heat, subtract, divergence, args, config } = ctx;
     spinner.succeed(`Scanned ${bold(String(Object.keys(schema.tables).length))} tables`);
     const subtractRan = subtract.unusedRan || subtract.auditRan;
-    const nothingToAdd = findings.length === 0 && invalid.length === 0;
+    const nothingToAdd = findings.length === 0 && invalid.length === 0 && divergence.findings.length === 0;
     const nothingToSubtract = subtract.unused.length === 0 && subtract.redundant.length === 0 && subtract.audit.length === 0;
     if (nothingToAdd && (!subtractRan || nothingToSubtract)) {
         if (subtractRan) {
@@ -2410,6 +2448,11 @@ async function renderDoctorHuman(ctx) {
         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) {
         warn(`Found ${bold(String(findings.length))} unindexed relation probe(s)`);
         newline();
@@ -2417,10 +2460,10 @@ async function renderDoctorHuman(ctx) {
         console.log(`  ${dim('once per parent row, so an unindexed FK costs a full table scan PER PARENT.')}`);
         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) {
@@ -2429,6 +2472,7 @@ async function renderDoctorHuman(ctx) {
         }
     }
     renderInvalidIndexes(invalid);
+    renderPlanDivergence(divergence, attached);
     if (subtract.unusedRan) {
         renderUnusedIndexes(subtract.unused, subtract.minScans, snapshot);
         renderRedundantIndexes(subtract.redundant);
@@ -2525,8 +2569,96 @@ function renderDoctorAudit(audit, minScans, snapshot) {
     console.log(`  ${dim('Consider dropping the ones you confirm are unused. Nothing here is auto-dropped.')}`);
     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(`    ${dim(symbols.tee)} ${yellow('cached-plan risk:')} this unindexed filter column can also flip a cached plan.`);
+    console.log(`      ${dim(`${divInt(d.rows)} rows in ${divInt(d.pages)} pages, rarest value ~${divInt(d.rarestBucket)} rows, below the assumed LIMIT ${d.assumedLimit}.`)}`);
+    console.log(`      ${dim(`Without the index the good plan is a seq scan (${divInt(d.pages)} pages); a promoted generic`)}`);
+    console.log(`      ${dim(`plan cannot see the value is rare, keeps the ordered "${d.orderColumn}" walk, and reads`)}`);
+    console.log(`      ${dim(`up to ~${tuples} tuples before it fills the LIMIT.`)}`);
+    console.log(`      ${dim('Postgres promotes this shape exactly when the workload keeps asking for the rare')}`);
+    console.log(`      ${dim('value: that is the case where the custom plan is expensive enough for the generic')}`);
+    console.log(`      ${dim('estimate to look cheaper.')}`);
+    for (const line of divergenceAmplificationLines(d))
+        console.log(`      ${dim(line)}`);
+    console.log(`      ${dim('Adding the index above is the fix. Confirm first if you want to:')}`);
+    for (const line of d.diagnosticSql.split('\n')) {
+        console.log(`        ${green(line)}`);
+    }
+    console.log(`      ${dim('After adding this index, re-run doctor. This column is expected to reappear as a')}`);
+    console.log(`      ${dim('sparse-value finding in the cached-plan section. That later finding is exposure, not')}`);
+    console.log(`      ${dim('a regression: the index makes the good plan much cheaper, which is why the ratio it')}`);
+    console.log(`      ${dim('quotes is larger, and on a measured fixture it is also what stops Postgres from')}`);
+    console.log(`      ${dim('promoting the generic plan at all. Treat the reappearance as the normal end state;')}`);
+    console.log(`      ${dim("use the diagnostic block's generic_plans counter to decide whether anything more is")}`);
+    console.log(`      ${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(`  ${dim(`Cost triage based on live statistics (stats reset ${ageLabel} ago). Thresholds: tiny < ${STATS_THRESHOLDS.tinyTableRows.toLocaleString()} rows,`)}`);
     console.log(`  ${dim(`"real" write rate >= ${STATS_THRESHOLDS.highWritesPerDay.toLocaleString()}/day, "many" indexes >= ${STATS_THRESHOLDS.manyIndexes}.`)}`);
@@ -2545,12 +2677,12 @@ function renderTiers(findings, snapshot, _args) {
         console.log(`  ${bold(tierColor[tier](`${TIER_LABEL[tier]} (${inTier.length})`))}`);
         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) {
     warn('Statistics unavailable or too young to score cost: showing size-sorted topology only.');
     for (const notice of snapshot.notices)
         console.log(`  ${dim(`- ${notice}`)}`);
@@ -2560,7 +2692,7 @@ function renderTopologyFallback(findings, snapshot) {
     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. */
@@ -2578,7 +2710,10 @@ function renderFinding(f, opts) {
             console.log(`    ${dim(symbols.tee)} ${dim(reason)}`);
         }
     }
-    console.log(`    ${dim(symbols.teeEnd)} ${green(doctorCreateSql(f, { concurrently: opts.concurrently }))}`);
+    const last = opts.divergence ? symbols.tee : symbols.teeEnd;
+    console.log(`    ${dim(last)} ${green(doctorCreateSql(f, { concurrently: opts.concurrently }))}`);
+    if (opts.divergence)
+        renderDivergenceEvidence(opts.divergence);
     newline();
 }
 /** The invalid-index report section (a failed CONCURRENTLY build leaves these behind). */
@@ -2594,6 +2729,198 @@ function renderInvalidIndexes(invalid) {
         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_THRESHOLDS;
+    console.log(`  ${dim(`Gates, indexed column: the wrong plan must walk >= ${t.minWalkPages} pages and >= ${Math.round(t.minWalkFraction * 100)}% of the table.`)}`);
+    console.log(`  ${dim(`Gates, unindexed column: the rarest value must hold fewer rows than the limit, and the wrong`)}`);
+    console.log(`  ${dim(`plan must walk >= ${t.minGenericTupleWalk.toLocaleString('en-US')} tuples. Assumed LIMIT ${t.assumedLimit} throughout.`)}`);
+    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.')}`);
+}
+/** Round to a whole number and group it, for the divergence report's estimates. */
+function divInt(n) {
+    if (!Number.isFinite(n))
+        return 'unbounded';
+    return Math.round(n).toLocaleString('en-US');
+}
+/**
+ * The plan-divergence section: columns whose value distribution can flip a
+ * cached plan. Finding-only by design, there is no `--fix` for it: the fix is
+ * 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, 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(`  ${dim(`Cached-plan divergence: ${rendered.size} finding(s), shown with the index findings above.`)}`);
+        renderDivergenceGates(divergence);
+        newline();
+    }
+    if (findings.length === 0 && notices.length === 0)
+        return;
+    if (findings.length > 0) {
+        warn(`${bold(String(findings.length))} column(s) whose value distribution can flip a cached plan`);
+        newline();
+        console.log(`  ${dim('Postgres may promote a named prepared statement to a GENERIC plan from its sixth execution,')}`);
+        console.log(`  ${dim('but only when the generic plan is not ESTIMATED to cost more than the average custom')}`);
+        console.log(`  ${dim('plan. A generic plan cannot see your values: it estimates "col = $1" as rows /')}`);
+        console.log(`  ${dim('n_distinct and an unknown LIMIT as 10% of the child estimate. When those defaults')}`);
+        console.log(`  ${dim('land on the other side of a plan boundary from the real value, the plan flips.')}`);
+        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(`  ${yellow(symbols.warning)} ${bold(cyan(`${f.table}.${f.column}`))}  ${gray('UNINDEXED-FILTER FLIP')}`);
+            console.log(`    ${dim(symbols.tee)} ${divInt(f.rows)} rows in ${divInt(f.pages)} pages, rarest value ~${bold(divInt(f.rarestBucket))} rows, below the assumed LIMIT ${f.assumedLimit}`);
+            console.log(`    ${dim(symbols.tee)} no index serves ${f.column} = $1, so the good plan is a seq scan (${divInt(f.pages)} pages);`);
+            console.log(`      ${dim(`a promoted generic plan keeps the ordered "${f.orderColumn}" walk and reads up to ~${divInt(f.tuplesWalked ?? f.rows)} tuples`)}`);
+            console.log(`      ${dim('before it fills the LIMIT.')}`);
+            for (const line of divergenceAmplificationLines(f))
+                console.log(`      ${dim(line)}`);
+            console.log(`    ${dim(symbols.tee)} ${dim(`filter-column correlation ${f.correlation.toFixed(2)}, ${analyzedLabel(f)}`)}`);
+            console.log(`    ${dim(symbols.tee)} ${dim('the fix is an index that can serve this equality. A partial or expression index')}`);
+            console.log(`      ${dim('on the column does not: the planner has no path for the bare predicate. A hash')}`);
+            console.log(`      ${dim('index does, and a column served by one is scored by the other rule instead.')}`);
+            console.log(`    ${dim(symbols.teeEnd)} ${dim('confirm with YOUR values before changing anything:')}`);
+            for (const line of f.diagnosticSql.split('\n')) {
+                console.log(`      ${green(line)}`);
+            }
+            newline();
+            continue;
+        }
+        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(`${f.table}.${f.column}`))}  ${gray('SPARSE-VALUE FLIP')}`);
+        console.log(`    ${dim(symbols.tee)} generic estimate ${bold(divInt(f.genericEstimate))} rows ${dim(`(${divInt(f.rows)} rows / ${divInt(f.distinctValues)} distinct values)`)}`);
+        console.log(`    ${dim(symbols.tee)} rarest value bucket ${bold(divInt(f.rarestBucket))} rows ${dim('(pg_stats most_common_freqs / residual bucket)')}`);
+        console.log(`    ${dim(symbols.tee)} crossover ${bold(divInt(f.crossoverRows ?? 0))} rows ${dim(`(sqrt(limit ${f.assumedLimit} x ${divInt(f.pages)} pages); ${divInt(f.crossoverRowsWide ?? 0)} at limit ${f.thresholds.wideLimit})`)}`);
+        console.log(`    ${dim(symbols.tee)} ${dim(`values below the crossover: ${divInt(f.valuesBelowCrossover ?? 0)} of ${divInt(f.distinctValues)}, filter-column correlation ${f.correlation.toFixed(2)}, ${analyzedLabel(f)}`)}`);
+        console.log(`    ${dim(symbols.tee)} for such a value the generic plan walks ~${bold(divInt(f.walkPages ?? 0))} of ${divInt(f.pages)} pages ${dim(`(${Math.round((f.walkFraction ?? 0) * 100)}% of the table)`)}`);
+        console.log(`      ${dim(`for reads shaped WHERE ${f.column} = $1 ORDER BY ${f.orderColumn} LIMIT $n,`)}`);
+        console.log(`      ${dim("where the custom plan reads only that value's own rows.")}`);
+        console.log(`    ${dim(symbols.tee)} ${dim('No amplification figure is printed, deliberately. This models how many rows a')}`);
+        console.log(`      ${dim('value has, not WHERE they sit in the heap, and the second half can move the')}`);
+        console.log(`      ${dim('real cost by an order of magnitude. Measure it instead:')}`);
+        console.log(`    ${dim(symbols.teeEnd)} ${dim('confirm with YOUR values before changing anything:')}`);
+        for (const line of f.diagnosticSql.split('\n')) {
+            console.log(`      ${green(line)}`);
+        }
+        newline();
+    }
+    if (findings.length > 0) {
+        const first = findings.find((f) => f.branch === 'sparse-value');
+        console.log(`  ${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(`       ${dim('generic_plans is 0, Postgres is planning with your real values and there is nothing')}`);
+        console.log(`       ${dim('to fix. A finding is exposure, not an incident, and many shapes never promote.')}`);
+        console.log(`    2. If it does promote, compare the two plans. Both SETs matter: without them a`);
+        console.log(`       ${dim('repeated seq scan resumes where the last one stopped and a catastrophic case reads')}`);
+        console.log(`       ${dim('as harmless.')}`);
+        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 ${cyan('forceCustomPlan')}. It`);
+            console.log(`       ${dim('withholds the prepared-statement NAME for that one query, so the driver re-parses')}`);
+            console.log(`       ${dim('it every execution and it is always planned with the real values. No GUC, no SET')}`);
+            console.log(`       ${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(`       ${dim('On the core client:')}`);
+            console.log(`         ${cyan(`db.${snakeToCamel(first.table)}.findMany({`)}`);
+            console.log(`           ${cyan(args)}`);
+            console.log(`           ${cyan('limit: 20, forceCustomPlan: true,')}`);
+            console.log(`         ${cyan('})')}`);
+            console.log(`       ${dim("Through turbine-orm/prisma-compat, the same option on the delegate call (Prisma's")}`);
+            console.log(`       ${dim('`take`, not `limit`). The Prisma MODEL name is not knowable from the schema side,')}`);
+            console.log(`       ${dim('so substitute your own:')}`);
+            console.log(`         ${cyan('compat.<Model>.findMany({')}`);
+            console.log(`           ${cyan(args)}`);
+            console.log(`           ${cyan('take: 20, forceCustomPlan: true,')}`);
+            console.log(`         ${cyan('})')}`);
+            console.log(`       ${dim(`The compat passthrough requires turbine >= ${COMPAT_PASSTHROUGH_VERSION}. On an older version the option`)}`);
+            console.log(`       ${dim('is accepted and ignored there, so confirm at the wire with the same')}`);
+            console.log(`       ${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(`       ${dim('use. There are measured shapes where a generic plan is dramatically better: an')}`);
+            console.log(`       ${dim('unordered LIMIT over a value whose rows are packed at the end of the heap reads')}`);
+            console.log(`       ${dim('4,262 buffers under a custom plan against 71 under a generic one. That fixture is')}`);
+            console.log(`       ${dim('printed in full at turbineorm.dev/relations, so the number is checkable rather')}`);
+            console.log(`       ${dim('than asserted. Pinning every statement')}`);
+            console.log(`       ${dim('in one direction trades this finding for its mirror image. That applies equally to')}`);
+            console.log(`       ${dim("Turbine's client-level `planCacheMode` and to a SET or ALTER ROLE applied outside")}`);
+            console.log(`       ${dim('Turbine.')}`);
+            console.log(`    5. A composite index on (${first.column}, ${first.orderColumn}) makes the GOOD plan better. It`);
+            console.log(`       ${dim('does NOT stop the generic plan from choosing the other one, and it can widen the gap.')}`);
+            console.log(`       ${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(`       ${dim('serves the equality, then re-run doctor and re-score. The index moves the')}`);
+            console.log(`       ${dim('divergence in both directions at once (it makes the good plan much cheaper, which')}`);
+            console.log(`       ${dim('widens the ratio, and on a measured fixture it also stopped Postgres promoting the')}`);
+            console.log(`       ${dim('generic plan at all), so do not assume the finding is closed by adding it.')}`);
+        }
+        newline();
+        console.log(`  ${dim('This finding is derived from statistics, not from your traffic: it says the DISTRIBUTION')}`);
+        console.log(`  ${dim('admits a damaging flip, not that a query is running one today. It cannot see where a')}`);
+        console.log(`  ${dim('value physically sits in the heap, so a clean report is not evidence of immunity, and')}`);
+        console.log(`  ${dim('a column that is neither an FK nor indexed is not in the scored population at all.')}`);
+        renderDivergenceGates(divergence);
+        newline();
+    }
+    if (notices.length > 0) {
+        console.log(`  ${dim('Not scored for cached-plan divergence (statistics missing):')}`);
+        for (const n of notices) {
+            console.log(`    ${dim(`- ${n.table}.${n.column}: ${n.reason}`)}`);
+        }
+        newline();
+    }
+}
 /** Write the --fix migration (CONCURRENTLY + directive by default; plain with --no-concurrently). */
 function renderFixMigration(findings, config, args) {
     const concurrently = args.noConcurrently !== true;
@@ -3067,7 +3394,7 @@ function showHelp() {
     console.log(`      ${dim('status')}           Show applied/pending migrations`);
     console.log(`    ${cyan('seed')}               Run seed file`);
     console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
-    console.log(`    ${cyan('doctor')}             Cost-aware missing-FK-index triage ${dim('(--fix, --json, --unused, --audit)')}`);
+    console.log(`    ${cyan('doctor')}             Index + cached-plan triage ${dim('(--fix, --json, --unused, --audit)')}`);
     console.log(`    ${cyan('studio')}             Launch local read-only web UI ${dim('(--write for writes, --demo for a sample DB)')}`);
     console.log(`    ${cyan('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);

package/dist/client.d.ts

@@ -295,7 +295,22 @@ export interface TurbineConfig {
      * Default `undefined`: Turbine issues NOTHING and the backend keeps its own
      * default (`auto`), byte-identical to not setting the option.
      *
-     * SESSION-LEVEL, NOT PER QUERY. It is applied as a connection parameter
+     * SESSION-LEVEL. THE PER-QUERY LEVER IS A DIFFERENT, NARROWER ONE. This
+     * option is a connection parameter and cannot be unset for a single query, so
+     * a client-wide value cannot express "custom here, `auto` there". The read
+     * option `forceCustomPlan: true` covers that case, and only that case: it
+     * withholds the prepared-statement NAME for one query, and because the driver
+     * re-parses an unnamed statement on every execution, the counter that
+     * promotion depends on is reset before it is ever reached. That
+     * mechanism can only ever mean custom, so there is deliberately no per-query
+     * `force_generic_plan`; that direction stays here, at the connection. The two
+     * do NOT compose in the other order either: `'force_generic_plan'` set here
+     * governs unnamed statements as well as named ones (measured), so a
+     * per-query `forceCustomPlan: true` cannot escape it and is REFUSED with
+     * `ValidationError` (E003) instead of silently doing nothing. Leave this
+     * option unset (or `'auto'`) if any query needs the per-query lever.
+     *
+     * IT IS APPLIED as a connection parameter
      * (`options=-c plan_cache_mode=...`) when the pool opens a connection, so it
      * is in force for that connection's very first statement and persists for its
      * whole life: every pooled checkout, `$transaction`, stream and pipeline on

package/dist/client.js

@@ -27,7 +27,7 @@ import { setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationE
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
-import { closestName, markTurbineParser, quoteIdent, registerUtcTemporalParsers, warnParserOverwrite, } from './query/utils.js';
+import { markTurbineParser, quoteIdent, registerUtcTemporalParsers, suggestKey, warnParserOverwrite, } from './query/utils.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { createSubscription, validateChannel, } from './realtime.js';
 import { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
@@ -141,50 +141,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 = 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 suggestKey(key, CONFIG_KEY_SET);
 }
 /**
  * Dev-mode notice for a key on the config object that is not part of the config
@@ -650,6 +614,10 @@ export class TurbineClient {
             jsonEncoding: config.jsonEncoding,
             globalFilters: config.globalFilters,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
+            // Forwarded so a per-query `forceCustomPlan` can refuse the combination
+            // this client's own connections would silently defeat, see the
+            // `planCacheMode` note on QueryInterfaceOptions.
+            planCacheMode,
             sqlCache: config.sqlCache ?? true,
             sqlCacheSize: config.sqlCacheSize,
             dialect: config.dialect,

package/dist/dialect.d.ts

@@ -375,6 +375,15 @@ export interface Dialect {
      * setting (`SET plan_cache_mode = auto | force_custom_plan |
      * force_generic_plan`). Gates the opt-in `planCacheMode` client option.
      *
+     * It ALSO gates the per-query `forceCustomPlan` read option, which uses a
+     * different mechanism (it withholds the prepared-statement name, so the
+     * driver re-parses the statement on every execution and the counter that
+     * generic-plan promotion depends on never reaches its threshold) but
+     * asks the identical capability question: does this engine have a PostgreSQL
+     * plan cache whose generic-plan promotion is worth pinning? An engine that
+     * answers no cannot honour either option, so both refuse on the same flag
+     * rather than on two flags that could never disagree.
+     *
      * A capability flag rather than a `dialect.name === 'postgresql'` test, for
      * the same reason every other refusal here is one: the setting is a property
      * of the PostgreSQL PLAN CACHE, not of the SQL string, so a