@lossless.org/client 1.13.0 → 1.14.0

package/dist_ts/nosqldb/classes.queryplaninspection.d.ts

@@ -0,0 +1,65 @@
+import * as plugins from './plugins.js';
+import type { SmartdataDb } from './classes.db.js';
+import type { MongoFilter, TSmartdataProjection, TSmartdataSort } from './classes.doc.js';
+export interface ISmartdataQueryPlanOptions<T> {
+    /** Validated exactly like the filter of the model's ordinary reads. */
+    filter: MongoFilter<T>;
+    /** Declared paths or `_id`, each 1 or -1, as for `getCursor()` and `getOffsetPage()`. */
+    sort?: TSmartdataSort<T>;
+    /** Declared paths or `_id`, 0 or 1, as for `getCursor()` and `getOffsetPage()`. */
+    projection?: TSmartdataProjection<T>;
+    /** 1..10000. Without it the plan executes over every match. */
+    limit?: number;
+    /** Client deadline for the explained execution. Default 5000ms, maximum 120000ms. */
+    timeoutMS?: number;
+    signal?: AbortSignal;
+}
+/** One stage of the winning plan, in depth-first order from the root. */
+export interface ISmartdataQueryPlanStage {
+    /** The engine's stage name, such as `IXSCAN`, `COLLSCAN`, `FETCH`, `SORT` or `LIMIT`. */
+    readonly stage: string;
+    /** 0 for the root; a stage's inputs follow it at one level deeper. */
+    readonly depth: number;
+    /** The index the stage reads, when the engine names one. */
+    readonly indexName?: string;
+    /** The scan direction, when the engine states one. */
+    readonly direction?: 'forward' | 'backward';
+}
+export interface ISmartdataQueryPlan {
+    /** The winning plan's stage tree, flattened depth-first. */
+    readonly stages: readonly ISmartdataQueryPlanStage[];
+    readonly nReturned: number;
+    readonly totalKeysExamined: number;
+    readonly totalDocsExamined: number;
+    /** Present when the engine reports it. */
+    readonly executionTimeMillis?: number;
+}
+/** @internal The query-plan options after their bounds are checked. */
+export interface IValidatedQueryPlanOptions<T> {
+    readonly filter: MongoFilter<T>;
+    readonly sort: TSmartdataSort<T> | undefined;
+    readonly projection: TSmartdataProjection<T> | undefined;
+    readonly limit: number | undefined;
+    readonly timeoutMS: number;
+    readonly signal: AbortSignal | undefined;
+}
+/** @internal The normalized query one inspection explains. */
+export interface IQueryPlanRequest {
+    readonly collectionName: string;
+    readonly filter: plugins.mongodb.Filter<plugins.mongodb.Document>;
+    readonly sort: plugins.mongodb.Sort | undefined;
+    readonly projection: plugins.mongodb.Document | undefined;
+    readonly limit: number | undefined;
+    readonly timeoutMS: number;
+    readonly signal: AbortSignal | undefined;
+}
+/** @internal Refuses every option shape the query-plan inspection does not define. */
+export declare const requireQueryPlanOptions: <T>(optionsArg: ISmartdataQueryPlanOptions<T>) => IValidatedQueryPlanOptions<T>;
+/** @internal Reduces an `executionStats` explanation to the stable summary; exported for its unit test. */
+export declare const summarizeQueryPlanExplanation: (explanationArg: plugins.mongodb.Document) => ISmartdataQueryPlan;
+/**
+ * @internal Explains one model query with `executionStats` on the given
+ * database. Nothing is created, bound or hydrated; the raw explanation never
+ * leaves this module.
+ */
+export declare const inspectQueryPlan: (dbArg: SmartdataDb, requestArg: IQueryPlanRequest) => Promise<ISmartdataQueryPlan>;

package/dist_ts/nosqldb/classes.queryplaninspection.js

@@ -0,0 +1,148 @@
+import * as plugins from './plugins.js';
+import { SmartdataPersistenceError, createSmartdataTimeoutError, isMongoDeadlineError } from './classes.persistence.js';
+import { requireOperationSignal, requireOperationTimeoutMS } from './classes.operationdeadline.js';
+import { runCursorOperation } from './classes.cursoroperation.js';
+import { collectionTopologyDbInspectionSymbol } from './classes.collectiontopology.js';
+const queryPlanOptionKeys = ['filter', 'sort', 'projection', 'limit', 'timeoutMS', 'signal'];
+const maximumPlanStages = 256;
+const maximumPlanDepth = 64;
+const maximumPlanStringLength = 1024;
+/** MongoDB's `CommandNotFound`, the answer of an engine that implements no `explain`. */
+const commandNotFoundCode = 59;
+const isRecord = (valueArg) => typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+const isPlainRecord = (valueArg) => {
+    if (!isRecord(valueArg))
+        return false;
+    const prototype = Object.getPrototypeOf(valueArg);
+    return prototype === Object.prototype || prototype === null;
+};
+/** @internal Refuses every option shape the query-plan inspection does not define. */
+export const requireQueryPlanOptions = (optionsArg) => {
+    const options = optionsArg;
+    if (!isPlainRecord(options) || Reflect.ownKeys(options).some((keyArg) => typeof keyArg !== 'string' || !queryPlanOptionKeys.includes(keyArg) ||
+        !('value' in Object.getOwnPropertyDescriptor(options, keyArg)))) {
+        throw new SmartdataPersistenceError('invalid_argument', 'Invalid query plan inspection options.');
+    }
+    if (!isPlainRecord(optionsArg.filter)) {
+        throw new SmartdataPersistenceError('invalid_argument', 'Query plan inspection requires a plain filter object.');
+    }
+    const limit = optionsArg.limit;
+    if (limit !== undefined &&
+        (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < 1 || limit > 10_000)) {
+        throw new SmartdataPersistenceError('invalid_argument', 'limit must be an integer from 1 through 10000.');
+    }
+    return {
+        filter: optionsArg.filter,
+        sort: optionsArg.sort,
+        projection: optionsArg.projection,
+        limit,
+        timeoutMS: requireOperationTimeoutMS(optionsArg.timeoutMS, 'timeoutMS') ?? 5_000,
+        signal: requireOperationSignal(optionsArg.signal, 'signal'),
+    };
+};
+const unreadablePlan = () => new SmartdataPersistenceError('unsupported_operation', 'The engine returned an unreadable query plan.');
+const readCount = (valueArg) => {
+    if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < 0) {
+        throw unreadablePlan();
+    }
+    return valueArg;
+};
+const readPlanString = (valueArg) => {
+    if (typeof valueArg !== 'string' || valueArg.length === 0 || valueArg.length > maximumPlanStringLength) {
+        throw unreadablePlan();
+    }
+    return valueArg;
+};
+/**
+ * Flattens the winning plan depth-first. MongoDB's slot-based engine wraps the
+ * classic tree as `queryPlan`; every other field of a stage stays behind.
+ */
+const flattenWinningPlan = (winningPlanArg) => {
+    const root = isRecord(winningPlanArg) && winningPlanArg.stage === undefined && isRecord(winningPlanArg.queryPlan)
+        ? winningPlanArg.queryPlan
+        : winningPlanArg;
+    const stages = [];
+    const visit = (nodeArg, depthArg) => {
+        if (!isRecord(nodeArg) || depthArg >= maximumPlanDepth || stages.length === maximumPlanStages) {
+            throw unreadablePlan();
+        }
+        const direction = nodeArg.direction === 'forward' || nodeArg.direction === 'backward'
+            ? nodeArg.direction
+            : undefined;
+        stages.push(Object.freeze({
+            stage: readPlanString(nodeArg.stage),
+            depth: depthArg,
+            ...(nodeArg.indexName === undefined ? {} : { indexName: readPlanString(nodeArg.indexName) }),
+            ...(direction === undefined ? {} : { direction }),
+        }));
+        const inputs = nodeArg.inputStages === undefined ? [] : nodeArg.inputStages;
+        if (!Array.isArray(inputs))
+            throw unreadablePlan();
+        if (nodeArg.inputStage !== undefined)
+            visit(nodeArg.inputStage, depthArg + 1);
+        for (const input of inputs)
+            visit(input, depthArg + 1);
+    };
+    visit(root, 0);
+    return stages;
+};
+/** @internal Reduces an `executionStats` explanation to the stable summary; exported for its unit test. */
+export const summarizeQueryPlanExplanation = (explanationArg) => {
+    const queryPlanner = explanationArg.queryPlanner;
+    const executionStats = explanationArg.executionStats;
+    if (!isRecord(queryPlanner) || !isRecord(executionStats) || executionStats.executionSuccess === false) {
+        throw unreadablePlan();
+    }
+    const stages = flattenWinningPlan(queryPlanner.winningPlan);
+    const executionTimeMillis = executionStats.executionTimeMillis === undefined
+        ? undefined
+        : readCount(executionStats.executionTimeMillis);
+    return Object.freeze({
+        stages: Object.freeze(stages),
+        nReturned: readCount(executionStats.nReturned),
+        totalKeysExamined: readCount(executionStats.totalKeysExamined),
+        totalDocsExamined: readCount(executionStats.totalDocsExamined),
+        ...(executionTimeMillis === undefined ? {} : { executionTimeMillis }),
+    });
+};
+/**
+ * @internal Explains one model query with `executionStats` on the given
+ * database. Nothing is created, bound or hydrated; the raw explanation never
+ * leaves this module.
+ */
+export const inspectQueryPlan = async (dbArg, requestArg) => {
+    const { signal } = requestArg;
+    signal?.throwIfAborted();
+    let failure;
+    let explanation;
+    try {
+        explanation = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg) => {
+            const cursor = mongoDbArg.collection(requestArg.collectionName).find(requestArg.filter, {
+                ...(requestArg.sort === undefined ? {} : { sort: requestArg.sort }),
+                ...(requestArg.projection === undefined ? {} : { projection: requestArg.projection }),
+                ...(requestArg.limit === undefined ? {} : { limit: requestArg.limit }),
+                ...(signal === undefined ? {} : { signal }),
+            });
+            try {
+                return await runCursorOperation(cursor, (cursorArg) => cursorArg.explain('executionStats', { timeoutMS: requestArg.timeoutMS }), signal);
+            }
+            catch (errorArg) {
+                failure = { error: errorArg };
+                throw errorArg;
+            }
+        });
+    }
+    catch (errorArg) {
+        signal?.throwIfAborted();
+        if (failure !== undefined && isMongoDeadlineError(failure.error)) {
+            throw createSmartdataTimeoutError('Query plan inspection exceeded its client deadline.', failure.error);
+        }
+        if (failure !== undefined && failure.error instanceof plugins.mongodb.MongoServerError &&
+            failure.error.code === commandNotFoundCode) {
+            throw new SmartdataPersistenceError('unsupported_operation', 'The connected engine does not explain queries.');
+        }
+        throw errorArg;
+    }
+    return summarizeQueryPlanExplanation(explanation);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5xdWVyeXBsYW5pbnNwZWN0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvbm9zcWxkYi9jbGFzc2VzLnF1ZXJ5cGxhbmluc3BlY3Rpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFHeEMsT0FBTyxFQUFFLHlCQUF5QixFQUFFLDJCQUEyQixFQUFFLG9CQUFvQixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDeEgsT0FBTyxFQUFFLHNCQUFzQixFQUFFLHlCQUF5QixFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDbkcsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDbEUsT0FBTyxFQUFFLG9DQUFvQyxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUEyRHZGLE1BQU0sbUJBQW1CLEdBQXNCLENBQUMsUUFBUSxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsT0FBTyxFQUFFLFdBQVcsRUFBRSxRQUFRLENBQUMsQ0FBQztBQUNoSCxNQUFNLGlCQUFpQixHQUFHLEdBQUcsQ0FBQztBQUM5QixNQUFNLGdCQUFnQixHQUFHLEVBQUUsQ0FBQztBQUM1QixNQUFNLHVCQUF1QixHQUFHLElBQUksQ0FBQztBQUNyQyx5RkFBeUY7QUFDekYsTUFBTSxtQkFBbUIsR0FBRyxFQUFFLENBQUM7QUFFL0IsTUFBTSxRQUFRLEdBQUcsQ0FBQyxRQUFpQixFQUF1QyxFQUFFLENBQzFFLE9BQU8sUUFBUSxLQUFLLFFBQVEsSUFBSSxRQUFRLEtBQUssSUFBSSxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsQ0FBQztBQUVoRixNQUFNLGFBQWEsR0FBRyxDQUFDLFFBQWlCLEVBQXVDLEVBQUU7SUFDL0UsSUFBSSxDQUFDLFFBQVEsQ0FBQyxRQUFRLENBQUM7UUFBRSxPQUFPLEtBQUssQ0FBQztJQUN0QyxNQUFNLFNBQVMsR0FBRyxN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

package/dist_ts/nosqldb/index.d.ts

@@ -16,6 +16,7 @@ export * from './classes.doc.js';
 export { ordinaryPersistence } from './classes.ordinarypersistence.js';
 export type { IOrdinaryPersistenceOptions } from './classes.ordinarypersistence.js';
 export type { ISmartdataStoredInspectionOptions, ISmartdataStoredInspection, ISmartdataStoredDocumentEvidence, ISmartdataStoredEvidenceInspection, TSmartdataOrdinaryDocumentEvidence, } from './classes.storedinspection.js';
+export type { ISmartdataQueryPlanOptions, ISmartdataQueryPlan, ISmartdataQueryPlanStage, } from './classes.queryplaninspection.js';
 export { SmartdataPersistenceError } from './classes.persistence.js';
 export type { TSmartdataPersistenceErrorCode } from './classes.persistence.js';
 export * from './classes.exactpersistence.js';

package/dist_ts/nosqldb/index.js

@@ -16,4 +16,4 @@ export * from './classes.distributedcoordinator.js';
 export * from './classes.cached-document.js';
 import * as convenience from './classes.convenience.js';
 export { convenience };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9ub3NxbGRiL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLDhFQUE4RTtBQUM5RSxPQUFPLFdBQVcsQ0FBQztBQUVuQixPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFhMUQsT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUc5QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsa0NBQWtDLENBQUM7QUFPakQsY0FBYyx5QkFBeUIsQ0FBQztBQVl4QyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLGtDQUFrQyxDQUFDO0FBT3ZFLE9BQU8sRUFBRSx5QkFBeUIsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBRXJFLGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxxQ0FBcUMsQ0FBQztBQUNwRCxjQUFjLDhCQUE4QixDQUFDO0FBRTdDLE9BQU8sS0FBSyxXQUFXLE1BQU0sMEJBQTBCLENBQUM7QUFFeEQsT0FBTyxFQUFFLFdBQVcsRUFBRSxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9ub3NxbGRiL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLDhFQUE4RTtBQUM5RSxPQUFPLFdBQVcsQ0FBQztBQUVuQixPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFhMUQsT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUc5QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsa0NBQWtDLENBQUM7QUFPakQsY0FBYyx5QkFBeUIsQ0FBQztBQVl4QyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLGtDQUFrQyxDQUFDO0FBVXZFLE9BQU8sRUFBRSx5QkFBeUIsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBRXJFLGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxxQ0FBcUMsQ0FBQztBQUNwRCxjQUFjLDhCQUE4QixDQUFDO0FBRTdDLE9BQU8sS0FBSyxXQUFXLE1BQU0sMEJBQTBCLENBQUM7QUFFeEQsT0FBTyxFQUFFLFdBQVcsRUFBRSxDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lossless.org/client",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "private": false,
   "description": "One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.",
   "exports": {
@@ -83,7 +83,7 @@
     "@clickhouse/client": "1.23.1",
     "@git.zone/tsbuild": "5.0.0",
     "@git.zone/tsrun": "3.0.1",
-    "@git.zone/tstest": "6.3.1",
+    "@git.zone/tstest": "6.3.2",
     "@lossless.org/nosqldb": "8.0.2",
     "@lossless.org/nosqldb-qualified": "npm:@lossless.org/nosqldb@10.7.2",
     "@lossless.org/objectstorage": "10.3.1",

package/readme.md

@@ -108,6 +108,7 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Transactions ended by close | a `session.withTransaction()` whose session `db.close()` ends while it runs rejects with `SmartdataPersistenceError` code `unsupported_operation` — "nothing was committed" before the commit, "the commit outcome is unknown" during it — instead of resolving with the callback's result |
 | Transaction commit outcome | `SmartdataSession.getCommitOutcome(error)` states for every value a `session.withTransaction()` rejected with whether the transaction could have committed: `not_committed` (nothing was committed) or `unknown` (a commit was sent and never confirmed); the rejection itself keeps its identity |
 | Cancellation | `signal` on every exact call, `atomicDeleteMany()` and `session.withTransaction(callback, { signal })`, which interrupts the session's operation in flight, rolls the attempt back and never commits after an abort |
+| Query-plan inspection | `Model.inspectQueryPlan(db, { filter, sort?, projection?, limit?, timeoutMS?, signal? })` — the winning plan's stages (`stage`, `depth`, `indexName`, `direction`) and `nReturned`/`totalKeysExamined`/`totalDocsExamined`, read-only and bounded, so a consumer proves a model query uses its intended index without raw driver access |
 | Disposable test databases on a unix socket | `SmartdataTestDatabase.create({ connection: { socketPath } })` from `@lossless.org/client/testsupport` reaches an engine that listens only on a unix-domain socket, fault helpers included; the loopback `host`/`port` form is unchanged |
 
 `docs/source/smartdata/readme.md` documents each one with its refusals.
@@ -137,6 +138,7 @@ The document model runs on both NoSQLDB and MongoDB, but several APIs do not mea
 | collection validators (`validator`, `validationLevel`, `validationAction`) | no client API; a migration owns a validator through the driver. 10.7.0 and newer create the collection, list the options exactly as given and enforce them on every model write: a violating `insert()` or `atomicUpdate()` rejects with the engine's `DocumentValidationFailure` (121) and its `errInfo`, which the client passes through unchanged rather than mapping to a `SmartdataPersistenceError` code, and stores nothing. Models initialize on a validated collection like on any other. 8.0.2 refuses the option with `InvalidOptions` (72) and creates no collection, so a validator is never silently dropped | enforced; not exercised by the client's MongoDB suite |
 | write conflicts between transactions, and writes outside a transaction to a document a transaction holds | 10.7.2 (since 10.6.1) detects a conflict at the statement, as MongoDB does: the first writer wins, and the later transaction's statement rejects with the engine's `WriteConflict` (112) labelled `TransientTransactionError`, which the client passes through so `session.withTransaction()` re-runs that callback. A write outside a transaction waits until the transaction holding its document ends, then applies on top; the wait is bounded by the write's own `timeoutMS` and by the engine's fixed 60-second transaction lifetime, after which a waiting writer aborts the holder. Awaiting such a write inside the holding transaction's callback therefore stalls that transaction until one of the two expires. 8.0.2 detects the conflict at commit: the first transaction to commit wins, a write outside a transaction applies at once, and the transaction that wrote first re-runs. Both writes land on either engine; a callback must be safe to re-run and must not swallow the statement error | first writer wins at the statement and outside writes wait, MongoDB's documented rule; not exercised by the client's MongoDB suite |
 | value-form `$elemMatch` in read filters (`{ scores: { $elemMatch: { $gte: 80, $lt: 90 } } }`, `{ labels: { $not: { $elemMatch: { $nin: runnerLabels } } } }`) | exact on 10.7.1 and newer: the operators apply to each array element as a whole, so the range matches only a document with one score inside it and the claim selects a job only when every one of its labels is a runner label. 8.0.2 parses every operand as a query over embedded documents and refuses the value form with `TypeMismatch` (14). A non-document operand is refused on both, with MongoDB's `BadValue` (2) on 10.7.1 and newer and 14 on 8.0.2. The client passes the operand through unchanged; the filter type admits the value form over scalar elements and the document form over embedded documents. Atomic filters (`atomicUpdate()` and the other atomic writes) accept no `$elemMatch` on any backend: the client refuses it with `invalid_argument` before any backend is contacted | exact |
+| `Model.inspectQueryPlan()` | explains on 10.7.2: the summary names the winning plan's stages and its execution totals. 8.0.2 answers `explain` with `CommandNotFound` (59), and the call rejects with `unsupported_operation` ("The connected engine does not explain queries.") rather than returning a plan it cannot know. Stage shapes are the engine's own: on 10.7.2 a limited sort on an unindexed field is `LIMIT` over `SORT` over `COLLSCAN`, an equality on a unique single-field index is `FETCH` over `IXSCAN`, and an `$or` whose branches each have an index is a `COLLSCAN` | explains: the same limited sort is `SORT` over `COLLSCAN`, the limit folded into the sort; the equality is `EXPRESS_IXSCAN` on the unique index; the `$or` is `SUBPLAN` over `FETCH` over `OR` over one `IXSCAN` per branch |
 | aggregation-pipeline (array) updates | refused by the client with `invalid_argument` before any backend is contacted. A client-owned refusal, not an engine limit: both qualified engines apply a pipeline update themselves | same client refusal |
 
 `test/nosqldb/smartdb/test.engine-capability-boundary.node.ts` asserts the identity, grouped-totals, guarded-`$expr`, partial-index, collection-validator, write-conflict, `$elemMatch` and pipeline-update rows against both qualified engines, so a boundary that moves shows up as a failing suite rather than as a changed number in a consumer. The two halves of the grouped-totals, guarded-`$expr`, write-conflict and `$elemMatch` rows are separate tests, each bound to the engine that answers it, and the engine's own composite-key answer stays under assertion through the raw `aggregateGroupedTotals()` boundary — one literal row on 8.0.2, the two exact pairs on 10.7.2. The same boundary pins the rest of the engine's `$group` stage: a non-document accumulator is refused with `TypeMismatch` (14) on 10.7.2 while 8.0.2 answers it, and a `$cond` inside a composite key is evaluated per document on 10.7.2 while 8.0.2 answers its single literal row. It also pins whether a migration can create a partial index — 10.7.2 creates it and lists the filter, 8.0.2 refuses with 72 — and a collection validator — 10.7.2 creates and enforces it against model inserts and updates, 8.0.2 refuses with 72 — which writer a conflict sends back: on 10.7.2 the later transaction fails at its statement and re-runs while a write outside a transaction waits for the holder's commit, on 8.0.2 the later transaction commits first and the holder re-runs — and what `$elemMatch` answers through `getInstances()`: 10.7.2 matches the documented range and the `$not`/`$elemMatch`/`$nin` claim exactly as the MongoDB filter suite asserts them, 8.0.2 refuses both with 14, and a non-document operand is refused with 2 on 10.7.2 and 14 on 8.0.2. The `watch()` row is the contract refusal `ts/nosqldb/classes.collection.ts` states; the engine suite opens no change stream.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@lossless.org/client',
-  version: '1.13.0',
+  version: '1.14.0',
   description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
 }

package/ts/nosqldb/classes.doc.ts

@@ -16,6 +16,10 @@ import {
   type ISmartdataStoredInspectionOptions, type ISmartdataStoredInspection,
   type ISmartdataStoredEvidenceInspection,
 } from './classes.storedinspection.js';
+import {
+  inspectQueryPlan, requireQueryPlanOptions,
+  type ISmartdataQueryPlan, type ISmartdataQueryPlanOptions,
+} from './classes.queryplaninspection.js';
 import {
   getIdentityDocumentIdField,
   type IManager,
@@ -3727,6 +3731,32 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     return inspectStoredDocumentEvidence(this, dbArg, optionsArg);
   }
 
+  /**
+   * Explains one model query with `executionStats` on `dbArg` and returns the
+   * winning plan's stages and execution totals, so a consumer can prove which
+   * index serves the query. Read-only: nothing is created, bound or hydrated.
+   */
+  public static async inspectQueryPlan<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    dbArg: SmartdataDb,
+    optionsArg: ISmartdataQueryPlanOptions<T>,
+  ): Promise<ISmartdataQueryPlan> {
+    const model = this as unknown as typeof SmartDataDbDoc;
+    const options = requireQueryPlanOptions(optionsArg);
+    model.assertHydratedProjection(options.projection);
+    const declaredRoots = model.getDeclaredPersistedRoots();
+    const declaredQueryPaths = model.getDeclaredQueryPaths();
+    return inspectQueryPlan(dbArg, {
+      collectionName: getExpectedCollectionTopologyForModel(model).collectionName,
+      filter: model.normalizeReadFilter(options.filter),
+      sort: normalizeSort(options.sort, declaredRoots, declaredQueryPaths),
+      projection: normalizeProjection(options.projection, declaredRoots, declaredQueryPaths),
+      limit: options.limit,
+      timeoutMS: options.timeoutMS,
+      signal: options.signal,
+    });
+  }
+
   public static createInstanceFromMongoDbNativeDoc<T>(
     this: plugins.tsclass.typeFest.Class<T>,
     mongoDbNativeDocArg: any,

package/ts/nosqldb/classes.queryplaninspection.ts

@@ -0,0 +1,220 @@
+import * as plugins from './plugins.js';
+import type { SmartdataDb } from './classes.db.js';
+import type { MongoFilter, TSmartdataProjection, TSmartdataSort } from './classes.doc.js';
+import { SmartdataPersistenceError, createSmartdataTimeoutError, isMongoDeadlineError } from './classes.persistence.js';
+import { requireOperationSignal, requireOperationTimeoutMS } from './classes.operationdeadline.js';
+import { runCursorOperation } from './classes.cursoroperation.js';
+import { collectionTopologyDbInspectionSymbol } from './classes.collectiontopology.js';
+
+export interface ISmartdataQueryPlanOptions<T> {
+  /** Validated exactly like the filter of the model's ordinary reads. */
+  filter: MongoFilter<T>;
+  /** Declared paths or `_id`, each 1 or -1, as for `getCursor()` and `getOffsetPage()`. */
+  sort?: TSmartdataSort<T>;
+  /** Declared paths or `_id`, 0 or 1, as for `getCursor()` and `getOffsetPage()`. */
+  projection?: TSmartdataProjection<T>;
+  /** 1..10000. Without it the plan executes over every match. */
+  limit?: number;
+  /** Client deadline for the explained execution. Default 5000ms, maximum 120000ms. */
+  timeoutMS?: number;
+  signal?: AbortSignal;
+}
+
+/** One stage of the winning plan, in depth-first order from the root. */
+export interface ISmartdataQueryPlanStage {
+  /** The engine's stage name, such as `IXSCAN`, `COLLSCAN`, `FETCH`, `SORT` or `LIMIT`. */
+  readonly stage: string;
+  /** 0 for the root; a stage's inputs follow it at one level deeper. */
+  readonly depth: number;
+  /** The index the stage reads, when the engine names one. */
+  readonly indexName?: string;
+  /** The scan direction, when the engine states one. */
+  readonly direction?: 'forward' | 'backward';
+}
+
+export interface ISmartdataQueryPlan {
+  /** The winning plan's stage tree, flattened depth-first. */
+  readonly stages: readonly ISmartdataQueryPlanStage[];
+  readonly nReturned: number;
+  readonly totalKeysExamined: number;
+  readonly totalDocsExamined: number;
+  /** Present when the engine reports it. */
+  readonly executionTimeMillis?: number;
+}
+
+/** @internal The query-plan options after their bounds are checked. */
+export interface IValidatedQueryPlanOptions<T> {
+  readonly filter: MongoFilter<T>;
+  readonly sort: TSmartdataSort<T> | undefined;
+  readonly projection: TSmartdataProjection<T> | undefined;
+  readonly limit: number | undefined;
+  readonly timeoutMS: number;
+  readonly signal: AbortSignal | undefined;
+}
+
+/** @internal The normalized query one inspection explains. */
+export interface IQueryPlanRequest {
+  readonly collectionName: string;
+  readonly filter: plugins.mongodb.Filter<plugins.mongodb.Document>;
+  readonly sort: plugins.mongodb.Sort | undefined;
+  readonly projection: plugins.mongodb.Document | undefined;
+  readonly limit: number | undefined;
+  readonly timeoutMS: number;
+  readonly signal: AbortSignal | undefined;
+}
+
+const queryPlanOptionKeys: readonly string[] = ['filter', 'sort', 'projection', 'limit', 'timeoutMS', 'signal'];
+const maximumPlanStages = 256;
+const maximumPlanDepth = 64;
+const maximumPlanStringLength = 1024;
+/** MongoDB's `CommandNotFound`, the answer of an engine that implements no `explain`. */
+const commandNotFoundCode = 59;
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const isPlainRecord = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  if (!isRecord(valueArg)) return false;
+  const prototype = Object.getPrototypeOf(valueArg);
+  return prototype === Object.prototype || prototype === null;
+};
+
+/** @internal Refuses every option shape the query-plan inspection does not define. */
+export const requireQueryPlanOptions = <T>(
+  optionsArg: ISmartdataQueryPlanOptions<T>,
+): IValidatedQueryPlanOptions<T> => {
+  const options: unknown = optionsArg;
+  if (!isPlainRecord(options) || Reflect.ownKeys(options).some((keyArg) =>
+    typeof keyArg !== 'string' || !queryPlanOptionKeys.includes(keyArg) ||
+    !('value' in Object.getOwnPropertyDescriptor(options, keyArg)!))) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Invalid query plan inspection options.');
+  }
+  if (!isPlainRecord(optionsArg.filter)) {
+    throw new SmartdataPersistenceError('invalid_argument', 'Query plan inspection requires a plain filter object.');
+  }
+  const limit: unknown = optionsArg.limit;
+  if (limit !== undefined &&
+    (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < 1 || limit > 10_000)) {
+    throw new SmartdataPersistenceError('invalid_argument', 'limit must be an integer from 1 through 10000.');
+  }
+  return {
+    filter: optionsArg.filter,
+    sort: optionsArg.sort,
+    projection: optionsArg.projection,
+    limit,
+    timeoutMS: requireOperationTimeoutMS(optionsArg.timeoutMS, 'timeoutMS') ?? 5_000,
+    signal: requireOperationSignal(optionsArg.signal, 'signal'),
+  };
+};
+
+const unreadablePlan = (): SmartdataPersistenceError =>
+  new SmartdataPersistenceError('unsupported_operation', 'The engine returned an unreadable query plan.');
+
+const readCount = (valueArg: unknown): number => {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < 0) {
+    throw unreadablePlan();
+  }
+  return valueArg;
+};
+
+const readPlanString = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0 || valueArg.length > maximumPlanStringLength) {
+    throw unreadablePlan();
+  }
+  return valueArg;
+};
+
+/**
+ * Flattens the winning plan depth-first. MongoDB's slot-based engine wraps the
+ * classic tree as `queryPlan`; every other field of a stage stays behind.
+ */
+const flattenWinningPlan = (winningPlanArg: unknown): ISmartdataQueryPlanStage[] => {
+  const root = isRecord(winningPlanArg) && winningPlanArg.stage === undefined && isRecord(winningPlanArg.queryPlan)
+    ? winningPlanArg.queryPlan
+    : winningPlanArg;
+  const stages: ISmartdataQueryPlanStage[] = [];
+  const visit = (nodeArg: unknown, depthArg: number): void => {
+    if (!isRecord(nodeArg) || depthArg >= maximumPlanDepth || stages.length === maximumPlanStages) {
+      throw unreadablePlan();
+    }
+    const direction = nodeArg.direction === 'forward' || nodeArg.direction === 'backward'
+      ? nodeArg.direction
+      : undefined;
+    stages.push(Object.freeze({
+      stage: readPlanString(nodeArg.stage),
+      depth: depthArg,
+      ...(nodeArg.indexName === undefined ? {} : { indexName: readPlanString(nodeArg.indexName) }),
+      ...(direction === undefined ? {} : { direction }),
+    }));
+    const inputs = nodeArg.inputStages === undefined ? [] : nodeArg.inputStages;
+    if (!Array.isArray(inputs)) throw unreadablePlan();
+    if (nodeArg.inputStage !== undefined) visit(nodeArg.inputStage, depthArg + 1);
+    for (const input of inputs) visit(input, depthArg + 1);
+  };
+  visit(root, 0);
+  return stages;
+};
+
+/** @internal Reduces an `executionStats` explanation to the stable summary; exported for its unit test. */
+export const summarizeQueryPlanExplanation = (explanationArg: plugins.mongodb.Document): ISmartdataQueryPlan => {
+  const queryPlanner = explanationArg.queryPlanner;
+  const executionStats = explanationArg.executionStats;
+  if (!isRecord(queryPlanner) || !isRecord(executionStats) || executionStats.executionSuccess === false) {
+    throw unreadablePlan();
+  }
+  const stages = flattenWinningPlan(queryPlanner.winningPlan);
+  const executionTimeMillis = executionStats.executionTimeMillis === undefined
+    ? undefined
+    : readCount(executionStats.executionTimeMillis);
+  return Object.freeze({
+    stages: Object.freeze(stages),
+    nReturned: readCount(executionStats.nReturned),
+    totalKeysExamined: readCount(executionStats.totalKeysExamined),
+    totalDocsExamined: readCount(executionStats.totalDocsExamined),
+    ...(executionTimeMillis === undefined ? {} : { executionTimeMillis }),
+  });
+};
+
+/**
+ * @internal Explains one model query with `executionStats` on the given
+ * database. Nothing is created, bound or hydrated; the raw explanation never
+ * leaves this module.
+ */
+export const inspectQueryPlan = async (
+  dbArg: SmartdataDb,
+  requestArg: IQueryPlanRequest,
+): Promise<ISmartdataQueryPlan> => {
+  const { signal } = requestArg;
+  signal?.throwIfAborted();
+  let failure: { readonly error: unknown } | undefined;
+  let explanation: plugins.mongodb.Document;
+  try {
+    explanation = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg) => {
+      const cursor = mongoDbArg.collection(requestArg.collectionName).find(requestArg.filter, {
+        ...(requestArg.sort === undefined ? {} : { sort: requestArg.sort }),
+        ...(requestArg.projection === undefined ? {} : { projection: requestArg.projection }),
+        ...(requestArg.limit === undefined ? {} : { limit: requestArg.limit }),
+        ...(signal === undefined ? {} : { signal }),
+      });
+      try {
+        return await runCursorOperation(cursor, (cursorArg) =>
+          cursorArg.explain('executionStats', { timeoutMS: requestArg.timeoutMS }), signal);
+      } catch (errorArg) {
+        failure = { error: errorArg };
+        throw errorArg;
+      }
+    });
+  } catch (errorArg) {
+    signal?.throwIfAborted();
+    if (failure !== undefined && isMongoDeadlineError(failure.error)) {
+      throw createSmartdataTimeoutError('Query plan inspection exceeded its client deadline.', failure.error);
+    }
+    if (failure !== undefined && failure.error instanceof plugins.mongodb.MongoServerError &&
+      failure.error.code === commandNotFoundCode) {
+      throw new SmartdataPersistenceError('unsupported_operation',
+        'The connected engine does not explain queries.');
+    }
+    throw errorArg;
+  }
+  return summarizeQueryPlanExplanation(explanation);
+};

package/ts/nosqldb/index.ts

@@ -45,6 +45,9 @@ export type {
   ISmartdataStoredDocumentEvidence, ISmartdataStoredEvidenceInspection,
   TSmartdataOrdinaryDocumentEvidence,
 } from './classes.storedinspection.js';
+export type {
+  ISmartdataQueryPlanOptions, ISmartdataQueryPlan, ISmartdataQueryPlanStage,
+} from './classes.queryplaninspection.js';
 export { SmartdataPersistenceError } from './classes.persistence.js';
 export type { TSmartdataPersistenceErrorCode } from './classes.persistence.js';
 export * from './classes.exactpersistence.js';