interaqt 1.1.2 → 1.1.3

package/agent/skill/interaqt-patterns.md

@@ -15,12 +15,12 @@ const User = Entity.create({
     Property.create({ name: 'name', type: 'string' }),
     Property.create({ name: 'email', type: 'string' }),
     Property.create({ name: 'age', type: 'number' }),
-    Property.create({ name: 'status', type: 'string', defaultValue: 'active' }),
+    Property.create({ name: 'status', type: 'string', defaultValue: () => 'active' }),
     Property.create({ name: 'createdAt', type: 'string', defaultValue: () => new Date().toISOString() }),
     Property.create({
       name: 'fullName',
       type: 'string',
-      getValue: (record) => `${record.firstName} ${record.lastName}`
+      computed: (record) => `${record.firstName} ${record.lastName}`
     })
   ]
 })
@@ -52,7 +52,7 @@ The Klass pattern uses `generateUUID()` internally. Manual IDs risk collisions a
 ### Checklist
 - [ ] Entity name is PascalCase and singular (`User` not `users`)
 - [ ] No manual UUID assignment
-- [ ] Computed properties that depend only on the same record use `getValue`, NOT Transform
+- [ ] Computed properties that depend only on the same record use `computed`, NOT Transform
 - [ ] Properties with reactive computations (Count, etc.) include `defaultValue`
 
 ---
@@ -148,7 +148,7 @@ Without `type`, the framework cannot determine cardinality. ALWAYS explicitly se
 | Check ANY related record matches condition | `Any` |
 | Derive new entities from events or other entities | `Transform` (on Entity `computation`) |
 | Update a property value based on state transitions | `StateMachine` (on Property `computation`) |
-| Simple computation from same-record fields | `getValue` (on Property) |
+| Simple computation from same-record fields | `computed` (on Property) |
 
 ```typescript
 import { Entity, Property, Relation, Count, WeightedSummation, Transform, InteractionEventEntity } from 'interaqt'
@@ -184,12 +184,12 @@ Property.create({
 Property.create({
   name: 'formattedPrice',
   type: 'string',
-  getValue: (record) => `$${record.price}`
+  computed: (record) => `$${record.price}`
 })
 ```
 
 ### WHY
-Transform creates new records in a computed entity collection. It CANNOT update a single property. Use `getValue` for same-entity property computations.
+Transform creates new records in a computed entity collection. It CANNOT update a single property. Use `computed` for same-entity property computations.
 
 ### WRONG: Transform for counting
 ```typescript
@@ -220,8 +220,8 @@ Count uses incremental algorithms. Transform loads all records into memory, whic
 ```typescript
 // DON'T — Controller does NOT accept a computations parameter
 const controller = new Controller({
-  system, entities, relations, activities, interactions,
-  dict: [myComputation],  // dict is for Dictionaries, not computations
+  system, entities, relations,
+  eventSources: [myComputation],  // eventSources is for Interactions, not computations
 })
 ```
 
@@ -243,7 +243,7 @@ All computations are declared within the `computation` field of Entity, Relation
 - [ ] Transform is on `Entity.computation` or `Relation.computation`, NEVER on `Property.computation`
 - [ ] Count, WeightedSummation, Every, Any are on `Property.computation`
 - [ ] StateMachine is on `Property.computation`
-- [ ] `getValue` is used for same-record-only property derivations
+- [ ] `computed` is used for same-record-only property derivations
 - [ ] Properties with computation ALWAYS have `defaultValue`
 - [ ] NEVER pass computations to Controller constructor
 
@@ -261,9 +261,9 @@ const CreatePost = Interaction.create({
   action: Action.create({ name: 'createPost' }),
   payload: Payload.create({
     items: [
-      PayloadItem.create({ name: 'title', required: true }),
-      PayloadItem.create({ name: 'content', required: true }),
-      PayloadItem.create({ name: 'postId', base: Post, isRef: true })
+      PayloadItem.create({ name: 'title', type: 'string', required: true }),
+      PayloadItem.create({ name: 'content', type: 'string', required: true }),
+      PayloadItem.create({ name: 'postId', type: 'string', base: Post, isRef: true })
     ]
   })
 })
@@ -310,8 +310,7 @@ const controller = new Controller({
   system,
   entities: [User, Post],
   relations: [UserPosts],
-  activities: [],
-  interactions: [CreatePost],
+  eventSources: [CreatePost],
   dict: [],
   recordMutationSideEffects: []
 })
@@ -319,18 +318,18 @@ const controller = new Controller({
 await controller.setup(true)
 ```
 
-### WRONG: Calling callInteraction before setup
+### WRONG: Calling dispatch before setup
 ```typescript
 // DON'T — setup MUST come first
-const controller = new Controller({ system, entities, relations, activities, interactions, dict: [] })
-await controller.callInteraction('CreatePost', { user: { id: '1' }, payload: { title: 'Hi' } })
+const controller = new Controller({ system, entities, relations, eventSources: [CreatePost], dict: [] })
+await controller.dispatch(CreatePost, { user: { id: '1' }, payload: { title: 'Hi' } })
 ```
 
 ### CORRECT:
 ```typescript
-const controller = new Controller({ system, entities, relations, activities, interactions, dict: [] })
+const controller = new Controller({ system, entities, relations, eventSources: [CreatePost], dict: [] })
 await controller.setup(true)
-await controller.callInteraction('CreatePost', { user: { id: '1' }, payload: { title: 'Hi' } })
+await controller.dispatch(CreatePost, { user: { id: '1' }, payload: { title: 'Hi' } })
 ```
 
 ### WHY
@@ -338,15 +337,15 @@ await controller.callInteraction('CreatePost', { user: { id: '1' }, payload: { t
 
 ### Checklist
 - [ ] `system.conceptClass = KlassByName` is set before creating Controller
-- [ ] `controller.setup(true)` is called BEFORE any `callInteraction`
+- [ ] `controller.setup(true)` is called BEFORE any `dispatch`
 - [ ] `dict` contains only Dictionary instances, not computations
 
 ---
 
-## When Calling Interactions
+## When Dispatching Interactions
 
 ```typescript
-const result = await controller.callInteraction('CreatePost', {
+const result = await controller.dispatch(CreatePost, {
   user: { id: 'user-1', role: 'author' },
   payload: {
     title: 'My Post',
@@ -361,17 +360,17 @@ if (result.error) {
 
 ### WRONG: Using try-catch for error handling
 ```typescript
-// DON'T — interaqt does NOT throw exceptions
+// DON'T — interaqt does NOT throw exceptions by default
 try {
-  await controller.callInteraction('CreatePost', { user: { id: '1' }, payload: {} })
+  await controller.dispatch(CreatePost, { user: { id: '1' }, payload: {} })
 } catch (e) {
-  // This code will NEVER execute
+  // This code will NEVER execute (unless forceThrowDispatchError is true)
 }
 ```
 
 ### CORRECT:
 ```typescript
-const result = await controller.callInteraction('CreatePost', {
+const result = await controller.dispatch(CreatePost, {
   user: { id: '1' },
   payload: {}
 })
@@ -381,20 +380,26 @@ if (result.error) {
 ```
 
 ### WHY
-The framework catches all errors internally and returns them via `result.error`. Exceptions are never thrown to callers.
+The framework catches all errors internally and returns them via `result.error`. Exceptions are never thrown to callers (unless `forceThrowDispatchError: true` is set on Controller).
+
+### WRONG: Passing a name string instead of instance
+```typescript
+// DON'T — first argument must be the event source instance, not a string
+controller.dispatch('CreatePost', payload)
+```
 
 ### WRONG: Using non-existent API methods
 ```typescript
 // DON'T — these methods do NOT exist
-controller.dispatch('CreatePost', payload)
+controller.callInteraction('CreatePost', payload)
 controller.run()
 controller.execute()
 ```
 
 ### CORRECT:
 ```typescript
-// The ONLY method to trigger interactions
-await controller.callInteraction('CreatePost', {
+// The ONLY method to trigger interactions — first arg is the instance reference
+await controller.dispatch(CreatePost, {
   user: { id: 'user-1' },
   payload: { title: 'Hi' }
 })
@@ -403,7 +408,7 @@ await controller.callInteraction('CreatePost', {
 ### Checklist
 - [ ] ALWAYS pass a `user` object with at least `id`
 - [ ] ALWAYS check `result.error` — NEVER use try-catch
-- [ ] Use `controller.callInteraction(name, args)` — no other dispatch method exists
+- [ ] Use `controller.dispatch(eventSourceInstance, args)` — first arg is the instance, NOT a name string
 
 ---
 
@@ -486,13 +491,13 @@ describe('Feature', () => {
     system = new MonoSystem(new PGLiteDB())
     system.conceptClass = KlassByName
     controller = new Controller({
-      system, entities, relations, activities, interactions, dict: [], recordMutationSideEffects: []
+      system, entities, relations, eventSources, dict: [], recordMutationSideEffects: []
     })
     await controller.setup(true)
   })
 
   test('creates a post via interaction', async () => {
-    const result = await controller.callInteraction('CreatePost', {
+    const result = await controller.dispatch(CreatePost, {
       user: { id: 'user-1' },
       payload: { title: 'Test', content: 'Hello' }
     })
@@ -518,8 +523,8 @@ const post = await system.storage.create('Post', { title: 'Test', content: 'Hell
 
 ### CORRECT:
 ```typescript
-// Use callInteraction to test business logic
-const result = await controller.callInteraction('CreatePost', {
+// Use dispatch to test business logic
+const result = await controller.dispatch(CreatePost, {
   user: { id: 'user-1' },
   payload: { title: 'Test', content: 'Hello' }
 })
@@ -531,6 +536,6 @@ const result = await controller.callInteraction('CreatePost', {
 ### Checklist
 - [ ] Use `PGLiteDB` for test databases
 - [ ] Call `controller.setup(true)` in `beforeEach`
-- [ ] Test business logic through `callInteraction`, not direct storage
+- [ ] Test business logic through `controller.dispatch`, not direct storage
 - [ ] Check `result.error` — NEVER use try-catch
 - [ ] ALWAYS pass `attributeQuery` when asserting on query results

package/agent/skill/interaqt-recipes.md

@@ -30,7 +30,7 @@ const User = Entity.create({
       name: 'postCount',
       type: 'number',
       defaultValue: () => 0,
-      computation: Count.create({ record: UserPosts })
+      computation: Count.create({ property: 'posts' })
     })
   ]
 })
@@ -76,8 +76,8 @@ const CreatePost = Interaction.create({
   action: Action.create({ name: 'createPost' }),
   payload: Payload.create({
     items: [
-      PayloadItem.create({ name: 'title', required: true }),
-      PayloadItem.create({ name: 'content', required: true })
+      PayloadItem.create({ name: 'title', type: 'string', required: true }),
+      PayloadItem.create({ name: 'content', type: 'string', required: true })
     ]
   })
 })
@@ -91,8 +91,7 @@ const controller = new Controller({
   system,
   entities: [User, Post],
   relations: [UserPosts],
-  activities: [],
-  interactions: [CreatePost],
+  eventSources: [CreatePost],
   dict: [],
   recordMutationSideEffects: []
 })
@@ -105,7 +104,7 @@ const adminUser = await system.storage.create('User', {
   name: 'Alice', email: 'alice@example.com'
 })
 
-const result = await controller.callInteraction('CreatePost', {
+const result = await controller.dispatch(CreatePost, {
   user: adminUser,
   payload: { title: 'First Post', content: 'Hello World' }
 })
@@ -121,7 +120,7 @@ const user = await system.storage.findOne(
 ```
 
 ## Design Decisions
-- **Count on `postCount`**: Automatically maintained when UserPosts relations change. No manual update logic needed.
+- **Count on `postCount`**: Uses `property: 'posts'` to count related Post records via the `posts` navigation property. Automatically maintained when UserPosts relations change — no manual update logic needed.
 - **Transform on Post entity**: Posts are created reactively when `CreatePost` interaction fires. The Transform checks `interactionName` and returns entity data.
 - **Relation direction**: `source: Post, target: User, type: 'n:1'` — many posts to one user. `sourceProperty: 'author'` lets you navigate from Post to User; `targetProperty: 'posts'` lets you navigate from User to Posts.
 
@@ -143,49 +142,6 @@ import {
   Controller, MonoSystem, PGLiteDB, KlassByName, MatchExp
 } from 'interaqt'
 
-// --- Interactions ---
-
-const SubmitOrder = Interaction.create({
-  name: 'SubmitOrder',
-  action: Action.create({ name: 'submitOrder' }),
-  payload: Payload.create({
-    items: [
-      PayloadItem.create({ name: 'product', required: true }),
-      PayloadItem.create({ name: 'quantity', required: true })
-    ]
-  })
-})
-
-const PayOrder = Interaction.create({
-  name: 'PayOrder',
-  action: Action.create({ name: 'payOrder' }),
-  payload: Payload.create({
-    items: [
-      PayloadItem.create({ name: 'orderId', base: Order, isRef: true, required: true })
-    ]
-  })
-})
-
-const ShipOrder = Interaction.create({
-  name: 'ShipOrder',
-  action: Action.create({ name: 'shipOrder' }),
-  payload: Payload.create({
-    items: [
-      PayloadItem.create({ name: 'orderId', base: Order, isRef: true, required: true })
-    ]
-  })
-})
-
-const CancelOrder = Interaction.create({
-  name: 'CancelOrder',
-  action: Action.create({ name: 'cancelOrder' }),
-  payload: Payload.create({
-    items: [
-      PayloadItem.create({ name: 'orderId', base: Order, isRef: true, required: true })
-    ]
-  })
-})
-
 // --- State Nodes ---
 
 const pendingState = StateNode.create({ name: 'pending' })
@@ -211,18 +167,36 @@ const Order = Entity.create({
         transfers: [
           StateTransfer.create({
             current: pendingState, next: paidState,
-            trigger: PayOrder,
-            computeTarget: (event) => ({ id: event.payload.orderId })
+            trigger: {
+              recordName: InteractionEventEntity.name,
+              type: 'create',
+              record: { interactionName: 'PayOrder' }
+            },
+            computeTarget: function(mutationEvent) {
+              return { id: mutationEvent.record.payload.orderId }
+            }
           }),
           StateTransfer.create({
             current: paidState, next: shippedState,
-            trigger: ShipOrder,
-            computeTarget: (event) => ({ id: event.payload.orderId })
+            trigger: {
+              recordName: InteractionEventEntity.name,
+              type: 'create',
+              record: { interactionName: 'ShipOrder' }
+            },
+            computeTarget: function(mutationEvent) {
+              return { id: mutationEvent.record.payload.orderId }
+            }
           }),
           StateTransfer.create({
             current: pendingState, next: cancelledState,
-            trigger: CancelOrder,
-            computeTarget: (event) => ({ id: event.payload.orderId })
+            trigger: {
+              recordName: InteractionEventEntity.name,
+              type: 'create',
+              record: { interactionName: 'CancelOrder' }
+            },
+            computeTarget: function(mutationEvent) {
+              return { id: mutationEvent.record.payload.orderId }
+            }
           })
         ],
         initialState: pendingState
@@ -245,6 +219,49 @@ const Order = Entity.create({
   })
 })
 
+// --- Interactions ---
+
+const SubmitOrder = Interaction.create({
+  name: 'SubmitOrder',
+  action: Action.create({ name: 'submitOrder' }),
+  payload: Payload.create({
+    items: [
+      PayloadItem.create({ name: 'product', type: 'string', required: true }),
+      PayloadItem.create({ name: 'quantity', type: 'number', required: true })
+    ]
+  })
+})
+
+const PayOrder = Interaction.create({
+  name: 'PayOrder',
+  action: Action.create({ name: 'payOrder' }),
+  payload: Payload.create({
+    items: [
+      PayloadItem.create({ name: 'orderId', type: 'string', base: Order, isRef: true, required: true })
+    ]
+  })
+})
+
+const ShipOrder = Interaction.create({
+  name: 'ShipOrder',
+  action: Action.create({ name: 'shipOrder' }),
+  payload: Payload.create({
+    items: [
+      PayloadItem.create({ name: 'orderId', type: 'string', base: Order, isRef: true, required: true })
+    ]
+  })
+})
+
+const CancelOrder = Interaction.create({
+  name: 'CancelOrder',
+  action: Action.create({ name: 'cancelOrder' }),
+  payload: Payload.create({
+    items: [
+      PayloadItem.create({ name: 'orderId', type: 'string', base: Order, isRef: true, required: true })
+    ]
+  })
+})
+
 // --- Controller Setup & Usage ---
 
 const system = new MonoSystem(new PGLiteDB())
@@ -254,8 +271,7 @@ const controller = new Controller({
   system,
   entities: [Order],
   relations: [],
-  activities: [],
-  interactions: [SubmitOrder, PayOrder, ShipOrder, CancelOrder],
+  eventSources: [SubmitOrder, PayOrder, ShipOrder, CancelOrder],
   dict: [],
   recordMutationSideEffects: []
 })
@@ -264,7 +280,7 @@ await controller.setup(true)
 const user = { id: 'user-1' }
 
 // Submit order
-const submitResult = await controller.callInteraction('SubmitOrder', {
+const submitResult = await controller.dispatch(SubmitOrder, {
   user,
   payload: { product: 'Widget', quantity: 3 }
 })
@@ -276,14 +292,14 @@ const order = await system.storage.findOne('Order',
 // order.status === 'pending'
 
 // Pay order
-await controller.callInteraction('PayOrder', {
+await controller.dispatch(PayOrder, {
   user,
   payload: { orderId: order.id }
 })
 // order.status → 'paid'
 
 // Ship order
-await controller.callInteraction('ShipOrder', {
+await controller.dispatch(ShipOrder, {
   user,
   payload: { orderId: order.id }
 })
@@ -292,22 +308,27 @@ await controller.callInteraction('ShipOrder', {
 
 ## Design Decisions
 - **StateMachine on `status` property**: Status transitions are declarative. The framework enforces valid transitions — you cannot jump from `pending` to `shipped` directly.
-- **`computeTarget`**: Each StateTransfer uses `computeTarget` to identify WHICH order the transition applies to, using the orderId from the interaction payload.
+- **`trigger` is a pattern object**: Each StateTransfer `trigger` is a `RecordMutationEventPattern` that matches against InteractionEvent creation events — it is NOT an Interaction instance. The `record.interactionName` field matches the specific interaction by name string.
+- **`computeTarget`**: Receives the `RecordMutationEvent` and returns which order the transition applies to. Access the InteractionEvent data via `mutationEvent.record` (e.g. `mutationEvent.record.payload.orderId`).
 - **Transform on Entity `computation`**: Creates order records reactively when `SubmitOrder` fires.
 - **Cancellation only from `pending`**: Only one `cancelledState` transfer is defined (from `pending`). Attempting to cancel a paid order will have no effect.
+- **Declaration order**: Order entity is defined before the Interactions that reference it (via `base: Order`). The StateMachine triggers use interaction name strings (not variable references), avoiding circular dependencies.
 
 ---
 
 # Recipe: Student GPA with Weighted Summation
 
 ## Scenario
-A student grading system where each student has grades for multiple subjects, each with different credit weights. The student's GPA is automatically computed using WeightedSummation.
+A student grading system where each student has grades for multiple subjects, each with different credit weights. The student's GPA is automatically computed using WeightedSummation. Grades are added via an Interaction to ensure computations trigger correctly.
 
 ## Complete Implementation
 
 ```typescript
 import {
-  Entity, Property, Relation, WeightedSummation, Count,
+  Entity, Property, Relation,
+  WeightedSummation, Summation, Count,
+  Interaction, Action, Payload, PayloadItem,
+  Transform, InteractionEventEntity,
   Controller, MonoSystem, PGLiteDB, KlassByName, MatchExp
 } from 'interaqt'
 
@@ -322,7 +343,8 @@ const Student = Entity.create({
       type: 'number',
       defaultValue: () => 0,
       computation: WeightedSummation.create({
-        record: StudentGrades,
+        property: 'grades',
+        direction: 'source',
         attributeQuery: [['target', { attributeQuery: ['score', 'credit'] }]],
         callback: (relation) => ({
           weight: relation.target.credit,
@@ -334,20 +356,17 @@ const Student = Entity.create({
       name: 'totalCredits',
       type: 'number',
       defaultValue: () => 0,
-      computation: WeightedSummation.create({
-        record: StudentGrades,
-        attributeQuery: [['target', { attributeQuery: ['credit'] }]],
-        callback: (relation) => ({
-          weight: 1,
-          value: relation.target.credit
-        })
+      computation: Summation.create({
+        property: 'grades',
+        direction: 'source',
+        attributeQuery: [['target', { attributeQuery: ['credit'] }]]
       })
     }),
     Property.create({
       name: 'courseCount',
       type: 'number',
       defaultValue: () => 0,
-      computation: Count.create({ record: StudentGrades })
+      computation: Count.create({ property: 'grades' })
     })
   ]
 })
@@ -358,7 +377,22 @@ const Grade = Entity.create({
     Property.create({ name: 'subject', type: 'string' }),
     Property.create({ name: 'score', type: 'number' }),
     Property.create({ name: 'credit', type: 'number' })
-  ]
+  ],
+  computation: Transform.create({
+    record: InteractionEventEntity,
+    attributeQuery: ['interactionName', 'payload'],
+    callback: function(event) {
+      if (event.interactionName === 'AddGrade') {
+        return {
+          subject: event.payload.subject,
+          score: event.payload.score,
+          credit: event.payload.credit,
+          student: { id: event.payload.studentId }
+        }
+      }
+      return null
+    }
+  })
 })
 
 // --- Relations ---
@@ -371,6 +405,21 @@ const StudentGrades = Relation.create({
   type: '1:n'
 })
 
+// --- Interactions ---
+
+const AddGrade = Interaction.create({
+  name: 'AddGrade',
+  action: Action.create({ name: 'addGrade' }),
+  payload: Payload.create({
+    items: [
+      PayloadItem.create({ name: 'studentId', type: 'string', required: true }),
+      PayloadItem.create({ name: 'subject', type: 'string', required: true }),
+      PayloadItem.create({ name: 'score', type: 'number', required: true }),
+      PayloadItem.create({ name: 'credit', type: 'number', required: true })
+    ]
+  })
+})
+
 // --- Controller Setup & Usage ---
 
 const system = new MonoSystem(new PGLiteDB())
@@ -380,8 +429,7 @@ const controller = new Controller({
   system,
   entities: [Student, Grade],
   relations: [StudentGrades],
-  activities: [],
-  interactions: [],
+  eventSources: [AddGrade],
   dict: [],
   recordMutationSideEffects: []
 })
@@ -389,8 +437,14 @@ await controller.setup(true)
 
 const student = await system.storage.create('Student', { name: 'Alice' })
 
-await system.storage.create('Grade', { subject: 'Math', score: 90, credit: 4, student: student.id })
-await system.storage.create('Grade', { subject: 'English', score: 80, credit: 3, student: student.id })
+await controller.dispatch(AddGrade, {
+  user: { id: 'system' },
+  payload: { studentId: student.id, subject: 'Math', score: 90, credit: 4 }
+})
+await controller.dispatch(AddGrade, {
+  user: { id: 'system' },
+  payload: { studentId: student.id, subject: 'English', score: 80, credit: 3 }
+})
 
 const result = await system.storage.findOne('Student',
   MatchExp.atom({ key: 'id', value: ['=', student.id] }),
@@ -403,16 +457,17 @@ const result = await system.storage.findOne('Student',
 ```
 
 ## Design Decisions
-- **WeightedSummation for GPA**: The `weight` is the credit value, and the `value` is the score. The framework computes `sum(weight*value) / sum(weight)` automatically.
-- **Separate Count for courseCount**: Even though totalCredits could imply count, Count is more efficient and semantically clear for counting.
-- **`attributeQuery` in computation**: Specifies which fields of related records to fetch, avoiding loading unnecessary data.
+- **WeightedSummation for GPA**: Uses `property: 'grades'` (property-level mode) to aggregate per-student. The `weight` is the credit value, and the `value` is the score. The framework computes `sum(weight*value) / sum(weight)` automatically.
+- **Summation for totalCredits**: Uses `Summation` (not `WeightedSummation`) because `totalCredits` is a simple sum. `WeightedSummation` with `weight=1` would compute an average, not a sum.
+- **Count for courseCount**: More efficient and semantically clear for counting than Summation or WeightedSummation.
+- **Grades added via Interaction + Transform**: Using `controller.dispatch` ensures reactive computations (WeightedSummation, Summation, Count) are triggered. Direct `storage.create` bypasses reactive computations and should only be used for prerequisite data (like creating the Student record).
 
 ---
 
-# Recipe: Interaction with Payload Validation
+# Recipe: Interaction with Condition Validation
 
 ## Scenario
-A content moderation system where only published posts can be shared. Demonstrates Attributive-based payload validation on interactions.
+A content moderation system where only published posts can be shared. Demonstrates Condition-based validation on Interactions: the framework checks the condition before allowing the interaction to proceed.
 
 ## Complete Implementation
 
@@ -420,7 +475,7 @@ A content moderation system where only published posts can be shared. Demonstrat
 import {
   Entity, Property,
   Interaction, Action, Payload, PayloadItem,
-  Attributive, BoolExp,
+  Condition,
   Controller, MonoSystem, PGLiteDB, KlassByName, MatchExp
 } from 'interaqt'
 
@@ -430,20 +485,11 @@ const Post = Entity.create({
   name: 'Post',
   properties: [
     Property.create({ name: 'title', type: 'string' }),
-    Property.create({ name: 'status', type: 'string', defaultValue: 'draft' })
+    Property.create({ name: 'status', type: 'string', defaultValue: () => 'draft' })
   ]
 })
 
-// --- Attributive (validation rule) ---
-
-const PublishedPost = Attributive.create({
-  name: 'PublishedPost',
-  content: function(post, eventArgs) {
-    return post.status === 'published'
-  }
-})
-
-// --- Interaction with validation ---
+// --- Interaction with condition ---
 
 const SharePost = Interaction.create({
   name: 'SharePost',
@@ -452,12 +498,23 @@ const SharePost = Interaction.create({
     items: [
       PayloadItem.create({
         name: 'post',
+        type: 'string',
         base: Post,
         isRef: true,
-        required: true,
-        attributives: PublishedPost
+        required: true
       })
     ]
+  }),
+  conditions: Condition.create({
+    name: 'postMustBePublished',
+    content: async function(event) {
+      const post = await this.system.storage.findOne('Post',
+        MatchExp.atom({ key: 'id', value: ['=', event.payload.post] }),
+        undefined,
+        ['id', 'status']
+      )
+      return post?.status === 'published'
+    }
   })
 })
 
@@ -470,8 +527,7 @@ const controller = new Controller({
   system,
   entities: [Post],
   relations: [],
-  activities: [],
-  interactions: [SharePost],
+  eventSources: [SharePost],
   dict: [],
   recordMutationSideEffects: []
 })
@@ -480,22 +536,22 @@ await controller.setup(true)
 const draftPost = await system.storage.create('Post', { title: 'Draft', status: 'draft' })
 const publishedPost = await system.storage.create('Post', { title: 'Published', status: 'published' })
 
-// Sharing a draft post fails validation
-const failResult = await controller.callInteraction('SharePost', {
+// Sharing a draft post fails the condition check
+const failResult = await controller.dispatch(SharePost, {
   user: { id: 'user-1' },
-  payload: { post: { id: draftPost.id } }
+  payload: { post: draftPost.id }
 })
-// failResult.error is defined — draft post cannot be shared
+// failResult.error is defined — condition rejected: post is not published
 
 // Sharing a published post succeeds
-const successResult = await controller.callInteraction('SharePost', {
+const successResult = await controller.dispatch(SharePost, {
   user: { id: 'user-1' },
-  payload: { post: { id: publishedPost.id } }
+  payload: { post: publishedPost.id }
 })
 // successResult.error is undefined — success
 ```
 
 ## Design Decisions
-- **Attributive on PayloadItem**: The `PublishedPost` attributive is attached directly to the PayloadItem, so the framework validates the referenced entity's data before the interaction proceeds.
-- **`isRef: true`**: The payload contains only an ID reference. The framework loads the full record and runs the attributive check against it.
-- **Error in result, not exception**: Validation failures are returned in `result.error`, consistent with all interaqt error handling.
+- **Condition on Interaction**: The `Condition.create` is attached to the Interaction's `conditions` field. The `content` function receives the event args and returns `true` to allow or `false` to reject. The `this` context is bound to the Controller, providing access to `this.system.storage` for database queries.
+- **`isRef: true`**: The payload contains only an ID reference. With `isRef: true`, the payload value is the entity ID directly (e.g., `payload: { post: draftPost.id }`).
+- **Error in result, not exception**: Condition failures return `{ error: { type: 'condition check failed' } }`, consistent with all interaqt error handling. Never use try-catch.

package/agent/skill/interaqt-reference.md

@@ -8,18 +8,21 @@
 
 ```typescript
 Entity.create(args: {
-  name: string                        // PascalCase, singular, unique
-  properties: PropertyInstance[]      // Array of Property.create() results
+  name: string                        // PascalCase, singular, unique, must match /^[a-zA-Z0-9_]+$/
+  properties?: PropertyInstance[]     // Array of Property.create() results (defaults to [])
   computation?: ComputationInstance   // Transform for derived entities
-  baseEntity?: EntityInstance         // For filtered entities
-  filterCondition?: MatchExp          // For filtered entities
+  baseEntity?: EntityInstance | RelationInstance  // For filtered entities
+  matchExpression?: MatchExp          // Filter condition for filtered entities
+  inputEntities?: EntityInstance[]    // For merged entities
+  commonProperties?: PropertyInstance[]  // Shared attributes for merged entities
 }): EntityInstance
 ```
 
 Constraints:
 - NEVER pass `uuid` — the framework generates it
-- `name` must match `/^[a-zA-Z0-9_]+$/`
 - `computation` accepts only Transform (for creating derived entity collections)
+- **Filtered entity**: set `baseEntity` + `matchExpression`
+- **Merged entity**: set `inputEntities` + `commonProperties` (cannot define own `properties`)
 
 ---
 
@@ -27,21 +30,21 @@ Constraints:
 
 ```typescript
 Property.create(args: {
-  name: string                        // Property name
-  type?: 'string' | 'number' | 'boolean' | 'object'
+  name: string                        // Must match /^[a-zA-Z0-9_]+$/
+  type: string                        // Required: 'string' | 'number' | 'boolean' | 'object'
   collection?: boolean                // true for array types
-  defaultValue?: any | (() => any)    // Static value or factory function
-  getValue?: (record: any) => any     // Computed from same-record fields (not persisted)
-  computed?: (record: any) => any     // Alias for getValue
-  computation?: ComputationInstance   // Reactive: Count, WeightedSummation, Every, Any, StateMachine
+  defaultValue?: Function             // Factory function returning default value
+  computed?: (record: any) => any     // Computed from same-record fields (not persisted)
+  computation?: ComputationInstance   // Reactive: Count, Summation, WeightedSummation, Every, Any, StateMachine, Custom
 }): PropertyInstance
 ```
 
 Constraints:
-- `getValue`/`computed` are for same-record derivations only — NOT persisted
+- `type` is REQUIRED — always specify it
+- `computed` is for same-record derivations only — NOT persisted
 - `computation` results ARE persisted and auto-updated
-- When using `computation`, ALWAYS provide `defaultValue`
-- NEVER use Transform on Property `computation` — Transform belongs on Entity `computation`
+- When using `computation`, provide `defaultValue`
+- NEVER use Transform on Property `computation` — Transform belongs on Entity/Relation `computation`
 
 ---
 
@@ -49,20 +52,33 @@ Constraints:
 
 ```typescript
 Relation.create(args: {
-  source: EntityInstance               // Source entity
+  // Base relation (all required for normal relations):
+  name?: string                       // Optional — auto-generated if omitted
+  source: EntityInstance | RelationInstance
   sourceProperty: string              // Navigation property on source
-  target: EntityInstance               // Target entity
+  target: EntityInstance | RelationInstance
   targetProperty: string              // Navigation property on target
   type: '1:1' | '1:n' | 'n:1' | 'n:n'
   properties?: PropertyInstance[]     // Relation's own properties
   computation?: ComputationInstance   // Transform for computed relations
+  isTargetReliance?: boolean          // Defaults to false
+
+  // Filtered relation:
+  baseRelation?: RelationInstance     // Base relation to filter from
+  matchExpression?: MatchExp          // Filter condition
+
+  // Merged relation:
+  inputRelations?: RelationInstance[] // Relations to merge (must share same source/target)
+  commonProperties?: PropertyInstance[]  // Shared attributes for merged relations
 }): RelationInstance
 ```
 
 Constraints:
-- NEVER specify `name` — auto-generated from source+target entity names
-- ALWAYS specify `type` explicitly
+- `name` is optional — auto-generated as `${source.name}_${sourceProperty}_${targetProperty}_${target.name}`
+- ALWAYS specify `type` explicitly for base relations
 - Symmetric relations: set `source === target` AND `sourceProperty === targetProperty`
+- **Filtered relation**: requires `baseRelation` + `matchExpression` + `sourceProperty` + `targetProperty`
+- **Merged relation**: requires `inputRelations` + `sourceProperty` + `targetProperty` (cannot specify `source`/`target`/`properties`)
 
 ---
 
@@ -73,10 +89,16 @@ Interaction.create(args: {
   name: string                        // Interaction identifier
   action: ActionInstance              // Action.create() result (identifier only)
   payload?: PayloadInstance           // Payload.create() result
-  conditions?: ConditionInstance      // Execution conditions
+  conditions?: ConditionsInstance | ConditionInstance  // Execution conditions
+  data?: EntityInstance | RelationInstance  // Entity/Relation to query (for data retrieval)
+  dataPolicy?: DataPolicyInstance     // Fixed data access constraints
 }): InteractionInstance
 ```
 
+Constraints:
+- For data retrieval, use `GetAction` as action and specify `data`
+- `conditions` accepts either a single `Condition` or a `Conditions` (combined with BoolExp)
+
 ---
 
 ## Action.create
@@ -89,6 +111,7 @@ Action.create(args: {
 
 Constraints:
 - Action is ONLY an identifier — no `handler`, `execute`, or `callback`
+- Use `GetAction` (pre-built) for data retrieval interactions
 
 ---
 
@@ -101,37 +124,34 @@ Payload.create(args: {
 
 PayloadItem.create(args: {
   name: string                        // Parameter name
+  type: string                        // Required: data type
   base?: EntityInstance               // Entity reference for validation
   isRef?: boolean                     // true = reference by ID to existing entity
   required?: boolean                  // true = mandatory parameter
   isCollection?: boolean             // true = array of items
-  attributives?: AttributiveInstance  // Validation rules (only works when base is set)
+  itemRef?: AttributiveInstance | EntityInstance  // Reference to entities defined in other interactions (for Activity)
 }): PayloadItemInstance
 ```
 
-Constraints:
-- Without `base`: framework only checks required/collection, no concept validation
-- With `base` + `isRef: true`: framework verifies entity exists by ID
-- With `base` + `attributives`: framework validates data against attributive rules
-- `attributives` are checked for EVERY item when `isCollection: true`
-
 ---
 
 ## Count.create
 
 ```typescript
 Count.create(args: {
-  record: EntityInstance | RelationInstance   // What to count
+  record?: EntityInstance | RelationInstance   // What to count (for entity/global level)
+  property?: string                           // Relation property name (for property level)
   direction?: 'source' | 'target'            // For relation counting
   callback?: (record: any) => boolean        // Filter function
   attributeQuery?: AttributeQueryData        // Fields to load for callback
-  dataDeps?: DataDepsConfig                  // External data dependencies
+  dataDeps?: DataDependencies                // External data dependencies
 }): CountInstance
 ```
 
 Constraints:
-- Place on Property `computation`, not Entity `computation`
-- ALWAYS provide `defaultValue` on the Property
+- Use `record` for global/entity-level counting, `property` for property-level counting
+- Place on Property `computation` or Dictionary `computation`
+- Provide `defaultValue` on the Property when using as property computation
 
 ---
 
@@ -139,10 +159,12 @@ Constraints:
 
 ```typescript
 WeightedSummation.create(args: {
-  record: RelationInstance                   // Relation to aggregate
-  callback: (relation: any) => { weight: number, value: number }
+  record?: EntityInstance | RelationInstance   // Entity/relation to aggregate (for global level)
+  property?: string                           // Relation property name (for property level)
+  direction?: 'source' | 'target'            // For relation-based computation
+  callback: (record: any) => { weight: number, value: number }
   attributeQuery?: AttributeQueryData
-  dataDeps?: DataDepsConfig
+  dataDeps?: DataDependencies
 }): WeightedSummationInstance
 ```
 
@@ -150,19 +172,41 @@ Result: `sum(weight * value) / sum(weight)`
 
 ---
 
+## Summation.create
+
+```typescript
+Summation.create(args: {
+  record?: EntityInstance | RelationInstance   // Entity/relation to sum (for global level)
+  property?: string                           // Relation property name (for property level)
+  direction?: 'source' | 'target'            // For relation-based summation
+  attributeQuery: AttributeQueryData          // Required: specifies field path to sum
+}): SummationInstance
+```
+
+Sums the field pointed to by the leftmost path in `attributeQuery`. Undefined/null/NaN/Infinity values are treated as 0.
+
+---
+
 ## Every.create / Any.create
 
 ```typescript
 Every.create(args: {
-  record: RelationInstance
-  callback: (relation: any) => boolean
+  record?: EntityInstance | RelationInstance   // For global level
+  property?: string                           // Relation property name (for property level)
+  direction?: 'source' | 'target'
+  callback: (record: any) => boolean
   attributeQuery?: AttributeQueryData
+  dataDeps?: DataDependencies
+  notEmpty?: boolean                          // Return value when collection is empty
 }): EveryInstance
 
 Any.create(args: {
-  record: RelationInstance
-  callback: (relation: any) => boolean
+  record?: EntityInstance | RelationInstance
+  property?: string
+  direction?: 'source' | 'target'
+  callback: (record: any) => boolean
   attributeQuery?: AttributeQueryData
+  dataDeps?: DataDependencies
 }): AnyInstance
 ```
 
@@ -175,17 +219,33 @@ Any.create(args: {
 
 ```typescript
 Transform.create(args: {
-  record: EntityInstance | RelationInstance   // Source data
-  callback: (record: any, dataDeps?: any) => any | null
+  // Mode 1: Entity/Relation Transform
+  record?: EntityInstance | RelationInstance   // Source data
   attributeQuery?: AttributeQueryData
-  dataDeps?: DataDepsConfig
+
+  // Mode 2: Event-Driven Transform
+  eventDeps?: {
+    [key: string]: {
+      recordName: string
+      type: 'create' | 'update' | 'delete'
+      record?: Record<string, unknown>
+      oldRecord?: Record<string, unknown>
+    }
+  }
+
+  // Common
+  callback: Function                          // (this: Controller, record/mutationEvent) => any | any[] | null
+  dataDeps?: { [key: string]: DataDep }
 }): TransformInstance
 ```
 
 Constraints:
 - Place on Entity `computation` or Relation `computation`, NEVER on Property
-- Return `null` from callback to skip (conditional transformation)
+- Return `null`/`undefined` from callback to skip (conditional transformation)
+- Return array to create multiple records from one source
 - NEVER reference the entity being defined as `record` (circular reference)
+- Use `eventDeps` mode for interaction-based transformations (recommended)
+- Use `record` mode for deriving entities from other entities
 
 ---
 
@@ -208,12 +268,16 @@ Place on Property `computation`. The property value equals the current state nod
 ```typescript
 StateNode.create(args: {
   name: string
-  computeValue?: (lastValue: any) => any    // Dynamic value when entering this state
+  computeValue?: (this: Controller, lastValue: any, event?: any) => any
 }): StateNodeInstance
 ```
 
 - Without `computeValue`: property value is the state name string
 - With `computeValue`: property value is the function's return value
+- `lastValue`: previous property value before transition (undefined for initial state)
+- `event`: the event record that triggered the transition (undefined during initialization)
+  - For interaction triggers: access `event.payload`, `event.user`, `event.interactionName`
+- `this` is bound to the Controller instance — async functions can use `this.system.storage`
 
 ---
 
@@ -223,12 +287,28 @@ StateNode.create(args: {
 StateTransfer.create(args: {
   current: StateNodeInstance                // From state
   next: StateNodeInstance                   // To state
-  trigger: InteractionInstance              // Interaction that causes transition
-  computeTarget: (event: any) => { id: any }  // Identifies which record to transition
+  trigger: RecordMutationEventPattern       // Pattern to match against mutation events
+  computeTarget?: Function                  // Determines which records to transition
 }): StateTransferInstance
 ```
 
-`computeTarget` extracts the target entity ID from the interaction event payload.
+**`trigger`** — a partial pattern object, NOT an Interaction instance:
+```typescript
+trigger: {
+  recordName: string             // e.g. InteractionEventEntity.name
+  type: 'create' | 'update' | 'delete'
+  record?: Record<string, any>   // deep partial match, e.g. { interactionName: myInteraction.name }
+  oldRecord?: Record<string, any>
+  keys?: string[]
+}
+```
+
+**`computeTarget`** — receives the mutation event, returns which record(s) to transition:
+- Entity: `{ id: string }` or `{ id: string }[]`
+- Relation: `{ source: { id: string }, target: { id: string } }`
+- Return `undefined` to skip
+- `this` is bound to Controller — async functions can use `this.system.storage`
+- Required for property-level StateMachines; omit for global StateMachines
 
 ---
 
@@ -236,26 +316,34 @@ StateTransfer.create(args: {
 
 ```typescript
 new Controller(args: {
-  system: MonoSystem
-  entities: EntityInstance[]
-  relations: RelationInstance[]
-  activities: ActivityInstance[]
-  interactions: InteractionInstance[]
-  dict: DictionaryInstance[]               // Global dictionaries, NOT computations
-  recordMutationSideEffects?: any[]
+  system: System
+  entities?: EntityInstance[]
+  relations?: RelationInstance[]
+  eventSources?: EventSourceInstance[]       // Interactions, custom EventSources, etc.
+  dict?: DictionaryInstance[]               // Global dictionaries
+  recordMutationSideEffects?: RecordMutationSideEffect[]
+  computations?: (new (...args: any[]) => Computation)[]  // Additional computation handle classes
+  ignoreGuard?: boolean                     // Skip guard checks when true
+  forceThrowDispatchError?: boolean         // Throw errors instead of returning them
 }): Controller
 
-controller.setup(install: boolean): Promise<void>
-controller.callInteraction(name: string, args: {
-  user: { id: string, [key: string]: any }
-  payload?: { [key: string]: any }
-}): Promise<{ error?: { message: string, [key: string]: any }, [key: string]: any }>
+controller.setup(install?: boolean): Promise<void>
+
+controller.dispatch<TArgs, TResult>(
+  eventSource: EventSourceInstance<TArgs, TResult>,
+  args: TArgs
+): Promise<DispatchResponse>
+
+// DispatchResponse = { error?, data?, effects?, sideEffects?, context? }
 ```
 
 Constraints:
-- ALWAYS call `setup(true)` before any `callInteraction`
+- ALWAYS call `setup(true)` before any `dispatch`
 - `dict` is for Dictionary instances ONLY — never pass computations here
-- `callInteraction` NEVER throws — errors are in `result.error`
+- `dispatch` first parameter is the event source object reference, NOT a name string
+- `dispatch` NEVER throws by default — errors are in `result.error`
+- Set `forceThrowDispatchError: true` to make dispatch throw instead
+- Controller automatically registers event source entities (e.g. `InteractionEventEntity`)
 
 ---
 
@@ -284,20 +372,29 @@ system.storage.find(
 
 system.storage.findOne(
   entityName: string,
-  matchExp: MatchExp,
+  matchExp?: MatchExp,
   modifier?: any,
   attributeQuery?: AttributeQuery
 ): Promise<any>
 
 system.storage.create(entityName: string, data: object): Promise<any>
-system.storage.update(entityName: string, matchExp: MatchExp, data: object): Promise<void>
+system.storage.update(entityName: string, matchExp: MatchExp, data: object): Promise<any>
 system.storage.delete(entityName: string, matchExp: MatchExp): Promise<void>
+
+// Dictionary-specific API
+system.storage.dict.get(key: string): Promise<any>
+system.storage.dict.set(key: string, value: any): Promise<void>
+
+// General KV storage
+system.storage.get(itemName: string, id: string, initialValue?: any): Promise<any>
+system.storage.set(itemName: string, id: string, value: any): Promise<any>
 ```
 
 Constraints:
 - ALWAYS pass `attributeQuery` to `find`/`findOne` — without it, only `id` is returned
 - Use `['*']` for all fields
 - `create`/`update`/`delete` bypass all validation — use ONLY for test setup
+- When querying relations, use dot notation for source/target: `{ key: 'source.id', value: ['=', id] }`
 
 ---
 
@@ -306,12 +403,15 @@ Constraints:
 ```typescript
 MatchExp.atom(args: { key: string, value: [operator, value] }): MatchExp
 
-// Operators: '=', '!=', '>', '>=', '<', '<=', 'like', 'in', 'between', 'not', 'exist'
+// Operators: '=', '!=', '>', '>=', '<', '<=', 'like', 'in', 'between', 'not'
 
 // Chaining
 matchExp.and(args: { key: string, value: [operator, value] }): MatchExp
 matchExp.or(args: { key: string, value: [operator, value] }): MatchExp
 
+// From object (all AND)
+MatchExp.fromObject({ status: 'active', age: 25 }): MatchExp
+
 // Nested field access
 MatchExp.atom({ key: 'author.name', value: ['=', 'Alice'] })
 ```
@@ -346,24 +446,43 @@ MatchExp.atom({ key: 'author.name', value: ['=', 'Alice'] })
 
 ```typescript
 Attributive.create(args: {
-  name: string
+  name?: string
   content: (record: any, eventArgs: any) => boolean
 }): AttributiveInstance
 ```
 
-Used on PayloadItem `attributives` to validate referenced entities.
+Used on Interaction `userAttributives` to validate user context.
 
 ---
 
 ## BoolExp
 
 ```typescript
-BoolExp.atom(attributive: AttributiveInstance): BoolExp
-boolExp.and(other: BoolExp): BoolExp
-boolExp.or(other: BoolExp): BoolExp
+BoolExp.atom(data: T): BoolExp
+boolExp.and(other: BoolExp | T): BoolExp
+boolExp.or(other: BoolExp | T): BoolExp
 ```
 
-Combines multiple Attributives for complex validation logic.
+Combines multiple Attributives, Conditions, or other expressions for complex logic.
+
+---
+
+## Condition.create / Conditions.create
+
+```typescript
+Condition.create(args: {
+  name?: string
+  content: (this: Controller, event: InteractionEventArgs) => Promise<boolean>
+}): ConditionInstance
+
+Conditions.create(args: {
+  content: BoolExp<ConditionInstance>     // Combined with AND/OR logic
+}): ConditionsInstance
+```
+
+- `content` returns `true` to allow, `false` to reject
+- `this` is bound to Controller — can access `this.system.storage`
+- Failed conditions return `{ error: { type: 'condition check failed' } }`
 
 ---
 
@@ -374,12 +493,53 @@ Dictionary.create(args: {
   name: string
   type: 'string' | 'number' | 'boolean' | 'object'
   collection?: boolean
-  defaultValue?: any | (() => any)
+  defaultValue?: Function
   computation?: ComputationInstance
 }): DictionaryInstance
 ```
 
-Global state values. Pass to Controller's `dict` parameter. Access via `system.storage.get('state', name)`.
+Global state values. Pass to Controller's `dict` parameter. Access via `system.storage.dict.get(name)` / `system.storage.dict.set(name, value)`.
+
+---
+
+## EventSource.create
+
+```typescript
+EventSource.create(args: {
+  name: string                        // Event source identifier
+  entity: EntityInstance              // Entity to persist event records
+  guard?: (this: Controller, args: TArgs) => Promise<void>
+  mapEventData?: (args: TArgs) => Record<string, any>
+  resolve?: (this: Controller, args: TArgs) => Promise<TResult>
+  afterDispatch?: (this: Controller, args: TArgs, result: { data?: TResult }) => Promise<Record<string, unknown> | void>
+}): EventSourceInstance
+```
+
+Custom event source for scheduled tasks, webhooks, or any non-interaction trigger. Dispatch via `controller.dispatch(eventSource, args)`.
+
+---
+
+## HardDeletionProperty.create
+
+```typescript
+HardDeletionProperty.create(): PropertyInstance
+```
+
+Creates a property named `_isDeleted_`. When its value transitions to `true` (via StateMachine), the Controller physically deletes the record. Use with `DELETED_STATE` / `NON_DELETED_STATE`.
+
+---
+
+## RecordMutationSideEffect.create
+
+```typescript
+RecordMutationSideEffect.create(args: {
+  name: string
+  record: { name: string }            // Entity/relation name to monitor
+  content: (this: Controller, event: RecordMutationEvent) => Promise<any>
+}): RecordMutationSideEffect
+```
+
+Triggers custom logic on record mutations within dispatch context. Results available in `dispatchResult.sideEffects`.
 
 ---
 
@@ -387,23 +547,52 @@ Global state values. Pass to Controller's `dict` parameter. Access via `system.s
 
 ```typescript
 import {
+  // Data model
   Entity, Property, Relation,
-  Interaction, Action, Payload, PayloadItem,
+
+  // Event sources
+  EventSource, Interaction, Action, GetAction, Payload, PayloadItem,
   Activity,
-  Count, Every, Any, Sum, Summation, WeightedSummation, Average,
+
+  // Computations
+  Count, Every, Any, Summation, WeightedSummation, Average,
   Transform, StateMachine, StateNode, StateTransfer,
-  RealTime, Expression, Inequality, Equation, MathResolver,
-  Attributive, Attributives, Condition, Conditions,
+  RealTime, Custom,
+
+  // Math (for RealTime)
+  Expression, Inequality, Equation, MathResolver,
+
+  // Validation & conditions
+  Attributive, Attributives, DataAttributive, DataAttributives,
+  Condition, Conditions,
+
+  // Data policy
+  DataPolicy,
+
+  // Expressions
   BoolExp, MatchExp,
+
+  // System
   Controller, MonoSystem, Dictionary,
+  RecordMutationSideEffect,
+  HardDeletionProperty, HARD_DELETION_PROPERTY_NAME,
+  NON_DELETED_STATE, DELETED_STATE,
+
+  // Built-in entities
   InteractionEventEntity,
+
+  // Drivers
   PGLiteDB, SQLiteDB, PostgreSQLDB, MysqlDB,
+
+  // Utilities
   KlassByName
 } from 'interaqt'
 ```
 
 Non-existent exports (commonly mistaken):
 - `InteractionEvent` → use `InteractionEventEntity`
-- `FilteredEntity` → use `Entity.create` with `baseEntity` + `filterCondition`
+- `FilteredEntity` → use `Entity.create` with `baseEntity` + `matchExpression`
 - `RelationBasedEvery` → use `Every`
+- `Sum` → use `Summation`
+- `callInteraction` → use `controller.dispatch(eventSource, args)`
 - `User`, `Post`, etc. → no pre-built entities exist

package/package.json

@@ -42,7 +42,7 @@
     "sync:agent": "tsx scripts/sync-agent-files.ts",
     "release": "release-it"
   },
-  "version": "1.1.2",
+  "version": "1.1.3",
   "main": "dist/index.js",
   "files": [
     "dist",