@bandeira-tech/b3nd-save 0.8.1

package/esm/elasticsearch/store.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ElasticsearchStore — Elasticsearch implementation of Store.
+ *
+ * Pure mechanical byte storage with no protocol awareness. URIs are
+ * partitioned into one index per `protocol_hostname` pair, with the
+ * path as the document `_id`. Payload bytes are base64-encoded into a
+ * string field — ES has no native binary type that round-trips
+ * arbitrary bytes through `_source`.
+ *
+ * `fn=ls` / `fn=count` are pushed down via an ES regex query that
+ * enforces the shallow-direct-leaves contract: `<docPrefix>[^/]+`.
+ * Lucene regex queries are auto-anchored, so the pattern must match
+ * the full `_id`.
+ */
+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 { EntityStore } from "../entity-store.js";
+import type { EntityRecord, EntitySchema } from "../entity.js";
+import type { StoreCapabilities, StoreWriteResult } from "../types.js";
+import type { ElasticsearchExecutor } from "./mod.js";
+export declare class ElasticsearchStore implements EntityStore<BytesOnlyEntityMeta> {
+    private readonly indexPrefix;
+    private readonly executor;
+    constructor(indexPrefix: string, executor: ElasticsearchExecutor);
+    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
+    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
+    write(meta: BytesOnlyEntityMeta, 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;
+    private _readOne;
+    private _leafQuery;
+    private _ls;
+    private _count;
+    private _deleteBytes;
+    status(): Promise<StatusResult>;
+    capabilities(): StoreCapabilities;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/elasticsearch/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;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;AAQ/D,OAAO,KAAK,EACV,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAwCtD,qBAAa,kBAAmB,YAAW,WAAW,CAAC,mBAAmB,CAAC;IACzE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;gBAErC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB;IAUhE,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;IAkCzB,OAAO,CAAC,UAAU;YAQJ,QAAQ;IAOtB,OAAO,CAAC,UAAU;YAQJ,GAAG;YAoCH,MAAM;YAQN,YAAY;IAqBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAyBrC,YAAY,IAAI,iBAAiB;CAGlC"}

package/esm/elasticsearch/store.js

@@ -0,0 +1,213 @@
+/**
+ * ElasticsearchStore — Elasticsearch implementation of Store.
+ *
+ * Pure mechanical byte storage with no protocol awareness. URIs are
+ * partitioned into one index per `protocol_hostname` pair, with the
+ * path as the document `_id`. Payload bytes are base64-encoded into a
+ * string field — ES has no native binary type that round-trips
+ * arbitrary bytes through `_source`.
+ *
+ * `fn=ls` / `fn=count` are pushed down via an ES regex query that
+ * enforces the shallow-direct-leaves contract: `<docPrefix>[^/]+`.
+ * Lucene regex queries are auto-anchored, so the pattern must match
+ * the full `_id`.
+ */
+import { bytesOnlyDelete, bytesOnlyEntitySupport, bytesOnlyRead, bytesOnlyWrite, } from "../byte-entity-shim.js";
+import { decodeBase64, encodeBase64 } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.js";
+import { dispatchRead } from "../dispatch.js";
+import { storageFailure } from "../errors.js";
+import { toBytes } from "../payload.js";
+import { validateReadParams } from "../read.js";
+const STORE_NAME = "ElasticsearchStore";
+/** Escape characters that are special in Lucene regex syntax. */
+function escapeLuceneRegex(input) {
+    return input.replace(/[.?+*|{}\[\]()"\\#@&<>~]/g, "\\$&");
+}
+/**
+ * Parse a URI into an Elasticsearch index name and document ID.
+ * `protocol://hostname/path` → index: `prefix_protocol_hostname`,
+ * docId: `path` (without leading slash).
+ */
+function uriToIndexAndDocId(uri, indexPrefix) {
+    const url = new URL(uri);
+    const protocol = url.protocol.replace(":", "");
+    const hostname = url.hostname;
+    return {
+        index: `${indexPrefix}_${protocol}_${hostname}`,
+        docId: url.pathname.substring(1),
+    };
+}
+/** Reconstruct a URI from an index name + document ID. */
+function indexAndDocIdToUri(index, indexPrefix, docId) {
+    const withoutPrefix = index.substring(indexPrefix.length + 1);
+    const firstUnderscore = withoutPrefix.indexOf("_");
+    const protocol = withoutPrefix.substring(0, firstUnderscore);
+    const hostname = withoutPrefix.substring(firstUnderscore + 1);
+    return `${protocol}://${hostname}/${docId}`;
+}
+export class ElasticsearchStore {
+    indexPrefix;
+    executor;
+    constructor(indexPrefix, executor) {
+        if (!indexPrefix)
+            throw new Error("indexPrefix is required");
+        if (!executor)
+            throw new Error("executor is required");
+        this.indexPrefix = indexPrefix;
+        this.executor = executor;
+    }
+    // ── EntityStore surface ──────────────────────────────────────────
+    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));
+    }
+    read(meta, urls) {
+        return bytesOnlyRead(meta, STORE_NAME, urls, (u) => this._readBytes(u));
+    }
+    delete(meta, uris) {
+        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    }
+    // ── Byte ops (BYTES_ENTITY routing) ──────────────────────────────
+    async _writeBytes(entries) {
+        const results = [];
+        for (const entry of entries) {
+            try {
+                const { index, docId } = uriToIndexAndDocId(entry.uri, this.indexPrefix);
+                // We mirror docId into a `path` source field so `ls`/`count`
+                // can run analyzed queries against it — ES 8 disallows
+                // `regexp` (and prefix/wildcard) against the `_id` metadata
+                // field. ES's default dynamic mapping for a string source
+                // field produces `path` (text) + `path.keyword` (keyword);
+                // we target `path.keyword` for exact-match regex push-down.
+                const bytes = await toBytes(entry.payload);
+                await this.executor.index(index, docId, {
+                    payload: encodeBase64(bytes),
+                    path: docId,
+                });
+                results.push({ success: true });
+            }
+            catch (err) {
+                results.push({
+                    success: false,
+                    ...storageFailure(err, "Write failed", entry.uri),
+                });
+            }
+        }
+        return results;
+    }
+    _readBytes(urls) {
+        return dispatchRead(urls, STORE_NAME, {
+            read: (p) => this._readOne(p.uri),
+            ls: (p) => this._ls(p),
+            count: (p) => this._count(p),
+        });
+    }
+    async _readOne(uri) {
+        const { index, docId } = uriToIndexAndDocId(uri, this.indexPrefix);
+        const doc = await this.executor.get(index, docId);
+        if (!doc)
+            return undefined;
+        return decodeBase64(doc.payload);
+    }
+    _leafQuery(docPrefix) {
+        return {
+            regexp: {
+                "path.keyword": `${escapeLuceneRegex(docPrefix)}[^/]+`,
+            },
+        };
+    }
+    async _ls(parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const { params } = parsed;
+        const format = params.format ?? "full";
+        const { index, docId } = uriToIndexAndDocId(parsed.uri, this.indexPrefix);
+        const body = {
+            query: this._leafQuery(docId),
+        };
+        if (params.sortBy === "uri") {
+            // Sort on the keyword subfield, same reason as the query above.
+            body.sort = [{
+                    "path.keyword": params.sortOrder === "desc" ? "desc" : "asc",
+                }];
+        }
+        if (params.limit !== undefined) {
+            const page = params.page ?? 1;
+            body.size = params.limit;
+            body.from = (page - 1) * params.limit;
+        }
+        else {
+            body.size = 10_000;
+        }
+        if (format === "uris")
+            body._source = false;
+        const result = await this.executor.search(index, body);
+        if (format === "uris") {
+            return result.hits.map((hit) => indexAndDocIdToUri(index, this.indexPrefix, hit._id));
+        }
+        return result.hits.map((hit) => [
+            indexAndDocIdToUri(index, this.indexPrefix, hit._id),
+            hit._source ? decodeBase64(hit._source.payload) : undefined,
+        ]);
+    }
+    async _count(parsed) {
+        if (parsed.params.pattern !== undefined) {
+            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+        }
+        const { index, docId } = uriToIndexAndDocId(parsed.uri, this.indexPrefix);
+        return await this.executor.count(index, { query: this._leafQuery(docId) });
+    }
+    async _deleteBytes(uris) {
+        const results = [];
+        for (const uri of uris) {
+            try {
+                const { index, docId } = uriToIndexAndDocId(uri, this.indexPrefix);
+                await this.executor.delete(index, docId);
+                results.push({ success: true });
+            }
+            catch (err) {
+                results.push({
+                    success: false,
+                    ...storageFailure(err, "Delete failed", uri),
+                });
+            }
+        }
+        return results;
+    }
+    // ── Status ───────────────────────────────────────────────────────
+    async status() {
+        try {
+            const ok = await this.executor.ping();
+            if (!ok) {
+                return {
+                    status: "unhealthy",
+                    message: "Elasticsearch cluster is not reachable",
+                    fns: ["read", "ls", "count"],
+                };
+            }
+            return {
+                status: "healthy",
+                message: "Elasticsearch store is operational",
+                fns: ["read", "ls", "count"],
+                details: { indexPrefix: this.indexPrefix },
+            };
+        }
+        catch (error) {
+            return {
+                status: "unhealthy",
+                message: error instanceof Error ? error.message : String(error),
+                fns: ["read", "ls", "count"],
+            };
+        }
+    }
+    capabilities() {
+        return { atomicBatch: false };
+    }
+}

package/esm/entity-store.d.ts

@@ -0,0 +1,106 @@
+/**
+ * EntityStore — schema-aware storage contract.
+ *
+ * A single store instance hosts many entities side-by-side. Nothing is
+ * pinned at construction; every operation is keyed by an opaque
+ * {@link EntityMeta} returned from {@link EntityStore.entitySupport}.
+ *
+ * ## Three-step lifecycle, controlled by the caller
+ *
+ * 1. **`entitySupport(schema)`** — pure. Compiles the schema into the
+ *    backend's operational handle (column plans, target table names,
+ *    bytes-field sets, the per-field {@link EntitySupport} report).
+ *    No side effects, no IO. The returned meta is what the rest of
+ *    the surface consumes.
+ * 2. **`provisionEntity(meta)`** — idempotent. Materialises the
+ *    entity on the medium: creates the table, allocates the bucket,
+ *    writes the index. Re-running with the same meta is a no-op.
+ *    Running with a meta whose shape conflicts with what is already
+ *    provisioned at the same name surfaces an error.
+ * 3. **`entityStatus(meta)`** — checks whether the entity described
+ *    by `meta` is live on the medium right now. Returns `"live"`
+ *    only when the medium's current shape matches `meta`; a same-name
+ *    entity with a different shape reports `"unprovisioned"`. Use to
+ *    decide whether to provision now or skip; do not use as a
+ *    precondition before every operation — it adds cost that the
+ *    natural backend failure already gives you for free.
+ *
+ * Provisioning is the caller's job. `write` / `read` / `delete` do
+ * not pre-check or auto-provision; if a meta refers to an entity
+ * that is not live on the medium, the operation surfaces the
+ * backend's natural failure (storage error / undefined table / etc.).
+ *
+ * ## Strictness
+ *
+ * Writes/reads/deletes are strict. A record that does not match the
+ * meta's declared shape produces a `StoreWriteResult.error` (or
+ * `DeleteResult.error` for delete-time failures). The store never
+ * silently drops or coerces — coercion is the client's job (see
+ * `SaveClient`, which projects raw bytes into a `BYTES_ENTITY`
+ * record when its target is `BYTES_ENTITY`).
+ *
+ * Reads return `Output<EntityRecord | undefined>` for `fn=read`;
+ * `fn=ls` and `fn=count` follow the same conventions as `Store`
+ * (URI lists and numbers — see `./read.ts`).
+ */
+import type { DeleteResult, Output, StatusResult } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import type { EntityMeta, EntityRecord, EntitySchema } from "./entity.js";
+import type { StoreCapabilities, StoreWriteResult } from "./types.js";
+export interface EntityStore<TMeta extends EntityMeta = EntityMeta> {
+    /**
+     * Compile a schema into the backend's opaque operational handle.
+     * Pure: no IO, no cache mutation. The caller owns the returned
+     * meta's lifetime and decides whether to memoize, re-derive, or
+     * pass it through.
+     */
+    entitySupport(schema: EntitySchema): TMeta;
+    /**
+     * Whether the entity described by `meta` is live on the medium.
+     * `"live"` only when the medium's current shape matches `meta`;
+     * a same-name entity with a different shape reports
+     * `"unprovisioned"` so callers do not act on a collision.
+     */
+    entityStatus(meta: TMeta): Promise<"live" | "unprovisioned">;
+    /**
+     * Materialise the entity described by `meta` on the medium.
+     * Idempotent: repeat calls with the same meta no-op. Calling with
+     * a meta whose shape conflicts with an already-provisioned entity
+     * at the same name throws.
+     */
+    provisionEntity(meta: TMeta): Promise<void>;
+    /**
+     * Write records described by `meta` at the given URIs. Per-entry
+     * result is returned in input order. A record that does not match
+     * `meta`'s declared shape produces a failure result for that
+     * entry — the store does not coerce. Calling with a meta whose
+     * entity is not live on the medium surfaces the backend's natural
+     * storage failure per entry.
+     */
+    write(meta: TMeta, entries: {
+        uri: string;
+        record: EntityRecord;
+    }[]): Promise<StoreWriteResult[]>;
+    /**
+     * Read records described by `meta` at the given URLs. URLs follow
+     * the standard `fn=read|ls|count|x-*` grammar — see `./read.ts`.
+     * `fn=read` yields `Output<EntityRecord | undefined>` (undefined
+     * payload means miss); `fn=ls` and `fn=count` follow the package
+     * conventions. Reads against an entity that is not live on the
+     * medium surface as misses or the backend's natural read error.
+     */
+    read<T = EntityRecord | undefined>(meta: TMeta, urls: string[]): Promise<Output<T>[]>;
+    /**
+     * Delete records described by `meta` at the given URIs. Per-entry
+     * result is returned in input order.
+     */
+    delete(meta: TMeta, uris: string[]): Promise<DeleteResult[]>;
+    /** Health + capabilities, aggregated across all hosted entities. */
+    status(): Promise<StatusResult>;
+    /**
+     * Optional capability reporting. Backends advertise what they can
+     * do so clients can make informed decisions (e.g. wrap deletes +
+     * writes in a transaction when `atomicBatch` is true).
+     */
+    capabilities?(): StoreCapabilities;
+}
+//# sourceMappingURL=entity-store.d.ts.map

package/esm/entity-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-store.d.ts","sourceRoot":"","sources":["../src/entity-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,kEAAkE,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,WAAW,WAAW,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU;IAChE;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAAC;IAE3C;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;IAE7D;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C;;;;;;;OAOG;IACH,KAAK,CACH,IAAI,EAAE,KAAK,EACX,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAE/B;;;;;;;OAOG;IACH,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE7D,oEAAoE;IACpE,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAEhC;;;;OAIG;IACH,YAAY,CAAC,IAAI,iBAAiB,CAAC;CACpC"}

package/esm/entity-store.js

@@ -0,0 +1,46 @@
+/**
+ * EntityStore — schema-aware storage contract.
+ *
+ * A single store instance hosts many entities side-by-side. Nothing is
+ * pinned at construction; every operation is keyed by an opaque
+ * {@link EntityMeta} returned from {@link EntityStore.entitySupport}.
+ *
+ * ## Three-step lifecycle, controlled by the caller
+ *
+ * 1. **`entitySupport(schema)`** — pure. Compiles the schema into the
+ *    backend's operational handle (column plans, target table names,
+ *    bytes-field sets, the per-field {@link EntitySupport} report).
+ *    No side effects, no IO. The returned meta is what the rest of
+ *    the surface consumes.
+ * 2. **`provisionEntity(meta)`** — idempotent. Materialises the
+ *    entity on the medium: creates the table, allocates the bucket,
+ *    writes the index. Re-running with the same meta is a no-op.
+ *    Running with a meta whose shape conflicts with what is already
+ *    provisioned at the same name surfaces an error.
+ * 3. **`entityStatus(meta)`** — checks whether the entity described
+ *    by `meta` is live on the medium right now. Returns `"live"`
+ *    only when the medium's current shape matches `meta`; a same-name
+ *    entity with a different shape reports `"unprovisioned"`. Use to
+ *    decide whether to provision now or skip; do not use as a
+ *    precondition before every operation — it adds cost that the
+ *    natural backend failure already gives you for free.
+ *
+ * Provisioning is the caller's job. `write` / `read` / `delete` do
+ * not pre-check or auto-provision; if a meta refers to an entity
+ * that is not live on the medium, the operation surfaces the
+ * backend's natural failure (storage error / undefined table / etc.).
+ *
+ * ## Strictness
+ *
+ * Writes/reads/deletes are strict. A record that does not match the
+ * meta's declared shape produces a `StoreWriteResult.error` (or
+ * `DeleteResult.error` for delete-time failures). The store never
+ * silently drops or coerces — coercion is the client's job (see
+ * `SaveClient`, which projects raw bytes into a `BYTES_ENTITY`
+ * record when its target is `BYTES_ENTITY`).
+ *
+ * Reads return `Output<EntityRecord | undefined>` for `fn=read`;
+ * `fn=ls` and `fn=count` follow the same conventions as `Store`
+ * (URI lists and numbers — see `./read.ts`).
+ */
+export {};

package/esm/entity.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Entity schema types.
+ *
+ * `b3nd-save` ships one store interface: `EntityStore` (see
+ * `./entity-store.ts`) — schema-aware: every operation takes the
+ * `EntitySchema` it targets, so a single store instance can host many
+ * entities side-by-side. Schema is per-call, not pinned at
+ * construction.
+ *
+ * Entities are a client-layer concern. Clients map their wire payload
+ * (`Output<T>`) into `EntityRecord`s and call the store with an
+ * explicit schema; the store organises the medium accordingly
+ * (separate Postgres tables, separate Mongo collections, separate
+ * in-memory record maps). The schema travels with the data: there is
+ * no implicit "current entity" inside the store.
+ *
+ * ## Open type vocabulary
+ *
+ * `EntityField.type` is `string[]`. The strings this package knows
+ * about live in {@link TYPE_TAGS}, but the field type itself is
+ * intentionally not a literal union — entities are shared across
+ * protocols and custom stores, and one protocol's `"money"` or
+ * `"geo"` tag should travel unchanged through stores that don't
+ * recognise it. A field may carry multiple tags (e.g.
+ * `["string", "email"]`) — they are refinements, not a value-type
+ * union. A store consults the tags it knows to decide how to
+ * materialise the field, and reports any field whose tags it cannot
+ * make sense of as unsupported.
+ *
+ * ## Coercion vs. error reporting
+ *
+ * The store is strict: anything that doesn't fit the schema becomes
+ * an error result so the rig wiring can be fixed. Coercion and field
+ * projection are the client's job — `SaveClient` in its default
+ * `BYTES_ENTITY` mode builds a `{ payload: bytes }` record from
+ * incoming bytes; in record mode it passes records through verbatim.
+ * If a record arrives with extra or mistyped fields, the store
+ * reports the error rather than silently dropping data.
+ */
+/**
+ * Canonical type tags published by this package.
+ *
+ * Stores in `b3nd-save` recognise these tags. Other protocols and
+ * custom stores may freely add their own; `EntityField.type` stays
+ * `string[]` so unknown tags pass through intact.
+ */
+export declare const TYPE_TAGS: {
+    readonly STRING: "string";
+    readonly NUMBER: "number";
+    readonly BIGINT: "bigint";
+    readonly BOOLEAN: "boolean";
+    readonly BYTES: "bytes";
+    readonly TIMESTAMP: "timestamp";
+    readonly JSON: "json";
+};
+/**
+ * A field of an entity — a name plus an open list of type tags.
+ *
+ * Multiple tags are refinements describing the same value (e.g.
+ * `["string", "email"]` — a string value semantically an email). A
+ * store that understands `"string"` can store the value; the
+ * `"email"` tag is a hint stores that want to validate or index
+ * differently can use.
+ */
+export interface EntityField {
+    name: string;
+    type: string[];
+}
+/**
+ * Declarative description of an entity.
+ *
+ * `name` is the entity's identifier in the medium — e.g. the Postgres
+ * table name, the Mongo collection name. Authors should pick a value
+ * that is safe for those mediums (lowercase, no special chars).
+ */
+export interface EntitySchema {
+    name: string;
+    fields: EntityField[];
+}
+/**
+ * A record of an entity — values keyed by field name. The type is
+ * `Record<string, unknown>` because the schema is open: per-field
+ * value types are decided by the tags an adapter understands. Store
+ * implementations validate against the schema on the way in.
+ */
+export type EntityRecord = Record<string, unknown>;
+/**
+ * Per-field support reported by `EntityStore.entitySupport`.
+ *
+ * A field is *supported* when the store recognised at least one of
+ * its tags and would provision storage for it. Unsupported fields
+ * carry a human-readable `reason`. Stores do not silently drop
+ * unsupported fields on write — see the file header on coercion.
+ */
+export interface EntitySupport {
+    entity: string;
+    supported: string[];
+    unsupported: {
+        name: string;
+        reason: string;
+    }[];
+}
+/**
+ * Opaque operational handle for an entity on a specific store.
+ *
+ * Returned by `EntityStore.entitySupport(schema)` and threaded back
+ * to `provisionEntity`, `entityStatus`, `write`, `read`, and
+ * `delete`. The base shape only exposes `support`; each backend
+ * extends this with whatever it needs to operate (column plans,
+ * target table names, bytes-field sets, etc.). The caller treats
+ * the meta as opaque and owns its lifetime — the store keeps no
+ * per-entity caches of its own.
+ */
+export interface EntityMeta {
+    readonly support: EntitySupport;
+}
+/**
+ * Canonical entity for raw-byte storage.
+ *
+ * `EntityStore.write(BYTES_ENTITY, [{ uri, record: { payload: bytes }}])`
+ * is how opaque bytes go into the store; pair it with `mapToBytes`
+ * from `./clients` to expose a bytes-on-the-wire `ProtocolInterfaceNode`.
+ */
+export declare const BYTES_ENTITY: EntitySchema;
+//# sourceMappingURL=entity.d.ts.map

package/esm/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;;;;;;;CAQZ,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,YAG1B,CAAC"}

package/esm/entity.js

@@ -0,0 +1,66 @@
+/**
+ * Entity schema types.
+ *
+ * `b3nd-save` ships one store interface: `EntityStore` (see
+ * `./entity-store.ts`) — schema-aware: every operation takes the
+ * `EntitySchema` it targets, so a single store instance can host many
+ * entities side-by-side. Schema is per-call, not pinned at
+ * construction.
+ *
+ * Entities are a client-layer concern. Clients map their wire payload
+ * (`Output<T>`) into `EntityRecord`s and call the store with an
+ * explicit schema; the store organises the medium accordingly
+ * (separate Postgres tables, separate Mongo collections, separate
+ * in-memory record maps). The schema travels with the data: there is
+ * no implicit "current entity" inside the store.
+ *
+ * ## Open type vocabulary
+ *
+ * `EntityField.type` is `string[]`. The strings this package knows
+ * about live in {@link TYPE_TAGS}, but the field type itself is
+ * intentionally not a literal union — entities are shared across
+ * protocols and custom stores, and one protocol's `"money"` or
+ * `"geo"` tag should travel unchanged through stores that don't
+ * recognise it. A field may carry multiple tags (e.g.
+ * `["string", "email"]`) — they are refinements, not a value-type
+ * union. A store consults the tags it knows to decide how to
+ * materialise the field, and reports any field whose tags it cannot
+ * make sense of as unsupported.
+ *
+ * ## Coercion vs. error reporting
+ *
+ * The store is strict: anything that doesn't fit the schema becomes
+ * an error result so the rig wiring can be fixed. Coercion and field
+ * projection are the client's job — `SaveClient` in its default
+ * `BYTES_ENTITY` mode builds a `{ payload: bytes }` record from
+ * incoming bytes; in record mode it passes records through verbatim.
+ * If a record arrives with extra or mistyped fields, the store
+ * reports the error rather than silently dropping data.
+ */
+/**
+ * Canonical type tags published by this package.
+ *
+ * Stores in `b3nd-save` recognise these tags. Other protocols and
+ * custom stores may freely add their own; `EntityField.type` stays
+ * `string[]` so unknown tags pass through intact.
+ */
+export const TYPE_TAGS = {
+    STRING: "string",
+    NUMBER: "number",
+    BIGINT: "bigint",
+    BOOLEAN: "boolean",
+    BYTES: "bytes",
+    TIMESTAMP: "timestamp",
+    JSON: "json",
+};
+/**
+ * Canonical entity for raw-byte storage.
+ *
+ * `EntityStore.write(BYTES_ENTITY, [{ uri, record: { payload: bytes }}])`
+ * is how opaque bytes go into the store; pair it with `mapToBytes`
+ * from `./clients` to expose a bytes-on-the-wire `ProtocolInterfaceNode`.
+ */
+export const BYTES_ENTITY = {
+    name: "bytes",
+    fields: [{ name: "payload", type: [TYPE_TAGS.BYTES] }],
+};

package/esm/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Backend-author helpers for translating thrown executor errors into
+ * the structured failure shape used by `StoreWriteResult` and
+ * `DeleteResult`.
+ *
+ * Every Save backend ends up wanting the same `try/catch → { error,
+ * errorDetail }` translation; this keeps the per-store catch blocks
+ * one line and the error code consistent (`STORAGE_ERROR` for
+ * anything that came from the underlying driver).
+ */
+import type { B3ndError } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+/**
+ * Build the structured-failure half of a Store result from a thrown
+ * value. `fallback` is used when `err` isn't an `Error` (rare). `uri`
+ * is included on `errorDetail` when the failure attributes to a
+ * specific entry — omit for atomic-batch failures that affect the
+ * whole batch.
+ */
+export declare function storageFailure(err: unknown, fallback: string, uri?: string): {
+    error: string;
+    errorDetail: B3ndError;
+};
+//# sourceMappingURL=errors.d.ts.map

package/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kEAAkE,CAAC;AAElG;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,GACX;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,SAAS,CAAA;CAAE,CAM3C"}

package/esm/errors.js

@@ -0,0 +1,25 @@
+/**
+ * Backend-author helpers for translating thrown executor errors into
+ * the structured failure shape used by `StoreWriteResult` and
+ * `DeleteResult`.
+ *
+ * Every Save backend ends up wanting the same `try/catch → { error,
+ * errorDetail }` translation; this keeps the per-store catch blocks
+ * 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";
+/**
+ * Build the structured-failure half of a Store result from a thrown
+ * value. `fallback` is used when `err` isn't an `Error` (rare). `uri`
+ * is included on `errorDetail` when the failure attributes to a
+ * specific entry — omit for atomic-batch failures that affect the
+ * whole batch.
+ */
+export function storageFailure(err, fallback, uri) {
+    const message = err instanceof Error ? err.message : fallback;
+    return {
+        error: message,
+        errorDetail: Errors.storageError(message, uri),
+    };
+}