bunsane 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to bunsane are documented here.
 
+## 0.5.2 — 2026-06-19
+
+### Added
+
+- **`withLock(key, fn, options?)`** — public distributed-lock primitive,
+  exported from `bunsane/core`. Runs `fn` while holding a PostgreSQL advisory
+  lock and always releases it (even if `fn` throws); only one holder of a given
+  `key` runs `fn` at a time across every process pointed at the same database.
+  Returns `{ acquired: true, result }`, or `{ acquired: false }` when the lock
+  is held elsewhere (`fn` does not run). Wraps the same `DistributedLock`
+  singleton and PostgreSQL session the scheduler uses for task exclusion, now
+  surfaced for app-level "run once cluster-wide" work — reindex, migration,
+  cache rebuild. `options.wait` (ms, default `0` = try once) blocks for the lock
+  instead of skipping; `options.retryInterval` (default 100 ms) sets the poll
+  cadence. Layers an in-process guard over the advisory lock because PostgreSQL
+  advisory locks are reentrant per session — without it, two concurrent
+  same-key callers in one process would both win. Not reentrant; crash-safe
+  (session-scoped); honors `distributedLocking: false` (then always reports
+  `acquired: true` with no real lock). Also re-exported from
+  `bunsane/core/scheduler`. A new `core/index.ts` barrel establishes
+  `bunsane/core` as a public entry point.
+
 ## 0.5.1 — 2026-06-16
 
 ### Added

package/core/app/requestRouter.ts

@@ -198,16 +198,45 @@ export async function handleRequest(app: any, req: Request): Promise<Response> {
 
         for (const [route, folder] of app.staticAssets) {
             if (url.pathname.startsWith(route)) {
-                const relativePath = url.pathname.slice(route.length);
-                const filePath = path.join(folder, relativePath);
+                const rawRelative = url.pathname.slice(route.length);
+                // Decode percent-encoding first so encoded traversal sequences
+                // (e.g. %2e%2e%2f) can't slip past the containment check.
+                let decodedRelative: string;
                 try {
-                    const file = Bun.file(filePath);
+                    decodedRelative = decodeURIComponent(rawRelative);
+                } catch {
+                    clearTimeout(timeoutId);
+                    return wrap(new Response("Bad request", {
+                        status: 400,
+                        headers: { "Content-Type": "text/plain" },
+                    }));
+                }
+                // Resolve absolutely and confirm the target stays inside the
+                // served folder — blocks path traversal (../) out of the dir.
+                // Strip leading slashes so path.resolve treats the request as
+                // relative to the folder (an absolute-looking arg would reset
+                // to the filesystem root and bypass containment).
+                const relForResolve = decodedRelative.replace(/^[/\\]+/, "");
+                const resolvedBase = path.resolve(folder);
+                const resolvedFile = path.resolve(resolvedBase, relForResolve);
+                if (
+                    resolvedFile !== resolvedBase &&
+                    !resolvedFile.startsWith(resolvedBase + path.sep)
+                ) {
+                    clearTimeout(timeoutId);
+                    return wrap(new Response("Forbidden", {
+                        status: 403,
+                        headers: { "Content-Type": "text/plain" },
+                    }));
+                }
+                try {
+                    const file = Bun.file(resolvedFile);
                     if (await file.exists()) {
                         clearTimeout(timeoutId);
                         return wrap(new Response(file));
                     }
                 } catch (error) {
-                    logger.error(`Error serving static file ${filePath}:`, error as any);
+                    logger.error(`Error serving static file ${resolvedFile}:`, error as any);
                 }
             }
         }

package/core/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Public `bunsane/core` entry point.
+ *
+ * Subpath imports (`bunsane/core/App`, `bunsane/core/middleware`, …) remain the
+ * primary surface; this barrel re-exports cross-cutting primitives intended to
+ * be imported as `bunsane/core`.
+ */
+
+export {
+    withLock,
+    type WithLockOptions,
+    type LockOutcome,
+    DistributedLock,
+    getDistributedLock,
+    resetDistributedLock,
+    DEFAULT_LOCK_CONFIG,
+    type DistributedLockConfig,
+    type LockResult,
+} from "./scheduler";

package/core/scheduler/index.ts

@@ -13,3 +13,9 @@ export {
     type DistributedLockConfig,
     type LockResult,
 } from './DistributedLock';
+
+export {
+    withLock,
+    type WithLockOptions,
+    type LockOutcome,
+} from './withLock';

package/core/scheduler/withLock.ts

@@ -0,0 +1,98 @@
+/**
+ * withLock — run a function while holding a PostgreSQL advisory lock.
+ *
+ * Thin convenience wrapper over the shared {@link DistributedLock} singleton.
+ * Acquires the lock for `key`, runs `fn`, and always releases it — even if
+ * `fn` throws. Only one holder of a given `key` runs `fn` at a time, across
+ * every process pointed at the same database. When the lock is unavailable the
+ * call returns `{ acquired: false }` without running `fn` (unless `wait` is
+ * set, in which case it polls until the lock frees or the deadline passes).
+ *
+ * Two layers of exclusion:
+ *  - Across processes: PostgreSQL `pg_advisory_lock`, owned by the singleton's
+ *    pinned connection (one PG session per instance).
+ *  - Within a process: an in-memory `Set`. PostgreSQL advisory locks are
+ *    *reentrant per session*, so two concurrent callers sharing this instance's
+ *    session would both win the pg lock — the Set makes same-process contention
+ *    exclusive too.
+ *
+ * Notes:
+ *  - Not reentrant. Calling `withLock(key, …)` for a key already held by this
+ *    process returns `{ acquired: false }` (or waits, then gives up).
+ *  - Shares the scheduler's singleton + PG session. Keys live under the same
+ *    namespace prefix as scheduler task ids — pick keys unlikely to collide.
+ *  - Honors the singleton's `enabled` config: if distributed locking was
+ *    disabled (`getDistributedLock({ enabled: false })`), `tryAcquire` always
+ *    reports success and no real lock is taken.
+ *
+ * @example
+ * const res = await withLock("rebuild-search-index", async () => {
+ *   await rebuildIndex();
+ *   return "done";
+ * });
+ * if (!res.acquired) {
+ *   // another instance is already rebuilding — skip
+ * } else {
+ *   console.log(res.result); // "done"
+ * }
+ */
+import { getDistributedLock } from "./DistributedLock";
+
+export interface WithLockOptions {
+    /** Max ms to wait for the lock before giving up. 0 (default) = try once. */
+    wait?: number;
+    /** Poll interval while waiting, in ms. Default 100. */
+    retryInterval?: number;
+}
+
+export type LockOutcome<T> =
+    | { acquired: false; result?: undefined }
+    | { acquired: true; result: T };
+
+/** In-process holders, keyed by lock key (see "Within a process" above). */
+const localHeld = new Set<string>();
+
+const sleep = (ms: number): Promise<void> =>
+    new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function withLock<T>(
+    key: string,
+    fn: () => Promise<T> | T,
+    options: WithLockOptions = {}
+): Promise<LockOutcome<T>> {
+    const { wait = 0, retryInterval = 100 } = options;
+    const deadline = wait > 0 ? Date.now() + wait : 0;
+
+    // In-process gate. The has-check that exits the loop and the subsequent
+    // add() run without an await between them, so this is atomic on JS's single
+    // thread — concurrent same-key callers cannot both pass.
+    while (localHeld.has(key)) {
+        if (!deadline || Date.now() >= deadline) {
+            return { acquired: false };
+        }
+        await sleep(retryInterval);
+    }
+    localHeld.add(key);
+
+    try {
+        const lock = getDistributedLock();
+
+        let acquired = (await lock.tryAcquire(key)).acquired;
+        while (!acquired && deadline && Date.now() < deadline) {
+            await sleep(retryInterval);
+            acquired = (await lock.tryAcquire(key)).acquired;
+        }
+
+        if (!acquired) {
+            return { acquired: false };
+        }
+
+        try {
+            return { acquired: true, result: await fn() };
+        } finally {
+            await lock.release(key);
+        }
+    } finally {
+        localHeld.delete(key);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.5.2",
+    "version": "0.5.4",
     "author": {
         "name": "yaaruu"
     },

package/query/ComponentInclusionNode.ts

@@ -3,6 +3,7 @@ import type { QueryResult } from "./QueryNode";
 import { QueryContext } from "./QueryContext";
 import { shouldUseLateralJoins, shouldUseDirectPartition } from "../core/Config";
 import { FilterBuilderRegistry } from "./FilterBuilderRegistry";
+import { jsonbInListCast } from "./FilterBuilder";
 import { ComponentRegistry } from "../core/components";
 import { getMetadataStorage } from "../core/metadata";
 import { assertIdentifier } from "./SqlIdentifier";
@@ -95,8 +96,9 @@ export class ComponentInclusionNode extends QueryNode {
             return `${jsonPath} ${filter.operator} $${context.addParam(filter.value)}`;
         } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
             if (Array.isArray(filter.value) && filter.value.length > 0) {
-                const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}`).join(', ');
-                return `${jsonPath} ${filter.operator} (${placeholders})`;
+                const cast = jsonbInListCast(filter.value);
+                const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}${cast.param}`).join(', ');
+                return `${cast.lhs(jsonPath)} ${filter.operator} (${placeholders})`;
             } else if (Array.isArray(filter.value) && filter.value.length === 0) {
                 return filter.operator === 'IN' ? 'FALSE' : 'TRUE';
             }
@@ -665,8 +667,9 @@ export class ComponentInclusionNode extends QueryNode {
                 condition = `(${jsonPath})::boolean ${filter.operator} $${context.addParam(filter.value)}`;
             } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
                 if (Array.isArray(filter.value) && filter.value.length > 0) {
-                    const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}`).join(', ');
-                    condition = `${jsonPath} ${filter.operator} (${placeholders})`;
+                    const cast = jsonbInListCast(filter.value);
+                    const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}${cast.param}`).join(', ');
+                    condition = `${cast.lhs(jsonPath)} ${filter.operator} (${placeholders})`;
                 } else {
                     return null; // Invalid or empty array - fall back to normal path
                 }
@@ -860,14 +863,17 @@ export class ComponentInclusionNode extends QueryNode {
                         // String LIKE/ILIKE comparison - no casting
                         condition = `${jsonPath} ${filter.operator} $${context.addParam(filter.value)}`;
                     } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
-                        // IN/NOT IN comparison - handle arrays properly
+                        // IN/NOT IN comparison - handle arrays properly. Numeric/
+                        // boolean lists need a cast on both the JSONB text field
+                        // and each parameter, else `text IN (1, 2)` errors.
                         if (Array.isArray(filter.value) && filter.value.length > 0) {
+                            const cast = jsonbInListCast(filter.value);
                             let placeholders = '';
                             for (let i = 0; i < filter.value.length; i++) {
                                 if (i) placeholders += ', ';
-                                placeholders += '$' + context.addParam(filter.value[i]);
+                                placeholders += '$' + context.addParam(filter.value[i]) + cast.param;
                             }
-                            condition = `${jsonPath} ${filter.operator} (${placeholders})`;
+                            condition = `${cast.lhs(jsonPath)} ${filter.operator} (${placeholders})`;
                         } else if (Array.isArray(filter.value) && filter.value.length === 0) {
                             // Empty array: IN () is always false, NOT IN () is always true
                             condition = filter.operator === 'IN' ? 'FALSE' : 'TRUE';

package/query/FilterBuilder.ts

@@ -90,6 +90,25 @@ export function buildJSONBPath(field: string, alias: string): string {
     return `${alias}.data->'${field}'`;
 }
 
+/**
+ * Determine the type cast for an `IN` / `NOT IN` value list against a JSONB
+ * text-extracted field (`data->>'x'` always yields text). Without a cast a
+ * numeric/boolean list produces `text IN (1, 2)` → PostgreSQL "operator does
+ * not exist: text = integer". When every element is a number (or boolean) we
+ * cast both the field and each parameter, mirroring the scalar `=` path. Mixed
+ * or string lists stay as plain text comparison (the correct default).
+ *
+ * @returns `lhs(path)` wraps the field expression; `param` is the per-parameter
+ *          cast suffix (e.g. `::numeric`), `''` for text.
+ */
+export function jsonbInListCast(values: any[]): { lhs: (path: string) => string; param: string } {
+    const allNumbers = values.length > 0 && values.every(v => typeof v === 'number');
+    if (allNumbers) return { lhs: (p) => `(${p})::numeric`, param: '::numeric' };
+    const allBooleans = values.length > 0 && values.every(v => typeof v === 'boolean');
+    if (allBooleans) return { lhs: (p) => `(${p})::boolean`, param: '::boolean' };
+    return { lhs: (p) => p, param: '' };
+}
+
 /**
  * Compose multiple filter builders into a single builder that applies all conditions
  *

package/query/OrNode.ts

@@ -5,6 +5,24 @@ import { OrQuery } from "./OrQuery";
 import { ComponentRegistry } from "../core/components";
 import { shouldUseDirectPartition } from "../core/Config";
 import { getMembershipTable } from "./membershipSource";
+import { jsonbInListCast } from "./FilterBuilder";
+
+/**
+ * Gate for the base-dependency single-pass OR rewrite (base scanned once,
+ * branches combined as OR-of-EXISTS instead of N× base + UNION + DISTINCT).
+ *
+ * Default ON — the single-pass shape is parity-proven against the legacy UNION
+ * path (identical exec/paginate/count results) and ~20× faster (no per-branch
+ * cartesian nested-loop; base anti-join computed once). Read at call time.
+ *
+ * Kill-switch: set BUNSANE_ORNODE_SINGLE_PASS=0 (or "false") to revert to the
+ * legacy UNION shape instantly, no redeploy — for the unlikely case a real
+ * Postgres planner regresses on a specific OR shape.
+ */
+function shouldUseOrSinglePass(): boolean {
+    const v = process.env.BUNSANE_ORNODE_SINGLE_PASS;
+    return v !== '0' && v !== 'false';
+}
 
 export class OrNode extends QueryNode {
     private orQuery: OrQuery;
@@ -111,15 +129,17 @@ export class OrNode extends QueryNode {
                             break;
                         case "IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                branchSql += ` AND ${jsonPath} IN (${placeholders})`;
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                branchSql += ` AND ${cast.lhs(jsonPath)} IN (${placeholders})`;
                                 context.params.push(...value);
                             }
                             break;
                         case "NOT IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                branchSql += ` AND ${jsonPath} NOT IN (${placeholders})`;
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                branchSql += ` AND ${cast.lhs(jsonPath)} NOT IN (${placeholders})`;
                                 context.params.push(...value);
                             }
                             break;
@@ -150,7 +170,7 @@ export class OrNode extends QueryNode {
         if (context.excludedComponentIds.size > 0) {
             const excludedTypes = Array.from(context.excludedComponentIds);
             const placeholders = excludedTypes.map(() => `$${paramIndex++}`).join(', ');
-            conditions.push(`NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = or_results.id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`);
+            conditions.push(`NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = or_results.entity_id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`);
             context.params.push(...excludedTypes);
         }
 
@@ -232,15 +252,17 @@ export class OrNode extends QueryNode {
                             break;
                         case "IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                conditions.push(`${jsonPath} IN (${placeholders})`);
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                conditions.push(`${cast.lhs(jsonPath)} IN (${placeholders})`);
                                 context.params.push(...value);
                             }
                             break;
                         case "NOT IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                conditions.push(`${jsonPath} NOT IN (${placeholders})`);
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                conditions.push(`${cast.lhs(jsonPath)} NOT IN (${placeholders})`);
                                 context.params.push(...value);
                             }
                             break;
@@ -329,15 +351,43 @@ export class OrNode extends QueryNode {
         let baseEntityQuery = "";
 
         if (hasComponentDependency) {
-            // Get base entities from ComponentInclusionNode
+            // Get base entities from ComponentInclusionNode.
+            //
+            // CRITICAL: the base set must be UNBOUNDED. OrNode embeds this SQL
+            // as `FROM (base) WHERE EXISTS (<or filter>)` and applies LIMIT/
+            // OFFSET to the *final* OR-filtered result below. If the base node
+            // bakes the caller's LIMIT/OFFSET into its own SQL, the EXISTS OR
+            // filter only ever sees the first page of base entities (ordered by
+            // entity_id), so any match beyond that page silently vanishes —
+            // e.g. a search whose only hits live on page 2+ returns 0 rows
+            // while count() (which strips pagination) reports them. Null out
+            // pagination around the base build, then restore so the final
+            // pagination below is unaffected. cursorId is left intact: it
+            // constrains the candidate set (entity_id > cursor) which composes
+            // correctly with the final LIMIT.
             const componentNode = this.dependencies[0];
             if (componentNode) {
+                const savedLimit = context.limit;
+                const savedOffset = context.offsetValue;
+                context.limit = null;
+                context.offsetValue = 0;
                 const baseResult = componentNode.execute(context);
+                context.limit = savedLimit;
+                context.offsetValue = savedOffset;
                 baseEntityQuery = baseResult.sql;
                 paramIndex = baseResult.context.paramIndex;
             }
         }
 
+        // Gated single-pass rewrite: scan the base set ONCE and combine the OR
+        // branches as a disjunction of EXISTS predicates, instead of embedding
+        // the base SQL inside every branch and UNION-ing (N× base scan +
+        // UNION dedup + redundant outer DISTINCT). Same param push order, same
+        // result set, same ORDER BY entity_id ASC + pagination semantics.
+        if (hasComponentDependency && baseEntityQuery && shouldUseOrSinglePass()) {
+            return this.executeBaseSinglePass(context, baseEntityQuery, paramIndex);
+        }
+
         // Build SQL for each branch
         for (const branch of this.orQuery.branches) {
             const componentId = ComponentRegistry.getComponentId(branch.component.name);
@@ -408,15 +458,17 @@ export class OrNode extends QueryNode {
                             break;
                         case "IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                filterConditions.push(`${jsonPath} IN (${placeholders})`);
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                filterConditions.push(`${cast.lhs(jsonPath)} IN (${placeholders})`);
                                 context.params.push(...value);
                             }
                             break;
                         case "NOT IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                filterConditions.push(`${jsonPath} NOT IN (${placeholders})`);
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                filterConditions.push(`${cast.lhs(jsonPath)} NOT IN (${placeholders})`);
                                 context.params.push(...value);
                             }
                             break;
@@ -447,7 +499,7 @@ export class OrNode extends QueryNode {
             for (const componentType of allComponentTypes) {
                 const componentId = ComponentRegistry.getComponentId(componentType);
                 if (componentId) {
-                    componentConditions.push(`EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_all WHERE ec_all.entity_id = or_results.id AND ec_all.type_id = $${paramIndex} AND ec_all.deleted_at IS NULL)`);
+                    componentConditions.push(`EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_all WHERE ec_all.entity_id = or_results.entity_id AND ec_all.type_id = $${paramIndex} AND ec_all.deleted_at IS NULL)`);
                     context.params.push(componentId);
                     paramIndex++;
                 }
@@ -469,7 +521,7 @@ export class OrNode extends QueryNode {
         if (context.excludedComponentIds.size > 0) {
             const excludedTypes = Array.from(context.excludedComponentIds);
             const placeholders = excludedTypes.map(() => `$${paramIndex++}`).join(', ');
-            conditions.push(`NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = or_results.id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`);
+            conditions.push(`NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = or_results.entity_id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`);
             context.params.push(...excludedTypes);
         }
 
@@ -498,7 +550,150 @@ export class OrNode extends QueryNode {
             params: context.params,
             context
         };
-    }    public getNodeType(): string {
+    }
+
+    /**
+     * Build a single OR branch as an `EXISTS (...)` predicate against the
+     * branch component's table, correlated to `idExpr` (e.g. `base.id`).
+     * Mirrors the filter switch of the legacy dependency branch exactly —
+     * same SQL fragments, same param push order — so the single-pass shape is
+     * result- and parameter-identical to the UNION shape it replaces.
+     */
+    private buildBranchExists(
+        branch: OrQuery['branches'][number],
+        idExpr: string,
+        context: QueryContext,
+        paramIndex: number
+    ): { sql: string; paramIndex: number } {
+        const componentId = ComponentRegistry.getComponentId(branch.component.name);
+        if (!componentId) {
+            throw new Error(`Component ${branch.component.name} is not registered`);
+        }
+
+        const componentTableName = this.getComponentTableName(componentId);
+        const componentIdParamIndex = paramIndex;
+
+        let sql = `EXISTS (
+            SELECT 1 FROM ${componentTableName} c
+            WHERE c.entity_id = ${idExpr}
+            AND c.type_id = $${componentIdParamIndex}
+            AND c.deleted_at IS NULL`;
+
+        context.params.push(componentId);
+        paramIndex++;
+
+        if (branch.filters && branch.filters.length > 0) {
+            for (const filter of branch.filters) {
+                const { field, operator, value } = filter;
+                const jsonPath = `c.data->>'${field}'`;
+
+                switch (operator) {
+                    case "=":
+                    case ">":
+                    case "<":
+                    case ">=":
+                    case "<=":
+                    case "!=":
+                        if (typeof value === "string") {
+                            sql += ` AND ${jsonPath} ${operator} $${paramIndex}`;
+                        } else {
+                            sql += ` AND (${jsonPath})::numeric ${operator} $${paramIndex}`;
+                        }
+                        context.params.push(value);
+                        paramIndex++;
+                        break;
+                    case "LIKE":
+                    case "ILIKE":
+                        sql += ` AND ${jsonPath} ${operator} $${paramIndex}`;
+                        context.params.push(value);
+                        paramIndex++;
+                        break;
+                    case "IN":
+                        if (Array.isArray(value)) {
+                            const cast = jsonbInListCast(value);
+                            const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                            sql += ` AND ${cast.lhs(jsonPath)} IN (${placeholders})`;
+                            context.params.push(...value);
+                        }
+                        break;
+                    case "NOT IN":
+                        if (Array.isArray(value)) {
+                            const cast = jsonbInListCast(value);
+                            const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                            sql += ` AND ${cast.lhs(jsonPath)} NOT IN (${placeholders})`;
+                            context.params.push(...value);
+                        }
+                        break;
+                    default:
+                        throw new Error(`Unsupported operator: ${operator}`);
+                }
+            }
+        }
+
+        sql += ")";
+        return { sql, paramIndex };
+    }
+
+    /**
+     * Single-pass execution for OR-on-base queries. The base set (the embedded
+     * ComponentInclusionNode SQL) is referenced once; each OR branch becomes an
+     * EXISTS predicate OR-ed together. Exclusions, ordering and pagination
+     * match the UNION path exactly (the base node already applied exclusions —
+     * re-applying here is the same idempotent no-op the UNION path performed).
+     */
+    private executeBaseSinglePass(
+        context: QueryContext,
+        baseEntityQuery: string,
+        paramIndexStart: number
+    ): QueryResult {
+        let paramIndex = paramIndexStart;
+
+        const existsClauses: string[] = [];
+        for (const branch of this.orQuery.branches) {
+            const built = this.buildBranchExists(branch, 'base.id', context, paramIndex);
+            existsClauses.push(built.sql);
+            paramIndex = built.paramIndex;
+        }
+
+        let sql = `SELECT base.id as id FROM (${baseEntityQuery}) AS base WHERE (${existsClauses.join(' OR ')})`;
+
+        // Entity exclusions (idempotent — base already excluded them).
+        if (context.excludedEntityIds.size > 0) {
+            const excludedIds = Array.from(context.excludedEntityIds);
+            const placeholders = excludedIds.map(() => `$${paramIndex++}`).join(', ');
+            sql += ` AND base.id NOT IN (${placeholders})`;
+            context.params.push(...excludedIds);
+        }
+
+        // Component exclusions (idempotent — base already excluded them).
+        if (context.excludedComponentIds.size > 0) {
+            const excludedTypes = Array.from(context.excludedComponentIds);
+            const placeholders = excludedTypes.map(() => `$${paramIndex++}`).join(', ');
+            sql += ` AND NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = base.id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`;
+            context.params.push(...excludedTypes);
+        }
+
+        sql += " ORDER BY base.id";
+
+        if (context.limit !== null) {
+            sql += ` LIMIT $${paramIndex++}`;
+            context.params.push(context.limit);
+        }
+        if (context.offsetValue > 0) {
+            sql += ` OFFSET $${paramIndex++}`;
+            context.params.push(context.offsetValue);
+        }
+
+        context.paramIndex = paramIndex;
+
+        return {
+            sql,
+            params: context.params,
+            context
+        };
+    }
+
+    public getNodeType(): string {
         return "OrNode";
     }
 }