@xcitedbs/client 0.2.10 → 0.2.12

package/llms.txt

@@ -1,18 +1,18 @@
 # XciteDB
 
-> XciteDB is a versioned XML and JSON document database delivered as a Backend-as-a-Service (BaaS). It provides Git-like branching, commits, time-travel, and hierarchical document identifiers over a high-performance embedded LMDB engine, exposed through a REST + WebSocket API.
+> XciteDB is a versioned XML and JSON document database delivered as a Backend-as-a-Service (BaaS). It provides **temporal revisions** (every dated write is a revision), **workspaces** for isolated editing, **checkpoints** for optional named snapshots, time-travel reads, and hierarchical document identifiers over a high-performance embedded LMDB engine, exposed through a REST + WebSocket API.
 
 ## Important: Non-Standard Conventions
 
 These are the most common sources of confusion for developers and AI assistants:
 
-1. **The default branch is the empty string `""`, not `"main"`.** When no `X-Branch` header is sent (or `context.branch` is omitted/empty in the SDK), the server operates on the root timeline. A branch named `"main"` may exist as a user-created branch, but it is not required or special.
+1. **The default workspace is the empty string `""`, not `"main"`.** When no `X-Workspace` header is sent (or `context.workspace` / `context.branch` is omitted/empty in the SDK), the server operates on the root timeline. `X-Branch` is a supported alias of `X-Workspace`. A workspace named `"main"` may exist as user-created metadata, but it is not required or special.
 
 2. **Identifiers are hierarchical, path-like strings** — e.g. `/us/bills/hr1`, `/manual/v2/chapter3`. They are NOT auto-generated UUIDs. The leading `/` is part of the identifier. Parent/child relationships are derived from the path structure (like a filesystem). The server indexes this hierarchy natively.
 
 3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type, stored with structural shredding. JSON documents are a parallel store keyed by identifier string. Both are fully versioned.
 
-4. **Context (branch + date) travels as HTTP headers**, not URL path segments. Use `X-Branch` and `X-Date` headers (or the SDK `context` option) to select which branch and point-in-time you are reading/writing.
+4. **`X-Date` and temporal revision (not “only now”).** Workspace and date context travel as HTTP headers (`X-Workspace` preferred, `X-Branch` alias, `X-Date`), or the SDK `context` option — not as URL path segments. **`X-Date` is not limited to the current server time.** Pass any instant you need as **ISO 8601** (e.g. `2024-01-15T00:00:00`) or **`mm/dd/yyyy`** (optional **`:HH:MM:SS`**) — for example an **official publication or approval date**, or any historical “as of” moment. When **`X-Date` is set**, that value applies to **both** **reads** (query as-of that instant) **and** **writes** (the new revision is stored under that revision instant). When **`X-Date` is omitted** and you do **not** send **`X-Unversioned: true`**, **writes** use **flat** keys (no date suffix on that write); **reads** still resolve **as of the current time**. **`X-Unversioned: true`** requests explicit flat keys and must **not** be combined with **`X-Date`** (the server returns 400).
 
 5. **XML documents carry their identifier inside the XML** — specifically via a `db:identifier` attribute on the root element (e.g. `<chapter db:identifier="/book/ch1">...</chapter>`). When writing XML, the server extracts the identifier from the document body.
 
@@ -22,7 +22,21 @@ 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
+
+- **Write at a specific date** (law effective date, publication date, approval date): Set `context.date` / `X-Date` and write. No workspaces or checkpoints needed. Every write with a date creates a **temporal revision** automatically.
+
+- **Read historical data** (“what was the document on March 1, 2024?”): Set `context.date` / `X-Date` and read. The engine returns the revision at or before that instant.
+
+- **Isolated editing** (draft/review/publish): Create a **workspace**, make changes, then **publish** to the main timeline. Optionally create **checkpoints** for named snapshots within the workspace.
+
+- **Audit trail with named snapshots:** Create checkpoints with messages. List/inspect checkpoints for history.
+
+- **Undo a batch of changes:** **Revert** to a prior checkpoint (removes all changes after that point on the workspace).
+
+Legacy REST paths (`/api/v1/branches`, `/commits`, `/tags`, `/diff`) remain as **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
 
 ## Glossary: Project id, display name, and groups
 
@@ -44,7 +58,7 @@ These are the most common sources of confusion for developers and AI assistants:
 
 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"`.
 
@@ -54,6 +68,8 @@ These are the most common sources of confusion for developers and AI assistants:
 
 11. **Integration tests should assert token claims**, not only **`/app/auth/me`**. The profile endpoint can look fine while the JWT still carries viewer-style **`groups`**; for ABAC the token payload is authoritative. Use **`getTokenClaims()`** (JS SDK) or decode the JWT in your harness.
 
+12. **`X-Date` / `context.date` is not “server clock only.”** Revisions are keyed by the **instant you send**, not an implicit “now” when you set the header. To record a document under a **business date** (published, approved, effective), set **`X-Date`** or **`context.date`** to that instant before writing. Omitting **`X-Date`** does **not** substitute the current time on the write path — it selects **flat** writes (see convention 4).
+
 ## API key capability matrix (typical)
 
 | Capability | API key `role` | Public key allowed? |
@@ -89,11 +105,11 @@ 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-Branch` / `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.
 
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
@@ -107,15 +123,15 @@ import { XCiteDBClient } from '@xcitedbs/client';
 const client = new XCiteDBClient({
   baseUrl: 'http://localhost:8080',
   apiKey: 'your-api-key',
-  // branch: '' means root timeline (the default); omit or use '' for default
-  context: { branch: '', date: '' },
+  // workspace: '' means root timeline (the default); omit or use '' for default
+  context: { workspace: '', date: '' },
 });
 
 // Health check (no auth required)
 await client.health();
 
-// List all branches
-const branches = await client.listBranches();
+// List all workspaces
+const workspaces = await client.listWorkspaces();
 
 // Query documents by identifier prefix
 const docs = await client.queryDocuments({ match_start: '/manual/' });
@@ -140,18 +156,18 @@ const prefs = await client.get<Record<string, unknown>>('app.prefs');
 await client.remove('app.prefs');
 const keys = await client.list(undefined, 50, 0);
 
-// Branch helper: create branch, run work, commit, merge back (restores context)
-await client.withBranch('feature-x', async (c) => {
+// Workspace helper: create workspace, run work, checkpoint, publish back (restores context)
+await client.withWorkspace('feature-x', async (c) => {
   await c.writeJsonDocument('app.settings', { theme: 'light' });
   return 'ok';
 }, { message: 'Light theme', autoMerge: true, fromBranch: '' });
 
-// Create a branch, make changes, commit, merge
-await client.createBranch('feature-x');
-client.setContext({ branch: 'feature-x' });
+// Create a workspace, make changes, checkpoint, publish
+await client.createWorkspace('feature-x');
+client.setContext({ workspace: 'feature-x' });
 await client.writeJsonDocument('app.settings', { theme: 'light' });
-const commit = await client.createCommit('Switch to light theme');
-await client.mergeBranch('', 'feature-x'); // merge into root (default) branch
+const checkpoint = await client.createCheckpoint('Switch to light theme');
+await client.publishWorkspace('', 'feature-x'); // publish into root (default) workspace
 
 // Attach JSON metadata to a document
 await client.addMeta('/manual/v1/intro', { status: 'draft', owner: 'alice' });
@@ -161,8 +177,10 @@ const lock = await client.acquireLock('/manual/v1/intro');
 // ... edit ...
 await client.releaseLock('/manual/v1/intro', lock.lock_id);
 
-// Full-text search (embedded XciteFTS; enable per project in server settings)
-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(
@@ -180,8 +198,9 @@ interface XCiteDBClientOptions {
   accessToken?: string;         // Platform JWT (from platformLogin)
   appUserAccessToken?: string;  // End-user JWT (from loginAppUser)
   context?: {
-    branch?: string;   // Branch name; '' = default/root timeline
-    date?: string;     // Point-in-time (ISO-like or internal date key)
+    workspace?: string; // Workspace name; '' = default/root timeline (preferred)
+    branch?: string;    // @deprecated alias of workspace; sends X-Workspace
+    date?: string;     // X-Date: as-of reads + write revision; any ISO/mm-dd-yyyy instant, not only "now"
     prefix?: string;   // Optional identifier prefix filter
     project_id?: string; // Preferred: project id for app-user public auth (`tenant_id` on wire)
     tenant_id?: string; // Deprecated alias of project_id
@@ -200,7 +219,7 @@ interface XCiteDBClientOptions {
 - `loginAppUser(email, password)` — App end-user sign-in
 - `XCiteDBClient.buildProjectGroup(projectId, 'admin'|'editor'|'viewer')` — Static helper: canonical `project:<tenant_id>:<role>` string
 - `getTokenClaims()` — Decode current `appUserAccessToken` or `accessToken` payload (no signature verification); use for ABAC debugging
-- `setContext(ctx)` — Update branch/date context
+- `setContext(ctx)` — Update workspace/date context
 - `setProjectId(id)` — Switch active project (platform console)
 
 **XML Documents:**
@@ -225,19 +244,20 @@ interface XCiteDBClientOptions {
 - `queryMeta(identifier, path?)` — Read metadata
 - `clearMeta(query)` — Remove metadata
 
-**Versioning:**
-- `withBranch(name, fn, options?)` — Create branch, run callback on client, commit, merge back (optional `autoMerge: false`)
-- `createBranch(name, fromBranch?, fromDate?)` — Create branch
-- `listBranches()` — List all branches
-- `mergeBranch(target, source, options?)` — Merge branches
-- `deleteBranch(name)` — Delete branch
-- `createCommit(message, author?)` — Commit current state
-- `listCommits(options?)` — List commits
-- `rollbackToCommit(commitId)` — Rollback to prior commit
-- `cherryPick(commitId, message?)` — Cherry-pick a commit
-- `diff(from, to, includeContent?)` — Diff between revisions
-- `createTag(name, commitId, message?)` — Tag a commit
-- `listTags()` / `deleteTag(name)` — Manage tags
+**Versioning (workspaces & checkpoints):**
+- `withWorkspace(name, fn, options?)` — Create workspace, run callback, checkpoint, publish back (optional `autoMerge: false`; `fromBranch` = parent workspace)
+- `createWorkspace(name, fromBranch?, fromDate?)` — Create workspace
+- `listWorkspaces()` — List workspaces
+- `publishWorkspace(target, source, options?)` — Publish workspace changes to a target timeline
+- `deleteWorkspace(name)` — Delete workspace
+- `createCheckpoint(message, author?)` — Named snapshot of current state
+- `listCheckpoints(options?)` — List checkpoints
+- `revertToCheckpoint(checkpointId)` — Revert workspace to a prior checkpoint
+- `applyCheckpoint(checkpointId, message?)` — Apply another checkpoint’s changes here
+- `compare(from, to, includeContent?)` — Compare revisions
+- `createBookmark(name, checkpointId, message?)` — Bookmark a checkpoint
+- `listBookmarks()` / `deleteBookmark(name)` — Manage bookmarks
+- **Deprecated aliases:** `withBranch`, `createBranch`, `listBranches`, `mergeBranch`, `deleteBranch`, `createCommit`, `listCommits`, `rollbackToCommit`, `cherryPick`, `diff`, `createTag`, `listTags`, `deleteTag` (same HTTP behavior)
 
 **Locks:**
 - `acquireLock(identifier, expires?)` — Acquire cooperative lock
@@ -245,7 +265,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
 
@@ -260,7 +280,7 @@ interface XCiteDBClientOptions {
 ### Advanced: policy expressions (ABAC)
 
 - **Actions** (use in `policy.actions`): `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
-- **`conditions.expression`** uses the same predicate syntax as Unquery `?` filters. **Context:** `subject.id` and **`subject.user_id`** (same value for app users), `subject.email`, `subject.role`, `subject.groups`, `subject.attr.*` (app-user JSON attributes), `resource.identifier`, `resource.path` (array of path segments; indices follow non-empty `/` segments after API canonicalization, e.g. `/userdata/u1/x` → `[userdata,u1,x]`), `env.branch`. Policy **`match_start` / `match_end` / `exact`** strings are canonicalized like API identifiers (add leading `/` when omitted).
+- **`conditions.expression`** uses the same predicate syntax as Unquery `?` filters. **Context:** `subject.id` and **`subject.user_id`** (same value for app users), `subject.email`, `subject.role`, `subject.groups`, `subject.attr.*` (app-user JSON attributes), `resource.identifier`, `resource.path` (array of path segments; indices follow non-empty `/` segments after API canonicalization, e.g. `/userdata/u1/x` → `[userdata,u1,x]`), `env.branch` (workspace name; legacy name retained in policy engine). Policy **`match_start` / `match_end` / `exact`** strings are canonicalized like API identifiers (add leading `/` when omitted).
 - **Operators:** `=`, `!=`, `>=`, `<=`, `>`, `<`, `in`, `contains`, `starts_with`, `ends_with`, `&`, `|`, `!`, `+` (string concat), postfix `!` (exists).
 - **Examples:** `resource.path[0] = subject.attr.tenant_code` — tenant isolation; `subject.attr.level >= 5` — numeric attribute gate.
 
@@ -269,7 +289,7 @@ interface XCiteDBClientOptions {
 - **Events:** `meta_changed`, `document_written`, `document_deleted`.
 - **`match`:** required non-empty **`identifiers`** (same pattern objects as policy `resources.identifiers`); optional **`match_meta_path`** (exact or `prefix*`); optional **`match_operation`:** `set` | `append` | `delete`.
 - **`action`:** **`query`** (document query), **`unquery`** (Unquery template), **`target_identifier`** (or `"$trigger_identifier"`), **`meta_path`**, **`mode`:** `set` | `append`.
-- **Unquery vars:** `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`. **Trigger `conditions.expression` context:** `trigger.{event,meta_path,operation}`, `value`, `resource`, `env.branch` (no `subject`).
+- **Unquery vars:** `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`. **Trigger `conditions.expression` context:** `trigger.{event,meta_path,operation}`, `value`, `resource`, `env.branch` (workspace; no `subject`).
 
 ### Advanced: Unquery DSL (`unquery(query, unqueryDoc)`)
 
@@ -312,7 +332,7 @@ async def main():
     async with XCiteDBClient(
         "http://localhost:8080",
         api_key="your-key",
-        context=DatabaseContext(branch="", date=""),
+        context=DatabaseContext(workspace="", date=""),
     ) as client:
         print(await client.health())
         ids = await client.query_documents(XCiteQuery(match_start="/manual/"))
@@ -320,6 +340,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="...")
 
@@ -334,7 +355,7 @@ asyncio.run(main())
 xcitedb::XCiteDBClientOptions opt;
 opt.base_url = "http://127.0.0.1:8080";
 opt.api_key = "your-key";
-opt.context.branch = "";  // root timeline
+opt.context.workspace = "";  // root timeline (branch is deprecated alias)
 
 xcitedb::XCiteDBClient client(opt);
 auto health = client.health();
@@ -347,9 +368,9 @@ auto ids = client.query_documents(q);
 
 - **Multi-tenant**: Each project is an isolated tenant with its own data, users, keys, and policies.
 - **LMDB engine**: Data is memory-mapped; reads are microsecond-class on warm data.
-- **Versioning**: Every write is versioned. Branches isolate work. Commits snapshot state. Time-travel reads any historical state via `X-Date`.
+- **Versioning**: **Temporal revisions** are always on when using dates. **Workspaces** isolate draft work; **checkpoints** are optional named snapshots; **publish** merges a workspace into a target timeline. **`X-Date`** selects an instant for **as-of reads** and, when set, for **writes** under that revision (any calendar time you choose — e.g. publication date — not only “now”). Omit **`X-Date`** for **flat** writes on that request, or use **`X-Unversioned: true`** to state that explicitly.
 - **Two user tiers**: Platform operators manage infrastructure; App users are end-users of applications built on XciteDB.
-- **Security policies (ABAC)**: Fine-grained allow/deny rules on actions, resources, roles, and branches.
+- **Security policies (ABAC)**: Fine-grained allow/deny rules on actions, resources, roles, and workspaces (`env.branch` in expressions).
 - **WebSocket**: Real-time notifications for document changes at `/api/v1/ws`.
 
 ## Documentation
@@ -360,10 +381,10 @@ 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
-- Branches — Branch management
-- Commits & tags — Version snapshots
+- Workspaces — Isolated editing environments
+- Checkpoints & bookmarks — Named snapshots and references
 - Locks — Cooperative editing locks
 - Authentication — JWT, API keys, platform vs app users
 - Security policies — ABAC access control

package/package.json

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