@fadhilp/stateql 0.6.0 → 0.8.0

package/README.md

@@ -76,12 +76,13 @@ its cache entry is valid. Use `--cache bypass` when a fresh read is required.
 
 ## Connections and profiles
 
-A connection accepts exactly one source: a direct target, `--env`, or
-`--profile`.
+A connection accepts exactly one source: a direct target, `--env`,
+`--credential-ref`, or `--profile`.
 
 ```bash
 stql connect <sqlite-path|postgres-url|mysql-url|mongodb-url> [--name NAME] [--read-write]
 stql connect --env ENV [--name NAME] [--read-write]
+stql connect --credential-ref REF [--name NAME] [--read-write]
 stql connect --profile NAME
 stql disconnect
 stql status
@@ -113,19 +114,26 @@ connection metadata.
 
 ### Local profiles
 
-Profiles store connection targets, read-only policy, and environment-variable
-names. Credential values are never stored. Profiles persist under `STQL_HOME`
-with other StateQL metadata.
+Profiles store exactly one connection target, environment-variable name, or
+opaque credential reference together with read-only policy. Credential values
+are never stored. Profiles persist under `STQL_HOME` with other StateQL
+metadata, and list/show responses include `credential_ref` when configured.
 
 ```bash
 stql profile add local ./app.sqlite --read-write
 stql profile add production --env PROD_DATABASE_URL --read-only
+stql profile add hosted --credential-ref 'vault://team/app' --read-only
 stql profile list
 stql profile show production
 stql connect local
 stql connect --profile production
 ```
 
+Credential references are bounded nonempty opaque strings; StateQL does not
+apply environment-variable syntax or normalization to them. They can only be
+resolved by a trusted host `CredentialResolver`, so the standalone CLI may
+store them in profiles but cannot connect with them.
+
 A bare connection target matching a profile name resolves to that profile;
 otherwise it remains a path or database URL.
 
@@ -253,8 +261,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 +433,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
@@ -439,8 +472,9 @@ for user confirmation before changing membership or the shared connection.
 
 ### Harness credential resolution
 
-Library integrations can resolve a profile's credential reference through a
-trusted approval or secret-storage layer instead of mutating `process.env`:
+Library integrations can resolve environment-variable names or opaque
+credential references through a trusted approval or secret-storage layer
+instead of mutating `process.env`:
 
 ```ts
 import {
@@ -454,6 +488,7 @@ async function resolveCredential(
 ): Promise<string | undefined> {
   const approved = await credentialBroker.request({
     reference: request.reference,
+    source: request.source ?? "secret_env",
     actor: request.actorId,
     session: request.session.id,
     operation: request.operation,
@@ -471,13 +506,16 @@ const stateql = StateQL.forActor({
 });
 ```
 
-When no custom resolver is configured, StateQL reads references from
-`process.env`. A configured resolver is authoritative: returning `undefined`
-produces `CREDENTIAL_UNAVAILABLE` and never falls back to the process
-environment. Resolvers may throw `CredentialResolutionError` with `denied`,
-`cancelled`, `timeout`, or `unavailable` to produce controlled, secret-free
-failures. Unknown resolver errors are replaced with a generic
-`CREDENTIAL_RESOLUTION_FAILED` response.
+When no custom resolver is configured, StateQL reads only `secret_env`
+references from `process.env`; `credential_ref` never falls back to the
+environment. A configured resolver is authoritative for both sources: returning
+`undefined` produces `CREDENTIAL_UNAVAILABLE` and never falls back to the
+process environment. Resolver requests include `source` (`secret_env` or
+`credential_ref`) while retaining `reference`; source may be omitted only on
+legacy secret-environment request objects. Resolvers may throw
+`CredentialResolutionError` with `denied`, `cancelled`, `timeout`, or
+`unavailable` to produce controlled, secret-free failures. Unknown resolver
+errors are replaced with a generic `CREDENTIAL_RESOLUTION_FAILED` response.
 
 StateQL calls the resolver only immediately before database access, after SQL
 safety and duplicate checks. Requests contain actor and session identity, the

package/dist/src/cli.js

@@ -13,6 +13,7 @@ const parsed = parseArgs({
         name: { type: "string" },
         profile: { type: "string" },
         env: { type: "string" },
+        "credential-ref": { type: "string" },
         "read-only": { type: "boolean" },
         "read-write": { type: "boolean" },
         params: { type: "string" },
@@ -143,6 +144,7 @@ async function dispatch() {
             return stateql.connect(subcommand, {
                 ...(values.name ? { name: values.name } : {}),
                 ...(values.env ? { secretEnv: values.env } : {}),
+                ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
                 ...(values.profile ? { profile: values.profile } : {}),
                 ...(values["read-only"]
                     ? { readOnly: true }
@@ -282,6 +284,7 @@ async function dispatchProfile(action, args) {
             }
             return stateql.addProfile(requireValue(args[0], "profile name"), args[1], {
                 ...(values.env ? { secretEnv: values.env } : {}),
+                ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
                 readOnly: !values["read-write"],
             });
         case "list":
@@ -576,9 +579,10 @@ function helpText() {
 Usage: stql <command> [arguments] [options]
 
 Commands:
-  connect, disconnect, status
-  profile add|list|show|remove
-  session start|list|show|summary|close
+  connect TARGET | --env ENV | --credential-ref REF | --profile NAME
+  disconnect, status
+  profile add NAME [TARGET | --env ENV | --credential-ref REF]
+  profile list|show|remove
   query, filter, exec, show, rows, count, columns, export
   mongo query|exec|plan '<EJSON command>'
   alias set
@@ -590,6 +594,7 @@ Commands:
 
 SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
 Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
+Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
 State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
 Output: --output agent|json|jsonl|text|silent (default: agent).
 Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;

package/dist/src/connection.d.ts

@@ -1,9 +1,9 @@
 import type { ConnectionRecord } from "./store.js";
-import type { Driver, StateConfidence } from "./types.js";
+import type { CredentialSource, Driver, StateConfidence } from "./types.js";
 export declare function databaseIdentity(connection: ConnectionRecord): unknown;
 export declare function detectDriver(target: string): Driver;
 export declare function mongoDatabaseName(target: string): string;
-export declare function credentialSource(value: string, expectedDriver?: Driver): {
+export declare function credentialSource(value: string, expectedDriver?: Driver, referenceSource?: CredentialSource): {
     driver: Driver;
     source: string;
 };
@@ -13,3 +13,4 @@ export declare function version(connection: ConnectionRecord): string;
 export declare function confidence(connection: ConnectionRecord): StateConfidence;
 export declare function validateProfileName(name: string): void;
 export declare function isEnvironmentName(name: string): boolean;
+export declare function validateCredentialRef(reference: unknown): asserts reference is string;

package/dist/src/connection.js

@@ -6,6 +6,7 @@ export function databaseIdentity(connection) {
         database: connection.database_name,
         source: connection.source,
         secretEnvironment: connection.secret_env,
+        credentialReference: connection.credential_ref,
     };
 }
 export function detectDriver(target) {
@@ -43,11 +44,14 @@ export function mongoDatabaseName(target) {
     }
     throw new StateQLError("INVALID_COMMAND", "MongoDB URL must include an explicit database name.");
 }
-export function credentialSource(value, expectedDriver) {
+export function credentialSource(value, expectedDriver, referenceSource = "secret_env") {
+    const sourceLabel = referenceSource === "credential_ref"
+        ? "Credential reference"
+        : "Secret environment variable";
     const explicitSqlite = /^sqlite:(?!\/\/)/i.test(value);
     const driver = explicitSqlite ? "sqlite" : detectDriver(value);
     if (driver === "sqlite" && (!explicitSqlite || value.length === 7)) {
-        throw new StateQLError("INVALID_COMMAND", "Secret environment variable must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source; MongoDB URLs are also supported.", {
+        throw new StateQLError("INVALID_COMMAND", `${sourceLabel} must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source; MongoDB URLs are also supported.`, {
             suggestedAction: "Store the full database URL, or prefix an SQLite path with sqlite:.",
         });
     }
@@ -58,7 +62,7 @@ export function credentialSource(value, expectedDriver) {
                 throw new Error();
         }
         catch {
-            throw new StateQLError("INVALID_COMMAND", "Secret environment variable must contain a valid database URL.");
+            throw new StateQLError("INVALID_COMMAND", `${sourceLabel} must contain a valid database URL.`);
         }
     }
     if (expectedDriver && driver !== expectedDriver) {
@@ -101,3 +105,10 @@ export function validateProfileName(name) {
 export function isEnvironmentName(name) {
     return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
 }
+export function validateCredentialRef(reference) {
+    if (typeof reference === "string" &&
+        reference.trim().length > 0 &&
+        reference.length <= 1_024)
+        return;
+    throw new StateQLError("INVALID_COMMAND", "Credential reference must be a nonempty string of at most 1024 characters.");
+}

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, CredentialSource, 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,22 @@ 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"]);
+        },
+    },
+    {
+        name: "credential_refs_v1",
+        apply: migrateCredentialRefs,
+        validate: validateCredentialRefs,
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -119,10 +135,15 @@ function createInitialSchema(db) {
       name TEXT PRIMARY KEY,
       target TEXT,
       secret_env TEXT,
+      credential_ref TEXT,
       read_only INTEGER NOT NULL,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL,
-      CHECK(target IS NOT NULL OR secret_env IS NOT NULL)
+      CHECK (
+        (target IS NOT NULL) +
+        (secret_env IS NOT NULL) +
+        (credential_ref IS NOT NULL) = 1
+      )
     );
     CREATE TABLE IF NOT EXISTS connections (
       id TEXT PRIMARY KEY,
@@ -132,6 +153,7 @@ function createInitialSchema(db) {
       database_name TEXT NOT NULL,
       source TEXT NOT NULL,
       secret_env TEXT,
+      credential_ref TEXT,
       read_only INTEGER NOT NULL,
       version INTEGER NOT NULL,
       created_at TEXT NOT NULL,
@@ -221,6 +243,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,
@@ -289,6 +312,69 @@ function validateSharedSessionActors(db) {
             throw new Error(`State migration left ${table}.${column} empty.`);
     }
 }
+function migrateCredentialRefs(db) {
+    const profileColumns = new Set(db.prepare("PRAGMA table_info(profiles)").all().map((column) => column.name));
+    const hasCredentialRef = profileColumns.has("credential_ref");
+    if (!profileCredentialRefSchemaCurrent(db)) {
+        const missingSources = db.prepare(`SELECT COUNT(*) AS count FROM profiles
+       WHERE target IS NULL AND secret_env IS NULL${hasCredentialRef ? " AND credential_ref IS NULL" : ""}`).get();
+        if (missingSources.count) {
+            throw new Error("State migration found a profile without a connection source.");
+        }
+        const legacyCredentialRef = hasCredentialRef ? "credential_ref" : "NULL";
+        db.exec(`
+      ALTER TABLE profiles RENAME TO profiles_legacy_credential_refs_v1;
+      CREATE TABLE profiles (
+        name TEXT PRIMARY KEY,
+        target TEXT,
+        secret_env TEXT,
+        credential_ref TEXT,
+        read_only INTEGER NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        CHECK (
+          (target IS NOT NULL) +
+          (secret_env IS NOT NULL) +
+          (credential_ref IS NOT NULL) = 1
+        )
+      );
+      INSERT INTO profiles
+        (name, target, secret_env, credential_ref, read_only, created_at, updated_at)
+      SELECT
+        name,
+        CASE
+          WHEN ${legacyCredentialRef} IS NULL AND secret_env IS NULL THEN target
+          ELSE NULL
+        END,
+        CASE WHEN ${legacyCredentialRef} IS NULL THEN secret_env ELSE NULL END,
+        ${legacyCredentialRef},
+        read_only,
+        created_at,
+        updated_at
+      FROM profiles_legacy_credential_refs_v1;
+      DROP TABLE profiles_legacy_credential_refs_v1;
+    `);
+    }
+    addColumn(db, "connections", "credential_ref", "TEXT");
+}
+function validateCredentialRefs(db) {
+    requireColumns(db, "profiles", ["credential_ref"]);
+    requireColumns(db, "connections", ["credential_ref"]);
+    if (!profileCredentialRefSchemaCurrent(db)) {
+        throw new Error("State migration did not enforce exactly one profile source.");
+    }
+    const invalid = db.prepare(`SELECT COUNT(*) AS count FROM profiles
+     WHERE (target IS NOT NULL) +
+           (secret_env IS NOT NULL) +
+           (credential_ref IS NOT NULL) != 1`).get();
+    if (invalid.count) {
+        throw new Error("State migration left a profile with ambiguous connection sources.");
+    }
+}
+function profileCredentialRefSchemaCurrent(db) {
+    const row = db.prepare("SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = 'profiles'").get();
+    return Boolean(row?.sql && /CHECK\s*\(\s*\(target IS NOT NULL\)\s*\+\s*\(secret_env IS NOT NULL\)\s*\+\s*\(credential_ref IS NOT NULL\)\s*=\s*1\s*\)/i.test(row.sql));
+}
 function addColumn(db, table, column, definition) {
     const columns = db.prepare(`PRAGMA table_info(${table})`).all();
     if (!columns.some((candidate) => candidate.name === column)) {

package/dist/src/response-data.js

@@ -13,6 +13,7 @@ export function profileData(profile) {
         profile: profile.name,
         target: profile.target,
         secret_env: profile.secret_env,
+        credential_ref: profile.credential_ref,
         read_only: Boolean(profile.read_only),
     };
 }

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,8 +1,9 @@
+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, mongoDatabaseName, normalizeSqliteSource, validateProfileName, version, } from "./connection.js";
+import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, mongoDatabaseName, normalizeSqliteSource, validateCredentialRef, 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";
@@ -41,6 +42,7 @@ export class StateQL {
     maxResultBytes;
     timeoutMs;
     signal;
+    commandContexts = new AsyncLocalStorage();
     credentialResolver;
     now;
     closed = false;
@@ -88,12 +90,16 @@ export class StateQL {
             if (session.active_transaction_id) {
                 throw new StateQLError("TRANSACTION_FAILED", "Commit or roll back the active transaction before connecting again.");
             }
-            const sourceCount = [target, options.profile, options.secretEnv]
-                .filter((value) => value !== undefined).length;
-            if (sourceCount > 1) {
-                throw new StateQLError("INVALID_COMMAND", "Use exactly one connection target, profile, or secret environment variable.");
+            const sourceCount = [
+                target,
+                options.profile,
+                options.secretEnv,
+                options.credentialRef,
+            ].filter((value) => value !== undefined).length;
+            if (sourceCount !== 1) {
+                throw new StateQLError("INVALID_COMMAND", "Use exactly one connection target, profile, secret environment variable, or credential reference.");
             }
-            const implicitProfile = !options.profile && !options.secretEnv && target
+            const implicitProfile = !options.profile && !options.secretEnv && !options.credentialRef && target
                 ? this.store.getProfile(target)
                 : undefined;
             const profile = options.profile
@@ -102,16 +108,28 @@ export class StateQL {
             if (options.profile && !profile) {
                 throw new StateQLError("CONNECTION_NOT_FOUND", `Profile "${options.profile}" was not found.`, { suggestedAction: "Run stql profile list." });
             }
+            if (profile &&
+                [profile.target, profile.secret_env, profile.credential_ref]
+                    .filter((value) => value !== null).length !== 1) {
+                throw new StateQLError("STATE_CORRUPTED", `Profile "${profile.name}" does not have exactly one connection source.`);
+            }
             const resolvedTarget = profile?.target ?? target;
             const secretEnv = options.secretEnv ?? profile?.secret_env ?? undefined;
-            if (secretEnv && !isEnvironmentName(secretEnv)) {
+            const credentialRef = options.credentialRef ?? profile?.credential_ref ?? undefined;
+            if (secretEnv !== undefined && !isEnvironmentName(secretEnv)) {
                 throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
             }
+            if (credentialRef !== undefined)
+                validateCredentialRef(credentialRef);
+            const credentialReference = secretEnv ?? credentialRef;
+            const credentialReferenceSource = secretEnv !== undefined
+                ? "secret_env"
+                : credentialRef !== undefined ? "credential_ref" : undefined;
             const readOnly = options.readOnly ??
                 (profile ? Boolean(profile.read_only) : true);
             const context = this.executionContext(options);
-            const secret = secretEnv
-                ? await this.resolveCredential(secretEnv, session, "connect", readOnly ? "read" : "write", context, {
+            const secret = credentialReference && credentialReferenceSource
+                ? await this.resolveCredential(credentialReference, credentialReferenceSource, session, "connect", readOnly ? "read" : "write", context, {
                     ...(profile ? { profile: { name: profile.name } } : {}),
                     requestedReadOnly: readOnly,
                 })
@@ -119,23 +137,23 @@ export class StateQL {
             if (!secret) {
                 throw new StateQLError("INVALID_COMMAND", "Connection target is required.");
             }
-            const resolvedSource = secretEnv
-                ? credentialSource(secret)
+            const resolvedSource = credentialReferenceSource
+                ? credentialSource(secret, undefined, credentialReferenceSource)
                 : { driver: detectDriver(secret), source: secret };
             const { driver } = resolvedSource;
             if (driver !== "sqlite" &&
-                !secretEnv &&
+                !credentialReference &&
                 databaseUrlHasSecret(secret)) {
-                throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env.`, {
-                    suggestedAction: "Set the URL in an environment variable and reconnect with --env NAME.",
+                throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env or --credential-ref.`, {
+                    suggestedAction: "Use an environment variable or trusted host credential reference.",
                 });
             }
-            const adapterSource = secretEnv
+            const adapterSource = credentialReferenceSource
                 ? resolvedSource.source
                 : driver === "sqlite" ? normalizeSqliteSource(secret) : secret;
             const source = driver === "sqlite"
                 ? adapterSource
-                : secretEnv
+                : credentialReferenceSource
                     ? redact(secret)
                     : adapterSource;
             const databaseName = driver === "sqlite"
@@ -151,6 +169,7 @@ export class StateQL {
                 database_name: databaseName,
                 source,
                 secret_env: secretEnv ?? null,
+                credential_ref: credentialRef ?? null,
                 read_only: readOnly ? 1 : 0,
                 version: 0,
                 created_at: this.now().toISOString(),
@@ -178,6 +197,7 @@ export class StateQL {
                 databaseName,
                 source,
                 ...(secretEnv ? { secretEnv } : {}),
+                ...(credentialRef ? { credentialRef } : {}),
                 readOnly,
             });
             if (!connection) {
@@ -204,20 +224,25 @@ export class StateQL {
     async addProfile(name, target, options = {}) {
         return this.run("profile.add", async () => {
             validateProfileName(name);
-            if (Boolean(target) === Boolean(options.secretEnv)) {
-                throw new StateQLError("INVALID_COMMAND", "Profile requires exactly one target or secret environment variable.");
+            const sourceCount = [target, options.secretEnv, options.credentialRef]
+                .filter((value) => value !== undefined).length;
+            if (sourceCount !== 1 || target === "") {
+                throw new StateQLError("INVALID_COMMAND", "Profile requires exactly one target, secret environment variable, or credential reference.");
             }
             if (this.store.getProfile(name)) {
                 throw new StateQLError("INVALID_COMMAND", `Profile "${name}" already exists.`);
             }
-            if (options.secretEnv && !isEnvironmentName(options.secretEnv)) {
+            if (options.secretEnv !== undefined && !isEnvironmentName(options.secretEnv)) {
                 throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
             }
+            if (options.credentialRef !== undefined) {
+                validateCredentialRef(options.credentialRef);
+            }
             let storedTarget = target;
             if (target) {
                 const driver = detectDriver(target);
                 if (driver !== "sqlite" && databaseUrlHasSecret(target)) {
-                    throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env.`);
+                    throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env or --credential-ref.`);
                 }
                 if (driver === "sqlite")
                     storedTarget = normalizeSqliteSource(target);
@@ -226,6 +251,7 @@ export class StateQL {
                 name,
                 target: storedTarget,
                 secretEnv: options.secretEnv,
+                credentialRef: options.credentialRef,
                 readOnly: options.readOnly ?? true,
             });
             return {
@@ -1303,11 +1329,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 +1392,182 @@ 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,
+                            credentialRef: command.credential_ref,
+                            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,
+                            credentialRef: command.credential_ref,
+                        });
+                    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 +1582,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;
@@ -2007,9 +2048,13 @@ export class StateQL {
         throw new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
     }
     async resolveConnectionSource(connection, session, operation, access, context) {
-        if (!connection.secret_env)
+        const reference = connection.secret_env ?? connection.credential_ref;
+        if (!reference)
             return connection.source;
-        const value = await this.resolveCredential(connection.secret_env, session, operation, access, context, {
+        const source = connection.secret_env
+            ? "secret_env"
+            : "credential_ref";
+        const value = await this.resolveCredential(reference, source, session, operation, access, context, {
             connection: {
                 id: connection.id,
                 name: connection.name,
@@ -2018,9 +2063,9 @@ export class StateQL {
                 readOnly: Boolean(connection.read_only),
             },
         });
-        return credentialSource(value, connection.driver).source;
+        return credentialSource(value, connection.driver, source).source;
     }
-    async resolveCredential(reference, session, operation, access, context, details = {}) {
+    async resolveCredential(reference, source, session, operation, access, context, details = {}) {
         const resolver = this.credentialResolver;
         if (!resolver) {
             if (context.signal?.aborted) {
@@ -2029,13 +2074,16 @@ export class StateQL {
             if (context.deadline <= Date.now()) {
                 throw credentialStateQLError(reference, new CredentialResolutionError("timeout"));
             }
-            const value = env[reference];
-            if (value)
-                return value;
+            if (source === "secret_env") {
+                const value = env[reference];
+                if (value)
+                    return value;
+            }
             throw credentialStateQLError(reference, new CredentialResolutionError("unavailable"));
         }
         const request = {
             reference,
+            source,
             actorId: this.actorId,
             session: { id: session.id, name: session.name },
             operation,
@@ -2074,7 +2122,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 +2152,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 +2175,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 +2207,7 @@ export class StateQL {
                 id: commandId,
                 sessionId: session.id,
                 actorId: this.actorId,
+                origin,
                 command,
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: stateqlError.details.executed,
@@ -2185,6 +2236,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 +2246,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;
@@ -17,6 +17,7 @@ export interface ConnectionRecord {
     database_name: string;
     source: string;
     secret_env: string | null;
+    credential_ref: string | null;
     read_only: number;
     version: number;
     created_at: string;
@@ -25,6 +26,7 @@ export interface ProfileRecord {
     name: string;
     target: string | null;
     secret_env: string | null;
+    credential_ref: string | null;
     read_only: number;
     created_at: string;
     updated_at: string;
@@ -98,6 +100,7 @@ export interface HistoryRecord {
     timestamp: string;
     session_id: string;
     actor_id: string;
+    origin: CommandOrigin;
     command: string;
     sql: string | null;
     handle: string | null;
@@ -135,6 +138,7 @@ export declare class StateStore {
         name: string;
         target?: string;
         secretEnv?: string;
+        credentialRef?: string;
         readOnly: boolean;
     }): ProfileRecord;
     getProfile(name: string): ProfileRecord | undefined;
@@ -148,6 +152,7 @@ export declare class StateStore {
         databaseName: string;
         source: string;
         secretEnv?: string;
+        credentialRef?: string;
         readOnly: boolean;
     }): ConnectionRecord | undefined;
     getConnection(id: string): ConnectionRecord | undefined;
@@ -270,6 +275,7 @@ export declare class StateStore {
     addHistory(input: {
         sessionId: string;
         actorId: string;
+        origin?: CommandOrigin;
         command: string;
         sql?: string;
         handle?: string;
@@ -279,7 +285,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

@@ -235,9 +235,9 @@ export class StateStore {
         const timestamp = this.now().toISOString();
         this.db
             .prepare(`INSERT INTO profiles
-          (name, target, secret_env, read_only, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?)`)
-            .run(input.name, input.target ?? null, input.secretEnv ?? null, input.readOnly ? 1 : 0, timestamp, timestamp);
+          (name, target, secret_env, credential_ref, read_only, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.name, input.target ?? null, input.secretEnv ?? null, input.credentialRef ?? null, input.readOnly ? 1 : 0, timestamp, timestamp);
         return this.getProfile(input.name);
     }
     getProfile(name) {
@@ -274,9 +274,9 @@ export class StateStore {
             this.db
                 .prepare(`INSERT INTO connections
             (id, session_id, name, driver, database_name, source, secret_env,
-             read_only, version, created_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, ?)`)
-                .run(id, input.sessionId, input.name, input.driver, input.databaseName, input.source, input.secretEnv ?? null, input.readOnly ? 1 : 0, timestamp);
+             credential_ref, read_only, version, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?)`)
+                .run(id, input.sessionId, input.name, input.driver, input.databaseName, input.source, input.secretEnv ?? null, input.credentialRef ?? null, input.readOnly ? 1 : 0, timestamp);
             this.db
                 .prepare(`UPDATE sessions
            SET active_connection_id = ?, updated_at = ?
@@ -415,6 +415,8 @@ export class StateStore {
              AND previous_connection.source = current_connection.source
              AND COALESCE(previous_connection.secret_env, '') =
                  COALESCE(current_connection.secret_env, '')
+             AND COALESCE(previous_connection.credential_ref, '') =
+                 COALESCE(current_connection.credential_ref, '')
              AND previous_connection.database_name = current_connection.database_name
            ORDER BY operations.created_at DESC LIMIT 1`)
                 .get(input.connectionId, input.idempotencyKey);
@@ -795,10 +797,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 +814,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,8 +1,15 @@
 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 {
+export type CredentialSource = "secret_env" | "credential_ref";
+interface CredentialRequestBase {
     reference: string;
     actorId: string;
     session: {
@@ -24,6 +31,12 @@ export interface CredentialRequest {
         readOnly: boolean;
     };
 }
+/** Omitted source remains backward-compatible with legacy secret_env requests. */
+export type CredentialRequest = CredentialRequestBase & ({
+    source?: "secret_env";
+} | {
+    source: "credential_ref";
+});
 export type CredentialResolver = (request: CredentialRequest) => string | undefined | Promise<string | undefined>;
 export type StateConfidence = "authoritative" | "transaction_snapshot" | "database_reported" | "local" | "ttl_based" | "unknown";
 export interface Warning {
@@ -64,6 +77,7 @@ export interface HistoryEntry {
     timestamp: string;
     session_id: string;
     actor_id: string;
+    origin: CommandOrigin;
     command: string;
     sql: string | null;
     handle: string | null;
@@ -184,6 +198,9 @@ export interface ExecutionOptions {
     timeoutMs?: number;
     signal?: AbortSignal;
 }
+export interface HistoryOptions {
+    origin?: CommandOrigin;
+}
 export interface StateQLOptions extends ExecutionOptions {
     home?: string;
     session?: string;
@@ -229,10 +246,12 @@ export interface ConnectOptions extends ExecutionOptions {
     readOnly?: boolean;
     secretEnv?: string;
     profile?: string;
+    credentialRef?: string;
 }
 export interface ProfileOptions {
     readOnly?: boolean;
     secretEnv?: string;
+    credentialRef?: string;
 }
 export interface RowsOptions {
     offset?: number;
@@ -263,6 +282,7 @@ export interface BatchCommand {
     cache?: "auto" | "bypass" | "require";
     read_only?: boolean;
     secret_env?: string;
+    credential_ref?: string;
     profile?: string;
     replay?: boolean;
     idempotency_key?: string;
@@ -272,11 +292,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;
@@ -298,6 +321,7 @@ export interface ProfileData {
     profile: string;
     target: string | null;
     secret_env: string | null;
+    credential_ref: string | null;
     read_only: boolean;
 }
 export interface ProfilesData {
@@ -521,3 +545,4 @@ export interface CloseSessionData {
     session_id: string;
     state: string;
 }
+export {};

package/package.json

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