interaqt 0.3.1 → 0.4.0

package/agent/agentspace/knowledge/generator/api-reference.md

@@ -163,14 +163,14 @@ HardDeletionProperty.create(config?: HardDeletionPropertyConfig): PropertyInstan
 ```
 
 **Parameters**
-- `config.name` (string, optional): Property name, defaults to `'_isDeleted_'`
+- `config.name` (string, optional): Property name, defaults to `HARD_DELETION_PROPERTY_NAME`
 
 **Usage with StateMachine**
 
 HardDeletionProperty is typically used with StateMachine to manage record deletion:
 
 ```typescript
-import { DELETED_STATE, NON_DELETED_STATE } from 'interaqt'
+import { DELETED_STATE, NON_DELETED_STATE, HARD_DELETION_PROPERTY_NAME } from 'interaqt'
 
 // Define deletion StateMachine for the HardDeletionProperty
 const deletionStateMachine = StateMachine.create({
@@ -178,7 +178,12 @@ const deletionStateMachine = StateMachine.create({
     defaultState: NON_DELETED_STATE,
     transfers: [
         StateTransfer.create({
-            trigger: DeleteUserInteraction,
+            trigger: {
+                recordName: InteractionEventEntity.name,
+                record: {
+                    interactionName: DeleteUserInteraction.name
+                }
+            },
             current: NON_DELETED_STATE,
             next: DELETED_STATE,
             computeTarget: function(event) {
@@ -208,6 +213,11 @@ const User = Entity.create({
 2. The deletion is physical - the record is completely removed from the database
 3. This is different from soft deletion where records remain but are marked as deleted
 
+**Note**: When you need to find the HardDeletionProperty after entity creation, use:
+```typescript
+const hardDeletionProp = entity.properties.find(p => p.name === HARD_DELETION_PROPERTY_NAME)
+```
+
 **Example: Entity Creation and Deletion Pattern**
 
 ```typescript
@@ -217,16 +227,31 @@ const Article = Entity.create({
     properties: [
         Property.create({ name: 'title', type: 'string' }),
         Property.create({ name: 'content', type: 'string' }),
+        Property.create({ name: 'slug', type: 'string' }),
         HardDeletionProperty.create()
     ],
     // Transform creates new articles from interaction events
     computation: Transform.create({
-        record: InteractionEventEntity,
-        callback: function(event) {
+        eventDeps: {
+            ArticleInteraction: {
+                recordName: InteractionEventEntity.name,
+                type: 'create'
+            }
+        },
+        callback: async function(this: Controller, mutationEvent) {
+            const event = mutationEvent.record;
             if (event.interactionName === 'CreateArticle') {
+                // Use Controller to generate article slug
+                const existingCount = await this.system.storage.find('Article',
+                    undefined,
+                    undefined,
+                    ['id']
+                );
+                
                 return {
                     title: event.payload.title,
-                    content: event.payload.content
+                    content: event.payload.content,
+                    slug: `article-${existingCount.length + 1}`
                 }
             }
             return null
@@ -241,7 +266,12 @@ deletionProperty.computation = StateMachine.create({
     defaultState: NON_DELETED_STATE,
     transfers: [
         StateTransfer.create({
-            trigger: DeleteArticleInteraction,
+            trigger: {
+                recordName: InteractionEventEntity.name,
+                record: {
+                    interactionName: DeleteArticleInteraction.name
+                }
+            },
             current: NON_DELETED_STATE,
             next: DELETED_STATE,
             computeTarget: function(event) {
@@ -755,10 +785,211 @@ Transform.create(config: TransformConfig): TransformInstance
 ```
 
 **Parameters**
-- `config.record` (Entity|Relation, required): Entity or relation to transform from (source collection)
-- `config.callback` (function, required): Transformation function that converts source data to target data
-- `config.attributeQuery` (AttributeQueryData, required): Attribute query configuration
+Transform supports two modes of operation:
+
+1. **Entity/Relation Transform Mode**:
+   - `config.record` (Entity|Relation, required): Entity or relation to transform from (source collection)
+   - `config.attributeQuery` (AttributeQueryData, optional): Attribute query configuration
+   - `config.callback` (function, required): Transformation function that converts source data to target data
+     - **Context**: `this` is bound to the Controller instance, providing access to system APIs via `this.system.storage`, `this.globals`, etc.
+     - **Signature**: `function(this: Controller, record: any): any | any[]`
+
+2. **Event-Driven Transform Mode** (Recommended for interaction-based transformations):
+   - `config.eventDeps` (EventDeps, required): Event dependencies that trigger the transformation
+   - `config.callback` (function, required): Transformation function that processes mutation events
+     - **Context**: `this` is bound to the Controller instance, providing access to system APIs via `this.system.storage`, `this.globals`, etc.
+     - **Signature**: `function(this: Controller, mutationEvent: MutationEvent): any | any[]`
+
+**Event Dependencies (eventDeps)**
+
+The `eventDeps` parameter allows Transform to react to specific mutation events (create, update, delete) on entities. This is the recommended approach for transforming data based on interactions or system events.
+
+```typescript
+interface EventDep {
+  recordName: string;  // Entity name to listen to
+  type: 'create' | 'update' | 'delete';  // Event type
+}
+
+// Example eventDeps structure
+eventDeps: {
+  UserCreate: {
+    recordName: 'User',
+    type: 'create'
+  },
+  UserUpdate: {
+    recordName: 'User', 
+    type: 'update'
+  }
+}
+```
+
+**Examples**
+
+1. **Entity-to-Entity Transform** (for deriving new entities from existing ones):
+```typescript
+// Create discounted products from regular products
+const DiscountedProduct = Entity.create({
+  name: 'DiscountedProduct',
+  properties: [
+    Property.create({ name: 'name', type: 'string' }),
+    Property.create({ name: 'originalPrice', type: 'number' }),
+    Property.create({ name: 'discountedPrice', type: 'number' })
+  ],
+  computation: Transform.create({
+    record: Product,
+    attributeQuery: ['name', 'price'],
+    callback: async function(this: Controller, product) {
+      // Access system configuration via Controller
+      const discountRate = await this.system.storage.get('config', 'globalDiscountRate', 0.1);
+      
+      return {
+        name: product.name,
+        originalPrice: product.price,
+        discountedPrice: product.price * (1 - discountRate)
+      };
+    }
+  })
+})
+```
+
+2. **Event-Driven Transform** (recommended for interaction-based transformations):
+```typescript
+// Create audit logs from user mutations
+const UserAudit = Entity.create({
+  name: 'UserAudit',
+  properties: [
+    Property.create({ name: 'action', type: 'string' }),
+    Property.create({ name: 'userId', type: 'string' }),
+    Property.create({ name: 'timestamp', type: 'string' }),
+    Property.create({ name: 'changes', type: 'object' })
+  ],
+  computation: Transform.create({
+    eventDeps: {
+      UserCreate: {
+        recordName: 'User',
+        type: 'create'
+      },
+      UserUpdate: {
+        recordName: 'User',
+        type: 'update'
+      },
+      UserDelete: {
+        recordName: 'User',
+        type: 'delete'
+      }
+    },
+    callback: function(this: Controller, mutationEvent) {
+      // Access Controller APIs via 'this'
+      console.log('Audit log created by:', this.name); // Controller name
+      
+      return {
+        action: mutationEvent.type,
+        userId: (mutationEvent.record?.id || mutationEvent.oldRecord?.id),
+        timestamp: new Date().toISOString(),
+        changes: {
+          old: mutationEvent.oldRecord,
+          new: mutationEvent.record
+        }
+      }
+    }
+  })
+})
+```
 
+3. **Transform from Interaction Events**:
+```typescript
+// Create articles from interactions
+const Article = Entity.create({
+  name: 'Article',
+  properties: [
+    Property.create({ name: 'title', type: 'string' }),
+    Property.create({ name: 'content', type: 'string' }),
+    Property.create({ name: 'authorId', type: 'string' }),
+    Property.create({ name: 'authorName', type: 'string' })
+  ],
+  computation: Transform.create({
+    eventDeps: {
+      ArticleInteraction: {
+        recordName: InteractionEventEntity.name,
+        type: 'create'
+      }
+    },
+    callback: async function(this: Controller, mutationEvent) {
+      const event = mutationEvent.record;
+      if (event.interactionName === 'CreateArticle') {
+        // Use Controller to fetch additional user data
+        const author = await this.system.storage.findOne('User', 
+          this.globals.MatchExp.atom({ key: 'id', value: ['=', event.user.id] }),
+          undefined,
+          ['id', 'name']
+        );
+        
+        return {
+          title: event.payload.title,
+          content: event.payload.content,
+          authorId: event.user.id,
+          authorName: author?.name || 'Unknown'
+        }
+      }
+      return null;
+    }
+  })
+})
+```
+
+4. **One-to-Many Transform**:
+```typescript
+// Create multiple notifications from one order
+const Notification = Entity.create({
+  name: 'Notification',
+  properties: [
+    Property.create({ name: 'type', type: 'string' }),
+    Property.create({ name: 'recipient', type: 'string' }),
+    Property.create({ name: 'message', type: 'string' })
+  ],
+  computation: Transform.create({
+    eventDeps: {
+      OrderCreate: {
+        recordName: 'Order',
+        type: 'create'
+      }
+    },
+    callback: async function(this: Controller, mutationEvent) {
+      const order = mutationEvent.record;
+      
+      // Use Controller to fetch warehouse email from configuration
+      const warehouseEmail = await this.system.storage.get('config', 'warehouseEmail', 'warehouse@company.com');
+      
+      // Use Controller to check if customer wants notifications
+      const customer = await this.system.storage.findOne('User',
+        this.globals.MatchExp.atom({ key: 'email', value: ['=', order.customerEmail] }),
+        undefined,
+        ['id', 'notificationPreferences']
+      );
+      
+      const notifications = [];
+      
+      // Only send customer notification if they opted in
+      if (customer?.notificationPreferences?.orderUpdates !== false) {
+        notifications.push({
+          type: 'order_confirmation',
+          recipient: order.customerEmail,
+          message: `Order ${order.orderNumber} confirmed`
+        });
+      }
+      
+      // Always notify warehouse
+      notifications.push({
+        type: 'warehouse_notification',
+        recipient: warehouseEmail,
+        message: `New order ${order.orderNumber} to process`
+      });
+      
+      return notifications;
+    }
+  })
+})
+```
 
 **Key Points**
 
@@ -767,7 +998,23 @@ Transform.create(config: TransformConfig): TransformInstance
    - Array of objects: Creates multiple target records from one source
    - `null`/`undefined`: Creates no records (useful for filtering)
 
-2. **Automatic Updates**: When source records are updated or deleted, the transformed records are automatically updated or removed
+2. **Automatic Updates**: 
+   - For entity/relation transforms: When source records are updated or deleted, the transformed records are automatically updated or removed
+   - For event-driven transforms: New records are created in response to mutation events
+
+3. **Choosing Between Modes**:
+   - Use `record` mode when deriving entities from other entities (e.g., creating views or projections)
+   - Use `eventDeps` mode when creating entities in response to system events or interactions
+
+4. **MutationEvent Structure** (for eventDeps callbacks):
+   ```typescript
+   {
+     type: 'create' | 'update' | 'delete',
+     recordName: string,
+     record?: any,      // New/current record (for create/update)
+     oldRecord?: any    // Previous record (for update/delete)
+   }
+   ```
 
 ### StateMachine.create()
 
@@ -796,7 +1043,7 @@ const MyStateMachine = StateMachine.create({
     transfers: [...],
     defaultState: StateNode.create({
         name: 'pending',
-        computeValue: (lastValue) => {
+        computeValue: (lastValue, mutationEvent) => {
             // Explicitly handle initial value
             return lastValue || 'initial_state_value';
         }
@@ -818,7 +1065,13 @@ const OrderStateMachine = StateMachine.create({
         StateTransfer.create({
             current: pendingState,
             next: confirmedState,
-            trigger: ConfirmOrderInteraction
+            trigger: {
+                recordName: InteractionEventEntity.name,
+                record: {
+                    interactionName: ConfirmOrderInteraction.name
+                }
+            },
+            computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.orderId })
         })
     ],
     defaultState: pendingState
@@ -837,9 +1090,27 @@ const UserTargetRelation = Relation.create({
     ],
     // Use Transform to create relations
     computation: Transform.create({
-        record: InteractionEventEntity,
-        callback: function(event) {
+        eventDeps: {
+            RelationInteraction: {
+                recordName: InteractionEventEntity.name,
+                type: 'create'
+            }
+        },
+        callback: async function(this: Controller, mutationEvent) {
+            const event = mutationEvent.record;
             if (event.interactionName === 'CreateRelation') {
+                // Use Controller to validate the relation
+                const sourceExists = await this.system.storage.findOne('User',
+                    MatchExp.atom({ key: 'id', value: ['=', event.payload.sourceUser.id] }),
+                    undefined,
+                    ['id']
+                );
+                
+                if (!sourceExists) {
+                    console.log('Source user not found, skipping relation creation');
+                    return null;
+                }
+                
                 return {
                     source: event.payload.sourceUser,
                     target: event.payload.targetEntity,
@@ -860,19 +1131,24 @@ relationDeletionProperty.computation = StateMachine.create({
     defaultState: NON_DELETED_STATE,
     transfers: [
         StateTransfer.create({
-            trigger: DeleteRelationInteraction,
+            trigger: {
+                recordName: InteractionEventEntity.name,
+                record: {
+                    interactionName: DeleteRelationInteraction.name
+                }
+            },
             current: NON_DELETED_STATE,
             next: DELETED_STATE,
-            computeTarget: async function(this: Controller, event: any) {
+            computeTarget: async function(this: Controller, mutationEvent: any) {
                 const MatchExp = this.globals.MatchExp;
                 const relation = await this.system.storage.findOne(
                     UserTargetRelation.name,
                     MatchExp.atom({
                         key: 'source.id',
-                        value: ['=', event.payload.sourceId]
+                        value: ['=', mutationEvent.record.payload.sourceId]
                     }).and({
                         key: 'target.id',
-                        value: ['=', event.payload.targetId]
+                        value: ['=', mutationEvent.record.payload.targetId]
                     }),
                     undefined,
                     ['id']
@@ -1052,8 +1328,8 @@ const nextRecomputeTimeKey = controller.scheduler.getBoundStateName(
 );
 
 // Read state values
-const lastRecomputeTime = await system.storage.get(DICTIONARY_RECORD, lastRecomputeTimeKey);
-const nextRecomputeTime = await system.storage.get(DICTIONARY_RECORD, nextRecomputeTimeKey);
+const lastRecomputeTime = await system.storage.dict.get(lastRecomputeTimeKey);
+const nextRecomputeTime = await system.storage.dict.get(nextRecomputeTimeKey);
 ```
 
 ### Custom.create()
@@ -1516,10 +1792,13 @@ const activeUsers = Dictionary.create({
     computation: Transform.create({
         record: User,
         attributeQuery: ['id', 'lastLoginTime'],
-        callback: (users) => {
-            const oneHourAgo = Date.now() - 3600000;
+        callback: async function(this: Controller, users) {
+            // Use Controller to get activity threshold from config
+            const activityThreshold = await this.system.storage.get('config', 'userActivityThreshold', 3600000); // Default 1 hour
+            const cutoffTime = Date.now() - activityThreshold;
+            
             return users
-                .filter(u => u.lastLoginTime > oneHourAgo)
+                .filter(u => u.lastLoginTime > cutoffTime)
                 .map(u => u.id);
         }
     })
@@ -1586,13 +1865,13 @@ const pendingState = StateNode.create({ name: 'pending' });
 // Store timestamp when entering state
 const processedState = StateNode.create({
     name: 'processed',
-    computeValue: () => new Date().toISOString()
+    computeValue: (lastValue, mutationEvent) => new Date().toISOString()
 });
 
 // Store complex object
 const activeState = StateNode.create({
     name: 'active',
-    computeValue: () => ({
+    computeValue: (lastValue, mutationEvent) => ({
         activatedAt: Math.floor(Date.now()/1000),  // In seconds
         status: 'active',
         metadata: { source: 'manual' }
@@ -1602,7 +1881,7 @@ const activeState = StateNode.create({
 // Increment value based on previous state
 const incrementingState = StateNode.create({
     name: 'incrementing',
-    computeValue: (lastValue) => {
+    computeValue: (lastValue, mutationEvent) => {
         const baseValue = typeof lastValue === 'number' ? lastValue : 0;
         return baseValue + 1;
     }
@@ -1611,7 +1890,7 @@ const incrementingState = StateNode.create({
 // Preserve previous value
 const idleState = StateNode.create({
     name: 'idle',
-    computeValue: (lastValue) => {
+    computeValue: (lastValue, mutationEvent) => {
         return typeof lastValue === 'number' ? lastValue : 0;
     }
 });
@@ -1619,7 +1898,7 @@ const idleState = StateNode.create({
 // Return null to delete (for entity/relation state machines)
 const deletedState = StateNode.create({
     name: 'deleted',
-    computeValue: () => null
+    computeValue: (lastValue, mutationEvent) => null
 });
 
 // Async computeValue - fetch data from database
@@ -1644,7 +1923,7 @@ const enrichedState = StateNode.create({
 // Async computeValue - external API call
 const verifiedState = StateNode.create({
     name: 'verified',
-    computeValue: async (lastValue) => {
+    computeValue: async (lastValue, mutationEvent) => {
         // Simulate external verification
         const verificationResult = await someExternalAPI.verify(lastValue.data);
         
@@ -1660,9 +1939,9 @@ const verifiedState = StateNode.create({
 // Using event parameter - access user information
 const approvedState = StateNode.create({
     name: 'approved',
-    computeValue: (lastValue, event) => {
+    computeValue: (lastValue, mutationEvent) => {
         // Access user who triggered the approval
-        const approver = event?.user?.name || 'system';
+        const approver = mutationEvent?.record?.user?.name || 'system';
         return {
             status: 'approved',
             approvedAt: Math.floor(Date.now()/1000),  // In seconds
@@ -1674,14 +1953,14 @@ const approvedState = StateNode.create({
 // Using event parameter - access payload data
 const updatedState = StateNode.create({
     name: 'updated',
-    computeValue: (lastValue, event) => {
+    computeValue: (lastValue, mutationEvent) => {
         // Merge payload data with existing value
-        if (event?.payload) {
+        if (mutationEvent?.record?.payload) {
             return {
                 ...lastValue,
-                ...event.payload.updates,
+                ...mutationEvent.record.payload.updates,
                 lastModifiedAt: Math.floor(Date.now()/1000),  // In seconds
-                lastModifiedBy: event.user?.id
+                lastModifiedBy: mutationEvent.record.user?.id
             };
         }
         return lastValue;
@@ -1691,15 +1970,15 @@ const updatedState = StateNode.create({
 // Using event parameter - conditional logic based on interaction
 const reviewedState = StateNode.create({
     name: 'reviewed',
-    computeValue: (lastValue, event) => {
+    computeValue: (lastValue, mutationEvent) => {
         // Different behavior based on which interaction triggered the transition
-        if (event?.interactionName === 'approve') {
+        if (mutationEvent?.record?.interactionName === 'approve') {
             return { status: 'approved', reviewedAt: Math.floor(Date.now()/1000) };  // In seconds
-        } else if (event?.interactionName === 'reject') {
+        } else if (mutationEvent?.record?.interactionName === 'reject') {
             return { 
                 status: 'rejected', 
                 reviewedAt: Math.floor(Date.now()/1000),  // In seconds
-                reason: event.payload?.reason || 'No reason provided'
+                reason: mutationEvent.record.payload?.reason || 'No reason provided'
             };
         }
         return { status: 'pending_review' };
@@ -1713,31 +1992,55 @@ StateNodes with `computeValue` are used in StateMachine to compute property valu
 
 ```typescript
 // Counter that increments on interaction
+const idleState = StateNode.create({ 
+    name: 'idle', 
+    computeValue: (lastValue, mutationEvent) => lastValue || 0 
+});
+const incrementingState = StateNode.create({ 
+    name: 'incrementing', 
+    computeValue: (lastValue, mutationEvent) => (lastValue || 0) + 1 
+});
+
 const CounterStateMachine = StateMachine.create({
-    states: [
-        StateNode.create({ 
-            name: 'idle', 
-            computeValue: (lastValue) => lastValue || 0 
-        }),
-        StateNode.create({ 
-            name: 'incrementing', 
-            computeValue: (lastValue) => (lastValue || 0) + 1 
+    states: [idleState, incrementingState],
+    transfers: [
+        StateTransfer.create({
+            trigger: {
+                recordName: InteractionEventEntity.name,
+                record: {
+                    interactionName: IncrementInteraction.name
+                }
+            },
+            current: idleState,
+            next: incrementingState,
+            computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.counterId })
         })
     ],
-    transfers: [/* ... */],
     defaultState: idleState
 });
 
 // Timestamp tracking
+const pendingState = StateNode.create({ name: 'pending' });
+const processedState = StateNode.create({ 
+    name: 'processed', 
+    computeValue: (lastValue, mutationEvent) => new Date().toISOString() 
+});
+
 const ProcessingStateMachine = StateMachine.create({
-    states: [
-        StateNode.create({ name: 'pending' }),
-        StateNode.create({ 
-            name: 'processed', 
-            computeValue: () => new Date().toISOString() 
+    states: [pendingState, processedState],
+    transfers: [
+        StateTransfer.create({
+            trigger: {
+                recordName: InteractionEventEntity.name,
+                record: {
+                    interactionName: ProcessInteraction.name
+                }
+            },
+            current: pendingState,
+            next: processedState,
+            computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.itemId })
         })
     ],
-    transfers: [/* ... */],
     defaultState: pendingState
 });
 
@@ -1764,7 +2067,7 @@ StateTransfer.create(config: StateTransferConfig): StateTransferInstance
 ```
 
 **Parameters**
-- `config.trigger` (Interaction, required): The Interaction instance that triggers this state transfer. Must be a reference to an Interaction created with `Interaction.create()`
+- `config.trigger` (RecordMutationEventPattern, required): A partial pattern to match against RecordMutationEvent. Supports deep partial matching of event properties.
 - `config.current` (StateNode, required): Current state node
 - `config.next` (StateNode, required): Next state node
 - `config.computeTarget` (function, optional): Function to compute which records should undergo this state transition. Returns the target record(s) that should be affected by this state change.
@@ -1785,37 +2088,83 @@ The `computeTarget` function determines which specific records should transition
   - Async: `async function(this: Controller, event: InteractionEvent) => TargetRecord`
 - **Event Parameter**: Contains interaction details including `event.payload` with the interaction's payload data
 
+**Trigger Pattern**
+
+The `trigger` parameter now accepts a RecordMutationEventPattern that allows deep partial matching:
+
+```typescript
+// Match interaction events by name
+trigger: {
+    recordName: InteractionEventEntity.name,  // Use the constant, not hardcoded string
+    record: {
+        interactionName: 'approve'  // Or better: ApproveInteraction.name
+    }
+}
+
+// Match data mutation events
+trigger: {
+    recordName: 'User',
+    type: 'update'  // Match only update events
+}
+
+// Match with complex patterns
+trigger: {
+    recordName: InteractionEventEntity.name,
+    record: {
+        interactionName: 'updateStatus',
+        payload: {
+            status: 'active'  // Only trigger when status is set to 'active'
+        }
+    }
+}
+```
+
 **Examples**
 ```typescript
 // Simple state transfer (no computeTarget needed for global state)
 const approveTransfer = StateTransfer.create({
-    trigger: ApproveInteraction,
+    trigger: {
+        recordName: InteractionEventEntity.name,
+        record: {
+            interactionName: ApproveInteraction.name
+        }
+    },
     current: pendingState,
     next: approvedState
 });
 
 // Entity state transfer - specify which entity to update
 const incrementTransfer = StateTransfer.create({
-    trigger: IncrementInteraction,
+    trigger: {
+        recordName: InteractionEventEntity.name,
+        record: {
+            interactionName: IncrementInteraction.name
+        }
+    },
     current: idleState,
     next: incrementingState,
-    computeTarget: (event) => {
+    computeTarget: (mutationEvent) => {
         // Return the counter entity that should transition states
-        return { id: event.payload.counter.id };
+        return { id: mutationEvent.record.payload.counter.id };
     }
 });
 
 // Relation state transfer - create new relation
 const assignReviewerTransfer = StateTransfer.create({
-    trigger: AssignReviewerInteraction,
+    trigger: {
+        recordName: InteractionEventEntity.name,
+        record: {
+            interactionName: AssignReviewerInteraction.name
+        }
+    },
     current: unassignedState,
     next: assignedState,
-    computeTarget: async function(this: Controller, event) {
+    computeTarget: async function(this: Controller, mutationEvent) {
         // Find the request entity
         const request = await this.system.storage.findOne('Request', 
             this.globals.MatchExp.atom({
                 key: 'id',
-                value: ['=', event.payload.requestId]
+                value: ['=', mutationEvent.record.payload.requestId]
             }),
             undefined,
             ['id']
@@ -1824,53 +2173,51 @@ const assignReviewerTransfer = StateTransfer.create({
         // Return source and target to create/update relation
         return {
             source: request,  // Can be {id: '...'} or full entity
-            target: event.payload.reviewer  // From payload
+            target: mutationEvent.record.payload.reviewer  // From payload
         };
     }
 });
 
-// Relation state transfer - simple source/target
-const createFriendshipTransfer = StateTransfer.create({
-    trigger: AddFriendInteraction,
-    current: notFriendsState,
-    next: friendsState,
-    computeTarget: (event) => ({
-        source: event.user,  // The user initiating the friendship
-        target: { id: event.payload.friendId }  // The friend being added
-    })
+// Trigger on specific payload values
+const publishTransfer = StateTransfer.create({
+    trigger: {
+        recordName: InteractionEventEntity.name,
+        record: {
+            interactionName: UpdateStatusInteraction.name,
+            payload: {
+                newStatus: 'published'  // Only trigger when status changes to 'published'
+            }
+        }
+    },
+    current: draftState,
+    next: publishedState,
+    computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.documentId })
 });
 
-// Relation state transfer - existing relation
-const updateRelationTransfer = StateTransfer.create({
-    trigger: UpdateStatusInteraction,
-    current: activeState,
+// Trigger on data mutations (non-interaction events)
+const dataUpdateTransfer = StateTransfer.create({
+    trigger: {
+        recordName: 'Order',
+        type: 'update'  // Only trigger on Order updates
+    },
+    current: processingState,
     next: updatedState,
-    computeTarget: async function(this: Controller, event) {
-        // Find existing relation
-        const relation = await this.system.storage.findOneRelationByName(UserProjectRelation.name,
-            this.globals.MatchExp.atom({
-                key: 'source.id',
-                value: ['=', event.user.id]
-            }).and({
-                key: 'target.id', 
-                value: ['=', event.payload.projectId]
-            }),
-            undefined,
-            ['id']
-        );
-        
-        return relation;  // Return existing relation by id
-    }
+    computeTarget: (mutationEvent) => ({ id: mutationEvent.record.id })
 });
 
 // Multiple targets - return array
 const bulkApproveTransfer = StateTransfer.create({
-    trigger: BulkApproveInteraction,
+    trigger: {
+        recordName: InteractionEventEntity.name,
+        record: {
+            interactionName: BulkApproveInteraction.name
+        }
+    },
     current: pendingState,
     next: approvedState,
-    computeTarget: (event) => {
+    computeTarget: (mutationEvent) => {
         // Return multiple entities to transition
-        return event.payload.items.map(item => ({ id: item.id }));
+        return mutationEvent.record.payload.items.map(item => ({ id: item.id }));
     }
 });
 ```
@@ -2090,15 +2437,26 @@ const UserPostRelation = Relation.create({
   source: User,
   target: Post,
   computation: Transform.create({
-    record: InteractionEventEntity,
-    callback: (event) => {
+    eventDeps: {
+      PostInteraction: {
+        recordName: InteractionEventEntity.name,
+        type: 'create'
+      }
+    },
+    callback: async function(this: Controller, mutationEvent) {
+      const event = mutationEvent.record;
       if (event.interactionName === 'CreatePost') {
+        // Use Controller to validate and enhance data
+        const now = Math.floor(Date.now() / 1000);
+        
         // This is where the actual creation logic is
         return {
           source: event.user.id,
           target: {
             title: event.payload.title,
-            content: event.payload.content
+            content: event.payload.content,
+            createdAt: now,
+            updatedAt: now
           }
         };
       }
@@ -2535,6 +2893,50 @@ interface System {
 
 Storage layer interface providing data persistence functionality.
 
+**Interface Definition**
+```typescript
+interface Storage {
+    // Entity mapping
+    map: any
+    
+    // Transaction operations
+    beginTransaction: (transactionName?: string) => Promise<any>
+    commitTransaction: (transactionName?: string) => Promise<any>
+    rollbackTransaction: (transactionName?: string) => Promise<any>
+    
+    // Dictionary-specific API
+    dict: {
+        get: (key: string) => Promise<any>
+        set: (key: string, value: any) => Promise<void>
+    }
+    
+    // General KV storage
+    get: (itemName: string, id: string, initialValue?: any) => Promise<any>
+    set: (itemName: string, id: string, value: any, events?: RecordMutationEvent[]) => Promise<any>
+    
+    // Entity/Relation operations
+    setup: (entities: EntityInstance[], relations: RelationInstance[], createTables?: boolean) => any
+    findOne: (entityName: string, ...args: any[]) => Promise<any>
+    find: (entityName: string, ...args: any[]) => Promise<any[]>
+    create: (entityName: string, data: any, events?: RecordMutationEvent[]) => Promise<any>
+    update: (entityName: string, ...args: any[]) => Promise<any>
+    delete: (entityName: string, data: any, events?: RecordMutationEvent[]) => Promise<any>
+    
+    // Relation-specific operations
+    findOneRelationByName: (relationName: string, ...args: any[]) => Promise<any>
+    findRelationByName: (relationName: string, ...args: any[]) => Promise<any>
+    updateRelationByName: (relationName: string, matchExpressionData: any, rawData: any, events?: RecordMutationEvent[]) => Promise<any>
+    removeRelationByName: (relationName: string, matchExpressionData: any, events?: RecordMutationEvent[]) => Promise<any>
+    addRelationByNameById: (relationName: string, sourceEntityId: string, targetEntityId: string, rawData?: any, events?: RecordMutationEvent[]) => Promise<any>
+    
+    // Utility methods
+    getRelationName: (entityName: string, attributeName: string) => string
+    getEntityName: (entityName: string, attributeName: string) => string
+    listen: (callback: RecordMutationCallback) => void
+    destroy: () => void
+}
+```
+
 **Main Methods**
 
 #### Transaction Operations
@@ -2938,10 +3340,43 @@ await storage.removeRelationByName('UserPostRelation',  // Don't hardcode!
 )
 ```
 
+#### Dictionary Operations
+
+**dict.get(key: string)**
+Get value from Dictionary storage.
+
+```typescript
+// Get dictionary value
+const userCount = await storage.dict.get('userCount')
+
+// Returns undefined if key doesn't exist
+const config = await storage.dict.get('systemConfig')
+if (config === undefined) {
+  // Handle missing value
+}
+```
+
+**dict.set(key: string, value: any)**
+Set value in Dictionary storage.
+
+```typescript
+// Set dictionary value
+await storage.dict.set('userCount', 100)
+
+// Store complex objects
+await storage.dict.set('systemConfig', {
+  maxUsers: 1000,
+  maintenanceMode: false,
+  features: ['chat', 'notifications']
+})
+```
+
+**Note**: The Dictionary API is specifically designed for storing global state values that are defined as Dictionary instances in the system. It provides a cleaner, more focused API compared to the general KV storage operations.
+
 #### KV Storage Operations
 
 **get(itemName: string, id: string, initialValue?: any)**
-Get value from key-value storage.
+Get value from general key-value storage.
 
 ```typescript
 // Get value with default
@@ -2949,7 +3384,7 @@ const maxUsers = await storage.get('config', 'maxUsers', 100)
 ```
 
 **set(itemName: string, id: string, value: any, events?: RecordMutationEvent[])**
-Set value in key-value storage.
+Set value in general key-value storage.
 
 ```typescript
 // Set configuration value
@@ -2963,6 +3398,8 @@ await storage.set('cache', 'userPreferences', {
 })
 ```
 
+**Note**: The general KV storage operations (`get`/`set`) are for arbitrary key-value pairs. For Dictionary entities specifically, prefer using the `dict` API.
+
 #### Utility Methods
 
 **getRelationName(entityName: string, attributeName: string)**