@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/planner/optimizer.js

@@ -10,8 +10,10 @@ import { createOptContext } from './framework/context.js';
 import { PassManager, PassId } from './framework/pass.js';
 // Phase 2 rules
 import { ruleMaterializationAdvisory } from './rules/cache/rule-materialization-advisory.js';
+import { ruleMaterializedViewRewrite } from './rules/cache/rule-materialized-view-rewrite.js';
 // Phase 1.5 rules
 import { ruleSelectAccessPath } from './rules/access/rule-select-access-path.js';
+import { ruleLensAuxiliaryAccess } from './rules/access/rule-lens-auxiliary-access.js';
 import { ruleMonotonicLimitPushdown } from './rules/access/rule-monotonic-limit-pushdown.js';
 import { ruleMonotonicRangeAccess } from './rules/access/rule-monotonic-range-access.js';
 import { ruleAsofStrategySelect } from './rules/access/rule-asof-strategy-select.js';
@@ -24,6 +26,9 @@ import { ruleSargableRangeRewrite } from './rules/predicate/rule-sargable-range-
 import { ruleJoinKeyInference } from './rules/join/rule-join-key-inference.js';
 import { ruleJoinGreedyCommute } from './rules/join/rule-join-greedy-commute.js';
 import { ruleJoinElimination, ruleJoinEliminationUnderAggregate } from './rules/join/rule-join-elimination.js';
+import { ruleJoinExistencePruning, ruleJoinExistencePruningUnderAggregate } from './rules/join/rule-join-existence-pruning.js';
+import { ruleSemijoinExistenceRecovery, ruleSemijoinExistenceRecoveryUnderAggregate } from './rules/join/rule-semijoin-existence-recovery.js';
+import { ruleInnerJoinExistenceRecovery } from './rules/join/rule-inner-join-existence-recovery.js';
 import { ruleFanOutLookupJoin } from './rules/join/rule-fanout-lookup-join.js';
 import { ruleFanOutBatchedOuter } from './rules/join/rule-fanout-batched-outer.js';
 import { ruleAsyncGatherUnionAll } from './rules/parallel/rule-async-gather-union-all.js';
@@ -80,6 +85,44 @@ export class Optimizer {
      * Register rules with their appropriate passes
      */
     registerRulesToPasses() {
+        // Materialized-view query rewrite (read side). Registered FIRST in the
+        // Structural pass so it fires on the pristine `Project(Filter?(Retrieve(
+        // TableReference)))` — before grow-retrieve / predicate-pushdown reposition
+        // the Filter and before the Physical pass absorbs a predicate into a range
+        // scan — where the matcher can read the fragment's WHERE off the live plan.
+        // Pass rules fire in REGISTRATION order (not by `priority`), so placement here
+        // is what guarantees first-fire. Logical→logical: the substituted maintained-table
+        // TableReference then flows through normal physical access selection, so
+        // `query_plan()` shows an ordinary scan of the MV's own table for free.
+        this.passManager.addRuleToPass(PassId.Structural, {
+            id: 'materialized-view-rewrite',
+            nodeType: PlanNodeType.Project,
+            phase: 'rewrite',
+            fn: ruleMaterializedViewRewrite,
+            priority: 6,
+            // Replaces a read-only scan-project-filter fragment with a provably
+            // row-equivalent backing scan; the dropped base-scan subtree is pure (the
+            // matcher admits only recognized predicates, no subqueries) and the
+            // replacement re-emits the fragment's identical output attribute ids.
+            sideEffectMode: 'safe',
+        });
+        // Aggregate arm of the same rewrite (`mv-query-rewrite-aggregate-rollup`):
+        // recognizes a logical `Aggregate(Filter?(scan))` answered from a grouped MV
+        // (exact-key direct scan or superset-key rollup re-aggregation). Registered as
+        // a SECOND handle because pass rules fire only on their `nodeType` and are
+        // deduped by id — so the aggregate arm needs the `Aggregate` node type and a
+        // distinct id. It honors the canonical `materialized-view-rewrite` disable
+        // switch internally (see the rule), so existing rule-disable controls turn off
+        // both arms. Registered immediately after the Project arm so it likewise fires
+        // on the pristine fragment, before grow-retrieve / predicate-pushdown.
+        this.passManager.addRuleToPass(PassId.Structural, {
+            id: 'materialized-view-rewrite-aggregate',
+            nodeType: PlanNodeType.Aggregate,
+            phase: 'rewrite',
+            fn: ruleMaterializedViewRewrite,
+            priority: 6,
+            sideEffectMode: 'safe',
+        });
         // Structural pass rules (top-down) - for operations that need parent context
         // Register grow-retrieve for ALL relational node types
         // The rule itself will determine if growth is possible
@@ -100,7 +143,10 @@ export class Optimizer {
                 nodeType,
                 phase: 'rewrite',
                 fn: ruleGrowRetrieve,
-                priority: 10
+                priority: 10,
+                // Slides operators down into a Retrieve boundary, whose pipeline is
+                // always a read by construction (RetrieveNode is the vtab read entry).
+                sideEffectMode: 'safe',
             });
         }
         // Join key inference (structural/characteristic)
@@ -109,7 +155,9 @@ export class Optimizer {
             nodeType: PlanNodeType.Join,
             phase: 'rewrite',
             fn: ruleJoinKeyInference,
-            priority: 15
+            priority: 15,
+            // Diagnostic-only: never returns a transformed node.
+            sideEffectMode: 'safe',
         });
         // Greedy join commute: place smaller input on the left to improve nested-loop-like costs
         this.passManager.addRuleToPass(PassId.Structural, {
@@ -117,7 +165,10 @@ export class Optimizer {
             nodeType: PlanNodeType.Join,
             phase: 'rewrite',
             fn: ruleJoinGreedyCommute,
-            priority: 16
+            priority: 16,
+            // Swaps left/right of an inner join — would reorder side-effect
+            // execution. The rule refuses when either side carries a write.
+            sideEffectMode: 'aware',
         });
         // DISTINCT elimination: remove redundant DISTINCT when source already has unique keys
         this.passManager.addRuleToPass(PassId.Structural, {
@@ -125,7 +176,10 @@ export class Optimizer {
             nodeType: PlanNodeType.Distinct,
             phase: 'rewrite',
             fn: ruleDistinctElimination,
-            priority: 18
+            priority: 18,
+            // Unwraps DISTINCT around its source; source survives verbatim and any
+            // writes inside it still execute the same number of times.
+            sideEffectMode: 'safe',
         });
         // Projection pruning: remove unused inner projections in Project-on-Project
         this.passManager.addRuleToPass(PassId.Structural, {
@@ -133,7 +187,31 @@ export class Optimizer {
             nodeType: PlanNodeType.Project,
             phase: 'rewrite',
             fn: ruleProjectionPruning,
-            priority: 19
+            priority: 19,
+            // Drops unreferenced inner projections — refuses to drop any whose
+            // scalar expression carries a side effect.
+            sideEffectMode: 'aware',
+        });
+        // Lens auxiliary-access routing: route an outer-query predicate over an
+        // inlined lens view through an advertised auxiliary structure (nd-tree /
+        // vector / full-text) — an auxiliary seek ⋈ logical-key semi-join — instead
+        // of a residual filter over the full decomposition scan. Registered BEFORE
+        // predicate-pushdown (priority 20) so the matched predicate is still directly
+        // above the LensAuxiliaryAccess marker when this fires; within the top-down
+        // Structural pass, rules run in registration order, so placing this block
+        // ahead of pushdown is what guarantees first-fire on the Filter. No-ops on
+        // any Filter whose subtree has no marker (every non-lens / non-routable-lens
+        // view), so ordinary queries are untouched.
+        this.passManager.addRuleToPass(PassId.Structural, {
+            id: 'lens-auxiliary-access',
+            nodeType: PlanNodeType.Filter,
+            phase: 'rewrite',
+            fn: ruleLensAuxiliaryAccess,
+            priority: 17,
+            // Replaces a Filter over the lens marker with a semi-join against an
+            // auxiliary scan; the logical body (left) survives verbatim and the
+            // auxiliary scan it adds is a fresh read-only table reference.
+            sideEffectMode: 'safe',
         });
         // Sargable range rewrite: turn `f(col) = c` (for monotone-lossy `f` with
         // a bucketBounds-aware logical type) into `col >= L AND col < U` so the
@@ -146,7 +224,9 @@ export class Optimizer {
             nodeType: PlanNodeType.Filter,
             phase: 'rewrite',
             fn: ruleSargableRangeRewrite,
-            priority: 18
+            priority: 18,
+            // Rewrites a single scalar conjunct shape in place; no subtree moved.
+            sideEffectMode: 'safe',
         });
         // Aggregate-aware predicate pushdown: splits a Filter above an aggregate so
         // conjuncts on GROUP-BY-determined columns land below the aggregate. Runs
@@ -157,14 +237,21 @@ export class Optimizer {
             nodeType: PlanNodeType.Filter,
             phase: 'rewrite',
             fn: ruleAggregatePredicatePushdown,
-            priority: 19
+            priority: 19,
+            // Moves Filter conjuncts below an Aggregate, changing which rows reach
+            // the source subtree. Refuses when source has side effects.
+            sideEffectMode: 'aware',
         });
         this.passManager.addRuleToPass(PassId.Structural, {
             id: 'predicate-pushdown',
             nodeType: PlanNodeType.Filter,
             phase: 'rewrite',
             fn: rulePredicatePushdown,
-            priority: 20
+            priority: 20,
+            // Slides Filter past Sort/Distinct/Project/Alias/Retrieve, changing
+            // which rows reach the layer below — refuses when the immediate child
+            // subtree carries a write.
+            sideEffectMode: 'aware',
         });
         // Filter merge: combine adjacent Filter nodes into one AND-combined Filter
         this.passManager.addRuleToPass(PassId.Structural, {
@@ -172,7 +259,12 @@ export class Optimizer {
             nodeType: PlanNodeType.Filter,
             phase: 'rewrite',
             fn: ruleFilterMerge,
-            priority: 21
+            priority: 21,
+            // Merges two adjacent Filters into AND; the source subtree is untouched
+            // and only the order of predicate-clause evaluation changes (predicates
+            // are pure today; the audit gate that DML-in-expression-position needs
+            // is on rules that move or drop SUBTREES, not predicate ASTs).
+            sideEffectMode: 'safe',
         });
         // Scalar CSE: deduplicate common scalar expressions across Project + Filter + Sort chains
         this.passManager.addRuleToPass(PassId.Structural, {
@@ -180,7 +272,11 @@ export class Optimizer {
             nodeType: PlanNodeType.Project,
             phase: 'rewrite',
             fn: ruleScalarCSE,
-            priority: 22
+            priority: 22,
+            // Deduplicates scalar expressions — would silently collapse N copies of
+            // a side-effect-bearing scalar into 1. The rule's collector skips any
+            // non-deterministic or side-effect-bearing expression.
+            sideEffectMode: 'aware',
         });
         // EC-driven predicate inference: materialize inferred equality predicates
         // from the cross of predicate-derived constant bindings and the source's
@@ -195,7 +291,12 @@ export class Optimizer {
             nodeType: PlanNodeType.Filter,
             phase: 'rewrite',
             fn: rulePredicateInferenceEquivalence,
-            priority: 22
+            priority: 22,
+            // Materializes inferred equality conjuncts and optionally injects
+            // branch filters above an inner/cross join's children — would change
+            // which rows reach a side-effect-bearing branch. Refuses branch
+            // injection when the target branch has side effects.
+            sideEffectMode: 'aware',
         });
         // GROUP BY FD simplification: drop GROUP BY columns determined by other
         // GROUP BY columns under the aggregate's output FDs + ECs. Picker MIN()
@@ -209,7 +310,127 @@ export class Optimizer {
             nodeType: PlanNodeType.Aggregate,
             phase: 'rewrite',
             fn: ruleGroupByFdSimplification,
-            priority: 23
+            priority: 23,
+            // Drops bare-column GROUP BY entries (re-emitting them as picker
+            // aggregates). The dropped expressions are pure ColumnReferenceNodes
+            // by construction, so no side-effect-bearing scalar can be lost.
+            sideEffectMode: 'safe',
+        });
+        // Join existence-flag pruning (demand-gated): drop an `exists … as` match
+        // flag from a JoinNode when no ancestor demands its output attribute id, so
+        // `hasExistenceColumns` flips false on the last drop and the five
+        // flag-guarded join rules re-enable. Registered AFTER projection-pruning
+        // (19) / predicate-pushdown (20) / scalar-cse (22) so the demand set is
+        // settled, and BEFORE fanout-lookup-join (23) and join-elimination (24) so
+        // the freshly-pruned Project threads through them in the same applyRules
+        // loop. The PostOptimization join rules (join-physical-selection,
+        // monotonic-merge-join) and the Structural Join-typed lateral-top1-asof
+        // (visited top-down after this ancestor Project) see the flag-free join
+        // automatically.
+        this.passManager.addRuleToPass(PassId.Structural, {
+            id: 'join-existence-pruning',
+            nodeType: PlanNodeType.Project,
+            phase: 'rewrite',
+            fn: ruleJoinExistencePruning,
+            priority: 22,
+            // Drops only a derived, read-only `{true,false}` boolean column; both
+            // join sides survive verbatim, so no write can be skipped or reordered.
+            sideEffectMode: 'safe',
+        });
+        // Aggregate variant of existence-flag pruning: drop an `exists … as` match
+        // flag from a JoinNode reachable through a pass-through chain under an
+        // AggregateNode (the Project entrypoint never sees this shape). Priority 22
+        // mirrors the Project entrypoint and places it BEFORE
+        // join-elimination-aggregate (priority 26), so a freshly-pruned Aggregate
+        // threads into that rule in the same applyRules loop — the aggregate-side
+        // analogue of why join-existence-pruning (22) runs before
+        // join-elimination (24).
+        this.passManager.addRuleToPass(PassId.Structural, {
+            id: 'join-existence-pruning-aggregate',
+            nodeType: PlanNodeType.Aggregate,
+            phase: 'rewrite',
+            fn: ruleJoinExistencePruningUnderAggregate,
+            priority: 22,
+            // Same as the Project entrypoint: drops only a derived, read-only
+            // `{true,false}` boolean column; both join sides survive verbatim and
+            // the Aggregate is reconstructed with identical groupBy / aggregates /
+            // output attrs (a pure source swap), so no write can be skipped.
+            sideEffectMode: 'safe',
+        });
+        // Semi/anti-join existence-flag recovery (demand-SHAPE gated): the complement
+        // of `join-existence-pruning`. When the sole `exists … as` flag on a
+        // `left join` is demanded ONLY as a top-level boolean probe
+        // (`where flag` ⇒ semi, `where not flag` ⇒ anti), rewrite the JoinNode to the
+        // equivalent semi/anti join — the same shape `subquery-decorrelation` emits —
+        // re-opening physical join selection and the IND-folding cascade. Registered
+        // AFTER `join-existence-pruning` (so an undemanded sibling flag is dropped
+        // first, maximizing the sole-spec precondition) and BEFORE
+        // `fanout-lookup-join` / `join-elimination` and the IND folders
+        // `anti-join-fk-empty` / `semi-join-fk-trivial` (Join, registered below) so
+        // the recovered semi/anti threads into them in the same applyRules loop —
+        // exactly why `subquery-decorrelation` precedes those folders. Pass rules fire
+        // in REGISTRATION order, so this placement (22 < priority 23 < 26) is what
+        // realizes the ordering; the priority value is documentation.
+        this.passManager.addRuleToPass(PassId.Structural, {
+            id: 'semijoin-existence-recovery',
+            nodeType: PlanNodeType.Project,
+            phase: 'rewrite',
+            fn: ruleSemijoinExistenceRecovery,
+            priority: 23,
+            // Recovers a semi/anti join, which short-circuits the right side's scan at
+            // the first match — changing R's execution count. Refuses when R carries a
+            // write (mirrors subquery-decorrelation's impure-inner refusal).
+            sideEffectMode: 'aware',
+        });
+        // Inner-join existence-flag recovery (demand-SHAPE gated): the fallback
+        // complement of `semijoin-existence-recovery`. When the sole `exists … as`
+        // flag on a `left join` is a POSITIVE top-level probe (`where flag`) AND
+        // EITHER ≥1 right-side column is demanded above the join OR R fans out
+        // (non-unique on the join column, where a semi join would unsoundly collapse
+        // duplicates), rewrite the JoinNode to a plain `inner join` (drop the flag,
+        // keep both sides) — re-opening physical join selection, non-nullable right
+        // typing, and the FK/IND cascade the live flag pinned shut. The two recovery
+        // rules consult the SAME `rightMatchesAtMostOne` and so are provably disjoint
+        // on the positive-probe space INDEPENDENT of registration order (semi fires
+        // iff !rightColDemanded && unique-R; inner iff rightColDemanded || !unique-R).
+        // Registered (in registration order) BEFORE `fanout-lookup-join` /
+        // `join-elimination` (24) / the Join-typed IND folders (26) so the recovered
+        // inner join threads into them in the same applyRules loop.
+        this.passManager.addRuleToPass(PassId.Structural, {
+            id: 'inner-join-existence-recovery',
+            nodeType: PlanNodeType.Project,
+            phase: 'rewrite',
+            fn: ruleInnerJoinExistenceRecovery,
+            priority: 23,
+            // Logically scans R the same number of times as the flag-bearing left
+            // join, but dropping the flag re-enables join-physical-selection, which can
+            // pick a hash join that scans R once total — changing an impure R's
+            // execution count. Refuses when R carries a write (mirrors the sibling).
+            sideEffectMode: 'aware',
+        });
+        // Aggregate counterpart of `semijoin-existence-recovery`: the same probe-only
+        // flag recovery anchored on an `AggregateNode` for the bare `count(*) … where
+        // flag` / `group by` shape that plans with NO enclosing Project (the probe
+        // Filter + flag-bearing join sit under the Aggregate, so the Project entrypoint
+        // never fires). Registered (in registration order) AFTER
+        // `join-existence-pruning-aggregate` (22, so an undemanded sibling flag is
+        // dropped first, maximizing the sole-spec precondition) and BEFORE the
+        // Join-typed IND folders `anti-join-fk-empty` / `semi-join-fk-trivial` and
+        // `join-elimination-aggregate` (all 26), so the recovered semi/anti threads
+        // into them in the same applyRules loop — the aggregate analogue of the Project
+        // rule's placement. No nodeType collision with the Project `semijoin-existence-
+        // recovery` (Project vs Aggregate). Unlike the Project anchor it has NO inner
+        // fallback: a right-col-demanded / fan-out positive probe stays `left`.
+        this.passManager.addRuleToPass(PassId.Structural, {
+            id: 'semijoin-existence-recovery-aggregate',
+            nodeType: PlanNodeType.Aggregate,
+            phase: 'rewrite',
+            fn: ruleSemijoinExistenceRecoveryUnderAggregate,
+            priority: 23,
+            // Recovers a semi/anti join under an Aggregate — short-circuits R's scan at
+            // the first match (semi), changing R's execution count. Same impure-R refusal
+            // as the Project entrypoint.
+            sideEffectMode: 'aware',
         });
         // Fan-out lookup join (FK→PK): cluster N LEFT/INNER nested-loop joins from
         // a common outer into one parallel `FanOutLookupJoinNode` when the cost
@@ -225,7 +446,11 @@ export class Optimizer {
             nodeType: PlanNodeType.Project,
             phase: 'rewrite',
             fn: ruleFanOutLookupJoin,
-            priority: 23
+            priority: 23,
+            // Clusters per-outer-row branches into a parallel fan-out — drives
+            // branches concurrently. Refuses to cluster a branch whose subtree
+            // carries a write.
+            sideEffectMode: 'aware',
         });
         // Join elimination (FK→PK): drop LEFT/INNER joins whose non-preserved side
         // is never referenced above the join and is at-most-one-matching per a
@@ -237,7 +462,10 @@ export class Optimizer {
             nodeType: PlanNodeType.Project,
             phase: 'rewrite',
             fn: ruleJoinElimination,
-            priority: 24
+            priority: 24,
+            // Drops the non-preserved side of a join — refuses to drop a subtree
+            // that carries a write.
+            sideEffectMode: 'aware',
         });
         // Subquery decorrelation: transform correlated EXISTS/IN into semi/anti joins
         // Runs after predicate pushdown (priority 25 > 20) so inner predicates are already pushed
@@ -246,7 +474,11 @@ export class Optimizer {
             nodeType: PlanNodeType.Filter,
             phase: 'rewrite',
             fn: ruleSubqueryDecorrelation,
-            priority: 25
+            priority: 25,
+            // Transforms EXISTS(correlated) / IN(correlated) into semi/anti
+            // joins, changing how many times the inner subquery's subtree is
+            // executed — refuses when the inner subtree carries a write.
+            sideEffectMode: 'aware',
         });
         // IND-driven existence folding (priority 26 — runs after decorrelation has
         // materialized EXISTS / NOT EXISTS as semi/anti joins):
@@ -259,17 +491,23 @@ export class Optimizer {
             nodeType: PlanNodeType.Join,
             phase: 'rewrite',
             fn: ruleAntiJoinFkEmpty,
-            priority: 26
+            priority: 26,
+            // Folds an anti-join to EmptyRelation, dropping both sides. Refuses
+            // when either side carries a write.
+            sideEffectMode: 'aware',
         });
         this.passManager.addRuleToPass(PassId.Structural, {
             id: 'semi-join-fk-trivial',
             nodeType: PlanNodeType.Join,
             phase: 'rewrite',
             fn: ruleSemiJoinFkTrivial,
-            priority: 26
+            priority: 26,
+            // Drops the R side of a semi-join (replacing with a NOT NULL filter on
+            // L). Refuses when R carries a write.
+            sideEffectMode: 'aware',
         });
         // Aggregate variant of join-elimination: when an Aggregate sits over an
-        // FK-covered inner join and only references the FK side (or `count(*)`),
+        // FK-covered left/right/inner join and only references the FK side (or `count(*)`),
         // drop the join. Shares chain-walking + FK-PK alignment with
         // ruleJoinElimination via the same module.
         this.passManager.addRuleToPass(PassId.Structural, {
@@ -277,7 +515,10 @@ export class Optimizer {
             nodeType: PlanNodeType.Aggregate,
             phase: 'rewrite',
             fn: ruleJoinEliminationUnderAggregate,
-            priority: 26
+            priority: 26,
+            // Drops the non-preserved side of a left/right/inner join sitting under
+            // an Aggregate — same guard as ruleJoinElimination.
+            sideEffectMode: 'aware',
         });
         // ORDER BY FD pruning: drop trailing ORDER BY keys functionally determined
         // by the leading bare-column keys (under the source's FDs + ECs). Reduces
@@ -292,7 +533,12 @@ export class Optimizer {
             nodeType: PlanNodeType.Sort,
             phase: 'rewrite',
             fn: ruleOrderByFdPruning,
-            priority: 26
+            priority: 26,
+            // Drops trailing ORDER BY keys (or the whole Sort) — the keys are
+            // either bare ColumnReferenceNodes (pure) or kept opaque. The Sort's
+            // source is preserved verbatim. Whole-Sort elimination is also safe:
+            // it returns `node.source`, so every subtree below survives intact.
+            sideEffectMode: 'safe',
         });
         // Predicate-contradiction folding (priority 27 — after IND rules at 26):
         // detect when (filter predicate ∧ source domainConstraints ∧ literal
@@ -312,6 +558,9 @@ export class Optimizer {
             phase: 'rewrite',
             fn: ruleFilterContradiction,
             priority: 27,
+            // Replaces the Filter (and its source) with EmptyRelation — refuses
+            // when the source subtree carries a write.
+            sideEffectMode: 'aware',
         });
         // Empty-relation folding (priority 27 — after IND rules at 26): recognize
         // provably-empty subtrees (Filter on lit-false, or any host with an
@@ -324,6 +573,8 @@ export class Optimizer {
             phase: 'rewrite',
             fn: ruleFilterFoldEmpty,
             priority: 27,
+            // `Filter(x, lit-false)` drops `x` — refuses when `x` has side effects.
+            sideEffectMode: 'aware',
         });
         this.passManager.addRuleToPass(PassId.Structural, {
             id: 'fold-project-empty',
@@ -331,6 +582,10 @@ export class Optimizer {
             phase: 'rewrite',
             fn: ruleProjectFoldEmpty,
             priority: 27,
+            // Fires only when source is already an EmptyRelation (a pure marker
+            // with no children); side-effect-bearing subtree cannot reach this
+            // fold without itself first being folded.
+            sideEffectMode: 'safe',
         });
         this.passManager.addRuleToPass(PassId.Structural, {
             id: 'fold-sort-empty',
@@ -338,6 +593,8 @@ export class Optimizer {
             phase: 'rewrite',
             fn: ruleSortFoldEmpty,
             priority: 27,
+            // Source is EmptyRelation; see fold-project-empty.
+            sideEffectMode: 'safe',
         });
         this.passManager.addRuleToPass(PassId.Structural, {
             id: 'fold-limit-empty',
@@ -345,6 +602,8 @@ export class Optimizer {
             phase: 'rewrite',
             fn: ruleLimitOffsetFoldEmpty,
             priority: 27,
+            // Source is EmptyRelation; see fold-project-empty.
+            sideEffectMode: 'safe',
         });
         this.passManager.addRuleToPass(PassId.Structural, {
             id: 'fold-distinct-empty',
@@ -352,6 +611,8 @@ export class Optimizer {
             phase: 'rewrite',
             fn: ruleDistinctFoldEmpty,
             priority: 27,
+            // Source is EmptyRelation; see fold-project-empty.
+            sideEffectMode: 'safe',
         });
         this.passManager.addRuleToPass(PassId.Structural, {
             id: 'fold-join-empty',
@@ -359,6 +620,10 @@ export class Optimizer {
             phase: 'rewrite',
             fn: ruleJoinFoldEmpty,
             priority: 27,
+            // Folds an inner/cross/semi/anti join with an empty side to Empty,
+            // dropping the *other* side — refuses when the dropped side carries
+            // a write.
+            sideEffectMode: 'aware',
         });
         // Physical pass rules (bottom-up) - for logical to physical transformations
         this.passManager.addRuleToPass(PassId.Physical, {
@@ -366,7 +631,10 @@ export class Optimizer {
             nodeType: PlanNodeType.Retrieve,
             phase: 'impl',
             fn: ruleSelectAccessPath,
-            priority: 10
+            priority: 10,
+            // Replaces a logical Retrieve with a physical access node over the
+            // same TableReference — read-only by construction.
+            sideEffectMode: 'safe',
         });
         // QuickPick join enumeration (optional via tuning)
         this.passManager.addRuleToPass(PassId.Physical, {
@@ -374,14 +642,20 @@ export class Optimizer {
             nodeType: PlanNodeType.Join,
             phase: 'impl',
             fn: ruleQuickPickJoinEnumeration,
-            priority: 5
+            priority: 5,
+            // Reorders inner-join trees by cost — would change side-effect
+            // execution order. Refuses when any leaf relation has side effects.
+            sideEffectMode: 'aware',
         });
         this.passManager.addRuleToPass(PassId.Physical, {
             id: 'aggregate-physical',
             nodeType: PlanNodeType.Aggregate,
             phase: 'impl',
             fn: ruleAggregatePhysical,
-            priority: 20
+            priority: 20,
+            // Selects Stream vs Hash aggregate; the source is preserved verbatim
+            // (or wrapped in a Sort, which executes its source once).
+            sideEffectMode: 'safe',
         });
         // Recognize lateral-top-1 asof. Runs in the Structural pass (before
         // predicate-pushdown at priority 20) so the lateral's Filter still
@@ -392,7 +666,12 @@ export class Optimizer {
             nodeType: PlanNodeType.Join,
             phase: 'rewrite',
             fn: ruleLateralTop1Asof,
-            priority: 5
+            priority: 5,
+            // Recognizes a very narrow shape (Project/Limit/Sort/Filter chain
+            // over a vtab leaf that advertises asofRight) — leaf must be a
+            // physical TableReference, so all participating subtrees are
+            // read-only by construction.
+            sideEffectMode: 'safe',
         });
         // Post-optimization pass rules (bottom-up) - for cleanup and caching
         // Physical join selection runs here (after Physical pass) so QuickPick can
@@ -406,7 +685,10 @@ export class Optimizer {
             nodeType: PlanNodeType.Join,
             phase: 'impl',
             fn: ruleMonotonicMergeJoin,
-            priority: 4
+            priority: 4,
+            // Replaces a logical Join with a MergeJoin; both children survive
+            // in their original positions (no swap).
+            sideEffectMode: 'safe',
         });
         // Monotonic streaming-window recognition. Runs after monotonic-merge-join
         // (priority 4) so child joins have already become MergeJoins and
@@ -417,14 +699,20 @@ export class Optimizer {
             nodeType: PlanNodeType.Window,
             phase: 'impl',
             fn: ruleMonotonicWindow,
-            priority: 6
+            priority: 6,
+            // Tags the WindowNode with a streaming config in place; source and
+            // functions are preserved verbatim.
+            sideEffectMode: 'safe',
         });
         this.passManager.addRuleToPass(PassId.PostOptimization, {
             id: 'join-physical-selection',
             nodeType: PlanNodeType.Join,
             phase: 'impl',
             fn: ruleJoinPhysicalSelection,
-            priority: 5
+            priority: 5,
+            // May swap build/probe sides of an INNER hash join — would reorder
+            // side-effect execution. Refuses when either side has side effects.
+            sideEffectMode: 'aware',
         });
         // Monotonic LIMIT/OFFSET pushdown: replace LimitOffset[/Sort]/access-leaf
         // with OrdinalSlice when the leaf advertises supportsOrdinalSeek. Runs in
@@ -434,7 +722,11 @@ export class Optimizer {
             nodeType: PlanNodeType.LimitOffset,
             phase: 'impl',
             fn: ruleMonotonicLimitPushdown,
-            priority: 8
+            priority: 8,
+            // Slides LIMIT/OFFSET into a physical access leaf via OrdinalSlice;
+            // only fires when the chain peels to a SeqScan/IndexScan/IndexSeek
+            // (all read-only by construction).
+            sideEffectMode: 'safe',
         });
         // Monotonic range-scan recognition. Runs on physical leaves to annotate
         // `rangeBoundedOn` when a handled range/equality bounds the monotonic
@@ -458,7 +750,9 @@ export class Optimizer {
                 nodeType,
                 phase: 'rewrite',
                 fn: ruleMonotonicRangeAccess,
-                priority: 9
+                priority: 9,
+                // Pure annotation of a physical access leaf (read-only).
+                sideEffectMode: 'safe',
             });
         }
         this.passManager.addRuleToPass(PassId.PostOptimization, {
@@ -466,14 +760,20 @@ export class Optimizer {
             nodeType: PlanNodeType.Filter,
             phase: 'rewrite',
             fn: ruleMonotonicRangeAccess,
-            priority: 9
+            priority: 9,
+            // Defensive escalation: drops a leaf's monotonicOn advertisement;
+            // the leaf and Filter source tree survive verbatim.
+            sideEffectMode: 'safe',
         });
         this.passManager.addRuleToPass(PassId.PostOptimization, {
             id: 'mutating-subquery-cache',
             nodeType: PlanNodeType.Join,
             phase: 'rewrite',
             fn: ruleMutatingSubqueryCache,
-            priority: 10
+            priority: 10,
+            // Specifically *targets* side-effect-bearing right sides and wraps
+            // them in a run-once CacheNode — the canonical aware rule.
+            sideEffectMode: 'aware',
         });
         // AsofScan strategy selection (hash → merge). Runs after the leaves'
         // physical.ordering / monotonicOn are finalized (range-access at
@@ -483,7 +783,9 @@ export class Optimizer {
             nodeType: PlanNodeType.AsofScan,
             phase: 'impl',
             fn: ruleAsofStrategySelect,
-            priority: 11
+            priority: 11,
+            // Flips a strategy field on an existing AsofScan; children survive.
+            sideEffectMode: 'safe',
         });
         // Async-gather UNION ALL fold: collapse a chain of
         // SetOperationNode(unionAll) into one N-ary AsyncGatherNode(unionAll)
@@ -502,7 +804,11 @@ export class Optimizer {
             nodeType: PlanNodeType.SetOperation,
             phase: 'rewrite',
             fn: ruleAsyncGatherUnionAll,
-            priority: 17
+            priority: 17,
+            // Drives N branches concurrently — would interleave writes from
+            // side-effect-bearing branches in non-deterministic order. Refuses
+            // when any branch carries a write.
+            sideEffectMode: 'aware',
         });
         // Async-gather ZIP BY KEY fold: collapse a `Project` over a chain of
         // binary full-outer `JoinNode`s sharing a common key set into one N-ary
@@ -517,7 +823,9 @@ export class Optimizer {
             nodeType: PlanNodeType.Project,
             phase: 'rewrite',
             fn: ruleAsyncGatherZipByKey,
-            priority: 17
+            priority: 17,
+            // Concurrent N-ary zip by key — same concern as union-all gather.
+            sideEffectMode: 'aware',
         });
         // Eager-prefetch probe wrap: when a physical hash join's build (right)
         // side is high-latency, wrap the probe (left) side in an
@@ -536,7 +844,11 @@ export class Optimizer {
             nodeType: PlanNodeType.HashJoin,
             phase: 'rewrite',
             fn: ruleEagerPrefetchProbe,
-            priority: 15
+            priority: 15,
+            // Wraps the probe side in a concurrent prefetch pump — iterates the
+            // probe subtree concurrently with the build side, which would
+            // interleave writes. Refuses when either side has side effects.
+            sideEffectMode: 'aware',
         });
         // Fan-out batched-outer recognition: flip an already-formed
         // `FanOutLookupJoinNode` from serial to batched outer mode when the per-row
@@ -553,14 +865,23 @@ export class Optimizer {
             nodeType: PlanNodeType.FanOutLookupJoin,
             phase: 'rewrite',
             fn: ruleFanOutBatchedOuter,
-            priority: 16
+            priority: 16,
+            // Flips fan-out outer pump to batched (concurrent) — interleaves
+            // outer iteration with branch lookups. Refuses on side-effect outer.
+            sideEffectMode: 'aware',
         });
         this.passManager.addRuleToPass(PassId.PostOptimization, {
             id: 'cte-optimization',
             nodeType: PlanNodeType.CTE,
             phase: 'rewrite',
             fn: ruleCteOptimization,
-            priority: 20
+            priority: 20,
+            // Wraps a CTE source in CacheNode. CacheNode materializes on first
+            // read and replays on subsequent reads — a run-once fence over the
+            // source, so a side-effect-bearing CTE that was previously rerun
+            // per reference would now run once. That is sound but order-changing,
+            // so the rule is aware of side effects.
+            sideEffectMode: 'aware',
         });
         // IN-subquery caching: wrap uncorrelated IN subquery sources in CacheNode
         this.passManager.addRuleToPass(PassId.PostOptimization, {
@@ -568,7 +889,9 @@ export class Optimizer {
             nodeType: PlanNodeType.In,
             phase: 'rewrite',
             fn: ruleInSubqueryCache,
-            priority: 25
+            priority: 25,
+            // Already gates on `isFunctional(source)` (deterministic + read-only).
+            sideEffectMode: 'aware',
         });
         // Register materialization advisory for multiple node types
         const nodeTypesForMaterialization = [
@@ -591,7 +914,17 @@ export class Optimizer {
                 nodeType,
                 phase: 'rewrite',
                 fn: ruleMaterializationAdvisory,
-                priority: 30
+                priority: 30,
+                // Delegates to MaterializationAdvisory. The advisory does not
+                // explicitly consult `hasSideEffects` — soundness for impure
+                // subtrees rests on CacheNode itself being a run-once fence
+                // (materialize-on-first-read, replay thereafter), so a
+                // side-effect-bearing subtree that the advisory would otherwise
+                // wrap runs exactly once instead of per-reference. That is a
+                // count-change but order-preserving rewrite — and matches the
+                // run-once contract the scalar / IN / EXISTS emitters apply
+                // directly when their inner is impure (see `docs/runtime.md`).
+                sideEffectMode: 'aware',
             });
         }
         log('Registered rules to optimization passes');