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

Adopting invalidation_listener in a repo that already runs a local copy. Three things change, and only the first is obvious.

The exemption format. The hub's pre-shared walker keyed by BARE MODULE PATH (src/aibots/gateway/acl.py). The shared parser wants a path:line:symbol triple and rejects anything else with ExemptionError, so an unmigrated file does not degrade -- it aborts the domain. Rewrite each entry as <path>:*:<registry-spelling>, keeping its # rationale: line. * means "any line in that file", which is what you want: keying an exemption to a line number silently stops matching when the line moves.

minimum_live_registries is yours to supply, and it is REQUIRED with no default. Count the L2-live registries your repo actually wires and put that number in the shell. It is the floor that makes a green report mean anything.

Repo-specific shell assertions do not come across. A local walker typically carries checks the shared domain has no equivalent for -- which processes must be in scope, that an L1-only registry is not dragged in, detector positive/negative cases. Those are yours to keep: port them into the thin shell rather than assuming the domain replaced them, because deleting the local file deletes them silently.

This note describes a one-time migration and should be deleted once every consumer has adopted the domain. Tracked as ENF-7WQ2 in the 14-eng-ai-bot backlog, which is this family's backlog of record -- not this repo's, so do not go looking for it here.

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.
`dependency_alignment`	Declared dependencies match actual imports (no undeclared module-top sibling import, no declaration nothing imports); designated contracts packages import only stdlib, their own namespace, and configured extras; a package with a pinned `DependencyFloor` declares exactly the ruled hard-dependency list, no more and no fewer.
`dict_state_detection`	No raw `dict`/`OrderedDict` persistent state in `__init__`; use `SQLiteBackend` (L1) or NATS KV for shared state.
`invalidation_listener`	Every L2-live `CollectionRegistry` starts the cross-pod invalidation listener, and every start is paired with a stop. Carries a REQUIRED non-vacuity floor: a scan reaching nothing reports what a clean repo reports.
`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:

# 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

Add 3tears-enforcement as a dev dependency.
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.
Create per-domain exemption files at tests/enforcement/_<domain>_exemptions.txt if needed. Every exemption requires a preceding # rationale: <specific reason> line.
Run pytest tests/enforcement/ to verify the scanners work against your tree.

How to add a new enforcement domain

Create src/threetears/enforcement/<domain>/ with walkers.py, config.py, runner.py, and __init__.py.
Use common/ helpers (ast_helpers, collection_registry, repo_layout, pyproject_discovery, inheritance, exemptions, modes, violations, reports). Do not duplicate scaffolding. Two in particular, because both have already been re-implemented in this package rather than imported:
- ast_helpers owns the dotted-name spelling family -- dotted, callee_names, receiver, argument_spellings. If you are about to write a loop that walks an ast.Attribute chain accumulating segments, it exists. Three copies of that walk shipped here before it was shared, each differing by one detail that turned out to be a parameter (dotted's unwrap_subscript is the survivor).
- collection_registry owns "which CollectionRegistry names are L2-live" -- take the answer from there rather than re-deriving it. CLIENT_SPELLINGS is a heuristic list that grows, so a second copy goes stale silently while still compiling.
Walkers return list[Violation]. Configs are frozen dataclasses. Runners orchestrate walker → exemption-application → mode-resolution → report.
Write unit tests in tests/<domain>/.
Document the domain in this README.

Release files for 3tears-enforcement 0.51.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for 3tears-enforcement 0.51.0
File	Size	Uploaded
3tears_enforcement-0.51.0.tar.gz	218.5 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for 3tears-enforcement 0.51.0
File	Interpreter	ABI	Platform	Reset
3tears_enforcement-0.51.0-py3-none-any.whl 201.0 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 419.6 kB

Release files / 3tears_enforcement-0.51.0.tar.gz

Download URL	3tears_enforcement-0.51.0.tar.gz
Size	218.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`ef8842774ec8caa34e010ae9f65e03d6545e90869464a642a3259acddc31c38d`
BLAKE2b-256 checksum How to use checksums	`b3415d4b6053e838ac6afc1e1e9b2c52d6db65e39797f7d6af8d0d542bc7ddb5`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/pacepace/3tears
Publishing commit: github.com/pacepace/3tears/tree/a32576d6b81eabb20fc1d573fd36e39dcc9bcfc4

Workflow

Publishing configuration: github.com/pacepace/3tears/blob/a32576d6b81eabb20fc1d573fd36e39dcc9bcfc4/.github/workflows/release.yml
Publishing logs: github.com/pacepace/3tears/actions/runs/35951365800/attempts/1

Artifact

Subject: 3tears_enforcement-0.51.0.tar.gz
SHA-256 checksum: ef8842774ec8caa34e010ae9f65e03d6545e90869464a642a3259acddc31c38d Verifying attestations

Release files / 3tears_enforcement-0.51.0-py3-none-any.whl

Download URL	3tears_enforcement-0.51.0-py3-none-any.whl
Size	201.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`47f8fd86e7389d99769f3500e6c303777a740fb0ac54a4b56b1ca3aab55ba6cb`
BLAKE2b-256 checksum How to use checksums	`6b0535f8e3eed06b89398bee23e8f9469685bea23c7276987cb948ae0146f1e1`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/pacepace/3tears
Publishing commit: github.com/pacepace/3tears/tree/a32576d6b81eabb20fc1d573fd36e39dcc9bcfc4

Workflow

Publishing configuration: github.com/pacepace/3tears/blob/a32576d6b81eabb20fc1d573fd36e39dcc9bcfc4/.github/workflows/release.yml
Publishing logs: github.com/pacepace/3tears/actions/runs/35951365800/attempts/1

Artifact

Subject: 3tears_enforcement-0.51.0-py3-none-any.whl
SHA-256 checksum: 47f8fd86e7389d99769f3500e6c303777a740fb0ac54a4b56b1ca3aab55ba6cb Verifying attestations