@routier/core 0.3.0 → 0.4.0

package/dist/plugins/index.cjs

@@ -2398,8 +2398,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;
     }
@@ -2420,7 +2438,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") {
@@ -2432,13 +2450,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) {
@@ -2446,7 +2464,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;
@@ -2457,8 +2475,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") {
@@ -2469,8 +2489,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") {
@@ -2482,7 +2504,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 = {
@@ -2490,7 +2512,10 @@ class QueryOptionsCollection {
             option: {
                 name,
                 target: this.nextExecutionTarget,
-                value
+                value,
+                ...this.nextExecutionReason == null ? {} : {
+                    reason: this.nextExecutionReason
+                }
             }
         };
         this.nextIndex++;
@@ -2513,7 +2538,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
@@ -2524,7 +2549,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");
         }
     }
     /**
@@ -2538,6 +2563,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];
@@ -2571,10 +2598,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 = [];
         };
@@ -2584,6 +2613,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") {
@@ -3033,27 +3064,32 @@ __webpack_require__.d(__webpack_exports__, {
   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),
+  nearestBy: () => (/* reexport */ nearestBy),
+  readJoinKey: () => (/* reexport */ readJoinKey),
   serializeBulkPersist: () => (/* reexport */ serializeBulkPersist),
   hashJoin: () => (/* reexport */ hashJoin),
   EphemeralDataPlugin: () => (/* reexport */ EphemeralDataPlugin),
   QueryOptionsCollection: () => (/* reexport */ QueryOptionsCollection/* .QueryOptionsCollection */.H),
+  toEntityShape: () => (/* reexport */ toEntityShape),
   loadJoinInnerSide: () => (/* reexport */ loadJoinInnerSide),
   DataTranslator: () => (/* reexport */ DataTranslator),
+  withExecutedQueries: () => (/* reexport */ withExecutedQueries),
   createRequestHandler: () => (/* reexport */ createRequestHandler),
   SqlTranslator: () => (/* reexport */ SqlTranslator),
   QueryOrdering: () => (/* reexport */ types_QueryOrdering),
@@ -3595,7 +3631,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) {
@@ -4295,6 +4335,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";
@@ -4309,6 +4729,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
@@ -4780,6 +5202,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
@@ -4788,7 +5211,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));
@@ -4797,7 +5222,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
+                            } : {}
                         });
                     });
                 });
@@ -5446,6 +5877,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: {
@@ -5555,7 +5990,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
                 });
@@ -5648,7 +6089,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":
@@ -5682,7 +6123,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")}`;
     }
@@ -5712,6 +6153,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;
         }