interaqt 1.1.3 → 1.3.0

package/README.md

@@ -245,6 +245,40 @@ const system = new MonoSystem(new PostgreSQLDB({ /* connection config */ }))
 
 ---
 
+## Schema Constraints and Transaction Boundaries
+
+interaqt supports schema-level uniqueness for framework-managed records. Declare uniqueness at the Entity or Relation level with `UniqueConstraint`; the storage setup installs database unique indexes and reports duplicate writes as structured framework errors.
+
+```typescript
+import { Entity, Property, UniqueConstraint } from 'interaqt'
+
+const User = Entity.create({
+  name: 'User',
+  properties: [
+    Property.create({ name: 'email', type: 'string' })
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'User_email_unique',
+      properties: ['email'],
+      violationCode: 'USER_EMAIL_DUPLICATE'
+    })
+  ]
+})
+```
+
+`controller.dispatch()` runs event persistence and synchronous computation writes in one transaction. Unique conflicts roll back the whole dispatch attempt and can be handled with `ConstraintViolationError` or `findConstraintViolationError(error)`.
+
+For diagnostics and migration planning, inspect the read-only schema metadata:
+
+```typescript
+system.storage.schema.constraints
+system.storage.schema.records
+system.storage.schema.tables
+```
+
+---
+
 ## Installation
 
 ```bash
@@ -291,8 +325,9 @@ npm install @electric-sql/pglite
 - **Activities** — Compose multi-step business workflows from ordered Interactions
 - **Attributive Permissions** — Declarative, entity-aware access control
 - **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
-- **Side Effects** — Hook into record mutations for external integrations (email, payments, file uploads)
+- **Post-Commit Side Effects** — Use `postCommit` or record mutation side effects for external integrations after commit
 
 ---
 

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.
 
+`postCommit` is the recommended place for irreversible external IO tied to one interaction. `RecordMutationSideEffect` is the recommended place for irreversible external IO driven by record mutations. Interaction callbacks, custom computation callbacks, `afterDispatch`, and `asyncReturn` may be replayed by PostgreSQL transaction retry; post-commit hooks and 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/03-entity-relations.md

@@ -36,14 +36,20 @@ One-to-one relations represent unique correspondences between two entities, such
 ### Basic One-to-One Relation
 
 ```javascript
-import { Entity, Property, Relation } from 'interaqt';
+import { Entity, Property, Relation, UniqueConstraint } from 'interaqt';
 
 // Define user entity
 const User = Entity.create({
   name: 'User',
   properties: [
-    Property.create({ name: 'email', type: 'string', unique: true }),
+    Property.create({ name: 'email', type: 'string' }),
     Property.create({ name: 'name', type: 'string' })
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'User_email_unique',
+      properties: ['email']
+    })
   ]
 });
 
@@ -116,8 +122,14 @@ One-to-many relations represent that one entity can be associated with multiple
 const User = Entity.create({
   name: 'User',
   properties: [
-    Property.create({ name: 'email', type: 'string', unique: true }),
+    Property.create({ name: 'email', type: 'string' }),
     Property.create({ name: 'name', type: 'string' })
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'User_email_unique',
+      properties: ['email']
+    })
   ]
 });
 
@@ -195,8 +207,14 @@ Many-to-many relations represent multiple associations between two entities, suc
 const Tag = Entity.create({
   name: 'Tag',
   properties: [
-    Property.create({ name: 'name', type: 'string', unique: true }),
+    Property.create({ name: 'name', type: 'string' }),
     Property.create({ name: 'color', type: 'string', defaultValue: '#666666' })
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'Tag_name_unique',
+      properties: ['name']
+    })
   ]
 });
 
@@ -499,15 +517,21 @@ const UserPosts = Relation.create({
 ## Complete Example: Blog System Relation Design
 
 ```javascript
-import { Entity, Property, Relation } from 'interaqt';
+import { Entity, Property, Relation, UniqueConstraint } from 'interaqt';
 
 // Entity definitions
 const User = Entity.create({
   name: 'User',
   properties: [
-    Property.create({ name: 'email', type: 'string', unique: true }),
+    Property.create({ name: 'email', type: 'string' }),
     Property.create({ name: 'name', type: 'string' }),
     Property.create({ name: 'avatar', type: 'string' })
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'User_email_unique',
+      properties: ['email']
+    })
   ]
 });
 
@@ -532,8 +556,14 @@ const Comment = Entity.create({
 const Tag = Entity.create({
   name: 'Tag',
   properties: [
-    Property.create({ name: 'name', type: 'string', unique: true }),
+    Property.create({ name: 'name', type: 'string' }),
     Property.create({ name: 'color', type: 'string', defaultValue: '#666666' })
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'Tag_name_unique',
+      properties: ['name']
+    })
   ]
 });
 

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 `postCommit` for interaction-specific effects or `recordMutationSideEffects` for mutation-driven effects; both run 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,30 @@ 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.
+
+Use `postCommit` for interaction-specific external IO that should run only after the final successful commit:
+
+```javascript
+CreateOrder.postCommit = async function(args, result) {
+  await sendOrderWebhook(result.data);
+  return { webhookSent: true };
+};
+```
+
+If `postCommit` fails, committed data is not rolled back; the error is reported in `result.sideEffects.__postCommit.error`. Use `recordMutationSideEffects` when the side effect should be driven by record mutation events rather than by a specific interaction.
+
 ## 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

@@ -9,6 +9,7 @@ import {
   // Entity-related
   Entity,
   Property,
+  UniqueConstraint,
   
   // Relation-related
   Relation,
@@ -53,6 +54,13 @@ import {
   // Storage and Query
   Controller,
   MonoSystem,
+  runWithTransactionRetry,
+  isRetryableTransactionError,
+  isRequireSerializableRetry,
+  ConstraintViolationError,
+  ConstraintSetupError,
+  findConstraintViolationError,
+  normalizeDatabaseError,
   
   // Dictionary (Global State)
   Dictionary,
@@ -92,17 +100,36 @@ import {
 
 ### Basic Entity Definition
 ```javascript
-import { Entity, Property } from 'interaqt';
+import { Entity, Property, UniqueConstraint } from 'interaqt';
 
 const User = Entity.create({
   name: 'User',
   properties: [
     Property.create({ name: 'name', type: 'string' }),
     Property.create({ name: 'email', type: 'string' })
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'User_email_unique',
+      properties: ['email']
+    })
   ]
 });
 ```
 
+### Data Constraints
+```javascript
+import {
+  UniqueConstraint,
+  ConstraintViolationError,
+  ConstraintSetupError,
+  findConstraintViolationError,
+  normalizeDatabaseError
+} from 'interaqt';
+```
+
+`UniqueConstraint` declares persistent database uniqueness at Entity or Relation level. Runtime duplicate writes are reported with `ConstraintViolationError`; setup/index creation problems are reported with `ConstraintSetupError`. Use `findConstraintViolationError(error)` when the top-level error may be a wrapped computation error.
+
 ### Complete CRUD Setup
 ```javascript
 import { 
@@ -173,4 +200,8 @@ 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.
+
+7. **Constraint helpers**: `UniqueConstraint`, `ConstraintViolationError`, `ConstraintSetupError`, `findConstraintViolationError`, and `normalizeDatabaseError` are exported for schema-level uniqueness and stable duplicate handling.

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-reference.md

@@ -512,10 +512,11 @@ EventSource.create(args: {
   mapEventData?: (args: TArgs) => Record<string, any>
   resolve?: (this: Controller, args: TArgs) => Promise<TResult>
   afterDispatch?: (this: Controller, args: TArgs, result: { data?: TResult }) => Promise<Record<string, unknown> | void>
+  postCommit?: (this: Controller, args: TArgs, result: { data?: TResult, context?: Record<string, unknown> }) => Promise<Record<string, unknown> | void>
 }): EventSourceInstance
 ```
 
-Custom event source for scheduled tasks, webhooks, or any non-interaction trigger. Dispatch via `controller.dispatch(eventSource, args)`.
+Custom event source for scheduled tasks, webhooks, or any non-interaction trigger. Dispatch via `controller.dispatch(eventSource, args)`. `afterDispatch` runs inside the retryable transaction; use `postCommit` for external IO that must run only after commit.
 
 ---
 

package/dist/builtins/interaction/activity/ActivityManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActivityManager.d.ts","sourceRoot":"","sources":["../../../../src/builtins/interaction/activity/ActivityManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAqE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC1H,OAAO,EAA8B,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAG1G,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,eAAO,MAAM,eAAe,eAAe,CAAA;AAE3C,eAAO,MAAM,mBAAmB,gBAwB9B,CAAA;AAEF,eAAO,MAAM,2BAA2B,kBAOtC,CAAA;AAEF,MAAM,WAAW,qBAAqB;IAClC,YAAY,EAAE,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAA;IAC7C,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAChC;AAED,qBAAa,eAAe;IACjB,aAAa,4BAAkC;IAC/C,mBAAmB,4BAAkC;IAE5D,OAAO,CAAC,oBAAoB,CAAsC;IAClE,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,iBAAiB,CAAyB;gBAG9C,UAAU,EAAE,gBAAgB,EAAE;IA8BlC,OAAO,CAAC,mCAAmC;IAmE3C,OAAO,CAAC,sBAAsB;IAU9B,SAAS,IAAI,qBAAqB;IAQlC,qCAAqC,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM;IAI5F,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI7D,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;CAGxE"}
+{"version":3,"file":"ActivityManager.d.ts","sourceRoot":"","sources":["../../../../src/builtins/interaction/activity/ActivityManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAqE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC1H,OAAO,EAA8B,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAG1G,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,eAAO,MAAM,eAAe,eAAe,CAAA;AAE3C,eAAO,MAAM,mBAAmB,gBAwB9B,CAAA;AAEF,eAAO,MAAM,2BAA2B,kBAOtC,CAAA;AAEF,MAAM,WAAW,qBAAqB;IAClC,YAAY,EAAE,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAA;IAC7C,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAChC;AAED,qBAAa,eAAe;IACjB,aAAa,4BAAkC;IAC/C,mBAAmB,4BAAkC;IAE5D,OAAO,CAAC,oBAAoB,CAAsC;IAClE,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,iBAAiB,CAAyB;gBAG9C,UAAU,EAAE,gBAAgB,EAAE;IA8BlC,OAAO,CAAC,mCAAmC;IAoE3C,OAAO,CAAC,sBAAsB;IAU9B,SAAS,IAAI,qBAAqB;IAQlC,qCAAqC,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM;IAI5F,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI7D,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;CAGxE"}