@xcitedbs/client 0.2.16 → 0.2.18

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, Flags, JsonDocumentBatchItem, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, Flags, JsonDocumentBatchItem, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -422,10 +422,13 @@ export declare class XCiteDBClient {
     /**
      * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
      * For storing JSON data by key, use `writeJsonDocument`.
+     *
+     * On cooperative-lock conflict the server returns **423** with a {@link LockConflictBody} shape in {@link XCiteDBError.body}.
      */
     writeXmlDocument(xml: string, options?: WriteDocumentOptions): Promise<void>;
     /**
      * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
+     * Rows with `error === 'lock_conflict'` include `current_lock` (code **423** per row).
      */
     writeXmlDocumentsBatch(items: XmlDocumentBatchItem[]): Promise<DocumentBatchResponse>;
     /**
@@ -460,9 +463,33 @@ export declare class XCiteDBClient {
     queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;
     queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string): Promise<T>;
     clearMeta(query: XCiteQuery): Promise<boolean>;
-    acquireLock(identifier: string, expires?: number): Promise<LockInfo>;
+    /**
+     * Acquire a cooperative lock. On exclusive conflict the server returns HTTP 409 with a
+     * {@link LockConflictBody} body (thrown as {@link XCiteDBError} with `.status === 409`).
+     */
+    acquireLock(identifier: string, expiresOrOpts?: number | AcquireLockOptions): Promise<LockInfo>;
+    /**
+     * Release a lock. **404** with {@link LockUnknownBody} if the lock id is unknown; **410** with
+     * {@link LockExpiredBody} if the lock TTL expired and was garbage-collected (same server process hint).
+     */
     releaseLock(identifier: string, lockId: string): Promise<boolean>;
-    findLocks(identifier: string): Promise<LockInfo[]>;
+    /**
+     * Force-release a lock using `force_unlock` ABAC authority. Pass the **raw** stored identifier
+     * from {@link findLocks} (no iso-prefix); often the path as returned by the server for another principal.
+     */
+    forceReleaseLock(identifier: string, lockId: string): Promise<boolean>;
+    /**
+     * Extend lock TTL (holder must match). **404** {@link LockUnknownBody} / **410** {@link LockExpiredBody}
+     * behave like {@link releaseLock}.
+     */
+    extendLock(identifier: string, lockId: string, ttlSeconds: number): Promise<LockInfo>;
+    /**
+     * List locks visible under the given path. Pass `metaId` style paths (e.g. `/spaces/owner/docs/docId`).
+     * With `{ asPrefix: true }`, calls `GET /api/v1/locks?prefix=...` (same truncation rules as `identifier`).
+     */
+    findLocks(identifier: string, opts?: {
+        asPrefix?: boolean;
+    }): Promise<LockInfo[]>;
     /**
      * Run Unquery (`POST /api/v1/unquery`): declarative analytics over documents matching `query`.
      * The `unquery` argument is a JSON template; keys are output fields, string values are expressions.

package/dist/client.js

@@ -1194,6 +1194,8 @@ class XCiteDBClient {
     /**
      * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
      * For storing JSON data by key, use `writeJsonDocument`.
+     *
+     * On cooperative-lock conflict the server returns **423** with a {@link LockConflictBody} shape in {@link XCiteDBError.body}.
      */
     async writeXmlDocument(xml, options) {
         await this.request('POST', '/api/v1/documents', {
@@ -1204,6 +1206,7 @@ class XCiteDBClient {
     }
     /**
      * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
+     * Rows with `error === 'lock_conflict'` include `current_lock` (code **423** per row).
      */
     async writeXmlDocumentsBatch(items) {
         const body = {
@@ -1424,13 +1427,29 @@ class XCiteDBClient {
         });
         return r?.ok !== false;
     }
-    async acquireLock(identifier, expires = 0) {
-        const lock = await this.request('POST', '/api/v1/locks', {
+    /**
+     * Acquire a cooperative lock. On exclusive conflict the server returns HTTP 409 with a
+     * {@link LockConflictBody} body (thrown as {@link XCiteDBError} with `.status === 409`).
+     */
+    async acquireLock(identifier, expiresOrOpts = 0) {
+        const opts = typeof expiresOrOpts === 'number' ? { ttlSeconds: expiresOrOpts } : expiresOrOpts ?? {};
+        const body = {
             identifier: this.isoPrefixId(identifier),
-            expires,
-        });
+        };
+        if (opts.ttlSeconds !== undefined && opts.ttlSeconds > 0) {
+            body.ttl_seconds = opts.ttlSeconds;
+        }
+        if (opts.mode)
+            body.mode = opts.mode;
+        if (opts.waitMs !== undefined && opts.waitMs > 0)
+            body.wait_ms = opts.waitMs;
+        const lock = await this.request('POST', '/api/v1/locks', body);
         return { ...lock, identifier: this.isoUnprefixId(lock.identifier) };
     }
+    /**
+     * Release a lock. **404** with {@link LockUnknownBody} if the lock id is unknown; **410** with
+     * {@link LockExpiredBody} if the lock TTL expired and was garbage-collected (same server process hint).
+     */
     async releaseLock(identifier, lockId) {
         const r = await this.request('DELETE', '/api/v1/locks', {
             identifier: this.isoPrefixId(identifier),
@@ -1438,8 +1457,37 @@ class XCiteDBClient {
         });
         return r?.ok !== false;
     }
-    async findLocks(identifier) {
-        const locks = await this.request('GET', `/api/v1/locks${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
+    /**
+     * Force-release a lock using `force_unlock` ABAC authority. Pass the **raw** stored identifier
+     * from {@link findLocks} (no iso-prefix); often the path as returned by the server for another principal.
+     */
+    async forceReleaseLock(identifier, lockId) {
+        const r = await this.request('DELETE', '/api/v1/locks', {
+            identifier,
+            lock_id: lockId,
+            force: true,
+        });
+        return r?.ok !== false;
+    }
+    /**
+     * Extend lock TTL (holder must match). **404** {@link LockUnknownBody} / **410** {@link LockExpiredBody}
+     * behave like {@link releaseLock}.
+     */
+    async extendLock(identifier, lockId, ttlSeconds) {
+        const lock = await this.request('PATCH', '/api/v1/locks', {
+            identifier: this.isoPrefixId(identifier),
+            lock_id: lockId,
+            ttl_seconds: ttlSeconds,
+        });
+        return { ...lock, identifier: this.isoUnprefixId(lock.identifier) };
+    }
+    /**
+     * List locks visible under the given path. Pass `metaId` style paths (e.g. `/spaces/owner/docs/docId`).
+     * With `{ asPrefix: true }`, calls `GET /api/v1/locks?prefix=...` (same truncation rules as `identifier`).
+     */
+    async findLocks(identifier, opts) {
+        const key = opts?.asPrefix ? 'prefix' : 'identifier';
+        const locks = await this.request('GET', `/api/v1/locks${buildQuery({ [key]: this.isoPrefixId(identifier) })}`);
         return Array.isArray(locks)
             ? locks.map((L) => ({ ...L, identifier: this.isoUnprefixId(L.identifier) }))
             : locks;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { XCiteDBClient } from './client';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, Flags, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, Flags, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/locks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/locks.test.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Wet tests: set XCITEDB_BASE_URL, XCITEDB_ADMIN_TOKEN, XCITEDB_TENANT_ID.
+ * Run: npm test
+ */
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const client_js_1 = require("./client.js");
+function wetEnv() {
+    const baseUrl = process.env.XCITEDB_BASE_URL?.trim();
+    const accessToken = process.env.XCITEDB_ADMIN_TOKEN?.trim();
+    const tenantId = process.env.XCITEDB_TENANT_ID?.trim();
+    if (!baseUrl || !accessToken || !tenantId)
+        return null;
+    return { baseUrl, accessToken, tenantId };
+}
+async function openTestSession(e) {
+    const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/test/sessions`;
+    const r = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${e.accessToken}`,
+            'X-Project-Id': e.tenantId,
+        },
+        body: '{}',
+    });
+    const data = (await r.json());
+    if (!r.ok || !data.session_token) {
+        throw new Error(`test session failed ${r.status}`);
+    }
+    const client = new client_js_1.XCiteDBClient({
+        baseUrl: e.baseUrl,
+        accessToken: e.accessToken,
+        platformConsole: true,
+        projectId: e.tenantId,
+        context: { project_id: e.tenantId },
+        testSessionToken: data.session_token,
+        testRequireAuth: true,
+    });
+    return { client, token: data.session_token };
+}
+const w = wetEnv();
+const wd = w ? node_test_1.describe : node_test_1.describe.skip;
+wd('locks (wet)', () => {
+    (0, node_test_1.it)('acquire, extend, release', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const { client: c, token } = await openTestSession(e);
+        try {
+            const path = '/sdk_locks/js_wet_roundtrip';
+            await c.writeJsonDocument(path, { k: 1 }, { overwrite: true });
+            const lock = await c.acquireLock(path, { ttlSeconds: 120, mode: 'exclusive' });
+            strict_1.default.ok(lock.lock_id);
+            strict_1.default.equal(lock.mode, 'exclusive');
+            const ext = await c.extendLock(path, lock.lock_id, 180);
+            strict_1.default.ok((ext.version ?? 0) >= (lock.version ?? 1));
+            const ok = await c.releaseLock(path, lock.lock_id);
+            strict_1.default.ok(ok);
+        }
+        finally {
+            await fetch(`${e.baseUrl.replace(/\/+$/, '')}/api/v1/test/sessions/current`, {
+                method: 'DELETE',
+                headers: { 'X-Test-Session': token },
+            });
+        }
+    });
+});

package/dist/types.d.ts

@@ -253,6 +253,38 @@ export interface LockInfo {
     time: number;
     expiration: number;
     branch: string;
+    holder?: string;
+    mode?: 'exclusive' | 'advisory';
+    version?: number;
+    acquired_at?: string;
+    expires_at?: string;
+}
+/** Options for {@link XCiteDBClient.acquireLock}. */
+export interface AcquireLockOptions {
+    /** Seconds until lock expires; server clamps (default 60). */
+    ttlSeconds?: number;
+    mode?: 'exclusive' | 'advisory';
+    /** Max milliseconds to wait when another exclusive lock is held. */
+    waitMs?: number;
+}
+/**
+ * Body returned with HTTP **409** on `acquireLock` conflict, or **423** on XML document write blocked by a lock.
+ * Inspect via {@link XCiteDBError} (`status` and `body`).
+ */
+export interface LockConflictBody {
+    error: 'lock_conflict';
+    current_lock: LockInfo;
+}
+/** Body returned with HTTP **410** when `extendLock` / `releaseLock` target a lock id that TTL-expired recently. */
+export interface LockExpiredBody {
+    error: 'lock_expired';
+    message?: string;
+    expired_at?: number;
+}
+/** Body returned with HTTP **404** when the lock id does not exist (or never existed) for the given identifier. */
+export interface LockUnknownBody {
+    error: 'lock_unknown';
+    message?: string;
 }
 export interface TokenPair {
     access_token: string;
@@ -374,6 +406,8 @@ export interface DocumentBatchResultRow {
     ok: boolean;
     error?: string;
     code?: number;
+    /** Present when `error === 'lock_conflict'` (HTTP-style code 423 in batch row). */
+    current_lock?: LockInfo;
 }
 export interface DocumentBatchResponse {
     results: DocumentBatchResultRow[];

package/llms-full.txt

@@ -843,17 +843,43 @@ Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_co
 
 ## Acquire lock
 
-**`POST /api/v1/locks`** — `{ "identifier": "/book/ch1", "expires": 600 }`
+**`POST /api/v1/locks`**
 
-Returns lock info. **`409`** if already locked.
+```json
+{
+  "identifier": "/book/ch1",
+  "ttl_seconds": 120,
+  "mode": "exclusive",
+  "wait_ms": 5000
+}
+```
+
+- **`ttl_seconds`** preferred; legacy **`expires`** is an alias. Omitted or `0` → server default (**60s**), clamped to **5–600s**.
+- **`mode`**: `exclusive` (blocks other exclusives; multiple `advisory` locks can coexist; an existing **exclusive** blocks new `advisory`).
+- **`wait_ms`**: optional 0–30000; server retries acquire every ~100ms until granted or timeout, then **`409`** with `{ "error":"lock_conflict", "current_lock": { ... } }`.
+
+Returns **`201`** with `LockInfo`: `lock_id`, `identifier`, `time`, `expiration`, `branch`, `holder`, `mode`, `version`, `acquired_at`, `expires_at` (ISO UTC).
+
+## Extend lock
+
+**`PATCH /api/v1/locks`** — `{ "identifier": "...", "lock_id": "...", "ttl_seconds": 120 }` — holder-only; bumps `version` and sets new expiry from **now**.
 
 ## Release lock
 
-**`DELETE /api/v1/locks`** — `{ "identifier": "/book/ch1", "lock_id": "..." }`
+**`DELETE /api/v1/locks`** — `{ "identifier": "...", "lock_id": "...", "force": false }`
+
+- Normal release: **`403`** `lock_holder_mismatch` if the lock exists but the identifier path does not match this principal (e.g. user isolation); **`404`** if `lock_id` unknown.
+- **`force: true`**: deletes the lock blob without path check; requires ABAC **`force_unlock`** (policies with **`write`** still satisfy this via synonym fallback).
 
 ## Query locks
 
-**`GET /api/v1/locks?identifier=...`** — Lists active locks.
+**`GET /api/v1/locks?identifier=...`** or **`?prefix=...`** — Lists active locks (same resolution). Response entries include **`holder`**.
+
+### Caveats
+
+- SDK **user isolation** rewrites identifiers; **`findLocks`** returns the **stored** path in `identifier` — use that for **`forceReleaseLock`** when releasing another principal’s lock.
+- Locks are keyed on the **resolved path at acquire time**. Renaming/moving an ancestor invalidates listing under the new path; **release locks before structural moves**, then reacquire.
+- **`lock_expired`** events are emitted when an expired lock row is garbage-collected on read (best-effort), not on a wall-clock timer.
 
 ---
 
@@ -1447,8 +1473,10 @@ interface DatabaseContext {
 - **Deprecated:** `diff(from: DiffRef, …)` — alias of `compare`
 
 ### Locks
-- `acquireLock(identifier, expires?)` → `LockInfo`
+- `acquireLock(identifier, ttlSeconds | { ttlSeconds, mode, waitMs })` → `LockInfo` (throws **`XCiteDBError`** with **409** and `lock_conflict` body on conflict)
 - `releaseLock(identifier, lockId)` → `boolean`
+- `forceReleaseLock(identifier, lockId)` → `boolean` (raw identifier when using isolation)
+- `extendLock(identifier, lockId, ttlSeconds)` → `LockInfo`
 - `findLocks(identifier)` → `LockInfo[]`
 
 ### Search

package/llms.txt

@@ -178,10 +178,12 @@ await client.publishWorkspace('', 'feature-x'); // publish into root (default) w
 // Attach JSON metadata to a document
 await client.addMeta('/manual/v1/intro', { status: 'draft', owner: 'alice' });
 
-// Acquire a cooperative lock
-const lock = await client.acquireLock('/manual/v1/intro');
+// Cooperative locks (exclusive blocks others; advisory is informational)
+const lock = await client.acquireLock('/manual/v1/intro', { ttlSeconds: 120, mode: 'exclusive' });
 // ... edit ...
 await client.releaseLock('/manual/v1/intro', lock.lock_id);
+// Force-release (requires force_unlock ABAC): use raw identifier from findLocks, no iso-prefix
+// await client.forceReleaseLock(storedIdentifier, lock.lock_id);
 
 // Full-text search (embedded XciteFTS; optional temporal filters on the query body)
 const results = await client.search({ query: 'installation guide', limit: 20, mode: 'fts' });
@@ -266,9 +268,12 @@ interface XCiteDBClientOptions {
 - **Deprecated aliases:** `withBranch`, `createBranch`, `listBranches`, `mergeBranch`, `deleteBranch`, `createCommit`, `listCommits`, `rollbackToCommit`, `cherryPick`, `diff`, `createTag`, `listTags`, `deleteTag` (same HTTP behavior)
 
 **Locks:**
-- `acquireLock(identifier, expires?)` — Acquire cooperative lock
-- `releaseLock(identifier, lockId)` — Release lock
-- `findLocks(identifier)` — Query active locks
+- `acquireLock(identifier, options?)` — `options`: `ttlSeconds` (server clamps 5–600, default 60), `mode` `exclusive`|`advisory`, `waitMs` (0–30000). Legacy `acquireLock(identifier, expiresNumber)` still works (maps to `ttlSeconds`). Body fields `ttl_seconds` and legacy `expires` accepted server-side.
+- `releaseLock(identifier, lockId)` — Holder release; 403 `lock_holder_mismatch` if path does not match principal; 404 if unknown `lockId`
+- `forceReleaseLock(identifier, lockId)` — Admin/owner release; pass **raw** stored identifier from `findLocks` when using user isolation
+- `extendLock(identifier, lockId, ttlSeconds)` — Refresh TTL (holder only)
+- `findLocks(identifier)` — Returns `holder`, `mode`, `version`, `acquired_at`, `expires_at`
+- ABAC actions: `lock`, `unlock`, `force_unlock`; policies with `write` only still authorize all three (compat)
 
 **Search & Analytics:**
 - `search(query)` — Full-text search (embedded FTS). Optional **`at_date`**, **`date_from`**, **`date_to`** on the query for temporal keyword search (use **`mode: 'fts'`**). Hits may include **`valid_from`** / **`valid_to`** (7-char internal keys).

package/package.json

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

package/unquery-ai-guide.md

@@ -1128,6 +1128,7 @@ Before returning a query, scan it against this checklist. These rules come strai
 ## 13. Cross-reference
 
 - [`docs/unquery-grammar.md`](./unquery-grammar.md) — Parser-faithful EBNF, AST nodes, lexer tokens, every static rule. Use this for syntax-checking, error attribution, or when extending Unquery tooling. MCP resource: `xcitedb://unquery-grammar`.
+- [Unquery playground](https://unquery-playground.vercel.app/) — Browser tool to try templates and expressions interactively (no XCiteDB server required for basic experiments).
 - [`web/src/docs/content/unquery-language-reference.html`](../web/src/docs/content/unquery-language-reference.html) — Human-oriented reference manual.
 - [`web/src/docs/content/unquery-tutorial.html`](../web/src/docs/content/unquery-tutorial.html) — Hands-on tutorial with the employees dataset.
 - XCiteDB-specific bits (workspaces, branches, identifiers, `->$date`, `->$branch`, `->$all`, `$xml*`, `$attr`, `$xpath`, `$node_date`, `$data_date`) only apply when running against XCiteDB. With the `unq` CLI on plain JSON files, ignore them.

package/unquery-grammar.md

@@ -2,7 +2,7 @@
 
 This document is the **ground truth** for Unquery syntax as implemented in the XCiteDB engine. It is derived from `TParser` in [`XCiteDB2/XCiteDB/src/TemplateParser.cpp`](../XCiteDB2/XCiteDB/src/TemplateParser.cpp) and the AST in [`XCiteDB2/XCiteDB/include/TemplateQuery.h`](../XCiteDB2/XCiteDB/include/TemplateQuery.h). Use it for **syntax checking** and **conservative static typing** of expressions inside JSON templates.
 
-Human-oriented prose and examples: [Unquery reference manual](../web/src/docs/content/unquery-language-reference.html) (Asciidoc source: `web/src/docs/unquery-source/unquery-language-reference.adoc`).
+Human-oriented prose and examples: [Unquery reference manual](../web/src/docs/content/unquery-language-reference.html) (Asciidoc source: `web/src/docs/unquery-source/unquery-language-reference.adoc`). Try queries in the browser: [Unquery playground](https://unquery-playground.vercel.app/).
 
 ---