litedbmodel 2.0.1 → 2.1.0

package/dist/scp/makesql/outtype.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — codegen `outType` derivation (spec §4.1; issues #58/#56).
+ *
+ * bc's TYPED-RAW de-box emitters (`rust-typed-raw` / `go-typed-raw` / `typescript-typed`) require
+ * each read node to carry an `outType` and the component an `outputType` (bc portable type
+ * notation). WITHOUT them the emitter hard-fails ("nothing to de-box") — the correct fail-closed
+ * behavior. This module derives those annotations for a READ component from:
+ *
+ *   1. the per-node SELECT projection (`table` + `select` ports) → a row `obj` type, each column's
+ *      bc scalar resolved from its SQL type (the schema/DDL SoT) via {@link sqlTypeToBcScalar};
+ *   2. the node cardinality (a Select node returns a row LIST → `{arr:rowObj}`; a Count → `int`; a
+ *      `.map` node wraps its per-element handler result → `{arr:<elem>}`);
+ *   3. the component `output` Φ-expression, walked to compose the `outputType` from the node types
+ *      (`{ref:[nodeId]}` → that node's outType; `{obj:{…}}`/`{arr:…}`/`{opt:…}` recurse).
+ *
+ * Spec §4.1 discipline: an ambiguous/unmappable projection is a HARD ERROR (no-assume,
+ * no-fallback) — a `*` projection, a computed/aliased column, or a column with no schema type
+ * THROWS. It is NEVER degraded to a boxed/untyped output; that would silently defeat the de-box.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseProjectionColumn = parseProjectionColumn;
+exports.nodeOutType = nodeOutType;
+exports.crudNodeAsType = crudNodeAsType;
+exports.deriveReadOutTypes = deriveReadOutTypes;
+const coltype_1 = require("../coltype");
+const tx_1 = require("./tx");
+/**
+ * Narrow a {@link BcScalar} to a bc {@link PortableScalarType}. `BcScalar`'s members
+ * (`string|int|float|bool|null`) are exactly bc 0.3.0's portable scalar notation, so this is an
+ * identity narrow. DATE/TIMESTAMP columns map to `string` at the `sqlTypeToBcScalar` layer (spec
+ * §4.1 owner decision; bc has no `date` scalar — behavior-contracts#84 deferred), so no `date`
+ * scalar ever reaches here.
+ */
+function toPortableScalar(scalar, _table, _column) {
+    return scalar;
+}
+function isMap(n) {
+    return 'map' in n;
+}
+/** The `{component, ports}` of a body node (unwrapping a `.map`). */
+function nodeRef(n) {
+    return isMap(n) ? { component: n.map.component, ports: n.map.ports } : { component: n.component, ports: n.ports };
+}
+function opKey(node) {
+    if (node === null || typeof node !== 'object' || Array.isArray(node))
+        return undefined;
+    const keys = Object.keys(node);
+    return keys.length === 1 ? keys[0] : undefined;
+}
+/** Read a required literal string port, or throw (the projection SoT must be a literal in the IR). */
+function stringPort(ports, name) {
+    const v = ports[name];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'string') {
+        throw new Error(`outtype: port '${name}' must be a literal string in the IR (got ${JSON.stringify(v)})`);
+    }
+    return v;
+}
+/** Read a literal `{arr:[str,…]}` string-list port (the SELECT projection). */
+function stringArrayPort(ports, name) {
+    const v = ports[name];
+    if (v === undefined)
+        return undefined;
+    if (typeof v === 'object' && v !== null && 'arr' in v && Array.isArray(v.arr)) {
+        return v.arr.map((e) => {
+            if (typeof e !== 'string')
+                throw new Error(`outtype: '${name}' entries must be literal strings (got ${JSON.stringify(e)})`);
+            return e;
+        });
+    }
+    throw new Error(`outtype: port '${name}' must be an {arr:[…]} literal in the IR (got ${JSON.stringify(v)})`);
+}
+/**
+ * The SINGLE projection-column parser (issue #59) — shared by BOTH the codegen `outType` derivation
+ * and the TS read-path materializer derivation so the two CANNOT diverge (the recurring source of
+ * silent-rounding leaks). Classifies ONE `select`-list entry:
+ *   - bare `col`                        → `{ kind:'column', underlying:'col', outputKey:'col' }`.
+ *   - qualified `t.col`                 → strip qualifier → `underlying:'col', outputKey:'col'`.
+ *   - aliased `col AS b` / `t.col AS b` → `underlying:'col', outputKey:'b'` (the driver row key).
+ *   - computed `COUNT(*)`, `NOW()`, `x::uuid`, `x+1`, aliased or not → `{ kind:'computed', text }`.
+ *   - `*` / `t.*`                       → HARD ERROR (the concrete column list is unknown).
+ * A SCHEMA-column entry MUST be typed against the declaration (a caller resolves + fail-closes on an
+ * undeclared column → never a silent rounded-i64 leak). A COMPUTED entry has no schema column to
+ * round: the read path leaves it raw; the codegen path (which needs every struct field typed) rejects
+ * it. This ONE parser guarantees every shape is classified identically for both paths.
+ */
+function parseProjectionColumn(col, table, at) {
+    const raw = col.trim();
+    if (raw === '*' || raw.endsWith('.*')) {
+        throw new Error(`outtype: ${at}: SELECT on '${table}' projects '${raw}' (a wildcard). A typed de-box needs the ` +
+            `concrete column list to build the row struct + type each column — spec §4.1 is column-typed. ` +
+            `Project explicit columns (no-assume, no-fallback).`);
+    }
+    // Split off an `AS <alias>` (case-insensitive; alias must be a bare identifier).
+    let expr = raw;
+    let alias;
+    const asMatch = /^(.*?)\s+AS\s+([A-Za-z_][A-Za-z0-9_]*)$/i.exec(raw);
+    if (asMatch !== null) {
+        expr = asMatch[1].trim();
+        alias = asMatch[2];
+    }
+    // A bare or qualified column reference — `col` or `qual.col` (identifiers only) — is a SCHEMA
+    // column. The qualifier (if present) names the column's OWNER table (a JOIN column), against which
+    // its type resolves; without a qualifier the column belongs to the node's base table.
+    const refMatch = /^(?:([A-Za-z_][A-Za-z0-9_]*)\.)?([A-Za-z_][A-Za-z0-9_]*)$/.exec(expr);
+    if (refMatch !== null) {
+        const qualifier = refMatch[1];
+        const underlying = refMatch[2];
+        return { kind: 'column', underlying, outputKey: alias ?? underlying, ...(qualifier !== undefined ? { qualifier } : {}) };
+    }
+    // Anything else (a function call `f(x)`, an aggregate `COUNT(*)`, a cast `x::uuid`, arithmetic, a
+    // literal) is a COMPUTED expression — no underlying schema column, so it cannot round an i64. The
+    // read path leaves it raw; the codegen path rejects it (it needs a concrete field type).
+    return { kind: 'computed', text: raw };
+}
+/**
+ * The row `obj` type of a SELECT projection: `{obj:{outputKey: <bcScalar>, …}}`. Each column is
+ * resolved ONCE via the SHARED {@link parseProjectionColumn} (bare / qualified / aliased) and its SQL
+ * type (from the schema SoT) yields BOTH the bc scalar (this outType, for codegen) AND — written into
+ * the `materializers` accumulator — the TS read-path {@link MaterializeClass} (INT32/INT64/date/bool).
+ * This is the SINGLE column-type resolution the whole read pipeline consumes: codegen reads the
+ * `obj`; the runtime read path reads `materializers`. They cannot diverge — they are two projections
+ * of the ONE resolution. A `*` / absent projection, a computed column, a duplicate OUTPUT key, or an
+ * undeclared underlying column is a HARD ERROR (no-assume, no-fallback) — for BOTH consumers.
+ */
+function rowObjType(table, projection, resolveColumnType, at, materializers) {
+    if (projection === undefined || projection.length === 0) {
+        throw new Error(`outtype: ${at}: SELECT on '${table}' has no explicit column projection ('*' / empty). A typed ` +
+            `de-box needs the concrete column list to build the row struct — spec §4.1 is column-typed. ` +
+            `Project explicit columns (no-assume, no-fallback).`);
+    }
+    const obj = {};
+    for (const col of projection) {
+        const entry = parseProjectionColumn(col, table, at);
+        // A computed expression has no concrete struct field type — HARD ERROR (spec §4.1 no-assume).
+        // The read path never reaches a separate lenient pass now; `*`/computed fail here for BOTH.
+        if (entry.kind === 'computed') {
+            throw new Error(`outtype: ${at}: projected expression '${entry.text}' on '${table}' is computed (function / ` +
+                `aggregate / cast / literal) and cannot be typed into a concrete row struct field. Typed ` +
+                `de-box (spec §4.1) requires bare/qualified/aliased schema columns. No-assume, no-fallback.`);
+        }
+        const { underlying, outputKey, qualifier } = entry;
+        if (outputKey in obj)
+            throw new Error(`outtype: ${at}: duplicate projected column key '${outputKey}' on '${table}'`);
+        // Resolve against the qualifier's table (a JOIN column) if present, else the node's base table.
+        const owner = qualifier ?? table;
+        // ONE resolution of the SQL type → both the bc scalar AND the materialize class. resolveColumnType
+        // throws on an undeclared column, sqlType* throw on an unknown SQL type — fail-closed by
+        // construction on the UNDERLYING column, keyed by the OUTPUT column (the driver's row key).
+        const sqlType = resolveColumnType(owner, underlying);
+        obj[outputKey] = toPortableScalar((0, coltype_1.sqlTypeToBcScalar)(sqlType), owner, underlying);
+        const klass = (0, coltype_1.sqlTypeToMaterializeClass)(sqlType);
+        if (klass !== 'passthrough')
+            materializers[outputKey] = klass; // omit passthrough (no-op coercion)
+    }
+    return { obj };
+}
+/**
+ * The outType + read-path materializers of ONE read body node — derived from the SINGLE column-type
+ * resolution ({@link rowObjType}). A `Select` returns a ROW LIST → `{arr:rowObj}`; a `Count` a single
+ * `int` (a scalar, no per-column map). A `.map` node wraps its per-element Select result. An
+ * unrecognized component throws (typed read de-box covers only the SQL read catalog).
+ */
+function nodeTypes(node, resolveColumnType) {
+    const { component, ports } = nodeRef(node);
+    const at = `node '${node.id}'`;
+    if (component === 'Count')
+        return { outType: 'int', materializers: {} };
+    if (component === 'Select') {
+        const table = stringPort(ports, 'table');
+        if (table === undefined)
+            throw new Error(`outtype: ${at}: Select node requires a literal 'table' port`);
+        const projection = stringArrayPort(ports, 'select');
+        const materializers = {};
+        const row = rowObjType(table, projection, resolveColumnType, at, materializers);
+        // A `.map` node iterates a list and invokes the inner component per element (row LIST per element
+        // → `{arr:{arr:rowObj}}`); a plain Select node returns the row list `{arr:rowObj}`.
+        const outType = isMap(node) ? { arr: { arr: row } } : { arr: row };
+        return { outType, materializers };
+    }
+    throw new Error(`outtype: ${at}: component '${component}' has no typed outType (typed read de-box covers Select/Count only). ` +
+        `A write / unknown node cannot be de-boxed here — no-assume, no-fallback.`);
+}
+/** The outType of ONE read body node (thin wrapper over {@link nodeTypes} for external callers). */
+function nodeOutType(node, resolveColumnType) {
+    return nodeTypes(node, resolveColumnType).outType;
+}
+/**
+ * Derive the component `outputType` by walking the `output` Φ-expression against a `nodeId →
+ * outType` map. `{ref:[id]}` resolves to that node's outType; `{obj:{k:expr,…}}` /
+ * `{arr:expr}` / `{opt:expr}` recurse structurally. A `ref` to an unknown id, or an operator the
+ * typed output path does not cover, is a HARD ERROR (no-assume, no-fallback) — the output must be
+ * a pure composition of typed node results, never a boxed dynamic tree.
+ */
+function outputType(output, byNode, at) {
+    const op = opKey(output);
+    if (op === 'ref' || op === 'refOpt') {
+        const path = output[op];
+        if (!Array.isArray(path) || path.length === 0 || typeof path[0] !== 'string') {
+            throw new Error(`outtype: ${at}: a '${op}' output must reference a node id`);
+        }
+        // A node-result ref is a single-segment path `[nodeId]`. A deeper path (field access on a node
+        // result) cannot be typed here without walking into the row struct — out of the bench's scope.
+        if (path.length !== 1 || path[0].startsWith('$') || path[0] === tx_1.IN_SENTINEL) {
+            throw new Error(`outtype: ${at}: output ref path ${JSON.stringify(path)} is not a bare node-result reference; ` +
+                `field access / input refs at the output position are not supported by the typed de-box path. No-assume, no-fallback.`);
+        }
+        const t = byNode.get(path[0]);
+        if (t === undefined)
+            throw new Error(`outtype: ${at}: output references node '${path[0]}' which has no derived outType`);
+        return t;
+    }
+    if (op === 'obj') {
+        const obj = output.obj;
+        if (obj === null || typeof obj !== 'object' || Array.isArray(obj))
+            throw new Error(`outtype: ${at}: 'obj' output must be a record`);
+        const out = {};
+        for (const [k, expr] of Object.entries(obj)) {
+            if (k === '__proto__')
+                throw new Error(`outtype: ${at}: '__proto__' key forbidden in output obj`);
+            out[k] = outputType(expr, byNode, `${at}.obj.${k}`);
+        }
+        return { obj: out };
+    }
+    if (op === 'arr') {
+        const arr = output.arr;
+        // An `{arr:<expr>}` output whose single element expr types the element (the typed corpus uses
+        // homogeneous arrays). An `{arr:[…]}` literal list is not a typed homogeneous array here.
+        if (Array.isArray(arr))
+            throw new Error(`outtype: ${at}: an '{arr:[…]}' literal list output cannot be typed as a homogeneous array. No-assume, no-fallback.`);
+        return { arr: outputType(arr, byNode, `${at}.arr`) };
+    }
+    if (op === 'opt') {
+        const inner = output.opt;
+        return { opt: outputType(inner, byNode, `${at}.opt`) };
+    }
+    throw new Error(`outtype: ${at}: output expression ${JSON.stringify(output)} is not a typed composition ` +
+        `(ref / obj / arr / opt of node results). The typed de-box path does not build a dynamic ` +
+        `Value output tree — no-assume, no-fallback.`);
+}
+/**
+ * PRE-COMPILE node-output type (bc 0.8.0 SA5 / #12): the determined `PortableType` a litedbmodel CRUD
+ * leaf annotates its authored node with, via bc's `.as(t)` recording API, so `compileBehaviors`'
+ * all-nodes-typed gate (`UNTYPED_NODE`) passes. Computed from the RAW authored ports (a plain `table`
+ * string + a plain `select` / `returning` column list — the same projection SoT `deriveReadOutTypes`
+ * reads post-compile, just moved to authoring time) + the model's inline `static columns` resolver.
+ *
+ *  - `Select` → the row LIST `{arr:{obj:{outKey:<scalar>,…}}}` from the `select` projection. This is
+ *    the value `.as` takes in BOTH positions: a top-level Select node's `outType` is this list; a
+ *    mapped Select's `.as` records it as the map ELEMENT type (bc convention — the per-parent row list).
+ *  - `Count` → NOT handled here: its output is the static `int` catalog `elemType` (no `.as`).
+ *  - `Insert`/`Update`/`Delete` → the RETURNING row list `{arr:{obj:…}}` from the `returning` port
+ *    (bare-column list). No `returning` → an EMPTY row list `{arr:{obj:{}}}` (the write surfaces rows
+ *    only via RETURNING; a no-RETURNING write yields empty rows — mirrors `writeouttype.ts`).
+ *
+ * Schema columns are parsed by the SAME {@link parseProjectionColumn} the read/codegen paths use and
+ * typed via the resolver (an undeclared column fails closed here at authoring — earlier than the
+ * post-compile derivation). A COMPUTED projected column (`COUNT(*) as n`, a cast, a literal) is OMITTED
+ * from the typed row struct — the read path leaves a computed column RAW (#59: "the read path leaves it
+ * raw; the codegen path rejects it"), so its field is absent from the de-box row type. This keeps the
+ * node's outType DETERMINED (gate passes) while preserving #59's raw-computed read behavior; the typed
+ * codegen path independently rejects a computed projection later (it needs every field typed). The
+ * value is the OUTPUT-row type only; SQL stays opaque text on the makeSQL leaf (types the node OUTPUT,
+ * never the SQL).
+ */
+function crudNodeAsType(component, ports, resolveColumnType, at) {
+    const table = ports['table'];
+    if (typeof table !== 'string') {
+        throw new Error(`outtype: ${at}: ${component} node requires a literal 'table' string port to type its output (got ${JSON.stringify(table)})`);
+    }
+    if (component === 'Select') {
+        const select = ports['select'];
+        if (!Array.isArray(select) || select.length === 0) {
+            throw new Error(`outtype: ${at}: Select has no explicit column projection ('*' / empty). A typed de-box needs the ` +
+                `concrete column list to build the row struct — spec §4.1 is column-typed. Project explicit columns.`);
+        }
+        const obj = {};
+        for (const raw of select) {
+            if (typeof raw !== 'string')
+                throw new Error(`outtype: ${at}: Select 'select' entries must be literal strings (got ${JSON.stringify(raw)})`);
+            const parsed = parseProjectionColumn(raw, table, at);
+            if (parsed.kind === 'computed')
+                continue; // computed column: read raw, omitted from the typed row (SA5-determined without it)
+            const { underlying, outputKey, qualifier } = parsed;
+            if (outputKey in obj)
+                throw new Error(`outtype: ${at}: duplicate projected column key '${outputKey}' on '${table}'`);
+            obj[outputKey] = toPortableScalar((0, coltype_1.sqlTypeToBcScalar)(resolveColumnType(qualifier ?? table, underlying)), qualifier ?? table, underlying);
+        }
+        return { arr: { obj } };
+    }
+    if (component === 'Insert' || component === 'Update' || component === 'Delete') {
+        // The RETURNING port is a single comma-separated bare-column string (`'id, author_id'`) or absent.
+        const returning = ports['returning'];
+        if (returning === undefined)
+            return { arr: { obj: {} } };
+        if (typeof returning !== 'string') {
+            throw new Error(`outtype: ${at}: ${component} 'returning' port must be a literal string (got ${JSON.stringify(returning)})`);
+        }
+        const cols = returning.split(',').map((c) => c.trim()).filter((c) => c.length > 0);
+        if (cols.length === 0)
+            return { arr: { obj: {} } };
+        return { arr: rowObjType(table, cols, resolveColumnType, at, {}) };
+    }
+    throw new Error(`outtype: ${at}: no pre-compile output type for component '${component}' (typed CRUD covers Select/Insert/Update/Delete; Count is static via catalog elemType).`);
+}
+/**
+ * Per-node `outType` (keyed by body node id) + the component `outputType`, derived for a READ
+ * component (spec §4.1). `cond` nodes are skipped for the per-node map but a `cond` at the OUTPUT
+ * position (a shared-branch merge) would be handled by {@link outputType} if reached — the bench's
+ * read outputs are ref / obj compositions of Select nodes. Any ambiguity throws (fail-closed).
+ */
+function deriveReadOutTypes(component, resolveColumnType) {
+    const byNode = new Map();
+    const materializersByNode = new Map();
+    for (const n of component.body) {
+        if ('cond' in n)
+            continue; // a cond node carries no SELECT projection; it is typed by its branch
+        // ONE resolution per node → the outType (codegen) AND the read-path materializers (runtime).
+        const t = nodeTypes(n, resolveColumnType);
+        byNode.set(n.id, t.outType);
+        if (Object.keys(t.materializers).length > 0)
+            materializersByNode.set(n.id, t.materializers);
+    }
+    return { byNode, outputType: outputType(component.output, byNode, `component '${component.name}' output`), materializersByNode };
+}
+//# sourceMappingURL=outtype.js.map

package/dist/scp/makesql/outtype.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outtype.js","sourceRoot":"","sources":["../../../src/scp/makesql/outtype.ts"],"names":[],"mappings":"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"}

package/dist/scp/makesql/pool-executor.d.ts

@@ -17,6 +17,38 @@
  * force either into a consumer that only uses the sync better-sqlite3 conformance path.
  */
 import type { SqlExecutorAsync } from './static-bundle';
+/** The minimal `pg.types` surface: register a per-OID text parser. */
+export interface PgTypesLike {
+    setTypeParser(oid: number, parser: (value: string) => unknown): void;
+}
+/**
+ * Register `pg` type parsers so the read-path de-box (issue #59) gets coercible values: the
+ * DATE/TIMESTAMP/TIMESTAMPTZ/TIME family is returned as its NATIVE TEXTUAL string (NOT a JS Date),
+ * honoring the `date→string` outType and carrying the TZ for timestamptz. int8 already arrives as a
+ * string (pg default), so it needs no parser. Idempotent. Call ONCE, before building the pool, from
+ * the consumer that owns the `pg` module (`import { types } from 'pg'; configurePgDeboxTypeParsers(types)`).
+ *
+ * WHY the GLOBAL parser (a documented, deliberate exception): `pg`'s default DATE parser builds a JS
+ * `Date` at LOCAL midnight, which shifts the UTC CALENDAR DAY (e.g. `2026-07-14` → a Date whose UTC
+ * day is `2026-07-13`). That loss happens INSIDE the driver, BEFORE the materializer sees the value —
+ * so materializer-side coercion CANNOT recover the correct calendar day from the already-shifted
+ * Date. Reading the native text (this parser) is the only lossless option, and `pg` exposes type
+ * parsers only at module (process-global) scope. It is set ONCE at pool creation, not per read. The
+ * materializer's `Date → ISO string` path remains as a defensive fallback for any driver/config that
+ * still slips a Date through, but the correct-day guarantee for pg DATE comes from this parser.
+ */
+export declare function configurePgDeboxTypeParsers(types: PgTypesLike): void;
+/**
+ * The `mysql2` pool options the read-path de-box (issue #59) requires: `supportBigNumbers` +
+ * `bigNumberStrings` so BIGINT arrives as an EXACT string (→ bigint; a plain number would already
+ * have rounded it), and `dateStrings` so the DATE/TIMESTAMP/DATETIME family arrives as its native
+ * textual string (→ the `date→string` outType, NOT a JS Date). Spread into `mysql.createPool(...)`.
+ */
+export declare const mysqlDeboxPoolOptions: {
+    readonly supportBigNumbers: true;
+    readonly bigNumberStrings: true;
+    readonly dateStrings: true;
+};
 /** The minimal `pg.Pool` surface we need: `query(text, values)` resolving `{ rows }`. */
 export interface PgPoolLike {
     query(text: string, values?: unknown[]): Promise<{
@@ -43,5 +75,43 @@ export declare function pgPoolExecutor(pool: PgPoolLike): SqlExecutorAsync;
  *
  * Recommend `connectionLimit` ≥ the plan's `concurrency` (default 16).
  */
+/** Minimal `pg` module surface: a `Pool` ctor + the global `types.setTypeParser`. */
+export interface PgModuleLike {
+    Pool: new (config: Record<string, unknown>) => PgPoolLike & {
+        end?: () => Promise<void>;
+    };
+    types: PgTypesLike;
+}
+/** Minimal `mysql2/promise` module surface: `createPool`. */
+export interface Mysql2ModuleLike {
+    createPool(config: Record<string, unknown>): MysqlPoolLike & {
+        end?: () => Promise<void>;
+    };
+}
+/**
+ * Build a PG pool + executor with the read-path de-box wired IN (issue #59): registers the pg date
+ * type parsers (DATE/TIMESTAMP family → native textual string) globally, then builds the pool.
+ * int8 already arrives as a string on pg. Returns `{ pool, exec }` — pass `exec` to
+ * `executeBehaviorAsync`. This is the production async path's de-box-correct entry (no hand-spread
+ * options).
+ */
+export declare function pgDeboxExecutor(pg: PgModuleLike, config: Record<string, unknown>): {
+    pool: PgPoolLike & {
+        end?: () => Promise<void>;
+    };
+    exec: SqlExecutorAsync;
+};
+/**
+ * Build a MySQL pool + executor with the read-path de-box wired IN (issue #59): the pool carries
+ * {@link mysqlDeboxPoolOptions} (`supportBigNumbers + bigNumberStrings` so BIGINT → exact string,
+ * `dateStrings` so the date family → string) — options that MUST be set at pool construction (a
+ * rounded BIGINT cannot be un-rounded post-hoc). Returns `{ pool, exec }` for `executeBehaviorAsync`.
+ */
+export declare function mysqlDeboxExecutor(mysql2: Mysql2ModuleLike, config: Record<string, unknown>): {
+    pool: MysqlPoolLike & {
+        end?: () => Promise<void>;
+    };
+    exec: SqlExecutorAsync;
+};
 export declare function mysqlPoolExecutor(pool: MysqlPoolLike): SqlExecutorAsync;
 //# sourceMappingURL=pool-executor.d.ts.map

package/dist/scp/makesql/pool-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool-executor.d.ts","sourceRoot":"","sources":["../../../src/scp/makesql/pool-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CACvF;AAED,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;CACvF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,gBAAgB,CAKjE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,gBAAgB,CAKvE"}
+{"version":3,"file":"pool-executor.d.ts","sourceRoot":"","sources":["../../../src/scp/makesql/pool-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAkBxD,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;CACtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAOpE;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;CAIxB,CAAC;AAEX,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CACvF;AAED,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;CACvF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,gBAAgB,CAKjE;AAED;;;;;;GAMG;AAQH,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,UAAU,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAC1F,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;CAC5F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,UAAU,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAI/J;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,aAAa,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAG7K;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,gBAAgB,CAKvE"}

package/dist/scp/makesql/pool-executor.js

@@ -18,8 +18,61 @@
  * force either into a consumer that only uses the sync better-sqlite3 conformance path.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mysqlDeboxPoolOptions = void 0;
+exports.configurePgDeboxTypeParsers = configurePgDeboxTypeParsers;
 exports.pgPoolExecutor = pgPoolExecutor;
+exports.pgDeboxExecutor = pgDeboxExecutor;
+exports.mysqlDeboxExecutor = mysqlDeboxExecutor;
 exports.mysqlPoolExecutor = mysqlPoolExecutor;
+// ── TS read-path driver de-box config (issue #59) ─────────────────────────────
+// The read-path materializer (`materializeCell`) coerces each driver cell to the JS form its SQL
+// column type declares (BIGINT→bigint, DATE→string, …). For that to be LOSSLESS the driver must
+// hand the value over in a coercible form:
+//   - PG: int8 (OID 20) already arrives as a STRING; DATE/TIMESTAMP/TIMESTAMPTZ arrive as a JS
+//     Date by default (TZ-shifted). `configurePgDeboxTypeParsers` registers `pg` type parsers so
+//     the date family arrives as its NATIVE TEXTUAL form (carrying TZ for timestamptz) — the
+//     value-preserving string the materializer expects. This is a GLOBAL `pg` setting (pg has no
+//     per-pool parser), applied once by the consumer that owns the pg import.
+//   - MySQL: BIGINT arrives as a rounded JS number by default (LOSSY). The pool MUST be built with
+//     `mysqlDeboxPoolOptions` (`supportBigNumbers + bigNumberStrings` so BIGINT→string, and
+//     `dateStrings` so the date family→string). `mysqlDeboxPoolOptions` is those options.
+/** PG type OIDs for the date/time family + int8 (bigint). */
+const PG_OID = { INT8: 20, DATE: 1082, TIMESTAMP: 1114, TIMESTAMPTZ: 1184, TIME: 1083, TIMETZ: 1266 };
+/**
+ * Register `pg` type parsers so the read-path de-box (issue #59) gets coercible values: the
+ * DATE/TIMESTAMP/TIMESTAMPTZ/TIME family is returned as its NATIVE TEXTUAL string (NOT a JS Date),
+ * honoring the `date→string` outType and carrying the TZ for timestamptz. int8 already arrives as a
+ * string (pg default), so it needs no parser. Idempotent. Call ONCE, before building the pool, from
+ * the consumer that owns the `pg` module (`import { types } from 'pg'; configurePgDeboxTypeParsers(types)`).
+ *
+ * WHY the GLOBAL parser (a documented, deliberate exception): `pg`'s default DATE parser builds a JS
+ * `Date` at LOCAL midnight, which shifts the UTC CALENDAR DAY (e.g. `2026-07-14` → a Date whose UTC
+ * day is `2026-07-13`). That loss happens INSIDE the driver, BEFORE the materializer sees the value —
+ * so materializer-side coercion CANNOT recover the correct calendar day from the already-shifted
+ * Date. Reading the native text (this parser) is the only lossless option, and `pg` exposes type
+ * parsers only at module (process-global) scope. It is set ONCE at pool creation, not per read. The
+ * materializer's `Date → ISO string` path remains as a defensive fallback for any driver/config that
+ * still slips a Date through, but the correct-day guarantee for pg DATE comes from this parser.
+ */
+function configurePgDeboxTypeParsers(types) {
+    const asString = (v) => v; // identity: keep the driver's native textual form
+    types.setTypeParser(PG_OID.DATE, asString);
+    types.setTypeParser(PG_OID.TIMESTAMP, asString);
+    types.setTypeParser(PG_OID.TIMESTAMPTZ, asString);
+    types.setTypeParser(PG_OID.TIME, asString);
+    types.setTypeParser(PG_OID.TIMETZ, asString);
+}
+/**
+ * The `mysql2` pool options the read-path de-box (issue #59) requires: `supportBigNumbers` +
+ * `bigNumberStrings` so BIGINT arrives as an EXACT string (→ bigint; a plain number would already
+ * have rounded it), and `dateStrings` so the DATE/TIMESTAMP/DATETIME family arrives as its native
+ * textual string (→ the `date→string` outType, NOT a JS Date). Spread into `mysql.createPool(...)`.
+ */
+exports.mysqlDeboxPoolOptions = {
+    supportBigNumbers: true,
+    bigNumberStrings: true,
+    dateStrings: true,
+};
 /**
  * Adapt a `pg.Pool` to the async executor seam. Each `exec` runs `pool.query`, which acquires a
  * pooled connection, runs the query, and releases it — so N concurrent siblings run on N pooled
@@ -35,12 +88,27 @@ function pgPoolExecutor(pool) {
     };
 }
 /**
- * Adapt a `mysql2/promise` pool to the async executor seam. `pool.query` acquires + releases a
- * pooled connection per call, so concurrent siblings run in parallel. The graph renders `?`
- * placeholders for the `mysql` dialect — `mysql2`'s native form.
- *
- * Recommend `connectionLimit` ≥ the plan's `concurrency` (default 16).
+ * Build a PG pool + executor with the read-path de-box wired IN (issue #59): registers the pg date
+ * type parsers (DATE/TIMESTAMP family → native textual string) globally, then builds the pool.
+ * int8 already arrives as a string on pg. Returns `{ pool, exec }` — pass `exec` to
+ * `executeBehaviorAsync`. This is the production async path's de-box-correct entry (no hand-spread
+ * options).
  */
+function pgDeboxExecutor(pg, config) {
+    configurePgDeboxTypeParsers(pg.types);
+    const pool = new pg.Pool(config);
+    return { pool, exec: pgPoolExecutor(pool) };
+}
+/**
+ * Build a MySQL pool + executor with the read-path de-box wired IN (issue #59): the pool carries
+ * {@link mysqlDeboxPoolOptions} (`supportBigNumbers + bigNumberStrings` so BIGINT → exact string,
+ * `dateStrings` so the date family → string) — options that MUST be set at pool construction (a
+ * rounded BIGINT cannot be un-rounded post-hoc). Returns `{ pool, exec }` for `executeBehaviorAsync`.
+ */
+function mysqlDeboxExecutor(mysql2, config) {
+    const pool = mysql2.createPool({ ...config, ...exports.mysqlDeboxPoolOptions });
+    return { pool, exec: mysqlPoolExecutor(pool) };
+}
 function mysqlPoolExecutor(pool) {
     return async (sql, params) => {
         const [rows] = await pool.query(sql, params);

package/dist/scp/makesql/pool-executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"pool-executor.js","sourceRoot":"","sources":["../../../src/scp/makesql/pool-executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;AAsBH,wCAKC;AASD,8CAKC;AA3BD;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,IAAgB;IAC7C,OAAO,KAAK,EAAE,GAAW,EAAE,MAAiB,EAAsC,EAAE;QAClF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,IAAmB;IACnD,OAAO,KAAK,EAAE,GAAW,EAAE,MAAiB,EAAsC,EAAE;QAClF,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"pool-executor.js","sourceRoot":"","sources":["../../../src/scp/makesql/pool-executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAyCH,kEAOC;AAgCD,wCAKC;AAkCD,0CAIC;AAQD,gDAGC;AAED,8CAKC;AAzID,iFAAiF;AACjF,iGAAiG;AACjG,gGAAgG;AAChG,2CAA2C;AAC3C,+FAA+F;AAC/F,iGAAiG;AACjG,6FAA6F;AAC7F,iGAAiG;AACjG,8EAA8E;AAC9E,mGAAmG;AACnG,4FAA4F;AAC5F,0FAA0F;AAE1F,6DAA6D;AAC7D,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAW,CAAC;AAO/G;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,2BAA2B,CAAC,KAAkB;IAC5D,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,kDAAkD;IAC7F,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3C,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAChD,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAClD,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3C,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACU,QAAA,qBAAqB,GAAG;IACnC,iBAAiB,EAAE,IAAI;IACvB,gBAAgB,EAAE,IAAI;IACtB,WAAW,EAAE,IAAI;CACT,CAAC;AAYX;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,IAAgB;IAC7C,OAAO,KAAK,EAAE,GAAW,EAAE,MAAiB,EAAsC,EAAE;QAClF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC,CAAC;AACJ,CAAC;AA2BD;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,EAAgB,EAAE,MAA+B;IAC/E,2BAA2B,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,MAAwB,EAAE,MAA+B;IAC1F,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,6BAAqB,EAAE,CAAC,CAAC;IACxE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,SAAgB,iBAAiB,CAAC,IAAmB;IACnD,OAAO,KAAK,EAAE,GAAW,EAAE,MAAiB,EAAsC,EAAE;QAClF,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC"}