litedbmodel 1.2.9 → 2.0.0

package/dist/scp/render.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — fragment-tree render + param assembly (WS1, #21).
+ *
+ * The NORMATIVE reference implementation of `docs/proposal/sql-dynamic-expansion-spec.md`.
+ * Given a compiled operation and a bound input scope, it deterministically produces the
+ * final SQLite SQL text (`?` placeholders) and the flat params array. Every multi-language
+ * runtime (WS3) must reproduce this byte-for-byte; this TS implementation is the golden
+ * reference the conformance harness pins.
+ *
+ * The three moving parts (dynamic-expansion spec):
+ *   §2 SKIP → fragment existence: a fragment with `when` is present iff `when` evaluates
+ *       to a present (non-null / true) binding; an absent fragment contributes NO SQL and
+ *       NO params.
+ *   §3 empty-WHERE degeneration: if no fragment is present the whole `{where}` splice
+ *       (including the ` WHERE ` keyword) collapses to the empty string.
+ *   §4 AND/OR structure + parenthesization: a nested tree renders `(… <connector> …)`.
+ *   §5 IN-list array expansion: a fragment slot marked `expand` turns its `(?)` into
+ *       `(?, ?, …)` for each element of the bound array (0 elements → the `1 = 0`
+ *       always-false degeneration, byte-identical to litedbmodel v1's empty-IN handling).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderOperation = renderOperation;
+const behavior_contracts_1 = require("behavior-contracts");
+const ir_1 = require("./ir");
+const dialect_1 = require("./dialect");
+/** A fragment tree carries a `connector`; a fragment carries `sql`. */
+function isTree(node) {
+    return 'connector' in node;
+}
+/**
+ * SKIP existence rule (dynamic-expansion spec §2): a fragment is present iff it is
+ * `always`, or its `when` Expression evaluates to a PRESENT binding — `null` and `false`
+ * are absent; everything else (including `0`, `""`) is present. This mirrors bc's
+ * strict-bool discipline: `when` is expected to be an explicit presence/bool Expression
+ * (e.g. `{ne:[{refOpt:["status"]}, null]}` in bc's flat scope), evaluated fail-closed by
+ * evaluateExpression.
+ */
+function fragmentPresent(f, scope) {
+    if (f.always === true)
+        return true;
+    if (f.when === undefined)
+        return false; // fail-closed: neither always nor when
+    const v = (0, behavior_contracts_1.evaluateExpression)(f.when, scope);
+    return v !== null && v !== false;
+}
+/**
+ * Render one leaf fragment's SQL + params into the accumulators. Handles IN-list
+ * expansion (spec §5): the slot at `expand` is an array; its `(?)` in `sql` becomes
+ * `(?, ?, …)` and each element is pushed as its own param.
+ */
+function renderFragment(f, scope, params) {
+    if (f.expand === undefined) {
+        for (const slot of f.params)
+            params.push((0, behavior_contracts_1.evaluateExpression)(slot, scope));
+        return f.sql;
+    }
+    // IN-list expansion. Evaluate all slots; the `expand` slot must be an array.
+    let sql = f.sql;
+    for (let i = 0; i < f.params.length; i++) {
+        const v = (0, behavior_contracts_1.evaluateExpression)(f.params[i], scope);
+        if (i === f.expand) {
+            if (!Array.isArray(v)) {
+                throw new Error(`IN-list expansion slot ${i} did not bind to an array (got ${v === null ? 'null' : typeof v})`);
+            }
+            if (v.length === 0) {
+                // Empty-array degeneration (dynamic-expansion spec §5): the whole `col IN (?)`
+                // fragment collapses to the always-false sentinel `1 = 0` — byte-identical to
+                // litedbmodel v1's DBConditions (an empty IN pushes NO params). The `col IN`
+                // prefix and the `(?)` slot are BOTH replaced.
+                sql = '1 = 0';
+                // no params pushed for this slot
+            }
+            else {
+                // Replace the single `(?)` with `(?, ?, …)` sized to the array; push each element.
+                sql = sql.replace('(?)', `(${v.map(() => '?').join(', ')})`);
+                for (const el of v)
+                    params.push(el);
+            }
+        }
+        else {
+            params.push(v);
+        }
+    }
+    return sql;
+}
+/**
+ * Render a fragment tree into a WHERE clause body (no leading ` WHERE ` keyword).
+ * Present fragments are joined by ` <connector> `; a nested tree is parenthesized
+ * (spec §4). Returns the empty string when NO fragment is present (degeneration, §3).
+ *
+ * Each fragment's `sql` already carries its own leading connector prefix when authored as
+ * a chained condition (e.g. `" AND status = ?"`), so this function STRIPS the accumulated
+ * connector from the first present fragment to avoid a dangling leading `AND`/`OR`, then
+ * joins the rest as-authored. To keep the golden output identical to litedbmodel v1 (which
+ * builds `parts.join(' AND ')` with no leading connector), fragment `sql` at the top level
+ * is authored WITHOUT a leading connector and joined here.
+ */
+function renderTree(tree, scope, params) {
+    const parts = [];
+    for (const node of tree.fragments) {
+        if (isTree(node)) {
+            const inner = renderTree(node, scope, params);
+            if (inner !== '')
+                parts.push(`(${inner})`);
+        }
+        else if (fragmentPresent(node, scope)) {
+            parts.push(renderFragment(node, scope, params));
+        }
+    }
+    if (parts.length === 0)
+        return '';
+    return parts.join(` ${tree.connector} `);
+}
+/**
+ * Render a compiled operation to final SQLite SQL + params for a bound input scope.
+ *
+ * Param order (matches SQL text order, dynamic-expansion spec §6): the compiled `sql`
+ * splices the WHERE tree at `{where}`; static params before the marker are emitted first,
+ * then the fragment params in tree order, then static params after the marker. WS1's CRUD
+ * shapes place all pre-WHERE statics (Insert values, Update SET) before `{where}` and all
+ * post-WHERE statics (LIMIT / OFFSET) after — so a single left-to-right walk of the
+ * spliced SQL yields the canonical `?` order.
+ */
+function renderOperation(op, input, dialect = dialect_1.SQLITE) {
+    const params = [];
+    const markerIdx = op.sql.indexOf(ir_1.WHERE_SLOT);
+    if (markerIdx === -1) {
+        // No dynamic WHERE: all params are static, in position order.
+        for (const slot of op.params)
+            params.push((0, behavior_contracts_1.evaluateExpression)(slot, input));
+        return { sql: finalize(op.sql, dialect), params };
+    }
+    const before = op.sql.slice(0, markerIdx);
+    const after = op.sql.slice(markerIdx + ir_1.WHERE_SLOT.length);
+    // Static params are partitioned by whether their `?` sits before or after the marker.
+    const beforeQ = countPlaceholders(before);
+    const preStatics = op.params.slice(0, beforeQ);
+    const postStatics = op.params.slice(beforeQ);
+    for (const slot of preStatics)
+        params.push((0, behavior_contracts_1.evaluateExpression)(slot, input));
+    let whereSql = '';
+    if (op.where !== null) {
+        const body = renderTree(op.where, input, params);
+        if (body !== '')
+            whereSql = ` WHERE ${body}`; // degeneration §3: drop keyword when empty
+    }
+    for (const slot of postStatics)
+        params.push((0, behavior_contracts_1.evaluateExpression)(slot, input));
+    return { sql: finalize(before + whereSql + after, dialect), params };
+}
+/**
+ * Apply the dialect's final placeholder pass over the FULLY-assembled SQL text (spec §8): for
+ * Postgres this converts `?`→`$1,$2,…` in ONE left-to-right pass (the number-reassignment
+ * problem is designed out — it runs once, after IN-list expansion + fragment splicing are all
+ * done); for SQLite/MySQL it is identity. This is the single place the `?`→`$N` conversion
+ * happens, so `params` order (already position-ordered by the walk above) matches `$N` order.
+ */
+function finalize(sql, dialect) {
+    return dialect.finalizePlaceholders(sql);
+}
+/** Count `?` placeholders in a static SQL segment (no fragment markers present). */
+function countPlaceholders(sql) {
+    let n = 0;
+    for (const ch of sql)
+        if (ch === '?')
+            n++;
+    return n;
+}
+//# sourceMappingURL=render.js.map

package/dist/scp/render.js.map

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

package/dist/scp/runtime.d.ts

@@ -0,0 +1,295 @@
+/**
+ * litedbmodel v2 SCP — the thin TS runtime (WS3, #23; spec §3 / §10 / §11).
+ *
+ * Consumes bc's runtime-core (`runBehavior` = plan stage execution + map/wire/skip
+ * propagation + Φ output assembly) and adds ONLY the SQL-backend concerns (spec §11):
+ * Backend-Compile bridge (WS1↔WS3), per-Catalog Handlers (render → driver execute →
+ * row→model assembly), and Error Mapping. It re-implements NO generic execution.
+ *
+ * ## Execution pipeline (spec §3)
+ *
+ *   validate → fragment select (SKIP) → array expand → Expression eval → bind → SQL execute
+ *   → assembly
+ *
+ * bc's `runBehavior` owns the orchestration (which node runs when, map iteration, wire
+ * binding, output merge). But the SQL-structural ports (`where` fragment tree, `limit`, …)
+ * MUST NOT go through bc's generic port evaluation — a `where` `{arr:[…]}` of comparison
+ * Expressions would evaluate to bare booleans (losing the SQL structure), and a SKIP guard
+ * over an ABSENT optional input would fail-closed with `UNKNOWN_BINDING`. So the runtime:
+ *
+ *  1. Backend-Compiles every SQL node up front ({@link import('./bridge').compileNode}) to a
+ *     WS1 `CompiledOperation` (SQL text + fragment tree + closed-set param slots).
+ *  2. Rewrites the IR into a SURROGATE graph: each SQL node keeps its `id` / wiring / `map`
+ *     shape, but its ports collapse to ONE synthetic `__scope` port — a bc `{obj:…}` that
+ *     re-exports every binding head the op references (`input` names, wire node ids, the
+ *     `map` element `as`). bc evaluates `__scope` in ITS scope (so `input`, sibling results
+ *     and the map element all resolve through bc's own machinery) and hands the plain scope
+ *     to the handler. No SQL-structural port is ever evaluated by bc.
+ *  3. Each handler renders its pre-compiled op against `ports.__scope` via WS1's normative
+ *     {@link renderOperation} (fragment select + array expand + Expression eval), binds the
+ *     params through the driver, executes REAL SQL, and returns the row list (assembly).
+ *
+ * ## Input normalization (SSoT — defaults live in the schema, not code)
+ *
+ * An OPTIONAL Input Port that the caller omits is normalized to `null` (present-as-null) so
+ * a SKIP guard `{ne:[{refOpt:[port]}, null]}` evaluates to `false` and drops its fragment —
+ * absent-key SKIP via `refOpt`. This is driven by the component's `inputPorts` schema
+ * (`required !== true` ⇒ optional), NOT an ad-hoc `?? null` in engine code: the schema is
+ * the single source of truth for which ports are optional.
+ */
+import { type Component, type Handlers, type Scope, type Value } from 'behavior-contracts';
+import type { BehaviorModelContract } from './authoring';
+import type { CompiledOperation } from './ir';
+import { SqlFailure } from './errors';
+import { type RelationDecl, type RelationOp, type RelationDriver } from './relation';
+import { type ReadOptions } from './typed-object';
+import { type TransactionPlan } from './write-plan';
+import { type TransactionResult } from './write-runtime';
+import { type EntityWritesDefinition, type LifecycleContract, type WriteLifecyclePhase } from './writes';
+import { type Dialect, type DialectName } from './dialect';
+/**
+ * The minimal synchronous SQLite driver surface the runtime needs (better-sqlite3
+ * `Database`). `all` returns the row list of a SELECT / RETURNING statement; `run` executes
+ * a non-returning write and reports `changes` + `lastInsertRowid`. In-process, synchronous
+ * — the sanctioned in-proc substitute for a docker integration DB (#23 AC).
+ */
+export interface SqliteDb {
+    prepare(sql: string): {
+        all(...params: unknown[]): unknown[];
+        run(...params: unknown[]): {
+            changes: number;
+            lastInsertRowid: number | bigint;
+        };
+        reader?: boolean;
+    };
+}
+/**
+ * Build the SQL handler registry: one handler per SQL Catalog name (spec §11 item 4).
+ *
+ * Exported so the mode-3 codegen path (WS7f) binds the IDENTICAL SQL handlers into bc's
+ * generated `bind(handlers)` accessor — the generated module bakes the surrogate IR literal and
+ * calls the SAME `runBehavior`, so pairing it with THIS handler builder makes the codegen output
+ * byte-identical to {@link executeBundle} by construction (not a parallel reimplementation).
+ */
+export declare function buildHandlers(db: SqliteDb, compiled: Record<string, CompiledOperation>, dialect: Dialect): Handlers;
+/**
+ * Normalize the caller input to `null` (present-as-null) for every OPTIONAL binding the
+ * caller omitted, so a SKIP guard using `refOpt` evaluates to `false` and drops its
+ * fragment (absent-key SKIP). "Optional" is determined from the SSoT, NOT an ad-hoc code
+ * default — a head is optional iff EITHER (a) the component's Input Port schema marks the
+ * port `required !== true`, OR (b) the head is SKIP-guarded in a compiled fragment (the
+ * SKIP fragment declares its driving input optional — spec §7). A REQUIRED, non-SKIP head
+ * that is missing is left absent so a real wiring bug surfaces loudly as bc's
+ * `UNKNOWN_BINDING` rather than being silently defaulted.
+ */
+export declare function normalizeInput(component: Component, optionalHeads: Set<string>, input: Scope): Scope;
+/** Execute options: the driver and the entry component (method) to run. */
+export interface ExecuteOptions {
+    /** The synchronous SQLite driver (better-sqlite3 `Database`). */
+    readonly db: SqliteDb;
+    /** The behavior method (component) name to run (default: the first component). */
+    readonly entry?: string;
+    /**
+     * The model's read-relation declarations (spec §4/§5). Compiled ONCE into the bundle's
+     * relation ops so the typed-object read surface ({@link read}) can batch-resolve both
+     * declarative-select and lazy relations via the SAME compiled op.
+     */
+    readonly relations?: readonly RelationDecl[];
+    /**
+     * The target SQL dialect (spec §4/§10). Defaults to `'sqlite'` (the in-process runtime seam
+     * is synchronous SQLite). A `'postgres'`/`'mysql'` bundle is Backend-Compiled dialect-tagged
+     * for the dialect golden + a language runtime; the `?`→`$N` (PG) conversion is applied at
+     * render time. The SSoT dialect strategy governs every dialect divergence.
+     */
+    readonly dialect?: DialectName;
+}
+/**
+ * The Backend-Compiled bundle of ONE behavior method (spec §8): the fully compiled SQL IR a
+ * thin per-language runtime (bc runtime-core + a SQL handler) can execute WITHOUT
+ * re-implementing litedbmodel's Backend-Compile. It is pure serializable JSON:
+ *
+ *  - `component` — the bc component's WIRING ONLY (body node ids / parent / map `over`+`as` /
+ *    `cond` / output / plan / inputPorts). The catalog nodes' original Expression-IR ports
+ *    are replaced by the surrogate `__scope` port so a consumer runtime feeds bc's
+ *    `runBehavior` the plan/map/wire orchestration with NO SQL-structural port to mis-evaluate.
+ *  - `operations` — `nodeId → CompiledOperation` (§8: `sql` with the `{where}` splice,
+ *    `where` fragment tree with existence rules, `params` static slots, `assembly`). Param
+ *    slots stay as Expression IR (`{coalesce:[…]}`, `{ref:[…]}`) so bc runtime-core owns
+ *    value/SKIP evaluation per language (they are NOT pre-evaluated to literals).
+ *  - `optionalHeads` — the input heads normalized to present-as-null (absent-key SKIP), so a
+ *    consumer runtime reproduces the same normalization from the bundle (not from TS state).
+ *
+ * `dialect` is the target SQL dialect (`'sqlite'`/`'postgres'`/`'mysql'`); the dialect axis is
+ * compiled ONCE, TS-side (spec §10). A PG bundle's `operations[*].sql` still carries `?`
+ * placeholders — the `?`→`$N` conversion is the render-time final one-pass, so the bundle stays
+ * uniform and dialect-tagged.
+ */
+export interface SqlBundle {
+    readonly irVersion: number;
+    readonly exprVersion: number;
+    readonly dialect: DialectName;
+    /** The surrogate component (wiring/plan/output only; catalog ports → `__scope`). */
+    readonly component: Component;
+    /** Backend-Compiled SQL IR per catalog node id (§8 shape). */
+    readonly operations: Record<string, CompiledOperation>;
+    /** Optional input heads normalized to present-as-null (absent-key SKIP). */
+    readonly optionalHeads: string[];
+    /**
+     * Pre-compiled read-relation batch ops (spec §8 `relation ops`), keyed by relation name.
+     * Derived ONCE (TS-side) from the model relation declarations, dialect-aware (SQLite).
+     * Pure JSON (each op's `query` is a {@link CompiledOperation}) so a thin per-language
+     * runtime gets the relation batch SQL for free (WS7). BOTH read surfaces (declarative
+     * select + lazy) resolve through these ops — the identical compiled op.
+     */
+    readonly relations: Record<string, RelationOp>;
+    /**
+     * The derived write-time-relations transaction plan (spec §6 / §8 `transaction plan`), present
+     * ONLY for a Command bundle whose base write declares an `onWrite` lifecycle. Pure JSON:
+     * ordered statements + gate-first rules + `$.entity` exposure. A WS7 runtime executes the SAME
+     * plan via {@link executeTransactionBundle} (bc-core render + a SQL handler + BEGIN/COMMIT) —
+     * no re-derivation per language (spec §6). Absent for read bundles and for Command bundles with
+     * no write-time relations (those run through the ordinary {@link executeBundle} path).
+     */
+    readonly transaction?: TransactionPlan;
+}
+/**
+ * Execute a published behavior contract (WS2 {@link BehaviorModelContract}) end-to-end:
+ * Backend-Compile every SQL node → surrogate IR → bc `runBehavior` (plan / map / wire /
+ * output) with SQL handlers → REAL SQLite execution → assembled Φ output.
+ *
+ * This is α's vertical slice: authoring → IR → Backend-Compile → thin runtime → real
+ * SQLite → assembly. The returned Value is the component's `output` (Φ merge) with each SQL
+ * node's slot filled by its executed row list.
+ *
+ * @throws {SqlFailure} a mapped driver failure re-surfaced at the boundary (a `fail`-policy
+ *   node re-throws through `runPlan` as `OP_FAILED`; the runtime unwraps it back to the
+ *   structured {@link SqlFailure} so the caller sees `kind` / `policy` / `sqliteCode`).
+ */
+export declare function executeBehavior(contract: BehaviorModelContract, input: Scope, options: ExecuteOptions): Value;
+/**
+ * Backend-Compile ONE behavior method of a contract into the serializable {@link SqlBundle}
+ * (spec §8) — the published multi-language artifact. This runs the WS1↔WS3 bridge and the
+ * surrogate rewrite ONCE, on the TS side (spec §10: the dialect axis is compiled once), and
+ * emits pure JSON: no TS runtime state is captured, so `JSON.stringify(bundle)` round-trips
+ * losslessly and a thin per-language runtime can execute it with bc runtime-core + a SQL
+ * handler alone (proven by the bundle round-trip test).
+ */
+export declare function compileBundle(contract: BehaviorModelContract, entry?: string, relations?: readonly RelationDecl[], dialectName?: DialectName): SqlBundle;
+/**
+ * Execute a {@link SqlBundle} (the §8 published artifact) end-to-end: feed bc `runBehavior`
+ * the bundle's surrogate component (plan / map / wire / output orchestration) with SQL
+ * handlers that render the bundle's `CompiledOperation`s and run REAL SQLite. This is the
+ * SAME code path a thin per-language runtime follows — it consumes ONLY the serialized
+ * bundle + bc runtime-core, never re-running litedbmodel's Backend-Compile. The bundle
+ * round-trip test parses this from JSON (no TS state) to prove self-sufficiency (WS7).
+ *
+ * @throws {SqlFailure} a mapped driver failure re-surfaced at the boundary.
+ */
+export declare function executeBundle(bundle: SqlBundle, input: Scope, options: ExecuteOptions): Value;
+/**
+ * Backend-Compile a Command method + its `entityWrites` save contract into a {@link SqlBundle}
+ * that carries the derived, gate-first write-time-relations {@link TransactionPlan} (spec §6/§8).
+ * The base write op is Backend-Compiled ONCE (the same {@link compileNode} bridge), and
+ * {@link deriveTransactionPlan} lowers the lifecycle's §6 effect arrays around it into the ordered
+ * statement list. The whole plan is pure JSON (it round-trips inside the bundle), so a WS7 runtime
+ * honors the SAME plan via {@link executeTransactionBundle} — no re-derivation.
+ *
+ * @throws if the method is not a Command, the phase lifecycle is not declared, the scope is not a
+ *   single base write, or a `$.entity.*` reference lacks a RETURNING body (all fail-closed).
+ */
+export declare function compileWriteBundle(contract: BehaviorModelContract, entry: string, writes: EntityWritesDefinition, phase: WriteLifecyclePhase, dialectName?: DialectName): SqlBundle;
+/**
+ * One member of a COMPOSITE (multi-write) Command (WS8a, #28 — spec §6 nested write / §14 tx-DAG):
+ * a named base write (its sole Insert/Update/Delete node in `entry`) carrying its OWN save-contract
+ * `effects`. A later member references an earlier member's RETURNING row via `$.ref.<name>.<field>`.
+ */
+export interface CompositeWriteEntry {
+    /** The Command method whose sole base-write node is this member's body. */
+    readonly entry: string;
+    /** The member's stable name (downstream members address its row as `$.ref.<name>.<field>`). */
+    readonly name: string;
+    /** The member's write-time-relations lifecycle for this phase (its gates/derive/edges/emits). */
+    readonly lifecycle: LifecycleContract;
+}
+/**
+ * Backend-Compile a COMPOSITE (multi-write) Command into a {@link SqlBundle} carrying ONE derived,
+ * gate-first, TOPOLOGICALLY-ORDERED transaction plan (spec §6 nested write / §14 "write-time tx DAG
+ * 導出"). Each {@link CompositeWriteEntry} contributes a named base write + its effects; a later
+ * member depends on an earlier via `$.ref.<name>.*` (e.g. a child INSERT keyed by the parent's
+ * RETURNING id). {@link deriveTransactionPlan} builds the data-dependency graph + gate-first
+ * constraint and derives the correct ordered plan (deterministic, stable tie-break; a cycle or
+ * dangling ref is ESCALATED). The plan is pure JSON — the 5 language runtimes execute it verbatim
+ * (they already bind each statement's `binds` row into scope for downstream `$.ref` resolution).
+ *
+ * @throws if an entry is missing/not a single-write node, or the DAG cannot be derived (cycle /
+ *   dangling `$.ref` / missing RETURNING on a referenced write) — all fail-closed.
+ */
+export declare function compileCompositeWriteBundle(contract: BehaviorModelContract, entries: readonly CompositeWriteEntry[], phase: WriteLifecyclePhase, dialectName?: DialectName): SqlBundle;
+/**
+ * Execute a COMPOSITE (multi-write) Command end-to-end as ONE real SQLite transaction with gate-
+ * first short-circuit + DAG-ordered statements (spec §6 / §14): Backend-Compile the members into a
+ * bundle with the derived tx-DAG plan, then run {@link executeTransactionBundle}.
+ */
+export declare function executeCompositeCommand(contract: BehaviorModelContract, entries: readonly CompositeWriteEntry[], phase: WriteLifecyclePhase, input: Scope, options: ExecuteOptions): TransactionResult;
+/**
+ * Execute a Command end-to-end as ONE real SQLite transaction with gate-first short-circuit
+ * (spec §6): Backend-Compile the Command + its save contract into a {@link SqlBundle} with a
+ * transaction plan, then run {@link executeTransactionBundle}. This is the v2 public write path
+ * ("write-time relations が自動導出 → 1 tx", spec §2.3).
+ *
+ * @throws {SqlFailure} a mapped driver failure (the transaction ROLLBACKs first).
+ */
+export declare function executeCommand(contract: BehaviorModelContract, writes: EntityWritesDefinition, phase: WriteLifecyclePhase, input: Scope, options: ExecuteOptions & {
+    readonly entry: string;
+}): TransactionResult;
+/**
+ * Execute a {@link SqlBundle}'s derived transaction plan (spec §6/§8) as ONE real SQLite
+ * transaction. This is the SAME code path a thin per-language runtime follows: it consumes ONLY
+ * the serialized {@link TransactionPlan} (pure JSON) + the render pipeline + a SQL driver, never
+ * re-deriving the plan. The bundle round-trip test parses this from JSON (no TS state) to prove
+ * WS7 self-sufficiency.
+ *
+ * @throws if the bundle carries no transaction plan (it is not a write-time-relations Command
+ *   bundle), or {@link SqlFailure} on a mapped driver failure.
+ */
+export declare function executeTransactionBundle(bundle: SqlBundle, input: Scope, options: ExecuteOptions): TransactionResult;
+/** Options for the typed-object {@link read} surface: base execution + relation read opts. */
+export interface ReadRuntimeOptions<R = Record<string, unknown>> extends ExecuteOptions, ReadOptions<R> {
+}
+/**
+ * The v2 typed-object read surface (spec §4/§5/§12): run a read behavior whose output is a
+ * row list (a Select), then wrap each raw row in a plain TYPED-OBJECT (own props = data only,
+ * NOT a DBModel instance) with read relations attached.
+ *
+ * - A relation named in `options.with` is DECLARATIVELY selected: batch-prefetched ONCE over
+ *   the whole page (staged, no N+1) and attached as an OWN prop.
+ * - Every OTHER declared relation is LAZY: a prototype getter that, on `await result.author`,
+ *   fires the SAME compiled relation op over the sibling set (batched — still no N+1).
+ * - `options.hydrate` recovers host objects (`(raw) => new Domain(raw)`) — the consumer-side
+ *   method-UX recovery. It stays in the runtime and never enters the bundle.
+ *
+ * Both surfaces share the ONE compiled relation op in the bundle (spec §5). The base row list
+ * is produced by the SAME {@link executeBundle} path (bc runtime-core + SQL handlers), so the
+ * read query itself is fully IR-driven; relations are the runtime's staged-batch concern.
+ *
+ * @throws if the behavior output is not a row list (the typed-object surface is for reads).
+ */
+export declare function read<R = Record<string, unknown>>(contract: BehaviorModelContract, input: Scope, options: ReadRuntimeOptions<R>): R[];
+/** {@link read} against an already-compiled {@link SqlBundle} (the published §8 artifact). */
+export declare function readBundle<R = Record<string, unknown>>(bundle: SqlBundle, input: Scope, options: ReadRuntimeOptions<R>): R[];
+/**
+ * Resolve ONE relation for a page of parent rows by driving bc's PLAN mechanism (spec §5:
+ * `deriveExecutionPlan` — result path → stage groups + concurrency). This is the staged-batch
+ * path: it builds a bc component with a single `map.batched` node over the parent rows and
+ * runs it through {@link runBehavior} (the SAME multi-language execution core WS7 languages
+ * use). Because the map is `batched`, bc evaluates every parent's key port and invokes the
+ * relation handler EXACTLY ONCE with `{items:[…]}` — so the relation op fires ONE batched
+ * query for the whole page (structurally no N+1, enforced by bc's batch contract). The
+ * handler runs the IDENTICAL compiled {@link RelationOp} the declarative-select and lazy
+ * surfaces use, and `into` attaches each parent's resolved child(ren).
+ *
+ * Returns the parent rows augmented with the relation under `op.name` (per cardinality).
+ */
+export declare function resolveRelationViaPlan(op: RelationOp, parents: readonly Record<string, unknown>[], db: RelationDriver): Record<string, unknown>[];
+export { SqlFailure };
+//# sourceMappingURL=runtime.d.ts.map

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

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