@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/sqlite/store.js

@@ -1,20 +1,71 @@
 /**
- * SqliteStore — SQLite implementation of Store.
+ * SqliteStore — SQLite implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. Pushes
- * fn=ls/fn=count down to SQL using the shallow-direct-leaves
- * predicate: `uri LIKE ? || '%' AND uri NOT LIKE ? || '%/%'`.
+ * 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 BLOB` column — no legacy
+ * special case.
  *
- * Uses an injected synchronous SqliteExecutor; results are wrapped in
- * Promise.resolve() to satisfy the async Store interface. `payload`
- * is a BLOB; the store does not inspect or transform its contents.
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it runs `planColumns` and returns
+ * a `SqliteEntityMeta` 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 `PRAGMA table_info`.
+ *
+ * Writes/reads/deletes consume the meta directly: no per-call cache
+ * gate. Operations against a not-yet-provisioned meta surface
+ * SQLite's natural failure 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.
+ *
+ * `fn=find` (v2 spec §3.5; foundation PR #82) reuses the same `_ls`
+ * SQL composition with a single branch: under `fn=find` the shallow
+ * safety predicate (`AND uri NOT LIKE prefix || '%/%'`) is DROPPED so
+ * the LIKE prefix walk crosses `/` and matches the whole subtree.
+ * The prefix bind is still a two-arg `[prefix, globToSqlLike(pattern)]`
+ * pair — never concatenated into the pattern body, so room/segment
+ * names containing literal `%`/`_` cannot break out of the parameter
+ * (LIKE-injection safety via `ESCAPE '\'`). `pushDownFind: true` is
+ * advertised so dispatch trusts the backend's deep walk.
+ *
+ * Writes are wrapped in a transaction (`capabilities.atomicBatch =
+ * true`). Stream-shaped values on `BLOB` columns are collected to
+ * `Uint8Array` *before* the transaction opens.
  */
-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 { globToSqlLike } from "../glob.js";
+import { TYPE_TAGS, } from "../entity.js";
+import { IDENTIFIER_PATTERN, isValidIdentifier } from "../identifiers.js";
+import { planColumns } from "./columns.js";
 const STORE_NAME = "SqliteStore";
+/**
+ * Escape the SQL `LIKE` metacharacters (`%`, `_`, `\`) in a literal
+ * prefix or substring so the value can be safely bound into a `LIKE ?`
+ * clause paired with `ESCAPE '\'`. Without this, a prefix carrying a
+ * literal `%` (URL-encoded byte segment) or `_` (snake_case segment)
+ * would expand to a SQL wildcard inside the bind value — a
+ * LIKE-injection that parameterisation alone does NOT block.
+ *
+ * Used by `_ls` and `_count` for every prefix bind so room/segment
+ * names containing `%`/`_` stay inert.
+ */
+function escapeSqlLike(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/%/g, "\\%")
+        .replace(/_/g, "\\_");
+}
 function rowToBytes(value) {
     if (value instanceof Uint8Array)
         return value;
@@ -22,129 +73,168 @@ function rowToBytes(value) {
         return new Uint8Array(value);
     if (Array.isArray(value))
         return new Uint8Array(value);
-    throw new Error(`SqliteStore: unexpected payload type ${typeof value}`);
+    throw new Error(`${STORE_NAME}: unexpected payload type ${typeof value}`);
+}
+function entityTableName(tablePrefix, entityName) {
+    if (!isValidIdentifier(entityName)) {
+        throw new Error(`${STORE_NAME}: entity name '${entityName}' must match ${IDENTIFIER_PATTERN.source}`);
+    }
+    return `${tablePrefix}_${entityName}_data`;
 }
 export class SqliteStore {
-    tableName;
+    tablePrefix;
     executor;
-    // Names of entities provisioned on this store. SqliteStore currently
-    // routes only BYTES_ENTITY, so this is at most `{"bytes"}` — but the
-    // tracking shape matches MemoryStore so `status().schema` reads the
-    // same way across backends.
-    provisioned = new Set();
     constructor(tablePrefix, executor) {
         if (!tablePrefix)
             throw new Error("tablePrefix is required");
+        if (!isValidIdentifier(tablePrefix)) {
+            throw new Error(`tablePrefix must match ${IDENTIFIER_PATTERN.source}; got '${tablePrefix}'`);
+        }
         if (!executor)
             throw new Error("executor is required");
-        this.tableName = `${tablePrefix}_data`;
+        this.tablePrefix = tablePrefix;
         this.executor = executor;
     }
-    // ── EntityStore surface ──────────────────────────────────────────
+    // ── Lifecycle ────────────────────────────────────────────────────
     entitySupport(schema) {
-        return bytesOnlyEntitySupport(schema);
-    }
-    entityStatus(meta) {
-        return Promise.resolve(meta.isBytes ? "live" : "unprovisioned");
-    }
-    provisionEntity(meta) {
-        // Only BYTES_ENTITY is honored at the storage layer; record the
-        // name so `status()` surfaces what callers can actually use.
-        // Non-bytes schemas are silently ignored — `write`/`read` already
-        // surface "Unsupported schema" via the shim.
-        if (meta.isBytes)
-            this.provisioned.add(meta.schema.name);
-        return Promise.resolve();
+        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 === "BLOB").map((c) => c.name)),
+        };
     }
-    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));
+    // deno-lint-ignore require-await
+    async entityStatus(meta) {
+        const info = this.executor.query(`PRAGMA table_info("${meta.tableName}")`);
+        const rows = (info.rows ?? []);
+        if (rows.length === 0)
+            return "unprovisioned";
+        const actual = new Map(rows.map((r) => [r.name, (r.type ?? "").toUpperCase()]));
+        for (const c of meta.columns) {
+            const got = actual.get(c.name);
+            if (got === undefined)
+                return "unprovisioned";
+            if (got !== c.sqlType)
+                return "unprovisioned";
+        }
+        // Reject collisions in the other direction: extra user columns
+        // present in the live table that the meta doesn't declare are 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";
     }
-    delete(meta, uris) {
-        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    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 TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS "idx_${meta.tableName}_uri" ON "${meta.tableName}" (uri);`;
+        // SQLite drivers vary on whether `query` accepts multi-statement
+        // SQL; split and run each.
+        for (const stmt of sql.split(";").map((s) => s.trim()).filter(Boolean)) {
+            this.executor.query(stmt);
+        }
+        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}'`);
+        }
     }
-    // ── Byte ops (BYTES_ENTITY routing) ──────────────────────────────
-    async _writeBytes(entries) {
+    // ── Write ────────────────────────────────────────────────────────
+    async write(meta, entries) {
         if (entries.length === 0)
             return [];
-        // Collect streams up front: the executor is synchronous (BLOB
-        // wants bytes), and we don't want to await mid-transaction.
-        const prepared = await Promise.all(entries.map(async (e) => ({
-            uri: e.uri,
-            bytes: await toBytes(e.payload),
-        })));
-        // `capabilities.atomicBatch` is true: the whole batch commits or
-        // nothing does. On failure every result is `{ success: false }`
-        // with the same root-cause error.
+        const out = new Array(entries.length);
+        const accepted = [];
+        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(() => "?").join(", ");
+        const updates = cols
+            .map((c) => `"${c.name}" = excluded."${c.name}"`)
+            .concat(["updated_at = datetime('now')"])
+            .join(", ");
         try {
             this.executor.transaction((tx) => {
-                for (const entry of prepared) {
-                    tx.query(`INSERT INTO ${this.tableName} (uri, payload, updated_at)
-             VALUES (?, ?, datetime('now'))
-             ON CONFLICT(uri) DO UPDATE SET
-               payload = excluded.payload,
-               updated_at = datetime('now')`, [entry.uri, entry.bytes]);
+                for (const { uri, record } of accepted) {
+                    const args = [uri];
+                    for (const c of cols)
+                        args.push(adaptForWrite(c, record[c.name]));
+                    tx.query(`INSERT INTO "${meta.tableName}" (uri${colList ? ", " + colList : ""}) VALUES (?${placeholders ? ", " + placeholders : ""})
+             ON CONFLICT(uri) DO UPDATE SET ${updates}`, args);
                 }
             });
-            return entries.map(() => ({ success: true }));
+            for (const { idx } of accepted)
+                out[idx] = { success: true };
+            return out;
         }
         catch (err) {
             const failure = storageFailure(err, "Write failed");
-            return entries.map(() => ({ success: false, ...failure }));
+            for (const { idx } of accepted)
+                out[idx] = { success: false, ...failure };
+            return out;
         }
     }
-    _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) => Promise.resolve(this._readOne(meta, p.uri)),
+            ls: (p) => Promise.resolve(this._ls(meta, p, false)),
+            find: (p) => Promise.resolve(this._ls(meta, p, true)),
+            count: (p) => Promise.resolve(this._count(meta, p)),
+            pushDownPattern: true,
+            pushDownCursor: true,
+            pushDownSortBy: true,
+            pushDownFind: true,
         });
     }
-    _readOne(uri) {
-        const result = this.executor.query(`SELECT payload FROM ${this.tableName} WHERE uri = ?`, [uri]);
-        if (!result.rows.length)
-            return undefined;
-        return rowToBytes(result.rows[0].payload);
-    }
-    _ls(parsed) {
-        validateReadParams(parsed.params, STORE_NAME);
-        const { params } = parsed;
-        const format = params.format ?? "full";
-        const select = format === "uris" ? "uri" : "uri, payload";
-        const order = params.sortBy === "uri"
-            ? ` ORDER BY uri ${params.sortOrder === "desc" ? "DESC" : "ASC"}`
-            : "";
-        let sql = `SELECT ${select} FROM ${this.tableName} WHERE uri LIKE ? || '%' AND uri NOT LIKE ? || '%/%'${order}`;
-        const args = [parsed.uri, parsed.uri];
-        if (params.limit !== undefined) {
-            const page = params.page ?? 1;
-            sql += ` LIMIT ? OFFSET ?`;
-            args.push(params.limit, (page - 1) * params.limit);
-        }
-        const result = this.executor.query(sql, args);
-        const rows = result.rows;
-        if (format === "uris")
-            return rows.map((r) => r.uri);
-        return rows.map((r) => [r.uri, rowToBytes(r.payload)]);
-    }
-    _count(parsed) {
-        if (parsed.params.pattern !== undefined) {
-            throw new Error(`${STORE_NAME}: pattern filter not supported`);
-        }
-        const result = this.executor.query(`SELECT COUNT(*) AS n FROM ${this.tableName} WHERE uri LIKE ? || '%' AND uri NOT LIKE ? || '%/%'`, [parsed.uri, parsed.uri]);
-        const row = result.rows[0];
-        return row?.n ?? 0;
-    }
-    _deleteBytes(uris) {
+    delete(meta, uris) {
         if (uris.length === 0)
             return Promise.resolve([]);
-        // Atomic batch: every uri either deletes together or not at all.
         try {
             this.executor.transaction((tx) => {
                 for (const uri of uris) {
-                    tx.query(`DELETE FROM ${this.tableName} WHERE uri = ?`, [uri]);
+                    tx.query(`DELETE FROM "${meta.tableName}" WHERE uri = ?`, [uri]);
                 }
             });
             return Promise.resolve(uris.map(() => ({ success: true })));
@@ -154,31 +244,245 @@ export class SqliteStore {
             return Promise.resolve(uris.map(() => ({ success: false, ...failure })));
         }
     }
-    // ── Status ───────────────────────────────────────────────────────
+    // ── Status / capabilities ────────────────────────────────────────
     status() {
         try {
             this.executor.query("SELECT 1");
             return Promise.resolve({
                 status: "healthy",
                 message: "SQLite store is operational",
-                schema: this.schemaUris(),
-                fns: ["read", "ls", "count"],
-                details: { tableName: this.tableName },
+                schema: this._listProvisionedEntities().map((n) => `entity:${n}`),
+                fns: ["read", "ls", "find", "count"],
+                details: { tablePrefix: this.tablePrefix },
             });
         }
         catch (error) {
             return Promise.resolve({
                 status: "unhealthy",
                 message: error instanceof Error ? error.message : String(error),
-                schema: this.schemaUris(),
-                fns: ["read", "ls", "count"],
+                schema: [],
+                fns: ["read", "ls", "find", "count"],
             });
         }
     }
-    schemaUris() {
-        return [...this.provisioned].map((name) => `entity:${name}`);
-    }
     capabilities() {
         return { atomicBatch: true };
     }
+    // ── Internals ────────────────────────────────────────────────────
+    _readOne(meta, uri) {
+        try {
+            if (meta.columns.length === 0) {
+                // Empty schema: presence-only — return an empty record on hit.
+                const res = this.executor.query(`SELECT 1 FROM "${meta.tableName}" WHERE uri = ?`, [uri]);
+                return res.rows && res.rows.length > 0 ? {} : undefined;
+            }
+            const cols = meta.columns.map((c) => `"${c.name}"`).join(", ");
+            const res = this.executor.query(`SELECT ${cols} FROM "${meta.tableName}" WHERE uri = ?`, [uri]);
+            if (!res.rows || res.rows.length === 0)
+                return undefined;
+            return adaptRowForRead(meta, res.rows[0]);
+        }
+        catch {
+            // `no such table` and other natural read failures surface as
+            // misses — matches the convention that unprovisioned entities
+            // read empty rather than throwing.
+            return undefined;
+        }
+    }
+    _ls(meta, parsed, deep) {
+        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;
+        // sortBy: "uri" sorts on the implicit URI column; any other value
+        // must be a declared user field (validated against meta.declared
+        // to keep the column name out of arbitrary user input).
+        const sortByCol = params.sortBy === "uri"
+            ? "uri"
+            : (params.sortBy !== undefined && meta.declared.has(params.sortBy)
+                ? `"${params.sortBy}"`
+                : "");
+        const order = sortByCol
+            ? ` ORDER BY ${sortByCol} ${params.sortOrder === "desc" ? "DESC" : "ASC"}`
+            : "";
+        // Base prefix predicate. Under `fn=ls` (deep=false) the
+        // shallow-direct-leaves safety predicate `AND uri NOT LIKE
+        // prefix||'%/%'` is layered on top so the listing stops at depth-1.
+        // Under `fn=find` (deep=true) that predicate is dropped — find's
+        // entire purpose is to cross `/` and walk the subtree.
+        //
+        // LIKE-injection safety: SQLite parameterisation prevents SQL
+        // injection but the `%`/`_` characters carried in the bind VALUE
+        // are still treated as wildcards by LIKE. Room and segment names
+        // routinely include `%` (URL-encoded bytes) or `_` (snake_case),
+        // so we ESCAPE the prefix bind with `\` and pair every LIKE clause
+        // with `ESCAPE '\'`. Without the escape, a prefix
+        // `store://r/100%/` would match `store://r/100x/...` too. The
+        // pattern body is also escaped (by `globToSqlLike`) and uses the
+        // same `ESCAPE '\'`.
+        const prefixLike = escapeSqlLike(parsed.uri);
+        let sql = `SELECT ${selectClause} FROM "${meta.tableName}" WHERE uri LIKE ? || '%' ESCAPE '\\'`;
+        const args = [prefixLike];
+        if (!deep) {
+            sql += ` AND uri NOT LIKE ? || '%/%' ESCAPE '\\'`;
+            args.push(prefixLike);
+        }
+        if (params.pattern !== undefined) {
+            args.push(prefixLike, globToSqlLike(params.pattern));
+            sql += ` AND uri LIKE ? || ? ESCAPE '\\'`;
+        }
+        if (params.cursor !== undefined) {
+            args.push(params.cursor);
+            const op = params.sortOrder === "desc" ? "<" : ">";
+            sql += ` AND uri ${op} ?`;
+        }
+        sql += order;
+        if (params.limit !== undefined) {
+            const page = params.page ?? 1;
+            sql += ` LIMIT ? OFFSET ?`;
+            args.push(params.limit, (page - 1) * params.limit);
+        }
+        try {
+            const res = 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),
+            ]);
+        }
+        catch {
+            return format === "uris" ? [] : [];
+        }
+    }
+    _count(meta, parsed) {
+        // Same LIKE-injection treatment as `_ls`: escape the prefix bind
+        // and pair every LIKE with `ESCAPE '\'` so literal `%`/`_` in
+        // room/segment names stay inert.
+        const prefixLike = escapeSqlLike(parsed.uri);
+        let sql = `SELECT COUNT(*) AS n FROM "${meta.tableName}" WHERE uri LIKE ? || '%' ESCAPE '\\' AND uri NOT LIKE ? || '%/%' ESCAPE '\\'`;
+        const args = [prefixLike, prefixLike];
+        if (parsed.params.pattern !== undefined) {
+            args.push(prefixLike, globToSqlLike(parsed.params.pattern));
+            sql += ` AND uri LIKE ? || ? ESCAPE '\\'`;
+        }
+        if (parsed.params.cursor !== undefined) {
+            args.push(parsed.params.cursor);
+            const op = parsed.params.sortOrder === "desc" ? "<" : ">";
+            sql += ` AND uri ${op} ?`;
+        }
+        try {
+            const res = this.executor.query(sql, args);
+            const row = res.rows?.[0];
+            return row?.n ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Enumerate every `{tablePrefix}_*_data` table currently in the
+     * database. Used by `status()` to advertise the entities a peer can
+     * talk to without per-entity bookkeeping.
+     */
+    _listProvisionedEntities() {
+        const res = this.executor.query(`SELECT name FROM sqlite_master WHERE type='table' AND name LIKE ? || '\\_%\\_data' ESCAPE '\\'`, [this.tablePrefix]);
+        const out = [];
+        for (const row of res.rows ?? []) {
+            const name = row.name;
+            const suffix = "_data";
+            const prefixWithU = `${this.tablePrefix}_`;
+            if (!name.startsWith(prefixWithU) || !name.endsWith(suffix))
+                continue;
+            out.push(name.slice(prefixWithU.length, name.length - suffix.length));
+        }
+        return out;
+    }
+}
+// ── Adapters ────────────────────────────────────────────────────────
+/**
+ * Collect any `ReadableStream` values on `BLOB` 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 SQLite driver will accept. */
+function adaptForWrite(col, value) {
+    if (value === undefined || value === null)
+        return null;
+    if (col.tag === TYPE_TAGS.JSON) {
+        return typeof value === "string" ? value : JSON.stringify(value);
+    }
+    if (col.tag === TYPE_TAGS.TIMESTAMP) {
+        if (value instanceof Date)
+            return value.toISOString();
+        if (typeof value === "number")
+            return new Date(value).toISOString();
+        return String(value);
+    }
+    if (col.tag === TYPE_TAGS.BOOLEAN) {
+        return value ? 1 : 0;
+    }
+    if (col.tag === TYPE_TAGS.BIGINT) {
+        // The injected sqlite executor may pass `bigint` through (e.g.
+        // `@db/sqlite`) or require `number` (e.g. the structurally-typed
+        // mock). Hand the value over unchanged for compatible drivers;
+        // numbers within safe range pass too.
+        return value;
+    }
+    return value;
+}
+/** Reconstruct an EntityRecord from a SQLite 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.tag === TYPE_TAGS.BYTES) {
+            rec[col.name] = rowToBytes(v);
+        }
+        else if (col.tag === TYPE_TAGS.JSON) {
+            rec[col.name] = typeof v === "string" ? JSON.parse(v) : v;
+        }
+        else if (col.tag === TYPE_TAGS.TIMESTAMP) {
+            rec[col.name] = v instanceof Date ? v : new Date(v);
+        }
+        else if (col.tag === TYPE_TAGS.BOOLEAN) {
+            rec[col.name] = Boolean(v);
+        }
+        else if (col.tag === TYPE_TAGS.BIGINT) {
+            // SQLite returns INTEGER as either JS `number` or `bigint`
+            // depending on the driver. Normalise to `bigint` so callers
+            // get a consistent shape regardless of the underlying driver.
+            rec[col.name] = typeof v === "bigint" ? v : BigInt(v);
+        }
+        else
+            rec[col.name] = v;
+    }
+    return rec;
 }

package/esm/types.d.ts

@@ -18,7 +18,7 @@
  * Cross-cutting types (`Output`, `ProtocolInterfaceNode`,
  * `DeleteResult`, `StatusResult`) still come from b3nd-core.
  */
-import type { B3ndError, DeleteResult, Output, StatusResult } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import type { B3ndError, DeleteResult, Output, StatusResult } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/src/types/types.js";
 /**
  * Payload type accepted by `write` and produced by `read`.
  *