@fadhilp/stateql 0.5.4 → 0.7.0

package/dist/src/stateql.js

@@ -1,9 +1,11 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { env } from "node:process";
 import { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapter, createAdapterContext, } from "./adapters.js";
-import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, normalizeSqliteSource, validateProfileName, version, } from "./connection.js";
+import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, mongoDatabaseName, normalizeSqliteSource, validateProfileName, version, } from "./connection.js";
 import { asStateQLError, CredentialResolutionError, StateQLError, } from "./errors.js";
+import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoReadCommand, validateMongoWriteCommand, MongoAdapter, } from "./mongodb.js";
 import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
 import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData, transactionData, } from "./response-data.js";
 import { analyzeSql } from "./sql.js";
@@ -40,6 +42,7 @@ export class StateQL {
     maxResultBytes;
     timeoutMs;
     signal;
+    commandContexts = new AsyncLocalStorage();
     credentialResolver;
     now;
     closed = false;
@@ -139,7 +142,9 @@ export class StateQL {
                     : adapterSource;
             const databaseName = driver === "sqlite"
                 ? basename(adapterSource)
-                : new URL(secret).pathname.replace(/^\//, "") || driver;
+                : driver === "mongodb"
+                    ? mongoDatabaseName(adapterSource)
+                    : new URL(secret).pathname.replace(/^\//, "") || driver;
             const draft = {
                 id: "pending",
                 session_id: session.id,
@@ -152,9 +157,11 @@ export class StateQL {
                 version: 0,
                 created_at: this.now().toISOString(),
             };
-            const adapter = await this.openAdapter(draft, context, adapterSource);
+            const adapter = driver === "mongodb"
+                ? await this.openMongoAdapter(draft, context, adapterSource)
+                : await this.openAdapter(draft, context, adapterSource);
             try {
-                await adapter.read("SELECT 1", []);
+                await adapter.ping();
             }
             catch (error) {
                 if (error instanceof AdapterExecutionError) {
@@ -524,6 +531,7 @@ export class StateQL {
     async query(sql, options = {}) {
         return this.run("query", async (session) => {
             const connection = this.requireConnection(session);
+            this.rejectMongoSql(connection, "mongoQuery");
             this.rejectDuringStagedTransaction(session, "Queries");
             const analysis = analyzeSql(sql, connection.driver);
             if (!analysis.read) {
@@ -615,6 +623,95 @@ export class StateQL {
             }
         }, sql);
     }
+    async mongoQuery(command, options = {}) {
+        return this.run("mongo.query", async (session) => {
+            const value = validatedMongoRead(command);
+            const serializedCommand = serializeMongoCommand(value);
+            const connection = this.requireMongoConnection(session, "mongoQuery");
+            this.rejectDuringStagedTransaction(session, "MongoDB queries");
+            const context = this.executionContext(options);
+            const adapterSource = await this.resolveConnectionSource(connection, session, "query", "read", context);
+            const adapter = await this.openMongoAdapter(connection, context, adapterSource);
+            try {
+                const stateVersion = version(connection);
+                const stateSignature = await adapter.signature();
+                const fingerprint = hash({
+                    command: serializedCommand,
+                    driver: connection.driver,
+                    connection: connection.id,
+                    database: connection.database_name,
+                    transaction: session.active_transaction_id,
+                    stateVersion,
+                });
+                const cached = this.store.findResult(fingerprint);
+                const cacheMode = options.cache ?? "auto";
+                const warnings = mongoPaginationWarnings(value);
+                if (cacheMode !== "bypass" &&
+                    cached &&
+                    cached.row_count <= this.maxResultRows &&
+                    this.cacheValid(cached, stateVersion, stateSignature)) {
+                    return {
+                        data: this.resultData(cached, true),
+                        handle: cached.id,
+                        cached: true,
+                        warnings,
+                        stateVersion,
+                        confidence: cached.state_confidence,
+                    };
+                }
+                if (cacheMode === "require") {
+                    throw new StateQLError("CACHE_MISS", "No valid cached result exists.", {
+                        retryable: true,
+                        suggestedAction: "Run with cache auto or cache bypass.",
+                    });
+                }
+                const result = await adapter.read(value, this.maxResultRows + 1);
+                if (result.rows.length > this.maxResultRows) {
+                    throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", `Query exceeds the ${this.maxResultRows}-row materialization limit.`, { suggestedAction: "Use a narrower filter or limit." });
+                }
+                const parameters = [serializedCommand];
+                const resultBytes = Buffer.byteLength(JSON.stringify(parameters), "utf8") +
+                    Buffer.byteLength(JSON.stringify(result.rows), "utf8") +
+                    Buffer.byteLength(JSON.stringify(result.columns), "utf8");
+                if (resultBytes > this.maxResultBytes) {
+                    throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", `Query exceeds the ${this.maxResultBytes}-byte materialization limit.`, { suggestedAction: "Return fewer or smaller documents." });
+                }
+                const expiresAt = new Date(this.now().getTime() + this.resultTtlSeconds * 1000).toISOString();
+                const saved = this.store.saveResult({
+                    sessionId: session.id,
+                    connectionId: connection.id,
+                    fingerprint,
+                    sql: mongoDescriptor(value.operation),
+                    parameters,
+                    rows: result.rows,
+                    columns: result.columns,
+                    stateVersion,
+                    stateSignature,
+                    stateConfidence: adapter.confidence,
+                    expiresAt,
+                });
+                return {
+                    data: this.resultData(saved, false),
+                    handle: saved.id,
+                    executed: true,
+                    warnings,
+                    stateVersion,
+                    confidence: adapter.confidence,
+                };
+            }
+            catch (error) {
+                if (error instanceof StateQLError)
+                    throw error;
+                if (error instanceof AdapterExecutionError) {
+                    throw stoppedStateQLError(error, true);
+                }
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
+            }
+            finally {
+                await closeAdapterQuietly(adapter);
+            }
+        });
+    }
     async show(idOrAlias) {
         return this.withResult("show", idOrAlias, async (result) => ({
             data: this.resultData(result, true),
@@ -755,9 +852,17 @@ export class StateQL {
     async exec(sql, options = {}) {
         return this.run("exec", async (session) => {
             const connection = this.requireConnection(session);
+            this.rejectMongoSql(connection, "mongoExec");
             return this.performExec(session, connection, sql, options, this.executionContext(options));
         }, sql);
     }
+    async mongoExec(command, options = {}) {
+        return this.run("mongo.exec", async (session) => {
+            const value = validatedMongoWrite(command);
+            const connection = this.requireMongoConnection(session, "mongoExec");
+            return this.performMongoExec(session, connection, value, options, this.executionContext(options));
+        });
+    }
     async receipt(id) {
         return this.run("receipt", async (session) => {
             const operation = this.store.getOperation(id);
@@ -771,7 +876,7 @@ export class StateQL {
             };
         });
     }
-    async beginTransaction(isolation = "serializable") {
+    async beginTransaction(isolation) {
         return this.run("transaction.begin", async (session) => {
             const connection = this.requireConnection(session);
             if (connection.read_only) {
@@ -780,7 +885,7 @@ export class StateQL {
             if (session.active_transaction_id) {
                 throw new StateQLError("TRANSACTION_FAILED", `Transaction "${session.active_transaction_id}" is already active.`);
             }
-            const normalizedIsolation = normalizeIsolation(isolation, connection.driver);
+            const normalizedIsolation = normalizeIsolation(isolation ?? (connection.driver === "mongodb" ? "snapshot" : "serializable"), connection.driver);
             const transaction = this.store.createTransaction({
                 sessionId: session.id,
                 actorId: this.actorId,
@@ -829,20 +934,30 @@ export class StateQL {
             // Validate durable payloads before opening a database adapter or changing
             // the transaction state.
             const operations = this.store.validatedTransactionOperations(transaction.id);
+            if (operations.some((operation) => operation.connection_id !== connection.id)) {
+                throw new StateQLError("TRANSACTION_FAILED", "Transaction contains writes staged for another connection.");
+            }
+            const mongoCommands = connection.driver === "mongodb"
+                ? operations.map(storedMongoOperation)
+                : undefined;
+            if (connection.driver !== "mongodb" &&
+                operations.some((operation) => operation.statement_type.startsWith("mongo."))) {
+                throw new StateQLError("TRANSACTION_FAILED", "Transaction contains native MongoDB writes for a SQL connection.");
+            }
             const context = this.executionContext(options);
             const adapterSource = await this.resolveConnectionSource(connection, session, "transaction.commit", "write", context);
-            const adapter = await this.openAdapter(connection, context, adapterSource);
+            const adapter = connection.driver === "mongodb"
+                ? await this.openMongoAdapter(connection, context, adapterSource)
+                : await this.openAdapter(connection, context, adapterSource);
             try {
                 if (!this.store.claimTransactionForCommit(transaction.id, session.id, this.actorId, operations)) {
                     throw new StateQLError("TRANSACTION_FAILED", "Transaction is no longer active.");
                 }
-                if (operations.some((operation) => operation.connection_id !== connection.id)) {
-                    this.store.finishTransaction(transaction.id, session.id, this.actorId, "failed");
-                    throw new StateQLError("TRANSACTION_FAILED", "Transaction contains writes staged for another connection.");
-                }
                 let results;
                 try {
-                    results = await adapter.writeBatch(operations, transaction.isolation_level);
+                    results = mongoCommands
+                        ? await adapter.writeBatch(mongoCommands, transaction.isolation_level)
+                        : await adapter.writeBatch(operations, transaction.isolation_level);
                 }
                 catch (error) {
                     if ((error instanceof BatchWriteError && !error.outcomeUnknown) ||
@@ -876,6 +991,9 @@ export class StateQL {
                         operations: operations.map((operation, index) => ({
                             id: operation.id,
                             affectedRows: results[index].affectedRows,
+                            ...(results[index].outcome
+                                ? { outcome: results[index].outcome }
+                                : {}),
                         })),
                     });
                 }
@@ -935,7 +1053,9 @@ export class StateQL {
             this.rejectDuringStagedTransaction(session, "Schema inspection");
             const context = this.executionContext(options);
             const adapterSource = await this.resolveConnectionSource(connection, session, "inspect", "read", context);
-            const adapter = await this.openAdapter(connection, context, adapterSource);
+            const adapter = connection.driver === "mongodb"
+                ? await this.openMongoAdapter(connection, context, adapterSource)
+                : await this.openAdapter(connection, context, adapterSource);
             try {
                 const data = await adapter.inspect(kind, table);
                 return {
@@ -962,6 +1082,7 @@ export class StateQL {
     async plan(sql, options = {}) {
         return this.run("plan", async (session) => {
             const connection = this.requireConnection(session);
+            this.rejectMongoSql(connection, "mongoPlan");
             this.rejectDuringStagedTransaction(session, "Plans");
             const analysis = analyzeSql(sql, connection.driver);
             if (analysis.read) {
@@ -1025,6 +1146,71 @@ export class StateQL {
             }
         }, sql);
     }
+    async mongoPlan(command, options = {}) {
+        return this.run("mongo.plan", async (session) => {
+            const value = validatedMongoWrite(command);
+            const serializedCommand = serializeMongoCommand(value);
+            const connection = this.requireMongoConnection(session, "mongoPlan");
+            this.rejectDuringStagedTransaction(session, "Plans");
+            const safety = analyzeMongoWriteSafety(value);
+            const context = this.executionContext(options);
+            const adapterSource = await this.resolveConnectionSource(connection, session, "plan", "read", context);
+            const adapter = await this.openMongoAdapter(connection, context, adapterSource);
+            try {
+                const stateSignature = await adapter.signature();
+                const expiresAt = new Date(this.now().getTime() + 10 * 60_000).toISOString();
+                const plan = this.store.savePlan({
+                    sessionId: session.id,
+                    ownerActorId: this.actorId,
+                    connectionId: connection.id,
+                    sql: mongoDescriptor(value.operation),
+                    parameters: [serializedCommand],
+                    statementType: `mongo.${value.operation}`,
+                    stateVersion: version(connection),
+                    stateSignature,
+                    destructive: safety.destructive || safety.unbounded,
+                    allowUnbounded: options.allowUnbounded ?? false,
+                    allowDestructive: options.allowDestructive ?? false,
+                    expiresAt,
+                });
+                return {
+                    data: {
+                        plan_id: plan.id,
+                        statement_type: plan.statement_type,
+                        destructive: Boolean(plan.destructive),
+                        requires_confirmation: (safety.unbounded && !Boolean(plan.allow_unbounded)) ||
+                            (safety.destructive && !Boolean(plan.allow_destructive)),
+                        required_overrides: [
+                            ...(safety.unbounded && !Boolean(plan.allow_unbounded)
+                                ? ["--allow-unbounded"]
+                                : []),
+                            ...(safety.destructive && !Boolean(plan.allow_destructive)
+                                ? ["--allow-destructive"]
+                                : []),
+                        ],
+                        state_version: plan.state_version,
+                        owner_actor_id: plan.owner_actor_id,
+                        expires_at: plan.expires_at,
+                    },
+                    handle: plan.id,
+                    executed: true,
+                    stateVersion: plan.state_version,
+                    confidence: adapter.confidence,
+                };
+            }
+            catch (error) {
+                if (error instanceof StateQLError)
+                    throw error;
+                if (error instanceof AdapterExecutionError) {
+                    throw stoppedStateQLError(error, true);
+                }
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
+            }
+            finally {
+                await closeAdapterQuietly(adapter);
+            }
+        });
+    }
     async apply(planId, options = {}) {
         let historySql;
         return this.run("apply", async (session) => {
@@ -1044,8 +1230,14 @@ export class StateQL {
             if (Date.parse(plan.expires_at) <= this.now().getTime()) {
                 throw new StateQLError("STALE_PLAN", "Plan has expired.");
             }
-            historySql = plan.sql;
-            const planParameters = parseJson(plan.parameters, `plan "${plan.id}" parameters`, isSqlParameters);
+            const nativePlan = plan.statement_type.startsWith("mongo.");
+            historySql = nativePlan ? undefined : plan.sql;
+            const mongoCommand = nativePlan
+                ? storedMongoPlan(plan.parameters, plan.statement_type, plan.id)
+                : undefined;
+            const planParameters = nativePlan
+                ? undefined
+                : parseJson(plan.parameters, `plan "${plan.id}" parameters`, isSqlParameters);
             const claimToken = this.store.nextId("claim");
             const claimed = this.store.claimPlan(plan.id, session.id, this.actorId, claimToken);
             if (!claimed) {
@@ -1058,9 +1250,17 @@ export class StateQL {
                     version(connection) !== claimed.state_version) {
                     throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
                 }
+                if (nativePlan && connection.driver !== "mongodb") {
+                    throw new StateQLError("STALE_PLAN", "MongoDB plan is not attached to a MongoDB connection.");
+                }
+                if (!nativePlan && connection.driver === "mongodb") {
+                    this.rejectMongoSql(connection, "mongoPlan");
+                }
                 const context = this.executionContext(options);
                 const adapterSource = await this.resolveConnectionSource(connection, session, "apply", "write", context);
-                const adapter = await this.openAdapter(connection, context, adapterSource);
+                const adapter = nativePlan
+                    ? await this.openMongoAdapter(connection, context, adapterSource)
+                    : await this.openAdapter(connection, context, adapterSource);
                 try {
                     if ((await adapter.signature()) !== claimed.state_signature) {
                         throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
@@ -1077,11 +1277,16 @@ export class StateQL {
                 finally {
                     await closeAdapterQuietly(adapter);
                 }
-                const result = await this.performExec(session, connection, claimed.sql, {
-                    params: planParameters,
-                    allowUnbounded: Boolean(claimed.allow_unbounded),
-                    allowDestructive: Boolean(claimed.allow_destructive),
-                }, context, { planId: claimed.id, claimToken }, adapterSource);
+                const result = mongoCommand
+                    ? await this.performMongoExec(session, connection, mongoCommand, {
+                        allowUnbounded: Boolean(claimed.allow_unbounded),
+                        allowDestructive: Boolean(claimed.allow_destructive),
+                    }, context, { planId: claimed.id, claimToken }, adapterSource)
+                    : await this.performExec(session, connection, claimed.sql, {
+                        params: planParameters,
+                        allowUnbounded: Boolean(claimed.allow_unbounded),
+                        allowDestructive: Boolean(claimed.allow_destructive),
+                    }, context, { planId: claimed.id, claimToken }, adapterSource);
                 return {
                     ...result,
                     data: { plan_id: claimed.id, ...result.data },
@@ -1100,11 +1305,13 @@ export class StateQL {
             }
         }, () => historySql);
     }
-    async history(limit = 20) {
+    async history(limit = 20, options = {}) {
         return this.run("history", async (session) => ({
             data: {
                 history: this.store
-                    .history(session.id, positiveInteger(limit, "limit"))
+                    .history(session.id, positiveInteger(limit, "limit"), options.origin === undefined
+                    ? undefined
+                    : parseCommandOrigin(options.origin))
                     .map(historyEntry),
             },
         }));
@@ -1131,7 +1338,7 @@ export class StateQL {
     async capabilities() {
         return this.run("capabilities", async () => ({
             data: {
-                drivers: ["mysql", "postgres", "sqlite"],
+                drivers: ["mongodb", "mysql", "postgres", "sqlite"],
                 features: {
                     result_handles: true,
                     write_deduplication: true,
@@ -1147,142 +1354,194 @@ export class StateQL {
                     state_purge: true,
                     state_quota: true,
                 },
+                driver_features: {
+                    mongodb: {
+                        sql: false,
+                        native_read: true,
+                        native_write: true,
+                        plans: true,
+                        transactions: true,
+                        transactions_require_replica_set: true,
+                        inspection: true,
+                    },
+                },
             },
         }));
     }
-    async executeCommand(command) {
-        if (!command || typeof command !== "object") {
-            return this.batchFailure("Batch command must be an object.");
-        }
+    async executeCommand(command, context = {}) {
+        let activeContext;
         try {
-            switch (command.command) {
-                case "connect":
-                    return this.connect(command.target, {
-                        name: command.name,
-                        readOnly: command.read_only,
-                        secretEnv: command.secret_env,
-                        profile: command.profile,
-                        timeoutMs: command.timeout_ms,
-                    });
-                case "disconnect":
-                    return this.disconnect();
-                case "status":
-                    return this.status();
-                case "profile.add":
-                    return this.addProfile(batchString(command.name, "name"), command.target, {
-                        readOnly: command.read_only ?? true,
-                        secretEnv: command.secret_env,
-                    });
-                case "profile.list":
-                    return this.listProfiles();
-                case "profile.show":
-                    return this.showProfile(batchString(command.name, "name"));
-                case "profile.remove":
-                    return this.removeProfile(batchString(command.name, "name"));
-                case "session.start":
-                    return this.startSession(batchString(command.name, "name"));
-                case "session.list":
-                    return this.listSessions();
-                case "session.show":
-                    return this.showSession(command.name);
-                case "session.summary":
-                    return this.sessionSummary();
-                case "session.close":
-                    return this.closeSession();
-                case "query": {
-                    const response = await this.query(batchString(command.sql, "sql"), {
-                        params: command.params ?? [],
-                        cache: command.cache ?? "auto",
-                        timeoutMs: command.timeout_ms,
-                    });
-                    if (!response.ok || !command.as)
-                        return response;
-                    const resultId = response.data.result_id;
-                    if (typeof resultId !== "string")
-                        return response;
-                    this.store.setAlias(response.session_id, command.as, resultId);
-                    return {
-                        ...response,
-                        data: { ...response.data, alias: command.as },
-                    };
-                }
-                case "filter": {
-                    const response = await this.filter(batchString(command.handle, "handle"), batchString(command.where, "where"), { params: command.params ?? [] });
-                    if (!response.ok || !command.as)
-                        return response;
-                    const resultId = response.data.result_id;
-                    if (typeof resultId !== "string")
-                        return response;
-                    this.store.setAlias(response.session_id, command.as, resultId);
-                    return {
-                        ...response,
-                        data: { ...response.data, alias: command.as },
-                    };
-                }
-                case "exec":
-                    return this.exec(batchString(command.sql, "sql"), {
-                        params: command.params ?? [],
-                        replay: command.replay ?? false,
-                        idempotencyKey: command.idempotency_key,
-                        allowUnbounded: command.allow_unbounded ?? false,
-                        allowDestructive: command.allow_destructive ?? false,
-                        timeoutMs: command.timeout_ms,
-                    });
-                case "show":
-                    return this.show(batchString(command.handle, "handle"));
-                case "rows":
-                    return this.rows(batchString(command.handle, "handle"), {
-                        offset: command.offset ?? 0,
-                        limit: command.limit ?? 20,
-                    });
-                case "count":
-                    return this.count(batchString(command.handle, "handle"));
-                case "columns":
-                    return this.columns(batchString(command.handle, "handle"));
-                case "alias.set":
-                    return this.setAlias(batchString(command.name, "name"), batchString(command.handle, "handle"));
-                case "inspect":
-                    return this.inspect(batchString(command.kind, "kind"), command.table, {
-                        timeoutMs: command.timeout_ms,
-                    });
-                case "transaction.begin":
-                    return this.beginTransaction(command.isolation);
-                case "transaction.status":
-                    return this.transactionStatus(command.handle);
-                case "transaction.commit":
-                    return this.commitTransaction(command.handle, {
-                        timeoutMs: command.timeout_ms,
-                    });
-                case "transaction.rollback":
-                    return this.rollbackTransaction(command.handle);
-                case "plan":
-                    return this.plan(batchString(command.sql, "sql"), {
-                        params: command.params ?? [],
-                        allowUnbounded: command.allow_unbounded ?? false,
-                        allowDestructive: command.allow_destructive,
-                        timeoutMs: command.timeout_ms,
-                    });
-                case "apply":
-                    return this.apply(batchString(command.handle, "handle"), {
-                        timeoutMs: command.timeout_ms,
-                    });
-                case "history":
-                    return this.history(command.limit ?? 20);
-                case "receipt":
-                    return this.receipt(batchString(command.handle, "handle"));
-                case "doctor":
-                    return this.doctor();
-                case "purge":
-                    return this.purge(command.scope ?? "expired");
-                case "capabilities":
-                    return this.capabilities();
-                default:
-                    return this.batchFailure(`Unknown batch command "${String(command.command)}".`);
-            }
+            activeContext = mergeCommandExecutionContext(this.commandContexts.getStore(), context);
         }
         catch (error) {
             return this.batchFailure(errorMessage(error));
         }
+        return this.commandContexts.run(activeContext, async () => {
+            if (!command || typeof command !== "object") {
+                return this.batchFailure("Batch command must be an object.");
+            }
+            try {
+                switch (command.command) {
+                    case "connect":
+                        return this.connect(command.target, {
+                            name: command.name,
+                            readOnly: command.read_only,
+                            secretEnv: command.secret_env,
+                            profile: command.profile,
+                            timeoutMs: command.timeout_ms,
+                        });
+                    case "disconnect":
+                        return this.disconnect();
+                    case "status":
+                        return this.status();
+                    case "profile.add":
+                        return this.addProfile(batchString(command.name, "name"), command.target, {
+                            readOnly: command.read_only ?? true,
+                            secretEnv: command.secret_env,
+                        });
+                    case "profile.list":
+                        return this.listProfiles();
+                    case "profile.show":
+                        return this.showProfile(batchString(command.name, "name"));
+                    case "profile.remove":
+                        return this.removeProfile(batchString(command.name, "name"));
+                    case "session.start":
+                        return this.startSession(batchString(command.name, "name"));
+                    case "session.list":
+                        return this.listSessions();
+                    case "session.show":
+                        return this.showSession(command.name);
+                    case "session.summary":
+                        return this.sessionSummary();
+                    case "session.close":
+                        return this.closeSession();
+                    case "query": {
+                        const response = await this.query(batchString(command.sql, "sql"), {
+                            params: command.params ?? [],
+                            cache: command.cache ?? "auto",
+                            timeoutMs: command.timeout_ms,
+                        });
+                        if (!response.ok || !command.as)
+                            return response;
+                        const resultId = response.data.result_id;
+                        if (typeof resultId !== "string")
+                            return response;
+                        this.store.setAlias(response.session_id, command.as, resultId);
+                        return {
+                            ...response,
+                            data: { ...response.data, alias: command.as },
+                        };
+                    }
+                    case "mongo.query": {
+                        const response = await this.mongoQuery(command.mongo, {
+                            cache: command.cache ?? "auto",
+                            timeoutMs: command.timeout_ms,
+                        });
+                        if (!response.ok || !command.as)
+                            return response;
+                        const resultId = response.data.result_id;
+                        if (typeof resultId !== "string")
+                            return response;
+                        this.store.setAlias(response.session_id, command.as, resultId);
+                        return {
+                            ...response,
+                            data: { ...response.data, alias: command.as },
+                        };
+                    }
+                    case "filter": {
+                        const response = await this.filter(batchString(command.handle, "handle"), batchString(command.where, "where"), { params: command.params ?? [] });
+                        if (!response.ok || !command.as)
+                            return response;
+                        const resultId = response.data.result_id;
+                        if (typeof resultId !== "string")
+                            return response;
+                        this.store.setAlias(response.session_id, command.as, resultId);
+                        return {
+                            ...response,
+                            data: { ...response.data, alias: command.as },
+                        };
+                    }
+                    case "exec":
+                        return this.exec(batchString(command.sql, "sql"), {
+                            params: command.params ?? [],
+                            replay: command.replay ?? false,
+                            idempotencyKey: command.idempotency_key,
+                            allowUnbounded: command.allow_unbounded ?? false,
+                            allowDestructive: command.allow_destructive ?? false,
+                            timeoutMs: command.timeout_ms,
+                        });
+                    case "mongo.exec":
+                        return this.mongoExec(command.mongo, {
+                            replay: command.replay ?? false,
+                            idempotencyKey: command.idempotency_key,
+                            allowUnbounded: command.allow_unbounded ?? false,
+                            allowDestructive: command.allow_destructive ?? false,
+                            timeoutMs: command.timeout_ms,
+                        });
+                    case "show":
+                        return this.show(batchString(command.handle, "handle"));
+                    case "rows":
+                        return this.rows(batchString(command.handle, "handle"), {
+                            offset: command.offset ?? 0,
+                            limit: command.limit ?? 20,
+                        });
+                    case "count":
+                        return this.count(batchString(command.handle, "handle"));
+                    case "columns":
+                        return this.columns(batchString(command.handle, "handle"));
+                    case "alias.set":
+                        return this.setAlias(batchString(command.name, "name"), batchString(command.handle, "handle"));
+                    case "inspect":
+                        return this.inspect(batchString(command.kind, "kind"), command.table, {
+                            timeoutMs: command.timeout_ms,
+                        });
+                    case "transaction.begin":
+                        return this.beginTransaction(command.isolation);
+                    case "transaction.status":
+                        return this.transactionStatus(command.handle);
+                    case "transaction.commit":
+                        return this.commitTransaction(command.handle, {
+                            timeoutMs: command.timeout_ms,
+                        });
+                    case "transaction.rollback":
+                        return this.rollbackTransaction(command.handle);
+                    case "plan":
+                        return this.plan(batchString(command.sql, "sql"), {
+                            params: command.params ?? [],
+                            allowUnbounded: command.allow_unbounded ?? false,
+                            allowDestructive: command.allow_destructive,
+                            timeoutMs: command.timeout_ms,
+                        });
+                    case "mongo.plan":
+                        return this.mongoPlan(command.mongo, {
+                            allowUnbounded: command.allow_unbounded ?? false,
+                            allowDestructive: command.allow_destructive,
+                            timeoutMs: command.timeout_ms,
+                        });
+                    case "apply":
+                        return this.apply(batchString(command.handle, "handle"), {
+                            timeoutMs: command.timeout_ms,
+                        });
+                    case "history":
+                        return this.history(command.limit ?? 20, {
+                            origin: command.history_origin,
+                        });
+                    case "receipt":
+                        return this.receipt(batchString(command.handle, "handle"));
+                    case "doctor":
+                        return this.doctor();
+                    case "purge":
+                        return this.purge(command.scope ?? "expired");
+                    case "capabilities":
+                        return this.capabilities();
+                    default:
+                        return this.batchFailure(`Unknown batch command "${String(command.command)}".`);
+                }
+            }
+            catch (error) {
+                return this.batchFailure(errorMessage(error));
+            }
+        });
     }
     async *batch(commands, options = {}) {
         const maxCommands = options.maxCommands ?? 1_000;
@@ -1297,13 +1556,14 @@ export class StateQL {
                 yield await this.batchFailure(`Batch cannot exceed ${maxCommands} commands.`);
                 return;
             }
-            const response = await this.executeCommand(command);
+            const response = await this.executeCommand(command, options.executionContext);
             yield response;
             if (!response.ok && !options.continueOnError)
                 return;
         }
     }
     async performExec(session, connection, sql, options, context, planClaim, resolvedSource) {
+        this.rejectMongoSql(connection, "mongoExec");
         if (connection.read_only) {
             throw new StateQLError("READ_ONLY_CONNECTION", "Connection is read-only.", { suggestedAction: "Reconnect with --read-write." });
         }
@@ -1492,6 +1752,197 @@ export class StateQL {
             }
         }
     }
+    async performMongoExec(session, connection, command, options, context, planClaim, resolvedSource) {
+        const value = validatedMongoWrite(command);
+        if (connection.driver !== "mongodb") {
+            throw new StateQLError("INVALID_COMMAND", "mongoExec requires an active MongoDB connection.");
+        }
+        if (connection.read_only) {
+            throw new StateQLError("READ_ONLY_CONNECTION", "Connection is read-only.", { suggestedAction: "Reconnect with --read-write." });
+        }
+        const safety = analyzeMongoWriteSafety(value);
+        if (safety.unbounded && !options.allowUnbounded) {
+            throw new StateQLError("UNBOUNDED_MUTATION", "MongoDB mutation has an empty filter.", { extra: { override_flag: "--allow-unbounded" } });
+        }
+        if (safety.destructive && !options.allowDestructive) {
+            throw new StateQLError("DESTRUCTIVE_OPERATION_BLOCKED", "Destructive MongoDB operation requires an explicit override.", { extra: { override_flag: "--allow-destructive" } });
+        }
+        if (options.idempotencyKey !== undefined &&
+            !options.idempotencyKey.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Idempotency key cannot be empty.");
+        }
+        const serializedCommand = serializeMongoCommand(value);
+        const parameters = [serializedCommand];
+        const fingerprint = hash({
+            command: serializedCommand,
+            database: databaseIdentity(connection),
+        });
+        const transactionId = session.active_transaction_id ?? undefined;
+        if (transactionId) {
+            const transaction = this.store.getTransaction(transactionId);
+            if (!transaction ||
+                transaction.session_id !== session.id ||
+                transaction.state !== "active" ||
+                transaction.connection_id !== connection.id) {
+                throw new StateQLError("TRANSACTION_FAILED", "Active transaction does not match the active connection.");
+            }
+            if (transaction.owner_actor_id !== this.actorId) {
+                throw new StateQLError("PERMISSION_DENIED", "Only the transaction owner may stage writes.");
+            }
+        }
+        const reservation = this.store.reserveOperation({
+            sessionId: session.id,
+            actorId: this.actorId,
+            connectionId: connection.id,
+            fingerprint,
+            sql: mongoDescriptor(value.operation),
+            parameters,
+            statementType: `mongo.${value.operation}`,
+            status: transactionId ? "pending" : "executing",
+            transactionId,
+            replay: options.replay ?? false,
+            idempotencyKey: options.idempotencyKey,
+            stateVersionBefore: version(connection),
+        });
+        if (reservation.denied === "membership") {
+            throw new StateQLError("PERMISSION_DENIED", "Actor membership changed before the write was reserved.");
+        }
+        if (reservation.denied === "transaction") {
+            const active = this.store.getSession(session.id)?.active_transaction_id;
+            const transaction = active ? this.store.getTransaction(active) : undefined;
+            if (transaction && transaction.owner_actor_id !== this.actorId) {
+                throw new StateQLError("PERMISSION_DENIED", "Only the transaction owner may stage writes.");
+            }
+            throw new StateQLError("TRANSACTION_FAILED", "The active transaction changed before the write was reserved.");
+        }
+        const previous = reservation.previous;
+        if (previous &&
+            options.idempotencyKey &&
+            !options.replay &&
+            previous.fingerprint !== fingerprint) {
+            throw new StateQLError("IDEMPOTENCY_CONFLICT", "Idempotency key was already used for a different write.", { extra: { previous_operation_id: previous.id } });
+        }
+        if (previous && !reservation.operation) {
+            if (previous.status === "executing" ||
+                previous.status === "outcome_unknown") {
+                throw new StateQLError("OUTCOME_UNKNOWN", "A matching write has an unknown outcome.", {
+                    executed: true,
+                    suggestedAction: "Inspect database state, then use --replay only if another execution is safe.",
+                    extra: { previous_operation_id: previous.id },
+                });
+            }
+            if (options.idempotencyKey) {
+                return {
+                    data: {
+                        ...operationData(previous),
+                        duplicate: true,
+                        duplicate_of: previous.id,
+                        idempotency_key: options.idempotencyKey,
+                    },
+                    handle: previous.id,
+                    cached: true,
+                    stateVersion: previous.state_version_after ?? previous.state_version_before,
+                };
+            }
+            throw new StateQLError("POTENTIAL_DUPLICATE_WRITE", "An equivalent operation was previously applied.", {
+                extra: {
+                    previous_operation_id: previous.id,
+                    replay_required: true,
+                },
+            });
+        }
+        const operation = reservation.operation;
+        if (transactionId) {
+            return {
+                data: operationData(operation),
+                handle: operation.id,
+                executed: false,
+                stateVersion: version(connection),
+            };
+        }
+        let adapter;
+        let adapterSource;
+        try {
+            adapterSource =
+                resolvedSource ??
+                    (await this.resolveConnectionSource(connection, session, "exec", "write", context));
+            adapter = await this.openMongoAdapter(connection, context, adapterSource);
+        }
+        catch (error) {
+            this.store.failOperation(operation.id);
+            if (error instanceof StateQLError)
+                throw error;
+            throw new StateQLError("CONNECTION_FAILED", "Database connection failed.", {
+                retryable: true,
+            });
+        }
+        try {
+            const write = await adapter.write(value);
+            try {
+                const finalized = planClaim
+                    ? this.store.finishPlannedOperation({
+                        planId: planClaim.planId,
+                        claimToken: planClaim.claimToken,
+                        operationId: operation.id,
+                        connectionId: connection.id,
+                        affectedRows: write.affectedRows,
+                        outcome: write.outcome,
+                    })
+                    : (() => {
+                        const stateVersion = this.store.bumpVersion(connection.id);
+                        return {
+                            operation: this.store.finishOperation(operation.id, write.affectedRows, stateVersion, write.outcome),
+                            stateVersion,
+                        };
+                    })();
+                const committed = finalized.operation;
+                const after = finalized.stateVersion;
+                return {
+                    data: {
+                        ...operationData(committed),
+                        duplicate: Boolean(previous),
+                        duplicate_override: Boolean(previous),
+                    },
+                    handle: committed.id,
+                    executed: true,
+                    stateVersion: after,
+                    confidence: adapter.confidence,
+                };
+            }
+            catch (error) {
+                this.store.markOperationOutcomeUnknown(operation.id);
+                throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
+                    executed: true,
+                    suggestedAction: "Inspect database state before issuing any replacement write.",
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof StateQLError)
+                throw error;
+            if (error instanceof AdapterExecutionError && !error.outcomeUnknown) {
+                this.store.failOperation(operation.id);
+                throw stoppedStateQLError(error, false);
+            }
+            if (error instanceof AdapterWriteError && !error.outcomeUnknown) {
+                this.store.failOperation(operation.id);
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { executed: true });
+            }
+            this.store.markOperationOutcomeUnknown(operation.id);
+            throw new StateQLError("OUTCOME_UNKNOWN", safeCredentialErrorMessage(error, adapterSource), {
+                executed: true,
+                suggestedAction: "Inspect database state, then use --replay only if another execution is safe.",
+            });
+        }
+        finally {
+            try {
+                await adapter.close();
+            }
+            catch {
+                // Write outcome and metadata are already recorded.
+            }
+        }
+    }
     batchFailure(message) {
         return this.run("batch", async () => {
             throw new StateQLError("INVALID_COMMAND", message);
@@ -1528,6 +1979,18 @@ export class StateQL {
         }
         return connection;
     }
+    requireMongoConnection(session, method) {
+        const connection = this.requireConnection(session);
+        if (connection.driver !== "mongodb") {
+            throw new StateQLError("INVALID_COMMAND", `${method} requires an active MongoDB connection.`);
+        }
+        return connection;
+    }
+    rejectMongoSql(connection, nativeMethod) {
+        if (connection.driver !== "mongodb")
+            return;
+        throw new StateQLError("INVALID_COMMAND", `SQL is not supported for MongoDB connections; use ${nativeMethod} instead.`, { suggestedAction: `Use ${nativeMethod} with a native MongoDB command.` });
+    }
     requireActiveTransaction(session, id) {
         const transactionId = id ?? session.active_transaction_id;
         if (!transactionId) {
@@ -1615,8 +2078,18 @@ export class StateQL {
             throw new StateQLError("CONNECTION_FAILED", safeCredentialErrorMessage(error, source), { retryable: true });
         }
     }
+    async openMongoAdapter(connection, context, source) {
+        try {
+            return new MongoAdapter(connection, context, { source });
+        }
+        catch (error) {
+            if (error instanceof StateQLError)
+                throw error;
+            throw new StateQLError("CONNECTION_FAILED", safeCredentialErrorMessage(error, source), { retryable: true });
+        }
+    }
     executionContext(options) {
-        return createAdapterContext(executionTimeout(options.timeoutMs ?? this.timeoutMs), options.signal ?? this.signal);
+        return createAdapterContext(executionTimeout(options.timeoutMs ?? this.timeoutMs), combineAbortSignals(options.signal, this.commandContexts.getStore()?.signal, this.signal));
     }
     resultData(result, cached) {
         const rows = this.store.resultRows(result);
@@ -1646,6 +2119,7 @@ export class StateQL {
     }
     async run(command, action, historySql) {
         const started = performance.now();
+        const origin = this.commandContexts.getStore()?.origin ?? "legacy";
         let session = this.store.ensureSession(this.sessionName);
         const commandId = this.store.nextId("cmd");
         if (!this.store.isSessionMember(session.id, this.actorId)) {
@@ -1668,6 +2142,7 @@ export class StateQL {
                 id: commandId,
                 sessionId: session.id,
                 actorId: this.actorId,
+                origin,
                 command,
                 ...(result.handle ? { handle: result.handle } : {}),
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
@@ -1699,6 +2174,7 @@ export class StateQL {
                 id: commandId,
                 sessionId: session.id,
                 actorId: this.actorId,
+                origin,
                 command,
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: stateqlError.details.executed,
@@ -1727,6 +2203,7 @@ function historyEntry(item) {
         timestamp: item.timestamp,
         session_id: item.session_id,
         actor_id: item.actor_id,
+        origin: item.origin,
         command: item.command,
         sql: item.sql,
         handle: item.handle,
@@ -1736,6 +2213,41 @@ function historyEntry(item) {
         error_code: item.error_code,
     };
 }
+const COMMAND_ORIGINS = new Set([
+    "legacy",
+    "user",
+    "model",
+    "system",
+    "api",
+]);
+function parseCommandOrigin(value) {
+    if (typeof value === "string" && COMMAND_ORIGINS.has(value)) {
+        return value;
+    }
+    throw new StateQLError("INVALID_COMMAND", `Unknown command origin "${String(value)}".`);
+}
+function mergeCommandExecutionContext(inherited, supplied) {
+    if (!supplied || typeof supplied !== "object") {
+        throw new StateQLError("INVALID_COMMAND", "Command execution context must be an object.");
+    }
+    if (supplied.signal !== undefined && !(supplied.signal instanceof AbortSignal)) {
+        throw new StateQLError("INVALID_COMMAND", "Command execution context signal must be an AbortSignal.");
+    }
+    return {
+        signal: combineAbortSignals(inherited?.signal, supplied.signal),
+        origin: supplied.origin === undefined
+            ? inherited?.origin
+            : parseCommandOrigin(supplied.origin),
+    };
+}
+function combineAbortSignals(...signals) {
+    const present = signals.filter((signal) => signal !== undefined);
+    if (present.length === 0)
+        return undefined;
+    if (present.length === 1)
+        return present[0];
+    return AbortSignal.any(present);
+}
 function markTransactionOutcomeUnknown(store, transactionId, sessionId, actorId) {
     try {
         store.markTransactionOutcomeUnknown(transactionId, sessionId, actorId);
@@ -1748,12 +2260,76 @@ function boundedReadSql(sql, limit) {
     const statement = sql.trim().replace(/;\s*$/, "");
     return `SELECT * FROM (${statement}) AS _stateql_bounded LIMIT ${limit}`;
 }
+function validatedMongoRead(command) {
+    try {
+        return validateMongoReadCommand(command);
+    }
+    catch (error) {
+        throw new StateQLError("INVALID_COMMAND", errorMessage(error));
+    }
+}
+function validatedMongoWrite(command) {
+    try {
+        return validateMongoWriteCommand(command);
+    }
+    catch (error) {
+        throw new StateQLError("INVALID_COMMAND", errorMessage(error));
+    }
+}
+function mongoDescriptor(operation) {
+    return `MongoDB native ${operation}`;
+}
+function mongoPaginationWarnings(command) {
+    const ordered = command.operation === "find"
+        ? command.options?.sort !== undefined
+        : command.pipeline.some((stage) => Object.prototype.hasOwnProperty.call(stage, "$sort"));
+    return ordered
+        ? []
+        : [{
+                code: "NON_DETERMINISTIC_PAGINATION",
+                message: "MongoDB result has no explicit sort.",
+            }];
+}
+function storedMongoOperation(operation) {
+    if (!operation.statement_type.startsWith("mongo.")) {
+        throw new StateQLError("TRANSACTION_FAILED", "MongoDB transaction contains a mixed or corrupt native payload.");
+    }
+    return storedMongoWrite(operation.parameters, operation.statement_type, `operation "${operation.id}"`, "TRANSACTION_FAILED");
+}
+function storedMongoPlan(parameters, statementType, planId) {
+    return storedMongoWrite(parameters, statementType, `plan "${planId}"`, "STALE_PLAN");
+}
+function storedMongoWrite(parameters, statementType, label, errorCode) {
+    try {
+        const payload = JSON.parse(parameters);
+        if (!Array.isArray(payload) ||
+            payload.length !== 1 ||
+            typeof payload[0] !== "string") {
+            throw new Error("payload must contain one EJSON command string");
+        }
+        const command = deserializeMongoWriteCommand(payload[0]);
+        if (statementType !== `mongo.${command.operation}`) {
+            throw new Error("operation does not match its statement type");
+        }
+        return command;
+    }
+    catch {
+        throw new StateQLError(errorCode, `Stored MongoDB ${label} payload is invalid.`);
+    }
+}
 function databaseDisplayName(driver) {
+    if (driver === "mongodb")
+        return "MongoDB";
     return driver === "postgres" ? "PostgreSQL" : "MySQL";
 }
 function normalizeIsolation(isolation, driver) {
     const normalized = isolation.trim().toLowerCase().replace(/[_-]+/g, " ")
         .replace(/\s+/g, " ");
+    if (driver === "mongodb") {
+        if (normalized === "snapshot")
+            return normalized;
+        throw new StateQLError("INVALID_COMMAND", `MongoDB does not support isolation level "${normalized}".`);
+    }
     const supported = new Set([
         "serializable",
         "repeatable read",