@toa.io/core 1.0.0-alpha.283 → 1.0.0-alpha.284

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.284](https://github.com/toa-io/toa/compare/v1.0.0-alpha.283...v1.0.0-alpha.284) (2026-09-05)
+
+### Bug Fixes
+
+* **core:** a criteria list coerces every value in it ([37f57ee](https://github.com/toa-io/toa/commit/37f57ee8b50907a13722b7a558b881cccf105442))
+
+### Features
+
+* an operation states what it is ([b5e2f66](https://github.com/toa-io/toa/commit/b5e2f66c8bf67924e2eaaaa11f283dfb4d810981))
+* **atomicity:** a replica can be told what it owns, not only ask ([f7b56b9](https://github.com/toa-io/toa/commit/f7b56b99cc43313f3f855df658a80fdc0659689e))
+
+
 # [1.0.0-alpha.283](https://github.com/toa-io/toa/compare/v1.0.0-alpha.282...v1.0.0-alpha.283) (2026-09-04)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.283",
+  "version": "1.0.0-alpha.284",
   "type": "module",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -27,5 +27,5 @@
     "openspan": "1.0.0-alpha.277",
     "uuid": "14.0.2"
   },
-  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
+  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf"
 }

package/src/contract/request.js

@@ -9,7 +9,7 @@ export class Request extends Contract {
   constructor (schema, definition) {
     super(schema)
 
-    for (const key of ['input', 'output', 'errors'])
+    for (const key of ['description', 'input', 'output', 'errors'])
       if (definition[key] !== undefined)
         this.discovery[key] = definition[key]
   }

package/src/outbox/outbox.js

@@ -33,6 +33,7 @@ export class Outbox extends Connector {
   #publishing = new Set()
 
   #timer
+  #off
   #pumping = false
   #closing = false
 
@@ -101,11 +102,20 @@ export class Outbox extends Connector {
 
     this.#timer = setInterval(() => this.#tick(), this.#interval)
     this.#timer.unref()
+
+    /*
+     * A lane changing hands is exactly when rows stranded in it become this replica's to
+     * publish, and the cycle would not notice for up to an interval. Being told costs a cycle
+     * that finds nothing in the usual case, where the claim arrives once and never changes.
+     */
+    this.#off = this.#atom.onassigned(() => this.#tick())
   }
 
   async close () {
     this.#closing = true
 
+    this.#off?.()
+
     if (this.#timer !== undefined) clearInterval(this.#timer)
 
     await this.#drain()

package/src/query/criteria.js

@@ -23,7 +23,14 @@ const coerce = (node, properties) => {
       throw new QuerySyntaxException(`Criteria selector '${node.left.selector}' is not defined`)
     }
 
-    if (COERCE[property.type] !== undefined) { node.right.value = COERCE[property.type](node.right.value) }
+    const coerce = COERCE[property.type]
+
+    // `=in=` and `=out=` carry a list, and coercing that as one value gives whatever
+    // `parseInt` makes of a comma-separated string
+    if (coerce !== undefined)
+      node.right.value = Array.isArray(node.right.value)
+        ? node.right.value.map((value) => coerce(value))
+        : coerce(node.right.value)
   } else {
     if (node.left !== undefined) coerce(node.left, properties)
     if (node.right !== undefined) coerce(node.right, properties)

package/test/outbox.test.js

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict'
 
 import { Outbox } from '../src/outbox/index.js'
 
-let emission, storage, atom, outbox
+let emission, storage, atom, outbox, listeners
 
 const BATCH = 4
 
@@ -28,7 +28,18 @@ beforeEach(() => {
     }
   }
 
-  atom = { slots: mock.fn(() => [0]), link: mock.fn() }
+  listeners = []
+
+  atom = {
+    slots: mock.fn(() => [0]),
+    onassigned: (listener) => {
+      listeners.push(listener)
+      listener({ i: 0, n: 1 })
+
+      return () => { listeners = listeners.filter((one) => one !== listener) }
+    },
+    link: mock.fn()
+  }
   outbox = new Outbox(emission, storage, atom, { interval: 1000, batch: BATCH })
 })
 
@@ -36,6 +47,11 @@ afterEach(() => {
   mock.timers.reset()
 })
 
+/** everything the current turn awaited, without moving the clock */
+const settled = async () => {
+  for (let i = 0; i < 20; i++) await Promise.resolve()
+}
+
 /** one cycle, and everything it awaited */
 const cycle = async () => {
   mock.timers.tick(1000)
@@ -119,3 +135,34 @@ function resetCalls (target = [assert, BATCH, page, cycle], seen = new Set()) {
     if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
     else resetCalls(value, seen)
 }
+
+it('should read as soon as a claim arrives, rather than on its next cycle', async () => {
+  atom.slots.mock.mockImplementation(() => null)
+
+  await outbox.open()
+  await settled()
+
+  assert.strictEqual(storage.outbox.pending.mock.callCount(), 0, 'nothing is owned yet')
+
+  atom.slots.mock.mockImplementation(() => [0])
+
+  for (const listener of listeners) listener({ i: 0, n: 1 })
+
+  await settled()
+
+  assert.strictEqual(storage.outbox.pending.mock.callCount(), 1,
+    'the lane is its own now, and the cycle is up to five seconds away')
+})
+
+it('should read the lanes it inherits when the group resizes', async () => {
+  await outbox.open()
+  await settled()
+
+  const before = storage.outbox.pending.mock.callCount()
+
+  for (const listener of listeners) listener({ i: 0, n: 2 })
+
+  await settled()
+
+  assert.strictEqual(storage.outbox.pending.mock.callCount(), before + 1)
+})

package/test/query.test.js

@@ -23,6 +23,13 @@ describe('criteria', () => {
     assert.deepStrictEqual(query.criteria, fixtures.samples.simple.parsed.criteria)
   })
 
+  it('should coerce every value of a list', () => {
+    const instance = new Query({ n: { type: 'integer' } })
+    const query = instance.parse({ criteria: 'n=in=(1,2,3)' })
+
+    assert.deepStrictEqual(query.criteria.right.value, [1, 2, 3])
+  })
+
   it('should keep a parsed criteria', () => {
     const instance = new Query(fixtures.samples.simple.properties)
 

package/types/atomicity.d.ts

@@ -22,6 +22,20 @@ declare namespace toa.core {
        */
       slots (total: number): number[] | null
 
+      /**
+       * Calls `listener` with the assignment this replica holds, and again whenever it
+       * changes — one arrived, was lost, or the group resized. Answers with what removes the
+       * listener again.
+       *
+       * A change and not a heartbeat: a group that stays as it is never calls back. It is
+       * called once as it is added, with the claim as it stands.
+       *
+       * What `slots` cannot say. Reading serves a consumer that asks often, where a stale
+       * answer costs it one cycle; a consumer that asks rarely has to be told, or it samples
+       * the one moment a rollout was passing through and stands down for a whole cycle.
+       */
+      onassigned (listener: (assignment: Assignment | null) => void): () => void
+
       /**
        * Debt the group has run up under each key, in milliseconds. Every call adds its own
        * deltas and reads back where the group stands, so a replica reports what it alone has
@@ -45,6 +59,12 @@ declare namespace toa.core {
         routine: (signal: AbortSignal, context: unknown) => Promise<T>): Promise<T>
     }
 
+    /** Which of the group this replica is, and how many of them there are. */
+    interface Assignment {
+      i: number
+      n: number
+    }
+
     interface Factory {
       /** @param group what the replicas deciding together have in common */
       atom (group: string, options?: object): Atom
@@ -55,4 +75,5 @@ declare namespace toa.core {
 }
 
 export type Atom = toa.core.atomicity.Atom
+export type Assignment = toa.core.atomicity.Assignment
 export type Factory = toa.core.atomicity.Factory

package/types/remote.d.ts

@@ -5,6 +5,7 @@ export class Remote extends Component {
 }
 
 interface Explanation {
+  description?: string
   input: Schema | null
   output: Schema | null
   errors?: string[]