@xcitedbs/client 0.2.21 → 0.2.24

package/dist/types.d.ts

@@ -170,6 +170,125 @@ export interface ProjectDocConfResponse {
     has_project_override: boolean;
     doc_conf_text: string | null;
 }
+/** `POST /api/v1/assets` success body (`201`). */
+export interface AssetUploadResult {
+    identifier: string;
+    uri: string;
+    target_name?: string;
+    content_type?: string;
+    size?: number;
+    sha256?: string;
+    etag?: string;
+}
+/** Options for {@link XCiteDBClient.uploadAsset}. */
+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';
+}
+/** Result of {@link XCiteDBClient.headAsset}. */
+export interface AssetHeadResult {
+    contentType: string;
+    size: number;
+    etag?: string;
+}
+/** `POST /api/v1/admin/assets/gc/dry-run` (admin). */
+export interface AssetGcDryRunResult {
+    manifest_count: number;
+    referenced_asset_count: number;
+    orphan_count: number;
+    orphan_sample: string[];
+}
+export type AssetStorageTargetType = 'internal' | 's3';
+/** One named storage target in `asset_storage_v2` (`GET/PUT /api/v1/project/settings/asset-storage`). */
+export interface AssetStorageTarget {
+    type: AssetStorageTargetType;
+    writable?: boolean;
+    s3_endpoint_url?: string;
+    s3_bucket?: string;
+    s3_region?: string;
+    access_key_id?: string;
+    /** On GET, redacted as `***` when set. */
+    secret_access_key?: string;
+    small_file_threshold_bytes?: number;
+    redirect_threshold_bytes?: number;
+    import_head_cache_ttl_seconds?: number;
+    [key: string]: unknown;
+}
+export interface AssetStorageMount {
+    path: string;
+    target: string;
+    key_template: string;
+}
+export interface AssetStorageImport {
+    path: string;
+    target: string;
+    key: string;
+    tree?: boolean;
+    content_type?: string;
+}
+/** Project asset storage v2 (`GET/PUT /api/v1/project/settings/asset-storage`). */
+export interface ProjectAssetStorageConfig {
+    targets: Record<string, AssetStorageTarget>;
+    mounts: AssetStorageMount[];
+    imports: AssetStorageImport[];
+}
+/** Body for `POST /api/v1/security/user-isolation/asset-shares`. */
+export interface AssetShareRequest {
+    /** Canonical or app-relative asset path (subject to user-isolation prefixing when enabled). */
+    identifier?: string;
+    /** `xcitedb:asset:/…` or raw `/…` path; not prefixed by the client. */
+    source_uri?: string;
+    target_user_id: string;
+    mode: UserIsolationShareMode;
+}
+/** Body for `DELETE /api/v1/security/user-isolation/asset-shares`. */
+export interface AssetUnshareRequest {
+    identifier?: string;
+    source_uri?: string;
+    target_user_id?: string;
+    sharer_user_id?: string;
+}
+export interface AssetShareListEntry {
+    identifier: string;
+    mode: string;
+}
+/** `GET /api/v1/security/user-isolation/asset-shares` */
+export interface AssetShareListResponse {
+    direction: string;
+    identifiers: AssetShareListEntry[];
+    scope?: string;
+    note?: string;
+}
+/** `POST /api/v1/security/asset-magic-links` */
+export interface CreateAssetMagicLinkRequest {
+    source_uri: string;
+    actions: ('read' | 'write')[];
+    expires_in_seconds: number;
+    max_uses?: number;
+}
+export interface AssetMagicLinkResult {
+    token: string;
+    token_id?: string;
+    expires_at: string;
+    link_url: string;
+}
+export interface AssetMagicLinkRecord {
+    token_id: string;
+    identifier: string;
+    actions?: unknown;
+    issued_by_user_id?: string;
+    issued_at?: string;
+    expires_at?: string;
+    max_uses?: number;
+    uses?: number;
+    revoked?: boolean;
+}
+export interface AssetMagicLinkListResponse {
+    tokens: AssetMagicLinkRecord[];
+}
 /** `GET /api/v1/platform/default-doc-conf` */
 export interface PlatformDefaultDocConfResponse {
     doc_conf_text: string;
@@ -399,11 +518,41 @@ export interface WriteDocumentOptions {
     is_top?: boolean;
     compare_attributes?: boolean;
 }
+/** Supported source formats for `POST /api/v1/documents/import` (server detects from bytes / filename). */
+export type DocumentImportFormat = 'docx' | 'odt' | 'rtf' | 'pdf' | 'txt' | 'md' | 'adoc';
+/** JSON body on successful import (`201 Created`). */
+export interface ImportDocumentResult {
+    identifier: string;
+    section_count: number;
+    source_format: string;
+}
+export interface ImportDocumentOptions {
+    /** Override root `db:identifier`; default is `/imported/<sanitized-filename>`. */
+    identifier?: string;
+    /** Original filename (helps sniff format when `File` is not available, e.g. Node `Blob` only). */
+    filename?: string;
+}
+/** `GET /api/v1/documents/export?format=…` */
+export type DocumentExportFormat = 'xml' | 'docx' | 'odt' | 'pdf' | 'txt' | 'md' | 'adoc';
+export interface ExportDocumentResult {
+    bytes: Uint8Array;
+    contentType: string;
+    filename: string;
+    /** Present for txt/md/adoc when server sends `X-XciteDB-Export-RoundTrip`. */
+    roundTrip?: 'exact' | 'lossy';
+    /** From `X-XciteDB-Export-Warning` when present. */
+    warning?: string;
+}
 /** One row in `POST /api/v1/documents/batch` or `POST /api/v1/json-documents/batch` response `results`. */
 export interface DocumentBatchResultRow {
     index: number;
     identifier: string;
     ok: boolean;
+    /**
+     * When `ok` is false, server batch precheck / write reason. Includes:
+     * `duplicate_identifier_in_batch` (409), `parent_inlines_batch_member` (409),
+     * `lock_conflict` (423), and other parse/policy strings.
+     */
     error?: string;
     code?: number;
     /** Present when `error === 'lock_conflict'` (HTTP-style code 423 in batch row). */
@@ -835,6 +984,8 @@ export interface CompareResult {
         date_key?: string;
     };
     total_changes: number;
+    /** Echo of request `match_start` when path-scoped compare was used. */
+    match_start?: string;
 }
 /** @deprecated Use {@link CompareResult}. */
 export type DiffResult = CompareResult;
@@ -857,6 +1008,16 @@ export interface PublishResult {
 }
 /** @deprecated Use {@link PublishResult}. */
 export type MergeResult = PublishResult;
+/** `POST /api/v1/user-workspaces/{id}/rebase` */
+export interface RebaseUserWorkspaceResult {
+    status: 'completed' | 'conflicts';
+    message?: string;
+    old_from_date_key?: string;
+    new_from_date_key?: string;
+    conflicts?: PublishConflict[];
+    auto_mergeable?: string[];
+    would_expose?: string[];
+}
 export type XCiteDBErrorExtras = {
     reason?: string;
     policyId?: string;

package/llms-full.txt

@@ -12,7 +12,7 @@ Before reading the full reference, note these critical differences from typical
 
 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.
 
-3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type. JSON documents are a parallel store. Both are fully versioned.
+3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type. JSON documents are a parallel store. Both are fully versioned. **Binary files** use the separate **assets** subsystem (not document shredding): canonical paths like `/assets/<uuid>`, stable **`xcitedb:asset:/…`** URIs, **`POST` / `GET` / `HEAD` / `DELETE /api/v1/assets/…`**, project **`asset-storage` v2** config, optional user-isolation **asset-shares**, and **asset magic links** (`?ml=`).
 
 4. **Context (workspace + date) travels as HTTP headers** (`X-Workspace` preferred, `X-Branch` alias, `X-Date`, and optionally `X-Unversioned` for explicit flat writes), not URL path segments.
 
@@ -28,14 +28,16 @@ Before reading the full reference, note these critical differences from typical
 
 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`**.
+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`**. **Locks:** cooperative lock metadata is read from the **base** layer as well as the overlay, but lock acquire/release only affects the overlay—so **`lock_conflict`** during overlay tests can reflect a lock still held in production; use **`findLocks` / `forceReleaseLock`** on your paths or a non-overlay session when testing locks.
+
+12. **SDK asset helpers.** JavaScript: `uploadAsset`, `getAsset`, `headAsset`, `deleteAsset`, `resolveAssetIdentifier`, `formatAssetUri`, `collectIdentifiersFromText`, plus `createAssetShare` / `createAssetMagicLink` and related APIs. Python: `upload_asset`, `get_asset`, `head_asset`, `xcitedb.asset_uri`. C++: `xcitedb/asset_uri.hpp`, `XCiteDBClient::upload_asset`, `get_asset_raw`, `head_asset_raw`, `delete_asset`, and security helpers mirroring the other SDKs.
 
 ## Choosing the Right Versioning Approach
 
 - **Write at a specific date:** Set `X-Date` / `context.date` and write — every dated write is a **temporal revision**; no workspace or checkpoint required.
 - **Read as-of a date:** Set `X-Date` and read; the engine returns the revision at or before that instant.
 - **Isolated editing (draft → publish):** Create a **workspace**, edit, then **publish** to the target timeline; optional **checkpoints** for named snapshots.
-- **App-user user workspaces (`_uw/<owner>/<slug>`):** **`GET/POST /api/v1/user-workspaces`**, grants, publish — see repository **`web/src/docs/content/user-workspaces.md`**.
+- **App-user user workspaces (`_uw/<owner>/<slug>`):** **`GET/POST /api/v1/user-workspaces`**, grants, publish, **rebase** — see repository **`web/src/docs/content/user-workspaces.md`**.
 - **Audit trail:** Checkpoints carry messages and affected identifiers; **bookmarks** name a checkpoint.
 - **Undo a batch:** **Revert** to a prior checkpoint on that workspace.
 
@@ -63,6 +65,8 @@ Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain
 
 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.
 
+8. **Identifier strings (minting).** The engine rejects identifiers containing byte **`0x01`**. The API canonicalizes hierarchical paths (**leading `/`**, **no trailing `/`**). Reserved namespaces include **`/_xcitedb/`**, **`/assets/`**, **`/public/assets/`**, and **`/public/shared/<tenant>/assets/`**. **`identifier_hierarchy_max_depth`** (default **4**) tunes hierarchy indexing; deeper paths still work but **`GET …/identifier-children`** may scan.
+
 ---
 
 # Part 1: Product Overview
@@ -434,6 +438,57 @@ The identifier is extracted from the `db:identifier` attribute in the root XML e
 
 Query parameters: `identifier` (required), `flags` (optional: `FirstMatch`, `IncludeChildren`, `NoChildren`, `KeepIndexNodes`), `filter`, `path_filter`.
 
+### Shallow node + subtree navigation
+
+- **`flags=NoChildren,KeepIndexNodes,FirstMatch`**: returns the matching node with inline leaf content plus **`db:N1`**, **`db:N2`**, … placeholders for shredded child slots (avoids loading the full deep subtree in one response).
+- Combine with **`GET /api/v1/documents/identifier-children?parent_path=…`** for the next level of hierarchy (`segment`, `full_path`, `is_identifier`, `has_children`).
+- **JavaScript SDK:** `queryByIdentifierFull(id)` loads **`FirstMatch,IncludeChildren`** for editor round-trips; **`queryByIdentifierShallow(id)`** + **`listChildIdentifiers(id)`** (e.g. `Promise.all` client-side) for sidebar / tree expansion.
+
+### Standalone subtree write (shredded model)
+
+You may `POST /api/v1/documents` with a root element whose `db:identifier` is a nested path (e.g. `/spaces/u/docs/doc1/sec-1`) without re-posting the parent document: the engine writes that subtree only and updates the identifier hierarchy index for the parent automatically. Keep `is_top: true` (default) on the write.
+
+### XML shredding semantics (must read)
+
+- **Auto-shred.** Any element with **`db:identifier`** is stored as its own LMDB row. The parent’s stored XML keeps a **`<db:N…/>`** placeholder for that slot. There is **no** size threshold and **no** opt-out.
+- **`is_top` is a marker only.** It registers a **`TOP:<xcitepath>`** alias for tooling; it does **not** change shredding, merge, or overwrite behavior.
+- **Batch ordering.** **`POST /api/v1/documents/batch`** processes **`items[]`** **sequentially**. Each item’s XML is shredded so **every** `db:identifier` in that payload becomes (or overwrites) its own row. Precheck returns per-row **`409`**: **`duplicate_identifier_in_batch`** when the same canonical root id appears in more than one item (the **later** row is rejected), and **`parent_inlines_batch_member`** when one item’s XML still contains **full** markup for another item’s **root** id in the same batch (prevents silently overwriting a fresher child row with a stale parent).
+- **Save the smallest dirty subtree.** Do not include live descendant XML for ids you also flush as standalone batch rows; use placeholders from a shallow read when you must touch the parent in the same request.
+
+**Round-trip:** Element structure, child order, and text are preserved. The server may add **`db:order`**, **`db:xcitepath`**, **`xmlns:db`**. Attribute order and insignificant whitespace are **not** byte-stable—compare by DOM, not raw bytes.
+
+### Batch XML writes
+
+**`POST /api/v1/documents/batch`** — JSON body **`{ "items": [ { "xml": "<…>", "is_top": true, "compare_attributes": false, "identifier": "/optional/match" }, … ] }`**. Response **`200`** with **`{ "results": [ { "index", "ok", "identifier", "error"?, "code"?, "current_lock"? } ] }`** (best-effort: later rows still run when earlier rows fail). JavaScript: **`writeXmlDocumentsBatch`**. Python: **`write_xml_documents_batch`**. C++: **`write_xml_documents_batch`**.
+
+### Minimal SPA editor recipe
+
+```typescript
+await client.enableUserIsolation();
+client.setContext({ workspace: '', project_id: projectId });
+
+async function loadDocForEditor(id: string) {
+  return client.queryByIdentifierFull(id);
+}
+
+async function sidebarRow(id: string) {
+  const [node, listed] = await Promise.all([
+    client.queryByIdentifierShallow(id),
+    client.listIdentifierChildren(id),
+  ]);
+  return { node, children: listed.children };
+}
+
+async function saveDirty(items: XmlDocumentBatchItem[]) {
+  const { results } = await client.writeXmlDocumentsBatch(items);
+  results.forEach((r, i) => {
+    if (!r.ok) console.warn(i, r.error, r.code);
+  });
+}
+```
+
+**Save rules:** (1) At most **one** batch item per flush may use a given root **`db:identifier`**. (2) Never ship a parent that **inlines** another item’s root id in the same batch. (3) **`is_top`** does not relax (1) or (2).
+
 ## Delete document
 
 **`DELETE /api/v1/documents/by-id?identifier=/book/ch1`**
@@ -526,7 +581,7 @@ Returns `{ identifiers: string[], total, offset, limit }`.
 
 ## Export document
 
-**`GET /api/v1/documents/export?id=/book/ch1&format=...`**
+**`GET /api/v1/documents/export?identifier=/book/ch1&format=...`**
 
 ## Export provision
 
@@ -847,6 +902,22 @@ Returns `{ status: "completed"|"conflicts", checkpoint?, commit?, merged_identif
 
 ---
 
+# App-user workspaces (`/api/v1/user-workspaces`)
+
+Per-user draft branches (`_uw/<owner>/<slug>`). See also **`web/src/docs/content/user-workspaces.md`**.
+
+## Rebase user workspace
+
+**`POST /api/v1/user-workspaces/{id}/rebase`**
+
+```json
+{ "auto_resolve": "none" }
+```
+
+Advances the workspace branch fork metadata to the **current tip** of its parent branch. Returns **`200`** with `{ status: "completed", message?, old_from_date_key, new_from_date_key, would_expose[], auto_mergeable[], conflicts: [] }`, or **`409`** with `{ status: "conflicts", conflicts: [...], auto_mergeable?, would_expose? }` when the same identifiers changed on both parent and workspace since the fork (same conflict shape as workspace publish).
+
+---
+
 # Checkpoints, bookmarks & compare
 
 ## Create checkpoint
@@ -896,13 +967,16 @@ Returns `{ checkpoints: [...], commits: [...], total, branch }` (mirrors).
 {
   "from": { "branch": "", "date": "2024-01-15T00:00:00" },
   "to": { "branch": "feature-x" },
-  "include_content": true
+  "include_content": true,
+  "match_start": "/spaces/u/docs/doc1"
 }
 ```
 
+Optional **`match_start`**: when set, only identifiers equal to that path or under it (prefix + `/`) are included in **`changes`** (tenant-wide noise is dropped).
+
 (Deprecated: **`POST /api/v1/diff`**; `date_key` still accepted internally but prefer **`date`**.)
 
-Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_content?, to_content? }], total_changes }`.
+Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_content?, to_content? }], total_changes, match_start? }` ( **`match_start`** echoed when the filter was used).
 
 ---
 
@@ -1506,7 +1580,13 @@ interface DatabaseContext {
 ### XML Documents
 - `writeXmlDocument(xml, options?)` → `void` — XML via JSON body (recommended). Deprecated: `writeDocumentJson`.
 - `writeXML(xml)` → `void` — Raw XML body
+- `importDocument(file, options?)` → `ImportDocumentResult` — multipart `POST /api/v1/documents/import`
+- `exportDocument(identifier, format?, options?)` → `ExportDocumentResult` — binary `GET /api/v1/documents/export`
 - `queryByIdentifier(identifier, flags?, filter?, pathFilter?)` → `string[]`
+- `queryByIdentifierFull(identifier, filter?, pathFilter?)` → `string[]` — `FirstMatch,IncludeChildren` (editor load)
+- `queryByIdentifierShallow(identifier, filter?, pathFilter?)` → `string[]` — `NoChildren,KeepIndexNodes,FirstMatch`
+- `listChildIdentifiers(parentPath?)` → `ListIdentifierChildrenResult` — alias of `listIdentifierChildren`
+- `writeXmlDocumentsBatch(items)` → `DocumentBatchResponse` — `POST /api/v1/documents/batch` (per-row `409`: `duplicate_identifier_in_batch`, `parent_inlines_batch_member`)
 - `queryDocuments(query: XCiteQuery, flags?, filter?, pathFilter?)` → `string[]`
 - `deleteDocument(identifier)` → `void`
 - `listIdentifiers(query: XCiteQuery)` → `ListIdentifiersResult`
@@ -1544,6 +1624,13 @@ interface DatabaseContext {
 - `publishWorkspace(targetWorkspace, sourceWorkspace, options?)` → `PublishResult`
 - **Deprecated:** `withBranch`, `createBranch`, `listBranches`, `getBranch`, `deleteBranch`, `mergeBranch` (same HTTP behavior)
 
+### App-user user workspaces (`_uw/…`)
+- `listUserWorkspaces()` → `{ user_workspaces: unknown[] }`
+- `createUserWorkspace(name, options?)` → `Record<string, unknown>`
+- `getUserWorkspace(id)` / `deleteUserWorkspace(id)` / `addUserWorkspaceGrant(id, body)` / `removeUserWorkspaceGrant(id, body)`
+- `publishUserWorkspace(id, options?)` → `PublishResult`-shaped JSON
+- `rebaseUserWorkspace(id, options?)` → `RebaseUserWorkspaceResult` — advances fork onto parent tip; **409** + `conflicts` on overlap (optional `autoResolve`: `none` | `source` | `target`)
+
 ### Checkpoints
 - `createCheckpoint(message, author?)` → `CheckpointRecord`
 - `listCheckpoints(options?)` → `{ checkpoints, total, branch }` (wire JSON may also include `commits` mirror)
@@ -1560,7 +1647,7 @@ interface DatabaseContext {
 - **Deprecated:** `createTag`, `listTags`, `getTag`, `deleteTag`
 
 ### Compare
-- `compare(from: CompareRef, to: CompareRef, includeContent?)` → `CompareResult`
+- `compare(from: CompareRef, to: CompareRef, includeContent?)` or `compare(from, to, { includeContent?, matchStart? })` → `CompareResult`
 - **Deprecated:** `diff(from: DiffRef, …)` — alias of `compare`
 
 ### Locks

package/llms.txt

@@ -22,7 +22,9 @@ 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). 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).
+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). **Overlay + locks:** cooperative locks are stored in LMDB meta; overlay sessions **read through** to **base-layer** locks, but **`acquireLock` / `releaseLock`** only mutate the overlay—so a `lock_conflict` in an overlay test can still mean a lock held in production; clear with **`findLocks`** / **`forceReleaseLock`** or use a non-overlay session for lock-sensitive tests.
+
+10. **Binary assets (v2) are not XML/JSON documents.** Files live under canonical asset identifiers (e.g. `/assets/<uuid>`) and stable **`xcitedb:asset:/…`** URIs. **`POST /api/v1/assets`** uploads raw bytes; **`GET` / `HEAD` / `DELETE /api/v1/assets/…`** use per-segment URL encoding (optional **`?ml=`** magic-link bearer). Project routing is **`GET/PUT /api/v1/project/settings/asset-storage`** (`targets`, `mounts`, `imports`). User-isolation **asset-shares** and **asset magic links** live under **`/api/v1/security/user-isolation/asset-shares`** and **`/api/v1/security/asset-magic-links`**. JS/Python/C++ SDKs expose upload/get/head/delete + URI helpers (`parseAssetUri`, `asset_uri.parse`, `asset_uri::parse`) and share/magic-link clients.
 
 ## Choosing the Right Versioning Approach
 
@@ -72,6 +74,8 @@ Legacy REST paths (`/api/v1/branches`, `/commits`, `/tags`, `/diff`) remain as *
 
 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).
 
+13. **Identifier strings (minting).** The engine rejects identifiers containing byte **`0x01`** (LMDB key separator). The API canonicalizes paths (**leading `/`**, **no trailing `/`**). Reserved namespaces include **`/_xcitedb/`**, **`/assets/`**, **`/public/assets/`**, and **`/public/shared/<tenant>/assets/`**. Server config **`identifier_hierarchy_max_depth`** defaults to **4**—deeper paths still work, but **`identifier-children`** listing may fall back to a scan.
+
 ## API key capability matrix (typical)
 
 | Capability | API key `role` | Public key allowed? |
@@ -158,6 +162,50 @@ When you build a backend that calls XCiteDB on behalf of users:
 - **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 stored in **fragment-level** keys (e.g. per field name). **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.
 
+## XML subtree writes (shredded model)
+
+- **Standalone subtree root.** Because XCiteDB shreds XML per identifier, you can `writeXmlDocument('<sec db:identifier="/spaces/u/docs/doc1/sec-1">…</sec>')` and the engine writes only that subtree — you do **not** need to re-send the parent document. The parent's children index (`id_hier`) is updated automatically. Keep `is_top: true` (default) on `POST /api/v1/documents` even when the `db:identifier` is nested under another path. Use `compare_attributes: true` only when you need attribute-level diffing for triggers.
+
+## XML shredding semantics (must read)
+
+- **Auto-shred.** Any element with **`db:identifier`** is stored as its own LMDB row. The parent’s stored XML keeps a **`<db:N…/>`** placeholder for that slot. There is **no** size threshold and **no** opt-out.
+- **`is_top` is a marker only.** It registers a **`TOP:<xcitepath>`** alias for tooling; it does **not** change shredding, merge, or overwrite behavior. Leaving **`true`** on every write is normal.
+- **`POST /api/v1/documents/batch`** runs items **in order**; each item’s write replaces LMDB rows for **every** `db:identifier` present in that item’s XML. The server prechecks each row and may return **`409`** with **`duplicate_identifier_in_batch`** (same root id in two items) or **`parent_inlines_batch_member`** (a parent’s XML still contains another item’s root id—a stale inlined child). Check **`results[i].ok`** on the JSON response.
+- **Save the smallest dirty subtree.** Do not flush a parent that still contains full XML for an identified child you also write in the same batch. Prefer placeholders from **`queryByIdentifierShallow`**, or write only the changed child documents.
+
+**Round-trip:** Element structure, child order, and text are preserved. The server may add **`db:order`**, **`db:xcitepath`**, **`xmlns:db`**. Attribute order and insignificant whitespace are **not** byte-stable—compare by DOM, not raw bytes.
+
+## Minimal SPA editor recipe
+
+```typescript
+await client.enableUserIsolation(); // if app users edit under namespaced paths
+client.setContext({ workspace: '', project_id: projectId });
+
+/** Full document for the editor (all shredded children inlined). */
+async function loadDocForEditor(id: string) {
+  return client.queryByIdentifierFull(id);
+  // same as: queryByIdentifier(id, 'FirstMatch,IncludeChildren')
+}
+
+/** Sidebar / tree: shallow shell + one hierarchy level (two parallel requests). */
+async function sidebarRow(id: string) {
+  const [node, listed] = await Promise.all([
+    client.queryByIdentifierShallow(id),
+    client.listIdentifierChildren(id),
+  ]);
+  return { node, children: listed.children };
+}
+
+async function saveDirty(items: XmlDocumentBatchItem[]) {
+  const { results } = await client.writeXmlDocumentsBatch(items);
+  results.forEach((r, i) => {
+    if (!r.ok) console.warn(i, r.error, r.code);
+  });
+}
+```
+
+**Three save rules:** (1) Each intended root **`db:identifier`** appears as the **root** of **at most one** batch item per flush. (2) Never ship a parent’s **full** subtree for a child id that is also its **own** batch row in the same request. (3) **`is_top`** does not relax (1) or (2).
+
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
@@ -191,6 +239,11 @@ await client.writeXmlDocument(
   '<chapter db:identifier="/manual/v1/intro"><title>Introduction</title></chapter>'
 );
 
+// Import DOCX/PDF (etc.) server-side — shredded into XML (`POST /api/v1/documents/import`, multipart field `file`)
+// const fileBlob = …; // Blob from <input type="file"> or fetch
+// await client.importDocument(fileBlob, { identifier: '/manual/imported/spec', filename: 'spec.docx' });
+// const out = await client.exportDocument('/manual/imported/spec', 'docx'); // bytes in `out.bytes`
+
 // Write a JSON document
 await client.writeJsonDocument('app.settings', { theme: 'dark', locale: 'en' });
 
@@ -273,8 +326,14 @@ interface XCiteDBClientOptions {
 
 **XML Documents:**
 - `writeXmlDocument(xml, options?)` — Store XML via JSON body (identifier inside XML). Deprecated alias: `writeDocumentJson`.
+- `writeXmlDocumentsBatch(items)` — `POST /api/v1/documents/batch`; per-row `ok` / `error` / `code` (see shredding section for `409` batch conflicts)
 - `writeXML(xml)` — Store raw XML with `Content-Type: application/xml`
+- `importDocument(file, options?)` — `POST /api/v1/documents/import` (multipart `file`). Server converts DOCX, ODF, RTF, PDF, Markdown, AsciiDoc, or plain text into shredded XML. Optional `identifier` query override; optional `filename` for sniffing when not a `File`.
+- `exportDocument(id, format?, options?)` — `GET /api/v1/documents/export` binary (`xml` | `docx` | `odt` | `pdf` | `txt` | `md` | `adoc`). Optional `strict` for text exports.
 - `queryByIdentifier(id, flags?, filter?)` — Get document(s) by identifier
+- `queryByIdentifierFull(id, filter?, pathFilter?)` — Same as `flags=FirstMatch,IncludeChildren` (editor load: full subtree)
+- `queryByIdentifierShallow(id, filter?, pathFilter?)` — Same as `flags=NoChildren,KeepIndexNodes,FirstMatch` (skeleton: placeholders `db:N*` for shredded slots; avoids full subtree)
+- `listChildIdentifiers(parentPath?)` — Alias of `listIdentifierChildren`; next level of identifier hierarchy (pair with `queryByIdentifierShallow` for sidebars—`Promise.all` both if you want one round-trip client-side)
 - `queryDocuments(query, flags?)` — List/filter documents
 - `deleteDocument(identifier)` — Delete by identifier
 - `listIdentifiers(query)` — List known identifiers with pagination
@@ -299,12 +358,12 @@ interface XCiteDBClientOptions {
 - `listWorkspaces()` — List workspaces
 - `publishWorkspace(target, source, options?)` — Publish workspace changes to a target timeline
 - `deleteWorkspace(name)` — Delete workspace
-- `listUserWorkspaces()` / `createUserWorkspace(name, options?)` / `getUserWorkspace(id)` / `deleteUserWorkspace(id)` / `addUserWorkspaceGrant(id, body)` / `removeUserWorkspaceGrant(id, body)` / `publishUserWorkspace(id, options?)` — App-user **`_uw/…`** workspaces
+- `listUserWorkspaces()` / `createUserWorkspace(name, options?)` / `getUserWorkspace(id)` / `deleteUserWorkspace(id)` / `addUserWorkspaceGrant(id, body)` / `removeUserWorkspaceGrant(id, body)` / `publishUserWorkspace(id, options?)` / `rebaseUserWorkspace(id, options?)` — App-user **`_uw/…`** workspaces (`rebase` advances the fork onto the parent tip; **409** + `conflicts` on overlap, like publish)
 - `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
+- `compare(from, to, includeContent?)` or `compare(from, to, { includeContent?, matchStart? })` — Compare revisions; optional **`matchStart`** restricts results to that identifier and descendants (same as document `match_start` query semantics)
 - `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)
@@ -369,6 +428,8 @@ When calling `queryByIdentifier` or `queryDocuments`, the `flags` parameter cont
 - `'NoChildren'` — Exclude children
 - `'KeepIndexNodes'` — Include index/structural nodes
 
+**Sidebar / AST navigation:** combine **`'NoChildren,KeepIndexNodes,FirstMatch'`** (or `queryByIdentifierShallow`) with **`listChildIdentifiers`** / **`listIdentifierChildren`** so each expansion is one shallow XML read plus one child list, instead of `IncludeChildren` loading the entire subtree.
+
 ### Errors
 
 All API errors throw `XCiteDBError` with `.status` (HTTP code) and `.body` (parsed response). Common codes: `401` unauthenticated, `403` forbidden by policy or RBAC, `404` not found, `409` conflict (lock), `422` validation, `423` project encrypted and locked, `429` rate limited. Many **ABAC** denials return `403` with `"message":"Forbidden"` plus optional **`policy_id`** and **`hint`** (check JWT `tenant_id` vs `project:` group middle segment).

package/package.json

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

package/unquery-ai-guide.md

@@ -4,6 +4,8 @@
 
 Unquery is a declarative language for querying and transforming structured documents (JSON and XML). It is the query language of XCiteDB and the `unq` command-line tool. Every query is itself a JSON document. The result is also JSON.
 
+> **Maintainers — parse regression tests:** Fenced `json` / `text` examples in this file, plus Unquery listings in [`web/src/docs/content/unquery-tutorial.html`](../web/src/docs/content/unquery-tutorial.html), feed the generated fixture [`XCiteDB2/tests/fixtures/unquery_tutorial_parse_cases.json`](../XCiteDB2/tests/fixtures/unquery_tutorial_parse_cases.json) (do not edit by hand). After changing examples here or in that HTML file, regenerate from the repo root with `python3 scripts/gen_unquery_tutorial_parse_cases.py`, then commit the updated JSON. CI / local builds run `unquery_tutorial_parse_test` (see [`XCiteDB2/tests/run_tests.sh`](../XCiteDB2/tests/run_tests.sh)).
+
 ---
 
 ## 0. AI preamble — must-read before writing a query