litedbmodel-runtime 2.0.0__py3-none-any.whl

litedbmodel_runtime/livedb_runner.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""litedbmodel SCP LIVE-DB conformance — Python runner (WS7g, #36).
+
+The Python leg of the coordinated cross-language LIVE-DB validation pass (spec §10 dialect axis).
+It loads the WS7g live-DB corpus (``conformance/vectors-livedb/livedb.json``) — the exec/tx bundles
+compiled for `postgres` + `mysql` — connects to REAL dockerized Postgres + MySQL, creates the
+needed tables in an ISOLATED per-language namespace, and runs each bundle through the SAME
+``litedbmodel_runtime`` (``execute_bundle`` / ``execute_transaction_bundle``) that the SQLite
+conformance uses — now backed by the live :class:`PostgresDriver` / :class:`MysqlDriver` seam. It
+asserts the assembled result equals the frozen SQLite reference (`expectedResult` /
+`expectedDbState`) — the §10 promise (same IR + input → same RESULT regardless of dialect).
+
+REAL DBs, no mock, NO silent skip: if PG or MySQL is unreachable the runner ERRORS OUT LOUDLY
+(exit 3) — it never passes vacuously. Connection config is env-driven (matching
+docker-compose.test.yml / the WS6 host defaults):
+
+    TEST_DB_HOST/PORT/USER/PASSWORD/NAME      (Postgres, default localhost:5433)
+    TEST_MYSQL_HOST/PORT/USER/PASSWORD/DB     (MySQL,    default localhost:3307)
+
+Emits the SAME machine-readable JSON summary the orchestrator expects as its LAST stdout line:
+    {"lang":"py-livedb","suites":{"livedb-pg":{..},"livedb-mysql":{..}},"total_pass",...}
+Exit: 0 all pass, 1 any fail, 2 corpus-version mismatch, 3 DB unreachable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+_PKG_PARENT = str(Path(__file__).resolve().parent.parent)
+if _PKG_PARENT not in sys.path:
+    sys.path.insert(0, _PKG_PARENT)
+
+from litedbmodel_runtime import (  # noqa: E402
+    MysqlDriver,
+    PostgresDriver,
+    execute_bundle,
+    execute_transaction_bundle,
+)
+
+SUPPORTED_CORPUS_VERSION = 1
+# A distinct namespace per language so 4 languages share ONE docker stack without cross-talk.
+PG_SCHEMA = os.environ.get("LIVEDB_PG_SCHEMA", "scp_py")
+MYSQL_DB = os.environ.get("LIVEDB_MYSQL_DB", "scp_py")
+
+
+def _corpus_path() -> Path:
+    env = os.environ.get("LITEDBMODEL_LIVEDB_VECTORS")
+    if env:
+        return Path(env)
+    return Path(__file__).resolve().parent.parent.parent / "conformance" / "vectors-livedb" / "livedb.json"
+
+
+def _pg_cfg() -> Dict[str, Any]:
+    return dict(
+        host=os.environ.get("TEST_DB_HOST", "localhost"),
+        port=int(os.environ.get("TEST_DB_PORT", "5433")),
+        user=os.environ.get("TEST_DB_USER", "testuser"),
+        password=os.environ.get("TEST_DB_PASSWORD", "testpass"),
+        dbname=os.environ.get("TEST_DB_NAME", "testdb"),
+    )
+
+
+def _mysql_cfg() -> Dict[str, Any]:
+    return dict(
+        host=os.environ.get("TEST_MYSQL_HOST", "localhost"),
+        port=int(os.environ.get("TEST_MYSQL_PORT", "3307")),
+        user=os.environ.get("TEST_MYSQL_USER", "testuser"),
+        password=os.environ.get("TEST_MYSQL_PASSWORD", "testpass"),
+        dbname=os.environ.get("TEST_MYSQL_DB", "testdb"),
+    )
+
+
+# ── value equality (numeric canon, mirror of vectors_runner) ───────────────────
+
+
+def _numeric_canon(x: Any) -> Any:
+    if isinstance(x, dict):
+        if len(x) == 1 and "$bigint" in x:
+            return int(x["$bigint"])
+        return {k: _numeric_canon(v) for k, v in x.items()}
+    if isinstance(x, list):
+        return [_numeric_canon(v) for v in x]
+    return x
+
+
+def _canon(x: Any) -> str:
+    return json.dumps(_numeric_canon(x), sort_keys=True, ensure_ascii=False)
+
+
+def _eq(a: Any, b: Any) -> bool:
+    return _canon(a) == _canon(b)
+
+
+def _encode(v: Any) -> Any:
+    """Encode a runtime value to pure JSON (mirror of vectors_runner.encode_value)."""
+    if isinstance(v, bool):
+        return v
+    if v is None or isinstance(v, (int, float, str)):
+        return v
+    if isinstance(v, list):
+        return [_encode(x) for x in v]
+    if isinstance(v, dict):
+        return {k: _encode(x) for k, x in v.items()}
+    return v
+
+
+# ── per-dialect table lifecycle ────────────────────────────────────────────────
+
+# The tables the corpus touches (drop order respects FK dependents-first).
+_ALL_TABLES = ["post_tags", "posts", "tags", "users", "idem", "uniq", "outbox"]
+
+
+def _reset_pg(driver: "PostgresDriver", schema: List[str]) -> None:
+    """Fresh namespace: drop the corpus tables (CASCADE) then apply the vector's DDL.
+
+    Dropping + recreating restarts SERIAL identity at 1, so the tx `entity.id` matches the SQLite
+    AUTOINCREMENT reference.
+    """
+    driver.exec_ddl([f"DROP TABLE IF EXISTS {t} CASCADE" for t in _ALL_TABLES])
+    driver.exec_ddl(list(schema))
+
+
+def _reset_mysql(driver: "MysqlDriver", schema: List[str]) -> None:
+    stmts = ["SET FOREIGN_KEY_CHECKS = 0"]
+    stmts += [f"DROP TABLE IF EXISTS {t}" for t in _ALL_TABLES]
+    stmts += ["SET FOREIGN_KEY_CHECKS = 1"]
+    driver.exec_ddl(stmts)
+    driver.exec_ddl(list(schema))
+
+
+def _run_exec(driver, bundle, vector) -> Dict[str, Any]:
+    result = _encode(execute_bundle(bundle, dict(vector["input"]), driver))
+    ok = _eq(result, vector["expectedResult"])
+    return {"ok": ok, "detail": None if ok else f"result {json.dumps(result)} != {json.dumps(vector['expectedResult'])}"}
+
+
+def _run_tx(driver, bundle, vector) -> Dict[str, Any]:
+    result = _encode(execute_transaction_bundle(bundle, dict(vector["input"]), driver))
+    result_ok = _eq(result, vector["expectedResult"])
+    state_ok = True
+    detail: List[str] = []
+    if not result_ok:
+        detail.append(f"result {json.dumps(result)} != {json.dumps(vector['expectedResult'])}")
+    for s in vector.get("expectedDbState", []) or []:
+        got = _encode(driver.prepare(s["query"]).all([]))
+        if not _eq(got, s["rows"]):
+            state_ok = False
+            detail.append(f"db-state '{s['query']}': {json.dumps(got)} != {json.dumps(s['rows'])}")
+    ok = result_ok and state_ok
+    return {"ok": ok, "detail": None if ok else "; ".join(detail)}
+
+
+def _run_dialect_leg(dialect: str, driver, reset_fn, corpus, bundle_key, schema_key) -> Dict[str, int]:
+    t = {"pass": 0, "fail": 0}
+    sys.stderr.write(f"\nlivedb-{dialect} — {len(corpus['vectors'])} vectors (real {dialect})\n")
+    for v in corpus["vectors"]:
+        reset_fn(driver, list(v[schema_key]))
+        bundle = v[bundle_key]
+        try:
+            if v["kind"] == "exec":
+                r = _run_exec(driver, bundle, v)
+            elif v["kind"] == "tx":
+                r = _run_tx(driver, bundle, v)
+            else:
+                r = {"ok": False, "detail": f"unknown kind {v['kind']}"}
+        except Exception as e:  # a live-DB failure is a vector FAILURE, never a fake pass
+            import traceback
+
+            r = {"ok": False, "detail": f"threw: {e}\n{traceback.format_exc()}"}
+        if r["ok"]:
+            t["pass"] += 1
+            sys.stderr.write(f"  ok  {v['name']}\n")
+        else:
+            t["fail"] += 1
+            sys.stderr.write(f"  XX  {v['name']}\n      {r.get('detail')}\n")
+    return t
+
+
+def main() -> int:
+    sys.stderr.write("litedbmodel SCP LIVE-DB conformance — Python runner (real PG + MySQL)\n")
+    corpus = json.loads(_corpus_path().read_text(encoding="utf-8"))
+    if corpus.get("corpusVersion") != SUPPORTED_CORPUS_VERSION:
+        sys.stderr.write(f"FAIL-CLOSED: corpusVersion {corpus.get('corpusVersion')} != {SUPPORTED_CORPUS_VERSION}\n")
+        print(json.dumps({"lang": "py-livedb", "suites": {}, "total_pass": 0, "total_fail": 0, "version_mismatch": True}))
+        return 2
+
+    # Connect (LOUD failure if unreachable — never skip).
+    try:
+        pg = PostgresDriver.connect(**_pg_cfg())
+        pg.exec_ddl([f"CREATE SCHEMA IF NOT EXISTS {PG_SCHEMA}", f"SET search_path TO {PG_SCHEMA}"])
+    except Exception as e:
+        sys.stderr.write(f"FATAL: Postgres unreachable at {_pg_cfg()['host']}:{_pg_cfg()['port']} — {e}\n")
+        return 3
+    try:
+        my = MysqlDriver.connect(**_mysql_cfg())
+        my.exec_ddl([f"CREATE DATABASE IF NOT EXISTS {MYSQL_DB}", f"USE {MYSQL_DB}"])
+    except Exception as e:
+        sys.stderr.write(f"FATAL: MySQL unreachable at {_mysql_cfg()['host']}:{_mysql_cfg()['port']} — {e}\n")
+        return 3
+
+    try:
+        pg_t = _run_dialect_leg("pg", pg, _reset_pg, corpus, "bundlePg", "schemaPg")
+        my_t = _run_dialect_leg("mysql", my, _reset_mysql, corpus, "bundleMysql", "schemaMysql")
+    finally:
+        pg.close()
+        my.close()
+
+    suites = {"livedb-pg": pg_t, "livedb-mysql": my_t}
+    total_pass = pg_t["pass"] + my_t["pass"]
+    total_fail = pg_t["fail"] + my_t["fail"]
+    sys.stderr.write(f"\n{total_pass} passed, {total_fail} failed / {total_pass + total_fail} live-DB vectors\n")
+    print(json.dumps({"lang": "py-livedb", "suites": suites, "total_pass": total_pass, "total_fail": total_fail, "version_mismatch": False}))
+    return 1 if total_fail > 0 else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

litedbmodel_runtime/render.py

@@ -0,0 +1,160 @@
+"""litedbmodel v2 SCP — fragment-tree render + param assembly (Python port of ``src/scp/render.ts``).
+
+A byte-for-byte port of the NORMATIVE dynamic-expansion reference
+(`docs/proposal/sql-dynamic-expansion-spec.md`). Given a §8 CompiledOperation and a bound input
+scope, it deterministically produces the final SQL text (`?` placeholders, or `$N` for Postgres
+via the dialect's final pass) + the flat params list — reproducing the TS `renderOperation`
+exactly. The four moving parts:
+
+  §2 SKIP → fragment existence: a fragment with `when` is present iff `when` evaluates to a
+      present (non-null / non-false) binding; an absent fragment contributes NO SQL and NO params.
+  §3 empty-WHERE degeneration: if no fragment is present the whole ` WHERE …` splice collapses.
+  §4 AND/OR structure + parenthesization: a nested tree renders `(… <connector> …)`.
+  §5 IN-list array expansion: an `expand` slot turns its `(?)` into `(?, ?, …)` per element (0
+      elements → the `1 = 0` always-false degeneration).
+
+The CLOSED Expression-IR evaluation (ref/refOpt/coalesce/eq/…) is delegated to
+behavior-contracts (`evaluate_expression`) — this module re-implements NO generic evaluator,
+exactly like the TS reference imports `evaluateExpression` from `behavior-contracts`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Mapping
+
+from behavior_contracts import evaluate_expression
+
+from .dialect import Dialect, SQLITE
+
+# The literal `{where}` splice marker inside CompiledOperation.sql (spec §8 / ir.ts WHERE_SLOT).
+WHERE_SLOT = "{where}"
+
+
+class RenderedSql:
+    """The result of rendering: final SQL text + flat params (1:1 with `?`)."""
+
+    __slots__ = ("sql", "params")
+
+    def __init__(self, sql: str, params: List[Any]) -> None:
+        self.sql = sql
+        self.params = params
+
+
+def _is_tree(node: Mapping[str, Any]) -> bool:
+    """A fragment tree carries a `connector`; a leaf fragment carries `sql`."""
+    return "connector" in node
+
+
+def _fragment_present(fragment: Mapping[str, Any], scope: Mapping[str, Any]) -> bool:
+    """SKIP existence (spec §2): present iff `always`, or `when` evaluates truthy-present.
+
+    `null` and `false` are absent; everything else (including `0`, `""`) is present — mirroring
+    the TS `fragmentPresent`. `when` is an explicit presence/bool Expression evaluated fail-closed
+    by bc's `evaluate_expression`. Neither `always` nor `when` set ⇒ fail-closed absent.
+    """
+    if fragment.get("always") is True:
+        return True
+    if "when" not in fragment:
+        return False  # fail-closed: neither always nor when
+    v = evaluate_expression(fragment["when"], scope)
+    return v is not None and v is not False
+
+
+def _render_fragment(fragment: Mapping[str, Any], scope: Mapping[str, Any], params: List[Any]) -> str:
+    """Render one leaf fragment's SQL + params into the accumulator (IN-list expansion, §5)."""
+    expand = fragment.get("expand")
+    frag_params = fragment["params"]
+    if expand is None:
+        for slot in frag_params:
+            params.append(evaluate_expression(slot, scope))
+        return fragment["sql"]
+
+    # IN-list expansion. Evaluate all slots; the `expand` slot must be an array.
+    sql = fragment["sql"]
+    for i, slot in enumerate(frag_params):
+        v = evaluate_expression(slot, scope)
+        if i == expand:
+            if not isinstance(v, list):
+                kind = "null" if v is None else type(v).__name__
+                raise ValueError(
+                    f"IN-list expansion slot {i} did not bind to an array (got {kind})"
+                )
+            if len(v) == 0:
+                # Empty-array degeneration (spec §5): `col IN (?)` collapses to the always-false
+                # sentinel `1 = 0`. No params pushed for this slot. Byte-identical to TS/v1.
+                sql = "1 = 0"
+            else:
+                # Replace the single `(?)` with `(?, ?, …)`; push each element.
+                sql = sql.replace("(?)", "(" + ", ".join("?" for _ in v) + ")", 1)
+                for el in v:
+                    params.append(el)
+        else:
+            params.append(v)
+    return sql
+
+
+def _render_tree(tree: Mapping[str, Any], scope: Mapping[str, Any], params: List[Any]) -> str:
+    """Render a fragment tree into a WHERE body (no leading ` WHERE `). Empty when none present (§3)."""
+    parts: List[str] = []
+    for node in tree["fragments"]:
+        if _is_tree(node):
+            inner = _render_tree(node, scope, params)
+            if inner != "":
+                parts.append(f"({inner})")
+        elif _fragment_present(node, scope):
+            parts.append(_render_fragment(node, scope, params))
+    if not parts:
+        return ""
+    return (f" {tree['connector']} ").join(parts)
+
+
+def _count_placeholders(sql: str) -> int:
+    """Count `?` placeholders in a static SQL segment (no fragment markers present)."""
+    return sql.count("?")
+
+
+def render_operation(
+    operation: Mapping[str, Any],
+    input_scope: Mapping[str, Any],
+    dialect: Dialect = SQLITE,
+) -> RenderedSql:
+    """Render a §8 CompiledOperation to final SQL + params for a bound input scope.
+
+    Byte-for-byte port of the TS `renderOperation`. Param order matches SQL text order (spec §6):
+    pre-WHERE statics, then fragment params in tree order, then post-WHERE statics. A single
+    left-to-right walk of the spliced SQL yields the canonical placeholder order; the dialect's
+    `finalize_placeholders` applies the `?`→`$N` pass ONCE over the fully-assembled text.
+    """
+    params: List[Any] = []
+    op_sql = operation["sql"]
+    op_params = operation["params"]
+    marker_idx = op_sql.find(WHERE_SLOT)
+
+    if marker_idx == -1:
+        # No dynamic WHERE: all params are static, in position order.
+        for slot in op_params:
+            params.append(evaluate_expression(slot, input_scope))
+        return RenderedSql(dialect.finalize_placeholders(op_sql), params)
+
+    before = op_sql[:marker_idx]
+    after = op_sql[marker_idx + len(WHERE_SLOT):]
+
+    # Static params are partitioned by whether their `?` sits before or after the marker.
+    before_q = _count_placeholders(before)
+    pre_statics = op_params[:before_q]
+    post_statics = op_params[before_q:]
+
+    for slot in pre_statics:
+        params.append(evaluate_expression(slot, input_scope))
+
+    where_sql = ""
+    where_tree = operation.get("where")
+    if where_tree is not None:
+        body = _render_tree(where_tree, input_scope, params)
+        if body != "":
+            where_sql = f" WHERE {body}"  # degeneration §3: drop keyword when empty
+
+    for slot in post_statics:
+        params.append(evaluate_expression(slot, input_scope))
+
+    return RenderedSql(dialect.finalize_placeholders(before + where_sql + after), params)

litedbmodel_runtime/runtime.py

@@ -0,0 +1,282 @@
+"""litedbmodel SCP Python runtime — the §8 bundle interpreter (WS7b, #31).
+
+The thin Python leg of the multi-language SCP runtime. It consumes the language-neutral §8
+published :class:`SqlBundle` (pure JSON: `sql` + fragment tree + closed-set Expression-IR param
+slots + optional transaction plan, dialect-tagged) and executes it against a SQL driver —
+SEMANTICS-IDENTICAL to the TS reference (``src/scp/runtime.ts`` + ``write-runtime.ts``).
+
+It re-implements NO generic execution/expression evaluation: bc's ``run_behavior`` owns the
+plan/map/wire/output orchestration and its ``evaluate_expression`` owns the CLOSED Expression-IR
+(ref/refOpt/coalesce/eq/…, the SKIP guards + param slots). This module adds ONLY the SQL-backend
+concerns (spec §11): render the pre-compiled op per dialect (``render_operation``) → bind params
+→ execute REAL SQL → row→result assembly; and, for a Command bundle, the gate-first write
+transaction (``execute_transaction_bundle``). This mirrors the TS runtime's division of labor
+exactly (bc-core + a SQL handler).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List, Mapping, Optional
+
+from behavior_contracts import run_behavior
+
+from .dialect import Dialect, dialect_for
+from .driver import Driver
+from .errors import SqlFailure, map_sqlite_error
+from .render import render_operation
+
+# The synthetic port that carries a SQL node's render scope (mirrors TS SCOPE_PORT).
+SCOPE_PORT = "__scope"
+# The reserved binding the body write's RETURNING row is exposed under (mirrors TS ENTITY_ROOT).
+ENTITY_ROOT = "__entity"
+
+_RETURNING_RE = re.compile(r"\breturning\b", re.IGNORECASE)
+
+
+# ── Value normalization at the SQL boundary ───────────────────────────────────
+
+
+def _to_driver_param(v: Any) -> Any:
+    """Convert a rendered param to a driver-bindable value (mirrors TS toDriverParam).
+
+    bc evaluates integers to plain Python `int` (not bigint), so no bigint narrowing is needed;
+    a bool is left as-is (sqlite3 binds it as 0/1, matching better-sqlite3). An object/dict is an
+    emit payload (`{obj:…}`) serialized to compact JSON for a text column — byte-identical to the
+    TS `JSON.stringify` (no spaces). Lists are IN-list elements handled during expansion, never
+    reaching here as a single param on the write path; pass through.
+    """
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, dict):
+        # Compact separators to match JS JSON.stringify (`{"a":1,"b":2}`, no spaces).
+        return json.dumps(v, separators=(",", ":"), ensure_ascii=False)
+    return v
+
+
+def _is_return_stmt(op: Mapping[str, Any], sql: str) -> bool:
+    """A SELECT or a write with RETURNING yields rows (mirrors TS hasReturn)."""
+    return op.get("component") == "Select" or bool(_RETURNING_RE.search(sql))
+
+
+# ── Handler: render → execute → assembly ──────────────────────────────────────
+
+
+def _execute_rendered(
+    driver: Driver,
+    op: Mapping[str, Any],
+    scope: Mapping[str, Any],
+    dialect: Dialect,
+) -> Mapping[str, Any]:
+    """Render + execute one op; return a bc ExecOutcome (`{ok}` / `{error}`). Mirrors TS."""
+    rendered = render_operation(op, scope, dialect)
+    params = [_to_driver_param(p) for p in rendered.params]
+    try:
+        stmt = driver.prepare(rendered.sql)
+    except Exception as e:  # driver error at prepare → mapped {error}
+        return {"error": map_sqlite_error(e).args[0] if e.args else str(e)}
+    try:
+        if _is_return_stmt(op, rendered.sql):
+            rows = stmt.all(params)
+            return {"ok": rows}
+        info = stmt.run(params)
+        # A non-returning write returns the RETURNING-less single-row summary shape.
+        return {"ok": [{"changes": info.changes, "lastInsertRowid": info.last_insert_rowid}]}
+    except Exception as e:
+        return {"error": str(map_sqlite_error(e))}
+
+
+def _build_handlers(
+    driver: Driver,
+    operations: Mapping[str, Any],
+    dialect: Dialect,
+):
+    """Build the SQL handler registry: one handler per SQL Catalog name (spec §11 item 4)."""
+
+    def handle(ports: Mapping[str, Any], ctx: Mapping[str, Any]) -> Mapping[str, Any]:
+        node_id = ctx["nodeId"]
+        op = operations.get(node_id)
+        if op is None:
+            return {"error": f"scp runtime: no compiled operation for node '{node_id}' ({ctx.get('component')})"}
+        scope = ports.get(SCOPE_PORT)
+        if not isinstance(scope, dict):
+            return {"error": f"scp runtime: node '{node_id}' surrogate scope did not evaluate to an object"}
+        return _execute_rendered(driver, op, scope, dialect)
+
+    return {"Select": handle, "Insert": handle, "Update": handle, "Delete": handle}
+
+
+# ── Input normalization (schema-driven — SSoT, no ad-hoc code default) ─────────
+
+
+def _normalize_input(
+    component: Mapping[str, Any],
+    optional_heads: List[str],
+    input_scope: Mapping[str, Any],
+) -> Dict[str, Any]:
+    """Normalize omitted OPTIONAL bindings to present-as-null (mirrors TS normalizeInput).
+
+    "Optional" comes from the SSoT: EITHER the component's Input Port schema marks the port
+    `required != True`, OR the head is listed in the bundle's `optionalHeads` (a SKIP-guarded /
+    refOpt head the TS compile derived). A REQUIRED, non-optional missing head is left absent so a
+    real wiring bug surfaces loudly as bc's UNKNOWN_BINDING — never silently defaulted.
+    """
+    out = dict(input_scope)
+    for port, schema in component.get("inputPorts", {}).items():
+        if schema.get("required") is not True and port not in out:
+            out[port] = None
+    for head in optional_heads:
+        if head not in out:
+            out[head] = None
+    return out
+
+
+# ── Public runtime entrypoints ────────────────────────────────────────────────
+
+
+def render_operation_bundle(operation: Mapping[str, Any], scope: Mapping[str, Any], dialect_name: str) -> Dict[str, Any]:
+    """Render a §8 CompiledOperation → {"sql", "params"} for a dialect name (render axis API)."""
+    rendered = render_operation(operation, scope, dialect_for(dialect_name))
+    return {"sql": rendered.sql, "params": rendered.params}
+
+
+def execute_bundle(bundle: Mapping[str, Any], input_scope: Mapping[str, Any], driver: Driver) -> Any:
+    """Execute a §8 read/exec SqlBundle end-to-end (bc run_behavior + SQL handlers).
+
+    The SAME code path a consumer runtime follows: it consumes ONLY the serialized bundle + bc
+    runtime-core, never re-running litedbmodel's Backend-Compile. Returns the component's `output`
+    (Φ merge) with each SQL node's slot filled by its executed row list — byte-identical to the TS
+    `executeBundle`.
+    """
+    surrogate = bundle["component"]
+    ir = {
+        "irVersion": bundle["irVersion"],
+        "exprVersion": bundle["exprVersion"],
+        "components": [surrogate],
+    }
+    handlers = _build_handlers(driver, bundle["operations"], dialect_for(bundle["dialect"]))
+    normalized = _normalize_input(surrogate, list(bundle.get("optionalHeads", [])), input_scope)
+    try:
+        return run_behavior(ir, handlers, normalized, surrogate["name"])
+    except Exception as e:
+        raise _re_error_to_sql_failure(e)
+
+
+# ── Write-time relations: gate-first transaction (spec §6 — port of write-runtime.ts) ──
+
+
+def _gate_short_circuit(gate: str, rows: List[Dict[str, Any]], changes: int) -> Optional[str]:
+    """Evaluate a gate rule on a statement result → short-circuit reason, or None to continue."""
+    if gate == "existsElseRollback":
+        return "requires_absent" if len(rows) == 0 else None
+    if gate == "insertedElseRollback":
+        return "unique_collision" if changes == 0 else None
+    if gate == "insertedElseNoop":
+        return "idempotent_duplicate" if changes == 0 else None
+    raise ValueError(f"scp write: unknown gate rule '{gate}'")
+
+
+def _exec_statement(
+    driver: Driver,
+    op: Mapping[str, Any],
+    scope: Mapping[str, Any],
+    dialect: Dialect,
+):
+    """Render + execute one tx statement; return (rows, changes). Mirrors TS execStatement."""
+    rendered = render_operation(op, scope, dialect)
+    params = [_to_driver_param(p) for p in rendered.params]
+    stmt = driver.prepare(rendered.sql)
+    if _is_return_stmt(op, rendered.sql):
+        rows = stmt.all(params)
+        return rows, len(rows)
+    info = stmt.run(params)
+    return [], info.changes
+
+
+def execute_transaction_bundle(bundle: Mapping[str, Any], input_scope: Mapping[str, Any], driver: Driver) -> Dict[str, Any]:
+    """Execute a §8 SqlBundle's derived transaction plan as ONE real transaction (gate-first).
+
+    Byte-for-byte port of the TS `executeTransactionBundle` → `executeTransaction` (spec §6):
+    statements run in the plan's fixed order (requires → idempotency → unique → body → derive →
+    edges → emits); a failing gate ROLLBACKs and the tail never executes. On success COMMITs and
+    returns the `$.entity` RETURNING row. A short-circuit returns `committed:false` (a legitimate
+    gate outcome), NOT a raised failure; a driver failure ROLLBACKs then raises a mapped SqlFailure.
+    """
+    plan = bundle.get("transaction")
+    if plan is None:
+        raise ValueError("scp write: this bundle carries no transaction plan (not a write-time-relations Command bundle)")
+    dialect = dialect_for(bundle["dialect"])
+
+    driver.prepare("BEGIN").run([])
+    executed: List[str] = []
+    scope: Dict[str, Any] = dict(input_scope)
+    entity: Optional[Dict[str, Any]] = None
+
+    try:
+        for stmt in plan["statements"]:
+            rows, changes = _exec_statement(driver, stmt["op"], scope, dialect)
+            executed.append(stmt["id"])
+
+            gate = stmt.get("gate")
+            if gate is not None:
+                reason = _gate_short_circuit(gate, rows, changes)
+                if reason is not None:
+                    driver.prepare("ROLLBACK").run([])
+                    return {
+                        "committed": False,
+                        "shortCircuit": {"statementId": stmt["id"], "reason": reason},
+                        "entity": None,
+                        "executed": executed,
+                    }
+
+            if stmt["id"] == plan.get("entityFrom"):
+                entity = rows[0] if rows else None
+                if entity is not None:
+                    scope[ENTITY_ROOT] = entity
+
+            # WS8a composite: bind THIS statement's RETURNING row under its `binds` name so a later
+            # `$.ref.<binds>.<field>` resolves against it (the tx-DAG data-dependency edge). Self-
+            # describing — the runtime binds the row the plan told it to; no re-derivation.
+            binds = stmt.get("binds")
+            if binds is not None and rows:
+                scope[binds] = rows[0]
+
+        driver.prepare("COMMIT").run([])
+        result: Dict[str, Any] = {"committed": True, "entity": entity, "executed": executed}
+        return result
+    except SqlFailure:
+        _safe_rollback(driver)
+        raise
+    except Exception as e:
+        _safe_rollback(driver)
+        raise map_sqlite_error(e)
+
+
+def _safe_rollback(driver: Driver) -> None:
+    try:
+        driver.prepare("ROLLBACK").run([])
+    except Exception:
+        pass  # best-effort; the original failure is surfaced by the caller
+
+
+# ── Dialect primitive (render axis + dialect suite) ────────────────────────────
+
+
+def order_by_nulls(expr: str, direction: str, nulls: str, dialect_name: str) -> str:
+    """The dialect NULLS-ordering primitive (native for PG/SQLite, IS NULL for MySQL)."""
+    return dialect_for(dialect_name).order_by_nulls(expr, direction, nulls)
+
+
+# ── Error re-surfacing (mirrors TS reErrorToSqlFailure) ────────────────────────
+
+
+def _re_error_to_sql_failure(e: Exception) -> Exception:
+    """Re-surface a structured SqlFailure from a bc OP_FAILED whose message embeds a SQLITE_ code."""
+    if isinstance(e, SqlFailure):
+        return e
+    message = str(e)
+    m = re.search(r"(SQLITE_[A-Z_]+)", message)
+    if m:
+        return map_sqlite_error(Exception(message))
+    return e