@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/elasticsearch/store.js

@@ -1,49 +1,112 @@
 /**
- * ElasticsearchStore — Elasticsearch implementation of Store.
+ * ElasticsearchStore — Elasticsearch implementation of `EntityStore`.
  *
- * 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`.
+ * One backend, many entities. Per-entity index naming partitions
+ * documents in a way that keeps queries simple:
  *
- * `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`.
+ * - `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 { bytesOnlyDelete, bytesOnlyEntitySupport, bytesOnlyRead, bytesOnlyWrite, } from "../byte-entity-shim.js";
-import { decodeBase64, encodeBase64 } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.js";
+import { decodeBase64, encodeBase64 } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/mod.js";
 import { dispatchRead } from "../dispatch.js";
 import { storageFailure } from "../errors.js";
 import { toBytes } from "../payload.js";
 import { validateReadParams } from "../read.js";
+import { saveGlobToRegexBody } from "../glob.js";
+import { BYTES_ENTITY, } from "../entity.js";
+import { IDENTIFIER_PATTERN, isValidIdentifier } from "../identifiers.js";
+import { computeSignature, decodeRecord, encodeRecord, planFields, } from "../json-fields.js";
 const STORE_NAME = "ElasticsearchStore";
+const META_INDEX_SUFFIX = "__meta__";
 /** Escape characters that are special in Lucene regex syntax. */
 function escapeLuceneRegex(input) {
     return input.replace(/[.?+*|{}\[\]()"\\#@&<>~]/g, "\\$&");
 }
 /**
- * Parse a URI into an Elasticsearch index name and document ID.
- * `protocol://hostname/path` → index: `prefix_protocol_hostname`,
- * docId: `path` (without leading slash).
+ * Parse a URI into the `(protocol, hostname, docId)` tuple. ES index
+ * naming gets layered on top by each entity meta.
  */
-function uriToIndexAndDocId(uri, indexPrefix) {
+function uriParts(uri) {
     const url = new URL(uri);
-    const protocol = url.protocol.replace(":", "");
-    const hostname = url.hostname;
     return {
-        index: `${indexPrefix}_${protocol}_${hostname}`,
+        protocol: url.protocol.replace(":", ""),
+        hostname: url.hostname,
         docId: url.pathname.substring(1),
     };
 }
-/** Reconstruct a URI from an index name + document ID. */
-function indexAndDocIdToUri(index, indexPrefix, docId) {
-    const withoutPrefix = index.substring(indexPrefix.length + 1);
-    const firstUnderscore = withoutPrefix.indexOf("_");
-    const protocol = withoutPrefix.substring(0, firstUnderscore);
-    const hostname = withoutPrefix.substring(firstUnderscore + 1);
-    return `${protocol}://${hostname}/${docId}`;
+function isBytesSchema(schema) {
+    return schema.name === BYTES_ENTITY.name;
+}
+/**
+ * Pick the right ES field name to sort on for a declared user field.
+ * Any string-encoded value (strings, base64-encoded bytes, decimal
+ * bigint strings, ISO timestamps) hits the dynamic `.keyword` subfield
+ * since ES 8+ disables fielddata on `text` by default; native numeric
+ * and boolean fields sort on the field directly; `json` fields aren't
+ * sortable, so we return `null` and let dispatch's post-sort fallback
+ * handle them.
+ */
+function esSortField(meta, fieldName) {
+    const plan = meta.fields.find((f) => f.name === fieldName);
+    if (!plan)
+        return null;
+    switch (plan.tag) {
+        case "string":
+        case "bytes":
+        case "bigint":
+        case "timestamp":
+            return `${fieldName}.keyword`;
+        case "number":
+        case "boolean":
+            return fieldName;
+        default:
+            return null;
+    }
 }
 export class ElasticsearchStore {
     indexPrefix;
@@ -56,87 +119,292 @@ export class ElasticsearchStore {
         this.indexPrefix = indexPrefix;
         this.executor = executor;
     }
-    // ── EntityStore surface ──────────────────────────────────────────
+    // ── Lifecycle ────────────────────────────────────────────────────
     entitySupport(schema) {
-        return bytesOnlyEntitySupport(schema);
-    }
-    entityStatus(meta) {
-        return Promise.resolve(meta.isBytes ? "live" : "unprovisioned");
-    }
-    provisionEntity(_meta) {
-        return Promise.resolve();
-    }
-    write(meta, entries) {
-        return bytesOnlyWrite(meta, STORE_NAME, entries, (e) => this._writeBytes(e));
+        if (isBytesSchema(schema)) {
+            const fields = [{ name: "payload", tag: "bytes" }];
+            return {
+                support: {
+                    entity: schema.name,
+                    supported: ["payload"],
+                    unsupported: [],
+                },
+                indexInfix: "",
+                isBytes: true,
+                fields,
+                declared: new Set(["payload"]),
+                bytesFields: new Set(["payload"]),
+                signature: computeSignature(schema.name, fields),
+            };
+        }
+        if (!isValidIdentifier(schema.name)) {
+            throw new Error(`${STORE_NAME}: entity name '${schema.name}' must match ${IDENTIFIER_PATTERN.source}`);
+        }
+        const { fields, unsupported } = planFields(schema.fields);
+        const declared = new Set(fields.map((f) => f.name));
+        const bytesFields = new Set(fields.filter((f) => f.tag === "bytes").map((f) => f.name));
+        return {
+            support: {
+                entity: schema.name,
+                supported: fields.map((f) => f.name),
+                unsupported,
+            },
+            indexInfix: `${schema.name}_`,
+            isBytes: false,
+            fields,
+            declared,
+            bytesFields,
+            signature: computeSignature(schema.name, fields),
+        };
     }
-    read(meta, urls) {
-        return bytesOnlyRead(meta, STORE_NAME, urls, (u) => this._readBytes(u));
+    async entityStatus(meta) {
+        const recorded = await this._readMetaSignature(meta.support.entity);
+        if (recorded === null)
+            return "unprovisioned";
+        return recorded === meta.signature ? "live" : "unprovisioned";
     }
-    delete(meta, uris) {
-        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    async provisionEntity(meta) {
+        const recorded = await this._readMetaSignature(meta.support.entity);
+        if (recorded !== null) {
+            if (recorded !== meta.signature) {
+                throw new Error(`${STORE_NAME}: entity '${meta.support.entity}' is already ` +
+                    `provisioned with a different shape`);
+            }
+            return;
+        }
+        await this.executor.index(this._metaIndex(), meta.support.entity, { signature: meta.signature });
     }
-    // ── Byte ops (BYTES_ENTITY routing) ──────────────────────────────
-    async _writeBytes(entries) {
+    // ── Write ────────────────────────────────────────────────────────
+    async write(meta, entries) {
+        if (entries.length === 0)
+            return [];
+        if ((await this._readMetaSignature(meta.support.entity)) !== meta.signature) {
+            return entries.map(({ uri }) => ({
+                success: false,
+                ...storageFailure(new Error(`${STORE_NAME}: entity '${meta.support.entity}' is not provisioned`), "Entity not provisioned", uri),
+            }));
+        }
         const results = [];
-        for (const entry of entries) {
-            try {
-                const { index, docId } = uriToIndexAndDocId(entry.uri, this.indexPrefix);
-                // We mirror docId into a `path` source field so `ls`/`count`
-                // can run analyzed queries against it — ES 8 disallows
-                // `regexp` (and prefix/wildcard) against the `_id` metadata
-                // field. ES's default dynamic mapping for a string source
-                // field produces `path` (text) + `path.keyword` (keyword);
-                // we target `path.keyword` for exact-match regex push-down.
-                const bytes = await toBytes(entry.payload);
-                await this.executor.index(index, docId, {
-                    payload: encodeBase64(bytes),
-                    path: docId,
+        for (const { uri, record } of entries) {
+            const extras = Object.keys(record).filter((k) => !meta.declared.has(k));
+            if (extras.length > 0) {
+                results.push({
+                    success: false,
+                    ...storageFailure(new Error(`record contains keys not declared in schema '${meta.support.entity}': ${extras.join(", ")}`), "Schema mismatch", uri),
                 });
+                continue;
+            }
+            try {
+                const { protocol, hostname, docId } = uriParts(uri);
+                const index = this._dataIndex(meta, protocol, hostname);
+                let body;
+                if (meta.isBytes) {
+                    const payload = record.payload;
+                    if (!(payload instanceof Uint8Array) &&
+                        !(payload instanceof ReadableStream)) {
+                        throw new Error("BYTES_ENTITY record.payload must be Uint8Array or ReadableStream");
+                    }
+                    const bytes = await toBytes(payload);
+                    body = { payload: encodeBase64(bytes), path: docId };
+                }
+                else {
+                    const normalised = await this._normaliseBytesFields(record, meta.bytesFields);
+                    body = {
+                        ...encodeRecord(meta.fields, normalised),
+                        path: docId,
+                    };
+                }
+                await this.executor.index(index, docId, body);
                 results.push({ success: true });
             }
             catch (err) {
                 results.push({
                     success: false,
-                    ...storageFailure(err, "Write failed", entry.uri),
+                    ...storageFailure(err, "Write failed", uri),
                 });
             }
         }
         return results;
     }
-    _readBytes(urls) {
+    // ── Read ─────────────────────────────────────────────────────────
+    read(meta, urls) {
         return dispatchRead(urls, STORE_NAME, {
-            read: (p) => this._readOne(p.uri),
-            ls: (p) => this._ls(p),
-            count: (p) => this._count(p),
+            read: (p) => this._readOne(meta, p.uri),
+            ls: (p) => this._ls(meta, p),
+            count: (p) => this._count(meta, p),
+            find: (p) => this._find(meta, p),
+            pushDownPattern: true,
+            pushDownCursor: true,
+            pushDownSortBy: true,
+            pushDownFind: true,
+            pushDownCount: true,
         });
     }
-    async _readOne(uri) {
-        const { index, docId } = uriToIndexAndDocId(uri, this.indexPrefix);
-        const doc = await this.executor.get(index, docId);
-        if (!doc)
+    async _readOne(meta, uri) {
+        try {
+            const { protocol, hostname, docId } = uriParts(uri);
+            const index = this._dataIndex(meta, protocol, hostname);
+            const doc = await this.executor.get(index, docId);
+            if (!doc)
+                return undefined;
+            if (meta.isBytes) {
+                return { payload: decodeBase64(doc.payload) };
+            }
+            return decodeRecord(meta.fields, doc);
+        }
+        catch {
             return undefined;
-        return decodeBase64(doc.payload);
+        }
     }
-    _leafQuery(docPrefix) {
+    /**
+     * 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).
+     */
+    _leafQuery(docPrefix, pattern, cursorPath, sortOrder) {
+        const body = pattern !== undefined ? saveGlobToRegexBody(pattern) : "[^/]+";
+        const regex = {
+            regexp: {
+                "path.keyword": `${escapeLuceneRegex(docPrefix)}${body}`,
+            },
+        };
+        if (cursorPath === undefined)
+            return regex;
+        const rangeKey = sortOrder === "desc" ? "lt" : "gt";
         return {
+            bool: {
+                must: [
+                    regex,
+                    { range: { "path.keyword": { [rangeKey]: cursorPath } } },
+                ],
+            },
+        };
+    }
+    async _ls(meta, parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const { params } = parsed;
+        const format = params.format ?? "full";
+        const { protocol, hostname, docId } = uriParts(parsed.uri);
+        const index = this._dataIndex(meta, protocol, hostname);
+        // Cursor URI uses the same protocol+hostname as the prefix (it's
+        // from a previous page of the same query), so just strip those
+        // off to get the path-keyword cursor value.
+        const cursorPath = params.cursor !== undefined
+            ? uriParts(params.cursor).docId
+            : undefined;
+        const body = {
+            query: this._leafQuery(docId, params.pattern, cursorPath, params.sortOrder),
+        };
+        // sortBy: "uri" sorts on `path.keyword` (uri is encoded as
+        // protocol+hostname+path; path.keyword is the comparable suffix
+        // we already index on). Any other value must be a declared field;
+        // dispatch only routes non-uri sortBy through here when
+        // pushDownSortBy is true, which it is for this backend.
+        //
+        // ES needs the right field name for sort: text fields are
+        // unsortable directly (fielddata is off by default in ES 8+) and
+        // must target the `.keyword` subfield instead. Numeric / date /
+        // boolean fields sort on the field itself. `json` fields aren't
+        // sortable, so we omit the sort clause and let dispatch's
+        // post-sort fallback handle them.
+        const dir = params.sortOrder === "desc" ? "desc" : "asc";
+        if (params.sortBy === "uri") {
+            body.sort = [{ "path.keyword": dir }];
+        }
+        else if (params.sortBy !== undefined && meta.declared.has(params.sortBy)) {
+            const esField = esSortField(meta, params.sortBy);
+            if (esField !== null)
+                body.sort = [{ [esField]: dir }];
+        }
+        if (params.limit !== undefined) {
+            const page = params.page ?? 1;
+            body.size = params.limit;
+            body.from = (page - 1) * params.limit;
+        }
+        else {
+            body.size = 10_000;
+        }
+        if (format === "uris")
+            body._source = false;
+        let result;
+        try {
+            result = await this.executor.search(index, body);
+        }
+        catch {
+            return format === "uris" ? [] : [];
+        }
+        if (format === "uris") {
+            return result.hits.map((hit) => `${protocol}://${hostname}/${hit._id}`);
+        }
+        return result.hits.map((hit) => {
+            const uri = `${protocol}://${hostname}/${hit._id}`;
+            if (!hit._source)
+                return [uri, undefined];
+            if (meta.isBytes) {
+                return [uri, { payload: decodeBase64(hit._source.payload) }];
+            }
+            return [uri, decodeRecord(meta.fields, hit._source)];
+        });
+    }
+    /**
+     * 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.
+     */
+    _subtreeQuery(docPrefix, pattern, cursorPath, sortOrder) {
+        if (pattern === undefined) {
+            throw new Error(`${STORE_NAME}: fn=find handler reached without params.pattern set ` +
+                `(parser invariant violated)`);
+        }
+        const body = saveGlobToRegexBody(pattern);
+        const regex = {
             regexp: {
-                "path.keyword": `${escapeLuceneRegex(docPrefix)}[^/]+`,
+                "path.keyword": `${escapeLuceneRegex(docPrefix)}${body}`,
+            },
+        };
+        if (cursorPath === undefined)
+            return regex;
+        const rangeKey = sortOrder === "desc" ? "lt" : "gt";
+        return {
+            bool: {
+                must: [
+                    regex,
+                    { range: { "path.keyword": { [rangeKey]: cursorPath } } },
+                ],
             },
         };
     }
-    async _ls(parsed) {
+    async _find(meta, parsed) {
         validateReadParams(parsed.params, STORE_NAME);
         const { params } = parsed;
         const format = params.format ?? "full";
-        const { index, docId } = uriToIndexAndDocId(parsed.uri, this.indexPrefix);
+        const { protocol, hostname, docId } = uriParts(parsed.uri);
+        const index = this._dataIndex(meta, protocol, hostname);
+        const cursorPath = params.cursor !== undefined
+            ? uriParts(params.cursor).docId
+            : undefined;
         const body = {
-            query: this._leafQuery(docId),
+            query: this._subtreeQuery(docId, params.pattern, cursorPath, params.sortOrder),
         };
+        const dir = params.sortOrder === "desc" ? "desc" : "asc";
         if (params.sortBy === "uri") {
-            // Sort on the keyword subfield, same reason as the query above.
-            body.sort = [{
-                    "path.keyword": params.sortOrder === "desc" ? "desc" : "asc",
-                }];
+            body.sort = [{ "path.keyword": dir }];
+        }
+        else if (params.sortBy !== undefined && meta.declared.has(params.sortBy)) {
+            const esField = esSortField(meta, params.sortBy);
+            if (esField !== null)
+                body.sort = [{ [esField]: dir }];
         }
         if (params.limit !== undefined) {
             const page = params.page ?? 1;
@@ -148,27 +416,56 @@ export class ElasticsearchStore {
         }
         if (format === "uris")
             body._source = false;
-        const result = await this.executor.search(index, body);
+        let result;
+        try {
+            result = await this.executor.search(index, body);
+        }
+        catch {
+            return format === "uris" ? [] : [];
+        }
         if (format === "uris") {
-            return result.hits.map((hit) => indexAndDocIdToUri(index, this.indexPrefix, hit._id));
+            return result.hits.map((hit) => `${protocol}://${hostname}/${hit._id}`);
         }
-        return result.hits.map((hit) => [
-            indexAndDocIdToUri(index, this.indexPrefix, hit._id),
-            hit._source ? decodeBase64(hit._source.payload) : undefined,
-        ]);
+        return result.hits.map((hit) => {
+            const uri = `${protocol}://${hostname}/${hit._id}`;
+            if (!hit._source)
+                return [uri, undefined];
+            if (meta.isBytes) {
+                return [uri, { payload: decodeBase64(hit._source.payload) }];
+            }
+            return [uri, decodeRecord(meta.fields, hit._source)];
+        });
     }
-    async _count(parsed) {
-        if (parsed.params.pattern !== undefined) {
-            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+    async _count(meta, parsed) {
+        const { protocol, hostname, docId } = uriParts(parsed.uri);
+        const index = this._dataIndex(meta, protocol, hostname);
+        const cursorPath = parsed.params.cursor !== undefined
+            ? uriParts(parsed.params.cursor).docId
+            : undefined;
+        try {
+            return await this.executor.count(index, {
+                query: this._leafQuery(docId, parsed.params.pattern, cursorPath, parsed.params.sortOrder),
+            });
+        }
+        catch {
+            return 0;
         }
-        const { index, docId } = uriToIndexAndDocId(parsed.uri, this.indexPrefix);
-        return await this.executor.count(index, { query: this._leafQuery(docId) });
     }
-    async _deleteBytes(uris) {
+    // ── Delete ───────────────────────────────────────────────────────
+    async delete(meta, uris) {
+        if (uris.length === 0)
+            return [];
+        if ((await this._readMetaSignature(meta.support.entity)) !== meta.signature) {
+            return uris.map((uri) => ({
+                success: false,
+                ...storageFailure(new Error(`${STORE_NAME}: entity '${meta.support.entity}' is not provisioned`), "Entity not provisioned", uri),
+            }));
+        }
         const results = [];
         for (const uri of uris) {
             try {
-                const { index, docId } = uriToIndexAndDocId(uri, this.indexPrefix);
+                const { protocol, hostname, docId } = uriParts(uri);
+                const index = this._dataIndex(meta, protocol, hostname);
                 await this.executor.delete(index, docId);
                 results.push({ success: true });
             }
@@ -181,7 +478,7 @@ export class ElasticsearchStore {
         }
         return results;
     }
-    // ── Status ───────────────────────────────────────────────────────
+    // ── Status / capabilities ────────────────────────────────────────
     async status() {
         try {
             const ok = await this.executor.ping();
@@ -189,13 +486,15 @@ export class ElasticsearchStore {
                 return {
                     status: "unhealthy",
                     message: "Elasticsearch cluster is not reachable",
-                    fns: ["read", "ls", "count"],
+                    fns: ["read", "ls", "count", "find"],
                 };
             }
+            const schema = await this._listProvisionedEntities();
             return {
                 status: "healthy",
                 message: "Elasticsearch store is operational",
-                fns: ["read", "ls", "count"],
+                schema: schema.map((s) => `entity:${s}`),
+                fns: ["read", "ls", "count", "find"],
                 details: { indexPrefix: this.indexPrefix },
             };
         }
@@ -203,11 +502,71 @@ export class ElasticsearchStore {
             return {
                 status: "unhealthy",
                 message: error instanceof Error ? error.message : String(error),
-                fns: ["read", "ls", "count"],
+                fns: ["read", "ls", "count", "find"],
             };
         }
     }
     capabilities() {
         return { atomicBatch: false };
     }
+    // ── Internals ────────────────────────────────────────────────────
+    /** Per-entity, per-`protocol_hostname` data index. */
+    _dataIndex(meta, protocol, hostname) {
+        return `${this.indexPrefix}_${meta.indexInfix}${protocol}_${hostname}`;
+    }
+    /** Single meta index holding `{name → signature}` provisioning records. */
+    _metaIndex() {
+        return `${this.indexPrefix}_${META_INDEX_SUFFIX}`;
+    }
+    /**
+     * Read the persisted signature for an entity, or `null` if no
+     * provisioning record exists.
+     */
+    async _readMetaSignature(entityName) {
+        try {
+            const doc = await this.executor.get(this._metaIndex(), entityName);
+            if (!doc)
+                return null;
+            return doc.signature ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Scan the meta index for every provisioned entity name. Used by
+     * `status()` to advertise the entities a peer can talk to.
+     */
+    async _listProvisionedEntities() {
+        try {
+            const result = await this.executor.search(this._metaIndex(), {
+                query: { match_all: {} },
+                size: 10_000,
+            });
+            return result.hits.map((h) => h._id);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Collect any `ReadableStream` values on `bytes`-tagged fields into
+     * `Uint8Array` and return a shallow-copied record.
+     */
+    async _normaliseBytesFields(record, bytesFields) {
+        const out = { ...record };
+        for (const name of bytesFields) {
+            const v = out[name];
+            if (v === undefined || v === null)
+                continue;
+            if (v instanceof Uint8Array)
+                continue;
+            if (v instanceof ReadableStream) {
+                out[name] = await toBytes(v);
+                continue;
+            }
+            throw new Error(`field '${name}' must be Uint8Array or ReadableStream, got ${typeof v}`);
+        }
+        return out;
+    }
 }

package/esm/entity-store.d.ts

@@ -43,7 +43,7 @@
  * `fn=ls` and `fn=count` follow the same conventions as `Store`
  * (URI lists and numbers — see `./read.ts`).
  */
-import type { DeleteResult, Output, StatusResult } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import type { DeleteResult, Output, StatusResult } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/src/types/types.js";
 import type { EntityMeta, EntityRecord, EntitySchema } from "./entity.js";
 import type { StoreCapabilities, StoreWriteResult } from "./types.js";
 export interface EntityStore<TMeta extends EntityMeta = EntityMeta> {

package/esm/errors.d.ts

@@ -8,7 +8,7 @@
  * one line and the error code consistent (`STORAGE_ERROR` for
  * anything that came from the underlying driver).
  */
-import type { B3ndError } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import type { B3ndError } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/src/types/types.js";
 /**
  * Build the structured-failure half of a Store result from a thrown
  * value. `fallback` is used when `err` isn't an `Error` (rare). `uri`