interaqt 0.8.2 → 0.8.4

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

@@ -162,27 +162,41 @@ git commit -m "feat: Task 3.1.2 - Complete entity and relation implementation"
 - [ ] Ensure all payloads match the documented fields
 - [ ] **🔴 CRITICAL: For query interactions (action: GetAction):**
   - **MUST declare `data` field** - specify the Entity or Relation to query
-  - **SHOULD declare `query` field** if there are predefined filters/fields (use Query.create with QueryItem)
-  - Example:
+  - **SHOULD declare `dataPolicy` field** if there are predefined filters/fields or access restrictions
+  - **⚠️ IMPORTANT: Data Access Scope vs Business Rules**
+    - If `dataConstraints` express **data access scope restrictions** (e.g., "can only view own entities", "can only view specific fields"), use `dataPolicy` NOT `condition`
+    - `dataPolicy` controls what data can be accessed AFTER the operation is permitted
+    - `condition` controls WHETHER the operation can execute (permissions/business rules)
+    - Example of data policy: Restricting visible fields, filtering by ownership
+  - Example with dynamic data policy (user-based filtering):
+    ```typescript
+    const ViewMyOrders = Interaction.create({
+      name: 'ViewMyOrders',
+      action: GetAction,
+      data: Order,
+      dataPolicy: DataPolicy.create({
+        match: function(this: Controller, event: any) {
+          // Only show user's own orders
+          return MatchExp.atom({key: 'owner.id', value:['=', event.user.id]})
+        }
+      })
+    })
+    ```
+  - Example with combined data policy (filtering + field restrictions + pagination):
     ```typescript
     const ViewMyFollowers = Interaction.create({
-      name: 'ViewUsers',
+      name: 'ViewMyFollowers',
       action: GetAction,
       data: User,  // REQUIRED: specify what to query
-      query: Query.create({  // OPTIONAL: predefined query config
-        items: [
-          QueryItem.create({
-            name: 'attributeQuery',
-            value: ['id', 'name', 'email']
-          }),
-          // Use function-based value to add conditional restrictions based on current context user
-          QueryItem.create({
-            name: 'match',
-            value: function(this:Controller, event:any) {
-              return MatchExp.atom({key: 'follow.id', value:['=', event.user.id]})
-            }
-          })
-        ]
+      dataPolicy: DataPolicy.create({
+        // Dynamic filter: only users who follow the current user
+        match: function(this: Controller, event: any) {
+          return MatchExp.atom({key: 'following.id', value:['=', event.user.id]})
+        },
+        // Field restrictions: only expose specific fields
+        attributeQuery: ['id', 'name', 'email'],
+        // Default pagination
+        modifier: { limit: 20, orderBy: { name: 'asc' } }
       })
     })
     ```

package/agent/.claude/agents/error-check-handler.md

@@ -1015,6 +1015,23 @@ const GetUserDonations = Interaction.create({
     ]
   })
 })
+
+// Query interaction with dataPolicy for access control
+const GetMyDonations = Interaction.create({
+  name: 'GetMyDonations',
+  action: GetAction,
+  data: Donation,  // ✅ Entity reference
+  dataPolicy: DataPolicy.create({
+    // ✅ Dynamic filter: users can only see their own donations
+    match: function(this: Controller, event: any) {
+      return MatchExp.atom({key: 'donor.id', value: ['=', event.user.id]})
+    },
+    // ✅ Field restrictions: limit exposed fields
+    attributeQuery: ['id', 'amount', 'createdAt', 'status'],
+    // ✅ Default pagination
+    modifier: { limit: 20, orderBy: { createdAt: 'desc' } }
+  })
+})
 ```
 
 ### Pattern 5: Test Error Checking

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

@@ -231,7 +231,40 @@ npm run generate-frontend-api
    }
    ```
 
-2. **Reference Existing Components for Patterns:**
+2. **Query Interactions Always Return Arrays:**
+   - Backend query-type interactions always return arrays in `response.data`
+   - To query a specific entity/relation, use the `match` field in the query options (2nd parameter)
+   - Do NOT put match criteria in the payload (1st parameter)
+   
+   ```typescript
+   // ✅ Correct: Use match in query options
+   const response = await apiClient.ViewVideoGenerationStatus(
+     { videoGenerationRequestId: videoId },  // payload
+     {
+       attributeQuery: ['id', 'status', 'videoUrl'],
+       match: {
+         key: 'id',
+         value: ['=', videoId]  // Match condition here
+       }
+     }
+   );
+   const item = response.data[0];  // Extract first item from array
+   
+   // ❌ Wrong: Don't rely on payload for filtering
+   const response = await apiClient.ViewVideoGenerationStatus(
+     { videoGenerationRequestId: videoId }  // This won't filter results
+   );
+   ```
+
+3. **Handling Asynchronous External System Tasks:**
+   - For asynchronous tasks that call external systems, backend typically does NOT implement polling unless explicitly specified in requirements
+   - Backend usually provides a separate API endpoint to trigger status updates
+   - Frontend can call this API to trigger backend status updates
+   - Frontend implementation options:
+     - **Manual trigger**: Add a button in the component for users to manually trigger the status update API
+     - **Automatic polling**: Implement polling in the component (on mount) until the task reaches a completion state
+
+4. **Reference Existing Components for Patterns:**
    - Look at `frontend/src/components/*.tsx` files
    - Follow the same patterns for API client usage
    - Check how error handling is implemented

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

@@ -45,6 +45,27 @@ This applies to BOTH async APIs (with task IDs) and sync APIs (immediate results
 - All integration documentation files MUST be prefixed with current module name from `.currentmodule`
 - Format: `docs/{module}.{integration-name}.integration-design.md`
 
+**🔴 CRITICAL PRINCIPLE: Status Polling Strategy**
+
+**Default Approach: Frontend Polling with Manual Query API**
+
+Backend polling consumes significant server resources. Follow this priority order:
+
+1. **Default (ALWAYS implement)**: Provide manual query API for frontend
+   - Create API endpoint to query external status
+   - Frontend can poll this API at its own pace
+   - Even if polling is needed, frontend handles it unless explicitly stated otherwise
+
+2. **Backend Polling (ONLY if explicitly required)**: Implement server-side polling
+   - ONLY implement if user explicitly requests "backend polling" in requirements
+   - Use with caution due to resource consumption
+   - Example: volcjmeng integration (only because explicitly required)
+
+3. **Webhook (ONLY if both conditions met)**: Implement webhook endpoint
+   - ONLY if external service supports webhook registration
+   - AND user can register webhook themselves
+   - Requires exposing public endpoint for external callbacks
+
 # Core Concepts
 
 ## Interaqt Framework

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

@@ -1280,6 +1280,22 @@ git commit -m "feat: Task 1.4 - Complete data concept extraction"
 - Interaction IDs must be semantic names (e.g., "BorrowBook", "ViewAvailableBooks") not codes (e.g., "I001")
 - ❌ If a requirement has role="System", it was incorrectly created - SKIP it, do NOT create interaction
 
+**⚠️ IMPORTANT: Distinguishing Data Access Constraints**
+
+For read-type interaction requirements with access restrictions, distinguish between:
+
+1. **Business Rules** - Constraints on whether the read operation can execute
+   - Example: "Only administrators can view XXX entity"
+   - Controls who can perform the action
+   - Should be specified in the `conditions` field
+
+2. **Data Policy** - Constraints on the scope of data returned
+   - Example: "Can only view own XXX entities" or "Can only view YYY fields of XXX entity"
+   - Controls what data is accessible after the operation is permitted
+   - Should be specified in the `dataConstraints` field
+
+These must be separated as they are implemented differently in subsequent phases.
+
 **⚠️ IMPORTANT: External Integration Interactions**
 
 If Task 1.4 includes API Call entities, design error handling interactions: