interaqt 0.4.0 → 0.4.2

package/agent/.claude/agents/code-generation-handler.md

@@ -152,7 +152,7 @@ git commit -m "feat: Task 3.1.2 - Complete entity and relation implementation"
 - Clear next step
 
 
-- [ ] Generate all interactions based on `docs/interaction-design.md`. **DO NOT define any conditions yet** - we will add permissions and business rules later in Task 3.2. No `condition` parameter in Interaction.create()
+- [ ] Generate all interactions based on `requirements/interaction-designs.json`. **DO NOT define any conditions yet** - we will add permissions and business rules later in Task 3.2. No `condition` parameter in Interaction.create()
 - [ ] Start with simple payload-only interactions (no conditions initially)
 - [ ] Ensure all payloads match the documented fields
 - [ ] **Type Check**: Run `npm run check` to ensure TypeScript compilation passes
@@ -380,7 +380,7 @@ git commit -m "feat: Task 3.2.0 - Create permission test file"
 **📋 Create the Permission and Business Rules Implementation Plan:**
 
 - [ ] Create `docs/business-rules-and-permission-control-implementation-plan.json` based on:
-  - `docs/interaction-design.md` (Stage 2 requirements)
+  - `requirements/interactions-design.json` 
   - `requirements/interaction-matrix.md` (permission requirements)
   - `requirements/test-cases.md` (business rule scenarios)
 
@@ -511,7 +511,7 @@ git commit -m "feat: Task 3.2.2 - Complete progressive permission and business r
 }
 ```
 
-- [ ] All permissions from `docs/interaction-design.md` are implemented
+- [ ] All permissions from `requirements/interactions-design.json` are implemented
 - [ ] All business rules from requirements are implemented
 - [ ] Each rule has comprehensive test coverage (success and failure cases)
 - [ ] All type checks pass (`npm run check`)

package/agent/.claude/agents/computation-generation-handler.md

@@ -10,7 +10,12 @@ color: blue
 
 ## START: Select Next Uncompleted Item
 
-**📖 Reference:** `./agentspace/knowledge/generator/computation-implementation.md` - Detailed computation implementation patterns and examples
+**📖 Reference** 
+- `./backend/crud.example.ts` + `./tests/crud.example.test.ts` - Simple CRUD operations with state machines, relations, and permissions
+- `./backend/versionControl.example.ts` + `./tests/versionControl.example.test.ts` - Version control with soft delete pattern
+- `./backend/versionControlHardDelete.example.ts` + `./tests/versionControlHardDelete.example.test.ts` - Version control with hard delete pattern
+- `./agentspace/knowledge/generator/computation-implementation.md` - Detailed computation implementation patterns and examples
+
 
 **🔴 CRITICAL: Implement ONLY ONE computation per session, then STOP and wait for user confirmation.**
 
@@ -54,6 +59,13 @@ color: blue
 1. **Implement the Computation** (following API Reference)
    - **📖 MANDATORY FIRST STEP: Completely read `./agentspace/knowledge/generator/api-reference.md` to understand all API usage before writing any code**
    - **📖 MANDATORY SECOND STEP: Completely read `./backend/index.ts` to understand all existing implementations from previous tasks**
+   - **📖 MANDATORY THIRD STEP: Study the reference example files above to understand the standard code structure and computation patterns**
+   - **🔴 CRITICAL: Check for existing computations** - If the target entity/relation already has computation code:
+     - **NEVER overwrite** existing computation logic
+     - **ADD branch logic** to handle the new interaction/scenario within existing Transform callback
+     - **PRESERVE all existing branches** to ensure previous test cases continue to pass
+     - Example: Add `else if` conditions or extend existing conditions in Transform callback
+   - **⚠️ Regression Prevention**: All previous tests must continue passing after adding new computation branches
    - **🔴 SPECIAL CASE 1: `_parent:[parent]` notation**
      - If the computation name contains `_parent:[parent]` (e.g., `_parent:[User]`), this means:
        - You should modify the PARENT entity's computation, not the current entity
@@ -166,6 +178,7 @@ color: blue
 4. **Write Test Implementation**
    - Add test to `tests/basic.test.ts` in 'Basic Functionality' describe group
    - Follow the test plan created above
+   - **📖 Reference the example test files above for testing patterns and structure**
    - For StateMachine computations, test ALL StateTransfer transitions
    - Test all CRUD operations the computation supports
    

package/agent/.claude/agents/implement-design-handler.md

@@ -51,7 +51,7 @@ You are a honest software expert with the following capabilities:
 }
 ```
 
-## Task 2.2: Interaction Analysis
+## Task 2.2: Computation Analysis
 
 **🔄 Update `docs/STATUS.json`:**
 ```json
@@ -60,75 +60,6 @@ You are a honest software expert with the following capabilities:
   "completed": false
 }
 ```
-**📖 MUST READ: `./agentspace/knowledge/generator/basic-interaction-generation.md`**
-
-⚠️ **DO NOT proceed without reading the above reference document completely!**
-
-**Create `docs/interaction-design.md` documenting:**
-
-- [ ] All interactions identified from use cases
-- [ ] For each interaction:
-  - Name and purpose
-  - Required payload fields
-  - Which entities/relations it affects
-  - Expected outcomes
-  - Permission requirements (for Stage 2)
-  - Business rules (for Stage 2)
-- [ ] **IMPORTANT**: Design interactions for core business logic first:
-  - Basic CRUD operations
-  - State transitions
-  - Relationship management
-- [ ] **Document but don't implement yet**:
-  - Permission checks (role-based access control)
-  - Business rule validations (e.g., quantity limits, state checks, time restrictions)
-  - Complex data validations beyond basic field requirements
-
-**Example structure:**
-```markdown
-# Interaction Design
-
-## CreateDormitory
-- **Purpose**: Create a new dormitory
-- **Payload**:
-  - name: string (required)
-  - capacity: number (required, 4-6)
-- **Effects**:
-  - Creates new Dormitory entity
-  - Initializes with empty beds
-- **Stage 2 - Permissions**: Only admin can create
-- **Stage 2 - Business Rules**: Capacity must be 4-6
-
-## AssignUserToDormitory
-- **Purpose**: Assign a student to a dormitory
-- **Payload**:
-  - userId: string
-  - dormitoryId: string
-- **Effects**:
-  - Creates UserDormitoryRelation
-  - Updates dormitory occupancy count
-- **Stage 2 - Permissions**: Admin or dormHead of target dormitory
-- **Stage 2 - Business Rules**: 
-  - User must not already be assigned
-  - Dormitory must have available capacity
-```
-
-**✅ END Task 2.2: Update `docs/STATUS.json`:**
-```json
-{
-  "currentTask": "Task 2.2",
-  "completed": true
-}
-```
-
-## Task 2.3: Computation Analysis
-
-**🔄 Update `docs/STATUS.json`:**
-```json
-{
-  "currentTask": "Task 2.3",
-  "completed": false
-}
-```
 **📖 PRIMARY GUIDE: `./agentspace/knowledge/generator/computation-analysis.md`**
 **📖 REFERENCE ONLY: `./agentspace/knowledge/generator/computation-implementation.md`**
 
@@ -138,7 +69,7 @@ You are a honest software expert with the following capabilities:
 1. **FIRST**: Read and understand `computation-analysis.md` completely
 2. **USE PREVIOUS OUTPUTS**: Base your analysis on:
    - `docs/data-design.json` (from Task 2.1)
-   - `docs/interaction-design.md` (from Task 2.2)
+   - `requirements/interactions-design.json`
 3. **ANALYZE**: For EVERY entity and EVERY property, follow the step-by-step analysis process
 4. **DOCUMENT**: Create `docs/computation-analysis.json` documenting your analysis for each entity/property
 5. **REFERENCE**: Use `./agentspace/knowledge/generator/computation-implementation.md` as a reference for syntax and examples
@@ -161,7 +92,6 @@ You are a honest software expert with the following capabilities:
   "completed": true,
   "completedItems": [
     "data-design.json created",
-    "interaction-design.md created",
     "computation-analysis.json created"
   ]
 }

package/agent/.claude/agents/requirements-analysis-handler.md

@@ -624,11 +624,57 @@ git commit -m "feat: Task 1.3 - Complete data concept extraction"
     "role": "Actor role",
     "action": "Action name",
     "payload": "Input data (optional)",
-    "data": "Data from current requirement (optional)",
+    "data": {
+        "creates": [
+            {
+                "target": "EntityOrRelationName",
+                "description": "Detailed description of how to create using what data",
+                "dependencies": ["Entity.property", "OtherEntity", "Relation.property"]
+            }
+        ],
+        "updates": [
+            {
+                "target": "EntityOrRelationName.propertyName",
+                "description": "Detailed description of how to update using what data",
+                "dependencies": ["Entity.property", "OtherEntity", "Relation.property"]
+            }
+        ],
+        "deletes": [
+            {
+                "target": "EntityOrRelationName",
+                "description": "Detailed description of how to delete and conditions",
+                "dependencies": ["Entity.property", "OtherEntity", "Relation.property"]
+            }
+        ],
+        "reads": ["Entity.property", "OtherEntity", "View"] // Only for read-type interactions
+    },
     "dataConstraints": "Inherited data constraints from fulfilled requirement"
 }
 ```
 
+### Data Field Specification Details
+
+The `data` field describes all data operations performed by the interaction:
+
+**For Write Operations (creates/updates/deletes):**
+- Each operation must specify:
+  - `target`: The entity/relation name (for creates/deletes) or entity/relation.property (for updates)
+  - `description`: Detailed explanation of how the operation is performed, including what data is used
+  - `dependencies`: Array of other entities/relations/properties that must be read to perform this operation
+- Dependencies should use dot notation for specific properties (e.g., `Book.availableCount`, `Reader.status`)
+- Dependencies include all data that needs to be read or validated during the operation
+
+**For Read Operations:**
+- `reads`: Array of entities/relations/properties that the user wants to retrieve through this interaction
+- Use dot notation for specific properties (e.g., `Book.title`, `Reader.name`)
+- Include views and aggregated values as needed
+- This represents the data the user expects to receive, not dependencies for internal operations
+
+**Important Notes:**
+- Write operations should NOT include a `reads` field - use `dependencies` within each operation instead
+- Read operations should ONLY have a `reads` field - no creates/updates/deletes
+- All referenced entities/relations must exist in the data concepts from Task 1.3
+
 ### Output: interactions-design.json
 
 Create `requirements/interactions-design.json`:
@@ -667,9 +713,20 @@ Create `requirements/interactions-design.json`:
           }
         },
         "data": {
-          "creates": ["BorrowRecord"],
-          "updates": ["Book.availableCount"],
-          "reads": ["Reader", "Book", "SystemConfig.maxBorrowLimit"]
+          "creates": [
+            {
+              "target": "BorrowRecord",
+              "description": "Create new borrow record using readerId, bookId, current timestamp as borrowDate, and calculated dueDate based on loan period from SystemConfig",
+              "dependencies": ["Reader", "Book", "SystemConfig.loanPeriod"]
+            }
+          ],
+          "updates": [
+            {
+              "target": "Book.availableCount",
+              "description": "Decrease available count by 1 after validating current count is greater than 0",
+              "dependencies": ["Book.availableCount"]
+            }
+          ]
         },
         "dataConstraints": [
           "Automatically decrease Book.availableCount by 1",
@@ -710,14 +767,64 @@ Create `requirements/interactions-design.json`:
           }
         },
         "data": {
-          "reads": ["Book", "Book.availableCount"],
-          "returns": "BookListView"
+          "reads": ["Book.title", "Book.author", "Book.availableCount", "Book.category"]
         },
         "dataConstraints": [
           "Only show books with availableCount > 0",
           "Exclude books marked as 'restricted' for regular readers"
         ]
       }
+    },
+    {
+      "id": "ReturnBook",
+      "fulfills_requirements": ["R102"],
+      "type": "update",
+      "specification": {
+        "role": "Librarian",
+        "action": "return",
+        "conditions": [
+          "BorrowRecord exists for the given readerId and bookId",
+          "BorrowRecord.returnDate is null"
+        ],
+        "payload": {
+          "readerId": {
+            "type": "string",
+            "description": "ID of the reader returning the book",
+            "required": true
+          },
+          "bookId": {
+            "type": "string",
+            "description": "ID of the book being returned",
+            "required": true
+          }
+        },
+        "data": {
+          "updates": [
+            {
+              "target": "BorrowRecord.returnDate",
+              "description": "Set return date to current timestamp for the specific borrow record matching readerId and bookId",
+              "dependencies": ["BorrowRecord.readerId", "BorrowRecord.bookId", "BorrowRecord.returnDate"]
+            },
+            {
+              "target": "Book.availableCount",
+              "description": "Increase available count by 1 after confirming the book return",
+              "dependencies": ["Book.availableCount", "BorrowRecord"]
+            }
+          ],
+          "deletes": [
+            {
+              "target": "BorrowRecord",
+              "description": "Delete the borrow record after successful return if hard deletion is enabled",
+              "dependencies": ["BorrowRecord.returnDate", "SystemConfig.enableHardDeletion"]
+            }
+          ]
+        },
+        "dataConstraints": [
+          "Only update return date if it's currently null",
+          "Increase Book.availableCount only after confirming valid return",
+          "Delete BorrowRecord only if system configuration allows hard deletion"
+        ]
+      }
     }
   ],
   "interaction_matrix": {

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:
@@ -92,12 +96,22 @@ Analyze the creation pattern:
 ```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"
@@ -109,8 +123,12 @@ Analyze the creation pattern:
 #### 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
@@ -169,8 +187,11 @@ 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
@@ -184,12 +205,23 @@ Similar to entities, analyze how relations are created:
 **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
@@ -333,12 +365,24 @@ Transform the analyzed data into the standard output format:
         "creation": {
           "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": {
@@ -368,12 +412,24 @@ Transform the analyzed data into the standard output format:
         "creation": {
           "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": {
@@ -470,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