@xcitedbs/client 0.2.6 → 0.2.8

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteQuery } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteQuery } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -129,17 +129,131 @@ export declare class XCiteDBClient {
     deleteAppUser(userId: string): Promise<void>;
     updateAppUserGroups(userId: string, groups: string[]): Promise<void>;
     updateAppUserStatus(userId: string, status: 'active' | 'disabled' | 'pending_verification'): Promise<void>;
+    /**
+     * Create an ABAC policy (`POST /api/v1/security/policies`). Requires admin/editor role.
+     * Use `conditions.expression` for attribute-based rules (same predicate syntax as Unquery `?` conditions).
+     * Policy actions: `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+     *
+     * @example Tenant isolation: first path segment must equal app-user attribute `tenant_code`.
+     * ```ts
+     * await client.createPolicy('tenant_isolation', {
+     *   effect: 'allow',
+     *   priority: 100,
+     *   subjects: { type: 'app_user' },
+     *   actions: ['read'],
+     *   resources: { identifiers: [{ match_start: '/' }] },
+     *   conditions: { expression: 'resource.path[0] = subject.attr.tenant_code' },
+     * });
+     * ```
+     *
+     * @example Deny viewers write access under `/admin/`.
+     * ```ts
+     * await client.createPolicy('deny_viewers_admin', {
+     *   effect: 'deny',
+     *   priority: 10,
+     *   subjects: { type: 'app_user', groups: ['viewers'] },
+     *   resources: { identifiers: [{ match_start: '/admin/' }] },
+     *   actions: ['write', 'delete', 'meta:write'],
+     * });
+     * ```
+     *
+     * @example Branch-only rule via `conditions.branches`.
+     * ```ts
+     * await client.createPolicy('staging_only', {
+     *   effect: 'allow',
+     *   priority: 50,
+     *   subjects: { type: 'app_user', groups: ['qa'] },
+     *   actions: ['read', 'write'],
+     *   resources: { identifiers: [{ match_start: '/staging/' }] },
+     *   conditions: { branches: ['stg', 'stg*'] },
+     * });
+     * ```
+     */
     createPolicy(policyId: string, policy: SecurityPolicy): Promise<StoredPolicyResponse>;
     listPolicies(): Promise<Record<string, SecurityPolicy>>;
     getPolicy(policyId: string): Promise<StoredPolicyResponse>;
     updatePolicy(policyId: string, policy: SecurityPolicy): Promise<PolicyUpdateResponse>;
     deletePolicy(policyId: string): Promise<void>;
+    /**
+     * Create or update a trigger (`POST /api/v1/triggers`). Definitions live under `/_xcitedb/triggers`.
+     * After matching events, the server runs `action.unquery` over `action.query` and writes JSON to
+     * `action.meta_path` on `action.target_identifier` (use `"$trigger_identifier"` for the firing doc).
+     * Unquery can use `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`.
+     *
+     * @example On meta change under `/projects/`, append a snapshot entry to an index document.
+     * ```ts
+     * await client.upsertTrigger('project_meta_index', {
+     *   event: 'meta_changed',
+     *   match: {
+     *     identifiers: [{ match_start: '/projects/' }],
+     *     match_meta_path: 'status',
+     *   },
+     *   action: {
+     *     query: { match: '$trigger_identifier' },
+     *     unquery: { lastId: '$trigger_identifier', path: '$trigger_meta_path' },
+     *     target_identifier: '/indexes/project_meta',
+     *     meta_path: 'entries',
+     *     mode: 'append',
+     *   },
+     * });
+     * ```
+     *
+     * @example On document write, write a computed summary onto the same identifier's meta.
+     * ```ts
+     * await client.upsertTrigger('doc_written_summary', {
+     *   event: 'document_written',
+     *   match: { identifiers: [{ match_start: '/articles/' }] },
+     *   action: {
+     *     query: { match: '$trigger_identifier' },
+     *     unquery: { id: '$identifier', nodeCount: '$count' },
+     *     target_identifier: '$trigger_identifier',
+     *     meta_path: 'stats',
+     *   },
+     * });
+     * ```
+     */
     upsertTrigger(triggerId: string, trigger: TriggerDefinition): Promise<StoredTriggerResponse>;
     listTriggers(): Promise<Record<string, TriggerDefinition>>;
     getTrigger(name: string): Promise<StoredTriggerResponse>;
     deleteTrigger(name: string): Promise<void>;
+    /**
+     * Dry-run access check (`POST /api/v1/security/check`). Returns `effect` and optional `matched_policy_id`.
+     * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+     *
+     * @example
+     * ```ts
+     * const r = await client.checkAccess(
+     *   {
+     *     type: 'app_user',
+     *     user_id: 'u1',
+     *     email: 'alice@example.com',
+     *     groups: ['editors'],
+     *     role: 'app_user',
+     *     attributes: { tenant_code: 'acme', level: 5 },
+     *   },
+     *   '/acme/reports/q1',
+     *   'read',
+     *   undefined,
+     *   'main'
+     * );
+     * console.log(r.effect, r.matched_policy_id);
+     * ```
+     */
     checkAccess(subject: PolicySubjectInput, identifier: string, action: string, metaPath?: string, branch?: string): Promise<AccessCheckResult>;
     getSecurityConfig(): Promise<SecurityConfig>;
+    /**
+     * Update tenant security defaults (`PUT /api/v1/security/config`). When ABAC is enabled, pair
+     * `app_user_default_effect: 'deny'` with explicit allow policies for least privilege.
+     *
+     * @example
+     * ```ts
+     * await client.updateSecurityConfig({
+     *   app_user_default_effect: 'deny',
+     *   default_effect: 'allow',
+     *   developer_bypass: true,
+     * });
+     * ```
+     */
     updateSecurityConfig(config: Partial<SecurityConfig>): Promise<void>;
     createBranch(name: string, fromBranch?: string, fromDate?: string): Promise<void>;
     deleteBranch(name: string): Promise<void>;
@@ -230,7 +344,32 @@ export declare class XCiteDBClient {
     acquireLock(identifier: string, expires?: number): Promise<LockInfo>;
     releaseLock(identifier: string, lockId: string): Promise<boolean>;
     findLocks(identifier: string): Promise<LockInfo[]>;
-    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: unknown): Promise<T>;
+    /**
+     * 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.
+     *
+     * @example Project a meta field into a result key.
+     * ```ts
+     * const out = await client.unquery<{ tag: string }>(
+     *   { match_start: '/manual/' },
+     *   { title: 'chapter_title' }
+     * );
+     * ```
+     *
+     * @example Count matching documents.
+     * ```ts
+     * const out = await client.unquery<{ total: number }>({ match_start: '/orders/' }, { total: '$count' });
+     * ```
+     *
+     * @example XPath from XML (string value must escape quotes for TS).
+     * ```ts
+     * const out = await client.unquery<{ heading: string }>(
+     *   { match: '/book/ch1' },
+     *   { heading: '$xpath("//h1")' }
+     * );
+     * ```
+     */
+    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: UnqueryTemplate): Promise<T>;
     search(q: TextSearchQuery): Promise<TextSearchResult>;
     reindex(): Promise<{
         status: string;

package/dist/client.js

@@ -502,6 +502,46 @@ class XCiteDBClient {
         await this.request('PUT', `/api/v1/app/users/${encodeURIComponent(userId)}/status`, { status });
     }
     // --- Security policies (developer admin/editor) ---
+    /**
+     * Create an ABAC policy (`POST /api/v1/security/policies`). Requires admin/editor role.
+     * Use `conditions.expression` for attribute-based rules (same predicate syntax as Unquery `?` conditions).
+     * Policy actions: `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+     *
+     * @example Tenant isolation: first path segment must equal app-user attribute `tenant_code`.
+     * ```ts
+     * await client.createPolicy('tenant_isolation', {
+     *   effect: 'allow',
+     *   priority: 100,
+     *   subjects: { type: 'app_user' },
+     *   actions: ['read'],
+     *   resources: { identifiers: [{ match_start: '/' }] },
+     *   conditions: { expression: 'resource.path[0] = subject.attr.tenant_code' },
+     * });
+     * ```
+     *
+     * @example Deny viewers write access under `/admin/`.
+     * ```ts
+     * await client.createPolicy('deny_viewers_admin', {
+     *   effect: 'deny',
+     *   priority: 10,
+     *   subjects: { type: 'app_user', groups: ['viewers'] },
+     *   resources: { identifiers: [{ match_start: '/admin/' }] },
+     *   actions: ['write', 'delete', 'meta:write'],
+     * });
+     * ```
+     *
+     * @example Branch-only rule via `conditions.branches`.
+     * ```ts
+     * await client.createPolicy('staging_only', {
+     *   effect: 'allow',
+     *   priority: 50,
+     *   subjects: { type: 'app_user', groups: ['qa'] },
+     *   actions: ['read', 'write'],
+     *   resources: { identifiers: [{ match_start: '/staging/' }] },
+     *   conditions: { branches: ['stg', 'stg*'] },
+     * });
+     * ```
+     */
     async createPolicy(policyId, policy) {
         return this.request('POST', '/api/v1/security/policies', {
             policy_id: policyId,
@@ -524,6 +564,44 @@ class XCiteDBClient {
         await this.request('DELETE', `/api/v1/security/policies/${encodeURIComponent(policyId)}`);
     }
     // --- Triggers (developer admin/editor) ---
+    /**
+     * Create or update a trigger (`POST /api/v1/triggers`). Definitions live under `/_xcitedb/triggers`.
+     * After matching events, the server runs `action.unquery` over `action.query` and writes JSON to
+     * `action.meta_path` on `action.target_identifier` (use `"$trigger_identifier"` for the firing doc).
+     * Unquery can use `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`.
+     *
+     * @example On meta change under `/projects/`, append a snapshot entry to an index document.
+     * ```ts
+     * await client.upsertTrigger('project_meta_index', {
+     *   event: 'meta_changed',
+     *   match: {
+     *     identifiers: [{ match_start: '/projects/' }],
+     *     match_meta_path: 'status',
+     *   },
+     *   action: {
+     *     query: { match: '$trigger_identifier' },
+     *     unquery: { lastId: '$trigger_identifier', path: '$trigger_meta_path' },
+     *     target_identifier: '/indexes/project_meta',
+     *     meta_path: 'entries',
+     *     mode: 'append',
+     *   },
+     * });
+     * ```
+     *
+     * @example On document write, write a computed summary onto the same identifier's meta.
+     * ```ts
+     * await client.upsertTrigger('doc_written_summary', {
+     *   event: 'document_written',
+     *   match: { identifiers: [{ match_start: '/articles/' }] },
+     *   action: {
+     *     query: { match: '$trigger_identifier' },
+     *     unquery: { id: '$identifier', nodeCount: '$count' },
+     *     target_identifier: '$trigger_identifier',
+     *     meta_path: 'stats',
+     *   },
+     * });
+     * ```
+     */
     async upsertTrigger(triggerId, trigger) {
         return this.request('POST', '/api/v1/triggers', {
             trigger_id: triggerId,
@@ -544,6 +622,29 @@ class XCiteDBClient {
         const q = buildQuery({ name });
         await this.request('DELETE', `/api/v1/triggers${q}`);
     }
+    /**
+     * Dry-run access check (`POST /api/v1/security/check`). Returns `effect` and optional `matched_policy_id`.
+     * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+     *
+     * @example
+     * ```ts
+     * const r = await client.checkAccess(
+     *   {
+     *     type: 'app_user',
+     *     user_id: 'u1',
+     *     email: 'alice@example.com',
+     *     groups: ['editors'],
+     *     role: 'app_user',
+     *     attributes: { tenant_code: 'acme', level: 5 },
+     *   },
+     *   '/acme/reports/q1',
+     *   'read',
+     *   undefined,
+     *   'main'
+     * );
+     * console.log(r.effect, r.matched_policy_id);
+     * ```
+     */
     async checkAccess(subject, identifier, action, metaPath, branch) {
         const body = { subject, identifier, action };
         if (metaPath !== undefined)
@@ -555,6 +656,19 @@ class XCiteDBClient {
     async getSecurityConfig() {
         return this.request('GET', '/api/v1/security/config');
     }
+    /**
+     * Update tenant security defaults (`PUT /api/v1/security/config`). When ABAC is enabled, pair
+     * `app_user_default_effect: 'deny'` with explicit allow policies for least privilege.
+     *
+     * @example
+     * ```ts
+     * await client.updateSecurityConfig({
+     *   app_user_default_effect: 'deny',
+     *   default_effect: 'allow',
+     *   developer_bypass: true,
+     * });
+     * ```
+     */
     async updateSecurityConfig(config) {
         await this.request('PUT', '/api/v1/security/config', config);
     }
@@ -887,6 +1001,31 @@ class XCiteDBClient {
     async findLocks(identifier) {
         return this.request('GET', `/api/v1/locks${buildQuery({ identifier })}`);
     }
+    /**
+     * 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.
+     *
+     * @example Project a meta field into a result key.
+     * ```ts
+     * const out = await client.unquery<{ tag: string }>(
+     *   { match_start: '/manual/' },
+     *   { title: 'chapter_title' }
+     * );
+     * ```
+     *
+     * @example Count matching documents.
+     * ```ts
+     * const out = await client.unquery<{ total: number }>({ match_start: '/orders/' }, { total: '$count' });
+     * ```
+     *
+     * @example XPath from XML (string value must escape quotes for TS).
+     * ```ts
+     * const out = await client.unquery<{ heading: string }>(
+     *   { match: '/book/ch1' },
+     *   { heading: '$xpath("//h1")' }
+     * );
+     * ```
+     */
     async unquery(query, unquery) {
         return this.request('POST', '/api/v1/unquery', { query, unquery });
     }

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, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, UnqueryResult, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -20,6 +20,13 @@ export type JsonDocumentData = Record<string, unknown>;
 export type MetaValue = unknown;
 /** Result of `unquery` (shape depends on the unquery definition). */
 export type UnqueryResult = unknown;
+/**
+ * Unquery DSL template document. Object keys become output field names; string values are
+ * expressions (e.g. `"$count"`, `"$xpath(\"//title\")"`, or a meta field name). Supports nested
+ * objects, arrays, and `$`-prefixed builtins. See `llms-full.txt` shipped with this package for
+ * the full DSL reference.
+ */
+export type UnqueryTemplate = Record<string, unknown>;
 /** Typical `POST /api/v1/platform/auth/register` response (fields vary by registration policy). */
 export interface PlatformRegisterResult {
     user_id?: string;
@@ -340,6 +347,12 @@ export interface PolicyResources {
 }
 export interface PolicyConditions {
     branches?: string[];
+    /**
+     * Unquery condition expression.
+     * Policies: evaluated against `{ subject, resource, env }`.
+     * Triggers: evaluated against `{ trigger, value, resource, env }` (see server docs).
+     */
+    expression?: string;
 }
 export interface SecurityPolicy {
     description?: string;
@@ -358,6 +371,8 @@ export interface PolicySubjectInput {
     groups?: string[];
     role?: string;
     username?: string;
+    /** Custom app-user attributes (mirrors stored user `attributes`); used by `conditions.expression`. */
+    attributes?: Record<string, unknown>;
 }
 export interface SecurityConfig {
     default_effect: 'allow' | 'deny';
@@ -386,8 +401,29 @@ export interface PolicyUpdateResponse {
     policy: SecurityPolicy;
     warnings?: string[];
 }
-/** Stored trigger document under /_xcitedb/triggers (server-defined shape). */
-export type TriggerDefinition = Record<string, unknown>;
+/** `match` block for stored triggers (`/_xcitedb/triggers`). */
+export interface TriggerMatch {
+    /** Non-empty array of identifier patterns (same shape as policy `resources.identifiers`). */
+    identifiers: PolicyIdentifierPattern[];
+    match_meta_path?: string;
+    match_operation?: 'set' | 'append' | 'delete';
+}
+/** `action` block: run unquery and write result to target meta. */
+export interface TriggerAction {
+    query: XCiteQuery;
+    unquery: UnqueryTemplate;
+    target_identifier: string;
+    meta_path: string;
+    mode?: 'set' | 'append';
+}
+/** Stored trigger document under /_xcitedb/triggers. */
+export interface TriggerDefinition {
+    enabled?: boolean;
+    event: 'meta_changed' | 'document_written' | 'document_deleted';
+    match: TriggerMatch;
+    conditions?: PolicyConditions;
+    action: TriggerAction;
+}
 export interface StoredTriggerResponse {
     trigger_id: string;
     trigger: TriggerDefinition;

package/llms-full.txt

@@ -26,7 +26,7 @@ Before reading the full reference, note these critical differences from typical
 
 9. **OpenAPI:** See repository `docs/openapi.yaml` for a machine-readable route map.
 
-10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, normal JWT/API-key checks are bypassed for those requests (synthetic admin for wet tests). Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
+10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
 
 ## Common Pitfalls
 
@@ -48,6 +48,8 @@ Before reading the full reference, note these critical differences from typical
 
 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()`.
 
+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, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Ephemeral test sessions" below.
+
 ---
 
 # Part 1: Product Overview
@@ -186,13 +188,15 @@ Browser and mobile apps can use OAuth2-style flows against `/api/v1/app/auth/oau
 
 # Ephemeral test sessions
 
+> **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised. Provision a session in `beforeAll` / `setUp` / test fixture setup and destroy it in `afterAll` / `tearDown` / fixture teardown.
+
 For **integration and wet tests** against a shared BaaS host without touching production data:
 
 | 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). |
 | **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:** test requests **skip** normal auth (convenient for automated tests). **`X-Test-Auth: required`:** require normal Bearer or API key; identity and ABAC apply, but data still comes from the test session DB. |
+| **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. |
 | **CORS** | Browsers may need **`X-Test-Session`** and **`X-Test-Auth`** in the deployment’s allowed CORS headers (defaults include them). |
 
@@ -202,6 +206,126 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 - **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor.
 - **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key` (and optional `test_require_auth`); `destroy_test_session()`.
 
+**JavaScript/TypeScript — complete test scaffold (Vitest / Jest):**
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { XCiteDBClient } from '@xcitedbs/client';
+
+describe('XciteDB integration', () => {
+  let client: XCiteDBClient;
+
+  beforeAll(async () => {
+    // Provisions an isolated, throwaway LMDB — production data is never touched.
+    client = await XCiteDBClient.createTestSession({
+      baseUrl: process.env.XCITEDB_URL ?? 'http://localhost:8080',
+      apiKey: process.env.XCITEDB_API_KEY!,
+    });
+  });
+
+  afterAll(async () => {
+    await client.destroyTestSession();
+  });
+
+  it('writes and reads a JSON document', async () => {
+    await client.writeJsonDocument('test.config', { env: 'test' });
+    const doc = await client.readJsonDocument<{ env: string }>('test.config');
+    expect(doc).toMatchObject({ env: 'test' });
+  });
+
+  it('writes and reads an XML document', async () => {
+    await client.writeXmlDocument(
+      '<doc db:identifier="/test/doc1"><title>Hello</title></doc>'
+    );
+    const xml = await client.queryByIdentifier('/test/doc1', 'FirstMatch');
+    expect(xml).toContain('<title>Hello</title>');
+  });
+
+  it('creates a branch, commits, and merges', async () => {
+    await client.withBranch('feature-test', async (c) => {
+      await c.writeJsonDocument('test.feature', { active: true });
+    }, { message: 'Add feature flag', autoMerge: true });
+    const doc = await client.readJsonDocument<{ active: boolean }>('test.feature');
+    expect(doc.active).toBe(true);
+  });
+});
+```
+
+**Python — complete test scaffold (pytest + pytest-asyncio):**
+
+```python
+import os
+import pytest
+import pytest_asyncio
+from xcitedb import XCiteDBClient
+
+@pytest_asyncio.fixture
+async def db():
+    # Provisions an isolated, throwaway LMDB — production data is never touched.
+    async with XCiteDBClient.test_session(
+        os.environ.get("XCITEDB_URL", "http://localhost:8080"),
+        api_key=os.environ["XCITEDB_API_KEY"],
+    ) as client:
+        yield client  # session is destroyed automatically on exit
+
+@pytest.mark.asyncio
+async def test_json_document(db):
+    await db.write_json_document("test.config", {"env": "test"})
+    doc = await db.read_json_document("test.config")
+    assert doc == {"env": "test"}
+
+@pytest.mark.asyncio
+async def test_xml_document(db):
+    await db.write_xml_document(
+        '<doc db:identifier="/test/doc1"><title>Hello</title></doc>'
+    )
+    result = await db.query_by_identifier("/test/doc1", "FirstMatch")
+    assert "<title>Hello</title>" in result
+
+@pytest.mark.asyncio
+async def test_branch_and_merge(db):
+    async with db.with_branch("feature-test", message="Add flag", auto_merge=True):
+        await db.put("test.feature", {"active": True})
+    doc = await db.get("test.feature")
+    assert doc["active"] is True
+```
+
+**C++ — complete test scaffold (Catch2):**
+
+```cpp
+#include <xcitedb/xcitedb.hpp>
+#include <catch2/catch_test_macros.hpp>
+#include <cstdlib>
+
+// Provisions an isolated, throwaway LMDB — production data is never touched.
+static xcitedb::XCiteDBClient make_test_client() {
+    xcitedb::XCiteDBClientOptions opt;
+    opt.base_url = std::getenv("XCITEDB_URL") ? std::getenv("XCITEDB_URL")
+                                               : "http://127.0.0.1:8080";
+    opt.api_key = std::getenv("XCITEDB_API_KEY");
+    return xcitedb::XCiteDBClient::create_test_session(opt);
+}
+
+TEST_CASE("XciteDB JSON document round-trip") {
+    auto client = make_test_client();
+    client.write_json_document("test.config", R"({"env":"test"})");
+    auto doc = client.read_json_document("test.config");
+    REQUIRE(doc.find("\"env\"") != std::string::npos);
+    REQUIRE(doc.find("\"test\"") != std::string::npos);
+    client.destroy_test_session();
+}
+
+TEST_CASE("XciteDB XML document round-trip") {
+    auto client = make_test_client();
+    client.write_xml_document(
+        R"(<doc db:identifier="/test/doc1"><title>Hello</title></doc>)"
+    );
+    auto xml = client.query_by_identifier("/test/doc1", "FirstMatch");
+    REQUIRE(xml.find("<title>Hello</title>") != std::string::npos);
+    client.destroy_test_session();
+}
+```
+
 ---
 
 # Health, version & discovery
@@ -435,6 +559,122 @@ Executes a structured query document (JSON DSL) for advanced analytics, bulk exp
 
 Unquery supports: hierarchical navigation (self, parents, ancestors, children, descendants), XPath queries on XML, JSON path navigation, counts, sums, string operations, type casting, and conditional branching. Results are always structured JSON.
 
+## Unquery DSL reference
+
+The `unquery` body is a **JSON template**: each **object key** names an output field; each **value** is either a nested object/array (recursed) or a **string parsed as an expression**. Arrays produce JSON arrays in order.
+
+### Core expression builtins (string values)
+
+- **Document / path:** `$identifier`, `$identifier(n)` (path segment by index), `$key`, `$index`, `$path`
+- **XML:** `$xpath("expr")`, `$lxpath("expr")` (leaf / no-children variant), `$xml`, `$xml_no_children`, `$node`, `$attr("name")`, `$child("name")`, `$text(expr)`
+- **Aggregates / size:** `$count`, `$sum(expr)`, `$avg(expr)`, `$min(expr)`, `$max(expr)`, `$size(expr)` (array length), `$length(expr)` (string length)
+- **String ops:** `$lower(expr)`, `$upper(expr)`, `$substr(s,start,len?)`, `$replace(src,from,to,all?)`, `$split(s,delim)`, `$join(arr,delim?)`, `$find`, `$ifind`
+- **Time / casts:** `$now`, `$to_time(expr,fmt?)`, `$time_to_str(expr,fmt?)`, `$string`, `$number`, `$int`, `$float`, `$bool(expr)`
+- **Control:** `$if(cond, then, else)`, `$var(name)` or `%name` (template variables), `$call(name)` (user `#func`), `$prev(default)`
+- **Other:** `$node_date`, `$data_date(expr?)`, `$in_filter("name")`, `$file`, `$csv`, `$env`, `$filename` (last three blocked in safety mode for standalone `evaluateCondition`)
+
+### Key-side syntax (JSON object member **names**, not values)
+
+- Plain names, dotted paths, `[index]`, `$(expression)` / `$expr` for dynamic keys
+- **`#if`**, **`#var`**, **`#assign`**, **`#func name (a,b,…)`**, **`#exists`**, **`#notexists`**, **`#return`**, **`#returnif`**
+- Suffixes on keys: `?condition` (filter branch), `@ ascending` / `@ descending` / `@ unique_ascending` / `@ unique_descending` on values
+- **Context navigation** after `->` (in key paths): `$self`, `$parent`, `$ancestors`, `$ancestors_and_self`, `$children`, `$descendants`, `$descendants_and_self`, `$date`, `$branch`, `$all`, `$var`, `$file`, `$csv`
+
+### Conditions (same grammar as policy `conditions.expression` and Unquery `?` on keys)
+
+Operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `in`, `not_in`, `contains`, `starts_with`, `ends_with`, `matches`, `is_array`, `is_object`, `is_string`, `is_number`, `is_int`, `is_float`, `is_bool`, `is_literal`. Logic: `&` (AND), `|` (OR), `!` (NOT). Postfix `!` on an expression tests **field exists**.
+
+### Graded examples
+
+**1. Project one meta field into an output key** (per matching document, then combined per engine rules):
+
+```json
+{
+  "query": { "match_start": "/manual/" },
+  "unquery": { "title": "chapter_title" }
+}
+```
+
+**2. Count documents in a prefix:**
+
+```json
+{
+  "query": { "match_start": "/orders/" },
+  "unquery": { "total": "$count" }
+}
+```
+
+**3. XPath from XML:**
+
+```json
+{
+  "query": { "match": "/book/ch1" },
+  "unquery": { "heading": "$xpath(\"//h1\")" }
+}
+```
+
+**4. Nested object with conditional key** (illustrative; exact key syntax may use `#if` blocks for complex trees):
+
+```json
+{
+  "query": { "match_start": "/items/" },
+  "unquery": {
+    "id": "$identifier",
+    "summary": {
+      "len": "$length(title_field)"
+    }
+  }
+}
+```
+
+SDK: `UnqueryTemplate` in `@xcitedbs/client` types; method `unquery(query, unquery)`.
+
+## ABAC policy expression language
+
+Policies may set **`conditions.expression`** (optional) and **`conditions.branches`** (optional array). If `branches` is non-empty, the request branch must match an entry (`"*"`, exact name, or `prefix*`).
+
+### Evaluation context for **policies** (`conditions.expression`)
+
+```json
+{
+  "subject": {
+    "id": "...",
+    "email": "...",
+    "type": "app_user|developer|...",
+    "role": "...",
+    "groups": ["..."],
+    "attr": { }
+  },
+  "resource": {
+    "identifier": "/full/path",
+    "path": ["segment", "segment"]
+  },
+  "env": { "branch": "..." }
+}
+```
+
+`subject.attr` mirrors app-user **custom attributes** from the user record. `resource.path` is the identifier split on `/` (non-empty segments only).
+
+### Operators (predicates)
+
+`=`, `!=`, `>=`, `<=`, `>`, `<`, `in`, `contains`, `starts_with`, `ends_with`, `&`, `|`, `!`, `+` (string concat), postfix `!` (exists).
+
+### Policy action strings (in `actions` arrays)
+
+Use: **`read`**, **`write`**, **`delete`**, **`list`**, **`meta:read`**, **`meta:write`**, **`unquery`**. (Do not use legacy `document:write`-style names in new policies.)
+
+### Copy-pasteable expression recipes (from integration tests)
+
+| Scenario | `conditions.expression` |
+|----------|-------------------------|
+| Tenant isolation (first path segment = user attr) | `resource.path[0] = subject.attr.tenant_code` |
+| Numeric level | `subject.attr.level >= 5` |
+| Project membership (second segment in array attr) | `resource.path[1] in subject.attr.projects` |
+| Boolean feature flag | `subject.attr.beta = true` |
+| Compound + branch (also use `conditions.branches` when needed) | `subject.email ends_with '@company.com' \| (subject.email ends_with '@partner.com' & env.branch = 'stg')` |
+
+Dry-run: **`POST /api/v1/security/check`** with `subject`, `identifier`, `action`, optional `meta_path`, `branch`.
+
 ---
 
 # Branches
@@ -569,27 +809,111 @@ Returns lock info. **`409`** if already locked.
 
 **Base path:** `/api/v1/triggers`
 
+Definitions are stored as JSON under **`/_xcitedb/triggers`**. After a matching event, the server runs **`action.unquery`** over documents selected by **`action.query`**, then writes the resulting JSON to **`action.meta_path`** on **`action.target_identifier`** (elevated privileges inside the same transaction). Nested trigger evaluation is blocked (no infinite loops).
+
 ## Create or update trigger
 
 **`POST /api/v1/triggers`**
 
 ```json
 {
-  "trigger_id": "on_status_review",
+  "trigger_id": "on_project_status_meta",
   "trigger": {
-    "match": { "meta_key": "status", "meta_value": "review" },
-    "action": { "type": "webhook", "url": "https://hooks.example.com/xcite" }
+    "enabled": true,
+    "event": "meta_changed",
+    "match": {
+      "identifiers": [{ "match_start": "/projects/" }],
+      "match_meta_path": "status",
+      "match_operation": "set"
+    },
+    "conditions": {
+      "branches": ["*", "main"],
+      "expression": "trigger.meta_path = \"status\""
+    },
+    "action": {
+      "query": { "match": "$trigger_identifier" },
+      "unquery": { "id": "$identifier", "status": "status" },
+      "target_identifier": "/indexes/project_status",
+      "meta_path": "entries",
+      "mode": "append"
+    }
+  }
+}
+```
+
+### Trigger fields
+
+| Field | Required | Description |
+|--------|----------|-------------|
+| `enabled` | No (default true) | If false, trigger is skipped. |
+| `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`. |
+
+### Expression context for **triggers** (`conditions.expression`)
+
+Not the same as policies: there is **no `subject`**. Context object:
+
+- **`trigger`**: `{ "event", "meta_path", "operation" }` (`operation`: `set` / `append` / `delete`)
+- **`value`**: JSON written at `meta_path` for `meta_changed`, or null
+- **`resource`**: `{ "identifier", "path" }` for the firing identifier
+- **`env`**: `{ "branch" }`
+
+### Unquery variables injected for triggers
+
+String template vars: **`$trigger_identifier`**, **`$trigger_meta_path`**, **`$trigger_operation`**. JSON var: **`$trigger_value`** (the written value when applicable).
+
+### Recipes
+
+**Meta change → append row to an index document**
+
+```json
+{
+  "trigger_id": "meta_index",
+  "trigger": {
+    "event": "meta_changed",
+    "match": {
+      "identifiers": [{ "match_start": "/docs/" }],
+      "match_meta_path": "reviewed"
+    },
+    "action": {
+      "query": { "match": "$trigger_identifier" },
+      "unquery": { "doc": "$trigger_identifier", "at": "$trigger_meta_path" },
+      "target_identifier": "/indexes/reviews",
+      "meta_path": "log",
+      "mode": "append"
+    }
+  }
+}
+```
+
+**Document written → write stats meta on the same identifier**
+
+```json
+{
+  "trigger_id": "article_stats",
+  "trigger": {
+    "event": "document_written",
+    "match": { "identifiers": [{ "match_start": "/articles/" }] },
+    "action": {
+      "query": { "match": "$trigger_identifier" },
+      "unquery": { "id": "$identifier", "nodes": "$count" },
+      "target_identifier": "$trigger_identifier",
+      "meta_path": "stats",
+      "mode": "set"
+    }
   }
 }
 ```
 
 ## List triggers
 
-**`GET /api/v1/triggers`** — Returns map of `{ trigger_id: trigger_definition }`.
+**`GET /api/v1/triggers`** — Returns map of `{ trigger_id: trigger_definition }`. Optional **`?name=`** returns one trigger as `{ trigger_id, trigger }`.
 
 ## Delete trigger
 
-**`DELETE /api/v1/triggers?name=on_status_review`**
+**`DELETE /api/v1/triggers?name=on_project_status_meta`**
 
 ---
 
@@ -609,7 +933,7 @@ Returns lock info. **`409`** if already locked.
     "priority": 10,
     "subjects": { "type": "app_user", "groups": ["viewers"] },
     "resources": { "identifiers": [{ "match_start": "/admin/" }] },
-    "actions": ["document:write", "document:delete"],
+    "actions": ["write", "delete", "meta:write"],
     "conditions": {}
   }
 }
@@ -630,11 +954,11 @@ Returns lock info. **`409`** if already locked.
 {
   "subject": { "type": "app_user", "groups": ["editors"] },
   "identifier": "/admin/config",
-  "action": "document:write"
+  "action": "write"
 }
 ```
 
-Returns `{ effect: "allow"|"deny", matched_policy_id? }`.
+Returns `{ effect: "allow"|"deny", matched_policy_id?, expression_context? }`.
 
 ## Security config
 
@@ -1084,6 +1408,9 @@ interface DatabaseContext {
 - `deleteTrigger(name)` → `void`
 
 ### App User Auth
+
+**App-user auth in test sessions.** The full app-user lifecycle works inside a test session: `registerAppUser` → `loginAppUser` → `appUserMe` / `updateAppUserProfile` / etc. App user records are stored in the test session’s isolated LMDB and cleaned up with the session. No `X-Test-Auth: required` is needed for this flow — the default bypass mode recognizes app-user tokens while still skipping developer auth.
+
 - `registerAppUser(email, password, displayName?, attributes?)` → `AppUser` (groups assigned from server config)
 - `loginAppUser(email, password)` → `AppUserTokenPair`
 - `refreshAppUser()` → `AppUserTokenPair`

package/llms.txt

@@ -22,7 +22,7 @@ These are the most common sources of confusion for developers and AI assistants:
 
 8. **Project vs tenant id.** In the SDK, prefer `context.project_id` (and `listMyProjects` / `switchProject`). Many JSON bodies and JWT claims still use the field name `tenant_id` for the same value — the client sends that wire name automatically.
 
-9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default those requests **skip** normal auth; send **`X-Test-Auth: required`** to exercise real JWT/API-key auth against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). The test DB starts **empty** (no copy of production project config or keys).
+9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default **developer** auth (API key / platform JWT) is bypassed, but **app-user** identity (`X-App-User-Token` or Bearer app-user JWT) is still recognized. Send **`X-Test-Auth: required`** to exercise full developer JWT/API-key auth and ABAC against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). The test DB starts **empty** (no copy of production project config or keys).
 
 ## Common Pitfalls
 
@@ -38,11 +38,15 @@ These are the most common sources of confusion for developers and AI assistants:
 
 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()`.
 
+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, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Test mode" below.
+
 ## Test mode (how to use)
 
+> **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised.
+
 1. **Provision:** `POST /api/v1/test/sessions` with `Authorization: Bearer …` or `X-API-Key` (same as normal API access). Response JSON includes the session token.
 2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Branch` / `context` as needed). Data is stored under the server’s `_test/<session>/` area, not your production tenant.
-3. **Auth behavior:** Omit extra headers for frictionless tests. To test policies and real identities, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
+3. **Auth behavior:** Developer auth (API key / platform JWT) is bypassed by default for frictionless tests. **App-user identity** (`X-App-User-Token` or Bearer app-user JWT) **is still recognized** in default mode, so `registerAppUser` → `loginAppUser` → `appUserMe` works inside a test session. To also exercise developer auth and ABAC policies, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
 4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
 5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or manual token + `test_session_token` / `test_require_auth` constructor args. **C++:** `XCiteDBClient::create_test_session(options)`, `destroy_test_session()`, optional `test_require_auth` in options.
 
@@ -206,6 +210,26 @@ interface XCiteDBClientOptions {
 **Triggers:**
 - `upsertTrigger(id, trigger)` / `listTriggers()` / `deleteTrigger(name)` — Automation triggers
 
+### Advanced: policy expressions (ABAC)
+
+- **Actions** (use in `policy.actions`): `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+- **`conditions.expression`** uses the same predicate syntax as Unquery `?` filters. **Context:** `subject.id`, `subject.email`, `subject.role`, `subject.groups`, `subject.attr.*` (app-user JSON attributes), `resource.identifier`, `resource.path` (array of path segments), `env.branch`.
+- **Operators:** `=`, `!=`, `>=`, `<=`, `>`, `<`, `in`, `contains`, `starts_with`, `ends_with`, `&`, `|`, `!`, `+` (string concat), postfix `!` (exists).
+- **Examples:** `resource.path[0] = subject.attr.tenant_code` — tenant isolation; `subject.attr.level >= 5` — numeric attribute gate.
+
+### Advanced: triggers (stored under `/_xcitedb/triggers`)
+
+- **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`.
+- **Unquery vars:** `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`. **Trigger `conditions.expression` context:** `trigger.{event,meta_path,operation}`, `value`, `resource`, `env.branch` (no `subject`).
+
+### Advanced: Unquery DSL (`unquery(query, unqueryDoc)`)
+
+- JSON **keys** = output fields; **string values** = expressions referencing meta/XML (e.g. field name `"title"` reads meta key `title`).
+- **Common builtins:** `$count`, `$sum(expr)`, `$avg(expr)`, `$min(expr)`, `$max(expr)`, `$xpath("…")`, `$identifier`, `$size(expr)`, `$length(expr)`, `$if(cond, a, b)`, `$var(name)` / `%name`.
+- **Example:** `{ "query": { "match_start": "/orders/" }, "unquery": { "n": "$count" } }` — count documents. Full grammar: **`llms-full.txt`** in this package.
+
 **App Users (admin):**
 - `listAppUsers()` / `createAppUser()` / `deleteAppUser()` — Manage end-user accounts
 - `registerAppUser(email, password, displayName?, attributes?)` — Self-registration (groups assigned from server config)

package/package.json

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