litedbmodel 2.0.1 → 2.1.0

package/dist/scp/makesql/static-bundle.js

@@ -49,6 +49,9 @@ const tx_1 = require("./tx");
 const makesql_1 = require("./makesql");
 const handler_1 = require("./handler");
 const tx_2 = require("./tx");
+const find_filter_guard_1 = require("../find-filter-guard");
+const outtype_1 = require("./outtype");
+const coltype_1 = require("../coltype");
 const errors_1 = require("../errors");
 const DBConditions_1 = require("../../DBConditions");
 const DBValues_1 = require("../../DBValues");
@@ -59,6 +62,10 @@ const authoring_sql_1 = require("../authoring-sql");
 function isMap(n) {
     return 'map' in n;
 }
+/** A bc 0.7.3+ `FanoutNode` (connection fan-out). litedbmodel never emits these. */
+function isFanout(n) {
+    return 'fanout' in n;
+}
 function nodeRef(n) {
     return isMap(n) ? { component: n.map.component, ports: n.map.ports } : { component: n.component, ports: n.ports };
 }
@@ -556,7 +563,7 @@ function compilePrimaryNode(node, dialect) {
     if (component === 'Select' || component === 'Count')
         return compileSelectNode(node, dialect);
     if (component === 'Insert' || component === 'Update' || component === 'Delete') {
-        const op = (0, tx_2.compileWriteNode)(node);
+        const op = (0, tx_2.compileWriteNode)(node, dialect);
         return [{ sql: op.sql, params: op.params }];
     }
     throw new Error(`static-bundle: catalog component '${component}' has no makeSQL compile (SQL CRUD only: Select/Count/Insert/Update/Delete)`);
@@ -576,6 +583,11 @@ function compileStaticBundle(contract, dialect, entry) {
     for (const n of component.body) {
         if ('cond' in n)
             continue;
+        if (isFanout(n)) {
+            // bc 0.7.3+ `FanoutNode`. litedbmodel never emits fanout — reject fail-closed rather
+            // than mistake it for the primary catalog `componentRef`.
+            throw new Error(`static-bundle: behavior '${component.name}' node '${n.id}' is a fanout node, not supported by litedbmodel (bc FanoutNode)`);
+        }
         if (isMap(n))
             continue;
         if (primary === undefined)
@@ -640,6 +652,8 @@ function collectRefOptHeads(node, into) {
 function skipGuardHeads(n, into) {
     if ('cond' in n)
         return;
+    if (isFanout(n))
+        return; // bc FanoutNode carries no where-ports SKIP guard (litedbmodel never emits it)
     const ports = isMap(n) ? n.map.ports : n.ports;
     const where = ports.where;
     if (typeof where !== 'object' || where === null || !('arr' in where))
@@ -673,6 +687,65 @@ function collectRefHeads(node, into) {
     for (const v of Object.values(node))
         collectRefHeads(v, into);
 }
+// ── FIND_FILTER leak guard: authored WHERE column keys (fail-closed model-scope enforcement) ──
+/**
+ * Collect the top-level COLUMN names an authored `where` port constrains — the LHS column of each
+ * eq/ne/cmp member, the IN-sentinel column, and (recursively) the columns of `and`/`or` groups and
+ * SKIP-`cond` members. This is exactly the key set v1 compares against when it folds a model's
+ * `FIND_FILTER` into the WHERE (`condsToRecord(FIND_FILTER)` keys vs the compiled predicate), so the
+ * {@link assertFindFilterFolded} guard can fail-closed when a FIND_FILTER model is SCP-compiled
+ * without its scope predicates folded in. Additive sentinel primitives (immediate/dynamic/exists/…)
+ * carry no plain column key and are skipped — a scope key must be an ordinary eq/cmp/in the author
+ * expressed, matching how a FIND_FILTER predicate manifests.
+ */
+function whereMemberColumns(node, into) {
+    const op = opKey(node);
+    if (op === undefined)
+        return;
+    if (op === 'and' || op === 'or') {
+        const args = node[op];
+        if (Array.isArray(args))
+            for (const m of args)
+                whereMemberColumns(m, into);
+        return;
+    }
+    if (op === 'cond') {
+        const cargs = node.cond;
+        if (Array.isArray(cargs) && cargs.length === 3)
+            whereMemberColumns(cargs[1], into);
+        return;
+    }
+    if (op === 'eq' || op in CMP_OPS) {
+        const args = node[op];
+        if (!Array.isArray(args) || args.length !== 2)
+            return;
+        const inCol = inSentinelColumn(args[0]);
+        if (inCol !== undefined) {
+            into.add(inCol);
+            return;
+        }
+        // A plain column ref LHS (a bare eq/cmp). An additive sentinel LHS (immediate/dynamic/exists/…)
+        // is NOT a plain column — its column key would be encoded in the primitive, so it is skipped
+        // (a FIND_FILTER scope key is always an ordinary eq/cmp/IS NULL the author must fold explicitly).
+        const lhsOp = opKey(args[0]);
+        if (lhsOp === 'ref' || lhsOp === 'refOpt') {
+            const path = args[0][lhsOp];
+            if (Array.isArray(path) && path.length > 0 && typeof path[path.length - 1] === 'string' && path[0] !== tx_1.IN_SENTINEL) {
+                into.add(path[path.length - 1]);
+            }
+        }
+    }
+}
+/** The authored WHERE column-key set of a read node's `where` port (for the FIND_FILTER guard). */
+function authoredWhereKeysOf(ports) {
+    const keys = new Set();
+    const arr = arrPort(ports, 'where');
+    if (arr === undefined)
+        return keys;
+    for (const m of arr)
+        whereMemberColumns(m, keys);
+    return keys;
+}
 // ── Runtime: evaluate value-specs + skip per-input, assemble, render, execute ──
 /** bc evaluates ints to bigint; convert a rendered param to a driver-bindable value. */
 function toDriverParam(v) {
@@ -784,181 +857,326 @@ function executeStaticWrite(bundle, input, db) {
     }
 }
 // ============================================================================
-// Step 0 — the bc-runBehavior read executor: bc composes (map / Φ-merge / wiring),
-// makeSQL executes. A read behavior method whose output is a Φ-merge of SQL nodes
-// (`{obj:{posts:ref[n0], authors:map(n0)}}`) is executed by rewriting each SQL node
-// to a `makeSQL` node carrying a synthetic `__scope` port and running bc `runBehavior`
-// with a handler that renders that node's static statements against the evaluated scope.
-// This gives map iteration + Φ output + wiring FOR FREE (bc owns orchestration).
+// #12 — the NATIVE read-graph walker (interpreter-free): litedbmodel composes map /
+// Φ-merge / wiring ITSELF over `compileBehaviors`' REAL `Select`/`Count`/map node IR
+// (no `__makeSqlNode`/`__scope` surrogate, no bc `runBehavior`). Each body node's SQL
+// comes from its `statementsById[id]` fragment templates (rendered against the walk
+// scope); topology (`map.over`/`as`, `plan.groups`, `output` Φ) is read off the real
+// nodes. This mirrors the rust/go/py/php native walkers — one shared orchestration model
+// across all 5 runtimes, `runBehavior` invoked on NONE of them.
 // ============================================================================
-/** The synthetic port that carries a SQL node's render scope (bc evaluates it in-scope). */
-const SCOPE_PORT = '__scope';
-/** The makeSQL catalog leaf name every rewritten SQL node references. */
-const NODE_COMPONENT = '__makeSqlNode';
-/** Collect every ref/refOpt path HEAD used inside an Expression IR node. */
-function collectAllHeads(node, heads) {
-    if (node === null || typeof node !== 'object')
-        return;
-    if (Array.isArray(node)) {
-        for (const el of node)
-            collectAllHeads(el, heads);
-        return;
-    }
-    const keys = Object.keys(node);
-    if (keys.length === 1 && (keys[0] === 'ref' || keys[0] === 'refOpt')) {
-        const path = node[keys[0]];
-        if (Array.isArray(path) && typeof path[0] === 'string')
-            heads.add(path[0]);
-        return;
-    }
-    for (const k of keys)
-        collectAllHeads(node[k], heads);
-}
-/** Every binding head a node's compiled statements reference (params + skip). */
-function statementHeads(statements) {
-    const heads = new Set();
-    for (const stmt of statements) {
-        for (const p of stmt.params)
-            collectAllHeads(p, heads);
-        if (stmt.skip !== undefined)
-            collectAllHeads(stmt.skip, heads);
-    }
-    return heads;
-}
-/**
- * Build the surrogate `__scope` port for a node: a bc `{obj:{…}}` re-exporting each referenced
- * head as `{ref:[head]}` (excluding the IN-sentinel column marker). bc evaluates this in ITS
- * scope (so `input`, sibling wire results and the `map` element `as` all resolve), then the
- * handler renders the node's static statements against the resulting plain scope.
- */
-function scopePort(statements) {
-    const obj = {};
-    for (const head of statementHeads(statements)) {
-        if (head === tx_1.IN_SENTINEL)
-            continue;
-        obj[head] = { ref: [head] };
-    }
-    return { obj };
-}
 /** Compile ONE authored SQL node (Select or CRUD write) into its static statements. */
 function compileNodeStatements(node, dialect) {
     const component = 'map' in node ? node.map.component : node.component;
     if (component === 'Select' || component === 'Count')
         return compileSelectNode(node, dialect);
-    const op = (0, tx_2.compileWriteNode)(node);
+    const op = (0, tx_2.compileWriteNode)(node, dialect);
     return [{ sql: op.sql, params: op.params }];
 }
 /**
- * Compile a READ behavior method into a portable {@link ReadGraph}: rewrite each authored SQL
- * body node to a `makeSQL` node carrying a synthetic `__scope` port (bc evaluates it in-scope),
- * and compile each node's static statements ONCE. SYMBOLIC — no concrete input. bc will own map
- * iteration / wire binding / Φ output at execute time; the handler renders each node's statements.
+ * Compile a READ behavior method into a portable {@link ReadGraph} (#12 de-surrogated): keep
+ * `compileBehaviors`' REAL `Select`/`Count`/map body nodes (only additively annotate each with its
+ * read `outType`), and compile each node's static `makeSQL` statements ONCE into the `statementsById`
+ * sidecar (keyed by the real body-node id). SYMBOLIC — no concrete input. The native walker
+ * ({@link executeReadGraph}) owns map iteration / wire binding / Φ output at execute time, rendering
+ * each node's statements against the walk scope — never bc `runBehavior`, never a `__scope` surrogate.
  */
-function compileReadGraph(contract, dialect, entry) {
+function compileReadGraph(contract, dialect, entry, findFilterModel, resolveColumnType) {
     const component = entry ? contract.components.find((c) => c.name === entry) : contract.components[0];
     if (component === undefined)
         throw new Error(`static-bundle: entry component '${entry ?? '<first>'}' not found in contract`);
+    // FIND_FILTER fail-closed guard (M2): when a `DBModel`-shaped source that DECLARES a `FIND_FILTER`
+    // (soft-delete / tenant scope) is routed through the SCP read compile, its scope predicates MUST be
+    // folded into the authored `where` of every read node — the SCP compile has no model context to
+    // auto-apply them (see find-filter-guard.ts). If any read node's authored WHERE omits a scope key,
+    // `assertFindFilterFolded` throws (never a silent cross-tenant / soft-deleted leak). No model
+    // supplied ⇒ nothing to enforce (the guard is a no-op for a model with no FIND_FILTER either way).
+    if (findFilterModel !== undefined) {
+        for (const n of component.body) {
+            if ('cond' in n)
+                continue;
+            if (isFanout(n)) {
+                // bc 0.7.3+ `FanoutNode`. litedbmodel never emits fanout — reject fail-closed rather
+                // than mis-read it as a Select/Count ref and skip the FIND_FILTER fold check.
+                throw new Error(`static-bundle: read component '${component.name}' node '${n.id}' is a fanout node, not supported by litedbmodel (bc FanoutNode)`);
+            }
+            const ref = 'map' in n ? n.map : n;
+            if (ref.component !== 'Select' && ref.component !== 'Count')
+                continue;
+            (0, find_filter_guard_1.assertFindFilterFolded)(findFilterModel, authoredWhereKeysOf(ref.ports));
+        }
+    }
     const statementsById = {};
     for (const n of component.body) {
         if ('cond' in n)
             continue;
+        if (isFanout(n)) {
+            // bc 0.7.3+ `FanoutNode`. litedbmodel never emits fanout — reject fail-closed rather
+            // than feed it to `compileNodeStatements` as a catalog ref.
+            throw new Error(`static-bundle: read component '${component.name}' node '${n.id}' is a fanout node, not supported by litedbmodel (bc FanoutNode)`);
+        }
         statementsById[n.id] = compileNodeStatements(n, dialect);
     }
-    const surrogateBody = component.body.map((n) => {
+    // SINGLE column-type resolution (issue #59 audit — unified read+codegen): `deriveReadOutTypes`
+    // resolves every projected column of the read ONCE (via the SHARED projection parser, all shapes:
+    // bare / qualified / aliased; `*` / computed / undeclared → HARD ERROR, spec §4.1) and returns BOTH
+    // the codegen `outType`/`outputType` annotations AND the TS read-path `materializersByNode` — two
+    // projections of the ONE resolution, so they cannot diverge (there is no second, weaker read-path
+    // pass). The column types come from the model's inline `static columns` (carried on the contract as
+    // `resolveColumnType`, always present for a read model), so this runs for EVERY read: codegen writes
+    // the outType IR annotations, the runtime read path consumes the materializers. Any ambiguity /
+    // undeclared column / `*` / computed projection throws here.
+    const readTypes = resolveColumnType !== undefined ? (0, outtype_1.deriveReadOutTypes)(component, resolveColumnType) : undefined;
+    const materializers = readTypes?.materializersByNode;
+    // #12 (de-surrogation): the read-graph IR is `compileBehaviors`' REAL component — the authored
+    // `Select`/`Count`/map nodes with their own `table`/`select`/`where`/… ports, NOT a hand-built
+    // `__makeSqlNode` + `__scope` surrogate. litedbmodel constructs NO `ComponentGraphIR`/`BodyNode`
+    // literal here: it only ADDITIVELY annotates each node with its read `outType` (issue #59) and the
+    // component with its `outputType` — the node SHAPE/ports are `compileBehaviors`' output untouched.
+    // The compiled SQL fragment templates ride the sidecar `statementsById` (opaque, v1-`DBConditions`-
+    // sourced TEXT), keyed by the SAME real body-node id; every language runtime walks this real-node
+    // IR natively (topology from the real nodes; SQL from `statementsById[id]`), never bc `runBehavior`.
+    const annotatedBody = component.body.map((n) => {
         if ('cond' in n)
             return n;
-        const stmts = statementsById[n.id];
-        if ('map' in n) {
-            return { ...n, map: { ...n.map, component: NODE_COMPONENT, ports: { [SCOPE_PORT]: scopePort(stmts) } } };
-        }
-        return { ...n, component: NODE_COMPONENT, ports: { [SCOPE_PORT]: scopePort(stmts) } };
+        const outType = readTypes?.byNode.get(n.id);
+        return outType !== undefined ? { ...n, outType } : n;
     });
-    const surrogate = { ...component, body: surrogateBody };
-    const ir = { irVersion: 1, exprVersion: 2, components: [surrogate] };
+    const irComponent = {
+        ...component,
+        body: annotatedBody,
+        ...(readTypes !== undefined ? { outputType: readTypes.outputType } : {}),
+    };
+    // Preserve `compileBehaviors`' OWN IR envelope (irVersion/exprVersion + any other metadata) — the
+    // read graph IR is the compiler's output with ONLY the single entry component swapped for its
+    // outType-annotated twin (additive). litedbmodel fabricates no `ComponentGraphIR`/`BodyNode`.
+    const ir = { ...contract.ir, components: [irComponent] };
     return {
         dialect,
         name: component.name,
         ir,
         statementsById,
         optionalHeads: [...optionalHeadsOfComponent(component, dialect)],
+        ...(materializers !== undefined && materializers.size > 0 ? { materializersByNode: Object.fromEntries(materializers) } : {}),
     };
 }
 /**
- * Execute a compiled {@link ReadGraph} via bc `runBehavior` + a makeSQL handler: bc drives map
- * iteration / wire binding / Φ output; the handler renders each node's static statements against
- * the evaluated `__scope` and runs REAL SQLite. Returns the component's Φ output. This is the
- * design's "bc composes, makeSQL executes" — the SAME path a per-language runtime follows.
+ * Apply a node's per-column materializers (issue #59) to its raw driver rows: coerce each cell to
+ * the JS form its SQL column type declares (BIGINT→bigint, INT→number, DATE→string, BOOLEAN→
+ * boolean). A no-op when the node has no materializer map (read compiled without a column-type
+ * resolver) or a column has no entry (defensive — only projected columns are typed). Mutates + returns
+ * the same row objects (they are freshly produced by the driver, so mutation is safe).
  */
-function executeReadGraph(graph, input, db) {
-    const handle = (ports, ctx) => {
-        const stmts = graph.statementsById[ctx.nodeId];
-        if (stmts === undefined)
-            return { error: `static-bundle: no statements for node '${ctx.nodeId}'` };
-        const scope = ports[SCOPE_PORT];
-        if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) {
-            return { error: `static-bundle: node '${ctx.nodeId}' surrogate scope did not evaluate to an object` };
+function materializeRows(rows, cols, safeIntegersOn = false) {
+    if (cols === undefined && !safeIntegersOn)
+        return rows;
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            const klass = cols?.[key];
+            if (klass !== undefined) {
+                row[key] = (0, coltype_1.materializeCell)(row[key], klass);
+                continue;
+            }
+            // Defensive (SQLite safeIntegers mode): when the statement was put in safe-integer mode for a
+            // BIGINT column, EVERY int column arrives as a bigint — including columns the resolver didn't
+            // type. Narrow a stray bigint back to a number when it fits safely, else to an exact string
+            // (so a value never leaks out as a raw bigint, which is not JSON-safe).
+            if (safeIntegersOn && typeof row[key] === 'bigint') {
+                const v = row[key];
+                row[key] = v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : v.toString();
+            }
         }
-        const { sql, params } = renderStatements(stmts, graph.dialect, scope);
-        try {
-            const rows = db.prepare(sql).all(...params);
-            return { ok: rows };
+    }
+    return rows;
+}
+/** True iff any projected column of this node is a 64-bit int (needs the driver in exact mode). */
+function hasInt64(cols) {
+    for (const k of Object.keys(cols))
+        if (cols[k] === 'int64')
+            return true;
+    return false;
+}
+/** The plan stages (`groups`) as body-index lists, or one-node-per-stage in declaration order. */
+function planStages(component) {
+    const plan = component.plan;
+    const groups = plan?.groups;
+    if (Array.isArray(groups)) {
+        return groups.map((st) => (Array.isArray(st) ? st.filter((i) => typeof i === 'number') : []));
+    }
+    return component.body.map((_n, i) => [i]);
+}
+/** The plan's `concurrency` bound (default 1 — serial when absent/≤1), for the async fan-out. */
+function planConcurrency(component) {
+    const plan = component.plan;
+    const c = plan?.concurrency;
+    return typeof c === 'number' && c >= 1 ? c : 1;
+}
+/**
+ * Bounded-parallel map preserving INPUT ORDER in the result. At most `limit` tasks run at once
+ * (`limit <= 1` ⇒ strictly serial). Deterministic: the output array is indexed by input position,
+ * regardless of completion order — mirrors bc `runPlanAsync`'s in-order commit, so the async walker's
+ * assembled result equals the serial walker's byte-for-byte.
+ */
+async function boundedMap(items, limit, fn) {
+    const out = new Array(items.length);
+    const cap = Math.max(1, Math.floor(limit));
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            out[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(cap, items.length) }, () => worker()));
+    return out;
+}
+/** Render + execute a node's `statementsById` fragments against `scope`, sync driver, with #59 de-box. */
+function execReadNodeSync(graph, nodeId, scope, db) {
+    const stmts = graph.statementsById[nodeId];
+    if (stmts === undefined)
+        throw new Error(`static-bundle: no statements for node '${nodeId}'`);
+    const { sql, params } = renderStatements(stmts, graph.dialect, scope);
+    const cols = graph.materializersByNode?.[nodeId];
+    try {
+        const stmt = db.prepare(sql);
+        // A BIGINT-projecting node runs in SQLite safe-integer mode so int8 comes back as an EXACT
+        // bigint (a JS number would round it — the #59 hole); `materializeRows` then narrows/stringifies.
+        let safeIntegersOn = false;
+        if (cols !== undefined && hasInt64(cols) && typeof stmt.safeIntegers === 'function') {
+            stmt.safeIntegers(true);
+            safeIntegersOn = true;
         }
-        catch (e) {
-            return { error: (0, errors_1.mapSqliteError)(e).message };
+        const rows = stmt.all(...params);
+        return materializeRows(rows, cols, safeIntegersOn);
+    }
+    catch (e) {
+        throw (0, errors_1.mapSqliteError)(e);
+    }
+}
+/** Compute ONE read-graph body node's value against `base`: a `cond` join, a `map` (per-element
+ * render+execute under the `as` binding), or a componentRef (render+execute). Sync driver. */
+function computeReadNodeSync(graph, node, base, db) {
+    if (node.cond !== undefined)
+        return (0, behavior_contracts_1.evaluateExpression)(node.cond, base);
+    if (node.map !== undefined) {
+        const over = (0, behavior_contracts_1.evaluateExpression)(node.map.over, base);
+        if (!Array.isArray(over))
+            throw new Error(`static-bundle: map '${node.id}': 'over' is not an array`);
+        const asName = node.map.as ?? '$';
+        const out = [];
+        for (const el of over) {
+            out.push(execReadNodeSync(graph, node.id, { ...base, [asName]: el }, db));
         }
-    };
-    const handlers = { [NODE_COMPONENT]: handle };
-    const normalized = { ...input };
+        return out;
+    }
+    return execReadNodeSync(graph, node.id, base, db);
+}
+/** Normalize omitted OPTIONAL heads to present-as-null (absent-key SKIP; SSoT-driven). */
+function normalizeReadInput(graph, input) {
+    const out = { ...input };
     for (const head of graph.optionalHeads)
-        if (!(head in normalized))
-            normalized[head] = null;
+        if (!(head in out))
+            out[head] = null;
+    return out;
+}
+/**
+ * Execute a compiled {@link ReadGraph} via the NATIVE walker (#12): walk `compileBehaviors`' REAL
+ * `Select`/`Count`/map node IR in `plan.groups` stage order — computing each node's rows from its
+ * `statementsById` fragments (rendered against the walk scope) and committing `(nodeId → value)` —
+ * then evaluate the component's `output` Φ expression. NO bc `runBehavior`, NO `__makeSqlNode`
+ * surrogate; litedbmodel owns map iteration / wire binding / Φ output. This is the SAME native
+ * orchestration model the rust/go/py/php runtimes follow — one shape, all 5 languages, interpreter-free.
+ */
+function executeReadGraph(graph, input, db) {
+    const component = graph.ir.components[0];
+    const body = component.body;
+    const output = component.output ?? null;
+    const normalized = normalizeReadInput(graph, input);
     try {
-        return (0, behavior_contracts_1.runBehavior)(graph.ir, handlers, normalized, graph.name);
+        const results = [];
+        for (const stage of planStages(component)) {
+            // Commit stage members in ascending body index (deterministic failure precedence).
+            const ordered = [...stage].sort((a, b) => a - b);
+            const base = { ...normalized };
+            for (const [id, v] of results)
+                base[id] = v;
+            for (const idx of ordered) {
+                const node = body[idx];
+                base[node.id] = results[results.push([node.id, computeReadNodeSync(graph, node, base, db)]) - 1][1];
+            }
+        }
+        const scope = { ...normalized };
+        for (const [id, v] of results)
+            scope[id] = v;
+        return (0, behavior_contracts_1.evaluateExpression)(output, scope);
     }
     catch (e) {
         throw reErrorToSqlFailure(e);
     }
 }
+/** Render + execute a node's `statementsById` fragments against `scope`, async driver, with #59 de-box. */
+async function execReadNodeAsync(graph, nodeId, scope, exec) {
+    const stmts = graph.statementsById[nodeId];
+    if (stmts === undefined)
+        throw new Error(`static-bundle: no statements for node '${nodeId}'`);
+    const { sql, params } = renderStatements(stmts, graph.dialect, scope);
+    try {
+        const rows = await exec(sql, params);
+        // #59 materializers: the pooled PG/MySQL drivers are configured so int8/BIGINT arrive as a string
+        // (→ bigint) and BOOLEAN as a JS boolean; `materializeCell` coerces each to the SQL-type JS form.
+        return materializeRows(rows, graph.materializersByNode?.[nodeId]);
+    }
+    catch (e) {
+        throw (0, errors_1.mapSqliteError)(e);
+    }
+}
+/** Async twin of {@link computeReadNodeSync}: dispatches a map stage's per-element queries in bounded
+ * parallel (the live PG/MySQL fan-out, capped at `concurrency`); a componentRef runs one query; a
+ * `cond` is pure. */
+async function computeReadNodeAsync(graph, node, base, exec, concurrency) {
+    if (node.cond !== undefined)
+        return (0, behavior_contracts_1.evaluateExpression)(node.cond, base);
+    if (node.map !== undefined) {
+        const over = (0, behavior_contracts_1.evaluateExpression)(node.map.over, base);
+        if (!Array.isArray(over))
+            throw new Error(`static-bundle: map '${node.id}': 'over' is not an array`);
+        const asName = node.map.as ?? '$';
+        return (await boundedMap(over, concurrency, (el) => execReadNodeAsync(graph, node.id, { ...base, [asName]: el }, exec)));
+    }
+    return execReadNodeAsync(graph, node.id, base, exec);
+}
 /**
- * Async twin of {@link executeReadGraph} — the PG / MySQL execution model (#40).
- *
- * Byte-identical composition (SAME IR, SAME per-node SQL text + params, SAME Φ output), but bc's
- * `runBehaviorAsync` drives it: the makeSQL handler returns a Promise, and bc dispatches the
- * INDEPENDENT sibling nodes of a plan stage on `runPlanAsync`'s bounded-parallel path (bc#23),
- * bounded by the plan's `concurrency` (default 16). Against a pooled async driver (`pg` / `mysql2`,
- * each `exec` call resolving on its own pooled connection), that becomes REAL parallel read-relation
- * DB I/O — the plan's declared concurrency finally cashes out as concurrent dispatch. The result is
- * deterministic (bc commits stage outcomes in declaration order), so it equals the serial
- * `executeReadGraph` output exactly; only the wall-clock changes.
- *
- * The conformance bar stays on the SYNC in-proc better-sqlite3 path (`executeReadGraph`); this async
- * path is the live PG/MySQL execution model and is proven by the latency-injecting concurrency test.
+ * Async twin of {@link executeReadGraph} — the live PG / MySQL execution model (#40). Byte-identical
+ * composition (SAME real-node IR, SAME per-node SQL text + params, SAME Φ output); within a plan stage
+ * the INDEPENDENT sibling nodes are dispatched concurrently against the pooled async executor (each
+ * `exec` resolving on its own pooled connection), and a map node's per-element queries fan out in
+ * bounded parallel. The result is deterministic (stage outcomes commit in declaration order), so it
+ * equals the serial `executeReadGraph` output exactly; only the wall-clock changes.
  */
 async function executeReadGraphAsync(graph, input, exec) {
-    const handle = async (ports, ctx) => {
-        const stmts = graph.statementsById[ctx.nodeId];
-        if (stmts === undefined)
-            return { error: `static-bundle: no statements for node '${ctx.nodeId}'` };
-        const scope = ports[SCOPE_PORT];
-        if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) {
-            return { error: `static-bundle: node '${ctx.nodeId}' surrogate scope did not evaluate to an object` };
-        }
-        const { sql, params } = renderStatements(stmts, graph.dialect, scope);
-        try {
-            const rows = await exec(sql, params);
-            return { ok: rows };
-        }
-        catch (e) {
-            return { error: (0, errors_1.mapSqliteError)(e).message };
-        }
-    };
-    const handlers = { [NODE_COMPONENT]: handle };
-    const normalized = { ...input };
-    for (const head of graph.optionalHeads)
-        if (!(head in normalized))
-            normalized[head] = null;
+    const component = graph.ir.components[0];
+    const body = component.body;
+    const output = component.output ?? null;
+    const concurrency = planConcurrency(component);
+    const normalized = normalizeReadInput(graph, input);
     try {
-        return await (0, behavior_contracts_1.runBehaviorAsync)(graph.ir, handlers, normalized, graph.name);
+        const results = [];
+        for (const stage of planStages(component)) {
+            const ordered = [...stage].sort((a, b) => a - b);
+            const base = { ...normalized };
+            for (const [id, v] of results)
+                base[id] = v;
+            // Independent siblings of a stage run in bounded parallel (capped at the plan concurrency;
+            // concurrency ≤ 1 ⇒ serial); committed in ascending body index order for determinism.
+            const vals = await boundedMap(ordered, concurrency, (idx) => computeReadNodeAsync(graph, body[idx], base, exec, concurrency));
+            ordered.forEach((idx, i) => results.push([body[idx].id, vals[i]]));
+        }
+        const scope = { ...normalized };
+        for (const [id, v] of results)
+            scope[id] = v;
+        return (0, behavior_contracts_1.evaluateExpression)(output, scope);
     }
     catch (e) {
         throw reErrorToSqlFailure(e);
@@ -980,7 +1198,7 @@ function executeReadBehavior(contract, input, dialect, db, entry) {
  */
 function renderReadPrimary(graph, input) {
     const ids = Object.keys(graph.statementsById);
-    // The primary node is the first body node in the surrogate IR order (map nodes reference it).
+    // The primary node is the first body node in the real-node IR order (map nodes reference it).
     const bodyIds = graph.ir.components[0].body.map((n) => n.id).filter((id) => ids.includes(id));
     const primaryId = bodyIds[0];
     if (primaryId === undefined)
@@ -1003,6 +1221,8 @@ function optionalHeadsOfComponent(component, dialect) {
     for (const n of component.body) {
         if ('cond' in n)
             continue;
+        if (isFanout(n))
+            continue; // bc FanoutNode: litedbmodel never emits it; carries no ref-opt heads.
         const stmts = compileNodeStatements(n, dialect);
         for (const stmt of stmts) {
             for (const p of stmt.params)