@xcitedbs/client 0.2.26 → 0.3.0

package/dist/client.d.ts

@@ -15,7 +15,12 @@ export declare class XCiteDBClient {
     private onAppUserTokensUpdated?;
     private onSessionInvalid?;
     private testSessionToken?;
-    private testRequireAuth?;
+    /**
+     * Test-session auth fidelity. `'bypass'` is the legacy mode that synthesizes a developer-admin
+     * identity server-side; `'required'` and `'preserve'` send `X-Test-Auth: required|preserve`.
+     * `createTestSession` defaults to `'required'`.
+     */
+    private testAuthMode?;
     private userIsolation?;
     private cachedAppUserId?;
     private readonly requestTimeoutMs?;
@@ -24,7 +29,14 @@ export declare class XCiteDBClient {
     constructor(options: XCiteDBClientOptions);
     /**
      * Create an ephemeral test database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
-     * then returns a client that sends `X-Test-Session` (auth-free by default).
+     * then returns a client that sends `X-Test-Session` on every subsequent request.
+     *
+     * **Auth fidelity (default = `'required'`):** the SDK now defaults to faithful auth so wet tests
+     * exercise the same role/credential gates as production. Pass `testAuth: 'preserve'` to keep
+     * faithful auth but skip ABAC bootstrapping (real auth, lenient policies). The legacy
+     * `'bypass'` mode (server synthesizes a developer-admin identity) is available but not the
+     * default — it erases the public-key context and produces tests that pass when production fails.
+     *
      * With `opts.overlay === true`, the server stores overlay mode: reads merge the empty `_test/...` LMDB
      * over the current project's production data (read-only base); writes stay under `_test/...` only.
      */
@@ -147,17 +159,43 @@ export declare class XCiteDBClient {
     createApiKey(name: string, expiresAt?: number, keyType?: 'secret' | 'public'): Promise<unknown>;
     changePassword(currentPassword: string, newPassword: string): Promise<void>;
     revokeApiKey(keyId: string): Promise<void>;
+    /**
+     * Self-register an app user. Public endpoint — set `context.project_id` on the client first.
+     *
+     * **Side effect:** clears any cached `appUserAccessToken` / `appUserRefreshToken` before the
+     * request. Without this, a previously logged-in client would send `Authorization: Bearer
+     * <stale-token>`, which the server (correctly) rejects with `reason: "already_authenticated"`.
+     * The clear runs before the request fires, so even a 4xx response leaves the client in a clean
+     * unauthenticated state — a fresh `loginAppUser` call works without manual `clearAppUserTokens`.
+     */
     registerAppUser(email: string, password: string, displayName?: string, attributes?: Record<string, unknown>): Promise<AppUser>;
     getOAuthProviders(): Promise<OAuthProvidersResponse>;
     /** Relative path + query for browser navigation to start OAuth (append to API base URL). */
     oauthAuthorizePath(provider: string): string;
-    /** Exchange one-time session code from OAuth browser redirect (public + tenant_id). */
+    /**
+     * Exchange one-time session code from OAuth browser redirect (public + tenant_id).
+     * Clears any cached app-user tokens before the request — see `loginAppUser` for rationale.
+     */
     exchangeOAuthCode(code: string): Promise<AppUserTokenPair>;
+    /**
+     * Sign in as an app user and **store** the issued access/refresh tokens on this client. Subsequent
+     * requests automatically send `Authorization: Bearer <access>` (or `X-App-User-Token` when paired
+     * with a developer key/JWT). Call `clearAppUserTokens()` (or `logoutAppUser()`) to drop them.
+     *
+     * **Side effect:** clears any cached `appUserAccessToken` / `appUserRefreshToken` before the
+     * request. Without this, a previously logged-in client would send `Authorization: Bearer
+     * <stale-token>` and the server would reject with `reason: "already_authenticated"`. The clear
+     * runs before the request fires, so re-logging in as a different user just works.
+     */
     loginAppUser(email: string, password: string): Promise<AppUserTokenPair>;
     refreshAppUser(): Promise<AppUserTokenPair>;
     logoutAppUser(): Promise<void>;
     appUserMe(): Promise<AppUser>;
     updateAppUserProfile(displayName?: string, attributes?: Record<string, unknown>): Promise<AppUser>;
+    /**
+     * Exchange a custom JWT for an app-user session.
+     * Clears any cached app-user tokens before the request — see `loginAppUser` for rationale.
+     */
     exchangeCustomToken(token: string): Promise<AppUserTokenPair>;
     /** Change app-user password (requires valid app-user access token). */
     changeAppUserPassword(currentPassword: string, newPassword: string): Promise<void>;
@@ -168,6 +206,24 @@ export declare class XCiteDBClient {
     /** Issue email verification token (developer-authenticated). Token omitted when delivery is smtp/webhook success. */
     sendAppUserVerification(userId: string): Promise<SendVerificationResponse>;
     getAppAuthConfig(): Promise<AppAuthConfig>;
+    /**
+     * Patch `auth.app_users.*` (PUT /api/v1/app/auth/config). Requires admin developer auth.
+     *
+     * Whitelisted keys: `enabled`, `registration_enabled`, `default_groups`,
+     * `require_email_verification`, `min_password_length`, `max_login_attempts`,
+     * `lockout_duration_seconds`, `access_token_expiry_seconds`, `refresh_token_expiry_seconds`,
+     * `reset_token_expiry_seconds`, `verification_token_expiry_seconds`, `public_base_url`.
+     *
+     * Secret-bearing fields (`jwt_secret`, `signing_key_path`, `custom_token_secret`,
+     * `oauth_providers`) are intentionally not patchable here — set them in server config and reload.
+     * Returns the full effective config including any `warnings`.
+     *
+     * @example Bootstrap a fresh project so registered users land in the editor group:
+     * ```ts
+     * await client.updateAppAuthConfig({ default_groups: ['editor'] });
+     * ```
+     */
+    updateAppAuthConfig(patch: Partial<AppAuthConfig>): Promise<AppAuthConfig>;
     getEmailConfig(): Promise<AppEmailConfig>;
     updateEmailConfig(config: AppEmailConfig): Promise<AppEmailConfig>;
     getEmailTemplates(): Promise<AppEmailTemplates>;
@@ -312,15 +368,31 @@ export declare class XCiteDBClient {
     updateSecurityConfig(config: Partial<SecurityConfig>): Promise<void>;
     /** Per-tenant user data spaces (`GET /api/v1/security/user-isolation`). Requires security admin. */
     getUserIsolationConfig(): Promise<UserIsolationConfig>;
+    /**
+     * Public-read sibling (`GET /api/v1/security/user-isolation/public`). Returns only the
+     * client-prefix-relevant fields (enabled, namespace_pattern, shared_*_paths). Lets SPAs
+     * configure isolation without admin auth.
+     */
+    getUserIsolationConfigPublic(): Promise<UserIsolationConfig>;
     /** Enable or reconfigure user isolation (`PUT /api/v1/security/user-isolation`). */
     setUserIsolationConfig(config: Partial<UserIsolationConfig>): Promise<UserIsolationConfig>;
     /** Disable user isolation and remove generated policies (`DELETE /api/v1/security/user-isolation`). */
     disableUserIsolation(): Promise<void>;
     /**
-     * Loads server isolation config; when enabled, configures client-side identifier prefixing to match
-     * the server (namespace + shared paths). Does not send `X-Prefix`; identifiers in requests are rewritten.
-     */
-    enableUserIsolation(): Promise<UserIsolationConfig>;
+     * Configure client-side identifier prefixing to match server-side user isolation. Does not send
+     * `X-Prefix`; identifiers in requests are rewritten by the SDK.
+     *
+     * Two forms:
+     * 1. **No-arg**: fetches the public read-only endpoint (`/api/v1/security/user-isolation/public`),
+     *    falling back to the admin endpoint on 404 (older servers). No admin auth needed in SPAs.
+     * 2. **Explicit config**: pass `{ namespace, shared_read_paths?, shared_write_paths? }` to skip
+     *    the network round-trip entirely. Useful when the BFF already knows the configuration.
+     */
+    enableUserIsolation(config?: {
+        namespace?: string;
+        shared_read_paths?: string[];
+        shared_write_paths?: string[];
+    }): Promise<UserIsolationConfig>;
     /**
      * Share a document from the caller’s user namespace with another app user (`POST …/user-isolation/shares`).
      * Requires an **app user** session (`appUserAccessToken` / `loginAppUser`) and tenant isolation enabled.
@@ -443,7 +515,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 +644,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

@@ -90,6 +90,27 @@ function warnIfHttpOnTlsPort(baseUrl) {
         /* ignore invalid baseUrl */
     }
 }
+/**
+ * Resolve the test-session auth mode from the new `testAuth` option and the deprecated
+ * `testRequireAuth` boolean. Used by both the {@link XCiteDBClient} constructor and
+ * {@link XCiteDBClient.createTestSession}. Returns `undefined` when the client is not in a
+ * test session at all (no `testSessionToken`).
+ *
+ * Precedence:
+ * - If `testAuth` is set, use it directly.
+ * - Else if `testRequireAuth === true`, use `'required'`.
+ * - Else if `testRequireAuth === false`, use `'bypass'` (legacy explicit opt-out).
+ * - Else `undefined` — caller decides default. `createTestSession` defaults to `'required'`.
+ */
+function resolveTestAuthMode(testAuth, testRequireAuth) {
+    if (testAuth !== undefined)
+        return testAuth;
+    if (testRequireAuth === true)
+        return 'required';
+    if (testRequireAuth === false)
+        return 'bypass';
+    return undefined;
+}
 /** Uses `AbortSignal.timeout` when the runtime supports it. */
 function requestTimeoutSignal(ms) {
     if (ms === undefined || ms <= 0)
@@ -113,14 +134,21 @@ class XCiteDBClient {
         this.onAppUserTokensUpdated = options.onAppUserTokensUpdated;
         this.onSessionInvalid = options.onSessionInvalid;
         this.testSessionToken = options.testSessionToken;
-        this.testRequireAuth = options.testRequireAuth === true;
+        this.testAuthMode = resolveTestAuthMode(options.testAuth, options.testRequireAuth);
         this.userIsolation = options.userIsolation;
         this.requestTimeoutMs = options.requestTimeoutMs;
         warnIfHttpOnTlsPort(this.baseUrl);
     }
     /**
      * Create an ephemeral test database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
-     * then returns a client that sends `X-Test-Session` (auth-free by default).
+     * then returns a client that sends `X-Test-Session` on every subsequent request.
+     *
+     * **Auth fidelity (default = `'required'`):** the SDK now defaults to faithful auth so wet tests
+     * exercise the same role/credential gates as production. Pass `testAuth: 'preserve'` to keep
+     * faithful auth but skip ABAC bootstrapping (real auth, lenient policies). The legacy
+     * `'bypass'` mode (server synthesizes a developer-admin identity) is available but not the
+     * default — it erases the public-key context and produces tests that pass when production fails.
+     *
      * With `opts.overlay === true`, the server stores overlay mode: reads merge the empty `_test/...` LMDB
      * over the current project's production data (read-only base); writes stay under `_test/...` only.
      */
@@ -146,12 +174,14 @@ class XCiteDBClient {
         if (opts.bootstrap !== undefined)
             sessionBody.bootstrap = opts.bootstrap;
         const data = await temp.request('POST', '/api/v1/test/sessions', Object.keys(sessionBody).length ? sessionBody : undefined, undefined, { no401Retry: true });
+        const mode = resolveTestAuthMode(opts.testAuth, opts.testRequireAuth) ?? 'required';
+        const keepCreds = mode !== 'bypass';
         const child = new XCiteDBClient({
             baseUrl: opts.baseUrl,
-            apiKey: opts.testRequireAuth ? opts.apiKey : undefined,
-            accessToken: opts.testRequireAuth ? opts.accessToken : undefined,
-            appUserAccessToken: opts.testRequireAuth ? opts.appUserAccessToken : undefined,
-            appUserRefreshToken: opts.testRequireAuth ? opts.appUserRefreshToken : undefined,
+            apiKey: keepCreds ? opts.apiKey : undefined,
+            accessToken: keepCreds ? opts.accessToken : undefined,
+            appUserAccessToken: keepCreds ? opts.appUserAccessToken : undefined,
+            appUserRefreshToken: keepCreds ? opts.appUserRefreshToken : undefined,
             context: opts.context,
             platformConsole: opts.platformConsole,
             projectId: opts.projectId,
@@ -159,7 +189,7 @@ class XCiteDBClient {
             onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
             onSessionInvalid: opts.onSessionInvalid,
             testSessionToken: data.session_token,
-            testRequireAuth: opts.testRequireAuth,
+            testAuth: mode,
             userIsolation: opts.userIsolation,
             requestTimeoutMs: opts.requestTimeoutMs,
         });
@@ -536,8 +566,10 @@ class XCiteDBClient {
         const h = {};
         if (this.testSessionToken) {
             h['X-Test-Session'] = this.testSessionToken;
-            if (this.testRequireAuth) {
-                h['X-Test-Auth'] = 'required';
+            // 'required' / 'preserve' send the header; 'bypass' (or undefined) omits it so the server
+            // applies the legacy synthesized-admin behavior.
+            if (this.testAuthMode === 'required' || this.testAuthMode === 'preserve') {
+                h['X-Test-Auth'] = this.testAuthMode;
             }
         }
         return h;
@@ -868,7 +900,17 @@ class XCiteDBClient {
         await this.request('DELETE', `/api/v1/project/keys/${encodeURIComponent(keyId)}`);
     }
     // --- App user auth (requires developer API key or JWT on the same tenant) ---
+    /**
+     * Self-register an app user. Public endpoint — set `context.project_id` on the client first.
+     *
+     * **Side effect:** clears any cached `appUserAccessToken` / `appUserRefreshToken` before the
+     * request. Without this, a previously logged-in client would send `Authorization: Bearer
+     * <stale-token>`, which the server (correctly) rejects with `reason: "already_authenticated"`.
+     * The clear runs before the request fires, so even a 4xx response leaves the client in a clean
+     * unauthenticated state — a fresh `loginAppUser` call works without manual `clearAppUserTokens`.
+     */
     async registerAppUser(email, password, displayName, attributes) {
+        this.clearAppUserTokens();
         const body = { email, password };
         if (displayName !== undefined)
             body.display_name = displayName;
@@ -887,15 +929,30 @@ class XCiteDBClient {
         const tid = raw && String(raw).length > 0 ? String(raw) : 'default';
         return `/api/v1/app/auth/oauth/${encodeURIComponent(provider)}/authorize${buildQuery({ tenant_id: tid })}`;
     }
-    /** Exchange one-time session code from OAuth browser redirect (public + tenant_id). */
+    /**
+     * Exchange one-time session code from OAuth browser redirect (public + tenant_id).
+     * Clears any cached app-user tokens before the request — see `loginAppUser` for rationale.
+     */
     async exchangeOAuthCode(code) {
+        this.clearAppUserTokens();
         const pair = await this.request('POST', '/api/v1/app/auth/oauth/exchange', this.mergeAppTenant({ code }));
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
         this.cacheAppUserIdFromPair(pair);
         return pair;
     }
+    /**
+     * Sign in as an app user and **store** the issued access/refresh tokens on this client. Subsequent
+     * requests automatically send `Authorization: Bearer <access>` (or `X-App-User-Token` when paired
+     * with a developer key/JWT). Call `clearAppUserTokens()` (or `logoutAppUser()`) to drop them.
+     *
+     * **Side effect:** clears any cached `appUserAccessToken` / `appUserRefreshToken` before the
+     * request. Without this, a previously logged-in client would send `Authorization: Bearer
+     * <stale-token>` and the server would reject with `reason: "already_authenticated"`. The clear
+     * runs before the request fires, so re-logging in as a different user just works.
+     */
     async loginAppUser(email, password) {
+        this.clearAppUserTokens();
         const pair = await this.request('POST', '/api/v1/app/auth/login', this.mergeAppTenant({ email, password }));
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
@@ -922,7 +979,12 @@ class XCiteDBClient {
             body.attributes = attributes;
         return this.request('PUT', '/api/v1/app/auth/me', body);
     }
+    /**
+     * Exchange a custom JWT for an app-user session.
+     * Clears any cached app-user tokens before the request — see `loginAppUser` for rationale.
+     */
     async exchangeCustomToken(token) {
+        this.clearAppUserTokens();
         const pair = await this.request('POST', '/api/v1/app/auth/custom-token', { token });
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
@@ -953,6 +1015,26 @@ class XCiteDBClient {
     async getAppAuthConfig() {
         return this.request('GET', '/api/v1/app/auth/config');
     }
+    /**
+     * Patch `auth.app_users.*` (PUT /api/v1/app/auth/config). Requires admin developer auth.
+     *
+     * Whitelisted keys: `enabled`, `registration_enabled`, `default_groups`,
+     * `require_email_verification`, `min_password_length`, `max_login_attempts`,
+     * `lockout_duration_seconds`, `access_token_expiry_seconds`, `refresh_token_expiry_seconds`,
+     * `reset_token_expiry_seconds`, `verification_token_expiry_seconds`, `public_base_url`.
+     *
+     * Secret-bearing fields (`jwt_secret`, `signing_key_path`, `custom_token_secret`,
+     * `oauth_providers`) are intentionally not patchable here — set them in server config and reload.
+     * Returns the full effective config including any `warnings`.
+     *
+     * @example Bootstrap a fresh project so registered users land in the editor group:
+     * ```ts
+     * await client.updateAppAuthConfig({ default_groups: ['editor'] });
+     * ```
+     */
+    async updateAppAuthConfig(patch) {
+        return this.request('PUT', '/api/v1/app/auth/config', patch);
+    }
     async getEmailConfig() {
         return this.request('GET', '/api/v1/app/email/config');
     }
@@ -1176,6 +1258,14 @@ class XCiteDBClient {
     async getUserIsolationConfig() {
         return this.request('GET', '/api/v1/security/user-isolation');
     }
+    /**
+     * Public-read sibling (`GET /api/v1/security/user-isolation/public`). Returns only the
+     * client-prefix-relevant fields (enabled, namespace_pattern, shared_*_paths). Lets SPAs
+     * configure isolation without admin auth.
+     */
+    async getUserIsolationConfigPublic() {
+        return this.request('GET', '/api/v1/security/user-isolation/public');
+    }
     /** Enable or reconfigure user isolation (`PUT /api/v1/security/user-isolation`). */
     async setUserIsolationConfig(config) {
         return this.request('PUT', '/api/v1/security/user-isolation', config);
@@ -1185,11 +1275,43 @@ class XCiteDBClient {
         await this.request('DELETE', '/api/v1/security/user-isolation');
     }
     /**
-     * Loads server isolation config; when enabled, configures client-side identifier prefixing to match
-     * the server (namespace + shared paths). Does not send `X-Prefix`; identifiers in requests are rewritten.
+     * Configure client-side identifier prefixing to match server-side user isolation. Does not send
+     * `X-Prefix`; identifiers in requests are rewritten by the SDK.
+     *
+     * Two forms:
+     * 1. **No-arg**: fetches the public read-only endpoint (`/api/v1/security/user-isolation/public`),
+     *    falling back to the admin endpoint on 404 (older servers). No admin auth needed in SPAs.
+     * 2. **Explicit config**: pass `{ namespace, shared_read_paths?, shared_write_paths? }` to skip
+     *    the network round-trip entirely. Useful when the BFF already knows the configuration.
      */
-    async enableUserIsolation() {
-        const cfg = await this.getUserIsolationConfig();
+    async enableUserIsolation(config) {
+        if (config && config.namespace) {
+            this.userIsolation = {
+                enabled: true,
+                namespace: config.namespace,
+                shared_read_paths: config.shared_read_paths,
+                shared_write_paths: config.shared_write_paths,
+            };
+            return {
+                enabled: true,
+                namespace_pattern: config.namespace,
+                shared_read_paths: config.shared_read_paths ?? [],
+                shared_write_paths: config.shared_write_paths ?? [],
+            };
+        }
+        let cfg;
+        try {
+            cfg = await this.getUserIsolationConfigPublic();
+        }
+        catch (err) {
+            // Older servers don't expose the public endpoint — try the admin one.
+            if (err instanceof types_1.XCiteDBError && err.status === 404) {
+                cfg = await this.getUserIsolationConfig();
+            }
+            else {
+                throw err;
+            }
+        }
         if (cfg.enabled) {
             this.userIsolation = {
                 enabled: true,
@@ -1462,7 +1584,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 +1928,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 +1942,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/dist/types.d.ts

@@ -676,7 +676,16 @@ export interface XCiteDBClientOptions {
      * Sends `X-Test-Session`; use with {@link XCiteDBClient.createTestSession}.
      */
     testSessionToken?: string;
-    /** When true with `testSessionToken`, sends `X-Test-Auth: required` so real credentials are validated. */
+    /**
+     * Test-session auth fidelity. `'required'` / `'preserve'` send `X-Test-Auth: <mode>`;
+     * `'bypass'` omits the header (server synthesizes a developer-admin identity). See
+     * {@link CreateTestSessionOptions.testAuth} for guidance on which to pick.
+     */
+    testAuth?: 'required' | 'preserve' | 'bypass';
+    /**
+     * @deprecated Use `testAuth`.
+     * `true` ↔ `testAuth: 'required'`; `false` ↔ `testAuth: 'bypass'`.
+     */
     testRequireAuth?: boolean;
     /** Auto-prefix identifiers for app-user sessions (see {@link UserIsolationOptions}). */
     userIsolation?: UserIsolationOptions;
@@ -730,7 +739,24 @@ export interface CreateTestSessionOptions {
     overlay?: boolean;
     /** Optional server-side bootstrap (user isolation, developer_bypass, policies). */
     bootstrap?: TestSessionBootstrap;
-    /** Keep `apiKey` / `accessToken` on the client and send `X-Test-Auth: required` on each request. */
+    /**
+     * Test-session auth fidelity mode (`X-Test-Auth` header on the returned client).
+     *
+     * - `'required'` (**SDK default**) — auth runs normally; ABAC default-deny applies until you bootstrap policies.
+     *   Tests that exercise role/credential checks (public-key denials, etc.) work as in production.
+     * - `'preserve'` — auth runs normally, but ABAC defaults to allow inside the test tenant when no
+     *   policies are configured. Use when you want production-faithful auth without writing ABAC policies.
+     * - `'bypass'` — server synthesizes a developer-admin identity. Erases the public-key context entirely;
+     *   tests that depend on auth/role failures will pass under bypass and fail in production. Avoid.
+     *
+     * @default 'required'
+     */
+    testAuth?: 'required' | 'preserve' | 'bypass';
+    /**
+     * @deprecated Use `testAuth: 'required'` (or omit for the SDK default).
+     * Setting `testRequireAuth: false` explicitly opts into legacy bypass mode (`testAuth: 'bypass'`).
+     * Setting `true` is equivalent to `testAuth: 'required'`.
+     */
     testRequireAuth?: boolean;
     onSessionTokensUpdated?: (pair: TokenPair) => void;
     onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
@@ -763,7 +789,10 @@ export interface OAuthProviderInfo {
 export interface OAuthProvidersResponse {
     providers: OAuthProviderInfo[];
 }
-/** Read-only effective `auth.app_users` (GET /api/v1/app/auth/config). */
+/**
+ * Effective `auth.app_users` (GET /api/v1/app/auth/config). Mutable subset is patchable
+ * via `updateAppAuthConfig` — see that method's JSDoc for which keys are accepted.
+ */
 export interface AppAuthConfig {
     enabled: boolean;
     registration_enabled: boolean;
@@ -778,6 +807,12 @@ export interface AppAuthConfig {
     verification_token_expiry_seconds: number;
     jwt_algorithm: string;
     public_base_url: string;
+    /**
+     * Bootstrap warnings the operator should act on. Today: `"default_groups_empty"` when
+     * `registration_enabled: true` is paired with an empty `default_groups` (self-registered users
+     * authenticate but cannot perform writes). The BFF / app shell should surface these at startup.
+     */
+    warnings?: string[];
 }
 export interface AppEmailSmtpConfig {
     host: string;
@@ -1051,8 +1086,16 @@ export interface RebaseUserWorkspaceResult {
     auto_mergeable?: string[];
     would_expose?: string[];
 }
+/**
+ * Canonical 403 `reason` codes the server can emit. Use as a discriminator on
+ * `XCiteDBForbiddenError.reason` in catch sites — TypeScript will warn if you forget a case.
+ *
+ * The trailing `(string & {})` keeps the type open to forward-compatible reasons added by newer
+ * servers without forcing a SDK bump on every new code.
+ */
+export type XCiteDBForbiddenReason = 'role_forbidden_public_key' | 'role_forbidden_not_admin' | 'role_forbidden_not_admin_or_editor' | 'role_forbidden_app_user_no_admin' | 'role_forbidden_viewer' | 'role_forbidden' | 'auth_admin_required' | 'auth_developer_required' | 'auth_app_user_required' | 'auth_app_user_or_developer_required' | 'auth_admin_or_app_user_required' | 'auth_developer_or_anonymous_required' | 'auth_developer_or_app_user_required' | 'auth_site_admin_required' | 'auth_platform_required' | 'auth_platform_console_required' | 'auth_project_member_required' | 'auth_project_admin_required' | 'auth_org_admin_required' | 'auth_org_member_required' | 'auth_missing' | 'already_authenticated' | 'registration_disabled' | 'system_tenant_register_forbidden' | 'system_tenant_login_forbidden' | 'system_tenant_refresh_forbidden' | 'forgot_password_self_forbidden' | 'account_pending_approval' | 'email_verification_required' | 'abac_default_deny' | 'abac_explicit_deny' | 'abac_reserved_namespace' | 'tenant_security_unconfigured' | 'user_workspace_forbidden' | 'user_workspace_requires_app_user' | 'user_workspaces_app_user_only' | 'user_workspaces_create_app_user_only' | 'share_invalid_user_id' | 'share_invalid_identifier' | 'share_outside_namespace' | 'share_group_not_owner' | 'share_group_admin_only' | 'magic_link_not_authorized' | 'magic_link_not_owner' | 'magic_link_session_forbidden' | 'magic_link_forbidden' | 'reserved_namespace' | 'xml_path_policy_redacted_all' | 'test_session_not_owned' | 'ip_access_denied' | 'cluster_secret_invalid' | 'tenant_not_active' | 'org_not_active' | 'org_create_not_allowed' | 'org_project_limit_reached' | (string & {});
 export type XCiteDBErrorExtras = {
-    reason?: string;
+    reason?: XCiteDBForbiddenReason;
     policyId?: string;
     hint?: string;
     expectedRole?: string;
@@ -1063,7 +1106,7 @@ export type XCiteDBErrorExtras = {
 export declare class XCiteDBError extends Error {
     readonly status: number;
     readonly body?: unknown | undefined;
-    reason?: string;
+    reason?: XCiteDBForbiddenReason;
     policyId?: string;
     hint?: string;
     expectedRole?: string;

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.
 
@@ -61,7 +61,7 @@ Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain
 
 5. **`context.project_id` (or `tenant_id`) is required for app-user self-registration.** `registerAppUser()` uses `mergeAppTenant(body)` to add `tenant_id` to the JSON body only when `context.project_id` or `context.tenant_id` is set. If both are omitted, the server cannot determine which project to register the user in. Always set `project_id` in the constructor `context` when calling `registerAppUser`, `loginAppUser`, and other public app-auth methods.
 
-6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To assign specific groups, use the admin endpoint `createAppUser()` instead, or update groups after registration via `updateAppUserGroups()`.
+6. **Self-registration uses server-configured default groups — set them before opening registration.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. With `default_groups: []` paired with `registration_enabled: true`, registered users authenticate but have no role groups and **cannot perform writes** (the failure is silent — every write returns 403 `role_forbidden_app_user_no_admin`). Set via `updateAppAuthConfig({ default_groups: ["editor"] })` (`PUT /api/v1/app/auth/config`, admin-gated) or via the platform console. `getAppAuthConfig()` includes `warnings: ["default_groups_empty"]` when this combination is detected; surface it at BFF startup so DB-reset bootstrap doesn't silently no-op. To assign specific groups outside the default, use the admin endpoint `createAppUser()` or `updateAppUserGroups()` after registration.
 
 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.
 
@@ -225,18 +225,20 @@ 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. |
+| **Auth** | Three modes via the **`X-Test-Auth`** header. **`required`** (SDK default as of this release): all auth is validated normally; ABAC applies, so role/credential checks (e.g. public-key on admin-write controllers → 403 `role_forbidden_public_key`) fire as in production. **`preserve`**: auth runs normally, but ABAC defaults to **allow** when the test tenant has no policies — production-faithful auth without forcing a policy bootstrap. **Header omitted** (legacy bypass): server synthesizes a developer-admin identity (`auth_user_type=member, role=admin`) and **erases the public-key context entirely** — tests that exercise auth/role failures will pass under bypass and fail in production. **App-user identity is still recognized in every mode**: 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`). |
 | **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`. |
 | **429 / suites** | Per-credential concurrent cap (default **5**, `test.max_sessions_per_key`). If **`createTestSession`** returns **429**, call **`destroyAllTestSessions`** (same API key / Bearer, no `X-Test-Session`) before retrying — typical **once in `beforeAll`** for large wet suites. |
 | **CORS** | Browsers may need **`X-Test-Session`** and **`X-Test-Auth`** in the deployment’s allowed CORS headers (defaults include them). |
 
 **SDK usage (summary):**
 
-- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`; optional **`bootstrap`** (`user_isolation`, `developer_bypass`, `policies`); read **`lastTestSessionBootstrap`** on the returned client when the server included a summary. `destroyTestSession()` calls `DELETE …/test/sessions/current`. On a **normal** client (same `apiKey` / Bearer, **no** `testSessionToken`), **`listTestSessions()`**, **`destroyAllTestSessions()`**, **`destroyTestSessionByToken(token)`** wrap the management routes (they never send `X-Test-Session`).
-- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …, bootstrap={…})` provisions and tears down; or **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`**, **`bootstrap`**, or both, then construct the client with the returned token; **`client.last_test_session_bootstrap`** mirrors the server summary. Management: **`await client.list_test_sessions()`**, **`await client.destroy_all_test_sessions()`**, **`await client.destroy_test_session_by_token(token)`** with `suppress_test_session` behavior (omit `X-Test-Session` on those paths).
-- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay`**, optional **`test_session_bootstrap`** on `XCiteDBClientOptions`, optional `test_require_auth`; **`last_test_session_bootstrap()`** on the returned client; `destroy_test_session()`. Management: **`list_test_sessions()`**, **`destroy_all_test_sessions()`**, **`destroy_test_session_by_token(token)`** on a client carrying the provisioning credential only.
+- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; **`testAuth: 'required' | 'preserve' | 'bypass'`** (default **`'required'`**); legacy **`testRequireAuth`** still accepted (`true` ↔ `'required'`, `false` ↔ `'bypass'`); optional **`bootstrap`** (`user_isolation`, `developer_bypass`, `policies`); read **`lastTestSessionBootstrap`** on the returned client when the server included a summary. `destroyTestSession()` calls `DELETE …/test/sessions/current`. On a **normal** client (same `apiKey` / Bearer, **no** `testSessionToken`), **`listTestSessions()`**, **`destroyAllTestSessions()`**, **`destroyTestSessionByToken(token)`** wrap the management routes (they never send `X-Test-Session`).
+- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …, bootstrap={…})` provisions and tears down; default `test_auth="required"`; pass **`test_auth="preserve"`** for real auth + lenient ABAC, **`test_auth="bypass"`** for legacy synthesized-admin. Or **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`**, **`bootstrap`**, or both, then construct the client with the returned token; **`client.last_test_session_bootstrap`** mirrors the server summary. Management: **`await client.list_test_sessions()`**, **`await client.destroy_all_test_sessions()`**, **`await client.destroy_test_session_by_token(token)`** with `suppress_test_session` behavior (omit `X-Test-Session` on those paths).
+- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay`**, optional **`test_session_bootstrap`** on `XCiteDBClientOptions`, optional **`test_auth`** (`"required"`/`"preserve"`/`"bypass"`; default `"required"`) or legacy `test_require_auth`; **`last_test_session_bootstrap()`** on the returned client; `destroy_test_session()`. Management: **`list_test_sessions()`**, **`destroy_all_test_sessions()`**, **`destroy_test_session_by_token(token)`** on a client carrying the provisioning credential only.
+
+> **Test fidelity warning.** The legacy bypass mode (omit `X-Test-Auth`) erases public-key context entirely — `isPublicKeyContext()` returns false for every request, so role gates that reject public keys silently pass in tests and fail in production. The SDK helpers default to `'required'` as of this release; explicitly opt into `'bypass'` only when you've verified the test does not depend on auth/role behavior. Use `'preserve'` to get production-faithful auth without writing ABAC policies for the test tenant.
 
 **A fresh test session is an empty tenant with zero policies.** With `X-Test-Auth: required`, ABAC default-deny applies until you bootstrap user isolation and/or policies. Typical `POST /api/v1/test/sessions` body:
 
@@ -606,8 +608,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 +624,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 +676,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 +889,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 +1108,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 +1634,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.3.0",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",