ff-639 — locks, audit, entitlements

[Tiendil]

No description provided.

[Copilot]

Pull request overview

This PR introduces three new backend modules (ffun.audit, ffun.locks, ffun.entitlements) alongside extensive new/updated specifications and governance rules, and wires entitlements into the CLI and cleaner workflow. It also updates the consistency-check workflow/config and adds async leak detection to the test suite.

Changes:

• Add new shared-service modules: append-only audit storage, PostgreSQL-backed logical mutexes, and entitlement persistence/merging + domain APIs.
• Add ffun entitlements CLI command family and integrate expired-entitlements cleanup into ffun cleaner.
• Expand/structure the specifications + depmesh governance rules, and adjust consistency-check/polish workflows plus test infrastructure (async leak detection).

Reviewed changes

Copilot reviewed 61 out of 68 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
workflows/polish.donna.md	Add timeout for backend test step.
workflows/inconsistency-check.donna.md	Update workflow prose to new “frontier” consistency-check behavior.
specs/meta/general.md	Add “Implementation neutrality” requirements.
specs/meta/backend_modules.md	New spec defining required structure/depmesh rules for backend module specs.
specs/intro.md	Expand spec directory/index entries (modules, CLI behavior, new module specs).
specs/dictionary.md	Add definition for “audit record”.
specs/behavior/cli/entitlements.md	New spec for ffun entitlements CLI contract.
specs/behavior/cli.md	New spec for shared CLI behavior and stable command-family contracts.
specs/backend_architecture/tests.md	Add requirements for asserting persisted effects in tests.
specs/backend_architecture/python.md	New backend-Python conventions (notably __slots__).
specs/backend_architecture/modules/locks.md	New module spec for PostgreSQL-backed logical mutexes.
specs/backend_architecture/modules/entitlements.md	New module spec for entitlement registry, persistence, merging, audit/events.
specs/backend_architecture/modules/audit.md	New module spec for append-only audit records and transactional API.
specs/backend_architecture/modules_layout.md	Update module inventory + stronger domain re-export guidance + dependency rules.
specs/backend_architecture/entities.md	Define SerializedId as a shared-boundary primitive.
specs/backend_architecture/db.md	Tighten schema constraint rules + type spelling + migration guidance + cross-module schema rules.
ffun/tach.toml	Introduce shared_services layer; classify audit/locks/queues accordingly.
ffun/pyproject.toml	Add pyleak; adjust pytest-asyncio loop-scope settings text/options.
ffun/poetry.lock	Lockfile update for new dev deps / Poetry version.
ffun/ffun/queues/tests/test_domain.py	Add tests asserting domain re-exports for tech operations.
ffun/ffun/queues/domain.py	Re-export tech_get_queue_records and tech_clear_queue via domain boundary.
ffun/ffun/locks/tests/test_operations.py	New tests for low-level lock acquire/release operations.
ffun/ffun/locks/tests/test_domain.py	New tests for lock identity, context managers, and concurrency behaviors.
ffun/ffun/locks/tests/make.py	Test factory for unique LockKind values.
ffun/ffun/locks/tests/helpers.py	Test helpers for inspecting lk_locks acquisition rows.
ffun/ffun/locks/tests/init.py	Package marker for locks tests.
ffun/ffun/locks/operations.py	Implement insert/delete acquisition row primitives.
ffun/ffun/locks/migrations/20260719_01_c0DeX-locks.py	Add lk_locks table migration.
ffun/ffun/locks/errors.py	Define lock module error types.
ffun/ffun/locks/entities.py	Define LockKind semantic string type.
ffun/ffun/locks/domain.py	Implement Lock and locked_transaction async context managers + identity validation.
ffun/ffun/locks/init.py	Package marker for locks module.
ffun/ffun/entitlements/tests/test_operations.py	New tests for entitlements persistence operations.
ffun/ffun/entitlements/tests/test_entities.py	New tests for entitlement enums/registry and entity validation.
ffun/ffun/entitlements/tests/test_domain.py	New tests for entitlement workflows, audit records, and business events.
ffun/ffun/entitlements/tests/make.py	Test factories for entitlement entities.
ffun/ffun/entitlements/tests/helpers.py	Test helpers for timestamps and cleanup utilities.
ffun/ffun/entitlements/tests/init.py	Package marker for entitlements tests.
ffun/ffun/entitlements/operations.py	Implement entitlements CRUD/timeline operations and queries.
ffun/ffun/entitlements/migrations/20260717_01_c0DeX-entitlements.py	Add entitlements tables + expiry index migration.
ffun/ffun/entitlements/errors.py	Define entitlement module error types.
ffun/ffun/entitlements/entities.py	Define entitlement enums, registry, and Pydantic entities.
ffun/ffun/entitlements/domain.py	Implement entitlement domain API, locking, audit recording, and business events.
ffun/ffun/entitlements/init.py	Module docstring for entitlements package.
ffun/ffun/domain/entities.py	Introduce SerializedId semantic string type.
ffun/ffun/core/tests/helpers.py	Add pool-capacity assertion helper used by concurrency tests.
ffun/ffun/conftest.py	Add autouse async leak detection via pyleak.
ffun/ffun/cli/commands/tests/test_entitlements.py	New tests for entitlements CLI parsing/dispatch and list output.
ffun/ffun/cli/commands/tests/test_cleaner.py	New test ensuring cleaner runs entitlements cleanup after orphan cleanup.
ffun/ffun/cli/commands/queues.py	Route queue cleanup through domain re-export instead of operations import.
ffun/ffun/cli/commands/entitlements.py	New Typer command family for entitlements management and listing.
ffun/ffun/cli/commands/cleaner.py	Add expired-entitlements cleanup step to cleaner command.
ffun/ffun/cli/application.py	Register entitlements Typer app under root CLI.
ffun/ffun/audit/tests/test_operations.py	New tests for audit record insert/load and transactional behavior.
ffun/ffun/audit/tests/test_entities.py	New tests for stable AuditEntityKind ids.
ffun/ffun/audit/tests/test_domain.py	New tests asserting domain re-exports.
ffun/ffun/audit/tests/helpers.py	Helper for loading a single audit record row.
ffun/ffun/audit/tests/init.py	Package marker for audit tests.
ffun/ffun/audit/operations.py	Implement audit record id generation, insert, and subject query.
ffun/ffun/audit/migrations/20260716_01_c0DeX-audit-records.py	Add a_records table + subject index migration.
ffun/ffun/audit/entities.py	Define audit record entity and semantic types.
ffun/ffun/audit/domain.py	Re-export audit operations via domain boundary.
ffun/ffun/audit/init.py	Package marker for audit module.
depmesh.toml	Add governance rules for CLI specs, module specs, and CLI/module Python files.
consistency.toml	Update concurrency/config keys and document child-agent settings.
changes/unreleased.md	Add release notes for new modules and entitlements CLI.
AGENTS.md	Update agent guidance (polish workflow + consistency-check queue commands).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.