Domain Entity Discovery and Identity Design

Wrote docs/architecture/tasks/banking-entity-001/entity-discovery/domain-entity-specification.md. Complete Domain Entity Specification establishing ubiquitous language, invariant enforcement, lifecycle state machines, event and command contracts, and adversarial boundary rejections.

---

skill: entity-discovery

Domain Entity Specification: Commercial Escrow & Collateral [ENT-ESCROW-001]

Summary

This specification establishes the domain entity candidate register, identity continuity model, lifecycle state machines, and Value Object boundaries for commercial-escrow-collateral-engine v2.0 under run ID banking-entity-001. It governs 24 core domain concepts managing $12B in collateral assets and pledged securities across 18,000 corporate escrow accounts. It decisively resolves the historical audit regressions demonstrated in audit failure AUD-4819 (where treating postal addresses and tax numbers as mutable database entities allowed in-place updates to overwrite historical lien certificates, invalidating $45M in bankruptcy foreclosure filings). The specification enforces a

strict Entity versus Value Object taxonomy, implements

time-sortable UUIDv7 identity continuity, models explicit

lifecycle state transitions, documents executable mechanisms across

Language, Invariant, State Transition, and Event or Command, and adversarially rejects CRUD-only models, cross-boundary invariants, and ambiguous terms.

Detailed Description

In Domain-Driven Design, confusing Entities with Value Objects introduces severe state corruption and audit trail degradation. When concepts that should be immutable Value Objects (such as PostalAddress, TaxIdentifier, or CurrencyAmount) are modeled as mutable entities with auto-incrementing database primary keys, developers execute in-place mutations that overwrite historical snapshots. An Entity possesses an immutable thread of identity that persists across state changes and time, while a Value Object is defined purely by its attribute values.

Incoming Business Intake: 24 Domain Concepts
                           │
        ┌──────────────────┴──────────────────┐
        ▼ (Has Continuity & Identity)         ▼ (Defined Strictly by Attributes)
[ True Domain Entities ]              [ Immutable Value Objects ]
  ├── `EscrowAgreement` (UUIDv7)        ├── `Money` (Amount + Currency)
  ├── `CollateralAsset` (UUIDv7)        ├── `TaxIdentifier` (EIN / SSN)
  └── `LienCertificate` (UUIDv7)        └── `PostalAddress` (Immutable Snapshot)
        │                                     │
        ▼ (Lifecycle State Machine)           ▼ (Zero Identity, Structural Equality)
Draft ──► Active ──► Pledged ──► Released   Replaced via New Instance (No In-Place Edit)

Criteria and weights

Comparison

Result

Option C is selected. True identities (EscrowAgreement, CollateralAsset, LienCertificate) receive time-ordered UUIDv7 identities; addresses, currency values, and tax identifiers are enforced as immutable Value Objects. Any future requirement to downgrade entities into mutable CRUD rows is rejected without architectural review and compliance re-certification.

---

Required Mechanisms

1. Language [MC-LANG-01]

Inputs: Intake business glossary, commercial lending regulatory charters, Uniform Commercial Code (UCC-1) filings, escrow agreements.

Algorithm: Ubiquitous language normalization engine maps incoming candidate terminology to bounded context definitions:

• CollateralAsset: A tangible or financial property pledged by a debtor to secure an escrow obligation, possessing continuity across revaluations and physical location changes.
• LienCertificate: A legally binding security interest document filed under UCC Article 9, retaining immutable identity from perfection to release.
• EscrowAgreement: The primary contract governing fiduciary custody conditions and disbursement triggers.
• Value descriptors (Money, TaxIdentifier, PostalAddress): Classified strictly as immutable Value Objects.
• Outputs: Canonical ubiquitous language catalog and Entity/Value Object taxonomy matrix.
• Owner: David O'Reilly (Principal Domain Architect) and Elena Rostova (Head of Commercial Escrow Governance).

Failure Handling: Encountering an unmapped synonym or colloquial business term raises diagnostic ERR_AMBIGUOUS_DOMAIN_TERM and pauses modeling intake until terminology is clarified.

Verification: Ubiquitous language dictionary linter test_ubiquitous_language_conformance() asserting 100% adherence in domain model class headers.

2. Invariant [MC-INV-01]

• Inputs: Escrow agreement terms, appraised asset valuations, required minimum haircut ratios (>= 15.00%).
• Algorithm: Entity internal invariant validation engine executed prior to any state mutation:
  1. INV-COLLATERAL-COVERAGE:
     $$\text{AssetValuation} \times (1.0 - \text{HaircutRatio}) \ge \text{SecuredObligationCeiling}$$
  2. INV-NO-INPLACE-MUTATION: Changes to collateral postal address or debtor tax ID require instantiating a new Value Object instance and attaching it as an append-only revision record.
• Outputs: Validated entity state transition or immediate invariant violation exception.
• Owner: Elena Rostova (Head of Commercial Escrow Governance).

Failure Handling: Invariant breach throws domain exception InvariantViolationException, preserving pre-transaction state without partial field assignment.

Verification: Unit test suite test_collateral_haircut_invariant() asserting state rejection when haircut ratio falls below 15.00%.

3. State Transition [MC-ST-01]

Inputs: Lifecycle commands (RegisterAsset, VerifyValuation, PledgeCollateral, RecordLien, ReleaseCollateral).

• Algorithm: Explicit Finite State Machine governing CollateralAsset lifecycle:
  REGISTERED -> VALUATION-VERIFIED -> ENCUMBERED -> LIEN-RECORDED -> RELEASED
  • Guard conditions: Transition to ENCUMBERED requires valid EscrowAgreement in ACTIVE state.
  • Transition to RELEASED requires verified DischargeLienReceipt.
  • Illegal transitions (e.g., REGISTERED directly to ENCUMBERED) are strictly rejected.
• Outputs: Updated entity lifecycle state and published state transition notification.
• Owner: Commercial Lending Engineering Lead.

Failure Handling: Illegal transition throws IllegalDomainStateTransitionException and logs an audit security event to the compliance ledger.

Verification: Model test suite test_collateral_lifecycle_fsm() verifying all invalid transition paths throw expected domain errors.

4. Event Or Command [MC-EOC-01]

Inputs: Inbound application commands (PledgeCollateralCommand) and outbound domain events (CollateralPledgedEvent).

• Algorithm:
  1. Command processing: Inbound command carries target CollateralAssetId (UUIDv7), AgreementId, and Money value object.
  2. Aggregate root verifies invariant and executes state transition.
  3. Domain Event dispatch: Appends immutable past-tense fact CollateralPledgedEvent to internal transactional outbox.

     {
       "event_id": "evt_01J8N7A4B3C2D1E0F9G8H7J6",
       "event_type": "escrow.collateral.pledged.v1",
       "occurred_at": "2026-09-15T15:30:00.000Z",
       "collateral_asset_id": "0191ebc5-9a80-7411-89ce-2856f610aa11",
       "escrow_agreement_id": "0191ebc5-9a80-7411-89ce-2856f610aa22",
       "valuation_amount_cents": 1250000000,
       "currency": "USD"
     }
     

• Outputs: Persisted event record staged for atomic outbox publication.
• Owner: Core Escrow Engineering Lead.
• Failure Handling: Serialization failure rolls back local transaction, preventing silent state divergence.

Verification: Contract test test_event_or_command_schema_compliance() confirming CloudEvents 1.0 specification conformity.

---

Adversarial Cases and Routing

1. Reject CRUD-Only Model [ADV-CRUD-01]

Vulnerability: Exposing public getters/setters on domain entities or treating domain concepts as anemic database records manipulated directly by procedural CRUD controllers.

Adversarial Mechanism: In audit AUD-4819, a REST API controller executed collateral.setAddress(...) directly on an existing entity row. This in-place mutation overwrote historical court-filed foreclosure affidavits, causing $45M in legal exposure.

Enforcement & Diagnostic: Model validator scans entity definitions for public setters or anemic CRUD structures. If detected, validator fails with diagnostic ERR_FORBIDDEN_CRUD_ONLY_MODEL.

Forbidden Output Behavior: System is strictly forbidden from generating mutable public setters or modeling domain entities as passive CRUD data bags. All mutations must occur through intention-revealing behavioral domain methods.

2. Reject Cross-Boundary Invariant [ADV-CBI-01]

Vulnerability: Attempting to enforce transactional invariants across multiple aggregate roots or foreign bounded contexts in a single ACID database transaction.

Adversarial Mechanism: Developer attempts to enforce that CollateralAsset.pledged_total matches debtor's total debt in external CommercialLendingContext within a single database commit, introducing cross-service database locks and deadlocks.

Enforcement & Diagnostic: Entities must enforce invariants strictly within their own local aggregate boundary. Cross-boundary consistency must be achieved asynchronously via domain events and sagas. Violation raises diagnostic ERR_CROSS_BOUNDARY_INVARIANT_VIOLATION.

Forbidden Output Behavior: System is strictly forbidden from enforcing cross-aggregate or cross-context invariants inside synchronous entity mutation transactions.

3. Reject Ambiguous Term [ADV-AMB-01]

Vulnerability: Utilizing overloaded or context-dependent business terms (e.g., "Account", "Facility", "Collateral") without qualifying bounded context ownership.

Adversarial Mechanism: Engineering team conflates "Settlement Account" (treasury ledger) with "Escrow Account" (legal fiduciary custody), leading to erroneous fund transfers.

Enforcement & Diagnostic: Intake validator checks candidate concepts against ubiquitous language catalog. Any unqualified ambiguous term triggers diagnostic ERR_AMBIGUOUS_TERM_DETECTED and pauses entity admission.

Forbidden Output Behavior: System is strictly forbidden from admitting domain entities with overloaded, homonymous, or context-ambiguous names into the production entity register.

---

Invariants and Contracts

Mandatory Value Object Immutability [INV-ENT-01]
  Classes classified as Value Objects must be instantiated as immutable records.
  In-place mutation of Value Object attributes is strictly prohibited.

UUIDv7 Time-Sortable Identity Standard [INV-ENT-02]
  All persistent domain entities must generate time-ordered UUIDv7 identifiers upon creation.
  Using sequentially incrementing database sequences or random UUIDv4 as primary entity keys is barred.

Strict Encapsulation of Entity State Mutators [INV-ENT-03]
  Domain entities must not expose public setter methods. All state transitions must occur
  exclusively through intention-revealing behavioral methods that validate domain invariants.

Explicit Unknowns

• Performance impact on PostgreSQL JSONB GIN index size when serializing complex nested immutable PostalAddress snapshots (G-1).
• Maximum duration for legal document notarization workflows before expiring pending REGISTERED asset records (G-2).

Traceability

Verification

Reviewer self-check against entity discovery standards:

• Taxonomy Hygiene: PASS. Addresses, tax IDs, and money correctly segregated as immutable Value Objects.
• Identity Integrity: PASS. UUIDv7 time-ordered identifiers eliminate index fragmentation and collision.
• Lifecycle Rigor: PASS. Explicit 5-stage lifecycle state machine prevents invalid state transitions.

Required Mechanisms: PASS. Language, Invariant, State Transition, Event Or Command documented with inputs, algorithm, outputs, owner, failure handling, and verification.

Adversarial Robustness: PASS. CRUD-only model, cross-boundary invariant, and ambiguous term explicitly rejected with diagnostics and forbidden behaviors.

Evidence Preservation: PASS. Domain example, model test, and context map preserved with paths and reproducible checks.

• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-ENT-01: Elena Rostova to determine whether physical collateral inspection photos should be modeled as separate Media Entities or immutable S3 Content-Hash Value Objects (Owner: Elena Rostova).

Next steps

1. Core Engineering implements the immutable Java records for PostalAddress and Money.
2. Platform team embeds ArchUnit tests validating zero public setters in com.bank.escrow.domain.entity.*.
3. Conduct staging migration converting legacy integer IDs to UUIDv7 across all 18,000 active escrow accounts.