aw-spec-cli 0.1.10 → 0.1.11

package/assets/guardrails/technology/java-spring/domain_abstraction.md

@@ -0,0 +1,424 @@
+# Domain Abstraction Component Specification
+
+> Pure technology/domain capability. This document defines the reusable domain abstractions
+> and their required behavior.
+>
+> These abstractions are optional capabilities. Applications and domain models MUST adopt
+> them only when the corresponding requirement exists.
+
+---
+
+## 1. Purpose
+
+Define a reusable Domain Abstraction capability that provides common domain-level abstractions required by applications.
+
+The component standardizes foundational domain concepts while keeping domain models independent of infrastructure and framework concerns.
+
+---
+
+## 2. Applicability
+
+This component MAY be adopted when the application requires the corresponding domain abstractions.
+
+The abstractions are reusable domain capabilities and MAY be adopted selectively by domain models.
+
+Applications MUST NOT require every domain entity to implement every abstraction.
+
+For example, an entity does not automatically become:
+
+- auditable;
+- soft-deletable;
+- tenant-aware;
+- a named entity;
+- an aggregate root.
+
+Abstractions MUST NOT be added merely for consistency or because they are available.
+
+---
+
+## 3. Entity Abstraction
+
+The component MUST provide an Entity abstraction parameterized by the identifier type.
+
+The Entity abstraction MUST represent an entity through its identity.
+
+The public Entity contract MUST expose retrieval of the identifier.
+
+The public Entity contract MUST NOT expose unrestricted identifier mutation.
+
+Entity identity MUST be treated as stable domain identity.
+
+Internal identifier initialization or mutation MUST be isolated from the general public contract.
+
+---
+
+## 4. Entity Base Implementation and Equality
+
+The component MUST provide a reusable base entity implementation that:
+
+- stores the identifier;
+- exposes the identifier through the Entity contract;
+- allows controlled internal identifier initialization;
+- provides identity-based equality and hash-code behavior.
+
+Entity equality MUST be based on entity identity rather than all entity attributes.
+
+The implementation MUST:
+
+- treat the same object instance as equal;
+- compare entities based on identifier when identifiers are available;
+- avoid considering mutable domain attributes as identity;
+- treat entities without a valid identifier as not equal to another entity solely because both identifiers are absent;
+- maintain consistent equality and hash-code behavior for subclasses or proxy-like implementations without requiring framework-specific dependencies.
+
+Attribute-based equality MUST NOT be used for entities.
+
+---
+
+## 5. Aggregate Root
+
+The component MUST provide an Aggregate Root abstraction representing the entry point for modifying an aggregate and maintaining its business invariants.
+
+The reusable base implementation MUST:
+
+- be an Entity;
+- implement the Aggregate Root abstraction;
+- support domain-event registration;
+- reject null domain events;
+- expose registered domain events through a read-only or unmodifiable view;
+- report whether domain events exist;
+- allow registered domain events to be cleared after handling or dispatch.
+
+The aggregate root MUST remain the domain boundary for the aggregate.
+
+External callers MUST NOT be able to directly mutate the internal domain-event collection.
+
+---
+
+## 6. Domain Events
+
+The component MUST provide a base abstraction for domain events representing significant business occurrences that have already happened.
+
+Each domain event MUST contain its occurrence timestamp.
+
+The occurrence timestamp MUST be immutable after event creation.
+
+Domain events MUST support both:
+
+- automatic timestamp creation;
+- explicit timestamp creation where required by tests or controlled event construction.
+
+The component MUST provide a capability for identifying objects that contain domain events.
+
+This capability MUST support:
+
+- retrieving events;
+- checking whether events exist;
+- clearing events.
+
+The internal event collection MUST NOT be directly mutable by external callers.
+
+### Responsibility Boundary
+
+The Domain Abstraction component is responsible only for representing and collecting domain events.
+
+It MUST NOT:
+
+- publish events to a message broker;
+- send events over HTTP;
+- persist events;
+- implement an outbox;
+- dispatch events to external systems.
+
+Event publication and delivery are outside the responsibility of this component.
+
+---
+
+## 7. Named Entity
+
+The component MUST provide an abstraction for entities that have a name attribute.
+
+The abstraction MUST support:
+
+- name retrieval;
+- controlled name modification.
+
+Named entity identity MUST continue to be determined by the entity identifier.
+
+The name MUST NOT become part of entity identity or equality.
+
+### Typed Named Entity
+
+The component MUST provide an abstraction combining:
+
+- Named Entity behavior;
+- Entity identity behavior.
+
+The generic identifier type MUST be preserved.
+
+### Named Entity Base
+
+The component MUST provide a reusable base implementation that:
+
+- inherits entity identity behavior;
+- provides the name property;
+- exposes name retrieval;
+- supports controlled name modification;
+- retains identity-based equality.
+
+---
+
+## 8. Auditable Entity
+
+The component MUST provide an Auditable Entity abstraction supporting:
+
+- creation timestamp;
+- creator identity;
+- modification timestamp;
+- modifier identity.
+
+Creation information represents historical facts and SHOULD remain immutable after creation.
+
+The mechanism used to populate audit information is outside the responsibility of this component.
+
+Modification fields MAY change when the entity is modified during its lifecycle.
+
+The component MUST NOT introduce a separate auditing framework or infrastructure.
+
+---
+
+## 9. Soft Deletable
+
+The component MUST provide a Soft Deletable abstraction representing logical deletion.
+
+The abstraction MUST support:
+
+- deleted state;
+- deletion timestamp;
+- deletion actor.
+
+The standard soft-delete operation MUST represent a complete deletion state by simultaneously:
+
+- marking the entity as deleted;
+- recording the deletion UTC timestamp;
+- recording the responsible deletion actor.
+
+The standard operation MUST NOT allow an incomplete deletion state.
+
+The component MUST NOT implement:
+
+- persistence filtering;
+- repository filtering;
+- database-specific soft-delete behavior.
+
+---
+
+## 10. Tenant Entity
+
+The component MUST provide a Tenant Entity abstraction for entities associated with a tenant.
+
+The abstraction MUST support:
+
+- tenant identifier retrieval;
+- controlled tenant identifier modification.
+
+The component MUST NOT implement:
+
+- tenant resolution;
+- authentication;
+- authorization;
+- tenant isolation;
+- persistence filtering.
+
+Tenant enforcement is outside the responsibility of this component.
+
+---
+
+## 11. Named ID Value Object and Factory
+
+### Named ID Value Object
+
+The component MUST provide a value abstraction combining:
+
+- an identifier;
+- a name.
+
+The value representation MUST preserve the behavior of representing the name together with the identifier.
+
+The Named ID MUST NOT become an Entity.
+
+Equality MUST remain strictly value-based.
+
+### Named ID Factory
+
+The component MUST provide a factory utility for creating Named ID values from entities.
+
+The factory MUST:
+
+- support creation from an Entity and a Named Entity;
+- support creation from an Entity implementing Named Entity;
+- reject null required inputs;
+- reject the operation when the required Named Entity behavior is not provided;
+- avoid silently creating an incomplete Named ID;
+- remain a creation utility only.
+
+The factory MUST NOT introduce persistence or infrastructure behavior.
+
+---
+
+## 12. Framework Independence
+
+The Domain Abstraction component MUST remain independent of application infrastructure and external technology concerns.
+
+The component MUST NOT require dependencies on:
+
+- Spring;
+- Spring Data;
+- JPA;
+- Hibernate;
+- HTTP;
+- REST;
+- servlet APIs;
+- database infrastructure;
+- messaging infrastructure;
+- web frameworks;
+- infrastructure security mechanisms.
+
+The component SHOULD rely only on standard Java capabilities required to implement its defined contracts.
+
+Dependency versions MUST be managed by the consuming application's approved dependency management.
+
+The component SHOULD NOT require environment-specific configuration.
+
+Core behavior MUST be deterministic and defined by its contracts.
+
+---
+
+## 13. Thread Safety
+
+Aggregate root instances and their internal domain-event collections are not required to be thread-safe.
+
+They are intended to be used within an appropriate application operation and transaction lifecycle.
+
+The component MUST NOT introduce generic synchronization or concurrent collections solely for defensive purposes.
+
+Applications requiring concurrent access MUST establish an appropriate concurrency strategy outside the component.
+
+---
+
+## 14. Security and Sensitive Data
+
+The component MUST NOT implement infrastructure security mechanisms.
+
+The following values are domain data within this component:
+
+- tenant identifiers;
+- audit identities;
+- entity identifiers;
+- domain event data.
+
+The component MUST NOT:
+
+- authenticate users;
+- authorize operations;
+- resolve user identities;
+- resolve tenants;
+- enforce tenant isolation;
+- implement access-control policies.
+
+---
+
+## 15. Prohibited Behavior
+
+The component MUST NOT:
+
+- introduce Spring dependencies;
+- introduce JPA or Hibernate dependencies;
+- implement persistence behavior;
+- implement repository behavior;
+- publish or transport domain events;
+- implement event brokers;
+- implement an outbox;
+- implement tenant resolution;
+- implement authorization;
+- implement authentication;
+- implement global exception handling;
+- implement HTTP Problem Details;
+- implement API Result Mapping;
+- implement application-level logging;
+- expose unrestricted entity identifier mutation;
+- expose mutable access to an aggregate's internal domain-event collection;
+- use entity attributes as the basis for entity identity equality;
+- introduce custom abstractions that are not required by the defined component contract.
+
+---
+
+## 16. Implementation Boundary
+
+This document defines the required behavior and contracts of the Domain Abstraction component.
+
+Exact implementation details MAY be selected by the implementation as long as the defined behavior is preserved.
+
+Unless explicitly required by this specification, this document does not mandate:
+
+- exact package names;
+- exact Java class names;
+- visibility modifiers;
+- constructor signatures;
+- collection implementations;
+- record versus class choices;
+- internal helper methods.
+
+The implementation MUST preserve the following behavioral contracts:
+
+- entity identity semantics;
+- controlled identifier mutation;
+- entity equality and hash-code semantics;
+- aggregate-root domain-event lifecycle;
+- read-only domain-event exposure;
+- immutable domain-event occurrence timestamps;
+- named-entity behavior;
+- auditing semantics;
+- complete soft-delete behavior;
+- UTC deletion timestamp behavior;
+- tenant identifier behavior;
+- Named ID value-based equality;
+- Named ID factory rejection behavior.
+
+---
+
+## 17. Acceptance Criteria
+
+- [ ] Entity identity is exposed without unrestricted identifier mutation.
+
+- [ ] Entity equality and hash-code behavior follow the defined identity semantics.
+
+- [ ] Aggregate roots support controlled domain-event registration and lifecycle.
+
+- [ ] Domain events reject null values.
+
+- [ ] Domain events are exposed without allowing external mutation.
+
+- [ ] Domain events contain immutable occurrence timestamps.
+
+- [ ] Named entities preserve identity-based equality.
+
+- [ ] Auditable entities provide the required audit information.
+
+- [ ] Creation audit information can remain immutable after creation.
+
+- [ ] Modification audit information can change during the entity lifecycle.
+
+- [ ] Soft deletion represents deleted state, deletion timestamp, and deletion actor as one complete operation.
+
+- [ ] Soft-delete timestamps use UTC.
+
+- [ ] Tenant entities provide tenant association without implementing tenant resolution or enforcement.
+
+- [ ] Named ID follows value-based equality.
+
+- [ ] Named ID factory rejects invalid or incomplete inputs.
+
+- [ ] The component has no dependency on Spring, JPA, Hibernate, HTTP, or other infrastructure frameworks.
+
+- [ ] The implementation preserves all behavioral contracts defined by this specification.