interaqt 0.3.1 → 0.4.0

package/agent/agentspace/knowledge/generator/computation-analysis.md

@@ -134,7 +134,7 @@ For each element:
 2. For properties, check controlType first:
    - If `creation-only` or `derived-with-parent` → use `_owner`
    - If `independent` → apply standard dependency analysis rules
-3. Apply the appropriate rules based on creation type and deletion capability
+3. Apply the appropriate rules based on creation type
 4. For entities/relations that can be hard-deleted, use Transform + HardDeletionProperty with StateMachine
 
 ### Step 3: Generate Output Document
@@ -149,7 +149,7 @@ Create `docs/computation-analysis.json` with this structure:
       "entityAnalysis": {
         "purpose": "<from data-design.json>",
         "lifecycle": "<directly copy from lifecycle field in data-design.json>",
-        "computationDecision": "<Transform/StateMachine/_parent:[ParentName]/None based on rules>",
+        "computationDecision": "<Transform/_parent:[ParentName]/None based on rules>",
         "reasoning": "<automated based on lifecycle and deletion capability>",
         "calculationMethod": "<from computationMethod>"
       },
@@ -175,7 +175,7 @@ Create `docs/computation-analysis.json` with this structure:
       "relationAnalysis": {
         "purpose": "<from data-design.json>",
         "lifecycle": "<directly copy from lifecycle field in data-design.json>",
-        "computationDecision": "<Transform/_parent:[ParentName]/StateMachine based on rules>",
+        "computationDecision": "<Transform/_parent:[ParentName] based on rules>",
         "reasoning": "<automated based on lifecycle>",
         "calculationMethod": "<from computationMethod>"
       }
@@ -223,11 +223,12 @@ Examples:
    ├─ lifecycle.creation.type: "interaction-created" + canBeDeleted: true (soft)? → Transform + status StateMachine
    ├─ lifecycle.creation.type: "interaction-created" + canBeDeleted: false? → Transform with InteractionEventEntity
    └─ lifecycle.creation.type: "derived"? → Transform from source entity
+   └─ lifecycle.creation.type: "mutation-derived"? → Transform from record mutation event
    
 2. Relation Lifecycle?
    ├─ lifecycle.creation.type: "created-with-entity"? → _parent:[parent]
    ├─ Can be deleted? → Transform/parent + HardDeletionProperty with StateMachine
-   ├─ Needs audit trail? → Original computation + status StateMachine (soft delete)
+   ├─ Needs audit trail? → Transform + status StateMachine (soft delete)
    └─ Never deleted? → Transform (if interaction-created) or _parent:[parent]
 
 3. Property Value?
@@ -244,22 +245,6 @@ Examples:
    └─ Check computationMethod → Map to Count/Summation/Custom
 ```
 
-## Implementation Checklist
-
-- [ ] Parse `data-design.json` completely
-- [ ] Apply mapping rules for every entity (check deletion capability)
-- [ ] Check `controlType` for every property first
-- [ ] Apply mapping rules for properties based on `controlType`
-- [ ] Apply mapping rules for every relation
-- [ ] Apply mapping rules for every dictionary
-- [ ] Format all dependencies correctly
-- [ ] Separate `dependencies` and `interactionDependencies`
-- [ ] Add `InteractionEventEntity` when needed
-- [ ] Verify properties with `controlType: "creation-only"` or `"derived-with-parent"` use `_owner`
-- [ ] Verify Transform + HardDeletionProperty is used for deletable entities (hard-delete)
-- [ ] Verify Transform + HardDeletionProperty is used for deletable relations (hard-delete)
-- [ ] Generate complete `computation-analysis.json`
-
 ## Common Patterns
 
 ### Timestamps
@@ -305,3 +290,20 @@ Before finalizing, verify:
 8. All dependencies are properly formatted with specific properties
 9. `InteractionEventEntity` is included when interactions are dependencies
 10. The parent name in `_parent:[ParentName]` matches `lifecycle.creation.parent`
+
+
+## Implementation Checklist
+
+- [ ] Parse `data-design.json` completely
+- [ ] Apply mapping rules for every entity (check deletion capability)
+- [ ] Check `controlType` for every property first
+- [ ] Apply mapping rules for properties based on `controlType`
+- [ ] Apply mapping rules for every relation
+- [ ] Apply mapping rules for every dictionary
+- [ ] Format all dependencies correctly
+- [ ] Separate `dependencies` and `interactionDependencies`
+- [ ] Add `InteractionEventEntity` when needed
+- [ ] Verify properties with `controlType: "creation-only"` or `"derived-with-parent"` use `_owner`
+- [ ] Verify Transform + HardDeletionProperty is used for deletable entities (hard-delete)
+- [ ] Verify Transform + HardDeletionProperty is used for deletable relations (hard-delete)
+- [ ] Generate complete `computation-analysis.json`

package/agent/agentspace/knowledge/generator/computation-implementation.md

@@ -94,8 +94,14 @@ When using `InteractionEventEntity` as the Transform input source, understand th
      name: 'Style'
    });
    Style.computation = Transform.create({
-     record: InteractionEventEntity,
-     callback: function(event) {
+     eventDeps: {
+       StyleInteraction: {
+         recordName: InteractionEventEntity.name,
+         type: 'create'
+       }
+     },
+     callback: function(mutationEvent) {
+       const event = mutationEvent.record;
        if (event.interactionName === 'UpdateStyle') {
          // This will CREATE a new Style, not update existing!
          return { id: event.payload.id, ... }  // WRONG!
@@ -115,7 +121,7 @@ When using `InteractionEventEntity` as the Transform input source, understand th
          trigger: UpdateStyleInteraction,
          current: updatedState,
          next: updatedState,
-         computeTarget: (event) => ({ id: event.payload.id })
+         computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
        })
      ]
    });
@@ -133,7 +139,7 @@ When using `InteractionEventEntity` as the Transform input source, understand th
          trigger: DeleteStyleInteraction,
          current: activeState,
          next: deletedState,
-         computeTarget: (event) => ({ id: event.payload.id })
+         computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
        })
      ]
    });
@@ -179,8 +185,14 @@ export const Style = Entity.create({
 });
 // Transform in Entity's computation property
 Style.computation = Transform.create({
-  record: InteractionEventEntity,
-  callback: function(event) {
+  eventDeps: {
+    StyleInteraction: {
+      recordName: InteractionEventEntity.name,
+      type: 'create'
+    }
+  },
+  callback: function(mutationEvent) {
+    const event = mutationEvent.record;
     if (event.interactionName === 'CreateStyle') {
       return {
         label: event.payload.label,
@@ -238,8 +250,14 @@ export const OrderItemRelation = Relation.create({
 
 
 Order.computation = Transform.create({
-  record: InteractionEventEntity,
-  callback: function(event) {
+  eventDeps: {
+    OrderInteraction: {
+      recordName: InteractionEventEntity.name,
+      type: 'create'
+    }
+  },
+  callback: function(mutationEvent) {
+    const event = mutationEvent.record;
     if (event.interactionName === 'CreateOrder') {
       return {
         orderNumber: event.payload.orderNumber,
@@ -374,13 +392,13 @@ statusProperty.computation = StateMachine.create({
       current: draftState,
       next: activeState,
       trigger: PublishStyle,
-      computeTarget: (event) => ({ id: event.payload.id })
+      computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
     }),
     StateTransfer.create({
       current: activeState,
       next: offlineState,
       trigger: DeleteStyle,
-      computeTarget: (event) => ({ id: event.payload.id })
+      computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
     })
   ]
 });
@@ -404,7 +422,7 @@ const UpdateStyle = Interaction.create({
 // Define state node with computeValue
 const updatedState = StateNode.create({
   name: 'updated',
-  computeValue: () => Math.floor(Date.now()/1000)  // Returns timestamp in seconds when state is entered
+  computeValue: (lastValue, mutationEvent) => Math.floor(Date.now()/1000)  // Returns timestamp in seconds when state is entered
 });
 
 const updatedAtProperty = Property.create({
@@ -420,7 +438,7 @@ updatedAtProperty.computation = StateMachine.create({
       current: updatedState,
       next: updatedState,  // Self-loop to same state
       trigger: UpdateStyle,
-      computeTarget: (event) => ({ id: event.payload.id })
+      computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
     })
   ]
 });
@@ -428,7 +446,7 @@ updatedAtProperty.computation = StateMachine.create({
 
 #### StateMachine with Event Context in computeValue
 
-The `computeValue` function can access the interaction event as a second parameter, allowing you to use interaction context (user, payload) in value computation:
+The `computeValue` function can access the mutation event as a second parameter, allowing you to use interaction context (user, payload) from `mutationEvent.record` in value computation:
 
 ```typescript
 // Track who made changes and what was changed
@@ -448,21 +466,21 @@ const UpdateArticle = Interaction.create({
 // State node that captures user and payload information
 const modifiedState = StateNode.create({
   name: 'modified',
-  // computeValue receives (lastValue, event) parameters
-  computeValue: (lastValue, event) => {
+  // computeValue receives (lastValue, mutationEvent) parameters
+  computeValue: (lastValue, mutationEvent) => {
     // Access user who triggered the update
-    const modifier = event?.user?.name || event?.user?.id || 'anonymous';
+    const modifier = mutationEvent?.record?.user?.name || mutationEvent?.record?.user?.id || 'anonymous';
     
     // Access payload to see what was changed
     const changes = [];
-    if (event?.payload?.title) changes.push('title');
-    if (event?.payload?.content) changes.push('content');
+    if (mutationEvent?.record?.payload?.title) changes.push('title');
+    if (mutationEvent?.record?.payload?.content) changes.push('content');
     
     return {
       modifiedAt: Math.floor(Date.now()/1000),
       modifiedBy: modifier,
       changedFields: changes,
-      updateReason: event?.payload?.updateReason || 'No reason provided',
+      updateReason: mutationEvent?.record?.payload?.updateReason || 'No reason provided',
       // Preserve previous modification history
       previousModifications: lastValue?.previousModifications || []
     };
@@ -483,7 +501,7 @@ modificationInfoProperty.computation = StateMachine.create({
       current: modifiedState,
       next: modifiedState,
       trigger: UpdateArticle,
-      computeTarget: (event) => ({ id: event.payload.id })
+      computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
     })
   ]
 });
@@ -502,25 +520,25 @@ const ApproveRequest = Interaction.create({
 
 const approvedState = StateNode.create({
   name: 'approved',
-  computeValue: (lastValue, event) => {
+  computeValue: (lastValue, mutationEvent) => {
     // Capture complete approval context from event
     return {
       status: 'approved',
       approvedAt: Math.floor(Date.now()/1000),
       approvedBy: {
-        id: event?.user?.id,
-        name: event?.user?.name,
-        role: event?.user?.role
+        id: mutationEvent?.record?.user?.id,
+        name: mutationEvent?.record?.user?.name,
+        role: mutationEvent?.record?.user?.role
       },
-      approvalComments: event?.payload?.comments,
+      approvalComments: mutationEvent?.record?.payload?.comments,
       // Keep approval history
       approvalHistory: [
         ...(lastValue?.approvalHistory || []),
         {
           action: 'approved',
           timestamp: Math.floor(Date.now()/1000),
-          user: event?.user?.name || 'unknown',
-          comments: event?.payload?.comments
+          user: mutationEvent?.record?.user?.name || 'unknown',
+          comments: mutationEvent?.record?.payload?.comments
         }
       ]
     };
@@ -528,11 +546,11 @@ const approvedState = StateNode.create({
 });
 ```
 
-**Key Points about Event Parameter:**
-- The `event` parameter is optional and may be `undefined` during initial state setup
-- Contains the full interaction context: `user`, `payload`, `interactionName`, etc.
+**Key Points about MutationEvent Parameter:**
+- The `mutationEvent` parameter is optional and may be `undefined` during initial state setup
+- Access the interaction context through `mutationEvent.record`: `user`, `payload`, `interactionName`, etc.
 - Useful for audit trails, tracking who made changes, and capturing interaction-specific data
-- Always use optional chaining (`?.`) when accessing event properties as it may be undefined
+- Always use optional chaining (`?.`) when accessing mutationEvent properties as it may be undefined
 
 
 ### 3. Custom - Complete User Control (USE WITH CAUTION!)
@@ -747,8 +765,14 @@ export const Style = Entity.create({
   ]
 });
 Style.computation = Transform.create({
-  record: InteractionEventEntity,
-  callback: (event) => {
+  eventDeps: {
+    StyleInteraction: {
+      recordName: InteractionEventEntity.name,
+      type: 'create'
+    }
+  },
+  callback: (mutationEvent) => {
+    const event = mutationEvent.record;
     if (event.interactionName === 'CreateStyle') {
       return {
         label: event.payload.label,
@@ -780,7 +804,7 @@ export const UpdateStyle = Interaction.create({
 // Property with update tracking
 const updatedState = StateNode.create({
   name: 'updated',
-  computeValue: () => Math.floor(Date.now()/1000)
+  computeValue: (lastValue, mutationEvent) => Math.floor(Date.now()/1000)
 });
 
 const updatedAtProperty = Property.create({
@@ -795,7 +819,7 @@ updatedAtProperty.computation = StateMachine.create({
       current: updatedState,
       next: updatedState,
       trigger: UpdateStyle,
-      computeTarget: (event) => ({ id: event.payload.id })
+      computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
     })
   ]
 });
@@ -831,7 +855,7 @@ statusProperty.computation = StateMachine.create({
       current: activeState,
       next: offlineState,
       trigger: DeleteStyle,
-      computeTarget: (event) => ({ id: event.payload.id })
+      computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
     })
   ]
 });
@@ -888,7 +912,7 @@ Property.create({
 // ✅ CORRECT: Updated at - updates on changes (in seconds)
 const updatedState = StateNode.create({
   name: 'updated',
-  computeValue: () => Math.floor(Date.now()/1000)  // Always convert to seconds!
+  computeValue: (lastValue, mutationEvent) => Math.floor(Date.now()/1000)  // Always convert to seconds!
 });
 
 const updatedAtProperty = Property.create({
@@ -903,7 +927,7 @@ updatedAtProperty.computation = StateMachine.create({
       current: updatedState,
       next: updatedState,
       trigger: UpdateInteraction,
-      computeTarget: (event) => ({ id: event.payload.id })
+      computeTarget: (mutationEvent) => ({ id: mutationEvent.record.payload.id })
     })
   ]
 });

package/agent/agentspace/knowledge/generator/data-analysis.md

@@ -81,6 +81,12 @@ Analyze the creation pattern:
 - **derived**: Entity is filtered/computed from other entities
   - No interactions directly create it
   - Views in data-concepts.json are typically derived
+  
+- **mutation-derived**: Entity is created from record mutation events
+  - Not directly in any interaction's `data.creates`
+  - Created by reactive computations (e.g., Transform) responding to other entities' creation/update/deletion
+  - Check for descriptions mentioning "when X is created/updated/deleted, create Y"
+  - Often used for audit logs, history tracking, or event-driven workflows
 
 **Example Analysis**:
 ```json
@@ -92,6 +98,12 @@ Analyze the creation pattern:
   "Automatically create individual bed entities for each bed"
 ]
 // Result: Dormitory is interaction-created, Bed is created-with-parent (parent: Dormitory)
+
+// For mutation-derived entity (not in any interaction's creates):
+// In data-concepts.json: "UserActivityLog: Records all user actions"
+// In interactions: No interaction directly creates UserActivityLog
+// In descriptions: "Activity logs are automatically created when users perform actions"
+// Result: UserActivityLog is mutation-derived
 ```
 
 #### 2.2 Determine Deletion Pattern
@@ -164,6 +176,10 @@ Similar to entities, analyze how relations are created:
 - **interaction-created**: Relation created independently
 - **created-with-entity**: Created when source/target entity is created
 - **derived**: Computed from data conditions
+- **mutation-derived**: Created from record mutation events
+  - Not directly in any interaction's `data.creates`
+  - Created by reactive computations responding to entity/relation changes
+  - Common for maintaining referential integrity or creating audit trails
 
 **Example**:
 ```json
@@ -174,6 +190,11 @@ Similar to entities, analyze how relations are created:
 // If it appeared with entity creation:
 // "CreatePost": "data": { "creates": ["Post", "PostAuthorRelation"] }
 // Result: PostAuthorRelation is created-with-entity (Post)
+
+// For mutation-derived relation:
+// UserFollowRelation not in any interaction's creates
+// Description: "Automatically created when user likes multiple posts by same author"
+// Result: UserFollowRelation is mutation-derived
 ```
 
 ### Step 5: Transform Dictionaries to Analysis Format
@@ -310,7 +331,7 @@ Transform the analyzed data into the standard output format:
       "computationMethod": "[Creation pattern description]",
       "lifecycle": {
         "creation": {
-          "type": "[interaction-created | derived | created-with-parent]",
+          "type": "[interaction-created | derived | created-with-parent | mutation-derived]",
           "parent": "[Parent entity name if created-with-parent]",
           "creationInteractions": "[List from Step 2.1]"
         },
@@ -345,7 +366,7 @@ Transform the analyzed data into the standard output format:
       "computationMethod": "[From Step 4.2]",
       "lifecycle": {
         "creation": {
-          "type": "[From Step 4.2]",
+          "type": "[interaction-created | created-with-entity | derived | mutation-derived]",
           "parent": "[If created-with-entity]",
           "creationInteractions": "[From Step 4.2]"
         },