@eventmodelers/cli 1.0.36 → 1.0.38

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-optimizing-stream-design/references/domain-patterns.md

@@ -1,150 +1,109 @@
-# Domain-Specific Stream Size Patterns
+# Domain-Specific Timeline Boundary Patterns
 
 ## Contents
 - E-commerce patterns
 - Banking patterns
 - SaaS patterns
-- Implementation checklist
+
+Each entry shows a well-scoped boundary for that domain: what identity it's anchored on, and why that identity — not a category or a time window — is the right one.
 
 ---
 
 ## E-commerce Domain
 
-**Order Aggregate**:
+**Order Entity**:
 ```
-Events: 5-20
+Identity: orderId
 Lifetime: 1-3 years
-Frequency: 1 event per few days
-Stream Length: 8-60 events
-Snapshotting: NOT NEEDED 
-Reason: Short entity lifetime, low frequency, few state changes
+Boundary: Everything that happens to this one order
+Reason for this boundary: the order has a clear owner (one customer,
+one checkout) and a natural end (delivered, cancelled, refunded)
 ```
 
-**Shopping Cart Aggregate**:
+**Shopping Cart Entity**:
 ```
-Events: 5-50+ (add/remove items many times)
-Lifetime: 30 minutes to 2 years (varies widely)
-Frequency: 1-10 events per hour (if active)
-Stream Length: 10-500+ events (depends on user behavior)
-Snapshotting: RARELY (only for frequent shoppers) 
-Strategy: Split abandoned vs. active carts if too long
+Identity: cartId (or customerId, if a customer has exactly one active cart)
+Lifetime: 30 minutes to 2 years (varies widely by product)
+Boundary: Items added/removed for this one cart
+Watch for: an "abandoned" cart and an "active" cart are different
+lifecycles — split into separate timelines if their behavior diverges
+(e.g. abandoned-cart recovery vs. active checkout flow)
 ```
 
-**User Account Aggregate**:
+**User Account Entity**:
 ```
-Events: 2-10 per year (profile updates, settings changes)
+Identity: userId
 Lifetime: 5-10+ years
-Frequency: Very low (events measured in months apart)
-Stream Length: 10-100 events
-Snapshotting: NOT NEEDED 
-Reason: Infrequent events, long lifetime, many separate streams
+Boundary: Profile and account-level state for this one user
+Watch for: account state, preferences, and session history are three
+different concerns with different change frequency — split them
+(UserProfile / UserPreferences / UserSessions) rather than bundling
 ```
 
 ---
 
 ## Banking Domain
 
-**Account Aggregate**:
+**Account Entity**:
 ```
-Events: 50-500+ per year (deposits, withdrawals, fees)
+Identity: accountId
 Lifetime: 10-50+ years
-Frequency: 0.1-2 events per day
-Stream Length: 500-25,000+ events
-Snapshotting: MAYBE (at 5000+) 
-Strategy: Consider splitting by time period or account type
-Alternative: Snapshotting might be justified for regulatory access needs
+Boundary: Deposits, withdrawals, and fees for this one account
+Watch for: an account spanning decades is still one identity — the
+boundary is correct even though the timeline is long-lived; don't
+split it just because it accumulates many events over a long life
 ```
 
-**Transaction Aggregate**:
+**Transaction Entity**:
 ```
-Events: 1-5 (Requested → Processing → Settled)
+Identity: transactionId
 Lifetime: 1-2 months (then archived)
-Frequency: Single transaction, short lifecycle
-Stream Length: 2-5 events
-Snapshotting: NEVER NEEDED 
-Reason: Tiny, immutable after completion
+Boundary: Requested → Processing → Settled, for this one transaction
+Reason for this boundary: a transaction is a short, self-contained
+lifecycle — treat it as its own timeline, not folded into the account
 ```
 
-**Loan Aggregate**:
+**Loan Entity**:
 ```
-Events: 100-500+ (payments, rate changes, modifications)
+Identity: loanId
 Lifetime: 5-30 years
-Frequency: 1-5 events per month
-Stream Length: 1000-10,000+ events
-Snapshotting: CONSIDER AT 5000 
-Strategy: Split by loan product, payment period, or status
-Example: ActiveLoan vs. CompletedLoan aggregates
+Boundary: Payments, rate changes, and modifications for this one loan
+Watch for: "active loan" and "completed loan" are different
+lifecycles with different access patterns — consider splitting into
+ActiveLoan vs. CompletedLoan if their consumers genuinely differ
 ```
 
 ---
 
 ## SaaS Domain
 
-**Subscription Aggregate**:
+**Subscription Entity**:
 ```
-Events: 2-20 (Created, Upgraded, Downgraded, Cancelled)
+Identity: subscriptionId
 Lifetime: 1-5+ years
-Frequency: 1-5 events per year
-Stream Length: 5-100 events
-Snapshotting: NOT NEEDED 
-Reason: Low frequency, well-defined lifecycle
+Boundary: Created, Upgraded, Downgraded, Cancelled — for this one subscription
+Reason for this boundary: a subscription has one clear owner and a
+well-defined lifecycle
 ```
 
-**User Workspace Aggregate**:
+**User Workspace Entity**:
 ```
-Events: 10-100+ (members added, roles changed, settings updated)
+Identity: workspaceId
 Lifetime: 2-5+ years
-Frequency: 0.5-5 events per month
-Stream Length: 10-500 events
-Snapshotting: NOT NEEDED 
-Reason: Moderate frequency, small discrete events
-```
-
-**Data Collection Aggregate**:
+Boundary: Members added, roles changed, settings updated — for this one workspace
+Watch for: workspace-level settings and individual member activity
+are different concerns — keep member activity in its own timeline if
+it needs independent access patterns
 ```
-Events: 100-10,000+ (data points added, processed, analyzed)
-Lifetime: 1-5+ years
-Frequency: 1-1000+ events per day (varies wildly)
-Stream Length: 100-50,000+ events
-Snapshotting: PROBABLY 
-Strategy: Split by data type, time period, or processing stage
-Question: Are all these events about the same business entity?
-         → If NO, split the aggregate
-         → If YES, snapshotting might be needed
-```
-
----
-
-## Implementation Checklist
-
-Before implementing snapshotting, answer ALL of these:
 
+**Data Collection Entity**:
 ```
-Design Questions:
-[ ] Does this aggregate have a single business identity?
-[ ] Can I split this into smaller aggregates?
-[ ] Are there natural lifecycle phases (archived vs. active)?
-[ ] Is event granularity appropriate (not too fine)?
-
-Performance Questions:
-[ ] Have I measured replay latency?
-[ ] Does latency exceed acceptable threshold?
-[ ] Is the problem snaphotting will solve?
-[ ] Or is it a design problem?
-
-Cost-Benefit Questions:
-[ ] How many writes per second?
-[ ] How many reads per second?
-[ ] What's the read latency requirement (SLA)?
-[ ] Is snapshotting complexity worth the benefit?
-
-Operational Questions:
-[ ] How will I version snapshots?
-[ ] How will I test snapshot recovery?
-[ ] How will I monitor snapshot health?
-[ ] Can I implement this given current skills?
+Identity: depends on what's actually being tracked as one thing
+Watch for: this is the domain most likely to hide a Pattern 3
+("Collection") anti-pattern — ask explicitly: "are all these data
+points about the same business entity?"
+  → If NO, the boundary is wrong: split by whatever entity each
+    data point actually belongs to.
+  → If YES, the boundary is fine even if the timeline accumulates a
+    lot of events — that's a volume question, not a boundary one.
 ```
-
-**If ANY question suggests redesign is better**: Redesign first, snapshot never.
-
-**If ALL questions support snapshotting**: Proceed with implementation.

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-optimizing-stream-design/references/patterns.md

@@ -1,25 +1,24 @@
-# Aggregate Boundary Design Patterns
+# Timeline Boundary Design Patterns
 
 ## Contents
-- Aggregate Boundary Design Patterns (5 patterns with examples)
-- Stream Size Decision Tree
-- Red Flags: Redesign Needed
-- Tips for Optimal Stream Design
+- Entity Boundary Design Patterns (5 patterns with examples)
+- Timeline Boundary Decision Tree
+- Red Flags: Boundary Is Wrong
+- Tips for Finding the Right Boundary
 
 ---
 
-## Aggregate Boundary Design Patterns
+## Entity Boundary Design Patterns
 
 ### Pattern 1: Single Entity (Most Common)
 
- CORRECT: One aggregate per entity
+CORRECT: One timeline boundary per business entity
 ```
-Aggregate: Order
+Entity: Order
 Root Identity: orderId (e.g., 'order-123')
-Entity: The specific order
 Lifetime: 1-2 years
 
-Events in stream:
+Events in timeline:
   1. OrderCreated (2024-01-15)
   2. OrderLineAdded (2024-01-15)
   3. OrderLineAdded (2024-01-15)
@@ -28,21 +27,17 @@ Events in stream:
   6. OrderShipped (2024-01-20)
   7. OrderDelivered (2024-01-25)
 
-Stream Length: 7 events
-Snapshotting: NOT NEEDED 
-
 Identity Principle: orderId is the natural business key
 Boundary: Everything about THIS specific order, nothing else
-Consistency: Only one order being modified at a time
 ```
 
 ---
 
 ### Pattern 2: Composite Entity (Proper Composition)
 
- CORRECT: Aggregate contains related child entities
+CORRECT: Entity contains related child entities
 ```
-Aggregate: Order
+Entity: Order
 Root Identity: orderId (e.g., 'order-456')
 
 Contains related children (same lifetime):
@@ -57,7 +52,7 @@ Contains related children (same lifetime):
   - PaymentInfo:
     method: credit_card, amount: $400
 
-Events in stream:
+Events in timeline:
   1. OrderCreated (customer-789, 3 items)
   2. OrderLineAdded (item 1)
   3. OrderLineAdded (item 2)
@@ -66,21 +61,18 @@ Events in stream:
   6. PaymentProcessed (authorization complete)
   7. OrderShipped (tracking 123456)
 
-Stream Length: 7 events
-Snapshotting: NOT NEEDED (well under 1000) 
-
 Pattern: Small, bounded number of children per parent
 Lifetime: Parent and all children created/destroyed together
-Consistency: All modified as a unit (can't ship without payment, etc.)
+Together: they change as a unit (can't ship without payment, etc.)
 ```
 
 ---
 
 ### Pattern 3: Collection (ANTI-PATTERN - DO NOT USE)
 
- WRONG: Treating a collection as aggregate
+WRONG: Treating a collection as an entity
 ```
-Bad Aggregate: AllOrders
+Bad Entity: AllOrders
 Root Identity: "all-orders-collection" (artificial, meaningless)
 
 Contains: Every order ever created
@@ -91,33 +83,23 @@ Events:
     4. OrderCreated (customer-003, order-004)
     ... (continues forever, unbounded)
 
-Month 1: 50,000 events
-Year 1: 600,000 events
-Year 5: 3,000,000 events 
-
-Stream Length: 1,000,000+ events
-Snapshotting: Doesn't help - design is fundamentally wrong 
-
 Problems with this approach:
   - No single business identity (it's a collection, not an entity)
-  - Stream grows unbounded (can never achieve performance SLA)
-  - Snapshotting won't fix it (snapshot is also 1M+ events)
-  - Can't split or scale
-  - Every write goes to same stream (contention)
+  - Timeline grows unbounded — no natural end to its lifetime
 
-Solution: Use a projection/read model query instead, not an aggregate
+Solution: Use a projection/read model query instead, not an entity
   - Query: "GetAllOrdersByCustomer(customer-id)"
   - Query: "GetOrdersByStatus(status)"
-  - Rebuild from individual Order streams on-demand
+  - Rebuild from individual Order timelines on-demand
 ```
 
 ---
 
 ### Pattern 4: Event Log (ANTI-PATTERN - DO NOT USE)
 
- WRONG: Using aggregate as event log
+WRONG: Using an entity as an event log
 ```
-Bad Aggregate: SystemLog
+Bad Entity: SystemLog
 Root Identity: "system-log" (meaningless placeholder)
 
 Contains: Every system event imaginable
@@ -130,37 +112,26 @@ Events:
     6. UserLoggedIn (user-223)
     ... (grows indefinitely, no pattern)
 
-Per Day: 100,000+ events
-Per Year: 36,500,000+ events 
-
-Stream Length: 10,000,000+ events
-Snapshotting: Impossible - design is fundamentally broken 
-
 Problems with this approach:
   - No business identity (log of everything)
   - Events unrelated to each other (mixing user, order, payment, inventory)
-  - No consistency boundary (user login != order creation)
   - Can't answer "what's the state of X?" (too mixed)
-  - Contention: every subsystem writing to same stream
-  - Can't replay meaningfully (mixed concerns)
 
-Solution: Use separate event logs or time-series database
-  - Keep dedicated event streams: Order, Payment, Inventory, User
-  - Use time-series DB for metrics/logs: Prometheus, DataDog, ELK
-  - Query system logs separately from domain events
+Solution: Use separate event timelines per business entity
+  - Keep dedicated event timelines: Order, Payment, Inventory, User
 ```
 
 ---
 
-### Pattern 5: Historical Aggregate (GOOD - When Needed)
+### Pattern 5: Historical Entity (GOOD - When Needed)
 
- CORRECT: Keep historical data for audit/compliance
+CORRECT: Keep historical data for audit/compliance as its own boundary
 ```
-Aggregate: ArchivedOrder
+Entity: ArchivedOrder
 Root Identity: archivedOrderId (e.g., 'archived-order-001')
 Purpose: Regulatory compliance (7-year retention)
 
-Contains: Snapshot + audit trail of an order
+Contains: A record + audit trail of an order
 Events:
     1. OrderArchived (original order-123 on 2023-12-31)
        - reason: compliance_retention
@@ -177,153 +148,101 @@ Events:
   ... (additional audit entries over time)
 
 Lifetime: 7 years (regulatory requirement)
-Stream Length: 500-2000 events (audit entries added slowly)
-Snapshotting: Not needed (historical, not active) 
 
-Key architectural principles:
-  - Completely separate from active Order aggregate
+Key principles:
+  - Completely separate from the active Order entity
   - Active Order is for current business operations
-  - Archived Order is immutable historical record
-  - Different access patterns, different SLAs
+  - Archived Order is an immutable historical record
+  - Different access patterns, different lifecycles
 ```
 
 ---
 
-## Stream Size Decision Tree
+## Timeline Boundary Decision Tree
 
-Use this to decide if your streams are properly designed:
+Use this to decide whether a timeline is bounded around the right business identity:
 
 ```
-Does your stream have a natural business identity?
- NO → This is not an aggregate, it's a log/report
-    SOLUTION: Use read model/projection, not aggregate
+Does your timeline have a natural business identity?
+ NO → This is not an entity, it's a log/report
+    SOLUTION: Use a read model/projection, not an entity
 
- YES → How many events does it accumulate?
+ YES → Does every event in the timeline belong to that one entity's lifecycle?
    
-    < 100 events
-       PERFECT: No optimization needed
+    YES → GOOD: Boundary is correctly scoped to one identity
    
-    100-1000 events
-      Is it growing because of high frequency?
-        NO →  GOOD: Probably well-designed
-        YES →  MONITOR: Watch for growth
-     
-      Does each event represent a meaningful state change?
-         YES →  GOOD: Healthy stream
-         NO →  REDESIGN: Too granular events
-   
-    1000-5000 events
-      Can you split this aggregate?
-        YES →  REDESIGN: Do it now
+    NO → The boundary is too wide — it's absorbing events that
+         belong to a different entity or a different concern
+        REDESIGN: Split by the entity each event actually concerns
           Examples: User → UserProfile + UserSessions
-                    Order → Order + OrderLineItems
-       
-        NO → Is read frequency high (> 10/sec)?
-           YES →  Consider snapshotting at 5000
-           NO →  ACCEPTABLE: Leave as-is
-     
-      Is latency critical (< 100ms)?
-         YES →  MONITOR: Measure replay time
-         NO →  ACCEPTABLE: No snapshotting needed
-   
-    5000-10000 events
-      This is a design problem →  REDESIGN
-      OR business justifies complexity → Snapshot at 5000
-     
-      Questions before snapshotting:
-         Can I split aggregate? (usually YES)
-         Can I reduce event granularity? (sometimes)
-         Am I using a read model for this aggregate? (maybe not)
-         If all NO → Then snapshot is justified
-   
-    > 10000 events
-        CRITICAL: Redesign required
-           This is NOT a properly designed aggregate
-           Snapshotting won't save you
-           Root cause: Aggregate boundary is wrong
+                    Order → Order + OrderLineItems (if line items
+                    have their own independent lifecycle)
 ```
 
 ---
 
-## Red Flags: Redesign Needed (Not Snapshotting)
+## Red Flags: Boundary Is Wrong
 
-If your stream exhibits ANY of these, snapshotting won't help—you need to redesign:
+If your timeline exhibits ANY of these, the fix is a narrower or different identity — not a technical workaround:
 
 ```
- Red Flag 1: Stream growing > 1000 events/day
-   Cause: Events are too granular
-   Solution: Batch events or coarsen granularity
-   Example: "UserClickedButton" → "UserCompletedTask" (higher level)
-
- Red Flag 2: Thousands of events but no business meaning
-   Cause: Treating log as aggregate
-   Solution: Use read model/query instead of aggregate
-   Example: "SystemMetricRecorded"  → Use time-series database 
-
- Red Flag 3: Stream contains unrelated entities
-   Cause: Aggregate boundary is wrong
-   Solution: Split into separate aggregates
-   Example: "AllOrders"  → "Order" per customer 
-
- Red Flag 4: Snapshot is 80% of the stream size
-   Cause: Snapshot isn't helping
-   Solution: Re-examine aggregate boundary
-   Example: If snapshot is 800 events and deltas 100, redesign
-
- Red Flag 5: Can't explain what business question the stream answers
-   Cause: Not a real aggregate
-   Solution: Convert to read model/projection
-   Example: "SystemEvents"  → Query specific streams 
-
- Red Flag 6: Stream length doubles every 6 months
-   Cause: Exponential growth pattern
-   Solution: Likely aggregate boundary issue
-   Example: Split by time period: 2024-Orders vs. 2025-Orders
+Red Flag 1: Timeline growing continuously with no natural end
+   Cause: The timeline identity spans an unbounded population, not one entity
+   Solution: Re-scope to a single business entity's lifecycle
+   Example: "AllOrders" timeline → "Order" per customer order
+
+Red Flag 2: Events with no shared business meaning
+   Cause: Treating a log as an entity
+   Solution: Use a read model/query instead of an entity
+   Example: "SystemMetricRecorded" → use a metrics/observability system
+
+Red Flag 3: Timeline contains unrelated entities
+   Cause: Entity boundary is wrong
+   Solution: Split into separate entities
+   Example: "AllOrders" → "Order" per customer
+
+Red Flag 4: Can't explain what single business question the timeline answers
+   Cause: Not a real entity — probably a collection or log
+   Solution: Convert to a read model/projection
+   Example: "SystemEvents" → query specific per-entity timelines instead
 ```
 
 ---
 
-## Tips for Optimal Stream Design
+## Tips for Finding the Right Boundary
 
-### 1. Favor Redesign Over Snapshotting
+### 1. Anchor on a Single Business Identity
 ```
-Cost:  Redesign effort < Snapshotting maintenance
-Quality: Better design > Better optimization
-Future: Smaller streams are easier to scale
+Every timeline should answer: "the history of exactly which entity?"
+If the answer is "a category of things" or "everything," the
+boundary is wrong — it's describing a collection, not an entity.
 ```
 
 ### 2. Understand Event Granularity
 ```
- RIGHT: One event per meaningful state change
- WRONG: Multiple events per semantic operation
+RIGHT: One event per meaningful state change
+WRONG: Multiple events per semantic operation
 Example: "UserUpdatedProfile" (1 event)
 NOT: "FirstNameChanged", "LastNameChanged", ... (N events)
 ```
 
-### 3. Split When Possible
+### 3. Split When the Identity Is Actually Two Identities
 ```
- AllOrders (growing unbounded)
- Order (per order)
- OrderLine (per line item)
-
- UserAccount (everything about user)
- UserProfile (personal info)
- UserPreferences (settings)
- UserSessions (login history)
+AllOrders (growing unbounded, no single identity)
+→ Order (per order)
+→ OrderLine (per line item, if it has its own independent lifecycle)
+
+UserAccount (everything about a user, several unrelated concerns)
+→ UserProfile (personal info)
+→ UserPreferences (settings)
+→ UserSessions (login history)
 ```
 
-### 4. Archive Old Data
+### 4. Separate Active From Historical Concerns
 ```
- Keep everything in active aggregate
- Move completed/closed data to archive aggregate
+Keeping everything in one entity forever conflates two different
+lifecycles: the entity while it's active, and its record afterward.
 Example:
   - ActiveSubscription (current state)
   - ArchivedSubscription (after cancelled)
 ```
-
-### 5. Measure Before Optimizing
-```
- Assume snapshotting is needed
- Measure replay latency first
- Only snapshot if measurement justifies it
-```