@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/dispatch.js

@@ -3,30 +3,398 @@
  *
  * Every store parses the input url, switches on `fn`, and calls back
  * into store-supplied handlers. Centralising the dispatch keeps the
- * `read`/`ls`/`count`/`x-*` switch identical across stores so they
- * cannot drift apart.
+ * `read`/`ls`/`find`/`count`/`x-*` switch identical across stores so
+ * they cannot drift apart.
  *
  * Stores call `dispatchRead(urls, handlers)`; the helper handles
  * parsing, the fn switch, and tuple assembly. Each handler receives
  * the parsed url and returns the payload — the helper wraps it into
  * `[inputUrl, payload]`.
+ *
+ * v2 listing-spec additions (see `.cc-chat/20260625121936-grammar-shape`):
+ *
+ * - **`find` case** — requires an explicit `handlers.find` registration
+ *   (mirrors the `ext?:` opt-in pattern). When `handlers.find` is
+ *   absent, dispatch throws via the same "unsupported fn" path as any
+ *   unknown verb — no silent fall-back through `ls`. Stores that
+ *   support deep walks must wire their own `find` handler (push-down
+ *   into the backend, or an in-process recursive walk built on `ls`).
+ *   See spec §3.5: a store that does not advertise `"find"` in
+ *   `status().fns` MUST throw on `fn=find`.
+ *
+ * - **`count` case (URL-shape-aware)** — `fn=count` is valid under any
+ *   URL shape (spec §3.2). Dispatch keeps the existing `handlers.count`
+ *   path for no-wildcard and shallow-wildcard URLs. When the URL carries
+ *   a `**` glob, `count` mirrors `find`'s deep walk: either the store
+ *   has set `pushDownCount: true` (dispatch trusts `handlers.count` to
+ *   run the deep COUNT in-backend) or dispatch calls `handlers.find` and
+ *   returns the length of the walked result. If the store advertises
+ *   neither (`pushDownCount` false AND no `handlers.find`), dispatch
+ *   throws "unsupported fn 'count'" — no silent shallow-count fall-back,
+ *   same loud-failure rule as `fn=find` (§3.5).
+ *
+ * - **cursor-as-trailing-slot** — when `find` or `ls` is called with
+ *   `limit=<n>`, dispatch appends ONE extra `Output` to the returned
+ *   array: `[<cursor-uri>, { next: "<opaque>" | null }]`. The cursor
+ *   URI is the original locator with `cursor=<opaque>` added (or
+ *   replaced). `next: null` signals end-of-result; otherwise `next` is
+ *   the opaque token to re-issue the request. The caller can do
+ *   `read([slot.uri])` literally and walk the next page.
  */
+import { compareSortable, projectRecord } from "./read.js";
+import { compileSaveGlob, matchesGlob } from "./glob.js";
 import { parseUrl } from "./url.js";
+/**
+ * Filter a sorted row list to entries strictly past the cursor.
+ * `cursor` is a URI from a previous page; with `sortOrder=asc` (default)
+ * we drop rows up to and including the cursor, with `desc` we drop rows
+ * at or after it. Comparison is the same `localeCompare` used by the
+ * default URI sort, so cursor pagination tracks the sort direction.
+ */
+function filterByCursor(rows, cursor, sortOrder) {
+    const desc = sortOrder === "desc";
+    return rows.filter(([uri]) => desc ? uri.localeCompare(cursor) < 0 : uri.localeCompare(cursor) > 0);
+}
+/**
+ * Read a named field from a payload, returning `undefined` for any
+ * non-record payload (eg `Uint8Array`, `ReadableStream`, miss). Used
+ * by the dispatch post-sort path so non-uri sortBy works against the
+ * `EntityRecord` shape returned by handlers.
+ */
+function recordField(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "object")
+        return undefined;
+    if (value instanceof Uint8Array)
+        return undefined;
+    if (value instanceof ReadableStream)
+        return undefined;
+    return value[field];
+}
+/** Same as `filterByCursor` but for `format=uris` payloads. */
+function filterUrisByCursor(uris, cursor, sortOrder) {
+    const desc = sortOrder === "desc";
+    return uris.filter((uri) => desc ? uri.localeCompare(cursor) < 0 : uri.localeCompare(cursor) > 0);
+}
+/**
+ * Compose the trailing cursor slot for a paginated `find` / `ls`
+ * response. Returns `[cursorUri, { next }]` where `cursorUri` is the
+ * original input url with `cursor=<opaque>` added (or replaced; every
+ * other param is preserved). `next` is the opaque token (the URI of
+ * the last entry returned) when more results are available, `null`
+ * when the page was the tail of the result set.
+ *
+ * The slot is appended UNCONDITIONALLY when `limit` was set in the
+ * request — callers shouldn't have to special-case "this might be the
+ * last page" or "this is empty"; the `next: null` case carries that
+ * signal. Re-issue is `read([slot.uri])` literally.
+ *
+ * URI composition: we operate on the original input url string (not
+ * `parsed.uri`) so the URI-embedded glob portion (`**`, etc.) is
+ * preserved. `cursor=` is set/replaced in place via URLSearchParams.
+ */
+function buildCursorSlot(inputUrl, cursorForUri, next) {
+    const qIdx = inputUrl.indexOf("?");
+    const uriPart = qIdx < 0 ? inputUrl : inputUrl.slice(0, qIdx);
+    const queryPart = qIdx < 0 ? "" : inputUrl.slice(qIdx + 1);
+    const sp = new URLSearchParams(queryPart);
+    // The cursor URI is the re-issuable locator: every other param
+    // preserved, `cursor=` set to the last row's URI we returned (so the
+    // caller can re-issue and get the next page — or, if we already
+    // returned the tail, get an empty page + `next: null`). When the
+    // page was empty entirely (no rows at all), there is no last URI to
+    // hang a cursor on; we drop it so the URI matches a fresh request.
+    if (cursorForUri !== null) {
+        sp.set("cursor", cursorForUri);
+    }
+    else {
+        sp.delete("cursor");
+    }
+    const qs = sp.toString();
+    const cursorUri = qs ? `${uriPart}?${qs}` : uriPart;
+    return [cursorUri, { next }];
+}
+/**
+ * Type guard: is the row a plain `Output` tuple (`[uri, payload]`).
+ * Used after we strip the cursor slot before applying further
+ * transformations to find/ls payloads.
+ */
+function lastUriOfRows(rows) {
+    if (rows.length === 0)
+        return null;
+    const last = rows[rows.length - 1];
+    if (typeof last === "string")
+        return last;
+    if (Array.isArray(last) && typeof last[0] === "string")
+        return last[0];
+    return null;
+}
 export async function dispatchRead(urls, storeName, handlers) {
     const out = [];
     for (const url of urls) {
         const parsed = parseUrl(url);
+        // Validate the combos dispatch itself enforces before stripping
+        // anything from the handler call, otherwise validateReadParams
+        // inside the handler never sees the original shape.
+        if (parsed.params.cursor !== undefined && parsed.params.page !== undefined) {
+            throw new Error(`${storeName}: cursor and page cannot be combined — pick one pagination mode`);
+        }
         let payload;
+        const fields = parsed.params.fields;
+        const pattern = parsed.params.pattern;
+        const cursor = parsed.params.cursor;
+        const sortBy = parsed.params.sortBy;
+        const needsPatternPostFilter = pattern !== undefined &&
+            !handlers.pushDownPattern;
+        const needsCursorPostFilter = cursor !== undefined &&
+            !handlers.pushDownCursor;
+        // Non-uri sortBy needs dispatch post-sort unless the backend
+        // explicitly handles arbitrary sortBy itself. `leaf` is a
+        // dispatch-level sort (basename localeCompare); it always
+        // post-sorts.
+        const needsSortByPostSort = sortBy !== undefined && sortBy !== "uri" &&
+            !handlers.pushDownSortBy;
         switch (parsed.fn) {
             case "read":
                 payload = await handlers.read(parsed);
+                if (fields && fields.length > 0) {
+                    payload = projectRecord(payload, fields);
+                }
                 break;
             case "ls":
-                payload = await handlers.ls(parsed);
+            case "find": {
+                const isFind = parsed.fn === "find";
+                // v2 §3.5: a store that does not advertise `"find"` in
+                // status().fns MUST throw on fn=find. We enforce that at the
+                // dispatch level by requiring an explicit `handlers.find`
+                // registration — no silent fall-back through `ls`. Error shape
+                // matches the unknown-fn throw below so existing callers can
+                // detect it the same way.
+                if (isFind && !handlers.find) {
+                    throw new Error(`${storeName}: unsupported fn 'find'`);
+                }
+                const format = parsed.params.format ?? "full";
+                // For find, `handlers.find` is guaranteed present by the guard
+                // above. For ls, the handler is `handlers.ls`.
+                const lsLikeHandler = isFind ? handlers.find : handlers.ls;
+                if (needsPatternPostFilter || needsCursorPostFilter ||
+                    needsSortByPostSort) {
+                    // Dispatch handles pattern/cursor/sortBy + pagination +
+                    // projection itself, so it asks the backend for the full
+                    // result first. Stripping `limit`/`page` is necessary so the
+                    // backend doesn't truncate the set before the filters run;
+                    // stripping `pattern`/`cursor`/non-uri `sortBy` is necessary
+                    // so backends that don't recognise them don't error out.
+                    // For non-uri sortBy we also have to force `format=full`
+                    // since records (not just URIs) are needed to read the
+                    // sort field.
+                    const handlerParams = { ...parsed.params };
+                    delete handlerParams.limit;
+                    delete handlerParams.page;
+                    delete handlerParams.fields;
+                    delete handlerParams.cursor;
+                    if (needsPatternPostFilter)
+                        delete handlerParams.pattern;
+                    const handlerFormat = needsSortByPostSort && format === "uris"
+                        ? "full"
+                        : format;
+                    handlerParams.format = handlerFormat;
+                    if (needsSortByPostSort)
+                        handlerParams.sortBy = "uri";
+                    const raw = await lsLikeHandler({
+                        ...parsed,
+                        params: handlerParams,
+                    });
+                    if (!Array.isArray(raw)) {
+                        payload = raw;
+                        break;
+                    }
+                    let arr = raw;
+                    if (needsPatternPostFilter) {
+                        // Hoist the compiled glob — the row loop is the only hot
+                        // spot we know about and the compile cost is non-trivial.
+                        const re = compileSaveGlob(pattern);
+                        arr = handlerFormat === "uris"
+                            ? arr.filter((uri) => uri.startsWith(parsed.uri) &&
+                                re.test(uri.slice(parsed.uri.length)))
+                            : arr.filter(([uri]) => uri.startsWith(parsed.uri) &&
+                                re.test(uri.slice(parsed.uri.length)));
+                    }
+                    if (needsCursorPostFilter) {
+                        arr = handlerFormat === "uris"
+                            ? filterUrisByCursor(arr, cursor, parsed.params.sortOrder)
+                            : filterByCursor(arr, cursor, parsed.params.sortOrder);
+                    }
+                    if (needsSortByPostSort) {
+                        // We forced format=full above, so arr is Array<Output>.
+                        const dir = parsed.params.sortOrder === "desc" ? -1 : 1;
+                        if (sortBy === "leaf") {
+                            arr = [...arr].sort(([a], [b]) => leafOf(a).localeCompare(leafOf(b)) * dir);
+                        }
+                        else {
+                            arr = [...arr].sort(([, a], [, b]) => {
+                                const av = recordField(a, sortBy);
+                                const bv = recordField(b, sortBy);
+                                return compareSortable(av, bv) * dir;
+                            });
+                        }
+                    }
+                    let truncated = false;
+                    if (parsed.params.limit !== undefined) {
+                        // page is incompatible with cursor (validateReadParams
+                        // throws on that combo); when only `page` is set the
+                        // page-based offset still applies.
+                        const start = needsCursorPostFilter
+                            ? 0
+                            : ((parsed.params.page ?? 1) - 1) * parsed.params.limit;
+                        const end = start + parsed.params.limit;
+                        truncated = arr.length > end;
+                        arr = arr.slice(start, end);
+                    }
+                    // If we forced format=full to access the sort field but the
+                    // caller asked for uris, project down to uris at the end.
+                    if (handlerFormat === "full" && format === "uris") {
+                        arr = arr.map(([uri]) => uri);
+                    }
+                    else if (fields && fields.length > 0 && format === "full") {
+                        arr = arr.map(([uri, record]) => [
+                            uri,
+                            projectRecord(record, fields),
+                        ]);
+                    }
+                    // Append cursor-as-trailing-slot whenever `limit` was set.
+                    // `cursorForUri`: the URI of the last row returned (or null if
+                    // the page was empty) — used to compose a re-issuable locator.
+                    // `next`: the opaque cursor for the next page, or `null` when
+                    // the page was the tail of the result set.
+                    if (parsed.params.limit !== undefined) {
+                        const lastUri = lastUriOfRows(arr);
+                        const next = truncated ? lastUri : null;
+                        arr = [...arr, buildCursorSlot(url, lastUri, next)];
+                    }
+                    payload = arr;
+                    break;
+                }
+                // Fast pass-through: the backend handled (or accepted) every
+                // param itself. We only need to optionally project the
+                // returned records and append the cursor slot.
+                const raw = await lsLikeHandler(parsed);
+                if (fields && fields.length > 0 && Array.isArray(raw) &&
+                    format === "full") {
+                    payload = raw.map(([uri, record]) => [
+                        uri,
+                        projectRecord(record, fields),
+                    ]);
+                }
+                else {
+                    payload = raw;
+                }
+                if (parsed.params.limit !== undefined && Array.isArray(payload)) {
+                    // We don't know if the backend truncated — the only safe
+                    // signal we have is "did we return `limit` items"; if we
+                    // did, callers should re-issue. False positives (cursor
+                    // points past the end) are correctness-safe: the next call
+                    // returns an empty page + a `next: null` slot.
+                    const arr = payload;
+                    const isFull = arr.length >= parsed.params.limit;
+                    const lastUri = lastUriOfRows(arr);
+                    const next = isFull ? lastUri : null;
+                    payload = [...arr, buildCursorSlot(url, lastUri, next)];
+                }
                 break;
-            case "count":
-                payload = await handlers.count(parsed);
+            }
+            case "count": {
+                // v2 §3.2: `count` honors any URL shape. A `**` glob in the URL
+                // means "count of all descendants" (the find-flavored count).
+                // The shallow ls-based filtered-count path below cannot serve
+                // that — handlers.ls returns one segment deep — so dispatch
+                // either routes to handlers.count (push-down opt-in) or walks
+                // via handlers.find and returns the length. Without either,
+                // throw rather than silently return a shallow count.
+                const isDeepCount = parsed.glob.includes("**");
+                if (isDeepCount && handlers.pushDownCount) {
+                    // Push-down deep count: trust the backend to translate the
+                    // full URL (glob included) into an efficient COUNT. Skip the
+                    // ls-based filtered-count path below — that path was designed
+                    // for shallow `?` / `*` filters and would short-circuit
+                    // through ls instead of count.
+                    payload = await handlers.count(parsed);
+                    break;
+                }
+                if (isDeepCount && !handlers.pushDownCount) {
+                    if (!handlers.find) {
+                        throw new Error(`${storeName}: unsupported fn 'count'`);
+                    }
+                    // In-process deep count via the find walk. We post-filter
+                    // against the user's glob (same rule the find path applies
+                    // when pushDownPattern is off) so a handler that walks an
+                    // over-broad prefix cannot inflate the count. Pagination
+                    // params are stripped — we want the full set to count, never
+                    // a page.
+                    const handlerParams = { ...parsed.params };
+                    delete handlerParams.limit;
+                    delete handlerParams.page;
+                    delete handlerParams.fields;
+                    delete handlerParams.cursor;
+                    if (!handlers.pushDownPattern)
+                        delete handlerParams.pattern;
+                    // Force a record-shape result so we can count tuples without
+                    // dealing with the `string[]` / `Output[]` branch — the format
+                    // is invisible to the caller, who only sees the count number.
+                    handlerParams.format = "full";
+                    const raw = await handlers.find({
+                        ...parsed,
+                        params: handlerParams,
+                    });
+                    if (!Array.isArray(raw)) {
+                        payload = 0;
+                        break;
+                    }
+                    let rows = raw;
+                    if (pattern !== undefined && !handlers.pushDownPattern) {
+                        const re = compileSaveGlob(pattern);
+                        rows = rows.filter(([uri]) => uri.startsWith(parsed.uri) &&
+                            re.test(uri.slice(parsed.uri.length)));
+                    }
+                    payload = rows.length;
+                    break;
+                }
+                if (needsPatternPostFilter || needsCursorPostFilter) {
+                    // Filtered count: list the matching URIs (cheap
+                    // `format=uris` path, no payload load) and return the
+                    // length. Slower than push-down COUNT, but the only way to
+                    // honour pattern/cursor without per-backend query
+                    // translation.
+                    const lsParams = {
+                        ...parsed.params,
+                        format: "uris",
+                    };
+                    delete lsParams.fields;
+                    delete lsParams.limit;
+                    delete lsParams.page;
+                    delete lsParams.cursor;
+                    if (needsPatternPostFilter)
+                        delete lsParams.pattern;
+                    const raw = await handlers.ls({ ...parsed, params: lsParams });
+                    if (!Array.isArray(raw)) {
+                        payload = 0;
+                        break;
+                    }
+                    let uris = raw;
+                    if (needsPatternPostFilter) {
+                        uris = uris.filter((uri) => matchesGlob(uri, parsed.uri, pattern));
+                    }
+                    if (needsCursorPostFilter) {
+                        uris = filterUrisByCursor(uris, cursor, parsed.params.sortOrder);
+                    }
+                    payload = uris.length;
+                }
+                else {
+                    payload = await handlers.count(parsed);
+                }
                 break;
+            }
             default:
                 if (parsed.fn.startsWith("x-") && handlers.ext) {
                     payload = await handlers.ext(parsed);
@@ -38,3 +406,11 @@ export async function dispatchRead(urls, storeName, handlers) {
     }
     return out;
 }
+// Local copy of leafOf to avoid an extra import — same recipe as
+// read.ts's exported helper. Keeping it local keeps the dispatch
+// module's import surface tight (we already pull compareSortable,
+// projectRecord, and the glob helpers).
+function leafOf(uri) {
+    const idx = uri.lastIndexOf("/");
+    return idx < 0 ? uri : uri.slice(idx + 1);
+}

package/esm/elasticsearch/store.d.ts

@@ -1,44 +1,143 @@
 /**
- * ElasticsearchStore — Elasticsearch implementation of Store.
- *
- * Pure mechanical byte storage with no protocol awareness. URIs are
- * partitioned into one index per `protocol_hostname` pair, with the
- * path as the document `_id`. Payload bytes are base64-encoded into a
- * string field — ES has no native binary type that round-trips
- * arbitrary bytes through `_source`.
- *
- * `fn=ls` / `fn=count` are pushed down via an ES regex query that
- * enforces the shallow-direct-leaves contract: `<docPrefix>[^/]+`.
- * Lucene regex queries are auto-anchored, so the pattern must match
- * the full `_id`.
+ * ElasticsearchStore — Elasticsearch implementation of `EntityStore`.
+ *
+ * One backend, many entities. Per-entity index naming partitions
+ * documents in a way that keeps queries simple:
+ *
+ * - `BYTES_ENTITY` → index `{indexPrefix}_{protocol}_{hostname}`,
+ *   docId = uri path. Document `_source` carries `payload` (base64)
+ *   and a mirrored `path` field that `ls`/`count` regex-queries hit
+ *   (ES 8 disallows regex on `_id`). This is the original layout —
+ *   no migration.
+ * - any other schema → index
+ *   `{indexPrefix}_{entityName}_{protocol}_{hostname}`, same docId
+ *   convention. Document `_source` carries the record fields encoded
+ *   per canonical `TYPE_TAGS` (bytes → base64, bigint → string,
+ *   timestamp → ISO-8601 — see `./fields.ts`) plus the mirrored
+ *   `path` field.
+ *
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it plans the field set and computes
+ * a collision signature. `provisionEntity(meta)` writes a tiny meta
+ * doc to `{indexPrefix}__meta__/entities` keyed by entity name, body
+ * `{signature}`; subsequent `entityStatus(meta)` reads it back. The
+ * meta doc is also used by `status()` to list provisioned entities.
+ *
+ * ## Read params
+ *
+ * `fn=ls` / `fn=count` push down to an ES regex query against the
+ * mirrored `path.keyword` field with the shallow-direct-leaves
+ * predicate `<docPrefix>[^/]+`. Standard params (`limit`/`page`/
+ * `sortBy=uri`/`sortOrder`/`format`) translate to `size`/`from`/`sort`,
+ * with `_source: false` for the `format=uris` fast path.
+ *
+ * `fn=find` (v2 §3.3) reuses the regex query shape but composes the
+ * body from `saveGlobToRegexBody(pattern)` directly — `**` → `.*`
+ * (crosses `/`), so the same query that backs `ls` walks the entire
+ * subtree. The query stays prefix-anchored on `path.keyword` (a
+ * `keyword` field with a term dictionary), which Lucene can serve via
+ * its `RegexpQuery` using DFA traversal of the term dictionary;
+ * prefix-anchored regexes are the fast case (the engine restricts the
+ * scan to terms whose common prefix matches the regex's required
+ * prefix). The default `[^/]+` shallow body that `_leafQuery` falls
+ * back to when no pattern is set is NOT reachable from the find path:
+ * `parseUrl` guarantees `params.pattern` is populated whenever
+ * `fn=find` dispatches here (URI-embedded glob or the dual-accept
+ * `?pattern=` form).
+ *
+ * `pushDownCount: true` — ES has a native `_count` API that runs the
+ * same query shape without scoring or document materialisation. Deep
+ * counts (URLs containing `**`) route directly to `_count` with the
+ * `saveGlobToRegexBody`-composed regex; dispatch never walks via
+ * `handlers.find` to count.
  */
-import type { DeleteResult, Output, StatusResult } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
-import { type BytesOnlyEntityMeta } from "../byte-entity-shim.js";
+import type { DeleteResult, Output, StatusResult } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/src/types/types.js";
 import type { EntityStore } from "../entity-store.js";
-import type { EntityRecord, EntitySchema } from "../entity.js";
+import { type EntityMeta, type EntityRecord, type EntitySchema } from "../entity.js";
 import type { StoreCapabilities, StoreWriteResult } from "../types.js";
+import { type FieldPlan } from "../json-fields.js";
 import type { ElasticsearchExecutor } from "./mod.js";
-export declare class ElasticsearchStore implements EntityStore<BytesOnlyEntityMeta> {
+/**
+ * ElasticsearchStore-specific entity handle.
+ *
+ * `indexInfix` is `""` for BYTES_ENTITY (current layout) or
+ * `{entityName}_` for custom entities — it's spliced between the
+ * store-level `indexPrefix` and the URI's `protocol_hostname` to
+ * partition documents by entity without changing the docId scheme.
+ * `isBytes` selects the legacy bytes-payload doc shape vs the
+ * JSON-encoded record shape. `fields`/`declared`/`bytesFields` drive
+ * write-time validation and encoding; `signature` is used for
+ * collision detection in `entityStatus` / `provisionEntity`.
+ */
+export interface ElasticsearchEntityMeta extends EntityMeta {
+    readonly indexInfix: string;
+    readonly isBytes: boolean;
+    readonly fields: readonly FieldPlan[];
+    readonly declared: ReadonlySet<string>;
+    readonly bytesFields: ReadonlySet<string>;
+    readonly signature: string;
+}
+export declare class ElasticsearchStore implements EntityStore<ElasticsearchEntityMeta> {
     private readonly indexPrefix;
     private readonly executor;
     constructor(indexPrefix: string, executor: ElasticsearchExecutor);
-    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
-    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
-    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
-    write(meta: BytesOnlyEntityMeta, entries: {
+    entitySupport(schema: EntitySchema): ElasticsearchEntityMeta;
+    entityStatus(meta: ElasticsearchEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(meta: ElasticsearchEntityMeta): Promise<void>;
+    write(meta: ElasticsearchEntityMeta, entries: {
         uri: string;
         record: EntityRecord;
     }[]): Promise<StoreWriteResult[]>;
-    read<T = EntityRecord | undefined>(meta: BytesOnlyEntityMeta, urls: string[]): Promise<Output<T>[]>;
-    delete(meta: BytesOnlyEntityMeta, uris: string[]): Promise<DeleteResult[]>;
-    private _writeBytes;
-    private _readBytes;
+    read<T = EntityRecord | undefined>(meta: ElasticsearchEntityMeta, urls: string[]): Promise<Output<T>[]>;
     private _readOne;
+    /**
+     * Lucene regex query for shallow direct-leaves under `docPrefix`.
+     * Pattern push-down: splice the glob's regex body in place of the
+     * default `[^/]+`. Cursor push-down: wrap the regex in a `bool`
+     * with a `range` on `path.keyword` (`gt` for asc, `lt` for desc).
+     */
     private _leafQuery;
     private _ls;
+    /**
+     * Lucene regex query for the deep walk (`fn=find`) under
+     * `docPrefix`. Mirrors `_leafQuery` but REQUIRES a pattern: parseUrl
+     * guarantees `params.pattern` is populated whenever fn=find
+     * dispatches here (URI-embedded glob or dual-accept `?pattern=`).
+     * If pattern is absent we throw rather than silently widening to
+     * `.*` — that would conflate "find everything" with a parser bug.
+     *
+     * The composed body uses `saveGlobToRegexBody` (which emits `.*` for
+     * `**`, crossing `/`), prepended with the escaped `docPrefix`. The
+     * resulting regex is prefix-anchored on the keyword field — Lucene
+     * restricts the term-dictionary scan to terms starting with the
+     * required literal prefix, so even broad `**` queries don't degrade
+     * to a full term scan.
+     */
+    private _subtreeQuery;
+    private _find;
     private _count;
-    private _deleteBytes;
+    delete(meta: ElasticsearchEntityMeta, uris: string[]): Promise<DeleteResult[]>;
     status(): Promise<StatusResult>;
     capabilities(): StoreCapabilities;
+    /** Per-entity, per-`protocol_hostname` data index. */
+    private _dataIndex;
+    /** Single meta index holding `{name → signature}` provisioning records. */
+    private _metaIndex;
+    /**
+     * Read the persisted signature for an entity, or `null` if no
+     * provisioning record exists.
+     */
+    private _readMetaSignature;
+    /**
+     * Scan the meta index for every provisioned entity name. Used by
+     * `status()` to advertise the entities a peer can talk to.
+     */
+    private _listProvisionedEntities;
+    /**
+     * Collect any `ReadableStream` values on `bytes`-tagged fields into
+     * `Uint8Array` and return a shallow-copied record.
+     */
+    private _normaliseBytesFields;
 }
 //# sourceMappingURL=store.d.ts.map

package/esm/elasticsearch/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/elasticsearch/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAC3E,OAAO,EAEL,KAAK,mBAAmB,EAIzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAQ/D,OAAO,KAAK,EACV,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAwCtD,qBAAa,kBAAmB,YAAW,WAAW,CAAC,mBAAmB,CAAC;IACzE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;gBAErC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB;IAUhE,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,mBAAmB;IAIxD,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAI1E,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,KAAK,CACH,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAS9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IASvB,MAAM,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAW5D,WAAW;IAkCzB,OAAO,CAAC,UAAU;YAQJ,QAAQ;IAOtB,OAAO,CAAC,UAAU;YAQJ,GAAG;YAoCH,MAAM;YAQN,YAAY;IAqBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAyBrC,YAAY,IAAI,iBAAiB;CAGlC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/elasticsearch/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAQ3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAIL,KAAK,SAAS,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AA4BtD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAwB,SAAQ,UAAU;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAmCD,qBAAa,kBACX,YAAW,WAAW,CAAC,uBAAuB,CAAC;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;gBAErC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB;IAUhE,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,uBAAuB;IA0CtD,YAAY,CAChB,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAM9B,eAAe,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB7D,KAAK,CACT,IAAI,EAAE,uBAAuB,EAC7B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA0E9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAcT,QAAQ;IAkBtB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;YAwBJ,GAAG;IAyEjB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,aAAa;YA8BP,KAAK;YA0DL,MAAM;IAyBd,MAAM,CACV,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,YAAY,EAAE,CAAC;IAmCpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IA2BrC,YAAY,IAAI,iBAAiB;IAMjC,sDAAsD;IACtD,OAAO,CAAC,UAAU;IAQlB,2EAA2E;IAC3E,OAAO,CAAC,UAAU;IAIlB;;;OAGG;YACW,kBAAkB;IAYhC;;;OAGG;YACW,wBAAwB;IAYtC;;;OAGG;YACW,qBAAqB;CAmBpC"}