interaqt 2.0.3 → 3.0.0

package/README.md

@@ -354,7 +354,7 @@ npm install @electric-sql/pglite
 - **StateMachine** — Model entity lifecycles with explicit state transitions triggered by events
 - **Filtered Entities** — Virtual views over entities, like reactive database views
 - **Activities** — Compose multi-step business workflows from ordered Interactions
-- **Attributive Permissions** — Declarative, entity-aware access control
+- **Condition Guards** — Declarative access control with full event context
 - **Dictionary** — Global reactive key-value state
 - **Schema Constraints** — Persistent unique constraints with structured duplicate errors
 - **Hard Deletion** — Built-in support for both soft and hard delete patterns

package/agent/agentspace/knowledge/generator/api-reference.md

@@ -2656,7 +2656,7 @@ const GetPostsPaginated = Interaction.create({
 > **⚠️ SECURITY: always declare `dataPolicy.match` for row-level access control.**
 > The caller-supplied `query.match` is merged with `dataPolicy.match` using AND — it can only *narrow* the
 > policy-defined scope. But if an interaction has **no** `dataPolicy.match`, the caller fully controls the filter
-> and can read **any** rows of the entity (userAttributives only decide *whether* the interaction may run,
+> and can read **any** rows of the entity (conditions only decide *whether* the interaction may run,
 > not *which rows* are visible). Every `GetAction` interaction on non-public data MUST declare `dataPolicy.match`.
 
 **Usage Examples for Get Data Interactions**
@@ -2971,12 +2971,11 @@ PayloadItem.create(config: PayloadItemConfig): PayloadItemInstance
 - `config.name` (string, required): Parameter name
 - `config.required` (boolean, optional): Whether it's required, defaults to false
 - `config.isCollection` (boolean, optional): Whether it's a collection type, defaults to false
-- `config.itemRef` (Attributive|Entity, optional): Used to reference entities defined in other interactions within Activity
 
 **Examples**
 ```typescript
 // Reference existing user
-const userRef = PayloadItem.create({
+const userItem = PayloadItem.create({
     name: 'user',
     required: true
 })
@@ -2992,12 +2991,6 @@ const reviewersItem = PayloadItem.create({
     name: 'reviewers',
     isCollection: true
 })
-
-// Activity item reference
-const activityItem = PayloadItem.create({
-    name: 'to',
-    itemRef: userRefB
-})
 ```
 
 ## 13.5 Activity-Related APIs

package/agent/agentspace/knowledge/generator/permission-test-implementation.md

@@ -42,6 +42,24 @@ expect((result.error as ConditionError).error.data.name).toBe('AdminRole')
 - `'no permission'` → Never used (legacy)
 - `'condition check failed'` → What you'll actually see
 
+### Guard Callback Return Contract (strict boolean)
+
+Condition callbacks must return an actual `boolean` (`true` or `false`).
+Any non-boolean return value — including truthy values like `'admin'` and falsy values
+like `null` / `0` / `''` — is treated as a definition error and the check fails
+(fail-closed), with an error message telling you what was returned.
+
+Why falsy non-booleans matter: under a `not(...)` combination, a sloppy falsy value
+would otherwise be inverted into a pass. Always coerce explicitly:
+
+```typescript
+// ❌ WRONG: short-circuit expressions can produce null/undefined/0
+content: async (event) => event.user.profile && event.user.profile.isAdmin
+
+// ✅ CORRECT: coerce to boolean
+content: async (event) => !!(event.user.profile && event.user.profile.isAdmin)
+```
+
 ## Testing Permission Patterns
 
 ### 1. Role-Based Permission Test

package/agent/agentspace/knowledge/generator/test-implementation.md

@@ -301,15 +301,16 @@ The interaqt framework wraps all exceptions in the return value, so you NEVER ne
 ### Error Types
 
 ```typescript
-// 1. Permission errors
+// 1. Permission errors (condition checks)
 const result = await controller.callInteraction('DeleteStyle', {
   user: viewerUser,  // viewer role cannot delete
   payload: { id: style.id }
 })
 expect(result.error).toBeDefined()
-expect((result.error as any).type).toBe('check user failed')
+expect((result.error as any).type).toBe('condition check failed')
+expect((result.error as any).error.data.name).toBe('AdminOnly')  // which condition failed
 
-// 2. Validation errors (payload attributive checks)
+// 2. Payload content validation errors (also condition checks)
 const result = await controller.callInteraction('PublishStyle', {
   user: adminUser,
   payload: { 
@@ -317,7 +318,7 @@ const result = await controller.callInteraction('PublishStyle', {
   }
 })
 expect(result.error).toBeDefined()
-expect((result.error as any).type).toBe('id not match attributive')
+expect((result.error as any).type).toBe('condition check failed')
 
 // 3. Missing required fields
 const result = await controller.callInteraction('CreateStyle', {
@@ -328,7 +329,7 @@ const result = await controller.callInteraction('CreateStyle', {
   }
 })
 expect(result.error).toBeDefined()
-expect((result.error as any).type).toBe('payload label missing')
+expect((result.error as any).type).toBe('label missing')
 
 // 4. Business rule violations (condition checks)
 const result = await controller.callInteraction('CreateStyle', {

package/agent/agentspace/knowledge/usage/02-define-entities-properties.md

@@ -320,18 +320,23 @@ const User = Entity.create({
 });
 ```
 
-If you need to perform uniqueness checks at the application level, you can implement them through the Attributive system:
+If you need to perform uniqueness checks at the application level, you can implement them as a Condition on the relevant Interaction:
 
 ```javascript
-const UniqueEmailAttributive = Attributive.create({
+const UniqueEmail = Condition.create({
   name: 'UniqueEmail',
-  content: async function(user, { system }) {
-    const existingUser = await system.storage.findOne('User', 
-      MatchExp.atom({ key: 'email', value: ['=', user.email] })
+  content: async function(event) {
+    const existingUser = await this.system.storage.findOne('User', 
+      MatchExp.atom({ key: 'email', value: ['=', event.payload.user.email] }),
+      undefined,
+      ['id']
     );
-    return !existingUser || existingUser.id === user.id;
+    return !existingUser || existingUser.id === event.payload.user.id;
   }
 });
+
+// Attach to the interaction that creates/updates users
+// Interaction.create({ name: 'UpdateUser', ..., conditions: UniqueEmail })
 ```
 
 ## Complete Example

package/agent/agentspace/knowledge/usage/04-reactive-computations.md

@@ -728,6 +728,11 @@ const User = Entity.create({
 
 ```javascript
 // ✅ Correct: Create a derived entity based on another entity
+// ⚠️ IMPORTANT: the callback must NOT return a top-level `id` field.
+//    Derived-record identity is managed by the framework; spreading the source
+//    record (`(product) => ({...product})`) carries its id along and fails fast.
+//    Strip it first: `({id: _, ...rest}) => ({...rest})`.
+//    (Nested references like `{author: {id}}` are fine — that's how relations attach.)
 const Product = Entity.create({
   name: 'Product',
   properties: [
@@ -1237,7 +1242,7 @@ Note: if several transfers share the same `current` state and their triggers mat
 
 ### Guarding Transitions
 
-There is no `condition` field on `StateTransfer`. Preconditions belong to the interaction layer (use `conditions` / `userAttributives` on the Interaction so unauthorized or invalid calls never produce an event), and fine-grained per-record filtering is expressed in `computeTarget` — return `null`/`undefined` (or an empty array) to skip the transition for records that should not transition:
+There is no `condition` field on `StateTransfer`. Preconditions belong to the interaction layer (use `conditions` on the Interaction so unauthorized or invalid calls never produce an event), and fine-grained per-record filtering is expressed in `computeTarget` — return `null`/`undefined` (or an empty array) to skip the transition for records that should not transition:
 
 ```javascript
 StateTransfer.create({

package/agent/agentspace/knowledge/usage/05-interactions.md

@@ -387,9 +387,23 @@ const CreateProduct = Interaction.create({
 
 ### Conditional Parameters
 
-The framework itself doesn't support dynamic required conditions and complex validation functions. These logics should be implemented in interaction handling:
+The framework itself doesn't support dynamic required conditions and complex validation functions. These logics should be implemented as conditions on the Interaction:
 
 ```javascript
+// Validation logic should be implemented through Condition
+const OrderIsValid = Condition.create({
+  name: 'OrderIsValid',
+  content: async function(event) {
+    const { payload } = event;
+    // Shipping address is required for orders under $100
+    if (payload.totalAmount < 100 && !payload.shippingAddress) {
+      return false;
+    }
+    // Coupon validation etc.
+    return true;
+  }
+});
+
 const CreateOrder = Interaction.create({
   name: 'CreateOrder',
   action: Action.create({ name: 'createOrder' }),
@@ -402,29 +416,15 @@ const CreateOrder = Interaction.create({
       }),
       PayloadItem.create({ 
         name: 'shippingAddress'
-        // Conditional required logic should be checked in interaction handling
+        // Conditional required logic is checked by OrderIsValid
       }),
       PayloadItem.create({ 
         name: 'couponCode'
-        // Coupon validation should be implemented in business logic
+        // Coupon validation is checked by OrderIsValid
       })
     ]
-  })
-});
-
-// Validation logic should be implemented in Transform or Attributive
-const orderValidation = Transform.create({
-  record: InteractionEventEntity,
-  callback: function(event) {
-    if (event.interactionName === 'CreateOrder') {
-      // Implement complex validation logic here
-      const { payload } = event;
-      if (payload.totalAmount < 100 && !payload.shippingAddress) {
-        throw new Error('Shipping address is required for orders under $100');
-      }
-      // Coupon validation etc.
-    }
-  }
+  }),
+  conditions: OrderIsValid
 });
 ```
 
@@ -986,6 +986,25 @@ const Review = Entity.create({
 ### Basic Permission Checks
 
 ```javascript
+// Use Condition for permission control
+const CanDeletePost = Condition.create({
+  name: 'canDeletePost',
+  content: async function(event) {
+    // Admin can delete any post
+    if (event.user.role === 'admin') {
+      return true;
+    }
+    
+    // Author can delete their own post
+    const post = await this.system.storage.findOne('Post',
+      MatchExp.atom({ key: 'id', value: ['=', event.payload.postId.id] }),
+      undefined,
+      [['author', { attributeQuery: ['id'] }]]
+    );
+    return !!post && post.author?.id === event.user.id;
+  }
+});
+
 // Interaction with permission requirements
 const DeletePost = Interaction.create({
   name: 'DeletePost',
@@ -995,36 +1014,23 @@ const DeletePost = Interaction.create({
       PayloadItem.create({ name: 'postId', base: Post, isRef: true })
     ]
   }),
-  // Permission logic should be implemented through Attributive
-});
-
-// Use Attributive for permission control
-const DeletePostPermission = Attributive.create({
-  name: 'canDeletePost',
-  type: 'boolean',
-  record: InteractionEventEntity,
-  computation: function(interactionEvent) {
-    if (interactionEvent.interactionName === 'DeletePost') {
-      const user = interactionEvent.user;
-      const postId = interactionEvent.payload.postId;
-      
-      // Admin can delete any post
-      if (user.role === 'admin') {
-        return true;
-      }
-      
-      // Author can delete their own post
-      // This would need to be checked against the actual post data
-      return false; // Simplified for example
-    }
-    return true;
-  }
+  // Permission logic is implemented through conditions
+  conditions: CanDeletePost
 });
 ```
 
 ### Role-Based Permission Control
 
 ```javascript
+// Permission check through Condition
+const CanModerateContent = Condition.create({
+  name: 'canModerateContent',
+  content: async function(event) {
+    // Only moderators and admins can moderate content
+    return ['moderator', 'admin'].includes(event.user.role);
+  }
+});
+
 // Content moderation interaction
 const ModerateContent = Interaction.create({
   name: 'ModerateContent',
@@ -1035,23 +1041,8 @@ const ModerateContent = Interaction.create({
       PayloadItem.create({ name: 'action', required: true }), // approve, reject, flag
       PayloadItem.create({ name: 'reason' })
     ]
-  })
-});
-
-// Permission check through Attributive
-const ModerationPermission = Attributive.create({
-  name: 'canModerateContent',
-  type: 'boolean',
-  record: InteractionEventEntity,
-  computation: function(interactionEvent) {
-    if (interactionEvent.interactionName === 'ModerateContent') {
-      const user = interactionEvent.user;
-      
-      // Only moderators and admins can moderate content
-      return ['moderator', 'admin'].includes(user.role);
-    }
-    return true;
-  }
+  }),
+  conditions: CanModerateContent
 });
 ```
 

package/agent/agentspace/knowledge/usage/06-attributive-permissions.md

@@ -1,10 +1,57 @@
-# Permission Control (Deprecated)
+# Permission Control (Attributive — Removed)
 
-The `userAttributives` and `dataAttributives` permission control features have been removed from the interaqt framework.
+The `Attributive` / `Attributives` concept has been **removed** from the interaqt framework, along with all of its attachment points:
 
-For controlling access to interactions and data, please use:
-- `conditions` parameter in Interaction.create() for execution conditions
-- Application-level authentication and authorization (e.g., JWT, OAuth)
-- Custom business logic in your interactions
+- `Interaction.userAttributives` / `Interaction.userRef`
+- `PayloadItem.attributives` / `PayloadItem.itemRef`
+- `createUserRoleAttributive` / `boolExpToAttributives`
+- activity `refs` and `isRef` user binding
 
-The framework now focuses on reactive business logic rather than built-in permission control.
+Declaring any of these now fails fast at declaration time with an error pointing here.
+
+## Use Conditions instead
+
+`Condition` is the single guard concept. A condition callback receives the **full event args** (`user`, `payload`, `query`, `activityId`) with the Controller as `this`, so every form previously expressed with attributives is expressible as a condition:
+
+```typescript
+// Role check (was: createUserRoleAttributive)
+const AdminOnly = Condition.create({
+  name: 'AdminOnly',
+  content: async function(event) {
+    return !!(event.user.roles && event.user.roles.includes('admin'))
+  }
+})
+
+// Payload-content check (was: PayloadItem.attributives)
+const PublishedPostOnly = Condition.create({
+  name: 'PublishedPostOnly',
+  content: async function(this: Controller, event) {
+    const post = await this.system.storage.findOne('Post',
+      MatchExp.atom({ key: 'id', value: ['=', event.payload.post.id] }),
+      undefined, ['status'])
+    return post?.status === 'published'
+  }
+})
+
+// Activity user binding (was: userRef/itemRef + isRef attributive):
+// query this activity's own interaction events to locate the bound user.
+const MustBeRequestReceiver = Condition.create({
+  name: 'MustBeRequestReceiver',
+  content: async function(this: Controller, event) {
+    if (!event.activityId) return false
+    const sendEvent = await this.system.storage.findOne(InteractionEventEntity.name,
+      MatchExp.atom({ key: 'interactionName', value: ['=', 'sendRequest'] })
+        .and({ key: 'activity.id', value: ['=', event.activityId] }),
+      undefined, ['*'])
+    return !!sendEvent && sendEvent.payload?.to?.id === event.user.id
+  }
+})
+```
+
+Combine conditions with `Conditions.create({ content: BoolExp.atom(a).and(b).or(c) })`.
+
+## Contract
+
+- Guard callbacks must return an actual `boolean`; any non-boolean result fails the check (fail-closed).
+- Conditions run inside the dispatch transaction, before the event record is persisted.
+- For row-level data access control on queries, use `dataPolicy` (match/modifier/attributeQuery) on GetAction interactions.