interaqt 0.3.1 → 0.4.1

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

@@ -63,8 +63,12 @@ For **EACH entity** in data-concepts.json:
 Analyze `requirements/interactions-design.json` to identify how entities are created:
 
 **Step A: Find Creation Interactions**
-1. Search all interactions where the entity appears in `data.creates`
-2. List these as `creationInteractions` (use interaction **names**, not IDs)
+1. Search all interactions where the entity appears in `interactions.specification.data.creates`
+2. For each creation interaction, capture:
+   - Interaction name (not ID)
+   - Description from the creates entry
+   - Dependencies from the creates entry
+3. Store as `creationInteractions` with detailed information for each interaction
 
 **Step B: Determine Creation Type**
 Analyze the creation pattern:
@@ -81,24 +85,50 @@ 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
 // In interaction "CreateDormitory":
 "data": {
-  "creates": ["Dormitory", "Bed"]
-},
-"dataConstraints": [
-  "Automatically create individual bed entities for each bed"
-]
-// Result: Dormitory is interaction-created, Bed is created-with-parent (parent: Dormitory)
+  "creates": [
+    {
+      "target": "Dormitory",
+      "description": "Create new dormitory with basic info",
+      "dependencies": ["DormitoryValidation"]
+    },
+    {
+      "target": "Bed", 
+      "description": "Automatically create individual bed entities for each bed",
+      "dependencies": ["Dormitory"]
+    }
+  ]
+}
+// Result: 
+// Dormitory is interaction-created with creation details
+// Bed is created-with-parent (parent: Dormitory) with creation details
+
+// 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
 
 Search interactions for deletion operations:
-1. Find interactions where entity appears in `data.deletes` (record interaction **names**, not IDs)
-2. Determine deletion type:
+1. Find interactions where entity appears in `data.deletes`
+2. For each deletion interaction, capture:
+   - Interaction name (not ID)
+   - Description from the deletes entry
+   - Dependencies from the deletes entry
+3. Determine deletion type:
    - **hard-delete**: Entity removed from storage
    - **soft-delete**: Entity marked as deleted (status change)
    - **auto-delete**: Deleted when parent/dependency is deleted
@@ -157,23 +187,46 @@ Similar to entities, analyze how relations are created:
 
 **Find Creation Interactions**:
 1. Search for relation name in `data.creates`
-2. Analyze creation context
-3. Record interaction **names**, not IDs
+2. For each creation interaction, capture:
+   - Interaction name (not ID)
+   - Description from the creates entry
+   - Dependencies from the creates entry
+3. Analyze creation context
 
 **Determine Creation Type**:
 - **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
 // UserBedAssignment appears in:
-// "AssignUserToBed": "data": { "creates": ["UserBedAssignment"] }
-// Result: interaction-created
+// "AssignUserToBed": "data": { 
+//   "creates": [{
+//     "target": "UserBedAssignment",
+//     "description": "Create assignment between user and bed",
+//     "dependencies": ["User", "Bed", "AvailabilityCheck"]
+//   }]
+// }
+// Result: interaction-created with detailed creation info
 
 // If it appeared with entity creation:
-// "CreatePost": "data": { "creates": ["Post", "PostAuthorRelation"] }
-// Result: PostAuthorRelation is created-with-entity (Post)
+// "CreatePost": "data": { 
+//   "creates": [
+//     {"target": "Post", "description": "Create new post", "dependencies": ["User"]},
+//     {"target": "PostAuthorRelation", "description": "Link post to author", "dependencies": ["Post", "User"]}
+//   ]
+// }
+// Result: PostAuthorRelation is created-with-entity (Post) with creation details
+
+// 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,14 +363,26 @@ 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]"
+          "creationInteractions": [
+            {
+              "name": "[Interaction name]",
+              "description": "[Description from creates entry]",
+              "dependencies": "[Dependencies from creates entry]"
+            }
+          ]
         },
         "deletion": {
           "canBeDeleted": "[true/false based on Step 2.2]",
           "deletionType": "[soft-delete | hard-delete | auto-delete]",
-          "deletionInteractions": "[List from Step 2.2]"
+          "deletionInteractions": [
+            {
+              "name": "[Interaction name]",
+              "description": "[Description from deletes entry]",
+              "dependencies": "[Dependencies from deletes entry]"
+            }
+          ]
         }
       },
       "properties": {
@@ -345,14 +410,26 @@ 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]"
+          "creationInteractions": [
+            {
+              "name": "[Interaction name]",
+              "description": "[Description from creates entry]",
+              "dependencies": "[Dependencies from creates entry]"
+            }
+          ]
         },
         "deletion": {
           "canBeDeleted": "[Based on analysis]",
           "deletionType": "[Type identified]",
-          "deletionInteractions": "[List of interactions]"
+          "deletionInteractions": [
+            {
+              "name": "[Interaction name]",
+              "description": "[Description from deletes entry]",
+              "dependencies": "[Dependencies from deletes entry]"
+            }
+          ]
         }
       },
       "properties": {
@@ -449,6 +526,31 @@ Entities filtered from base entities:
 }
 ```
 
+### 5. Multiple Creation Interactions
+Entity created by different interactions with different logic:
+```json
+"Style": {
+  "lifecycle": {
+    "creation": {
+      "type": "interaction-created",
+      "parent": null,
+      "creationInteractions": [
+        {
+          "name": "CreateStyle",
+          "description": "Create new Style entity with provided data, automatically setting status to 'draft', generating slug if not provided, and setting timestamps",
+          "dependencies": ["SlugUniquenessCheck"]
+        },
+        {
+          "name": "RestoreToVersion", 
+          "description": "Recreate Style entities from version snapshot data",
+          "dependencies": ["StyleVersion.snapshotData"]
+        }
+      ]
+    }
+  }
+}
+```
+
 ## Validation Checklist
 
 - [ ] All entities from data-concepts.json are analyzed