Skip to content

entities: enforce immutability doctrine across domain models#120

Closed
absoludity wants to merge 0 commit into
masterfrom
119-immutability-doctrine
Closed

entities: enforce immutability doctrine across domain models#120
absoludity wants to merge 0 commit into
masterfrom
119-immutability-doctrine

Conversation

@absoludity

@absoludity absoludity commented Mar 24, 2026

Copy link
Copy Markdown
Collaborator

Fixes #94 . Follows #119 (ignore the branch name). Much of the diff is just fixing to use model_copy or using tuples instead of lists etc.

Domain models are records — snapshots of business state — not stateful objects. Without an explicit contract, mutable collections creep in (list, dict), direct field assignment happens in use cases and repositories, and the distinction between "changing an entity" and "creating a new snapshot" becomes unclear. This matters especially in Temporal workflows where shared in-memory state across signal handlers and activity calls is a source of subtle replay bugs.

A new Entity base class establishes the contract: frozen=True prevents field reassignment, and two new doctrine tests enforce that all domain models inherit from Entity and use only immutable collection annotations (tuple, Mapping, frozenset).

All ceap and polling domain models now extend Entity. Mutable list/dict annotations have been replaced with tuple/Mapping. The repository base classes (memory and minio) previously mutated entity fields directly in update_timestamps — these now return new instances via model_copy. Use cases that assigned to entity fields mid-workflow do the same.

Test plan

  • pytest src/julee/core/doctrine/ --no-cov -v — 17 passed (2 new immutability tests)
  • pytest src/ -m unit --no-cov -q — 504 passed

@absoludity absoludity self-assigned this Mar 24, 2026
@absoludity absoludity requested a review from monkeypants March 24, 2026 00:24
@absoludity absoludity changed the base branch from 93-doctrine-scan-fix to master March 25, 2026 22:48
@absoludity absoludity closed this Mar 25, 2026
@absoludity absoludity force-pushed the 119-immutability-doctrine branch from d476e6a to d554307 Compare March 25, 2026 22:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add entity immutability doctrine test

1 participant