feat/aggregate reconstitute

.github/copilot-instructions.md

@@ -166,8 +166,8 @@ Do **not** implement `_payload` manually on decorated classes — the decorator
 ### ValueObject: Immutable Domain Values
 
 ```python
-from forging_blocks.foundation.value_object import ValueObject
-from collections.abc import Hashable
+from forging_blocks.domain.value_object import ValueObject
+
 
 class Email(ValueObject[str]):
     __slots__ = ("_value",)      # always include __slots__
@@ -181,13 +181,11 @@ class Email(ValueObject[str]):
     @property
     def value(self) -> str:
         return self._value
-
-    @property
-    def _equality_components(self) -> tuple[Hashable, ...]:
-        return (self._value,)    # controls equality and hashing
 ```
 
-`ValueObject` uses `@auto_freeze` internally. After `__init__` completes, any mutation raises `CantModifyImmutableAttributeError`. Concrete subclasses are frozen automatically — no decorator needed.
+Concrete ``ValueObject`` subclasses are automatically frozen and hashable via
+`auto_freeze` and `auto_hash` (applied through ``__init_subclass__``).
+After ``__init__`` completes, any mutation raises ``CantModifyImmutableAttributeError``.
 
 ### Specifications: Composable Predicates
 
@@ -459,7 +457,6 @@ class MyPort[T](OutboundPort):
 | Blocking I/O in async context | ❌ Flag | Add `async def` / `await` |
 | Manual `_payload` on `@event_dataclass` class | ❌ Flag | Decorator patches it automatically |
 | Missing `__slots__` on ValueObject subclass | ❌ Flag | Add `__slots__ = ("_field",)` |
-| Missing `_equality_components` on ValueObject | ❌ Flag | Implement required property |
 | `try/except` for control flow | ❌ Flag | Use `Result[T, E]` |
 | Overriding `@runtime_final` method | ❌ Flag | `TypeError` at class creation |
 | Overriding `apply`, `replay`, `collect_events` in AggregateRoot | ❌ Flag | These are runtime-final |

docs/guide/examples.md

@@ -82,7 +82,7 @@ class Task(Entity[int]):
         return self
 ```
 
-`Entity` uses **selective freezing** via `@auto_freeze(attrs=["_id"])` — the identity field (`_id`) is frozen after `__init__`, while other attributes remain mutable. This ensures the entity's identity never changes, while its state can evolve. See [Domain > Entities](../reference/domain/entities.md) for why identity matters, and [Foundation > Auto-freeze](../reference/foundation/auto-freeze.md) for the mechanism.
+`Entity` uses **selective freezing** via `@auto_freeze(attrs=["_id"])` — the identity field (`_id`) is frozen after `__init__`, while other attributes remain mutable. This ensures the entity's identity never changes, while its state can evolve. See [Domain > Entities](../reference/domain/entities.md) for why identity matters, and [Foundation > Auto Decorators](../reference/foundation/auto-decorators.md) for the mechanism.
 
 ---
 
@@ -127,8 +127,7 @@ The design is:
 ## 4. Modeling a value with ValueObject
 
 ```python
-from collections.abc import Hashable
-from forging_blocks.foundation.value_object import ValueObject
+from forging_blocks.domain.value_object import ValueObject
 
 
 class Email(ValueObject[str]):
@@ -144,16 +143,13 @@ class Email(ValueObject[str]):
     def value(self) -> str:
         return self._value
 
-    @property
-    def _equality_components(self) -> tuple[Hashable, ...]:
-        return (self._value,)
 ```
 
-`ValueObject` uses automatic freezing — subclasses need **no** `@auto_freeze`
-decorator or `_freeze()` call. Two `Email` instances with the same value are
-considered equal and can be used interchangeably as dictionary keys or set
-members. Attempting to mutate one after construction raises a
-`CantModifyImmutableAttributeError`.
+`ValueObject` uses `auto_freeze` and `auto_hash` under the hood --
+concrete subclasses are automatically frozen and hashable via
+``__init_subclass__``.  Two ``Email`` instances with the same value are
+equal and can be used as dictionary keys or set members.  Attempting to
+mutate one after construction raises a ``CantModifyImmutableAttributeError``.
 
 ---
 

docs/guide/getting-started.md

@@ -49,8 +49,7 @@ When a value is more than a primitive, you can wrap it in a `ValueObject` to
 make its rules visible and reusable.
 
 ```python
-from collections.abc import Hashable
-from forging_blocks.foundation.value_object import ValueObject
+from forging_blocks.domain.value_object import ValueObject
 
 
 class Email(ValueObject[str]):
@@ -65,14 +64,11 @@ class Email(ValueObject[str]):
     @property
     def value(self) -> str:
         return self._value
-
-    @property
-    def _equality_components(self) -> tuple[Hashable, ...]:
-        return (self._value,)
 ```
 
 `ValueObject` gives you value-based equality, hashability, and immutability
-out of the box, so that you can focus on the rules of *your* value.
+automatically via `auto_hash` and `auto_freeze`, so that you
+can focus on the rules of *your* value.
 
 ---
 

docs/reference/domain.md

@@ -35,9 +35,10 @@ The Domain block is the innermost ring. It imports nothing from outer layers. Wh
 - **[Value Object](domain/value-objects.md)** — Immutable, defined by its values; prevents primitive obsession
 - **[Aggregate Root](domain/aggregates.md)** — Consistency boundary; controls mutation and invariants
 - **[Specification](domain/specifications.md)** — Composable predicates for business rules, querying, and validation
+- **[Messages](domain/messages.md)** — Command, Event, Query (immutable, architecture-neutral)
 - **[Domain Errors](domain/errors.md)** — Invalid states and rule violations in domain terms
 - **[Validators](domain/validators.md)** — Concrete validation rules (RequiredValidator, EmailValidator, LengthValidator, RangeValidator)
-- **[Permissions](domain/permissions.md)** — Composable permission checkers (RoleBased, ResourceBased, Composite)
+- **[Permissions](domain/permissions.md)** — Composable permission checkers (protocol-based, application-defined)
 
 ---
 ## What it does not do
@@ -61,3 +62,5 @@ The Domain block is the innermost ring. It imports nothing from outer layers. Wh
 
 !!! note "Specification"
     A composable predicate over a candidate object for business rules, querying, and validation.
+!!! note "Message"
+    An immutable dataclass representing a command, event, or query.

docs/reference/foundation/messages.md → docs/reference/domain/messages.md

@@ -2,7 +2,7 @@
 
 Messages are immutable, architecture-neutral data carriers — **Command**, **Event**, and **Query**.
 
-All messages are frozen dataclasses with automatic serialization support (`to_dict`). Their type communicates intent: a Command asks for action, an Event records a fact, a Query requests data.
+All messages are frozen dataclasses. Their type communicates intent: a Command asks for action, an Event records a fact, a Query requests data. Serialization is handled by codecs in the infrastructure layer (see `DictMessageCodec`).
 
 ## Types
 
@@ -12,7 +12,7 @@ All messages are frozen dataclasses with automatic serialization support (`to_di
 
 ## Message dataclass decorator
 
-The `@message_dataclass` decorator creates boilerplate-free, frozen message types with automatic `to_dict()` and `from_dict()` support. Type aliases clarify intent:
+The ``@message_dataclass`` decorator creates boilerplate-free, frozen message types. Type aliases clarify intent:
 
 - `@command_dataclass` — For commands
 - `@event_dataclass` — For domain events
@@ -22,7 +22,7 @@ All aliases are the same decorator; the name signals intent. Instances are froze
 
 ## When to use
 
-Annotate a class with `@command_dataclass`, `@event_dataclass`, or `@query_dataclass`. The decorator handles freezing, `to_dict()`, and `from_dict()`. Choose the alias that matches the message's role — command for intent, event for facts, query for data requests.
+Annotate a class with ``@command_dataclass``, ``@event_dataclass``, or ``@query_dataclass``. The decorator handles freezing and wires up reconstruction via ``from_payload_fields``. Choose the alias that matches the message's role — command for intent, event for facts, query for data requests.
 
 !!! note "Related"
     See [Application Use Cases & Handlers](../application/use-cases.md) for how messages are processed.

docs/reference/domain/permissions.md

@@ -1,57 +1,57 @@
 # Permissions
 
-Composable permission-checking strategies for authorization decisions. Each checker evaluates an `AuthorizationContext` against a specific `Permission` and returns `True` when granted.
+Composable permission-checking strategies for authorization decisions. Each checker evaluates an application-defined context against a specific `Permission` and returns `True` when granted.
 
 ## PermissionChecker
 
-`PermissionChecker` is a `Protocol` that any permission-checking implementation must satisfy.
+`PermissionChecker[PermissionCheckContext]` is a `Protocol` that any permission-checking implementation must satisfy. The context type is provided by the application.
 
 ```python
-class PermissionChecker(Protocol):
-    async def check(self, context: AuthorizationContext, permission: Permission) -> bool:
+class PermissionChecker[PermissionCheckContext](Protocol):
+    async def check(self, context: PermissionCheckContext, permission: Permission) -> bool:
         ...
 ```
 
 Implementations may internally use synchronous logic, but must expose an `async def check(...)` method — callers always `await` the result.
 
-## RoleBasedPermissionChecker
+## CompositePermissionChecker
 
-Grants permissions based on a static mapping of roles to allowed permissions. Looks up the user's roles in the `AuthorizationContext` and checks whether any assigned role includes the requested permission.
+Combines multiple `PermissionChecker[PermissionCheckContext]` instances with OR logic. A check passes as soon as **any** inner checker approves. Returns `True` immediately on the first success; otherwise `False` after all checkers have been consulted.
 
 ```python
-checker = RoleBasedPermissionChecker({
-    "admin": [Permission.READ, Permission.WRITE, Permission.DELETE, Permission.ADMIN],
-    "editor": [Permission.READ, Permission.WRITE],
-})
+checker = CompositePermissionChecker([
+    my_role_checker,
+    my_resource_checker,
+])
+result = await checker.check(context, Permission.READ)
 ```
 
-## ResourcePermissionChecker
+## Designing your own checkers
 
-Grants permissions based on a static mapping of resource types to allowed permissions. Inspects `AuthorizationContext.resource_type` and checks whether the targeted resource type permits the requested permission.
+Applications define concrete `PermissionChecker` implementations that inspect their own context type. A role-based checker might look up permissions from a role-to-permission mapping:
 
 ```python
-checker = ResourcePermissionChecker({
-    "document": [Permission.READ, Permission.WRITE],
-    "image": [Permission.READ],
-})
+from forging_blocks.domain.permissions import PermissionChecker
+
+class RoleBasedChecker[PermissionCheckContext](PermissionChecker[PermissionCheckContext]):
+    def __init__(self, role_map: dict[str, list[Permission]]) -> None:
+        self._role_map = role_map
+
+    async def check(self, context: PermissionCheckContext, permission: Permission) -> bool:
+        roles = getattr(context, "roles", [])
+        for role in roles:
+            if permission in self._role_map.get(role, []):
+                return True
+        return False
 ```
 
-## CompositePermissionChecker
-
-Combines multiple `PermissionChecker` instances with OR logic. A check passes as soon as **any** inner checker approves. Returns `True` immediately on the first success; otherwise `False` after all checkers have been consulted.
-
-```python
-checker = CompositePermissionChecker([
-    RoleBasedPermissionChecker({"admin": [Permission.READ]}),
-    ResourcePermissionChecker({"document": [Permission.READ]}),
-])
-```
+A resource-based checker would similarly inspect resource metadata on the context object.
 
 ## When to use
 
-Use `RoleBasedPermissionChecker` for role-driven authorization (RBAC). Use `ResourcePermissionChecker` for resource-level access control. Combine them with `CompositePermissionChecker` when authorization depends on multiple factors — an admin role OR ownership of a document, for example.
+Use `CompositePermissionChecker` to combine multiple checkers when authorization depends on multiple factors — an admin role OR ownership of a document, for example. Define application-specific `PermissionChecker` subclasses for role-driven authorization (RBAC), resource-level access control, or any custom authorization logic.
 
-All checkers operate on the foundation `AuthorizationContext` and `Permission` types, keeping the domain free of infrastructure concerns.
+All checkers operate on the foundation `Permission` type and an application-defined context, keeping the domain free of infrastructure concerns.
 
 !!! note "Related"
-    See [Foundation Context](../foundation/context.md) for `AuthorizationContext` and `Permission`, and [Foundation Errors](../foundation/errors.md) for error types.
+    Permissions use the `Permission` enum (in `forging_blocks.foundation.permission`). See [Foundation Errors](../foundation/errors.md) for error types.

docs/reference/domain/specifications.md

@@ -9,4 +9,4 @@ A `Specification` encapsulates a rule evaluated with `is_satisfied_by(candidate)
 Subclass `Specification` and implement `is_satisfied_by(candidate) → bool`. Compose with `&`, `|`, `~` instead of nesting if-statements. Each specification is a single, testable unit of logic.
 
 !!! note "Where the implementation lives"
-    The specification pattern is defined in the [Foundation](../foundation.md) block because composable predicates are reusable outside the Domain block. The Domain block re-exports it.
+    The specification pattern is defined in the Domain block alongside Entity and AggregateRoot. It is imported from `forging_blocks.domain.specification`.

docs/reference/domain/value-objects.md

@@ -19,4 +19,4 @@ Inherit from `ValueObject` when you need immutability, value-based equality, and
     Value Objects prevent domain rules from being scattered across the codebase. Wrapping meaning in explicit types makes constraints visible, reusable, and testable.
 
 !!! note "Where the implementation lives"
-    The `ValueObject` base class lives in the [Foundation](../foundation.md) block because value-based equality and immutability are reusable outside the Domain block.
+    The `ValueObject` base class lives in the Domain block alongside Entity and AggregateRoot. It is imported from `forging_blocks.domain.value_object`.

docs/reference/foundation.md

@@ -15,8 +15,6 @@ Each abstraction serves one focused purpose:
 - `Result` replaces exceptions for predictable control flow.
 - `Port` defines boundaries as protocols — what is expected, not how.
 - `Error` gives structure to failure with messages and metadata.
-- `ValueObject` adds immutability, value equality, and hashing.
-- `Specification` composes business rules into testable predicates.
 
 These are not patterns you must use everywhere. They are tools you reach for when plain Python types stop communicating intent clearly enough.
 
@@ -27,7 +25,6 @@ Start with the abstractions that give the most immediate value:
 
 1. **`Result`** — Replace functions that return `None` on failure or raise exceptions for control flow. Return `Ok(value)` or `Err(error)` instead.
 2. **`Port`** — Define a protocol for any dependency you might swap later: repositories, event buses, loggers.
-3. **`ValueObject`** — Wrap primitive values when validation logic is scattered across functions.
 
 The Foundation block is pure Python — standard library only. It introduces no framework dependencies.
 
@@ -37,14 +34,11 @@ The Foundation block is pure Python — standard library only. It introduces no
 - **[Result](foundation/result.md)** — Explicit Ok/Err outcomes without exceptions for control flow
 - **[Ports](foundation/ports.md)** — Boundaries between components (InboundPort, OutboundPort)
 - **[Errors](foundation/errors.md)** — Structured error model (message + metadata, validation, rule violation, combined)
-- **[Messages](foundation/messages.md)** — Command, Event, Query (immutable, architecture-neutral)
-- **[Value Objects](foundation/value-objects.md)** — Immutable, value-based equality, hashing
-- **[Auto-Freeze](foundation/auto-freeze.md)** — Lightweight immutability without inheriting from ValueObject
-- **[Specifications](foundation/specifications.md)** — Composable predicates (and/or/not)
+- **[Auto Decorators](foundation/auto-decorators.md)** — Immutability, equality, and hashing decorators (auto_freeze, auto_eq, auto_hash)
 - **[Mappers](foundation/mappers.md)** — Explicit transformations between types
 - **[Identified](foundation/identified.md)** — Protocol for objects carrying an identifier
 - **[Meta Utilities](foundation/meta.md)** — Runtime enforcement (final, sealed, abstract)
-- **[Context](foundation/context.md)** — Immutable context objects (ServiceContext, AuthorizationContext, TransactionContext)
+
 - **[Rules](foundation/rules.md)** — Composable validation rules (ValidationRule)
 
 ---
@@ -66,12 +60,3 @@ The Foundation block is pure Python — standard library only. It introduces no
 
 !!! note "Error"
     A structured failure with a message and metadata, used across all layers.
-
-!!! note "Message"
-    An immutable dataclass representing a command, event, or query.
-
-!!! note "ValueObject"
-    An immutable object with value-based equality and hashing.
-
-!!! note "Specification"
-    A composable predicate over a candidate object for rules, validation, and filtering.