@bandeira-tech/b3nd-save 0.8.1

package/esm/payload.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Payload normalizers for backends.
+ *
+ * `StorePayload = Uint8Array | ReadableStream<Uint8Array>`. Backends
+ * with no native streaming path call `toBytes` on write to collect
+ * incoming streams. Backends that natively stream call `toStream` on
+ * read to wrap a buffered value back into a `ReadableStream` when
+ * that's the cheap shape for the caller.
+ *
+ * Both helpers go through `Response` so we get the platform's
+ * battle-tested coercion (handles `Uint8Array`, `ReadableStream`,
+ * locked stream errors, etc.) without re-implementing.
+ */
+import type { StorePayload } from "./types.js";
+/** Collect a `StorePayload` into a single `Uint8Array`. */
+export declare function toBytes(payload: StorePayload): Promise<Uint8Array>;
+/**
+ * Wrap a `StorePayload` as a `ReadableStream<Uint8Array>`. A
+ * `Uint8Array` becomes a single-chunk stream; an existing stream
+ * passes through. Use this on read paths from backends that prefer to
+ * yield a stream to callers.
+ */
+export declare function toStream(payload: StorePayload): ReadableStream<Uint8Array>;
+//# sourceMappingURL=payload.d.ts.map

package/esm/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../src/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,2DAA2D;AAC3D,wBAAsB,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAGxE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,cAAc,CAAC,UAAU,CAAC,CAG1E"}

package/esm/payload.js

@@ -0,0 +1,30 @@
+/**
+ * Payload normalizers for backends.
+ *
+ * `StorePayload = Uint8Array | ReadableStream<Uint8Array>`. Backends
+ * with no native streaming path call `toBytes` on write to collect
+ * incoming streams. Backends that natively stream call `toStream` on
+ * read to wrap a buffered value back into a `ReadableStream` when
+ * that's the cheap shape for the caller.
+ *
+ * Both helpers go through `Response` so we get the platform's
+ * battle-tested coercion (handles `Uint8Array`, `ReadableStream`,
+ * locked stream errors, etc.) without re-implementing.
+ */
+/** Collect a `StorePayload` into a single `Uint8Array`. */
+export async function toBytes(payload) {
+    if (payload instanceof Uint8Array)
+        return payload;
+    return new Uint8Array(await new Response(payload).arrayBuffer());
+}
+/**
+ * Wrap a `StorePayload` as a `ReadableStream<Uint8Array>`. A
+ * `Uint8Array` becomes a single-chunk stream; an existing stream
+ * passes through. Use this on read paths from backends that prefer to
+ * yield a stream to callers.
+ */
+export function toStream(payload) {
+    if (payload instanceof ReadableStream)
+        return payload;
+    return new Response(payload).body;
+}

package/esm/postgres/columns.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TYPE_TAGS → Postgres column type mapping for native entity tables.
+ *
+ * Each canonical tag in `TYPE_TAGS` resolves to one SQL type. A field
+ * carrying multiple tags (e.g. `["string", "email"]`) picks the first
+ * recognized canonical tag in declaration order — extra refinement
+ * tags pass through without affecting storage.
+ */
+import { type EntityField } from "../entity.js";
+export interface ColumnPlan {
+    /** Field/column name. */
+    name: string;
+    /** Postgres SQL type. */
+    sqlType: string;
+    /** The recognized tag that decided `sqlType` (for diagnostics). */
+    tag: string;
+}
+export interface ColumnPlanResult {
+    columns: ColumnPlan[];
+    unsupported: {
+        name: string;
+        reason: string;
+    }[];
+}
+/**
+ * Resolve a schema's fields into Postgres column plans.
+ *
+ * Skips fields whose tags are all outside `TYPE_TAGS`; reports them
+ * via `unsupported`. Rejects invalid field names up front so we never
+ * emit unsafe SQL identifiers.
+ */
+export declare function planColumns(fields: EntityField[]): ColumnPlanResult;
+//# sourceMappingURL=columns.d.ts.map

package/esm/postgres/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../../src/postgres/columns.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAa,MAAM,cAAc,CAAC;AAc3D,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,gBAAgB,CA0BnE"}

package/esm/postgres/columns.js

@@ -0,0 +1,51 @@
+/**
+ * TYPE_TAGS → Postgres column type mapping for native entity tables.
+ *
+ * Each canonical tag in `TYPE_TAGS` resolves to one SQL type. A field
+ * carrying multiple tags (e.g. `["string", "email"]`) picks the first
+ * recognized canonical tag in declaration order — extra refinement
+ * tags pass through without affecting storage.
+ */
+import { TYPE_TAGS } from "../entity.js";
+const SQL_TYPE = {
+    [TYPE_TAGS.STRING]: "TEXT",
+    [TYPE_TAGS.NUMBER]: "DOUBLE PRECISION",
+    [TYPE_TAGS.BIGINT]: "BIGINT",
+    [TYPE_TAGS.BOOLEAN]: "BOOLEAN",
+    [TYPE_TAGS.BYTES]: "BYTEA",
+    [TYPE_TAGS.TIMESTAMP]: "TIMESTAMPTZ",
+    [TYPE_TAGS.JSON]: "JSONB",
+};
+const FIELD_NAME = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+/**
+ * Resolve a schema's fields into Postgres column plans.
+ *
+ * Skips fields whose tags are all outside `TYPE_TAGS`; reports them
+ * via `unsupported`. Rejects invalid field names up front so we never
+ * emit unsafe SQL identifiers.
+ */
+export function planColumns(fields) {
+    const columns = [];
+    const unsupported = [];
+    for (const field of fields) {
+        if (!FIELD_NAME.test(field.name)) {
+            unsupported.push({
+                name: field.name,
+                reason: `field name must match ${FIELD_NAME.source}; got '${field.name}'`,
+            });
+            continue;
+        }
+        const tag = field.type.find((t) => SQL_TYPE[t] !== undefined);
+        if (!tag) {
+            unsupported.push({
+                name: field.name,
+                reason: field.type.length === 0
+                    ? "field declares no type tags"
+                    : `no recognised tag in [${field.type.join(", ")}]`,
+            });
+            continue;
+        }
+        columns.push({ name: field.name, sqlType: SQL_TYPE[tag], tag });
+    }
+    return { columns, unsupported };
+}

package/esm/postgres/mod.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PostgreSQL backend for b3nd.
+ *
+ * `EntityStore` implementation backed by PostgreSQL. Requires an
+ * injected `SqlExecutor` so the SDK does not depend on a specific
+ * Postgres driver. Tables are provisioned lazily via `ensureEntity` —
+ * no separate schema-bootstrap step.
+ */
+export interface SqlExecutorResult {
+    rows: unknown[];
+    rowCount?: number;
+}
+export interface SqlExecutor {
+    query: (sql: string, args?: unknown[]) => Promise<SqlExecutorResult>;
+    transaction: <T>(fn: (tx: SqlExecutor) => Promise<T>) => Promise<T>;
+    cleanup?: () => Promise<void>;
+}
+export { PostgresStore } from "./store.js";
+//# sourceMappingURL=mod.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/postgres/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrE,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/esm/postgres/mod.js

@@ -0,0 +1,9 @@
+/**
+ * PostgreSQL backend for b3nd.
+ *
+ * `EntityStore` implementation backed by PostgreSQL. Requires an
+ * injected `SqlExecutor` so the SDK does not depend on a specific
+ * Postgres driver. Tables are provisioned lazily via `ensureEntity` —
+ * no separate schema-bootstrap step.
+ */
+export { PostgresStore } from "./store.js";

package/esm/postgres/store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * PostgresStore — PostgreSQL implementation of `EntityStore`.
+ *
+ * One layout for every schema: `{prefix}_{entity}_data` with `uri TEXT
+ * PRIMARY KEY` and one column per supported field, typed by the
+ * canonical `TYPE_TAGS` it carries (see `./columns.ts`). `BYTES_ENTITY`
+ * is just an entity with one `payload BYTEA` column — no legacy
+ * special case.
+ *
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it runs `planColumns` and returns
+ * a `PostgresEntityMeta` with the target table name, column plans,
+ * bytes-column set, and the support report. No IO.
+ *
+ * `provisionEntity(meta)` runs `CREATE TABLE IF NOT EXISTS` and then
+ * verifies the live shape matches the meta (catches same-name-
+ * different-shape collisions). `entityStatus(meta)` performs the same
+ * check in isolation via `information_schema`.
+ *
+ * Writes/reads/deletes consume the meta directly: no per-call cache
+ * gate. If the table is not provisioned, Postgres returns
+ * `undefined_table` (`42P01`); the standard `storageFailure` wrap
+ * surfaces it per entry.
+ *
+ * `fn=ls` / `fn=count` push down to SQL — the shallow-direct-leaves
+ * predicate (`uri LIKE prefix% AND uri NOT LIKE prefix%/%`) is
+ * enforced in the WHERE clause against the entity's table.
+ *
+ * Writes are wrapped in a transaction (`capabilities.atomicBatch =
+ * true`). Stream-shaped values on `BYTEA` columns are collected to
+ * `Uint8Array` *before* the transaction opens, so a stream failure
+ * can't leave a half-applied commit.
+ */
+import type { DeleteResult, Output, StatusResult } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import type { EntityStore } from "../entity-store.js";
+import type { EntityMeta, EntityRecord, EntitySchema } from "../entity.js";
+import type { StoreCapabilities, StoreWriteResult } from "../types.js";
+import { type ColumnPlan } from "./columns.js";
+import type { SqlExecutor } from "./mod.js";
+/**
+ * PostgresStore-specific entity handle.
+ *
+ * `tableName` is the prefixed-and-suffixed target table; `columns`
+ * are the planned user columns (without the always-present `uri`,
+ * `created_at`, `updated_at`); `declared` is the set of user column
+ * names for the per-write extras check; `bytesColumns` drives
+ * pre-transaction stream normalisation.
+ */
+export interface PostgresEntityMeta extends EntityMeta {
+    readonly tableName: string;
+    readonly columns: readonly ColumnPlan[];
+    readonly declared: ReadonlySet<string>;
+    readonly bytesColumns: ReadonlySet<string>;
+}
+export declare class PostgresStore implements EntityStore<PostgresEntityMeta> {
+    private readonly tablePrefix;
+    private readonly executor;
+    constructor(tablePrefix: string, executor: SqlExecutor);
+    entitySupport(schema: EntitySchema): PostgresEntityMeta;
+    entityStatus(meta: PostgresEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(meta: PostgresEntityMeta): Promise<void>;
+    write(meta: PostgresEntityMeta, entries: {
+        uri: string;
+        record: EntityRecord;
+    }[]): Promise<StoreWriteResult[]>;
+    read<T = EntityRecord | undefined>(meta: PostgresEntityMeta, urls: string[]): Promise<Output<T>[]>;
+    delete(meta: PostgresEntityMeta, uris: string[]): Promise<DeleteResult[]>;
+    status(): Promise<StatusResult>;
+    capabilities(): StoreCapabilities;
+    private _readOne;
+    private _ls;
+    private _count;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/postgres/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAM3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,KAAK,UAAU,EAAe,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAM5C;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5C;AAoCD,qBAAa,aAAc,YAAW,WAAW,CAAC,kBAAkB,CAAC;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;gBAE3B,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW;IAetD,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB;IAkBjD,YAAY,CAChB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IA4B9B,eAAe,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBxD,KAAK,CACT,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA4E9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAQjB,MAAM,CACV,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,YAAY,EAAE,CAAC;IAkBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAoBrC,YAAY,IAAI,iBAAiB;YAMnB,QAAQ;YAqBR,GAAG;YAgCH,MAAM;CAcrB"}

package/esm/postgres/store.js

@@ -0,0 +1,364 @@
+/**
+ * PostgresStore — PostgreSQL implementation of `EntityStore`.
+ *
+ * One layout for every schema: `{prefix}_{entity}_data` with `uri TEXT
+ * PRIMARY KEY` and one column per supported field, typed by the
+ * canonical `TYPE_TAGS` it carries (see `./columns.ts`). `BYTES_ENTITY`
+ * is just an entity with one `payload BYTEA` column — no legacy
+ * special case.
+ *
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it runs `planColumns` and returns
+ * a `PostgresEntityMeta` with the target table name, column plans,
+ * bytes-column set, and the support report. No IO.
+ *
+ * `provisionEntity(meta)` runs `CREATE TABLE IF NOT EXISTS` and then
+ * verifies the live shape matches the meta (catches same-name-
+ * different-shape collisions). `entityStatus(meta)` performs the same
+ * check in isolation via `information_schema`.
+ *
+ * Writes/reads/deletes consume the meta directly: no per-call cache
+ * gate. If the table is not provisioned, Postgres returns
+ * `undefined_table` (`42P01`); the standard `storageFailure` wrap
+ * surfaces it per entry.
+ *
+ * `fn=ls` / `fn=count` push down to SQL — the shallow-direct-leaves
+ * predicate (`uri LIKE prefix% AND uri NOT LIKE prefix%/%`) is
+ * enforced in the WHERE clause against the entity's table.
+ *
+ * Writes are wrapped in a transaction (`capabilities.atomicBatch =
+ * true`). Stream-shaped values on `BYTEA` columns are collected to
+ * `Uint8Array` *before* the transaction opens, so a stream failure
+ * can't leave a half-applied commit.
+ */
+import { dispatchRead } from "../dispatch.js";
+import { storageFailure } from "../errors.js";
+import { toBytes } from "../payload.js";
+import { validateReadParams } from "../read.js";
+import { planColumns } from "./columns.js";
+const STORE_NAME = "PostgresStore";
+const TABLE_PREFIX = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+/** Map a `ColumnPlan.sqlType` to the `information_schema.columns.data_type` value. */
+const INFO_SCHEMA_TYPE = {
+    TEXT: "text",
+    "DOUBLE PRECISION": "double precision",
+    BIGINT: "bigint",
+    BOOLEAN: "boolean",
+    BYTEA: "bytea",
+    TIMESTAMPTZ: "timestamp with time zone",
+    JSONB: "jsonb",
+};
+/** Coerce a pg `bytea` row value into a `Uint8Array`. */
+function rowToBytes(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (typeof value === "string" && value.startsWith("\\x")) {
+        const hex = value.slice(2);
+        const out = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < out.length; i++) {
+            out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        }
+        return out;
+    }
+    throw new Error(`${STORE_NAME}: unexpected payload type ${typeof value}`);
+}
+function entityTableName(tablePrefix, entityName) {
+    if (!TABLE_PREFIX.test(entityName)) {
+        throw new Error(`${STORE_NAME}: entity name '${entityName}' must match ${TABLE_PREFIX.source}`);
+    }
+    return `${tablePrefix}_${entityName}_data`;
+}
+export class PostgresStore {
+    tablePrefix;
+    executor;
+    constructor(tablePrefix, executor) {
+        if (!tablePrefix)
+            throw new Error("tablePrefix is required");
+        if (!TABLE_PREFIX.test(tablePrefix)) {
+            throw new Error(`tablePrefix must match ${TABLE_PREFIX.source}; got '${tablePrefix}'`);
+        }
+        if (!executor)
+            throw new Error("executor is required");
+        this.tablePrefix = tablePrefix;
+        this.executor = executor;
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────
+    entitySupport(schema) {
+        const { columns, unsupported } = planColumns(schema.fields);
+        const support = {
+            entity: schema.name,
+            supported: columns.map((c) => c.name),
+            unsupported,
+        };
+        return {
+            support,
+            tableName: entityTableName(this.tablePrefix, schema.name),
+            columns,
+            declared: new Set(columns.map((c) => c.name)),
+            bytesColumns: new Set(columns.filter((c) => c.sqlType === "BYTEA").map((c) => c.name)),
+        };
+    }
+    async entityStatus(meta) {
+        const res = await this.executor.query(`SELECT column_name, data_type FROM information_schema.columns
+       WHERE table_name = $1`, [meta.tableName]);
+        const rows = (res.rows ?? []);
+        if (rows.length === 0)
+            return "unprovisioned";
+        const actual = new Map(rows.map((r) => [r.column_name, r.data_type]));
+        for (const c of meta.columns) {
+            const got = actual.get(c.name);
+            if (got === undefined)
+                return "unprovisioned";
+            const expected = INFO_SCHEMA_TYPE[c.sqlType];
+            if (expected !== undefined && got !== expected)
+                return "unprovisioned";
+        }
+        // Reject collisions in the other direction: the live table carrying
+        // user columns the meta does not declare is a different shape.
+        for (const name of actual.keys()) {
+            if (name === "uri" || name === "created_at" || name === "updated_at") {
+                continue;
+            }
+            if (!meta.declared.has(name))
+                return "unprovisioned";
+        }
+        return "live";
+    }
+    async provisionEntity(meta) {
+        const colDdl = meta.columns
+            .map((c) => `"${c.name}" ${c.sqlType}`)
+            .join(",\n  ");
+        const sql = `CREATE TABLE IF NOT EXISTS ${meta.tableName} (
+  uri TEXT PRIMARY KEY${meta.columns.length > 0 ? ",\n  " + colDdl : ""},
+  created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_${meta.tableName}_uri ON ${meta.tableName} (uri);`;
+        await this.executor.query(sql);
+        // If the table already existed with a different shape, the
+        // CREATE IF NOT EXISTS was a no-op — surface the collision.
+        const status = await this.entityStatus(meta);
+        if (status !== "live") {
+            throw new Error(`${STORE_NAME}: entity '${meta.support.entity}' is already ` +
+                `provisioned with a different shape at table '${meta.tableName}'`);
+        }
+    }
+    // ── Write ────────────────────────────────────────────────────────
+    async write(meta, entries) {
+        if (entries.length === 0)
+            return [];
+        const out = new Array(entries.length);
+        const accepted = [];
+        // Validate + collect stream-shaped bytes fields BEFORE the
+        // transaction. Per-entry validation errors leak as failures in
+        // their slots; everything else gets committed atomically below.
+        for (let i = 0; i < entries.length; i++) {
+            const { uri, record } = entries[i];
+            const extras = Object.keys(record).filter((k) => !meta.declared.has(k));
+            if (extras.length > 0) {
+                out[i] = {
+                    success: false,
+                    ...storageFailure(new Error(`${STORE_NAME}: record contains keys not declared in schema '${meta.support.entity}': ${extras.join(", ")}`), "Schema mismatch", uri),
+                };
+                continue;
+            }
+            try {
+                const normalised = await normaliseBytesFields(record, meta.bytesColumns);
+                accepted.push({ idx: i, uri, record: normalised });
+            }
+            catch (err) {
+                out[i] = {
+                    success: false,
+                    ...storageFailure(err, "Invalid record", uri),
+                };
+            }
+        }
+        if (accepted.length === 0)
+            return out;
+        const cols = meta.columns;
+        const colList = cols.map((c) => `"${c.name}"`).join(", ");
+        const placeholders = cols.map((_, i) => `$${i + 2}`).join(", ");
+        const updates = cols
+            .map((c) => `"${c.name}" = EXCLUDED."${c.name}"`)
+            .concat(["updated_at = CURRENT_TIMESTAMP"])
+            .join(", ");
+        try {
+            await this.executor.transaction(async (tx) => {
+                for (const { uri, record } of accepted) {
+                    const args = [uri];
+                    for (const c of cols)
+                        args.push(adaptForWrite(c, record[c.name]));
+                    await tx.query(`INSERT INTO ${meta.tableName} (uri${colList ? ", " + colList : ""}) VALUES ($1${placeholders ? ", " + placeholders : ""})
+             ON CONFLICT (uri) DO UPDATE SET ${updates}`, args);
+                }
+            });
+            for (const { idx } of accepted)
+                out[idx] = { success: true };
+            return out;
+        }
+        catch (err) {
+            // Atomic batch failure — every accepted entry shares the same failure.
+            // An undefined_table from a not-yet-provisioned meta lands here too.
+            const failure = storageFailure(err, "Write failed");
+            for (const { idx } of accepted)
+                out[idx] = { success: false, ...failure };
+            return out;
+        }
+    }
+    // ── Read ─────────────────────────────────────────────────────────
+    read(meta, urls) {
+        return dispatchRead(urls, STORE_NAME, {
+            read: (p) => this._readOne(meta, p.uri),
+            ls: (p) => this._ls(meta, p),
+            count: (p) => this._count(meta, p),
+        });
+    }
+    async delete(meta, uris) {
+        if (uris.length === 0)
+            return [];
+        try {
+            await this.executor.transaction(async (tx) => {
+                for (const uri of uris) {
+                    await tx.query(`DELETE FROM ${meta.tableName} WHERE uri = $1`, [uri]);
+                }
+            });
+            return uris.map(() => ({ success: true }));
+        }
+        catch (err) {
+            const failure = storageFailure(err, "Delete failed");
+            return uris.map(() => ({ success: false, ...failure }));
+        }
+    }
+    async status() {
+        try {
+            await this.executor.query("SELECT 1");
+            return {
+                status: "healthy",
+                message: "PostgreSQL store is operational",
+                fns: ["read", "ls", "count"],
+                details: { tablePrefix: this.tablePrefix },
+            };
+        }
+        catch (error) {
+            return {
+                status: "unhealthy",
+                message: `PostgreSQL health check failed: ${error instanceof Error ? error.message : String(error)}`,
+                fns: ["read", "ls", "count"],
+            };
+        }
+    }
+    capabilities() {
+        return { atomicBatch: true };
+    }
+    // ── Internals ────────────────────────────────────────────────────
+    async _readOne(meta, uri) {
+        if (meta.columns.length === 0) {
+            // Empty schema: presence-only — return an empty record on hit.
+            const res = await this.executor.query(`SELECT 1 FROM ${meta.tableName} WHERE uri = $1`, [uri]);
+            return res.rows && res.rows.length > 0 ? {} : undefined;
+        }
+        const cols = meta.columns.map((c) => `"${c.name}"`).join(", ");
+        const res = await this.executor.query(`SELECT ${cols} FROM ${meta.tableName} WHERE uri = $1`, [uri]);
+        if (!res.rows || res.rows.length === 0)
+            return undefined;
+        return adaptRowForRead(meta, res.rows[0]);
+    }
+    async _ls(meta, parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const { params } = parsed;
+        const format = params.format ?? "full";
+        const cols = meta.columns.length > 0
+            ? "uri, " + meta.columns.map((c) => `"${c.name}"`).join(", ")
+            : "uri";
+        const selectClause = format === "uris" ? "uri" : cols;
+        const order = params.sortBy === "uri"
+            ? ` ORDER BY uri ${params.sortOrder === "desc" ? "DESC" : "ASC"}`
+            : "";
+        let sql = `SELECT ${selectClause} FROM ${meta.tableName} WHERE uri LIKE $1 || '%' AND uri NOT LIKE $1 || '%/%'${order}`;
+        const args = [parsed.uri];
+        if (params.limit !== undefined) {
+            const page = params.page ?? 1;
+            args.push(params.limit, (page - 1) * params.limit);
+            sql += ` LIMIT $${args.length - 1} OFFSET $${args.length}`;
+        }
+        const res = await this.executor.query(sql, args);
+        const rows = (res.rows ?? []);
+        if (format === "uris")
+            return rows.map((r) => r.uri);
+        return rows.map((r) => [
+            r.uri,
+            adaptRowForRead(meta, r),
+        ]);
+    }
+    async _count(meta, parsed) {
+        if (parsed.params.pattern !== undefined) {
+            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+        }
+        const res = await this.executor.query(`SELECT COUNT(*)::int AS n FROM ${meta.tableName} WHERE uri LIKE $1 || '%' AND uri NOT LIKE $1 || '%/%'`, [parsed.uri]);
+        const row = res.rows?.[0];
+        return row?.n ?? 0;
+    }
+}
+/**
+ * Collect any `ReadableStream` values on `BYTEA` columns into
+ * `Uint8Array` and return a shallow-copied record. Runs before the
+ * write transaction so stream failures can't leave a half-applied
+ * commit. Non-stream values pass through verbatim.
+ */
+async function normaliseBytesFields(record, bytesColumns) {
+    if (bytesColumns.size === 0)
+        return record;
+    const out = { ...record };
+    for (const name of bytesColumns) {
+        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(`${STORE_NAME}: field '${name}' must be Uint8Array or ReadableStream, got ${typeof v}`);
+    }
+    return out;
+}
+/** Coerce a record field value into something the driver will accept. */
+function adaptForWrite(col, value) {
+    if (value === undefined || value === null)
+        return null;
+    if (col.sqlType === "JSONB") {
+        return typeof value === "string" ? value : JSON.stringify(value);
+    }
+    if (col.sqlType === "TIMESTAMPTZ") {
+        if (value instanceof Date)
+            return value.toISOString();
+        if (typeof value === "number")
+            return new Date(value).toISOString();
+        return value;
+    }
+    return value;
+}
+/** Reconstruct an EntityRecord from a Postgres row. */
+function adaptRowForRead(meta, row) {
+    const rec = {};
+    for (const col of meta.columns) {
+        const v = row[col.name];
+        if (v === null || v === undefined) {
+            rec[col.name] = undefined;
+            continue;
+        }
+        if (col.sqlType === "BYTEA")
+            rec[col.name] = rowToBytes(v);
+        else if (col.sqlType === "JSONB") {
+            rec[col.name] = typeof v === "string" ? JSON.parse(v) : v;
+        }
+        else if (col.sqlType === "TIMESTAMPTZ") {
+            rec[col.name] = v instanceof Date ? v : new Date(v);
+        }
+        else
+            rec[col.name] = v;
+    }
+    return rec;
+}

package/esm/read.d.ts

@@ -0,0 +1,40 @@
+/**
+ * In-process post-processing for `fn=ls` results.
+ *
+ * Stores that cannot push `sortBy`/`limit`/`page`/`format` down to
+ * their backend collect the raw `Output[]` rows under a prefix and
+ * pipe them through `applyReadParams`. Stores that CAN push these
+ * down (postgres, mongo, elasticsearch, s3) should skip this helper
+ * and handle the params in their query.
+ *
+ * Throws on unsupported params — programmer errors are not silent
+ * "misses." See project decisions in `project_core_upgrade.md`.
+ */
+import type { Output } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import type { ReadParams } from "./url.js";
+/**
+ * Validate standard ReadParams and throw on anything we cannot honor.
+ *
+ * Push-down stores (postgres, mongo, ES, S3) call this first, then
+ * translate the surviving params into their backend query language.
+ * Stores that post-process in memory call `applyReadParams` instead,
+ * which validates and applies in one go.
+ *
+ * Project-wide baseline: `pattern` and `cursor` are unsupported
+ * everywhere; `sortBy` only accepts `"uri"`; `format` only accepts
+ * `"full"` (default) or `"uris"`. Per-store relaxations should be
+ * added explicitly as features land.
+ */
+export declare function validateReadParams(params: ReadParams, storeName: string): void;
+/**
+ * Apply standard ReadParams to a list of rows.
+ *
+ * @param rows   raw `[uri, payload]` entries collected from the backend
+ * @param params parsed read params (from `parseUrl(...).params`)
+ * @param storeName label used in thrown error messages
+ *
+ * Returns `Output[]` when `format` is `"full"` (default) or `string[]`
+ * when `format` is `"uris"`.
+ */
+export declare function applyReadParams<T>(rows: Output<T>[], params: ReadParams, storeName: string): Output<T>[] | string[];
+//# sourceMappingURL=read.d.ts.map

package/esm/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kEAAkE,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,GAChB,IAAI,CAcN;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EACjB,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAkBxB"}