@routier/core 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -101,436 +101,6 @@ function isObjectWithType(value) {
 }
 
 
-},
-599(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
-
-// EXPORTS
-__webpack_require__.d(__webpack_exports__, {
-  TracingCapability: () => (/* reexport */ TracingCapability),
-  Capability: () => (/* reexport */ Capability),
-  PerformanceCapability: () => (/* reexport */ PerformanceCapability)
-});
-
-;// CONCATENATED MODULE: ./src/capabilities/Capability.ts
-class Capability {
-    excludedNames = new Set([
-        "Array",
-        "Set",
-        "Map",
-        "AbortController",
-        "AbortSignal",
-        "SchemaString",
-        "SchemaNumber",
-        "SchemaArray",
-        "SchemaBoolean",
-        "SchemaDate",
-        "SchemaObject",
-        "SchemaDefault",
-        "SchemaDeserialize",
-        "SchemaDistinct",
-        "SchemaSearchable",
-        "SchemaFrom",
-        "SchemaIdentity",
-        "SchemaIndex",
-        "SchemaKey",
-        "SchemaNullable",
-        "SchemaOptional",
-        "SchemaReadonly",
-        "SchemaSerialize",
-        "SchemaTracked",
-        "SchemaComputed",
-        "SchemaFunction",
-        "SchemaBase",
-        "SchemaDefinition"
-    ]);
-    isValidObject(obj) {
-        return typeof obj === "object" && obj !== null;
-    }
-    isCallableMethod(descriptor, key) {
-        return descriptor?.value && typeof descriptor.value === 'function' && key !== 'constructor' && key !== 'undefined';
-    }
-    canExplore(descriptor) {
-        if (typeof descriptor.value !== "object") {
-            return false;
-        }
-        if (descriptor.value == null) {
-            return false;
-        }
-        const name = this.getName(descriptor.value);
-        if (name == null) {
-            return true;
-        }
-        return this.excludedNames.has(name) === false;
-    }
-    getName(value) {
-        if (value.constructor != null) {
-            return value.constructor.name;
-        }
-        return null;
-    }
-    getPath(info, propertyName) {
-        let parent = info.parent;
-        const path = [
-            info.propertyName,
-            propertyName
-        ];
-        while(parent != null){
-            path.unshift(parent.propertyName);
-            parent = parent.parent;
-        }
-        return path.join(".");
-    }
-    explore(instance, onDiscover) {
-        if (!this.isValidObject(instance)) {
-            return;
-        }
-        const explore = [
-            {
-                instance,
-                propertyName: this.getName(instance)
-            }
-        ];
-        const visited = new Set();
-        for(let i = 0; i < explore.length; i++){
-            const info = explore[i];
-            const item = info.instance;
-            if (visited.has(item)) {
-                continue;
-            }
-            const allKeys = [
-                ...Object.getOwnPropertyNames(item),
-                ...Object.getOwnPropertySymbols(item)
-            ];
-            for (const key of allKeys){
-                const descriptor = Object.getOwnPropertyDescriptor(item, key);
-                const isCallable = this.isCallableMethod(descriptor, key);
-                onDiscover(info, {
-                    name: key,
-                    isCallable
-                });
-                if (this.canExplore(descriptor) === false) {
-                    continue;
-                }
-                const path = this.getPath(info, key);
-                explore.push({
-                    instance: descriptor.value,
-                    parent: info,
-                    propertyName: key,
-                    path
-                });
-            }
-            visited.add(item);
-        }
-    }
-}
-
-// EXTERNAL MODULE: ./src/utilities/strings.ts
-var strings = __webpack_require__(615);
-;// CONCATENATED MODULE: ./src/capabilities/performance/PerformanceTracker.ts
-class PerformanceTracker {
-    methodTimings = new Map();
-    operationStartTimes = new Map();
-    startMethodTiming(operationId, methodPath) {
-        const startTime = performance.now();
-        const key = `${operationId}:${methodPath}`;
-        // Track operation start time for delta calculations
-        if (!this.operationStartTimes.has(operationId)) {
-            this.operationStartTimes.set(operationId, startTime);
-        }
-        this.methodTimings.set(key, {
-            startTime
-        });
-        return startTime;
-    }
-    recordNextMethodStart(operationId, methodPath) {
-        const key = `${operationId}:${methodPath}`;
-        const timing = this.methodTimings.get(key);
-        if (timing) {
-            timing.nextMethodStartTime = performance.now();
-        }
-    }
-    endMethodTiming(operationId, methodPath) {
-        const endTime = performance.now();
-        const key = `${operationId}:${methodPath}`;
-        const timing = this.methodTimings.get(key);
-        if (!timing) {
-            return {
-                startTime: endTime
-            };
-        }
-        const duration = endTime - timing.startTime;
-        const timeToNextCall = timing.nextMethodStartTime ? timing.nextMethodStartTime - timing.startTime : undefined;
-        // Clean up
-        this.methodTimings.delete(key);
-        return {
-            startTime: timing.startTime,
-            endTime,
-            duration,
-            nextMethodStartTime: timing.nextMethodStartTime,
-            timeToNextCall
-        };
-    }
-    formatDuration(milliseconds) {
-        if (milliseconds < 1) {
-            return `${(milliseconds * 1000).toFixed(1)}μs`;
-        } else if (milliseconds < 1000) {
-            return `${milliseconds.toFixed(2)}ms`;
-        } else {
-            return `${(milliseconds / 1000).toFixed(2)}s`;
-        }
-    }
-    getDeltaFromOperationStart(operationId, currentTime) {
-        const operationStartTime = this.operationStartTimes.get(operationId);
-        return operationStartTime ? currentTime - operationStartTime : 0;
-    }
-    cleanupOperation(operationId) {
-        this.operationStartTimes.delete(operationId);
-    }
-}
-
-// EXTERNAL MODULE: ./src/utilities/uuid.ts
-var uuid = __webpack_require__(618);
-;// CONCATENATED MODULE: ./src/capabilities/tracing/CallTraceManager.ts
-
-class CallTraceManager {
-    activeOperationId = null;
-    activeCallStack = [];
-    startNewOperation() {
-        const operationId = (0,uuid/* .uuid */.u)(8);
-        this.activeOperationId = operationId;
-        this.activeCallStack = [];
-        return operationId;
-    }
-    isNewOperation() {
-        return this.activeOperationId === null;
-    }
-    getActiveOperationId() {
-        if (!this.activeOperationId) {
-            throw new Error('No active operation context');
-        }
-        return this.activeOperationId;
-    }
-    addMethodToTrace(methodPath) {
-        if (this.isNewOperation()) {
-            this.activeCallStack = [
-                methodPath
-            ];
-        } else {
-            this.activeCallStack.push(methodPath);
-        }
-        return [
-            ...this.activeCallStack
-        ];
-    }
-    removeMethodFromTrace() {
-        if (!this.isNewOperation()) {
-            this.activeCallStack.pop();
-        }
-    }
-    endOperation() {
-        this.activeOperationId = null;
-        this.activeCallStack = [];
-    }
-    formatMethodPaths(methodPaths) {
-        return methodPaths.map((path)=>path.replace(/ → /g, '.'));
-    }
-    getCurrentTrace() {
-        return [
-            ...this.activeCallStack
-        ];
-    }
-}
-
-// EXTERNAL MODULE: ./src/utilities/logger.ts
-var logger = __webpack_require__(581);
-;// CONCATENATED MODULE: ./src/capabilities/PerformanceCapability.ts
-
-
-
-
-
-class PerformanceCapability extends Capability {
-    callTraceManager;
-    performanceTracker;
-    filter;
-    childDurations = new Map();
-    constructor(options){
-        super();
-        this.filter = options?.filter ?? (()=>true);
-        this.callTraceManager = new CallTraceManager();
-        this.performanceTracker = new PerformanceTracker();
-    }
-    apply(instance) {
-        this.explore(instance, (meta, info)=>{
-            if (info.isCallable) {
-                const originalMethod = meta.instance[info.name].bind(meta.instance);
-                meta.instance[info.name] = (...args)=>{
-                    const path = `${meta.path}.${String(info.name)}()`;
-                    if (this.filter(path, info, meta) === false) {
-                        return originalMethod(...args);
-                    }
-                    const isNewOperation = this.callTraceManager.isNewOperation();
-                    let operationId;
-                    let callTrace;
-                    let depth;
-                    if (isNewOperation) {
-                        operationId = this.callTraceManager.startNewOperation();
-                        this.childDurations.set(operationId, []);
-                        callTrace = this.callTraceManager.addMethodToTrace(path);
-                        depth = callTrace.length - 1;
-                        const formattedCallTrace = this.callTraceManager.formatMethodPaths(callTrace);
-                        this.performanceTracker.startMethodTiming(operationId, path);
-                        logger/* .logger.log */.vF.log(`\n${'═'.repeat(60)}`);
-                        logger/* .logger.log */.vF.log(`▶ ORIGIN [${operationId}] ${path}`);
-                        if (args.length > 0) {
-                            logger/* .logger.log */.vF.log(`  Args:`, (0,strings/* .stringifyObject */.Zm)(args, 4, 0));
-                        }
-                        logger/* .logger.log */.vF.log(`  Call Stack: ${formattedCallTrace.join(' → ')}`);
-                    } else {
-                        operationId = this.callTraceManager.getActiveOperationId();
-                        callTrace = this.callTraceManager.addMethodToTrace(path);
-                        depth = callTrace.length - 1;
-                        const indent = '  '.repeat(Math.min(depth, 4));
-                        // Track children for this child method too
-                        const childMethodKey = `${operationId}:${path}`;
-                        this.childDurations.set(childMethodKey, []);
-                        this.performanceTracker.startMethodTiming(operationId, path);
-                        logger/* .logger.log */.vF.log(`${indent}└─ CHILD [${operationId}] ${path}`);
-                        if (args.length > 0) {
-                            logger/* .logger.log */.vF.log(`${indent}   Args:`, (0,strings/* .stringifyObject */.Zm)(args, 4, 0));
-                        }
-                    }
-                    try {
-                        return originalMethod(...args);
-                    } finally{
-                        const metrics = this.performanceTracker.endMethodTiming(operationId, path);
-                        const duration = metrics.duration ?? 0;
-                        const formattedDuration = this.performanceTracker.formatDuration(duration);
-                        if (isNewOperation) {
-                            const childDurations = this.childDurations.get(operationId) ?? [];
-                            const totalChildTime = childDurations.reduce((sum, d)=>sum + d, 0);
-                            const formattedTotalChildTime = this.performanceTracker.formatDuration(totalChildTime);
-                            const overhead = duration - totalChildTime;
-                            const formattedOverhead = this.performanceTracker.formatDuration(Math.max(0, overhead));
-                            logger/* .logger.log */.vF.log(`\n${'═'.repeat(60)}`);
-                            logger/* .logger.log */.vF.log(`◀ COMPLETE [${operationId}] ${path}`);
-                            logger/* .logger.log */.vF.log(`  Total Duration: ${formattedDuration}`);
-                            if (childDurations.length > 0) {
-                                logger/* .logger.log */.vF.log(`  Children Duration: ${formattedTotalChildTime} (${childDurations.length} calls)`);
-                                logger/* .logger.log */.vF.log(`  Overhead: ${formattedOverhead}`);
-                            }
-                            logger/* .logger.log */.vF.log(`${'═'.repeat(60)}\n`);
-                            this.childDurations.delete(operationId);
-                            this.performanceTracker.cleanupOperation(operationId);
-                            this.callTraceManager.endOperation();
-                        } else {
-                            const indent = '  '.repeat(Math.min(depth, 4));
-                            const childMethodKey = `${operationId}:${path}`;
-                            const childDurations = this.childDurations.get(childMethodKey) ?? [];
-                            const totalChildTime = childDurations.reduce((sum, d)=>sum + d, 0);
-                            const formattedTotalChildTime = this.performanceTracker.formatDuration(totalChildTime);
-                            const overhead = duration - totalChildTime;
-                            const formattedOverhead = this.performanceTracker.formatDuration(Math.max(0, overhead));
-                            logger/* .logger.log */.vF.log(`${indent}   ✓ ${formattedDuration}`);
-                            if (childDurations.length > 0) {
-                                logger/* .logger.log */.vF.log(`${indent}     Children: ${formattedTotalChildTime} (${childDurations.length} calls), Overhead: ${formattedOverhead}`);
-                            }
-                            // Clean up child method tracking
-                            this.childDurations.delete(childMethodKey);
-                            // Find the parent method and add this duration to its children list
-                            // The parent is the method one level up in the call trace
-                            const currentTrace = this.callTraceManager.getCurrentTrace();
-                            if (currentTrace.length > 1) {
-                                // Parent is the second-to-last item in the trace (before we remove current)
-                                const parentPath = currentTrace[currentTrace.length - 2];
-                                // Check if parent is the root operation (trace length 2 means root + this child)
-                                if (currentTrace.length === 2) {
-                                    // Direct child of root - add to root's children list
-                                    const rootChildDurations = this.childDurations.get(operationId);
-                                    if (rootChildDurations) {
-                                        rootChildDurations.push(duration);
-                                    }
-                                } else {
-                                    // Nested child - add to parent method's children list
-                                    const parentMethodKey = `${operationId}:${parentPath}`;
-                                    const parentChildDurations = this.childDurations.get(parentMethodKey);
-                                    if (parentChildDurations) {
-                                        parentChildDurations.push(duration);
-                                    }
-                                }
-                            }
-                        }
-                        this.callTraceManager.removeMethodFromTrace();
-                    }
-                };
-            }
-        });
-    }
-}
-
-;// CONCATENATED MODULE: ./src/capabilities/TracingCapability.ts
-
-
-
-class TracingCapability extends Capability {
-    callTraceManager;
-    filter;
-    constructor(options){
-        super();
-        this.filter = options?.filter ?? (()=>true);
-        this.callTraceManager = new CallTraceManager();
-    }
-    apply(instance) {
-        this.explore(instance, (meta, info)=>{
-            if (info.isCallable) {
-                const originalMethod = meta.instance[info.name].bind(meta.instance);
-                meta.instance[info.name] = (...args)=>{
-                    const path = `${meta.path}.${String(info.name)}()`;
-                    if (this.filter(path, info, meta) === false) {
-                        return originalMethod(...args);
-                    }
-                    const isNewOperation = this.callTraceManager.isNewOperation();
-                    let operationId;
-                    if (isNewOperation) {
-                        operationId = this.callTraceManager.startNewOperation();
-                        const callTrace = this.callTraceManager.addMethodToTrace(path);
-                        const formattedCallTrace = this.callTraceManager.formatMethodPaths(callTrace);
-                        console.log(`\n${'═'.repeat(60)}`);
-                        console.log(`▶ ORIGIN [${operationId}] ${path}`);
-                        if (args.length > 0) {
-                            console.log(`  Args:`, (0,strings/* .stringifyObject */.Zm)(args, 4, 0));
-                        }
-                        console.log(`  Call Stack: ${formattedCallTrace.join(' → ')}`);
-                    } else {
-                        operationId = this.callTraceManager.getActiveOperationId();
-                        const callTrace = this.callTraceManager.addMethodToTrace(path);
-                        const indent = '  '.repeat(Math.min(callTrace.length - 1, 4));
-                        console.log(`${indent}└─ CHILD [${operationId}] ${path}`);
-                        if (args.length > 0) {
-                            console.log(`${indent}   Args:`, (0,strings/* .stringifyObject */.Zm)(args, 4, 0));
-                        }
-                    }
-                    try {
-                        return originalMethod(...args);
-                    } finally{
-                        this.callTraceManager.removeMethodFromTrace();
-                        if (isNewOperation) {
-                            this.callTraceManager.endOperation();
-                        }
-                    }
-                };
-            }
-        });
-    }
-}
-
-;// CONCATENATED MODULE: ./src/capabilities/index.ts
-
-
-
-
-
-
 },
 980(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
 __webpack_require__.d(__webpack_exports__, {
@@ -3687,38 +3257,46 @@ var TrampolinePipeline = __webpack_require__(416);
 
 
 },
-771(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+454(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
 
 // EXPORTS
 __webpack_require__.d(__webpack_exports__, {
   DEFAULT_SEMI_JOIN_KEY_THRESHOLD: () => (/* reexport */ DEFAULT_SEMI_JOIN_KEY_THRESHOLD),
   TranslatedArrayValue: () => (/* reexport */ TranslatedArrayValue),
+  collectingSink: () => (/* reexport */ collectingSink),
   semiJoinFilter: () => (/* reexport */ semiJoinFilter),
   CacheDbPlugin: () => (/* reexport */ CacheDbPlugin),
   Query: () => (/* reexport */ Query),
   splitSendableOptions: () => (/* reexport */ splitSendableOptions),
   executeJoin: () => (/* reexport */ executeJoin),
+  formatExplanation: () => (/* reexport */ formatExplanation),
   serializePersistResult: () => (/* reexport */ serializePersistResult),
+  explainQuery: () => (/* reexport */ explainQuery),
+  cosineDistance: () => (/* reexport */ cosineDistance),
   RetryDbPlugin: () => (/* reexport */ RetryDbPlugin),
-  nearestBy: () => (/* reexport */ nearestBy),
   BatchingDbPlugin: () => (/* reexport */ BatchingDbPlugin),
   applyInnerOptions: () => (/* reexport */ applyInnerOptions),
-  TranslatedSingleValue: () => (/* reexport */ TranslatedSingleValue),
+  MEMORY_EXECUTION_EXPLANATIONS: () => (/* reexport */ MEMORY_EXECUTION_EXPLANATIONS),
   TupleTranslator: () => (/* reexport */ TupleTranslator),
-  cosineDistance: () => (/* reexport */ cosineDistance),
+  TranslatedSingleValue: () => (/* reexport */ TranslatedSingleValue),
   ConcurrencyDbPlugin: () => (/* reexport */ ConcurrencyDbPlugin),
   TranslatedGroupValue: () => (/* reexport */ TranslatedGroupValue),
   deserializeBulkPersist: () => (/* reexport */ deserializeBulkPersist),
+  EXECUTED_QUERIES_UNSUPPORTED: () => (/* reexport */ EXECUTED_QUERIES_UNSUPPORTED),
   joinInPlugin: () => (/* reexport */ joinInPlugin),
-  readJoinKey: () => (/* reexport */ readJoinKey),
   deserializePersistResult: () => (/* reexport */ deserializePersistResult),
-  toEntityShape: () => (/* reexport */ toEntityShape),
-  serializeBulkPersist: () => (/* reexport */ serializeBulkPersist),
+  loggerSink: () => (/* reexport */ loggerSink),
+  nearestBy: () => (/* reexport */ nearestBy),
+  readJoinKey: () => (/* reexport */ readJoinKey),
   hashJoin: () => (/* reexport */ hashJoin),
   EphemeralDataPlugin: () => (/* reexport */ EphemeralDataPlugin),
   QueryOptionsCollection: () => (/* reexport */ QueryOptionsCollection/* .QueryOptionsCollection */.H),
+  serializeBulkPersist: () => (/* reexport */ serializeBulkPersist),
+  toEntityShape: () => (/* reexport */ toEntityShape),
   loadJoinInnerSide: () => (/* reexport */ loadJoinInnerSide),
   DataTranslator: () => (/* reexport */ DataTranslator),
+  withExecutedQueries: () => (/* reexport */ withExecutedQueries),
+  TelemetryDbPlugin: () => (/* reexport */ TelemetryDbPlugin),
   createRequestHandler: () => (/* reexport */ createRequestHandler),
   SqlTranslator: () => (/* reexport */ SqlTranslator),
   QueryOrdering: () => (/* reexport */ types_QueryOrdering),
@@ -4260,7 +3838,11 @@ class Query {
         id: `${event.id}-inner`,
         source: event.source,
         action: "query",
-        reason: "join inner side"
+        reason: "join inner side",
+        explain: event.explain,
+        // The same array the outer read pushes into, so a join reports BOTH reads in execution
+        // order. Built fresh rather than spread, so this has to be carried explicitly.
+        executedQueries: event.executedQueries
     };
     query(innerEvent, (result)=>{
         if (result.ok === Result/* .PluginEventResult.ERROR */.D.ERROR) {
@@ -4960,6 +4542,386 @@ class SqlTranslator extends DataTranslator {
 
 
 
+;// CONCATENATED MODULE: ./src/plugins/query/explain.ts
+
+/**
+ * One sentence per reason code, written for someone meeting pushdown for the first time.
+ *
+ * Beside the codes rather than in the formatter, so console output, a failing test and the
+ * docs all say the same thing.
+ */ const MEMORY_EXECUTION_EXPLANATIONS = {
+    "not-parsable": "A filter could not be parsed into an expression tree, so it and every option after it run in memory.",
+    "unmapped-property": "The property is not stored in the database, so it can only be read after deserialization.",
+    "renamed-property": "The property is stored under a different name, and selectors use the in-memory name, so it can only be read after deserialization.",
+    "map-rename": "A map renames or drops properties, so every option after it refers to names the database does not have.",
+    "after-nearest": "A similarity search orders and limits rows, and the plugin cannot report whether it performed the search, so every option after it runs in memory.",
+    "after-join": "A join produces [outer, inner] tuples rather than entities, and the plugin cannot report how it joined, so every option after it runs in memory.",
+    "cross-plugin-join": "The two sides of this join live on different plugins, so neither can read the other's rows and the join runs in the datastore."
+};
+const EXECUTED_QUERIES_UNSUPPORTED = "This plugin did not report what it executed. It may not support explain.";
+const DATABASE_STEP_DESCRIPTION = "These options are sent to the plugin.";
+const MEMORY_STEP_DESCRIPTION = "Routier runs these over the rows the database returned, after deserializing them.";
+const UNNARROWED_READ_DESCRIPTION = "No option could be pushed down, so the plugin reads the whole collection.";
+/**
+ * The reportable shape of one option's value.
+ *
+ * Serializable facts only, never the live selector functions — an explanation is a document a
+ * caller may log, diff in a test, or send to a server, and a closure survives none of that.
+ */ const detailOf = (option)=>{
+    if (option.name === "filter") {
+        const value = option.value;
+        if (value.expression == null) {
+            return undefined;
+        }
+        try {
+            return {
+                expression: types/* .Expression.toJson */.r4.toJson(value.expression)
+            };
+        } catch  {
+            // `valueToJson` rejects a value no wire can carry. Reporting the rest of the
+            // explanation beats taking the diagnostic down with the query it describes.
+            return {
+                expressionUnavailable: "This filter holds a value that cannot be serialized."
+            };
+        }
+    }
+    if (option.name === "sort") {
+        const value = option.value;
+        return {
+            propertyName: value.propertyName,
+            direction: value.direction
+        };
+    }
+    if (option.name === "skip" || option.name === "take") {
+        return {
+            value: option.value
+        };
+    }
+    if (option.name === "nearest") {
+        const value = option.value;
+        return {
+            propertyName: value.propertyName,
+            dimensions: value.vector.length,
+            count: value.count
+        };
+    }
+    if (option.name === "join") {
+        const value = option.value;
+        return {
+            kind: value.kind,
+            outerKey: value.outerKey.propertyName,
+            innerKey: value.innerKey.propertyName,
+            crossPlugin: value.crossPlugin,
+            innerOptions: explainedOptionsOf(value.innerOptions)
+        };
+    }
+    if (option.name === "map" || option.name === "group") {
+        const value = option.value;
+        return {
+            fields: value.fields.map((x)=>({
+                    from: x.sourceName,
+                    to: x.destinationName
+                }))
+        };
+    }
+    return undefined;
+};
+const explainedOptionOf = (option, index)=>{
+    const detail = detailOf(option);
+    return {
+        index,
+        name: option.name,
+        ...detail == null ? {} : {
+            detail
+        }
+    };
+};
+const explainedOptionsOf = (options)=>{
+    const explained = [];
+    let index = 0;
+    options.forEach((option)=>explained.push(explainedOptionOf(option, index++)));
+    return explained;
+};
+const summarize = (steps)=>{
+    const reasons = [];
+    let database = 0;
+    let memory = 0;
+    for (const step of steps){
+        if (step.executedIn === "database") {
+            database += step.options.length;
+            continue;
+        }
+        memory += step.options.length;
+        if (step.reason != null && reasons.includes(step.reason) === false) {
+            reasons.push(step.reason);
+        }
+    }
+    const counts = `${database} ${database === 1 ? "option ran" : "options ran"} in the database, ${memory} ran in memory.`;
+    const causes = reasons.map((reason)=>MEMORY_EXECUTION_EXPLANATIONS[reason]).join(" ");
+    return {
+        database,
+        memory,
+        reasons,
+        explanation: causes.length === 0 ? counts : `${counts} ${causes}`
+    };
+};
+/**
+ * Groups options into consecutive runs that execute in the same place.
+ *
+ * A step boundary is where execution moves, and a reader has to see the statement as step 1 OF
+ * 2 to understand it is not the whole query. Cutting over to memory is a ratchet, so the
+ * database options are always a prefix and there are at most two steps.
+ *
+ * A database step is emitted even when NO option pushed down, because the plugin is dispatched
+ * either way — `createQueryPayload` always builds a database event. Without it, the worst case
+ * the feature exists to expose reports "0 in the database" while the backend reads the whole
+ * table, which is the opposite of the truth.
+ */ const toExecutionSteps = (options)=>{
+    const steps = [];
+    let index = 0;
+    options.forEach((option)=>{
+        const explained = explainedOptionOf(option, index++);
+        const current = steps[steps.length - 1];
+        if (current != null && current.executedIn === option.target) {
+            current.options.push(explained);
+            return;
+        }
+        steps.push({
+            step: steps.length + 1,
+            of: 0,
+            executedIn: option.target,
+            description: option.target === "database" ? DATABASE_STEP_DESCRIPTION : MEMORY_STEP_DESCRIPTION,
+            options: [
+                explained
+            ],
+            ...option.reason == null ? {} : {
+                reason: option.reason,
+                explanation: MEMORY_EXECUTION_EXPLANATIONS[option.reason]
+            }
+        });
+    });
+    if (steps[0]?.executedIn !== "database") {
+        steps.unshift({
+            step: 0,
+            of: 0,
+            executedIn: "database",
+            description: UNNARROWED_READ_DESCRIPTION,
+            options: []
+        });
+    }
+    for(let i = 0; i < steps.length; i++){
+        steps[i].step = i + 1;
+        steps[i].of = steps.length;
+    }
+    return steps;
+};
+/**
+ * Builds the explanation from the resolved options, with no plugin involvement.
+ *
+ * Takes the collection BEFORE `split()`, and throws otherwise. Splitting re-adds each half
+ * into a fresh collection, which re-derives targets without the options that caused them — a
+ * post-join filter alone in the memory half derives back to `"database"`, and the document
+ * would report memory work as having run in the database.
+ */ const explainQuery = (options, context)=>{
+    if (options.isDerived === true) {
+        throw new Error("explainQuery was given a collection produced by split() or splitAt(). Those re-derive " + "execution targets without the options that caused them, so the explanation would report " + "memory work as having run in the database. Pass the collection as it was resolved, " + "before splitting.");
+    }
+    const executionSteps = toExecutionSteps(options);
+    return {
+        collection: context.collection,
+        database: context.database,
+        summary: summarize(executionSteps),
+        executionSteps,
+        plugin: {
+            kind: context.pluginKind
+        }
+    };
+};
+/**
+ * Attaches what the backend reported to the step that was sent to it.
+ *
+ * Reporting is optional for a plugin, so an empty report is not an error: the step is marked
+ * `executedQueriesUnsupported` instead, and the rest of the explanation stands — the pushdown
+ * analysis comes from the options and is correct with or without the plugin's statements.
+ *
+ * Copies the steps rather than writing into them, so the explanation a caller already holds
+ * does not gain statements after the fact. Options and their details are shared with the
+ * original — nothing mutates them, and copying deeper would only look safer than it is.
+ */ const withExecutedQueries = (explanation, executedQueries)=>{
+    let attached = false;
+    const executionSteps = explanation.executionSteps.map((step)=>{
+        // Only the first database step: a plugin reports what IT ran, and everything it ran
+        // was sent as one dispatch. Stamping the same statements onto a second database step
+        // would claim they ran twice.
+        if (step.executedIn !== "database" || attached === true) {
+            return {
+                ...step,
+                options: [
+                    ...step.options
+                ]
+            };
+        }
+        attached = true;
+        if (executedQueries.length === 0) {
+            return {
+                ...step,
+                options: [
+                    ...step.options
+                ],
+                executedQueriesUnsupported: EXECUTED_QUERIES_UNSUPPORTED
+            };
+        }
+        return {
+            ...step,
+            options: [
+                ...step.options
+            ],
+            executedQueries: [
+                ...executedQueries
+            ]
+        };
+    });
+    return {
+        ...explanation,
+        executionSteps
+    };
+};
+
+;// CONCATENATED MODULE: ./src/plugins/query/formatExplanation.ts
+const OPTION_LABEL_WIDTH = 8;
+const WRAP_WIDTH = 68;
+/** Wraps `text` to `WRAP_WIDTH`, prefixing every line with `indent`. */ const wrap = (text, indent)=>{
+    const lines = [];
+    let line = "";
+    for (const word of text.split(" ")){
+        if (line.length > 0 && line.length + word.length + 1 > WRAP_WIDTH) {
+            lines.push(indent + line);
+            line = word;
+            continue;
+        }
+        line = line.length === 0 ? word : `${line} ${word}`;
+    }
+    if (line.length > 0) {
+        lines.push(indent + line);
+    }
+    return lines;
+};
+const COMPARATOR_SYMBOLS = {
+    "equals": "===",
+    "greater-than": ">",
+    "greater-than-equals": ">=",
+    "less-than": "<",
+    "less-than-equals": "<="
+};
+const describeValue = (value)=>{
+    if (value == null) {
+        return "?";
+    }
+    if (value.k === "raw") {
+        return typeof value.v === "string" ? `"${value.v}"` : String(value.v);
+    }
+    if (value.k === "date") {
+        return value.v;
+    }
+    if (value.k === "array") {
+        return `[${value.v.map(describeValue).join(", ")}]`;
+    }
+    return value.k === "undefined" ? "undefined" : String(value.v);
+};
+/** Renders a serialized expression back to something close to the source predicate. */ const describeExpression = (expression)=>{
+    if (expression == null) {
+        return "?";
+    }
+    if (expression.t === "operator") {
+        return `${describeExpression(expression.left)} ${expression.operator} ${describeExpression(expression.right)}`;
+    }
+    if (expression.t === "comparator") {
+        const left = describeExpression(expression.left);
+        const right = describeExpression(expression.right);
+        const symbol = COMPARATOR_SYMBOLS[expression.comparator];
+        if (symbol == null) {
+            return `${left}.${expression.comparator}(${right})${expression.negated === true ? " === false" : ""}`;
+        }
+        return `${left} ${expression.negated === true ? "!==" : symbol} ${right}`;
+    }
+    if (expression.t === "property") {
+        return expression.path;
+    }
+    if (expression.t === "value") {
+        return describeValue(expression.value);
+    }
+    return expression.t === "empty" ? "(no filter)" : "(not parsable)";
+};
+const describeOption = (option)=>{
+    const detail = option.detail;
+    if (detail == null) {
+        return "";
+    }
+    if (option.name === "filter") {
+        return detail.expression == null ? String(detail.expressionUnavailable ?? "") : describeExpression(detail.expression);
+    }
+    if (option.name === "sort") {
+        return `${detail.propertyName} ${detail.direction}`;
+    }
+    if (option.name === "skip" || option.name === "take") {
+        return String(detail.value);
+    }
+    if (option.name === "join") {
+        return `${detail.kind} → ${detail.outerKey} = ${detail.innerKey}`;
+    }
+    if (option.name === "nearest") {
+        return `${detail.propertyName}, ${detail.count} nearest`;
+    }
+    if (option.name === "map" || option.name === "group") {
+        const fields = detail.fields;
+        return fields.map((x)=>x.from === x.to ? x.from : `${x.from} → ${x.to}`).join(", ");
+    }
+    return "";
+};
+const formatStep = (step, lines)=>{
+    const reason = step.reason == null ? "" : `  [${step.reason}]`;
+    lines.push(`  STEP ${step.step} of ${step.of} — ${step.executedIn}${reason}`);
+    lines.push(...wrap(step.description, "    "));
+    if (step.explanation != null) {
+        lines.push(...wrap(step.explanation, "    "));
+    }
+    lines.push("");
+    for (const option of step.options){
+        lines.push(`    ${option.name.padEnd(OPTION_LABEL_WIDTH)} ${describeOption(option)}`.trimEnd());
+    }
+    for (const executed of step.executedQueries ?? []){
+        lines.push("");
+        lines.push(...executed.text.split("\n").map((line)=>`    ${line}`));
+        if (executed.parameters != null && executed.parameters.length > 0) {
+            lines.push(`    parameters: ${JSON.stringify(executed.parameters)}`);
+        }
+    }
+    if (step.executedQueriesUnsupported != null) {
+        lines.push("");
+        lines.push(...wrap(step.executedQueriesUnsupported, "    "));
+    }
+    lines.push("");
+};
+/**
+ * Renders an explanation for a terminal.
+ *
+ * The STEP headers carry the whole lesson: a reader who has never heard of pushdown still sees
+ * that the statement in step 1 is not the entire query. Nobody should have to notice a missing
+ * ORDER BY to work that out.
+ */ const formatExplanation = (explanation)=>{
+    const { collection, database, summary, executionSteps } = explanation;
+    const stepCount = `${executionSteps.length} ${executionSteps.length === 1 ? "step" : "steps"}`;
+    const lines = [
+        `${collection} · ${database} · ${stepCount}`,
+        ""
+    ];
+    for (const step of executionSteps){
+        formatStep(step, lines);
+    }
+    lines.push(...wrap(summary.explanation, "  "));
+    return lines.join("\n");
+};
+
 ;// CONCATENATED MODULE: ./src/plugins/query/types.ts
 var types_QueryOrdering = /*#__PURE__*/ function(QueryOrdering) {
     QueryOrdering["Descending"] = "desc";
@@ -4974,6 +4936,8 @@ var types_QueryOrdering = /*#__PURE__*/ function(QueryOrdering) {
 
 
 
+
+
 // EXTERNAL MODULE: ./src/expressions/evaluate.ts
 var evaluate = __webpack_require__(379);
 ;// CONCATENATED MODULE: ./src/plugins/wire/query.ts
@@ -5445,6 +5409,7 @@ const createRequestHandler = (options)=>{
                 const queryOptions = deserializeQueryOptions(request.options, schema, resolveSchema, // Applied to the outer collection AND to every collection a join reaches, so a
                 // join cannot be used to read around a scope
                 (target)=>scopeExpressionFor(target, context, "query"));
+                const executedQueries = [];
                 return await new Promise((resolve)=>{
                     plugin.query({
                         // `false`: nothing here attaches to a change tracker — the tracker lives on
@@ -5453,7 +5418,9 @@ const createRequestHandler = (options)=>{
                         schemas: schemas,
                         id: (0,uuid/* .uuid */.u)(8),
                         source: "RequestHandler",
-                        action: "query"
+                        action: "query",
+                        explain: request.explain,
+                        executedQueries
                     }, (result)=>{
                         if (result.ok === Result/* .PluginEventResult.ERROR */.D.ERROR) {
                             resolve(failed(result.error));
@@ -5462,7 +5429,13 @@ const createRequestHandler = (options)=>{
                         resolve({
                             ok: true,
                             kind: "query",
-                            value: result.data.value
+                            value: result.data.value,
+                            // Only when asked, and only what the plugin reported. A plugin
+                            // that reported nothing sends nothing, and the caller marks the
+                            // remote step as not reported.
+                            ...request.explain === true && executedQueries.length > 0 ? {
+                                executedQueries
+                            } : {}
                         });
                     });
                 });
@@ -6111,6 +6084,10 @@ class EphemeralDataPlugin {
                 }
                 innerRows.push(cloneRecord(record));
             }
+            const narrowing = outerKeys == null ? "full scan" : `narrowed by ${outerKeys.size} outer ${outerKeys.size === 1 ? "key" : "keys"}`;
+            event.executedQueries.push({
+                text: `${innerSchema.collectionName}: scanned ${innerRows.length} in-memory ${innerRows.length === 1 ? "record" : "records"} for join inner side (${narrowing})`
+            });
             done({
                 ok: "success",
                 innerSide: {
@@ -6220,7 +6197,13 @@ class EphemeralDataPlugin {
                  * collection to pair it with three rows.
                  *
                  * `cloned` is in storage shape, so the keys are read by resolved column name.
-                 */ const joinOption = operation.options.getLast("join");
+                 */ // No statement to quote — an ephemeral store walks its own records. Said
+                // plainly so `.explain()` does not leave a reader wondering whether the
+                // plugin simply failed to report. Before the inner side, to match execution order.
+                event.executedQueries.push({
+                    text: `${operation.schema.collectionName}: scanned ${cloned.length} in-memory ${cloned.length === 1 ? "record" : "records"}`
+                });
+                const joinOption = operation.options.getLast("join");
                 const outerKeys = joinOption == null ? null : distinctJoinKeys(cloned, joinOption.value.outerKey, joinOption.value.semiJoinKeyThreshold, {
                     storageShape: true
                 });
@@ -6304,6 +6287,69 @@ class RetryDbPlugin {
     }
 }
 
+;// CONCATENATED MODULE: ./src/plugins/TelemetryDbPlugin.ts
+
+/** Default sink: writes through the levelled logger, so ROUTIER_LOG_LEVEL governs it. */ const loggerSink = ()=>(e)=>{
+        const line = `[routier] ${e.operation} ${e.schemas.join(",")} ${e.durationMs.toFixed(1)}ms`;
+        if (e.ok === "error") {
+            logger/* .logger.error */.vF.error(line, e.error);
+            return;
+        }
+        logger/* .logger.info */.vF.info(line);
+    };
+/** Pushes every event into `into`. For tests and custom buffering. */ const collectingSink = (into)=>(e)=>{
+        into.push(e);
+    };
+class TelemetryDbPlugin {
+    plugin;
+    onEvent;
+    constructor(plugin, options = {}){
+        this.plugin = plugin;
+        this.onEvent = options.onEvent ?? loggerSink();
+    }
+    get databaseName() {
+        return this.plugin.databaseName;
+    }
+    query(event, done) {
+        const start = performance.now();
+        this.plugin.query(event, (result)=>{
+            this.emit("query", event, result, start);
+            done(result);
+        });
+    }
+    bulkPersist(event, done) {
+        const start = performance.now();
+        this.plugin.bulkPersist(event, (result)=>{
+            this.emit("bulkPersist", event, result, start);
+            done(result);
+        });
+    }
+    destroy(event, done) {
+        const start = performance.now();
+        this.plugin.destroy(event, (result)=>{
+            this.emit("destroy", event, result, start);
+            done(result);
+        });
+    }
+    emit(operation, event, result, start) {
+        try {
+            this.onEvent({
+                operation,
+                eventId: event.id,
+                source: event.source,
+                schemas: [
+                    ...event.schemas.values()
+                ].map((s)=>s.collectionName),
+                durationMs: performance.now() - start,
+                ok: result.ok,
+                error: result.ok === "success" ? undefined : result.error
+            });
+        } catch  {
+        // A broken sink must never fail the data operation.
+        }
+    }
+}
+
 ;// CONCATENATED MODULE: ./src/plugins/CacheDbPlugin.ts
 
 /**
@@ -6313,7 +6359,7 @@ class RetryDbPlugin {
  * `PropertyInfo` objects carrying functions and would not survive `JSON.stringify`. A filter is
  * identified by its source text plus its params, which is what the expression is derived from
  * anyway — two queries with the same source and params are the same query.
- */ const describeOption = (option)=>{
+ */ const CacheDbPlugin_describeOption = (option)=>{
     const value = option.value;
     switch(option.name){
         case "filter":
@@ -6347,7 +6393,7 @@ class CacheDbPlugin {
     /** `schemaId` first, so invalidating a schema is a prefix match. */ keyFor(event) {
         const parts = [];
         event.operation.options.forEach((option)=>{
-            parts.push(`${option.name}:${describeOption(option)}`);
+            parts.push(`${option.name}:${CacheDbPlugin_describeOption(option)}`);
         });
         return `${String(event.operation.schema.id)}\u0000${parts.join("\u0001")}`;
     }
@@ -6377,6 +6423,12 @@ class CacheDbPlugin {
             // Re-set to move it to the end of the insertion order: most recently used.
             this.entries.delete(key);
             this.entries.set(key, cached);
+            // Said rather than left blank. A hit means no database was touched, which is a fact
+            // worth reporting — and an empty report would otherwise read as a plugin that failed
+            // to say what it ran.
+            event.executedQueries.push({
+                text: "cache hit — no query was executed"
+            });
             done(Result/* .PluginEventResult.success */.D.success(event.id, this.rebuild(cached)));
             return;
         }
@@ -6762,6 +6814,7 @@ const DEFAULT_MAX_BATCH_SIZE = 100;
 
 
 
+
 },
 198(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
 __webpack_require__.d(__webpack_exports__, {
@@ -6774,8 +6827,26 @@ __webpack_require__.d(__webpack_exports__, {
 class QueryOptionsCollection {
     options = new Map();
     nextExecutionTarget = "database";
+    nextExecutionReason = null;
     nextIndex = 0;
     enumeratedItems = [];
+    /** Cuts over to memory execution, keeping the first cause. See `MemoryExecutionReason`. */ cutOverToMemory(reason) {
+        this.nextExecutionTarget = "memory";
+        if (this.nextExecutionReason == null) {
+            this.nextExecutionReason = reason;
+        }
+    }
+    /**
+     * True when `split()` or `splitAt()` produced this collection.
+     *
+     * Those rebuild each half by re-adding its options, which re-derives execution targets
+     * without the options that caused them — a post-join filter alone in the memory half
+     * derives back to `"database"`. Anything reading `target` as a report of where work runs
+     * has to reject a derived collection; see `explainQuery`.
+     */ derived = false;
+    get isDerived() {
+        return this.derived;
+    }
     get items() {
         return this.options;
     }
@@ -6796,7 +6867,7 @@ class QueryOptionsCollection {
             if (mapValue.fields.some((x)=>x.isRename === true) || mapValue.fields.some((x)=>x.property?.isUnmapped === true)) {
                 // Cut over to memory execution since we are renaming a property with .map
                 // We do not want to figure out how the new name flows through the entire query
-                this.nextExecutionTarget = "memory";
+                this.cutOverToMemory("map-rename");
             }
         }
         if (name === "filter") {
@@ -6808,13 +6879,13 @@ class QueryOptionsCollection {
                 return;
             }
             if (filterValue.expression.type === "not-parsable") {
-                this.nextExecutionTarget = "memory";
+                this.cutOverToMemory("not-parsable");
             } else {
                 (0,_expressions_utils__rspack_import_0/* .forEach */.j)(filterValue.expression, (expression)=>{
                     if ((0,_assertions__rspack_import_1.isPropertyExpression)(expression) && expression.property.isUnmapped) {
                         // Cut over to memory execution, unmapped properties are not in the database and
                         // cannot be queried
-                        this.nextExecutionTarget = "memory";
+                        this.cutOverToMemory("unmapped-property");
                         return false;
                     }
                     if ((0,_assertions__rspack_import_1.isPropertyExpression)(expression) && expression.property.hasRenamedSegments) {
@@ -6822,7 +6893,7 @@ class QueryOptionsCollection {
                         // `from` (storage) names, but filter selectors reference the
                         // in-memory names.  Memory execution runs after deserialization,
                         // where the in-memory names exist
-                        this.nextExecutionTarget = "memory";
+                        this.cutOverToMemory("renamed-property");
                         return false;
                     }
                     return true;
@@ -6833,8 +6904,10 @@ class QueryOptionsCollection {
             const sortValue = value;
             // Same rule as filters: sort selectors reference in-memory names, which
             // only exist after deserialization when the property is renamed or unmapped
-            if (sortValue.property != null && (sortValue.property.isUnmapped || sortValue.property.hasRenamedSegments)) {
-                this.nextExecutionTarget = "memory";
+            if (sortValue.property != null && sortValue.property.isUnmapped) {
+                this.cutOverToMemory("unmapped-property");
+            } else if (sortValue.property != null && sortValue.property.hasRenamedSegments) {
+                this.cutOverToMemory("renamed-property");
             }
         }
         if (name === "nearest") {
@@ -6845,8 +6918,10 @@ class QueryOptionsCollection {
             //
             // This is also what lets every translator's in-memory fallback read the column by
             // its resolved name — anything whose storage name differs never reaches them.
-            if (nearestValue.property != null && (nearestValue.property.isUnmapped || nearestValue.property.hasRenamedSegments)) {
-                this.nextExecutionTarget = "memory";
+            if (nearestValue.property != null && nearestValue.property.isUnmapped) {
+                this.cutOverToMemory("unmapped-property");
+            } else if (nearestValue.property != null && nearestValue.property.hasRenamedSegments) {
+                this.cutOverToMemory("renamed-property");
             }
         }
         if (name === "join") {
@@ -6858,7 +6933,7 @@ class QueryOptionsCollection {
             // Set BEFORE the item is created, unlike `nearest`'s ratchet below, because this
             // moves the join option itself rather than everything after it.
             if (joinValue.crossPlugin === true) {
-                this.nextExecutionTarget = "memory";
+                this.cutOverToMemory("cross-plugin-join");
             }
         }
         const item = {
@@ -6866,7 +6941,10 @@ class QueryOptionsCollection {
             option: {
                 name,
                 target: this.nextExecutionTarget,
-                value
+                value,
+                ...this.nextExecutionReason == null ? {} : {
+                    reason: this.nextExecutionReason
+                }
             }
         };
         this.nextIndex++;
@@ -6889,7 +6967,7 @@ class QueryOptionsCollection {
             //
             // A plugin that DID push the search down loses nothing but the chance to also
             // push down what follows it, which is a limit over ten rows.
-            this.nextExecutionTarget = "memory";
+            this.cutOverToMemory("after-nearest");
         }
         if (name === "join") {
             // Everything AFTER a join runs in memory, for the same reason as `nearest`: this
@@ -6900,7 +6978,7 @@ class QueryOptionsCollection {
             // OUTER rows read, not the pairs produced — a plausible-looking result with the
             // wrong number of rows in it. Conjuncts that can safely run earlier are split off
             // by the query builder BEFORE dispatch, which is the only exception.
-            this.nextExecutionTarget = "memory";
+            this.cutOverToMemory("after-join");
         }
     }
     /**
@@ -6914,6 +6992,8 @@ class QueryOptionsCollection {
         const sortedItems = this.enumeratedItems.toSorted((a, b)=>a.index - b.index);
         const before = new QueryOptionsCollection();
         const after = new QueryOptionsCollection();
+        before.derived = true;
+        after.derived = true;
         let at = null;
         for(let i = 0, length = sortedItems.length; i < length; i++){
             const { option } = sortedItems[i];
@@ -6947,10 +7027,12 @@ class QueryOptionsCollection {
                 ]
             ]));
         const nextExecutionTarget = this.nextExecutionTarget;
+        const nextExecutionReason = this.nextExecutionReason;
         const nextIndex = this.nextIndex;
         return ()=>{
             this.options = new Map(options);
             this.nextExecutionTarget = nextExecutionTarget;
+            this.nextExecutionReason = nextExecutionReason;
             this.nextIndex = nextIndex;
             this.enumeratedItems = [];
         };
@@ -6960,6 +7042,8 @@ class QueryOptionsCollection {
         const sortedItems = this.enumeratedItems.toSorted((a, b)=>a.index - b.index);
         const memoryQueryOptionsCollection = new QueryOptionsCollection();
         const databaseQueryOptionsCollection = new QueryOptionsCollection();
+        memoryQueryOptionsCollection.derived = true;
+        databaseQueryOptionsCollection.derived = true;
         for(let i = 0, length = sortedItems.length; i < length; i++){
             const sortedItem = sortedItems[i];
             if (sortedItem.option.target === "database") {
@@ -13736,13 +13820,13 @@ __webpack_require__.d(__webpack_exports__, {
   BulkPersistChanges: () => (/* reexport safe */ _collections__rspack_import_2.BulkPersistChanges),
   BulkPersistResult: () => (/* reexport safe */ _collections__rspack_import_2.BulkPersistResult),
   CacheDbPlugin: () => (/* reexport safe */ _plugins__rspack_import_7.CacheDbPlugin),
-  Capability: () => (/* reexport safe */ _capabilities__rspack_import_11.Capability),
   CodeBuilder: () => (/* reexport safe */ _codegen__rspack_import_1.CodeBuilder),
   ComparatorExpression: () => (/* reexport safe */ _expressions__rspack_import_4.ComparatorExpression),
   ConcurrencyDbPlugin: () => (/* reexport safe */ _plugins__rspack_import_7.ConcurrencyDbPlugin),
   ContainerBlock: () => (/* reexport safe */ _codegen__rspack_import_1.ContainerBlock),
   DEFAULT_SEMI_JOIN_KEY_THRESHOLD: () => (/* reexport safe */ _plugins__rspack_import_7.DEFAULT_SEMI_JOIN_KEY_THRESHOLD),
   DataTranslator: () => (/* reexport safe */ _plugins__rspack_import_7.DataTranslator),
+  EXECUTED_QUERIES_UNSUPPORTED: () => (/* reexport safe */ _plugins__rspack_import_7.EXECUTED_QUERIES_UNSUPPORTED),
   EXPRESSION_TYPES: () => (/* reexport safe */ _expressions__rspack_import_4.EXPRESSION_TYPES),
   EmptyExpression: () => (/* reexport safe */ _expressions__rspack_import_4.EmptyExpression),
   EphemeralDataPlugin: () => (/* reexport safe */ _plugins__rspack_import_7.EphemeralDataPlugin),
@@ -13754,12 +13838,12 @@ __webpack_require__.d(__webpack_exports__, {
   IfBuilder: () => (/* reexport safe */ _codegen__rspack_import_1.IfBuilder),
   JsonTranslator: () => (/* reexport safe */ _plugins__rspack_import_7.JsonTranslator),
   LOG_LEVELS: () => (/* reexport safe */ _utilities__rspack_import_10.LOG_LEVELS),
+  MEMORY_EXECUTION_EXPLANATIONS: () => (/* reexport safe */ _plugins__rspack_import_7.MEMORY_EXECUTION_EXPLANATIONS),
   MemoryDataCollection: () => (/* reexport safe */ _collections__rspack_import_2.MemoryDataCollection),
   NotParsableExpression: () => (/* reexport safe */ _expressions__rspack_import_4.NotParsableExpression),
   ObjectBuilder: () => (/* reexport safe */ _codegen__rspack_import_1.ObjectBuilder),
   OperatorExpression: () => (/* reexport safe */ _expressions__rspack_import_4.OperatorExpression),
   OptimisticConcurrencyError: () => (/* reexport safe */ _errors__rspack_import_3.OptimisticConcurrencyError),
-  PerformanceCapability: () => (/* reexport safe */ _capabilities__rspack_import_11.PerformanceCapability),
   PluginDestroyedError: () => (/* reexport safe */ _errors__rspack_import_3.PluginDestroyedError),
   PluginEventResult: () => (/* reexport safe */ _results__rspack_import_8.PluginEventResult),
   PropertyExpression: () => (/* reexport safe */ _expressions__rspack_import_4.PropertyExpression),
@@ -13809,7 +13893,7 @@ __webpack_require__.d(__webpack_exports__, {
   StringBuilder: () => (/* reexport safe */ _codegen__rspack_import_1.StringBuilder),
   SyncronousQueue: () => (/* reexport safe */ _pipeline__rspack_import_6.SyncronousQueue),
   TagCollection: () => (/* reexport safe */ _collections__rspack_import_2.TagCollection),
-  TracingCapability: () => (/* reexport safe */ _capabilities__rspack_import_11.TracingCapability),
+  TelemetryDbPlugin: () => (/* reexport safe */ _plugins__rspack_import_7.TelemetryDbPlugin),
   TrampolinePipeline: () => (/* reexport safe */ _pipeline__rspack_import_6.TrampolinePipeline),
   TranslatedArrayValue: () => (/* reexport safe */ _plugins__rspack_import_7.TranslatedArrayValue),
   TranslatedGroupValue: () => (/* reexport safe */ _plugins__rspack_import_7.TranslatedGroupValue),
@@ -13827,6 +13911,7 @@ __webpack_require__.d(__webpack_exports__, {
   assertString: () => (/* reexport safe */ _assertions__rspack_import_0.assertString),
   cast: () => (/* reexport safe */ _utilities__rspack_import_10.cast),
   clone: () => (/* reexport safe */ _utilities__rspack_import_10.clone),
+  collectingSink: () => (/* reexport safe */ _plugins__rspack_import_7.collectingSink),
   combineExpressions: () => (/* reexport safe */ _expressions__rspack_import_4.combineExpressions),
   combineQueryOptionsCollections: () => (/* reexport safe */ _utilities__rspack_import_10.combineQueryOptionsCollections),
   compiledSchemaToJsonSchema: () => (/* reexport safe */ _schema__rspack_import_9.compiledSchemaToJsonSchema),
@@ -13839,9 +13924,11 @@ __webpack_require__.d(__webpack_exports__, {
   distinctJoinKeys: () => (/* reexport safe */ _plugins__rspack_import_7.distinctJoinKeys),
   evaluate: () => (/* reexport safe */ _expressions__rspack_import_4.evaluate),
   executeJoin: () => (/* reexport safe */ _plugins__rspack_import_7.executeJoin),
+  explainQuery: () => (/* reexport safe */ _plugins__rspack_import_7.explainQuery),
   extractTypeInfo: () => (/* reexport safe */ _schema__rspack_import_9.extractTypeInfo),
   fastHash: () => (/* reexport safe */ _utilities__rspack_import_10.fastHash),
   forEach: () => (/* reexport safe */ _expressions__rspack_import_4.forEach),
+  formatExplanation: () => (/* reexport safe */ _plugins__rspack_import_7.formatExplanation),
   getLogLevel: () => (/* reexport safe */ _utilities__rspack_import_10.getLogLevel),
   getProperties: () => (/* reexport safe */ _expressions__rspack_import_4.getProperties),
   hasPrimitiveElements: () => (/* reexport safe */ _schema__rspack_import_9.hasPrimitiveElements),
@@ -13861,6 +13948,7 @@ __webpack_require__.d(__webpack_exports__, {
   joinInPlugin: () => (/* reexport safe */ _plugins__rspack_import_7.joinInPlugin),
   loadJoinInnerSide: () => (/* reexport safe */ _plugins__rspack_import_7.loadJoinInnerSide),
   logger: () => (/* reexport safe */ _utilities__rspack_import_10.logger),
+  loggerSink: () => (/* reexport safe */ _plugins__rspack_import_7.loggerSink),
   measure: () => (/* reexport safe */ _performance__rspack_import_5.measure),
   nearestBy: () => (/* reexport safe */ _plugins__rspack_import_7.nearestBy),
   noop: () => (/* reexport safe */ _utilities__rspack_import_10.noop),
@@ -13889,7 +13977,8 @@ __webpack_require__.d(__webpack_exports__, {
   toStrictPredicate: () => (/* reexport safe */ _expressions__rspack_import_4.toStrictPredicate),
   unsafeCast: () => (/* reexport safe */ _utilities__rspack_import_10.unsafeCast),
   uuid: () => (/* reexport safe */ _utilities__rspack_import_10.uuid),
-  uuidv4: () => (/* reexport safe */ _utilities__rspack_import_10.uuidv4)
+  uuidv4: () => (/* reexport safe */ _utilities__rspack_import_10.uuidv4),
+  withExecutedQueries: () => (/* reexport safe */ _plugins__rspack_import_7.withExecutedQueries)
 });
 /* import */ var _assertions__rspack_import_0 = __webpack_require__(126);
 /* import */ var _codegen__rspack_import_1 = __webpack_require__(80);
@@ -13898,12 +13987,10 @@ __webpack_require__.d(__webpack_exports__, {
 /* import */ var _expressions__rspack_import_4 = __webpack_require__(138);
 /* import */ var _performance__rspack_import_5 = __webpack_require__(971);
 /* import */ var _pipeline__rspack_import_6 = __webpack_require__(314);
-/* import */ var _plugins__rspack_import_7 = __webpack_require__(771);
+/* import */ var _plugins__rspack_import_7 = __webpack_require__(454);
 /* import */ var _results__rspack_import_8 = __webpack_require__(264);
 /* import */ var _schema__rspack_import_9 = __webpack_require__(755);
 /* import */ var _utilities__rspack_import_10 = __webpack_require__(222);
-/* import */ var _capabilities__rspack_import_11 = __webpack_require__(599);
-