3tears-enforcement 0.14.0__tar.gz

3tears_enforcement-0.14.0/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Claude Code local state
+.claude/
+
+# prawduct session evidence (local governance artifacts, never shipped)
+.prawduct/
+
+# macOS folder metadata
+.DS_Store

3tears_enforcement-0.14.0/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.

3tears_enforcement-0.14.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: 3tears-enforcement
+Version: 0.14.0
+Summary: Static-analysis enforcement scanners for the 3tears ecosystem (cache primitive contract, underscore-access discipline, codebase conventions, etc.)
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: 3tears>=0.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# 3tears-enforcement
+
+Shared static-analysis enforcement scanners for the 3tears ecosystem.
+
+## What this package does
+
+Each module under `threetears.enforcement.<domain>` ships an AST-based scanner that enforces a single architectural invariant across a Python source tree. Consumer repos import the scanner, inject their per-repo configuration (allowlists, exemption files, src roots), and run it from a thin pytest test class.
+
+This replaces a previous pattern in which the same enforcement test files were vendored verbatim across multiple repos with manual sync requirements. The shared package eliminates duplication and drift while keeping per-repo configuration where it belongs.
+
+## Domains
+
+| Module | Invariant enforced |
+|---|---|
+| `cache` | Every stateful data surface routes through `BaseCollection`; no bespoke SQLiteBackend wrappers; no direct pool access to Collection-backed tables; every migration-defined table has a Collection class. |
+| `underscore_access` | Underscore prefix is a stability contract: no cross-module private import, no cross-class protected access, modules with public names have `__all__`, no subclass shadowing of base private attributes, no `__all__` listing private names. |
+| `codebase_conventions` | No bare `print()`, no stdlib `logging.getLogger` (use `threetears.observe`), `from __future__ import annotations` required, return type annotations required. |
+| `coercion_coverage` | Tool subclasses override `execute`, never `run`, preserving the `normalize_kwargs → execute` input-coercion path. |
+| `dict_state_detection` | No raw `dict`/`OrderedDict` persistent state in `__init__`; use `SQLiteBackend` (L1) or NATS KV for shared state. |
+| `logger_coverage` | Every production module declares a module-level `log = get_logger(__name__)` unless explicitly exempt. |
+| `migration_yugabyte_safety` | Migration shapes are yugabyte-safe per `threetears.core.data.migrations.enforcement`. |
+| `nats_wrapper_usage` | All `nats-py` imports route through `threetears.nats.NatsClient`; no direct `import nats`. |
+| `no_silent_swallow` | Exception handlers must log, re-raise, or carry `# NOSILENT: <reason>`. |
+| `no_stdlib_logging` | No production module imports stdlib `logging` directly; use `threetears.observe`. |
+
+## How to use it
+
+Each domain exposes a configuration dataclass and a high-level runner:
+
+```python
+# tests/enforcement/test_cache_primitive_usage.py
+from pathlib import Path
+from threetears.enforcement.cache import CacheEnforcementConfig, run_cache_enforcement
+
+_CONFIG = CacheEnforcementConfig(
+    repo_root=Path(__file__).parents[2],
+    allowed_sqlite_construction_sites=frozenset({
+        "packages/registry/src/threetears/registry/l1_cache.py",
+    }),
+    collection_table_allowlist={
+        "memories": "MemoriesCollection",
+        # ... per-repo
+    },
+    migration_table_allowlist=frozenset({"_schema_migrations"}),
+    exemptions_path=Path(__file__).parent / "_cache_exemptions.txt",
+    enforcement_mode_env_var="CACHE_ENFORCEMENT_MODE",
+)
+
+class TestCachePrimitiveUsage:
+    def test_no_bespoke_sqlite_backend_construction(self) -> None:
+        run_cache_enforcement(_CONFIG, walker="sqlite_construction")
+
+    def test_no_bespoke_cache_wrapper_classes(self) -> None:
+        run_cache_enforcement(_CONFIG, walker="wrapper_class")
+
+    def test_no_direct_pool_access_to_collection_tables(self) -> None:
+        run_cache_enforcement(_CONFIG, walker="pool_access")
+
+    def test_all_tables_have_collections(self) -> None:
+        run_cache_enforcement(_CONFIG, walker="missing_collection")
+```
+
+Per-repo exemption files (e.g., `_cache_exemptions.txt`) stay in the consumer repo's `tests/enforcement/` directory. The package's `parse_exemptions_with_rationale` reads them at test time.
+
+## How to onboard a new repo
+
+1. Add `3tears-enforcement` as a dev dependency.
+2. For each domain you want to enforce: create a thin shell test file at `tests/enforcement/test_<domain>.py` following the pattern above. Inject your repo's allowlists/exemptions.
+3. Create per-domain exemption files at `tests/enforcement/_<domain>_exemptions.txt` if needed. Every exemption requires a preceding `# rationale: <specific reason>` line.
+4. Run `pytest tests/enforcement/` to verify the scanners work against your tree.
+
+## How to add a new enforcement domain
+
+1. Create `src/threetears/enforcement/<domain>/` with `walkers.py`, `config.py`, `runner.py`, and `__init__.py`.
+2. Use `common/` helpers (`ast_helpers`, `repo_layout`, `pyproject_discovery`, `inheritance`, `exemptions`, `modes`, `violations`, `reports`). Do not duplicate scaffolding.
+3. Walkers return `list[Violation]`. Configs are frozen dataclasses. Runners orchestrate walker → exemption-application → mode-resolution → report.
+4. Write unit tests in `tests/<domain>/`.
+5. Document the domain in this README.

3tears_enforcement-0.14.0/README.md

@@ -0,0 +1,78 @@
+# 3tears-enforcement
+
+Shared static-analysis enforcement scanners for the 3tears ecosystem.
+
+## What this package does
+
+Each module under `threetears.enforcement.<domain>` ships an AST-based scanner that enforces a single architectural invariant across a Python source tree. Consumer repos import the scanner, inject their per-repo configuration (allowlists, exemption files, src roots), and run it from a thin pytest test class.
+
+This replaces a previous pattern in which the same enforcement test files were vendored verbatim across multiple repos with manual sync requirements. The shared package eliminates duplication and drift while keeping per-repo configuration where it belongs.
+
+## Domains
+
+| Module | Invariant enforced |
+|---|---|
+| `cache` | Every stateful data surface routes through `BaseCollection`; no bespoke SQLiteBackend wrappers; no direct pool access to Collection-backed tables; every migration-defined table has a Collection class. |
+| `underscore_access` | Underscore prefix is a stability contract: no cross-module private import, no cross-class protected access, modules with public names have `__all__`, no subclass shadowing of base private attributes, no `__all__` listing private names. |
+| `codebase_conventions` | No bare `print()`, no stdlib `logging.getLogger` (use `threetears.observe`), `from __future__ import annotations` required, return type annotations required. |
+| `coercion_coverage` | Tool subclasses override `execute`, never `run`, preserving the `normalize_kwargs → execute` input-coercion path. |
+| `dict_state_detection` | No raw `dict`/`OrderedDict` persistent state in `__init__`; use `SQLiteBackend` (L1) or NATS KV for shared state. |
+| `logger_coverage` | Every production module declares a module-level `log = get_logger(__name__)` unless explicitly exempt. |
+| `migration_yugabyte_safety` | Migration shapes are yugabyte-safe per `threetears.core.data.migrations.enforcement`. |
+| `nats_wrapper_usage` | All `nats-py` imports route through `threetears.nats.NatsClient`; no direct `import nats`. |
+| `no_silent_swallow` | Exception handlers must log, re-raise, or carry `# NOSILENT: <reason>`. |
+| `no_stdlib_logging` | No production module imports stdlib `logging` directly; use `threetears.observe`. |
+
+## How to use it
+
+Each domain exposes a configuration dataclass and a high-level runner:
+
+```python
+# tests/enforcement/test_cache_primitive_usage.py
+from pathlib import Path
+from threetears.enforcement.cache import CacheEnforcementConfig, run_cache_enforcement
+
+_CONFIG = CacheEnforcementConfig(
+    repo_root=Path(__file__).parents[2],
+    allowed_sqlite_construction_sites=frozenset({
+        "packages/registry/src/threetears/registry/l1_cache.py",
+    }),
+    collection_table_allowlist={
+        "memories": "MemoriesCollection",
+        # ... per-repo
+    },
+    migration_table_allowlist=frozenset({"_schema_migrations"}),
+    exemptions_path=Path(__file__).parent / "_cache_exemptions.txt",
+    enforcement_mode_env_var="CACHE_ENFORCEMENT_MODE",
+)
+
+class TestCachePrimitiveUsage:
+    def test_no_bespoke_sqlite_backend_construction(self) -> None:
+        run_cache_enforcement(_CONFIG, walker="sqlite_construction")
+
+    def test_no_bespoke_cache_wrapper_classes(self) -> None:
+        run_cache_enforcement(_CONFIG, walker="wrapper_class")
+
+    def test_no_direct_pool_access_to_collection_tables(self) -> None:
+        run_cache_enforcement(_CONFIG, walker="pool_access")
+
+    def test_all_tables_have_collections(self) -> None:
+        run_cache_enforcement(_CONFIG, walker="missing_collection")
+```
+
+Per-repo exemption files (e.g., `_cache_exemptions.txt`) stay in the consumer repo's `tests/enforcement/` directory. The package's `parse_exemptions_with_rationale` reads them at test time.
+
+## How to onboard a new repo
+
+1. Add `3tears-enforcement` as a dev dependency.
+2. For each domain you want to enforce: create a thin shell test file at `tests/enforcement/test_<domain>.py` following the pattern above. Inject your repo's allowlists/exemptions.
+3. Create per-domain exemption files at `tests/enforcement/_<domain>_exemptions.txt` if needed. Every exemption requires a preceding `# rationale: <specific reason>` line.
+4. Run `pytest tests/enforcement/` to verify the scanners work against your tree.
+
+## How to add a new enforcement domain
+
+1. Create `src/threetears/enforcement/<domain>/` with `walkers.py`, `config.py`, `runner.py`, and `__init__.py`.
+2. Use `common/` helpers (`ast_helpers`, `repo_layout`, `pyproject_discovery`, `inheritance`, `exemptions`, `modes`, `violations`, `reports`). Do not duplicate scaffolding.
+3. Walkers return `list[Violation]`. Configs are frozen dataclasses. Runners orchestrate walker → exemption-application → mode-resolution → report.
+4. Write unit tests in `tests/<domain>/`.
+5. Document the domain in this README.

3tears_enforcement-0.14.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "3tears-enforcement"
+version = "0.14.0"
+description = "Static-analysis enforcement scanners for the 3tears ecosystem (cache primitive contract, underscore-access discipline, codebase conventions, etc.)"
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [{name = "pace"}]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "3tears>=0.5.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+]
+
+[project.urls]
+Repository = "https://github.com/pacepace/3tears"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threetears"]
+
+[tool.uv.sources]
+3tears = { workspace = true }

3tears_enforcement-0.14.0/src/threetears/enforcement/__init__.py

@@ -0,0 +1,5 @@
+"""3tears-enforcement: shared static-analysis enforcement scanners.
+
+See package README for the catalog of enforcement domains and onboarding
+instructions for new consumer repos.
+"""

3tears_enforcement-0.14.0/src/threetears/enforcement/cache/__init__.py

@@ -0,0 +1,52 @@
+"""cache enforcement domain — the 3tears Collection-as-the-primitive contract.
+
+four walkers in this domain enforce that every stateful data surface
+in a 3tears-consuming repo is a :class:`BaseCollection` (transitively)
+rather than a bespoke wrapper around :class:`SQLiteBackend` or a raw
+``pool.fetch`` call:
+
+- :func:`find_sqlite_constructions` — flag every
+  ``SQLiteBackend(...)`` call outside the sanctioned factories.
+- :func:`find_wrapper_classes` — flag classes that hold a
+  ``SQLiteBackend`` field AND expose cache api (``get`` / ``put`` /
+  ``set`` / ``delete`` / ``upsert``) AND do NOT transitively subclass
+  any ``base_collection_names``.
+- :func:`find_direct_pool_access` — flag ``pool.fetch`` /
+  ``fetchrow`` / ``fetchval`` / ``execute`` calls whose SQL text
+  references a table mapped in ``collection_table_allowlist``.
+- :func:`find_missing_collections` — flag migration-defined tables
+  whose mapped Collection class does not transitively subclass any
+  ``base_collection_names``. **uses** :func:`transitively_subclasses_any
+  <threetears.enforcement.common.inheritance.transitively_subclasses_any>`
+  so chains like ``MemoriesCollection → SchemaBackedCollection →
+  BaseCollection`` resolve correctly across path-dep package
+  boundaries (this is the originally-failing bug fix the cache lift
+  was created for).
+
+per-repo configuration goes through :class:`CacheEnforcementConfig`;
+:func:`run_cache_enforcement` is the pytest-friendly entry point that
+orchestrates the walkers, applies the rationale-required exemption
+list, emits the report, and fails in strict mode.
+"""
+
+from threetears.enforcement.cache.config import (
+    CacheEnforcementConfig,
+)
+from threetears.enforcement.cache.runner import (
+    run_cache_enforcement,
+)
+from threetears.enforcement.cache.walkers import (
+    find_direct_pool_access,
+    find_missing_collections,
+    find_sqlite_constructions,
+    find_wrapper_classes,
+)
+
+__all__ = [
+    "CacheEnforcementConfig",
+    "find_direct_pool_access",
+    "find_missing_collections",
+    "find_sqlite_constructions",
+    "find_wrapper_classes",
+    "run_cache_enforcement",
+]

3tears_enforcement-0.14.0/src/threetears/enforcement/cache/config.py

@@ -0,0 +1,138 @@
+"""configuration dataclass for cache-primitive-usage enforcement.
+
+the cache domain enforces a single contract: every stateful data
+surface in a consuming repo is a :class:`BaseCollection` (transitively)
+rather than a bespoke wrapper around :class:`SQLiteBackend` or raw
+``pool`` access. four walkers cover the four ways the contract can be
+broken (bespoke construction, wrapper classes, direct pool access,
+migration-defined tables that lack a Collection); one config dataclass
+captures every per-repo knob.
+
+the configurable knobs let consumers manage repo-specific allowlists
+without forking the walkers:
+
+- :attr:`allowed_sqlite_construction_sites` — relative-posix paths
+  where bare :class:`SQLiteBackend(...)` construction is sanctioned
+  (named factories like ``hub/common/l1_cache.py``). ``tests/`` trees
+  are always permitted regardless of this set; the canonical
+  hardcodes that.
+- :attr:`collection_table_allowlist` — table-to-Collection-class
+  mapping. drives both the direct-pool-access walker (which knows
+  which tables have a Collection) and the missing-collection walker
+  (which verifies the named class actually exists and transitively
+  reaches a Collection base).
+- :attr:`migration_table_allowlist` — bookkeeping tables defined in
+  migrations that legitimately lack Collections
+  (``_schema_migrations``, LangGraph ``checkpoints``).
+- :attr:`base_collection_names` — terminal class names that satisfy
+  "this is a Collection". default is ``{"BaseCollection"}``;
+  intermediate bases (``SchemaBackedCollection``, etc.) are walked
+  transitively via the common inheritance graph and do NOT need to
+  be listed here.
+- :attr:`scan_roots` / :attr:`inheritance_roots` — split src-root
+  responsibilities. ``scan_roots`` is *where to look for violations*
+  (defaults to :func:`find_local_src_roots
+  <threetears.enforcement.common.repo_layout.find_local_src_roots>`,
+  the consumer's own code only — never path-deps). ``inheritance_roots``
+  is *where to build the cross-package class-base graph* used by
+  :func:`find_wrapper_classes` and :func:`find_missing_collections`'s
+  transitive subclass walk (defaults to :func:`discover_src_roots
+  <threetears.enforcement.common.pyproject_discovery.discover_src_roots>`,
+  which is path-dep aware so chains like ``MemoriesCollection →
+  SchemaBackedCollection → BaseCollection`` resolve across package
+  boundaries). splitting them prevents Option B path-dep walking from
+  dragging upstream code into the violation scan.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__all__ = ["CacheEnforcementConfig"]
+
+
+_DEFAULT_CACHE_METHOD_NAMES: frozenset[str] = frozenset(
+    {
+        "get",
+        "put",
+        "set",
+        "delete",
+        "upsert",
+    }
+)
+
+
+_DEFAULT_BASE_COLLECTION_NAMES: frozenset[str] = frozenset({"BaseCollection"})
+
+
+@dataclass(frozen=True)
+class CacheEnforcementConfig:
+    """per-repo config for the cache-primitive-usage enforcement domain.
+
+    :ivar repo_root: absolute path to the consumer repo's root (the
+        directory containing its top-level ``pyproject.toml``).
+    :ivar scan_roots: where to LOOK for violations. when ``None``, the
+        runner uses :func:`find_local_src_roots
+        <threetears.enforcement.common.repo_layout.find_local_src_roots>`
+        — always scoped to the consumer's own code, never walks
+        path-deps. set explicitly only to override discovery in tests
+        or specialised harnesses.
+    :ivar inheritance_roots: where to BUILD the inheritance graph
+        (used by :func:`~threetears.enforcement.cache.walkers.find_wrapper_classes`
+        and :func:`~threetears.enforcement.cache.walkers.find_missing_collections`
+        for :func:`transitively_subclasses_any
+        <threetears.enforcement.common.inheritance.transitively_subclasses_any>`).
+        when ``None``, the runner uses :func:`discover_src_roots
+        <threetears.enforcement.common.pyproject_discovery.discover_src_roots>`
+        — path-dep aware so chains like ``MemoriesCollection →
+        SchemaBackedCollection → BaseCollection`` resolve correctly
+        across package boundaries.
+    :ivar exemptions_path: path to ``_cache_exemptions.txt``;
+        ``None`` means "no exemptions file". the file uses the shared
+        rationale-required ``file:line:symbol`` format parsed by
+        :func:`~threetears.enforcement.common.exemptions.parse_exemptions_with_rationale`.
+    :ivar mode_env_var: environment variable controlling strict vs
+        report mode. defaults to ``CACHE_ENFORCEMENT_MODE``.
+    :ivar allowed_sqlite_construction_sites: forward-slash relative
+        paths (relative to ``repo_root``) where bare
+        :class:`SQLiteBackend(...)` construction is sanctioned. files
+        under any ``tests/`` directory are always permitted regardless
+        of this set; the canonical hardcodes that.
+    :ivar collection_table_allowlist: ``{table_name:
+        expected_collection_class_name}`` mapping. drives both
+        :func:`~threetears.enforcement.cache.walkers.find_direct_pool_access`
+        (which tables have a Collection) and
+        :func:`~threetears.enforcement.cache.walkers.find_missing_collections`
+        (which verifies the named class transitively reaches a
+        Collection base).
+    :ivar migration_table_allowlist: tables created in migrations that
+        legitimately lack Collections. bookkeeping tables (e.g.
+        ``_schema_migrations``), LangGraph state (``checkpoints``,
+        ``checkpoint_writes``), and tables owned by sibling repos.
+    :ivar cache_method_names: public method names that, combined with
+        a :class:`SQLiteBackend` field, indicate a wrapper class.
+        kept liberal so any new bespoke wrapper hits the walker;
+        defaults to ``{"get", "put", "set", "delete", "upsert"}``.
+    :ivar base_collection_names: terminal class names that satisfy
+        "this is a Collection." default is just ``{"BaseCollection"}``
+        — transitive walking through ``SchemaBackedCollection`` and
+        other intermediate bases is automatic via
+        :func:`~threetears.enforcement.common.inheritance.transitively_subclasses_any`.
+        consumers do NOT need to enumerate intermediate bases here.
+    """
+
+    repo_root: Path
+    scan_roots: tuple[Path, ...] | None = None
+    inheritance_roots: tuple[Path, ...] | None = None
+    exemptions_path: Path | None = None
+    mode_env_var: str = "CACHE_ENFORCEMENT_MODE"
+    allowed_sqlite_construction_sites: frozenset[str] = frozenset()
+    collection_table_allowlist: dict[str, str] = field(default_factory=dict)
+    migration_table_allowlist: frozenset[str] = frozenset()
+    cache_method_names: frozenset[str] = field(
+        default_factory=lambda: _DEFAULT_CACHE_METHOD_NAMES,
+    )
+    base_collection_names: frozenset[str] = field(
+        default_factory=lambda: _DEFAULT_BASE_COLLECTION_NAMES,
+    )