@xcitedbs/client 0.3.9 → 0.3.11

package/dist/client.d.ts

@@ -143,6 +143,22 @@ export declare class XCiteDBClient {
         message: string;
         session_token: string;
     }>;
+    /**
+     * Seal a *standalone* sandbox as a fixture base (`POST /api/v1/sandboxes/{name}/seal`).
+     *
+     * Stamps the supplied fingerprint on the fixture's metadata. Test sessions and dev sandboxes
+     * can then attach to this fixture by passing the matching `expectedBaseFingerprint`. Mismatch
+     * is `409 fingerprint_mismatch` — consumers MUST re-run setup, not retry.
+     */
+    sealSandbox(name: string, opts: import('./types').SealSandboxOptions): Promise<import('./types').SandboxInfo>;
+    /**
+     * Unseal a fixture sandbox (`POST /api/v1/sandboxes/{name}/unseal`).
+     *
+     * Clears the seal + fingerprint and bumps `reset_generation` so any cached overlay routing
+     * forces a fresh validation. Typical re-seed flow: `unseal → resetSandbox → re-populate →
+     * sealSandbox` at a new fingerprint.
+     */
+    unsealSandbox(name: string): Promise<import('./types').SandboxInfo>;
     /** Destroy a sandbox; revokes bound API keys and removes membership rows. Owner only. */
     destroySandbox(name: string): Promise<{
         message: string;
@@ -188,6 +204,19 @@ export declare class XCiteDBClient {
     /** Sets active project for platform console mode (`X-Project-Id`). */
     setProjectId(projectId: string): void;
     setContext(ctx: DatabaseContext): void;
+    private static mergeContext;
+    /**
+     * Create a child client that shares transport/auth wiring with this one but has an
+     * independent context. Forking does not mutate the parent; child and parent can be used
+     * concurrently with different workspaces, dates, or prefixes. Use this in place of
+     * `setContext → do work → setContext(prev)`.
+     *
+     * Auth tokens (api key, access token, app-user tokens) are copied at fork time. Subsequent
+     * token rotation via `setTokens` / `setAppUserTokens` (or callbacks) updates only the
+     * instance that triggered it; if you fork long-lived clients, keep token state in sync via
+     * the `onSessionTokensUpdated` / `onAppUserTokensUpdated` callbacks supplied at construction.
+     */
+    fork(partial?: Partial<DatabaseContext>): XCiteDBClient;
     setTokens(access: string, refresh?: string): void;
     /** End-user (app) tokens. With developer `accessToken`/`apiKey`, sent as `X-App-User-Token`. */
     setAppUserTokens(access: string, refresh?: string): void;
@@ -751,7 +780,7 @@ export declare class XCiteDBClient {
         merge?: MergeResult;
     }>;
     /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
-    writeXML(xml: string, _options?: WriteDocumentOptions): Promise<void>;
+    writeXML(xml: string, options?: WriteDocumentOptions): Promise<void>;
     /**
      * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
      * For storing JSON data by key, use `writeJsonDocument`.
@@ -785,21 +814,27 @@ export declare class XCiteDBClient {
      * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
      */
     writeDocumentJson(xml: string, options?: WriteDocumentOptions): Promise<void>;
-    queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
+    queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<string[]>;
     /**
      * Shallow read (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`):
      * root element with inline leaves plus **identifier-bearing stub elements** (`db:stub="true"`) for shredded
      * child slots instead of opaque `db:N*` placeholders. Safe to round-trip with {@link writeXmlDocument}.
      * For sidebar / AST navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
      */
-    queryByIdentifierShallow(identifier: string, filter?: string, pathFilter?: string): Promise<string[]>;
+    queryByIdentifierShallow(identifier: string, filter?: string, pathFilter?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<string[]>;
     /**
      * Load a document with all shredded children inlined (`FirstMatch,IncludeChildren` on `GET /by-id`).
      * The returned array has **length 0 or 1**; when present, index `0` is the full XML string.
      * Use this for editor round-trips. For navigation without loading the full subtree, use
      * {@link queryByIdentifierShallow} plus {@link listIdentifierChildren}.
      */
-    queryByIdentifierFull(identifier: string, filter?: string, pathFilter?: string): Promise<string[]>;
+    queryByIdentifierFull(identifier: string, filter?: string, pathFilter?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<string[]>;
     /** Alias of {@link listIdentifierChildren} — immediate child segments under `parentPath` (identifier hierarchy). */
     listChildIdentifiers(parentPath?: string): Promise<ListIdentifierChildrenResult>;
     queryDocuments(query: XCiteQuery, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
@@ -815,10 +850,12 @@ export declare class XCiteDBClient {
     addMeta(identifier: string, value: unknown, path?: string, opts?: {
         mode?: 'set' | 'append' | 'merge_append';
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     addMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
         mode?: 'set' | 'append' | 'merge_append';
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     /**
      * Strict array-extend: `value` must be an array; the stored target at `path` must be an array
@@ -828,9 +865,11 @@ export declare class XCiteDBClient {
      */
     appendMeta(identifier: string, value: unknown[], path?: string, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     appendMetaByQuery(query: XCiteQuery, value: unknown[], path?: string, firstMatch?: boolean, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     /**
      * Deep-extend: walks the payload and extends any nested arrays found in storage. Scalars and
@@ -839,17 +878,31 @@ export declare class XCiteDBClient {
      */
     mergeAppendMeta(identifier: string, value: unknown, path?: string, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     mergeAppendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     /** Convenience: push a single item. Wraps `item` in `[item]` and calls {@link appendMeta}. */
-    appendItem(identifier: string, item: unknown, path?: string, opts?: {
+    appendItem<T = unknown>(identifier: string, item: T, path?: string, opts?: {
+        overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
+    }): Promise<boolean>;
+    /** Convenience: push a single item via query. Wraps `item` in `[item]` and calls {@link appendMetaByQuery}. */
+    appendItemByQuery<T = unknown>(query: XCiteQuery, item: T, path?: string, firstMatch?: boolean, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
+    }): Promise<boolean>;
+    queryMeta<T = MetaValue>(identifier: string, path?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<T>;
+    queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<T>;
+    clearMeta(query: XCiteQuery, opts?: {
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
-    queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;
-    queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string): Promise<T>;
-    clearMeta(query: XCiteQuery): Promise<boolean>;
     /**
      * Acquire a cooperative lock. On exclusive conflict the server returns HTTP 409 with a
      * {@link LockConflictBody} body (thrown as {@link XCiteDBError} with `.status === 409`).
@@ -902,7 +955,10 @@ export declare class XCiteDBClient {
      * );
      * ```
      */
-    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: UnqueryTemplate): Promise<T>;
+    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: UnqueryTemplate, opts?: {
+        context?: Partial<DatabaseContext>;
+        strict?: boolean;
+    }): Promise<T>;
     search(q: TextSearchQuery): Promise<TextSearchResult>;
     reindex(): Promise<{
         status: string;

package/dist/client.js

@@ -201,6 +201,11 @@ class XCiteDBClient {
             sessionBody.additional_keys = opts.additionalKeys;
         if (opts.bootstrap !== undefined)
             sessionBody.bootstrap = opts.bootstrap;
+        if (opts.baseSandboxName)
+            sessionBody.base_sandbox_name = opts.baseSandboxName;
+        if (opts.expectedBaseFingerprint) {
+            sessionBody.expected_base_fingerprint = opts.expectedBaseFingerprint;
+        }
         const data = await temp.request('POST', '/api/v1/test/sessions', Object.keys(sessionBody).length ? sessionBody : undefined, undefined, { no401Retry: true });
         const mode = resolveTestAuthMode(opts.testAuth, opts.testRequireAuth) ?? 'required';
         const keepCreds = mode !== 'bypass';
@@ -629,6 +634,15 @@ class XCiteDBClient {
         if (canonical.startsWith('/users/') && !canonical.startsWith(`${ns}/`) && canonical !== ns) {
             return canonical;
         }
+        // Tenant-managed share-alias roots are never under any user namespace; pass them through
+        // unchanged so app users can read documents shared with them via group / public / anonymous
+        // share aliases (server alias paths produced by UserIsolationService::compute*ShareAliasPath).
+        if (canonical.startsWith('/groups/') ||
+            canonical.startsWith('/shared/') ||
+            canonical.startsWith('/shared-readonly/') ||
+            canonical.startsWith('/public/')) {
+            return canonical;
+        }
         const combined = `${ns}${canonical === '/' ? '/' : canonical}`;
         const finalId = combined.replace(/\/+/g, '/');
         if (!finalId.startsWith(ns) || (finalId.length > ns.length && finalId.charAt(ns.length) !== '/')) {
@@ -718,7 +732,18 @@ class XCiteDBClient {
      * a fresh client constructed with that key (no header threading needed).
      */
     async createSandbox(opts) {
-        return this.request('POST', '/api/v1/sandboxes', opts, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+        // Translate camelCase fixture-attach options to the snake_case wire format
+        // the server expects. Other fields pass through unchanged.
+        const body = { ...opts };
+        if (opts.baseSandboxName) {
+            body.base_sandbox_name = opts.baseSandboxName;
+            delete body.baseSandboxName;
+        }
+        if (opts.expectedBaseFingerprint) {
+            body.expected_base_fingerprint = opts.expectedBaseFingerprint;
+            delete body.expectedBaseFingerprint;
+        }
+        return this.request('POST', '/api/v1/sandboxes', body, undefined, { suppressTestSessionHeader: true, no401Retry: true });
     }
     /** List sandboxes for the current project (`GET /api/v1/sandboxes`). */
     async listSandboxes() {
@@ -737,6 +762,26 @@ class XCiteDBClient {
     async resetSandbox(name) {
         return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/reset`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
     }
+    /**
+     * Seal a *standalone* sandbox as a fixture base (`POST /api/v1/sandboxes/{name}/seal`).
+     *
+     * Stamps the supplied fingerprint on the fixture's metadata. Test sessions and dev sandboxes
+     * can then attach to this fixture by passing the matching `expectedBaseFingerprint`. Mismatch
+     * is `409 fingerprint_mismatch` — consumers MUST re-run setup, not retry.
+     */
+    async sealSandbox(name, opts) {
+        return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/seal`, { fingerprint: opts.fingerprint }, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
+    /**
+     * Unseal a fixture sandbox (`POST /api/v1/sandboxes/{name}/unseal`).
+     *
+     * Clears the seal + fingerprint and bumps `reset_generation` so any cached overlay routing
+     * forces a fresh validation. Typical re-seed flow: `unseal → resetSandbox → re-populate →
+     * sealSandbox` at a new fingerprint.
+     */
+    async unsealSandbox(name) {
+        return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/unseal`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
     /** Destroy a sandbox; revokes bound API keys and removes membership rows. Owner only. */
     async destroySandbox(name) {
         return this.request('DELETE', `/api/v1/sandboxes/${encodeURIComponent(name)}`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
@@ -821,11 +866,33 @@ class XCiteDBClient {
         this.projectId = projectId;
     }
     setContext(ctx) {
-        const next = { ...this.defaultContext, ...ctx };
-        if (ctx.workspace !== undefined) {
-            next.branch = ctx.workspace;
+        this.defaultContext = XCiteDBClient.mergeContext(this.defaultContext, ctx);
+    }
+    static mergeContext(prev, partial) {
+        const next = { ...prev, ...partial };
+        if (partial.workspace !== undefined) {
+            next.branch = partial.workspace;
         }
-        this.defaultContext = next;
+        return next;
+    }
+    /**
+     * Create a child client that shares transport/auth wiring with this one but has an
+     * independent context. Forking does not mutate the parent; child and parent can be used
+     * concurrently with different workspaces, dates, or prefixes. Use this in place of
+     * `setContext → do work → setContext(prev)`.
+     *
+     * Auth tokens (api key, access token, app-user tokens) are copied at fork time. Subsequent
+     * token rotation via `setTokens` / `setAppUserTokens` (or callbacks) updates only the
+     * instance that triggered it; if you fork long-lived clients, keep token state in sync via
+     * the `onSessionTokensUpdated` / `onAppUserTokensUpdated` callbacks supplied at construction.
+     */
+    fork(partial) {
+        const child = Object.create(XCiteDBClient.prototype);
+        Object.assign(child, this);
+        child.defaultContext = XCiteDBClient.mergeContext(this.defaultContext, partial ?? {});
+        // Context can shift the user-isolation prefix; the parent's cached app-user id no longer applies.
+        child.cachedAppUserId = undefined;
+        return child;
     }
     setTokens(access, refresh) {
         this.accessToken = access;
@@ -844,9 +911,9 @@ class XCiteDBClient {
         this.appUserRefreshToken = undefined;
         this.clearAppUserIdCache();
     }
-    contextHeaders() {
+    contextHeaders(override) {
         const h = {};
-        const c = this.defaultContext;
+        const c = override ? XCiteDBClient.mergeContext(this.defaultContext, override) : this.defaultContext;
         const ws = c.workspace ?? c.branch;
         if (ws)
             h['X-Workspace'] = ws;
@@ -907,11 +974,12 @@ class XCiteDBClient {
     async request(method, path, body, extraHeaders, opts) {
         const no401Retry = opts?.no401Retry === true;
         const suppressTestSessionHeader = opts?.suppressTestSessionHeader === true;
+        const contextOverride = opts?.contextOverride;
         for (let attempt = 0; attempt < 2; attempt++) {
             const url = joinUrl(this.baseUrl, path);
             const headers = {
                 ...this.authHeaders(),
-                ...this.contextHeaders(),
+                ...this.contextHeaders(contextOverride),
                 ...(suppressTestSessionHeader ? {} : this.testHeaders()),
                 ...extraHeaders,
             };
@@ -2067,25 +2135,18 @@ class XCiteDBClient {
      * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.
      */
     async withWorkspace(workspaceName, fn, options) {
-        const prev = { ...this.defaultContext };
-        const fromWs = options?.fromBranch ?? prev.branch ?? prev.workspace ?? '';
-        let checkpoint;
+        const fromWs = options?.fromBranch ?? this.defaultContext.branch ?? this.defaultContext.workspace ?? '';
+        await this.createWorkspace(workspaceName, fromWs || undefined, this.defaultContext.date || undefined);
+        const child = this.fork({ workspace: workspaceName, branch: workspaceName });
+        const result = await fn(child);
+        const checkpoint = await child.createCheckpoint(options?.message ?? `Workspace ${workspaceName}`, options?.author);
         let publish;
-        try {
-            await this.createWorkspace(workspaceName, fromWs || undefined, prev.date || undefined);
-            this.setContext({ workspace: workspaceName, branch: workspaceName });
-            const result = await fn(this);
-            checkpoint = await this.createCheckpoint(options?.message ?? `Workspace ${workspaceName}`, options?.author);
-            if (options?.autoMerge !== false) {
-                publish = await this.publishWorkspace(fromWs, workspaceName, {
-                    message: options?.message,
-                });
-            }
-            return { result, checkpoint, publish };
-        }
-        finally {
-            this.setContext(prev);
+        if (options?.autoMerge !== false) {
+            publish = await child.publishWorkspace(fromWs, workspaceName, {
+                message: options?.message,
+            });
         }
+        return { result, checkpoint, publish };
     }
     /** @deprecated Use {@link withWorkspace}. */
     async withBranch(branchName, fn, options) {
@@ -2093,11 +2154,9 @@ class XCiteDBClient {
         return { result: r.result, commit: r.checkpoint, merge: r.publish };
     }
     /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
-    async writeXML(xml, _options) {
+    async writeXML(xml, options) {
         const payload = this.isoApplyXmlDbIdentifier(xml);
-        await this.request('POST', '/api/v1/documents', payload, {
-            'Content-Type': 'application/xml',
-        });
+        await this.request('POST', '/api/v1/documents', payload, { 'Content-Type': 'application/xml' }, { contextOverride: options?.context });
     }
     /**
      * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
@@ -2114,7 +2173,7 @@ class XCiteDBClient {
             xml: this.isoApplyXmlDbIdentifier(xml),
             is_top: options?.is_top ?? true,
             compare_attributes: options?.compare_attributes ?? false,
-        });
+        }, undefined, { contextOverride: options?.context });
     }
     /**
      * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
@@ -2194,14 +2253,16 @@ class XCiteDBClient {
     async writeDocumentJson(xml, options) {
         return this.writeXmlDocument(xml, options);
     }
-    async queryByIdentifier(identifier, flags, filter, pathFilter) {
+    async queryByIdentifier(identifier, flags, filter, pathFilter, opts) {
         const q = buildQuery({
             identifier: this.isoPrefixId(identifier),
             flags: flags,
             filter,
             path_filter: pathFilter,
         });
-        return this.request('GET', `/api/v1/documents/by-id${q}`);
+        return this.request('GET', `/api/v1/documents/by-id${q}`, undefined, undefined, {
+            contextOverride: opts?.context,
+        });
     }
     /**
      * Shallow read (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`):
@@ -2209,8 +2270,8 @@ class XCiteDBClient {
      * child slots instead of opaque `db:N*` placeholders. Safe to round-trip with {@link writeXmlDocument}.
      * For sidebar / AST navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
      */
-    async queryByIdentifierShallow(identifier, filter, pathFilter) {
-        return this.queryByIdentifier(identifier, 'NoChildren,KeepIndexNodes,FirstMatch', filter, pathFilter);
+    async queryByIdentifierShallow(identifier, filter, pathFilter, opts) {
+        return this.queryByIdentifier(identifier, 'NoChildren,KeepIndexNodes,FirstMatch', filter, pathFilter, opts);
     }
     /**
      * Load a document with all shredded children inlined (`FirstMatch,IncludeChildren` on `GET /by-id`).
@@ -2218,8 +2279,8 @@ class XCiteDBClient {
      * Use this for editor round-trips. For navigation without loading the full subtree, use
      * {@link queryByIdentifierShallow} plus {@link listIdentifierChildren}.
      */
-    async queryByIdentifierFull(identifier, filter, pathFilter) {
-        return this.queryByIdentifier(identifier, 'FirstMatch,IncludeChildren', filter, pathFilter);
+    async queryByIdentifierFull(identifier, filter, pathFilter, opts) {
+        return this.queryByIdentifier(identifier, 'FirstMatch,IncludeChildren', filter, pathFilter, opts);
     }
     /** Alias of {@link listIdentifierChildren} — immediate child segments under `parentPath` (identifier hierarchy). */
     async listChildIdentifiers(parentPath) {
@@ -2369,7 +2430,9 @@ class XCiteDBClient {
             body.mode = opts.mode;
         if (opts?.overwrite)
             body.overwrite = true;
-        const r = await this.request('POST', '/api/v1/meta', body);
+        const r = await this.request('POST', '/api/v1/meta', body, undefined, {
+            contextOverride: opts?.context,
+        });
         return r?.ok !== false;
     }
     async addMetaByQuery(query, value, path = '', firstMatch = false, opts) {
@@ -2383,7 +2446,9 @@ class XCiteDBClient {
             body.mode = opts.mode;
         if (opts?.overwrite)
             body.overwrite = true;
-        const r = await this.request('POST', '/api/v1/meta', body);
+        const r = await this.request('POST', '/api/v1/meta', body, undefined, {
+            contextOverride: opts?.context,
+        });
         return r?.ok !== false;
     }
     /**
@@ -2413,16 +2478,18 @@ class XCiteDBClient {
     async appendItem(identifier, item, path = '', opts) {
         return this.appendMeta(identifier, [item], path, opts);
     }
-    async queryMeta(identifier, path = '') {
-        return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`);
+    /** Convenience: push a single item via query. Wraps `item` in `[item]` and calls {@link appendMetaByQuery}. */
+    async appendItemByQuery(query, item, path = '', firstMatch = false, opts) {
+        return this.appendMetaByQuery(query, [item], path, firstMatch, opts);
     }
-    async queryMetaByQuery(query, path = '') {
-        return this.request('POST', '/api/v1/meta/query', { query: this.isoPrefixQuery(query), path });
+    async queryMeta(identifier, path = '', opts) {
+        return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`, undefined, undefined, { contextOverride: opts?.context });
     }
-    async clearMeta(query) {
-        const r = await this.request('DELETE', '/api/v1/meta', {
-            query: this.isoPrefixQuery(query),
-        });
+    async queryMetaByQuery(query, path = '', opts) {
+        return this.request('POST', '/api/v1/meta/query', { query: this.isoPrefixQuery(query), path }, undefined, { contextOverride: opts?.context });
+    }
+    async clearMeta(query, opts) {
+        const r = await this.request('DELETE', '/api/v1/meta', { query: this.isoPrefixQuery(query) }, undefined, { contextOverride: opts?.context });
         return r?.ok !== false;
     }
     /**
@@ -2515,8 +2582,9 @@ class XCiteDBClient {
      * );
      * ```
      */
-    async unquery(query, unquery) {
-        return this.request('POST', '/api/v1/unquery', { query: this.isoPrefixQuery(query), unquery });
+    async unquery(query, unquery, opts) {
+        const extraHeaders = opts?.strict ? { 'X-Unquery-Strict': 'true' } : undefined;
+        return this.request('POST', '/api/v1/unquery', { query: this.isoPrefixQuery(query), unquery }, extraHeaders, { contextOverride: opts?.context });
     }
     async search(q) {
         const body = { query: q.query };

package/dist/client.test.js

@@ -611,6 +611,285 @@ const types_js_1 = require("./types.js");
         }
     });
 });
+(0, node_test_1.describe)('client.fork()', () => {
+    (0, node_test_1.it)('child sends overridden workspace; parent keeps original on parallel calls', async () => {
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input, init) => {
+            const h = new Headers(init?.headers);
+            seen.push({ url: String(input), workspace: h.get('X-Workspace') });
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const parent = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            const child = parent.fork({ workspace: 'feature-x' });
+            await Promise.all([
+                parent.queryMeta('/d1'),
+                child.queryMeta('/d2'),
+                parent.queryMeta('/d3'),
+            ]);
+            strict_1.default.equal(seen.length, 3);
+            const byUrl = new Map(seen.map((s) => [s.url, s.workspace]));
+            strict_1.default.equal([...byUrl.keys()].some((u) => u.includes('%2Fd1')), true);
+            const ws = (id) => seen.find((s) => s.url.includes(id)).workspace;
+            strict_1.default.equal(ws('%2Fd1'), 'main');
+            strict_1.default.equal(ws('%2Fd2'), 'feature-x');
+            strict_1.default.equal(ws('%2Fd3'), 'main');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('child setContext does not mutate parent', async () => {
+        const c = new client_js_1.XCiteDBClient({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            context: { workspace: 'main', date: '2025-01-01' },
+        });
+        const child = c.fork({ workspace: 'feat' });
+        child.setContext({ workspace: 'feat-v2', date: '2025-12-31' });
+        // Capture parent's headers via a single request.
+        const orig = globalThis.fetch;
+        let parentWs = null;
+        let parentDate = null;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            const h = new Headers(init?.headers);
+            parentWs = h.get('X-Workspace');
+            parentDate = h.get('X-Date');
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            await c.queryMeta('/p');
+            strict_1.default.equal(parentWs, 'main');
+            strict_1.default.equal(parentDate, '2025-01-01');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('fork() with no arg copies parent context verbatim', async () => {
+        const c = new client_js_1.XCiteDBClient({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            context: { workspace: 'w', date: '2025-06-01', prefix: '/p' },
+        });
+        const child = c.fork();
+        let h = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            h = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            await child.queryMeta('/d');
+            strict_1.default.equal(h.get('X-Workspace'), 'w');
+            strict_1.default.equal(h.get('X-Date'), '2025-06-01');
+            strict_1.default.equal(h.get('X-Prefix'), '/p');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('fork({workspace}) mirrors workspace into branch (back-compat alias)', async () => {
+        const c = new client_js_1.XCiteDBClient({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            context: { workspace: 'main', branch: 'main' },
+        });
+        const child = c.fork({ workspace: 'feature-y' });
+        // Inspect via a request: server only sees X-Workspace, but the deprecated branch alias
+        // must update too so legacy code paths inside the SDK that read `branch` see the new value.
+        let h = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            h = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            await child.queryMeta('/d');
+            strict_1.default.equal(h.get('X-Workspace'), 'feature-y');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('per-call opts.context override', () => {
+    (0, node_test_1.it)('queryMeta {context: {workspace}} sends overridden X-Workspace', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            await c.queryMeta('/d', '', { context: { workspace: 'feature-x' } });
+            strict_1.default.equal(captured.get('X-Workspace'), 'feature-x');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('opts.context does NOT mutate the client default context', async () => {
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            const h = new Headers(init?.headers);
+            seen.push(h.get('X-Workspace') ?? '');
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            await c.queryMeta('/a', '', { context: { workspace: 'one-off' } });
+            await c.queryMeta('/b'); // should fall back to default 'main'
+            strict_1.default.deepEqual(seen, ['one-off', 'main']);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('addMeta opts.context overrides workspace and date', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main', date: '2025-01-01' },
+            });
+            await c.addMeta('/d', { x: 1 }, '', {
+                context: { workspace: 'feat', date: '2025-12-31' },
+            });
+            strict_1.default.equal(captured.get('X-Workspace'), 'feat');
+            strict_1.default.equal(captured.get('X-Date'), '2025-12-31');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('appendItem opts.context flows through to the wrapped appendMeta call', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+            await c.appendItem('/d', 1, 'list', { context: { workspace: 'w-pc' } });
+            strict_1.default.equal(captured.get('X-Workspace'), 'w-pc');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('unquery opts.context overrides workspace', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            await c.unquery({ match_start: '/x/' }, { id: '$identifier' }, { context: { workspace: 'unq' } });
+            strict_1.default.equal(captured.get('X-Workspace'), 'unq');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('writeXmlDocument options.context overrides workspace', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            await c.writeXmlDocument('<?xml version="1.0"?><doc xmlns:db="http://www.xcitedb.com/schema" db:identifier="/x"/>', { context: { workspace: 'wxd' } });
+            strict_1.default.equal(captured.get('X-Workspace'), 'wxd');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('appendItem / appendItemByQuery', () => {
+    (0, node_test_1.it)('appendItem wraps a typed item in [item] and POSTs mode=append', async () => {
+        const captured = { value: null };
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input, init) => {
+            captured.value = {
+                url: String(input),
+                body: JSON.parse(String(init?.body ?? '{}')),
+            };
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+            const review = { stars: 5, text: 'great' };
+            const ok = await c.appendItem('/products/p1', review, 'reviews');
+            strict_1.default.equal(ok, true);
+            strict_1.default.match(captured.value.url, /\/api\/v1\/meta$/);
+            const body = captured.value.body;
+            strict_1.default.equal(body.identifier, '/products/p1');
+            strict_1.default.equal(body.path, 'reviews');
+            strict_1.default.equal(body.mode, 'append');
+            strict_1.default.deepEqual(body.value, [review]);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('appendItemByQuery wraps a typed item in [item] and includes first_match', async () => {
+        const captured = { value: null };
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured.value = { body: JSON.parse(String(init?.body ?? '{}')) };
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+            const ok = await c.appendItemByQuery({ match_start: '/products/' }, 42, 'tags', true);
+            strict_1.default.equal(ok, true);
+            const body = captured.value.body;
+            strict_1.default.equal(body.path, 'tags');
+            strict_1.default.equal(body.first_match, true);
+            strict_1.default.equal(body.mode, 'append');
+            strict_1.default.deepEqual(body.value, [42]);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
 (0, node_test_1.describe)('listTriggerEvents', () => {
     (0, node_test_1.it)('passes limit and parses events', async () => {
         let url = '';

package/dist/types.d.ts

@@ -569,6 +569,8 @@ export interface DatabaseContext {
 export interface WriteDocumentOptions {
     is_top?: boolean;
     compare_attributes?: boolean;
+    /** Per-call context override. Merged on top of the client's default context for this request only. */
+    context?: Partial<DatabaseContext>;
 }
 /** Supported source formats for `POST /api/v1/documents/import` (server detects from bytes / filename). */
 export type DocumentImportFormat = 'docx' | 'odt' | 'rtf' | 'pdf' | 'txt' | 'md' | 'adoc';
@@ -852,6 +854,26 @@ export interface CreateTestSessionOptions {
      * When true, creates an overlay test session: writable ephemeral LMDB with production project data as read-only base.
      */
     overlay?: boolean;
+    /**
+     * When set, attach the new test session to a sealed standalone sandbox (a "fixture") instead of the
+     * production project as the read-only base. Implies `overlay: true`.
+     *
+     * Use this for e2e suites where many tests share the same expensive setup (created users, seeded
+     * data, etc.) — set up the fixture once via the sandbox API, seal it with a content fingerprint,
+     * then point each test session at it. Multiple test sessions can attach to the same fixture
+     * concurrently; each gets its own ephemeral overlay layer.
+     */
+    baseSandboxName?: string;
+    /**
+     * Required iff {@link baseSandboxName} is set. The fingerprint your setup script stamped on the
+     * fixture (typically `hash(seed_inputs) + schema_version + git_sha`).
+     *
+     * On mismatch the server returns **`409 fingerprint_mismatch`** — the recovery action is to
+     * **re-run setup** to refresh the fixture, NOT to retry. The whole feature's safety property
+     * hinges on consumers handling this error correctly: a stale fixture must never silently serve
+     * old data.
+     */
+    expectedBaseFingerprint?: string;
     /**
      * API keys to snapshot into the new session's config DB so requests carrying any of these keys
      * (alongside `X-Test-Session: <token>`) authenticate against the session, not production.
@@ -908,6 +930,22 @@ export interface SandboxInfo {
     owner_member_id: string;
     /** Present in list responses: the requesting member's role in this sandbox, or "" if not a member. */
     my_role?: 'owner' | 'editor' | 'viewer' | '';
+    /**
+     * True for *fixture* sandboxes — empty initial DB, no production overlay underneath. Eligible
+     * to be sealed and used as a base for test sessions or other sandboxes. Mutually exclusive
+     * with `base_sandbox_name` on create.
+     */
+    standalone?: boolean;
+    /** True when this standalone sandbox has been sealed as a fixture base. */
+    sealed?: boolean;
+    /** Content fingerprint set when this sandbox was last sealed (only present on fixtures). */
+    base_fingerprint?: string;
+    /** Unix seconds at which the fixture was last sealed. */
+    sealed_at?: number;
+    /** First 8 chars of the parent fixture token, when this sandbox attached to a fixture base. */
+    base_sandbox_token_prefix?: string;
+    /** Echoed at create time when this sandbox is attached to a fixture base. */
+    expected_base_fingerprint?: string;
 }
 /** Options for {@link XCiteDBClient.createSandbox}. */
 export interface CreateSandboxOptions {
@@ -921,6 +959,31 @@ export interface CreateSandboxOptions {
     base_branch?: string;
     /** Defaults to "log" — webhooks/auth-emails get captured instead of firing. */
     effects_policy?: 'real' | 'log' | 'mock';
+    /**
+     * Fixture mode: an empty initial DB with no production overlay. Required for sealing the
+     * sandbox as a fixture base later. At most one standalone sandbox is allowed per
+     * `(org_id, project_id)`. Mutually exclusive with {@link baseSandboxName} and
+     * `effects_policy: 'real'`.
+     */
+    standalone?: boolean;
+    /**
+     * Attach this dev sandbox to a sealed standalone fixture as its base. The fixture provides the
+     * read-only baseline; this sandbox holds the writable overlay. Same fingerprint contract as
+     * {@link CreateTestSessionOptions.baseSandboxName} — mismatch is `409 fingerprint_mismatch`.
+     * Mutually exclusive with {@link standalone}.
+     */
+    baseSandboxName?: string;
+    /** Required iff {@link baseSandboxName} is set. */
+    expectedBaseFingerprint?: string;
+}
+/** Body for {@link XCiteDBClient.sealSandbox}. */
+export interface SealSandboxOptions {
+    /**
+     * Content fingerprint to stamp on the fixture. Should be derived from your seed inputs +
+     * schema version + app version (typically git SHA). On a subsequent attach, consumers must
+     * pass the same fingerprint via `expectedBaseFingerprint` — mismatch is a hard failure.
+     */
+    fingerprint: string;
 }
 /** Response from {@link XCiteDBClient.mintSandboxApiKey}. The `api_key` value is shown once. */
 export interface SandboxApiKeyMintResult {

package/dist/user-isolation.test.js

@@ -118,6 +118,8 @@ wd('user isolation (wet)', () => {
         const slug = `js-iso-doc-${suffix}`;
         try {
             await admin.setUserIsolationConfig({ enabled: true, namespace_pattern: '/users/${user.id}' });
+            // Default-deny ABAC requires bypass for the platform admin to do data-doc ops in this project.
+            await admin.updateSecurityConfig({ developer_bypass: true });
             const u = await admin.createAppUser(email, password, undefined, [
                 client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
             ]);
@@ -134,6 +136,7 @@ wd('user isolation (wet)', () => {
             await admin.deleteAppUser(u.user_id);
         }
         finally {
+            await admin.updateSecurityConfig({ developer_bypass: false }).catch(() => { });
             await admin.disableUserIsolation().catch(() => { });
         }
     });
@@ -153,6 +156,7 @@ wd('user isolation (wet)', () => {
                 namespace_pattern: '/users/${user.id}',
                 shared_read_paths: [sharedPath],
             });
+            await admin.updateSecurityConfig({ developer_bypass: true });
             await admin.writeJsonDocument(docPath, { _xcite_json_doc: true, tag: 'shared' });
             const created = await admin.createAppUser(email, password, undefined, [
                 client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
@@ -169,6 +173,7 @@ wd('user isolation (wet)', () => {
             await admin.deleteAppUser(created.user_id);
         }
         finally {
+            await admin.updateSecurityConfig({ developer_bypass: false }).catch(() => { });
             await admin.disableUserIsolation().catch(() => { });
         }
     });
@@ -198,6 +203,7 @@ wd('user isolation (wet)', () => {
                 enabled: true,
                 namespace_pattern: '/users/${user.id}',
             });
+            await admin.updateSecurityConfig({ developer_bypass: true });
             userA = await admin.createAppUser(emailA, password, undefined, [
                 client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
             ]);
@@ -249,6 +255,7 @@ wd('user isolation (wet)', () => {
                 await admin.deleteAppUser(userB.user_id).catch(() => { });
             if (userA)
                 await admin.deleteAppUser(userA.user_id).catch(() => { });
+            await admin.updateSecurityConfig({ developer_bypass: false }).catch(() => { });
             await admin.disableUserIsolation().catch(() => { });
         }
     });

package/llms.txt

@@ -159,6 +159,24 @@ If you skip the bootstrap, an app-user JWT cannot read or write `/spaces/<userId
 
 **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)`.
 
+### Fixture-base test sessions (e2e shared setup)
+
+When an e2e suite (Playwright etc.) re-runs the same expensive setup before every test — create users, seed documents, configure policies — that setup dominates wall-clock time. **Fixture-base mode** lets you do the setup **once per CI run**, share it across many tests in parallel, and treat staleness as a hard failure rather than a silent bug.
+
+Lifecycle:
+
+1. **Create a fixture sandbox** (one-time per project): `POST /api/v1/sandboxes` with `{"name":"e2e-fixture","standalone":true}`. A standalone sandbox has an empty initial DB and no production overlay underneath. **Only one standalone sandbox is allowed per `(org, project)`** — bumping fingerprints, not creating new fixtures, is the way to evolve.
+2. **Populate it** via the regular API (open a sandbox session against it, run your seed script, etc.). Effects policy `real` is rejected for standalone sandboxes; `log` (default) or `mock` are valid.
+3. **Seal it** with a content fingerprint: `POST /api/v1/sandboxes/e2e-fixture/seal` with `{"fingerprint":"<hash>"}`. The fingerprint should encode anything that affects stored shape: at minimum `hash(seed_inputs) + schema_version + git_sha` (every commit pessimistically invalidates the fixture — the friction of a manual version bump is worse than rerunning a fast API-only setup).
+4. **Attach test sessions to the fixture:** `POST /api/v1/test/sessions` with `{"overlay":true,"base_sandbox_name":"e2e-fixture","expected_base_fingerprint":"<hash>"}`. Many test sessions can attach concurrently; each gets its own ephemeral overlay layer; reads see the fixture's data, writes go to the test's overlay only. Mismatch on `expected_base_fingerprint` is **`409 fingerprint_mismatch` — the recovery action is to RE-RUN SETUP, not to retry**. This is the safety property of the cache: a stale fixture must never silently serve old data.
+5. **Re-seed** when the app or seed inputs change: `POST /api/v1/sandboxes/e2e-fixture/unseal` → `POST /api/v1/sandboxes/e2e-fixture/reset` → repopulate via API → `POST /api/v1/sandboxes/e2e-fixture/seal` at the new fingerprint.
+
+**Dev sandboxes can also attach to a fixture** (interactive testing on top of fixture data instead of production): `POST /api/v1/sandboxes` with `{"name":"my-feature","base_sandbox_name":"e2e-fixture","expected_base_fingerprint":"<hash>"}`. Same fingerprint contract; if the fixture is later re-sealed, the dev sandbox's next request fails with `fixture_fingerprint_changed` — recovery in v1 is to delete and recreate the dev sandbox.
+
+**Security:** the fixture-base resolver is keyed on the **caller's** `(org, project)`, not user input — there is no way for tenant A to attach to tenant B's fixture by name. The membership check (caller must be owner/editor of the fixture) returns a generic 404 for both not-found and not-a-member, so cross-tenant existence cannot be probed.
+
+**SDK helpers:** **JS:** `client.createTestSession({ baseUrl, apiKey, baseSandboxName, expectedBaseFingerprint })`, `client.createSandbox({ name, baseSandboxName, expectedBaseFingerprint })`, `client.sealSandbox(name, { fingerprint })`, `client.unsealSandbox(name)`. **Python:** `XCiteDBClient.test_session(base_url, base_sandbox_name=..., expected_base_fingerprint=...)`, `client.seal_sandbox(name, fingerprint=...)`, `client.unseal_sandbox(name)`. **C++:** set `options.test_session_base_sandbox_name` + `options.test_session_expected_base_fingerprint` then `create_test_session`; `seal_sandbox(name, fingerprint)`, `unseal_sandbox(name)`. **MCP:** tools `seal_sandbox`, `unseal_sandbox`; the `create_sandbox` and `create_test_session` tools accept the new fields.
+
 ## Wrapping XCiteDB in a higher-level service
 
 When you build a backend that calls XCiteDB on behalf of users:

package/package.json

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