interaqt 0.7.3 → 0.8.0

package/agent/.claude/settings.local.json

@@ -3,6 +3,9 @@
     "allow": [
       "Bash(npm run check)",
       "Bash(npm run test)",
+      "Read(STATUS.json)",
+      "Write(STATUS.json)",
+      "Edit(STATUS.json)",
       "Read(docs/**)",
       "Write(docs/**)",
       "Edit(docs/**)",
@@ -38,7 +41,39 @@
       "Bash(npm run reset)",
       "Bash(git restore backend/index.ts docs/computation-implementation-plan.json tests/basic.test.ts)",
       "Bash(npm run setup)",
-      "Bash(mv backend/index.template.ts backend/index.ts)"
+      "Bash(mv backend/index.template.ts backend/index.ts)",
+      "Bash(npm run build)",
+      "Bash(npm run dev:frontend)",
+      "Bash(npm run dev)",
+      "Bash(pkill:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vitest run:*)",
+      "Bash(npm run generate-frontend-api)",
+      "Bash(lsof:*)",
+      "Bash(curl:*)",
+      "Bash(test:*)",
+      "Bash(rg:*)",
+      "Bash(bash:*)",
+      "Bash(npm run type-check)",
+      "Bash(echo:*)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "Bash(sed:*)",
+      "Bash(awk:*)",
+      "Bash(tr:*)",
+      "Bash(cut:*)",
+      "Bash(sort:*)",
+      "Bash(uniq:*)",
+      "Bash(wc:*)",
+      "Bash(node:*)",
+      "WebSearch",
+      "WebFetch",
+      "Bash(if [ -z \"$VOLC_ACCESS_KEY_ID\" ])",
+      "Bash(then echo \"VOLC_ACCESS_KEY_ID is empty or not set\")",
+      "Bash(else echo \"VOLC_ACCESS_KEY_ID is set\")",
+      "Bash(fi:*)",
+      "Bash(if [ -z \"$VOLC_SECRET_ACCESS_KEY\" ])",
+      "Bash(then echo \"VOLC_SECRET_ACCESS_KEY is empty or not set\")"
     ],
     "deny": [],
     "ask": []

package/agent/CLAUDE.md

@@ -9,44 +9,123 @@ You are a honest software expert with the following capabilities:
 
 This guide provides a comprehensive step-by-step process for generating backend projects based on the interaqt framework.
 
-## CRITICAL: Progress Tracking with STATUS.json
-**Before starting ANY work, create `docs/STATUS.json` to track your progress:**
+## CRITICAL: Module Selection and Progress Tracking
+
+**🔴 STEP 0: Determine Current Working Module**
+
+Before starting any work, you MUST determine which module you're working on:
+
+1. **Check if user specified module in their prompt:**
+   - If YES: Write the module name to `.currentmodule` file (create if doesn't exist, overwrite entire content if exists)
+   - If NO: Continue to step 2
+
+2. **Check if `.currentmodule` file exists:**
+   - If YES: Read the module name from `.currentmodule`
+   - If NO: **STOP and ask user which module to work on**, then write the module name to `.currentmodule`
+
+3. **Set the module name for this session:** Use this module name for all subsequent operations
+
+**🔴 IMPORTANT: Module-Based Progress Tracking**
+
+Each module has its own progress tracking file:
+- **File location**: `docs/{module}.status.json` (where `{module}` is the current module name from `.currentmodule`)
+- **Before starting ANY work, read or create the module's status file:**
 
 ```json
 {
+  "module": "moduleName",
   "currentTask": "Task 1",
   "completed": false,
   "completedItems": []
 }
 ```
 
-** IMPORTANT: All tasks in this guide use a global unique numbering system (Task x.x.x.x). You can always find your current position by checking `docs/STATUS.json`, which tracks the exact Task number you were working on.**
+** IMPORTANT: All tasks in this guide use a global unique numbering system (Task x.x.x.x). You can always find your current position by checking `docs/{module}.status.json`, which tracks the exact Task number you were working on for that module.**
+
+**Task Numbering Hierarchy:**
+- **Top-level tasks**: Task 1, Task 2, Task 3 (major phases)
+- **Sub-tasks**: Task 1.1, Task 1.2, Task 1.3, Task 1.4, etc. (steps within a phase)
+- **Sub-sub-tasks**: Task 1.1.1, Task 3.1.4.3, etc. (nested steps)
+- **Rule**: Extract the first digit to determine which sub-agent handles the task
+
+** IMPORTANT: Module-Based Generation - All generated artifacts should be organized by module name read from `.currentmodule` file.**
 
 ## Task-Based Workflow System
 
 **📖 STEP 1: Check Current Progress**
-1. Read `docs/STATUS.json` to find your current task number (e.g., "Task 1", "Task 2", "Task 3")
-2. If the file doesn't exist, you should start with Task 1
+1. Read current module name from `.currentmodule` file
+2. Read `docs/{module}.status.json` to find your current task number (e.g., "Task 1.3", "Task 2.1", "Task 3.1.4.3")
+3. If the status file doesn't exist, you should start with Task 1
+
+**📖 STEP 2: Determine Sub-Agent from Task Number**
 
-**📖 STEP 2: Execute Corresponding Task**
-Based on the current task in `docs/STATUS.json`, use the appropriate sub-agent:
+**Extract top-level task (first digit) from currentTask to determine sub-agent:**
+
+Algorithm:
+```
+if currentTask starts with "Task 3.1.4.3": use computation-generation-handler
+else if currentTask starts with "Task 3.2.2": use permission-generation-handler
+else:
+  topLevel = first digit of currentTask
+  if topLevel == 1: use requirements-analysis-handler
+  if topLevel == 2: use implement-design-handler
+  if topLevel == 3: use code-generation-handler
+  if topLevel == 4: use implement-integration-handler
+```
 
-- **Task 1** → Use sub-agent `requirements-analysis-handler`
-- **Task 2** → Use sub-agent `implement-design-handler`
-- **Task 3** → Use sub-agent `code-generation-handler` (default for Task 3)
-  - **Exception: Task 3.1.4.3 - Computation Implementation Loop** → Use sub-agent `computation-generation-handler` during the implementation loop
-  - **Exception: Task 3.2.2 - Permission and Business Rule Implementation Loop** → Use sub-agent `permission-generation-handler` during the implementation loop
+Examples:
+- "Task 1.3" → Top-level is 1 → `requirements-analysis-handler`
+- "Task 2.5.2" → Top-level is 2 → `implement-design-handler`
+- "Task 3.1.4.3" → Exception → `computation-generation-handler`
+- "Task 3.2.2" → Exception → `permission-generation-handler`
+- "Task 3.x" (other) → Top-level is 3 → `code-generation-handler`
+- "Task 4.2" → Top-level is 4 → `implement-integration-handler`
+
+**📖 STEP 3: Execute Task with Sub-Agent**
+
+Sub-agent mapping:
+- **Task 1.x** (any sub-task of Task 1) → Use `requirements-analysis-handler`
+- **Task 2.x** (any sub-task of Task 2) → Use `implement-design-handler`
+- **Task 3.x** (any sub-task of Task 3) → Use `code-generation-handler`
+  - **Exception: Task 3.1.4.3.x** → Use `computation-generation-handler`
+  - **Exception: Task 3.2.2.x** → Use `permission-generation-handler`
+- **Task 4.x** (any sub-task of Task 4) → Use `implement-integration-handler`
+- **Error Checking** → Use `error-check-handler` when user requests error checking
+
+**CRITICAL - Task Continuation Logic:**
+- **Within same top-level**: Task 1.3 → Task 1.4 (stay in same sub-agent, do NOT jump to Task 2)
+- **Move to next top-level**: Only when status shows `"currentTask": "Task 1"` (no suffix) AND `"completed": true`, then move to Task 2
+- Each sub-agent handles its own task progression; only switch sub-agents when explicitly moving to a new top-level task
+
+**📋 STEP 4: Error Checking (Optional)**
+
+At any point in the workflow, you can use the `error-check-handler` sub-agent to perform comprehensive error checking:
+- Creates a detailed error report in `docs/{module}.error-check-report.md`
+- Checks all phases systematically (Module Setup, Requirements, Design, Code Generation, Frontend, Integration)
+- Identifies CRITICAL, HIGH PRIORITY, and MEDIUM PRIORITY errors
+- Provides specific file paths, line numbers, and suggested fixes
+- Does NOT fix errors - only finds and reports them
+
+**When to use error-check-handler:**
+- User explicitly requests error checking or quality assurance
+- Before marking any major phase complete (Task 1, Task 2, Task 3)
+- After completing implementation but before moving to production
+- When debugging issues or trying to understand problems
 
 **🔴 CRITICAL - AUTORUN EXECUTION CONTROL:**
 
-**For Top-Level Tasks (Task 1, Task 2, Task 3):**
-- **Check `SCHEDULE.json`**: When `"autorun": true`, automatically proceed to the next top-level task after completing the current one
-- **Example**: If Task 1 is completed and `autorun: true`, automatically start Task 2 without waiting for user instruction
+**For Top-Level Tasks (Task 1, Task 2, Task 3, Task 4):**
+- **IMPORTANT**: "Task 1 complete" means status shows `"currentTask": "Task 1"` (NOT "Task 1.x") AND `"completed": true`
+- **Task 1.3 is WITHIN Task 1**: Continue to Task 1.4 within same sub-agent; do NOT jump to Task 2
+- **Check `SCHEDULE.json`**: When `"autorun": true`, automatically proceed to next top-level task ONLY after current top-level shows as fully completed
+- **Example**: Status shows "Task 1.3" → Continue to Task 1.4 (stay in requirements-analysis-handler)
+- **Example**: Status shows "Task 1" with `completed: true` and `autorun: true` → Start Task 2 (switch to implement-design-handler)
+- **Example**: Status shows "Task 3" with `completed: true` and `autorun: true` → Start Task 4 (switch to implement-integration-handler)
 - **When `autorun` is false or doesn't exist**: Stop after completing each top-level task and wait for user's instruction to continue
 
 **For Loop Tasks Within Sub-Tasks:**
 - **Check `SCHEDULE.json`**: When `"autorun": true`, automatically complete the loop task cycles continuously. When `autorun` doesn't exist or is `false`, execute only one iteration of the loop task then stop and wait for user's manual instruction to proceed with the next iteration
-- **Loop Termination Condition**: Continue looping until the `completionCriteria` in `docs/STATUS.json` is fully satisfied
+- **Loop Termination Condition**: Continue looping until the `completionCriteria` in `docs/{module}.status.json` is fully satisfied
 - **Example**: For Task 3.1.4.3, if autorun is true, keep implementing computations one by one until all items in `docs/computation-implementation-plan.json` have `completed: true`
 - **Example**: For Task 3.2.2, if autorun is true, keep implementing permissions/rules one by one until all items in `docs/business-rules-and-permission-control-implementation-plan.json` have `completed: true`
 - **IMPORTANT**: Only after the completion criteria is met can you proceed to the next task

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

@@ -2,14 +2,20 @@
 
 ## Overview
 
-This guide helps you select the appropriate computation type for each entity, property, relation, and dictionary based on the structured information in `data-design.json` and `interaction-design.md`.
+This guide helps you select the appropriate computation type for each entity, property, relation, and dictionary based on the structured information in `requirements/{module}.data-design.json` and `requirements/{module}.interaction-design.md`.
+
+**IMPORTANT**: First read the current module name from `.currentmodule` file in project root, and use it to construct the file paths. For example, if `.currentmodule` contains `user-management`, then the paths would be:
+- `requirements/user-management.data-design.json`
+- `requirements/user-management.interaction-design.md`
 
 
 ## Input Files
 
 You will receive two input files:
-1. **data-design.json**: Contains structured data dependencies and lifecycle information
-2. **interaction-design.md**: Describes all interactions and their effects
+1. **requirements/{module}.data-design.json**: Contains structured data dependencies and lifecycle information
+2. **requirements/{module}.interaction-design.md**: Describes all interactions and their effects
+
+Note: Replace `{module}` with the value from `.currentmodule` file.
 
 ## Direct Mapping Rules
 
@@ -27,13 +33,17 @@ The `_owner` notation indicates that this property's value is fully controlled b
 
 Properties marked with `_owner` don't need separate computation control - their logic is embedded in the owner's creation or derivation process.
 
+Note: Properties with `controlType: "integration-result"` are NOT marked as `_owner` - they use `StateMachine` to observe and extract values from API Call entity updates.
+
 ### 1. Entity-Level Computations
 
 Look at the entity's `lifecycle.creation` and `lifecycle.deletion`:
 
 | Creation Type | Deletion | Computation Decision |
 |---------------|----------|---------------------|
+| `"integration-event"` | Always `canBeDeleted: false` | `None` - Entity is externally controlled by webhook/callback from external systems |
 | `"created-with-parent"` | Any | `_parent:[lifecycle.creation.parent]` (created by parent's computation) |
+| `"mutation-derived"` | Any | `Transform` from record mutation events (both interaction-created and entity-created produce mutations) |
 | `"interaction-created"` | `canBeDeleted: false` | `Transform` with `InteractionEventEntity` |
 | `"interaction-created"` | `canBeDeleted: true` with `hard-delete` | `Transform` + `HardDeletionProperty` with `StateMachine` |
 | `"interaction-created"` | `canBeDeleted: true` with `soft-delete` | `Transform` + status property with `StateMachine` |
@@ -61,11 +71,17 @@ Check `lifecycle.creation` and `lifecycle.deletion`:
 
 ### 3. Property-Level Computations
 
+**🔴 CRITICAL RULE: Properties can NEVER use Transform computation**
+- Transform is ONLY for Entity/Relation creation
+- Properties must use: _owner, StateMachine, computed, aggregations (Count/Sum/etc.), or Custom
+- Even if a property needs to respond to external events (like Integration Events), use StateMachine with appropriate triggers
+
 First check the property's `controlType`, then analyze dependencies if needed:
 
 | Control Type | Computation Decision |
 |--------------|---------------------|
 | `creation-only` | `_owner` - controlled by entity/relation creation |
+| `integration-result` | `StateMachine` - observes API Call entity updates, extracts result from response data |
 | `derived-with-parent` | `_owner` - controlled by parent's derivation |
 | `independent` | Further analysis needed (see below) |
 
@@ -75,29 +91,52 @@ Analyze the property's `dataDependencies`, `interactionDependencies`, and `compu
 
 | Condition | Computation Decision |
 |-----------|---------------------|
-| Has `interactionDependencies` that can modify it | `StateMachine` for state transitions or value updates |
-| Has `dataDependencies` with relations/entities | Aggregation computation based on `computationMethod` |
+| `calculationMethod` contains "sum of", "count of", "aggregate", or involves Record entities | `Custom` or aggregation (e.g., balance = sum(deposits) - sum(withdrawals)) |
+| Has `interactionDependencies` that can modify it | `StateMachine` for state transitions or value updates (even for external events) |
+| Has `dataDependencies` with relations/entities (including Integration Events) | `StateMachine` if triggered by events, otherwise aggregation computation |
 | `dataDependencies` = self properties only | `computed` function |
 | Complex calculation with multiple entities | `Custom` |
 | Only has `initialValue`, no dependencies | No computation (use `defaultValue`) |
 
+**Common Pattern - Integration Result Properties:**
+- **If `controlType: "integration-result"`** → **Always use `StateMachine`**
+- Pattern: Property computed from API Call entity's response data
+- Example: `Donation.voiceUrl` computed from `TTSAPICall.responseData`
+- Implementation:
+  - Trigger: Monitor API Call entity creation/update
+  - ComputeTarget: Find the business entity that needs the result
+  - ComputeValue: Extract value from API Call entity's response field
+
+**Common Pattern - Integration Event Updates:**
+- Property needs to update based on Integration Event (e.g., TTSEvent) → Use `StateMachine`
+- Set trigger to monitor the Integration Event Entity creation: `trigger: { recordName: 'TTSEvent', type: 'create' }`
+- Use `computeTarget` to find the target entity/relation to update
+- Use `computeValue` to extract and return the new value from the event
+
 #### Decision Priority (check in order):
 
 1. **Check `controlType` first**:
    - `creation-only` → **_owner** (property controlled by entity/relation creation)
+   - `integration-result` → **StateMachine** (observes API Call entity, extracts from response)
    - `derived-with-parent` → **_owner** (property controlled by parent derivation)
    - `independent` → Continue to step 2
 
-2. **If has `interactionDependencies` that can modify**:
+2. **Check `calculationMethod` for aggregate patterns**:
+   - Contains "sum of", "count of", "aggregate" keywords → `Custom` or aggregation
+   - Involves multiple Record entities (deposits/withdrawals) → `Custom` 
+   - Example: balance = sum(RechargeRecord) - sum(DonationRecord) → `Custom`
+   - If found, use `Custom` or aggregation, **skip step 3**
+
+3. **If has `interactionDependencies` that can modify**:
    - Property changes in response to interactions → `StateMachine`
    - For timestamps: Use StateMachine with `computeValue`
    - For status fields: Use StateMachine with StateNodes
 
-3. **If has `dataDependencies` (no interactions)**:
+4. **If has `dataDependencies` (no interactions)**:
    - Check `computationMethod` for aggregation type
    - Relations/entities involved → Use appropriate aggregation
 
-4. **If uses only own entity properties**:
+5. **If uses only own entity properties**:
    - Simple derivation → `computed` function
    - Better performance than Custom
 
@@ -123,32 +162,39 @@ Based on `computationMethod` description:
 ## Automated Decision Process
 
 ### Step 1: Parse Input Files
-Read `data-design.json` and extract:
+First, read the module name from `.currentmodule` file in project root to get the current module name.
+
+Then read `requirements/{module}.data-design.json` and extract:
 - Entity definitions with their properties and lifecycle (creation and deletion)
 - Relation definitions with their lifecycle
 - Dictionary definitions
 
 ### Step 2: Apply Mapping Rules
 For each element:
-1. Check lifecycle.creation.type and lifecycle.deletion for entities and relations
-2. For properties, check controlType first:
+1. **For entities**: Check in this priority order:
+   - First check if `isIntegrationEvent: true` → set computation to "None" (externally controlled)
+   - Then check if `isAPICallEntity: true` → set computation to "Transform" (mutation-derived pattern)
+   - Then check lifecycle.creation.type and lifecycle.deletion
+   - For entities that can be hard-deleted, use Transform + HardDeletionProperty with StateMachine
+2. **For relations**: Check lifecycle.creation.type and lifecycle.deletion
+   - For relations that can be hard-deleted, use Transform + HardDeletionProperty with StateMachine
+3. **For properties**: Check controlType first (PRIORITY ORDER):
    - If `creation-only` or `derived-with-parent` → use `_owner`
+   - **If `integration-result` → DIRECTLY use `StateMachine` (no further analysis)**
    - If `independent` → apply standard dependency analysis rules
-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
 
-Create `docs/computation-analysis.json` with this structure:
+Create `requirements/{module}.computation-analysis.json` (using the module name from `.currentmodule`) with this structure:
 
 ```json
 {
   "entities": [
     {
-      "name": "<from data-design.json>",
+      "name": "<from requirements/{module}.data-design.json>",
       "entityAnalysis": {
-        "purpose": "<from data-design.json>",
-        "lifecycle": "<directly copy from lifecycle field in data-design.json>",
+        "purpose": "<from requirements/{module}.data-design.json>",
+        "lifecycle": "<directly copy from lifecycle field in requirements/{module}.data-design.json>",
         "computationDecision": "<Transform/_parent:[ParentName]/None based on rules>",
         "reasoning": "<automated based on lifecycle and deletion capability>",
         "calculationMethod": "<from computationMethod>"
@@ -156,14 +202,14 @@ Create `docs/computation-analysis.json` with this structure:
       "propertyAnalysis": [
         {
           "propertyName": "<property name>",
-          "type": "<from data-design.json>",
-          "purpose": "<from data-design.json>",
-          "controlType": "<from data-design.json: creation-only/derived-with-parent/independent>",
+          "type": "<from requirements/{module}.data-design.json>",
+          "purpose": "<from requirements/{module}.data-design.json>",
+          "controlType": "<from requirements/{module}.data-design.json: creation-only/integration-result/derived-with-parent/independent>",
           "dataSource": "<from computationMethod>",
           "computationDecision": "<_owner/StateMachine/Count/etc. based on controlType and rules>",
           "reasoning": "<automated based on controlType and rules>",
           "dependencies": <convert dataDependencies to proper format>,
-          "interactionDependencies": <from data-design.json>,
+          "interactionDependencies": <from requirements/{module}.data-design.json>,
           "calculationMethod": "<from computationMethod>"
         }
       ]
@@ -171,10 +217,10 @@ Create `docs/computation-analysis.json` with this structure:
   ],
   "relations": [
     {
-      "name": "<from data-design.json>",
+      "name": "<from requirements/{module}.data-design.json>",
       "relationAnalysis": {
-        "purpose": "<from data-design.json>",
-        "lifecycle": "<directly copy from lifecycle field in data-design.json>",
+        "purpose": "<from requirements/{module}.data-design.json>",
+        "lifecycle": "<directly copy from lifecycle field in requirements/{module}.data-design.json>",
         "computationDecision": "<Transform/_parent:[ParentName] based on rules>",
         "reasoning": "<automated based on lifecycle>",
         "calculationMethod": "<from computationMethod>"
@@ -183,15 +229,15 @@ Create `docs/computation-analysis.json` with this structure:
   ],
   "dictionaries": [
     {
-      "name": "<from data-design.json>",
+      "name": "<from requirements/{module}.data-design.json>",
       "dictionaryAnalysis": {
-        "purpose": "<from data-design.json>",
-        "type": "<from data-design.json>",
+        "purpose": "<from requirements/{module}.data-design.json>",
+        "type": "<from requirements/{module}.data-design.json>",
         "collection": "<determine from type>",
         "computationDecision": "<apply dictionary rules>",
         "reasoning": "<automated based on computationMethod>",
         "dependencies": <format properly>,
-        "interactionDependencies": <from data-design.json>,
+        "interactionDependencies": <from requirements/{module}.data-design.json>,
         "calculationMethod": "<from computationMethod>"
       }
     }
@@ -218,12 +264,14 @@ Examples:
 
 ```
 1. Entity Lifecycle?
+   ├─ isIntegrationEvent: true? → None (externally controlled)
+   ├─ isAPICallEntity: true? → Transform (mutation-derived pattern)
    ├─ lifecycle.creation.type: "created-with-parent"? → _parent:[parent]
+   ├─ lifecycle.creation.type: "mutation-derived"? → Transform from record mutation event
    ├─ lifecycle.creation.type: "interaction-created" + canBeDeleted: true (hard)? → Transform + HardDeletionProperty with StateMachine
    ├─ 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]
@@ -231,11 +279,14 @@ Examples:
    ├─ Needs audit trail? → Transform + status StateMachine (soft delete)
    └─ Never deleted? → Transform (if interaction-created) or _parent:[parent]
 
-3. Property Value?
+3. Property Value? (🔴 NEVER Transform - Transform is ONLY for Entity/Relation)
    ├─ controlType: "creation-only"? → _owner (controlled by entity/relation)
+   ├─ controlType: "integration-result"? → StateMachine (observe API Call entity)
    ├─ controlType: "derived-with-parent"? → _owner (controlled by parent)
    ├─ controlType: "independent"?
+   │  ├─ calculationMethod has "sum of"/"count of"/"aggregate" or Record entities? → Custom or aggregation
    │  ├─ Has interactionDependencies that can modify? → StateMachine
+   │  ├─ Depends on Integration Event? → StateMachine with event trigger
    │  ├─ Has dataDependencies with relations? → Aggregation computation
    │  ├─ Only uses own properties? → computed
    │  └─ Complex with multiple entities? → Custom
@@ -255,11 +306,52 @@ Examples:
 - With defined transitions: Use StateMachine with StateNodes
 - Example: pending → approved/rejected
 
+### Integration Result Properties
+**🔴 DIRECT RULE: `controlType: "integration-result"` → Always `StateMachine`**
+
+Properties with `controlType: "integration-result"` are computed from external API/integration results:
+- **Pattern**: Extract values from API Call entity's response data
+- **Computation**: Always use `StateMachine`
+- **Trigger**: Observe API Call entity creation/update events
+- **Logic**: 
+  - Use `computeTarget` to find the business entity that owns this property
+  - Use `computeValue` to extract the result from API Call entity's response field
+  - Typically extract from the LATEST successful API Call (status='completed')
+
+**Example**:
+```json
+{
+  "propertyName": "voiceUrl",
+  "controlType": "integration-result",
+  "dataDependencies": ["TTSAPICall.responseData", "TTSAPICall.status"],
+  "computationDecision": "StateMachine",
+  "reasoning": "controlType is 'integration-result' - directly maps to StateMachine to observe API Call entity"
+}
+```
+
+**Implementation notes**:
+- Monitor related API Call entity (via relation) for updates
+- Extract result when API Call reaches completed status
+- Handle multiple API Call attempts (retries) by using the latest successful one
+
 ### Counts and Aggregations
 - Simple counts: Use `Count`
 - Sums: Use `Summation`
 - Calculated totals (price × quantity): Use `WeightedSummation`
 
+### Balance/Accumulation Properties
+**🔴 CRITICAL**: Properties that aggregate from transaction records should use `Custom`, NOT `StateMachine`
+- Pattern: `balance = sum(deposits) - sum(withdrawals)`
+- Examples:
+  - `UserGiftProfile.giftBalance = sum(RechargeRecord.amount) - sum(DonationRecord.giftAmount)`
+  - `Account.balance = sum(CreditRecord.amount) - sum(DebitRecord.amount)`
+  - `Inventory.stockLevel = sum(PurchaseOrder.quantity) - sum(SalesOrder.quantity)`
+- **How to identify**: 
+  - `calculationMethod` contains "sum of", "aggregate", "increased by", "decreased by"
+  - Involves multiple Record entities (entities ending in "Record", "Transaction", "Event")
+  - Even if has `interactionDependencies`, prioritize aggregation over StateMachine
+- Use `Custom` computation to aggregate from related records reactively
+
 ### Deletion Patterns
 
 #### For Entities:
@@ -278,23 +370,31 @@ Examples:
 ## Validation
 
 Before finalizing, verify:
-1. Every entity with `interactionDependencies` has appropriate computation:
+1. **🔴 CRITICAL**: NO property has `computationDecision: "Transform"` - Transform is ONLY for Entity/Relation
+2. Every entity with `isIntegrationEvent: true` has `computationDecision: "None"` or no computation
+3. Every entity with `isAPICallEntity: true` has `computationDecision: "Transform"`
+4. Every entity with `interactionDependencies` has appropriate computation:
    - If `canBeDeleted: true` with `hard-delete` → Must use Transform + HardDeletionProperty with StateMachine
-   - If `canBeDeleted: false` → Can use Transform (unless `created-with-parent`)
-2. Entities/relations with `lifecycle.creation.type: "created-with-parent/entity"` use `_parent:[ParentName]`
-3. Properties with `controlType: "creation-only"` or `"derived-with-parent"` have computation `_owner`
-4. Properties with `controlType: "independent"` are analyzed for appropriate computation
-5. Properties with modifying `interactionDependencies` use StateMachine (if `controlType: "independent"`)
-6. Properties with only `dataDependencies` use data-based computation (if `controlType: "independent"`)
-7. All entities or relations with `canBeDeleted:true` and `hard-delete` use Transform + HardDeletionProperty
-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`
+   - If `canBeDeleted: false` → Can use Transform (unless `created-with-parent` or `integration-event`)
+5. Entities/relations with `lifecycle.creation.type: "created-with-parent/entity"` use `_parent:[ParentName]`
+6. Properties with `controlType: "creation-only"` or `"derived-with-parent"` have computation `_owner`
+7. Properties with `controlType: "integration-result"` use `StateMachine` to observe API Call entities
+8. Properties with `controlType: "independent"` are analyzed for appropriate computation
+9. Properties with modifying `interactionDependencies` use StateMachine (if `controlType: "independent"`)
+10. Properties that depend on Integration Events use StateMachine with event triggers (NOT Transform)
+11. Properties with only `dataDependencies` use data-based computation (if `controlType: "independent"`)
+12. All entities or relations with `canBeDeleted:true` and `hard-delete` use Transform + HardDeletionProperty
+13. All dependencies are properly formatted with specific properties
+14. `InteractionEventEntity` is included when interactions are dependencies
+15. The parent name in `_parent:[ParentName]` matches `lifecycle.creation.parent`
 
 
 ## Implementation Checklist
 
-- [ ] Parse `data-design.json` completely
+- [ ] Read module name from `.currentmodule` file in project root
+- [ ] Parse `requirements/{module}.data-design.json` completely
+- [ ] Check for entities with `isIntegrationEvent: true` and set computation to "None"
+- [ ] Check for entities with `isAPICallEntity: true` and set computation to "Transform"
 - [ ] Apply mapping rules for every entity (check deletion capability)
 - [ ] Check `controlType` for every property first
 - [ ] Apply mapping rules for properties based on `controlType`
@@ -304,6 +404,7 @@ Before finalizing, verify:
 - [ ] Separate `dependencies` and `interactionDependencies`
 - [ ] Add `InteractionEventEntity` when needed
 - [ ] Verify properties with `controlType: "creation-only"` or `"derived-with-parent"` use `_owner`
+- [ ] Verify entities with `lifecycle.creation.type: "integration-event"` have no computation
 - [ ] 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`
+- [ ] Generate complete `requirements/{module}.computation-analysis.json`