@fadhilp/stateql 0.11.0 → 0.11.1

package/README.md

@@ -479,16 +479,40 @@ context as `options.executionContext` for all commands in that batch.
 
 ### Actor workspaces
 
-`StateQL.forActor(...)` resolves the actor's attached session directly from
-StateQL storage, avoiding a duplicate actor-to-session mapping in integrations.
-On first use, it creates a legacy-compatible session named after the actor. Use
-`new StateQL({ session, actor })` when the session is already known.
-
-Membership is managed only through the library API, not batch commands:
-`linkActor(session, actorId)`, `unlinkActor(session, actorId)`,
-`listActors(session)`, and `resolveActor(actorId)`. An existing member must link
-an actor before that actor opens an existing workspace. Integrations should ask
-for user confirmation before changing membership or the shared connection.
+`StateQL.forWorkspace(...)` is a trusted-host primitive that atomically creates
+or reopens a durable workspace, attaches the requested actor, and returns a
+client bound to that actor:
+
+```ts
+const stateql = StateQL.forWorkspace({
+  home: "./.stql",
+  workspace: "pylon-global",
+  actor: "pylon-session:abc123",
+  credentialResolver,
+  signal,
+});
+```
+
+Repeated opens of the same actor and workspace are idempotent. An actor already
+attached elsewhere fails with a `StateQLError` whose code is
+`PERMISSION_DENIED`; StateQL never moves or merges it. All actor options,
+including limits, credential resolution, cancellation, `home`, and `now`, are
+preserved. The workspace name also reserves a same-named actor identity for
+legacy compatibility, so workspace and actor identifiers must be globally
+collision-free. The returned client is still bound only to `actor`, preserving
+plan, transaction, operation, and history ownership.
+
+`StateQL.forActor(...)` retains its existing behavior: it resolves the actor's
+attached session directly from StateQL storage and creates a legacy-compatible
+session named after the actor on first use. Use `new StateQL({ session, actor })`
+when the session and membership are already known.
+
+Membership management and `forWorkspace` are library-only host capabilities,
+not batch or CLI commands. Existing member-authorized management remains
+available through `linkActor(session, actorId)`, `unlinkActor(session, actorId)`,
+`listActors(session)`, and `resolveActor(actorId)`. Integrations should ask for
+user confirmation before changing membership or the shared connection; a host
+calling `forWorkspace` is responsible for authorizing that workspace access.
 
 ### Harness credential resolution
 

package/dist/src/index.d.ts

@@ -2,4 +2,4 @@ export { StateQL } from "./stateql.js";
 export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
 export type { CredentialResolutionFailure } from "./errors.js";
 export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
-export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, 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, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, 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, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, 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, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";

package/dist/src/stateql.d.ts

@@ -1,9 +1,11 @@
 import { type TableChange } from "./table-editor.js";
-import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
+import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
 export declare class StateQL {
     /** Runtime contract marker for passwordRef/password_ref support. */
     static readonly passwordReferenceVersion: 1;
     static forActor(options: StateQLActorOptions): StateQL;
+    /** Opens one actor in a named shared workspace for a trusted library host. */
+    static forWorkspace(options: StateQLWorkspaceOptions): StateQL;
     private readonly store;
     private readonly sessionName;
     private readonly actorId;

package/dist/src/stateql.js

@@ -17,6 +17,7 @@ import { compactRows, defaultHome, hash, isSqlParameters, parseJson, redact, } f
 const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
 const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 const DEFAULT_CREDENTIAL_RESOLUTION_TIMEOUT_MS = 120_000;
+const WORKSPACE_BOOTSTRAP = Symbol("StateQL.workspaceBootstrap");
 export class StateQL {
     /** Runtime contract marker for passwordRef/password_ref support. */
     static passwordReferenceVersion = 1;
@@ -37,6 +38,21 @@ export class StateQL {
             store.close();
         }
     }
+    /** Opens one actor in a named shared workspace for a trusted library host. */
+    static forWorkspace(options) {
+        if (!options.workspace.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Workspace name is required.");
+        }
+        if (!options.actor.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
+        }
+        const { workspace, ...actorOptions } = options;
+        return new StateQL({
+            ...actorOptions,
+            session: workspace,
+            [WORKSPACE_BOOTSTRAP]: true,
+        });
+    }
     store;
     sessionName;
     actorId;
@@ -80,7 +96,12 @@ export class StateQL {
         }
         const store = new StateStore(options.home ?? defaultHome(), this.now, maxStateBytes);
         try {
-            store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
+            if (options[WORKSPACE_BOOTSTRAP]) {
+                store.bootstrapWorkspace(this.sessionName, this.actorId);
+            }
+            else {
+                store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
+            }
         }
         catch (error) {
             store.close();

package/dist/src/store.d.ts

@@ -132,6 +132,7 @@ export declare class StateStore {
     private insertWithRandomId;
     ensureSession(name?: string): SessionRecord;
     bootstrapSession(name: string, actorId: string, ensureLegacyMembership: boolean): SessionRecord;
+    bootstrapWorkspace(name: string, actorId: string): SessionRecord;
     createSession(name: string): SessionRecord;
     isSessionMember(sessionId: string, actorId: string): boolean;
     linkActor(sessionId: string, requestingActorId: string, actorId: string): "linked" | "already_linked" | "actor_conflict" | "denied";

package/dist/src/store.js

@@ -132,6 +132,56 @@ export class StateStore {
             throw error;
         }
     }
+    bootstrapWorkspace(name, actorId) {
+        const timestamp = this.now().toISOString();
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            let row = this.db
+                .prepare("SELECT id, status FROM sessions WHERE name = ? LIMIT 1")
+                .get(name);
+            const identities = actorId === name ? [actorId] : [name, actorId];
+            for (const identity of identities) {
+                const existing = this.resolveActor(identity);
+                if (existing && existing.id !== row?.id) {
+                    throw new StateQLError("PERMISSION_DENIED", `Actor "${identity}" is already attached to workspace "${existing.name}" and cannot be attached to workspace "${name}".`);
+                }
+            }
+            if (!row) {
+                const id = this.insertWithRandomId("s", "sessions", (candidate) => {
+                    this.db
+                        .prepare(`INSERT INTO sessions
+                (id, name, status, created_at, updated_at)
+               VALUES (?, ?, 'active', ?, ?)`)
+                        .run(candidate, name, timestamp, timestamp);
+                });
+                row = { id, status: "active" };
+            }
+            else if (row.status !== "active") {
+                this.db
+                    .prepare(`UPDATE sessions
+             SET status = 'active', updated_at = ?
+             WHERE id = ?`)
+                    .run(timestamp, row.id);
+            }
+            for (const identity of identities) {
+                if (this.isSessionMember(row.id, identity))
+                    continue;
+                this.db
+                    .prepare(`INSERT INTO session_members(session_id, actor_id, attached_at)
+             VALUES (?, ?, ?)`)
+                    .run(row.id, identity, timestamp);
+            }
+            const session = this.getSessionByName(name);
+            if (!session)
+                throw new Error(`Could not open workspace "${name}".`);
+            this.db.exec("COMMIT");
+            return session;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
     createSession(name) {
         return this.bootstrapSession(name, name, true);
     }

package/dist/src/types.d.ts

@@ -274,6 +274,10 @@ export interface StateQLOptions extends ExecutionOptions {
 export type StateQLActorOptions = Omit<StateQLOptions, "session" | "actor"> & {
     actor: string;
 };
+/** Trusted-host options for opening one actor in a named shared workspace. */
+export type StateQLWorkspaceOptions = StateQLActorOptions & {
+    workspace: string;
+};
 export interface QueryOptions extends ExecutionOptions {
     params?: SqlParameters;
     cache?: "auto" | "bypass" | "require";

package/package.json

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