turbine-orm 0.55.0 → 0.56.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. 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.
 

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,7 @@ 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_sql_js_1 = require("../schema-sql.js");
 const config_js_1 = require("./config.js");
 const destructive_js_1 = require("./destructive.js");
@@ -192,6 +193,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 +2313,27 @@ 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) : [];
+    const probedTables = [...new Set(missing.map((m) => m.table))];
+    const statsTables = [...new Set([...probedTables, ...divergenceColumns.map((c) => c.table)])];
     let snapshot;
     try {
         snapshot = await (0, index_stats_js_1.collectStatsSnapshot)({
             connectionString: url,
             schema: config.schema,
-            tables: probedTables,
+            tables: statsTables,
             columns: probedColumns,
+            distributionColumns: divergenceColumns,
         });
     }
     catch (err) {
@@ -2361,9 +2372,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 };
     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 +2393,7 @@ async function cmdDoctor(args, config) {
         usable,
         heat,
         subtract,
+        divergence,
         args,
         config,
     });
@@ -2442,13 +2461,17 @@ 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;
     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) {
@@ -2479,6 +2502,7 @@ async function renderDoctorHuman(ctx) {
         }
     }
     renderInvalidIndexes(invalid);
+    renderPlanDivergence(divergence);
     if (subtract.unusedRan) {
         renderUnusedIndexes(subtract.unused, subtract.minScans, snapshot);
         renderRedundantIndexes(subtract.redundant);
@@ -2644,6 +2668,92 @@ function renderInvalidIndexes(invalid) {
         (0, ui_js_1.newline)();
     }
 }
+/** 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) {
+    const { findings, notices } = divergence;
+    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)();
+    }
+    for (const f of findings) {
+        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)(`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) {
+        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.')}`);
+        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.')}`);
+        (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.`)}`);
+        (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 +3227,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

package/dist/cjs/client.js

@@ -658,6 +658,10 @@ 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/cjs/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

package/dist/cjs/index-stats.d.ts

@@ -86,6 +86,12 @@ export interface TableStats {
     table: string;
     /** pg_class.reltuples. 0 or -1 means never-analyzed → treated as UNKNOWN (null rows). */
     reltuples: number;
+    /**
+     * pg_class.relpages. The SIZE input the plan-divergence crossover is computed
+     * from (a plan boundary tracks pages relative to the LIMIT, not rows).
+     * Absent when the pg_class read degraded; 0 means never analyzed.
+     */
+    relpages?: number;
     /** pg_stat_user_tables.n_live_tup, a cross-check for reltuples. */
     nLiveTup?: number;
     nTupIns?: number;
@@ -100,6 +106,13 @@ export interface TableStats {
     tableSizeBytes?: number;
     /** Count of indexes already on the table (pg_index). */
     existingIndexCount?: number;
+    /**
+     * The later of pg_stat_user_tables.last_analyze / last_autoanalyze: when the
+     * planner's column statistics were last refreshed. This, NOT stats_reset, is
+     * the freshness that matters for anything read out of pg_stats. Null when
+     * never analyzed; absent when the pg_stat read degraded.
+     */
+    lastAnalyze?: Date | null;
 }
 /**
  * Placeholder for an index column that is an EXPRESSION, not a plain column
@@ -133,6 +146,27 @@ export interface IndexStat {
     /** pg_relation_size of the index heap, bytes. Size reclaimed by a drop. */
     sizeBytes?: number;
 }
+/**
+ * The value distribution of one column, read from pg_stats with
+ * `inherited = false`. Consumed by the plan-divergence advisor, which needs to
+ * reproduce the planner's OWN estimates rather than approximate them.
+ */
+export interface ColumnDistribution {
+    table: string;
+    column: string;
+    /**
+     * pg_stats.n_distinct, RAW: a positive value is a count, a negative value is a
+     * fraction of the row count. Kept undecoded so the consumer decodes it exactly
+     * the way the planner does. 0 means the column was never analyzed.
+     */
+    nDistinct: number;
+    /** pg_stats.correlation, signed. NULL for types with no ordering. */
+    correlation: number | null;
+    /** pg_stats.most_common_freqs, or null when the column has no MCV list. */
+    mostCommonFreqs: number[] | null;
+    /** cardinality(most_common_vals): how many values the MCV list actually covers. */
+    mcvCount: number;
+}
 /**
  * A point-in-time read of the statistics the triage needs. Every part is
  * optional at the field level so the pure scorer degrades honestly.
@@ -150,6 +184,13 @@ export interface StatsSnapshot {
     indexes: IndexStat[];
     /** null_frac per probed column, keyed `table.column`. */
     nullFrac: Record<string, number>;
+    /**
+     * Value distribution per candidate column, keyed `table.column`. Optional at
+     * the snapshot level: a caller that never asked for distribution statistics
+     * (or whose pg_stats read degraded) leaves it absent, and the plan-divergence
+     * advisor reports that as a suppressed candidate rather than scoring a guess.
+     */
+    columnStats?: Record<string, ColumnDistribution>;
     /** Per-signal degradation notices (privileges, catalog gaps, timeouts). */
     notices: string[];
 }
@@ -347,6 +388,11 @@ export interface CollectSnapshotOptions {
     tables: string[];
     /** Columns to read null_frac for (single-column probes). */
     columns: ProbedColumn[];
+    /**
+     * Columns to read the full value distribution for (n_distinct, correlation,
+     * MCV frequencies). One extra pg_stats query; empty skips it entirely.
+     */
+    distributionColumns?: ProbedColumn[];
     /** statement_timeout for each catalog read. Default 5000ms. */
     statementTimeoutMs?: number;
 }

package/dist/cjs/index-stats.js

@@ -148,6 +148,7 @@ function emptyStatsSnapshot(notices = []) {
         tables: {},
         indexes: [],
         nullFrac: {},
+        columnStats: {},
         notices,
     };
 }
@@ -590,12 +591,14 @@ async function collectStatsSnapshot(options) {
             }
         }
         // --- table stats (pg_stat_user_tables) ---------------------------------
-        const statRows = await run('pg_stat_user_tables', `SELECT relname, n_tup_ins, n_tup_upd, n_tup_del, n_tup_hot_upd, seq_scan, seq_tup_read, n_live_tup
+        const statRows = await run('pg_stat_user_tables', `SELECT relname, n_tup_ins, n_tup_upd, n_tup_del, n_tup_hot_upd, seq_scan, seq_tup_read, n_live_tup,
+              greatest(last_analyze, last_autoanalyze) AS last_analyze
          FROM pg_stat_user_tables
         WHERE schemaname = $1 AND relname = ANY($2)`, [options.schema, options.tables]);
         // --- class size + existing index count (pg_class) ----------------------
         const classRows = await run('pg_class size', `SELECT c.relname,
               c.reltuples::bigint::text AS reltuples,
+              c.relpages::bigint::text AS relpages,
               pg_total_relation_size(c.oid)::text AS total_size,
               pg_relation_size(c.oid)::text AS table_size,
               (SELECT count(*) FROM pg_index i WHERE i.indrelid = c.oid)::text AS index_count
@@ -618,6 +621,7 @@ async function collectStatsSnapshot(options) {
             for (const row of classRows) {
                 const s = ensure(row.relname);
                 s.reltuples = Number(row.reltuples);
+                s.relpages = Number(row.relpages);
                 s.totalSizeBytes = Number(row.total_size);
                 s.tableSizeBytes = Number(row.table_size);
                 s.existingIndexCount = Number(row.index_count);
@@ -634,6 +638,7 @@ async function collectStatsSnapshot(options) {
                 s.seqScan = Number(row.seq_scan);
                 s.seqTupRead = Number(row.seq_tup_read);
                 s.nLiveTup = Number(row.n_live_tup);
+                s.lastAnalyze = row.last_analyze == null ? null : new Date(row.last_analyze);
             }
         }
         // --- invalid + all indexes (whole schema, for invalid detection) -------
@@ -697,6 +702,42 @@ async function collectStatsSnapshot(options) {
                 }
             }
         }
+        // --- value distribution for divergence candidates (pg_stats) -----------
+        const distCols = options.distributionColumns ?? [];
+        if (distCols.length > 0) {
+            // `inherited = false` is required: on a partitioned parent the inherited
+            // row describes the whole tree, and a per-partition plan is not chosen
+            // from it. most_common_vals is an anyarray, so its cardinality is read
+            // through a text[] cast (array_length on anyarray cannot resolve a type).
+            const distRows = await run('pg_stats.distribution', `SELECT s.tablename, s.attname,
+                s.n_distinct::text AS n_distinct,
+                s.correlation::text AS correlation,
+                s.most_common_freqs,
+                coalesce(array_length(s.most_common_vals::text::text[], 1), 0)::text AS mcv_count
+           FROM pg_stats s
+           JOIN unnest($2::text[], $3::text[]) AS probe(t, c)
+             ON probe.t = s.tablename AND probe.c = s.attname
+          WHERE s.schemaname = $1 AND s.inherited = false`, [options.schema, distCols.map((c) => c.table), distCols.map((c) => c.column)]);
+            if (distRows) {
+                const byKey = snapshot.columnStats ?? {};
+                for (const row of distRows) {
+                    byKey[`${row.tablename}.${row.attname}`] = {
+                        table: row.tablename,
+                        column: row.attname,
+                        nDistinct: Number(row.n_distinct),
+                        correlation: row.correlation == null ? null : Number(row.correlation),
+                        mostCommonFreqs: row.most_common_freqs == null ? null : row.most_common_freqs.map(Number),
+                        mcvCount: row.mcv_count == null ? 0 : Number(row.mcv_count),
+                    };
+                }
+                snapshot.columnStats = byKey;
+            }
+            else {
+                // The read failed (privileges, catalog gap). Leave columnStats absent so
+                // the advisor suppresses every candidate instead of scoring zeros.
+                snapshot.columnStats = undefined;
+            }
+        }
     }
     finally {
         try {