@fadhilp/stateql 0.6.0 → 0.7.0

package/README.md

@@ -253,8 +253,9 @@ cancels active work.
 - MySQL deadlines destroy the active connection.
 - MongoDB uses driver deadlines and closes stopped operations.
 
-A timed-out write may return `OUTCOME_UNKNOWN` when its commit status cannot be
-proven.
+A timed-out or cancelled write may return `OUTCOME_UNKNOWN` when its commit
+status cannot be proven. Cancellation stops that command's driver work; it does
+not close the `StateQL` actor, and later commands remain usable.
 
 ## Durable state and result reuse
 
@@ -424,6 +425,30 @@ if (response.ok) {
 }
 ```
 
+Hosts that dispatch batch-shaped commands can attach trusted metadata out of
+band. `origin` is audit/source metadata only; it never changes actor membership,
+workspace access, or write authorization.
+
+```ts
+const controller = new AbortController();
+await stateql.executeCommand(
+  { command: "query", sql: "SELECT * FROM users", cache: "bypass" },
+  { origin: "user", signal: controller.signal },
+);
+
+const userHistory = await stateql.history(50, { origin: "user" });
+await stateql.executeCommand(
+  { command: "history", limit: 50, history_origin: "user" },
+  { origin: "model" },
+);
+```
+
+Supported origins are `legacy`, `user`, `model`, `system`, and `api`. Existing
+direct calls and `executeCommand(command)` calls are recorded as `legacy`.
+`history_origin` is only a retrieval filter; putting an `origin` field in a
+`BatchCommand` cannot attribute the command. `batch` accepts the same trusted
+context as `options.executionContext` for all commands in that batch.
+
 ### Actor workspaces
 
 `StateQL.forActor(...)` resolves the actor's attached session directly from

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
 export { StateQL } from "./stateql.js";
 export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
 export type { CredentialResolutionFailure } from "./errors.js";
-export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CapabilitiesData, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, PurgeData, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
+export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, PurgeData, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";

package/dist/src/migrations.js

@@ -64,6 +64,17 @@ const MIGRATIONS = [
             requireColumns(db, "operations", ["outcome_json"]);
         },
     },
+    {
+        name: "history_origin_v1",
+        apply(db) {
+            addColumn(db, "history", "origin", "TEXT NOT NULL DEFAULT 'legacy'");
+            db.exec("CREATE INDEX IF NOT EXISTS history_session_origin ON history(session_id, origin)");
+        },
+        validate(db) {
+            requireColumns(db, "history", ["origin"]);
+            requireIndexes(db, ["history_session_origin"]);
+        },
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -221,6 +232,7 @@ function createInitialSchema(db) {
       session_id TEXT NOT NULL,
       actor_id TEXT NOT NULL,
       command TEXT NOT NULL,
+      origin TEXT NOT NULL DEFAULT 'legacy',
       sql TEXT,
       handle TEXT,
       executed INTEGER NOT NULL,

package/dist/src/stateql.d.ts

@@ -1,4 +1,4 @@
-import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchOptions, CapabilitiesData, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
+import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, BatchOptions, CapabilitiesData, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
 export declare class StateQL {
     static forActor(options: StateQLActorOptions): StateQL;
     private readonly store;
@@ -12,6 +12,7 @@ export declare class StateQL {
     private readonly maxResultBytes;
     private readonly timeoutMs;
     private readonly signal?;
+    private readonly commandContexts;
     private readonly credentialResolver?;
     private readonly now;
     private closed;
@@ -57,11 +58,11 @@ export declare class StateQL {
     plan(sql: string, options?: PlanOptions): Promise<Response<PlanData>>;
     mongoPlan(command: MongoWriteCommand, options?: MongoPlanOptions): Promise<Response<PlanData>>;
     apply(planId: string, options?: ExecutionOptions): Promise<Response<ApplyData>>;
-    history(limit?: number): Promise<Response<HistoryData>>;
+    history(limit?: number, options?: HistoryOptions): Promise<Response<HistoryData>>;
     doctor(): Promise<Response<DoctorData>>;
     purge(scope?: "expired" | "results" | "history" | "all"): Promise<Response<PurgeData>>;
     capabilities(): Promise<Response<CapabilitiesData>>;
-    executeCommand(command: BatchCommand): Promise<Response<unknown>>;
+    executeCommand(command: BatchCommand, context?: CommandExecutionContext): Promise<Response<unknown>>;
     batch(commands: Iterable<BatchCommand> | AsyncIterable<BatchCommand>, options?: BatchOptions): AsyncGenerator<Response<unknown>>;
     private performExec;
     private performMongoExec;

package/dist/src/stateql.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { env } from "node:process";
@@ -41,6 +42,7 @@ export class StateQL {
     maxResultBytes;
     timeoutMs;
     signal;
+    commandContexts = new AsyncLocalStorage();
     credentialResolver;
     now;
     closed = false;
@@ -1303,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),
             },
         }));
@@ -1364,169 +1368,180 @@ export class StateQL {
             },
         }));
     }
-    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 "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);
-                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;
@@ -1541,7 +1556,7 @@ 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;
@@ -2074,7 +2089,7 @@ export class StateQL {
         }
     }
     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);
@@ -2104,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)) {
@@ -2126,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 } : {}),
@@ -2157,6 +2174,7 @@ export class StateQL {
                 id: commandId,
                 sessionId: session.id,
                 actorId: this.actorId,
+                origin,
                 command,
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: stateqlError.details.executed,
@@ -2185,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,
@@ -2194,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);

package/dist/src/store.d.ts

@@ -1,5 +1,5 @@
 import { DatabaseSync } from "node:sqlite";
-import type { Column, Driver, MongoWriteOutcome, Row, SqlParameters, StateConfidence } from "./types.js";
+import type { Column, CommandOrigin, Driver, MongoWriteOutcome, Row, SqlParameters, StateConfidence } from "./types.js";
 export interface SessionRecord {
     id: string;
     name: string;
@@ -98,6 +98,7 @@ export interface HistoryRecord {
     timestamp: string;
     session_id: string;
     actor_id: string;
+    origin: CommandOrigin;
     command: string;
     sql: string | null;
     handle: string | null;
@@ -270,6 +271,7 @@ export declare class StateStore {
     addHistory(input: {
         sessionId: string;
         actorId: string;
+        origin?: CommandOrigin;
         command: string;
         sql?: string;
         handle?: string;
@@ -279,7 +281,7 @@ export declare class StateStore {
         errorCode?: string;
         id?: string;
     }): HistoryRecord;
-    history(sessionId: string, limit: number): HistoryRecord[];
+    history(sessionId: string, limit: number, origin?: CommandOrigin): HistoryRecord[];
     recentOperations(sessionId: string, limit: number): OperationRecord[];
     knownResults(sessionId: string, limit: number): Array<ResultRecord & {
         alias: string | null;

package/dist/src/store.js

@@ -795,10 +795,10 @@ export class StateStore {
         const id = input.id ?? this.nextId("cmd");
         this.db
             .prepare(`INSERT INTO history
-          (id, timestamp, session_id, actor_id, command, sql, handle, executed,
-           cached, success, error_code)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(id, this.now().toISOString(), input.sessionId, input.actorId, input.command, boundedHistorySql(input.sql), input.handle ?? null, input.executed ? 1 : 0, input.cached ? 1 : 0, input.success ? 1 : 0, input.errorCode ?? null);
+          (id, timestamp, session_id, actor_id, origin, command, sql, handle,
+           executed, cached, success, error_code)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, this.now().toISOString(), input.sessionId, input.actorId, input.origin ?? "legacy", input.command, boundedHistorySql(input.sql), input.handle ?? null, input.executed ? 1 : 0, input.cached ? 1 : 0, input.success ? 1 : 0, input.errorCode ?? null);
         this.db
             .prepare(`DELETE FROM history
          WHERE rowid IN (
@@ -812,13 +812,13 @@ export class StateStore {
             .prepare("SELECT * FROM history WHERE id = ?")
             .get(id);
     }
-    history(sessionId, limit) {
+    history(sessionId, limit, origin) {
         return this.db
             .prepare(`SELECT * FROM history
-         WHERE session_id = ?
+         WHERE session_id = ?${origin === undefined ? "" : " AND origin = ?"}
          ORDER BY rowid DESC
          LIMIT ?`)
-            .all(sessionId, limit);
+            .all(...(origin === undefined ? [sessionId, limit] : [sessionId, origin, limit]));
     }
     recentOperations(sessionId, limit) {
         return this.db

package/dist/src/types.d.ts

@@ -1,5 +1,11 @@
 export type SqlDriver = "sqlite" | "postgres" | "mysql";
 export type Driver = SqlDriver | "mongodb";
+export type CommandOrigin = "legacy" | "user" | "model" | "system" | "api";
+/** Trusted host metadata for one executeCommand call; never part of BatchCommand input. */
+export interface CommandExecutionContext {
+    signal?: AbortSignal;
+    origin?: CommandOrigin;
+}
 export type CredentialAccess = "read" | "write";
 export type CredentialOperation = "connect" | "query" | "inspect" | "plan" | "exec" | "apply" | "transaction.commit";
 export interface CredentialRequest {
@@ -64,6 +70,7 @@ export interface HistoryEntry {
     timestamp: string;
     session_id: string;
     actor_id: string;
+    origin: CommandOrigin;
     command: string;
     sql: string | null;
     handle: string | null;
@@ -184,6 +191,9 @@ export interface ExecutionOptions {
     timeoutMs?: number;
     signal?: AbortSignal;
 }
+export interface HistoryOptions {
+    origin?: CommandOrigin;
+}
 export interface StateQLOptions extends ExecutionOptions {
     home?: string;
     session?: string;
@@ -272,11 +282,14 @@ export interface BatchCommand {
     limit?: number;
     isolation?: string;
     timeout_ms?: number;
+    /** Retrieval filter for the history command; does not attribute this command. */
+    history_origin?: CommandOrigin;
     scope?: "expired" | "results" | "history" | "all";
 }
 export interface BatchOptions {
     continueOnError?: boolean;
     maxCommands?: number;
+    executionContext?: CommandExecutionContext;
 }
 export interface Column {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",