@xcitedbs/client 0.2.26 → 0.2.27

package/dist/client.d.ts

@@ -443,7 +443,13 @@ export declare class XCiteDBClient {
     listUserWorkspaces(): Promise<{
         user_workspaces: Record<string, unknown>[];
     }>;
-    /** Create a user workspace (`POST /api/v1/user-workspaces`). Returns the workspace record (top-level JSON). */
+    /**
+     * Create a user workspace (`POST /api/v1/user-workspaces`). Returns the workspace record (top-level JSON).
+     *
+     * `sourceBranch` defaults to the root timeline (`""`) — works on a fresh project with no other
+     * workspaces. `"main"` is normalized to `""` server-side; the persisted record stores `""`. If
+     * you pass an explicit non-existent `sourceBranch`, the server returns 400 with the offending name.
+     */
     createUserWorkspace(name: string, options?: {
         sourceBranch?: string;
         sourceDate?: string;
@@ -566,17 +572,38 @@ export declare class XCiteDBClient {
     listIdentifierChildren(parentPath?: string): Promise<ListIdentifierChildrenResult>;
     queryLog(query: XCiteQuery, fromDate: string, toDate: string): Promise<LogEntry[]>;
     addMeta(identifier: string, value: unknown, path?: string, opts?: {
-        mode?: 'set' | 'append';
+        mode?: 'set' | 'append' | 'merge_append';
         overwrite?: boolean;
     }): Promise<boolean>;
     addMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
-        mode?: 'set' | 'append';
+        mode?: 'set' | 'append' | 'merge_append';
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Strict array-extend: `value` must be an array; the stored target at `path` must be an array
+     * (or absent). Server returns 400 `append_payload_not_array` or 409 `append_target_not_array`
+     * otherwise. To merge an object payload (recursing into nested arrays), use {@link mergeAppendMeta}.
+     * To push a single item, use {@link appendItem}.
+     */
+    appendMeta(identifier: string, value: unknown[], path?: string, opts?: {
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    appendMetaByQuery(query: XCiteQuery, value: unknown[], path?: string, firstMatch?: boolean, opts?: {
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Deep-extend: walks the payload and extends any nested arrays found in storage. Scalars and
+     * non-array objects in the payload are written as `set` at their respective paths. Use this
+     * when you intentionally want recursive array-extend; otherwise prefer {@link appendMeta}.
+     */
+    mergeAppendMeta(identifier: string, value: unknown, path?: string, opts?: {
         overwrite?: boolean;
     }): Promise<boolean>;
-    appendMeta(identifier: string, value: unknown, path?: string, opts?: {
+    mergeAppendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
         overwrite?: boolean;
     }): Promise<boolean>;
-    appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
+    /** Convenience: push a single item. Wraps `item` in `[item]` and calls {@link appendMeta}. */
+    appendItem(identifier: string, item: unknown, path?: string, opts?: {
         overwrite?: boolean;
     }): Promise<boolean>;
     queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;

package/dist/client.js

@@ -1462,7 +1462,13 @@ class XCiteDBClient {
     async listUserWorkspaces() {
         return this.request('GET', '/api/v1/user-workspaces');
     }
-    /** Create a user workspace (`POST /api/v1/user-workspaces`). Returns the workspace record (top-level JSON). */
+    /**
+     * Create a user workspace (`POST /api/v1/user-workspaces`). Returns the workspace record (top-level JSON).
+     *
+     * `sourceBranch` defaults to the root timeline (`""`) — works on a fresh project with no other
+     * workspaces. `"main"` is normalized to `""` server-side; the persisted record stores `""`. If
+     * you pass an explicit non-existent `sourceBranch`, the server returns 400 with the offending name.
+     */
     async createUserWorkspace(name, options) {
         const body = { name };
         if (options?.sourceBranch)
@@ -1800,8 +1806,8 @@ class XCiteDBClient {
     }
     async addMeta(identifier, value, path = '', opts) {
         const body = { identifier: this.isoPrefixId(identifier), value, path };
-        if (opts?.mode === 'append')
-            body.mode = 'append';
+        if (opts?.mode === 'append' || opts?.mode === 'merge_append')
+            body.mode = opts.mode;
         if (opts?.overwrite)
             body.overwrite = true;
         const r = await this.request('POST', '/api/v1/meta', body);
@@ -1814,19 +1820,40 @@ class XCiteDBClient {
             path,
             first_match: firstMatch,
         };
-        if (opts?.mode === 'append')
-            body.mode = 'append';
+        if (opts?.mode === 'append' || opts?.mode === 'merge_append')
+            body.mode = opts.mode;
         if (opts?.overwrite)
             body.overwrite = true;
         const r = await this.request('POST', '/api/v1/meta', body);
         return r?.ok !== false;
     }
+    /**
+     * Strict array-extend: `value` must be an array; the stored target at `path` must be an array
+     * (or absent). Server returns 400 `append_payload_not_array` or 409 `append_target_not_array`
+     * otherwise. To merge an object payload (recursing into nested arrays), use {@link mergeAppendMeta}.
+     * To push a single item, use {@link appendItem}.
+     */
     async appendMeta(identifier, value, path = '', opts) {
         return this.addMeta(identifier, value, path, { mode: 'append', ...opts });
     }
     async appendMetaByQuery(query, value, path = '', firstMatch = false, opts) {
         return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append', ...opts });
     }
+    /**
+     * Deep-extend: walks the payload and extends any nested arrays found in storage. Scalars and
+     * non-array objects in the payload are written as `set` at their respective paths. Use this
+     * when you intentionally want recursive array-extend; otherwise prefer {@link appendMeta}.
+     */
+    async mergeAppendMeta(identifier, value, path = '', opts) {
+        return this.addMeta(identifier, value, path, { mode: 'merge_append', ...opts });
+    }
+    async mergeAppendMetaByQuery(query, value, path = '', firstMatch = false, opts) {
+        return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'merge_append', ...opts });
+    }
+    /** Convenience: push a single item. Wraps `item` in `[item]` and calls {@link appendMeta}. */
+    async appendItem(identifier, item, path = '', opts) {
+        return this.appendMeta(identifier, [item], path, opts);
+    }
     async queryMeta(identifier, path = '') {
         return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`);
     }

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 Before reading the full reference, note these critical differences from typical databases:
 
-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), 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.
+1. **The default workspace is the root timeline (`""`); `"main"` is its alias.** When no `X-Workspace` header is sent (or `context.workspace` / `context.branch` is omitted/empty), the server operates on the root timeline. `"main"` passed in any header, body field (`source_branch`, `from_branch`, `target_branch`, `branch`, `source_workspace`, `target_workspace`), or query param is normalized server-side to `""`. **Wrinkle to know:** the canonical stored form is `""`. If you pass `source_branch: "main"` to `createUserWorkspace`, the persisted record reads back as `source_branch: ""` — `""` is the source of truth; `"main"` is just a convenience input. `X-Branch` is a supported alias of `X-Workspace`. Attempting to **create** a branch literally named `"main"` (e.g. `POST /api/v1/workspaces {"name": "main"}`) returns 400 — the name is reserved.
 
 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.
 
@@ -225,7 +225,7 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 
 | Step | What to do |
 |------|------------|
-| **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). Optional JSON body **`{"overlay":true}`** provisions a **read-through production** session (writable delta only under `_test/<uuid>/`; production LMDB is read-only base). |
+| **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes **`session_token`** (UUID), **`tenant_id`** (the session's logical tenant id, formatted as `xcitedbtest-<session_token>` — useful for ABAC group strings like `project:<tenant_id>:editor`), `expires_at`, and `session_ttl_seconds`. Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). Optional JSON body **`{"overlay":true}`** provisions a **read-through production** session (writable delta only under `_test/<uuid>/`; production LMDB is read-only base). |
 | **Use** | Send **`X-Test-Session: <session_token>`** on document and other data API requests. The server routes to a dedicated LMDB under its data root (`_test/<id>/`), not the caller’s production tenant. **`tenant_id` / `X-Project-Id` semantics do not select production** while the test header is present—the synthetic test tenant is implied. |
 | **Auth** | **Default:** developer auth (API key / platform JWT) is **bypassed** with a synthetic admin identity. However, **app-user identity is still recognized**: if `X-App-User-Token` or a Bearer app-user JWT is present, the request runs as that app user (for routes like `/app/auth/me`). **`X-Test-Auth: required`:** all auth is validated normally; ABAC applies, but data still comes from the test session DB. |
 | **Manage** | **`GET /api/v1/test/sessions`** — list sessions for the current credential. **`DELETE /api/v1/test/sessions/current`** — destroy the session named by **`X-Test-Session`** (no other auth). **`DELETE /api/v1/test/sessions/all`** — destroy all sessions for the credential. **`DELETE /api/v1/test/sessions/{token}`** — destroy one session if owned by the credential. Do **not** send **`X-Test-Session`** on these `/api/v1/test/*` routes. **SDKs:** JS `listTestSessions` / `destroyAllTestSessions` / `destroyTestSessionByToken`; Python `list_test_sessions` / `destroy_all_test_sessions` / `destroy_test_session_by_token`; C++ same snake_case; MCP tools `list_test_sessions`, `destroy_all_test_sessions`, `destroy_test_session_by_token`. |
@@ -606,8 +606,8 @@ Attach structured **JSON metadata** to documents or nodes.
 | `identifier` **or** `query` | one required | Target document id or document query |
 | `value` | yes | JSON to write (omit only for string-specific query batch paths handled by the server) |
 | `path` | no (default `""`) | Meta path (dot-separated keys; `[i]` for array indices) |
-| `mode` | no (default `"set"`) | `"set"` — write/replace at `path`. For **arrays** at `path`, indices `0..n-1` are written and any previous tail beyond the new length is cleared. `"append"` — array-extend behavior applies only when the **payload** at `path` is a JSON **array**; new elements are written after the stored length from the array marker `[n]` at `path`. If nothing array-shaped is stored there, the effective prior length is `0` (indices start at `0`). Scalars or a non-array object at `path` are not merged via array-append (object payloads recurse; nested array fields follow the same rules under their own paths). See **Append semantics** below. |
-| `overwrite` | no (default `false`) | When `true`, delete existing metadata under `path` **before** applying `value`. That runs before array logic: with `mode: "append"` it clears the stored `[n]` marker, so the subsequent write always starts at index `0` (you do not keep prior elements). To extend an existing array, use **`overwrite: false`**. For “clear then replace the whole array”, use **`overwrite: true`** with **`mode: "set"`** (or `append` after clear, which is equivalent to writing from `0`). |
+| `mode` | no (default `"set"`) | `"set"` — write/replace at `path`. For **arrays** at `path`, indices `0..n-1` are written and any previous tail beyond the new length is cleared. `"append"` — **strict** array-extend: `value` **must** be a JSON array, and the stored value at `path` must be an array (or absent). The new elements are written after the stored length. `"merge_append"` — **deep** array-extend: walks the payload and extends any nested arrays in storage; scalars and non-array objects in the payload are written as `set` at their own paths. Use `merge_append` only when you intentionally want recursion. See **Append semantics** below. |
+| `overwrite` | no (default `false`) | When `true`, delete existing metadata under `path` **before** applying `value`. That runs before array logic: with `mode: "append"` or `"merge_append"` it clears the stored `[n]` marker, so the subsequent write always starts at index `0` (you do not keep prior elements). To extend an existing array, use **`overwrite: false`**. For “clear then replace the whole array”, use **`overwrite: true`** with **`mode: "set"`**. |
 | `first_match` | no | With `query`, only the first matching identifier is updated when `true`. |
 
 ```json
@@ -622,23 +622,47 @@ Attach structured **JSON metadata** to documents or nodes.
 
 ### Append semantics
 
-- **`mode: "append"`** only changes array behavior when the **JSON at `path` in this request’s `value`** is an **array** (or when traversing an object payload, each **nested** field whose value is an array, under the same `append` flag). A **scalar** or **non-array object** at `path` does not run “append after `[n]`” logic for that node.
-- To **extend** an existing list in storage, the **stored** value at `path` should already be an array (the server keeps a `[length]` marker). New payload elements are written at indices `length`, `length+1`, … If there is **no** valid array marker at `path` in storage, append still succeeds but behaves like a **first write** from index `0`.
-- **`overwrite: true` + `append`:** do not use this expecting “delete old tail then append onto what was left” — overwrite **removes everything under `path` first**, so append always indexes from **`0`**. Prefer **`overwrite: false`** + **`append`** to grow a list; use **`overwrite: true`** + **`set`** when replacing the whole subtree/array.
+- **`mode: "append"` (strict).** The `value` **must** be a JSON array. Non-array payloads (objects, scalars, strings) are rejected with **`400 append_payload_not_array`**. The stored value at `path` must be an array (or absent). If a non-array value is already stored at `path`, the request is rejected with **`409 append_target_not_array`** to avoid silently overwriting it. Empty array `[]` is a no-op success. Missing path is OK — a fresh array is created.
+- **`mode: "merge_append"` (deep).** Walks the payload as if it were a tree of writes. Object payloads recurse into their fields; at each leaf where the stored value is an array and the payload is an array, elements are extended after the stored length. Scalars and non-array objects at leaves are written as `set` at their own paths. Use this only when you intentionally want a single request to extend several nested arrays at once. There is **no** strict precheck — the recursive semantics is the contract.
+- **`overwrite: true` + append modes:** overwrite removes everything under `path` first, so append always indexes from **`0`**. Prefer **`overwrite: false`** + **`append`** to grow a list; use **`overwrite: true`** + **`set`** when replacing the whole subtree/array.
 
-**Example — extend `tags` without overwrite** (stored `tags` is `["a","b"]`; result `["a","b","c","d"]`):
+**Example — strict append: extend `tags`** (stored `tags` is `["a","b"]`; result `["a","b","c","d"]`):
 
 ```json
 {
   "identifier": "/book/ch1",
   "path": "tags",
   "mode": "append",
-  "overwrite": false,
   "value": ["c", "d"]
 }
 ```
 
-**Example — same payload with `overwrite: true`** (clears `tags` first; result only `["c","d"]`):
+**Example — push a single item.** Strict append requires an array; wrap a single item:
+
+```json
+{
+  "identifier": "/book/ch1",
+  "path": "comments",
+  "mode": "append",
+  "value": [{"author": "alice", "text": "lgtm"}]
+}
+```
+
+The JS SDK exposes `appendItem(id, item, path)` as sugar for this; Python has `append_item`; C++ has `append_item`.
+
+**Example — merge_append: extend several arrays in one shot** (stored `tags` is `["a"]`, `reviewers` is `["alice"]`):
+
+```json
+{
+  "identifier": "/book/ch1",
+  "mode": "merge_append",
+  "value": {"tags": ["b","c"], "reviewers": ["bob"]}
+}
+```
+
+Result: `tags` becomes `["a","b","c"]`; `reviewers` becomes `["alice","bob"]`.
+
+**Example — overwrite + append** (clears `tags` first; result only `["c","d"]`):
 
 ```json
 {
@@ -650,7 +674,7 @@ Attach structured **JSON metadata** to documents or nodes.
 }
 ```
 
-Can also use `"query"` instead of `"identifier"` to target multiple documents by query filter.
+Can also use `"query"` instead of `"identifier"` to target multiple documents by query filter. With strict `mode: "append"`, the target precheck runs per matched identifier; on the first one whose stored value at `path` is non-array, the response is `409 append_target_not_array` with `detail.identifier` naming the offender.
 
 ## Query metadata (GET)
 
@@ -863,7 +887,7 @@ Dry-run: **`POST /api/v1/security/check`** with `subject`, `identifier`, `action
 **Preferred base path:** `/api/v1/workspaces`  
 **Deprecated alias:** `/api/v1/branches` (same handlers)
 
-**IMPORTANT: The default workspace is the empty string `""`.** When no workspace is specified, the server uses the root timeline.
+**IMPORTANT: The default workspace is the empty string `""`.** When no workspace is specified, the server uses the root timeline. `"main"` is normalized to `""` server-side wherever a workspace name appears (headers, body fields, query params); the canonical stored form is always `""`. Attempting to create a branch literally named `"main"` returns 400 (reserved name).
 
 ## List workspaces
 
@@ -1082,7 +1106,7 @@ Definitions are stored as JSON under **`/_xcitedb/triggers`**. After a matching
 | `event` | Yes | `meta_changed`, `document_written`, or `document_deleted`. |
 | `match` | Yes | Must include **`identifiers`**: non-empty array of identifier patterns (`exact`, `match_start`, `match_end`, `contains`, `regex`). Optional **`match_meta_path`**: exact path or prefix ending with `*`. Optional **`match_operation`**: `set`, `append`, or `delete` (meta / delete ops). |
 | `conditions` | No | Optional **`branches`** (same as policies) and **`expression`** (see below). |
-| `action` | Yes | **`query`** (`XCiteQuery`), **`unquery`** (Unquery DSL template), **`target_identifier`** (literal or `"$trigger_identifier"`), **`meta_path`**, optional **`mode`**: `set` (default) or `append`. |
+| `action` | Yes | **`query`** (`XCiteQuery`), **`unquery`** (Unquery DSL template), **`target_identifier`** (literal or `"$trigger_identifier"`), **`meta_path`**, optional **`mode`**: `set` (default), `append` (strict — unquery output must be a JSON array, stored target must be an array; trigger logs and skips on misuse), or `merge_append` (deep — recurses into objects to extend nested arrays). |
 
 ### Expression context for **triggers** (`conditions.expression`)
 
@@ -1608,10 +1632,13 @@ interface DatabaseContext {
 - `put(identifier, data, opts?)` / `get<T>(identifier)` / `remove(identifier)` / `list(match?, limit?, offset?)` — JSON CRUD aliases (`opts` same as `writeJsonDocument`)
 
 ### Metadata
-- `addMeta(identifier, value, path?, opts?)` → `boolean` — `opts`: `mode?: 'set'|'append'`, `overwrite?: boolean`
+- `addMeta(identifier, value, path?, opts?)` → `boolean` — `opts`: `mode?: 'set'|'append'|'merge_append'`, `overwrite?: boolean`
 - `addMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
-- `appendMeta(identifier, value, path?, opts?)` → `boolean` — same as `addMeta` with `mode: 'append'`
-- `appendMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
+- `appendMeta(identifier, value: unknown[], path?, opts?)` → `boolean` — **strict** array-extend; `value` typed as array. Server returns `400 append_payload_not_array` / `409 append_target_not_array` on misuse.
+- `appendMetaByQuery(query, value: unknown[], path?, firstMatch?, opts?)` → `boolean` — strict.
+- `mergeAppendMeta(identifier, value, path?, opts?)` → `boolean` — **deep** array-extend (recurses into objects, extends nested arrays). Use only when you intentionally want recursion.
+- `mergeAppendMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
+- `appendItem(identifier, item, path?, opts?)` → `boolean` — sugar for `appendMeta(id, [item], path, opts)`.
 - `queryMeta<T>(identifier, path?)` → `T`
 - `queryMetaByQuery<T>(query, path?)` → `T`
 - `clearMeta(query)` → `boolean`

package/llms.txt

@@ -6,7 +6,7 @@
 
 These are the most common sources of confusion for developers and AI assistants:
 
-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.
+1. **The default workspace is the root timeline (`""`); `"main"` is its alias.** 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. `"main"` passed in any header, body field (`source_branch`, `from_branch`, `target_branch`, `branch`, `source_workspace`, `target_workspace`), or query param is normalized server-side to `""`. **Wrinkle to know:** the canonical stored form is `""`. If you pass `source_branch: "main"` to `createUserWorkspace`, the persisted record reads back as `source_branch: ""` — `""` is the source of truth; `"main"` is just a convenience input. `X-Branch` is a supported alias of `X-Workspace`. Attempting to **create** a branch literally named `"main"` (e.g. `POST /api/v1/workspaces {"name": "main"}`) returns 400 — the name is reserved.
 
 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.
 
@@ -159,7 +159,7 @@ When you build a backend that calls XCiteDB on behalf of users:
 ## JSON documents and metadata (merge, overwrite, efficiency)
 
 - **JSON documents merge by default.** `POST /api/v1/json-documents` merges the posted `data` into the existing document (object fields combined per XCiteDB meta merge rules). Send **`overwrite: true`** to clear all stored JSON under that document root first, then write only the new payload. SDKs accept the same flag (e.g. `writeJsonDocument(id, data, { overwrite: true })` in JavaScript).
-- **Metadata `mode` and arrays.** **`POST /api/v1/meta`** uses **`mode`**: default **`set`** writes or replaces at `path` (arrays are replaced in range; excess old indices cleared); **`append`** appends array elements after existing ones at `path`. Optional **`overwrite: true`** clears metadata under `path` before writing. JavaScript: **`appendMeta`** or **`addMeta(..., { mode: 'append' })`**; Python/C++: **`append_meta`** or **`add_meta`** with **`mode`** / **`overwrite`** (see SDK sections below).
+- **Metadata `mode` and arrays.** **`POST /api/v1/meta`** uses **`mode`**: default **`set`** writes or replaces at `path`; **`append`** is **strict** array-extend — `value` must be a JSON array AND the stored target at `path` must already be an array (or absent). Otherwise the server returns **`400 append_payload_not_array`** or **`409 append_target_not_array`**. **`merge_append`** is the legacy "deep" behavior — recurses into object payloads and extends nested arrays in storage; use only when you intentionally want recursion. Optional **`overwrite: true`** clears metadata under `path` before writing. JavaScript: **`appendMeta(id, [items], path)`** (strict, types `value` as array), **`mergeAppendMeta(id, value, path)`** (deep), **`appendItem(id, item, path)`** (sugar for a single item). Python/C++: **`append_meta` / `merge_append_meta` / `append_item`**.
 - **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)
@@ -349,8 +349,10 @@ interface XCiteDBClientOptions {
 - **Quick JSON aliases:** `put`, `get`, `remove`, `list` — same as the four methods above
 
 **Metadata (JSON on XML):**
-- `addMeta(identifier, value, path?, opts?)` — Set or append metadata (`opts?.mode`: `set`|`append`; `opts?.overwrite`)
-- `appendMeta(identifier, value, path?, opts?)` — Append at `path` (same as `addMeta` with `mode: 'append'`)
+- `addMeta(identifier, value, path?, opts?)` — Set or append metadata (`opts?.mode`: `set`|`append`|`merge_append`; `opts?.overwrite`)
+- `appendMeta(identifier, value: unknown[], path?, opts?)` — **Strict** array-extend at `path`; `value` typed as array. Server returns `400 append_payload_not_array` / `409 append_target_not_array` on misuse.
+- `mergeAppendMeta(identifier, value, path?, opts?)` — **Deep** array-extend (recurses into objects, extends nested arrays). Use only when you intentionally want recursion.
+- `appendItem(identifier, item, path?, opts?)` — Convenience: wraps `item` in `[item]` and calls `appendMeta`.
 - `queryMeta(identifier, path?)` — Read metadata
 - `clearMeta(query)` — Remove metadata
 
@@ -402,7 +404,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`.
+- **`action`:** **`query`** (document query), **`unquery`** (Unquery template), **`target_identifier`** (or `"$trigger_identifier"`), **`meta_path`**, **`mode`:** `set` | `append` (strict — unquery output must be a JSON array) | `merge_append` (deep — recurses into objects to extend nested arrays).
 - **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)`)

package/package.json

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