@xcitedbs/client 0.3.10 → 0.3.12

package/README.md

@@ -67,6 +67,85 @@ Call **`POST /api/v1/test/sessions`** with your normal API key or Bearer (same p
 
 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.
 
+## Gotchas and conventions
+
+These trip up most first-time users; they're listed once here so you don't hit them twice.
+
+### Search (`search`) tokenizes on hyphens
+
+The full-text index treats `-` as a token boundary, so `client.search({ query: 'Test - Article' })` won't match a document titled exactly `"Test - Article"` — it tokenizes to `Test`, `Article` and ranks any doc containing both. Use `search` only for relevance queries.
+
+For exact-title or exact-meta lookups, use **`unquery`** with a meta-equality filter:
+
+```ts
+client.unquery(
+  { match_start: '/spaces/<u>/docs/' },
+  [{ title: 'title', match: '$equals(title, $string("Test - Article"))' }]
+);
+```
+
+### `list*` methods return wrapper objects, not bare arrays
+
+For consistency, every `list*` family method returns an object with the data nested under a named key:
+
+| Method | Wrapper shape |
+|---|---|
+| `listIdentifiers` | `{ identifiers: string[], total, offset, limit }` |
+| `listCheckpoints` | `{ checkpoints: CheckpointRecord[], total, branch }` |
+| `listUserWorkspaces` | `{ user_workspaces: [...] }` |
+| `listBookmarks` | `{ bookmarks: [...], total }` |
+
+Don't `for…of` the result directly — use `for (const x of ids.identifiers)`, not `for (const x of ids)`.
+
+### Reading meta — `getMeta` and `queryMeta`
+
+The read sibling of `addMeta` / `appendMeta` / `clearMeta` is **`getMeta`** (alias of `queryMeta`). With an empty `path` it returns the whole top-level meta object, which by convention is keyed by tool/flow:
+
+```ts
+const meta = await client.getMeta(docId);            // { lint: {...}, summary: {...}, ... }
+const lint = await client.getMeta(docId, 'lint');    // just the lint sub-object
+```
+
+For an array-typed or keyed-object meta path (e.g. an items list, or a per-tool dictionary), pair with **`appendItem`** to push and **`removeItem`** to atomically delete by key — `removeItem` matches against `id` / `item_id` (or by string equality for primitive arrays) and writes back inside one server-side write txn, avoiding the read/modify/write race that read-then-set on the client would create.
+
+### Overlay test sessions — visibility matrix
+
+`createTestSession({ overlay: true })` lets you read production data and write into an isolated overlay. The visibility model is **not "read-through everywhere"** — these are the layers that participate in the overlay→base fallback:
+
+| API | Sees prod data? |
+|---|---|
+| Document and meta reads (anywhere in the doc store) | **yes** |
+| Branch table existence checks (e.g. `_uw/<owner>/<slug>`) | **yes** |
+| Per-branch identifier scans on base-only branches (`listIdentifiers`, `compare`) | **yes** |
+| User-workspace records (`listUserWorkspaces`, `getUserWorkspace`) | **yes** |
+| Branch tip / commit lookups (`listCheckpoints`, `compare` against checkpoints) | **yes** |
+| `publishUserWorkspace` writes | sandboxed in overlay — does **not** touch prod |
+| `createCheckpoint`, `addMeta`, `addDocument`, etc. | sandboxed in overlay |
+
+Anything you write inside an overlay session lives under `_test/<uuid>/` and is dropped when the session is destroyed. To inspect a real production conflict mutation-free, call the production admin client directly with `{ autoResolve: 'none' }`.
+
+### `compare()` ref shapes
+
+`{ branch }` without `date` or `checkpoint_id` resolves to the branch's **live tip**, not its base. On a branch with zero checkpoints the server returns 400 `branch_has_no_commits` rather than producing an ambiguous diff — pass an explicit `date` or `checkpoint_id` instead.
+
+`compare()` accepts **both** `matchStart` (camelCase, our convention) and `match_start` (snake_case, matching `XCiteQuery`) on the options object; they're equivalent.
+
+### `withContext` / `fork`
+
+`fork(partial)` returns a child client with the merged context (workspace, date, prefix). **`withContext(partial)`** is a one-line alias for the same operation.
+
+### `_xcite_json_doc` sentinel
+
+JSON documents written via `writeJsonDocument` no longer leak the internal `_xcite_json_doc: true` marker into the read payload — the server strips it before serializing. Older clients that filtered it out can drop that workaround. Likewise, `deleteDocument` now correctly removes JSON documents (it routes JSON ids through `deleteJSON` automatically); you don't need to pick `deleteJsonDocument` based on the document's storage shape.
+
+### `testAuth: 'bypass'` requires the creator credential
+
+When you create a test session, the issuing API key/Bearer is the **creator credential**. Calling endpoints under `X-Test-Auth: bypass` requires presenting that same credential alongside `X-Test-Session`; it isn't only a login restriction. If you can't present the creator credential (e.g. you're operating from a different identity), switch to `X-Test-Auth: required` and the session itself authenticates the request.
+
+### BFF/SPA-side concerns (tracked separately)
+
+The following are app/BFF-repo concerns rather than SDK or server bugs: `getOrCreateDraft` check-then-act races (TOCTOU on per-`(user, key)` resource minting); coexisting legacy and modern `last-drafts` storage formats with different identifier encodings; and project-level workspace wiring of `@xcitedbs/client` for top-level diagnostic scripts. They're tracked in the BFF/SPA repo and aren't fixed here.
+
 ## Build
 
 ```bash

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, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, TriggerEventsResponse, StoredPolicyResponse, TxnRequest, TxnResponse, VerifyAppUserTokenOptions, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareDirection, AppUserGroup, CreateGroupParams, ListGroupsResponse } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, TriggerEventsResponse, StoredPolicyResponse, TxnRequest, TxnResponse, VerifyAppUserTokenOptions, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareDirection, AppUserGroup, CreateGroupParams, ListGroupsResponse, FunctionManifest, FunctionListItem, FunctionDeployRequest, FunctionSecretsList } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -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;
@@ -201,6 +217,8 @@ export declare class XCiteDBClient {
      * the `onSessionTokensUpdated` / `onAppUserTokensUpdated` callbacks supplied at construction.
      */
     fork(partial?: Partial<DatabaseContext>): XCiteDBClient;
+    /** Alias for {@link fork}. Both names are commonly guessed; this avoids a discoverability cliff. */
+    withContext(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;
@@ -438,6 +456,56 @@ export declare class XCiteDBClient {
      * `admin`/`editor` roles can read this; public-key requests are rejected.
      */
     listTriggerEvents(limit?: number): Promise<TriggerEventsResponse>;
+    /**
+     * List deployed functions for the current project. Returns metadata only
+     * (no wasm bytes). Requires admin or editor role on the project.
+     */
+    listFunctions(): Promise<FunctionListItem[]>;
+    /**
+     * Fetch a single function's manifest. Wasm bytes are omitted unless
+     * `includeWasm` is true (admin export path).
+     */
+    getFunction(name: string, opts?: {
+        includeWasm?: boolean;
+    }): Promise<FunctionManifest>;
+    /**
+     * Deploy / replace a function. Body MUST include `wasm_b64` (base64 wasm
+     * bytes) plus the manifest fields. Server validates the wasm magic and
+     * compiles it before persisting.
+     */
+    deployFunction(name: string, manifest: FunctionDeployRequest): Promise<FunctionManifest>;
+    deleteFunction(name: string): Promise<{
+        deleted: string;
+    }>;
+    invokeFunction<T = unknown>(name: string, body?: unknown): Promise<T>;
+    /**
+     * List the secret-name slots for a function. Each entry carries `set:
+     * true|false` — values are NEVER returned. The `orphan_secrets` field, if
+     * present, lists names that were once set but no longer appear in the
+     * manifest's `secrets[]` declaration; clean up via deleteFunctionSecret.
+     * Requires admin role.
+     */
+    listFunctionSecrets(name: string): Promise<FunctionSecretsList>;
+    /**
+     * Set one or more secret values. Each KEY must be declared in the
+     * manifest's `secrets[]` array; values are encrypted at rest and never
+     * round-trip on any GET. Requires admin role.
+     *
+     * @example
+     * ```ts
+     * await client.setFunctionSecrets('charge', {
+     *   STRIPE_KEY: 'sk_live_...',
+     *   WEBHOOK_SIGNING_KEY: 'whsec_...',
+     * });
+     * ```
+     */
+    setFunctionSecrets(name: string, values: Record<string, string>): Promise<{
+        function: string;
+        set: string[];
+    }>;
+    deleteFunctionSecret(name: string, key: string): Promise<{
+        deleted: string;
+    }>;
     /**
      * Dry-run access check (`POST /api/v1/security/check`). Returns `effect` and optional `matched_policy_id`.
      * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `unquery`.
@@ -657,12 +725,14 @@ export declare class XCiteDBClient {
     compare(from: CompareRef, to: CompareRef, options?: {
         includeContent?: boolean;
         matchStart?: string;
+        match_start?: string;
     }): Promise<CompareResult>;
     /** @deprecated Use {@link compare}. */
     diff(from: DiffRef, to: DiffRef, includeContent?: boolean): Promise<DiffResult>;
     diff(from: DiffRef, to: DiffRef, options?: {
         includeContent?: boolean;
         matchStart?: string;
+        match_start?: string;
     }): Promise<DiffResult>;
     /**
      * Compare two XML provision trees structurally + textually and write the resulting
@@ -873,6 +943,20 @@ export declare class XCiteDBClient {
         overwrite?: boolean;
         context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
+    /**
+     * Atomic single-item removal — sibling to {@link appendItem}. Resolves to true when
+     * the item was found and removed, false (HTTP 404) when no match. Behavior depends on
+     * the meta shape at `path`:
+     *   - object → drops the field named `itemKey` (siblings untouched).
+     *   - array  → drops entries equal to `itemKey` (string), or whose `id`/`item_id`
+     *     matches `itemKey`.
+     * Read+filter+write happens server-side inside one write txn so concurrent removes
+     * on the same key elect exactly one winner — use this instead of read-then-set on the
+     * client to avoid the race-loser cleanup the convention warns about.
+     */
+    removeItem(identifier: string, itemKey: string, path?: string, opts?: {
+        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;
@@ -881,6 +965,14 @@ export declare class XCiteDBClient {
     queryMeta<T = MetaValue>(identifier: string, path?: string, opts?: {
         context?: Partial<DatabaseContext>;
     }): Promise<T>;
+    /**
+     * Alias for {@link queryMeta} that pairs by name with {@link addMeta} / {@link appendMeta} /
+     * {@link clearMeta}. With `path` empty this returns the whole top-level meta object — which
+     * by convention is keyed per tool/flow.
+     */
+    getMeta<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>;

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';
@@ -727,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() {
@@ -746,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 });
@@ -858,6 +894,10 @@ class XCiteDBClient {
         child.cachedAppUserId = undefined;
         return child;
     }
+    /** Alias for {@link fork}. Both names are commonly guessed; this avoids a discoverability cliff. */
+    withContext(partial) {
+        return this.fork(partial);
+    }
     setTokens(access, refresh) {
         this.accessToken = access;
         if (refresh !== undefined)
@@ -1570,6 +1610,72 @@ class XCiteDBClient {
             limit: typeof r?.limit === 'number' ? r.limit : 0,
         };
     }
+    // ----- Functions / BFF (Phase 2 + 2.5 + 9) -----
+    // Server-side WASM functions stored at /_xcitedb/functions/<name> per
+    // tenant. Manifests carry runtime, identity_mode, limits, env (non-secret
+    // config), egress_allowlist, secrets[] (capability declaration), and the
+    // raw wasm bytes (base64). Secret VALUES live in a separate per-function
+    // store and are never returned by any GET path — only set via PUT and
+    // observed as `set: true|false` via list.
+    /**
+     * List deployed functions for the current project. Returns metadata only
+     * (no wasm bytes). Requires admin or editor role on the project.
+     */
+    async listFunctions() {
+        const r = await this.request('GET', '/api/v1/functions');
+        return Array.isArray(r?.functions) ? r.functions : [];
+    }
+    /**
+     * Fetch a single function's manifest. Wasm bytes are omitted unless
+     * `includeWasm` is true (admin export path).
+     */
+    async getFunction(name, opts) {
+        const q = buildQuery({ include_wasm: opts?.includeWasm ? 'true' : undefined });
+        return this.request('GET', `/api/v1/functions/${encodeURIComponent(name)}${q}`);
+    }
+    /**
+     * Deploy / replace a function. Body MUST include `wasm_b64` (base64 wasm
+     * bytes) plus the manifest fields. Server validates the wasm magic and
+     * compiles it before persisting.
+     */
+    async deployFunction(name, manifest) {
+        return this.request('PUT', `/api/v1/functions/${encodeURIComponent(name)}`, manifest);
+    }
+    async deleteFunction(name) {
+        return this.request('DELETE', `/api/v1/functions/${encodeURIComponent(name)}`);
+    }
+    async invokeFunction(name, body) {
+        return this.request('POST', `/api/v1/functions/${encodeURIComponent(name)}/invoke`, body);
+    }
+    /**
+     * List the secret-name slots for a function. Each entry carries `set:
+     * true|false` — values are NEVER returned. The `orphan_secrets` field, if
+     * present, lists names that were once set but no longer appear in the
+     * manifest's `secrets[]` declaration; clean up via deleteFunctionSecret.
+     * Requires admin role.
+     */
+    async listFunctionSecrets(name) {
+        return this.request('GET', `/api/v1/functions/${encodeURIComponent(name)}/secrets`);
+    }
+    /**
+     * Set one or more secret values. Each KEY must be declared in the
+     * manifest's `secrets[]` array; values are encrypted at rest and never
+     * round-trip on any GET. Requires admin role.
+     *
+     * @example
+     * ```ts
+     * await client.setFunctionSecrets('charge', {
+     *   STRIPE_KEY: 'sk_live_...',
+     *   WEBHOOK_SIGNING_KEY: 'whsec_...',
+     * });
+     * ```
+     */
+    async setFunctionSecrets(name, values) {
+        return this.request('PUT', `/api/v1/functions/${encodeURIComponent(name)}/secrets`, values);
+    }
+    async deleteFunctionSecret(name, key) {
+        return this.request('DELETE', `/api/v1/functions/${encodeURIComponent(name)}/secrets/${encodeURIComponent(key)}`);
+    }
     /**
      * Dry-run access check (`POST /api/v1/security/check`). Returns `effect` and optional `matched_policy_id`.
      * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `unquery`.
@@ -1989,7 +2095,9 @@ class XCiteDBClient {
         }
         else if (third !== undefined && typeof third === 'object') {
             include_content = third.includeContent ?? false;
-            match_start = third.matchStart;
+            // Accept both casings: matchStart (camelCase, our convention) and match_start
+            // (snake_case, matching XCiteQuery and the wire field). camelCase wins on conflict.
+            match_start = third.matchStart ?? third.match_start;
         }
         const body = {
             from,
@@ -2442,6 +2550,33 @@ class XCiteDBClient {
     async appendItem(identifier, item, path = '', opts) {
         return this.appendMeta(identifier, [item], path, opts);
     }
+    /**
+     * Atomic single-item removal — sibling to {@link appendItem}. Resolves to true when
+     * the item was found and removed, false (HTTP 404) when no match. Behavior depends on
+     * the meta shape at `path`:
+     *   - object → drops the field named `itemKey` (siblings untouched).
+     *   - array  → drops entries equal to `itemKey` (string), or whose `id`/`item_id`
+     *     matches `itemKey`.
+     * Read+filter+write happens server-side inside one write txn so concurrent removes
+     * on the same key elect exactly one winner — use this instead of read-then-set on the
+     * client to avoid the race-loser cleanup the convention warns about.
+     */
+    async removeItem(identifier, itemKey, path = '', opts) {
+        const body = {
+            identifier: this.isoPrefixId(identifier),
+            item_key: itemKey,
+            path,
+        };
+        try {
+            const r = await this.request('DELETE', '/api/v1/meta/item', body, undefined, { contextOverride: opts?.context });
+            return r?.ok !== false;
+        }
+        catch (e) {
+            if (e instanceof types_1.XCiteDBError && e.status === 404)
+                return false;
+            throw e;
+        }
+    }
     /** 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);
@@ -2449,6 +2584,14 @@ class XCiteDBClient {
     async queryMeta(identifier, path = '', opts) {
         return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`, undefined, undefined, { contextOverride: opts?.context });
     }
+    /**
+     * Alias for {@link queryMeta} that pairs by name with {@link addMeta} / {@link appendMeta} /
+     * {@link clearMeta}. With `path` empty this returns the whole top-level meta object — which
+     * by convention is keyed per tool/flow.
+     */
+    async getMeta(identifier, path = '', opts) {
+        return this.queryMeta(identifier, path, opts);
+    }
     async queryMetaByQuery(query, path = '', opts) {
         return this.request('POST', '/api/v1/meta/query', { query: this.isoPrefixQuery(query), path }, undefined, { contextOverride: opts?.context });
     }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { XCiteDBClient } from './client';
 export { parseAssetUri, formatAssetUri, collectIdentifiersFromText, ASSET_URI_PREFIX } from './assetUri';
 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, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SandboxApiKeyMintResult, SandboxInfo, SandboxMember, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TriggerEvent, TriggerEventsResponse, TxnOperation, TxnOperationResult, TxnPrecondition, TxnPreconditionResult, TxnRequest, TxnResponse, JwksKey, JwksResponse, VerifyAppUserTokenOptions, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, UserIsolationShareListEntry, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareTarget, ShareDirection, AppUserGroup, AppUserGroupKind, CreateGroupParams, ListGroupsResponse, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateSandboxOptions, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SandboxApiKeyMintResult, SandboxInfo, SandboxMember, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TriggerEvent, TriggerEventsResponse, FunctionManifest, FunctionListItem, FunctionDeployRequest, FunctionLimits, FunctionSecretEntry, FunctionSecretsList, TxnOperation, TxnOperationResult, TxnPrecondition, TxnPreconditionResult, TxnRequest, TxnResponse, JwksKey, JwksResponse, VerifyAppUserTokenOptions, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, UserIsolationShareListEntry, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareTarget, ShareDirection, AppUserGroup, AppUserGroupKind, CreateGroupParams, ListGroupsResponse, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateSandboxOptions, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError, XCiteDBForbiddenError, XCiteDBNotFoundError, XCiteDBAuthError, XCiteDBLockConflictError, } from './types';

package/dist/types.d.ts

@@ -854,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.
@@ -910,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 {
@@ -923,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 {
@@ -1162,6 +1223,93 @@ export interface StoredTriggerResponse {
     trigger_id: string;
     trigger: TriggerDefinition;
 }
+export interface FunctionLimits {
+    /** Per-invocation fuel budget (0 = use server default). */
+    fuel?: number;
+    /** Per-invocation wall-clock cap in ms (0 = use server default). */
+    wall_ms?: number;
+    /** Per-invocation linear-memory cap in MiB (0 = use server default). */
+    mem_mb?: number;
+}
+/**
+ * Wire-format function manifest as surfaced by `GET /api/v1/functions/{name}`.
+ * Note: `wasm_b64` is included only when `?include_wasm=true` was requested
+ * (admin export path); the standard read path returns `wasm_size` instead.
+ * Secret VALUES are NEVER returned by any GET path — `secrets` here is the
+ * capability-list declaration (just names).
+ */
+export interface FunctionManifest {
+    name: string;
+    version: number;
+    entrypoint: string;
+    /** Phase 2.5: only `"raw_wasm"`. Phase 4 adds `"javy"` (server-compiled JS/TS). */
+    runtime: 'raw_wasm' | 'javy';
+    /** Phase 2.5: only `"as_caller"`. Phase 5 adds `"as_role"`. */
+    identity_mode: 'as_caller' | 'as_role';
+    role?: string;
+    limits: FunctionLimits;
+    /**
+     * Per-function egress allowlist applied by `xcite.fetch`. Hostnames and
+     * `*.example.com` glob patterns; empty = no external HTTP allowed.
+     */
+    egress_allowlist: string[];
+    /**
+     * Capability-style declaration of secret names this function may read at
+     * runtime. Set values via `setFunctionSecrets` — they are never echoed
+     * back. To remove a name from the function's capability set, drop it
+     * from this array on the next deploy AND call `deleteFunctionSecret` for
+     * any orphaned value.
+     */
+    secrets: string[];
+    /**
+     * Non-secret config: URLs, feature flags, model names. Round-trips on
+     * GET — DO NOT put API keys / passwords here.
+     */
+    env: Record<string, string | number | boolean | null>;
+    /** Size of the stored .wasm bytes in bytes. */
+    wasm_size?: number;
+    /** Only present when `getFunction(name, { includeWasm: true })`. */
+    wasm_b64?: string;
+}
+/** Compact metadata used by the list endpoint (`GET /api/v1/functions`). */
+export type FunctionListItem = FunctionManifest;
+/**
+ * Body for `PUT /api/v1/functions/{name}` (function deploy). The server
+ * fills `name` from the URL path; sending it in the body is ignored.
+ * Validation: `wasm_b64` is required and must decode to a wasm module
+ * starting with the magic header `\\0asm`.
+ */
+export interface FunctionDeployRequest {
+    version?: number;
+    entrypoint?: string;
+    runtime?: 'raw_wasm' | 'javy';
+    identity_mode?: 'as_caller' | 'as_role';
+    role?: string;
+    limits?: FunctionLimits;
+    egress_allowlist?: string[];
+    secrets?: string[];
+    env?: Record<string, string | number | boolean | null>;
+    /** Required: base64-encoded wasm bytes. */
+    wasm_b64: string;
+}
+export interface FunctionSecretEntry {
+    name: string;
+    /** True iff a value is currently stored. Values themselves are never returned. */
+    set: boolean;
+}
+export interface FunctionSecretsList {
+    function: string;
+    secrets: FunctionSecretEntry[];
+    /**
+     * Names that have a stored value but are no longer declared in the
+     * manifest's `secrets[]` array. Operators should either re-declare or
+     * delete each one — orphans are unreachable by guests but still take
+     * storage and audit attention.
+     */
+    orphan_secrets?: string[];
+    /** "project" | "sealed" | "none" — which encryption backend the server picked. */
+    backend: string;
+}
 /** Named snapshot on a workspace (checkpoint). */
 export interface CheckpointRecord {
     id: string;

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.10",
+  "version": "0.3.12",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",