interaqt 1.5.7 → 1.5.8

package/agent/.claude/agents/bug-fix-handler.md

@@ -27,6 +27,7 @@ This agent assumes the following project structure (configurable):
 - Use Transform computations with `eventDeps` for creating entities/relations from interactions
 - Always use `.name` property when querying entities/relations (never hardcode strings)
 - Properties can have `defaultValue` OR `computation`, but not both
+- Scoped serial numbers must use `ScopedSequence` on a number property plus a matching `UniqueConstraint`; never fix them with `StateMachine`, raw SQL, or `max + 1`
 - Timestamp properties must use seconds: `Math.floor(Date.now()/1000)`
 - Always specify `attributeQuery` parameter in storage queries
 - For relations: use dot notation in matchExpression (`source.id`) and nested queries in attributeQuery

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

@@ -118,6 +118,7 @@ git commit -m "feat: Task 3.1.1 - Setup module file and register in index"
   - **IMPORTANT: If a property will have `computed` or `computation`, do NOT set `defaultValue`**
     - The computation will provide the value, defaultValue would conflict
     - Either use defaultValue OR computation, never both
+    - For future scoped serial numbers, create the primitive scope fields now, but leave the serial property without `defaultValue`; `ScopedSequence` will be attached in the computation phase
 - [ ] Generate all relations with proper cardinality
   - Relations define how entities connect
   - Relations create the property names for accessing related entities

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

@@ -180,6 +180,8 @@ color: blue
      })
    - Remove any `defaultValue` if adding computation to that property
    - Never use Transform in Property computation
+   - Use `ScopedSequence` for scoped serial numbers (for example project + prefix + serialNumber). Do not generate `StateMachine`, `Custom`, raw SQL, or `max + 1` logic for this case.
+   - When generating `ScopedSequence`, ensure the property is `type: 'number'`, scope fields are already present on the created record, and a `UniqueConstraint` covers scope fields plus the sequence property.
    - For `_owner` properties, always set them in the owner's creation/derivation logic
 
 2. **Type Check**

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

@@ -263,15 +263,16 @@ Before starting any checks, create a comprehensive checklist document in `docs/{
 - [ ] ERROR_CI_015: Test not checking all `ownerProperties` after entity creation
 - [ ] ERROR_CI_016: Test not verifying all `createdWithRelations` were created
 - [ ] ERROR_CI_017: StateMachine test not covering all StateTransfer transitions
-- [ ] ERROR_CI_018: Type check not run before running tests
-- [ ] ERROR_CI_019: Tests marked as completed but actually failing
-- [ ] ERROR_CI_020: Tests skipped with `.skip()` or `.todo()`
-- [ ] ERROR_CI_021: More than 10 fix attempts made without stopping
-- [ ] ERROR_CI_022: Error document not created in `docs/errors/` after repeated failures
-- [ ] ERROR_CI_023: `lastError` field not updated in implementation plan after failure
-- [ ] ERROR_CI_024: Item marked `completed: true` but tests still failing
-- [ ] ERROR_CI_025: **CRITICAL**: Computation uses mock/placeholder data instead of complete implementation
-- [ ] ERROR_CI_026: **CRITICAL**: Computation contains side effects (email, AI calls, etc.) that should be in integration
+- [ ] ERROR_CI_018: Scoped serial number implemented with StateMachine/Custom/raw SQL/max+1 instead of ScopedSequence
+- [ ] ERROR_CI_019: Type check not run before running tests
+- [ ] ERROR_CI_020: Tests marked as completed but actually failing
+- [ ] ERROR_CI_021: Tests skipped with `.skip()` or `.todo()`
+- [ ] ERROR_CI_022: More than 10 fix attempts made without stopping
+- [ ] ERROR_CI_023: Error document not created in `docs/errors/` after repeated failures
+- [ ] ERROR_CI_024: `lastError` field not updated in implementation plan after failure
+- [ ] ERROR_CI_025: Item marked `completed: true` but tests still failing
+- [ ] ERROR_CI_026: **CRITICAL**: Computation uses mock/placeholder data instead of complete implementation
+- [ ] ERROR_CI_027: **CRITICAL**: Computation contains side effects (email, AI calls, etc.) that should be in integration
 
 **Check Results**: [To be filled]
 

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

@@ -138,6 +138,7 @@ When analyzing properties in `docs/{module}.data-design.json`:
 - [ ] Create analysis document at `docs/{module}.computation-analysis.json`
 - [ ] Analyze each entity systematically (creation source, update requirements, deletion strategy)
 - [ ] Analyze each property individually (type, purpose, data source, update frequency)
+- [ ] Use `ScopedSequence` for scoped serial/order-number properties; do not model them as StateMachine counters or Custom computations
 - [ ] Analyze each relation's complete lifecycle (creation, updates, deletion)
 - [ ] Select appropriate computation type based on decision trees
 - [ ] Document reasoning for each computation decision

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

@@ -1560,6 +1560,65 @@ const lastRecomputeTime = await system.storage.dict.get(lastRecomputeTimeKey);
 const nextRecomputeTime = await system.storage.dict.get(nextRecomputeTimeKey);
 ```
 
+### ScopedSequence.create()
+
+Create a transactional scoped sequence allocator for a number property. Use it for serial numbers that must be unique inside a declared business scope.
+
+**Syntax**
+```typescript
+ScopedSequence.create(config: ScopedSequenceConfig): ScopedSequenceInstance
+```
+
+**Parameters**
+- `config.name` (string, required): Sequence name, must match `/^[a-zA-Z0-9_]+$/`
+- `config.scope` (array, required): Ordered scope items:
+  - Primitive: `{ name, type: 'string' | 'number' | 'boolean', path }`
+  - Reference: `{ name, type: 'ref', base: EntityInstance, path }`
+- `config.initialValue` (number, optional): Defaults to `0`; first automatic allocation returns `initialValue + step`
+- `config.step` (positive integer, optional): Defaults to `1`
+- `config.allowManualValue` (boolean, optional): Defaults to `false`; if true, provided values are preserved and do not advance the counter
+- `config.initializeFrom` (optional): Migration seed declaration `{ record, valuePath, scope, aggregate: 'max' }`
+
+**Example**
+```typescript
+const assetSerial = ScopedSequence.create({
+    name: 'projectAssetSerial',
+    scope: [
+        { name: 'project', type: 'ref', base: Project, path: 'project' },
+        { name: 'prefix', type: 'string', path: 'prefix' }
+    ]
+})
+
+const Media = Entity.create({
+    name: 'Media',
+    properties: [
+        Property.create({ name: 'project', type: 'id' }),
+        Property.create({ name: 'prefix', type: 'string' }),
+        Property.create({
+            name: 'serialNumber',
+            type: 'number',
+            computation: assetSerial
+        })
+    ],
+    constraints: [
+        UniqueConstraint.create({
+            name: 'uniqMediaProjectPrefixSerial',
+            properties: ['project', 'prefix', 'serialNumber']
+        })
+    ]
+})
+```
+
+**Generation rules**
+- Only place `ScopedSequence` on `Property.computation`, and only when the property type is `number`.
+- Do not add `defaultValue` to the same property.
+- Do not use a non-null insert-time constraint for the sequence property; allocation is post-create/pre-commit.
+- Scope paths must read stable primitive/ref values already present on the created host record.
+- Do not use relation traversal, database queries, or another post-create computation as scope input.
+- Always add a `UniqueConstraint` over the scope fields plus the allocated property.
+- Do not generate `StateMachine`, `Custom`, raw SQL, or `max + 1` logic for scoped serial numbers.
+- For existing data, use `initializeFrom` to seed every existing scope with `MAX(valuePath)`. Do not partial-seed with `initializeFrom.match` unless the sequence will only ever allocate for that exact subset.
+
 ### Custom.create()
 
 Create custom computation with completely user-defined calculation logic.

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

@@ -73,7 +73,7 @@ Check `lifecycle.creation` and `lifecycle.deletion`:
 
 **🔴 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
+- Properties must use: _owner, StateMachine, ScopedSequence, 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:
@@ -92,6 +92,7 @@ Analyze the property's `dataDependencies`, `interactionDependencies`, and `compu
 | Condition | Computation Decision |
 |-----------|---------------------|
 | `calculationMethod` contains "sum of", "count of", "aggregate", or involves Record entities | `Custom` or aggregation (e.g., balance = sum(deposits) - sum(withdrawals)) |
+| Needs a serial/order number scoped by other record fields (e.g. project + prefix) | `ScopedSequence` |
 | 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 |

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

@@ -570,9 +570,10 @@ import { Custom, Dictionary, GlobalBoundState, Entity, Property, Relation } from
 Before using Custom computation, ask yourself:
 1. Can I use Transform for entity/relation creation? → Use Transform
 2. Can I use StateMachine for updates? → Use StateMachine
-3. Can I use Count/Summation/Every/Any for aggregations? → Use those
-4. Can I use computed/getValue for simple calculations? → Use those
-5. Can I combine existing computations? → Combine them
+3. Do I need a scoped serial number allocated on create? → Use ScopedSequence
+4. Can I use Count/Summation/Every/Any for aggregations? → Use those
+5. Can I use computed/getValue for simple calculations? → Use those
+6. Can I combine existing computations? → Combine them
 
 **Only use Custom when:**
 - You need complex business logic that doesn't fit ANY existing computation type
@@ -741,6 +742,50 @@ When using `type: 'property'` with Custom computation:
 
 **Remember:** The power of interaqt comes from its declarative computations. Custom computation breaks this paradigm and should only be used when absolutely necessary. Always try to express your logic using the standard computation types first!
 
+### 4. ScopedSequence - Scoped Atomic Serial Numbers
+
+Use `ScopedSequence` when a property should receive the next number within a declared business scope during record creation.
+
+```typescript
+import { Entity, Property, ScopedSequence, UniqueConstraint } from 'interaqt';
+
+const Asset = Entity.create({
+  name: 'Asset',
+  properties: [
+    Property.create({ name: 'project', type: 'id' }),
+    Property.create({ name: 'prefix', type: 'string' }),
+    Property.create({
+      name: 'serialNumber',
+      type: 'number',
+      computation: ScopedSequence.create({
+        name: 'projectAssetSerial',
+        scope: [
+          { name: 'project', type: 'ref', base: Project, path: 'project' },
+          { name: 'prefix', type: 'string', path: 'prefix' },
+        ],
+      }),
+    }),
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'uniqAssetProjectPrefixSerial',
+      properties: ['project', 'prefix', 'serialNumber'],
+    }),
+  ],
+});
+```
+
+Generation rules:
+
+- Only generate `ScopedSequence` on a `number` property.
+- Do not add `defaultValue` to the same property.
+- Ensure every scope path is present on the new host record before allocation. Populate scope inputs in the Transform/interaction data that creates the host record.
+- Do not derive the scope from relation traversal or a query.
+- Do not generate `StateMachine`, `Custom`, raw SQL, or `max + 1` allocation for scoped serials.
+- Always generate a `UniqueConstraint` covering scope fields plus the allocated property.
+- If existing rows already have serial values, add `initializeFrom` so migration can seed `MAX(serialNumber)` per scope.
+- Do not use `initializeFrom.match` for partial seeding unless the sequence property will only allocate for that exact subset forever.
+
 ## Implementation Steps
 
 ### Step 1: Entity Creation Pattern

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

@@ -374,7 +374,7 @@ Search `requirements/{module}.interactions-design.json` (using the module name f
 Transform the computation description using semantic best practices:
 - **Don't copy directly** from `requirements/{module}.data-concepts.json`
 - Apply the "Best Practices for Computation Design" principles
-- Use semantic computations (Count, Every, Any, Summation, etc.) where possible
+- Use semantic computations (Count, Every, Any, Summation, ScopedSequence, etc.) where possible
 - Decompose complex calculations into intermediate properties
 - Make the computation intent clear and implementation-ready
 

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

@@ -182,6 +182,13 @@ type RecordMutationEvent = {
 - **Effects are useful for**: Getting auto-generated IDs, tracking all mutations in complex interactions, debugging what changed
 - **Storage queries are better for**: Verifying computed properties, checking related data, confirming final state
 
+**ScopedSequence testing:**
+- Create records through `controller.dispatch` / `controller.callInteraction`, not direct `storage.create`, so the post-create/pre-commit allocator runs.
+- Verify first value semantics (`initialValue + step`), independent scopes, manual value rejection, and uniqueness.
+- For rollback/delete behavior, assert the next successful allocation follows the documented transactional counter semantics.
+- For existing data migration, assert every existing scope is seeded to `MAX(serialNumber)` and the next allocation returns `max + step`.
+- For PostgreSQL release coverage, run `INTERAQT_POSTGRES_DATABASE=interaqt_test npm run test:postgres-scoped-sequence`.
+
 #### 🔴 IMPORTANT: Use Storage APIs for Verification
 When testing interactions, **directly use storage.find/findOne to verify results**. DO NOT create query interactions just for testing purposes:
 

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

@@ -83,12 +83,58 @@ Reactive computation is a **declarative way of defining data**:
 
 ### 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.
+Built-in computations such as Count, Summation, Average, Every, Any, WeightedSummation, StateMachine, ScopedSequence, and data-based Transform use atomic state updates, row locks, unique indexes, or scoped sequence rows 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.
 
+### Scoped Atomic Sequences
+
+Use `ScopedSequence` for per-scope serial numbers such as "next media number per project and prefix". This is a property computation, not a service call and not a `StateMachine(lastValue + 1)`.
+
+```typescript
+import { Entity, Property, ScopedSequence, UniqueConstraint } from 'interaqt'
+
+const assetSerial = ScopedSequence.create({
+  name: 'projectAssetSerial',
+  scope: [
+    { name: 'project', type: 'ref', base: Project, path: 'project' },
+    { name: 'prefix', type: 'string', path: 'prefix' },
+  ],
+})
+
+const Media = Entity.create({
+  name: 'Media',
+  properties: [
+    Property.create({ name: 'project', type: 'id' }),
+    Property.create({ name: 'prefix', type: 'string' }),
+    Property.create({
+      name: 'serialNumber',
+      type: 'number',
+      computation: assetSerial,
+    }),
+  ],
+  constraints: [
+    UniqueConstraint.create({
+      name: 'uniqMediaProjectPrefixSerial',
+      properties: ['project', 'prefix', 'serialNumber'],
+    }),
+  ],
+})
+```
+
+Rules:
+
+- The host property must be `type: 'number'`.
+- Do not set a `defaultValue` on the same property. The allocator supplies the value after the create mutation and before commit.
+- Scope paths can only read stable primitive/ref values already present on the created record.
+- Missing or type-mismatched scope values are errors.
+- `allowManualValue: true` is for import/backfill and does not advance the counter.
+- Existing data migration should use `initializeFrom` to seed every scope with `MAX(serialNumber)`.
+- Keep the `UniqueConstraint`; the allocator prevents normal duplicates, and the constraint is the integrity backstop.
+- PostgreSQL is the production-safe cross-process driver for this feature.
+
 ### Core Principle: Data Existence
 
 In interaqt, all data has its "reason for existence":

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

@@ -149,6 +149,14 @@ 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.
 
+For `ScopedSequence` changes, also run:
+
+```bash
+INTERAQT_POSTGRES_DATABASE=interaqt_test npm run test:postgres-scoped-sequence
+```
+
+Scoped sequence tests must cover allocation through `controller.dispatch`, not direct `storage.create`. Include first-value semantics, multi-scope isolation, manual import behavior, rollback/delete behavior, migration seeding from existing data, and real PostgreSQL two-controller concurrency.
+
 ### Key API Methods
 
 #### 1. Controller APIs

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

@@ -525,6 +525,63 @@ Create a custom computation when built-in computations are not expressive enough
 
 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.
 
+### ScopedSequence.create()
+
+Create a transactional per-scope sequence allocator for a `number` property.
+
+**Syntax**
+```typescript
+ScopedSequence.create(config: ScopedSequenceConfig): KlassInstance<typeof ScopedSequence>
+```
+
+**Parameters**
+- `config.name` (string, required): Sequence name, must match `/^[a-zA-Z0-9_]+$/`
+- `config.scope` (array, required): Ordered scope items. Primitive items use `{ name, type: 'string' | 'number' | 'boolean', path }`; ref items use `{ name, type: 'ref', base: Entity, path }`
+- `config.initialValue` (number, optional): Defaults to `0`; first automatic allocation returns `initialValue + step`
+- `config.step` (positive integer, optional): Defaults to `1`
+- `config.allowManualValue` (boolean, optional): Defaults to `false`; when true, a provided value is preserved and does not advance the counter
+- `config.initializeFrom` (object, optional): Migration seed declaration using `{ record, valuePath, scope, aggregate: 'max' }`
+
+**Examples**
+```typescript
+const assetSerial = ScopedSequence.create({
+    name: 'projectAssetSerial',
+    scope: [
+        { name: 'project', type: 'ref', base: Project, path: 'project' },
+        { name: 'prefix', type: 'string', path: 'prefix' }
+    ],
+    initialValue: 0,
+    step: 1
+})
+
+const Media = Entity.create({
+    name: 'Media',
+    properties: [
+        Property.create({ name: 'project', type: 'id' }),
+        Property.create({ name: 'prefix', type: 'string' }),
+        Property.create({
+            name: 'serialNumber',
+            type: 'number',
+            computation: assetSerial
+        })
+    ],
+    constraints: [
+        UniqueConstraint.create({
+            name: 'uniqMediaProjectPrefixSerial',
+            properties: ['project', 'prefix', 'serialNumber']
+        })
+    ]
+})
+```
+
+**Important semantics**
+- `ScopedSequence` only belongs on `Property.computation`, and the property must be `type: 'number'`.
+- It is post-create/pre-commit, not an insert-time database default. Do not combine it with a non-null insert-time requirement.
+- Scope paths must read stable values already present on the newly created host record.
+- Keep a `UniqueConstraint` over scope fields plus the sequence property.
+- PostgreSQL is production-safe for cross-connection allocation; PGLite and SQLite are local/test-level only.
+- Existing data migrations must seed every future allocation scope. Do not use `initializeFrom.match` to seed only part of a sequence that will allocate for all host rows.
+
 ### StateMachine.create()
 
 Create state machine computation.

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

@@ -32,6 +32,7 @@ import {
   Summation,
   WeightedSummation,
   Transform,
+  ScopedSequence,
   StateMachine,
   StateNode,
   StateTransfer,
@@ -154,6 +155,7 @@ import {
   Summation,
   WeightedSummation,
   Transform,
+  ScopedSequence,
   StateMachine,
   StateNode,
   StateTransfer
@@ -200,8 +202,10 @@ 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. `ScopedSequence` is production-safe for cross-connection/cross-process allocation on PostgreSQL; PGLiteDB and SQLiteDB are local/test-level only for scoped sequence concurrency.
 
 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.
+7. **Constraint helpers**: `UniqueConstraint`, `ConstraintViolationError`, `ConstraintSetupError`, `findConstraintViolationError`, and `normalizeDatabaseError` are exported for schema-level uniqueness and stable duplicate handling.
+
+8. **Scoped serial allocation**: `ScopedSequence` is exported for number property computations that allocate per-scope serials. Always pair it with a `UniqueConstraint` over the scope fields plus the sequence property.

package/agent/agentspace/knowledge/usage/19-common-anti-patterns.md

@@ -255,6 +255,44 @@ StateMachine.create({
 });
 ```
 
+### ❌ Using StateMachine or max+1 for Scoped Serial Numbers
+
+```javascript
+// ❌ WRONG: not safe across PostgreSQL connections
+Property.create({
+  name: 'serialNumber',
+  type: 'number',
+  computation: StateMachine.create({
+    // lastValue + 1 is per-record state logic, not a transactional scoped counter
+  })
+});
+
+// ❌ WRONG: "SELECT MAX(serialNumber) + 1" races under concurrency
+async function allocateSerial(projectId, prefix) {
+  const max = await db.query('select max(serialNumber) ...');
+  return max + 1;
+}
+```
+
+```javascript
+// ✅ CORRECT: declare the allocation as a property computation
+const serial = ScopedSequence.create({
+  name: 'projectAssetSerial',
+  scope: [
+    { name: 'project', type: 'ref', base: Project, path: 'project' },
+    { name: 'prefix', type: 'string', path: 'prefix' }
+  ]
+});
+
+Property.create({
+  name: 'serialNumber',
+  type: 'number',
+  computation: serial
+});
+```
+
+Always pair `ScopedSequence` with a `UniqueConstraint` over the scope fields plus the sequence property. For existing data, seed every scope through migration `initializeFrom`; do not partially seed a sequence that will later allocate for all host rows.
+
 ## 6. Testing Mistakes
 
 ### ❌ Using try-catch for Error Testing

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

@@ -8,6 +8,7 @@ interaqt now uses PostgreSQL as the concurrency coordinator for multi-process de
 
 - 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_`.
+- `ScopedSequence` uses an internal `_ScopedSequence_` table plus transactional `INSERT ... ON CONFLICT ... DO UPDATE ... RETURNING` to allocate per-scope serial numbers safely across controllers and processes.
 - Custom computations default to retryable `SERIALIZABLE` execution.
 - Async return handling runs in a retryable transaction and applies freshness checks.
 
@@ -79,6 +80,28 @@ 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.
 
+## ScopedSequence Atomic Counters
+
+Use `ScopedSequence` when a number property needs a unique serial inside a business scope, for example `project + prefix + serialNumber`.
+
+Key semantics:
+
+- Allocation happens after the host record create mutation and before the dispatch transaction commits.
+- First automatic value is `initialValue + step`.
+- Rollback rolls back the sequence increment because counter state and business writes share the same transaction.
+- Deleting a record does not decrement the counter.
+- Manual values are rejected unless `allowManualValue: true`.
+- `allowManualValue: true` is for import/backfill only and does not advance the counter.
+- Keep a `UniqueConstraint` over the scope fields and allocated property as the database integrity backstop.
+- PostgreSQL is the production-safe driver for cross-connection/cross-process allocation. PGLite and SQLite are test/local single-process options only.
+
+Migration rules:
+
+- Adding or changing a `ScopedSequence` is not an ordinary recompute. Approve it as unrebuildable plus a scoped sequence seed/no-seed decision.
+- Use `initializeFrom` to seed counters from existing values with `MAX(valuePath)` per scope.
+- Do not partial-seed with `initializeFrom.match` when future allocations cover all host rows; otherwise unseeded existing scopes can later collide.
+- Removing a declared `ScopedSequence` must be reviewed explicitly. Do not silently drop the declaration from the manifest while leaving internal counter state behind.
+
 ## Transaction API
 
 Use callback transactions:
@@ -103,3 +126,11 @@ 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.
+
+For `ScopedSequence`, also run:
+
+```bash
+INTERAQT_POSTGRES_DATABASE=interaqt_test npm run test:postgres-scoped-sequence
+```
+
+This is the critical acceptance test for cross-controller scoped counter allocation.

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

@@ -142,7 +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
+21. [PostgreSQL Concurrency Migration](./20-postgresql-concurrency-migration.md) - Retry, async, PostgreSQL ids, and ScopedSequence migration notes
 
 ## 📞 Need Help?
 

package/agent/skill/interaqt-migration.md

@@ -15,6 +15,8 @@ Phase 1.5 uses a two-step review workflow:
 
 Migration supports additive schema changes, changed/new computation recompute, downstream propagation, filtered membership rebuild, destructive-scope review, post-backfill constraint verification, and explicit fact-to-computation takeover.
 
+`ScopedSequence` is migration-managed state, not a recomputable derivation. Adding or changing a scoped sequence requires an explicit seed/no-seed decision, and removing a scoped sequence declaration must be treated as an explicit migration review item because existing `_ScopedSequence_` counter rows are internal state and must not be silently discarded.
+
 Phase 1.5 does not guess or execute rename/copy/merge/split primitives. Rename candidates may be recorded for review, but compute-route migration will still obey physical layout and destructive-change safety gates.
 
 ---
@@ -275,6 +277,54 @@ Review checklist for takeover:
 
 ---
 
+## ScopedSequence Migration
+
+`ScopedSequence` allocates transactional per-scope counters for number properties. It is intentionally not full-recomputable: migration must seed or explicitly approve empty-state initialization instead of calling the computation for existing rows.
+
+When adding a `ScopedSequence` to an existing property:
+
+```typescript
+Property.create({
+  name: 'serialNumber',
+  type: 'number',
+  computation: ScopedSequence.create({
+    name: 'projectAssetSerial',
+    scope: [
+      { name: 'project', type: 'ref', base: Project, path: 'project' },
+      { name: 'prefix', type: 'string', path: 'prefix' },
+    ],
+    initializeFrom: {
+      record: Media,
+      valuePath: 'serialNumber',
+      scope: [
+        { name: 'project', path: 'project' },
+        { name: 'prefix', path: 'prefix' },
+      ],
+      aggregate: 'max',
+    },
+  }),
+})
+```
+
+Review rules:
+
+- Approve the normal computation review as `decision: 'unrebuildable'`.
+- If `initializeFrom` is present, approve the matching `scoped-sequence-seed` decision.
+- If `initializeFrom` is absent, approve `scoped-sequence-no-seed` only when the host table is empty and the diff reports `expectedHostCount: 0`.
+- `initializeFrom.valuePath` must match the target property and every matched existing row must have a valid numeric value.
+- Seed every existing scope that the future property will allocate for. Do not use `initializeFrom.match` to seed only a subset while leaving other existing scopes with unseeded serials.
+- Keep a database `UniqueConstraint` over the scope fields and sequence property.
+- Changing `scope`, `initialValue`, `step`, `allowManualValue`, or initializer policy changes the allocation signature and requires explicit review.
+- Removing a declared `ScopedSequence` must be reviewed explicitly; do not treat it as a harmless removed computation.
+
+Testing rules:
+
+- PGLite/SQLite are useful for local migration tests, but the production gate is real PostgreSQL.
+- Run `npm run test:postgres-scoped-sequence` when scoped sequence allocation or migration behavior changes.
+- For existing-data migration, test that the next allocation returns `max(existingSerial) + step` for every scope.
+
+---
+
 ## Event and Async Handlers
 
 Event-based computations without full compute support require external rebuild handlers.
@@ -322,6 +372,8 @@ Approved diff cannot bypass core safety gates:
 - Fact destructive schema changes remain blocked.
 - Entity/relation output replacement still needs previous manifest ownership proof.
 - Fact-to-computation takeover requires explicit `computation-takeover` approval and, for entity/relation targets, exact destructive-scope approval.
+- ScopedSequence additions/changes require explicit seed/no-seed review and are not ordinary recompute changes.
+- ScopedSequence removals require explicit review before the declaration disappears from the manifest.
 - Async computations require an approved async completion decision and runtime handler.
 - Event-based computations without full compute require an approved event rebuild decision and runtime handler.
 - Destructive computed output requires exact approved ids.
@@ -412,10 +464,11 @@ This phase does not support converting handwritten properties to `StateMachine`
 - [ ] Review logical model changes, storage changes, function hashes/text, required decisions, and safety output.
 - [ ] Add one explicit decision for every required decision.
 - [ ] For fact-to-computation takeover, approve both `computation-takeover` and the matching `computation: changed` decision.
+- [ ] For ScopedSequence changes, approve `computation: unrebuildable` plus matching seed/no-seed decisions, and verify every existing scope is seeded.
 - [ ] For entity/relation takeover, approve the exact destructive ids and rerun dry-run if the database changed.
 - [ ] Provide runtime handlers for event rebuild and async completion decisions.
 - [ ] Run `controller.migrate({ approvedDiff, dryRun: true, handlers })`.
 - [ ] Confirm `blockingChanges` is empty and `rebuildPlan` is expected.
 - [ ] Confirm destructive scopes match exactly when cleanup is intentional.
 - [ ] Run `controller.migrate({ approvedDiff, handlers })`.
-- [ ] Run integration tests for the production driver, especially PostgreSQL/MySQL.
+- [ ] Run integration tests for the production driver, especially PostgreSQL/MySQL. For ScopedSequence, run `npm run test:postgres-scoped-sequence`.