interaqt 0.3.1 → 0.4.1

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
@@ -80,9 +92,7 @@ color: blue
    - **🔴 SPECIAL CASE 2: `_owner` notation**
      - If the computation decision is `_owner`, this means:
        - The property's value is fully controlled by its owner entity/relation's computation
-       - You should modify the OWNER entity/relation's creation or derivation logic, not add a separate property computation
-       - For `controlType: "creation-only"`: Add the property assignment logic in the entity/relation's creation Transform or StateMachine
-       - For `controlType: "derived-with-parent"`: The property is part of the parent's derivation computation
+       - You should modify the OWNER entity/relation's creation or derivation logic, not add a separate property computation. Add the property assignment logic in the entity/relation's creation Transform
        - Example: For a `createdAt` property with `_owner`, add timestamp assignment in the entity's Transform that creates it
    - Add computation code using assignment pattern at end of file:
      ```typescript
@@ -168,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

@@ -178,7 +178,7 @@ We focus on data-centric requirements. Human software usage delegates unsuitable
 
 **DO NOT create "automatic system" requirements.** Our framework is reactive - avoid designing autonomous system behaviors.
 
-**Transform "automatic" requirements into:**
+**Transform "non-data-reactive" requirements into:**
 
 1. **Reactive Data Requirements**: 
    - ❌ WRONG: "System automatically counts total books"
@@ -192,6 +192,10 @@ We focus on data-centric requirements. Human software usage delegates unsuitable
    - ❌ WRONG: "System automatically creates uniform record when employee is created"
    - ✅ CORRECT: "When creating employee, automatically create uniform record" (as data constraint)
 
+4. **Data Replacement Operations**:
+   - ❌ WRONG: "Replace old data with new data"
+   - ✅ CORRECT: "Create new data + Delete old data" (as two separate operations)
+
 **For unavoidable side-effect requirements** (e.g., "automatically send notification"):
 - Design the requirement but explicitly mark as **"Currently Not Supported"**
 - Document: "This requirement involves automatic side-effects which are not supported by the current reactive framework"
@@ -201,6 +205,7 @@ We focus on data-centric requirements. Human software usage delegates unsuitable
 - "Auto-send reminders" → "Reminder needed status is computed based on due date" + "Send reminder interaction"
 - "Auto-validate ISBN" → "Can only create books with valid ISBN format" (constraint)
 - "Auto-update inventory" → "Available count is computed based on total copies minus borrowed copies"
+- "Replace employee profile" → "Create new employee profile" + "Delete old employee profile" (two interactions)
 
 ### Step 1: Create Read Requirements from Goals
 
@@ -288,6 +293,20 @@ Create `requirements/requirements-analysis.json`:
         },
         "business_constraints": ["[Business rule 1]"],
         "data_constraints": ["[Data constraint 1]"]
+      },
+      {
+        "id": "R103",
+        "type": "delete",
+        "title": "[Requirement name]",
+        "parent": "R001",
+        "role": "[Role]",
+        "data": {
+          "type": "entity|relation",
+          "description": "[Data to delete]"
+        },
+        "deletion_type": "hard",
+        "deletion_rules": ["[Rule 1: e.g., Cannot delete if has active references]", "[Rule 2]"],
+        "business_constraints": ["[Business rule 1]"]
       }
     ],
     "from_R101": [
@@ -367,6 +386,11 @@ For each entity property:
 - **Computation Method**: For aggregated or computed values
 - **Data Dependencies**: For computed values, list dependencies
 
+**Hard Deletion Property**:
+- If delete requirements in Task 1.2 specify `"deletion_type": "hard"`
+- Add **HardDeletionProperty** to the entity/relation
+- Document deletion rules from requirements as property metadata
+
 ### Step 3: Relation Identification and Analysis
 
 **Relations are the ONLY way to connect entities** - they replace traditional foreign key patterns.
@@ -459,9 +483,17 @@ Create `requirements/data-concepts.json`:
             "description": "Total copies minus borrowed copies",
             "dependencies": ["BookCopy", "BorrowRecord"]
           }
+        },
+        {
+          "name": "_hardDeletion",
+          "type": "HardDeletionProperty",
+          "required": false,
+          "computed": false,
+          "deletion_rules": ["Cannot delete if has active borrow records", "Only administrators can delete"],
+          "source_requirement": "R103"
         }
       ],
-      "referenced_in": ["R001", "R101", "R201"],
+      "referenced_in": ["R001", "R101", "R103", "R201"],
       "note": "No authorId or publisherId - use BookAuthorRelation and BookPublisherRelation instead"
     },
     {
@@ -514,9 +546,17 @@ Create `requirements/data-concepts.json`:
           "name": "dueDate",
           "type": "date",
           "required": true
+        },
+        {
+          "name": "_hardDeletion",
+          "type": "HardDeletionProperty",
+          "required": false,
+          "computed": false,
+          "deletion_rules": ["Auto-delete when book is returned"],
+          "source_requirement": "R103"
         }
       ],
-      "lifecycle": "Created on borrow, updated on return",
+      "lifecycle": "Created on borrow, updated on return, deleted on return or book deletion",
       "referenced_in": ["R102", "R103"]
     },
     {
@@ -584,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`:
@@ -627,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",
@@ -670,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": {