@xcitedbs/client 0.2.24 → 0.2.26

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, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -509,12 +509,18 @@ export declare class XCiteDBClient {
      * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
      * For storing JSON data by key, use `writeJsonDocument`.
      *
+     * **Pruned writes:** you may include **`db:stub="true"`** (or legacy **`<db:N…/>`**) under a parent to preserve shredded children
+     * without inlining their bodies; stubs must be empty and reference an existing row (see product `llms.txt` / OpenAPI notes).
+     * Malformed hierarchical identifiers return **400** `invalid_identifier`; invalid stub/placeholder XML returns **400** `xml_write_rejected`.
+     *
      * On cooperative-lock conflict the server returns **423** with a {@link LockConflictBody} shape in {@link XCiteDBError.body}.
      */
     writeXmlDocument(xml: string, options?: WriteDocumentOptions): Promise<void>;
     /**
      * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
      * Rows with `error === 'lock_conflict'` include `current_lock` (code **423** per row).
+     * **`409`** precheck rows may include **`detail`** (`identifier` for duplicates; `parent` + `inlined_child` for parent inline).
+     * Identifiers on **`db:stub="true"`** only are batch references and do not count as inlined bodies for precheck.
      */
     writeXmlDocumentsBatch(items: XmlDocumentBatchItem[]): Promise<DocumentBatchResponse>;
     /**
@@ -534,13 +540,15 @@ export declare class XCiteDBClient {
     writeDocumentJson(xml: string, options?: WriteDocumentOptions): Promise<void>;
     queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
     /**
-     * Shallow read: root element with inline leaves plus `db:N*` placeholders for shredded child slots
-     * (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`). For sidebar / AST
-     * navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
+     * Shallow read (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`):
+     * root element with inline leaves plus **identifier-bearing stub elements** (`db:stub="true"`) for shredded
+     * child slots instead of opaque `db:N*` placeholders. Safe to round-trip with {@link writeXmlDocument}.
+     * For sidebar / AST navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
      */
     queryByIdentifierShallow(identifier: string, filter?: string, pathFilter?: string): Promise<string[]>;
     /**
      * Load a document with all shredded children inlined (`FirstMatch,IncludeChildren` on `GET /by-id`).
+     * The returned array has **length 0 or 1**; when present, index `0` is the full XML string.
      * Use this for editor round-trips. For navigation without loading the full subtree, use
      * {@link queryByIdentifierShallow} plus {@link listIdentifierChildren}.
      */
@@ -678,6 +686,8 @@ export declare class XCiteDBClient {
     headAsset(uriOrIdentifier: string, opts?: {
         ml?: string;
     }): Promise<AssetHeadResult>;
+    /** `GET /api/v1/assets` — paginated, ABAC-filtered listing. Magic-link auth is rejected by the server. */
+    listAssets(opts?: ListAssetsOptions): Promise<AssetListResponse>;
     /** Admin: GC dry-run — manifest vs live meta references (`POST /api/v1/admin/assets/gc/dry-run`). */
     adminAssetsGcDryRun(opts?: {
         ownerUserId?: string;

package/dist/client.js

@@ -1538,6 +1538,10 @@ class XCiteDBClient {
      * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
      * For storing JSON data by key, use `writeJsonDocument`.
      *
+     * **Pruned writes:** you may include **`db:stub="true"`** (or legacy **`<db:N…/>`**) under a parent to preserve shredded children
+     * without inlining their bodies; stubs must be empty and reference an existing row (see product `llms.txt` / OpenAPI notes).
+     * Malformed hierarchical identifiers return **400** `invalid_identifier`; invalid stub/placeholder XML returns **400** `xml_write_rejected`.
+     *
      * On cooperative-lock conflict the server returns **423** with a {@link LockConflictBody} shape in {@link XCiteDBError.body}.
      */
     async writeXmlDocument(xml, options) {
@@ -1550,6 +1554,8 @@ class XCiteDBClient {
     /**
      * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
      * Rows with `error === 'lock_conflict'` include `current_lock` (code **423** per row).
+     * **`409`** precheck rows may include **`detail`** (`identifier` for duplicates; `parent` + `inlined_child` for parent inline).
+     * Identifiers on **`db:stub="true"`** only are batch references and do not count as inlined bodies for precheck.
      */
     async writeXmlDocumentsBatch(items) {
         const body = {
@@ -1630,19 +1636,20 @@ class XCiteDBClient {
             filter,
             path_filter: pathFilter,
         });
-        const rows = await this.request('GET', `/api/v1/documents/by-id${q}`);
-        return Array.isArray(rows) ? rows.map((x) => this.isoUnprefixId(String(x))) : rows;
+        return this.request('GET', `/api/v1/documents/by-id${q}`);
     }
     /**
-     * Shallow read: root element with inline leaves plus `db:N*` placeholders for shredded child slots
-     * (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`). For sidebar / AST
-     * navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
+     * Shallow read (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`):
+     * root element with inline leaves plus **identifier-bearing stub elements** (`db:stub="true"`) for shredded
+     * child slots instead of opaque `db:N*` placeholders. Safe to round-trip with {@link writeXmlDocument}.
+     * For sidebar / AST navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
      */
     async queryByIdentifierShallow(identifier, filter, pathFilter) {
         return this.queryByIdentifier(identifier, 'NoChildren,KeepIndexNodes,FirstMatch', filter, pathFilter);
     }
     /**
      * Load a document with all shredded children inlined (`FirstMatch,IncludeChildren` on `GET /by-id`).
+     * The returned array has **length 0 or 1**; when present, index `0` is the full XML string.
      * Use this for editor round-trips. For navigation without loading the full subtree, use
      * {@link queryByIdentifierShallow} plus {@link listIdentifierChildren}.
      */
@@ -1674,8 +1681,7 @@ class XCiteDBClient {
         if (pq.filter_any_meta === true) {
             params.any_meta = '1';
         }
-        const rows = await this.request('GET', `/api/v1/documents${buildQuery(params)}`);
-        return Array.isArray(rows) ? rows.map((x) => this.isoUnprefixId(String(x))) : rows;
+        return this.request('GET', `/api/v1/documents${buildQuery(params)}`);
     }
     async deleteDocument(identifier) {
         await this.request('DELETE', `/api/v1/documents/by-id${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
@@ -2257,6 +2263,20 @@ class XCiteDBClient {
         this.notifySessionInvalidIfNeeded(path, 401);
         throw new types_1.XCiteDBError('Request failed after retry', 401, null);
     }
+    /** `GET /api/v1/assets` — paginated, ABAC-filtered listing. Magic-link auth is rejected by the server. */
+    async listAssets(opts) {
+        const params = {};
+        if (opts?.prefix)
+            params.prefix = opts.prefix;
+        if (typeof opts?.limit === 'number')
+            params.limit = String(opts.limit);
+        if (opts?.cursor)
+            params.cursor = opts.cursor;
+        if (opts?.includeHeader)
+            params.include_header = 'true';
+        const q = buildQuery(params);
+        return this.request('GET', `/api/v1/assets${q}`, undefined);
+    }
     /** Admin: GC dry-run — manifest vs live meta references (`POST /api/v1/admin/assets/gc/dry-run`). */
     async adminAssetsGcDryRun(opts) {
         const q = opts?.ownerUserId && opts.ownerUserId.trim()

package/dist/client.test.js

@@ -32,6 +32,28 @@ const types_js_1 = require("./types.js");
             globalThis.fetch = orig;
         }
     });
+    (0, node_test_1.it)('queryByIdentifier / queryDocuments return XML bodies unmodified under userIsolation', async () => {
+        const xml = '<?xml version="1.0"?><doc xmlns:db="http://www.xcitedb.com/schema"><a href="https://example.com//path">x</a></doc>';
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async () => {
+            return new Response(JSON.stringify([xml]), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'test-key',
+                userIsolation: { enabled: true, namespace: '/users/{userId}' },
+            });
+            c.setAppUserTokens('header.eyJzdWIiOiJ1c2VyLTEifQ.sig');
+            const a = await c.queryByIdentifier('/x');
+            strict_1.default.deepEqual(a, [xml]);
+            const b = await c.queryDocuments({ match: '/x' });
+            strict_1.default.deepEqual(b, [xml]);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
     (0, node_test_1.it)('403 becomes XCiteDBForbiddenError with policy_id and request ids', async () => {
         const orig = globalThis.fetch;
         globalThis.fetch = node_test_1.mock.fn(async () => {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { XCiteDBClient } from './client';
 export { parseAssetUri, formatAssetUri, collectIdentifiersFromText, ASSET_URI_PREFIX } from './assetUri';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError, XCiteDBForbiddenError, XCiteDBNotFoundError, XCiteDBAuthError, XCiteDBLockConflictError, } from './types';

package/dist/types.d.ts

@@ -194,6 +194,34 @@ export interface AssetHeadResult {
     size: number;
     etag?: string;
 }
+/** One row of `GET /api/v1/assets`. Header fields are present only when `include_header=true`. */
+export interface AssetListItem {
+    identifier: string;
+    uri: string;
+    content_type?: string;
+    size?: number;
+    sha256?: string;
+    etag?: string;
+    target_name?: string;
+    owner_user_id?: string;
+    created?: string;
+}
+/** `GET /api/v1/assets` paginated, ABAC-filtered. */
+export interface AssetListResponse {
+    items: AssetListItem[];
+    next_cursor: string | null;
+}
+/** Options for {@link XCiteDBClient.listAssets}. */
+export interface ListAssetsOptions {
+    /** Filter by canonical id prefix (e.g. `/users/abc/assets/`). */
+    prefix?: string;
+    /** Page size, 1..1000 (default 200). */
+    limit?: number;
+    /** Last identifier from previous page (exclusive). */
+    cursor?: string;
+    /** Include per-asset header fields (`content_type`, `size`, …). */
+    includeHeader?: boolean;
+}
 /** `POST /api/v1/admin/assets/gc/dry-run` (admin). */
 export interface AssetGcDryRunResult {
     manifest_count: number;
@@ -555,6 +583,11 @@ export interface DocumentBatchResultRow {
      */
     error?: string;
     code?: number;
+    /**
+     * Structured context for XML batch **`409`** precheck rows, e.g. `{ identifier }` for
+     * `duplicate_identifier_in_batch` or `{ parent, inlined_child }` for `parent_inlines_batch_member`.
+     */
+    detail?: Record<string, string>;
     /** Present when `error === 'lock_conflict'` (HTTP-style code 423 in batch row). */
     current_lock?: LockInfo;
 }

package/llms-full.txt

@@ -65,7 +65,7 @@ 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.
+8. **Identifier strings (minting).** The API canonicalizes hierarchical paths (**leading `/`**, **no trailing `/`**). **`POST /api/v1/documents`** rejects malformed ids with **`400`** JSON **`{ "error": "invalid_identifier", "reason", "identifier", "detail" }`**: no commas, no ASCII control characters (including **`0x01`**), no `//` or empty segments, no adjacent duplicate segments (e.g. `/a/b/b/c`). 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.
 
 ---
 
@@ -430,7 +430,7 @@ With `Content-Type: application/json`:
 
 With `Content-Type: application/xml`: send raw XML body.
 
-The identifier is extracted from the `db:identifier` attribute in the root XML element.
+The identifier is extracted from the `db:identifier` attribute in the root XML element. Malformed root identifiers return **`400`** (`invalid_identifier`). Invalid stub/placeholder XML on write returns **`400`** with `error: "xml_write_rejected"` and a `message` string.
 
 ## Get document by identifier
 
@@ -440,7 +440,8 @@ Query parameters: `identifier` (required), `flags` (optional: `FirstMatch`, `Inc
 
 ### 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).
+- **`flags=NoChildren,KeepIndexNodes,FirstMatch`**: returns the matching node with inline leaf content plus **identifier-bearing stub elements** **`db:stub="true"`** for shredded child slots (real element names; avoids loading the full deep subtree in one response). The engine still stores internal **`<db:N…/>`** placeholders on disk.
+- **`GET …/by-id`** with **`FirstMatch,IncludeChildren`** returns a JSON array of **length 0 or 1**; index `0` is the full assembled XML when present.
 - 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.
 
@@ -450,16 +451,17 @@ You may `POST /api/v1/documents` with a root element whose `db:identifier` is a
 
 ### 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.
+- **Auto-shred.** Any element with **`db:identifier`** is stored as its own LMDB row. The parent’s stored XML keeps an internal **`<db:N…/>`** placeholder for that slot (engine-only). There is **no** size threshold and **no** opt-out.
+- **Pruned writes.** Clients may send **stub** elements (**`db:stub="true"`**) or legacy **`<db:N…/>`** under a parent to preserve subtrees without inlining full XML. Stubs must be empty, reference an **existing** identifier, and must not appear at the document root; violations are **`400`** (`xml_write_rejected`).
 - **`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.
+- **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 **except** ids that appear **only** on **`db:stub="true"`** elements (references, not inlined bodies). 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 **fully inlines** another item’s **root** id in the same batch (stubs referencing another batch member are allowed).
+- **Idempotency (retries).** Re-sending the same XML with the same **`X-Date`** (or unversioned mode) is a no-op when the revision is unchanged; reuse the date key on retries.
 
 **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`**.
+**`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"?, "detail"?, "current_lock"? } ] }`** (`detail` for **`409`** precheck rows: duplicate → `{ "identifier": "<root>" }`; parent inline → `{ "parent": "<root>", "inlined_child": "<other>" }`). 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
 
@@ -487,7 +489,7 @@ async function saveDirty(items: XmlDocumentBatchItem[]) {
 }
 ```
 
-**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).
+**Batch save rules:** (1) At most **one** batch item per flush may use a given root **`db:identifier`** (`duplicate_identifier_in_batch`). (2) Do not ship a parent that **fully inlines** another item’s root id in the same batch (`parent_inlines_batch_member`); **`db:stub="true"`** references to another batch member are **allowed**. (3) **`is_top`** does not relax (1) or (2).
 
 ## Delete document
 
@@ -1583,10 +1585,10 @@ interface DatabaseContext {
 - `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`
+- `queryByIdentifierFull(identifier, filter?, pathFilter?)` → `string[]` — `FirstMatch,IncludeChildren` (editor load); array length **0 or 1**
+- `queryByIdentifierShallow(identifier, filter?, pathFilter?)` → `string[]` — `NoChildren,KeepIndexNodes,FirstMatch` (skeleton with **`db:stub="true"`** child markers)
 - `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`)
+- `writeXmlDocumentsBatch(items)` → `DocumentBatchResponse` — `POST /api/v1/documents/batch` (per-row `409` + optional **`detail`**; stubs exempt from duplicate-root / parent-inline checks per semantics above)
 - `queryDocuments(query: XCiteQuery, flags?, filter?, pathFilter?)` → `string[]`
 - `deleteDocument(identifier)` → `void`
 - `listIdentifiers(query: XCiteQuery)` → `ListIdentifiersResult`

package/llms.txt

@@ -74,7 +74,7 @@ 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.
+13. **Identifier strings (minting).** The API canonicalizes paths (**leading `/`**, **no trailing `/`**). **`POST /api/v1/documents`** rejects malformed hierarchical ids with **`400`** and JSON **`{ "error": "invalid_identifier", "reason", "identifier", "detail" }`**: no commas, no ASCII control characters (including **`0x01`** LMDB separator), no `//` or empty path segments, no **adjacent duplicate** path segments (e.g. `/a/b/b/c`). 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)
 
@@ -168,12 +168,14 @@ When you build a backend that calls XCiteDB on behalf of users:
 
 ## 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.
+- **Auto-shred.** Any element with **`db:identifier`** is stored as its own LMDB row. The parent’s stored XML keeps an internal **`<db:N…/>`** placeholder for that slot (engine-only). There is **no** size threshold and **no** opt-out.
+- **Shallow reads (`NoChildren,KeepIndexNodes`).** The API returns **identifier-bearing stubs** instead of opaque placeholders: **`<elem db:identifier="…" db:xcitepath="…" db:order="…" db:stub="true"/>`** (real element name, empty element). Clients may round-trip these stubs through **`writeXmlDocument`**; preserved subtrees are not deleted. You may also send legacy **`<db:N…/>`** placeholders from older clients; the engine resolves them under the parent’s **`db:xcitepath`**.
+- **Pruned writes.** You may mix **full** identified subtrees and **stub** markers (or placeholders) under one parent. Stubs must be **empty** (no element children, no non-whitespace text), carry **`db:identifier`** (or legacy **`identifier`**) pointing at an **existing** row, and optional **`db:order`**, **`db:xcitepath`**, **`xmlns:db`** only. The document root must not be a stub. Violations yield **`400`** with `error: "xml_write_rejected"` and a **`message`** string (`stub_*` / `placeholder_*`).
 - **`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.
+- **`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 **except** identifiers that appear only on **`db:stub="true"`** elements (those are references, not inlined document bodies). 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 **fully inlines** another item’s root id). Failed rows include a JSON **`detail`** object: for duplicates **`{ "identifier": "<root>" }`**; for parent inline **`{ "parent": "<root>", "inlined_child": "<other root>" }`**. Check **`results[i].ok`** on the JSON response.
+- **Idempotency (retries).** Re-sending the same XML body with the same **`X-Date`** (or unversioned mode) is a safe no-op when the stored revision is unchanged; use the same date key on client retries to avoid duplicate logical revisions.
 
-**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.
+**Round-trip:** Element structure, child order, and text are preserved. The server may add **`db:order`**, **`db:xcitepath`**, **`xmlns:db`**. Any app-specific structural metadata that must survive write→read (e.g. numbering aligned with an editor) must live **inside the stored XML** (or JSON metadata via **`addMeta`**); the server does not sync arbitrary sidecar fields. Attribute order and insignificant whitespace are **not** byte-stable—compare by DOM, not raw bytes.
 
 ## Minimal SPA editor recipe
 
@@ -184,7 +186,7 @@ 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')
+  // Returns JSON array length 0 or 1: when present, index 0 is one fully assembled XML string (document order).
 }
 
 /** Sidebar / tree: shallow shell + one hierarchy level (two parallel requests). */
@@ -204,7 +206,7 @@ async function saveDirty(items: XmlDocumentBatchItem[]) {
 }
 ```
 
-**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).
+**Batch save rules:** (1) Each intended root **`db:identifier`** appears as the **root** of **at most one** batch item per flush (**`duplicate_identifier_in_batch`**). (2) Do not ship a parent’s **full** subtree for a child id that is also its **own** batch row in the same request (**`parent_inlines_batch_member`**). Stubs **`db:stub="true"`** referencing another batch member are **allowed** and do not trigger (2). (3) **`is_top`** does not relax (1) or (2).
 
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
@@ -326,13 +328,13 @@ 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)
+- `writeXmlDocumentsBatch(items)` — `POST /api/v1/documents/batch`; per-row `ok` / `error` / `code` / optional `detail` (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)
+- `queryByIdentifierFull(id, filter?, pathFilter?)` — Same as `flags=FirstMatch,IncludeChildren` (editor load: full subtree). Response array is **length 0 or 1**; the single string is the full document.
+- `queryByIdentifierShallow(id, filter?, pathFilter?)` — Same as `flags=NoChildren,KeepIndexNodes,FirstMatch` (skeleton: **`db:stub="true"`** elements for shredded child 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

package/package.json

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