litedbmodel-runtime 2.0.0__tar.gz

litedbmodel_runtime-2.0.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: litedbmodel-runtime
+Version: 2.0.0
+Summary: Thin multi-language runtime for litedbmodel v2 SCP §8 bundles (Python port). Interprets the published SqlBundle (sql + fragment tree + Expression-IR param slots + transaction plan, dialect-tagged) and executes it against a SQL driver — semantics-identical to the TS reference. Delegates Expression-IR evaluation to behavior-contracts.
+Author: foo-ogawa
+License: MIT
+Keywords: orm,sql,ir,runtime,conformance,litedbmodel
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: behavior-contracts==0.2.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: livedb
+Requires-Dist: psycopg[binary]>=3.1; extra == "livedb"
+Requires-Dist: pymysql>=1.1; extra == "livedb"
+
+# litedbmodel-runtime (Python)
+
+The Python leg of the litedbmodel v2 SCP multi-language runtime. Interprets the language-neutral
+§8 published bundle (`SqlBundle`) and executes it against a DB-API SQL driver,
+semantics-identical to the TS reference (`src/scp`).
+
+**Status: WS7a scaffold.** The buildable package skeleton + the conformance runner entry point are
+here; the runtime body (render / execute / transaction) is **WS7b**.
+
+## behavior-contracts dependency
+
+The runtime delegates the CLOSED Expression-IR evaluation to the shared common core
+[`behavior-contracts`](https://pypi.org/project/behavior-contracts/) — **consumed from PyPI**
+(`behavior-contracts==0.2.0`), exactly as the TS reference imports it from npm. No local path
+dependency (the `check-no-local-deps` gate forbids `../`-escaping deps).
+
+## Layout
+
+```
+python/
+  pyproject.toml                       # PyPI package (litedbmodel-runtime), version-synced from package.json
+  litedbmodel_runtime/
+    __init__.py
+    runtime.py                         # WS7b: the §8 bundle interpreter surface
+    vectors_runner.py                  # conformance runner entry (WS7b body)
+  tests/                               # WS7b runtime tests
+```

litedbmodel_runtime-2.0.0/README.md

@@ -0,0 +1,27 @@
+# litedbmodel-runtime (Python)
+
+The Python leg of the litedbmodel v2 SCP multi-language runtime. Interprets the language-neutral
+§8 published bundle (`SqlBundle`) and executes it against a DB-API SQL driver,
+semantics-identical to the TS reference (`src/scp`).
+
+**Status: WS7a scaffold.** The buildable package skeleton + the conformance runner entry point are
+here; the runtime body (render / execute / transaction) is **WS7b**.
+
+## behavior-contracts dependency
+
+The runtime delegates the CLOSED Expression-IR evaluation to the shared common core
+[`behavior-contracts`](https://pypi.org/project/behavior-contracts/) — **consumed from PyPI**
+(`behavior-contracts==0.2.0`), exactly as the TS reference imports it from npm. No local path
+dependency (the `check-no-local-deps` gate forbids `../`-escaping deps).
+
+## Layout
+
+```
+python/
+  pyproject.toml                       # PyPI package (litedbmodel-runtime), version-synced from package.json
+  litedbmodel_runtime/
+    __init__.py
+    runtime.py                         # WS7b: the §8 bundle interpreter surface
+    vectors_runner.py                  # conformance runner entry (WS7b body)
+  tests/                               # WS7b runtime tests
+```

litedbmodel_runtime-2.0.0/litedbmodel_runtime/__init__.py

@@ -0,0 +1,60 @@
+"""litedbmodel v2 SCP — Python runtime (WS7b, #31).
+
+The Python leg of the multi-language SCP runtime. It interprets the language-neutral §8 published
+bundle (``SqlBundle``: sql text + fragment tree + closed-set Expression-IR param slots +
+transaction plan, dialect-tagged) and executes it against a SQL driver, semantics-identical to
+the TS reference (``src/scp``). The generic Expression-IR evaluation (SKIP guards, param slots)
+and the plan/map/wire/output orchestration are delegated to the shared common core
+``behavior-contracts`` (PyPI) — this package re-implements NO generic evaluator, only the
+SQL-backend concerns (render → bind → execute → assembly + gate-first transaction), exactly like
+the TS runtime.
+"""
+
+from __future__ import annotations
+
+from .dialect import SQLITE, POSTGRES, MYSQL, Dialect, dialect_for, to_dollar_placeholders
+from .driver import Driver, MysqlDriver, PostgresDriver, PreparedStatement, RunInfo, SqliteDriver
+from .errors import SqlFailure, map_sqlite_error
+from .render import RenderedSql, WHERE_SLOT, render_operation
+from .runtime import (
+    ENTITY_ROOT,
+    SCOPE_PORT,
+    execute_bundle,
+    execute_transaction_bundle,
+    order_by_nulls,
+    render_operation_bundle,
+)
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "__version__",
+    # dialect
+    "SQLITE",
+    "POSTGRES",
+    "MYSQL",
+    "Dialect",
+    "dialect_for",
+    "to_dollar_placeholders",
+    # driver seam
+    "Driver",
+    "PreparedStatement",
+    "RunInfo",
+    "SqliteDriver",
+    "PostgresDriver",
+    "MysqlDriver",
+    # errors
+    "SqlFailure",
+    "map_sqlite_error",
+    # render
+    "RenderedSql",
+    "WHERE_SLOT",
+    "render_operation",
+    "render_operation_bundle",
+    # runtime
+    "ENTITY_ROOT",
+    "SCOPE_PORT",
+    "execute_bundle",
+    "execute_transaction_bundle",
+    "order_by_nulls",
+]

litedbmodel_runtime-2.0.0/litedbmodel_runtime/dialect.py

@@ -0,0 +1,99 @@
+"""litedbmodel v2 SCP — dialect strategy table (Python port of ``src/scp/dialect.ts``).
+
+The SINGLE SOURCE OF TRUTH for every SQL-dialect difference the render pipeline needs, ported
+byte-for-byte from the TS reference (spec §4/§5/§8/§10). The dialect axis is compiled ONCE
+TS-side; the published bundle carries `?` placeholders and a `dialect` tag, and this module only
+needs the render-time concerns a thin runtime touches:
+
+  - ``finalize_placeholders`` — the `?`→`$N` final one-pass (Postgres only; SQLite/MySQL identity).
+  - ``order_by_nulls`` — deterministic NULLS ordering (native for PG/SQLite, `IS NULL` emulation
+    for MySQL) — the WS6-flagged dialect primitive exercised by the conformance `dialect` suite.
+
+The INSERT-conflict / guard-INSERT strategy methods are NOT needed by the runtime: those are a
+compile-time concern (the published bundle's `operations[*].sql` already carries the fully
+rendered conflict clause — e.g. `ON CONFLICT DO NOTHING`), so the runtime never re-derives them.
+This mirrors the TS runtime, which likewise only calls `finalizePlaceholders` / `orderByNulls`.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict
+
+# Known dialects (spec §4 breadth: PG/MySQL/SQLite).
+DIALECT_NAMES = ("sqlite", "postgres", "mysql")
+
+
+def to_dollar_placeholders(sql: str) -> str:
+    """Replace each `?` with `$1, $2, …` left-to-right (Postgres §8 final one-pass).
+
+    Byte-identical to the TS `toDollarPlaceholders`: it runs ONCE over the fully-assembled,
+    param-flattened SQL text, so placeholder numbering is a plain running counter (the
+    number-reassignment problem cannot reappear). Every `?` on the compiled surface is a bound
+    param position — the render pipeline never emits a literal `?` inside a string literal.
+    """
+    n = 0
+    out = []
+    for ch in sql:
+        if ch == "?":
+            n += 1
+            out.append(f"${n}")
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def _identity(sql: str) -> str:
+    return sql
+
+
+def _order_by_nulls_native(expr: str, direction: str, nulls: str) -> str:
+    # Postgres / SQLite (3.30+): native `NULLS FIRST/LAST`.
+    return f"{expr} {direction} NULLS {nulls}"
+
+
+def _order_by_nulls_mysql(expr: str, direction: str, nulls: str) -> str:
+    # MySQL has no NULLS FIRST/LAST — emulate with a leading `IS NULL` sort key.
+    # In MySQL NULL sorts LOWEST; `expr IS NULL` is 1 for null, 0 otherwise.
+    #   NULLS FIRST: nulls must come first → order the IS-NULL flag DESC (1 before 0).
+    #   NULLS LAST:  nulls must come last  → order the IS-NULL flag ASC  (0 before 1).
+    flag_dir = "DESC" if nulls == "FIRST" else "ASC"
+    return f"{expr} IS NULL {flag_dir}, {expr} {direction}"
+
+
+class Dialect:
+    """A frozen dialect strategy: the render-time text producers a thin runtime consumes."""
+
+    __slots__ = ("name", "_finalize", "_order_by_nulls")
+
+    def __init__(
+        self,
+        name: str,
+        finalize: Callable[[str], str],
+        order_by_nulls: Callable[[str, str, str], str],
+    ) -> None:
+        self.name = name
+        self._finalize = finalize
+        self._order_by_nulls = order_by_nulls
+
+    def finalize_placeholders(self, sql: str) -> str:
+        return self._finalize(sql)
+
+    def order_by_nulls(self, expr: str, direction: str, nulls: str) -> str:
+        return self._order_by_nulls(expr, direction, nulls)
+
+
+SQLITE = Dialect("sqlite", _identity, _order_by_nulls_native)
+POSTGRES = Dialect("postgres", to_dollar_placeholders, _order_by_nulls_native)
+MYSQL = Dialect("mysql", _identity, _order_by_nulls_mysql)
+
+_DIALECTS: Dict[str, Dialect] = {"sqlite": SQLITE, "postgres": POSTGRES, "mysql": MYSQL}
+
+
+def dialect_for(name: str) -> Dialect:
+    """Resolve a dialect name to its strategy (fail-closed — no silent default)."""
+    d = _DIALECTS.get(name)
+    if d is None:
+        raise ValueError(
+            f"scp dialect: unknown dialect '{name}' (known: {', '.join(_DIALECTS)})"
+        )
+    return d

litedbmodel_runtime-2.0.0/litedbmodel_runtime/driver.py

@@ -0,0 +1,252 @@
+"""litedbmodel v2 SCP — SQL driver seam (WS7b).
+
+The minimal synchronous SQL-driver surface the runtime needs, mirroring the TS `SqliteDb`
+seam (`prepare(sql).all(...) / .run(...)`). The conformance bar executes against an in-process
+stdlib ``sqlite3`` connection (:class:`SqliteDriver`) — the sanctioned in-proc substitute for a
+docker integration DB (#31 AC; live PG/MySQL is deferred to a coordinated cross-language docker
+pass). A psycopg / mysql-connector driver plugs into this SAME abstract seam later: implement
+:class:`Driver.prepare` returning a :class:`PreparedStatement` (`all` / `run`) over the
+paramstyle the bundle's dialect emits (`$N` for Postgres, `?`/`%s` for MySQL) — no runtime change.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from typing import Any, Dict, List, Optional, Protocol, Sequence
+
+
+class RunInfo:
+    """The summary of a non-returning write: affected-row count + last insert rowid."""
+
+    __slots__ = ("changes", "last_insert_rowid")
+
+    def __init__(self, changes: int, last_insert_rowid: int) -> None:
+        self.changes = changes
+        self.last_insert_rowid = last_insert_rowid
+
+
+class PreparedStatement(Protocol):
+    """A prepared statement: `all` returns the row list (SELECT/RETURNING); `run` a write summary."""
+
+    def all(self, params: Sequence[Any]) -> List[Dict[str, Any]]: ...
+
+    def run(self, params: Sequence[Any]) -> RunInfo: ...
+
+
+class Driver(Protocol):
+    """The synchronous SQL-driver seam (mirrors the TS `SqliteDb`)."""
+
+    def prepare(self, sql: str) -> PreparedStatement: ...
+
+
+class _SqlitePrepared:
+    """A prepared statement over a stdlib ``sqlite3`` connection."""
+
+    __slots__ = ("_conn", "_sql")
+
+    def __init__(self, conn: "sqlite3.Connection", sql: str) -> None:
+        self._conn = conn
+        self._sql = sql
+
+    def all(self, params: Sequence[Any]) -> List[Dict[str, Any]]:
+        cur = self._conn.execute(self._sql, tuple(params))
+        cols = [c[0] for c in cur.description] if cur.description is not None else []
+        rows = [dict(zip(cols, r)) for r in cur.fetchall()]
+        cur.close()
+        return rows
+
+    def run(self, params: Sequence[Any]) -> RunInfo:
+        cur = self._conn.execute(self._sql, tuple(params))
+        changes = cur.rowcount if cur.rowcount is not None else 0
+        last = cur.lastrowid if cur.lastrowid is not None else 0
+        cur.close()
+        return RunInfo(changes, last)
+
+
+class SqliteDriver:
+    """An in-process stdlib ``sqlite3`` driver implementing the :class:`Driver` seam.
+
+    This is the runnable conformance seam: it binds `?` placeholders positionally, so a
+    Postgres-tagged bundle's `$N` text is NOT what runs here — the exec/tx vectors run only the
+    SQLite-tagged bundles (the §10 promise: same IR + input → same RESULT regardless of dialect
+    text). PG/MySQL SQL-text conformance is proven on the render axis; live PG/MySQL execution is
+    the coordinated docker pass.
+    """
+
+    __slots__ = ("conn",)
+
+    def __init__(self, conn: "sqlite3.Connection") -> None:
+        self.conn = conn
+
+    @classmethod
+    def in_memory(cls, schema: Sequence[str]) -> "SqliteDriver":
+        conn = sqlite3.connect(":memory:")
+        conn.execute("PRAGMA foreign_keys = ON")
+        for stmt in schema:
+            conn.execute(stmt)
+        conn.commit()
+        return cls(conn)
+
+    def prepare(self, sql: str) -> _SqlitePrepared:
+        return _SqlitePrepared(self.conn, sql)
+
+    def close(self) -> None:
+        self.conn.close()
+
+
+# ── Live PostgreSQL / MySQL drivers (WS7g, #36) ────────────────────────────────
+#
+# The SAME synchronous `Driver` seam, now backed by REAL psycopg (Postgres) / PyMySQL (MySQL)
+# connections — proving the deferred live-DB execution axis (spec §10 dialect axis). The runtime
+# is UNCHANGED: it renders the dialect-tagged bundle (Postgres → `$N`, MySQL → `?`), binds the
+# rendered params positionally, and calls `prepare(sql).all(...)` / `.run(...)`. Each live driver
+# adapts the rendered placeholder text to its DB's native paramstyle (both DB-API drivers here use
+# `%s`), and MySQL emulates the missing `RETURNING` at this seam (strip → execute → re-select the
+# inserted PK) — the sanctioned dialect-behavior-by-convention (mirrors the WS6 TS ScpDialect).
+#
+# The transaction envelope: the runtime issues `prepare("BEGIN"|"COMMIT"|"ROLLBACK").run([])`.
+# The live drivers run with autocommit ON so those literal statements control the transaction
+# exactly like the SQLite seam's implicit-then-explicit tx — a real BEGIN…COMMIT on the live DB.
+
+# `$1`, `$2`, … (Postgres render output).
+_DOLLAR_RE = re.compile(r"\$\d+")
+# `INSERT INTO <table> (...) ... RETURNING <cols>` — MySQL RETURNING emulation parse.
+_RETURNING_RE = re.compile(r"\s+RETURNING\s+(.+?)\s*$", re.IGNORECASE | re.DOTALL)
+_INSERT_TABLE_RE = re.compile(r"^\s*INSERT\s+(?:IGNORE\s+)?INTO\s+([A-Za-z_][A-Za-z0-9_]*)", re.IGNORECASE)
+
+
+def _dollar_to_pyformat(sql: str) -> str:
+    """Postgres `$N` → DB-API `%s` (positional). Render already numbers left-to-right 1..N, so a
+    plain replace preserves order. Literal `%` is doubled so psycopg/pymysql don't treat it as a
+    format directive (the rendered SQL never contains a literal `%`, but this keeps the seam safe).
+    """
+    return _DOLLAR_RE.sub("%s", sql.replace("%", "%%"))
+
+
+def _qmark_to_pyformat(sql: str) -> str:
+    """MySQL render keeps `?`; PyMySQL binds `%s`. Replace each `?` with `%s` (literal `%` doubled)."""
+    return sql.replace("%", "%%").replace("?", "%s")
+
+
+class _LivePrepared:
+    """A prepared statement over a live DB-API connection (psycopg / PyMySQL).
+
+    `paramstyle_xform` adapts the rendered placeholder text; `emulate_returning` toggles the MySQL
+    RETURNING emulation. Transaction-control literals (BEGIN/COMMIT/ROLLBACK) execute verbatim.
+    """
+
+    __slots__ = ("_conn", "_sql", "_xform", "_emulate_returning")
+
+    def __init__(self, conn: Any, sql: str, xform, emulate_returning: bool) -> None:
+        self._conn = conn
+        self._sql = sql
+        self._xform = xform
+        self._emulate_returning = emulate_returning
+
+    def _fetch_all(self, cur) -> List[Dict[str, Any]]:
+        cols = [d[0] for d in cur.description] if cur.description is not None else []
+        return [dict(zip(cols, r)) for r in cur.fetchall()]
+
+    def all(self, params: Sequence[Any]) -> List[Dict[str, Any]]:
+        # MySQL has no RETURNING: strip it, run the INSERT, re-select the inserted PK's columns.
+        if self._emulate_returning:
+            m = _RETURNING_RE.search(self._sql)
+            if m is not None:
+                returning_cols = m.group(1)
+                insert_sql = self._sql[: m.start()]
+                table_m = _INSERT_TABLE_RE.match(insert_sql)
+                if table_m is None:
+                    raise ValueError(
+                        f"scp mysql driver: cannot emulate RETURNING for non-INSERT statement: {self._sql!r}"
+                    )
+                table = table_m.group(1)
+                cur = self._conn.cursor()
+                cur.execute(self._xform(insert_sql), tuple(params))
+                last_id = cur.lastrowid
+                cur.close()
+                sel = self._conn.cursor()
+                sel.execute(f"SELECT {returning_cols} FROM {table} WHERE id = %s", (last_id,))
+                rows = self._fetch_all(sel)
+                sel.close()
+                return rows
+        cur = self._conn.cursor()
+        cur.execute(self._xform(self._sql), tuple(params))
+        rows = self._fetch_all(cur)
+        cur.close()
+        return rows
+
+    def run(self, params: Sequence[Any]) -> RunInfo:
+        cur = self._conn.cursor()
+        cur.execute(self._xform(self._sql), tuple(params))
+        changes = cur.rowcount if cur.rowcount is not None and cur.rowcount >= 0 else 0
+        last = cur.lastrowid if getattr(cur, "lastrowid", None) is not None else 0
+        cur.close()
+        return RunInfo(changes, last)
+
+
+class PostgresDriver:
+    """A live Postgres driver (psycopg 3) implementing the :class:`Driver` seam.
+
+    Renders a `postgres`-tagged bundle → `$N` text; this driver rewrites `$N`→`%s` for psycopg and
+    executes REAL SQL over a live connection. Autocommit ON so the runtime's BEGIN/COMMIT/ROLLBACK
+    literals control the transaction (a genuine PG transaction for the gate-first write-tx).
+    """
+
+    __slots__ = ("conn",)
+
+    def __init__(self, conn: Any) -> None:
+        self.conn = conn
+
+    @classmethod
+    def connect(cls, *, host: str, port: int, user: str, password: str, dbname: str) -> "PostgresDriver":
+        import psycopg  # imported lazily so the SQLite conformance never needs the driver installed
+
+        conn = psycopg.connect(host=host, port=port, user=user, password=password, dbname=dbname, autocommit=True)
+        return cls(conn)
+
+    def exec_ddl(self, statements: Sequence[str]) -> None:
+        cur = self.conn.cursor()
+        for stmt in statements:
+            cur.execute(stmt)
+        cur.close()
+
+    def prepare(self, sql: str) -> _LivePrepared:
+        return _LivePrepared(self.conn, sql, _dollar_to_pyformat, emulate_returning=False)
+
+    def close(self) -> None:
+        self.conn.close()
+
+
+class MysqlDriver:
+    """A live MySQL driver (PyMySQL) implementing the :class:`Driver` seam.
+
+    Renders a `mysql`-tagged bundle → `?` text; this driver rewrites `?`→`%s` for PyMySQL. MySQL
+    8.0 has NO `RETURNING`, so an INSERT…RETURNING is emulated at this seam (strip → INSERT →
+    re-select the AUTO_INCREMENT PK's columns) — the dialect-behavior-by-convention the WS6 TS
+    ScpDialect uses. Autocommit ON so the runtime's BEGIN/COMMIT/ROLLBACK literals bracket the tx.
+    """
+
+    __slots__ = ("conn",)
+
+    def __init__(self, conn: Any) -> None:
+        self.conn = conn
+
+    @classmethod
+    def connect(cls, *, host: str, port: int, user: str, password: str, dbname: str) -> "MysqlDriver":
+        import pymysql  # lazy import (conformance bar never needs it)
+
+        conn = pymysql.connect(host=host, port=port, user=user, password=password, database=dbname, autocommit=True)
+        return cls(conn)
+
+    def exec_ddl(self, statements: Sequence[str]) -> None:
+        cur = self.conn.cursor()
+        for stmt in statements:
+            cur.execute(stmt)
+        cur.close()
+
+    def prepare(self, sql: str) -> _LivePrepared:
+        return _LivePrepared(self.conn, sql, _qmark_to_pyformat, emulate_returning=True)
+
+    def close(self) -> None:
+        self.conn.close()

litedbmodel_runtime-2.0.0/litedbmodel_runtime/errors.py

@@ -0,0 +1,83 @@
+"""litedbmodel v2 SCP — Error Mapping (Python port of ``src/scp/errors.ts``, spec §11 item 5).
+
+Maps a SQLite driver error (Python ``sqlite3`` exceptions, or a better-sqlite3-shaped
+``SQLITE_*`` code carried in a message tag) to a structured :class:`SqlFailure` with a stable
+`kind` + the bc Execution-Plan Policy Kind the runtime honors (fail / retry / continue).
+
+The mapping is closed and explicit (no silent catch-all that hides a driver error): an
+unrecognized error maps to ``kind='driver_error'`` / ``policy='fail'`` — loud, and carrying the
+original code + message. The `SQLITE_*` code family is mirrored from the TS reference; for the
+stdlib ``sqlite3`` driver (whose exceptions do not carry a `SQLITE_*` string code on Python <3.11)
+the code is derived from the message text ("UNIQUE constraint failed", "FOREIGN KEY constraint
+failed", …) so the same kind/policy is produced as the better-sqlite3 seam.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from typing import Optional
+
+# The SCP failure kinds and their honored bc Policy Kind.
+_KIND_POLICY = {
+    "constraint_violation": "fail",
+    "foreign_key_violation": "fail",
+    "retryable": "retry",
+    "driver_error": "fail",
+}
+
+
+class SqlFailure(Exception):
+    """A mapped SCP failure: SCP `kind`, honored bc Policy Kind, the SQLite code, a message."""
+
+    def __init__(self, kind: str, policy: str, sqlite_code: Optional[str], message: str) -> None:
+        super().__init__(message)
+        self.kind = kind
+        self.policy = policy
+        self.sqlite_code = sqlite_code
+
+
+def _code_from_bettersqlite_tag(message: str) -> Optional[str]:
+    """Extract a `SQLITE_*` code embedded by the TS seam (`[SQLITE_...] ...`) or a bare mention."""
+    m = re.search(r"(SQLITE_[A-Z_]+)", message)
+    return m.group(1) if m else None
+
+
+def _code_from_stdlib(e: BaseException) -> Optional[str]:
+    """Derive a `SQLITE_*`-style code from a stdlib sqlite3 exception (type + message text)."""
+    # Python 3.11+ exposes sqlite_errorname (e.g. 'SQLITE_CONSTRAINT_UNIQUE'); prefer it.
+    name = getattr(e, "sqlite_errorname", None)
+    if isinstance(name, str) and name.startswith("SQLITE_"):
+        return name
+    msg = str(e)
+    if isinstance(e, sqlite3.IntegrityError):
+        if "FOREIGN KEY" in msg:
+            return "SQLITE_CONSTRAINT_FOREIGNKEY"
+        return "SQLITE_CONSTRAINT"
+    if isinstance(e, sqlite3.OperationalError):
+        if "locked" in msg:
+            return "SQLITE_LOCKED"
+        if "busy" in msg:
+            return "SQLITE_BUSY"
+    return None
+
+
+def map_sqlite_error(e: BaseException) -> SqlFailure:
+    """Map a caught driver error to a :class:`SqlFailure` (byte-for-byte kind/policy with TS)."""
+    if isinstance(e, sqlite3.Error):
+        code = _code_from_stdlib(e)
+    else:
+        code = _code_from_bettersqlite_tag(str(e))
+
+    if code is None:
+        message = str(e)
+        return SqlFailure("driver_error", "fail", None, f"non-SQLite driver error: {message}")
+
+    tagged = f"[{code}] {e}"
+    if code == "SQLITE_CONSTRAINT_FOREIGNKEY":
+        return SqlFailure("foreign_key_violation", "fail", code, tagged)
+    if code.startswith("SQLITE_CONSTRAINT"):
+        return SqlFailure("constraint_violation", "fail", code, tagged)
+    if code in ("SQLITE_BUSY", "SQLITE_LOCKED"):
+        return SqlFailure("retryable", "retry", code, tagged)
+    return SqlFailure("driver_error", "fail", code, tagged)