matrx-orm 3.1.77__tar.gz → 3.1.78__tar.gz

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/CLAUDE.md

@@ -38,6 +38,9 @@ Every table that becomes a Model needs row identity: a single-column primary key
   Large reconciliation/export scans call `.all(use_cache=False)` so returned
   models do not quadratically populate the process identity cache. Contract:
   [`matrx_orm/query/FEATURE.md`](matrx_orm/query/FEATURE.md).
+- **Conflict writes**: bulk insert-ignore and counter-upsert row coercion runs
+  off the event loop before statement chunking. Contract:
+  [`matrx_orm/operations/FEATURE.md`](matrx_orm/operations/FEATURE.md).
 - **Migrations**: `MigrationDB`, `MigrationLoader`, `MigrationExecutor`, `makemigrations`, `migrate` — migrations declare explicit `dependencies` and apply in topological order (no multi-head/merge support yet).
 - **Admin router** (FastAPI): `admin_router` exposes read/write endpoints for any registered model; bulk response rendering stays off the event loop. Contract: [`matrx_orm/admin/FEATURE.md`](matrx_orm/admin/FEATURE.md).
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.77
+Version: 3.1.78
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
@@ -25,7 +25,7 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.18
+Requires-Dist: matrx-utils>=2.0.19
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0
@@ -57,6 +57,8 @@ Python 3.13+ required. Needs a PostgreSQL server (or Supabase / any Postgres-com
 - **Admin router** (FastAPI): `admin_router` exposes a ready-to-mount set of read/write endpoints for every registered model.
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.
 - **Adapters**: `AsyncPostgreSQLAdapter`, `SupabaseAdapter`, `PostgRESTClientAdapter`.
+- **Local artifact reads**: `read_local_sqlite_rows` provides a validated, read-only
+  projection boundary for SQLite files owned by external tools such as Chromium.
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.
 - **Schema builder** (`matrx_orm.schema_builder`): code generation for Python + TypeScript type definitions from the live DB schema — useful for keeping a frontend's row types in sync.
 

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/README.md

@@ -18,6 +18,8 @@ Python 3.13+ required. Needs a PostgreSQL server (or Supabase / any Postgres-com
 - **Admin router** (FastAPI): `admin_router` exposes a ready-to-mount set of read/write endpoints for every registered model.
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.
 - **Adapters**: `AsyncPostgreSQLAdapter`, `SupabaseAdapter`, `PostgRESTClientAdapter`.
+- **Local artifact reads**: `read_local_sqlite_rows` provides a validated, read-only
+  projection boundary for SQLite files owned by external tools such as Chromium.
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.
 - **Schema builder** (`matrx_orm.schema_builder`): code generation for Python + TypeScript type definitions from the live DB schema — useful for keeping a frontend's row types in sync.
 

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/matrx_orm/__init__.py

@@ -43,6 +43,7 @@ from .platform_db import (
     platform_connection_url,
     register_platform_db,
 )
+from .local_sqlite import SQLiteValue, read_local_sqlite_rows
 from .core.diagnostics import collect_pool_diagnostics, log_pool_diagnostics
 from .core.introspection import introspect_columns, introspect_rls_policies, schema_exists
 from .core.one_database import OneDatabaseReport, PoolIdentity, audit_one_database
@@ -633,6 +634,12 @@ __all__ = [
     "AsyncPostgreSQLAdapter",
     "SupabaseAdapter",
     "PostgRESTClientAdapter",
+    "create_external_pool",
+    "get_registered_pool",
+    "open_listener_connection",
+    # ── Read-only local SQLite artifacts ──────────────────────────────────────
+    "SQLiteValue",
+    "read_local_sqlite_rows",
     # ── Cache ──────────────────────────────────────────────────────────────────
     "CachePolicy",
     "StateManager",

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/matrx_orm/admin/FEATURE.md

@@ -14,10 +14,21 @@ FastAPI admin surface.
 - **The page cap is 2,000 rows.** Keep `ADMIN_LIST_MAX_PAGE_SIZE` aligned with the
   dashboard constant in `orm-proxy.ts`.
 
+## Database identity
+
+- **A table is `database.schema.table`.** `GET /tables` and cache stats expose
+  `database_name`; every columns, row, mutation, bulk, and cache endpoint accepts
+  `database=` and passes it to the multi-database model registry.
+- **Ambiguity is a controlled conflict.** An omitted database that matches more
+  than one registered model returns HTTP 409 with the candidates. It never guesses
+  and never escapes as a request crash.
+
 Verified against `router.py` and
-`tests/level1/test_admin_response_rendering.py` on 2026-08-17.
+`tests/level1/test_admin_db_columns.py` on 2026-08-17.
 
 ## Change Log
 
 - 2026-08-17 — Moved bulk row serialization and JSON encoding off the event
   loop after a 1.1-second production stall.
+- 2026-08-17 — Carried database identity through every admin relation endpoint
+  and converted unqualified cross-database ambiguity into HTTP 409.

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/matrx_orm/admin/router.py

@@ -58,22 +58,42 @@ _COMPOSITE_ROW_ID_PREFIX = "cmp1_"
 # ---------------------------------------------------------------------------
 
 
-def _model_by_table(table_name: str, schema: str | None = None) -> type | None:
-    return model_registry.get_model_by_table(schema or "public", table_name)
+def _model_by_table(
+    table_name: str,
+    schema: str | None = None,
+    database: str | None = None,
+) -> type | None:
+    return model_registry.get_model_by_table(
+        schema or "public",
+        table_name,
+        database=database,
+    )
 
 
-def _require_model(table_name: str, schema: str | None = None) -> type:
-    model = _model_by_table(table_name, schema)
+def _require_model(
+    table_name: str,
+    schema: str | None = None,
+    database: str | None = None,
+) -> type:
+    try:
+        model = _model_by_table(table_name, schema, database)
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
     if model is None:
         effective_schema = schema or "public"
+        database_suffix = f" in database '{database}'" if database else ""
         log.warning(
-            "Table '%s.%s' not found in model registry",
+            "Table '%s.%s' not found in model registry%s",
             effective_schema,
             table_name,
+            database_suffix,
         )
         raise HTTPException(
             status_code=404,
-            detail=f"Table '{effective_schema}.{table_name}' not found in model registry",
+            detail=(
+                f"Table '{effective_schema}.{table_name}' not found in model registry"
+                f"{database_suffix}"
+            ),
         )
     return model
 
@@ -428,16 +448,19 @@ async def _fetch_check_choices(model: type) -> dict[str, list[str]]:
 async def list_tables() -> list[dict[str, object]]:
     models = model_registry.all_models()
     log.info("list_tables: %d models in registry", len(models))
-    sample_model = next(iter(models.values()), None)
-    db_counts = await _fetch_db_column_counts(sample_model) if sample_model else {}
+    counts_by_database: dict[str, dict[tuple[str, str], int]] = {}
     tables = []
     for model in models.values():
         meta = model._meta
         schema = _model_schema(model)
+        database = model.get_database_name()
+        if database not in counts_by_database:
+            counts_by_database[database] = await _fetch_db_column_counts(model)
         orm_count = len(meta.fields)
-        db_count = db_counts.get((schema, meta.table_name))
+        db_count = counts_by_database[database].get((schema, meta.table_name))
         tables.append(
             {
+                "database_name": database,
                 "table_name": meta.table_name,
                 "table_schema": schema,
                 "name": meta.table_name,
@@ -445,7 +468,7 @@ async def list_tables() -> list[dict[str, object]]:
                 "column_count": db_count if db_count is not None else orm_count,
             }
         )
-    tables.sort(key=lambda t: (t["table_schema"], t["table_name"]))
+    tables.sort(key=lambda t: (t["database_name"], t["table_schema"], t["table_name"]))
     return tables
 
 
@@ -453,8 +476,9 @@ async def list_tables() -> list[dict[str, object]]:
 async def get_columns(
     table_name: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> list[dict[str, object]]:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     columns = await _admin_column_descriptors(model)
 
     # Enrich with CHECK constraint choices from the database
@@ -647,8 +671,9 @@ async def list_rows(
     sort_dir: str = Query("asc", pattern="^(asc|desc)$"),
     search: str | None = Query(None, description="Column filters as 'col1:val1,col2:val2'"),
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> Response:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info(
         "list_rows: table=%s page=%d size=%d sort_by=%s sort_dir=%s search=%s",
         table_name,
@@ -707,8 +732,9 @@ async def get_row(
     table_name: str,
     row_id: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info("get_row: table=%s id=%s", table_name, row_id)
 
     try:
@@ -724,8 +750,9 @@ async def create_row(
     table_name: str,
     request: Request,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     body: dict[str, Any] = await request.json()
     log.info("create_row: table=%s fields=%s", table_name, list(body.keys()))
 
@@ -744,8 +771,9 @@ async def update_row(
     row_id: str,
     request: Request,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     body: dict[str, Any] = await request.json()
     log.info("update_row: table=%s id=%s fields=%s", table_name, row_id, list(body.keys()))
 
@@ -764,8 +792,9 @@ async def delete_row(
     table_name: str,
     row_id: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info("delete_row: table=%s id=%s", table_name, row_id)
 
     try:
@@ -783,10 +812,11 @@ async def bulk_delete_rows(
     table_name: str,
     request: Request,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
     """Delete many rows in one call. Never fails the whole batch on one bad id —
     returns a partial-result envelope so the caller can report what landed."""
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     body: dict[str, Any] = await request.json()
     ids = body.get("ids")
     if not isinstance(ids, list) or not ids:
@@ -830,11 +860,12 @@ async def bulk_update_rows(
     table_name: str,
     request: Request,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
     """Apply the same field changes to many rows in one call. Never fails the
     whole batch on one bad id — returns a partial-result envelope (same shape
     as bulk-delete) so the caller can report what landed."""
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     body: dict[str, Any] = await request.json()
     ids = body.get("ids")
     data = body.get("data")
@@ -901,12 +932,13 @@ async def cache_stats() -> list[dict[str, object]]:
         results.append(
             {
                 "model_name": model.__name__,
+                "database_name": model.get_database_name(),
                 "table_name": model._meta.table_name,
                 "table_schema": _model_schema(model),
                 "cached_count": count,
             }
         )
-    results.sort(key=lambda r: (r["table_schema"], r["table_name"]))
+    results.sort(key=lambda r: (r["database_name"], r["table_schema"], r["table_name"]))
     return results
 
 
@@ -914,9 +946,10 @@ async def cache_stats() -> list[dict[str, object]]:
 async def clear_table_cache(
     table_name: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
     """Flush the entire in-memory cache for a table."""
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info("clear_table_cache: %s", table_name)
 
     try:
@@ -932,9 +965,10 @@ async def evict_row_cache(
     table_name: str,
     row_id: str,
     schema: str | None = Query(None, description="PostgreSQL schema name"),
+    database: str | None = Query(None, description="Registered database project name"),
 ) -> JSONResponse:
     """Evict a single record from the in-memory cache."""
-    model = _require_model(table_name, schema)
+    model = _require_model(table_name, schema, database)
     log.info("evict_row_cache: %s/%s", table_name, row_id)
 
     try:

matrx_orm-3.1.78/matrx_orm/local_sqlite.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import re
+import sqlite3
+from collections.abc import Sequence
+from pathlib import Path
+
+type SQLiteValue = str | int | float | bytes | None
+
+_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+
+
+def _identifier(value: str) -> str:
+    if not _IDENTIFIER.fullmatch(value):
+        raise ValueError(f"invalid SQLite identifier: {value!r}")
+    return f'"{value}"'
+
+
+def read_local_sqlite_rows(
+    database: str | Path,
+    *,
+    table: str,
+    columns: Sequence[str],
+    order_by: Sequence[str] = (),
+) -> list[tuple[SQLiteValue, ...]]:
+    """Read a projected table from a local SQLite artifact in read-only mode."""
+    if not columns:
+        raise ValueError("columns must contain at least one identifier")
+
+    projection = ", ".join(_identifier(column) for column in columns)
+    statement = f"SELECT {projection} FROM {_identifier(table)}"
+    if order_by:
+        statement += " ORDER BY " + ", ".join(_identifier(column) for column in order_by)
+
+    path = Path(database).expanduser().resolve()
+    connection = sqlite3.connect(f"{path.as_uri()}?mode=ro", uri=True)
+    try:
+        return [tuple(row) for row in connection.execute(statement)]
+    finally:
+        connection.close()

matrx_orm-3.1.78/matrx_orm/operations/FEATURE.md

@@ -0,0 +1,23 @@
+# Conflict-write operations
+
+`conflict_writes.py` provides typed insert-ignore and conflict-update primitives
+for append-only rows, partial unique indexes, and atomic counters.
+
+## Event-loop safety
+
+- **Bulk row coercion never runs on the event loop.** `bulk_insert_ignore` and
+  `bulk_upsert_increment` pass model construction, defaults, and field DB-value
+  conversion through `_prep_bulk_rows`, which uses `asyncio.to_thread`.
+- **Single-row writes stay inline.** `insert_ignore` and
+  `upsert_with_conflict` avoid thread-dispatch overhead for one row.
+- **Statement chunking still enforces the bind-parameter ceiling.** Offloading
+  row preparation does not change `_MAX_BIND_PARAMS` or caller-connection
+  transaction semantics.
+
+Verified against `conflict_writes.py` and
+`tests/level1/test_conflict_writes.py` on 2026-08-17.
+
+## Change Log
+
+- 2026-08-17 — Moved bulk model materialization off the event loop after a
+  scheduled search-performance import froze unrelated requests for 2.8 seconds.

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/matrx_orm/operations/conflict_writes.py

@@ -33,6 +33,7 @@ primitive instead of hand-rolled f-strings.
 
 from __future__ import annotations
 
+import asyncio
 import re
 from typing import TYPE_CHECKING, Any
 
@@ -115,6 +116,12 @@ def _prep_rows(model_cls: type[Model], objects_data: list[dict[str, Any]]) -> li
     return data_list
 
 
+async def _prep_bulk_rows(
+    model_cls: type[Model], objects_data: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    return await asyncio.to_thread(_prep_rows, model_cls, objects_data)
+
+
 async def _run(
     model_cls: type[Model],
     sql: str,
@@ -171,7 +178,7 @@ async def bulk_insert_ignore(
     if isinstance(returning, str) and not _IDENT_RE.match(returning):
         raise ValueError(f"returning column must be a plain identifier; got {returning!r}")
     returning_clause = "*" if returning is True else returning if returning else "1"
-    data_list = _prep_rows(model_cls, objects_data)
+    data_list = await _prep_bulk_rows(model_cls, objects_data)
     target_clause = _render_conflict_target(on_conflict)
     table = model_cls._meta.qualified_table_name
     col_count = len({k for row in data_list for k in row})
@@ -362,7 +369,7 @@ async def bulk_upsert_increment(
             raise ValueError(f"set_fields column must be a plain identifier; got {col!r}")
         if col in increments:
             raise ValueError(f"{col!r} is in both increments and set_fields — pick one")
-    data_list = _prep_rows(model_cls, objects_data)
+    data_list = await _prep_bulk_rows(model_cls, objects_data)
     target_clause = _render_conflict_target(on_conflict)
     table = model_cls._meta.qualified_table_name
 

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.77"
+version = "3.1.78"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.18",
+    "matrx-utils>=2.0.19",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/tests/level1/test_admin_db_columns.py

@@ -4,13 +4,16 @@ from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
+from fastapi import HTTPException
 from matrx_orm.admin.router import (
     COMPOSITE_ROW_ID_FIELD,
     _admin_column_descriptors,
     _db_row_to_descriptor,
     _decode_row_id,
     _model_by_table,
+    _require_model,
     _serialize,
+    list_tables,
 )
 
 
@@ -35,7 +38,7 @@ def test_admin_model_lookup_defaults_to_exact_public_key() -> None:
         return_value=sentinel,
     ) as lookup:
         assert _model_by_table("definition") is sentinel
-    lookup.assert_called_once_with("public", "definition")
+    lookup.assert_called_once_with("public", "definition", database=None)
 
 
 def test_admin_model_lookup_uses_requested_schema() -> None:
@@ -44,7 +47,66 @@ def test_admin_model_lookup_uses_requested_schema() -> None:
         return_value=None,
     ) as lookup:
         assert _model_by_table("definition", "agent") is None
-    lookup.assert_called_once_with("agent", "definition")
+    lookup.assert_called_once_with("agent", "definition", database=None)
+
+
+def test_admin_model_lookup_uses_requested_database() -> None:
+    sentinel = object()
+    with patch(
+        "matrx_orm.admin.router.model_registry.get_model_by_table",
+        return_value=sentinel,
+    ) as lookup:
+        assert _model_by_table("users", "auth", "main") is sentinel
+    lookup.assert_called_once_with("auth", "users", database="main")
+
+
+def test_admin_model_lookup_returns_conflict_for_ambiguous_relation() -> None:
+    with (
+        patch(
+            "matrx_orm.admin.router.model_registry.get_model_by_table",
+            side_effect=ValueError("Table 'auth.users' is ambiguous across databases"),
+        ),
+        pytest.raises(HTTPException) as exc_info,
+    ):
+        _require_model("users", "auth")
+
+    assert exc_info.value.status_code == 409
+    assert "ambiguous" in str(exc_info.value.detail)
+
+
+@pytest.mark.asyncio
+async def test_admin_table_inventory_exposes_database_identity() -> None:
+    model = SimpleNamespace(
+        __name__="Users",
+        _meta=SimpleNamespace(
+            table_name="users",
+            db_schema="auth",
+            fields={"id": object()},
+        ),
+        get_database_name=lambda: "supabase_automation_matrix",
+    )
+    with (
+        patch(
+            "matrx_orm.admin.router.model_registry.all_models",
+            return_value={("supabase_automation_matrix", "auth", "Users"): model},
+        ),
+        patch(
+            "matrx_orm.admin.router._fetch_db_column_counts",
+            new=AsyncMock(return_value={("auth", "users"): 24}),
+        ),
+    ):
+        tables = await list_tables()
+
+    assert tables == [
+        {
+            "database_name": "supabase_automation_matrix",
+            "table_name": "users",
+            "table_schema": "auth",
+            "name": "users",
+            "model_name": "Users",
+            "column_count": 24,
+        }
+    ]
 
 
 def test_composite_row_identity_round_trips() -> None:

{matrx_orm-3.1.77 → matrx_orm-3.1.78}/tests/level1/test_conflict_writes.py

@@ -13,6 +13,9 @@ caller-connection seam are all exercised without a registered database.
 
 from __future__ import annotations
 
+import asyncio
+import threading
+import time
 from typing import Any
 
 import pytest
@@ -27,6 +30,7 @@ from matrx_orm.operations.conflict_writes import (
     bulk_insert_ignore,
     bulk_upsert_increment,
 )
+import matrx_orm.operations.conflict_writes as conflict_writes
 
 
 class _Meta:
@@ -143,6 +147,76 @@ async def test_insert_ignore_empty_is_noop_without_touching_connection() -> None
     assert conn.calls == []
 
 
+@pytest.mark.asyncio
+async def test_insert_ignore_prepares_bulk_rows_off_event_loop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    model = _make_model("t", {"id": TextField()})
+    conn = _CaptureConn()
+    loop_thread = threading.get_ident()
+    prep_thread: int | None = None
+    original_prep_rows = conflict_writes._prep_rows
+
+    def slow_prep_rows(
+        model_cls: type,
+        objects_data: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        nonlocal prep_thread
+        prep_thread = threading.get_ident()
+        time.sleep(0.05)
+        return original_prep_rows(model_cls, objects_data)
+
+    monkeypatch.setattr(conflict_writes, "_prep_rows", slow_prep_rows)
+    write_task = asyncio.create_task(
+        bulk_insert_ignore(model, [{"id": "x"}], on_conflict=["id"], connection=conn)
+    )
+
+    await asyncio.sleep(0.01)
+
+    assert not write_task.done()
+    await write_task
+    assert prep_thread is not None
+    assert prep_thread != loop_thread
+
+
+@pytest.mark.asyncio
+async def test_increment_prepares_bulk_rows_off_event_loop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    model = _make_model("t", {"id": TextField(), "count": IntegerField()})
+    conn = _CaptureConn()
+    loop_thread = threading.get_ident()
+    prep_thread: int | None = None
+    original_prep_rows = conflict_writes._prep_rows
+
+    def slow_prep_rows(
+        model_cls: type,
+        objects_data: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        nonlocal prep_thread
+        prep_thread = threading.get_ident()
+        time.sleep(0.05)
+        return original_prep_rows(model_cls, objects_data)
+
+    monkeypatch.setattr(conflict_writes, "_prep_rows", slow_prep_rows)
+    write_task = asyncio.create_task(
+        bulk_upsert_increment(
+            model,
+            [{"id": "x", "count": 1}],
+            on_conflict=["id"],
+            increments={"count": 1},
+            connection=conn,
+        )
+    )
+
+    await asyncio.sleep(0.01)
+
+    assert not write_task.done()
+    await write_task
+    assert prep_thread is not None
+    assert prep_thread != loop_thread
+
+
 @pytest.mark.asyncio
 async def test_insert_ignore_returning_column_gives_landed_ids_only() -> None:
     """The matrx-rag derived-chunk write shape: ON CONFLICT DO NOTHING, then

matrx_orm-3.1.78/tests/level1/test_local_sqlite.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from matrx_orm import read_local_sqlite_rows
+
+
+def _fixture_database(path: Path) -> None:
+    connection = sqlite3.connect(path)
+    try:
+        connection.execute("CREATE TABLE events (id INTEGER PRIMARY KEY, label TEXT, payload BLOB)")
+        connection.executemany(
+            "INSERT INTO events (id, label, payload) VALUES (?, ?, ?)",
+            [(2, "later", b"two"), (1, "first", b"one")],
+        )
+        connection.commit()
+    finally:
+        connection.close()
+
+
+def test_read_local_sqlite_rows_projects_and_orders(tmp_path: Path) -> None:
+    database = tmp_path / "artifact.db"
+    _fixture_database(database)
+
+    rows = read_local_sqlite_rows(
+        database,
+        table="events",
+        columns=("label", "payload"),
+        order_by=("id",),
+    )
+
+    assert rows == [("first", b"one"), ("later", b"two")]
+
+
+def test_read_local_sqlite_rows_rejects_statement_shaped_table_name(tmp_path: Path) -> None:
+    database = tmp_path / "artifact.db"
+    _fixture_database(database)
+
+    with pytest.raises(ValueError, match="invalid SQLite identifier"):
+        read_local_sqlite_rows(
+            database,
+            table='events"; DELETE FROM events; --',
+            columns=("id",),
+        )
+
+
+@pytest.mark.parametrize("columns", [(), ("label DESC",)])
+def test_read_local_sqlite_rows_rejects_invalid_projection(
+    tmp_path: Path, columns: tuple[str, ...]
+) -> None:
+    database = tmp_path / "artifact.db"
+    _fixture_database(database)
+
+    with pytest.raises(ValueError):
+        read_local_sqlite_rows(database, table="events", columns=columns)