interaqt 1.1.2 → 1.2.0

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

@@ -553,7 +553,7 @@ EventSource.create<TArgs, TResult>(
   ```typescript
   async function(this: Controller, args: TArgs): Promise<TResult>
   ```
-- `config.afterDispatch` (function, optional): Hook called after dispatch completes. Can return additional context.
+- `config.afterDispatch` (function, optional): Hook called inside the retryable transaction attempt. Can return additional context, but must be retry-safe and must not perform irreversible external IO.
   ```typescript
   async function(this: Controller, args: TArgs, result: { data?: TResult }): Promise<Record<string, unknown> | void>
   ```
@@ -664,7 +664,7 @@ const result = await controller.dispatch(webhookSource, {
 2. `guard` runs before event processing; throw to reject the event
 3. `mapEventData` converts dispatch args into the format stored in the entity
 4. `resolve` returns data to the caller (useful for query-type events)
-5. `afterDispatch` runs after successful processing and can return additional context
+5. `afterDispatch` runs inside the retryable transaction attempt and can return additional context
 6. The Controller automatically registers the event source's entity if not already in the entities list
 7. Interaction is a built-in EventSource type that provides pre-built `guard`, `mapEventData`, and `resolve` implementations
 
@@ -1631,6 +1631,13 @@ Custom.create(config: CustomConfig): CustomInstance
   - For accessing dictionaries: use `type: 'global'` with `source: DictionaryInstance`
 - `config.useLastValue` (boolean, optional): Whether to use last computed value in incremental computation
 - `config.attributeQuery` (AttributeQueryData, optional): Attribute query configuration
+- `config.concurrency` (`'serializable' | 'atomic-safe'`, optional): Defaults to `'serializable'`. Serializable custom computations are retried in PostgreSQL `SERIALIZABLE` transactions. Use `'atomic-safe'` only when the callback is explicitly written with atomic state, idempotent patches, or other safe primitives.
+
+**Retry safety**
+
+Custom `compute`, `incrementalCompute`, `incrementalPatchCompute`, and `asyncReturn` callbacks may be replayed after transaction retry. Keep them deterministic and avoid irreversible external IO. Put post-commit external work in `recordMutationSideEffects`.
+
+For async custom computations, `ComputationResult.async({ freshnessKey })` can override the default freshness stream. Property async freshness is scoped to the host record, global async freshness is scoped to the global result, and entity/relation async freshness defaults to the result target.
 
 **Examples**
 
@@ -3376,7 +3383,7 @@ type DispatchResponse = {
 2. Execute `guard` (if provided and `ignoreGuard` is false)
 3. Map event data via `mapEventData` and create event record
 4. Execute `resolve` (if provided) - returns data
-5. Execute `afterDispatch` (if provided) - returns context
+5. Execute `afterDispatch` (if provided) inside the retryable transaction attempt - returns context
 6. Commit transaction
 7. Run RecordMutationSideEffects
 
@@ -3465,9 +3472,10 @@ interface Storage {
     map: any
     
     // Transaction operations
-    beginTransaction: (transactionName?: string) => Promise<any>
-    commitTransaction: (transactionName?: string) => Promise<any>
-    rollbackTransaction: (transactionName?: string) => Promise<any>
+    runInTransaction: <T>(
+        options: { name?: string; isolation?: 'READ COMMITTED' | 'SERIALIZABLE' },
+        fn: () => Promise<T>
+    ) => Promise<T>
     
     // Dictionary-specific API
     dict: {
@@ -3506,22 +3514,12 @@ interface Storage {
 
 #### Transaction Operations
 
-**beginTransaction(transactionName?: string)**
-Begin a database transaction.
-```typescript
-await storage.beginTransaction('updateOrder')
-```
-
-**commitTransaction(transactionName?: string)**
-Commit a database transaction.
+**runInTransaction(options, fn)**
+Run a callback inside a database transaction. The callback form is the only supported transaction boundary because it keeps the transaction connection bound to the full async chain.
 ```typescript
-await storage.commitTransaction('updateOrder')
-```
-
-**rollbackTransaction(transactionName?: string)**
-Rollback a database transaction.
-```typescript
-await storage.rollbackTransaction('updateOrder')
+await storage.runInTransaction({ name: 'updateOrder' }, async () => {
+  await storage.update('Order', match, data)
+})
 ```
 
 #### Entity/Relation Operations

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

@@ -5,6 +5,12 @@ Computations are the reactive core of interaqt, connecting interactions to entit
 
 ## Types of Computations
 
+## Retry Safety
+
+Computation callbacks may be replayed under PostgreSQL transaction retry. Keep callbacks deterministic and database-focused. Do not perform irreversible external IO in `compute`, `incrementalCompute`, `incrementalPatchCompute`, Transform callbacks, StateMachine compute functions, or `asyncReturn`.
+
+For custom computations, the default concurrency mode is `serializable`; use `concurrency: 'atomic-safe'` only when the callback is explicitly safe under concurrent `READ COMMITTED` execution.
+
 ### 1. Transform - Creates Entities/Relations
 
 **ONLY use in Entity/Relation computation, NEVER in Property!**

package/agent/agentspace/knowledge/generator/integration-implementation-handler.md

@@ -206,6 +206,8 @@ async setup(controller: Controller) {
 
 **Purpose**: Define side effects that synchronize reactive data changes to external systems.
 
+`RecordMutationSideEffect` is the recommended place for irreversible external IO. Interaction callbacks, custom computation callbacks, `afterDispatch`, and `asyncReturn` may be replayed by PostgreSQL transaction retry; side effects run after the final successful commit.
+
 **Use Cases**:
 - Push data mutations to external APIs
 - Publish messages to message queues

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

@@ -81,6 +81,14 @@ Reactive computation is a **declarative way of defining data**:
 - **Incremental computation**: Framework uses efficient incremental algorithms to avoid unnecessary recomputation
 - **Persistent**: Computation results are stored in the database for fast queries
 
+### PostgreSQL Concurrency Guarantees
+
+Built-in computations such as Count, Summation, Average, Every, Any, WeightedSummation, StateMachine, and data-based Transform use atomic state updates, row locks, or unique indexes on PostgreSQL. They are safe when multiple Node.js processes share one PostgreSQL database.
+
+Custom computations are different because interaqt cannot inspect user callback logic. `Custom.create()` defaults to `concurrency: 'serializable'`, so the framework promotes the transaction to PostgreSQL `SERIALIZABLE` and retries on `40001` / `40P01`. Use `concurrency: 'atomic-safe'` only when the custom computation is explicitly written with atomic state, idempotent patches, or other safe primitives.
+
+Because retry replays the transaction attempt, `guard`, `mapEventData`, `resolve`, computation callbacks, `afterDispatch`, and `asyncReturn` must be deterministic and retry-safe. Put irreversible external IO in `recordMutationSideEffects`, which runs after the final commit.
+
 ### Core Principle: Data Existence
 
 In interaqt, all data has its "reason for existence":

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

@@ -21,6 +21,19 @@ const result = await controller.callInteraction('CreatePost', {
 });
 ```
 
+## Retry-Safe Interaction Callbacks
+
+`Controller.dispatch()` runs interaction processing inside a retryable transaction. PostgreSQL SERIALIZABLE promotion or retryable SQLSTATE errors (`40001`, `40P01`) may replay the transaction attempt.
+
+These interaction callbacks must be deterministic and retry-safe:
+
+- `guard`
+- `mapEventData`
+- `resolve`
+- `afterDispatch`
+
+`afterDispatch` runs before commit inside the retryable transaction attempt. It can return response context or perform retry-safe database work, but it must not perform irreversible external IO. Put emails, webhooks, message publishing, payment calls, and other post-commit external effects in `recordMutationSideEffects`.
+
 ## Basic Concepts of Interactions
 
 ### What is an Interaction

package/agent/agentspace/knowledge/usage/10-async-computations.md

@@ -205,6 +205,19 @@ const currentWeather = await system.storage.get('state', 'currentWeather');
 console.log('Current weather:', currentWeather);
 ```
 
+### Retry and Freshness Semantics
+
+`handleAsyncReturn()` runs inside the same retryable transaction model as `Controller.dispatch()`. If PostgreSQL reports a retryable transaction error, or if the async result applies a custom/full-replace path that requires `SERIALIZABLE`, interaqt may replay the async return attempt.
+
+Keep `asyncReturn` deterministic and database-focused. Do not send emails, call payment APIs, publish messages, or perform other irreversible external IO from `asyncReturn`; those effects can be duplicated by a retry. Put irreversible post-commit work in `recordMutationSideEffects`.
+
+Async tasks also use a freshness key so stale results do not overwrite newer work:
+
+- Property async computations default to a key scoped by computation and host record.
+- Global async computations default to a key scoped by computation and global result.
+- Entity and relation async computations default to the result target, which means each target has one global freshness stream.
+- Pass an explicit `freshnessKey` to `ComputationResult.async({ freshnessKey })` when multiple independent async streams should be allowed for the same entity or relation target.
+
 ## Implementing Entity Async Computations
 
 ### Use Cases

package/agent/agentspace/knowledge/usage/13-testing.md

@@ -13,10 +13,10 @@ Many LLMs generate incorrect API usage. Here's the correct way to use interaqt t
 controller.run()                           // ❌ No such method
 storage.findByProperty('Entity', 'prop')   // ❌ No such method
 controller.execute()                       // ❌ No such method
-controller.dispatch()                      // ❌ No such method
 
 // ✅ CORRECT: Use these APIs instead
-controller.callInteraction('InteractionName', args)  // ✅ Call interactions
+controller.callInteraction('InteractionName', args)  // ✅ Call interaction by name
+controller.dispatch(InteractionObject, args)         // ✅ Dispatch an event source object
 storage.findOne('Entity', MatchExp)                  // ✅ Find single record
 storage.find('Entity', MatchExp)                     // ✅ Find multiple records
 storage.create('Entity', data)                       // ✅ Create record
@@ -139,6 +139,16 @@ describe('Feature Tests', () => {
 })
 ```
 
+### PostgreSQL Concurrency Tests
+
+For changes that affect runtime transactions, custom computations, async computations, PostgreSQL id generation, or reactive computation state, run the real PostgreSQL suite:
+
+```bash
+INTERAQT_POSTGRES_DATABASE=interaqt_test npm run test:postgres-concurrency
+```
+
+This script fails when the database environment variable is missing. Plain `npm test` may skip PostgreSQL-specific tests in local lightweight environments.
+
 ### Key API Methods
 
 #### 1. Controller APIs

package/agent/agentspace/knowledge/usage/14-api-reference.md

@@ -514,6 +514,16 @@ Transform.create(config: TransformConfig): KlassInstance<typeof Transform>
 - `config.callback` (function, required): Transformation function that converts source data to target data
 - `config.attributeQuery` (AttributeQueryData, required): Attribute query configuration
 
+### Custom.create()
+
+Create a custom computation when built-in computations are not expressive enough.
+
+**Concurrency parameter**
+- `config.concurrency` (optional): `'serializable' | 'atomic-safe'`, defaults to `'serializable'`.
+- `'serializable'`: interaqt runs the custom computation in a retryable PostgreSQL `SERIALIZABLE` transaction.
+- `'atomic-safe'`: you explicitly promise the custom computation only uses atomic state, idempotent patches, or other concurrency-safe primitives. Full recompute and entity/relation full replace paths still require SERIALIZABLE even for `atomic-safe` custom computations.
+
+Custom callbacks may be replayed after retryable transaction failures. Do not perform irreversible external IO inside custom `compute`, `incrementalCompute`, `incrementalPatchCompute`, or `asyncReturn`; use `recordMutationSideEffects` for post-commit external work.
 
 ### StateMachine.create()
 

package/agent/agentspace/knowledge/usage/18-api-exports-reference.md

@@ -53,6 +53,9 @@ import {
   // Storage and Query
   Controller,
   MonoSystem,
+  runWithTransactionRetry,
+  isRetryableTransactionError,
+  isRequireSerializableRetry,
   
   // Dictionary (Global State)
   Dictionary,
@@ -173,4 +176,6 @@ const controller = new Controller({
 
 4. **Filtered Entities**: Created using `Entity.create()` with `baseEntity` and `filterCondition`, not a separate import.
 
-5. **Database Drivers**: Choose one based on your needs - PGLiteDB for in-memory testing, PostgreSQLDB for production, etc. 
+5. **Database Drivers**: Choose one based on your needs - PGLiteDB for in-memory testing, PostgreSQLDB for production, etc. 
+
+6. **Transaction helpers**: `runWithTransactionRetry`, `isRetryableTransactionError`, and `isRequireSerializableRetry` are exported for advanced runtime integrations and tests. Most application code should use `Controller.dispatch()` or `system.storage.runInTransaction()` instead of calling retry helpers directly.

package/agent/agentspace/knowledge/usage/20-postgresql-concurrency-migration.md

@@ -0,0 +1,105 @@
+# PostgreSQL Concurrency Migration
+
+This note summarizes user-visible changes from the PostgreSQL reactive computation concurrency fix.
+
+## What Changed
+
+interaqt now uses PostgreSQL as the concurrency coordinator for multi-process deployments:
+
+- Built-in computations use atomic state updates, row locks, unique indexes, or SERIALIZABLE retry where needed.
+- PostgreSQL id generation uses native sequences instead of writing `_IDS_`.
+- Custom computations default to retryable `SERIALIZABLE` execution.
+- Async return handling runs in a retryable transaction and applies freshness checks.
+
+## Callback Replay Rules
+
+The following callbacks may be replayed after SERIALIZABLE promotion, `40001`, or `40P01`:
+
+- `guard`
+- `mapEventData`
+- `resolve`
+- computation callbacks
+- `afterDispatch`
+- `asyncReturn`
+
+Keep these callbacks deterministic. Do not send emails, charge payments, call irreversible external APIs, publish messages, or write non-transactional resources from these callbacks.
+
+Use `recordMutationSideEffects` for irreversible external IO. Side effects run after the final successful commit and are not replayed for failed attempts.
+
+## Custom Computation Concurrency
+
+`Custom.create()` now defaults to:
+
+```typescript
+Custom.create({
+  name: 'MyComputation',
+  concurrency: 'serializable',
+  // ...
+})
+```
+
+Use `concurrency: 'atomic-safe'` only when the custom computation is explicitly safe under concurrent PostgreSQL `READ COMMITTED` execution, for example because it only uses atomic state or idempotent patches.
+
+Even with `atomic-safe`, full recompute and entity/relation full replace paths still require SERIALIZABLE.
+
+## Async Return Freshness
+
+`handleAsyncReturn()` locks the task row and checks whether the task is still current.
+
+Default freshness streams:
+
+- Property async computation: scoped to the host record.
+- Global async computation: scoped to the global result.
+- Entity/relation async computation: scoped to the result target.
+
+Pass an explicit `freshnessKey` when one entity or relation target needs multiple independent async streams:
+
+```typescript
+return ComputationResult.async({
+  freshnessKey: `tenant:${tenantId}:job:${jobId}`,
+  // task args...
+})
+```
+
+Stale tasks are marked `skipped` and do not call `asyncReturn`.
+
+## PostgreSQL ID Sequences
+
+PostgreSQL ids are allocated with native sequences.
+
+Migration behavior:
+
+- New databases start at id `1`.
+- Existing table max id is used to initialize the sequence.
+- Existing `_IDS_` rows are read as legacy migration input when the table exists.
+- Databases without `_IDS_` are supported.
+- Shared physical tables use one sequence per physical table/id field.
+
+Do not write `_IDS_` to control ids. `_IDS_` is legacy input only.
+
+PostgreSQL sequence gaps are normal after rollback or failed transactions. Do not depend on contiguous ids.
+
+## Transaction API
+
+Use callback transactions:
+
+```typescript
+await system.storage.runInTransaction(
+  { name: 'my-operation', isolation: 'SERIALIZABLE' },
+  async () => {
+    // transactional work
+  }
+)
+```
+
+Do not use old manual transaction APIs such as `beginTransaction`, `commitTransaction`, or `rollbackTransaction`.
+
+## Testing PostgreSQL Concurrency
+
+Run the real PostgreSQL concurrency suite with:
+
+```bash
+INTERAQT_POSTGRES_DATABASE=interaqt_test npm run test:postgres-concurrency
+```
+
+This script intentionally fails when `INTERAQT_POSTGRES_DATABASE` is missing, so PostgreSQL concurrency coverage cannot silently skip in CI.

package/agent/agentspace/knowledge/usage/README.md

@@ -142,6 +142,7 @@ Remember: **Stop thinking "how to do", start thinking "what is"**!
 18. [Performance Optimization](./17-performance-optimization.md) - Performance tips
 19. [API Exports Reference](./18-api-exports-reference.md) - Complete list of available imports
 20. [Common Anti-Patterns](./19-common-anti-patterns.md) - Mistakes to avoid
+21. [PostgreSQL Concurrency Migration](./20-postgresql-concurrency-migration.md) - Retry, async, and sequence migration notes
 
 ## 📞 Need Help?
 

package/agent/skill/interaqt-patterns.md

@@ -15,12 +15,12 @@ const User = Entity.create({
     Property.create({ name: 'name', type: 'string' }),
     Property.create({ name: 'email', type: 'string' }),
     Property.create({ name: 'age', type: 'number' }),
-    Property.create({ name: 'status', type: 'string', defaultValue: 'active' }),
+    Property.create({ name: 'status', type: 'string', defaultValue: () => 'active' }),
     Property.create({ name: 'createdAt', type: 'string', defaultValue: () => new Date().toISOString() }),
     Property.create({
       name: 'fullName',
       type: 'string',
-      getValue: (record) => `${record.firstName} ${record.lastName}`
+      computed: (record) => `${record.firstName} ${record.lastName}`
     })
   ]
 })
@@ -52,7 +52,7 @@ The Klass pattern uses `generateUUID()` internally. Manual IDs risk collisions a
 ### Checklist
 - [ ] Entity name is PascalCase and singular (`User` not `users`)
 - [ ] No manual UUID assignment
-- [ ] Computed properties that depend only on the same record use `getValue`, NOT Transform
+- [ ] Computed properties that depend only on the same record use `computed`, NOT Transform
 - [ ] Properties with reactive computations (Count, etc.) include `defaultValue`
 
 ---
@@ -148,7 +148,7 @@ Without `type`, the framework cannot determine cardinality. ALWAYS explicitly se
 | Check ANY related record matches condition | `Any` |
 | Derive new entities from events or other entities | `Transform` (on Entity `computation`) |
 | Update a property value based on state transitions | `StateMachine` (on Property `computation`) |
-| Simple computation from same-record fields | `getValue` (on Property) |
+| Simple computation from same-record fields | `computed` (on Property) |
 
 ```typescript
 import { Entity, Property, Relation, Count, WeightedSummation, Transform, InteractionEventEntity } from 'interaqt'
@@ -184,12 +184,12 @@ Property.create({
 Property.create({
   name: 'formattedPrice',
   type: 'string',
-  getValue: (record) => `$${record.price}`
+  computed: (record) => `$${record.price}`
 })
 ```
 
 ### WHY
-Transform creates new records in a computed entity collection. It CANNOT update a single property. Use `getValue` for same-entity property computations.
+Transform creates new records in a computed entity collection. It CANNOT update a single property. Use `computed` for same-entity property computations.
 
 ### WRONG: Transform for counting
 ```typescript
@@ -220,8 +220,8 @@ Count uses incremental algorithms. Transform loads all records into memory, whic
 ```typescript
 // DON'T — Controller does NOT accept a computations parameter
 const controller = new Controller({
-  system, entities, relations, activities, interactions,
-  dict: [myComputation],  // dict is for Dictionaries, not computations
+  system, entities, relations,
+  eventSources: [myComputation],  // eventSources is for Interactions, not computations
 })
 ```
 
@@ -243,7 +243,7 @@ All computations are declared within the `computation` field of Entity, Relation
 - [ ] Transform is on `Entity.computation` or `Relation.computation`, NEVER on `Property.computation`
 - [ ] Count, WeightedSummation, Every, Any are on `Property.computation`
 - [ ] StateMachine is on `Property.computation`
-- [ ] `getValue` is used for same-record-only property derivations
+- [ ] `computed` is used for same-record-only property derivations
 - [ ] Properties with computation ALWAYS have `defaultValue`
 - [ ] NEVER pass computations to Controller constructor
 
@@ -261,9 +261,9 @@ const CreatePost = Interaction.create({
   action: Action.create({ name: 'createPost' }),
   payload: Payload.create({
     items: [
-      PayloadItem.create({ name: 'title', required: true }),
-      PayloadItem.create({ name: 'content', required: true }),
-      PayloadItem.create({ name: 'postId', base: Post, isRef: true })
+      PayloadItem.create({ name: 'title', type: 'string', required: true }),
+      PayloadItem.create({ name: 'content', type: 'string', required: true }),
+      PayloadItem.create({ name: 'postId', type: 'string', base: Post, isRef: true })
     ]
   })
 })
@@ -310,8 +310,7 @@ const controller = new Controller({
   system,
   entities: [User, Post],
   relations: [UserPosts],
-  activities: [],
-  interactions: [CreatePost],
+  eventSources: [CreatePost],
   dict: [],
   recordMutationSideEffects: []
 })
@@ -319,18 +318,18 @@ const controller = new Controller({
 await controller.setup(true)
 ```
 
-### WRONG: Calling callInteraction before setup
+### WRONG: Calling dispatch before setup
 ```typescript
 // DON'T — setup MUST come first
-const controller = new Controller({ system, entities, relations, activities, interactions, dict: [] })
-await controller.callInteraction('CreatePost', { user: { id: '1' }, payload: { title: 'Hi' } })
+const controller = new Controller({ system, entities, relations, eventSources: [CreatePost], dict: [] })
+await controller.dispatch(CreatePost, { user: { id: '1' }, payload: { title: 'Hi' } })
 ```
 
 ### CORRECT:
 ```typescript
-const controller = new Controller({ system, entities, relations, activities, interactions, dict: [] })
+const controller = new Controller({ system, entities, relations, eventSources: [CreatePost], dict: [] })
 await controller.setup(true)
-await controller.callInteraction('CreatePost', { user: { id: '1' }, payload: { title: 'Hi' } })
+await controller.dispatch(CreatePost, { user: { id: '1' }, payload: { title: 'Hi' } })
 ```
 
 ### WHY
@@ -338,15 +337,15 @@ await controller.callInteraction('CreatePost', { user: { id: '1' }, payload: { t
 
 ### Checklist
 - [ ] `system.conceptClass = KlassByName` is set before creating Controller
-- [ ] `controller.setup(true)` is called BEFORE any `callInteraction`
+- [ ] `controller.setup(true)` is called BEFORE any `dispatch`
 - [ ] `dict` contains only Dictionary instances, not computations
 
 ---
 
-## When Calling Interactions
+## When Dispatching Interactions
 
 ```typescript
-const result = await controller.callInteraction('CreatePost', {
+const result = await controller.dispatch(CreatePost, {
   user: { id: 'user-1', role: 'author' },
   payload: {
     title: 'My Post',
@@ -361,17 +360,17 @@ if (result.error) {
 
 ### WRONG: Using try-catch for error handling
 ```typescript
-// DON'T — interaqt does NOT throw exceptions
+// DON'T — interaqt does NOT throw exceptions by default
 try {
-  await controller.callInteraction('CreatePost', { user: { id: '1' }, payload: {} })
+  await controller.dispatch(CreatePost, { user: { id: '1' }, payload: {} })
 } catch (e) {
-  // This code will NEVER execute
+  // This code will NEVER execute (unless forceThrowDispatchError is true)
 }
 ```
 
 ### CORRECT:
 ```typescript
-const result = await controller.callInteraction('CreatePost', {
+const result = await controller.dispatch(CreatePost, {
   user: { id: '1' },
   payload: {}
 })
@@ -381,20 +380,26 @@ if (result.error) {
 ```
 
 ### WHY
-The framework catches all errors internally and returns them via `result.error`. Exceptions are never thrown to callers.
+The framework catches all errors internally and returns them via `result.error`. Exceptions are never thrown to callers (unless `forceThrowDispatchError: true` is set on Controller).
+
+### WRONG: Passing a name string instead of instance
+```typescript
+// DON'T — first argument must be the event source instance, not a string
+controller.dispatch('CreatePost', payload)
+```
 
 ### WRONG: Using non-existent API methods
 ```typescript
 // DON'T — these methods do NOT exist
-controller.dispatch('CreatePost', payload)
+controller.callInteraction('CreatePost', payload)
 controller.run()
 controller.execute()
 ```
 
 ### CORRECT:
 ```typescript
-// The ONLY method to trigger interactions
-await controller.callInteraction('CreatePost', {
+// The ONLY method to trigger interactions — first arg is the instance reference
+await controller.dispatch(CreatePost, {
   user: { id: 'user-1' },
   payload: { title: 'Hi' }
 })
@@ -403,7 +408,7 @@ await controller.callInteraction('CreatePost', {
 ### Checklist
 - [ ] ALWAYS pass a `user` object with at least `id`
 - [ ] ALWAYS check `result.error` — NEVER use try-catch
-- [ ] Use `controller.callInteraction(name, args)` — no other dispatch method exists
+- [ ] Use `controller.dispatch(eventSourceInstance, args)` — first arg is the instance, NOT a name string
 
 ---
 
@@ -486,13 +491,13 @@ describe('Feature', () => {
     system = new MonoSystem(new PGLiteDB())
     system.conceptClass = KlassByName
     controller = new Controller({
-      system, entities, relations, activities, interactions, dict: [], recordMutationSideEffects: []
+      system, entities, relations, eventSources, dict: [], recordMutationSideEffects: []
     })
     await controller.setup(true)
   })
 
   test('creates a post via interaction', async () => {
-    const result = await controller.callInteraction('CreatePost', {
+    const result = await controller.dispatch(CreatePost, {
       user: { id: 'user-1' },
       payload: { title: 'Test', content: 'Hello' }
     })
@@ -518,8 +523,8 @@ const post = await system.storage.create('Post', { title: 'Test', content: 'Hell
 
 ### CORRECT:
 ```typescript
-// Use callInteraction to test business logic
-const result = await controller.callInteraction('CreatePost', {
+// Use dispatch to test business logic
+const result = await controller.dispatch(CreatePost, {
   user: { id: 'user-1' },
   payload: { title: 'Test', content: 'Hello' }
 })
@@ -531,6 +536,6 @@ const result = await controller.callInteraction('CreatePost', {
 ### Checklist
 - [ ] Use `PGLiteDB` for test databases
 - [ ] Call `controller.setup(true)` in `beforeEach`
-- [ ] Test business logic through `callInteraction`, not direct storage
+- [ ] Test business logic through `controller.dispatch`, not direct storage
 - [ ] Check `result.error` — NEVER use try-catch
 - [ ] ALWAYS pass `attributeQuery` when asserting on query results