Evolution Pattern

SEA™ DSL pattern for concept versioning and migration.

Evolution Annotations

Annotation Purpose Required
v X.Y.Z Version number On evolved entities
@replaces Previous version reference Yes
@changes Change description Recommended
@migration_policy mandatory/optional On ConceptChange
@breaking_change true/false On ConceptChange

Complete Pattern

@namespace "com.example.procurement"
@version "2.0.0"

// ============================================================================
// ORIGINAL ENTITY (v1.0.0)
// ============================================================================

Entity "Vendor" v1.0.0 in procurement
  // Original fields: name, address, contact

// ============================================================================
// EVOLVED ENTITY (v2.0.0)
// ============================================================================

Entity "VendorV2" v2.0.0
  @replaces "Vendor" v1.0.0
  @changes [
    "added credit_limit field",
    "added payment_terms field",
    "renamed contact to primary_contact"
  ]
in procurement

// ============================================================================
// MIGRATION DEFINITION
// ============================================================================

ConceptChange "Vendor_v2_migration"
  @from_version v1.0.0
  @to_version v2.0.0
  @migration_policy mandatory
  @breaking_change true

// ============================================================================
// NON-BREAKING EVOLUTION (v2.1.0)
// ============================================================================

Entity "VendorV2_1" v2.1.0
  @replaces "VendorV2" v2.0.0
  @changes [
    "added secondary_contact field (optional)"
  ]
in procurement

ConceptChange "Vendor_v2_1_migration"
  @from_version v2.0.0
  @to_version v2.1.0
  @migration_policy optional
  @breaking_change false

// ============================================================================
// FLOW EVOLUTION
// ============================================================================

Flow "CreateVendorV2"
  @cqrs { "kind": "command" }
  @tx { "transactional": true }
  @replaces "CreateVendor" v1.0.0
from "Admin" to "VendorV2"

// ============================================================================
// POLICIES
// ============================================================================

Policy version_lineage_required
  per Constraint Obligation priority 10
  @rationale "Evolved concepts must declare lineage"
as: forall e in entities where e.version > "1.0.0":
    (e.replaces != null)

Policy no_orphan_migrations
  per Constraint Obligation priority 10
as: forall m in conceptchanges:
    exists e in entities: (e.version = m.to_version)

Migration Process

  1. Create new version with @replaces and @changes
  2. Define ConceptChange with migration policy
  3. Update flows to reference new entity
  4. Deprecate old version (keep for compatibility window)

Best Practices

Last Updated: January 2026