@xcitedbs/client 0.3.3 → 0.3.5

package/dist/client.d.ts

@@ -82,8 +82,25 @@ export declare class XCiteDBClient {
     private getAppUserId;
     private normalizeIsolationNamespaceTemplate;
     private canonicalId;
-    /** Resolved namespace root, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
+    /** Resolve the configured namespace template for an explicit user id. Returns null if isolation is off, no template, or `userId` is empty. */
+    private userIsolationNamespaceFor;
+    /** Resolved namespace root for the calling user, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
     private userIsolationNamespace;
+    /**
+     * Namespace for the current request's identity context.
+     *
+     * On a user-workspace branch (`_uw/<owner>/<slug>`) where the calling user is
+     * a member but not the owner, returns the *owner's* namespace — docs in the
+     * workspace are stored at `<owner_ns>/<rel>`, not at the caller's
+     * `<self_ns>/<rel>`. For the owner, non-`_uw/` branches, malformed
+     * branches, or when isolation is off, falls back to the calling user's
+     * namespace.
+     *
+     * Mirrors the server-side branch-aware behavior in
+     * `UserIsolationService::prefixIdentifier` so the SDK's pre-prefixing
+     * lands on the right namespace before the request leaves.
+     */
+    private userIsolationContextNamespace;
     private allSharedPassthroughPrefixes;
     private pathMatchesSharedPassthrough;
     private isoPrefixId;

package/dist/client.js

@@ -185,6 +185,8 @@ class XCiteDBClient {
         const sessionBody = {};
         if (opts.overlay === true)
             sessionBody.overlay = true;
+        if (opts.additionalKeys !== undefined)
+            sessionBody.additional_keys = opts.additionalKeys;
         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 });
@@ -521,13 +523,12 @@ class XCiteDBClient {
         }
         return t;
     }
-    /** Resolved namespace root, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
-    userIsolationNamespace() {
+    /** Resolve the configured namespace template for an explicit user id. Returns null if isolation is off, no template, or `userId` is empty. */
+    userIsolationNamespaceFor(userId) {
         if (!this.userIsolation?.enabled) {
             return null;
         }
-        const uid = this.getAppUserId();
-        if (!uid) {
+        if (!userId) {
             return null;
         }
         const rawTpl = this.normalizeIsolationNamespaceTemplate(this.userIsolation.namespace ?? '/users/{userId}');
@@ -535,7 +536,42 @@ class XCiteDBClient {
         if (!trimmed) {
             return null;
         }
-        return trimmed.replace(/{userId}/g, uid).replace(/{user_id}/g, uid);
+        return trimmed.replace(/{userId}/g, userId).replace(/{user_id}/g, userId);
+    }
+    /** Resolved namespace root for the calling user, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
+    userIsolationNamespace() {
+        return this.userIsolationNamespaceFor(this.getAppUserId());
+    }
+    /**
+     * Namespace for the current request's identity context.
+     *
+     * On a user-workspace branch (`_uw/<owner>/<slug>`) where the calling user is
+     * a member but not the owner, returns the *owner's* namespace — docs in the
+     * workspace are stored at `<owner_ns>/<rel>`, not at the caller's
+     * `<self_ns>/<rel>`. For the owner, non-`_uw/` branches, malformed
+     * branches, or when isolation is off, falls back to the calling user's
+     * namespace.
+     *
+     * Mirrors the server-side branch-aware behavior in
+     * `UserIsolationService::prefixIdentifier` so the SDK's pre-prefixing
+     * lands on the right namespace before the request leaves.
+     */
+    userIsolationContextNamespace() {
+        const selfId = this.getAppUserId();
+        const branch = this.defaultContext.workspace ?? this.defaultContext.branch;
+        if (branch && branch.startsWith('_uw/')) {
+            const m = branch.match(/^_uw\/([^/]+)\/[^/]+$/);
+            if (m) {
+                const ownerId = m[1];
+                if (ownerId && ownerId !== selfId) {
+                    const ns = this.userIsolationNamespaceFor(ownerId);
+                    if (ns) {
+                        return ns;
+                    }
+                }
+            }
+        }
+        return this.userIsolationNamespaceFor(selfId);
     }
     allSharedPassthroughPrefixes() {
         const o = this.userIsolation;
@@ -564,7 +600,7 @@ class XCiteDBClient {
         return false;
     }
     isoPrefixId(id) {
-        const ns = this.userIsolationNamespace();
+        const ns = this.userIsolationContextNamespace();
         if (!ns) {
             return id;
         }
@@ -589,7 +625,7 @@ class XCiteDBClient {
         return finalId;
     }
     isoUnprefixId(id) {
-        const ns = this.userIsolationNamespace();
+        const ns = this.userIsolationContextNamespace();
         if (!ns) {
             return id;
         }
@@ -606,7 +642,7 @@ class XCiteDBClient {
         return canonical;
     }
     isoPrefixQuery(q) {
-        if (!this.userIsolationNamespace()) {
+        if (!this.userIsolationContextNamespace()) {
             return q;
         }
         const out = { ...q };
@@ -622,7 +658,7 @@ class XCiteDBClient {
         return out;
     }
     isoApplyXmlDbIdentifier(xml) {
-        if (!this.userIsolationNamespace()) {
+        if (!this.userIsolationContextNamespace()) {
             return xml;
         }
         return xml.replace(/(db:identifier\s*=\s*")([^"]*)(")/, (_m, p1, mid, p3) => {

package/dist/client.test.js

@@ -32,6 +32,80 @@ const types_js_1 = require("./types.js");
             globalThis.fetch = orig;
         }
     });
+    (0, node_test_1.it)('user-workspace branch (`_uw/<owner>/<slug>`) prefixes paths with owner namespace, not caller', async () => {
+        // Issue B repro at the unit level: an invitee on someone else's user
+        // workspace must namespace identifiers to the owner's user_id parsed
+        // from the branch, not their own. We assert the outbound URL — SDK
+        // routes prefixing through userIsolationContextNamespace() which
+        // checks `_uw/<owner>/<slug>` and substitutes the owner.
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            seen.push(String(input));
+            return new Response(JSON.stringify({ ok: true, _xcite_json_doc: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'test-key',
+                userIsolation: { enabled: true, namespace: '/users/{userId}' },
+            });
+            // sub claim = "user-B"
+            c.setAppUserTokens('header.eyJzdWIiOiJ1c2VyLUIifQ.sig');
+            // Owner of the workspace is "user-A"; we are "user-B".
+            c.setContext({ branch: '_uw/user-A/shared', project_id: 'p1' });
+            await c.readJsonDocument('/drafts/x');
+            strict_1.default.equal(seen.length, 1);
+            strict_1.default.match(seen[0], /identifier=%2Fusers%2Fuser-A%2Fdrafts%2Fx/, `expected identifier prefixed with owner ns, got: ${seen[0]}`);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('non-`_uw` branch keeps caller-namespace prefixing (regression guard)', async () => {
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            seen.push(String(input));
+            return new Response(JSON.stringify({ ok: true, _xcite_json_doc: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'test-key',
+                userIsolation: { enabled: true, namespace: '/users/{userId}' },
+            });
+            c.setAppUserTokens('header.eyJzdWIiOiJ1c2VyLUIifQ.sig');
+            c.setContext({ branch: 'main', project_id: 'p1' });
+            await c.readJsonDocument('/drafts/x');
+            strict_1.default.match(seen[0], /identifier=%2Fusers%2Fuser-B%2Fdrafts%2Fx/, `expected identifier prefixed with caller ns, got: ${seen[0]}`);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('owner of `_uw/<self>/<slug>` workspace uses own namespace (no-op for owner)', async () => {
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            seen.push(String(input));
+            return new Response(JSON.stringify({ ok: true, _xcite_json_doc: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'test-key',
+                userIsolation: { enabled: true, namespace: '/users/{userId}' },
+            });
+            c.setAppUserTokens('header.eyJzdWIiOiJ1c2VyLUEifQ.sig'); // user-A
+            c.setContext({ branch: '_uw/user-A/shared', project_id: 'p1' });
+            await c.readJsonDocument('/drafts/x');
+            strict_1.default.match(seen[0], /identifier=%2Fusers%2Fuser-A%2Fdrafts%2Fx/, `expected owner to keep own ns, got: ${seen[0]}`);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
     (0, node_test_1.it)('queryByIdentifier / queryDocuments return XML bodies unmodified under userIsolation', async () => {
         const xml = '<?xml version="1.0"?><doc xmlns:db="http://www.xcitedb.com/schema"><a href="https://example.com//path">x</a></doc>';
         const orig = globalThis.fetch;
@@ -315,6 +389,51 @@ const types_js_1 = require("./types.js");
         }));
         strict_1.default.equal(h.get('X-Test-Auth'), 'preserve');
     });
+    (0, node_test_1.it)('forwards bootstrap.triggers and surfaces triggers_created on the client', async () => {
+        const captured = { value: null };
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_input, init) => {
+            captured.value = { body: JSON.parse(String(init?.body ?? '{}')) };
+            return new Response(JSON.stringify({
+                session_token: 'tok-trig',
+                expires_at: Date.now() + 60000,
+                session_ttl_seconds: 60,
+                bootstrap: {
+                    user_isolation_applied: false,
+                    developer_bypass_applied: false,
+                    policies_created: [],
+                    triggers_created: ['t-write-meta'],
+                },
+            }), { status: 201 });
+        });
+        try {
+            const client = await client_js_1.XCiteDBClient.createTestSession({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                bootstrap: {
+                    triggers: [
+                        {
+                            trigger_id: 't-write-meta',
+                            trigger: {
+                                event: 'meta_changed',
+                                match: { identifiers: [{ match_start: '/' }] },
+                                action: { unquery: { x: '$count' }, target_identifier: '/_audit', meta_path: 'n', mode: 'set' },
+                            },
+                        },
+                    ],
+                },
+            });
+            const body = captured.value.body;
+            const boot = body.bootstrap;
+            const triggers = boot.triggers;
+            strict_1.default.equal(triggers.length, 1);
+            strict_1.default.equal(triggers[0].trigger_id, 't-write-meta');
+            strict_1.default.deepEqual(client.lastTestSessionBootstrap?.triggers_created, ['t-write-meta']);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
 });
 (0, node_test_1.describe)('enableUserIsolation', () => {
     (0, node_test_1.it)('with explicit config, configures prefixing without any HTTP call', async () => {

package/dist/types.d.ts

@@ -720,12 +720,24 @@ export interface TestSessionBootstrap {
         policy_id: string;
         policy: SecurityPolicy;
     }>;
+    /**
+     * Per-test trigger set. Installed into the synthetic test tenant only — the project's
+     * global trigger registry is untouched. Each entry is `{ trigger_id, trigger }`; the
+     * `trigger` shape matches `upsertTrigger`. Validation errors abort the bootstrap with
+     * `400 bootstrap_trigger_invalid`; storage failures abort with `500 bootstrap_trigger_failed`.
+     */
+    triggers?: Array<{
+        trigger_id: string;
+        trigger: TriggerDefinition;
+    }>;
 }
 /** `bootstrap` summary returned by the server after a bootstrapped test session is created. */
 export interface TestSessionBootstrapSummary {
     user_isolation_applied?: boolean;
     developer_bypass_applied?: boolean;
     policies_created?: string[];
+    /** IDs of triggers installed by the bootstrap (in input order). */
+    triggers_created?: string[];
 }
 /** One row from `GET /api/v1/test/sessions` (management; no `X-Test-Session` on that route). */
 export interface TestSessionInfo {
@@ -749,7 +761,19 @@ export interface CreateTestSessionOptions {
      * When true, creates an overlay test session: writable ephemeral LMDB with production project data as read-only base.
      */
     overlay?: boolean;
-    /** Optional server-side bootstrap (user isolation, developer_bypass, policies). */
+    /**
+     * API keys to snapshot into the new session's config DB so requests carrying any of these keys
+     * (alongside `X-Test-Session: <token>`) authenticate against the session, not production.
+     *
+     * Typical use: a backend-for-frontend (BFF) that performs admin-scoped writes on behalf of the
+     * SPA. Without registering the BFF's admin key here, the BFF would receive `401
+     * test_session_unknown_api_key` when forwarding `X-Test-Session` to XCiteDB.
+     *
+     * Each entry must be a valid production API key on the project hosting the session — otherwise
+     * the server returns `400 additional_key_invalid` (with the offending index) and aborts.
+     */
+    additionalKeys?: string[];
+    /** Optional server-side bootstrap (user isolation, developer_bypass, policies, triggers). */
     bootstrap?: TestSessionBootstrap;
     /**
      * Test-session auth fidelity mode (`X-Test-Auth` header on the returned client).

package/dist/user-isolation.test.js

@@ -172,4 +172,92 @@ wd('user isolation (wet)', () => {
             await admin.disableUserIsolation().catch(() => { });
         }
     });
+    (0, node_test_1.it)('user-workspace branch: invitee reads owner-namespaced docs through self-namespace API', async () => {
+        // Issue B repro: when user B is granted readwrite on user A's user
+        // workspace and reads a doc on the workspace branch, the SDK must
+        // namespace the path with A's user_id (parsed from the `_uw/<owner>/<slug>`
+        // branch), not B's. Server-side prefixIdentifier already passes the
+        // identifier through unchanged for workspace members; the SDK must put
+        // the owner's namespace on the path before sending.
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = adminClient(e);
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const emailA = `js_uwA_${suffix}@apitest.invalid`;
+        const emailB = `js_uwB_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        const slug = `js-uw-doc-${suffix}`;
+        const wsName = `shared-${suffix}`;
+        let userA;
+        let userB;
+        let workspaceId;
+        let workspaceBranch;
+        try {
+            await admin.setUserIsolationConfig({
+                enabled: true,
+                namespace_pattern: '/users/${user.id}',
+            });
+            userA = await admin.createAppUser(emailA, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            userB = await admin.createAppUser(emailB, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            const appA = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await appA.loginAppUser(emailA, password);
+            // A creates the workspace, captures the branch from the response,
+            // grants B readwrite, and writes a doc on the workspace branch.
+            const ws = (await appA.createUserWorkspace(wsName));
+            strict_1.default.ok(ws.id, 'workspace id missing');
+            strict_1.default.ok(ws.branch && ws.branch.startsWith('_uw/'), 'workspace branch missing');
+            workspaceId = ws.id;
+            workspaceBranch = ws.branch;
+            strict_1.default.equal(workspaceBranch, `_uw/${userA.user_id}/${slugifyForAssert(wsName)}`, 'branch should be _uw/<ownerId>/<slug>');
+            await appA.addUserWorkspaceGrant(workspaceId, { user_id: userB.user_id, mode: 'rw' });
+            appA.setContext({ branch: workspaceBranch });
+            await appA.writeJsonDocument(`/${slug}`, { _xcite_json_doc: true, who: 'A', v: 1 });
+            // B opens the workspace branch and reads the doc using the relative
+            // identifier — must resolve to A's namespace, not B's.
+            const appB = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: workspaceBranch, project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await appB.loginAppUser(emailB, password);
+            const doc = await appB.readJsonDocument(`/${slug}`);
+            strict_1.default.equal(doc.who, 'A');
+            strict_1.default.equal(doc.v, 1);
+            // List on the workspace branch — identifiers must come back stripped
+            // of the owner's namespace (isoUnprefixId symmetry).
+            const list = await appB.listJsonDocuments(`/${slug.split('-')[0]}`);
+            const ids = (list.identifiers ?? []);
+            strict_1.default.ok(ids.includes(`/${slug}`), `expected response to include /${slug}, got ${JSON.stringify(ids)}`);
+        }
+        finally {
+            if (workspaceId) {
+                await admin
+                    .deleteJsonDocument(`/users/${userA?.user_id ?? ''}/${slug}`)
+                    .catch(() => { });
+                await admin.deleteUserWorkspace(workspaceId).catch(() => { });
+            }
+            if (userB)
+                await admin.deleteAppUser(userB.user_id).catch(() => { });
+            if (userA)
+                await admin.deleteAppUser(userA.user_id).catch(() => { });
+            await admin.disableUserIsolation().catch(() => { });
+        }
+    });
 });
+// Mirrors UserWorkspaceService::slugify (lowercase, runs of non-alphanumerics → '-', trim '-').
+function slugifyForAssert(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+}

package/llms-full.txt

@@ -377,6 +377,58 @@ TEST_CASE("XciteDB XML document round-trip") {
 }
 ```
 
+## Overlay sessions with a backend-for-frontend (BFF)
+
+When a single-page app is in an overlay test session and an admin-scoped action is delegated to a server-side BFF (e.g. group grants, project-editor enrolment, anything the SPA cannot do with its own credentials), the BFF must route through the **same overlay** — otherwise admin writes land in production while the SPA still reads from the overlay, and the SPA sees stale state.
+
+The mechanism is the same `X-Test-Session` header used for SPA requests, plus pre-registering the BFF's admin key on the session at create time so the server accepts it.
+
+1. **Pre-register the BFF admin key** when the SPA creates the session (SDK option `additionalKeys`, wire field `additional_keys`):
+
+   ```typescript
+   const client = await XCiteDBClient.createTestSession({
+     baseUrl, apiKey: SPA_PUBLIC_KEY,
+     overlay: true,
+     additionalKeys: [BFF_ADMIN_KEY],   // snapshotted into the session config
+     bootstrap: { user_isolation: { /* ... */ } },
+   });
+   ```
+
+   Each entry is a production API key the BFF will use. The server snapshots each into the session's config DB so requests carrying that key alongside `X-Test-Session: <token>` authenticate against the session, not production. Without this, the BFF gets `401 test_session_unknown_api_key`. An invalid key (one not present in production for the session's project) returns `400 additional_key_invalid` with the offending array index, and the session is rolled back.
+
+2. **SPA forwards `X-Test-Session` to the BFF** as a normal request header:
+
+   ```typescript
+   const r = await fetch('/api/app/grant-editor', {
+     method: 'POST',
+     headers: { 'X-Test-Session': client.testSessionToken ?? '' },
+     body: JSON.stringify({ user_id: u.user_id }),
+   });
+   ```
+
+3. **BFF reads the inbound header and propagates it on its outbound XCiteDB call.** With the JS SDK, instantiate a per-request admin client carrying the test-session token — don't reuse a long-lived admin client, since the same BFF process serves both real and test traffic:
+
+   ```typescript
+   app.post('/api/app/grant-editor', async (req, res) => {
+     const testSession = req.header('X-Test-Session') || undefined;
+     const admin = new XCiteDBClient({
+       baseUrl: process.env.XCITEDB_URL!,
+       apiKey: process.env.XCITEDB_BFF_KEY!,   // == BFF_ADMIN_KEY
+       testSessionToken: testSession,           // undefined ⇒ hits production as today
+     });
+     await admin.updateAppUserGroups(req.body.user_id, [
+       XCiteDBClient.buildProjectGroup(process.env.XCITEDB_PROJECT_ID!, 'editor'),
+     ]);
+     res.status(204).end();
+   });
+   ```
+
+   The same shape works in any HTTP framework — the only requirement is propagating `X-Test-Session` from inbound to outbound. Production traffic doesn't carry the header, so `testSessionToken` falls back to `undefined` and the admin client behaves as before.
+
+**Verification.** With this wired up, an end-to-end test that registers an app user, calls the BFF endpoint, then reads the user's groups through the SPA's overlay client should see the freshly-granted group on the next read. Without the propagation, the read returns the user's groups as they were at session creation (typically empty) and admin-gated routes return `403`.
+
+The behavior is bolted to two server pieces: `additional_keys` snapshotting in `TestController::create` (`src/controllers/TestController.cpp`) and the test-session header dispatch in `AuthFilterShared` (`src/filters/AuthFilterShared.cpp`) — there's no separate "attach admin client to existing session" API; the snapshot + header pair is sufficient.
+
 ---
 
 # Health, version & discovery

package/llms.txt

@@ -138,11 +138,23 @@ SDKs surface these fields on typed errors (e.g. `XCiteDBForbiddenError.policyId`
   "bootstrap": {
     "user_isolation": { "enabled": true, "namespace_pattern": "/spaces/${user.id}" },
     "developer_bypass": true,
-    "policies": []
+    "policies": [],
+    "triggers": [
+      {
+        "trigger_id": "audit-writes",
+        "trigger": {
+          "event": "meta_changed",
+          "match": { "identifiers": [{ "match_start": "/" }] },
+          "action": { "unquery": { "n": "$count" }, "target_identifier": "/_audit", "meta_path": "n", "mode": "set" }
+        }
+      }
+    ]
   }
 }
 ```
 
+`bootstrap.triggers` installs per-test triggers into the synthetic test tenant only — the project's global trigger registry (`/_xcitedb/triggers`) is never touched. Each entry is `{ trigger_id, trigger }` (same shape as `upsertTrigger`); validation errors abort with `400 bootstrap_trigger_invalid`. The summary echoes back `triggers_created: string[]`.
+
 If you skip the bootstrap, an app-user JWT cannot read or write `/spaces/<userId>/...` — even paths the user "owns" — and you will see 403 with reason `tenant_security_unconfigured`.
 
 **SDK one-liners for bootstrap:** **JS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, testRequireAuth: true, bootstrap: { user_isolation: { enabled: true, namespace_pattern: '/spaces/${user.id}' }, developer_bypass: true } })`. **Python:** `async with XCiteDBClient.test_session(base_url, api_key=sk, test_require_auth=True, bootstrap={...}) as c:`. **C++:** set `options.test_session_bootstrap = nlohmann::json::parse(R"(...)");` then `XCiteDBClient::create_test_session(options)`.

package/package.json

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

package/unquery-ai-guide.md

@@ -85,7 +85,7 @@ A path selects a value from the current context.
 | `[n]` | Array index (0-based) | `"Dependants[0].FirstName"` |
 | `[expr]` | Computed index | `"Field1[$index+1]"` |
 | `[]` | Whole array (projection over all elements) | `"Array1[].Field1"` |
-| `[a:b]` | Array **slice** in a context modifier (half-open; negative counts from end) | `"scores:[0:3]"`, `"scores:[-2:]"` |
+| `[a:b]` | Array **slice** in a context modifier or path expression (half-open; negative counts from end) | `"scores:[0:3]"`, `"scores[2:5]"`, `"$size(scores[:3])"` |
 | `/Field` | Absolute from document root | `"/employees.$(.)"` |
 | `../Field` | Up one path level (skips array indices) | `"../DBInstanceIdentifier"` |
 | `<<Field` | Read same field in *previous* document context | `"<<Field1"` after a `->$file(...)` |
@@ -710,6 +710,34 @@ Allowed only against literals (see §0.8 and §4.8):
 
 Each recipe shows a small input-shape sketch, the Unquery template, and (where useful) the equivalent jq one-liner for cross-reference.
 
+### 10.0 Materializing many rows from a prefix walk — pick a multi-row shape
+
+Common gotcha for prefix-walk queries (`{ match_start: '/index/users/' }` and similar) feeding a search dropdown or candidate list: if the template root is a **single object**, every document iteration *overwrites* the same fields and you keep only the **last** match's values.
+
+`{ "name": "name", "email": "email" }` — *wrong* for multi-row output. Returns one document's fields, not a list. (See §1's "evaluate once vs. per pass".)
+
+Three correct shapes for "give me one row per matching document":
+
+**Array of objects** (most common — preserves order, easy to iterate client-side):
+
+```json
+[{ "id": "$identifier", "name": "name", "email": "email" }]
+```
+
+**Map keyed by identifier** (constant-time lookup by id, no duplicates):
+
+```json
+{ "$($identifier)": { "name": "name", "email": "email" } }
+```
+
+**Array of identifiers only** (just need the keys, e.g. for a count or follow-up reads):
+
+```json
+["$identifier"]
+```
+
+The bare-object form is correct *only* when the prefix narrows to exactly one document or you genuinely want "last match wins" (e.g. picking a single config row). For dropdowns, search results, member lists, or any "show me everything matching" use case, default to the array-of-objects shape.
+
 ### 10.1 Pick one field per document → array
 
 ```json

package/unquery-grammar.md

@@ -128,7 +128,7 @@ Climbing parser levels:
 |--------|-----------|------------|
 | 0 | `+`, `-` | Left via loop: each new rhs parsed with `expression(1)`. |
 | 1 | `*`, `/`, `mod` | Left; rhs parsed with `expression(2)`. |
-| 3 | Postfix `.token` and `[ expr ]` | Postfix chain on current `res`. |
+| 3 | Postfix `.token`, `[ expr ]`, `[ slice ]` | Postfix chain on current `res`. |
 
 Parentheses: `(` `expression(0)` `)` as primary.
 
@@ -138,12 +138,13 @@ Parentheses: `(` `expression(0)` `)` as primary.
 expression   ::= '(' expression ')'
                 | baseExpression ( ( '+' | '-' ) expression(1)
                                  | ( '*' | '/' | 'mod' ) expression(2) )*
-                | baseExpression ( '.' fieldSegment | '[' expression ']' )*
+                | baseExpression ( '.' fieldSegment | '[' expression ']' | '[' slice ']' )*
 
+slice        ::= INT? ':' INT?                    (* INT may be `-` INT for negative-from-end *)
 fieldSegment ::= IDENT | BACKTICK_STR | '$' IDENT ...   (* lexer token after '.'; special case: if token starts with '$', subfield parse backs up — see pathWithBrackets *)
 ```
 
-**Postfix** (prec ≤ 3): after `consume()` of `.` or `[`, if `[` then parse `expression(0)` unless next is `]`; require `]`; build `TExprSubfield(res, expr_or_empty, is_index)`.
+**Postfix** (prec ≤ 3): after `consume()` of `.` or `[`, if `[` then either (a) parse a slice `INT? ':' INT?` followed by `]` → `TExprSlice(res, …)`, or (b) parse `expression(0)` followed by `]` → `TExprSubfield(res, expr_or_empty, is_index)`. Empty `[]` builds `TExprSubfield` with no expression. Slice detection uses backtracking: a single integer with no `:` falls through to the expression form.
 
 ### 4.3 `baseExpression` — alternatives (first token disambiguation)
 
@@ -151,7 +152,8 @@ Roughly in parse order:
 
 | Prefix / form | AST | Notes |
 |-----------------|-----|--------|
-| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. (Slice `[a:b]` form is currently parsed only on context modifiers, not in path expressions.) |
+| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. |
+| `[` (INT)? `:` (INT)? `]` | `TExprSlice(TExprField("."), …)` | Half-open array slice on `.`. Negative ints count from end. Bounds must be integer literals (with optional `-`). Yields a JSON array. |
 | `$` `(` `expression` `)` | `TExprField(expr)` | Evaluate / path from dynamic name (`$()`). |
 | `$if` `(` `condition` `,` `expression` `,` `expression` `)` | `TExprITE` | |
 | `$call` `(` IDENT `)` | `TExprCall(name)` | Zero-arg user function by name. |