@xcitedbs/client 0.2.11 → 0.2.13

package/README.md

@@ -34,6 +34,19 @@ const docs = await client.queryByIdentifier('/test1', 'FirstMatch');
 await client.put('app.settings', { theme: 'dark' });
 ```
 
+### Full-text search (temporal)
+
+`client.search()` accepts `TextSearchQuery` with optional **`at_date`** (point-in-time), **`date_from`** / **`date_to`** (range overlap), and **`mode`: `'fts'`** for pure keyword search. Omit temporal fields for the default “current” posting view. Hits may include **`valid_from`** / **`valid_to`** (7-character internal date keys returned by the server).
+
+```typescript
+await client.search({
+  query: 'installation guide',
+  mode: 'fts',
+  at_date: '2024-06-01',
+  limit: 20,
+});
+```
+
 ### WebSocket
 
 ```typescript
@@ -45,6 +58,15 @@ client.subscribe(
 
 With JWT in browsers, tokens are passed as `access_token` query parameter on the WebSocket URL. API keys can use `api_key` query parameter.
 
+## Test sessions (ephemeral and overlay)
+
+Call **`POST /api/v1/test/sessions`** with your normal API key or Bearer (same project context as usual). Use **`XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`** to get a client that sends **`X-Test-Session`** on requests.
+
+- **Default:** isolated empty LMDB under the server’s `_test/<uuid>/` (writes never touch production).
+- **Overlay:** pass **`overlay: true`** in **`createTestSession`** options (or **`POST`** body **`{"overlay":true}`**). The server layers a writable LMDB on top of the **current project’s on-disk data opened read-only** so you can debug against real data; changes still live only under `_test/<uuid>/`. Use project-scoped credentials or platform Bearer + **`X-Project-Id`** as when calling production APIs.
+
+Tear down with **`destroyTestSession()`** (or **`DELETE /api/v1/test/sessions/current`** with the session header). See **`llms.txt`** / **`llms-full.txt`** in this package for full behavior, limits, and auth notes.
+
 ## 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, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery, UserIsolationConfig } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery, UserIsolationConfig } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -18,10 +18,13 @@ export declare class XCiteDBClient {
     private testRequireAuth?;
     private userIsolation?;
     private cachedAppUserId?;
+    private readonly requestTimeoutMs?;
     constructor(options: XCiteDBClientOptions);
     /**
-     * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
+     * Create an ephemeral test database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
      * then returns a client that sends `X-Test-Session` (auth-free by default).
+     * With `opts.overlay === true`, the server stores overlay mode: reads merge the empty `_test/...` LMDB
+     * over the current project's production data (read-only base); writes stay under `_test/...` only.
      */
     static createTestSession(opts: CreateTestSessionOptions): Promise<XCiteDBClient>;
     /**
@@ -433,12 +436,18 @@ export declare class XCiteDBClient {
     queryLog(query: XCiteQuery, fromDate: string, toDate: string): Promise<LogEntry[]>;
     addMeta(identifier: string, value: unknown, path?: string, opts?: {
         mode?: 'set' | 'append';
+        overwrite?: boolean;
     }): Promise<boolean>;
     addMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
         mode?: 'set' | 'append';
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    appendMeta(identifier: string, value: unknown, path?: string, opts?: {
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
+        overwrite?: boolean;
     }): Promise<boolean>;
-    appendMeta(identifier: string, value: unknown, path?: string): Promise<boolean>;
-    appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean): Promise<boolean>;
     queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;
     queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string): Promise<T>;
     clearMeta(query: XCiteQuery): Promise<boolean>;
@@ -484,6 +493,18 @@ export declare class XCiteDBClient {
     getProjectSearchSettings(): Promise<ProjectSearchSettings>;
     /** Update project search settings (`PUT /api/v1/project/settings/search`). Returns the same shape as GET. */
     updateProjectSearchSettings(patch: ProjectSearchSettingsUpdate): Promise<ProjectSearchSettings>;
+    /** Per-project `document.conf` override (`GET /api/v1/project/settings/doc-conf`). */
+    getProjectDocConf(): Promise<ProjectDocConfResponse>;
+    /** Save or clear project `document.conf` (`PUT /api/v1/project/settings/doc-conf`). */
+    updateProjectDocConf(body: {
+        doc_conf_text: string;
+    } | {
+        clear: true;
+    }): Promise<ProjectDocConfResponse>;
+    /** Remove project override; server uses platform default (`DELETE /api/v1/project/settings/doc-conf`). */
+    deleteProjectDocConf(): Promise<ProjectDocConfResponse>;
+    /** Embedded platform default `document.conf` text (`GET /api/v1/platform/default-doc-conf`). */
+    getPlatformDefaultDocConf(): Promise<PlatformDefaultDocConfResponse>;
     /** Blocking full DB scan (admin; no calls to embedding API). Prefer {@link postVectorIndexEstimateSession} for UI. */
     getVectorIndexEstimate(): Promise<VectorIndexEstimate>;
     /** Start background estimate (202); cancel prior session for this tenant. */
@@ -502,12 +523,16 @@ export declare class XCiteDBClient {
      * The final event has `done: true` and may include `sources`.
      */
     ragQueryStream(options: Omit<RagQueryOptions, 'stream'>, onEvent: (ev: RagStreamEvent) => void): Promise<void>;
-    writeJsonDocument(identifier: string, data: unknown): Promise<void>;
+    writeJsonDocument(identifier: string, data: unknown, opts?: {
+        overwrite?: boolean;
+    }): Promise<void>;
     readJsonDocument<T = unknown>(identifier: string): Promise<T>;
     deleteJsonDocument(identifier: string): Promise<void>;
     listJsonDocuments(match?: string, limit?: number, offset?: number): Promise<ListIdentifiersResult>;
     /** JSON document shorthand — same as {@link writeJsonDocument}. */
-    put(identifier: string, data: unknown): Promise<void>;
+    put(identifier: string, data: unknown, opts?: {
+        overwrite?: boolean;
+    }): Promise<void>;
     /** JSON document read — same as {@link readJsonDocument}. */
     get<T = unknown>(identifier: string): Promise<T>;
     /** JSON document delete — same as {@link deleteJsonDocument}. */

package/dist/client.js

@@ -18,6 +18,30 @@ function buildQuery(params) {
     const s = sp.toString();
     return s ? `?${s}` : '';
 }
+function warnIfHttpOnTlsPort(baseUrl) {
+    try {
+        const u = new URL(baseUrl);
+        if (u.protocol !== 'http:')
+            return;
+        if (u.port === '443') {
+            if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+                console.warn('[@xcitedbs/client] baseUrl uses http: on port 443; use https:// to avoid hangs or TLS errors.');
+            }
+        }
+    }
+    catch {
+        /* ignore invalid baseUrl */
+    }
+}
+/** Uses `AbortSignal.timeout` when the runtime supports it. */
+function requestTimeoutSignal(ms) {
+    if (ms === undefined || ms <= 0)
+        return undefined;
+    const ctor = AbortSignal;
+    if (typeof ctor.timeout === 'function')
+        return ctor.timeout(ms);
+    return undefined;
+}
 class XCiteDBClient {
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/+$/, '');
@@ -34,10 +58,14 @@ class XCiteDBClient {
         this.testSessionToken = options.testSessionToken;
         this.testRequireAuth = options.testRequireAuth === true;
         this.userIsolation = options.userIsolation;
+        this.requestTimeoutMs = options.requestTimeoutMs;
+        warnIfHttpOnTlsPort(this.baseUrl);
     }
     /**
-     * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
+     * Create an ephemeral test database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
      * then returns a client that sends `X-Test-Session` (auth-free by default).
+     * With `opts.overlay === true`, the server stores overlay mode: reads merge the empty `_test/...` LMDB
+     * over the current project's production data (read-only base); writes stay under `_test/...` only.
      */
     static async createTestSession(opts) {
         const temp = new XCiteDBClient({
@@ -53,8 +81,9 @@ class XCiteDBClient {
             onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
             onSessionInvalid: opts.onSessionInvalid,
             userIsolation: opts.userIsolation,
+            requestTimeoutMs: opts.requestTimeoutMs,
         });
-        const data = await temp.request('POST', '/api/v1/test/sessions', undefined, undefined, { no401Retry: true });
+        const data = await temp.request('POST', '/api/v1/test/sessions', opts.overlay === true ? { overlay: true } : undefined, undefined, { no401Retry: true });
         return new XCiteDBClient({
             baseUrl: opts.baseUrl,
             apiKey: opts.testRequireAuth ? opts.apiKey : undefined,
@@ -70,6 +99,7 @@ class XCiteDBClient {
             testSessionToken: data.session_token,
             testRequireAuth: opts.testRequireAuth,
             userIsolation: opts.userIsolation,
+            requestTimeoutMs: opts.requestTimeoutMs,
         });
     }
     /**
@@ -444,6 +474,9 @@ class XCiteDBClient {
                     init.body = JSON.stringify(body);
                 }
             }
+            const sig = requestTimeoutSignal(this.requestTimeoutMs);
+            if (sig)
+                init.signal = sig;
             const res = await fetch(url, init);
             const text = await res.text();
             let data;
@@ -1319,6 +1352,8 @@ class XCiteDBClient {
         const body = { identifier: this.isoPrefixId(identifier), value, path };
         if (opts?.mode === 'append')
             body.mode = 'append';
+        if (opts?.overwrite)
+            body.overwrite = true;
         const r = await this.request('POST', '/api/v1/meta', body);
         return r?.ok !== false;
     }
@@ -1331,14 +1366,16 @@ class XCiteDBClient {
         };
         if (opts?.mode === 'append')
             body.mode = 'append';
+        if (opts?.overwrite)
+            body.overwrite = true;
         const r = await this.request('POST', '/api/v1/meta', body);
         return r?.ok !== false;
     }
-    async appendMeta(identifier, value, path = '') {
-        return this.addMeta(identifier, value, path, { mode: 'append' });
+    async appendMeta(identifier, value, path = '', opts) {
+        return this.addMeta(identifier, value, path, { mode: 'append', ...opts });
     }
-    async appendMetaByQuery(query, value, path = '', firstMatch = false) {
-        return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append' });
+    async appendMetaByQuery(query, value, path = '', firstMatch = false, opts) {
+        return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append', ...opts });
     }
     async queryMeta(identifier, path = '') {
         return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`);
@@ -1410,12 +1447,18 @@ class XCiteDBClient {
             body.offset = q.offset;
         if (q.limit !== undefined)
             body.limit = q.limit;
-        if (q.mode)
+        if (q.mode !== undefined)
             body.mode = q.mode;
         if (q.min_score !== undefined)
             body.min_score = q.min_score;
         if (q.semantic_weight !== undefined)
             body.semantic_weight = q.semantic_weight;
+        if (q.at_date !== undefined && q.at_date !== '')
+            body.at_date = q.at_date;
+        if (q.date_from !== undefined && q.date_from !== '')
+            body.date_from = q.date_from;
+        if (q.date_to !== undefined && q.date_to !== '')
+            body.date_to = q.date_to;
         const data = await this.request('POST', '/api/v1/search', body);
         const hits = [];
         if (Array.isArray(data.hits)) {
@@ -1436,6 +1479,12 @@ class XCiteDBClient {
                     if (o.source === 'fts' || o.source === 'semantic' || o.source === 'both') {
                         hit.source = o.source;
                     }
+                    if (typeof o.valid_from === 'string' && o.valid_from.length > 0) {
+                        hit.valid_from = o.valid_from;
+                    }
+                    if (typeof o.valid_to === 'string' && o.valid_to.length > 0) {
+                        hit.valid_to = o.valid_to;
+                    }
                     hits.push(hit);
                 }
             }
@@ -1460,6 +1509,22 @@ class XCiteDBClient {
     async updateProjectSearchSettings(patch) {
         return this.request('PUT', '/api/v1/project/settings/search', patch);
     }
+    /** Per-project `document.conf` override (`GET /api/v1/project/settings/doc-conf`). */
+    async getProjectDocConf() {
+        return this.request('GET', '/api/v1/project/settings/doc-conf');
+    }
+    /** Save or clear project `document.conf` (`PUT /api/v1/project/settings/doc-conf`). */
+    async updateProjectDocConf(body) {
+        return this.request('PUT', '/api/v1/project/settings/doc-conf', body);
+    }
+    /** Remove project override; server uses platform default (`DELETE /api/v1/project/settings/doc-conf`). */
+    async deleteProjectDocConf() {
+        return this.request('DELETE', '/api/v1/project/settings/doc-conf');
+    }
+    /** Embedded platform default `document.conf` text (`GET /api/v1/platform/default-doc-conf`). */
+    async getPlatformDefaultDocConf() {
+        return this.request('GET', '/api/v1/platform/default-doc-conf');
+    }
     /** Blocking full DB scan (admin; no calls to embedding API). Prefer {@link postVectorIndexEstimateSession} for UI. */
     async getVectorIndexEstimate() {
         return this.request('GET', '/api/v1/project/settings/search/vector-index-estimate', undefined);
@@ -1593,8 +1658,11 @@ class XCiteDBClient {
         }
         throw new types_1.XCiteDBError('RAG stream failed after retry', 401, null);
     }
-    async writeJsonDocument(identifier, data) {
-        await this.request('POST', '/api/v1/json-documents', { identifier: this.isoPrefixId(identifier), data });
+    async writeJsonDocument(identifier, data, opts) {
+        const body = { identifier: this.isoPrefixId(identifier), data };
+        if (opts?.overwrite)
+            body.overwrite = true;
+        await this.request('POST', '/api/v1/json-documents', body);
     }
     async readJsonDocument(identifier) {
         return this.request('GET', `/api/v1/json-documents${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
@@ -1623,8 +1691,8 @@ class XCiteDBClient {
         return { identifiers: [], total: 0, offset: 0, limit: 0 };
     }
     /** JSON document shorthand — same as {@link writeJsonDocument}. */
-    async put(identifier, data) {
-        return this.writeJsonDocument(identifier, data);
+    async put(identifier, data, opts) {
+        return this.writeJsonDocument(identifier, data, opts);
     }
     /** JSON document read — same as {@link readJsonDocument}. */
     async get(identifier) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { XCiteDBClient } from './client';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationOptions, WorkspaceInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, 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, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationOptions, WorkspaceInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -41,12 +41,20 @@ export interface TextSearchQuery {
     branch?: string;
     offset?: number;
     limit?: number;
-    /** Default `fts`. `semantic` / `hybrid` require vector search (and hybrid requires FTS). */
-    mode?: 'fts' | 'semantic' | 'hybrid';
+    /**
+     * Default server behavior when omitted: `auto` (hybrid if FTS+vector enabled, else semantic or FTS).
+     * Explicit `fts` / `semantic` / `hybrid` require the matching capabilities to be enabled.
+     */
+    mode?: 'auto' | 'fts' | 'semantic' | 'hybrid';
     /** Minimum cosine similarity for semantic / hybrid vector leg (default 0.3). */
     min_score?: number;
     /** Hybrid only: weight of semantic vs FTS in weighted RRF (0–1, default 0.5). */
     semantic_weight?: number;
+    /** Point-in-time FTS filter (ISO date string; server maps to internal date key). */
+    at_date?: string;
+    /** Range FTS filter: interval overlap with [date_from, date_to) (ISO dates). */
+    date_from?: string;
+    date_to?: string;
 }
 export interface TextSearchHit {
     identifier: string;
@@ -59,6 +67,9 @@ export interface TextSearchHit {
     score: number;
     /** Present for semantic / hybrid search. */
     source?: 'fts' | 'semantic' | 'both';
+    /** FTS temporal window for this hit (internal 7-char keys), when returned by the server. */
+    valid_from?: string;
+    valid_to?: string;
 }
 export interface TextSearchResult {
     hits: TextSearchHit[];
@@ -153,6 +164,15 @@ export interface ProjectSearchSettingsUpdate {
     llm_base_url?: string | null;
     llm_api_key?: string;
 }
+/** `GET /api/v1/project/settings/doc-conf` (and returned after `PUT` / `DELETE`). */
+export interface ProjectDocConfResponse {
+    has_project_override: boolean;
+    doc_conf_text: string | null;
+}
+/** `GET /api/v1/platform/default-doc-conf` */
+export interface PlatformDefaultDocConfResponse {
+    doc_conf_text: string;
+}
 /** `POST /api/v1/rag/query` (non-streaming: set `stream: false` or omit). */
 export interface RagQueryOptions {
     question: string;
@@ -314,6 +334,11 @@ export interface DatabaseContext {
     workspace?: string;
     /** @deprecated Prefer {@link DatabaseContext.workspace}. Sent as `X-Branch` when `workspace` is unset. */
     branch?: string;
+    /**
+     * As-of revision time, sent as `X-Date`. Accepted forms (whole string must match; trailing spaces ignored):
+     * `mm/dd/yyyy`, `mm/dd/yyyy:HH:MM:SS`, ISO `YYYY-MM-DDTHH:MM:SS` with optional numeric timezone,
+     * `YYYY-MM-DD HH:MM:SS`, and ISO date-only `YYYY-MM-DD`.
+     */
     date?: string;
     prefix?: string;
     /**
@@ -392,6 +417,11 @@ export interface XCiteDBClientOptions {
     testRequireAuth?: boolean;
     /** Auto-prefix identifiers for app-user sessions (see {@link UserIsolationOptions}). */
     userIsolation?: UserIsolationOptions;
+    /**
+     * Per-request timeout in milliseconds for normal REST calls (uses `AbortSignal.timeout` when available).
+     * Omit for no timeout. Streaming RAG (`ragQueryStream`) does not apply this.
+     */
+    requestTimeoutMs?: number;
 }
 /** Options for {@link XCiteDBClient.createTestSession} (provisions via API key or Bearer). */
 export interface CreateTestSessionOptions {
@@ -403,12 +433,17 @@ export interface CreateTestSessionOptions {
     context?: DatabaseContext;
     platformConsole?: boolean;
     projectId?: string;
+    /**
+     * When true, creates an overlay test session: writable ephemeral LMDB with production project data as read-only base.
+     */
+    overlay?: boolean;
     /** Keep `apiKey` / `accessToken` on the client and send `X-Test-Auth: required` on each request. */
     testRequireAuth?: boolean;
     onSessionTokensUpdated?: (pair: TokenPair) => void;
     onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
     onSessionInvalid?: () => void;
     userIsolation?: UserIsolationOptions;
+    requestTimeoutMs?: number;
 }
 /** Application user (tenant-scoped), distinct from developer users. */
 export interface AppUser {

package/llms-full.txt

@@ -26,7 +26,9 @@ Before reading the full reference, note these critical differences from typical
 
 9. **OpenAPI:** See repository `docs/openapi.yaml` for a machine-readable route map.
 
-10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
+10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. With a default body (omit or `{}`), the test LMDB starts **empty** (no cloned production project config).
+
+11. **Overlay test sessions.** Same **`POST`**, with JSON **`{"overlay":true}`**, while authenticated for the **project to debug** (project-scoped API key, or platform Bearer + **`X-Project-Id`**). The session metadata records overlay mode; subsequent requests need only **`X-Test-Session`**. The server opens **`XCiteDB(_test/<uuid>/data, <production data path>)`**: production is used as a **read-only base**; reads merge overlay + base; **writes never modify production**. If the production data directory is missing, opening the session database fails. JS **`createTestSession({ …, overlay: true })`**, C++ **`test_session_overlay`** + **`create_test_session`**, MCP **`create_test_session`** tool **`overlay: true`**.
 
 ## Choosing the Right Versioning Approach
 
@@ -58,7 +60,7 @@ Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain
 
 6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To assign specific groups, use the admin endpoint `createAppUser()` instead, or update groups after registration via `updateAppUserGroups()`.
 
-7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Ephemeral test sessions" below.
+7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real LMDB under `_test/<uuid>/` (empty by default, or **overlay** on read-only production with **`{"overlay":true}`** / **`overlay: true`** / **`test_session_overlay`**). See "Ephemeral test sessions" below.
 
 ---
 
@@ -205,7 +207,7 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 
 | Step | What to do |
 |------|------------|
-| **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). |
+| **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). Optional JSON body **`{"overlay":true}`** provisions a **read-through production** session (writable delta only under `_test/<uuid>/`; production LMDB is read-only base). |
 | **Use** | Send **`X-Test-Session: <session_token>`** on document and other data API requests. The server routes to a dedicated LMDB under its data root (`_test/<id>/`), not the caller’s production tenant. **`tenant_id` / `X-Project-Id` semantics do not select production** while the test header is present—the synthetic test tenant is implied. |
 | **Auth** | **Default:** developer auth (API key / platform JWT) is **bypassed** with a synthetic admin identity. However, **app-user identity is still recognized**: if `X-App-User-Token` or a Bearer app-user JWT is present, the request runs as that app user (for routes like `/app/auth/me`). **`X-Test-Auth: required`:** all auth is validated normally; ABAC applies, but data still comes from the test session DB. |
 | **Manage** | **`GET /api/v1/test/sessions`** — list sessions for the current credential. **`DELETE /api/v1/test/sessions/current`** — destroy the session named by **`X-Test-Session`** (no other auth). **`DELETE /api/v1/test/sessions/all`** — destroy all sessions for the credential. **`DELETE /api/v1/test/sessions/{token}`** — destroy one session if owned by the credential. Do **not** send **`X-Test-Session`** on these `/api/v1/test/*` routes. |
@@ -213,9 +215,9 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 
 **SDK usage (summary):**
 
-- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })` returns a client configured with `testSessionToken`; optional `testRequireAuth: true` maps to `X-Test-Auth: required`. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
-- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor.
-- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key` (and optional `test_require_auth`); `destroy_test_session()`.
+- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
+- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor. For overlay until the helper accepts a flag, call **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`** then construct the client with the returned token.
+- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay = true`**, and optional `test_require_auth`; `destroy_test_session()`.
 
 **JavaScript/TypeScript — complete test scaffold (Vitest / Jest):**
 
@@ -450,14 +452,23 @@ Returns `{ parent_path, parent_is_identifier, children: [{ segment, full_path, i
 
 **`POST /api/v1/json-documents`**
 
+JSON body fields:
+
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `identifier` | yes | Document path key |
+| `data` | yes | JSON value to merge or store |
+| `overwrite` | no (default `false`) | When `true`, delete all metadata under the document root first, then write `data` only. When `false`, **`data` is merged** into any existing document (nested objects combine fields; nested arrays follow meta merge rules—see Metadata). |
+
 ```json
 {
   "identifier": "app.settings",
-  "data": { "theme": "dark", "maxUploadMb": 25 }
+  "data": { "theme": "dark", "maxUploadMb": 25 },
+  "overwrite": false
 }
 ```
 
-Note: The SDK method uses `identifier` and `data` fields. Some older documentation shows `key` and `value`.
+Note: SDKs use `identifier` and `data` (optional `overwrite`). Some older documentation shows `key` and `value`.
 
 ## Read JSON document
 
@@ -501,15 +512,26 @@ Attach structured **JSON metadata** to documents or nodes.
 
 **`POST /api/v1/meta`**
 
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `identifier` **or** `query` | one required | Target document id or document query |
+| `value` | yes | JSON to write (omit only for string-specific query batch paths handled by the server) |
+| `path` | no (default `""`) | Meta path (dot-separated keys; `[i]` for array indices) |
+| `mode` | no (default `"set"`) | `"set"` — write/replace at `path`. For **arrays** at `path`, indices `0..n-1` are written and any previous tail beyond the new length is cleared. `"append"` — for **arrays** at `path`, new elements are written after existing indices (extend in place). |
+| `overwrite` | no (default `false`) | When `true`, delete existing metadata under `path` before applying `value`. |
+| `first_match` | no | With `query`, only the first matching identifier is updated when `true`. |
+
 ```json
 {
   "identifier": "/book/ch1",
   "value": { "status": "review", "owner": "alice" },
-  "path": ""
+  "path": "",
+  "mode": "set",
+  "overwrite": false
 }
 ```
 
-Optional `"mode": "append"` to append rather than overwrite.
+Use `"mode": "append"` to extend arrays at `path` instead of replacing them.
 
 Can also use `"query"` instead of `"identifier"` to target multiple documents by query filter.
 
@@ -525,11 +547,17 @@ Can also use `"query"` instead of `"identifier"` to target multiple documents by
 
 **`DELETE /api/v1/meta`** — `{ "query": {...} }`
 
+## JSON metadata storage model (best practices)
+
+- **Field-indexed objects.** Metadata and standalone JSON documents share the same shredded-key storage. **JSON objects** map to named paths so fields can be read or updated without loading a monolithic blob.
+- **Dictionary threshold.** When the **set of distinct field names** on an object reaches the server threshold (default **32**, native setting `meta_dict_field_threshold`), XCiteDB switches that object to **dictionary storage** (`{*}` plus per-field keys) for scalable indexed access.
+- **Modeling guidance.** Prefer stable **`{ "key": value, ... }`** / nested-object shapes for records you look up by key. Arrays are appropriate for ordered lists; use **`mode: "append"`** when appending to a stored array.
+
 ---
 
 # Search
 
-Full-text search (backed by Meilisearch or Elasticsearch).
+Full-text search uses **embedded XciteFTS** (LMDB index per project). **Semantic** and **hybrid** (FTS + vector) search are available when vector search is enabled in project settings. The JSON field **`mode`** selects behavior (`auto` picks the best option for the project, or set `fts`, `semantic`, or `hybrid` explicitly).
 
 **Base path:** `/api/v1/search`
 
@@ -543,15 +571,26 @@ Full-text search (backed by Meilisearch or Elasticsearch).
   "doc_types": ["xml", "json"],
   "branch": "",
   "limit": 20,
-  "offset": 0
+  "offset": 0,
+  "mode": "fts"
 }
 ```
 
-Response: `{ hits: [{ identifier, path, doc_type, branch, snippet, score, xcitepath? }], total, query }`.
+Optional fields (also on SDK `TextSearchQuery` and the MCP `search` tool): **`min_score`**, **`semantic_weight`** for semantic/hybrid.
+
+**Temporal FTS** (posting intervals; applies to the FTS keyword index—use **`mode`: `"fts"`** for pure temporal keyword search, or hybrid where the FTS leg participates):
+
+| Field | Meaning |
+|-------|---------|
+| **`at_date`** | Date string (e.g. ISO `YYYY-MM-DD` or `mm/dd/yyyy` as accepted by the server). A posting matches if it is valid at that instant: `start <= at_date < end` (internal 7-char keys after `date2key`). |
+| **`date_from`**, **`date_to`** | Date strings defining a half-open range `[date_from, date_to)`. A posting matches if its `[start, end)` **overlaps** that range. Either bound may be omitted (open-ended). |
+| *(none of the three)* | **Current-time** view: only postings whose interval is still “open” (end at the internal max sentinel) are included. |
+
+**Response:** `{ hits: [...], total, query }`. Each hit has **`identifier`**, **`path`**, **`doc_type`**, **`branch`**, **`snippet`**, **`score`**, and optionally **`xcitepath`** (XML). Semantic/hybrid hits may include **`source`**: `fts` \| `semantic` \| `both`. When the server infers a temporal window for the matched term(s), hits may include **`valid_from`** and **`valid_to`** as **7-character internal date keys** (same alphabet as revision keys—not ISO). Omitted for full-range/unversioned postings or when not computed.
 
 ## Reindex
 
-**`POST /api/v1/search/reindex`** — Rebuilds the search index.
+**`POST /api/v1/search/reindex`** — Rebuilds the full-text search index.
 
 ---
 
@@ -1361,17 +1400,17 @@ interface DatabaseContext {
 - `queryLog(query, fromDate, toDate)` → `LogEntry[]`
 
 ### JSON Documents
-- `writeJsonDocument(identifier, data)` → `void`
+- `writeJsonDocument(identifier, data, opts?)` → `void` — merge by default; `opts?.overwrite` replaces root
 - `readJsonDocument<T>(identifier)` → `T` (default `unknown`)
 - `deleteJsonDocument(identifier)` → `void`
 - `listJsonDocuments(match?, limit?, offset?)` → `ListIdentifiersResult`
-- `put(identifier, data)` / `get<T>(identifier)` / `remove(identifier)` / `list(match?, limit?, offset?)` — JSON CRUD aliases
+- `put(identifier, data, opts?)` / `get<T>(identifier)` / `remove(identifier)` / `list(match?, limit?, offset?)` — JSON CRUD aliases (`opts` same as `writeJsonDocument`)
 
 ### Metadata
-- `addMeta(identifier, value, path?, opts?)` → `boolean`
+- `addMeta(identifier, value, path?, opts?)` → `boolean` — `opts`: `mode?: 'set'|'append'`, `overwrite?: boolean`
 - `addMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
-- `appendMeta(identifier, value, path?)` → `boolean`
-- `appendMetaByQuery(query, value, path?, firstMatch?)` → `boolean`
+- `appendMeta(identifier, value, path?, opts?)` → `boolean` — same as `addMeta` with `mode: 'append'`
+- `appendMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
 - `queryMeta<T>(identifier, path?)` → `T`
 - `queryMetaByQuery<T>(query, path?)` → `T`
 - `clearMeta(query)` → `boolean`
@@ -1411,7 +1450,7 @@ interface DatabaseContext {
 - `findLocks(identifier)` → `LockInfo[]`
 
 ### Search
-- `search(query: TextSearchQuery)` → `TextSearchResult`
+- `search(query: TextSearchQuery)` → `TextSearchResult`. Query may include **`at_date`**, **`date_from`**, **`date_to`** (ISO-style or `mm/dd/yyyy` strings) for temporal FTS; set **`mode`: `"fts"`** for keyword-only temporal search. Hits may include **`valid_from`** / **`valid_to`** (7-char internal keys) when the server returns an inferred validity window.
 - `reindex()` → `{ status, message }`
 
 ### Unquery
@@ -1544,6 +1583,7 @@ async def main():
         print(await client.read_json_document("app.settings"))
         print(await client.list_identifiers(XCiteQuery(match_start="/manual/")))
         print(await client.search(TextSearchQuery(query="guide", limit=10)))
+        # Temporal FTS: await client.search(TextSearchQuery(query="guide", mode="fts", at_date="2024-06-01"))
         await client.platform_login("admin@localhost", "password")
         # await client.login_app_user("user@example.com", "pw")  # set context.project_id / tenant_id if needed
         async with client.with_workspace("feature-x", message="WIP", auto_merge=True):

package/llms.txt

@@ -22,7 +22,7 @@ These are the most common sources of confusion for developers and AI assistants:
 
 8. **Project vs tenant id.** In the SDK, prefer `context.project_id` (and `listMyProjects` / `switchProject`). Many JSON bodies and JWT claims still use the field name `tenant_id` for the same value — the client sends that wire name automatically.
 
-9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default **developer** auth (API key / platform JWT) is bypassed, but **app-user** identity (`X-App-User-Token` or Bearer app-user JWT) is still recognized. Send **`X-Test-Auth: required`** to exercise full developer JWT/API-key auth and ABAC against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). The test DB starts **empty** (no copy of production project config or keys).
+9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default **developer** auth (API key / platform JWT) is bypassed, but **app-user** identity (`X-App-User-Token` or Bearer app-user JWT) is still recognized. Send **`X-Test-Auth: required`** to exercise full developer JWT/API-key auth and ABAC against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). By default the test LMDB starts **empty** (no production data). **Overlay mode:** same **`POST`** with JSON body **`{"overlay":true}`** (while authenticated for the project you want to inspect—project-scoped API key, or platform Bearer + **`X-Project-Id`**). The server opens a **writable** LMDB under `_test/<uuid>/` with that project’s on-disk store as a **read-only base** (dual LMDB): reads see production + overlay deltas; **writes never touch production**. **`XCiteDBClient.createTestSession({ …, overlay: true })`** sends that body. After creation, only **`X-Test-Session`** is required on requests (overlay is stored in session metadata).
 
 ## Choosing the Right Versioning Approach
 
@@ -58,7 +58,7 @@ Legacy REST paths (`/api/v1/branches`, `/commits`, `/tags`, `/diff`) remain as *
 
 6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To set groups explicitly, use **`createAppUser`** with a `groups` array (e.g. `[XCiteDBClient.buildProjectGroup(projectId, 'editor')]`) or **`updateAppUserGroups`**. The server rejects `project:<x>:*` groups when `<x>` is not a known internal project id (avoids mistaking the display name for the tenant id).
 
-7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Test mode" below.
+7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real LMDB that is scoped under `_test/<uuid>/` and destroyed after the test (empty by default, or **overlay** on read-only production when you pass **`{"overlay":true}`** / **`overlay: true`**). See "Test mode" below.
 
 8. **403 on writes with ABAC is often a JWT/group string mismatch.** Decode the app-user access token early: log **`tenant_id`**, **`groups`**, **`sub`**. The middle segment of every **`project:<x>:role`** group must equal **`tenant_id`** exactly. Document write denials may return JSON fields **`policy_id`** and **`hint`** alongside `"Forbidden"`.
 
@@ -105,11 +105,17 @@ await app.writeJsonDocument('userdata/alice/profile', { ok: true });
 
 > **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised.
 
-1. **Provision:** `POST /api/v1/test/sessions` with `Authorization: Bearer …` or `X-API-Key` (same as normal API access). Response JSON includes the session token.
-2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Workspace` / `context` as needed). Data is stored under the server’s `_test/<session>/` area, not your production tenant.
+1. **Provision:** `POST /api/v1/test/sessions` with `Authorization: Bearer …` or `X-API-Key` (same as normal API access). Optional JSON body **`{"overlay":true}`** creates an **overlay** session (read-through production, writes only under `_test/<session>/`). Response JSON includes the session token (and **`"overlay": true`** when applicable).
+2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Workspace` / `context` as needed). Data writes go under the server’s `_test/<session>/` tree; overlay sessions **do not** write to production paths.
 3. **Auth behavior:** Developer auth (API key / platform JWT) is bypassed by default for frictionless tests. **App-user identity** (`X-App-User-Token` or Bearer app-user JWT) **is still recognized** in default mode, so `registerAppUser` → `loginAppUser` → `appUserMe` works inside a test session. To also exercise developer auth and ABAC policies, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
 4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
-5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or manual token + `test_session_token` / `test_require_auth` constructor args. **C++:** `XCiteDBClient::create_test_session(options)`, `destroy_test_session()`, optional `test_require_auth` in options.
+5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `overlay: true`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or provision with **`POST /api/v1/test/sessions`** and JSON **`{"overlay":true}`** when you need overlay, then pass `test_session_token` / `test_require_auth` to the constructor. **C++:** `XCiteDBClient::create_test_session(options)` with optional `test_session_overlay = true`, `destroy_test_session()`, optional `test_require_auth` in options.
+
+## JSON documents and metadata (merge, overwrite, efficiency)
+
+- **JSON documents merge by default.** `POST /api/v1/json-documents` merges the posted `data` into the existing document (object fields combined per XCiteDB meta merge rules). Send **`overwrite: true`** to clear all stored JSON under that document root first, then write only the new payload. SDKs accept the same flag (e.g. `writeJsonDocument(id, data, { overwrite: true })` in JavaScript).
+- **Metadata `mode` and arrays.** **`POST /api/v1/meta`** uses **`mode`**: default **`set`** writes or replaces at `path` (arrays are replaced in range; excess old indices cleared); **`append`** appends array elements after existing ones at `path`. Optional **`overwrite: true`** clears metadata under `path` before writing. JavaScript: **`appendMeta`** or **`addMeta(..., { mode: 'append' })`**; Python/C++: **`append_meta`** or **`add_meta`** with **`mode`** / **`overwrite`** (see SDK sections below).
+- **Prefer dictionary-style objects.** Shredded JSON metadata is keyed by field names. **Object maps** get per-field storage; when an object accumulates enough distinct field names (server default threshold **32**), XCiteDB switches automatically to **dictionary storage** (`{*}` plus per-field keys) for efficient indexed access. For lookup-heavy or wide records, use **`{ "key": value, ... }`** shapes (or one document per logical row) rather than opaque arrays when you need keyed reads.
 
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
@@ -177,8 +183,10 @@ const lock = await client.acquireLock('/manual/v1/intro');
 // ... edit ...
 await client.releaseLock('/manual/v1/intro', lock.lock_id);
 
-// Full-text search (requires Meilisearch or Elasticsearch backend)
-const results = await client.search({ query: 'installation guide', limit: 20 });
+// Full-text search (embedded XciteFTS; optional temporal filters on the query body)
+const results = await client.search({ query: 'installation guide', limit: 20, mode: 'fts' });
+// Point-in-time keyword search: { query: '...', mode: 'fts', at_date: '2024-06-01' }
+// Range overlap: { query: '...', mode: 'fts', date_from: '2024-01-01', date_to: '2025-01-01' }
 
 // Subscribe to real-time changes via WebSocket
 const sub = client.subscribe(
@@ -230,15 +238,15 @@ interface XCiteDBClientOptions {
 - `listIdentifierChildren(parentPath?)` — Navigate identifier hierarchy
 
 **JSON Documents:**
-- `writeJsonDocument(identifier, data)` — Store a JSON document
+- `writeJsonDocument(identifier, data, opts?)` — Store or merge a JSON document (`opts?.overwrite` replaces entire document root)
 - `readJsonDocument(identifier)` — Read a JSON document (generic `readJsonDocument<T>()` supported)
 - `deleteJsonDocument(identifier)` — Delete a JSON document
 - `listJsonDocuments(match?, limit?, offset?)` — List JSON document keys
 - **Quick JSON aliases:** `put`, `get`, `remove`, `list` — same as the four methods above
 
 **Metadata (JSON on XML):**
-- `addMeta(identifier, value, path?)` — Set metadata on a document
-- `appendMeta(identifier, value, path?)` — Append to metadata
+- `addMeta(identifier, value, path?, opts?)` — Set or append metadata (`opts?.mode`: `set`|`append`; `opts?.overwrite`)
+- `appendMeta(identifier, value, path?, opts?)` — Append at `path` (same as `addMeta` with `mode: 'append'`)
 - `queryMeta(identifier, path?)` — Read metadata
 - `clearMeta(query)` — Remove metadata
 
@@ -263,7 +271,7 @@ interface XCiteDBClientOptions {
 - `findLocks(identifier)` — Query active locks
 
 **Search & Analytics:**
-- `search(query)` — Full-text search
+- `search(query)` — Full-text search (embedded FTS). Optional **`at_date`**, **`date_from`**, **`date_to`** on the query for temporal keyword search (use **`mode: 'fts'`**). Hits may include **`valid_from`** / **`valid_to`** (7-char internal keys).
 - `reindex()` — Rebuild search index
 - `unquery(query, unqueryDoc)` — Execute Unquery DSL
 
@@ -338,6 +346,7 @@ async def main():
         await client.write_json_document("app.settings", {"theme": "dark"})
         print(await client.read_json_document("app.settings"))
         print(await client.search(TextSearchQuery(query="guide", limit=10)))
+        # Temporal FTS: TextSearchQuery(query="guide", mode="fts", at_date="2024-06-01")
         pair = await client.platform_login("admin@localhost", "password")
         # await client.login_app_user("user@example.com", "secret", tenant_id="...")
 
@@ -378,7 +387,7 @@ auto ids = client.query_documents(q);
 - Documents — XML document CRUD, identifiers, hierarchy
 - JSON documents — JSON document CRUD
 - Metadata — JSON metadata on documents
-- Search — Full-text search
+- Search — Full-text (embedded FTS; optional temporal `at_date` / `date_from` / `date_to`; hit `valid_from` / `valid_to`)
 - Unquery — Declarative query DSL
 - Workspaces — Isolated editing environments
 - Checkpoints & bookmarks — Named snapshots and references

package/package.json

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