@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/s3/store.d.ts

@@ -1,46 +1,148 @@
 /**
- * S3Store — Amazon S3 implementation of Store.
+ * S3Store — Amazon S3 implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. One S3
- * object per entry. Object body is the payload bytes verbatim; the
- * store is opaque.
+ * One backend, many entities. Layouts:
  *
- * `fn=ls` / `fn=count` are shallow direct-leaves only: list objects
- * under the URI's key prefix, then filter to keys whose remainder
- * contains no further `/`. The `format=uris` fast path returns the
- * URIs without issuing `getObject`; `format=full` only fetches the
- * selected page.
+ * - `BYTES_ENTITY` → object key `{prefix}{uriToKey(uri)}.bin` holding
+ *   the raw payload bytes (existing layout — no migration).
+ * - any other schema → object key
+ *   `{prefix}entities/{entityName}/{uriToKey(uri)}.bin` holding a
+ *   JSON-encoded record. 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)` writes a tiny meta
+ * object at `{prefix}__meta__/entities/{name}` holding the signature;
+ * subsequent `entityStatus(meta)` reads it back.
+ *
+ * ## Read params
+ *
+ * `fn=ls` / `fn=count` are shallow direct-leaves only: `listObjects`
+ * under the entity's key range, filter to direct-child `.bin` keys
+ * (no further `/`). Standard params (`limit`/`page`/`sortBy=uri`/
+ * `sortOrder`/`format`) are applied in memory; `format=uris` and
+ * `count` skip the per-leaf `getObject`.
+ *
+ * `fn=find` is the recursive variant (v2 spec §3.3, §3.5): S3's
+ * `listObjects(prefix)` already walks every key under the prefix
+ * (the flat keyspace is what S3 returns natively — the shallow
+ * `tail.includes("/")` drop in `_listChildUris` is an in-process
+ * filter we omit for find). Dispatch applies the glob post-filter,
+ * sort, cursor, and pagination on top. We declare `pushDownFind:
+ * false` honestly: the *prefix* is pushed down (S3 supports nothing
+ * else), but the §3.3 glob grammar (`?`, `*`, `**`, mid-`**`) is
+ * richer than what S3's list API expresses, so the glob match still
+ * happens in dispatch.
+ *
+ * ### Known limit: listObjects pagination
+ *
+ * S3's `ListObjectsV2` returns at most 1000 keys per response and
+ * paginates via `ContinuationToken`. The current `S3Executor.listObjects`
+ * contract returns a flat `string[]` — executors are expected to walk
+ * the continuation themselves and concatenate. The in-tree integration
+ * executor (`./integration.test.ts`) does NOT yet paginate, so any
+ * entity holding >1000 records will silently truncate in the
+ * integration suite. Production executors built on the AWS SDK
+ * (e.g. via `@aws-sdk/client-s3`'s paginator) get this for free.
+ *
+ * ### Push-down matrix
+ *
+ * - `pushDownPattern`: not advertised — dispatch runs the glob.
+ * - `pushDownCursor`: not advertised — dispatch slices in JS.
+ * - `pushDownSortBy`: not advertised — dispatch sorts in JS.
+ * - `pushDownFind`: false (see above).
+ * - `pushDownCount`: not advertised — S3 has no efficient COUNT
+ *   (a COUNT translation would require streaming every key under
+ *   the prefix and tallying). For deep counts (`**`), dispatch
+ *   walks via the find handler and returns the length.
  */
-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 { S3Executor } from "./mod.js";
-export declare class S3Store implements EntityStore<BytesOnlyEntityMeta> {
+/**
+ * S3Store-specific entity handle.
+ *
+ * `keyPrefix` is the S3 key root for this entity's objects (the
+ * store's `prefix` for BYTES_ENTITY, plus `entities/{name}/` for
+ * custom). `isBytes` selects the raw-payload object body vs the
+ * JSON-encoded record body. `fields`/`declared`/`bytesFields` drive
+ * write-time validation and encoding; `signature` is used for
+ * collision detection.
+ */
+export interface S3EntityMeta extends EntityMeta {
+    readonly keyPrefix: string;
+    readonly isBytes: boolean;
+    readonly fields: readonly FieldPlan[];
+    readonly declared: ReadonlySet<string>;
+    readonly bytesFields: ReadonlySet<string>;
+    readonly signature: string;
+}
+export declare class S3Store implements EntityStore<S3EntityMeta> {
     private readonly bucket;
     private readonly executor;
     private readonly prefix;
     constructor(bucket: string, executor: S3Executor, prefix?: string);
-    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
-    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
-    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
-    write(meta: BytesOnlyEntityMeta, entries: {
+    entitySupport(schema: EntitySchema): S3EntityMeta;
+    entityStatus(meta: S3EntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(meta: S3EntityMeta): Promise<void>;
+    write(meta: S3EntityMeta, 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: S3EntityMeta, urls: string[]): Promise<Output<T>[]>;
     private _readOne;
     /** List direct-child URIs under a prefix (no recursion into sub-prefixes). */
     private _listChildUris;
+    /**
+     * List every descendant URI under a prefix (deep walk). Powers
+     * `fn=find`. Unlike `_listChildUris`, this keeps keys whose tail
+     * contains `/` — S3's `listObjects(prefix)` already returns every
+     * key under the prefix (flat keyspace), so the recursive walk is
+     * "the same call without the shallow drop". Dispatch's
+     * `compileSaveGlob` post-filter then applies the user's deep glob
+     * pattern (e.g. `**` or `**` + `/sub/*.md`), sort, cursor, and
+     * pagination.
+     *
+     * Pagination: relies on `S3Executor.listObjects` to walk
+     * continuation tokens itself (see the module-level comment about
+     * the in-tree integration executor's known truncation).
+     */
+    private _listAllDescendantUris;
     private _ls;
     private _count;
-    private _deleteBytes;
+    /**
+     * `fn=find` handler: deep walk under the prefix, return Output[] or
+     * string[] depending on `format`. dispatch runs the glob post-filter,
+     * sort, pagination, and cursor slot on top.
+     */
+    private _find;
+    delete(meta: S3EntityMeta, uris: string[]): Promise<DeleteResult[]>;
     status(): Promise<StatusResult>;
     capabilities(): StoreCapabilities;
-    private _resolveKey;
+    /** Full S3 key for a record under an entity. */
+    private _dataKey;
+    /** Full S3 key for an entity's meta object. */
+    private _metaKey;
+    /**
+     * Read the persisted signature for an entity, or `null` if no
+     * provisioning record exists.
+     */
+    private _readMetaSignature;
+    /**
+     * Scan the meta keyspace for every provisioned entity name. Used by
+     * `status()` to advertise the entities a peer can talk to.
+     */
+    private _listProvisionedEntities;
+    /**
+     * Collect any `ReadableStream` values on `bytes`-tagged fields into
+     * `Uint8Array` and return a shallow-copied record.
+     */
+    private _normaliseBytesFields;
 }
 //# sourceMappingURL=store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/s3/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;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;AAgB3C,qBAAa,OAAQ,YAAW,WAAW,CAAC,mBAAmB,CAAC;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM;IAWjE,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;IAwBzB,OAAO,CAAC,UAAU;YAQJ,QAAQ;IAOtB,8EAA8E;YAChE,cAAc;YAad,GAAG;YA0BH,MAAM;YAON,YAAY;IAoBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IA4BrC,YAAY,IAAI,iBAAiB;IAIjC,OAAO,CAAC,WAAW;CAGpB"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/s3/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;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,UAAU,EAAE,MAAM,UAAU,CAAC;AAmB3C;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,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,OAAQ,YAAW,WAAW,CAAC,YAAY,CAAC;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM;IAWjE,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY;IA0C3C,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;IA2E9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAcT,QAAQ;IAgBtB,8EAA8E;YAChE,cAAc;IAgB5B;;;;;;;;;;;;;OAaG;YACW,sBAAsB;YAetB,GAAG;YA4BH,MAAM;IAYpB;;;;OAIG;YACW,KAAK;IAoBb,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,gDAAgD;IAChD,OAAO,CAAC,QAAQ;IAIhB,+CAA+C;IAC/C,OAAO,CAAC,QAAQ;IAIhB;;;OAGG;YACW,kBAAkB;IAahC;;;OAGG;YACW,wBAAwB;IAYtC;;;OAGG;YACW,qBAAqB;CAmBpC"}

package/esm/s3/store.js

@@ -1,22 +1,75 @@
 /**
- * S3Store — Amazon S3 implementation of Store.
+ * S3Store — Amazon S3 implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. One S3
- * object per entry. Object body is the payload bytes verbatim; the
- * store is opaque.
+ * One backend, many entities. Layouts:
  *
- * `fn=ls` / `fn=count` are shallow direct-leaves only: list objects
- * under the URI's key prefix, then filter to keys whose remainder
- * contains no further `/`. The `format=uris` fast path returns the
- * URIs without issuing `getObject`; `format=full` only fetches the
- * selected page.
+ * - `BYTES_ENTITY` → object key `{prefix}{uriToKey(uri)}.bin` holding
+ *   the raw payload bytes (existing layout — no migration).
+ * - any other schema → object key
+ *   `{prefix}entities/{entityName}/{uriToKey(uri)}.bin` holding a
+ *   JSON-encoded record. 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)` writes a tiny meta
+ * object at `{prefix}__meta__/entities/{name}` holding the signature;
+ * subsequent `entityStatus(meta)` reads it back.
+ *
+ * ## Read params
+ *
+ * `fn=ls` / `fn=count` are shallow direct-leaves only: `listObjects`
+ * under the entity's key range, filter to direct-child `.bin` keys
+ * (no further `/`). Standard params (`limit`/`page`/`sortBy=uri`/
+ * `sortOrder`/`format`) are applied in memory; `format=uris` and
+ * `count` skip the per-leaf `getObject`.
+ *
+ * `fn=find` is the recursive variant (v2 spec §3.3, §3.5): S3's
+ * `listObjects(prefix)` already walks every key under the prefix
+ * (the flat keyspace is what S3 returns natively — the shallow
+ * `tail.includes("/")` drop in `_listChildUris` is an in-process
+ * filter we omit for find). Dispatch applies the glob post-filter,
+ * sort, cursor, and pagination on top. We declare `pushDownFind:
+ * false` honestly: the *prefix* is pushed down (S3 supports nothing
+ * else), but the §3.3 glob grammar (`?`, `*`, `**`, mid-`**`) is
+ * richer than what S3's list API expresses, so the glob match still
+ * happens in dispatch.
+ *
+ * ### Known limit: listObjects pagination
+ *
+ * S3's `ListObjectsV2` returns at most 1000 keys per response and
+ * paginates via `ContinuationToken`. The current `S3Executor.listObjects`
+ * contract returns a flat `string[]` — executors are expected to walk
+ * the continuation themselves and concatenate. The in-tree integration
+ * executor (`./integration.test.ts`) does NOT yet paginate, so any
+ * entity holding >1000 records will silently truncate in the
+ * integration suite. Production executors built on the AWS SDK
+ * (e.g. via `@aws-sdk/client-s3`'s paginator) get this for free.
+ *
+ * ### Push-down matrix
+ *
+ * - `pushDownPattern`: not advertised — dispatch runs the glob.
+ * - `pushDownCursor`: not advertised — dispatch slices in JS.
+ * - `pushDownSortBy`: not advertised — dispatch sorts in JS.
+ * - `pushDownFind`: false (see above).
+ * - `pushDownCount`: not advertised — S3 has no efficient COUNT
+ *   (a COUNT translation would require streaming every key under
+ *   the prefix and tallying). For deep counts (`**`), dispatch
+ *   walks via the find handler and returns the length.
  */
-import { bytesOnlyDelete, bytesOnlyEntitySupport, bytesOnlyRead, bytesOnlyWrite, } from "../byte-entity-shim.js";
 import { dispatchRead } from "../dispatch.js";
 import { storageFailure } from "../errors.js";
+import { toBytes } from "../payload.js";
 import { 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 = "S3Store";
 const EXT = ".bin";
+const ENTITY_KEY_PREFIX = "entities";
+const META_KEY_PREFIX = "__meta__/entities";
 /** `protocol://host/path` → `protocol_host/path`. */
 function uriToKey(uri) {
     return uri.replace("://", "_").replace(/^\//, "");
@@ -26,6 +79,9 @@ function keyTailToUri(tail) {
     const noExt = tail.endsWith(EXT) ? tail.slice(0, -EXT.length) : tail;
     return noExt.replace("_", "://");
 }
+function isBytesSchema(schema) {
+    return schema.name === BYTES_ENTITY.name;
+}
 export class S3Store {
     bucket;
     executor;
@@ -39,56 +95,138 @@ export class S3Store {
         this.executor = executor;
         this.prefix = prefix ?? "";
     }
-    // ── 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: [],
+                },
+                keyPrefix: this.prefix,
+                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,
+            },
+            keyPrefix: `${this.prefix}${ENTITY_KEY_PREFIX}/${schema.name}/`,
+            isBytes: false,
+            fields,
+            declared,
+            bytesFields,
+            signature: computeSignature(schema.name, fields),
+        };
     }
-    read(meta, urls) {
-        return bytesOnlyRead(meta, STORE_NAME, urls, (u) => this._readBytes(u));
+    async entityStatus(meta) {
+        const recorded = await this._readMetaSignature(meta.support.entity);
+        if (recorded === null)
+            return "unprovisioned";
+        return recorded === meta.signature ? "live" : "unprovisioned";
     }
-    delete(meta, uris) {
-        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    async provisionEntity(meta) {
+        const recorded = await this._readMetaSignature(meta.support.entity);
+        if (recorded !== null) {
+            if (recorded !== meta.signature) {
+                throw new Error(`${STORE_NAME}: entity '${meta.support.entity}' is already ` +
+                    `provisioned with a different shape`);
+            }
+            return;
+        }
+        await this.executor.putObject(this._metaKey(meta.support.entity), new TextEncoder().encode(meta.signature), "text/plain");
     }
-    // ── 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) {
+            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 {
-                await this.executor.putObject(this._resolveKey(entry.uri), entry.payload, "application/octet-stream");
+                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");
+                    }
+                    await this.executor.putObject(this._dataKey(meta, uri), payload, "application/octet-stream");
+                }
+                else {
+                    const normalised = await this._normaliseBytesFields(record, meta.bytesFields);
+                    const json = JSON.stringify(encodeRecord(meta.fields, normalised));
+                    await this.executor.putObject(this._dataKey(meta, uri), new TextEncoder().encode(json), "application/json");
+                }
                 results.push({ success: true });
             }
             catch (err) {
                 results.push({
                     success: false,
-                    ...storageFailure(err, "Write failed", entry.uri),
+                    ...storageFailure(err, "Write failed", uri),
                 });
             }
         }
         return results;
     }
-    _readBytes(urls) {
+    // ── Read ─────────────────────────────────────────────────────────
+    read(meta, urls) {
         return dispatchRead(urls, STORE_NAME, {
-            read: (p) => this._readOne(p.uri),
-            ls: (p) => this._ls(p),
-            count: (p) => this._count(p),
+            read: (p) => this._readOne(meta, p.uri),
+            ls: (p) => this._ls(meta, p),
+            count: (p) => this._count(meta, p),
+            find: (p) => this._find(meta, p),
+            // The handler returns every descendant URI under the prefix;
+            // dispatch's `compileSaveGlob` post-filter applies the §3.3
+            // grammar (`?`, `*`, `**`, mid-`**`). S3's list API only
+            // expresses prefix matching, so push-down stops at the prefix.
+            pushDownFind: false,
         });
     }
-    async _readOne(uri) {
-        const content = await this.executor.getObject(this._resolveKey(uri));
-        return content ?? undefined;
+    async _readOne(meta, uri) {
+        const stream = await this.executor.getObject(this._dataKey(meta, uri));
+        if (!stream)
+            return undefined;
+        if (meta.isBytes)
+            return { payload: stream };
+        try {
+            const bytes = await new Response(stream).bytes();
+            const text = new TextDecoder().decode(bytes);
+            return decodeRecord(meta.fields, JSON.parse(text));
+        }
+        catch {
+            return undefined;
+        }
     }
     /** List direct-child URIs under a prefix (no recursion into sub-prefixes). */
-    async _listChildUris(prefixUri) {
-        const keyPrefix = `${this.prefix}${uriToKey(prefixUri)}`;
+    async _listChildUris(meta, prefixUri) {
+        const keyPrefix = `${meta.keyPrefix}${uriToKey(prefixUri)}`;
         const keys = await this.executor.listObjects(keyPrefix);
         const uris = [];
         for (const key of keys) {
@@ -96,16 +234,42 @@ export class S3Store {
                 continue;
             const tail = key.slice(keyPrefix.length);
             if (tail.includes("/"))
-                continue; // nested, not a direct leaf
+                continue;
+            uris.push(`${prefixUri}${keyTailToUri(tail)}`);
+        }
+        return uris;
+    }
+    /**
+     * List every descendant URI under a prefix (deep walk). Powers
+     * `fn=find`. Unlike `_listChildUris`, this keeps keys whose tail
+     * contains `/` — S3's `listObjects(prefix)` already returns every
+     * key under the prefix (flat keyspace), so the recursive walk is
+     * "the same call without the shallow drop". Dispatch's
+     * `compileSaveGlob` post-filter then applies the user's deep glob
+     * pattern (e.g. `**` or `**` + `/sub/*.md`), sort, cursor, and
+     * pagination.
+     *
+     * Pagination: relies on `S3Executor.listObjects` to walk
+     * continuation tokens itself (see the module-level comment about
+     * the in-tree integration executor's known truncation).
+     */
+    async _listAllDescendantUris(meta, prefixUri) {
+        const keyPrefix = `${meta.keyPrefix}${uriToKey(prefixUri)}`;
+        const keys = await this.executor.listObjects(keyPrefix);
+        const uris = [];
+        for (const key of keys) {
+            if (!key.endsWith(EXT))
+                continue;
+            const tail = key.slice(keyPrefix.length);
             uris.push(`${prefixUri}${keyTailToUri(tail)}`);
         }
         return uris;
     }
-    async _ls(parsed) {
+    async _ls(meta, parsed) {
         validateReadParams(parsed.params, STORE_NAME);
         const { params } = parsed;
         const format = params.format ?? "full";
-        let uris = await this._listChildUris(parsed.uri);
+        let uris = await this._listChildUris(meta, parsed.uri);
         if (params.sortBy === "uri") {
             const dir = params.sortOrder === "desc" ? -1 : 1;
             uris = [...uris].sort((a, b) => a.localeCompare(b) * dir);
@@ -119,21 +283,56 @@ export class S3Store {
             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;
     }
-    async _count(parsed) {
+    async _count(meta, 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;
+        return (await this._listChildUris(meta, parsed.uri)).length;
     }
-    async _deleteBytes(uris) {
+    /**
+     * `fn=find` handler: deep walk under the prefix, return Output[] or
+     * string[] depending on `format`. dispatch runs the glob post-filter,
+     * sort, pagination, and cursor slot on top.
+     */
+    async _find(meta, parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const format = parsed.params.format ?? "full";
+        const uris = await this._listAllDescendantUris(meta, parsed.uri);
+        if (format === "uris")
+            return uris;
+        const out = [];
+        for (const uri of uris) {
+            const rec = await this._readOne(meta, uri);
+            if (rec !== undefined)
+                out.push([uri, rec]);
+        }
+        return out;
+    }
+    // ── 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.deleteObject(this._resolveKey(uri));
+                await this.executor.deleteObject(this._dataKey(meta, uri));
                 results.push({ success: true });
             }
             catch (err) {
@@ -145,7 +344,7 @@ export class S3Store {
         }
         return results;
     }
-    // ── Status ───────────────────────────────────────────────────────
+    // ── Status / capabilities ────────────────────────────────────────
     async status() {
         try {
             const ok = await this.executor.headBucket();
@@ -153,31 +352,88 @@ export class S3Store {
                 return {
                     status: "unhealthy",
                     message: `Bucket not accessible: ${this.bucket}`,
-                    fns: ["read", "ls", "count"],
+                    fns: ["read", "ls", "find", "count"],
                 };
             }
+            const schema = await this._listProvisionedEntities();
             return {
                 status: "healthy",
                 message: "S3 store is operational",
-                fns: ["read", "ls", "count"],
-                details: {
-                    bucket: this.bucket,
-                    prefix: this.prefix || "(none)",
-                },
+                schema: schema.map((s) => `entity:${s}`),
+                fns: ["read", "ls", "find", "count"],
+                details: { bucket: this.bucket, prefix: this.prefix || "(none)" },
             };
         }
         catch (error) {
             return {
                 status: "unhealthy",
                 message: error instanceof Error ? error.message : String(error),
-                fns: ["read", "ls", "count"],
+                fns: ["read", "ls", "find", "count"],
             };
         }
     }
     capabilities() {
         return { atomicBatch: false };
     }
-    _resolveKey(uri) {
-        return `${this.prefix}${uriToKey(uri)}${EXT}`;
+    // ── Internals ────────────────────────────────────────────────────
+    /** Full S3 key for a record under an entity. */
+    _dataKey(meta, uri) {
+        return `${meta.keyPrefix}${uriToKey(uri)}${EXT}`;
+    }
+    /** Full S3 key for an entity's meta object. */
+    _metaKey(entityName) {
+        return `${this.prefix}${META_KEY_PREFIX}/${entityName}`;
+    }
+    /**
+     * Read the persisted signature for an entity, or `null` if no
+     * provisioning record exists.
+     */
+    async _readMetaSignature(entityName) {
+        try {
+            const stream = await this.executor.getObject(this._metaKey(entityName));
+            if (!stream)
+                return null;
+            const bytes = await new Response(stream).bytes();
+            return new TextDecoder().decode(bytes);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Scan the meta keyspace for every provisioned entity name. Used by
+     * `status()` to advertise the entities a peer can talk to.
+     */
+    async _listProvisionedEntities() {
+        const metaKeyPrefix = `${this.prefix}${META_KEY_PREFIX}/`;
+        try {
+            const keys = await this.executor.listObjects(metaKeyPrefix);
+            return keys
+                .map((k) => k.slice(metaKeyPrefix.length))
+                .filter((k) => k.length > 0 && !k.includes("/"));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Collect any `ReadableStream` values on `bytes`-tagged fields into
+     * `Uint8Array` and return a shallow-copied record.
+     */
+    async _normaliseBytesFields(record, bytesFields) {
+        const out = { ...record };
+        for (const name of bytesFields) {
+            const v = out[name];
+            if (v === undefined || v === null)
+                continue;
+            if (v instanceof Uint8Array)
+                continue;
+            if (v instanceof ReadableStream) {
+                out[name] = await toBytes(v);
+                continue;
+            }
+            throw new Error(`field '${name}' must be Uint8Array or ReadableStream, got ${typeof v}`);
+        }
+        return out;
     }
 }