litedbmodel 2.0.0 → 2.0.1

package/dist/scp/makesql/makesql.d.ts

@@ -0,0 +1,99 @@
+/**
+ * litedbmodel v2 SCP — the LOCKED minimal bc integration: ONE catalog component
+ * **`makeSQL(sql, params, skip?)`** (a behavior-contracts catalog leaf, exactly like
+ * graphddb's `GetItem`/`Query`).
+ *
+ * ## The locked model (owner-specified — nothing else exists)
+ *
+ * - bc integration = ONE catalog component `makeSQL`. Ports:
+ *     - `sql`    — tuned dialect SQL text (a string; `?` placeholders).
+ *     - `params` — value list. Each element is EITHER a bound value (an opaque SQL
+ *                  value: number/string/bool/null/Date/array/…) OR a **nested
+ *                  `makeSQL`** (a `{ sql, params, skip? }` object) whose `sql` is
+ *                  spliced at the corresponding `?` and whose params flow inline.
+ *                  A subquery / sub-expression is a nested `makeSQL` in a param slot.
+ *     - `skip?`  — presence condition. When satisfied, the component contributes
+ *                  NOTHING (its `sql` and its `params` both drop).
+ * - A query = a composition of `makeSQL` components. bc composes; present ones
+ *   concatenate. There is NO relation-op / operator / "kind" for SQL structure.
+ * - `= ANY`, `CROSS JOIN LATERAL`, `UNNEST`, cast, subquery, batch shapes are ALL
+ *   TEXT inside `sql`. Never modeled.
+ * - An array/rows param binds as ONE value with STATIC text on EVERY dialect
+ *   (epic #43/#45): PostgreSQL `= ANY(?::t[])` / `UNNEST`, MySQL/SQLite a single JSON
+ *   param expanded server-side (`MEMBER OF` / `JSON_TABLE` / `json_each`). There is no
+ *   array placeholder-count-expansion anywhere anymore.
+ *
+ * litedbmodel supplies (spec §11): the `makeSQL` catalog entry, its **handler**
+ * (bind params → execute SQL), and the **compile** step that emits the tuned dialect
+ * SQL text (by REUSING the original tuned builders — see `compile-*.ts`). bc supplies
+ * composition / value-eval / envelope / plan (it comes free once queries are `makeSQL`
+ * components). The bundle stays pure JSON (multi-language ready).
+ */
+import type { CatalogEntry } from 'behavior-contracts';
+/** The single catalog leaf name. Everything SQL is a `makeSQL`. */
+export declare const MAKESQL: "makeSQL";
+/**
+ * A bound SQL param value OR a nested `makeSQL` (subquery / sub-expression).
+ *
+ * A nested `makeSQL` in a param slot is how subqueries are represented: its `sql`
+ * splices into the parent's `?` position and its params flow into the parent's param
+ * stream in order. This is the ONLY recursion; there is no other SQL-structure
+ * vocabulary.
+ */
+export type SqlParam = unknown | MakeSQL;
+/**
+ * The `makeSQL` port bundle — the ONLY structural type.
+ *
+ * `sql` is complete tuned SQL text with `?` placeholders (leading connector included
+ * where the composition needs it, exactly as the original builder emits). `params`
+ * are 1:1 with the top-level `?` (a bound value fills one `?`; a nested `makeSQL`
+ * param splices its own `sql`, which may contain further `?`). `skip`, when `true`,
+ * omits the whole component (sql AND params).
+ */
+export interface MakeSQL {
+    sql: string;
+    params: SqlParam[];
+    /** Presence condition already resolved to a boolean at bind/eval time. */
+    skip?: boolean;
+}
+/** Structural guard: a nested-`makeSQL` param has a string `sql`; a bound value does not. */
+export declare function isMakeSQL(p: SqlParam): p is MakeSQL;
+/**
+ * The `makeSQL` catalog entry (bc `CatalogEntry`). A leaf Specialty Component: name +
+ * Port contract + output shape. The handler implementation is separate (see
+ * `handler.ts`) — the IR carries only the reference name + port wiring (C4).
+ *
+ * `params` is a dynamic-arity port family (the value list length is query-specific),
+ * so `additionalPorts` is not needed: `params` is a single arr-typed port, `sql` a
+ * string, `skip` an optional bool. `output.shape = 'items'` (a SELECT yields rows; a
+ * write yields RETURNING rows or `[]`).
+ */
+export declare const makeSqlCatalogEntry: CatalogEntry;
+/** The litedbmodel catalog — a single leaf, `makeSQL`. */
+export declare const LITEDBMODEL_MAKESQL_CATALOG: Record<string, CatalogEntry>;
+/** A fully-assembled statement: complete SQL text (`?`) + a flat ordered value list. */
+export interface AssembledSql {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Assemble one `makeSQL` into `{ sql, params }`.
+ *
+ * - If `skip` is true, this component contributes nothing: returns empty text + no
+ *   params (the caller composes over the survivors).
+ * - Otherwise interleave the literal `sql` (split on `?`) with each param: a bound
+ *   value emits a single `?` and contributes its value; a nested `makeSQL` splices
+ *   its assembled `sql` and contributes its assembled params (recursively). A nested
+ *   `makeSQL` that is itself skipped contributes empty text + no params.
+ */
+export declare function assembleMakeSQL(node: MakeSQL): AssembledSql;
+/**
+ * Compose an ordered list of `makeSQL` components into one statement: concatenate the
+ * assembled `sql` of every PRESENT component and their params in order (the locked
+ * model's "present ones concatenate"). Skipped components drop entirely.
+ *
+ * Each component's `sql` already carries whatever connector text the tuned builder
+ * emits for that position, so concatenation is byte-faithful for every skip subset.
+ */
+export declare function composeMakeSQL(nodes: MakeSQL[]): AssembledSql;
+//# sourceMappingURL=makesql.d.ts.map

package/dist/scp/makesql/makesql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"makesql.d.ts","sourceRoot":"","sources":["../../../src/scp/makesql/makesql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,mEAAmE;AACnE,eAAO,MAAM,OAAO,EAAG,SAAkB,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,6FAA6F;AAC7F,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,IAAI,OAAO,CAOnD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,YASjC,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAEpE,CAAC;AAWF,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAwB3D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,YAAY,CAS7D"}

package/dist/scp/makesql/makesql.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — the LOCKED minimal bc integration: ONE catalog component
+ * **`makeSQL(sql, params, skip?)`** (a behavior-contracts catalog leaf, exactly like
+ * graphddb's `GetItem`/`Query`).
+ *
+ * ## The locked model (owner-specified — nothing else exists)
+ *
+ * - bc integration = ONE catalog component `makeSQL`. Ports:
+ *     - `sql`    — tuned dialect SQL text (a string; `?` placeholders).
+ *     - `params` — value list. Each element is EITHER a bound value (an opaque SQL
+ *                  value: number/string/bool/null/Date/array/…) OR a **nested
+ *                  `makeSQL`** (a `{ sql, params, skip? }` object) whose `sql` is
+ *                  spliced at the corresponding `?` and whose params flow inline.
+ *                  A subquery / sub-expression is a nested `makeSQL` in a param slot.
+ *     - `skip?`  — presence condition. When satisfied, the component contributes
+ *                  NOTHING (its `sql` and its `params` both drop).
+ * - A query = a composition of `makeSQL` components. bc composes; present ones
+ *   concatenate. There is NO relation-op / operator / "kind" for SQL structure.
+ * - `= ANY`, `CROSS JOIN LATERAL`, `UNNEST`, cast, subquery, batch shapes are ALL
+ *   TEXT inside `sql`. Never modeled.
+ * - An array/rows param binds as ONE value with STATIC text on EVERY dialect
+ *   (epic #43/#45): PostgreSQL `= ANY(?::t[])` / `UNNEST`, MySQL/SQLite a single JSON
+ *   param expanded server-side (`MEMBER OF` / `JSON_TABLE` / `json_each`). There is no
+ *   array placeholder-count-expansion anywhere anymore.
+ *
+ * litedbmodel supplies (spec §11): the `makeSQL` catalog entry, its **handler**
+ * (bind params → execute SQL), and the **compile** step that emits the tuned dialect
+ * SQL text (by REUSING the original tuned builders — see `compile-*.ts`). bc supplies
+ * composition / value-eval / envelope / plan (it comes free once queries are `makeSQL`
+ * components). The bundle stays pure JSON (multi-language ready).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LITEDBMODEL_MAKESQL_CATALOG = exports.makeSqlCatalogEntry = exports.MAKESQL = void 0;
+exports.isMakeSQL = isMakeSQL;
+exports.assembleMakeSQL = assembleMakeSQL;
+exports.composeMakeSQL = composeMakeSQL;
+/** The single catalog leaf name. Everything SQL is a `makeSQL`. */
+exports.MAKESQL = 'makeSQL';
+/** Structural guard: a nested-`makeSQL` param has a string `sql`; a bound value does not. */
+function isMakeSQL(p) {
+    return (typeof p === 'object' &&
+        p !== null &&
+        typeof p.sql === 'string' &&
+        Array.isArray(p.params));
+}
+/**
+ * The `makeSQL` catalog entry (bc `CatalogEntry`). A leaf Specialty Component: name +
+ * Port contract + output shape. The handler implementation is separate (see
+ * `handler.ts`) — the IR carries only the reference name + port wiring (C4).
+ *
+ * `params` is a dynamic-arity port family (the value list length is query-specific),
+ * so `additionalPorts` is not needed: `params` is a single arr-typed port, `sql` a
+ * string, `skip` an optional bool. `output.shape = 'items'` (a SELECT yields rows; a
+ * write yields RETURNING rows or `[]`).
+ */
+exports.makeSqlCatalogEntry = {
+    name: exports.MAKESQL,
+    inputPorts: {
+        sql: { type: 'string', required: true },
+        params: { type: 'arr' },
+        skip: { type: 'bool' },
+    },
+    output: { shape: 'items' },
+    portableToIR: true,
+};
+/** The litedbmodel catalog — a single leaf, `makeSQL`. */
+exports.LITEDBMODEL_MAKESQL_CATALOG = {
+    [exports.MAKESQL]: exports.makeSqlCatalogEntry,
+};
+/**
+ * Assemble one `makeSQL` into `{ sql, params }`.
+ *
+ * - If `skip` is true, this component contributes nothing: returns empty text + no
+ *   params (the caller composes over the survivors).
+ * - Otherwise interleave the literal `sql` (split on `?`) with each param: a bound
+ *   value emits a single `?` and contributes its value; a nested `makeSQL` splices
+ *   its assembled `sql` and contributes its assembled params (recursively). A nested
+ *   `makeSQL` that is itself skipped contributes empty text + no params.
+ */
+function assembleMakeSQL(node) {
+    if (node.skip === true)
+        return { sql: '', params: [] };
+    const chunks = node.sql.split('?');
+    if (chunks.length - 1 !== node.params.length) {
+        throw new Error(`makeSQL placeholder/param mismatch: ${chunks.length - 1} '?' vs ${node.params.length} params in ${JSON.stringify(node.sql)}`);
+    }
+    let sql = chunks[0];
+    const params = [];
+    for (let i = 0; i < node.params.length; i++) {
+        const p = node.params[i];
+        if (isMakeSQL(p)) {
+            const inner = assembleMakeSQL(p);
+            sql += inner.sql + chunks[i + 1];
+            params.push(...inner.params);
+        }
+        else {
+            sql += '?' + chunks[i + 1];
+            params.push(p);
+        }
+    }
+    return { sql, params };
+}
+/**
+ * Compose an ordered list of `makeSQL` components into one statement: concatenate the
+ * assembled `sql` of every PRESENT component and their params in order (the locked
+ * model's "present ones concatenate"). Skipped components drop entirely.
+ *
+ * Each component's `sql` already carries whatever connector text the tuned builder
+ * emits for that position, so concatenation is byte-faithful for every skip subset.
+ */
+function composeMakeSQL(nodes) {
+    let sql = '';
+    const params = [];
+    for (const node of nodes) {
+        const r = assembleMakeSQL(node);
+        sql += r.sql;
+        params.push(...r.params);
+    }
+    return { sql, params };
+}
+//# sourceMappingURL=makesql.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"makesql.js","sourceRoot":"","sources":["../../../src/scp/makesql/makesql.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAkCH,8BAOC;AAqDD,0CAwBC;AAUD,wCASC;AArID,mEAAmE;AACtD,QAAA,OAAO,GAAG,SAAkB,CAAC;AA4B1C,6FAA6F;AAC7F,SAAgB,SAAS,CAAC,CAAW;IACnC,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACV,OAAQ,CAAa,CAAC,GAAG,KAAK,QAAQ;QACtC,KAAK,CAAC,OAAO,CAAE,CAAa,CAAC,MAAM,CAAC,CACrC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACU,QAAA,mBAAmB,GAAiB;IAC/C,IAAI,EAAE,eAAO;IACb,UAAU,EAAE;QACV,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;QACvC,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;QACvB,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;KACvB;IACD,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;IAC1B,YAAY,EAAE,IAAI;CACnB,CAAC;AAEF,0DAA0D;AAC7C,QAAA,2BAA2B,GAAiC;IACvE,CAAC,eAAO,CAAC,EAAE,2BAAmB;CAC/B,CAAC;AAiBF;;;;;;;;;GASG;AACH,SAAgB,eAAe,CAAC,IAAa;IAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAEvD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,uCAAuC,MAAM,CAAC,MAAM,GAAG,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,MAAM,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC9H,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;YACjB,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;YACjC,GAAG,IAAI,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,KAAgB;IAC7C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QAChC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AACzB,CAAC"}

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

@@ -0,0 +1,47 @@
+/**
+ * litedbmodel v2 SCP — pooled async `SqlExecutorAsync` factories for PG / MySQL (#40).
+ *
+ * The read-graph async execution model (`executeReadGraphAsync`) dispatches independent sibling
+ * relations in bounded parallel via bc `runBehaviorAsync`. For that concurrency to become REAL
+ * parallel DB I/O the driver seam must be an async CONNECTION POOL — each concurrent `exec` call
+ * checks out a DISTINCT pooled connection. These factories adapt a `pg.Pool` / `mysql2` pool to the
+ * {@link SqlExecutorAsync} seam.
+ *
+ * The read graph already renders the dialect placeholder form (`$N` for postgres, `?` for
+ * MySQL/SQLite, via `renderPlaceholders`) and flattens params 1:1, so each executor is a THIN
+ * adapter — it passes the already-rendered `{ sql, params }` straight to the pool. The pool sizing
+ * should be aligned with the plan's `concurrency` (default 16) so `concurrency` sibling relations
+ * can each hold a live connection without queueing.
+ *
+ * `pg` / `mysql2` are optional peer dependencies loaded dynamically — importing this module does not
+ * force either into a consumer that only uses the sync better-sqlite3 conformance path.
+ */
+import type { SqlExecutorAsync } from './static-bundle';
+/** The minimal `pg.Pool` surface we need: `query(text, values)` resolving `{ rows }`. */
+export interface PgPoolLike {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/** The minimal `mysql2/promise` pool surface: `query(sql, values)` resolving `[rows, fields]`. */
+export interface MysqlPoolLike {
+    query(sql: string, values?: unknown[]): Promise<[Record<string, unknown>[], unknown]>;
+}
+/**
+ * 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
+ * connections in parallel. The graph renders `$N` placeholders for the `postgres` dialect, so the
+ * `sql` is already in `pg`'s native form.
+ *
+ * Recommend constructing the pool with `max` ≥ the plan's `concurrency` (default 16).
+ */
+export declare function pgPoolExecutor(pool: PgPoolLike): SqlExecutorAsync;
+/**
+ * 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).
+ */
+export declare function mysqlPoolExecutor(pool: MysqlPoolLike): SqlExecutorAsync;
+//# sourceMappingURL=pool-executor.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — pooled async `SqlExecutorAsync` factories for PG / MySQL (#40).
+ *
+ * The read-graph async execution model (`executeReadGraphAsync`) dispatches independent sibling
+ * relations in bounded parallel via bc `runBehaviorAsync`. For that concurrency to become REAL
+ * parallel DB I/O the driver seam must be an async CONNECTION POOL — each concurrent `exec` call
+ * checks out a DISTINCT pooled connection. These factories adapt a `pg.Pool` / `mysql2` pool to the
+ * {@link SqlExecutorAsync} seam.
+ *
+ * The read graph already renders the dialect placeholder form (`$N` for postgres, `?` for
+ * MySQL/SQLite, via `renderPlaceholders`) and flattens params 1:1, so each executor is a THIN
+ * adapter — it passes the already-rendered `{ sql, params }` straight to the pool. The pool sizing
+ * should be aligned with the plan's `concurrency` (default 16) so `concurrency` sibling relations
+ * can each hold a live connection without queueing.
+ *
+ * `pg` / `mysql2` are optional peer dependencies loaded dynamically — importing this module does not
+ * force either into a consumer that only uses the sync better-sqlite3 conformance path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pgPoolExecutor = pgPoolExecutor;
+exports.mysqlPoolExecutor = mysqlPoolExecutor;
+/**
+ * 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
+ * connections in parallel. The graph renders `$N` placeholders for the `postgres` dialect, so the
+ * `sql` is already in `pg`'s native form.
+ *
+ * Recommend constructing the pool with `max` ≥ the plan's `concurrency` (default 16).
+ */
+function pgPoolExecutor(pool) {
+    return async (sql, params) => {
+        const result = await pool.query(sql, params);
+        return result.rows;
+    };
+}
+/**
+ * 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).
+ */
+function mysqlPoolExecutor(pool) {
+    return async (sql, params) => {
+        const [rows] = await pool.query(sql, params);
+        return rows;
+    };
+}
+//# sourceMappingURL=pool-executor.js.map

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

@@ -0,0 +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"}

package/dist/scp/makesql/static-bundle.d.ts

@@ -0,0 +1,185 @@
+/**
+ * litedbmodel v2 SCP — the STATIC, PORTABLE `makeSQL` bundle + its runtime (epic #43/#45
+ * Phase B; design #45 owner-confirmed static-bundle decision).
+ *
+ * This is the SOLE read/compile path of the makeSQL SCP model, expressed as a compile step
+ * that is **symbolic** (no concrete input needed) and a runtime that evaluates value-specs +
+ * skip PER-INPUT via behavior-contracts. It REPLACES the reduced-spine `../runtime.ts`
+ * `SqlBundle`/`compileBundle`/`executeBundle` for the read path.
+ *
+ * ## The static bundle shape (design #45)
+ *
+ * A compiled behavior method is a bundle of ordered {@link StaticStatement} — each a
+ * `makeSQL` TEMPLATE:
+ *   - `sql`    — tuned dialect SQL text (`?` placeholders), COMPLETE and value-independent
+ *                (compiled ONCE; the single-JSON-param array forms + PG `= ANY`/UNNEST keep
+ *                the text fixed regardless of the runtime array length — no per-input text).
+ *   - `params` — value-specs = bc Expression IR (`{ref:[…]}` / small ops / literals), 1:1 with
+ *                the top-level `?`, evaluated AT RUNTIME by bc `evaluateExpression`.
+ *   - `skip?`  — a bc presence expression, evaluated at runtime; when truthy the whole
+ *                statement (its `sql` and `params`) drops (contributes NOTHING).
+ *
+ * So the compile step emits a reusable portable artifact; the runtime (this module's
+ * {@link executeStaticBundle}) evaluates skip + params per-input via bc, assembles present
+ * fragments, renders placeholders, and executes. This unifies read/write/codegen on ONE
+ * `SqlBundle` shape and enables multi-language IR-reference execution.
+ *
+ * ## Symbolic compile — reuses `authoring-compile`'s port decoding, defers evaluation
+ *
+ * Phase A's `authoring-compile.ts` compiled per-input EAGERLY (it called `evaluateExpression`
+ * on every value slot to produce concrete `{sql, params}`). Here we keep the SAME closed-set
+ * port decoding (`../bridge.ts` operators, IN-sentinel, SKIP-`cond` collapse) but DEFER the
+ * value/skip evaluation to the runtime: a where-member's value operand stays as its raw bc
+ * Expression IR, a SKIP-`cond` guard becomes the statement's `skip` expression, and the SQL
+ * text is emitted once.
+ */
+import { type Scope, type Value, type ComponentGraphIR } from 'behavior-contracts';
+import type { ComponentRefNode, MapNode, BehaviorModelContract } from '../authoring';
+import { type Dialect } from './handler';
+/** A closed-set bc Expression IR node used as a deferred value-spec or a skip expression. */
+export type ValueSpec = unknown;
+/**
+ * One statement of a static bundle — a `makeSQL` TEMPLATE. `sql` is the complete tuned SQL
+ * text (`?` placeholders, value-independent); `params` are deferred value-specs (bc
+ * Expression IR) evaluated at runtime; `skip`, when present, is a bc presence expression
+ * evaluated at runtime (truthy ⇒ drop the whole statement).
+ */
+export interface StaticStatement {
+    /** Complete tuned SQL text (`?` placeholders). */
+    readonly sql: string;
+    /** Deferred value-specs — closed-set bc Expression IR, 1:1 with the top-level `?`. */
+    readonly params: readonly ValueSpec[];
+    /** Optional bc presence expression; truthy ⇒ the whole statement drops. */
+    readonly skip?: ValueSpec;
+    /**
+     * A WHERE-clause fragment: its `sql` is a bare predicate body (no leading connector). The
+     * runtime prepends ` WHERE ` to the FIRST present fragment and ` AND ` to each later one, so
+     * a skipped fragment never leaves a dangling connector. A statement WITHOUT this flag emits
+     * its `sql` verbatim.
+     */
+    readonly whereFragment?: true;
+}
+/**
+ * The static, portable compiled artifact of ONE authored behavior method (the read path).
+ * Pure JSON — every statement's `sql` is fixed text and its `params`/`skip` are bc Expression
+ * IR, so `JSON.stringify` round-trips losslessly and a per-language runtime can execute it
+ * with bc + a SQL driver alone.
+ */
+export interface StaticBundle {
+    readonly dialect: Dialect;
+    /** The behavior (component) name. */
+    readonly name: string;
+    /** Ordered `makeSQL` statement templates composed into the read query. */
+    readonly statements: readonly StaticStatement[];
+    /** Input heads normalized to present-as-null (absent-key SKIP; SSoT-driven). */
+    readonly optionalHeads: readonly string[];
+}
+type RefLike = ComponentRefNode | MapNode;
+/**
+ * Compile ONE authored `Select` node into its static `makeSQL` statement templates:
+ * the head `SELECT … FROM t` fragment plus one guarded WHERE fragment per member, then the
+ * trailing GROUP BY / ORDER BY / LIMIT / OFFSET tail. The head + GROUP BY + ORDER BY TEXT is
+ * produced by the ORIGINAL `compileSelect` (which reproduces `_buildSelectSQL` byte-for-byte),
+ * never a v2 hand-roll. LIMIT/OFFSET are INLINE literals in v1; for the static bundle they are
+ * deferred value-specs bound as `?` (a portable equivalent a per-language runtime renders
+ * identically) — evaluated at runtime.
+ */
+export declare function compileSelectNode(node: RefLike, dialect: Dialect): StaticStatement[];
+/**
+ * Compile the primary CRUD query of an authored behavior method into a {@link StaticBundle}.
+ * Relation `.map` nodes are NOT part of the primary bundle (they are the read-relations concern
+ * — step 3, still on the reduced spine). The compile is SYMBOLIC (no concrete input); the runtime
+ * ({@link executeStaticBundle} for reads / {@link executeStaticWrite} for writes) evaluates skip +
+ * value-specs per-input.
+ */
+export declare function compileStaticBundle(contract: BehaviorModelContract, dialect: Dialect, entry?: string): StaticBundle;
+/** The minimal synchronous SQLite driver surface (better-sqlite3 `Database`). */
+export interface SqliteDb {
+    prepare(sql: string): {
+        all(...params: unknown[]): unknown[];
+        run(...params: unknown[]): {
+            changes: number;
+            lastInsertRowid: number | bigint;
+        };
+    };
+}
+/**
+ * Execute a {@link StaticBundle} read query end-to-end against real SQLite: normalize optional
+ * heads, evaluate skip + value-specs per-input, assemble present fragments, render, and run the
+ * SELECT. Returns the row list.
+ */
+export declare function executeStaticBundle(bundle: StaticBundle, input: Scope, db: SqliteDb): Record<string, unknown>[];
+/**
+ * Execute a single-statement WRITE {@link StaticBundle} (Insert/Update/Delete) against real
+ * SQLite: evaluate the deferred value-specs per-input, render, and run the statement. A statement
+ * with a RETURNING tail returns its rows; a non-returning write returns a single-row summary
+ * `[{ changes, lastInsertRowid }]`. A driver error maps to a {@link SqlFailure} at the boundary.
+ * (A Command with write-time relations rides the tx-DAG plan of `./tx`, not this path.)
+ */
+export declare function executeStaticWrite(bundle: StaticBundle, input: Scope, db: SqliteDb): Record<string, unknown>[];
+/**
+ * The compiled, portable READ graph of a behavior method: the surrogate bc `ComponentGraphIR`
+ * (each SQL node → a `makeSQL` node with one `__scope` port; wiring / map / Φ output preserved)
+ * plus the per-node static statement templates and the optional heads. Pure JSON —
+ * `JSON.stringify` round-trips, so a per-language runtime executes it with bc + a SQL driver.
+ */
+export interface ReadGraph {
+    readonly dialect: Dialect;
+    readonly name: string;
+    /** The surrogate bc IR (catalog nodes → `makeSQL` `__scope`-port nodes). */
+    readonly ir: ComponentGraphIR;
+    /** Per-node static `makeSQL` statement templates, keyed by body node id. */
+    readonly statementsById: Record<string, readonly StaticStatement[]>;
+    /** Input heads normalized to present-as-null (absent-key SKIP; SSoT-driven). */
+    readonly optionalHeads: readonly string[];
+}
+/**
+ * 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.
+ */
+export declare function compileReadGraph(contract: BehaviorModelContract, dialect: Dialect, entry?: string): ReadGraph;
+/**
+ * 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.
+ */
+export declare function executeReadGraph(graph: ReadGraph, input: Scope, db: SqliteDb): Value;
+/** An async driver seam: run a rendered `{ sql, params }` and resolve to result rows (#40). */
+export type SqlExecutorAsync = (sql: string, params: unknown[]) => Promise<Record<string, unknown>[]>;
+/**
+ * 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.
+ */
+export declare function executeReadGraphAsync(graph: ReadGraph, input: Scope, exec: SqlExecutorAsync): Promise<Value>;
+/**
+ * Convenience: compile + execute a READ behavior method whose output may be a Φ-merge of SQL
+ * nodes (including relation `.map` nodes). Equivalent to `executeReadGraph(compileReadGraph(...))`.
+ */
+export declare function executeReadBehavior(contract: BehaviorModelContract, input: Scope, dialect: Dialect, db: SqliteDb, entry?: string): Value;
+/**
+ * Render the PRIMARY read node's statements of a {@link ReadGraph} against an input scope to its
+ * dialect SQL text + bound params (the render axis for conformance golden). The primary node is
+ * the first non-map body node (the root SELECT the relations map over). Optional heads are
+ * normalized to present-as-null first (absent-key SKIP), so an omitted optional head renders the
+ * SAME text a runtime would produce.
+ */
+export declare function renderReadPrimary(graph: ReadGraph, input: Scope): {
+    sql: string;
+    params: unknown[];
+};
+export {};
+//# sourceMappingURL=static-bundle.d.ts.map

package/dist/scp/makesql/static-bundle.d.ts.map

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