docs(driver-sql): say why applyFilterCondition keeps logicalOp after #3776 (#3799)

#3776 left `logicalOp === 'or'` unreachable: all four call sites pass 'and' —
the sole external caller plus the `$and`/`$or`/`$not` arms — so the ~15
`logicalOp === 'or'` ternaries are dead code.

Keep the parameter rather than prune it. `applyFilterCondition` is `protected`,
i.e. subclass API (`SqliteWasmDriver` here, `TursoDriver` downstream), and the
flag is the seam an override needs to attach a condition into an OR group.
Removing it is source-breaking for any subclass overriding the four-parameter
signature, which under this repo's lockstep versioning costs a whole-stack
major — steep for deleting a flag that changes no behavior.

Document both halves at the method so the arms read as unreachable by design,
not as dead code inviting a "fix" that makes a branch propagate 'or' again —
precisely the #3774 miscompile.

Comment-only. sql-driver-or-filter.test.ts (19 cases) and the full driver-sql
suite (386) stay green; empty changeset since this releases nothing.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/driver-sql-logicalop-retention-note.md

@@ -0,0 +1,26 @@
+---
+---
+
+docs(driver-sql): record why `applyFilterCondition` keeps its `logicalOp` parameter
+
+Comment-only; no behavior change, and this changeset releases nothing.
+
+#3776 made `logicalOp === 'or'` unreachable. All four call sites now pass
+`'and'` — the sole external caller plus the `$and`/`$or`/`$not` arms — because
+every key inside one filter object AND-s at every depth, and the `orWhere` that
+OR-s `$or`'s branches is applied to each branch's own sub-builder rather than
+handed down as `logicalOp`. Handing it down was the #3774 miscompile that
+widened every `$or` filter.
+
+That leaves ~15 `logicalOp === 'or'` ternaries that nothing in the repo can
+reach. They are kept deliberately: `applyFilterCondition` is `protected`, so it
+is subclass API (`SqliteWasmDriver` here, `TursoDriver` downstream), and the
+flag is the seam an override needs to attach a condition into an OR group.
+Removing it would be source-breaking for any subclass that overrides the
+four-parameter signature, which in this repo's lockstep versioning costs a
+whole-stack major — a steep price for deleting a flag that changes no behavior.
+
+The method-level TSDoc now states both halves, so the arms read as unreachable
+*by design* instead of as dead code inviting a "fix" that makes a branch
+propagate `'or'` again. `sql-driver-or-filter.test.ts` (19 cases) pins the
+semantics that made the flag dead.

packages/plugins/driver-sql/src/sql-driver.ts

@@ -3804,6 +3804,22 @@ export class SqlDriver implements IDataDriver {
     }
   }
 
+  /**
+   * Compiles a Filter Protocol condition onto `builder`.
+   *
+   * `logicalOp` controls only how this condition attaches to `builder`
+   * (`where` vs `orWhere`) — never how its contents combine. It is never
+   * `'or'` on any in-repo path: the sole caller passes `'and'` and every
+   * combinator recurses with `'and'`, because all keys in one filter object
+   * AND at every depth. The `orWhere` that OR-s `$or`'s branches is applied
+   * to each branch's own sub-builder; handing `'or'` down instead is exactly
+   * what widened every `$or` filter (#3774 — see sql-driver-or-filter.test.ts).
+   *
+   * So the `logicalOp === 'or'` arms below are unreachable **by design**, not
+   * dead weight to prune: the method is `protected`, i.e. subclass API, and
+   * the flag is the seam an override needs to attach a condition into an OR
+   * group. Do not "fix" them by making a branch propagate `'or'` again.
+   */
   protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp: 'and' | 'or' = 'and', tableHint?: string | null) {
     if (!condition || typeof condition !== 'object') return;
     const table = tableHint ?? this.coercionKey(builder);