@xcitedbs/client 0.3.4 → 0.3.6

package/dist/client.d.ts

@@ -82,8 +82,25 @@ export declare class XCiteDBClient {
     private getAppUserId;
     private normalizeIsolationNamespaceTemplate;
     private canonicalId;
-    /** Resolved namespace root, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
+    /** Resolve the configured namespace template for an explicit user id. Returns null if isolation is off, no template, or `userId` is empty. */
+    private userIsolationNamespaceFor;
+    /** Resolved namespace root for the calling user, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
     private userIsolationNamespace;
+    /**
+     * Namespace for the current request's identity context.
+     *
+     * On a user-workspace branch (`_uw/<owner>/<slug>`) where the calling user is
+     * a member but not the owner, returns the *owner's* namespace — docs in the
+     * workspace are stored at `<owner_ns>/<rel>`, not at the caller's
+     * `<self_ns>/<rel>`. For the owner, non-`_uw/` branches, malformed
+     * branches, or when isolation is off, falls back to the calling user's
+     * namespace.
+     *
+     * Mirrors the server-side branch-aware behavior in
+     * `UserIsolationService::prefixIdentifier` so the SDK's pre-prefixing
+     * lands on the right namespace before the request leaves.
+     */
+    private userIsolationContextNamespace;
     private allSharedPassthroughPrefixes;
     private pathMatchesSharedPassthrough;
     private isoPrefixId;
@@ -108,6 +125,58 @@ export declare class XCiteDBClient {
     destroyTestSessionByToken(token: string): Promise<{
         message: string;
     }>;
+    /**
+     * Create a long-lived developer sandbox via `POST /api/v1/sandboxes`. Returns the server's
+     * `SandboxInfo`. To start using the sandbox immediately, follow up with `client.useSandbox(name)`,
+     * or mint a sandbox-bound API key with `mintSandboxApiKey` and route subsequent requests through
+     * a fresh client constructed with that key (no header threading needed).
+     */
+    createSandbox(opts: import('./types').CreateSandboxOptions): Promise<import('./types').SandboxInfo>;
+    /** List sandboxes for the current project (`GET /api/v1/sandboxes`). */
+    listSandboxes(): Promise<import('./types').SandboxInfo[]>;
+    /** Fetch a sandbox's detail by name (`GET /api/v1/sandboxes/{name}`). */
+    getSandbox(name: string): Promise<import('./types').SandboxInfo>;
+    /** Update mutable sandbox fields (`PATCH /api/v1/sandboxes/{name}`). */
+    updateSandbox(name: string, patch: Partial<Pick<import('./types').SandboxInfo, 'description' | 'pinned' | 'expires_at' | 'effects_policy'>>): Promise<import('./types').SandboxInfo>;
+    /** Drop overlay writes for a sandbox while preserving membership and bound keys. */
+    resetSandbox(name: string): Promise<{
+        message: string;
+        session_token: string;
+    }>;
+    /** Destroy a sandbox; revokes bound API keys and removes membership rows. Owner only. */
+    destroySandbox(name: string): Promise<{
+        message: string;
+        session_token: string;
+    }>;
+    listSandboxMembers(name: string): Promise<import('./types').SandboxMember[]>;
+    addSandboxMember(name: string, member_id: string, role: 'editor' | 'viewer'): Promise<{
+        message: string;
+    }>;
+    removeSandboxMember(name: string, member_id: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Mint an API key bound to the given sandbox. Requests presenting this key automatically route
+     * into the sandbox without an `X-Test-Session` header — paste it into your dev `.env` and
+     * existing client/curl/SDK calls just work. The `api_key` field is shown once; persist it now.
+     */
+    mintSandboxApiKey(name: string, opts?: {
+        name?: string;
+        role?: 'admin' | 'editor' | 'viewer';
+        key_type?: 'secret' | 'public';
+        expires_at?: number;
+    }): Promise<import('./types').SandboxApiKeyMintResult>;
+    /**
+     * Pin this client to a named sandbox: subsequent requests carry `X-Test-Session: <token>`.
+     * Returns the sandbox info. Throws if the name does not resolve.
+     *
+     * If you instead want zero-header DX, mint a sandbox-bound API key with
+     * `mintSandboxApiKey(name)` and construct a fresh client with that `apiKey` — the server
+     * pre-filter resolves the binding without touching the test-session header.
+     */
+    useSandbox(name: string): Promise<import('./types').SandboxInfo>;
+    /** Clear any pinned test/sandbox session token from this client (subsequent requests hit production). */
+    clearSandbox(): void;
     /** True if this client would send API key or Bearer credentials on a normal request. */
     private sentAuthCredentials;
     /** 401 on these paths is an expected auth flow outcome, not a dead session. */

package/dist/client.js

@@ -185,6 +185,8 @@ class XCiteDBClient {
         const sessionBody = {};
         if (opts.overlay === true)
             sessionBody.overlay = true;
+        if (opts.additionalKeys !== undefined)
+            sessionBody.additional_keys = opts.additionalKeys;
         if (opts.bootstrap !== undefined)
             sessionBody.bootstrap = opts.bootstrap;
         const data = await temp.request('POST', '/api/v1/test/sessions', Object.keys(sessionBody).length ? sessionBody : undefined, undefined, { no401Retry: true });
@@ -521,13 +523,12 @@ class XCiteDBClient {
         }
         return t;
     }
-    /** Resolved namespace root, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
-    userIsolationNamespace() {
+    /** Resolve the configured namespace template for an explicit user id. Returns null if isolation is off, no template, or `userId` is empty. */
+    userIsolationNamespaceFor(userId) {
         if (!this.userIsolation?.enabled) {
             return null;
         }
-        const uid = this.getAppUserId();
-        if (!uid) {
+        if (!userId) {
             return null;
         }
         const rawTpl = this.normalizeIsolationNamespaceTemplate(this.userIsolation.namespace ?? '/users/{userId}');
@@ -535,7 +536,42 @@ class XCiteDBClient {
         if (!trimmed) {
             return null;
         }
-        return trimmed.replace(/{userId}/g, uid).replace(/{user_id}/g, uid);
+        return trimmed.replace(/{userId}/g, userId).replace(/{user_id}/g, userId);
+    }
+    /** Resolved namespace root for the calling user, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
+    userIsolationNamespace() {
+        return this.userIsolationNamespaceFor(this.getAppUserId());
+    }
+    /**
+     * Namespace for the current request's identity context.
+     *
+     * On a user-workspace branch (`_uw/<owner>/<slug>`) where the calling user is
+     * a member but not the owner, returns the *owner's* namespace — docs in the
+     * workspace are stored at `<owner_ns>/<rel>`, not at the caller's
+     * `<self_ns>/<rel>`. For the owner, non-`_uw/` branches, malformed
+     * branches, or when isolation is off, falls back to the calling user's
+     * namespace.
+     *
+     * Mirrors the server-side branch-aware behavior in
+     * `UserIsolationService::prefixIdentifier` so the SDK's pre-prefixing
+     * lands on the right namespace before the request leaves.
+     */
+    userIsolationContextNamespace() {
+        const selfId = this.getAppUserId();
+        const branch = this.defaultContext.workspace ?? this.defaultContext.branch;
+        if (branch && branch.startsWith('_uw/')) {
+            const m = branch.match(/^_uw\/([^/]+)\/[^/]+$/);
+            if (m) {
+                const ownerId = m[1];
+                if (ownerId && ownerId !== selfId) {
+                    const ns = this.userIsolationNamespaceFor(ownerId);
+                    if (ns) {
+                        return ns;
+                    }
+                }
+            }
+        }
+        return this.userIsolationNamespaceFor(selfId);
     }
     allSharedPassthroughPrefixes() {
         const o = this.userIsolation;
@@ -564,7 +600,7 @@ class XCiteDBClient {
         return false;
     }
     isoPrefixId(id) {
-        const ns = this.userIsolationNamespace();
+        const ns = this.userIsolationContextNamespace();
         if (!ns) {
             return id;
         }
@@ -589,7 +625,7 @@ class XCiteDBClient {
         return finalId;
     }
     isoUnprefixId(id) {
-        const ns = this.userIsolationNamespace();
+        const ns = this.userIsolationContextNamespace();
         if (!ns) {
             return id;
         }
@@ -606,7 +642,7 @@ class XCiteDBClient {
         return canonical;
     }
     isoPrefixQuery(q) {
-        if (!this.userIsolationNamespace()) {
+        if (!this.userIsolationContextNamespace()) {
             return q;
         }
         const out = { ...q };
@@ -622,7 +658,7 @@ class XCiteDBClient {
         return out;
     }
     isoApplyXmlDbIdentifier(xml) {
-        if (!this.userIsolationNamespace()) {
+        if (!this.userIsolationContextNamespace()) {
             return xml;
         }
         return xml.replace(/(db:identifier\s*=\s*")([^"]*)(")/, (_m, p1, mid, p3) => {
@@ -663,6 +699,73 @@ class XCiteDBClient {
         const enc = encodeURIComponent(token);
         return this.request('DELETE', `/api/v1/test/sessions/${enc}`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
     }
+    /**
+     * Create a long-lived developer sandbox via `POST /api/v1/sandboxes`. Returns the server's
+     * `SandboxInfo`. To start using the sandbox immediately, follow up with `client.useSandbox(name)`,
+     * or mint a sandbox-bound API key with `mintSandboxApiKey` and route subsequent requests through
+     * 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 });
+    }
+    /** List sandboxes for the current project (`GET /api/v1/sandboxes`). */
+    async listSandboxes() {
+        const r = await this.request('GET', '/api/v1/sandboxes', undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+        return r.sandboxes ?? [];
+    }
+    /** Fetch a sandbox's detail by name (`GET /api/v1/sandboxes/{name}`). */
+    async getSandbox(name) {
+        return this.request('GET', `/api/v1/sandboxes/${encodeURIComponent(name)}`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
+    /** Update mutable sandbox fields (`PATCH /api/v1/sandboxes/{name}`). */
+    async updateSandbox(name, patch) {
+        return this.request('PATCH', `/api/v1/sandboxes/${encodeURIComponent(name)}`, patch, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
+    /** Drop overlay writes for a sandbox while preserving membership and bound keys. */
+    async resetSandbox(name) {
+        return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/reset`, 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 });
+    }
+    async listSandboxMembers(name) {
+        const r = await this.request('GET', `/api/v1/sandboxes/${encodeURIComponent(name)}/members`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+        return r.members ?? [];
+    }
+    async addSandboxMember(name, member_id, role) {
+        return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/members`, { member_id, role }, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
+    async removeSandboxMember(name, member_id) {
+        return this.request('DELETE', `/api/v1/sandboxes/${encodeURIComponent(name)}/members/${encodeURIComponent(member_id)}`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
+    /**
+     * Mint an API key bound to the given sandbox. Requests presenting this key automatically route
+     * into the sandbox without an `X-Test-Session` header — paste it into your dev `.env` and
+     * existing client/curl/SDK calls just work. The `api_key` field is shown once; persist it now.
+     */
+    async mintSandboxApiKey(name, opts = {}) {
+        return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/api-keys`, opts, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
+    /**
+     * Pin this client to a named sandbox: subsequent requests carry `X-Test-Session: <token>`.
+     * Returns the sandbox info. Throws if the name does not resolve.
+     *
+     * If you instead want zero-header DX, mint a sandbox-bound API key with
+     * `mintSandboxApiKey(name)` and construct a fresh client with that `apiKey` — the server
+     * pre-filter resolves the binding without touching the test-session header.
+     */
+    async useSandbox(name) {
+        const info = await this.getSandbox(name);
+        if (!info.session_token)
+            throw new Error(`useSandbox: server returned no session_token for "${name}"`);
+        this.testSessionToken = info.session_token;
+        return info;
+    }
+    /** Clear any pinned test/sandbox session token from this client (subsequent requests hit production). */
+    clearSandbox() {
+        this.testSessionToken = undefined;
+    }
     /** True if this client would send API key or Bearer credentials on a normal request. */
     sentAuthCredentials() {
         return !!(this.apiKey || this.accessToken || this.appUserAccessToken);
@@ -2461,8 +2564,8 @@ class XCiteDBClient {
         }
         const ct = opts.contentType.trim() || 'application/octet-stream';
         const qParts = [];
-        if (opts.scope === 'public') {
-            qParts.push('scope=public');
+        if (opts.scope === 'shared') {
+            qParts.push('scope=shared');
         }
         if (opts.identifier !== undefined && opts.identifier !== '') {
             qParts.push(`identifier=${encodeURIComponent(opts.identifier)}`);

package/dist/client.test.js

@@ -32,6 +32,80 @@ const types_js_1 = require("./types.js");
             globalThis.fetch = orig;
         }
     });
+    (0, node_test_1.it)('user-workspace branch (`_uw/<owner>/<slug>`) prefixes paths with owner namespace, not caller', async () => {
+        // Issue B repro at the unit level: an invitee on someone else's user
+        // workspace must namespace identifiers to the owner's user_id parsed
+        // from the branch, not their own. We assert the outbound URL — SDK
+        // routes prefixing through userIsolationContextNamespace() which
+        // checks `_uw/<owner>/<slug>` and substitutes the owner.
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            seen.push(String(input));
+            return new Response(JSON.stringify({ ok: true, _xcite_json_doc: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'test-key',
+                userIsolation: { enabled: true, namespace: '/users/{userId}' },
+            });
+            // sub claim = "user-B"
+            c.setAppUserTokens('header.eyJzdWIiOiJ1c2VyLUIifQ.sig');
+            // Owner of the workspace is "user-A"; we are "user-B".
+            c.setContext({ branch: '_uw/user-A/shared', project_id: 'p1' });
+            await c.readJsonDocument('/drafts/x');
+            strict_1.default.equal(seen.length, 1);
+            strict_1.default.match(seen[0], /identifier=%2Fusers%2Fuser-A%2Fdrafts%2Fx/, `expected identifier prefixed with owner ns, got: ${seen[0]}`);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('non-`_uw` branch keeps caller-namespace prefixing (regression guard)', async () => {
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            seen.push(String(input));
+            return new Response(JSON.stringify({ ok: true, _xcite_json_doc: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'test-key',
+                userIsolation: { enabled: true, namespace: '/users/{userId}' },
+            });
+            c.setAppUserTokens('header.eyJzdWIiOiJ1c2VyLUIifQ.sig');
+            c.setContext({ branch: 'main', project_id: 'p1' });
+            await c.readJsonDocument('/drafts/x');
+            strict_1.default.match(seen[0], /identifier=%2Fusers%2Fuser-B%2Fdrafts%2Fx/, `expected identifier prefixed with caller ns, got: ${seen[0]}`);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('owner of `_uw/<self>/<slug>` workspace uses own namespace (no-op for owner)', async () => {
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            seen.push(String(input));
+            return new Response(JSON.stringify({ ok: true, _xcite_json_doc: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'test-key',
+                userIsolation: { enabled: true, namespace: '/users/{userId}' },
+            });
+            c.setAppUserTokens('header.eyJzdWIiOiJ1c2VyLUEifQ.sig'); // user-A
+            c.setContext({ branch: '_uw/user-A/shared', project_id: 'p1' });
+            await c.readJsonDocument('/drafts/x');
+            strict_1.default.match(seen[0], /identifier=%2Fusers%2Fuser-A%2Fdrafts%2Fx/, `expected owner to keep own ns, got: ${seen[0]}`);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
     (0, node_test_1.it)('queryByIdentifier / queryDocuments return XML bodies unmodified under userIsolation', async () => {
         const xml = '<?xml version="1.0"?><doc xmlns:db="http://www.xcitedb.com/schema"><a href="https://example.com//path">x</a></doc>';
         const orig = globalThis.fetch;

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, 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, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, 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, TxnOperation, TxnOperationResult, TxnPrecondition, TxnPreconditionResult, TxnRequest, TxnResponse, JwksKey, JwksResponse, VerifyAppUserTokenOptions, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, 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

@@ -192,8 +192,10 @@ export interface UploadAssetOptions {
     contentType: string;
     /** When set (with default scope), uploaded to this path after user-isolation prefixing rules on the server. */
     identifier?: string;
-    /** `public` writes under `/public/assets/…`. Default project/user scope when omitted. */
-    scope?: 'project' | 'public';
+    /** `shared` writes under `/shared/assets/…` (tenant-common, readable by all logged-in app users).
+     *  Default project/user scope when omitted. To publish anonymously, upload normally and use the
+     *  share API with `target_user_id: "#anonymous"`. */
+    scope?: 'project' | 'shared';
 }
 /** Result of {@link XCiteDBClient.headAsset}. */
 export interface AssetHeadResult {
@@ -761,6 +763,18 @@ export interface CreateTestSessionOptions {
      * When true, creates an overlay test session: writable ephemeral LMDB with production project data as read-only base.
      */
     overlay?: boolean;
+    /**
+     * 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.
+     *
+     * Typical use: a backend-for-frontend (BFF) that performs admin-scoped writes on behalf of the
+     * SPA. Without registering the BFF's admin key here, the BFF would receive `401
+     * test_session_unknown_api_key` when forwarding `X-Test-Session` to XCiteDB.
+     *
+     * Each entry must be a valid production API key on the project hosting the session — otherwise
+     * the server returns `400 additional_key_invalid` (with the offending index) and aborts.
+     */
+    additionalKeys?: string[];
     /** Optional server-side bootstrap (user isolation, developer_bypass, policies, triggers). */
     bootstrap?: TestSessionBootstrap;
     /**
@@ -788,6 +802,53 @@ export interface CreateTestSessionOptions {
     userIsolation?: UserIsolationOptions;
     requestTimeoutMs?: number;
 }
+/** A long-lived developer sandbox: named overlay on a project + branch. */
+export interface SandboxInfo {
+    session_token: string;
+    name: string;
+    description: string;
+    org_id: string;
+    project_id: string;
+    base_branch: string;
+    pinned: boolean;
+    effects_policy: 'real' | 'log' | 'mock';
+    created_at: number;
+    last_used: number;
+    expires_at: number;
+    reset_generation: number;
+    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' | '';
+}
+/** Options for {@link XCiteDBClient.createSandbox}. */
+export interface CreateSandboxOptions {
+    /** Required. Kebab-case, 1-64 chars, must start with a-z, no consecutive hyphens. */
+    name: string;
+    description?: string;
+    /** Pinned sandboxes are not garbage-collected by idle TTL. */
+    pinned?: boolean;
+    /** Unix seconds; 0 = no explicit expiry. */
+    expires_at?: number;
+    base_branch?: string;
+    /** Defaults to "log" — webhooks/auth-emails get captured instead of firing. */
+    effects_policy?: 'real' | 'log' | 'mock';
+}
+/** Response from {@link XCiteDBClient.mintSandboxApiKey}. The `api_key` value is shown once. */
+export interface SandboxApiKeyMintResult {
+    api_key: string;
+    key_id: string;
+    prefix: string;
+    key_type: 'secret' | 'public';
+    bound_sandbox_id: string;
+    sandbox_name: string;
+    message: string;
+}
+export interface SandboxMember {
+    member_id: string;
+    role: 'owner' | 'editor' | 'viewer';
+    added_at: number;
+    added_by: string;
+}
 /** Application user (tenant-scoped), distinct from developer users. */
 export interface AppUser {
     user_id: string;
@@ -966,7 +1027,17 @@ export interface PolicyUpdateResponse {
 export interface TriggerMatch {
     /** Non-empty array of identifier patterns (same shape as policy `resources.identifiers`). */
     identifiers: PolicyIdentifierPattern[];
+    /**
+     * Single meta path pattern (exact, or `prefix*`). Mutually exclusive with `match_meta_paths`;
+     * the server rejects writes that set both fields.
+     */
     match_meta_path?: string;
+    /**
+     * Array of meta path patterns (anyOf). Each entry is exact or `prefix*`. Useful for one
+     * trigger gating multiple fields of the same shape (e.g. role-restricted profile fields).
+     * Empty array means no constraint. Mutually exclusive with `match_meta_path`.
+     */
+    match_meta_paths?: string[];
     match_operation?: 'set' | 'append' | 'delete';
 }
 /** `action` block: run unquery and write result to target meta. */
@@ -980,10 +1051,21 @@ export interface TriggerAction {
 /** Stored trigger document under /_xcitedb/triggers. */
 export interface TriggerDefinition {
     enabled?: boolean;
+    /**
+     * `"after"` (default): run after the write commits, may run actions. `"before"`:
+     * predicate-only — runs before the write applies and rejects with HTTP 422 when matched.
+     * BEFORE triggers must not have `action` or `actions`.
+     */
+    phase?: 'before' | 'after';
     event: 'meta_changed' | 'document_written' | 'document_deleted';
     match: TriggerMatch;
     conditions?: PolicyConditions;
-    action: TriggerAction;
+    /** AFTER-trigger single action (legacy). Mutually exclusive with `actions`. Forbidden on BEFORE triggers. */
+    action?: TriggerAction;
+    /** AFTER-trigger multi-action variant. Mutually exclusive with `action`. Forbidden on BEFORE triggers. */
+    actions?: TriggerAction[];
+    /** BEFORE-trigger reject message surfaced to clients on HTTP 422. */
+    reject_reason?: string;
 }
 export interface StoredTriggerResponse {
     trigger_id: string;

package/dist/user-isolation.test.js

@@ -172,4 +172,92 @@ wd('user isolation (wet)', () => {
             await admin.disableUserIsolation().catch(() => { });
         }
     });
+    (0, node_test_1.it)('user-workspace branch: invitee reads owner-namespaced docs through self-namespace API', async () => {
+        // Issue B repro: when user B is granted readwrite on user A's user
+        // workspace and reads a doc on the workspace branch, the SDK must
+        // namespace the path with A's user_id (parsed from the `_uw/<owner>/<slug>`
+        // branch), not B's. Server-side prefixIdentifier already passes the
+        // identifier through unchanged for workspace members; the SDK must put
+        // the owner's namespace on the path before sending.
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = adminClient(e);
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const emailA = `js_uwA_${suffix}@apitest.invalid`;
+        const emailB = `js_uwB_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        const slug = `js-uw-doc-${suffix}`;
+        const wsName = `shared-${suffix}`;
+        let userA;
+        let userB;
+        let workspaceId;
+        let workspaceBranch;
+        try {
+            await admin.setUserIsolationConfig({
+                enabled: true,
+                namespace_pattern: '/users/${user.id}',
+            });
+            userA = await admin.createAppUser(emailA, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            userB = await admin.createAppUser(emailB, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            const appA = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await appA.loginAppUser(emailA, password);
+            // A creates the workspace, captures the branch from the response,
+            // grants B readwrite, and writes a doc on the workspace branch.
+            const ws = (await appA.createUserWorkspace(wsName));
+            strict_1.default.ok(ws.id, 'workspace id missing');
+            strict_1.default.ok(ws.branch && ws.branch.startsWith('_uw/'), 'workspace branch missing');
+            workspaceId = ws.id;
+            workspaceBranch = ws.branch;
+            strict_1.default.equal(workspaceBranch, `_uw/${userA.user_id}/${slugifyForAssert(wsName)}`, 'branch should be _uw/<ownerId>/<slug>');
+            await appA.addUserWorkspaceGrant(workspaceId, { user_id: userB.user_id, mode: 'rw' });
+            appA.setContext({ branch: workspaceBranch });
+            await appA.writeJsonDocument(`/${slug}`, { _xcite_json_doc: true, who: 'A', v: 1 });
+            // B opens the workspace branch and reads the doc using the relative
+            // identifier — must resolve to A's namespace, not B's.
+            const appB = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: workspaceBranch, project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await appB.loginAppUser(emailB, password);
+            const doc = await appB.readJsonDocument(`/${slug}`);
+            strict_1.default.equal(doc.who, 'A');
+            strict_1.default.equal(doc.v, 1);
+            // List on the workspace branch — identifiers must come back stripped
+            // of the owner's namespace (isoUnprefixId symmetry).
+            const list = await appB.listJsonDocuments(`/${slug.split('-')[0]}`);
+            const ids = (list.identifiers ?? []);
+            strict_1.default.ok(ids.includes(`/${slug}`), `expected response to include /${slug}, got ${JSON.stringify(ids)}`);
+        }
+        finally {
+            if (workspaceId) {
+                await admin
+                    .deleteJsonDocument(`/users/${userA?.user_id ?? ''}/${slug}`)
+                    .catch(() => { });
+                await admin.deleteUserWorkspace(workspaceId).catch(() => { });
+            }
+            if (userB)
+                await admin.deleteAppUser(userB.user_id).catch(() => { });
+            if (userA)
+                await admin.deleteAppUser(userA.user_id).catch(() => { });
+            await admin.disableUserIsolation().catch(() => { });
+        }
+    });
 });
+// Mirrors UserWorkspaceService::slugify (lowercase, runs of non-alphanumerics → '-', trim '-').
+function slugifyForAssert(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+}

package/llms-full.txt

@@ -377,6 +377,58 @@ TEST_CASE("XciteDB XML document round-trip") {
 }
 ```
 
+## Overlay sessions with a backend-for-frontend (BFF)
+
+When a single-page app is in an overlay test session and an admin-scoped action is delegated to a server-side BFF (e.g. group grants, project-editor enrolment, anything the SPA cannot do with its own credentials), the BFF must route through the **same overlay** — otherwise admin writes land in production while the SPA still reads from the overlay, and the SPA sees stale state.
+
+The mechanism is the same `X-Test-Session` header used for SPA requests, plus pre-registering the BFF's admin key on the session at create time so the server accepts it.
+
+1. **Pre-register the BFF admin key** when the SPA creates the session (SDK option `additionalKeys`, wire field `additional_keys`):
+
+   ```typescript
+   const client = await XCiteDBClient.createTestSession({
+     baseUrl, apiKey: SPA_PUBLIC_KEY,
+     overlay: true,
+     additionalKeys: [BFF_ADMIN_KEY],   // snapshotted into the session config
+     bootstrap: { user_isolation: { /* ... */ } },
+   });
+   ```
+
+   Each entry is a production API key the BFF will use. The server snapshots each into the session's config DB so requests carrying that key alongside `X-Test-Session: <token>` authenticate against the session, not production. Without this, the BFF gets `401 test_session_unknown_api_key`. An invalid key (one not present in production for the session's project) returns `400 additional_key_invalid` with the offending array index, and the session is rolled back.
+
+2. **SPA forwards `X-Test-Session` to the BFF** as a normal request header:
+
+   ```typescript
+   const r = await fetch('/api/app/grant-editor', {
+     method: 'POST',
+     headers: { 'X-Test-Session': client.testSessionToken ?? '' },
+     body: JSON.stringify({ user_id: u.user_id }),
+   });
+   ```
+
+3. **BFF reads the inbound header and propagates it on its outbound XCiteDB call.** With the JS SDK, instantiate a per-request admin client carrying the test-session token — don't reuse a long-lived admin client, since the same BFF process serves both real and test traffic:
+
+   ```typescript
+   app.post('/api/app/grant-editor', async (req, res) => {
+     const testSession = req.header('X-Test-Session') || undefined;
+     const admin = new XCiteDBClient({
+       baseUrl: process.env.XCITEDB_URL!,
+       apiKey: process.env.XCITEDB_BFF_KEY!,   // == BFF_ADMIN_KEY
+       testSessionToken: testSession,           // undefined ⇒ hits production as today
+     });
+     await admin.updateAppUserGroups(req.body.user_id, [
+       XCiteDBClient.buildProjectGroup(process.env.XCITEDB_PROJECT_ID!, 'editor'),
+     ]);
+     res.status(204).end();
+   });
+   ```
+
+   The same shape works in any HTTP framework — the only requirement is propagating `X-Test-Session` from inbound to outbound. Production traffic doesn't carry the header, so `testSessionToken` falls back to `undefined` and the admin client behaves as before.
+
+**Verification.** With this wired up, an end-to-end test that registers an app user, calls the BFF endpoint, then reads the user's groups through the SPA's overlay client should see the freshly-granted group on the next read. Without the propagation, the read returns the user's groups as they were at session creation (typically empty) and admin-gated routes return `403`.
+
+The behavior is bolted to two server pieces: `additional_keys` snapshotting in `TestController::create` (`src/controllers/TestController.cpp`) and the test-session header dispatch in `AuthFilterShared` (`src/filters/AuthFilterShared.cpp`) — there's no separate "attach admin client to existing session" API; the snapshot + header pair is sufficient.
+
 ---
 
 # Health, version & discovery
@@ -1105,18 +1157,55 @@ Definitions are stored as JSON under **`/_xcitedb/triggers`**. After a matching
 | Field | Required | Description |
 |--------|----------|-------------|
 | `enabled` | No (default true) | If false, trigger is skipped. |
+| `phase` | No (default `"after"`) | `"after"` runs post-write actions; `"before"` is predicate-only and rejects the write with HTTP 422 when matched. BEFORE triggers must not have `action` or `actions`. |
 | `event` | Yes | `meta_changed`, `document_written`, or `document_deleted`. |
-| `match` | Yes | Must include **`identifiers`**: non-empty array of identifier patterns (`exact`, `match_start`, `match_end`, `contains`, `regex`). Optional **`match_meta_path`**: exact path or prefix ending with `*`. Optional **`match_operation`**: `set`, `append`, or `delete` (meta / delete ops). |
+| `match` | Yes | Must include **`identifiers`**: non-empty array of identifier patterns (`exact`, `match_start`, `match_end`, `contains`, `regex`). Optional **`match_meta_path`** (single exact path or `prefix*`) **or** **`match_meta_paths`** (array of patterns, anyOf — useful for one trigger gating multiple fields; mutually exclusive with `match_meta_path`). Optional **`match_operation`**: `set`, `append`, or `delete`. |
 | `conditions` | No | Optional **`branches`** (same as policies) and **`expression`** (see below). |
-| `action` | Yes | **`query`** (`XCiteQuery`), **`unquery`** (Unquery DSL template), **`target_identifier`** (literal or `"$trigger_identifier"`), **`meta_path`**, optional **`mode`**: `set` (default), `append` (strict — unquery output must be a JSON array, stored target must be an array; trigger logs and skips on misuse), or `merge_append` (deep — recurses into objects to extend nested arrays). |
+| `action` | AFTER only | **`query`** (`XCiteQuery`), **`unquery`** (Unquery DSL template), **`target_identifier`** (literal or `"$trigger_identifier"`), **`meta_path`**, optional **`mode`**: `set` (default), `append` (strict — unquery output must be a JSON array, stored target must be an array; trigger logs and skips on misuse), or `merge_append` (deep — recurses into objects to extend nested arrays). Mutually exclusive with `actions`. |
+| `actions` | AFTER only | Array of action objects for multi-op fan-out. Each `kind` is one of `WriteMeta`, `AppendMeta`, `WriteJson`, `DeleteIdentifier`, `AddIdentifier`, `ClearMetaPath`. Mutually exclusive with `action`. |
+| `reject_reason` | BEFORE only | Message returned to clients on HTTP 422 when the trigger matches. |
 
-### Expression context for **triggers** (`conditions.expression`)
+### BEFORE triggers (predicate-only)
+
+`phase: "before"` triggers run *before* the write applies and reject it with **HTTP 422** when the match and conditions both hold. They are predicate-only — no `action` / `actions`. Fired only on writes routed through **`/api/v1/txn`** (regular `/api/v1/meta` and `/api/v1/json-documents` writes do not invoke BEFORE triggers).
+
+The expression sees **`prior`** alongside `value`:
 
-Not the same as policies: there is **no `subject`**. Context object:
+- **`prior`** (BEFORE + `meta_changed` only) — value at the same `meta_path` before the write. Bound only when at least one BEFORE trigger's expression references `prior`. JSON `null` when the path is currently absent.
+
+Common patterns (the expression grammar uses `=` / `!=` / `<` / `>`, and single `&` / `|` for boolean):
+
+- **Immutability after first set**: `prior is_literal & value != prior` — rejects only when a literal value already exists and differs.
+- **Monotonic non-decreasing**: `prior is_literal & value < prior`.
+- **Role-gated field**: `subject.role != 'system'` (no `prior` needed).
+
+Example (`song.id` immutable once set):
+
+```json
+{
+  "trigger_id": "song_id_immutable",
+  "trigger": {
+    "phase": "before",
+    "event": "meta_changed",
+    "match": {
+      "identifiers": [{ "match_start": "/spaces/" }],
+      "match_meta_path": "id"
+    },
+    "conditions": {
+      "expression": "prior is_literal & value != prior"
+    },
+    "reject_reason": "song id is immutable once set"
+  }
+}
+```
+
+### Expression context for **triggers** (`conditions.expression`)
 
 - **`trigger`**: `{ "event", "meta_path", "operation" }` (`operation`: `set` / `append` / `delete`)
 - **`value`**: JSON written at `meta_path` for `meta_changed`, or null
+- **`prior`** (BEFORE + `meta_changed` only): value at `meta_path` before the write, or `null` if absent
 - **`resource`**: `{ "identifier", "path" }` for the firing identifier
+- **`subject`**: `{ "id", "user_id", "email", "type", "role", "groups", "attr" }` (BEFORE only — AFTER triggers historically have no subject)
 - **`env`**: `{ "branch" }`
 
 ### Unquery variables injected for triggers

package/package.json

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

package/unquery-ai-guide.md

@@ -85,7 +85,7 @@ A path selects a value from the current context.
 | `[n]` | Array index (0-based) | `"Dependants[0].FirstName"` |
 | `[expr]` | Computed index | `"Field1[$index+1]"` |
 | `[]` | Whole array (projection over all elements) | `"Array1[].Field1"` |
-| `[a:b]` | Array **slice** in a context modifier (half-open; negative counts from end) | `"scores:[0:3]"`, `"scores:[-2:]"` |
+| `[a:b]` | Array **slice** in a context modifier or path expression (half-open; negative counts from end) | `"scores:[0:3]"`, `"scores[2:5]"`, `"$size(scores[:3])"` |
 | `/Field` | Absolute from document root | `"/employees.$(.)"` |
 | `../Field` | Up one path level (skips array indices) | `"../DBInstanceIdentifier"` |
 | `<<Field` | Read same field in *previous* document context | `"<<Field1"` after a `->$file(...)` |
@@ -710,6 +710,34 @@ Allowed only against literals (see §0.8 and §4.8):
 
 Each recipe shows a small input-shape sketch, the Unquery template, and (where useful) the equivalent jq one-liner for cross-reference.
 
+### 10.0 Materializing many rows from a prefix walk — pick a multi-row shape
+
+Common gotcha for prefix-walk queries (`{ match_start: '/index/users/' }` and similar) feeding a search dropdown or candidate list: if the template root is a **single object**, every document iteration *overwrites* the same fields and you keep only the **last** match's values.
+
+`{ "name": "name", "email": "email" }` — *wrong* for multi-row output. Returns one document's fields, not a list. (See §1's "evaluate once vs. per pass".)
+
+Three correct shapes for "give me one row per matching document":
+
+**Array of objects** (most common — preserves order, easy to iterate client-side):
+
+```json
+[{ "id": "$identifier", "name": "name", "email": "email" }]
+```
+
+**Map keyed by identifier** (constant-time lookup by id, no duplicates):
+
+```json
+{ "$($identifier)": { "name": "name", "email": "email" } }
+```
+
+**Array of identifiers only** (just need the keys, e.g. for a count or follow-up reads):
+
+```json
+["$identifier"]
+```
+
+The bare-object form is correct *only* when the prefix narrows to exactly one document or you genuinely want "last match wins" (e.g. picking a single config row). For dropdowns, search results, member lists, or any "show me everything matching" use case, default to the array-of-objects shape.
+
 ### 10.1 Pick one field per document → array
 
 ```json

package/unquery-grammar.md

@@ -128,7 +128,7 @@ Climbing parser levels:
 |--------|-----------|------------|
 | 0 | `+`, `-` | Left via loop: each new rhs parsed with `expression(1)`. |
 | 1 | `*`, `/`, `mod` | Left; rhs parsed with `expression(2)`. |
-| 3 | Postfix `.token` and `[ expr ]` | Postfix chain on current `res`. |
+| 3 | Postfix `.token`, `[ expr ]`, `[ slice ]` | Postfix chain on current `res`. |
 
 Parentheses: `(` `expression(0)` `)` as primary.
 
@@ -138,12 +138,13 @@ Parentheses: `(` `expression(0)` `)` as primary.
 expression   ::= '(' expression ')'
                 | baseExpression ( ( '+' | '-' ) expression(1)
                                  | ( '*' | '/' | 'mod' ) expression(2) )*
-                | baseExpression ( '.' fieldSegment | '[' expression ']' )*
+                | baseExpression ( '.' fieldSegment | '[' expression ']' | '[' slice ']' )*
 
+slice        ::= INT? ':' INT?                    (* INT may be `-` INT for negative-from-end *)
 fieldSegment ::= IDENT | BACKTICK_STR | '$' IDENT ...   (* lexer token after '.'; special case: if token starts with '$', subfield parse backs up — see pathWithBrackets *)
 ```
 
-**Postfix** (prec ≤ 3): after `consume()` of `.` or `[`, if `[` then parse `expression(0)` unless next is `]`; require `]`; build `TExprSubfield(res, expr_or_empty, is_index)`.
+**Postfix** (prec ≤ 3): after `consume()` of `.` or `[`, if `[` then either (a) parse a slice `INT? ':' INT?` followed by `]` → `TExprSlice(res, …)`, or (b) parse `expression(0)` followed by `]` → `TExprSubfield(res, expr_or_empty, is_index)`. Empty `[]` builds `TExprSubfield` with no expression. Slice detection uses backtracking: a single integer with no `:` falls through to the expression form.
 
 ### 4.3 `baseExpression` — alternatives (first token disambiguation)
 
@@ -151,7 +152,8 @@ Roughly in parse order:
 
 | Prefix / form | AST | Notes |
 |-----------------|-----|--------|
-| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. (Slice `[a:b]` form is currently parsed only on context modifiers, not in path expressions.) |
+| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. |
+| `[` (INT)? `:` (INT)? `]` | `TExprSlice(TExprField("."), …)` | Half-open array slice on `.`. Negative ints count from end. Bounds must be integer literals (with optional `-`). Yields a JSON array. |
 | `$` `(` `expression` `)` | `TExprField(expr)` | Evaluate / path from dynamic name (`$()`). |
 | `$if` `(` `condition` `,` `expression` `,` `expression` `)` | `TExprITE` | |
 | `$call` `(` IDENT `)` | `TExprCall(name)` | Zero-arg user function by name. |