@xcitedbs/client 0.2.18 → 0.2.20

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, 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;
@@ -19,6 +19,8 @@ export declare class XCiteDBClient {
     private userIsolation?;
     private cachedAppUserId?;
     private readonly requestTimeoutMs?;
+    /** Set by {@link XCiteDBClient.createTestSession} when the server returns a `bootstrap` summary. */
+    lastTestSessionBootstrap?: TestSessionBootstrapSummary;
     constructor(options: XCiteDBClientOptions);
     /**
      * Create an ephemeral test database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
@@ -55,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. */
@@ -269,6 +285,10 @@ export declare class XCiteDBClient {
      * ```
      */
     checkAccess(subject: PolicySubjectInput, identifier: string, action: string, branch?: string): Promise<AccessCheckResult>;
+    /**
+     * Dry-run access (`POST /api/v1/security/check`). Same as {@link checkAccess}; use for debugging 403s.
+     */
+    diagnoseAccess(subject: PolicySubjectInput, identifier: string, action: string, branch?: string): Promise<AccessCheckResult>;
     getSecurityConfig(): Promise<SecurityConfig>;
     /**
      * Update tenant security defaults (`PUT /api/v1/security/config`). When ABAC is enabled, pair

package/dist/client.js

@@ -8,6 +8,44 @@ function joinUrl(base, path) {
     const p = path.startsWith('/') ? path : `/${path}`;
     return `${b}${p}`;
 }
+function newClientRequestId() {
+    const c = globalThis.crypto?.randomUUID?.();
+    if (c)
+        return c;
+    const a = new Uint8Array(16);
+    if (globalThis.crypto?.getRandomValues)
+        globalThis.crypto.getRandomValues(a);
+    else
+        for (let i = 0; i < 16; i++)
+            a[i] = Math.floor(Math.random() * 256);
+    return Array.from(a, (x) => x.toString(16).padStart(2, '0')).join('');
+}
+function extrasFromErrorBody(data, serverRequestId, clientRequestId) {
+    const bodyObj = typeof data === 'object' && data !== null ? data : undefined;
+    return {
+        reason: bodyObj && typeof bodyObj.reason === 'string' ? bodyObj.reason : undefined,
+        policyId: bodyObj && typeof bodyObj.policy_id === 'string' ? bodyObj.policy_id : undefined,
+        hint: bodyObj && typeof bodyObj.hint === 'string' ? bodyObj.hint : undefined,
+        expectedRole: bodyObj && typeof bodyObj.expected_role === 'string' ? bodyObj.expected_role : undefined,
+        actualRole: bodyObj && typeof bodyObj.actual_role === 'string' ? bodyObj.actual_role : undefined,
+        serverRequestId,
+        clientRequestId,
+    };
+}
+/** @internal */
+function throwForFailedHttp(status, path, data, msg, serverRequestId, clientRequestId) {
+    const extras = extrasFromErrorBody(data, serverRequestId, clientRequestId);
+    const Ctor = status === 403
+        ? types_1.XCiteDBForbiddenError
+        : status === 404
+            ? types_1.XCiteDBNotFoundError
+            : status === 401
+                ? types_1.XCiteDBAuthError
+                : status === 409 || status === 423
+                    ? types_1.XCiteDBLockConflictError
+                    : types_1.XCiteDBError;
+    throw new Ctor(msg || `HTTP ${status}`, status, data, extras);
+}
 function buildQuery(params) {
     const sp = new URLSearchParams();
     for (const [k, v] of Object.entries(params)) {
@@ -83,8 +121,13 @@ class XCiteDBClient {
             userIsolation: opts.userIsolation,
             requestTimeoutMs: opts.requestTimeoutMs,
         });
-        const data = await temp.request('POST', '/api/v1/test/sessions', opts.overlay === true ? { overlay: true } : undefined, undefined, { no401Retry: true });
-        return new XCiteDBClient({
+        const sessionBody = {};
+        if (opts.overlay === true)
+            sessionBody.overlay = true;
+        if (opts.bootstrap !== undefined)
+            sessionBody.bootstrap = opts.bootstrap;
+        const data = await temp.request('POST', '/api/v1/test/sessions', Object.keys(sessionBody).length ? sessionBody : undefined, undefined, { no401Retry: true });
+        const child = new XCiteDBClient({
             baseUrl: opts.baseUrl,
             apiKey: opts.testRequireAuth ? opts.apiKey : undefined,
             accessToken: opts.testRequireAuth ? opts.accessToken : undefined,
@@ -101,6 +144,10 @@ class XCiteDBClient {
             userIsolation: opts.userIsolation,
             requestTimeoutMs: opts.requestTimeoutMs,
         });
+        if (data.bootstrap && typeof data.bootstrap === 'object') {
+            child.lastTestSessionBootstrap = data.bootstrap;
+        }
+        return child;
     }
     /**
      * Canonical `project:<tenant_id>:<role>` group string. The middle segment must match the app JWT `tenant_id`
@@ -332,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);
@@ -458,12 +532,17 @@ 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();
+            headers['X-Request-Id'] = outgoingRequestId;
             let init = { method, headers };
             if (body !== undefined) {
                 if (typeof body === 'string') {
@@ -477,7 +556,14 @@ class XCiteDBClient {
             const sig = requestTimeoutSignal(this.requestTimeoutMs);
             if (sig)
                 init.signal = sig;
-            const res = await fetch(url, init);
+            let res;
+            try {
+                res = await fetch(url, init);
+            }
+            catch (e) {
+                const m = e instanceof Error ? e.message : 'Network error';
+                throw new types_1.XCiteDBError(m, 0, null, { clientRequestId: outgoingRequestId });
+            }
             const text = await res.text();
             let data;
             try {
@@ -499,7 +585,7 @@ class XCiteDBClient {
                 ? String(data.message)
                 : res.statusText;
             this.notifySessionInvalidIfNeeded(path, res.status);
-            throw new types_1.XCiteDBError(msg || `HTTP ${res.status}`, res.status, data);
+            throwForFailedHttp(res.status, path, data, msg || `HTTP ${res.status}`, res.headers.get('X-Request-Id') ?? undefined, res.headers.get('X-Client-Request-Id') ?? undefined);
         }
         this.notifySessionInvalidIfNeeded(path, 401);
         throw new types_1.XCiteDBError('Request failed after retry', 401, null);
@@ -926,6 +1012,12 @@ class XCiteDBClient {
             body.branch = branch;
         return this.request('POST', '/api/v1/security/check', body);
     }
+    /**
+     * Dry-run access (`POST /api/v1/security/check`). Same as {@link checkAccess}; use for debugging 403s.
+     */
+    async diagnoseAccess(subject, identifier, action, branch) {
+        return this.checkAccess(subject, identifier, action, branch);
+    }
     async getSecurityConfig() {
         return this.request('GET', '/api/v1/security/config');
     }
@@ -1680,9 +1772,11 @@ class XCiteDBClient {
         });
         for (let attempt = 0; attempt < 2; attempt++) {
             const url = joinUrl(this.baseUrl, path);
+            const outgoingRequestId = newClientRequestId();
             const headers = {
                 ...this.requestHeaders(),
                 'Content-Type': 'application/json',
+                'X-Request-Id': outgoingRequestId,
             };
             const res = await fetch(url, { method: 'POST', headers, body: payload });
             if (res.status === 401 &&
@@ -1703,12 +1797,15 @@ class XCiteDBClient {
                     ? String(data.message)
                     : res.statusText;
                 this.notifySessionInvalidIfNeeded(path, res.status);
-                throw new types_1.XCiteDBError(msg || `HTTP ${res.status}`, res.status, data);
+                throwForFailedHttp(res.status, path, data, msg || `HTTP ${res.status}`, res.headers.get('X-Request-Id') ?? undefined, res.headers.get('X-Client-Request-Id') ?? undefined);
             }
             const streamBody = res.body;
             if (!streamBody) {
                 const text = await res.text();
-                throw new types_1.XCiteDBError('RAG stream: empty response body', res.status, text);
+                throw new types_1.XCiteDBError('RAG stream: empty response body', res.status, text, {
+                    serverRequestId: res.headers.get('X-Request-Id') ?? undefined,
+                    clientRequestId: res.headers.get('X-Client-Request-Id') ?? undefined,
+                });
             }
             const reader = streamBody.getReader();
             const decoder = new TextDecoder();

package/dist/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.test.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for HTTP error mapping (mocked fetch).
+ */
+const node_test_1 = require("node:test");
+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 () => {
+            return new Response(JSON.stringify({
+                message: 'Forbidden',
+                reason: 'tenant_security_unconfigured',
+                policy_id: 'abac_denied',
+                hint: 'add policies',
+            }), {
+                status: 403,
+                headers: {
+                    'X-Request-Id': 'srv-req-1',
+                    'X-Client-Request-Id': 'cli-req-1',
+                },
+            });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'test-key' });
+            await c.health();
+            strict_1.default.fail('expected error');
+        }
+        catch (e) {
+            strict_1.default.ok(e instanceof types_js_1.XCiteDBForbiddenError);
+            const err = e;
+            strict_1.default.equal(err.policyId, 'abac_denied');
+            strict_1.default.equal(err.reason, 'tenant_security_unconfigured');
+            strict_1.default.equal(err.hint, 'add policies');
+            strict_1.default.equal(err.serverRequestId, 'srv-req-1');
+            strict_1.default.equal(err.clientRequestId, 'cli-req-1');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});

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, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
-export { XCiteDBError } 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/index.js

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XCiteDBError = exports.WebSocketSubscription = exports.XCiteDBClient = void 0;
+exports.XCiteDBLockConflictError = exports.XCiteDBAuthError = exports.XCiteDBNotFoundError = exports.XCiteDBForbiddenError = exports.XCiteDBError = exports.WebSocketSubscription = exports.XCiteDBClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "XCiteDBClient", { enumerable: true, get: function () { return client_1.XCiteDBClient; } });
 var websocket_1 = require("./websocket");
 Object.defineProperty(exports, "WebSocketSubscription", { enumerable: true, get: function () { return websocket_1.WebSocketSubscription; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "XCiteDBError", { enumerable: true, get: function () { return types_1.XCiteDBError; } });
+Object.defineProperty(exports, "XCiteDBForbiddenError", { enumerable: true, get: function () { return types_1.XCiteDBForbiddenError; } });
+Object.defineProperty(exports, "XCiteDBNotFoundError", { enumerable: true, get: function () { return types_1.XCiteDBNotFoundError; } });
+Object.defineProperty(exports, "XCiteDBAuthError", { enumerable: true, get: function () { return types_1.XCiteDBAuthError; } });
+Object.defineProperty(exports, "XCiteDBLockConflictError", { enumerable: true, get: function () { return types_1.XCiteDBLockConflictError; } });

package/dist/types.d.ts

@@ -504,6 +504,34 @@ export interface XCiteDBClientOptions {
      */
     requestTimeoutMs?: number;
 }
+/** `bootstrap` payload for `POST /api/v1/test/sessions` (see server docs / `llms.txt`). */
+export interface TestSessionBootstrap {
+    user_isolation?: {
+        enabled: boolean;
+        namespace_pattern: string;
+        shared_read_paths?: string[];
+        shared_write_paths?: string[];
+    };
+    developer_bypass?: boolean;
+    policies?: Array<{
+        policy_id: string;
+        policy: SecurityPolicy;
+    }>;
+}
+/** `bootstrap` summary returned by the server after a bootstrapped test session is created. */
+export interface TestSessionBootstrapSummary {
+    user_isolation_applied?: boolean;
+    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;
@@ -518,6 +546,8 @@ export interface CreateTestSessionOptions {
      * When true, creates an overlay test session: writable ephemeral LMDB with production project data as read-only base.
      */
     overlay?: boolean;
+    /** Optional server-side bootstrap (user isolation, developer_bypass, policies). */
+    bootstrap?: TestSessionBootstrap;
     /** Keep `apiKey` / `accessToken` on the client and send `X-Test-Auth: required` on each request. */
     testRequireAuth?: boolean;
     onSessionTokensUpdated?: (pair: TokenPair) => void;
@@ -677,6 +707,7 @@ export interface SecurityConfig {
 export interface AccessCheckResult {
     effect: 'allow' | 'deny';
     matched_policy_id?: string;
+    reason?: string;
 }
 export interface StoredPolicyResponse {
     policy_id: string;
@@ -826,8 +857,36 @@ export interface PublishResult {
 }
 /** @deprecated Use {@link PublishResult}. */
 export type MergeResult = PublishResult;
+export type XCiteDBErrorExtras = {
+    reason?: string;
+    policyId?: string;
+    hint?: string;
+    expectedRole?: string;
+    actualRole?: string;
+    serverRequestId?: string;
+    clientRequestId?: string;
+};
 export declare class XCiteDBError extends Error {
     readonly status: number;
     readonly body?: unknown | undefined;
-    constructor(message: string, status: number, body?: unknown | undefined);
+    reason?: string;
+    policyId?: string;
+    hint?: string;
+    expectedRole?: string;
+    actualRole?: string;
+    serverRequestId?: string;
+    clientRequestId?: string;
+    constructor(message: string, status: number, body?: unknown | undefined, extras?: XCiteDBErrorExtras);
+}
+export declare class XCiteDBForbiddenError extends XCiteDBError {
+    constructor(message: string, status: number, body?: unknown, extras?: XCiteDBErrorExtras);
+}
+export declare class XCiteDBNotFoundError extends XCiteDBError {
+    constructor(message: string, status: number, body?: unknown, extras?: XCiteDBErrorExtras);
+}
+export declare class XCiteDBAuthError extends XCiteDBError {
+    constructor(message: string, status: number, body?: unknown, extras?: XCiteDBErrorExtras);
+}
+export declare class XCiteDBLockConflictError extends XCiteDBError {
+    constructor(message: string, status: number, body?: unknown, extras?: XCiteDBErrorExtras);
 }

package/dist/types.js

@@ -1,12 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XCiteDBError = void 0;
+exports.XCiteDBLockConflictError = exports.XCiteDBAuthError = exports.XCiteDBNotFoundError = exports.XCiteDBForbiddenError = exports.XCiteDBError = void 0;
 class XCiteDBError extends Error {
-    constructor(message, status, body) {
+    constructor(message, status, body, extras) {
         super(message);
         this.status = status;
         this.body = body;
         this.name = 'XCiteDBError';
+        if (extras) {
+            this.reason = extras.reason;
+            this.policyId = extras.policyId;
+            this.hint = extras.hint;
+            this.expectedRole = extras.expectedRole;
+            this.actualRole = extras.actualRole;
+            this.serverRequestId = extras.serverRequestId;
+            this.clientRequestId = extras.clientRequestId;
+        }
     }
 }
 exports.XCiteDBError = XCiteDBError;
+class XCiteDBForbiddenError extends XCiteDBError {
+    constructor(message, status, body, extras) {
+        super(message, status, body, extras);
+        this.name = 'XCiteDBForbiddenError';
+    }
+}
+exports.XCiteDBForbiddenError = XCiteDBForbiddenError;
+class XCiteDBNotFoundError extends XCiteDBError {
+    constructor(message, status, body, extras) {
+        super(message, status, body, extras);
+        this.name = 'XCiteDBNotFoundError';
+    }
+}
+exports.XCiteDBNotFoundError = XCiteDBNotFoundError;
+class XCiteDBAuthError extends XCiteDBError {
+    constructor(message, status, body, extras) {
+        super(message, status, body, extras);
+        this.name = 'XCiteDBAuthError';
+    }
+}
+exports.XCiteDBAuthError = XCiteDBAuthError;
+class XCiteDBLockConflictError extends XCiteDBError {
+    constructor(message, status, body, extras) {
+        super(message, status, body, extras);
+        this.name = 'XCiteDBLockConflictError';
+    }
+}
+exports.XCiteDBLockConflictError = XCiteDBLockConflictError;

package/llms-full.txt

@@ -199,6 +199,19 @@ Browser and mobile apps can use OAuth2-style flows against `/api/v1/app/auth/oau
 
 ---
 
+## When a request returns 403
+
+XCiteDB returns one of two 403 shapes; both include `reason`:
+
+- Generic role/credential 403: `{ "error": "Error", "message": "Forbidden", "code": 403, "reason": "role_forbidden_*"|"auth_*" }`. The credential failed before ABAC ran. Verify that the API key is not a `public` key for write controllers, that the app-user JWT has `project:<tenant>:admin|editor`, and that for `POST /api/v1/security/policies` the credential resolves to `role: "admin"`.
+- ABAC 403: also includes `policy_id` ("abac_denied" / "reserved_namespace" / explicit deny rule id) and `hint`. When `reason == "tenant_security_unconfigured"`, the tenant has zero policies and default-deny took over — typical inside a fresh test session.
+
+First debugging step: call `POST /api/v1/security/check` with the same subject + identifier + action to get `effect` and `matched_policy_id` without state changes.
+
+The server's request id is in the `X-Request-Id` response header. If you also send your own `X-Request-Id` on the request, XCiteDB echoes it back as `X-Client-Request-Id` and includes it in activity logs (search via `GET /api/v1/project/logs?request_id=<uuid>`).
+
+SDKs surface these fields on typed errors (e.g. `XCiteDBForbiddenError.policyId`, `serverRequestId`, `clientRequestId` in JavaScript; `policy_id`, `server_request_id` in Python/C++).
+
 # Ephemeral test sessions
 
 > **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised. Provision a session in `beforeAll` / `setUp` / test fixture setup and destroy it in `afterAll` / `tearDown` / fixture teardown.
@@ -210,14 +223,29 @@ 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, … })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
-- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor. For overlay until the helper accepts a flag, call **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`** then construct the client with the returned token.
-- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay = true`**, and optional `test_require_auth`; `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:
+
+```json
+{
+  "bootstrap": {
+    "user_isolation": { "enabled": true, "namespace_pattern": "/spaces/${user.id}" },
+    "developer_bypass": true,
+    "policies": []
+  }
+}
+```
+
+Skipping bootstrap yields 403 with `reason: "tenant_security_unconfigured"` for app-user reads/writes under `/spaces/<userId>/...`.
 
 **JavaScript/TypeScript — complete test scaffold (Vitest / Jest):**
 
@@ -229,11 +257,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 () => {
@@ -517,8 +548,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
@@ -531,7 +562,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.
 
@@ -681,6 +740,15 @@ Operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `in`, `not_in`, `contains`, `starts_
 
 SDK: `UnqueryTemplate` in `@xcitedbs/client` types; method `unquery(query, unquery)`.
 
+### `reason` / `policy_id` markers (403 debugging)
+
+| reason | policy_id | Meaning |
+|--------|------------|---------|
+| `abac_explicit_deny` | &lt;your-rule-id&gt; | An explicit deny rule matched. |
+| `abac_default_deny` | `abac_denied` | No allow policy matched; tenant `default_effect` (or `app_user_default_effect`) deny took over. |
+| `tenant_security_unconfigured` | `abac_denied` | Same as default deny but the tenant has **zero** policies — usual for a fresh test session without bootstrap. |
+| `abac_reserved_namespace` | `reserved_namespace` | App-user or public-key request touched `_xcitedb*` reserved identifiers. |
+
 ## ABAC policy expression language
 
 Policies may set **`conditions.expression`** (optional) and **`conditions.branches`** (optional array). If `branches` is non-empty, the request branch must match an entry (`"*"`, exact name, or `prefix*`).
@@ -1314,12 +1382,34 @@ For logged-in users (not only platform admins):
 
 ---
 
+## Wrapping XCiteDB in a higher-level service
+
+When you build a backend that calls XCiteDB on behalf of users:
+
+- Never collapse upstream errors to a generic `xcitedb_upstream` code. Pass `body.policy_id`, `body.hint`, `body.reason`, `body.expected_role`, `body.actual_role` through your error wrapper. They are stable, low-cardinality, and safe to surface to test fixtures.
+- Capture `X-Request-Id` from XCiteDB's response and log it next to your own request id. Send your service's own request id as `X-Request-Id` on outgoing calls; XCiteDB will echo it as `X-Client-Request-Id`.
+- Distinguish service-key calls vs end-user-token calls in your error trace; tag the call site so a 403 from a user-token spine read and a 403 from an admin `createPolicy` are distinguishable.
+- Do not assume an end-user implicitly has read access to documents under `/spaces/<their_user_id>/....` That is only true when user isolation is enabled on the tenant with the matching `namespace_pattern`. In production tenants this is one-time setup; in test sessions use the bootstrap option on `POST /api/v1/test/sessions`.
+
 # Part 3: SDK Reference
 
 # JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
 
+### Typed 403 handling
+
+```typescript
+import { XCiteDBClient, XCiteDBForbiddenError } from '@xcitedbs/client';
+try {
+  await client.readJsonDocument('/spaces/u1/docs/d/spine.json');
+} catch (e) {
+  if (e instanceof XCiteDBForbiddenError) {
+    console.error({ reason: e.reason, policyId: e.policyId, hint: e.hint, requestId: e.serverRequestId });
+  }
+}
+```
+
 ## Quick Start
 
 ```typescript
@@ -1592,6 +1682,19 @@ class XCiteDBError extends Error {
 
 Install: `pip install xcitedb`
 
+### Typed 403 handling
+
+```python
+from xcitedb import XCiteDBClient, XCiteDBForbiddenError
+
+async def main():
+    client = XCiteDBClient("http://localhost:8080", api_key="your-key")
+    try:
+        await client.read_json_document("/spaces/u1/docs/d/spine.json")
+    except XCiteDBForbiddenError as e:
+        print(e.reason, e.policy_id, e.hint, e.server_request_id)
+```
+
 ```python
 import asyncio
 from xcitedb import (
@@ -1644,6 +1747,21 @@ q.match_start = "/manual/";
 auto ids = client.query_documents(q);
 ```
 
-Synchronous (blocking) HTTP client. Methods mirror the JavaScript SDK with C++ naming (`write_xml_document`, deprecated `write_document_json`). Errors throw `xcitedb::XCiteDBError` with `.status()` and `.body()`.
+Synchronous (blocking) HTTP client. Methods mirror the JavaScript SDK with C++ naming (`write_xml_document`, deprecated `write_document_json`). Errors throw `xcitedb::XCiteDBError` (or subclasses such as `xcitedb::XCiteDBForbiddenError`) with `.status()`, `.body()`, `.reason()`, `.policy_id()`, `.hint()`, `.server_request_id()`, and `.client_request_id()`.
+
+### Typed 403 handling
+
+```cpp
+#include <xcitedb/xcitedb.hpp>
+#include <iostream>
+
+void example(xcitedb::XCiteDBClient& client) {
+  try {
+    client.read_json_document("/spaces/u1/docs/d/spine.json");
+  } catch (const xcitedb::XCiteDBForbiddenError& e) {
+    std::cerr << e.reason() << " " << e.policy_id() << " " << e.hint() << " " << e.server_request_id() << "\n";
+  }
+}
+```
 
 Includes optional `xcitevcs` CLI for command-line operations (legacy branch/commit vocabulary on the wire, documents, search, import/export).

package/llms.txt

@@ -101,6 +101,19 @@ await app.writeJsonDocument('userdata/alice/profile', { ok: true });
 
 **Python:** `XCiteDBClient.build_project_group(project_id, "editor")` or module `build_project_group`. **C++:** `XCiteDBClient::build_project_group(project_id, "editor")`.
 
+## When a request returns 403
+
+XCiteDB returns one of two 403 shapes; both include `reason`:
+
+- Generic role/credential 403: `{ "error": "Error", "message": "Forbidden", "code": 403, "reason": "role_forbidden_*"|"auth_*" }`. The credential failed before ABAC ran. Verify that the API key is not a `public` key for write controllers, that the app-user JWT has `project:<tenant>:admin|editor`, and that for `POST /api/v1/security/policies` the credential resolves to `role: "admin"`.
+- ABAC 403: also includes `policy_id` ("abac_denied" / "reserved_namespace" / explicit deny rule id) and `hint`. When `reason == "tenant_security_unconfigured"`, the tenant has zero policies and default-deny took over — typical inside a fresh test session.
+
+First debugging step: call `POST /api/v1/security/check` with the same subject + identifier + action to get `effect` and `matched_policy_id` without state changes.
+
+The server's request id is in the `X-Request-Id` response header. If you also send your own `X-Request-Id` on the request, XCiteDB echoes it back as `X-Client-Request-Id` and includes it in activity logs (search via `GET /api/v1/project/logs?request_id=<uuid>`).
+
+SDKs surface these fields on typed errors (e.g. `XCiteDBForbiddenError.policyId`, `serverRequestId`, `clientRequestId` in JavaScript; `policy_id`, `server_request_id` in Python/C++).
+
 ## Test mode (how to use)
 
 > **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised.
@@ -109,7 +122,33 @@ await app.writeJsonDocument('userdata/alice/profile', { ok: true });
 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, … })`, optional `overlay: true`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or provision with **`POST /api/v1/test/sessions`** and JSON **`{"overlay":true}`** when you need overlay, then pass `test_session_token` / `test_require_auth` to the constructor. **C++:** `XCiteDBClient::create_test_session(options)` with optional `test_session_overlay = true`, `destroy_test_session()`, optional `test_require_auth` in options.
+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`:
+
+```json
+{
+  "bootstrap": {
+    "user_isolation": { "enabled": true, "namespace_pattern": "/spaces/${user.id}" },
+    "developer_bypass": true,
+    "policies": []
+  }
+}
+```
+
+If you skip the bootstrap, an app-user JWT cannot read or write `/spaces/<userId>/...` — even paths the user "owns" — and you will see 403 with reason `tenant_security_unconfigured`.
+
+**SDK one-liners for bootstrap:** **JS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, testRequireAuth: true, bootstrap: { user_isolation: { enabled: true, namespace_pattern: '/spaces/${user.id}' }, developer_bypass: true } })`. **Python:** `async with XCiteDBClient.test_session(base_url, api_key=sk, test_require_auth=True, bootstrap={...}) as c:`. **C++:** set `options.test_session_bootstrap = nlohmann::json::parse(R"(...)");` then `XCiteDBClient::create_test_session(options)`.
+
+## Wrapping XCiteDB in a higher-level service
+
+When you build a backend that calls XCiteDB on behalf of users:
+
+- Never collapse upstream errors to a generic `xcitedb_upstream` code. Pass `body.policy_id`, `body.hint`, `body.reason`, `body.expected_role`, `body.actual_role` through your error wrapper. They are stable, low-cardinality, and safe to surface to test fixtures.
+- Capture `X-Request-Id` from XCiteDB's response and log it next to your own request id. Send your service's own request id as `X-Request-Id` on outgoing calls; XCiteDB will echo it as `X-Client-Request-Id`.
+- Distinguish service-key calls vs end-user-token calls in your error trace; tag the call site so a 403 from a user-token spine read and a 403 from an admin `createPolicy` are distinguishable.
+- Do not assume an end-user implicitly has read access to documents under `/spaces/<their_user_id>/....` That is only true when user isolation is enabled on the tenant with the matching `namespace_pattern`. In production tenants this is one-time setup; in test sessions use the bootstrap option.
 
 ## JSON documents and metadata (merge, overwrite, efficiency)
 

package/package.json

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