turbine-orm 0.58.0 → 0.59.1

package/README.md

@@ -454,7 +454,7 @@ const db = turbine({
 
 Where a pg-style alias exists (`max`, `idleTimeoutMillis`, `connectionTimeoutMillis`), the explicit Turbine field wins when both are set.
 
-> **`planCacheMode` (Postgres only, opt-in).** PostgreSQL may promote a **named** prepared statement to a generic plan from its sixth execution onward, and a generic plan is costed blind to the bound values. On a predicate whose selectivity swings per value (a `tenant_id` equality on a shared table, where one value matches a handful of rows and another matches most of them), the statement can be locked onto a plan chosen for the average value, and it never reverts. `planCacheMode: 'auto' | 'force_custom_plan' | 'force_generic_plan'` pins the backend's choice; `'force_custom_plan'` re-plans every execution and removes the cliff. It is applied as a connection parameter (`options=-c plan_cache_mode=...`) when Turbine opens a connection, so it is in force for that connection's first statement and for every checkout, `$transaction`, stream and pipeline on it, and it cannot race your first query. Leave it unset (the default) and Turbine sends nothing at all. Reach for it when you have measured a statement getting slower after its fifth execution. **Correction to the 0.54 text, which said `findMany` / `findFirst` bind `LIMIT $n` and are "much less exposed":** that was false. PostgreSQL does not deny the planner a limit fraction for a bound limit, it substitutes a default of 10% of the child node's own row estimate (clamped at one row), and an unknown `OFFSET` triggers the same substitution even when the limit is a constant, which a paginated Turbine read always has. Two things also need saying about the sentence that opens this note. The sixth execution is a ceiling, not a trigger: `auto` promotes only when the generic plan's **estimated** cost is not worse than the average custom cost, so many statements are never promoted at all, and `pg_prepared_statements.generic_plans` is how you tell. And the shape that gets promoted unprompted is the one with **no limit**, not the limited one: measured on a skewed join predicate, an unlimited `count()`-shaped statement promoted under the default `auto` and ran a nested loop at 430x the buffers of the custom plan, while the same predicate under `LIMIT $n` was never promoted across eight executions (its substituted row count made the generic plan look more expensive). A limited `findMany` gives the planner two unknowns instead of one, which is not the same as more damage. `implicitPkOrdering` is **off by default in core**, so a default `findMany` emits no `ORDER BY`; switching it on adds an ordering a generic plan can walk the whole table in. Measure with `plan_cache_mode = force_generic_plan` against `force_custom_plan` rather than reasoning about which shapes ought to be safe; the fixtures and numbers are on the [relations page](https://turbineorm.dev/relations) and in the 0.55.0 changelog. **Two 0.56 corrections to the paragraph above.** First, "neither an ORDER BY nor a limit is required" is true, but it read as if ordering did not matter: on a real multi-tenant schema swept table by table, every divergent shape had an `ORDER BY` and every shape without one measured 1.00x, so it is not necessary in general and is still the strongest single predictor in practice. Second, a custom plan is not automatically the better one: on a reproducible fixture where one dense value's rows are packed at the end of the heap, `LIMIT 20` with no ordering reads 4,262 buffers custom against 71 generic (the default `auto` never promotes there, so it produces the 4,262-buffer plan too). Since 0.56 the per-query read arg **`forceCustomPlan: true`** covers the case a connection-wide setting cannot express, custom on one query and `auto` everywhere else, and `turbine doctor` detects the distribution that admits the flip. **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`).
+> **`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: in a table-by-table sweep of a multi-tenant schema, every divergent shape measured 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.
 

package/dist/cjs/cli/index.js

@@ -2389,7 +2389,8 @@ async function cmdDoctor(args, config) {
         : { findings: [], notices: [], candidatesConsidered: 0, consideredIndexed: 0, consideredUnindexed: 0 };
     // Statistics can say how bad a flip WOULD be; only the planner can say whether
     // it is reachable. The `unindexed-filter` branch shipped in 0.57 without that
-    // question answered and was right 6 times in 13 on a real schema, so every one
+    // question answered, and a measured sample of 13 findings held up only 6 times,
+    // so every one
     // of its findings is now put to a plan-only EXPLAIN. Nothing is executed, and a
     // probe that fails keeps its finding rather than dropping it.
     const flipProbe = divergenceOn && scored.findings.some(plan_flip_probe_js_1.needsFlipProbe)

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

@@ -6,13 +6,14 @@
  * `plan-divergence.ts` scores a column from statistics alone and answers "IF the
  * cached plan flips, how bad is it". Its `unindexed-filter` branch (0.57) shipped
  * without an answer to the prior question, "CAN it flip at all", and that turned
- * out to be the majority case: on a real 118-model schema the branch produced 39
- * findings of which a measured sample was right 6 times in 13.
+ * out to be the majority case: in validation against a large schema the branch
+ * emitted 39 findings, and a measured sample of 13 of them held up only 6 times.
  *
- * Every false positive had one signature: **the generic plan kept the same
- * sequential scan the custom plan chose.** There was no flip to be had, so the
+ * Every false positive had one signature: **the generic plan was not the ordered
+ * index walk the finding claims.** There was no flip to be had, so the
  * amplification the finding printed described a plan the planner would never
- * pick.
+ * pick. See {@link verdictFromPlanJson} for the two ways a plan fails to be that
+ * walk; 0.58.0 shipped only one of them and 0.59.0 added the other.
  *
  * ## Why this is a probe and not another rule
  *
@@ -54,11 +55,10 @@
  * ```
  *
  * The custom plan is not needed. The finding's whole claim is that a promoted
- * generic plan abandons the seq scan for an ordered index walk, so if the generic
- * plan IS a seq scan on the target table, the claim is refuted no matter what the
- * custom plan does. Asking one question instead of two halves the work and
- * removes the need for a representative rare value, which statistics do not
- * carry.
+ * generic plan performs an ordered index walk, so a generic plan that is NOT that
+ * walk refutes it no matter what the custom plan does. Asking one question
+ * instead of two halves the work and removes the need for a representative rare
+ * value, which statistics do not carry.
  *
  * `NULL` is a safe argument precisely because the plan is generic: a generic plan
  * is built without looking at the value, which is the property the whole check is
@@ -80,11 +80,11 @@ import type { PlanDivergenceFinding, PlanDivergenceReport } from './plan-diverge
 /**
  * The planner's answer for one finding.
  *
- * - `'flip-reachable'`, the generic plan is NOT a plain seq scan of the target
+ * - `'flip-reachable'`, the generic plan IS an ordered index walk on the target
  *   table, so the divergence the finding describes is one the planner can
  *   actually choose.
- * - `'no-flip'`, the generic plan sequentially scans the target table, the same
- *   access the good plan uses. Nothing to diverge to.
+ * - `'no-flip'`, the generic plan is not that walk (a `Sort` bounds it, or the
+ *   access is a plain seq scan). Nothing to diverge to.
  * - `'unknown'`, the probe did not produce an answer. The finding is kept.
  */
 export type FlipVerdict = 'flip-reachable' | 'no-flip' | 'unknown';
@@ -133,11 +133,49 @@ export declare function buildFlipProbeSql(finding: PlanDivergenceFinding, name:
  * Exported for unit tests: the plan shapes this has to classify are exactly the
  * ones that are tedious to produce live.
  *
- * The rule is deliberately narrow. Only a `Seq Scan` ON THE TARGET TABLE refutes
- * a finding. A seq scan of some other relation in a more complex plan says
- * nothing about this column, and anything that is not a plain sequential scan of
- * the target (index scan, bitmap heap scan, index-only scan) leaves the flip
- * reachable.
+ * ## The question, stated exactly
+ *
+ * The finding claims the generic plan performs an ORDERED INDEX WALK along the
+ * `ORDER BY` column and fetches nearly every tuple before the `LIMIT` fills. So
+ * the refutation is not "the plan is a seq scan", it is **"the plan is not that
+ * ordered walk"**, and there are two ways for it not to be:
+ *
+ * 1. A `Sort` lies above the target table's scan. A sort materializes the whole
+ *    matched set and orders it, so the cost is bounded by how many rows match,
+ *    not by how far into the heap the ordered walk has to travel. Whatever feeds
+ *    it (seq scan, bitmap heap scan) the catastrophic shape is absent.
+ * 2. The target's own scan node is a `Seq Scan`. Kept as an independent ground
+ *    rather than folded into the first, so a hypothetical ordered seq scan with
+ *    no sort still refutes.
+ *
+ * 0.58.0 shipped only the second ground and therefore missed every LOW-estimate
+ * column that has ANY usable index, because those plan as `Limit > Sort > Bitmap
+ * Heap Scan`. The case that surfaced it was a column carrying
+ * `btree (col) WHERE col IS NOT NULL`: an equality predicate implies not-null, so
+ * that partial index is fully usable and the plan never reaches a seq scan.
+ * Reproduced, and the fixture is the pair below at the same estimate:
+ *
+ * ```txt
+ * partial index, est 1.9   Limit > Sort > Bitmap Heap Scan   <- 0.58 kept this
+ * no index,      est 1.9   Limit > Sort > Seq Scan           <- 0.58 refuted this
+ * either,        est 500   Limit > Index Scan (no Sort)      <- both keep, correctly
+ * ```
+ *
+ * ## Why this is not "exclude partial-index columns"
+ *
+ * Because a partial index whose predicate is NOT implied by the equality does not
+ * serve the query at all, and such a column produces a genuine finding: one was
+ * measured at 19,961x. The property that matters is whether the planner COULD
+ * use it, which is a proof obligation over predicates, and the plan already
+ * carries the answer. Reading the plan is cheaper and cannot drift from the
+ * planner's own implication rules.
+ *
+ * ## The safe direction is KEEP
+ *
+ * Over-refuting deletes real findings, which is invisible in the report;
+ * over-keeping only costs noise. So `Incremental Sort` does NOT refute: it means
+ * the index supplies a PREFIX of the ordering and the walk is still partly
+ * ordered, which is closer to the catastrophic shape than to the bounded one.
  */
 export declare function verdictFromPlanJson(payload: unknown, table: string): FlipVerdict;
 export interface ProbePlanFlipsOptions {

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

@@ -7,13 +7,14 @@
  * `plan-divergence.ts` scores a column from statistics alone and answers "IF the
  * cached plan flips, how bad is it". Its `unindexed-filter` branch (0.57) shipped
  * without an answer to the prior question, "CAN it flip at all", and that turned
- * out to be the majority case: on a real 118-model schema the branch produced 39
- * findings of which a measured sample was right 6 times in 13.
+ * out to be the majority case: in validation against a large schema the branch
+ * emitted 39 findings, and a measured sample of 13 of them held up only 6 times.
  *
- * Every false positive had one signature: **the generic plan kept the same
- * sequential scan the custom plan chose.** There was no flip to be had, so the
+ * Every false positive had one signature: **the generic plan was not the ordered
+ * index walk the finding claims.** There was no flip to be had, so the
  * amplification the finding printed described a plan the planner would never
- * pick.
+ * pick. See {@link verdictFromPlanJson} for the two ways a plan fails to be that
+ * walk; 0.58.0 shipped only one of them and 0.59.0 added the other.
  *
  * ## Why this is a probe and not another rule
  *
@@ -55,11 +56,10 @@
  * ```
  *
  * The custom plan is not needed. The finding's whole claim is that a promoted
- * generic plan abandons the seq scan for an ordered index walk, so if the generic
- * plan IS a seq scan on the target table, the claim is refuted no matter what the
- * custom plan does. Asking one question instead of two halves the work and
- * removes the need for a representative rare value, which statistics do not
- * carry.
+ * generic plan performs an ordered index walk, so a generic plan that is NOT that
+ * walk refutes it no matter what the custom plan does. Asking one question
+ * instead of two halves the work and removes the need for a representative rare
+ * value, which statistics do not carry.
  *
  * `NULL` is a safe argument precisely because the plan is generic: a generic plan
  * is built without looking at the value, which is the property the whole check is
@@ -166,39 +166,83 @@ function buildFlipProbeSql(finding, name, searchSchema) {
         deallocate: `DEALLOCATE ${name}`,
     };
 }
-function* walkPlan(node) {
-    yield node;
-    for (const child of node.Plans ?? [])
-        yield* walkPlan(child);
-}
 /**
  * Read a verdict out of one `EXPLAIN (FORMAT JSON)` payload.
  *
  * Exported for unit tests: the plan shapes this has to classify are exactly the
  * ones that are tedious to produce live.
  *
- * The rule is deliberately narrow. Only a `Seq Scan` ON THE TARGET TABLE refutes
- * a finding. A seq scan of some other relation in a more complex plan says
- * nothing about this column, and anything that is not a plain sequential scan of
- * the target (index scan, bitmap heap scan, index-only scan) leaves the flip
- * reachable.
+ * ## The question, stated exactly
+ *
+ * The finding claims the generic plan performs an ORDERED INDEX WALK along the
+ * `ORDER BY` column and fetches nearly every tuple before the `LIMIT` fills. So
+ * the refutation is not "the plan is a seq scan", it is **"the plan is not that
+ * ordered walk"**, and there are two ways for it not to be:
+ *
+ * 1. A `Sort` lies above the target table's scan. A sort materializes the whole
+ *    matched set and orders it, so the cost is bounded by how many rows match,
+ *    not by how far into the heap the ordered walk has to travel. Whatever feeds
+ *    it (seq scan, bitmap heap scan) the catastrophic shape is absent.
+ * 2. The target's own scan node is a `Seq Scan`. Kept as an independent ground
+ *    rather than folded into the first, so a hypothetical ordered seq scan with
+ *    no sort still refutes.
+ *
+ * 0.58.0 shipped only the second ground and therefore missed every LOW-estimate
+ * column that has ANY usable index, because those plan as `Limit > Sort > Bitmap
+ * Heap Scan`. The case that surfaced it was a column carrying
+ * `btree (col) WHERE col IS NOT NULL`: an equality predicate implies not-null, so
+ * that partial index is fully usable and the plan never reaches a seq scan.
+ * Reproduced, and the fixture is the pair below at the same estimate:
+ *
+ * ```txt
+ * partial index, est 1.9   Limit > Sort > Bitmap Heap Scan   <- 0.58 kept this
+ * no index,      est 1.9   Limit > Sort > Seq Scan           <- 0.58 refuted this
+ * either,        est 500   Limit > Index Scan (no Sort)      <- both keep, correctly
+ * ```
+ *
+ * ## Why this is not "exclude partial-index columns"
+ *
+ * Because a partial index whose predicate is NOT implied by the equality does not
+ * serve the query at all, and such a column produces a genuine finding: one was
+ * measured at 19,961x. The property that matters is whether the planner COULD
+ * use it, which is a proof obligation over predicates, and the plan already
+ * carries the answer. Reading the plan is cheaper and cannot drift from the
+ * planner's own implication rules.
+ *
+ * ## The safe direction is KEEP
+ *
+ * Over-refuting deletes real findings, which is invisible in the report;
+ * over-keeping only costs noise. So `Incremental Sort` does NOT refute: it means
+ * the index supplies a PREFIX of the ordering and the walk is still partly
+ * ordered, which is closer to the catastrophic shape than to the bounded one.
  */
 function verdictFromPlanJson(payload, table) {
     const root = Array.isArray(payload) ? payload[0] : undefined;
     const plan = root?.Plan;
     if (!plan)
         return 'unknown';
-    for (const node of walkPlan(plan)) {
-        if (node['Relation Name'] !== table)
-            continue;
+    // Walk root-downward, tracking whether a full Sort sits ABOVE the target's
+    // scan. Depth matters: a Sort somewhere else in a larger plan says nothing
+    // about how this table is reached.
+    const search = (node, sortedAbove) => {
         const type = node['Node Type'];
-        if (type === undefined)
-            continue;
-        return type === 'Seq Scan' ? 'no-flip' : 'flip-reachable';
-    }
-    // The target table is not in the plan at all, which should not happen for a
-    // statement that selects from it. Treated as unknown rather than as a refutation.
-    return 'unknown';
+        if (node['Relation Name'] === table && type !== undefined) {
+            if (sortedAbove)
+                return 'no-flip';
+            return type === 'Seq Scan' ? 'no-flip' : 'flip-reachable';
+        }
+        // 'Incremental Sort' is deliberately excluded, see the header.
+        const nowSorted = sortedAbove || type === 'Sort';
+        for (const child of node.Plans ?? []) {
+            const found = search(child, nowSorted);
+            if (found !== null)
+                return found;
+        }
+        return null;
+    };
+    // The target table not appearing at all should not happen for a statement that
+    // selects from it. Treated as unknown rather than as a refutation.
+    return search(plan, false) ?? 'unknown';
 }
 /**
  * Ask the planner, once per candidate finding, whether the flip is reachable.

package/dist/cli/index.js

@@ -2339,7 +2339,8 @@ async function cmdDoctor(args, config) {
         : { findings: [], notices: [], candidatesConsidered: 0, consideredIndexed: 0, consideredUnindexed: 0 };
     // Statistics can say how bad a flip WOULD be; only the planner can say whether
     // it is reachable. The `unindexed-filter` branch shipped in 0.57 without that
-    // question answered and was right 6 times in 13 on a real schema, so every one
+    // question answered, and a measured sample of 13 findings held up only 6 times,
+    // so every one
     // of its findings is now put to a plan-only EXPLAIN. Nothing is executed, and a
     // probe that fails keeps its finding rather than dropping it.
     const flipProbe = divergenceOn && scored.findings.some(needsFlipProbe)

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

@@ -6,13 +6,14 @@
  * `plan-divergence.ts` scores a column from statistics alone and answers "IF the
  * cached plan flips, how bad is it". Its `unindexed-filter` branch (0.57) shipped
  * without an answer to the prior question, "CAN it flip at all", and that turned
- * out to be the majority case: on a real 118-model schema the branch produced 39
- * findings of which a measured sample was right 6 times in 13.
+ * out to be the majority case: in validation against a large schema the branch
+ * emitted 39 findings, and a measured sample of 13 of them held up only 6 times.
  *
- * Every false positive had one signature: **the generic plan kept the same
- * sequential scan the custom plan chose.** There was no flip to be had, so the
+ * Every false positive had one signature: **the generic plan was not the ordered
+ * index walk the finding claims.** There was no flip to be had, so the
  * amplification the finding printed described a plan the planner would never
- * pick.
+ * pick. See {@link verdictFromPlanJson} for the two ways a plan fails to be that
+ * walk; 0.58.0 shipped only one of them and 0.59.0 added the other.
  *
  * ## Why this is a probe and not another rule
  *
@@ -54,11 +55,10 @@
  * ```
  *
  * The custom plan is not needed. The finding's whole claim is that a promoted
- * generic plan abandons the seq scan for an ordered index walk, so if the generic
- * plan IS a seq scan on the target table, the claim is refuted no matter what the
- * custom plan does. Asking one question instead of two halves the work and
- * removes the need for a representative rare value, which statistics do not
- * carry.
+ * generic plan performs an ordered index walk, so a generic plan that is NOT that
+ * walk refutes it no matter what the custom plan does. Asking one question
+ * instead of two halves the work and removes the need for a representative rare
+ * value, which statistics do not carry.
  *
  * `NULL` is a safe argument precisely because the plan is generic: a generic plan
  * is built without looking at the value, which is the property the whole check is
@@ -80,11 +80,11 @@ import type { PlanDivergenceFinding, PlanDivergenceReport } from './plan-diverge
 /**
  * The planner's answer for one finding.
  *
- * - `'flip-reachable'`, the generic plan is NOT a plain seq scan of the target
+ * - `'flip-reachable'`, the generic plan IS an ordered index walk on the target
  *   table, so the divergence the finding describes is one the planner can
  *   actually choose.
- * - `'no-flip'`, the generic plan sequentially scans the target table, the same
- *   access the good plan uses. Nothing to diverge to.
+ * - `'no-flip'`, the generic plan is not that walk (a `Sort` bounds it, or the
+ *   access is a plain seq scan). Nothing to diverge to.
  * - `'unknown'`, the probe did not produce an answer. The finding is kept.
  */
 export type FlipVerdict = 'flip-reachable' | 'no-flip' | 'unknown';
@@ -133,11 +133,49 @@ export declare function buildFlipProbeSql(finding: PlanDivergenceFinding, name:
  * Exported for unit tests: the plan shapes this has to classify are exactly the
  * ones that are tedious to produce live.
  *
- * The rule is deliberately narrow. Only a `Seq Scan` ON THE TARGET TABLE refutes
- * a finding. A seq scan of some other relation in a more complex plan says
- * nothing about this column, and anything that is not a plain sequential scan of
- * the target (index scan, bitmap heap scan, index-only scan) leaves the flip
- * reachable.
+ * ## The question, stated exactly
+ *
+ * The finding claims the generic plan performs an ORDERED INDEX WALK along the
+ * `ORDER BY` column and fetches nearly every tuple before the `LIMIT` fills. So
+ * the refutation is not "the plan is a seq scan", it is **"the plan is not that
+ * ordered walk"**, and there are two ways for it not to be:
+ *
+ * 1. A `Sort` lies above the target table's scan. A sort materializes the whole
+ *    matched set and orders it, so the cost is bounded by how many rows match,
+ *    not by how far into the heap the ordered walk has to travel. Whatever feeds
+ *    it (seq scan, bitmap heap scan) the catastrophic shape is absent.
+ * 2. The target's own scan node is a `Seq Scan`. Kept as an independent ground
+ *    rather than folded into the first, so a hypothetical ordered seq scan with
+ *    no sort still refutes.
+ *
+ * 0.58.0 shipped only the second ground and therefore missed every LOW-estimate
+ * column that has ANY usable index, because those plan as `Limit > Sort > Bitmap
+ * Heap Scan`. The case that surfaced it was a column carrying
+ * `btree (col) WHERE col IS NOT NULL`: an equality predicate implies not-null, so
+ * that partial index is fully usable and the plan never reaches a seq scan.
+ * Reproduced, and the fixture is the pair below at the same estimate:
+ *
+ * ```txt
+ * partial index, est 1.9   Limit > Sort > Bitmap Heap Scan   <- 0.58 kept this
+ * no index,      est 1.9   Limit > Sort > Seq Scan           <- 0.58 refuted this
+ * either,        est 500   Limit > Index Scan (no Sort)      <- both keep, correctly
+ * ```
+ *
+ * ## Why this is not "exclude partial-index columns"
+ *
+ * Because a partial index whose predicate is NOT implied by the equality does not
+ * serve the query at all, and such a column produces a genuine finding: one was
+ * measured at 19,961x. The property that matters is whether the planner COULD
+ * use it, which is a proof obligation over predicates, and the plan already
+ * carries the answer. Reading the plan is cheaper and cannot drift from the
+ * planner's own implication rules.
+ *
+ * ## The safe direction is KEEP
+ *
+ * Over-refuting deletes real findings, which is invisible in the report;
+ * over-keeping only costs noise. So `Incremental Sort` does NOT refute: it means
+ * the index supplies a PREFIX of the ordering and the walk is still partly
+ * ordered, which is closer to the catastrophic shape than to the bounded one.
  */
 export declare function verdictFromPlanJson(payload: unknown, table: string): FlipVerdict;
 export interface ProbePlanFlipsOptions {

package/dist/plan-flip-probe.js

@@ -6,13 +6,14 @@
  * `plan-divergence.ts` scores a column from statistics alone and answers "IF the
  * cached plan flips, how bad is it". Its `unindexed-filter` branch (0.57) shipped
  * without an answer to the prior question, "CAN it flip at all", and that turned
- * out to be the majority case: on a real 118-model schema the branch produced 39
- * findings of which a measured sample was right 6 times in 13.
+ * out to be the majority case: in validation against a large schema the branch
+ * emitted 39 findings, and a measured sample of 13 of them held up only 6 times.
  *
- * Every false positive had one signature: **the generic plan kept the same
- * sequential scan the custom plan chose.** There was no flip to be had, so the
+ * Every false positive had one signature: **the generic plan was not the ordered
+ * index walk the finding claims.** There was no flip to be had, so the
  * amplification the finding printed described a plan the planner would never
- * pick.
+ * pick. See {@link verdictFromPlanJson} for the two ways a plan fails to be that
+ * walk; 0.58.0 shipped only one of them and 0.59.0 added the other.
  *
  * ## Why this is a probe and not another rule
  *
@@ -54,11 +55,10 @@
  * ```
  *
  * The custom plan is not needed. The finding's whole claim is that a promoted
- * generic plan abandons the seq scan for an ordered index walk, so if the generic
- * plan IS a seq scan on the target table, the claim is refuted no matter what the
- * custom plan does. Asking one question instead of two halves the work and
- * removes the need for a representative rare value, which statistics do not
- * carry.
+ * generic plan performs an ordered index walk, so a generic plan that is NOT that
+ * walk refutes it no matter what the custom plan does. Asking one question
+ * instead of two halves the work and removes the need for a representative rare
+ * value, which statistics do not carry.
  *
  * `NULL` is a safe argument precisely because the plan is generic: a generic plan
  * is built without looking at the value, which is the property the whole check is
@@ -124,39 +124,83 @@ export function buildFlipProbeSql(finding, name, searchSchema) {
         deallocate: `DEALLOCATE ${name}`,
     };
 }
-function* walkPlan(node) {
-    yield node;
-    for (const child of node.Plans ?? [])
-        yield* walkPlan(child);
-}
 /**
  * Read a verdict out of one `EXPLAIN (FORMAT JSON)` payload.
  *
  * Exported for unit tests: the plan shapes this has to classify are exactly the
  * ones that are tedious to produce live.
  *
- * The rule is deliberately narrow. Only a `Seq Scan` ON THE TARGET TABLE refutes
- * a finding. A seq scan of some other relation in a more complex plan says
- * nothing about this column, and anything that is not a plain sequential scan of
- * the target (index scan, bitmap heap scan, index-only scan) leaves the flip
- * reachable.
+ * ## The question, stated exactly
+ *
+ * The finding claims the generic plan performs an ORDERED INDEX WALK along the
+ * `ORDER BY` column and fetches nearly every tuple before the `LIMIT` fills. So
+ * the refutation is not "the plan is a seq scan", it is **"the plan is not that
+ * ordered walk"**, and there are two ways for it not to be:
+ *
+ * 1. A `Sort` lies above the target table's scan. A sort materializes the whole
+ *    matched set and orders it, so the cost is bounded by how many rows match,
+ *    not by how far into the heap the ordered walk has to travel. Whatever feeds
+ *    it (seq scan, bitmap heap scan) the catastrophic shape is absent.
+ * 2. The target's own scan node is a `Seq Scan`. Kept as an independent ground
+ *    rather than folded into the first, so a hypothetical ordered seq scan with
+ *    no sort still refutes.
+ *
+ * 0.58.0 shipped only the second ground and therefore missed every LOW-estimate
+ * column that has ANY usable index, because those plan as `Limit > Sort > Bitmap
+ * Heap Scan`. The case that surfaced it was a column carrying
+ * `btree (col) WHERE col IS NOT NULL`: an equality predicate implies not-null, so
+ * that partial index is fully usable and the plan never reaches a seq scan.
+ * Reproduced, and the fixture is the pair below at the same estimate:
+ *
+ * ```txt
+ * partial index, est 1.9   Limit > Sort > Bitmap Heap Scan   <- 0.58 kept this
+ * no index,      est 1.9   Limit > Sort > Seq Scan           <- 0.58 refuted this
+ * either,        est 500   Limit > Index Scan (no Sort)      <- both keep, correctly
+ * ```
+ *
+ * ## Why this is not "exclude partial-index columns"
+ *
+ * Because a partial index whose predicate is NOT implied by the equality does not
+ * serve the query at all, and such a column produces a genuine finding: one was
+ * measured at 19,961x. The property that matters is whether the planner COULD
+ * use it, which is a proof obligation over predicates, and the plan already
+ * carries the answer. Reading the plan is cheaper and cannot drift from the
+ * planner's own implication rules.
+ *
+ * ## The safe direction is KEEP
+ *
+ * Over-refuting deletes real findings, which is invisible in the report;
+ * over-keeping only costs noise. So `Incremental Sort` does NOT refute: it means
+ * the index supplies a PREFIX of the ordering and the walk is still partly
+ * ordered, which is closer to the catastrophic shape than to the bounded one.
  */
 export function verdictFromPlanJson(payload, table) {
     const root = Array.isArray(payload) ? payload[0] : undefined;
     const plan = root?.Plan;
     if (!plan)
         return 'unknown';
-    for (const node of walkPlan(plan)) {
-        if (node['Relation Name'] !== table)
-            continue;
+    // Walk root-downward, tracking whether a full Sort sits ABOVE the target's
+    // scan. Depth matters: a Sort somewhere else in a larger plan says nothing
+    // about how this table is reached.
+    const search = (node, sortedAbove) => {
         const type = node['Node Type'];
-        if (type === undefined)
-            continue;
-        return type === 'Seq Scan' ? 'no-flip' : 'flip-reachable';
-    }
-    // The target table is not in the plan at all, which should not happen for a
-    // statement that selects from it. Treated as unknown rather than as a refutation.
-    return 'unknown';
+        if (node['Relation Name'] === table && type !== undefined) {
+            if (sortedAbove)
+                return 'no-flip';
+            return type === 'Seq Scan' ? 'no-flip' : 'flip-reachable';
+        }
+        // 'Incremental Sort' is deliberately excluded, see the header.
+        const nowSorted = sortedAbove || type === 'Sort';
+        for (const child of node.Plans ?? []) {
+            const found = search(child, nowSorted);
+            if (found !== null)
+                return found;
+        }
+        return null;
+    };
+    // The target table not appearing at all should not happen for a statement that
+    // selects from it. Treated as unknown rather than as a refutation.
+    return search(plan, false) ?? 'unknown';
 }
 /**
  * Ask the planner, once per candidate finding, whether the flip is reachable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",
@@ -126,8 +126,9 @@
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",
     "check:error-codes": "tsx scripts/check-error-codes.ts",
+    "check:changelog": "node scripts/check-changelog-headings.mjs",
     "check:package": "publint --strict && attw --pack . --profile node16",
-    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit && npm run check:error-codes && npm run size",
+    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit && npm run check:error-codes && npm run check:changelog && npm run size",
     "prepack": "node scripts/strip-prepare.mjs",
     "postpack": "node scripts/restore-prepare.mjs",
     "size": "size-limit",