3tears 0.14.0__py3-none-any.whl

3tears-0.14.0.dist-info/METADATA

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: 3tears
+Version: 0.14.0
+Summary: Three-tier caching framework for Python -- L1 SQLite, L2 NATS KV, L3 PostgreSQL
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: 3tears-nats
+Requires-Dist: 3tears-observe
+Requires-Dist: aiosqlite
+Requires-Dist: asyncpg
+Requires-Dist: cryptography>=42
+Requires-Dist: nats-py
+Requires-Dist: pydantic
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: sqlalchemy
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=1.0; extra == 'duckdb'
+Provides-Extra: testing
+Requires-Dist: docker>=7.0; extra == 'testing'
+Requires-Dist: pytest>=8.0; extra == 'testing'
+Requires-Dist: testcontainers[nats,postgres]>=4.0; extra == 'testing'
+Provides-Extra: tracing
+Requires-Dist: opentelemetry-api>=1.20; extra == 'tracing'
+Description-Content-Type: text/markdown
+
+# 3tears Core
+
+Three-tier caching library for Python applications. Provides collections (L1 SQLite -> L2 NATS KV -> L3 PostgreSQL) with subscript access, entity proxy objects, and configurable flush strategies.
+
+## Architecture
+
+```
+L1 (SQLite, in-process, sync)  ->  L2 (NATS KV, shared, async)  ->  L3 (PostgreSQL, persistent, async)
+```
+
+- **L1**: In-memory SQLite via WAL mode. Sync access. Used by entity attribute reads and writes.
+- **L2**: NATS KV shared cache. Async. Cross-pod consistency for multi-instance deployments.
+- **L3**: PostgreSQL (or PostGIS, YugabyteDB, etc.). Async. Source of truth.
+
+Reads promote up the stack (L3 miss -> L2 miss -> L1 hit on next access). Writes flow down (L1 -> L2 -> L3, with optional deferred flush).
+
+## Quick Start
+
+### 1. Configure the Registry
+
+```python
+from threetears.core.collections.registry import CollectionRegistry
+from threetears.core.cache.sqlite import SQLiteBackend
+
+# Create and configure
+l1 = SQLiteBackend("my_app_cache")
+l1.initialize(sa_metadata)  # SQLAlchemy metadata with your table definitions
+
+registry = CollectionRegistry()
+registry.configure(
+    l1_backend=l1,          # SQLiteBackend instance
+    l2_client=nats_client,  # NATS client (optional, None to skip L2)
+    l3_pool=postgres_pool,  # asyncpg pool
+)
+```
+
+### 2. Per-Collection Pool Overrides
+
+Different collections can use different databases:
+
+```python
+# Default: all collections use YugabyteDB
+registry.configure(l3_pool=yugabyte_pool)
+
+# Override: geo collection uses PostGIS
+registry.configure()  # keep defaults
+# When creating the collection, register with override:
+geo_collection = GeoCollection(registry, config, nats_client, write_buffer)
+registry.register(geo_collection, l3_pool=postgis_pool)
+```
+
+### 3. Define a Collection
+
+```python
+from threetears.core.collections.base import BaseCollection
+from threetears.core.entities.base import BaseEntity
+
+class UserEntity(BaseEntity):
+    primary_key_field = "user_id"
+
+class UsersCollection(BaseCollection[UserEntity]):
+    primary_key_column = "user_id"
+
+    @property
+    def table_name(self) -> str:
+        return "users"
+
+    @property
+    def entity_class(self) -> type[UserEntity]:
+        return UserEntity
+
+    async def fetch_from_store(self, entity_id):
+        row = await self.l3_pool.fetchrow(
+            "SELECT * FROM users WHERE user_id = $1", entity_id
+        )
+        return dict(row) if row else None
+
+    async def save_to_store(self, data, original_timestamp=None):
+        # INSERT or UPDATE with optimistic locking
+        ...
+
+    async def delete_from_store(self, entity_id):
+        await self.l3_pool.execute(
+            "DELETE FROM users WHERE user_id = $1", entity_id
+        )
+
+    def serialize(self, data):
+        return json.dumps(data, default=str).encode()
+
+    def deserialize(self, data):
+        return json.loads(data)
+```
+
+### 4. Create Collection Instances
+
+```python
+from threetears.core.collections.flush import WriteBuffer
+
+write_buffer = WriteBuffer()
+users = UsersCollection(registry, config, nats_client, write_buffer)
+```
+
+The `config` parameter must satisfy the `CoreConfig` protocol:
+
+```python
+class CoreConfig(Protocol):
+    collection_flush: str           # "ALWAYS", "ON_CHECKPOINT", "ON_SCHEDULE", "ON_SHUTDOWN"
+    collection_flush_interval: int  # seconds between scheduled flushes
+    collection_flush_tables: str    # comma-separated table names eligible for deferred flush
+```
+
+## Access Patterns
+
+### Subscript Access (sync, transparent pull-through)
+
+Subscript access is the primary API. On L1 miss, data is transparently pulled through L2/L3 via a background event loop. No `await` needed, no `ensure()` required:
+
+```python
+# Read entity -- pulls through L2/L3 automatically on L1 miss
+entity = users[user_id]
+
+# Read single field
+name = users[user_id, "name_display"]
+
+# Write single field (writes to L1, tracks for flush)
+users[user_id, "name_display"] = "New Name"
+
+# Write full entity data (writes dict to L1)
+users[user_id] = {"user_id": user_id, "name_display": "New Name", ...}
+
+# Check if entity is in L1 (does NOT pull through -- L1 only)
+if user_id in users:
+    entity = users[user_id]
+```
+
+`__getitem__` raises `KeyError` only if the entity doesn't exist in any tier. The L1 fast path is ~microseconds; an L1 miss with pull-through adds ~50-200us bridge overhead plus the actual L2/L3 I/O time.
+
+
+For hot-path code where you want to avoid the sync-async bridge overhead on first access, you can pre-warm L1:
+
+```python
+await users.ensure(user_id)  # async: pre-warms L1
+entity = users[user_id]       # guaranteed L1 hit, no bridge needed
+```
+
+### Async Operations
+
+```python
+# Three-tier read: L1 -> L2 -> L3, promotes on miss. Returns None if not found.
+entity = await users.get(user_id)
+
+# Create a new entity (not persisted until save)
+entity = users.create({"user_id": uuid7(), "name_display": "Alice", ...})
+
+# Save through three-tier write path (L3 -> L1 -> L2)
+await users.save_entity(entity)
+# Or via entity directly:
+await entity.save()
+
+# Reload from L3 (discards local changes)
+await entity.reload()
+
+# Delete from all tiers
+await users.delete(user_id)
+
+# Invalidate L1 + L2 (force next read to hit L3)
+await users.invalidate_cache(user_id)
+```
+
+### Entity Attribute Access
+
+Entities are thin cache proxies. Field data lives in L1, not in the entity object.
+
+```python
+entity = await users.get(user_id)
+
+# Read (checks entity._changes first, then L1 cache)
+print(entity.name_display)
+
+# Write (writes to L1 + tracks change)
+entity.name_display = "Updated Name"
+
+# Check dirty state
+entity.is_dirty  # True after modification
+entity.is_new    # True if created via collection.create()
+
+# Get all changes
+entity.get_changes()  # {"name_display": "Updated Name"}
+
+# Export full entity data from L1
+entity.to_dict()
+
+# Persist
+await entity.save()
+```
+
+## Flush Strategies
+
+Controls when deferred writes reach L3 (PostgreSQL):
+
+| Strategy | Behavior |
+|---|---|
+| `ALWAYS` | Every `save_entity()` writes to L3 immediately |
+| `ON_CHECKPOINT` | Writes buffer to L1 + L2; flushes to L3 on explicit `flush_pending()` call |
+| `ON_SCHEDULE` | Same as ON_CHECKPOINT but with timer-based auto-flush |
+| `ON_SHUTDOWN` | Writes buffer; flushes to L3 on application shutdown |
+
+Only tables listed in `collection_flush_tables` are eligible for deferred writes. All other tables always write immediately regardless of strategy.
+
+## Optimistic Locking
+
+Collections use `date_updated` for optimistic locking. When saving an existing entity, the `save_to_store` implementation should check:
+
+```sql
+UPDATE users SET ... WHERE user_id = $1 AND date_updated = $2
+```
+
+If `rows_affected == 0` for an UPDATE, `BaseCollection.save_entity()` raises `ConcurrentModificationError`.
+
+## Subclassing Guide
+
+**BaseEntity**: Set `primary_key_field` to your PK column name. Add computed properties as needed. Do NOT store data in instance attributes. All data lives in L1.
+
+**BaseCollection**: Set `primary_key_column`. Implement the 5 abstract methods: `fetch_from_store`, `save_to_store`, `delete_from_store`, `serialize`, `deserialize`. Use `self.l3_pool` for database access. Add domain-specific query methods (e.g., `find_by_email`).

3tears-0.14.0.dist-info/RECORD

@@ -0,0 +1,74 @@
+threetears/core/__init__.py,sha256=mb496zXGod8nu5U5MYqAIimf17RhKGn8HQCwhSZJ35A,7920
+threetears/core/_bridge.py,sha256=ZWQ8VTCoCo3a2qFDGXvMdBkQEtRwKmN4YHM71jVRD-M,3196
+threetears/core/config.py,sha256=F4UQ2xOhPpCnyWtKwcPN0jjLzRdI6wimAduG2EDNoMg,1145
+threetears/core/exceptions.py,sha256=Gb1dX9nHeZwYR8IbSKEWkq64XQmQa5XAUCTdxaVV5uQ,843
+threetears/core/models.py,sha256=Qct7JQ745FBMhHIHkys1B50_taOIQS9v9R3x68Y1_XE,3315
+threetears/core/namespaces.py,sha256=AjJljMOvHIf1RPrlEPf0Yt0bt2HJ-xvGn2Pf_61HztI,6746
+threetears/core/pagination.py,sha256=hh2zzWsXalYkpKeu0kvLHLSnHuoXEveEXTKUUdwgvVI,8710
+threetears/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+threetears/core/serialization.py,sha256=kXyr1n_Pth7H7HKYXvdWdphz2aHLYR86kSBKkeDh6vY,8174
+threetears/core/backends/__init__.py,sha256=Cd2i4XCC9NoD8yNBKGjc44JuyzhXvVocg7MfIJxUMXI,466
+threetears/core/backends/nats_proxy.py,sha256=zsE8qIlbnxMCVIxRDaqKNPpea2hUDMdsdaGuDnzhhhw,45219
+threetears/core/backends/protocol.py,sha256=rjK8Eti8yOQirQ7f4O6dgRm3tm4t3RQN0DY3K2aLbWg,8544
+threetears/core/backends/schema_sql.py,sha256=kzFZVZAFoEpr6DtkGGeGAF_3tHOV3fmhkxSjwsp2zuY,26528
+threetears/core/backends/sql.py,sha256=SM_SVRdlZWpo2l3_uZBO7InkmjS5BlXFvx3n-Au5cv0,22466
+threetears/core/cache/__init__.py,sha256=ogytyqLU788XI9V3U-bs7VPV8RizCHttvqUWOZ7sUf8,213
+threetears/core/cache/base.py,sha256=CW4IzztA5PdD9ibJnk8Evm0EMgXcz8o5WhiY51Lf_Yc,4424
+threetears/core/cache/duckdb.py,sha256=avwNz2Zfr0lXUHjcJPMsUK3GC1qXD4qhNCUyzlSA0ow,15640
+threetears/core/cache/kv.py,sha256=XL9cp-tKTwiU-u_ffEH4Q9rP-a2Pezn7tx_euhwD6q0,15695
+threetears/core/cache/sqlite.py,sha256=bxsTkT80xf5xJGUUVYLhWpAwBYcbs_kVx5X6ov1k7nM,22845
+threetears/core/collections/__init__.py,sha256=GH8lOwvUkOUowbas9PsbhgX5bfltW9QpfoZkIvTIOaI,1513
+threetears/core/collections/asyncpg_init.py,sha256=OXSH3ut1NZSKWbooGhiJjQIeppsDNy_C53bbCY41A0s,2964
+threetears/core/collections/base.py,sha256=p_YSvGQ5CTTBsZLg0U4RTumqNfhrDpbhScYNBNAgoXM,50404
+threetears/core/collections/durable_store.py,sha256=aVmj3taLR1A_U52uL8g1heXBpeAebqPU5DT57fmwCHU,4487
+threetears/core/collections/flush.py,sha256=55e0am_dCE7BKII3o0r-IEkPp9y7iU-UnYOUaXXgUFQ,19343
+threetears/core/collections/merge.py,sha256=dr6ghTEsFREgAxq205qSf7E3O-aQvA66blFXCNp4C3I,3284
+threetears/core/collections/registry.py,sha256=KhrjhsU6cEcRW2ttwqyWJuvMMHFianD4Z39H5bN4_bM,15204
+threetears/core/collections/schema_backed.py,sha256=lK4Zzq0FYCreVCR39wxOdwTkvb6F7-9DItSwiyQMzkk,67628
+threetears/core/coordination/__init__.py,sha256=2npblE9Rz8Fhc2gVQgzL_Vf4FeLu6Eb8X45VpGefh6U,882
+threetears/core/coordination/lease.py,sha256=ul7as2Rk4kb7vFbUG_OYQbJnCNc003WTGvXu6S-NWdA,21829
+threetears/core/coordination/replay_guard.py,sha256=Vz6fAxzzs_2dHynF5FbznUs0j7guL-r3M9rK4qbjpSc,6148
+threetears/core/data/__init__.py,sha256=i2lF_ISys1DT0WL62VhAcmZWg5kCJt2YqVWkZxcuAZ0,692
+threetears/core/data/collection_factory.py,sha256=CrWi3Ug-hshgjx_fdEoJHOd8uXZf5XR0z01elVj3CyU,13181
+threetears/core/data/schema.py,sha256=Th-AkNqL7dnqRD9mvaxkVSueE0Juy3qn3WIF1RpB5Rk,10595
+threetears/core/data/sql_builder.py,sha256=hBsM7mRl401uokqp4kCwzAYKx4jq2UtYLu7bXwH6KAA,4451
+threetears/core/data/store.py,sha256=6jCvQmmxpgKU7bMfUfeHJJCJTJ2EFz9yzYT24sxieDg,6658
+threetears/core/data/migrations/README.md,sha256=K4g_493ZseWpPkC6JanYzXEi-3dYlI7D8hJ7CAfxRP4,5880
+threetears/core/data/migrations/__init__.py,sha256=dthh1-xDVr1skRun8vlN10lzv-gp_w75bqQJGuzflYg,2528
+threetears/core/data/migrations/drift.py,sha256=z5ICxZGTUbopGlLq4zsHIvLc7ivMMm8r6ijAzszg_5c,19205
+threetears/core/data/migrations/enforcement.py,sha256=SqUPhX1YE8VxLLKEFqFCK90V3Kp9Hk6uay5t6ZD8pj8,30355
+threetears/core/data/migrations/errors.py,sha256=fR5nJz7JmUJrrF1-iBhkAfk3nunUp_eAUOYIKA23-BU,2167
+threetears/core/data/migrations/helpers.py,sha256=re8No56Ho4TNL_T1pqTeGwj8q3-20JugX9JXjMEsTYw,32290
+threetears/core/data/migrations/preview.py,sha256=wpzs4WzDcOlo4utljvZKZFpj7Q_TVDalPgOp4LNMk8E,5710
+threetears/core/data/migrations/registry.py,sha256=PFcb1J0QqhSN8gFZnZT1pN4m-IdPbZqBJaOSay38tnU,7000
+threetears/core/data/migrations/runner.py,sha256=t9AmXLMfSnO--ju48DdHvO_DfGtTScck5QSPsf24eE0,28397
+threetears/core/data/migrations/scope.py,sha256=rSjzT8mnlz5w0v6iK6mEhksiEu01OjOIspoWFedAUyk,940
+threetears/core/data/migrations/template.py,sha256=wV4La9s07MKCM3pcKDmJBw4aZLFl317a3AJasz7KvG8,4155
+threetears/core/entities/__init__.py,sha256=pg_ZfKCl985QE3I4cULHtdZYqHrISaNbVtsC9U-AgHM,79
+threetears/core/entities/base.py,sha256=8f7Q72RllkUtR2RQvAVGomABBUy6GUo3q2mx8QRQQJ8,9913
+threetears/core/security/__init__.py,sha256=N-9MURzzY2w7OiFd-V9Sg1jXVZgLm8GdPuooQsO_Dpo,3223
+threetears/core/security/encryption.py,sha256=-JYPdwhz8qgRIu4RjcmZJIku07TMQz1iHJLfheiR6Dc,4841
+threetears/core/security/identity_token.py,sha256=plzaySeuCsn1tJWSVg2DBlXcEUAlWSVVGxfojhyKGeQ,15976
+threetears/core/security/jwks_provider.py,sha256=Y27IPXp3qWrzZcJZ2sITnB4GeNgc3UuP6CIkrLE5TGU,12403
+threetears/core/security/pop.py,sha256=yrJ1zkonxD2gnP_8nIPFtmcXI-9LmT9aTL_m7IayrEk,7128
+threetears/core/security/proxy_assertion.py,sha256=qyTvpV-FYf57sdJGY-rTowupKQEym3W2PRU6jsyS2H0,7664
+threetears/core/security/proxy_signer.py,sha256=fA3RYtwnYXRXZMhGRc-vbHs1EiIfO6-_HybZxvADsjU,4988
+threetears/core/security/sandbox.py,sha256=HzzUOh4Dc4KZTaBHedx1VIaC6w24LG7wMlOD0S2v-qU,17293
+threetears/core/security/secret_refs.py,sha256=qTrdgZml-OF426x4MHPYTeDemF02HUcBAEZOV4XwpYo,9055
+threetears/core/testing/__init__.py,sha256=Qh80JK-hplWOTYx6aXx10K3MKDPNz1IBfJ0gwntqb_0,1933
+threetears/core/testing/containers.py,sha256=C9xgKyqKMvCl3Cfwo4Oo6PNoVmUx27GnVXiWPQ2PSI0,5132
+threetears/core/testing/fixtures.py,sha256=urGJ_vKCuBoTvL8tvSJ4YJl7kiYKiLBnqYnFsv_PsMw,5417
+threetears/core/testing/sqla_parity.py,sha256=it5hNUhRHJbTsihUstaQILeR8gN3ucA-_dNtp2oZo-M,13730
+threetears/core/utils/__init__.py,sha256=5J7nVqjGILm4OTuDXXWM1eIO3eqeNxi2bsCQlPRgBQY,850
+threetears/core/utils/atomic_write.py,sha256=ka3Zcp8iOVCIYHsmPsSkvsXPzKDVCU0vnVPVFmRPDhs,2887
+threetears/core/utils/pg_pool_kwargs.py,sha256=NzbDA3eJzLhkeiuKdh2xGf7v3hbWDyNeKfnROdZS2ws,13503
+threetears/knowledge/__init__.py,sha256=F8nzHbO0b9m2AQC6ZlXucLicGb3a5nDU8iG-z1J2CUs,2390
+threetears/knowledge/chains.py,sha256=vmxuQxY3j4G5O53pP5WN0vniT7seJFlKktFMYKLBKzY,8331
+threetears/knowledge/concept_merge.py,sha256=YXFx3RoR1TyNLEi8KX4JBtBLDmRjfRHvYDBAHn6t0tg,12189
+threetears/knowledge/events.py,sha256=4dINoD6ShwaxJd0Gq5BGdoLbdkq5YZKAJdrow6_i_4E,9398
+threetears/knowledge/merge.py,sha256=iCigU-AyzvZ7qkc6EL--8jvY0m6kLQnlbE1-JpSHWLU,13915
+threetears/knowledge/scope.py,sha256=PrMzejWMKVOxxHu8Cpr3e7V_laFHlS5fMtSjPj-owpg,3470
+3tears-0.14.0.dist-info/METADATA,sha256=xZFiUGGW9IYLq8exv8et4HBVAfTFctNt7NxbmN7ukLI,8438
+3tears-0.14.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+3tears-0.14.0.dist-info/licenses/LICENSE,sha256=7GWEoEOcFJenZLt4LDzqH2K7QLxo_2m8rzG7Vv8VGXo,1066
+3tears-0.14.0.dist-info/RECORD,,

3tears-0.14.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

3tears-0.14.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Pace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

threetears/core/__init__.py

@@ -0,0 +1,170 @@
+"""threetears.core — three-tier caching framework.
+
+Public API re-exports for convenient top-level imports.
+"""
+
+from __future__ import annotations
+
+# Version derived from pyproject.toml so the metadata is the single
+# source of truth -- a future release that bumps pyproject without
+# updating ``__init__.py`` can't drift the runtime ``__version__``.
+# The except guard handles the rare case where the package isn't
+# installed via importlib.metadata (e.g. running directly from a
+# checked-out source tree without ``uv sync``); the fallback keeps
+# imports working but reports ``unknown`` rather than crashing.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+from typing import TYPE_CHECKING
+
+try:
+    __version__ = _version("3tears")
+except _PackageNotFoundError:  # pragma: no cover - dev fallback
+    __version__ = "unknown"
+
+# lazy public API (PEP 562). the package namespace no longer imports its
+# implementation modules eagerly: importing this package (or any of its
+# submodules) costs only this file, and each public attribute resolves
+# its defining module on first access. the TYPE_CHECKING block carries
+# the real imports so mypy and IDEs see the full statically-typed API;
+# the _LAZY map is the runtime equivalent. the three-way agreement
+# between __all__, _LAZY, and the TYPE_CHECKING block is pinned by the
+# package's lazy-surface consistency test.
+# decision record: docs/separate-concerns-decisions.md (hand-rolled
+# PEP 562 over lazy_loader -- zero added runtime deps, no stub drift).
+if TYPE_CHECKING:
+    from threetears.core.collections.base import BaseCollection
+    from threetears.core.collections.registry import CollectionRegistry
+    from threetears.core.config import CoreConfig, DefaultCoreConfig
+    from threetears.core.coordination import KVLease, LeaseHandle, LeaseLost, LeaseTimeout, LeaseUnavailable
+    from threetears.core.data.collection_factory import create_dynamic_collection
+    from threetears.core.data.migrations import MigrationRunner
+    from threetears.core.data.schema import ColumnDef, ForeignKeyDef, IndexDef, TableDef
+    from threetears.core.data.sql_builder import build_create_index_sql, build_create_table_sql
+    from threetears.core.data.store import DataStore
+    from threetears.core.entities.base import BaseEntity
+    from threetears.core.exceptions import ConcurrentModificationError, DataLayerUnavailableError
+    from threetears.core.namespaces import PLURAL_PREFIX_BY_NAMESPACE_TYPE, build_namespace_name, sanitize_segment
+    from threetears.core.pagination import CursorError, Keyset, Page, decode_cursor, encode_cursor
+    from threetears.core.security import PathSandbox, Sandbox, SandboxDecision, SandboxDenied
+    from threetears.core.serialization import (
+        FormatHandler,
+        UnknownFormatError,
+        deserialize_from_json,
+        handler_for,
+        register_handler,
+        serialize_to_json,
+    )
+    from threetears.core.utils.atomic_write import atomic_write
+
+# public attribute -> (defining module, attribute name in that module)
+_LAZY: dict[str, tuple[str, str]] = {
+    "BaseCollection": ("threetears.core.collections.base", "BaseCollection"),
+    "BaseEntity": ("threetears.core.entities.base", "BaseEntity"),
+    "CollectionRegistry": ("threetears.core.collections.registry", "CollectionRegistry"),
+    "ColumnDef": ("threetears.core.data.schema", "ColumnDef"),
+    "ConcurrentModificationError": ("threetears.core.exceptions", "ConcurrentModificationError"),
+    "CoreConfig": ("threetears.core.config", "CoreConfig"),
+    "CursorError": ("threetears.core.pagination", "CursorError"),
+    "DataLayerUnavailableError": ("threetears.core.exceptions", "DataLayerUnavailableError"),
+    "DataStore": ("threetears.core.data.store", "DataStore"),
+    "DefaultCoreConfig": ("threetears.core.config", "DefaultCoreConfig"),
+    "ForeignKeyDef": ("threetears.core.data.schema", "ForeignKeyDef"),
+    "FormatHandler": ("threetears.core.serialization", "FormatHandler"),
+    "IndexDef": ("threetears.core.data.schema", "IndexDef"),
+    "KVLease": ("threetears.core.coordination", "KVLease"),
+    "Keyset": ("threetears.core.pagination", "Keyset"),
+    "LeaseHandle": ("threetears.core.coordination", "LeaseHandle"),
+    "LeaseLost": ("threetears.core.coordination", "LeaseLost"),
+    "LeaseTimeout": ("threetears.core.coordination", "LeaseTimeout"),
+    "LeaseUnavailable": ("threetears.core.coordination", "LeaseUnavailable"),
+    "MigrationRunner": ("threetears.core.data.migrations", "MigrationRunner"),
+    "PLURAL_PREFIX_BY_NAMESPACE_TYPE": ("threetears.core.namespaces", "PLURAL_PREFIX_BY_NAMESPACE_TYPE"),
+    "Page": ("threetears.core.pagination", "Page"),
+    "PathSandbox": ("threetears.core.security", "PathSandbox"),
+    "Sandbox": ("threetears.core.security", "Sandbox"),
+    "SandboxDecision": ("threetears.core.security", "SandboxDecision"),
+    "SandboxDenied": ("threetears.core.security", "SandboxDenied"),
+    "TableDef": ("threetears.core.data.schema", "TableDef"),
+    "UnknownFormatError": ("threetears.core.serialization", "UnknownFormatError"),
+    "atomic_write": ("threetears.core.utils.atomic_write", "atomic_write"),
+    "build_create_index_sql": ("threetears.core.data.sql_builder", "build_create_index_sql"),
+    "build_create_table_sql": ("threetears.core.data.sql_builder", "build_create_table_sql"),
+    "build_namespace_name": ("threetears.core.namespaces", "build_namespace_name"),
+    "create_dynamic_collection": ("threetears.core.data.collection_factory", "create_dynamic_collection"),
+    "decode_cursor": ("threetears.core.pagination", "decode_cursor"),
+    "deserialize_from_json": ("threetears.core.serialization", "deserialize_from_json"),
+    "encode_cursor": ("threetears.core.pagination", "encode_cursor"),
+    "handler_for": ("threetears.core.serialization", "handler_for"),
+    "register_handler": ("threetears.core.serialization", "register_handler"),
+    "sanitize_segment": ("threetears.core.namespaces", "sanitize_segment"),
+    "serialize_to_json": ("threetears.core.serialization", "serialize_to_json"),
+}
+
+__all__ = [
+    "BaseCollection",
+    "BaseEntity",
+    "CollectionRegistry",
+    "ColumnDef",
+    "ConcurrentModificationError",
+    "CoreConfig",
+    "CursorError",
+    "DataLayerUnavailableError",
+    "DataStore",
+    "DefaultCoreConfig",
+    "ForeignKeyDef",
+    "FormatHandler",
+    "IndexDef",
+    "KVLease",
+    "LeaseHandle",
+    "LeaseLost",
+    "LeaseTimeout",
+    "LeaseUnavailable",
+    "MigrationRunner",
+    "PLURAL_PREFIX_BY_NAMESPACE_TYPE",
+    "PathSandbox",
+    "Sandbox",
+    "SandboxDecision",
+    "SandboxDenied",
+    "TableDef",
+    "UnknownFormatError",
+    "atomic_write",
+    "build_create_index_sql",
+    "build_create_table_sql",
+    "build_namespace_name",
+    "create_dynamic_collection",
+    "deserialize_from_json",
+    "handler_for",
+    "register_handler",
+    "sanitize_segment",
+    "serialize_to_json",
+]
+
+
+def __getattr__(name: str) -> object:
+    """resolve a public attribute from its defining module on first access.
+
+    :param name: attribute name being resolved
+    :ptype name: str
+    :return: the resolved attribute (also cached in module globals so
+        ``__getattr__`` fires at most once per name)
+    :rtype: object
+    :raises AttributeError: when ``name`` is not part of the public API
+    """
+    entry = _LAZY.get(name)
+    if entry is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    module_name, attr = entry
+    value: object = getattr(import_module(module_name), attr)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """include lazy attributes in ``dir()`` output.
+
+    :return: sorted union of materialized globals and lazy names
+    :rtype: list[str]
+    """
+    return sorted(set(globals()) | set(_LAZY))

threetears/core/_bridge.py

@@ -0,0 +1,102 @@
+"""Background event loop for sync-to-async bridging.
+
+Provides a singleton daemon thread running its own event loop. Sync code
+(like __getitem__) submits async coroutines via run_coroutine_threadsafe
+and blocks on the result.
+
+``fire_and_forget`` is loop-aware: when called from a thread that already
+has a running event loop (e.g., an ASGI handler), it schedules the task on
+that loop via ``create_task`` so that async resources (e.g., asyncpg
+connection pools) stay on the correct loop. When called from pure sync code
+with no running loop, it falls back to the background loop.
+
+Pattern borrowed from fsspec (pandas/dask/xarray ecosystem).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Any, Coroutine, TypeVar
+
+__all__ = [
+    "T",
+    "drain",
+    "fire_and_forget",
+    "shutdown",
+    "sync_await",
+]
+
+T = TypeVar("T")
+
+_lock = threading.Lock()
+_loop: asyncio.AbstractEventLoop | None = None
+_thread: threading.Thread | None = None
+
+
+def _ensure_loop() -> asyncio.AbstractEventLoop:
+    """Lazily start the background event loop on first use."""
+    global _loop, _thread
+    if _loop is not None and _loop.is_running():
+        return _loop
+    with _lock:
+        if _loop is not None and _loop.is_running():
+            return _loop
+        _loop = asyncio.new_event_loop()
+        _thread = threading.Thread(
+            target=_loop.run_forever,
+            daemon=True,
+            name="threetears-async-bridge",
+        )
+        _thread.start()
+        return _loop
+
+
+def sync_await(coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine from sync code, blocking until complete."""
+    loop = _ensure_loop()
+    future = asyncio.run_coroutine_threadsafe(coro, loop)
+    return future.result()
+
+
+def fire_and_forget(coro: Coroutine[Any, Any, Any]) -> None:
+    """Submit an async coroutine without blocking.
+
+    When called from a thread with a running event loop, schedules the task
+    on that loop (``create_task``). When called from pure sync code, uses
+    the background loop (``run_coroutine_threadsafe``).
+    """
+    try:
+        loop = asyncio.get_running_loop()
+        loop.create_task(coro)
+    except RuntimeError:
+        bg_loop = _ensure_loop()
+        asyncio.run_coroutine_threadsafe(coro, bg_loop)
+
+
+def drain() -> None:
+    """Wait for all pending tasks on the background loop to complete."""
+    if _loop is None or not _loop.is_running():
+        return
+
+    async def _drain() -> None:
+        # Get all tasks on this loop and wait for them
+        tasks = [t for t in asyncio.all_tasks(_loop) if not t.done() and t is not asyncio.current_task()]
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    future = asyncio.run_coroutine_threadsafe(_drain(), _loop)
+    future.result(timeout=10)
+
+
+def shutdown() -> None:
+    """Stop the background loop and join the thread. For clean teardown."""
+    global _loop, _thread
+    if _loop is not None and _loop.is_running():
+        _loop.call_soon_threadsafe(_loop.stop)
+    if _thread is not None:
+        _thread.join(timeout=5)
+        _thread = None
+    if _loop is not None:
+        _loop.close()
+        _loop = None

threetears/core/backends/__init__.py

@@ -0,0 +1,16 @@
+"""L3 durable-tier backends + protocols."""
+
+from __future__ import annotations
+
+from threetears.core.backends.nats_proxy import NatsProxyL3Backend
+from threetears.core.backends.protocol import DurableStore, L3Backend, parse_rowcount
+from threetears.core.backends.sql import SqlL3Backend, bound_request_connection
+
+__all__ = [
+    "DurableStore",
+    "L3Backend",
+    "NatsProxyL3Backend",
+    "SqlL3Backend",
+    "bound_request_connection",
+    "parse_rowcount",
+]