@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/localstorage/store.js

@@ -1,17 +1,62 @@
 /**
- * LocalStorageStore — browser localStorage implementation of Store.
+ * LocalStorageStore — browser localStorage implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. Uses
- * `localStorage` as a flat key→string KV. Payload bytes are
- * base64-encoded since `localStorage` values are strings.
+ * One backend, many entities. Layouts:
+ *
+ * - `BYTES_ENTITY` → key `{keyPrefix}{uri}` with a base64-encoded
+ *   payload string. Matches the original bytes-only layout, so
+ *   existing deployments keep working without migration.
+ * - any other schema → key `{keyPrefix}entities/{entityName}/{uri}`
+ *   with a JSON-encoded record string. Per-field canonical tags
+ *   round-trip the JSON boundary (bytes → base64, bigint → string,
+ *   timestamp → ISO-8601 — see `./fields.ts`).
+ *
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it plans the field set and computes
+ * a signature for collision detection. `provisionEntity(meta)` writes a
+ * tiny bookkeeping key (`{keyPrefix}__meta__/entities/{name}`) holding
+ * the signature; subsequent `entityStatus(meta)` reads it back and
+ * compares. Same-name different-shape provisioning throws.
+ *
+ * Writes/reads/deletes consume the meta directly: there is no per-call
+ * cache lookup gate. If `meta`'s bookkeeping is missing on the medium,
+ * `write` and `delete` surface a `"not provisioned"` storage failure
+ * per entry; `read` returns misses.
+ *
+ * ## Read params
+ *
+ * `fn=ls` / `fn=count` are shallow direct-leaves only. localStorage has
+ * no indexable cursor, so `_directLeaves` walks all keys once under the
+ * entity's `keyRoot` and standard params (`limit`/`page`/`sortBy`
+ * `=uri`/`sortOrder`/`format`) are applied in memory via
+ * `applyReadParams` from `../read.ts`.
+ *
+ * `fn=find` (v2 §3.5) walks every key under the entity's `keyRoot`
+ * matching the URI prefix at any depth — `_walkDeep` mirrors
+ * `_directLeaves` minus the `rest.includes("/")` cutoff. With
+ * `pushDownFind: false`, dispatch applies the embedded glob, sort,
+ * cursor, limit, format, and appends the cursor-as-trailing-slot.
+ * localStorage has no engine to leverage for push-down — iteration IS
+ * the work — so the symmetric shape (ls = shallow walk, find = deep
+ * walk; dispatch post-processes both) keeps the code minimal.
+ *
+ * `status().fns` advertises `["read", "ls", "count", "find"]`.
  */
-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 { applyReadParams } from "../read.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 = "LocalStorageStore";
+const ENTITY_PREFIX = "entities/";
+const META_PREFIX = "__meta__/entities/";
+function isBytesSchema(schema) {
+    return schema.name === BYTES_ENTITY.name;
+}
 export class LocalStorageStore {
     keyPrefix;
     storage;
@@ -23,66 +68,145 @@ export class LocalStorageStore {
             throw new Error("localStorage is not available in this environment");
         }
     }
-    getKey(uri) {
-        return `${this.keyPrefix}${uri}`;
-    }
-    // ── EntityStore surface ──────────────────────────────────────────
+    // ── Lifecycle ────────────────────────────────────────────────────
     entitySupport(schema) {
-        return bytesOnlyEntitySupport(schema);
+        if (isBytesSchema(schema)) {
+            const fields = [{ name: "payload", tag: "bytes" }];
+            return {
+                support: {
+                    entity: schema.name,
+                    supported: ["payload"],
+                    unsupported: [],
+                },
+                keyRoot: this.keyPrefix,
+                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,
+            },
+            keyRoot: `${this.keyPrefix}${ENTITY_PREFIX}${schema.name}/`,
+            isBytes: false,
+            fields,
+            declared,
+            bytesFields,
+            signature: computeSignature(schema.name, fields),
+        };
     }
     entityStatus(meta) {
-        return Promise.resolve(meta.isBytes ? "live" : "unprovisioned");
-    }
-    provisionEntity(_meta) {
-        return Promise.resolve();
+        const recorded = this._readMetaSignature(meta.support.entity);
+        if (recorded === null)
+            return Promise.resolve("unprovisioned");
+        return Promise.resolve(recorded === meta.signature ? "live" : "unprovisioned");
     }
-    write(meta, entries) {
-        return bytesOnlyWrite(meta, STORE_NAME, entries, (e) => this._writeBytes(e));
-    }
-    read(meta, urls) {
-        return bytesOnlyRead(meta, STORE_NAME, urls, (u) => this._readBytes(u));
-    }
-    delete(meta, uris) {
-        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    // deno-lint-ignore require-await
+    async provisionEntity(meta) {
+        const recorded = 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;
+        }
+        this.storage.setItem(`${this.keyPrefix}${META_PREFIX}${meta.support.entity}`, meta.signature);
     }
-    // ── Byte ops (BYTES_ENTITY routing) ──────────────────────────────
-    async _writeBytes(entries) {
+    // ── Write ────────────────────────────────────────────────────────
+    async write(meta, entries) {
+        if (entries.length === 0)
+            return [];
+        if (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) {
+        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 bytes = await toBytes(entry.payload);
-                this.storage.setItem(this.getKey(entry.uri), encodeBase64(bytes));
+                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);
+                    this.storage.setItem(`${meta.keyRoot}${uri}`, encodeBase64(bytes));
+                }
+                else {
+                    const normalised = await this._normaliseBytesFields(record, meta.bytesFields);
+                    const encoded = encodeRecord(meta.fields, normalised);
+                    this.storage.setItem(`${meta.keyRoot}${uri}`, JSON.stringify(encoded));
+                }
                 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) => Promise.resolve(this._readOne(meta, p.uri)),
+            ls: (p) => Promise.resolve(this._ls(meta, p)),
+            count: (p) => Promise.resolve(this._count(meta, p)),
+            // v2 §3.5: find walks every key under the URI prefix (no shallow
+            // `/` cutoff). With `pushDownFind: false`, dispatch applies the
+            // glob, sort, cursor, limit, format, and appends the cursor-as-
+            // trailing-slot. The handler's only job is to return every
+            // Output under the prefix — routed through `applyReadParams` so
+            // `format=uris` returns `string[]` (dispatch's post-filter path
+            // inspects rows differently depending on format). By the time
+            // the handler runs, dispatch has stripped pattern, cursor,
+            // limit, page, and fields; `applyReadParams` ends up as a thin
+            // format + uri-sort pass. localStorage has no engine to leverage
+            // for push-down — iteration IS the work — so the symmetric shape
+            // (ls = shallow walk, find = deep walk; dispatch post-processes
+            // both) keeps the code minimal.
+            find: (p) => Promise.resolve(applyReadParams(this._walkDeep(meta, p.uri), p.params, STORE_NAME)),
         });
     }
-    _readOne(uri) {
-        const serialized = this.storage.getItem(this.getKey(uri));
-        if (serialized === null)
+    _readOne(meta, uri) {
+        const stored = this.storage.getItem(`${meta.keyRoot}${uri}`);
+        if (stored === null)
             return undefined;
-        return decodeBase64(serialized);
+        if (meta.isBytes)
+            return { payload: decodeBase64(stored) };
+        return decodeRecord(meta.fields, JSON.parse(stored));
     }
     /**
-     * Walk localStorage once, returning `[uri, bytes]` for every entry
-     * whose URI is `prefix + <segment>` with no further `/`. Subtree-only
-     * paths are excluded by the slash check.
+     * Walk localStorage once, returning `Output<EntityRecord>` for every
+     * key under `meta.keyRoot` whose remainder is `uri + <segment>` with
+     * no further `/`. Subtree-only paths are excluded by the slash check.
      */
-    _directLeaves(prefixUri) {
-        const prefixKey = this.getKey(prefixUri);
+    _directLeaves(meta, uri) {
+        const prefixKey = `${meta.keyRoot}${uri}`;
         const out = [];
         for (let i = 0; i < this.storage.length; i++) {
             const key = this.storage.key(i);
@@ -91,25 +215,60 @@ export class LocalStorageStore {
             const rest = key.substring(prefixKey.length);
             if (rest === "" || rest.includes("/"))
                 continue;
-            const childUri = `${prefixUri}${rest}`;
-            out.push([childUri, this._readOne(childUri)]);
+            const childUri = `${uri}${rest}`;
+            const record = this._readOne(meta, childUri);
+            if (record !== undefined)
+                out.push([childUri, record]);
         }
         return out;
     }
-    _ls(parsed) {
-        return applyReadParams(this._directLeaves(parsed.uri), parsed.params, STORE_NAME);
+    /**
+     * Walk localStorage once, returning `Output<EntityRecord>` for every
+     * key under `meta.keyRoot` whose remainder starts with `uri` — at
+     * any depth. Powers `fn=find`. Unlike `_directLeaves`, there is no
+     * `/` cutoff: keys with further slashes past the prefix are kept.
+     * Dispatch applies the glob (and sort/cursor/limit/format) on top.
+     */
+    _walkDeep(meta, uri) {
+        const prefixKey = `${meta.keyRoot}${uri}`;
+        const out = [];
+        for (let i = 0; i < this.storage.length; i++) {
+            const key = this.storage.key(i);
+            if (!key || !key.startsWith(prefixKey))
+                continue;
+            const rest = key.substring(prefixKey.length);
+            if (rest === "")
+                continue;
+            const childUri = `${uri}${rest}`;
+            const record = this._readOne(meta, childUri);
+            if (record !== undefined)
+                out.push([childUri, record]);
+        }
+        return out;
+    }
+    _ls(meta, parsed) {
+        return applyReadParams(this._directLeaves(meta, parsed.uri), parsed.params, STORE_NAME);
     }
-    _count(parsed) {
+    _count(meta, parsed) {
         if (parsed.params.pattern !== undefined) {
             throw new Error(`${STORE_NAME}: pattern filter not supported`);
         }
-        return this._directLeaves(parsed.uri).length;
+        return this._directLeaves(meta, parsed.uri).length;
     }
-    _deleteBytes(uris) {
+    // ── Delete ───────────────────────────────────────────────────────
+    delete(meta, uris) {
+        if (uris.length === 0)
+            return Promise.resolve([]);
+        if (this._readMetaSignature(meta.support.entity) !== meta.signature) {
+            return Promise.resolve(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 {
-                this.storage.removeItem(this.getKey(uri));
+                this.storage.removeItem(`${meta.keyRoot}${uri}`);
                 results.push({ success: true });
             }
             catch (err) {
@@ -121,27 +280,61 @@ export class LocalStorageStore {
         }
         return Promise.resolve(results);
     }
-    // ── Status ───────────────────────────────────────────────────────
+    // ── Status / capabilities ────────────────────────────────────────
     status() {
         try {
             const testKey = `${this.keyPrefix}__health_check__`;
             this.storage.setItem(testKey, "ok");
             this.storage.removeItem(testKey);
+            const schema = [];
+            const metaPrefix = `${this.keyPrefix}${META_PREFIX}`;
+            for (let i = 0; i < this.storage.length; i++) {
+                const k = this.storage.key(i);
+                if (!k || !k.startsWith(metaPrefix))
+                    continue;
+                schema.push(`entity:${k.slice(metaPrefix.length)}`);
+            }
             return Promise.resolve({
                 status: "healthy",
-                schema: [],
-                fns: ["read", "ls", "count"],
+                schema,
+                fns: ["read", "ls", "count", "find"],
             });
         }
         catch {
             return Promise.resolve({
                 status: "unhealthy",
                 schema: [],
-                fns: ["read", "ls", "count"],
+                fns: ["read", "ls", "count", "find"],
             });
         }
     }
     capabilities() {
         return { atomicBatch: false };
     }
+    // ── Internals ────────────────────────────────────────────────────
+    _readMetaSignature(entityName) {
+        return this.storage.getItem(`${this.keyPrefix}${META_PREFIX}${entityName}`);
+    }
+    /**
+     * Collect any `ReadableStream` values on `bytes`-tagged fields into
+     * `Uint8Array` and return a shallow-copied record. Non-stream values
+     * pass through; matches the normalisation pattern used by Memory and
+     * Postgres.
+     */
+    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/memory/store.d.ts

@@ -36,8 +36,27 @@
  * record lands in the bucket. That coercion runs for every entity
  * that declares a bytes field; nothing about it is bytes-entity-
  * specific.
+ *
+ * ## Read pipeline
+ *
+ * `read()` routes through `dispatchRead` (same shell every other store
+ * uses) with four handlers — `read`, `ls`, `count`, `find`. The
+ * handlers are simple iterators over the bucket:
+ * - `ls` / `count`: shallow walk (direct leaves only — the
+ *   `rest.includes("/")` cutoff in `_walkShallow`).
+ * - `find` (v2 §3.5): deep walk (every key under the prefix, any
+ *   depth — `_walkRecursive`).
+ *
+ * `pushDownFind` is left **false**: memory has no engine to leverage
+ * for push-down, so the handler returns the raw deep walk and dispatch
+ * applies the glob, sort, cursor, limit, format, and appends the
+ * cursor-as-trailing-slot. This keeps the ls/find shape symmetric
+ * (shallow walk vs deep walk; dispatch post-processes both) and avoids
+ * duplicating `applyReadParams` plumbing inside the find handler.
+ *
+ * `status().fns` advertises `["read", "ls", "count", "find"]`.
  */
-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 { StoreCapabilities, StoreWriteResult } from "../types.js";
 import type { EntityStore } from "../entity-store.js";
 import { type EntityMeta, type EntityRecord, type EntitySchema } from "../entity.js";
@@ -63,9 +82,21 @@ export declare class MemoryStore implements EntityStore<MemoryEntityMeta> {
         record: EntityRecord;
     }[]): Promise<StoreWriteResult[]>;
     read<T = EntityRecord | undefined>(meta: MemoryEntityMeta, urls: string[]): Promise<Output<T>[]>;
-    private _walk;
-    private _list;
-    private _count;
+    /**
+     * Walk the bucket once and return every direct leaf under `uri` (the
+     * key has no further `/` past the prefix). Powers `ls` and `count`.
+     * The shallow `rest.includes("/")` cutoff is what makes this an `ls`
+     * walk; `_walkRecursive` is the matching deep walk for `find`.
+     */
+    private _walkShallow;
+    /**
+     * Walk the bucket once and return every record whose URI starts with
+     * the prefix — at any depth. Powers `fn=find`. Unlike `_walkShallow`,
+     * there is no `/` cutoff: keys with further slashes past the prefix
+     * are kept. Dispatch applies the glob (and sort/cursor/limit/format)
+     * on top.
+     */
+    private _walkRecursive;
     delete(meta: MemoryEntityMeta, uris: string[]): Promise<DeleteResult[]>;
     status(): Promise<StatusResult>;
     capabilities(): StoreCapabilities;

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAK3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAGlB,MAAM,cAAc,CAAC;AAKtB;;;;;;GAMG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,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;AAOD,qBAAa,WAAY,YAAW,WAAW,CAAC,gBAAgB,CAAC;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAIrD,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB;IAwC/C,YAAY,CAChB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAO9B,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBtD,KAAK,CACT,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAsDxB,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EACrC,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAiBvB,OAAO,CAAC,KAAK;IAgBb,OAAO,CAAC,KAAK;IA8Bb,OAAO,CAAC,MAAM;IAYd,MAAM,CACJ,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,YAAY,EAAE,CAAC;IAgC1B,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAQ/B,YAAY,IAAI,iBAAiB;CAGlC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAK3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAGlB,MAAM,cAAc,CAAC;AAKtB;;;;;;GAMG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,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;AAOD,qBAAa,WAAY,YAAW,WAAW,CAAC,gBAAgB,CAAC;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAIrD,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB;IAwC/C,YAAY,CAChB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAO9B,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBtD,KAAK,CACT,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAqD9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAiCvB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAgBpB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAoBtB,MAAM,CACJ,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,YAAY,EAAE,CAAC;IAgC1B,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAQ/B,YAAY,IAAI,iBAAiB;CAGlC"}

package/esm/memory/store.js

@@ -36,8 +36,28 @@
  * record lands in the bucket. That coercion runs for every entity
  * that declares a bytes field; nothing about it is bytes-entity-
  * specific.
+ *
+ * ## Read pipeline
+ *
+ * `read()` routes through `dispatchRead` (same shell every other store
+ * uses) with four handlers — `read`, `ls`, `count`, `find`. The
+ * handlers are simple iterators over the bucket:
+ * - `ls` / `count`: shallow walk (direct leaves only — the
+ *   `rest.includes("/")` cutoff in `_walkShallow`).
+ * - `find` (v2 §3.5): deep walk (every key under the prefix, any
+ *   depth — `_walkRecursive`).
+ *
+ * `pushDownFind` is left **false**: memory has no engine to leverage
+ * for push-down, so the handler returns the raw deep walk and dispatch
+ * applies the glob, sort, cursor, limit, format, and appends the
+ * cursor-as-trailing-slot. This keeps the ls/find shape symmetric
+ * (shallow walk vs deep walk; dispatch post-processes both) and avoids
+ * duplicating `applyReadParams` plumbing inside the find handler.
+ *
+ * `status().fns` advertises `["read", "ls", "count", "find"]`.
  */
-import { parseUrl } from "../url.js";
+import { dispatchRead } from "../dispatch.js";
+import { applyReadParams } from "../read.js";
 import { storageFailure } from "../errors.js";
 import { toBytes } from "../payload.js";
 import { TYPE_TAGS, } from "../entity.js";
@@ -142,24 +162,35 @@ export class MemoryStore {
         return results;
     }
     // ── Read ─────────────────────────────────────────────────────────
-    // deno-lint-ignore require-await
-    async read(meta, urls) {
+    read(meta, urls) {
         const bucket = this.buckets.get(meta.support.entity);
-        return urls.map((url) => {
-            const parsed = parseUrl(url);
-            switch (parsed.fn) {
-                case "read":
-                    return [url, bucket?.records.get(parsed.uri)];
-                case "ls":
-                    return [url, this._list(bucket?.records, parsed)];
-                case "count":
-                    return [url, this._count(bucket?.records, parsed)];
-                default:
-                    throw new Error(`${STORE_NAME}: unsupported fn '${parsed.fn}'`);
-            }
+        return dispatchRead(urls, STORE_NAME, {
+            read: (p) => bucket?.records.get(p.uri),
+            ls: (p) => applyReadParams(this._walkShallow(bucket?.records, p.uri), p.params, STORE_NAME),
+            count: (p) => this._walkShallow(bucket?.records, p.uri).length,
+            // v2 §3.5: find walks the entire bucket under the URI prefix
+            // (no shallow `/` cutoff). With `pushDownFind: false`, dispatch
+            // applies the glob, sort, cursor, limit, format, and appends the
+            // cursor-as-trailing-slot. The handler's only job is to return
+            // every Output under the prefix — routed through `applyReadParams`
+            // so `format=uris` returns `string[]` (dispatch's post-filter
+            // path inspects rows differently depending on format). By the
+            // time the handler runs, dispatch has stripped pattern, cursor,
+            // limit, page, and fields; `applyReadParams` ends up as a thin
+            // format + uri-sort pass. Memory has no engine to leverage for
+            // push-down — iteration IS the work — so the symmetric shape
+            // (ls = shallow walk, find = deep walk; dispatch post-processes
+            // both) keeps the code minimal.
+            find: (p) => applyReadParams(this._walkRecursive(bucket?.records, p.uri), p.params, STORE_NAME),
         });
     }
-    _walk(bucket, uri) {
+    /**
+     * Walk the bucket once and return every direct leaf under `uri` (the
+     * key has no further `/` past the prefix). Powers `ls` and `count`.
+     * The shallow `rest.includes("/")` cutoff is what makes this an `ls`
+     * walk; `_walkRecursive` is the matching deep walk for `find`.
+     */
+    _walkShallow(bucket, uri) {
         if (!bucket)
             return [];
         const prefix = uri.endsWith("/") ? uri : `${uri}/`;
@@ -174,37 +205,28 @@ export class MemoryStore {
         }
         return out;
     }
-    _list(bucket, parsed) {
-        const { params } = parsed;
-        if (params.pattern !== undefined) {
-            throw new Error(`${STORE_NAME}: pattern filter not supported`);
-        }
-        if (params.sortBy !== undefined && params.sortBy !== "uri") {
-            throw new Error(`${STORE_NAME}: unsupported sortBy: ${params.sortBy}`);
-        }
-        const format = params.format ?? "full";
-        if (format !== "full" && format !== "uris") {
-            throw new Error(`${STORE_NAME}: unsupported format: ${format}`);
-        }
-        let entries = this._walk(bucket, parsed.uri);
-        if (params.sortBy === "uri") {
-            const dir = params.sortOrder === "desc" ? -1 : 1;
-            entries = [...entries].sort(([a], [b]) => a.localeCompare(b) * dir);
-        }
-        if (params.limit !== undefined) {
-            const page = params.page ?? 1;
-            const start = (page - 1) * params.limit;
-            entries = entries.slice(start, start + params.limit);
-        }
-        if (format === "uris")
-            return entries.map(([uri]) => uri);
-        return entries;
-    }
-    _count(bucket, parsed) {
-        if (parsed.params.pattern !== undefined) {
-            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+    /**
+     * Walk the bucket once and return every record whose URI starts with
+     * the prefix — at any depth. Powers `fn=find`. Unlike `_walkShallow`,
+     * there is no `/` cutoff: keys with further slashes past the prefix
+     * are kept. Dispatch applies the glob (and sort/cursor/limit/format)
+     * on top.
+     */
+    _walkRecursive(bucket, uri) {
+        if (!bucket)
+            return [];
+        // For find the prefix is whatever the parser produced. When the
+        // caller wrote `mutable://room/**` the parser gives us
+        // `mutable://room/` (trailing `/` from `splitLocatorGlob`); when
+        // they wrote `mutable://room/alice/**` we get `mutable://room/alice/`.
+        // Either way we include every key whose prefix matches, no further
+        // truncation — that's what makes this the "deep" walk.
+        const out = [];
+        for (const [k, rec] of bucket) {
+            if (k.startsWith(uri) && k !== uri)
+                out.push([k, rec]);
         }
-        return this._walk(bucket, parsed.uri).length;
+        return out;
     }
     // ── Delete ───────────────────────────────────────────────────────
     delete(meta, uris) {
@@ -236,7 +258,7 @@ export class MemoryStore {
         return Promise.resolve({
             status: "healthy",
             schema: [...this.buckets.keys()].map((n) => `entity:${n}`),
-            fns: ["read", "ls", "count"],
+            fns: ["read", "ls", "count", "find"],
         });
     }
     capabilities() {

package/esm/mod.d.ts

@@ -19,6 +19,8 @@
 export type { StoreCapabilities, StoreWriteResult } from "./types.js";
 export type { ParsedUrl, ReadParams } from "./url.js";
 export { buildUrl, parseUrl, uriOf } from "./url.js";
+export type { WalkViaLsOptions } from "./walk-via-ls.js";
+export { walkViaLs } from "./walk-via-ls.js";
 export type { EntityField, EntityMeta, EntityRecord, EntitySchema, EntitySupport, } from "./entity.js";
 export { BYTES_ENTITY, TYPE_TAGS } from "./entity.js";
 export type { EntityStore } from "./entity-store.js";

package/esm/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEtE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAErD,YAAY,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,aAAa,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,YAAY,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEtE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAErD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,YAAY,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,aAAa,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,YAAY,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC"}

package/esm/mod.js

@@ -17,6 +17,7 @@
  * `TYPE_TAGS`, …) is re-exported from the root for convenience.
  */
 export { buildUrl, parseUrl, uriOf } from "./url.js";
+export { walkViaLs } from "./walk-via-ls.js";
 export { BYTES_ENTITY, TYPE_TAGS } from "./entity.js";
 export * as clients from "./clients/mod.js";
 export * as memory from "./memory/mod.js";