@xcitedbs/client 0.2.19 → 0.2.21

package/README.md

@@ -65,7 +65,7 @@ Call **`POST /api/v1/test/sessions`** with your normal API key or Bearer (same p
 - **Default:** isolated empty LMDB under the server’s `_test/<uuid>/` (writes never touch production).
 - **Overlay:** pass **`overlay: true`** in **`createTestSession`** options (or **`POST`** body **`{"overlay":true}`**). The server layers a writable LMDB on top of the **current project’s on-disk data opened read-only** so you can debug against real data; changes still live only under `_test/<uuid>/`. Use project-scoped credentials or platform Bearer + **`X-Project-Id`** as when calling production APIs.
 
-Tear down with **`destroyTestSession()`** (or **`DELETE /api/v1/test/sessions/current`** with the session header). See **`llms.txt`** / **`llms-full.txt`** in this package for full behavior, limits, and auth notes.
+Tear down with **`destroyTestSession()`** (or **`DELETE /api/v1/test/sessions/current`** with the session header). With the **same** API key / Bearer and **no** `X-Test-Session`, use **`listTestSessions()`**, **`destroyAllTestSessions()`**, and **`destroyTestSessionByToken(token)`** to clear leaked sessions before large suites (avoids the default per-credential concurrent cap). See **`llms.txt`** / **`llms-full.txt`** in this package for full behavior, limits, and auth notes.
 
 ## Build
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, Flags, JsonDocumentBatchItem, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, Flags, JsonDocumentBatchItem, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -57,6 +57,20 @@ export declare class XCiteDBClient {
     destroyTestSession(): Promise<{
         message: string;
     }>;
+    /**
+     * List active test sessions for the current API key or Bearer (`GET /api/v1/test/sessions`).
+     * Does not send `X-Test-Session` (management route).
+     */
+    listTestSessions(): Promise<TestSessionInfo[]>;
+    /** Destroy every test session owned by this credential (`DELETE /api/v1/test/sessions/all`). */
+    destroyAllTestSessions(): Promise<{
+        message: string;
+        destroyed: number;
+    }>;
+    /** Destroy a single owned session by token (`DELETE /api/v1/test/sessions/{token}`). */
+    destroyTestSessionByToken(token: string): Promise<{
+        message: string;
+    }>;
     /** True if this client would send API key or Bearer credentials on a normal request. */
     private sentAuthCredentials;
     /** 401 on these paths is an expected auth flow outcome, not a dead session. */
@@ -396,6 +410,36 @@ export declare class XCiteDBClient {
         message?: string;
         autoResolve?: 'none' | 'source' | 'target';
     }): Promise<MergeResult>;
+    /** List app-user draft workspaces visible to the caller (`GET /api/v1/user-workspaces`). */
+    listUserWorkspaces(): Promise<{
+        user_workspaces: Record<string, unknown>[];
+    }>;
+    /** Create a user workspace (`POST /api/v1/user-workspaces`). Returns the workspace record (top-level JSON). */
+    createUserWorkspace(name: string, options?: {
+        sourceBranch?: string;
+        sourceDate?: string;
+    }): Promise<Record<string, unknown>>;
+    getUserWorkspace(id: string): Promise<{
+        user_workspace: Record<string, unknown>;
+    }>;
+    deleteUserWorkspace(id: string): Promise<void>;
+    addUserWorkspaceGrant(id: string, body: {
+        user_id?: string;
+        group?: string;
+        mode: string;
+    }): Promise<{
+        user_workspace: Record<string, unknown>;
+    }>;
+    removeUserWorkspaceGrant(id: string, body: {
+        user_id?: string;
+        group?: string;
+    }): Promise<{
+        user_workspace: Record<string, unknown>;
+    }>;
+    publishUserWorkspace(id: string, options?: {
+        message?: string;
+        autoResolve?: string;
+    }): Promise<Record<string, unknown>>;
     /**
      * Create `workspaceName` from {@link options.fromBranch} (or current context), run `fn` scoped to that workspace,
      * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.

package/dist/client.js

@@ -379,6 +379,33 @@ class XCiteDBClient {
         }
         return this.request('DELETE', '/api/v1/test/sessions/current', undefined, undefined, { no401Retry: true });
     }
+    /**
+     * List active test sessions for the current API key or Bearer (`GET /api/v1/test/sessions`).
+     * Does not send `X-Test-Session` (management route).
+     */
+    async listTestSessions() {
+        const r = await this.request('GET', '/api/v1/test/sessions', undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+        const rows = r.sessions ?? [];
+        return rows.map((s) => ({
+            sessionToken: String(s.session_token ?? ''),
+            createdAt: Number(s.created_at ?? 0),
+            lastUsed: Number(s.last_used ?? 0),
+            ...(s.overlay === true ? { overlay: true } : {}),
+        }));
+    }
+    /** Destroy every test session owned by this credential (`DELETE /api/v1/test/sessions/all`). */
+    async destroyAllTestSessions() {
+        const r = await this.request('DELETE', '/api/v1/test/sessions/all', undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+        return {
+            message: String(r.message ?? ''),
+            destroyed: Number(r.destroyed ?? 0),
+        };
+    }
+    /** Destroy a single owned session by token (`DELETE /api/v1/test/sessions/{token}`). */
+    async destroyTestSessionByToken(token) {
+        const enc = encodeURIComponent(token);
+        return this.request('DELETE', `/api/v1/test/sessions/${enc}`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
     /** True if this client would send API key or Bearer credentials on a normal request. */
     sentAuthCredentials() {
         return !!(this.apiKey || this.accessToken || this.appUserAccessToken);
@@ -505,10 +532,13 @@ class XCiteDBClient {
     }
     async request(method, path, body, extraHeaders, opts) {
         const no401Retry = opts?.no401Retry === true;
+        const suppressTestSessionHeader = opts?.suppressTestSessionHeader === true;
         for (let attempt = 0; attempt < 2; attempt++) {
             const url = joinUrl(this.baseUrl, path);
             const headers = {
-                ...this.requestHeaders(),
+                ...this.authHeaders(),
+                ...this.contextHeaders(),
+                ...(suppressTestSessionHeader ? {} : this.testHeaders()),
                 ...extraHeaders,
             };
             const outgoingRequestId = newClientRequestId();
@@ -1216,6 +1246,37 @@ class XCiteDBClient {
     async mergeBranch(targetBranch, sourceBranch, options) {
         return this.publishWorkspace(targetBranch, sourceBranch, options);
     }
+    /** List app-user draft workspaces visible to the caller (`GET /api/v1/user-workspaces`). */
+    async listUserWorkspaces() {
+        return this.request('GET', '/api/v1/user-workspaces');
+    }
+    /** Create a user workspace (`POST /api/v1/user-workspaces`). Returns the workspace record (top-level JSON). */
+    async createUserWorkspace(name, options) {
+        const body = { name };
+        if (options?.sourceBranch)
+            body.source_branch = options.sourceBranch;
+        if (options?.sourceDate)
+            body.source_date = options.sourceDate;
+        return this.request('POST', '/api/v1/user-workspaces', body);
+    }
+    async getUserWorkspace(id) {
+        return this.request('GET', `/api/v1/user-workspaces/${encodeURIComponent(id)}`);
+    }
+    async deleteUserWorkspace(id) {
+        await this.request('DELETE', `/api/v1/user-workspaces/${encodeURIComponent(id)}`);
+    }
+    async addUserWorkspaceGrant(id, body) {
+        return this.request('POST', `/api/v1/user-workspaces/${encodeURIComponent(id)}/grants`, body);
+    }
+    async removeUserWorkspaceGrant(id, body) {
+        return this.request('DELETE', `/api/v1/user-workspaces/${encodeURIComponent(id)}/grants`, body);
+    }
+    async publishUserWorkspace(id, options) {
+        const body = { auto_resolve: options?.autoResolve ?? 'none' };
+        if (options?.message)
+            body.message = options.message;
+        return this.request('POST', `/api/v1/user-workspaces/${encodeURIComponent(id)}/publish`, body);
+    }
     /**
      * Create `workspaceName` from {@link options.fromBranch} (or current context), run `fn` scoped to that workspace,
      * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.

package/dist/client.test.js

@@ -11,6 +11,27 @@ const strict_1 = __importDefault(require("node:assert/strict"));
 const client_js_1 = require("./client.js");
 const types_js_1 = require("./types.js");
 (0, node_test_1.describe)('XCiteDBClient error mapping', () => {
+    (0, node_test_1.it)('listTestSessions omits X-Test-Session even when client has testSessionToken', async () => {
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input, init) => {
+            const h = new Headers(init?.headers);
+            strict_1.default.equal(h.get('X-Test-Session'), null);
+            strict_1.default.equal(h.get('X-API-Key'), 'test-key');
+            return new Response(JSON.stringify({ sessions: [] }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'test-key',
+                testSessionToken: '00000000-0000-0000-0000-000000000001',
+            });
+            const list = await c.listTestSessions();
+            strict_1.default.deepEqual(list, []);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
     (0, node_test_1.it)('403 becomes XCiteDBForbiddenError with policy_id and request ids', async () => {
         const orig = globalThis.fetch;
         globalThis.fetch = node_test_1.mock.fn(async () => {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { XCiteDBClient } from './client';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, Flags, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, Flags, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError, XCiteDBForbiddenError, XCiteDBNotFoundError, XCiteDBAuthError, XCiteDBLockConflictError, } from './types';

package/dist/types.d.ts

@@ -524,6 +524,14 @@ export interface TestSessionBootstrapSummary {
     developer_bypass_applied?: boolean;
     policies_created?: string[];
 }
+/** One row from `GET /api/v1/test/sessions` (management; no `X-Test-Session` on that route). */
+export interface TestSessionInfo {
+    sessionToken: string;
+    createdAt: number;
+    lastUsed: number;
+    /** Present when the session was created with overlay mode. */
+    overlay?: true;
+}
 /** Options for {@link XCiteDBClient.createTestSession} (provisions via API key or Bearer). */
 export interface CreateTestSessionOptions {
     baseUrl: string;

package/llms-full.txt

@@ -35,10 +35,11 @@ Before reading the full reference, note these critical differences from typical
 - **Write at a specific date:** Set `X-Date` / `context.date` and write — every dated write is a **temporal revision**; no workspace or checkpoint required.
 - **Read as-of a date:** Set `X-Date` and read; the engine returns the revision at or before that instant.
 - **Isolated editing (draft → publish):** Create a **workspace**, edit, then **publish** to the target timeline; optional **checkpoints** for named snapshots.
+- **App-user user workspaces (`_uw/<owner>/<slug>`):** **`GET/POST /api/v1/user-workspaces`**, grants, publish — see repository **`web/src/docs/content/user-workspaces.md`**.
 - **Audit trail:** Checkpoints carry messages and affected identifiers; **bookmarks** name a checkpoint.
 - **Undo a batch:** **Revert** to a prior checkpoint on that workspace.
 
-Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
+Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/api/v1/user-workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
 
 ## Common Pitfalls
 
@@ -223,14 +224,15 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 | **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). Optional JSON body **`{"overlay":true}`** provisions a **read-through production** session (writable delta only under `_test/<uuid>/`; production LMDB is read-only base). |
 | **Use** | Send **`X-Test-Session: <session_token>`** on document and other data API requests. The server routes to a dedicated LMDB under its data root (`_test/<id>/`), not the caller’s production tenant. **`tenant_id` / `X-Project-Id` semantics do not select production** while the test header is present—the synthetic test tenant is implied. |
 | **Auth** | **Default:** developer auth (API key / platform JWT) is **bypassed** with a synthetic admin identity. However, **app-user identity is still recognized**: if `X-App-User-Token` or a Bearer app-user JWT is present, the request runs as that app user (for routes like `/app/auth/me`). **`X-Test-Auth: required`:** all auth is validated normally; ABAC applies, but data still comes from the test session DB. |
-| **Manage** | **`GET /api/v1/test/sessions`** — list sessions for the current credential. **`DELETE /api/v1/test/sessions/current`** — destroy the session named by **`X-Test-Session`** (no other auth). **`DELETE /api/v1/test/sessions/all`** — destroy all sessions for the credential. **`DELETE /api/v1/test/sessions/{token}`** — destroy one session if owned by the credential. Do **not** send **`X-Test-Session`** on these `/api/v1/test/*` routes. |
+| **Manage** | **`GET /api/v1/test/sessions`** — list sessions for the current credential. **`DELETE /api/v1/test/sessions/current`** — destroy the session named by **`X-Test-Session`** (no other auth). **`DELETE /api/v1/test/sessions/all`** — destroy all sessions for the credential. **`DELETE /api/v1/test/sessions/{token}`** — destroy one session if owned by the credential. Do **not** send **`X-Test-Session`** on these `/api/v1/test/*` routes. **SDKs:** JS `listTestSessions` / `destroyAllTestSessions` / `destroyTestSessionByToken`; Python `list_test_sessions` / `destroy_all_test_sessions` / `destroy_test_session_by_token`; C++ same snake_case; MCP tools `list_test_sessions`, `destroy_all_test_sessions`, `destroy_test_session_by_token`. |
+| **429 / suites** | Per-credential concurrent cap (default **5**, `test.max_sessions_per_key`). If **`createTestSession`** returns **429**, call **`destroyAllTestSessions`** (same API key / Bearer, no `X-Test-Session`) before retrying — typical **once in `beforeAll`** for large wet suites. |
 | **CORS** | Browsers may need **`X-Test-Session`** and **`X-Test-Auth`** in the deployment’s allowed CORS headers (defaults include them). |
 
 **SDK usage (summary):**
 
-- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`; optional **`bootstrap`** (`user_isolation`, `developer_bypass`, `policies`); read **`lastTestSessionBootstrap`** on the returned client when the server included a summary. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
-- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …, bootstrap={…})` provisions and tears down; or **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`**, **`bootstrap`**, or both, then construct the client with the returned token; **`client.last_test_session_bootstrap`** mirrors the server summary.
-- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay`**, optional **`test_session_bootstrap`** on `XCiteDBClientOptions`, optional `test_require_auth`; **`last_test_session_bootstrap()`** on the returned client; `destroy_test_session()`.
+- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`; optional **`bootstrap`** (`user_isolation`, `developer_bypass`, `policies`); read **`lastTestSessionBootstrap`** on the returned client when the server included a summary. `destroyTestSession()` calls `DELETE …/test/sessions/current`. On a **normal** client (same `apiKey` / Bearer, **no** `testSessionToken`), **`listTestSessions()`**, **`destroyAllTestSessions()`**, **`destroyTestSessionByToken(token)`** wrap the management routes (they never send `X-Test-Session`).
+- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …, bootstrap={…})` provisions and tears down; or **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`**, **`bootstrap`**, or both, then construct the client with the returned token; **`client.last_test_session_bootstrap`** mirrors the server summary. Management: **`await client.list_test_sessions()`**, **`await client.destroy_all_test_sessions()`**, **`await client.destroy_test_session_by_token(token)`** with `suppress_test_session` behavior (omit `X-Test-Session` on those paths).
+- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay`**, optional **`test_session_bootstrap`** on `XCiteDBClientOptions`, optional `test_require_auth`; **`last_test_session_bootstrap()`** on the returned client; `destroy_test_session()`. Management: **`list_test_sessions()`**, **`destroy_all_test_sessions()`**, **`destroy_test_session_by_token(token)`** on a client carrying the provisioning credential only.
 
 **A fresh test session is an empty tenant with zero policies.** With `X-Test-Auth: required`, ABAC default-deny applies until you bootstrap user isolation and/or policies. Typical `POST /api/v1/test/sessions` body:
 
@@ -256,11 +258,14 @@ describe('XciteDB integration', () => {
   let client: XCiteDBClient;
 
   beforeAll(async () => {
-    // Provisions an isolated, throwaway LMDB — production data is never touched.
-    client = await XCiteDBClient.createTestSession({
+    const base = {
       baseUrl: process.env.XCITEDB_URL ?? 'http://localhost:8080',
       apiKey: process.env.XCITEDB_API_KEY!,
-    });
+    };
+    // Optional: clear sessions leaked from killed CI runs (same API key; default cap is 5).
+    const janitor = new XCiteDBClient(base);
+    await janitor.destroyAllTestSessions();
+    client = await XCiteDBClient.createTestSession(base);
   });
 
   afterAll(async () => {
@@ -544,8 +549,8 @@ Attach structured **JSON metadata** to documents or nodes.
 | `identifier` **or** `query` | one required | Target document id or document query |
 | `value` | yes | JSON to write (omit only for string-specific query batch paths handled by the server) |
 | `path` | no (default `""`) | Meta path (dot-separated keys; `[i]` for array indices) |
-| `mode` | no (default `"set"`) | `"set"` — write/replace at `path`. For **arrays** at `path`, indices `0..n-1` are written and any previous tail beyond the new length is cleared. `"append"` — for **arrays** at `path`, new elements are written after existing indices (extend in place). |
-| `overwrite` | no (default `false`) | When `true`, delete existing metadata under `path` before applying `value`. |
+| `mode` | no (default `"set"`) | `"set"` — write/replace at `path`. For **arrays** at `path`, indices `0..n-1` are written and any previous tail beyond the new length is cleared. `"append"` — array-extend behavior applies only when the **payload** at `path` is a JSON **array**; new elements are written after the stored length from the array marker `[n]` at `path`. If nothing array-shaped is stored there, the effective prior length is `0` (indices start at `0`). Scalars or a non-array object at `path` are not merged via array-append (object payloads recurse; nested array fields follow the same rules under their own paths). See **Append semantics** below. |
+| `overwrite` | no (default `false`) | When `true`, delete existing metadata under `path` **before** applying `value`. That runs before array logic: with `mode: "append"` it clears the stored `[n]` marker, so the subsequent write always starts at index `0` (you do not keep prior elements). To extend an existing array, use **`overwrite: false`**. For “clear then replace the whole array”, use **`overwrite: true`** with **`mode: "set"`** (or `append` after clear, which is equivalent to writing from `0`). |
 | `first_match` | no | With `query`, only the first matching identifier is updated when `true`. |
 
 ```json
@@ -558,7 +563,35 @@ Attach structured **JSON metadata** to documents or nodes.
 }
 ```
 
-Use `"mode": "append"` to extend arrays at `path` instead of replacing them.
+### Append semantics
+
+- **`mode: "append"`** only changes array behavior when the **JSON at `path` in this request’s `value`** is an **array** (or when traversing an object payload, each **nested** field whose value is an array, under the same `append` flag). A **scalar** or **non-array object** at `path` does not run “append after `[n]`” logic for that node.
+- To **extend** an existing list in storage, the **stored** value at `path` should already be an array (the server keeps a `[length]` marker). New payload elements are written at indices `length`, `length+1`, … If there is **no** valid array marker at `path` in storage, append still succeeds but behaves like a **first write** from index `0`.
+- **`overwrite: true` + `append`:** do not use this expecting “delete old tail then append onto what was left” — overwrite **removes everything under `path` first**, so append always indexes from **`0`**. Prefer **`overwrite: false`** + **`append`** to grow a list; use **`overwrite: true`** + **`set`** when replacing the whole subtree/array.
+
+**Example — extend `tags` without overwrite** (stored `tags` is `["a","b"]`; result `["a","b","c","d"]`):
+
+```json
+{
+  "identifier": "/book/ch1",
+  "path": "tags",
+  "mode": "append",
+  "overwrite": false,
+  "value": ["c", "d"]
+}
+```
+
+**Example — same payload with `overwrite: true`** (clears `tags` first; result only `["c","d"]`):
+
+```json
+{
+  "identifier": "/book/ch1",
+  "path": "tags",
+  "mode": "append",
+  "overwrite": true,
+  "value": ["c", "d"]
+}
+```
 
 Can also use `"query"` instead of `"identifier"` to target multiple documents by query filter.
 

package/llms.txt

@@ -10,7 +10,7 @@ These are the most common sources of confusion for developers and AI assistants:
 
 2. **Identifiers are hierarchical, path-like strings** — e.g. `/us/bills/hr1`, `/manual/v2/chapter3`. They are NOT auto-generated UUIDs. The leading `/` is part of the identifier. Parent/child relationships are derived from the path structure (like a filesystem). The server indexes this hierarchy natively.
 
-3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type, stored with structural shredding. JSON documents are a parallel store keyed by identifier string. Both are fully versioned.
+3. **Shredding vs sharding (do not confuse them).** **Shredding** breaks **XML and JSON** hierarchically into small **fragments** (elements, attributes, objects, fields, array slots, and similar structural pieces) so each fragment can live under its **own LMDB key/value**. That is **not** “sharding” in the usual distributed-database sense. **Sharding** in XCiteDB means **per-tenant** isolation (each **project** is its own shard of data); **finer-grain sharding** is planned separately. Sharding and shredding are unrelated axes. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type; JSON documents are a parallel store keyed by identifier string. Both are fully versioned.
 
 4. **`X-Date` and temporal revision (not “only now”).** Workspace and date context travel as HTTP headers (`X-Workspace` preferred, `X-Branch` alias, `X-Date`), or the SDK `context` option — not as URL path segments. **`X-Date` is not limited to the current server time.** Pass any instant you need as **ISO 8601** (e.g. `2024-01-15T00:00:00`) or **`mm/dd/yyyy`** (optional **`:HH:MM:SS`**) — for example an **official publication or approval date**, or any historical “as of” moment. When **`X-Date` is set**, that value applies to **both** **reads** (query as-of that instant) **and** **writes** (the new revision is stored under that revision instant). When **`X-Date` is omitted** and you do **not** send **`X-Unversioned: true`**, **writes** use **flat** keys (no date suffix on that write); **reads** still resolve **as of the current time**. **`X-Unversioned: true`** requests explicit flat keys and must **not** be combined with **`X-Date`** (the server returns 400).
 
@@ -32,11 +32,13 @@ These are the most common sources of confusion for developers and AI assistants:
 
 - **Isolated editing** (draft/review/publish): Create a **workspace**, make changes, then **publish** to the main timeline. Optionally create **checkpoints** for named snapshots within the workspace.
 
+- **App-user draft workspaces (`_uw/<owner>/<slug>`):** REST **`/api/v1/user-workspaces`**; SDK: `listUserWorkspaces`, `createUserWorkspace`, `getUserWorkspace`, `deleteUserWorkspace`, `addUserWorkspaceGrant`, `removeUserWorkspaceGrant`, `publishUserWorkspace`.
+
 - **Audit trail with named snapshots:** Create checkpoints with messages. List/inspect checkpoints for history.
 
 - **Undo a batch of changes:** **Revert** to a prior checkpoint (removes all changes after that point on the workspace).
 
-Legacy REST paths (`/api/v1/branches`, `/commits`, `/tags`, `/diff`) remain as **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
+Legacy REST paths (`/api/v1/branches`, `/commits`, `/tags`, `/diff`) remain as **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/api/v1/user-workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
 
 ## Glossary: Project id, display name, and groups
 
@@ -122,7 +124,8 @@ SDKs surface these fields on typed errors (e.g. `XCiteDBForbiddenError.policyId`
 2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Workspace` / `context` as needed). Data writes go under the server’s `_test/<session>/` tree; overlay sessions **do not** write to production paths.
 3. **Auth behavior:** Developer auth (API key / platform JWT) is bypassed by default for frictionless tests. **App-user identity** (`X-App-User-Token` or Bearer app-user JWT) **is still recognized** in default mode, so `registerAppUser` → `loginAppUser` → `appUserMe` works inside a test session. To also exercise developer auth and ABAC policies, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
 4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
-5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })`, optional `overlay: true`, optional `testRequireAuth`, optional `bootstrap` (`user_isolation`, `developer_bypass`, `policies`), then read `lastTestSessionBootstrap` on the returned client; `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(..., bootstrap={...})` or provision with **`POST /api/v1/test/sessions`** (JSON may include **`{"overlay":true}`** and/or **`bootstrap`**); use `client.last_test_session_bootstrap` after creation; pass `test_session_token` / `test_require_auth` to the constructor as before. **C++:** `XCiteDBClient::create_test_session(options)` with optional `test_session_overlay`, optional `test_session_bootstrap` on `XCiteDBClientOptions`, `last_test_session_bootstrap()` on the returned client, `destroy_test_session()`, optional `test_require_auth`.
+5. **429 / leaked sessions:** The server caps concurrent sessions per credential (`test.max_sessions_per_key`, default **5**). If **`createTestSession`** returns **429** (“Too many active test sessions for this credential”), reap with the **same** API key or Bearer (do **not** send `X-Test-Session` on management routes): **`destroyAllTestSessions()`** (JS), **`destroy_all_test_sessions()`** (Python/C++), or HTTP **`DELETE /api/v1/test/sessions/all`**. Large E2E wrappers often call that once before the suite so killed runs do not exhaust the slot budget.
+6. **SDKs (management = provisioning credential, no `X-Test-Session`):** **JS/TS:** `createTestSession`, `destroyTestSession()` (current session), `listTestSessions()`, `destroyAllTestSessions()`, `destroyTestSessionByToken(token)`; optional `overlay`, `testRequireAuth`, `bootstrap`; read `lastTestSessionBootstrap` on the returned client. **Python:** `test_session(...)` or manual POST; `destroy_test_session()`, `list_test_sessions()`, `destroy_all_test_sessions()`, `destroy_test_session_by_token(token)`; `last_test_session_bootstrap`. **C++:** `create_test_session`, `destroy_test_session()`, `list_test_sessions()`, `destroy_all_test_sessions()`, `destroy_test_session_by_token(token)`; `last_test_session_bootstrap`. **MCP:** tools `list_test_sessions`, `destroy_all_test_sessions`, `destroy_test_session_by_token`.
 
 **A fresh test session is an empty tenant with zero policies.** With `X-Test-Auth: required` the AuthFilter runs normally and ABAC is enforced against the test tenant — default-deny rejects every app-user read/write until you either enable user isolation or add explicit allow policies. The standard recipe is to use the bootstrap option on `POST /api/v1/test/sessions`:
 
@@ -153,7 +156,7 @@ When you build a backend that calls XCiteDB on behalf of users:
 
 - **JSON documents merge by default.** `POST /api/v1/json-documents` merges the posted `data` into the existing document (object fields combined per XCiteDB meta merge rules). Send **`overwrite: true`** to clear all stored JSON under that document root first, then write only the new payload. SDKs accept the same flag (e.g. `writeJsonDocument(id, data, { overwrite: true })` in JavaScript).
 - **Metadata `mode` and arrays.** **`POST /api/v1/meta`** uses **`mode`**: default **`set`** writes or replaces at `path` (arrays are replaced in range; excess old indices cleared); **`append`** appends array elements after existing ones at `path`. Optional **`overwrite: true`** clears metadata under `path` before writing. JavaScript: **`appendMeta`** or **`addMeta(..., { mode: 'append' })`**; Python/C++: **`append_meta`** or **`add_meta`** with **`mode`** / **`overwrite`** (see SDK sections below).
-- **Prefer dictionary-style objects.** Shredded JSON metadata is keyed by field names. **Object maps** get per-field storage; when an object accumulates enough distinct field names (server default threshold **32**), XCiteDB switches automatically to **dictionary storage** (`{*}` plus per-field keys) for efficient indexed access. For lookup-heavy or wide records, use **`{ "key": value, ... }`** shapes (or one document per logical row) rather than opaque arrays when you need keyed reads.
+- **Prefer dictionary-style objects.** **Shredded** JSON metadata is stored in **fragment-level** keys (e.g. per field name). **Object maps** get per-field storage; when an object accumulates enough distinct field names (server default threshold **32**), XCiteDB switches automatically to **dictionary storage** (`{*}` plus per-field keys) for efficient indexed access. For lookup-heavy or wide records, use **`{ "key": value, ... }`** shapes (or one document per logical row) rather than opaque arrays when you need keyed reads.
 
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
@@ -296,6 +299,7 @@ interface XCiteDBClientOptions {
 - `listWorkspaces()` — List workspaces
 - `publishWorkspace(target, source, options?)` — Publish workspace changes to a target timeline
 - `deleteWorkspace(name)` — Delete workspace
+- `listUserWorkspaces()` / `createUserWorkspace(name, options?)` / `getUserWorkspace(id)` / `deleteUserWorkspace(id)` / `addUserWorkspaceGrant(id, body)` / `removeUserWorkspaceGrant(id, body)` / `publishUserWorkspace(id, options?)` — App-user **`_uw/…`** workspaces
 - `createCheckpoint(message, author?)` — Named snapshot of current state
 - `listCheckpoints(options?)` — List checkpoints
 - `revertToCheckpoint(checkpointId)` — Revert workspace to a prior checkpoint
@@ -416,6 +420,7 @@ auto ids = client.query_documents(q);
 ## Architecture Notes
 
 - **Multi-tenant**: Each project is an isolated tenant with its own data, users, keys, and policies.
+- **Sharding vs shredding**: **Sharding** partitions the **tenant plane** (today, one isolated dataset per project; finer-grain sharding is on the roadmap). **Shredding** splits **individual documents** into **fragments** with their own keys—see convention 3.
 - **LMDB engine**: Data is memory-mapped; reads are microsecond-class on warm data.
 - **Versioning**: **Temporal revisions** are always on when using dates. **Workspaces** isolate draft work; **checkpoints** are optional named snapshots; **publish** merges a workspace into a target timeline. **`X-Date`** selects an instant for **as-of reads** and, when set, for **writes** under that revision (any calendar time you choose — e.g. publication date — not only “now”). Omit **`X-Date`** for **flat** writes on that request, or use **`X-Unversioned: true`** to state that explicitly.
 - **Two user tiers**: Platform operators manage infrastructure; App users are end-users of applications built on XciteDB.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",