@undefineds.co/xpod 0.1.0-local.202602081751

package/dist/storage/sparql/ComunicaQuintEngine.js

@@ -0,0 +1,727 @@
+"use strict";
+/**
+ * ComunicaQuintEngine - Comunica SPARQL engine backed by QuintStore
+ *
+ * Features:
+ * 1. Query pushdown optimization (LIMIT/ORDER BY)
+ * 2. FILTER pushdown via IQuerySource interface
+ * 3. External filters for security boundaries (ACL)
+ * 4. OPTIONAL optimization via QueryOptimizer
+ *
+ * Architecture:
+ * - Uses QuintQuerySource (IQuerySource) for proper FILTER pushdown
+ * - Uses QueryOptimizer for OPTIONAL and Compound Query optimization
+ * - Comunica pushes FILTER operations down to sources that declare support
+ * - QuintQuerySource extracts filters from algebra and applies them to QuintStore
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComunicaQuintEngine = void 0;
+const events_1 = require("events");
+const query_sparql_rdfjs_1 = require("@comunica/query-sparql-rdfjs");
+const utils_bindings_factory_1 = require("@comunica/utils-bindings-factory");
+const sparqlalgebrajs_1 = require("sparqlalgebrajs");
+const asynciterator_1 = require("asynciterator");
+const rdf_data_factory_1 = require("rdf-data-factory");
+const QuintQuerySource_1 = require("./QuintQuerySource");
+const QueryOptimizer_1 = require("./QueryOptimizer");
+// Context key names - must match Comunica's internal keys
+const CONTEXT_KEY_QUERY_SOURCES = '@comunica/bus-query-operation:querySources';
+const dataFactory = new rdf_data_factory_1.DataFactory();
+/**
+ * Custom RDF/JS Store backed by QuintStore
+ * Used for UPDATE operations (INSERT/DELETE) which don't need FILTER pushdown
+ */
+class QuintRdfStore {
+    constructor(store, getSecurityFilters, debug) {
+        this.store = store;
+        this.getSecurityFilters = getSecurityFilters;
+        this.debug = debug;
+    }
+    match(subject, predicate, object, graph) {
+        // Build QuintPattern
+        const pattern = {};
+        if (subject && subject.termType !== 'Variable') {
+            pattern.subject = subject;
+        }
+        if (predicate && predicate.termType !== 'Variable') {
+            pattern.predicate = predicate;
+        }
+        if (object && object.termType !== 'Variable') {
+            pattern.object = object;
+        }
+        if (graph && graph.termType !== 'Variable' && graph.termType !== 'DefaultGraph') {
+            pattern.graph = graph;
+        }
+        // Apply security filters (from upstream, e.g., ACL)
+        const securityFilters = this.getSecurityFilters();
+        if (securityFilters) {
+            if (securityFilters.subject && !pattern.subject) {
+                pattern.subject = securityFilters.subject;
+            }
+            if (securityFilters.predicate && !pattern.predicate) {
+                pattern.predicate = securityFilters.predicate;
+            }
+            if (securityFilters.object && !pattern.object) {
+                pattern.object = securityFilters.object;
+            }
+            if (securityFilters.graph && !pattern.graph) {
+                pattern.graph = securityFilters.graph;
+            }
+        }
+        if (this.debug) {
+            console.log(`[QuintRdfStore] match() called`);
+            console.log(`  pattern:`, pattern);
+        }
+        // Use wrap to convert Promise<Array> to AsyncIterator
+        const promiseIterator = (0, asynciterator_1.wrap)(this.store.get(pattern));
+        return promiseIterator;
+    }
+    /**
+     * Import quads from a stream (Sink interface)
+     */
+    import(stream) {
+        const emitter = new events_1.EventEmitter();
+        const quads = [];
+        let ended = false;
+        // Handle data events
+        stream.on('data', (quad) => {
+            quads.push(quad);
+        });
+        const handleEnd = () => {
+            if (ended)
+                return;
+            ended = true;
+            if (quads.length > 0) {
+                this.store.multiPut(quads)
+                    .then(() => emitter.emit('end'))
+                    .catch((err) => emitter.emit('error', err));
+            }
+            else {
+                emitter.emit('end');
+            }
+        };
+        stream.on('end', handleEnd);
+        stream.on('error', (err) => {
+            emitter.emit('error', err);
+        });
+        // Handle already-ended streams (synchronous streams)
+        // Use setImmediate to ensure we check after all synchronous data events
+        setImmediate(() => {
+            if (stream.readableEnded || stream.closed) {
+                handleEnd();
+            }
+        });
+        return emitter;
+    }
+    /**
+     * Remove quads from a stream (Store interface)
+     */
+    remove(stream) {
+        const emitter = new events_1.EventEmitter();
+        const deletePromises = [];
+        let ended = false;
+        stream.on('data', (quad) => {
+            const pattern = {
+                subject: quad.subject,
+                predicate: quad.predicate,
+                object: quad.object,
+            };
+            if (quad.graph && quad.graph.termType !== 'DefaultGraph') {
+                pattern.graph = quad.graph;
+            }
+            deletePromises.push(this.store.del(pattern));
+        });
+        const handleEnd = () => {
+            if (ended)
+                return;
+            ended = true;
+            Promise.all(deletePromises)
+                .then(() => emitter.emit('end'))
+                .catch((err) => emitter.emit('error', err));
+        };
+        stream.on('end', handleEnd);
+        stream.on('error', (err) => {
+            emitter.emit('error', err);
+        });
+        // Handle already-ended streams (synchronous streams)
+        setImmediate(() => {
+            if (stream.readableEnded || stream.closed) {
+                handleEnd();
+            }
+        });
+        return emitter;
+    }
+    /**
+     * Remove all matching quads (Store interface)
+     */
+    removeMatches(subject, predicate, object, graph) {
+        const emitter = new events_1.EventEmitter();
+        if (this.debug) {
+            console.log(`[QuintRdfStore] removeMatches()`, { subject, predicate, object, graph });
+        }
+        const pattern = {};
+        if (subject && subject.termType !== 'Variable') {
+            pattern.subject = subject;
+        }
+        if (predicate && predicate.termType !== 'Variable') {
+            pattern.predicate = predicate;
+        }
+        if (object && object.termType !== 'Variable') {
+            pattern.object = object;
+        }
+        if (graph && graph.termType !== 'Variable' && graph.termType !== 'DefaultGraph') {
+            pattern.graph = graph;
+        }
+        this.store.del(pattern)
+            .then(() => emitter.emit('end'))
+            .catch((err) => emitter.emit('error', err));
+        return emitter;
+    }
+    /**
+     * Delete a named graph (Store interface)
+     */
+    deleteGraph(graph) {
+        const emitter = new events_1.EventEmitter();
+        const graphTerm = typeof graph === 'string'
+            ? { termType: 'NamedNode', value: graph }
+            : graph;
+        const pattern = { graph: graphTerm };
+        this.store.del(pattern)
+            .then(() => emitter.emit('end'))
+            .catch((err) => emitter.emit('error', err));
+        return emitter;
+    }
+}
+class ComunicaQuintEngine {
+    constructor(store, options) {
+        // Current query optimization params
+        this.currentOptimizeParams = null;
+        // Current query's FILTER expressions for pushdown
+        this.currentFilterExpressions = new Map();
+        this.store = store;
+        this.debug = options?.debug ?? false;
+        // Create RdfStore for UPDATE operations
+        this.rdfStore = new QuintRdfStore(store, () => this.currentSecurityFilters, this.debug);
+        // Create BindingsFactory
+        this.bindingsFactory = new utils_bindings_factory_1.BindingsFactory(dataFactory);
+        // Create QuintQuerySource with IQuerySource interface for proper FILTER pushdown
+        this.querySource = new QuintQuerySource_1.QuintQuerySource(store, {
+            debug: this.debug,
+            bindingsFactory: this.bindingsFactory,
+            getSecurityFilters: () => this.currentSecurityFilters,
+            getOptimizeParams: () => this.currentOptimizeParams,
+            getFilterExpression: (varName) => this.currentFilterExpressions.get(varName),
+        });
+        // Create QueryOptimizer for OPTIONAL and Compound Query optimization
+        this.queryOptimizer = new QueryOptimizer_1.QueryOptimizer(store, {
+            debug: this.debug,
+            bindingsFactory: this.bindingsFactory,
+        });
+        this.engine = new query_sparql_rdfjs_1.QueryEngine();
+    }
+    /**
+     * Analyze a query's pushdown potential (stateless)
+     * Returns analysis of what can/cannot be pushed down without executing the query
+     */
+    analyzeQuery(query) {
+        const algebra = (0, sparqlalgebrajs_1.translate)(query);
+        return this.analyzeAlgebra(algebra);
+    }
+    /**
+     * Analyze algebra tree for pushdown potential
+     */
+    analyzeAlgebra(op) {
+        const result = {
+            hasFilter: false,
+            filterTypes: [],
+            pushdownable: [],
+            nonPushdownable: [],
+            estimatedPushdownRate: 1.0,
+        };
+        this.walkAlgebra(op, result);
+        // Calculate pushdown rate
+        const total = result.pushdownable.length + result.nonPushdownable.length;
+        if (total > 0) {
+            result.estimatedPushdownRate = result.pushdownable.length / total;
+        }
+        return result;
+    }
+    /**
+     * Walk algebra tree and collect filter info
+     */
+    walkAlgebra(op, result) {
+        if (op.type === 'filter') {
+            result.hasFilter = true;
+            const filterOp = op;
+            this.analyzeExpression(filterOp.expression, result);
+            this.walkAlgebra(filterOp.input, result);
+        }
+        else if ('input' in op && op.input) {
+            this.walkAlgebra(op.input, result);
+        }
+        if ('left' in op && op.left) {
+            this.walkAlgebra(op.left, result);
+        }
+        if ('right' in op && op.right) {
+            this.walkAlgebra(op.right, result);
+        }
+    }
+    /**
+     * Analyze a filter expression
+     */
+    analyzeExpression(expr, result) {
+        if (expr.expressionType === 'operator') {
+            const opExpr = expr;
+            const op = opExpr.operator.toLowerCase();
+            // Classify the operator
+            if (['=', '!='].includes(op)) {
+                result.filterTypes.push('equality');
+                result.pushdownable.push(op);
+            }
+            else if (['<', '>', '<=', '>='].includes(op)) {
+                result.filterTypes.push('range');
+                result.pushdownable.push(op);
+            }
+            else if (['in', 'notin'].includes(op)) {
+                result.filterTypes.push('equality');
+                result.pushdownable.push(op);
+            }
+            else if (['strstarts', 'strends', 'contains', 'regex'].includes(op)) {
+                result.filterTypes.push('string');
+                result.pushdownable.push(op);
+            }
+            else if (op === 'bound') {
+                result.filterTypes.push('bound');
+                result.pushdownable.push(op);
+            }
+            else if (['isiri', 'isuri', 'isblank', 'isliteral', 'isnumeric'].includes(op)) {
+                // Type checking functions - can be pushed down
+                result.filterTypes.push('typecheck');
+                result.pushdownable.push(op);
+            }
+            else if (op === 'langmatches') {
+                // LANGMATCHES can be pushed down using $endsWith on serialized format
+                result.filterTypes.push('language');
+                result.pushdownable.push(op);
+            }
+            else if (['&&', '||', '!'].includes(op)) {
+                result.filterTypes.push('logical');
+                // Recurse into logical operators
+                for (const arg of opExpr.args) {
+                    this.analyzeExpression(arg, result);
+                }
+            }
+            else {
+                // Non-pushdownable functions
+                result.filterTypes.push('function');
+                result.nonPushdownable.push(op);
+            }
+        }
+        else if (expr.expressionType === 'existence') {
+            result.filterTypes.push('exists');
+            result.pushdownable.push('exists');
+        }
+    }
+    /**
+     * Execute SELECT query
+     * Uses IQuerySource for proper FILTER pushdown
+     *
+     * OPTIONAL 优化：
+     * 如果查询包含多个 OPTIONAL 且只是获取属性（不参与过滤），
+     * 则先执行核心条件获取 subjects，再批量获取属性
+     */
+    async queryBindings(query, context) {
+        const params = this.extractOptimizeParams(query);
+        this.currentOptimizeParams = params;
+        this.currentSecurityFilters = context?.filters;
+        // Extract FILTER expressions from the query for pushdown
+        // Note: We don't clear these in finally because the stream is lazy-evaluated
+        // and sub-queries may need access to filters after this function returns
+        this.extractAndStoreFilters(query);
+        if (this.debug) {
+            console.log(`[ComunicaQuintEngine] Query optimization:`, this.currentOptimizeParams);
+            console.log(`[ComunicaQuintEngine] Security filters:`, this.currentSecurityFilters);
+            console.log(`[ComunicaQuintEngine] Filter expressions for pushdown:`, this.currentFilterExpressions.size);
+        }
+        // 尝试 OPTIONAL 优化（使用 QueryOptimizer）
+        try {
+            const algebra = (0, sparqlalgebrajs_1.translate)(query, { quads: true });
+            const optResult = this.queryOptimizer.analyzeQuery(algebra);
+            if (optResult.type === 'optional' && optResult.analysis) {
+                const optionalAnalysis = optResult.analysis;
+                if (this.debug) {
+                    console.log(`[ComunicaQuintEngine] OPTIONAL optimization available:`, {
+                        subjectVar: optionalAnalysis.subjectVar,
+                        predicates: optionalAnalysis.optionalPredicates?.length,
+                    });
+                }
+                // 执行核心查询获取 subjects
+                const coreBindings = await this.executeCoreQuery(optionalAnalysis.coreOperation, context);
+                // 使用 QueryOptimizer 执行优化查询（排序也在 QueryOptimizer 中处理）
+                const orderOptions = params?.orderVarName
+                    ? { varName: params.orderVarName, reverse: params.reverse }
+                    : undefined;
+                let results = await this.queryOptimizer.executeOptionalOptimized(optionalAnalysis, coreBindings, orderOptions);
+                // 应用 LIMIT 和 OFFSET
+                if (params?.offset || params?.limit) {
+                    const start = params.offset ?? 0;
+                    const end = params.limit ? start + params.limit : undefined;
+                    results = results.slice(start, end);
+                }
+                if (this.debug) {
+                    console.log(`[ComunicaQuintEngine] OPTIONAL optimized: ${results.length} results`);
+                }
+                const resultStream = (0, asynciterator_1.wrap)(Promise.resolve(results));
+                return resultStream;
+            }
+        }
+        catch (error) {
+            if (this.debug) {
+                console.log(`[ComunicaQuintEngine] OPTIONAL optimization failed, falling back:`, error);
+            }
+        }
+        // Create context with pre-identified source to bypass source identification
+        // This allows us to use our IQuerySource directly
+        // IMPORTANT: Use plain object instead of ActionContext to avoid version mismatch
+        // between the root @comunica/core and the one bundled with @comunica/query-sparql-rdfjs
+        // The engine will convert it to ActionContext using its internal @comunica/core
+        const { sources: _ignored, filters: _filters, ...restContext } = context || {};
+        const queryContext = {
+            ...restContext,
+            // Set the identified sources directly - this skips ActorContextPreprocessQuerySourceIdentify
+            [CONTEXT_KEY_QUERY_SOURCES]: [{ source: this.querySource }],
+        };
+        return await this.engine.queryBindings(query, queryContext);
+    }
+    /**
+     * 执行核心查询（不含 OPTIONAL）
+     */
+    async executeCoreQuery(coreOperation, _context) {
+        const bindings = [];
+        const mockContext = {
+            get: () => undefined,
+            getSafe: () => { throw new Error('Not implemented'); },
+            has: () => false,
+        };
+        const stream = this.querySource.queryBindings(coreOperation, mockContext, undefined);
+        for await (const binding of stream) {
+            bindings.push(binding);
+        }
+        return bindings;
+    }
+    /**
+     * Extract FILTER expressions from query and store them for later pushdown
+     * Maps variable names to their filter expressions
+     */
+    extractAndStoreFilters(query) {
+        this.currentFilterExpressions.clear();
+        try {
+            const algebra = (0, sparqlalgebrajs_1.translate)(query, { quads: true });
+            this.collectFilterExpressions(algebra);
+        }
+        catch (error) {
+            if (this.debug) {
+                console.log(`[ComunicaQuintEngine] Failed to extract filters:`, error);
+            }
+        }
+    }
+    /**
+     * Recursively collect FILTER expressions and their variable bindings
+     */
+    collectFilterExpressions(op) {
+        if (op.type === 'filter') {
+            const filterOp = op;
+            const expression = filterOp.expression;
+            // Extract variables from the expression
+            const variables = this.getExpressionVariables(expression);
+            // Store the expression for each variable
+            for (const varName of variables) {
+                // Merge with existing expressions for this variable
+                const existing = this.currentFilterExpressions.get(varName);
+                if (existing) {
+                    // Combine with AND
+                    this.currentFilterExpressions.set(varName, {
+                        type: 'expression',
+                        expressionType: 'operator',
+                        operator: '&&',
+                        args: [existing, expression],
+                    });
+                }
+                else {
+                    this.currentFilterExpressions.set(varName, expression);
+                }
+            }
+            // Continue to nested operations
+            this.collectFilterExpressions(filterOp.input);
+        }
+        else if ('input' in op && op.input) {
+            if (Array.isArray(op.input)) {
+                for (const child of op.input) {
+                    this.collectFilterExpressions(child);
+                }
+            }
+            else {
+                this.collectFilterExpressions(op.input);
+            }
+        }
+        if ('left' in op && op.left) {
+            this.collectFilterExpressions(op.left);
+        }
+        if ('right' in op && op.right) {
+            this.collectFilterExpressions(op.right);
+        }
+    }
+    /**
+     * Get variable names from an expression
+     */
+    getExpressionVariables(expr) {
+        const variables = [];
+        const collectVars = (e) => {
+            if (e.expressionType === 'term') {
+                const term = e.term;
+                if (term.termType === 'Variable') {
+                    variables.push(term.value);
+                }
+            }
+            else if (e.expressionType === 'operator') {
+                const opExpr = e;
+                for (const arg of opExpr.args) {
+                    collectVars(arg);
+                }
+            }
+        };
+        collectVars(expr);
+        return variables;
+    }
+    /**
+     * Get the current filter expression for a variable (used by QuintQuerySource)
+     */
+    getFilterExpressionForVariable(varName) {
+        return this.currentFilterExpressions.get(varName);
+    }
+    /**
+     * Execute ASK query
+     */
+    async queryBoolean(query, context) {
+        const params = this.extractOptimizeParams(query);
+        this.currentOptimizeParams = params;
+        this.currentSecurityFilters = context?.filters;
+        // Optimize ASK with limit=1
+        if (!this.currentOptimizeParams) {
+            this.currentOptimizeParams = { limit: 1 };
+        }
+        else if (this.currentOptimizeParams.limit === undefined) {
+            this.currentOptimizeParams.limit = 1;
+        }
+        try {
+            const { sources: _ignored, filters: _filters, ...restContext } = context || {};
+            const queryContext = {
+                ...restContext,
+                [CONTEXT_KEY_QUERY_SOURCES]: [{ source: this.querySource }],
+            };
+            return await this.engine.queryBoolean(query, queryContext);
+        }
+        finally {
+            this.currentOptimizeParams = null;
+            this.currentSecurityFilters = undefined;
+        }
+    }
+    /**
+     * Execute CONSTRUCT/DESCRIBE query
+     */
+    async queryQuads(query, context) {
+        console.log(`[ComunicaQuintEngine.queryQuads] Starting: ${query.slice(0, 100)}...`);
+        const params = this.extractOptimizeParams(query);
+        this.currentOptimizeParams = params;
+        this.currentSecurityFilters = context?.filters;
+        try {
+            const start = Date.now();
+            const { sources: _ignored, filters: _filters, ...restContext } = context || {};
+            const queryContext = {
+                ...restContext,
+                [CONTEXT_KEY_QUERY_SOURCES]: [{ source: this.querySource }],
+            };
+            const result = await this.engine.queryQuads(query, queryContext);
+            console.log(`[ComunicaQuintEngine.queryQuads] Completed in ${Date.now() - start}ms`);
+            return result;
+        }
+        catch (err) {
+            console.error(`[ComunicaQuintEngine.queryQuads] Failed:`, err);
+            throw err;
+        }
+        finally {
+            this.currentOptimizeParams = null;
+            this.currentSecurityFilters = undefined;
+        }
+    }
+    /**
+     * Execute UPDATE query (INSERT/DELETE)
+     * Uses RDF.Store interface since UPDATE doesn't need FILTER pushdown
+     */
+    async queryVoid(query, context) {
+        console.log(`[ComunicaQuintEngine.queryVoid] Starting: ${query.slice(0, 100)}...`);
+        this.currentSecurityFilters = context?.filters;
+        try {
+            const start = Date.now();
+            const result = await this.engine.queryVoid(query, {
+                sources: [this.rdfStore],
+                ...context,
+            });
+            console.log(`[ComunicaQuintEngine.queryVoid] Completed in ${Date.now() - start}ms`);
+            return result;
+        }
+        catch (err) {
+            console.error(`[ComunicaQuintEngine.queryVoid] Failed:`, err);
+            throw err;
+        }
+        finally {
+            this.currentSecurityFilters = undefined;
+        }
+    }
+    /**
+     * Extract optimization params from SPARQL query
+     */
+    extractOptimizeParams(query) {
+        try {
+            const algebra = (0, sparqlalgebrajs_1.translate)(query, { quads: true });
+            return this.extractOptimizeParamsFromAlgebra(algebra);
+        }
+        catch (error) {
+            if (this.debug) {
+                console.log(`[ComunicaQuintEngine] Failed to analyze query:`, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Extract optimization params from SPARQL algebra
+     */
+    extractOptimizeParamsFromAlgebra(algebra) {
+        let limit;
+        let offset;
+        let order;
+        let orderVarName;
+        let reverse;
+        let currentOp = algebra;
+        let canPushLimit = true;
+        while (currentOp) {
+            switch (currentOp.type) {
+                case 'slice': {
+                    const slice = currentOp;
+                    if (slice.length !== undefined) {
+                        limit = slice.length;
+                    }
+                    if (slice.start !== undefined) {
+                        offset = slice.start;
+                    }
+                    currentOp = slice.input;
+                    break;
+                }
+                case 'orderby': {
+                    const orderBy = currentOp;
+                    if (orderBy.expressions.length === 1) {
+                        const expr = orderBy.expressions[0];
+                        // 提取变量名和排序方向
+                        // ORDER BY ?name: { expressionType: "term", term: { value: "name" } }
+                        // ORDER BY DESC(?name): { expressionType: "operator", operator: "desc", args: [{ expressionType: "term", term: {...} }] }
+                        let varName;
+                        reverse = false;
+                        if (expr.expressionType === 'term') {
+                            const termExpr = expr;
+                            if (termExpr.term?.termType === 'Variable') {
+                                varName = termExpr.term.value;
+                            }
+                        }
+                        else if (expr.expressionType === 'operator') {
+                            const opExpr = expr;
+                            if (opExpr.operator === 'desc' && opExpr.args.length === 1) {
+                                reverse = true;
+                                const innerExpr = opExpr.args[0];
+                                if (innerExpr.expressionType === 'term') {
+                                    const termExpr = innerExpr;
+                                    if (termExpr.term?.termType === 'Variable') {
+                                        varName = termExpr.term.value;
+                                    }
+                                }
+                            }
+                            else if (opExpr.operator === 'asc' && opExpr.args.length === 1) {
+                                const innerExpr = opExpr.args[0];
+                                if (innerExpr.expressionType === 'term') {
+                                    const termExpr = innerExpr;
+                                    if (termExpr.term?.termType === 'Variable') {
+                                        varName = termExpr.term.value;
+                                    }
+                                }
+                            }
+                        }
+                        if (varName) {
+                            orderVarName = varName; // 保存原始变量名
+                            // 尝试直接映射（s/p/o/g）
+                            const termName = this.variableToTermName(varName);
+                            if (termName) {
+                                order = [termName];
+                            }
+                            // 如果直接映射失败，QuintQuerySource 会通过 pattern 分析来确定
+                        }
+                    }
+                    currentOp = orderBy.input;
+                    break;
+                }
+                case 'project':
+                case 'distinct':
+                case 'reduced': {
+                    currentOp = currentOp.input;
+                    break;
+                }
+                case 'bgp': {
+                    const bgp = currentOp;
+                    if (bgp.patterns.length === 1) {
+                        return { limit, offset, order, orderVarName, reverse };
+                    }
+                    canPushLimit = false;
+                    return canPushLimit ? { limit, offset, order, orderVarName, reverse } : null;
+                }
+                case 'join':
+                case 'leftjoin':
+                case 'union':
+                case 'minus':
+                    // 虽然不能下推 LIMIT，但仍然返回 ORDER BY 参数
+                    // 因为 OPTIONAL 优化路径会自己处理排序
+                    canPushLimit = false;
+                    if (orderVarName) {
+                        return { limit, offset, order, orderVarName, reverse };
+                    }
+                    return null;
+                case 'filter':
+                case 'extend':
+                case 'group':
+                    // 同样，返回 ORDER BY 参数供 OPTIONAL 优化路径使用
+                    if (orderVarName) {
+                        return { limit, offset, order, orderVarName, reverse };
+                    }
+                    return null;
+                default:
+                    return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Map SPARQL variable name to TermName
+     */
+    variableToTermName(varName) {
+        const mapping = {
+            's': 'subject',
+            'subject': 'subject',
+            'p': 'predicate',
+            'predicate': 'predicate',
+            'o': 'object',
+            'object': 'object',
+            'g': 'graph',
+            'graph': 'graph',
+        };
+        return mapping[varName.toLowerCase()] ?? null;
+    }
+}
+exports.ComunicaQuintEngine = ComunicaQuintEngine;
+//# sourceMappingURL=ComunicaQuintEngine.js.map