@undefineds.co/xpod 0.3.6 → 0.3.15

package/dist/storage/rdf/RdfLocalQueryEngine.js

@@ -0,0 +1,2705 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RdfLocalQueryEngine = void 0;
+exports.variable = variable;
+const n3_1 = require("n3");
+const types_1 = require("../quint/types");
+const RdfTermSemantics_1 = require("./RdfTermSemantics");
+const TERM_KEYS = ['graph', 'subject', 'predicate', 'object'];
+const PLANNER_SAMPLE_BINDINGS = 16;
+const XSD_DECIMAL = 'http://www.w3.org/2001/XMLSchema#decimal';
+const XSD_INTEGER = 'http://www.w3.org/2001/XMLSchema#integer';
+class RdfLocalQueryEngine {
+    constructor(index, textIndex, vectorIndex, rdf3xPrimaryIndex) {
+        this.index = index;
+        this.textIndex = textIndex;
+        this.vectorIndex = vectorIndex;
+        this.rdf3xPrimaryIndex = rdf3xPrimaryIndex;
+    }
+    query(query) {
+        const start = Date.now();
+        const metrics = {
+            engine: 'solid-rdf',
+            plan: [],
+            scannedRows: 0,
+            joinedRows: 0,
+            returnedRows: 0,
+            durationMs: 0,
+            indexChoices: [],
+            cardinalityEstimates: 0,
+            distinctCardinalityEstimates: 0,
+            searchCardinalityEstimates: 0,
+            filtersApplied: 0,
+            filtersPushedDown: 0,
+        };
+        const hasNonPatternSource = (query.values?.length ?? 0) > 0
+            || (query.textSearch?.length ?? 0) > 0
+            || (query.vectorSearch?.length ?? 0) > 0;
+        const requiredPatterns = query.patterns.length > 0
+            ? query.patterns
+            : query.unions?.length || hasNonPatternSource
+                ? []
+                : [{}];
+        let bindings = [{}];
+        const requiredFilters = query.filters ?? [];
+        const aggregates = queryAggregates(query);
+        const singleScanPushdown = this.singleScanPushdown(query, requiredPatterns, requiredFilters);
+        const countPushdown = this.countPushdown(query, requiredPatterns, requiredFilters);
+        const groupAggregatePushdown = this.groupAggregatePushdown(query, requiredPatterns, requiredFilters, aggregates);
+        const joinCountPushdown = this.joinCountPushdown(query, requiredPatterns, requiredFilters, aggregates);
+        const joinBasicAggregatePushdown = this.joinBasicAggregatePushdown(query, requiredPatterns, requiredFilters, aggregates);
+        let groupedAggregatePushed = false;
+        if (countPushdown) {
+            const countEstimate = countPushdown.distinctKey
+                ? this.index.countDistinct(countPushdown.pattern, countPushdown.distinctKey)
+                : undefined;
+            const count = countEstimate?.rows ?? this.index.count(countPushdown.pattern);
+            const result = countLiteral(count);
+            metrics.scannedRows = count;
+            metrics.joinedRows = count;
+            metrics.returnedRows = 1;
+            metrics.durationMs = Date.now() - start;
+            metrics.indexChoices.push('count');
+            metrics.filtersPushedDown += countPushdown.pushedDownFilters;
+            metrics.plan.push(`IndexCount(${describePattern(requiredPatterns[0])})`);
+            metrics.plan.push(countPushdown.distinctKey ? 'Aggregate(count-distinct-index)' : 'Aggregate(count-index)');
+            return {
+                bindings: [{ [countPushdown.as]: result }],
+                count,
+                metrics,
+            };
+        }
+        if (joinCountPushdown) {
+            const scan = this.index.countJoinPatterns(joinCountPushdown.patterns, {
+                aggregates,
+            });
+            const firstAggregate = aggregates[0];
+            const firstCount = firstAggregate ? Number(scan.bindings[0]?.[firstAggregate.as]?.value ?? 0) : 0;
+            metrics.scannedRows = scan.metrics.matchedRows;
+            metrics.joinedRows = scan.metrics.matchedRows;
+            metrics.returnedRows = scan.bindings.length;
+            metrics.durationMs = Date.now() - start;
+            metrics.indexChoices.push(scan.metrics.indexChoice);
+            metrics.filtersPushedDown += joinCountPushdown.pushedDownFilters;
+            if (joinCountPushdown.reorderPlan) {
+                metrics.plan.push(joinCountPushdown.reorderPlan);
+            }
+            metrics.plan.push(...storagePlanMarkers(scan.metrics.queryPlan));
+            metrics.plan.push(`IndexJoinCount(${joinCountPushdown.patterns.map((source) => describePatternSource(source)).join('|')})`);
+            metrics.plan.push(aggregatePlan(aggregates, false));
+            metrics.plan.push(aggregates.some((aggregate) => aggregate.distinct)
+                ? 'Aggregate(join-count-distinct-index)'
+                : 'Aggregate(join-count-index)');
+            return {
+                bindings: scan.bindings,
+                count: firstCount,
+                metrics,
+            };
+        }
+        if (joinBasicAggregatePushdown) {
+            const scan = this.index.aggregateJoinPatterns(joinBasicAggregatePushdown.patterns, {
+                aggregates,
+            });
+            metrics.scannedRows = scan.metrics.matchedRows;
+            metrics.joinedRows = scan.metrics.matchedRows;
+            metrics.returnedRows = scan.bindings.length;
+            metrics.durationMs = Date.now() - start;
+            metrics.indexChoices.push(scan.metrics.indexChoice);
+            metrics.filtersPushedDown += joinBasicAggregatePushdown.pushedDownFilters;
+            if (joinBasicAggregatePushdown.reorderPlan) {
+                metrics.plan.push(joinBasicAggregatePushdown.reorderPlan);
+            }
+            metrics.plan.push(...storagePlanMarkers(scan.metrics.queryPlan));
+            metrics.plan.push(`IndexJoinAggregate(${joinBasicAggregatePushdown.patterns.map((source) => describePatternSource(source)).join('|')})`);
+            metrics.plan.push(aggregatePlan(aggregates, false));
+            metrics.plan.push(aggregates.length > 1
+                ? 'Aggregate(join-basic-multi-index)'
+                : 'Aggregate(join-basic-index)');
+            return {
+                bindings: scan.bindings,
+                metrics,
+            };
+        }
+        const remainingSources = buildRequiredSources(requiredPatterns, query);
+        const requiredBgpPushdown = this.requiredBgpPushdown(query, requiredPatterns, requiredFilters);
+        if (groupAggregatePushdown) {
+            const scan = groupAggregatePushdown.countOnly
+                ? this.index.groupCountJoinPatterns(groupAggregatePushdown.patterns, {
+                    groupBy: query.groupBy ?? [],
+                    aggregates,
+                    ...(groupAggregatePushdown.having ? { having: groupAggregatePushdown.having } : {}),
+                    ...(groupAggregatePushdown.orderPushed ? { orderBy: query.orderBy } : {}),
+                    ...(groupAggregatePushdown.paginationPushed && query.limit !== undefined ? { limit: Math.max(0, query.limit) } : {}),
+                    ...(groupAggregatePushdown.paginationPushed && query.offset !== undefined ? { offset: Math.max(0, query.offset) } : {}),
+                })
+                : this.index.groupAggregateJoinPatterns(groupAggregatePushdown.patterns, {
+                    groupBy: query.groupBy ?? [],
+                    aggregates,
+                    ...(groupAggregatePushdown.having ? { having: groupAggregatePushdown.having } : {}),
+                    ...(groupAggregatePushdown.orderPushed ? { orderBy: query.orderBy } : {}),
+                    ...(groupAggregatePushdown.paginationPushed && query.limit !== undefined ? { limit: Math.max(0, query.limit) } : {}),
+                    ...(groupAggregatePushdown.paginationPushed && query.offset !== undefined ? { offset: Math.max(0, query.offset) } : {}),
+                });
+            const groupPlanPrefix = groupAggregatePushdown.countOnly ? 'IndexGroupCount' : 'IndexGroupAggregate';
+            bindings = scan.bindings;
+            metrics.scannedRows += scan.metrics.matchedRows;
+            metrics.joinedRows = scan.metrics.matchedRows;
+            metrics.indexChoices.push(scan.metrics.indexChoice);
+            metrics.filtersPushedDown += groupAggregatePushdown.pushedDownFilters;
+            metrics.filtersPushedDown += groupAggregatePushdown.pushedDownHaving;
+            if (groupAggregatePushdown.reorderPlan) {
+                metrics.plan.push(groupAggregatePushdown.reorderPlan);
+            }
+            metrics.plan.push(...storagePlanMarkers(scan.metrics.queryPlan));
+            metrics.plan.push(`${groupPlanPrefix}(${(query.groupBy ?? []).map((variableName) => `?${variableName}`).join(',')})`);
+            if (groupAggregatePushdown.pushedDownHaving > 0) {
+                metrics.plan.push(`${groupPlanPrefix}Having(${(query.having ?? []).map(describeFilter).join(',')})`);
+            }
+            if (groupAggregatePushdown.orderPushed) {
+                metrics.plan.push(`${groupPlanPrefix}Order(${describeQueryOrder(query.orderBy ?? [])})`);
+            }
+            if (groupAggregatePushdown.paginationPushed) {
+                metrics.plan.push(`${groupPlanPrefix}Limit`);
+            }
+            metrics.plan.push(aggregatePlan(aggregates, true));
+            metrics.plan.push(groupAggregatePushdown.countOnly
+                ? 'Aggregate(group-count-index)'
+                : aggregates.length > 1
+                    ? 'Aggregate(group-basic-multi-index)'
+                    : 'Aggregate(group-basic-index)');
+            remainingSources.splice(0, remainingSources.length);
+            groupedAggregatePushed = true;
+        }
+        else if (requiredBgpPushdown) {
+            const useRdf3xPrimary = this.canUseRdf3xPrimaryJoin(requiredBgpPushdown.patterns);
+            const scanOptions = {
+                ...(requiredBgpPushdown.project ? { project: requiredBgpPushdown.project } : {}),
+                ...(requiredBgpPushdown.distinctPushed ? { distinct: true } : {}),
+                ...(requiredBgpPushdown.orderPushed ? { orderBy: query.orderBy } : {}),
+                ...(requiredBgpPushdown.paginationPushed && query.limit !== undefined ? { limit: Math.max(0, query.limit) } : {}),
+                ...(requiredBgpPushdown.paginationPushed && query.offset !== undefined ? { offset: Math.max(0, query.offset) } : {}),
+                ...(requiredBgpPushdown.paginationPushed ? { countMatchedRows: false } : {}),
+            };
+            const scan = useRdf3xPrimary
+                ? this.rdf3xPrimaryIndex.joinPatterns(requiredBgpPushdown.patterns, scanOptions)
+                : this.index.joinPatterns(requiredBgpPushdown.patterns, scanOptions);
+            bindings = scan.bindings;
+            metrics.scannedRows += scan.metrics.matchedRows;
+            metrics.indexChoices.push(scan.metrics.indexChoice);
+            metrics.filtersPushedDown += requiredBgpPushdown.pushedDownFilters;
+            if (!useRdf3xPrimary && requiredBgpPushdown.reorderPlan) {
+                metrics.plan.push(requiredBgpPushdown.reorderPlan);
+            }
+            metrics.plan.push(...storagePlanMarkers(scan.metrics.queryPlan));
+            metrics.plan.push(`${useRdf3xPrimary ? 'Rdf3xPrimaryJoin' : 'IndexJoin'}(${requiredBgpPushdown.patterns.map((source) => describePatternSource(source)).join('|')})`);
+            if (requiredBgpPushdown.orderPushed) {
+                metrics.plan.push(`${useRdf3xPrimary ? 'Rdf3xPrimaryJoinOrder' : 'IndexJoinOrder'}(${describeQueryOrder(query.orderBy ?? [])})`);
+            }
+            if (requiredBgpPushdown.distinctPushed) {
+                metrics.plan.push(`${useRdf3xPrimary ? 'Rdf3xPrimaryJoinDistinct' : 'IndexJoinDistinct'}(${(requiredBgpPushdown.project ?? []).map((variableName) => `?${variableName}`).join(',')})`);
+            }
+            if (requiredBgpPushdown.paginationPushed) {
+                metrics.plan.push(useRdf3xPrimary ? 'Rdf3xPrimaryJoinLimit' : 'IndexJoinLimit');
+            }
+            remainingSources.splice(0, remainingSources.length);
+        }
+        while (remainingSources.length > 0) {
+            const sourceIndex = this.chooseRequiredSourceIndex(remainingSources, bindings, requiredFilters, metrics);
+            const [source] = remainingSources.splice(sourceIndex, 1);
+            bindings = this.joinRequiredSource(bindings, source, requiredFilters, metrics, singleScanPushdown);
+            if (bindings.length === 0) {
+                break;
+            }
+        }
+        if ((query.binds?.length ?? 0) > 0) {
+            bindings = this.applyBinds(bindings, query.binds ?? []);
+            metrics.plan.push(`Bind(${(query.binds ?? []).map(describeBind).join(',')})`);
+        }
+        for (const rawOptionalGroup of query.optional ?? []) {
+            const optionalGroup = normalizeOptionalGroup(rawOptionalGroup);
+            bindings = this.joinOptionalGroup(bindings, optionalGroup, metrics);
+            metrics.plan.push(`OptionalJoin(${optionalGroup.patterns.map(describePattern).join(',')})`);
+        }
+        for (const unionGroup of query.unions ?? []) {
+            bindings = this.joinUnionGroup(bindings, unionGroup.branches, requiredFilters, metrics);
+            metrics.plan.push(`Union(${unionGroup.branches.map((branch) => branch.patterns.map(describePattern).join(',')).join('|')})`);
+            if (bindings.length === 0) {
+                break;
+            }
+        }
+        for (const minusGroup of query.minus ?? []) {
+            bindings = this.applyMinusGroup(bindings, minusGroup, metrics);
+            metrics.plan.push(`Minus(${minusGroup.patterns.map(describePattern).join(',')})`);
+            if (bindings.length === 0) {
+                break;
+            }
+        }
+        for (const existsGroup of query.exists ?? []) {
+            bindings = this.applyExistsGroup(bindings, existsGroup, metrics);
+            metrics.plan.push(`Exists(${existsGroup.patterns.map(describePattern).join(',')})`);
+            if (bindings.length === 0) {
+                break;
+            }
+        }
+        const postRequiredFilters = this.requiredFiltersNeedingPostApply(query, requiredPatterns, requiredFilters, requiredBgpPushdown);
+        if (postRequiredFilters.length > 0 && !groupedAggregatePushed) {
+            bindings = bindings.filter((binding) => this.matchesFilters(binding, postRequiredFilters));
+            metrics.filtersApplied += postRequiredFilters.length;
+            metrics.plan.push(`Filter(${postRequiredFilters.map(describeFilter).join(',')})`);
+        }
+        if (groupedAggregatePushed && groupAggregatePushdown) {
+            if ((query.having?.length ?? 0) > groupAggregatePushdown.pushedDownHaving) {
+                bindings = bindings.filter((binding) => this.matchesFilters(binding, query.having ?? []));
+                metrics.filtersApplied += query.having?.length ?? 0;
+                metrics.plan.push(`Having(${(query.having ?? []).map(describeFilter).join(',')})`);
+            }
+        }
+        else if (aggregates.length > 0 && (query.groupBy?.length ?? 0) > 0) {
+            const joinedRows = bindings.length;
+            bindings = this.groupAggregateBindings(bindings, query.groupBy ?? [], aggregates);
+            metrics.joinedRows = joinedRows;
+            metrics.plan.push(aggregatePlan(aggregates, true));
+            if ((query.having?.length ?? 0) > 0) {
+                bindings = bindings.filter((binding) => this.matchesFilters(binding, query.having ?? []));
+                metrics.filtersApplied += query.having?.length ?? 0;
+                metrics.plan.push(`Having(${(query.having ?? []).map(describeFilter).join(',')})`);
+            }
+        }
+        else if (aggregates.length > 0) {
+            const { binding: aggregateBinding, firstCount } = this.aggregateBindings(bindings, aggregates);
+            const having = query.having ?? [];
+            if (having.length > 0 && !this.matchesFilters(aggregateBinding, having)) {
+                metrics.joinedRows = bindings.length;
+                metrics.returnedRows = 0;
+                metrics.durationMs = Date.now() - start;
+                metrics.filtersApplied += having.length;
+                metrics.plan.push(aggregatePlan(aggregates, false));
+                metrics.plan.push(`Having(${having.map(describeFilter).join(',')})`);
+                return {
+                    bindings: [],
+                    count: firstCount,
+                    metrics,
+                };
+            }
+            metrics.joinedRows = bindings.length;
+            metrics.returnedRows = 1;
+            metrics.durationMs = Date.now() - start;
+            metrics.plan.push(aggregatePlan(aggregates, false));
+            if (having.length > 0) {
+                metrics.filtersApplied += having.length;
+                metrics.plan.push(`Having(${having.map(describeFilter).join(',')})`);
+            }
+            return {
+                bindings: [aggregateBinding],
+                count: firstCount,
+                metrics,
+            };
+        }
+        const joinedRows = metrics.joinedRows > 0
+            ? metrics.joinedRows
+            : singleScanPushdown?.paginationPushed
+                || requiredBgpPushdown?.paginationPushed
+                ? metrics.scannedRows
+                : bindings.length;
+        if (query.orderBy
+            && query.orderBy.length > 0
+            && !singleScanPushdown?.orderPushed
+            && !requiredBgpPushdown?.orderPushed
+            && !groupAggregatePushdown?.orderPushed) {
+            bindings = [...bindings].sort((left, right) => compareBindings(left, right, query.orderBy ?? []));
+            metrics.plan.push('Sort');
+        }
+        let projected = query.select && query.select.length > 0
+            ? bindings.map((binding) => projectBinding(binding, query.select ?? []))
+            : bindings;
+        if (query.distinct && !requiredBgpPushdown?.distinctPushed) {
+            projected = distinctBindings(projected);
+            metrics.plan.push('Distinct');
+        }
+        if ((query.offset !== undefined || query.limit !== undefined)
+            && !singleScanPushdown?.paginationPushed
+            && !requiredBgpPushdown?.paginationPushed
+            && !groupAggregatePushdown?.paginationPushed) {
+            const startOffset = Math.max(0, query.offset ?? 0);
+            const endOffset = query.limit === undefined
+                ? undefined
+                : startOffset + Math.max(0, query.limit);
+            projected = projected.slice(startOffset, endOffset);
+            metrics.plan.push('Limit');
+        }
+        metrics.joinedRows = joinedRows;
+        metrics.returnedRows = projected.length;
+        metrics.durationMs = Date.now() - start;
+        return {
+            bindings: projected,
+            metrics,
+        };
+    }
+    chooseRequiredSourceIndex(sources, bindings, filters, metrics) {
+        const boundVariables = this.boundVariables(bindings);
+        const hasBoundVariables = boundVariables.size > 0;
+        const sampleBinding = bindings[0] ?? {};
+        const choices = sources.map((source, index) => {
+            const sourceVariables = variablesInRequiredSource(source);
+            const connected = sourceVariables.length === 0
+                || sourceVariables.some((variableName) => boundVariables.has(variableName));
+            return {
+                index,
+                disconnectedPenalty: hasBoundVariables && !connected ? 1 : 0,
+                estimatedRows: this.estimateSourceRows(source, bindings, filters, metrics),
+                rank: this.sourceRank(source, sampleBinding),
+            };
+        });
+        choices.sort((left, right) => (left.disconnectedPenalty - right.disconnectedPenalty
+            || left.estimatedRows - right.estimatedRows
+            || left.rank - right.rank
+            || left.index - right.index));
+        return choices[0]?.index ?? 0;
+    }
+    estimatePatternRows(pattern, bindings, filters, metrics) {
+        const sample = (bindings.length > 0 ? bindings : [{}]).slice(0, PLANNER_SAMPLE_BINDINGS);
+        const fanoutEstimate = this.estimatePatternRowsByDistinctFanout(pattern, sample, filters, metrics);
+        if (fanoutEstimate !== undefined) {
+            if (bindings.length > sample.length && sample.length > 0) {
+                return Math.ceil(fanoutEstimate * (bindings.length / sample.length));
+            }
+            return fanoutEstimate;
+        }
+        const estimates = new Map();
+        for (const binding of sample) {
+            const compiled = this.compilePattern(pattern, binding, filters);
+            if (!compiled) {
+                continue;
+            }
+            metrics.cardinalityEstimates = (metrics.cardinalityEstimates ?? 0) + 1;
+            const key = compiledPatternKey(compiled);
+            if (!estimates.has(key)) {
+                estimates.set(key, this.index.estimateCardinality(compiled).rows);
+                metrics.distinctCardinalityEstimates = (metrics.distinctCardinalityEstimates ?? 0) + 1;
+            }
+        }
+        const rows = sample.reduce((sum, binding) => {
+            const compiled = this.compilePattern(pattern, binding, filters);
+            return compiled ? sum + (estimates.get(compiledPatternKey(compiled)) ?? 0) : sum;
+        }, 0);
+        if (bindings.length > sample.length && sample.length > 0) {
+            return Math.ceil(rows * (bindings.length / sample.length));
+        }
+        return rows;
+    }
+    estimatePatternRowsByDistinctFanout(pattern, sample, filters, metrics) {
+        if (sample.length < 2) {
+            return undefined;
+        }
+        const boundSlots = this.boundPatternSlots(pattern, sample);
+        if (boundSlots.length === 0) {
+            return undefined;
+        }
+        const boundVariables = new Set(boundSlots.map((slot) => slot.variable));
+        if (filters.some((filter) => boundVariables.has(filter.variable))) {
+            return undefined;
+        }
+        const generalized = this.compilePattern(pattern, {}, filters);
+        if (!generalized) {
+            return undefined;
+        }
+        const total = this.index.estimateCardinality(generalized).rows;
+        const distinct = this.index.countDistinctTuple(generalized, boundSlots.map((slot) => slot.key)).rows;
+        metrics.cardinalityEstimates = (metrics.cardinalityEstimates ?? 0) + sample.length;
+        metrics.distinctCardinalityEstimates = (metrics.distinctCardinalityEstimates ?? 0) + 2;
+        if (distinct === 0 || total === 0) {
+            return 0;
+        }
+        return Math.ceil((total / distinct) * sample.length);
+    }
+    boundPatternSlots(pattern, sample) {
+        return TERM_KEYS
+            .map((key) => ({ key, value: pattern[key] }))
+            .filter((slot) => {
+            if (!isVariable(slot.value)) {
+                return false;
+            }
+            const variableName = slot.value.variable;
+            return sample.every((binding) => Boolean(binding[variableName]));
+        })
+            .map((slot) => ({ key: slot.key, variable: slot.value.variable }));
+    }
+    estimateSourceRows(source, bindings, filters, metrics) {
+        if (source.kind === 'pattern') {
+            if (source.tupleValues) {
+                return this.estimateTuplePatternRows(source, bindings, filters, metrics);
+            }
+            return this.estimatePatternRows(source.pattern, bindings, filters, metrics);
+        }
+        if (source.kind === 'values') {
+            return source.source.rows.length * Math.max(1, bindings.length);
+        }
+        const sample = (bindings.length > 0 ? bindings : [{}]).slice(0, PLANNER_SAMPLE_BINDINGS);
+        if (!this.searchSourceHasBoundVariables(source, sample)) {
+            metrics.searchCardinalityEstimates = (metrics.searchCardinalityEstimates ?? 0) + 1;
+            const estimate = source.kind === 'text'
+                ? this.estimateTextSearchRows(source)
+                : this.estimateVectorSearchRows(source);
+            return estimate * Math.max(1, bindings.length);
+        }
+        const sourceVariable = source.pattern.source;
+        const boundSourceEstimate = sourceVariable && this.canUseBoundSourceSearch(sample, source, sourceVariable)
+            ? this.estimateSearchRowsByBoundSource(source, sample, metrics)
+            : undefined;
+        if (boundSourceEstimate !== undefined) {
+            if (bindings.length > sample.length && sample.length > 0) {
+                return Math.ceil(boundSourceEstimate * (bindings.length / sample.length));
+            }
+            return boundSourceEstimate;
+        }
+        const results = source.kind === 'text'
+            ? this.textSearchResults(source)
+            : this.vectorSearchResults(source);
+        let rows = 0;
+        for (const binding of sample) {
+            for (const result of results) {
+                const next = source.kind === 'text'
+                    ? bindTextSearchResult(binding, source.pattern, result)
+                    : bindVectorSearchResult(binding, source.pattern, result);
+                if (next) {
+                    rows++;
+                }
+            }
+        }
+        if (bindings.length > sample.length && sample.length > 0) {
+            return Math.ceil(rows * (bindings.length / sample.length));
+        }
+        return rows;
+    }
+    estimateTuplePatternRows(source, bindings, filters, metrics) {
+        const sample = (bindings.length > 0 ? bindings : [{}]).slice(0, PLANNER_SAMPLE_BINDINGS);
+        const estimates = new Map();
+        let rows = 0;
+        for (const binding of sample) {
+            for (const row of source.tupleValues?.rows ?? []) {
+                const tupleBinding = mergeTupleValuesBinding(binding, source.tupleValues?.variables ?? [], row);
+                if (!tupleBinding) {
+                    continue;
+                }
+                const compiled = this.compilePattern(source.pattern, tupleBinding, filters);
+                if (!compiled) {
+                    continue;
+                }
+                metrics.cardinalityEstimates = (metrics.cardinalityEstimates ?? 0) + 1;
+                const key = compiledPatternKey(compiled);
+                if (!estimates.has(key)) {
+                    estimates.set(key, this.index.estimateCardinality(compiled).rows);
+                    metrics.distinctCardinalityEstimates = (metrics.distinctCardinalityEstimates ?? 0) + 1;
+                }
+                rows += estimates.get(key) ?? 0;
+            }
+        }
+        if (bindings.length > sample.length && sample.length > 0) {
+            return Math.ceil(rows * (bindings.length / sample.length));
+        }
+        return rows;
+    }
+    searchSourceHasBoundVariables(source, sample) {
+        const variables = variablesInRequiredSource(source);
+        return variables.some((variableName) => sample.some((binding) => Boolean(binding[variableName])));
+    }
+    estimateSearchRowsByBoundSource(source, sample, metrics) {
+        const sourceVariable = source.pattern.source;
+        if (!sourceVariable) {
+            return undefined;
+        }
+        const estimates = new Map();
+        let rows = 0;
+        let sawBoundSource = false;
+        for (const binding of sample) {
+            const term = binding[sourceVariable];
+            if (!term) {
+                return undefined;
+            }
+            sawBoundSource = true;
+            if (term.termType !== 'NamedNode') {
+                continue;
+            }
+            if (!estimates.has(term.value)) {
+                metrics.searchCardinalityEstimates = (metrics.searchCardinalityEstimates ?? 0) + 1;
+                estimates.set(term.value, source.kind === 'text'
+                    ? this.estimateTextSearchRows(source, term.value)
+                    : this.estimateVectorSearchRows(source, term.value));
+            }
+            rows += estimates.get(term.value) ?? 0;
+        }
+        return sawBoundSource ? rows : undefined;
+    }
+    estimateTextSearchRows(source, exactSource) {
+        if (!this.textIndex) {
+            throw new Error('RdfLocalQuery textSearch requires a configured RdfTextIndex');
+        }
+        const options = this.textSearchOptions(source.pattern, exactSource);
+        return options ? this.textIndex.estimateSearchCardinality(options).rows : 0;
+    }
+    estimateVectorSearchRows(source, exactSource) {
+        if (!this.vectorIndex) {
+            throw new Error('RdfLocalQuery vectorSearch requires a configured RdfVectorIndex');
+        }
+        const options = this.vectorSearchOptions(source.pattern, exactSource);
+        return options ? this.vectorIndex.estimateSearchCardinality(options).rows : 0;
+    }
+    boundVariables(bindings) {
+        const names = new Set();
+        for (const binding of bindings.slice(0, PLANNER_SAMPLE_BINDINGS)) {
+            for (const name of Object.keys(binding)) {
+                names.add(name);
+            }
+        }
+        return names;
+    }
+    patternRank(pattern, binding) {
+        let rank = 0;
+        for (const key of TERM_KEYS) {
+            const value = pattern[key];
+            if (!value)
+                continue;
+            if (isVariable(value)) {
+                if (binding[value.variable]) {
+                    rank += key === 'graph' ? 0 : 1;
+                }
+                else {
+                    rank += 8;
+                }
+            }
+            else {
+                rank += key === 'graph' ? 0 : 1;
+            }
+        }
+        return rank;
+    }
+    sourceRank(source, binding) {
+        if (source.kind === 'pattern') {
+            return this.patternRank(source.pattern, binding);
+        }
+        if (source.kind === 'values') {
+            return 0;
+        }
+        const variables = variablesInRequiredSource(source);
+        if (variables.some((variableName) => binding[variableName])) {
+            return 0;
+        }
+        return source.kind === 'text' ? 4 : 5;
+    }
+    joinRequiredSource(input, source, filters, metrics, singleScanPushdown) {
+        switch (source.kind) {
+            case 'pattern': {
+                const bindings = this.joinPattern(input, source, filters, metrics, false, singleScanPushdown?.options);
+                metrics.plan.push(`IndexScan(${describePattern(source.pattern)})`);
+                if (singleScanPushdown?.orderPushed) {
+                    metrics.plan.push(`IndexOrder(${describeScanOrder(singleScanPushdown.options)})`);
+                }
+                if (singleScanPushdown?.paginationPushed) {
+                    metrics.plan.push('IndexLimit');
+                }
+                return bindings;
+            }
+            case 'text': {
+                const bindings = this.joinTextSearch(input, source, metrics);
+                metrics.plan.push(`TextSearch(${describeTextSearch(source.pattern)})`);
+                return bindings;
+            }
+            case 'vector': {
+                const bindings = this.joinVectorSearch(input, source, metrics);
+                metrics.plan.push(`VectorSearch(${describeVectorSearch(source.pattern)})`);
+                return bindings;
+            }
+            case 'values': {
+                const bindings = joinValuesSource(input, source.source);
+                metrics.scannedRows += source.source.rows.length;
+                metrics.plan.push(`Values(${source.source.variables.map((variableName) => `?${variableName}`).join(',')})`);
+                return bindings;
+            }
+            default: {
+                const exhaustive = source;
+                throw new Error(`Unsupported RDF required source: ${JSON.stringify(exhaustive)}`);
+            }
+        }
+    }
+    joinOptionalGroup(input, optionalGroup, metrics) {
+        const optionalFilters = optionalGroup.filters ?? [];
+        if (optionalFilters.length > 0) {
+            metrics.plan.push(`OptionalFilter(${optionalFilters.map(describeFilter).join(',')})`);
+        }
+        return input.flatMap((binding) => {
+            let matches = [binding];
+            for (const source of optionalGroup.values ?? []) {
+                matches = joinValuesSource(matches, source);
+                metrics.scannedRows += source.rows.length;
+                metrics.plan.push(`OptionalValues(${source.variables.map((variableName) => `?${variableName}`).join(',')})`);
+                if (matches.length === 0) {
+                    return [binding];
+                }
+            }
+            for (const pattern of optionalGroup.patterns) {
+                matches = this.joinPattern(matches, { kind: 'pattern', pattern, originalIndex: -1 }, optionalFilters, metrics, true);
+                if (matches.length === 0) {
+                    return [binding];
+                }
+            }
+            for (const unionGroup of optionalGroup.unions ?? []) {
+                matches = this.joinUnionGroup(matches, unionGroup.branches, optionalFilters, metrics);
+                metrics.plan.push(`OptionalUnion(${unionGroup.branches.map((branch) => branch.patterns.map(describePattern).join(',')).join('|')})`);
+                if (matches.length === 0) {
+                    return [binding];
+                }
+            }
+            for (const rawNestedOptionalGroup of optionalGroup.optional ?? []) {
+                const nestedOptionalGroup = normalizeOptionalGroup(rawNestedOptionalGroup);
+                matches = this.joinOptionalGroup(matches, nestedOptionalGroup, metrics);
+                metrics.plan.push(`OptionalNestedJoin(${nestedOptionalGroup.patterns.map(describePattern).join(',')})`);
+                if (matches.length === 0) {
+                    return [binding];
+                }
+            }
+            for (const minusGroup of optionalGroup.minus ?? []) {
+                matches = this.applyMinusGroup(matches, minusGroup, metrics);
+                metrics.plan.push(`OptionalMinus(${minusGroup.patterns.map(describePattern).join(',')})`);
+                if (matches.length === 0) {
+                    return [binding];
+                }
+            }
+            for (const existsGroup of optionalGroup.exists ?? []) {
+                matches = this.applyExistsGroup(matches, existsGroup, metrics);
+                metrics.plan.push(`OptionalExists(${existsGroup.patterns.map(describePattern).join(',')})`);
+                if (matches.length === 0) {
+                    return [binding];
+                }
+            }
+            if ((optionalGroup.binds?.length ?? 0) > 0) {
+                matches = this.applyBinds(matches, optionalGroup.binds ?? []);
+                metrics.plan.push(`OptionalBind(${(optionalGroup.binds ?? []).map(describeBind).join(',')})`);
+            }
+            if (optionalFilters.length > 0) {
+                matches = matches.filter((match) => this.matchesFilters(match, optionalFilters));
+                metrics.filtersApplied += optionalFilters.length;
+                if (matches.length === 0) {
+                    return [binding];
+                }
+            }
+            return matches;
+        });
+    }
+    joinUnionGroup(input, branches, outerFilters, metrics) {
+        const output = [];
+        for (const binding of input) {
+            for (const branch of branches) {
+                let matches = [binding];
+                const branchFilters = [...outerFilters, ...(branch.filters ?? [])];
+                for (const source of branch.values ?? []) {
+                    matches = joinValuesSource(matches, source);
+                    metrics.scannedRows += source.rows.length;
+                    metrics.plan.push(`UnionValues(${source.variables.map((variableName) => `?${variableName}`).join(',')})`);
+                    if (matches.length === 0) {
+                        break;
+                    }
+                }
+                if (matches.length === 0) {
+                    continue;
+                }
+                for (const pattern of branch.patterns) {
+                    matches = this.joinPattern(matches, { kind: 'pattern', pattern, originalIndex: -1 }, branchFilters, metrics, false);
+                    if (matches.length === 0) {
+                        break;
+                    }
+                }
+                if (matches.length === 0) {
+                    continue;
+                }
+                if ((branch.binds?.length ?? 0) > 0) {
+                    matches = this.applyBinds(matches, branch.binds ?? []);
+                    metrics.plan.push(`UnionBind(${(branch.binds ?? []).map(describeBind).join(',')})`);
+                }
+                if (matches.length === 0) {
+                    continue;
+                }
+                for (const rawOptionalGroup of branch.optional ?? []) {
+                    const optionalGroup = normalizeOptionalGroup(rawOptionalGroup);
+                    matches = this.joinOptionalGroup(matches, optionalGroup, metrics);
+                    metrics.plan.push(`UnionOptionalJoin(${optionalGroup.patterns.map(describePattern).join(',')})`);
+                    if (matches.length === 0) {
+                        break;
+                    }
+                }
+                if (matches.length === 0) {
+                    continue;
+                }
+                if (branch.filters?.length) {
+                    matches = matches.filter((match) => this.matchesFilters(match, branch.filters ?? []));
+                    metrics.filtersApplied += branch.filters.length;
+                    metrics.plan.push(`UnionFilter(${branch.filters.map(describeFilter).join(',')})`);
+                }
+                output.push(...matches);
+            }
+        }
+        return output;
+    }
+    applyDependentValues(input, sources, metrics, label) {
+        let matches = input;
+        for (const source of sources ?? []) {
+            matches = joinValuesSource(matches, source);
+            metrics.scannedRows += source.rows.length;
+            metrics.plan.push(`${label}Values(${source.variables.map((variableName) => `?${variableName}`).join(',')})`);
+            if (matches.length === 0) {
+                break;
+            }
+        }
+        return matches;
+    }
+    applyMinusGroup(input, minusGroup, metrics) {
+        const filters = minusGroup.filters ?? [];
+        const output = [];
+        for (const binding of input) {
+            let matches = [binding];
+            matches = this.applyDependentValues(matches, minusGroup.values, metrics, 'Minus');
+            for (const pattern of minusGroup.patterns) {
+                matches = this.joinPattern(matches, { kind: 'pattern', pattern, originalIndex: -1 }, filters, metrics, false);
+                if (matches.length === 0) {
+                    break;
+                }
+            }
+            if (matches.length > 0) {
+                for (const unionGroup of minusGroup.unions ?? []) {
+                    matches = this.joinUnionGroup(matches, unionGroup.branches, filters, metrics);
+                    metrics.plan.push(`MinusUnion(${unionGroup.branches.map((branch) => branch.patterns.map(describePattern).join(',')).join('|')})`);
+                    if (matches.length === 0) {
+                        break;
+                    }
+                }
+            }
+            for (const rawOptionalGroup of minusGroup.optional ?? []) {
+                const optionalGroup = normalizeOptionalGroup(rawOptionalGroup);
+                matches = this.joinOptionalGroup(matches, optionalGroup, metrics);
+                metrics.plan.push(`MinusOptionalJoin(${optionalGroup.patterns.map(describePattern).join(',')})`);
+            }
+            if ((minusGroup.binds?.length ?? 0) > 0) {
+                matches = this.applyBinds(matches, minusGroup.binds ?? []);
+                metrics.plan.push(`MinusBind(${(minusGroup.binds ?? []).map(describeBind).join(',')})`);
+            }
+            if (filters.length > 0) {
+                matches = matches.filter((match) => this.matchesFilters(match, filters));
+                metrics.filtersApplied += filters.length;
+                metrics.plan.push(`MinusFilter(${filters.map(describeFilter).join(',')})`);
+            }
+            if (matches.length === 0) {
+                output.push(binding);
+            }
+        }
+        return output;
+    }
+    applyExistsGroup(input, existsGroup, metrics) {
+        const filters = existsGroup.filters ?? [];
+        const output = [];
+        for (const binding of input) {
+            let matches = [binding];
+            matches = this.applyDependentValues(matches, existsGroup.values, metrics, 'Exists');
+            for (const pattern of existsGroup.patterns) {
+                matches = this.joinPattern(matches, { kind: 'pattern', pattern, originalIndex: -1 }, filters, metrics, false);
+                if (matches.length === 0) {
+                    break;
+                }
+            }
+            if (matches.length > 0) {
+                for (const unionGroup of existsGroup.unions ?? []) {
+                    matches = this.joinUnionGroup(matches, unionGroup.branches, filters, metrics);
+                    metrics.plan.push(`ExistsUnion(${unionGroup.branches.map((branch) => branch.patterns.map(describePattern).join(',')).join('|')})`);
+                    if (matches.length === 0) {
+                        break;
+                    }
+                }
+            }
+            for (const rawOptionalGroup of existsGroup.optional ?? []) {
+                const optionalGroup = normalizeOptionalGroup(rawOptionalGroup);
+                matches = this.joinOptionalGroup(matches, optionalGroup, metrics);
+                metrics.plan.push(`ExistsOptionalJoin(${optionalGroup.patterns.map(describePattern).join(',')})`);
+            }
+            if ((existsGroup.binds?.length ?? 0) > 0) {
+                matches = this.applyBinds(matches, existsGroup.binds ?? []);
+                metrics.plan.push(`ExistsBind(${(existsGroup.binds ?? []).map(describeBind).join(',')})`);
+            }
+            if (filters.length > 0) {
+                matches = matches.filter((match) => this.matchesFilters(match, filters));
+                metrics.filtersApplied += filters.length;
+                metrics.plan.push(`ExistsFilter(${filters.map(describeFilter).join(',')})`);
+            }
+            if (matches.length > 0) {
+                output.push(binding);
+            }
+        }
+        return output;
+    }
+    joinPattern(input, source, filters, metrics, optional, scanOptions) {
+        const output = [];
+        const { pattern } = source;
+        for (const binding of input) {
+            const compiled = this.compilePattern(pattern, binding, filters);
+            if (!compiled) {
+                if (optional) {
+                    output.push(binding);
+                }
+                continue;
+            }
+            const tupleValues = this.tupleValuesForBinding(source, binding);
+            const scan = tupleValues
+                ? this.index.scanWithTupleConstraints(compiled, tupleValues, scanOptions)
+                : this.index.scan(compiled, scanOptions);
+            metrics.scannedRows += scan.metrics.matchedRows;
+            metrics.indexChoices.push(scan.metrics.indexChoice);
+            metrics.filtersPushedDown += compiled.pushedDownFilters;
+            metrics.plan.push(...storagePlanMarkers(scan.metrics.queryPlan));
+            for (const quad of scan.quads) {
+                const next = this.bindQuad(pattern, binding, quad);
+                const remainingFilters = filtersWithoutIndexes(filters, compiled.pushedDownFilterIndexes);
+                if (next && this.matchesNewlyBoundFilters(next, binding, remainingFilters)) {
+                    output.push(next);
+                }
+            }
+        }
+        return output;
+    }
+    requiredBgpPushdown(query, requiredPatterns, filters) {
+        if (requiredPatterns.length < 1
+            || (query.values?.length ?? 0) > 0
+            || (query.textSearch?.length ?? 0) > 0
+            || (query.vectorSearch?.length ?? 0) > 0
+            || (query.unions?.length ?? 0) > 0
+            || (query.minus?.length ?? 0) > 0
+            || (query.exists?.length ?? 0) > 0
+            || (query.optional?.length ?? 0) > 0
+            || (query.binds?.length ?? 0) > 0
+            || queryAggregates(query).length > 0) {
+            return undefined;
+        }
+        if (requiredPatterns.length === 1 && !query.distinct) {
+            return undefined;
+        }
+        if (!this.canPushRequiredBgpFilters(requiredPatterns, filters)) {
+            return undefined;
+        }
+        const distinctProject = query.distinct
+            ? this.requiredBgpDistinctProject(query, requiredPatterns, filters)
+            : undefined;
+        if (query.distinct && !distinctProject) {
+            return undefined;
+        }
+        const orderPushed = (query.orderBy?.length ?? 0) > 0;
+        if (orderPushed && !this.canPushRequiredBgpOrder(requiredPatterns, query.orderBy ?? [])) {
+            return undefined;
+        }
+        const sharedVariables = variablesSharedAcrossPatterns(requiredPatterns);
+        if (requiredPatterns.length > 1 && sharedVariables.size === 0) {
+            return undefined;
+        }
+        const compiled = requiredPatterns.map((pattern) => this.compileJoinPattern(pattern, filters));
+        if (compiled.some((entry) => !entry)) {
+            return undefined;
+        }
+        const reordered = this.reorderJoinPatterns(requiredPatterns, compiled, filters);
+        return {
+            patterns: reordered.patterns,
+            ...(reordered.reorderPlan ? { reorderPlan: reordered.reorderPlan } : {}),
+            orderPushed,
+            paginationPushed: query.limit !== undefined || query.offset !== undefined,
+            distinctPushed: Boolean(distinctProject),
+            ...(distinctProject ? { project: distinctProject } : {}),
+            pushedDownFilters: filters.length,
+        };
+    }
+    requiredBgpDistinctProject(query, requiredPatterns, filters) {
+        const visibleVariables = new Set(requiredPatterns.flatMap((pattern) => variablesInPattern(pattern)));
+        const projectedVariables = uniqueStrings(query.select && query.select.length > 0
+            ? query.select
+            : [...visibleVariables]);
+        if (projectedVariables.some((variableName) => !visibleVariables.has(variableName))) {
+            return undefined;
+        }
+        const requiredForRecheck = new Set(filters.flatMap((filter) => filterVariables(filter)));
+        for (const order of query.orderBy ?? []) {
+            requiredForRecheck.add(order.variable);
+        }
+        if ([...requiredForRecheck].some((variableName) => !projectedVariables.includes(variableName))) {
+            return undefined;
+        }
+        return projectedVariables;
+    }
+    canPushRequiredBgpFilters(requiredPatterns, filters) {
+        const variables = new Set(requiredPatterns.flatMap((pattern) => variablesInPattern(pattern)));
+        return filters.every((filter) => (!filter.variable2
+            && variables.has(filter.variable)
+            && isPushdownFilter(filter)
+            && this.compilePushdownFilter(filter.variable, [filter]) !== null));
+    }
+    canPushRequiredBgpOrder(requiredPatterns, orderBy) {
+        if (orderBy.length === 0) {
+            return true;
+        }
+        const variables = new Set(requiredPatterns.flatMap((pattern) => variablesInPattern(pattern)));
+        return orderBy.every((entry) => variables.has(entry.variable));
+    }
+    reorderJoinPatterns(requiredPatterns, compiledPatterns, filters) {
+        if (compiledPatterns.length < 2) {
+            return { patterns: compiledPatterns };
+        }
+        const candidates = requiredPatterns.map((pattern, index) => {
+            const compiled = this.compilePattern(pattern, {}, filters);
+            return {
+                index,
+                variables: new Set(variablesInPattern(pattern)),
+                estimatedRows: compiled ? this.index.estimateCardinality(compiled).rows : Number.MAX_SAFE_INTEGER,
+            };
+        });
+        const remaining = [...candidates];
+        const selected = [];
+        const selectedVariables = new Set();
+        while (remaining.length > 0) {
+            const hasSelectedVariables = selectedVariables.size > 0;
+            remaining.sort((left, right) => {
+                const leftConnected = !hasSelectedVariables || hasSharedVariable(left.variables, selectedVariables);
+                const rightConnected = !hasSelectedVariables || hasSharedVariable(right.variables, selectedVariables);
+                return Number(rightConnected) - Number(leftConnected)
+                    || left.estimatedRows - right.estimatedRows
+                    || left.index - right.index;
+            });
+            const [next] = remaining.splice(0, 1);
+            selected.push(next);
+            for (const variableName of next.variables) {
+                selectedVariables.add(variableName);
+            }
+        }
+        const order = selected.map((entry) => entry.index);
+        if (order.every((index, position) => index === position)) {
+            return { patterns: compiledPatterns };
+        }
+        return {
+            patterns: order.map((index) => compiledPatterns[index]),
+            reorderPlan: `JoinReorder(${order.join('>')})`,
+        };
+    }
+    compileJoinPattern(pattern, filters) {
+        const variables = {};
+        for (const key of TERM_KEYS) {
+            const value = pattern[key];
+            if (isVariable(value)) {
+                variables[key] = value.variable;
+            }
+        }
+        const compiled = this.compilePattern(pattern, {}, filters);
+        return compiled ? { pattern: compiled, variables } : undefined;
+    }
+    canUseRdf3xPrimaryJoin(patterns) {
+        return Boolean(this.rdf3xPrimaryIndex)
+            && patterns.length > 0
+            && patterns.every((entry) => isRdf3xCompatiblePattern(entry.pattern));
+    }
+    tupleValuesForBinding(source, binding) {
+        if (!source.tupleValues) {
+            return undefined;
+        }
+        const rows = source.tupleValues.rows.filter((row) => (source.tupleValues?.variables.every((variableName) => {
+            const existing = binding[variableName];
+            const value = row[variableName];
+            return !existing || !value || sameTerm(existing, value);
+        })));
+        return tupleConstraintSourceForPattern({ ...source.tupleValues, rows }, source.pattern);
+    }
+    joinTextSearch(input, source, metrics) {
+        metrics.indexChoices.push('text-chunk');
+        const sourceVariable = source.pattern.source;
+        if (sourceVariable && this.canUseBoundSourceSearch(input, source, sourceVariable)) {
+            return this.joinTextSearchByBoundSource(input, source, sourceVariable, metrics);
+        }
+        const results = this.textSearchResults(source);
+        metrics.scannedRows += results.length;
+        const output = [];
+        for (const binding of input) {
+            for (const result of results) {
+                const next = bindTextSearchResult(binding, source.pattern, result);
+                if (next) {
+                    output.push(next);
+                }
+            }
+        }
+        return output;
+    }
+    joinVectorSearch(input, source, metrics) {
+        metrics.indexChoices.push('vector-chunk');
+        const sourceVariable = source.pattern.source;
+        if (sourceVariable && this.canUseBoundSourceSearch(input, source, sourceVariable)) {
+            return this.joinVectorSearchByBoundSource(input, source, sourceVariable, metrics);
+        }
+        const results = this.vectorSearchResults(source);
+        metrics.scannedRows += results.length;
+        const output = [];
+        for (const binding of input) {
+            for (const result of results) {
+                const next = bindVectorSearchResult(binding, source.pattern, result);
+                if (next) {
+                    output.push(next);
+                }
+            }
+        }
+        return output;
+    }
+    joinTextSearchByBoundSource(input, source, sourceVariable, metrics) {
+        const cache = new Map();
+        const countedSources = new Set();
+        let globalResults;
+        let countedGlobal = false;
+        const output = [];
+        for (const binding of input) {
+            const term = binding[sourceVariable];
+            let results;
+            if (!term) {
+                globalResults ??= this.textSearchResults(source);
+                results = globalResults;
+                if (!countedGlobal) {
+                    metrics.scannedRows += results.length;
+                    countedGlobal = true;
+                }
+            }
+            else if (term.termType !== 'NamedNode') {
+                continue;
+            }
+            else {
+                if (!cache.has(term.value)) {
+                    cache.set(term.value, this.textSearchResults(source, term.value));
+                }
+                results = cache.get(term.value) ?? [];
+                if (!countedSources.has(term.value)) {
+                    metrics.scannedRows += results.length;
+                    countedSources.add(term.value);
+                }
+            }
+            for (const result of results) {
+                const next = bindTextSearchResult(binding, source.pattern, result);
+                if (next) {
+                    output.push(next);
+                }
+            }
+        }
+        return output;
+    }
+    joinVectorSearchByBoundSource(input, source, sourceVariable, metrics) {
+        const cache = new Map();
+        const countedSources = new Set();
+        let globalResults;
+        let countedGlobal = false;
+        const output = [];
+        for (const binding of input) {
+            const term = binding[sourceVariable];
+            let results;
+            if (!term) {
+                globalResults ??= this.vectorSearchResults(source);
+                results = globalResults;
+                if (!countedGlobal) {
+                    metrics.scannedRows += results.length;
+                    countedGlobal = true;
+                }
+            }
+            else if (term.termType !== 'NamedNode') {
+                continue;
+            }
+            else {
+                if (!cache.has(term.value)) {
+                    cache.set(term.value, this.vectorSearchResults(source, term.value));
+                }
+                results = cache.get(term.value) ?? [];
+                if (!countedSources.has(term.value)) {
+                    metrics.scannedRows += results.length;
+                    countedSources.add(term.value);
+                }
+            }
+            for (const result of results) {
+                const next = bindVectorSearchResult(binding, source.pattern, result);
+                if (next) {
+                    output.push(next);
+                }
+            }
+        }
+        return output;
+    }
+    canUseBoundSourceSearch(input, source, sourceVariable) {
+        if (hasSearchWindow(source)) {
+            return false;
+        }
+        const boundSources = new Set();
+        let sawBound = false;
+        for (const binding of input) {
+            const term = binding[sourceVariable];
+            if (!term) {
+                continue;
+            }
+            sawBound = true;
+            if (term.termType !== 'NamedNode') {
+                continue;
+            }
+            boundSources.add(term.value);
+        }
+        return sawBound && boundSources.size > 0;
+    }
+    textSearchResults(source, exactSource) {
+        if (exactSource === undefined && source.results) {
+            return source.results;
+        }
+        if (!this.textIndex) {
+            throw new Error('RdfLocalQuery textSearch requires a configured RdfTextIndex');
+        }
+        const options = this.textSearchOptions(source.pattern, exactSource);
+        const results = options ? this.textIndex.search(options) : [];
+        if (exactSource === undefined) {
+            source.results = results;
+        }
+        return results;
+    }
+    vectorSearchResults(source, exactSource) {
+        if (exactSource === undefined && source.results) {
+            return source.results;
+        }
+        if (!this.vectorIndex) {
+            throw new Error('RdfLocalQuery vectorSearch requires a configured RdfVectorIndex');
+        }
+        const options = this.vectorSearchOptions(source.pattern, exactSource);
+        const results = options ? this.vectorIndex.search(options) : [];
+        if (exactSource === undefined) {
+            source.results = results;
+        }
+        return results;
+    }
+    textSearchOptions(pattern, exactSource) {
+        return {
+            query: pattern.query,
+            source: exactSource,
+            workspace: pattern.scope?.workspace,
+            sourcePrefix: pattern.scope?.sourcePrefix,
+            limit: pattern.limit,
+            offset: pattern.offset,
+            orderBy: pattern.orderBy,
+        };
+    }
+    vectorSearchOptions(pattern, exactSource) {
+        return {
+            embedding: pattern.embedding,
+            metric: pattern.metric,
+            model: pattern.vectorModel,
+            source: exactSource,
+            workspace: pattern.scope?.workspace,
+            sourcePrefix: pattern.scope?.sourcePrefix,
+            limit: pattern.limit,
+            offset: pattern.offset,
+            threshold: pattern.threshold,
+            orderBy: pattern.orderBy,
+        };
+    }
+    applyBinds(input, binds) {
+        let output = input;
+        for (const bind of binds) {
+            output = output.flatMap((binding) => {
+                if (binding[bind.variable]) {
+                    return [];
+                }
+                const value = this.evaluateBindExpression(bind.expression, binding);
+                return value ? [{ ...binding, [bind.variable]: value }] : [binding];
+            });
+        }
+        return output;
+    }
+    evaluateBindExpression(expression, binding) {
+        switch (expression.type) {
+            case 'term':
+                return expression.term;
+            case 'variable':
+                return binding[expression.variable];
+            case 'stringValue': {
+                const value = binding[expression.variable];
+                return value ? n3_1.DataFactory.literal(value.value) : undefined;
+            }
+            case 'stringLength': {
+                const value = binding[expression.variable];
+                return value ? countLiteral(value.value.length) : undefined;
+            }
+            case 'lowerCase': {
+                const value = this.evaluateBindExpression(expression.expression, binding);
+                return value ? n3_1.DataFactory.literal(value.value.toLocaleLowerCase('en-US')) : undefined;
+            }
+            case 'upperCase': {
+                const value = this.evaluateBindExpression(expression.expression, binding);
+                return value ? n3_1.DataFactory.literal(value.value.toLocaleUpperCase('en-US')) : undefined;
+            }
+            case 'substring': {
+                const value = this.evaluateBindExpression(expression.expression, binding);
+                const startTerm = this.evaluateBindExpression(expression.start, binding);
+                const startValue = startTerm ? finiteBindNumber(startTerm) : undefined;
+                const lengthTerm = expression.length ? this.evaluateBindExpression(expression.length, binding) : undefined;
+                const lengthValue = lengthTerm ? finiteBindNumber(lengthTerm) : undefined;
+                if (!value || startValue === undefined || (expression.length && lengthValue === undefined)) {
+                    return undefined;
+                }
+                const start = Math.max(0, Math.round(startValue) - 1);
+                const length = lengthValue === undefined ? undefined : Math.max(0, Math.round(lengthValue));
+                return n3_1.DataFactory.literal(value.value.slice(start, length === undefined ? undefined : start + length));
+            }
+            case 'concat': {
+                const values = expression.expressions.map((item) => this.evaluateBindExpression(item, binding));
+                return values.every((value) => Boolean(value))
+                    ? n3_1.DataFactory.literal(values.map((value) => value.value).join(''))
+                    : undefined;
+            }
+            case 'iri': {
+                const value = this.evaluateBindExpression(expression.expression, binding);
+                if (!value) {
+                    return undefined;
+                }
+                try {
+                    return n3_1.DataFactory.namedNode(new URL(value.value, expression.base).href);
+                }
+                catch {
+                    return undefined;
+                }
+            }
+            default: {
+                const exhaustive = expression;
+                throw new Error(`Unsupported RDF local BIND expression: ${JSON.stringify(exhaustive)}`);
+            }
+        }
+    }
+    singleScanPushdown(query, requiredPatterns, filters) {
+        if (requiredPatterns.length !== 1
+            || (query.values?.length ?? 0) > 0
+            || (query.textSearch?.length ?? 0) > 0
+            || (query.vectorSearch?.length ?? 0) > 0
+            || (query.unions?.length ?? 0) > 0
+            || (query.minus?.length ?? 0) > 0
+            || (query.exists?.length ?? 0) > 0
+            || (query.optional?.length ?? 0) > 0
+            || queryAggregates(query).length > 0) {
+            return undefined;
+        }
+        const pattern = requiredPatterns[0];
+        const order = this.scanOrderForPattern(pattern, query.orderBy ?? []);
+        const orderRequested = (query.orderBy?.length ?? 0) > 0;
+        const orderPushed = Boolean(order);
+        const paginationRequested = query.limit !== undefined || query.offset !== undefined;
+        const paginationPushed = paginationRequested
+            && !query.distinct
+            && (!orderRequested || orderPushed)
+            && !patternHasRepeatedVariables(pattern)
+            && this.canPushAllFiltersForPattern(pattern, filters);
+        if (!orderPushed && !paginationPushed) {
+            return undefined;
+        }
+        return {
+            options: {
+                ...(order ?? {}),
+                ...(paginationPushed && query.limit !== undefined ? { limit: Math.max(0, query.limit) } : {}),
+                ...(paginationPushed && query.offset !== undefined ? { offset: Math.max(0, query.offset) } : {}),
+            },
+            orderPushed,
+            paginationPushed,
+        };
+    }
+    countPushdown(query, requiredPatterns, filters) {
+        const aggregates = queryAggregates(query);
+        if (aggregates.length !== 1
+            || aggregates[0].type !== 'count'
+            || (query.having?.length ?? 0) > 0
+            || requiredPatterns.length !== 1
+            || (query.values?.length ?? 0) > 0
+            || (query.textSearch?.length ?? 0) > 0
+            || (query.vectorSearch?.length ?? 0) > 0
+            || (query.unions?.length ?? 0) > 0
+            || (query.minus?.length ?? 0) > 0
+            || (query.exists?.length ?? 0) > 0
+            || (query.optional?.length ?? 0) > 0
+            || (query.groupBy?.length ?? 0) > 0
+            || query.orderBy?.length
+            || query.limit !== undefined
+            || query.offset !== undefined) {
+            return undefined;
+        }
+        const pattern = requiredPatterns[0];
+        if (patternHasRepeatedVariables(pattern)) {
+            return undefined;
+        }
+        const aggregate = aggregates[0];
+        if (aggregate.variable && !variablesInPattern(pattern).includes(aggregate.variable)) {
+            return undefined;
+        }
+        const distinctKey = aggregate.distinct
+            ? this.distinctCountKey(pattern, aggregate.variable)
+            : undefined;
+        if (aggregate.distinct && !distinctKey) {
+            return undefined;
+        }
+        if (!this.canPushAllFiltersForPattern(pattern, filters)) {
+            return undefined;
+        }
+        const compiled = this.compilePattern(pattern, {}, filters);
+        return compiled
+            ? {
+                as: aggregate.as,
+                pattern: compiled,
+                distinctKey,
+                pushedDownFilters: compiled.pushedDownFilters,
+            }
+            : undefined;
+    }
+    joinCountPushdown(query, requiredPatterns, filters, aggregates) {
+        if (aggregates.length === 0
+            || requiredPatterns.length < 2
+            || (query.having?.length ?? 0) > 0
+            || (query.groupBy?.length ?? 0) > 0
+            || (query.values?.length ?? 0) > 0
+            || (query.textSearch?.length ?? 0) > 0
+            || (query.vectorSearch?.length ?? 0) > 0
+            || (query.unions?.length ?? 0) > 0
+            || (query.minus?.length ?? 0) > 0
+            || (query.exists?.length ?? 0) > 0
+            || (query.optional?.length ?? 0) > 0
+            || (query.binds?.length ?? 0) > 0
+            || query.orderBy?.length
+            || query.limit !== undefined
+            || query.offset !== undefined
+            || query.distinct) {
+            return undefined;
+        }
+        if (aggregates.some((aggregate) => aggregate.type !== 'count')) {
+            return undefined;
+        }
+        if (!this.canPushRequiredBgpFilters(requiredPatterns, filters)) {
+            return undefined;
+        }
+        const visibleVariables = new Set(requiredPatterns.flatMap((pattern) => variablesInPattern(pattern)));
+        if (aggregates.some((aggregate) => aggregate.variable && !visibleVariables.has(aggregate.variable))) {
+            return undefined;
+        }
+        const sharedVariables = variablesSharedAcrossPatterns(requiredPatterns);
+        if (sharedVariables.size === 0) {
+            return undefined;
+        }
+        const compiled = requiredPatterns.map((pattern) => this.compileJoinPattern(pattern, filters));
+        if (compiled.some((entry) => !entry)) {
+            return undefined;
+        }
+        const reordered = this.reorderJoinPatterns(requiredPatterns, compiled, filters);
+        return {
+            patterns: reordered.patterns,
+            ...(reordered.reorderPlan ? { reorderPlan: reordered.reorderPlan } : {}),
+            pushedDownFilters: filters.length,
+        };
+    }
+    joinBasicAggregatePushdown(query, requiredPatterns, filters, aggregates) {
+        if (aggregates.length === 0
+            || !aggregates.some((aggregate) => aggregate.type !== 'count')
+            || requiredPatterns.length === 0
+            || (query.having?.length ?? 0) > 0
+            || (query.groupBy?.length ?? 0) > 0
+            || (query.values?.length ?? 0) > 0
+            || (query.textSearch?.length ?? 0) > 0
+            || (query.vectorSearch?.length ?? 0) > 0
+            || (query.unions?.length ?? 0) > 0
+            || (query.minus?.length ?? 0) > 0
+            || (query.exists?.length ?? 0) > 0
+            || (query.optional?.length ?? 0) > 0
+            || (query.binds?.length ?? 0) > 0
+            || query.orderBy?.length
+            || query.limit !== undefined
+            || query.offset !== undefined
+            || query.distinct) {
+            return undefined;
+        }
+        if (aggregates.some((aggregate) => aggregate.distinct || aggregate.type !== 'count' && !aggregate.variable)) {
+            return undefined;
+        }
+        const visibleVariables = new Set(requiredPatterns.flatMap((pattern) => variablesInPattern(pattern)));
+        if (aggregates.some((aggregate) => aggregate.variable && !visibleVariables.has(aggregate.variable))) {
+            return undefined;
+        }
+        const numericAggregateVariables = new Set(aggregates
+            .filter((aggregate) => aggregate.type !== 'count')
+            .map((aggregate) => aggregate.variable)
+            .filter((variableName) => Boolean(variableName)));
+        if (!this.canPushAggregateFilters(requiredPatterns, filters, numericAggregateVariables)) {
+            return undefined;
+        }
+        const sharedVariables = variablesSharedAcrossPatterns(requiredPatterns);
+        if (requiredPatterns.length > 1 && sharedVariables.size === 0) {
+            return undefined;
+        }
+        const compiled = requiredPatterns.map((pattern) => this.compileJoinPattern(pattern, filters));
+        if (compiled.some((entry) => !entry)) {
+            return undefined;
+        }
+        const reordered = this.reorderJoinPatterns(requiredPatterns, compiled, filters);
+        return {
+            patterns: reordered.patterns,
+            ...(reordered.reorderPlan ? { reorderPlan: reordered.reorderPlan } : {}),
+            pushedDownFilters: filters.length,
+        };
+    }
+    canPushAggregateFilters(requiredPatterns, filters, numericAggregateVariables) {
+        const variables = new Set(requiredPatterns.flatMap((pattern) => variablesInPattern(pattern)));
+        return filters.every((filter) => {
+            if (!variables.has(filter.variable) || filter.variable2) {
+                return false;
+            }
+            if (isNumericGuardFilter(filter) && numericAggregateVariables.has(filter.variable)) {
+                return true;
+            }
+            return isPushdownFilter(filter) && this.compilePushdownFilter(filter.variable, [filter]) !== null;
+        });
+    }
+    hasNumericAggregateGuards(filters, numericAggregateVariables) {
+        return [...numericAggregateVariables].every((variableName) => (filters.some((filter) => isNumericGuardFilter(filter) && filter.variable === variableName)));
+    }
+    groupAggregatePushdown(query, requiredPatterns, filters, aggregates) {
+        if (aggregates.length === 0
+            || (query.groupBy?.length ?? 0) === 0
+            || (query.values?.length ?? 0) > 0
+            || (query.textSearch?.length ?? 0) > 0
+            || (query.vectorSearch?.length ?? 0) > 0
+            || (query.unions?.length ?? 0) > 0
+            || (query.minus?.length ?? 0) > 0
+            || (query.exists?.length ?? 0) > 0
+            || (query.optional?.length ?? 0) > 0
+            || (query.binds?.length ?? 0) > 0
+            || query.distinct) {
+            return undefined;
+        }
+        if (aggregates.some((aggregate) => (aggregate.type !== 'count'
+            && (!aggregate.variable || aggregate.distinct)))) {
+            return undefined;
+        }
+        const numericAggregateVariables = new Set(aggregates
+            .filter((aggregate) => aggregate.type !== 'count')
+            .map((aggregate) => aggregate.variable)
+            .filter((variableName) => Boolean(variableName)));
+        if (!this.hasNumericAggregateGuards(filters, numericAggregateVariables)
+            || !this.canPushAggregateFilters(requiredPatterns, filters, numericAggregateVariables)) {
+            return undefined;
+        }
+        const visibleVariables = new Set(requiredPatterns.flatMap((pattern) => variablesInPattern(pattern)));
+        if ((query.groupBy ?? []).some((variableName) => !visibleVariables.has(variableName))) {
+            return undefined;
+        }
+        if (aggregates.some((aggregate) => aggregate.variable && !visibleVariables.has(aggregate.variable))) {
+            return undefined;
+        }
+        const countOnly = numericAggregateVariables.size === 0;
+        const aggregateVariables = new Set(aggregates.map((aggregate) => aggregate.as));
+        if ((query.orderBy ?? []).some((entry) => (!(query.groupBy ?? []).includes(entry.variable) && !aggregateVariables.has(entry.variable)))) {
+            return undefined;
+        }
+        const orderPushed = (query.orderBy?.length ?? 0) > 0;
+        const havingPushdown = this.groupAggregateHavingPushdown(query.having ?? [], aggregateVariables);
+        const havingPushed = (query.having?.length ?? 0) === 0 || havingPushdown !== undefined;
+        const paginationPushed = (query.limit !== undefined || query.offset !== undefined) && havingPushed;
+        const sharedVariables = variablesSharedAcrossPatterns(requiredPatterns);
+        if (requiredPatterns.length > 1 && sharedVariables.size === 0) {
+            return undefined;
+        }
+        const compiled = requiredPatterns.map((pattern) => this.compileJoinPattern(pattern, filters));
+        if (compiled.some((entry) => !entry)) {
+            return undefined;
+        }
+        const reordered = this.reorderJoinPatterns(requiredPatterns, compiled, filters);
+        return {
+            patterns: reordered.patterns,
+            ...(reordered.reorderPlan ? { reorderPlan: reordered.reorderPlan } : {}),
+            ...(havingPushdown && havingPushdown.length > 0 ? { having: havingPushdown } : {}),
+            pushedDownFilters: filters.length,
+            pushedDownHaving: havingPushdown?.length ?? 0,
+            orderPushed,
+            paginationPushed,
+            countOnly,
+        };
+    }
+    groupAggregateHavingPushdown(having, aggregateVariables) {
+        const compiled = [];
+        for (const filter of having) {
+            if (!aggregateVariables.has(filter.variable)
+                || filter.operand
+                || filter.variable2
+                || filter.value === undefined
+                || !isGroupAggregateHavingOperator(filter.operator)) {
+                return undefined;
+            }
+            const value = filterValueToNumber(filter.value);
+            if (value === undefined) {
+                return undefined;
+            }
+            compiled.push({
+                aggregate: filter.variable,
+                operator: filter.operator,
+                value,
+            });
+        }
+        return compiled;
+    }
+    distinctCountKey(pattern, variableName) {
+        if (!variableName) {
+            return undefined;
+        }
+        const keys = TERM_KEYS.filter((key) => {
+            const value = pattern[key];
+            return isVariable(value) && value.variable === variableName;
+        });
+        return keys.length === 1 ? keys[0] : undefined;
+    }
+    scanOrderForPattern(pattern, orderBy) {
+        if (orderBy.length === 0) {
+            return undefined;
+        }
+        const order = orderBy.map((entry) => termKeyForVariable(pattern, entry.variable));
+        if (order.some((key) => key === undefined)) {
+            return undefined;
+        }
+        const orderDirections = orderBy.map((entry) => entry.direction ?? 'asc');
+        const firstDirection = orderDirections[0];
+        const sameDirection = orderDirections.every((direction) => direction === firstDirection);
+        return {
+            order: order,
+            ...(sameDirection
+                ? { reverse: firstDirection === 'desc' || undefined }
+                : { orderDirections }),
+        };
+    }
+    canPushAllFiltersForPattern(pattern, filters) {
+        const variables = new Set(variablesInPattern(pattern));
+        return filters.every((filter) => (variables.has(filter.variable)
+            && isPushdownFilter(filter)
+            && this.compilePushdownFilter(filter.variable, [filter]) !== null));
+    }
+    requiredFiltersNeedingPostApply(query, requiredPatterns, filters, requiredBgpPushdown) {
+        if (filters.length === 0) {
+            return filters;
+        }
+        if (requiredBgpPushdown) {
+            return [];
+        }
+        if (!this.canElideRequiredPatternFilterRechecks(query, requiredPatterns)) {
+            return filters;
+        }
+        const requiredVariables = new Set(requiredPatterns.flatMap((pattern) => variablesInPattern(pattern)));
+        return filters.filter((filter) => !(requiredVariables.has(filter.variable)
+            && this.compilePushdownFilter(filter.variable, [filter]) !== null));
+    }
+    canElideRequiredPatternFilterRechecks(query, requiredPatterns) {
+        return requiredPatterns.length > 0
+            && (query.values?.length ?? 0) === 0
+            && (query.textSearch?.length ?? 0) === 0
+            && (query.vectorSearch?.length ?? 0) === 0
+            && (query.unions?.length ?? 0) === 0
+            && (query.minus?.length ?? 0) === 0
+            && (query.exists?.length ?? 0) === 0
+            && (query.optional?.length ?? 0) === 0
+            && (query.binds?.length ?? 0) === 0
+            && queryAggregates(query).length === 0;
+    }
+    compilePattern(pattern, binding, filters) {
+        const compiled = {};
+        const pushedDownFilterIndexes = new Set();
+        for (const key of TERM_KEYS) {
+            const value = pattern[key];
+            if (!value)
+                continue;
+            if (isVariable(value)) {
+                const bound = binding[value.variable];
+                if (bound) {
+                    compiled[key] = bound;
+                }
+                else {
+                    const pushdown = this.compilePushdownFilterWithIndexes(value.variable, filters);
+                    if (pushdown) {
+                        compiled[key] = pushdown.pattern;
+                        pushdown.filterIndexes.forEach((index) => pushedDownFilterIndexes.add(index));
+                    }
+                }
+            }
+            else {
+                compiled[key] = value;
+            }
+        }
+        return isConsistentPattern(compiled)
+            ? {
+                ...compiled,
+                pushedDownFilters: pushedDownFilterIndexes.size,
+                pushedDownFilterIndexes: [...pushedDownFilterIndexes],
+            }
+            : null;
+    }
+    bindQuad(pattern, binding, quad) {
+        const next = { ...binding };
+        for (const key of TERM_KEYS) {
+            const value = pattern[key];
+            if (!isVariable(value))
+                continue;
+            const term = quad[key];
+            const existing = next[value.variable];
+            if (existing && !sameTerm(existing, term)) {
+                return null;
+            }
+            next[value.variable] = term;
+        }
+        return next;
+    }
+    countBindings(bindings, variable, distinct) {
+        if (!distinct) {
+            return variable ? bindings.filter((binding) => binding[variable]).length : bindings.length;
+        }
+        if (!variable) {
+            return new Set(bindings.map((binding) => bindingKey(binding))).size;
+        }
+        return new Set(bindings
+            .map((binding) => binding[variable])
+            .filter((term) => Boolean(term))
+            .map((term) => (0, n3_1.termToId)(term))).size;
+    }
+    aggregateBindings(bindings, aggregates) {
+        const binding = {};
+        let firstCount = 0;
+        aggregates.forEach((aggregate, index) => {
+            const count = aggregate.type === 'count'
+                ? this.countBindings(bindings, aggregate.variable, aggregate.distinct)
+                : 0;
+            if (index === 0) {
+                firstCount = count;
+            }
+            const term = this.aggregateLiteral(bindings, aggregate);
+            if (term) {
+                binding[aggregate.as] = term;
+            }
+        });
+        return { binding, firstCount };
+    }
+    groupAggregateBindings(bindings, groupBy, aggregates) {
+        const groups = new Map();
+        for (const binding of bindings) {
+            const groupKey = groupBy.map((variableName) => {
+                const term = binding[variableName];
+                return term ? (0, n3_1.termToId)(term) : '__UNBOUND__';
+            }).join('\u001f');
+            const existing = groups.get(groupKey);
+            if (existing) {
+                existing.push(binding);
+            }
+            else {
+                groups.set(groupKey, [binding]);
+            }
+        }
+        return [...groups.values()].map((groupBindings) => {
+            const first = groupBindings[0];
+            const grouped = {};
+            for (const variableName of groupBy) {
+                if (first[variableName]) {
+                    grouped[variableName] = first[variableName];
+                }
+            }
+            for (const aggregate of aggregates) {
+                const term = this.aggregateLiteral(groupBindings, aggregate);
+                if (term) {
+                    grouped[aggregate.as] = term;
+                }
+            }
+            return grouped;
+        });
+    }
+    aggregateLiteral(bindings, aggregate) {
+        if (aggregate.type === 'count') {
+            return countLiteral(this.countBindings(bindings, aggregate.variable, aggregate.distinct));
+        }
+        const values = this.numericAggregateValues(bindings, aggregate.variable, aggregate.distinct);
+        if (values.length === 0) {
+            return aggregate.type === 'sum' ? decimalLiteral(0) : undefined;
+        }
+        switch (aggregate.type) {
+            case 'sum':
+                return decimalLiteral(values.reduce((total, value) => total + value, 0));
+            case 'avg':
+                return decimalLiteral(values.reduce((total, value) => total + value, 0) / values.length);
+            case 'min':
+                return decimalLiteral(Math.min(...values));
+            case 'max':
+                return decimalLiteral(Math.max(...values));
+            default: {
+                const exhaustive = aggregate.type;
+                throw new Error(`Unsupported RDF local aggregate type: ${exhaustive}`);
+            }
+        }
+    }
+    numericAggregateValues(bindings, variable, distinct) {
+        if (!variable) {
+            return [];
+        }
+        const values = [];
+        const seen = new Set();
+        for (const binding of bindings) {
+            const term = binding[variable];
+            if (!term || !isNumericTerm(term)) {
+                continue;
+            }
+            if (distinct) {
+                const key = (0, n3_1.termToId)(term);
+                if (seen.has(key)) {
+                    continue;
+                }
+                seen.add(key);
+            }
+            values.push((0, RdfTermSemantics_1.rdfNumericValue)(term.value));
+        }
+        return values;
+    }
+    compilePushdownFilter(variableName, filters) {
+        return this.compilePushdownFilterWithIndexes(variableName, filters)?.pattern ?? null;
+    }
+    compilePushdownFilterWithIndexes(variableName, filters) {
+        const pushable = filters
+            .map((filter, index) => ({ filter, index }))
+            .filter(({ filter }) => (filter.variable === variableName
+            && isPushdownFilter(filter)));
+        if (pushable.length === 0) {
+            return null;
+        }
+        const operators = {};
+        const filterIndexes = [];
+        for (const { filter, index } of pushable) {
+            switch (filter.operator) {
+                case '$eq':
+                case '$ne':
+                    if (filter.value === undefined)
+                        return null;
+                    if (!(0, types_1.isTerm)(filter.value))
+                        return null;
+                    operators[filter.operator] = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$gt':
+                case '$gte':
+                case '$lt':
+                case '$lte':
+                    if (filter.value === undefined)
+                        return null;
+                    operators[filter.operator] = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$in':
+                case '$notIn':
+                    if (!filter.values || filter.values.length === 0)
+                        return null;
+                    if (filter.values.some((value) => !(0, types_1.isTerm)(value)))
+                        return null;
+                    operators[filter.operator] = filter.values;
+                    filterIndexes.push(index);
+                    break;
+                case '$sameTerm':
+                    if (filter.variable2 || filter.value === undefined)
+                        return null;
+                    if (!(0, types_1.isTerm)(filter.value))
+                        return null;
+                    operators.$eq = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$termType':
+                    if (typeof filter.value !== 'string')
+                        return null;
+                    if (!['iri', 'blank', 'literal', 'numeric'].includes(filter.value))
+                        return null;
+                    operators.$termType = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$lang':
+                    if (typeof filter.value !== 'string')
+                        return null;
+                    operators.$language = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$notLang':
+                    if (typeof filter.value !== 'string')
+                        return null;
+                    operators.$notLanguage = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$langMatches':
+                    if (typeof filter.value !== 'string')
+                        return null;
+                    operators.$langMatches = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$datatype':
+                    if (filter.value === undefined || !(0, types_1.isTerm)(filter.value))
+                        return null;
+                    if (filter.value.termType !== 'NamedNode')
+                        return null;
+                    operators.$datatype = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$notDatatype':
+                    if (filter.value === undefined || !(0, types_1.isTerm)(filter.value))
+                        return null;
+                    if (filter.value.termType !== 'NamedNode')
+                        return null;
+                    operators.$notDatatype = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$startsWith':
+                    if (typeof filter.value !== 'string')
+                        return null;
+                    operators.$startsWith = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$contains':
+                case '$endsWith':
+                    if (typeof filter.value !== 'string')
+                        return null;
+                    operators[filter.operator] = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                case '$regex':
+                    if (typeof filter.value !== 'string')
+                        return null;
+                    if (filter.flags)
+                        return null;
+                    operators.$regex = filter.value;
+                    filterIndexes.push(index);
+                    break;
+                default:
+                    return null;
+            }
+        }
+        return Object.keys(operators).length > 0
+            ? { pattern: operators, filterIndexes }
+            : null;
+    }
+    matchesNewlyBoundFilters(binding, previousBinding, filters) {
+        const newlyBound = filters.filter((filter) => {
+            const variables = filterVariables(filter);
+            return variables.every((variableName) => binding[variableName])
+                && variables.some((variableName) => !previousBinding[variableName]);
+        });
+        return this.matchesFilters(binding, newlyBound);
+    }
+    matchesFilters(binding, filters) {
+        return filters.every((filter) => this.matchesFilter(binding, filter));
+    }
+    matchesFilter(binding, filter) {
+        const value = binding[filter.variable];
+        if (filter.operator === '$bound') {
+            return Boolean(filter.value) ? Boolean(value) : !value;
+        }
+        if (!value) {
+            return false;
+        }
+        const comparisonValue = filterOperandValue(value, filter.operand);
+        switch (filter.operator) {
+            case '$eq':
+                if (filter.variable2)
+                    return this.compareVariableFilter(binding, comparisonValue, filter, (comparison) => comparison === 0);
+                return filter.value !== undefined && sameTermOrLexical(comparisonValue, filter.value);
+            case '$ne':
+                if (filter.variable2)
+                    return this.compareVariableFilter(binding, comparisonValue, filter, (comparison) => comparison !== 0);
+                return filter.value === undefined || !sameTermOrLexical(comparisonValue, filter.value);
+            case '$gt':
+                if (filter.variable2)
+                    return this.compareVariableFilter(binding, comparisonValue, filter, (comparison) => comparison > 0);
+                return compareTermsForFilter(comparisonValue, filter.value) > 0;
+            case '$gte':
+                if (filter.variable2)
+                    return this.compareVariableFilter(binding, comparisonValue, filter, (comparison) => comparison >= 0);
+                return compareTermsForFilter(comparisonValue, filter.value) >= 0;
+            case '$lt':
+                if (filter.variable2)
+                    return this.compareVariableFilter(binding, comparisonValue, filter, (comparison) => comparison < 0);
+                return compareTermsForFilter(comparisonValue, filter.value) < 0;
+            case '$lte':
+                if (filter.variable2)
+                    return this.compareVariableFilter(binding, comparisonValue, filter, (comparison) => comparison <= 0);
+                return compareTermsForFilter(comparisonValue, filter.value) <= 0;
+            case '$in':
+                return (filter.values ?? []).some((candidate) => sameTermOrLexical(comparisonValue, candidate));
+            case '$notIn':
+                return !(filter.values ?? []).some((candidate) => sameTermOrLexical(comparisonValue, candidate));
+            case '$startsWith': {
+                const text = filterStringValue(value, comparisonValue);
+                return typeof filter.value === 'string' && text.startsWith(filter.value);
+            }
+            case '$contains': {
+                const text = filterStringValue(value, comparisonValue);
+                return typeof filter.value === 'string' && text.includes(filter.value);
+            }
+            case '$endsWith': {
+                const text = filterStringValue(value, comparisonValue);
+                return typeof filter.value === 'string' && text.endsWith(filter.value);
+            }
+            case '$regex': {
+                const text = filterStringValue(value, comparisonValue);
+                return typeof filter.value === 'string' && new RegExp(filter.value, filter.flags).test(text);
+            }
+            case '$termType':
+                return typeof filter.value === 'string' && matchesTermType(value, filter.value);
+            case '$sameTerm': {
+                const right = filter.variable2 ? binding[filter.variable2] : filter.value;
+                return Boolean(right && (0, types_1.isTerm)(right) && sameTerm(value, right));
+            }
+            case '$lang':
+                return typeof filter.value === 'string'
+                    && value.termType === 'Literal'
+                    && value.language === filter.value;
+            case '$notLang':
+                return typeof filter.value === 'string'
+                    && value.termType === 'Literal'
+                    && value.language !== filter.value;
+            case '$langMatches':
+                return typeof filter.value === 'string'
+                    && value.termType === 'Literal'
+                    && langMatches(value.language, filter.value);
+            case '$datatype':
+                return filter.value !== undefined
+                    && value.termType === 'Literal'
+                    && sameTermOrLexical(value.datatype, filter.value);
+            case '$notDatatype':
+                return filter.value !== undefined
+                    && value.termType === 'Literal'
+                    && !sameTermOrLexical(value.datatype, filter.value);
+            default: {
+                const exhaustive = filter.operator;
+                throw new Error(`Unsupported RDF local query filter operator: ${exhaustive}`);
+            }
+        }
+    }
+    compareVariableFilter(binding, comparisonValue, filter, predicate) {
+        if (!filter.variable2) {
+            return false;
+        }
+        const right = binding[filter.variable2];
+        if (!right) {
+            return false;
+        }
+        const rightValue = filterOperandValue(right, filter.operand);
+        return predicate(compareFilterValues(comparisonValue, rightValue));
+    }
+}
+exports.RdfLocalQueryEngine = RdfLocalQueryEngine;
+function variable(variableName) {
+    return { variable: variableName };
+}
+function isVariable(value) {
+    return Boolean(value && typeof value === 'object' && 'variable' in value);
+}
+function variablesInPattern(pattern) {
+    return TERM_KEYS
+        .map((key) => pattern[key])
+        .filter(isVariable)
+        .map((value) => value.variable);
+}
+function patternHasRepeatedVariables(pattern) {
+    const seen = new Set();
+    for (const variableName of variablesInPattern(pattern)) {
+        if (seen.has(variableName)) {
+            return true;
+        }
+        seen.add(variableName);
+    }
+    return false;
+}
+function variablesSharedAcrossPatterns(patterns) {
+    const counts = new Map();
+    for (const pattern of patterns) {
+        for (const variableName of new Set(variablesInPattern(pattern))) {
+            counts.set(variableName, (counts.get(variableName) ?? 0) + 1);
+        }
+    }
+    return new Set([...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([variableName]) => variableName));
+}
+function hasSharedVariable(left, right) {
+    for (const variableName of left) {
+        if (right.has(variableName)) {
+            return true;
+        }
+    }
+    return false;
+}
+function filterVariables(filter) {
+    return filter.variable2
+        ? [filter.variable, filter.variable2]
+        : [filter.variable];
+}
+function buildRequiredSources(patterns, query) {
+    const patternSources = patterns.map((pattern, originalIndex) => ({
+        kind: 'pattern',
+        pattern,
+        originalIndex,
+    }));
+    const remainingValues = [];
+    for (const [originalIndex, source] of (query.values ?? []).entries()) {
+        const patternSource = patternSources.find((candidate) => (!candidate.tupleValues && canAttachTupleValuesToPattern(source, candidate.pattern)));
+        if (patternSource) {
+            patternSource.tupleValues = source;
+            continue;
+        }
+        remainingValues.push({
+            kind: 'values',
+            source,
+            originalIndex,
+        });
+    }
+    return [
+        ...remainingValues,
+        ...patternSources,
+        ...(query.textSearch ?? []).map((pattern, originalIndex) => ({
+            kind: 'text',
+            pattern,
+            originalIndex,
+        })),
+        ...(query.vectorSearch ?? []).map((pattern, originalIndex) => ({
+            kind: 'vector',
+            pattern,
+            originalIndex,
+        })),
+    ];
+}
+function variablesInRequiredSource(source) {
+    if (source.kind === 'pattern') {
+        return uniqueStrings([
+            ...variablesInPattern(source.pattern),
+            ...(source.tupleValues?.variables ?? []),
+        ]);
+    }
+    if (source.kind === 'values') {
+        return source.source.variables;
+    }
+    return [
+        source.pattern.source,
+        source.pattern.chunk,
+        source.pattern.content,
+        source.pattern.heading,
+        source.pattern.score,
+        source.kind === 'vector' ? source.pattern.distance : undefined,
+        source.pattern.workspace,
+        source.pattern.localPath,
+        source.pattern.contentType,
+        source.pattern.ordinal,
+        source.pattern.level,
+        source.pattern.startOffset,
+        source.pattern.endOffset,
+        source.kind === 'vector' ? source.pattern.model : undefined,
+    ].filter((value) => Boolean(value));
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function filtersWithoutIndexes(filters, indexes) {
+    if (indexes.length === 0) {
+        return filters;
+    }
+    const pushedDown = new Set(indexes);
+    return filters.filter((_filter, index) => !pushedDown.has(index));
+}
+function joinValuesSource(input, source) {
+    const output = [];
+    for (const binding of input) {
+        for (const row of source.rows) {
+            const next = mergeTupleValuesBinding(binding, source.variables, row);
+            if (next) {
+                output.push(next);
+            }
+        }
+    }
+    return output;
+}
+function mergeTupleValuesBinding(binding, variables, row) {
+    const next = { ...binding };
+    for (const variableName of variables) {
+        const value = row[variableName];
+        if (!value) {
+            continue;
+        }
+        const existing = next[variableName];
+        if (existing && !sameTerm(existing, value)) {
+            return null;
+        }
+        next[variableName] = value;
+    }
+    return next;
+}
+function canAttachTupleValuesToPattern(source, pattern) {
+    if (source.variables.length < 2 || source.rows.length === 0) {
+        return false;
+    }
+    const slots = new Set();
+    for (const variableName of source.variables) {
+        if (source.rows.some((row) => !row[variableName])) {
+            return false;
+        }
+        const variableSlots = TERM_KEYS.filter((key) => {
+            const value = pattern[key];
+            return isVariable(value) && value.variable === variableName;
+        });
+        if (variableSlots.length !== 1) {
+            return false;
+        }
+        slots.add(variableSlots[0]);
+    }
+    return slots.size === source.variables.length
+        && source.rows.every((row) => source.variables.every((variableName) => Boolean(row[variableName])));
+}
+function tupleConstraintSourceForPattern(source, pattern) {
+    const columns = source.variables.map((variableName) => {
+        const key = termKeyForVariable(pattern, variableName);
+        if (!key) {
+            throw new Error(`Tuple VALUES variable is not bound by pattern: ${variableName}`);
+        }
+        return key;
+    });
+    return {
+        columns,
+        rows: source.rows.map((row) => {
+            const constraint = {};
+            source.variables.forEach((variableName, index) => {
+                constraint[columns[index]] = row[variableName];
+            });
+            return constraint;
+        }),
+    };
+}
+function normalizeOptionalGroup(group) {
+    return Array.isArray(group) ? { patterns: group } : group;
+}
+function compiledPatternKey(pattern) {
+    return TERM_KEYS
+        .map((key) => `${key}:${termMatchKey(pattern[key])}`)
+        .join('|');
+}
+function termMatchKey(match) {
+    if (!match) {
+        return '*';
+    }
+    if ((0, types_1.isTerm)(match)) {
+        return (0, n3_1.termToId)(match);
+    }
+    return JSON.stringify(match, (_key, value) => (0, types_1.isTerm)(value) ? (0, n3_1.termToId)(value) : value);
+}
+function termKeyForVariable(pattern, variableName) {
+    return TERM_KEYS.find((key) => {
+        const value = pattern[key];
+        return isVariable(value) && value.variable === variableName;
+    });
+}
+function isConsistentPattern(pattern) {
+    for (const key of TERM_KEYS) {
+        const value = pattern[key];
+        if (!value || (0, types_1.isTerm)(value)) {
+            continue;
+        }
+    }
+    return true;
+}
+function sameTerm(left, right) {
+    return (0, n3_1.termToId)(left) === (0, n3_1.termToId)(right);
+}
+function filterOperandValue(value, operand) {
+    switch (operand) {
+        case 'stringLength':
+            return value.value.length;
+        case 'stringValue':
+            return value.value;
+        case 'lowerStringValue':
+            return value.value.toLowerCase();
+        case 'upperStringValue':
+            return value.value.toUpperCase();
+        default:
+            return value;
+    }
+}
+function filterStringValue(value, comparisonValue) {
+    return typeof comparisonValue === 'string' ? comparisonValue : value.value;
+}
+function sameTermOrLexical(left, right) {
+    if (typeof left === 'number') {
+        if (isNumericFilterValue(right)) {
+            return left === (0, RdfTermSemantics_1.rdfNumericValue)((0, types_1.isTerm)(right) ? right.value : String(right));
+        }
+        return String(left) === String(right);
+    }
+    if (typeof left === 'string') {
+        return left === ((0, types_1.isTerm)(right) ? right.value : String(right));
+    }
+    return (0, types_1.isTerm)(right) ? sameTerm(left, right) : left.value === String(right);
+}
+function compareTermsForFilter(left, right) {
+    if (right === undefined) {
+        return 1;
+    }
+    return compareFilterValues(left, (0, types_1.isTerm)(right) ? right : right);
+}
+function compareFilterValues(left, right) {
+    if (typeof left === 'number') {
+        if (isNumericFilterValue(right)) {
+            return left - (0, RdfTermSemantics_1.rdfNumericValue)((0, types_1.isTerm)(right) ? right.value : String(right));
+        }
+        return String(left).localeCompare(String(right));
+    }
+    if (typeof left === 'string') {
+        const rightValue = (0, types_1.isTerm)(right) ? right.value : String(right);
+        return left.localeCompare(rightValue);
+    }
+    if (isNumericTerm(left) && isNumericFilterValue(right)) {
+        return (0, RdfTermSemantics_1.rdfNumericValue)(left.value) - (0, RdfTermSemantics_1.rdfNumericValue)((0, types_1.isTerm)(right) ? right.value : String(right));
+    }
+    const rightValue = (0, types_1.isTerm)(right) ? right.value : String(right);
+    return left.value.localeCompare(rightValue);
+}
+function matchesTermType(term, expected) {
+    switch (expected) {
+        case 'iri':
+            return term.termType === 'NamedNode';
+        case 'blank':
+            return term.termType === 'BlankNode';
+        case 'literal':
+            return term.termType === 'Literal';
+        case 'numeric':
+            return isNumericTerm(term);
+        default:
+            return false;
+    }
+}
+function langMatches(languageTag, languageRange) {
+    if (!languageTag) {
+        return false;
+    }
+    if (languageRange === '*') {
+        return true;
+    }
+    const normalizedTag = languageTag.toLowerCase();
+    const normalizedRange = languageRange.toLowerCase();
+    return normalizedTag === normalizedRange
+        || normalizedTag.startsWith(`${normalizedRange}-`);
+}
+function isNumericFilterValue(value) {
+    return (0, types_1.isTerm)(value)
+        ? isNumericTerm(value)
+        : (typeof value === 'number' || (typeof value === 'string' && (0, RdfTermSemantics_1.isFiniteNumericLexical)(value)));
+}
+function isNumericTerm(term) {
+    return (0, RdfTermSemantics_1.isRdfNumericTerm)(term);
+}
+function isPushdownFilter(filter) {
+    if (isNumericGuardFilter(filter)) {
+        return true;
+    }
+    if (filter.operand === 'stringLength') {
+        return false;
+    }
+    if (filter.operand === 'lowerStringValue' || filter.operand === 'upperStringValue') {
+        return false;
+    }
+    if (filter.operand === 'stringValue') {
+        return filter.operator === '$startsWith'
+            || filter.operator === '$contains'
+            || filter.operator === '$endsWith'
+            || filter.operator === '$regex';
+    }
+    return filter.operator === '$eq'
+        || filter.operator === '$ne'
+        || filter.operator === '$gt'
+        || filter.operator === '$gte'
+        || filter.operator === '$lt'
+        || filter.operator === '$lte'
+        || filter.operator === '$in'
+        || filter.operator === '$notIn'
+        || filter.operator === '$startsWith'
+        || filter.operator === '$contains'
+        || filter.operator === '$endsWith'
+        || filter.operator === '$regex'
+        || filter.operator === '$sameTerm'
+        || filter.operator === '$termType'
+        || filter.operator === '$lang'
+        || filter.operator === '$notLang'
+        || filter.operator === '$langMatches'
+        || filter.operator === '$datatype'
+        || filter.operator === '$notDatatype';
+}
+function isNumericGuardFilter(filter) {
+    return filter.operator === '$termType'
+        && filter.value === 'numeric'
+        && !filter.variable2
+        && !filter.operand;
+}
+function isGroupAggregateHavingOperator(operator) {
+    return operator === '$eq'
+        || operator === '$ne'
+        || operator === '$gt'
+        || operator === '$gte'
+        || operator === '$lt'
+        || operator === '$lte';
+}
+function filterValueToNumber(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        return (0, RdfTermSemantics_1.isFiniteNumericLexical)(value) ? (0, RdfTermSemantics_1.rdfNumericValue)(value) : undefined;
+    }
+    if ((0, types_1.isTerm)(value) && isNumericTerm(value)) {
+        return (0, RdfTermSemantics_1.rdfNumericValue)(value.value);
+    }
+    return undefined;
+}
+function projectBinding(binding, select) {
+    const projected = {};
+    for (const variableName of select) {
+        const value = binding[variableName];
+        if (value) {
+            projected[variableName] = value;
+        }
+    }
+    return projected;
+}
+function compareBindings(left, right, orderBy) {
+    for (const order of orderBy) {
+        const leftValue = left[order.variable] ? (0, n3_1.termToId)(left[order.variable]) : '';
+        const rightValue = right[order.variable] ? (0, n3_1.termToId)(right[order.variable]) : '';
+        const comparison = leftValue.localeCompare(rightValue);
+        if (comparison !== 0) {
+            return order.direction === 'desc' ? -comparison : comparison;
+        }
+    }
+    return 0;
+}
+function bindingKey(binding) {
+    return Object.keys(binding)
+        .sort()
+        .map((key) => `${key}=${(0, n3_1.termToId)(binding[key])}`)
+        .join('\u001f');
+}
+function distinctBindings(bindings) {
+    const seen = new Set();
+    const unique = [];
+    for (const binding of bindings) {
+        const key = bindingKey(binding);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(binding);
+    }
+    return unique;
+}
+function integerLiteral(value) {
+    return n3_1.DataFactory.literal(String(value), n3_1.DataFactory.namedNode(XSD_INTEGER));
+}
+function countLiteral(count) {
+    return integerLiteral(count);
+}
+function finiteBindNumber(term) {
+    if (term.termType !== 'Literal') {
+        return undefined;
+    }
+    const value = Number(term.value);
+    return Number.isFinite(value) ? value : undefined;
+}
+function decimalLiteral(value) {
+    return n3_1.DataFactory.literal(String(value), n3_1.DataFactory.namedNode(XSD_DECIMAL));
+}
+function describePattern(pattern) {
+    return TERM_KEYS
+        .filter((key) => pattern[key])
+        .map((key) => `${key}:${describePatternValue(pattern[key])}`)
+        .join(',');
+}
+function describePatternSource(source) {
+    return TERM_KEYS
+        .map((key) => {
+        const variableName = source.variables[key];
+        if (variableName) {
+            return `${key}:?${variableName}`;
+        }
+        const value = source.pattern[key];
+        return value ? `${key}:${termMatchKey(value)}` : undefined;
+    })
+        .filter(Boolean)
+        .join(',');
+}
+function describePatternValue(value) {
+    if (!value)
+        return '*';
+    if (isVariable(value))
+        return `?${value.variable}`;
+    if ((0, types_1.isTerm)(value))
+        return (0, n3_1.termToId)(value);
+    return 'op';
+}
+function describeFilter(filter) {
+    return `?${filter.variable}${filter.operand ? `:${filter.operand}` : ''}${filter.operator}`;
+}
+function describeTextSearch(pattern) {
+    const bindings = [
+        pattern.source ? `source:?${pattern.source}` : undefined,
+        pattern.chunk ? `chunk:?${pattern.chunk}` : undefined,
+        pattern.content ? `content:?${pattern.content}` : undefined,
+        pattern.heading ? `heading:?${pattern.heading}` : undefined,
+        pattern.score ? `score:?${pattern.score}` : undefined,
+    ].filter(Boolean).join(',');
+    const scope = pattern.scope?.workspace
+        ? `workspace:${pattern.scope.workspace}`
+        : pattern.scope?.sourcePrefix
+            ? `prefix:${pattern.scope.sourcePrefix}`
+            : '*';
+    const window = describeSearchWindow(pattern.limit, pattern.offset);
+    const order = describeSearchOrder(pattern.orderBy);
+    return `${JSON.stringify(pattern.query)}@${scope}${bindings ? ` ${bindings}` : ''}${window}${order}`;
+}
+function describeVectorSearch(pattern) {
+    const bindings = [
+        pattern.source ? `source:?${pattern.source}` : undefined,
+        pattern.chunk ? `chunk:?${pattern.chunk}` : undefined,
+        pattern.content ? `content:?${pattern.content}` : undefined,
+        pattern.heading ? `heading:?${pattern.heading}` : undefined,
+        pattern.score ? `score:?${pattern.score}` : undefined,
+        pattern.distance ? `distance:?${pattern.distance}` : undefined,
+    ].filter(Boolean).join(',');
+    const scope = pattern.scope?.workspace
+        ? `workspace:${pattern.scope.workspace}`
+        : pattern.scope?.sourcePrefix
+            ? `prefix:${pattern.scope.sourcePrefix}`
+            : '*';
+    const metric = pattern.metric ?? 'cosine';
+    const window = describeSearchWindow(pattern.limit, pattern.offset);
+    const order = describeSearchOrder(pattern.orderBy);
+    return `${metric}:${pattern.embedding.length}d@${scope}${bindings ? ` ${bindings}` : ''}${window}${order}`;
+}
+function describeSearchWindow(limit, offset) {
+    const parts = [
+        limit !== undefined ? `limit:${Math.max(0, limit)}` : undefined,
+        offset !== undefined ? `offset:${Math.max(0, offset)}` : undefined,
+    ].filter(Boolean);
+    return parts.length > 0 ? ` ${parts.join(',')}` : '';
+}
+function hasSearchWindow(source) {
+    return source.pattern.limit !== undefined || source.pattern.offset !== undefined;
+}
+function describeSearchOrder(orderBy) {
+    if (!orderBy?.length) {
+        return '';
+    }
+    return ` order:${orderBy.map((entry) => `${entry.field}:${entry.direction ?? 'asc'}`).join(',')}`;
+}
+function describeBind(bind) {
+    return `?${bind.variable}:=${describeBindExpression(bind.expression)}`;
+}
+function describeBindExpression(expression) {
+    switch (expression.type) {
+        case 'term':
+            if (expression.term.termType === 'Literal' && (0, RdfTermSemantics_1.isFiniteNumericLexical)(expression.term.value)) {
+                return expression.term.value;
+            }
+            return (0, n3_1.termToId)(expression.term);
+        case 'variable':
+            return `?${expression.variable}`;
+        case 'stringValue':
+            return `STR(?${expression.variable})`;
+        case 'stringLength':
+            return `STRLEN(?${expression.variable})`;
+        case 'lowerCase':
+            return `LCASE(${describeBindExpression(expression.expression)})`;
+        case 'upperCase':
+            return `UCASE(${describeBindExpression(expression.expression)})`;
+        case 'substring':
+            return `SUBSTR(${[
+                describeBindExpression(expression.expression),
+                describeBindExpression(expression.start),
+                expression.length === undefined ? undefined : describeBindExpression(expression.length),
+            ].filter(Boolean).join(',')})`;
+        case 'concat':
+            return `CONCAT(${expression.expressions.map(describeBindExpression).join(',')})`;
+        case 'iri':
+            return `IRI(${describeBindExpression(expression.expression)})`;
+        default: {
+            const exhaustive = expression;
+            return JSON.stringify(exhaustive);
+        }
+    }
+}
+function describeScanOrder(options) {
+    const order = options.order ?? [];
+    const directions = options.orderDirections ?? order.map(() => (options.reverse ? 'desc' : 'asc'));
+    const firstDirection = directions[0] ?? 'asc';
+    const sameDirection = directions.every((direction) => direction === firstDirection);
+    if (sameDirection) {
+        return `${firstDirection}:${order.join(',')}`;
+    }
+    return order.map((entry, index) => `${directions[index] ?? 'asc'}:${entry}`).join(',');
+}
+function describeQueryOrder(orderBy) {
+    return orderBy.map((entry) => `${entry.direction ?? 'asc'}:${entry.variable}`).join(',');
+}
+function storagePlanMarkers(queryPlan) {
+    return (queryPlan ?? []).filter((entry) => (entry.startsWith('TextSearch(')
+        || entry.startsWith('Rdf3x')
+        || entry === 'GraphMembershipFilter'
+        || entry === 'GraphPrefixMembershipFilter'
+        || entry.startsWith('LexicalRange(')
+        || entry.startsWith('NumericRange(')
+        || entry.startsWith('PrefixRange(')
+        || entry.startsWith('TermIn(')
+        || entry.startsWith('TermNotIn(')
+        || entry.startsWith('TermType(')
+        || entry.startsWith('Language(')
+        || entry.startsWith('Datatype(')
+        || entry.startsWith('TupleValuesJoin(')
+        || entry.startsWith('JoinBGP(')
+        || entry.startsWith('JoinOrder(')
+        || entry.startsWith('JoinDistinct(')
+        || entry.startsWith('JoinLimit')
+        || entry.startsWith('JoinGroupCountHaving(')
+        || entry.startsWith('JoinGroupAggregateHaving(')
+        || entry.startsWith('JoinGroupAggregateNumeric(')));
+}
+function isRdf3xCompatiblePattern(pattern) {
+    return TERM_KEYS.every((key) => {
+        const value = pattern[key];
+        if (!value || (0, types_1.isTerm)(value)) {
+            return true;
+        }
+        if (key === 'graph' && isGraphPrefixPattern(value)) {
+            return true;
+        }
+        if (key === 'object' && isRdf3xNumericRangePattern(value)) {
+            return true;
+        }
+        return false;
+    });
+}
+function isGraphPrefixPattern(value) {
+    return value !== null
+        && typeof value === 'object'
+        && Object.keys(value).length === 1
+        && '$startsWith' in value
+        && typeof value.$startsWith === 'string';
+}
+function isRdf3xNumericRangePattern(value) {
+    if (value === null || typeof value !== 'object' || 'termType' in value) {
+        return false;
+    }
+    const operators = ['$gt', '$gte', '$lt', '$lte'];
+    if (Object.keys(value).some((key) => !operators.includes(key))) {
+        return false;
+    }
+    let hasRange = false;
+    for (const operator of operators) {
+        const rangeValue = value[operator];
+        if (rangeValue === undefined) {
+            continue;
+        }
+        hasRange = true;
+        if (rdf3xNumericRangeValue(rangeValue) === undefined) {
+            return false;
+        }
+    }
+    return hasRange;
+}
+function rdf3xNumericRangeValue(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    if ((0, types_1.isTerm)(value)) {
+        return (0, RdfTermSemantics_1.isRdfNumericTerm)(value) ? (0, RdfTermSemantics_1.rdfNumericValue)(value.value) : undefined;
+    }
+    return undefined;
+}
+function bindTextSearchResult(binding, pattern, result) {
+    const next = { ...binding };
+    const chunkResource = `${result.source}#chunk-${encodeURIComponent(result.chunkKey)}`;
+    const candidates = [
+        [pattern.source, n3_1.DataFactory.namedNode(result.source)],
+        [pattern.chunk, n3_1.DataFactory.namedNode(chunkResource)],
+        [pattern.content, n3_1.DataFactory.literal(result.content)],
+        [pattern.heading, result.heading ? n3_1.DataFactory.literal(result.heading) : undefined],
+        [pattern.score, decimalLiteral(result.score)],
+        [pattern.workspace, n3_1.DataFactory.namedNode(result.workspace)],
+        [pattern.localPath, result.localPath ? n3_1.DataFactory.literal(result.localPath) : undefined],
+        [pattern.contentType, result.contentType ? n3_1.DataFactory.literal(result.contentType) : undefined],
+        [pattern.ordinal, integerLiteral(result.ordinal)],
+        [pattern.level, integerLiteral(result.level)],
+        [pattern.startOffset, integerLiteral(result.startOffset)],
+        [pattern.endOffset, integerLiteral(result.endOffset)],
+    ];
+    for (const [variableName, term] of candidates) {
+        if (!variableName || !term) {
+            continue;
+        }
+        const existing = next[variableName];
+        if (existing && !sameTerm(existing, term)) {
+            return null;
+        }
+        next[variableName] = term;
+    }
+    return next;
+}
+function bindVectorSearchResult(binding, pattern, result) {
+    const next = { ...binding };
+    const chunkResource = `${result.source}#chunk-${encodeURIComponent(result.chunkKey)}`;
+    const candidates = [
+        [pattern.source, n3_1.DataFactory.namedNode(result.source)],
+        [pattern.chunk, n3_1.DataFactory.namedNode(chunkResource)],
+        [pattern.content, n3_1.DataFactory.literal(result.content)],
+        [pattern.heading, result.heading ? n3_1.DataFactory.literal(result.heading) : undefined],
+        [pattern.score, decimalLiteral(result.score)],
+        [pattern.distance, decimalLiteral(result.distance)],
+        [pattern.workspace, n3_1.DataFactory.namedNode(result.workspace)],
+        [pattern.localPath, result.localPath ? n3_1.DataFactory.literal(result.localPath) : undefined],
+        [pattern.contentType, result.contentType ? n3_1.DataFactory.literal(result.contentType) : undefined],
+        [pattern.ordinal, integerLiteral(result.ordinal)],
+        [pattern.level, integerLiteral(result.level)],
+        [pattern.startOffset, integerLiteral(result.startOffset)],
+        [pattern.endOffset, integerLiteral(result.endOffset)],
+        [pattern.model, result.model ? n3_1.DataFactory.literal(result.model) : undefined],
+    ];
+    for (const [variableName, term] of candidates) {
+        if (!variableName || !term) {
+            continue;
+        }
+        const existing = next[variableName];
+        if (existing && !sameTerm(existing, term)) {
+            return null;
+        }
+        next[variableName] = term;
+    }
+    return next;
+}
+function queryAggregates(query) {
+    return query.aggregates ?? (query.aggregate ? [query.aggregate] : []);
+}
+function aggregatePlan(aggregates, grouped) {
+    if (aggregates.some((aggregate) => aggregate.type !== 'count')) {
+        const prefix = grouped ? 'group-' : '';
+        const suffix = aggregates.length > 1 ? '-multi' : '';
+        return `Aggregate(${prefix}basic${suffix})`;
+    }
+    if (aggregates.length === 1) {
+        const aggregate = aggregates[0];
+        if (grouped) {
+            return aggregate.distinct ? 'Aggregate(group-count-distinct)' : 'Aggregate(group-count)';
+        }
+        return aggregate.distinct ? 'Aggregate(count-distinct)' : 'Aggregate(count)';
+    }
+    if (grouped) {
+        return aggregates.some((aggregate) => aggregate.distinct)
+            ? 'Aggregate(group-count-multi-distinct)'
+            : 'Aggregate(group-count-multi)';
+    }
+    return aggregates.some((aggregate) => aggregate.distinct)
+        ? 'Aggregate(count-multi-distinct)'
+        : 'Aggregate(count-multi)';
+}
+//# sourceMappingURL=RdfLocalQueryEngine.js.map