@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/errors.js

@@ -8,7 +8,7 @@
  * one line and the error code consistent (`STORAGE_ERROR` for
  * anything that came from the underlying driver).
  */
-import { Errors } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.js";
+import { Errors } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/mod.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`

package/esm/fs/mod.d.ts

@@ -22,6 +22,32 @@ export interface FsExecutor {
      * returned — `ls` / `count` are shallow contracts.
      */
     listFiles: (dir: string) => Promise<string[]>;
+    /**
+     * Walk every *file* descendant of `dir` recursively and yield each
+     * file's path **relative to `dir`** (no leading `/`, forward-slash
+     * separated). Directories themselves MUST NOT be yielded — only file
+     * leaves. Order is unspecified; callers must sort if they need it.
+     *
+     * Contract for non-existent / empty `dir`: yield nothing (do NOT
+     * throw). This matches the existing `listFiles` convention — `fn=ls`
+     * on an empty/missing prefix returns `[]`, never an error — and the
+     * `fn=find` handler inherits the same shape.
+     *
+     * `AsyncIterable` lets backends that can stream the walk lazily
+     * (Deno's `walk`, S3's paginated `ListObjectsV2`, etc.) do so without
+     * materialising the full path list; in-memory executors can yield
+     * Map keys directly. Consumers that want a materialised array call
+     * `Array.fromAsync(executor.walkFiles(dir))`.
+     *
+     * Used by the `fn=find` handler in `FsStore` to drive recursive
+     * listings (v2 §3.3, §3.5). Stores that only need `fn=ls` / `fn=read`
+     * don't invoke this path; an executor that omits it would break
+     * `fn=find` but nothing else. (The interface marks it required so the
+     * TypeScript compiler catches the omission at the call site instead
+     * of at runtime — see the smoke-rig migration note in PR #82's
+     * follow-up.)
+     */
+    walkFiles: (dir: string) => AsyncIterable<string>;
     cleanup?: () => Promise<void>;
 }
 export { FsStore } from "./store.js";

package/esm/fs/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/fs/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IAChE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C;;;;OAIG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/fs/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IAChE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C;;;;OAIG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/esm/fs/store.d.ts

@@ -1,45 +1,122 @@
 /**
- * FsStore — Filesystem implementation of Store.
+ * FsStore — Filesystem implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. Writes one
- * file per entry; the file body is the payload bytes verbatim. The
- * store is opaque — it does not parse or transform contents.
+ * The store is naive: URIs it is handed ARE relative filesystem paths
+ * under `rootDir`, and record payloads ARE the bytes written to those
+ * paths. No URI rewriting, no bytes/typed bifurcation, no field
+ * planning. Only `BYTES_ENTITY` is supported — any other schema is
+ * rejected at `entitySupport` time. Callers that want typed storage
+ * or a custom on-disk shape supply that via a `SaveClient` mapper.
  *
- * `fn=ls` / `fn=count` are shallow direct-leaves only: they list the
- * `.bin` files directly inside the prefix's mapped directory, never
- * recursing into subdirectories.
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it validates the schema is
+ * `BYTES_ENTITY` and returns the operational handle (root path,
+ * signature for collision detection).
+ * `provisionEntity(meta)` writes a tiny meta file at
+ * `{rootDir}/.b3nd/entities/{name}` holding the signature; subsequent
+ * `entityStatus(meta)` reads it back. Same-name different-shape
+ * provisioning throws. The bookkeeping dir is dot-prefixed so an app
+ * that points `rootDir` straight at a tree it also serves/walks keeps
+ * the store's metadata out of the way — conventional dotfile-skipping
+ * walkers ignore it, and it won't collide with content.
+ *
+ * ## Read params
+ *
+ * `fn=ls` / `fn=count` (without a glob) are shallow direct-leaves only:
+ * `listFiles` on the prefix's directory (== `{rootDir}/{prefixUri}`),
+ * filter to direct-child files (no further `/`), apply standard
+ * params (`limit`/`page`/`sortBy=uri`/`sortOrder`/`format`) in memory
+ * before opening file streams.
+ *
+ * `fn=find` is the recursive variant (v2 spec §3.3, §3.5): the store
+ * calls `executor.walkFiles` on the prefix directory and yields the
+ * full subtree as URIs. The glob post-filter, pagination, sort, and
+ * cursor slot are all applied by `dispatchRead` (`pushDownFind: false`).
+ *
+ * ## URI safety
+ *
+ * The store rejects URIs containing `..` segments or leading `/` at
+ * write/read/delete time — everything else is treated as an opaque
+ * relative path. The caller's mapper is responsible for producing
+ * path-safe URIs; the store's validation is a defense-in-depth check,
+ * not a sanitizer.
  */
-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 { FsExecutor } from "./mod.js";
-export declare class FsStore implements EntityStore<BytesOnlyEntityMeta> {
+/**
+ * FsStore-specific entity handle.
+ *
+ * `signature` is used for collision detection at provision time. All
+ * FsStore metas today have the same signature (only BYTES_ENTITY is
+ * supported), but the field is kept so future changes to the on-disk
+ * meta shape trigger the same collision path.
+ */
+export interface FsEntityMeta extends EntityMeta {
+    readonly signature: string;
+}
+export declare class FsStore implements EntityStore<FsEntityMeta> {
     private readonly rootDir;
     private readonly executor;
     constructor(rootDir: string, executor: FsExecutor);
-    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
-    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
-    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
-    write(meta: BytesOnlyEntityMeta, entries: {
+    entitySupport(schema: EntitySchema): FsEntityMeta;
+    entityStatus(meta: FsEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(meta: FsEntityMeta): Promise<void>;
+    write(meta: FsEntityMeta, 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: FsEntityMeta, urls: string[]): Promise<Output<T>[]>;
     private _readOne;
-    /** Resolve the on-disk directory that holds the direct leaves of `prefixUri`. */
-    private _dirForPrefix;
     /** List direct-child URIs under a prefix (no recursion). */
     private _listChildUris;
+    /**
+     * List every descendant URI under a prefix (deep, recursive). Drives
+     * `fn=find` — `dispatchRead` then applies the glob, sort, cursor, and
+     * pagination on the result.
+     *
+     * Yields URIs as they come out of `executor.walkFiles`. Order is
+     * whatever the executor produces (Deno's `walk` is unspecified);
+     * dispatch's `sortBy=uri` / `sortBy=leaf` paths cover ordering when
+     * the caller asks for it.
+     */
+    private _listAllDescendantUris;
     private _ls;
+    /**
+     * `fn=find` handler: deep walk under the prefix, return Output[] or
+     * string[] depending on `format`. dispatch runs the glob post-filter,
+     * cursor slot, and pagination on top.
+     *
+     * `sortBy=uri` is handled here (the dispatch contract is: every
+     * backend handles native uri-sort itself; dispatch only post-sorts
+     * non-uri sortBy values). Without this, Deno's `walk` yields entries
+     * in directory-traversal order, which is unstable across platforms
+     * and not what `sortBy=uri` callers expect.
+     */
+    private _find;
     private _count;
-    private _deleteBytes;
+    delete(meta: FsEntityMeta, uris: string[]): Promise<DeleteResult[]>;
     status(): Promise<StatusResult>;
     capabilities(): StoreCapabilities;
-    private _resolvePath;
+    /** Full on-disk path for a record's URI. */
+    private _dataPath;
+    /** Directory under which direct-leaf records of a prefix URI live. */
+    private _dirForPrefix;
+    /** Full on-disk path for an entity's meta record. */
+    private _metaPath;
+    /**
+     * Read the persisted signature for an entity, or `null` if no
+     * provisioning record exists. Used by both `entityStatus` and the
+     * write/delete provisioning gate.
+     */
+    private _readMetaSignature;
+    /**
+     * Scan the meta directory for every provisioned entity name. Used by
+     * `status()` to advertise the entities a peer can talk to.
+     */
+    private _listProvisionedEntities;
 }
 //# sourceMappingURL=store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/fs/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,UAAU,EAAE,MAAM,UAAU,CAAC;AA2B3C,qBAAa,OAAQ,YAAW,WAAW,CAAC,mBAAmB,CAAC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;gBAE1B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU;IAUjD,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;IAuBzB,OAAO,CAAC,UAAU;YAQJ,QAAQ;IAUtB,iFAAiF;IACjF,OAAO,CAAC,aAAa;IAQrB,4DAA4D;YAC9C,cAAc;YAgBd,GAAG;YA0BH,MAAM;YAON,YAAY;IAmBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAyBrC,YAAY,IAAI,iBAAiB;IAIjC,OAAO,CAAC,YAAY;CAGrB"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/fs/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAK3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAM3C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAwBD,qBAAa,OAAQ,YAAW,WAAW,CAAC,YAAY,CAAC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;gBAE1B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU;IAUjD,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY;IAiB3C,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAMnE,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBlD,KAAK,CACT,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA2C9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAeT,QAAQ;IAUtB,4DAA4D;YAC9C,cAAc;IAc5B;;;;;;;;;OASG;YACW,sBAAsB;YAetB,GAAG;IA6BjB;;;;;;;;;;OAUG;YACW,KAAK;YAuBL,MAAM;IAcd,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAiCnE,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IA2BrC,YAAY,IAAI,iBAAiB;IAMjC,4CAA4C;IAC5C,OAAO,CAAC,SAAS;IAIjB,sEAAsE;IACtE,OAAO,CAAC,aAAa;IAKrB,qDAAqD;IACrD,OAAO,CAAC,SAAS;IAIjB;;;;OAIG;YACW,kBAAkB;IAchC;;;OAGG;YACW,wBAAwB;CAUvC"}

package/esm/fs/store.js

@@ -1,39 +1,70 @@
 /**
- * FsStore — Filesystem implementation of Store.
+ * FsStore — Filesystem implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. Writes one
- * file per entry; the file body is the payload bytes verbatim. The
- * store is opaque — it does not parse or transform contents.
+ * The store is naive: URIs it is handed ARE relative filesystem paths
+ * under `rootDir`, and record payloads ARE the bytes written to those
+ * paths. No URI rewriting, no bytes/typed bifurcation, no field
+ * planning. Only `BYTES_ENTITY` is supported — any other schema is
+ * rejected at `entitySupport` time. Callers that want typed storage
+ * or a custom on-disk shape supply that via a `SaveClient` mapper.
  *
- * `fn=ls` / `fn=count` are shallow direct-leaves only: they list the
- * `.bin` files directly inside the prefix's mapped directory, never
- * recursing into subdirectories.
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it validates the schema is
+ * `BYTES_ENTITY` and returns the operational handle (root path,
+ * signature for collision detection).
+ * `provisionEntity(meta)` writes a tiny meta file at
+ * `{rootDir}/.b3nd/entities/{name}` holding the signature; subsequent
+ * `entityStatus(meta)` reads it back. Same-name different-shape
+ * provisioning throws. The bookkeeping dir is dot-prefixed so an app
+ * that points `rootDir` straight at a tree it also serves/walks keeps
+ * the store's metadata out of the way — conventional dotfile-skipping
+ * walkers ignore it, and it won't collide with content.
+ *
+ * ## Read params
+ *
+ * `fn=ls` / `fn=count` (without a glob) are shallow direct-leaves only:
+ * `listFiles` on the prefix's directory (== `{rootDir}/{prefixUri}`),
+ * filter to direct-child files (no further `/`), apply standard
+ * params (`limit`/`page`/`sortBy=uri`/`sortOrder`/`format`) in memory
+ * before opening file streams.
+ *
+ * `fn=find` is the recursive variant (v2 spec §3.3, §3.5): the store
+ * calls `executor.walkFiles` on the prefix directory and yields the
+ * full subtree as URIs. The glob post-filter, pagination, sort, and
+ * cursor slot are all applied by `dispatchRead` (`pushDownFind: false`).
+ *
+ * ## URI safety
+ *
+ * The store rejects URIs containing `..` segments or leading `/` at
+ * write/read/delete time — everything else is treated as an opaque
+ * relative path. The caller's mapper is responsible for producing
+ * path-safe URIs; the store's validation is a defense-in-depth check,
+ * not a sanitizer.
  */
-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 { BYTES_ENTITY, } from "../entity.js";
 const STORE_NAME = "FsStore";
-const EXT = ".bin";
-/**
- * Convert a URI to a relative filesystem path.
- * `protocol://host/path` becomes `protocol_host/path.bin`.
- *
- * Only the FIRST `://` is rewritten — embedded `://` (rare but legal
- * in protocol-tunneling uris) stays in the path.
- */
-function uriToRelPath(uri) {
-    return uri.replace("://", "_") + EXT;
-}
+const META_DIR = ".b3nd/entities";
+const BYTES_SIGNATURE = "bytes:v1";
 /**
- * Convert a relative filesystem path back to a URI.
- * `protocol_host/path.bin` becomes `protocol://host/path`.
+ * Validate that a URI is safe to use as a relative filesystem path
+ * under `rootDir`. Rejects `..` segments (path traversal) and leading
+ * `/` (absolute paths). Everything else is passed through as-is —
+ * mappers own path shape.
  */
-function relPathToUri(relPath) {
-    const withoutExt = relPath.endsWith(EXT)
-        ? relPath.slice(0, -EXT.length)
-        : relPath;
-    return withoutExt.replace("_", "://");
+function assertPathSafe(uri) {
+    if (uri.startsWith("/")) {
+        throw new Error(`${STORE_NAME}: URI must not start with '/'; got '${uri}'`);
+    }
+    const parts = uri.split("/");
+    for (const p of parts) {
+        if (p === "..") {
+            throw new Error(`${STORE_NAME}: URI must not contain '..' segments; got '${uri}'`);
+        }
+    }
 }
 export class FsStore {
     rootDir;
@@ -46,64 +77,98 @@ export class FsStore {
         this.rootDir = rootDir.replace(/\/+$/, "");
         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 (schema.name !== BYTES_ENTITY.name) {
+            throw new Error(`${STORE_NAME}: only BYTES_ENTITY is supported. Compose a ` +
+                `SaveClient mapper to encode typed records to bytes upstream.`);
+        }
+        return {
+            support: {
+                entity: schema.name,
+                supported: ["payload"],
+                unsupported: [],
+            },
+            signature: BYTES_SIGNATURE,
+        };
     }
-    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;
+        }
+        const path = this._metaPath(meta.support.entity);
+        await this.executor.writeFile(path, new TextEncoder().encode(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) {
+        for (const { uri, record } of entries) {
             try {
-                await this.executor.writeFile(this._resolvePath(entry.uri), entry.payload);
+                assertPathSafe(uri);
+                const payload = record.payload;
+                if (!(payload instanceof Uint8Array) &&
+                    !(payload instanceof ReadableStream)) {
+                    throw new Error("BYTES_ENTITY record.payload must be Uint8Array or ReadableStream");
+                }
+                await this.executor.writeFile(this._dataPath(uri), payload);
                 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),
+            find: (p) => this._find(p),
+            // The fs handler does not interpret the glob — it returns every
+            // descendant URI; dispatch's `compileSaveGlob` post-filter does
+            // the matching. Keeping the executor interface free of glob
+            // semantics (Deno's `walk` has its own glob notion that does NOT
+            // match the §3.3 grammar). See PR design note.
+            pushDownFind: false,
         });
     }
     async _readOne(uri) {
         try {
-            return await this.executor.readFile(this._resolvePath(uri));
+            assertPathSafe(uri);
+            const stream = await this.executor.readFile(this._dataPath(uri));
+            return { payload: stream };
         }
         catch {
             return undefined;
         }
     }
-    /** Resolve the on-disk directory that holds the direct leaves of `prefixUri`. */
-    _dirForPrefix(prefixUri) {
-        const rel = uriToRelPath(prefixUri).slice(0, -EXT.length).replace(/\/+$/, "");
-        return rel ? `${this.rootDir}/${rel}` : this.rootDir;
-    }
     /** List direct-child URIs under a prefix (no recursion). */
     async _listChildUris(prefixUri) {
+        assertPathSafe(prefixUri);
         let files;
         try {
             files = await this.executor.listFiles(this._dirForPrefix(prefixUri));
@@ -111,10 +176,35 @@ export class FsStore {
         catch {
             return [];
         }
-        const relDir = uriToRelPath(prefixUri).slice(0, -EXT.length).replace(/\/+$/, "");
+        const base = prefixUri.replace(/\/+$/, "");
         return files
-            .filter((f) => f.endsWith(EXT) && !f.includes("/"))
-            .map((f) => relPathToUri(`${relDir}/${f}`));
+            .filter((f) => !f.includes("/"))
+            .map((f) => (base ? `${base}/${f}` : f));
+    }
+    /**
+     * List every descendant URI under a prefix (deep, recursive). Drives
+     * `fn=find` — `dispatchRead` then applies the glob, sort, cursor, and
+     * pagination on the result.
+     *
+     * Yields URIs as they come out of `executor.walkFiles`. Order is
+     * whatever the executor produces (Deno's `walk` is unspecified);
+     * dispatch's `sortBy=uri` / `sortBy=leaf` paths cover ordering when
+     * the caller asks for it.
+     */
+    async _listAllDescendantUris(prefixUri) {
+        assertPathSafe(prefixUri);
+        const dir = this._dirForPrefix(prefixUri);
+        const base = prefixUri.replace(/\/+$/, "");
+        const out = [];
+        try {
+            for await (const relPath of this.executor.walkFiles(dir)) {
+                out.push(base ? `${base}/${relPath}` : relPath);
+            }
+        }
+        catch {
+            return [];
+        }
+        return out;
     }
     async _ls(parsed) {
         validateReadParams(parsed.params, STORE_NAME);
@@ -134,32 +224,79 @@ export class FsStore {
             return uris;
         const out = [];
         for (const uri of uris) {
-            out.push([uri, await this._readOne(uri)]);
+            const rec = await this._readOne(uri);
+            if (rec !== undefined)
+                out.push([uri, rec]);
+        }
+        return out;
+    }
+    /**
+     * `fn=find` handler: deep walk under the prefix, return Output[] or
+     * string[] depending on `format`. dispatch runs the glob post-filter,
+     * cursor slot, and pagination on top.
+     *
+     * `sortBy=uri` is handled here (the dispatch contract is: every
+     * backend handles native uri-sort itself; dispatch only post-sorts
+     * non-uri sortBy values). Without this, Deno's `walk` yields entries
+     * in directory-traversal order, which is unstable across platforms
+     * and not what `sortBy=uri` callers expect.
+     */
+    async _find(parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const { params } = parsed;
+        const format = params.format ?? "full";
+        let uris = await this._listAllDescendantUris(parsed.uri);
+        if (params.sortBy === "uri") {
+            const dir = params.sortOrder === "desc" ? -1 : 1;
+            uris = [...uris].sort((a, b) => a.localeCompare(b) * dir);
+        }
+        if (format === "uris")
+            return uris;
+        const out = [];
+        for (const uri of uris) {
+            const rec = await this._readOne(uri);
+            if (rec !== undefined)
+                out.push([uri, rec]);
         }
         return out;
     }
     async _count(parsed) {
         if (parsed.params.pattern !== undefined) {
+            // Filtered count routes through dispatch's ls-and-count path,
+            // which strips `pattern` before calling our `ls` handler — we
+            // should never see `params.pattern` here. Throw loudly if we do:
+            // it means dispatch's contract changed and the post-filter is
+            // about to silently undercount.
             throw new Error(`${STORE_NAME}: pattern filter not supported`);
         }
         return (await this._listChildUris(parsed.uri)).length;
     }
-    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 {
-                await this.executor.removeFile(this._resolvePath(uri));
+                assertPathSafe(uri);
+                await this.executor.removeFile(this._dataPath(uri));
                 results.push({ success: true });
             }
             catch {
                 // File may not exist — succeed silently (matches the
-                // miss-is-not-an-error convention)
+                // miss-is-not-an-error convention).
                 results.push({ success: true });
             }
         }
         return results;
     }
-    // ── Status ───────────────────────────────────────────────────────
+    // ── Status / capabilities ────────────────────────────────────────
     async status() {
         try {
             const rootExists = await this.executor.exists(this.rootDir);
@@ -167,13 +304,15 @@ export class FsStore {
                 return {
                     status: "unhealthy",
                     message: `Root directory not found: ${this.rootDir}`,
-                    fns: ["read", "ls", "count"],
+                    fns: ["read", "ls", "find", "count"],
                 };
             }
+            const schema = await this._listProvisionedEntities();
             return {
                 status: "healthy",
                 message: "Filesystem store is operational",
-                fns: ["read", "ls", "count"],
+                schema: schema.map((s) => `entity:${s}`),
+                fns: ["read", "ls", "find", "count"],
                 details: { rootDir: this.rootDir },
             };
         }
@@ -181,14 +320,59 @@ export class FsStore {
             return {
                 status: "unhealthy",
                 message: error instanceof Error ? error.message : String(error),
-                fns: ["read", "ls", "count"],
+                fns: ["read", "ls", "find", "count"],
             };
         }
     }
     capabilities() {
         return { atomicBatch: false };
     }
-    _resolvePath(uri) {
-        return `${this.rootDir}/${uriToRelPath(uri)}`;
+    // ── Internals ────────────────────────────────────────────────────
+    /** Full on-disk path for a record's URI. */
+    _dataPath(uri) {
+        return `${this.rootDir}/${uri}`;
+    }
+    /** Directory under which direct-leaf records of a prefix URI live. */
+    _dirForPrefix(prefixUri) {
+        const rel = prefixUri.replace(/\/+$/, "");
+        return rel ? `${this.rootDir}/${rel}` : this.rootDir;
+    }
+    /** Full on-disk path for an entity's meta record. */
+    _metaPath(entityName) {
+        return `${this.rootDir}/${META_DIR}/${entityName}`;
+    }
+    /**
+     * Read the persisted signature for an entity, or `null` if no
+     * provisioning record exists. Used by both `entityStatus` and the
+     * write/delete provisioning gate.
+     */
+    async _readMetaSignature(entityName) {
+        const path = this._metaPath(entityName);
+        try {
+            if (!(await this.executor.exists(path)))
+                return null;
+            const stream = await this.executor.readFile(path);
+            const bytes = await new Response(stream).bytes();
+            return new TextDecoder().decode(bytes);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Scan the meta directory for every provisioned entity name. Used by
+     * `status()` to advertise the entities a peer can talk to.
+     */
+    async _listProvisionedEntities() {
+        const dir = `${this.rootDir}/${META_DIR}`;
+        try {
+            if (!(await this.executor.exists(dir)))
+                return [];
+            const files = await this.executor.listFiles(dir);
+            return files.filter((f) => !f.includes("/"));
+        }
+        catch {
+            return [];
+        }
     }
 }