turbine-orm 0.55.0 → 0.57.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. 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.d.ts

@@ -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)
@@ -61,6 +61,8 @@ export interface CliArgs {
     minScans?: number;
     /** `doctor --metrics-url <url>`: read _turbine_metrics for the table-heat boost from a separate DB. */
     metricsUrl?: string;
+    /** `doctor --no-plan-divergence`: skip the cached-plan divergence section (and its pg_stats read). */
+    noPlanDivergence?: boolean;
     /** `init --yes`/`-y`: accept every step's default non-interactively. */
     yes?: boolean;
     /** `init --skip-schema`: don't scaffold the schema file. */

package/dist/cjs/cli/index.js

@@ -15,7 +15,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)
@@ -82,6 +82,8 @@ const generate_js_1 = require("../generate.js");
 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 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");
@@ -192,6 +194,9 @@ 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;
@@ -2309,20 +2314,33 @@ async function cmdDoctor(args, config) {
     const missing = (0, index_advisor_js_1.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 ? (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)({
             connectionString: url,
             schema: config.schema,
-            tables: probedTables,
+            tables: statsTables,
             columns: probedColumns,
+            distributionColumns,
         });
     }
     catch (err) {
@@ -2361,9 +2379,16 @@ async function cmdDoctor(args, config) {
         ? (0, index_stats_js_1.auditDoctorIndexes)(snapshot, (0, index_advisor_js_1.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
+        ? (0, plan_divergence_js_1.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({
@@ -2375,6 +2400,7 @@ async function cmdDoctor(args, config) {
         usable,
         heat,
         subtract,
+        divergence,
         args,
         config,
     });
@@ -2442,13 +2468,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 ${(0, ui_js_1.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) {
@@ -2460,6 +2498,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)();
@@ -2467,10 +2510,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) {
@@ -2479,6 +2522,7 @@ async function renderDoctorHuman(ctx) {
         }
     }
     renderInvalidIndexes(invalid);
+    renderPlanDivergence(divergence, attached);
     if (subtract.unusedRan) {
         renderUnusedIndexes(subtract.unused, subtract.minScans, snapshot);
         renderRedundantIndexes(subtract.redundant);
@@ -2575,8 +2619,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}.`)}`);
@@ -2595,12 +2727,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}`)}`);
@@ -2610,7 +2742,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. */
@@ -2628,7 +2760,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). */
@@ -2644,6 +2779,198 @@ 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.')}`);
+}
+/** 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(`  ${(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) {
+        (0, ui_js_1.warn)(`${(0, ui_js_1.bold)(String(findings.length))} column(s) whose value distribution can flip a cached plan`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Postgres may promote a named prepared statement to a GENERIC plan from its sixth execution,')}`);
+        console.log(`  ${(0, ui_js_1.dim)('but only when the generic plan is not ESTIMATED to cost more than the average custom')}`);
+        console.log(`  ${(0, ui_js_1.dim)('plan. A generic plan cannot see your values: it estimates "col = $1" as rows /')}`);
+        console.log(`  ${(0, ui_js_1.dim)('n_distinct and an unknown LIMIT as 10% of the child estimate. When those defaults')}`);
+        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 ?? 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')}`);
+        console.log(`      ${(0, ui_js_1.dim)('value has, not WHERE they sit in the heap, and the second half can move the')}`);
+        console.log(`      ${(0, ui_js_1.dim)('real cost by an order of magnitude. Measure it 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)();
+    }
+    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')}`);
+        console.log(`       ${(0, ui_js_1.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(`       ${(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.')}`);
+        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 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) {
+        console.log(`  ${(0, ui_js_1.dim)('Not scored for cached-plan divergence (statistics missing):')}`);
+        for (const n of notices) {
+            console.log(`    ${(0, ui_js_1.dim)(`- ${n.table}.${n.column}: ${n.reason}`)}`);
+        }
+        (0, ui_js_1.newline)();
+    }
+}
 /** Write the --fix migration (CONCURRENTLY + directive by default; plain with --no-concurrently). */
 function renderFixMigration(findings, config, args) {
     const concurrently = args.noConcurrently !== true;
@@ -3117,7 +3444,7 @@ function showHelp() {
     console.log(`      ${(0, ui_js_1.dim)('status')}           Show applied/pending migrations`);
     console.log(`    ${(0, ui_js_1.cyan)('seed')}               Run seed file`);
     console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}      Show schema summary`);
-    console.log(`    ${(0, ui_js_1.cyan)('doctor')}             Cost-aware missing-FK-index triage ${(0, ui_js_1.dim)('(--fix, --json, --unused, --audit)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('doctor')}             Index + cached-plan triage ${(0, ui_js_1.dim)('(--fix, --json, --unused, --audit)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI ${(0, ui_js_1.dim)('(--write for writes, --demo for a sample DB)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${(0, ui_js_1.cyan)('observe')}            Launch metrics dashboard ${(0, ui_js_1.dim)('(requires TURBINE_OBSERVE_URL)')}`);

package/dist/cjs/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