@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/ipfs/mod.js

@@ -9,5 +9,24 @@
  * and streaming callers; `cat` returns a `ReadableStream<Uint8Array>`
  * to avoid materializing the block in memory unless the caller wants
  * it.
+ *
+ * ## Durability warning — session-scoped index
+ *
+ * IPFS blocks are pinned and durable, but the URI → CID index and
+ * provisioning bookkeeping live only in process memory (a `Map`
+ * inside the `IpfsStore` instance). After a process restart:
+ *
+ * - Previously-written blocks are unreachable: the store cannot map
+ *   any URI back to its CID.
+ * - `entityStatus(meta)` returns `"unprovisioned"` for every entity
+ *   until `provisionEntity` is called again.
+ * - `read` returns misses for all URIs that were valid before the
+ *   restart.
+ *
+ * `IpfsStore` is effectively session-scoped as an `EntityStore`.
+ * Persisting the index (e.g. writing a bucket-root IPFS block on
+ * each write and handing the root CID to the caller for rehydration)
+ * is deferred — callers that need durable addressing across restarts
+ * should track CIDs externally or use a different backend.
  */
 export { IpfsStore } from "./store.js";

package/esm/ipfs/store.d.ts

@@ -1,42 +1,103 @@
 /**
- * IpfsStore — IPFS implementation of Store.
+ * IpfsStore — IPFS implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. Writes
- * pinned IPFS objects and maintains an in-memory `uri → CID` index
- * for lookups. The block body is the payload bytes verbatim.
+ * One backend, many entities. Layouts:
+ *
+ * - `BYTES_ENTITY` → block holding the payload bytes verbatim. URI →
+ *   CID is tracked in an in-memory index under the entity bucket
+ *   `"bytes"`.
+ * - any other schema → block holding a JSON-encoded record. URI → CID
+ *   is tracked in a separate in-memory index under the entity name.
+ *   Per-field canonical `TYPE_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 collision signature. `provisionEntity(meta)` allocates the
+ * in-memory bucket and records the signature; subsequent
+ * `entityStatus(meta)` returns `"live"` only when the bucket's
+ * signature matches the meta exactly. Same-name different-shape
+ * provisioning throws.
+ *
+ * Note: IPFS itself has no concept of provisioning — the bucket lives
+ * only in memory inside this store instance. A fresh process must
+ * re-call `provisionEntity` before write/delete (read returns misses
+ * naturally), mirroring how Memory works for an in-process store.
+ *
+ * ## Read params
  *
  * `fn=ls` / `fn=count` are shallow direct-leaves only: scan the
- * in-memory index, keep URIs whose remainder under the prefix has no
- * further `/`.
+ * entity's in-memory URI → CID index, keep URIs whose remainder under
+ * the prefix has no further `/`. Standard params (`limit`/`page`/
+ * `sortBy=uri`/`sortOrder`/`format`) are applied in memory;
+ * `format=uris` and `count` skip per-leaf `cat`.
+ *
+ * `fn=find` (v2 §3.5): deep walk over the entity's in-memory URI →
+ * CID index (no shallow `/` cutoff). `pushDownFind` is left **false**
+ * — the index is just a `Map<uri, cid>`, structurally identical to
+ * memory's bucket; there is no IPFS-side query engine to leverage
+ * (CIDs are content-addressed blobs, not a queryable graph). Iteration
+ * IS the work, so dispatch's post-filter path (glob, sort, cursor,
+ * limit, format, cursor-as-trailing-slot) carries the load. Mirrors
+ * memory exactly (see `b3nd-save/src/memory/store.ts`).
+ *
+ * `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 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 { IpfsExecutor } from "./mod.js";
-export declare class IpfsStore implements EntityStore<BytesOnlyEntityMeta> {
+/**
+ * IpfsStore-specific entity handle.
+ *
+ * `isBytes` selects the raw-payload block layout vs the JSON-encoded
+ * record block layout. `fields`/`declared`/`bytesFields` drive
+ * write-time validation and encoding; `signature` is used for
+ * collision detection in `entityStatus` / `provisionEntity`.
+ */
+export interface IpfsEntityMeta extends EntityMeta {
+    readonly isBytes: boolean;
+    readonly fields: readonly FieldPlan[];
+    readonly declared: ReadonlySet<string>;
+    readonly bytesFields: ReadonlySet<string>;
+    readonly signature: string;
+}
+export declare class IpfsStore implements EntityStore<IpfsEntityMeta> {
     private readonly executor;
-    private readonly index;
+    private readonly buckets;
     constructor(executor: IpfsExecutor);
-    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
-    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
-    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
-    write(meta: BytesOnlyEntityMeta, entries: {
+    entitySupport(schema: EntitySchema): IpfsEntityMeta;
+    entityStatus(meta: IpfsEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(meta: IpfsEntityMeta): Promise<void>;
+    write(meta: IpfsEntityMeta, 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: IpfsEntityMeta, urls: string[]): Promise<Output<T>[]>;
     private _readOne;
-    /** Shallow direct-leaves from the in-memory URI index. */
+    /** Shallow direct-leaves from the entity's in-memory URI index. */
     private _directLeafUris;
     private _ls;
     private _count;
-    private _deleteBytes;
+    /**
+     * Deep walk: every URI under the prefix at any depth. Powers
+     * `fn=find`. Unlike `_directLeafUris`, 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 _allUris;
+    private _find;
+    delete(meta: IpfsEntityMeta, uris: string[]): Promise<DeleteResult[]>;
     status(): Promise<StatusResult>;
     capabilities(): StoreCapabilities;
+    /**
+     * 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/ipfs/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ipfs/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;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;AAM/D,OAAO,KAAK,EACV,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAQ7C,qBAAa,SAAU,YAAW,WAAW,CAAC,mBAAmB,CAAC;IAChE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;gBAE3C,QAAQ,EAAE,YAAY;IAOlC,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;IAiCzB,OAAO,CAAC,UAAU;YAQJ,QAAQ;IAYtB,0DAA0D;IAC1D,OAAO,CAAC,eAAe;YAWT,GAAG;IA0BjB,OAAO,CAAC,MAAM;YAOA,YAAY;IA4BpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAqCrC,YAAY,IAAI,iBAAiB;CAGlC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ipfs/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAM3E,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,YAAY,EAAE,MAAM,UAAU,CAAC;AAa7C;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,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;AAMD,qBAAa,SAAU,YAAW,WAAW,CAAC,cAAc,CAAC;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;gBAE/C,QAAQ,EAAE,YAAY;IAOlC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc;IAyC7C,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAOrE,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpD,KAAK,CACT,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA+E9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAmBT,QAAQ;IAmBtB,mEAAmE;IACnE,OAAO,CAAC,eAAe;YAaT,GAAG;IA4BjB,OAAO,CAAC,MAAM;IAOd;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;YAUF,KAAK;IA6Bb,MAAM,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAwCrE,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IA8BrC,YAAY,IAAI,iBAAiB;IAMjC;;;OAGG;YACW,qBAAqB;CAmBpC"}

package/esm/ipfs/store.js

@@ -1,97 +1,231 @@
 /**
- * IpfsStore — IPFS implementation of Store.
+ * IpfsStore — IPFS implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. Writes
- * pinned IPFS objects and maintains an in-memory `uri → CID` index
- * for lookups. The block body is the payload bytes verbatim.
+ * One backend, many entities. Layouts:
+ *
+ * - `BYTES_ENTITY` → block holding the payload bytes verbatim. URI →
+ *   CID is tracked in an in-memory index under the entity bucket
+ *   `"bytes"`.
+ * - any other schema → block holding a JSON-encoded record. URI → CID
+ *   is tracked in a separate in-memory index under the entity name.
+ *   Per-field canonical `TYPE_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 collision signature. `provisionEntity(meta)` allocates the
+ * in-memory bucket and records the signature; subsequent
+ * `entityStatus(meta)` returns `"live"` only when the bucket's
+ * signature matches the meta exactly. Same-name different-shape
+ * provisioning throws.
+ *
+ * Note: IPFS itself has no concept of provisioning — the bucket lives
+ * only in memory inside this store instance. A fresh process must
+ * re-call `provisionEntity` before write/delete (read returns misses
+ * naturally), mirroring how Memory works for an in-process store.
+ *
+ * ## Read params
  *
  * `fn=ls` / `fn=count` are shallow direct-leaves only: scan the
- * in-memory index, keep URIs whose remainder under the prefix has no
- * further `/`.
+ * entity's in-memory URI → CID index, keep URIs whose remainder under
+ * the prefix has no further `/`. Standard params (`limit`/`page`/
+ * `sortBy=uri`/`sortOrder`/`format`) are applied in memory;
+ * `format=uris` and `count` skip per-leaf `cat`.
+ *
+ * `fn=find` (v2 §3.5): deep walk over the entity's in-memory URI →
+ * CID index (no shallow `/` cutoff). `pushDownFind` is left **false**
+ * — the index is just a `Map<uri, cid>`, structurally identical to
+ * memory's bucket; there is no IPFS-side query engine to leverage
+ * (CIDs are content-addressed blobs, not a queryable graph). Iteration
+ * IS the work, so dispatch's post-filter path (glob, sort, cursor,
+ * limit, format, cursor-as-trailing-slot) carries the load. Mirrors
+ * memory exactly (see `b3nd-save/src/memory/store.ts`).
+ *
+ * `status().fns` advertises `["read", "ls", "count", "find"]`.
  */
-import { bytesOnlyDelete, bytesOnlyEntitySupport, bytesOnlyRead, bytesOnlyWrite, } from "../byte-entity-shim.js";
 import { dispatchRead } from "../dispatch.js";
 import { storageFailure } from "../errors.js";
-import { validateReadParams } from "../read.js";
+import { toBytes } from "../payload.js";
+import { applyReadParams, validateReadParams } 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 = "IpfsStore";
+function isBytesSchema(schema) {
+    return schema.name === BYTES_ENTITY.name;
+}
 export class IpfsStore {
     executor;
-    index = new Map();
+    buckets = new Map();
     constructor(executor) {
         if (!executor)
             throw new Error("executor is required");
         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: [],
+                },
+                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,
+            },
+            isBytes: false,
+            fields,
+            declared,
+            bytesFields,
+            signature: computeSignature(schema.name, fields),
+        };
     }
-    read(meta, urls) {
-        return bytesOnlyRead(meta, STORE_NAME, urls, (u) => this._readBytes(u));
+    // deno-lint-ignore require-await
+    async entityStatus(meta) {
+        const bucket = this.buckets.get(meta.support.entity);
+        if (!bucket)
+            return "unprovisioned";
+        return bucket.signature === meta.signature ? "live" : "unprovisioned";
     }
-    delete(meta, uris) {
-        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    // deno-lint-ignore require-await
+    async provisionEntity(meta) {
+        const existing = this.buckets.get(meta.support.entity);
+        if (existing) {
+            if (existing.signature !== meta.signature) {
+                throw new Error(`${STORE_NAME}: entity '${meta.support.entity}' is already ` +
+                    `provisioned with a different shape`);
+            }
+            return;
+        }
+        this.buckets.set(meta.support.entity, {
+            signature: meta.signature,
+            index: new Map(),
+        });
     }
-    // ── Byte ops (BYTES_ENTITY routing) ──────────────────────────────
-    async _writeBytes(entries) {
+    // ── Write ────────────────────────────────────────────────────────
+    async write(meta, entries) {
+        if (entries.length === 0)
+            return [];
+        const bucket = this.buckets.get(meta.support.entity);
+        if (!bucket || bucket.signature !== 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 cid = await this.executor.add(entry.payload);
+                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");
+                    }
+                    body = payload;
+                }
+                else {
+                    const normalised = await this._normaliseBytesFields(record, meta.bytesFields);
+                    const json = JSON.stringify(encodeRecord(meta.fields, normalised));
+                    body = new TextEncoder().encode(json);
+                }
+                const cid = await this.executor.add(body);
                 await this.executor.pin(cid);
-                // Unpin the old CID if this URI was already indexed
-                const existing = this.index.get(entry.uri);
+                const existing = bucket.index.get(uri);
                 if (existing) {
                     try {
                         await this.executor.unpin(existing.cid);
                     }
                     catch {
-                        // Old CID may already be unpinned — ignore
+                        // Old CID may already be unpinned — ignore.
                     }
                 }
-                this.index.set(entry.uri, { cid });
+                bucket.index.set(uri, { cid });
                 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) => Promise.resolve(this._count(meta, p)),
+            // v2 §3.5: find walks the entire in-memory CID index 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. 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. IPFS has no queryable engine — CIDs are content-addressed
+            // blobs — so iteration IS the work; the symmetric shape with
+            // memory (ls = shallow walk, find = deep walk; dispatch
+            // post-processes both) keeps the code minimal.
+            find: (p) => this._find(meta, p),
         });
     }
-    async _readOne(uri) {
-        const entry = this.index.get(uri);
+    async _readOne(meta, uri) {
+        const bucket = this.buckets.get(meta.support.entity);
+        if (!bucket)
+            return undefined;
+        const entry = bucket.index.get(uri);
         if (!entry)
             return undefined;
         try {
-            return await this.executor.cat(entry.cid);
+            const stream = await this.executor.cat(entry.cid);
+            if (meta.isBytes)
+                return { payload: stream };
+            const bytes = await new Response(stream).bytes();
+            const text = new TextDecoder().decode(bytes);
+            return decodeRecord(meta.fields, JSON.parse(text));
         }
         catch {
             return undefined;
         }
     }
-    /** Shallow direct-leaves from the in-memory URI index. */
-    _directLeafUris(prefixUri) {
+    /** Shallow direct-leaves from the entity's in-memory URI index. */
+    _directLeafUris(meta, prefixUri) {
+        const bucket = this.buckets.get(meta.support.entity);
+        if (!bucket)
+            return [];
         const out = [];
-        for (const uri of this.index.keys()) {
+        for (const uri of bucket.index.keys()) {
             if (!uri.startsWith(prefixUri))
                 continue;
             const tail = uri.slice(prefixUri.length);
@@ -101,11 +235,11 @@ export class IpfsStore {
         }
         return out;
     }
-    async _ls(parsed) {
+    async _ls(meta, parsed) {
         validateReadParams(parsed.params, STORE_NAME);
         const { params } = parsed;
         const format = params.format ?? "full";
-        let uris = this._directLeafUris(parsed.uri);
+        let uris = this._directLeafUris(meta, parsed.uri);
         if (params.sortBy === "uri") {
             const dir = params.sortOrder === "desc" ? -1 : 1;
             uris = [...uris].sort((a, b) => a.localeCompare(b) * dir);
@@ -119,29 +253,82 @@ export class IpfsStore {
             return uris;
         const out = [];
         for (const uri of uris) {
-            out.push([uri, await this._readOne(uri)]);
+            const rec = await this._readOne(meta, uri);
+            if (rec !== undefined)
+                out.push([uri, rec]);
         }
         return out;
     }
-    _count(parsed) {
+    _count(meta, parsed) {
         if (parsed.params.pattern !== undefined) {
             throw new Error(`${STORE_NAME}: pattern filter not supported`);
         }
-        return this._directLeafUris(parsed.uri).length;
+        return this._directLeafUris(meta, parsed.uri).length;
+    }
+    /**
+     * Deep walk: every URI under the prefix at any depth. Powers
+     * `fn=find`. Unlike `_directLeafUris`, there is no `/` cutoff — keys
+     * with further slashes past the prefix are kept. Dispatch applies the
+     * glob (and sort/cursor/limit/format) on top.
+     */
+    _allUris(meta, prefixUri) {
+        const bucket = this.buckets.get(meta.support.entity);
+        if (!bucket)
+            return [];
+        const out = [];
+        for (const uri of bucket.index.keys()) {
+            if (uri.startsWith(prefixUri) && uri !== prefixUri)
+                out.push(uri);
+        }
+        return out;
+    }
+    async _find(meta, parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const uris = this._allUris(meta, parsed.uri);
+        // Collect the rows once; let `applyReadParams` honour format /
+        // sort / cursor / limit. `format=uris` skips per-leaf `cat` since
+        // the bucket already holds the URIs. Dispatch has stripped the
+        // glob + cursor + limit by the time we run (pushDownFind: false),
+        // so this path is effectively a thin format/sort pass.
+        const format = parsed.params.format ?? "full";
+        if (format === "uris") {
+            // Build placeholder rows so applyReadParams's sort/cursor/limit
+            // can operate, then it projects to `string[]`. We never need the
+            // record values on this branch.
+            const rows = uris.map((u) => [u, {}]);
+            return applyReadParams(rows, parsed.params, STORE_NAME);
+        }
+        const rows = [];
+        for (const uri of uris) {
+            const rec = await this._readOne(meta, uri);
+            if (rec !== undefined)
+                rows.push([uri, rec]);
+        }
+        return applyReadParams(rows, parsed.params, STORE_NAME);
     }
-    async _deleteBytes(uris) {
+    // ── Delete ───────────────────────────────────────────────────────
+    async delete(meta, uris) {
+        if (uris.length === 0)
+            return [];
+        const bucket = this.buckets.get(meta.support.entity);
+        if (!bucket || bucket.signature !== 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 entry = this.index.get(uri);
+                const entry = bucket.index.get(uri);
                 if (entry) {
                     try {
                         await this.executor.unpin(entry.cid);
                     }
                     catch {
-                        // CID may already be unpinned — ignore
+                        // CID may already be unpinned — ignore.
                     }
-                    this.index.delete(uri);
+                    bucket.index.delete(uri);
                 }
                 results.push({ success: true });
             }
@@ -154,7 +341,7 @@ export class IpfsStore {
         }
         return results;
     }
-    // ── Status ───────────────────────────────────────────────────────
+    // ── Status / capabilities ────────────────────────────────────────
     async status() {
         try {
             const online = await this.executor.isOnline();
@@ -162,36 +349,50 @@ export class IpfsStore {
                 return {
                     status: "unhealthy",
                     message: "IPFS node is not reachable",
-                    fns: ["read", "ls", "count"],
+                    fns: ["read", "ls", "count", "find"],
                 };
             }
-            // Derive schema from indexed URIs
-            const programs = new Set();
-            for (const uri of this.index.keys()) {
-                try {
-                    const url = new URL(uri);
-                    programs.add(`${url.protocol}//${url.hostname}`);
-                }
-                catch {
-                    // skip malformed URIs
-                }
+            let indexedUris = 0;
+            for (const bucket of this.buckets.values()) {
+                indexedUris += bucket.index.size;
             }
             return {
                 status: "healthy",
-                schema: [...programs],
-                fns: ["read", "ls", "count"],
-                details: { indexedUris: this.index.size },
+                schema: [...this.buckets.keys()].map((n) => `entity:${n}`),
+                fns: ["read", "ls", "count", "find"],
+                details: { indexedUris },
             };
         }
         catch (error) {
             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 ────────────────────────────────────────────────────
+    /**
+     * 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;
+    }
 }