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

package/CHANGELOG.md

@@ -3,190 +3,6 @@
 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
-
-* **core:** an operation returns the errors it declares, and nothing else ([1c2b819](https://github.com/toa-io/toa/commit/1c2b8193ae7fbe86bc1a25053a6044ee4dd16a4a))
-* **storages:** take `Maybe` from core, not from the deprecated package ([bcaeeb3](https://github.com/toa-io/toa/commit/bcaeeb3c76c89af34e94ff569a210d21b7e87f64))
-
-### Features
-
-* **extensions:** an extension declares what it puts on a component's context ([133bc2a](https://github.com/toa-io/toa/commit/133bc2aad1e45a2d4aa68a08a5e44ca48d3b7414))
-
-
-# [1.0.0-alpha.282](https://github.com/toa-io/toa/compare/v1.0.0-alpha.281...v1.0.0-alpha.282) (2026-09-03)
-
-### Features
-
-* **core:** a Host for extensions ([6315eac](https://github.com/toa-io/toa/commit/6315eac1e9fb05be472272de06385c54ad5934ce))
-
-
-# [1.0.0-alpha.278](https://github.com/toa-io/toa/compare/v1.0.0-alpha.277...v1.0.0-alpha.278) (2026-09-03)
-
-**Note:** Version bump only for package @toa.io/core
-
-
-
-
-
-# [1.0.0-alpha.277](https://github.com/toa-io/toa/compare/v1.0.0-alpha.276...v1.0.0-alpha.277) (2026-09-03)
-
-### Bug Fixes
-
-* read a manifest the way js-yaml read one before ([fcea1b2](https://github.com/toa-io/toa/commit/fcea1b21996d6efa6c3198acbfc9f70f1ce0c35c))
-* settle what the module loader made asynchronous ([d4ab9df](https://github.com/toa-io/toa/commit/d4ab9dfb09e382da311dba08f52214e7645f4a6c))
-
-
-# [1.0.0-alpha.273](https://github.com/toa-io/toa/compare/v1.0.0-alpha.272...v1.0.0-alpha.273) (2026-09-02)
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
 
 **Note:** Version bump only for package @toa.io/core
-
-
-
-
-
-# [1.0.0-alpha.272](https://github.com/toa-io/toa/compare/v1.0.0-alpha.271...v1.0.0-alpha.272) (2026-09-01)
-
-
-### Bug Fixes
-
-* **core:** stop the reply contract from relaxing the declaration ([6222893](https://github.com/toa-io/toa/commit/622289326630b94deff93499d6a851bfaa57c69a))
-
-
-* feat(atomicity)!: take a quorum of independent servers ([862562f](https://github.com/toa-io/toa/commit/862562f24d77ec00127dbbd88d43802b208c643b))
-* refactor(atomicity)!: take the lock manager from the stash ([4fd91eb](https://github.com/toa-io/toa/commit/4fd91eb2fdb68f7b87aaf16d182794bbc567ba57))
-* refactor(core)!: pump the outbox in one cycle ([bf590fe](https://github.com/toa-io/toa/commit/bf590fe8ed59c701b5fd1a91ba4874685b79242f))
-* refactor(atomicity)!: make the connector a family, not a partitioner ([06fd63a](https://github.com/toa-io/toa/commit/06fd63ad6296b724ef83afccf4e4e25d0bcaf080))
-* refactor(atomicity)!: rename the connector and free it of the outbox ([21f1a41](https://github.com/toa-io/toa/commit/21f1a41aceafcfd35c7620014062fe46b54afa95))
-* feat(core)!: commit events with the state that produced them ([1eb68cc](https://github.com/toa-io/toa/commit/1eb68cc435dbfa03faa16009fceb866693d22e1a)), closes [#20](https://github.com/toa-io/toa/issues/20)
-
-
-### Features
-
-* **atomicity:** meter what the group has spent ([bb1118a](https://github.com/toa-io/toa/commit/bb1118aa60bfeb43d3212f2495b7797445f003c3))
-* **core:** give every component an atom aspect ([b501b9c](https://github.com/toa-io/toa/commit/b501b9cd3d5f5408d9faa71213e953fe2792cf9f))
-
-
-### BREAKING CHANGES
-
-* `atomicity.redis` accepts a list again, of independent servers rather
-than cluster nodes, and refuses an even number of them.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `context.stash.lock` is gone; lock through `context.atom` instead.
-A stash pointer resolving to several addresses now uses the first.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `Storage.outbox.pending` takes a fourth argument, the id to
-continue from.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `Factory.partition(group)` is `Factory.atom(group)`, and the
-`Partition` it returned is an `Atom`. `slots(total)` is unchanged.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `@toa.io/partitions.redis` is now `@toa.io/atomicity`, and its
-`lanes(total)` is `slots(total)`. Redis is declared as `atomicity` in the context
-rather than `outbox.redis`, and read from `TOA_ATOMICITY_REDIS`.
-`TOA_OUTBOX_PARTITION_INTERVAL` is `TOA_ATOMICITY_INTERVAL`.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-* `event.changeset` is removed; use `origin` and `state`. `State`
-takes an `Outbox` in place of an `Emission`. `difference` is dropped from
-`@toa.io/generic` along with its last caller.
-
-Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
-
-
-
-
-
-# [1.0.0-alpha.270](https://github.com/toa-io/toa/compare/v1.0.0-alpha.269...v1.0.0-alpha.270) (2026-08-31)
-
-
-### Bug Fixes
-
-* **core:** apply the input default on a remote call ([341699b](https://github.com/toa-io/toa/commit/341699b26c9299963a898368671633a9b3fb97ed))
-
-
-### Performance Improvements
-
-* **core:** do not snapshot a record an operation cannot commit ([a5e695b](https://github.com/toa-io/toa/commit/a5e695b0b1d4b00a91e40336deecd476c9646c89))
-* **core:** keep the parsed criteria of a query ([7efc694](https://github.com/toa-io/toa/commit/7efc694814c2a071ae7e48dbf1c6014db6025a9f))
-* stop rebuilding per-call values that never change ([4202504](https://github.com/toa-io/toa/commit/4202504c33fb9ef9694f9995f3d0397d3a186438))
-
-
-
-
-
-# [1.0.0-alpha.266](https://github.com/toa-io/toa/compare/v1.0.0-alpha.265...v1.0.0-alpha.266) (2026-08-29)
-
-
-### Bug Fixes
-
-* **core:** say a connector is disconnected once it has closed, not before ([d67b48e](https://github.com/toa-io/toa/commit/d67b48eaafaacd5c635d8b066413f84b8e6a3771))
-
-
-
-
-
-# [1.0.0-alpha.265](https://github.com/toa-io/toa/compare/v1.0.0-alpha.264...v1.0.0-alpha.265) (2026-08-29)
-
-
-### Features
-
-* **bridges.node:** add the dispose run command phase ([00df715](https://github.com/toa-io/toa/commit/00df7158f638b976ab09d4007102a4ead3c696c3))
-
-
-
-
-
-# [1.0.0-alpha.264](https://github.com/toa-io/toa/compare/v1.0.0-alpha.263...v1.0.0-alpha.264) (2026-08-29)
-
-**Note:** Version bump only for package @toa.io/core
-
-
-
-
-
-# [1.0.0-alpha.262](https://github.com/toa-io/toa/compare/v1.0.0-alpha.261...v1.0.0-alpha.262) (2026-08-28)
-
-
-### Features
-
-* **core:** identify the origin of a call with `request.source` ([9da6b66](https://github.com/toa-io/toa/commit/9da6b66df852690351a1e82c7b8cc176fd89774a))
-
-
-
-
-
-# [1.0.0-alpha.259](https://github.com/toa-io/toa/compare/v1.0.0-alpha.258...v1.0.0-alpha.259) (2026-08-24)
-
-
-### Features
-
-* **runtime:** split component RC into preflight and settle ([0d648b3](https://github.com/toa-io/toa/commit/0d648b314e4aac226c254bf01a86affa04b59b34))
-
-
-
-
-
-# [1.0.0-alpha.257](https://github.com/toa-io/toa/compare/v1.0.0-alpha.256...v1.0.0-alpha.257) (2026-08-24)
-
-
-### Bug Fixes
-
-* **core:** lift tombstone on commit when transition leaves it untouched ([38c0d15](https://github.com/toa-io/toa/commit/38c0d15e946c3e2d559d4b18aecc33e0fda2471a))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.284",
+  "version": "1.0.0-alpha.287",
   "type": "module",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -12,20 +12,32 @@
   "bugs": {
     "url": "https://github.com/toa-io/toa/issues"
   },
-  "main": "src/index.js",
-  "types": "types/index.ts",
+  "main": "transpiled/index.js",
+  "types": "transpiled/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./transpiled/index.d.ts",
+      "default": "./transpiled/index.js"
+    },
+    "./types": {
+      "types": "./transpiled/types/index.d.ts",
+      "default": "./transpiled/types/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "transpile": "tsc",
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
     "@rsql/parser": "1.6.0",
-    "@toa.io/generic": "1.0.0-alpha.283",
-    "js-yaml": "5.4.1",
-    "openspan": "1.0.0-alpha.277",
+    "@toa.io/generic": "1.0.0-alpha.286",
+    "@toa.io/schemas": "1.0.0-alpha.287",
+    "openspan": "1.0.0-alpha.286",
     "uuid": "14.0.2"
   },
-  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf"
+  "gitHead": "5c7944a70c16065ab6372072385cc1f02f5db77c"
 }

package/source/assignment.ts

@@ -0,0 +1,27 @@
+import { Operation } from './operation.js'
+import type { Store } from './operation.js'
+import type { Changeset } from './entities/changeset.js'
+
+export class Assignment extends Operation {
+  protected override async acquire(store: Store): Promise<void> {
+    const changeset = this.scope.changeset(store.request.query as any)
+
+    store.scope = changeset
+    store.state = changeset.get()
+  }
+
+  protected override async commit(store: Store): Promise<void> {
+    const { scope, state, reply, request } = store
+
+    if (reply.error !== undefined) return
+
+    const changeset = scope as Changeset
+
+    changeset.set(state)
+
+    const output = await this.scope.apply(changeset, request.input)
+
+    // assignment returns new state by default
+    if (store.reply.output === undefined) store.reply.output = output
+  }
+}

package/{src/call.js → source/call.ts}

@@ -1,13 +1,16 @@
 import { Readable } from 'node:stream'
 import { current, encode } from 'openspan'
 import { Connector } from './connector.js'
+import type { Transmission } from './transmission.js'
+import type { Request as Contract } from './contract/request.js'
+import type { Request, Source } from './types/request.js'
 
 export class Call extends Connector {
-  #transmitter
-  #contract
-  #source
+  readonly #transmitter: Transmission
+  readonly #contract: Contract
+  readonly #source: Source | undefined
 
-  constructor (transmitter, contract, source) {
+  public constructor(transmitter: Transmission, contract: Contract, source?: Source) {
     super()
 
     this.#transmitter = transmitter
@@ -17,15 +20,13 @@ export class Call extends Connector {
     this.depends(transmitter)
   }
 
-  async invoke (request = {}) {
+  public async invoke(request: Request = {}): Promise<any> {
     // the caller may have attributed the call itself, as the node bridge does
-    if (this.#source !== undefined)
-      request.source ??= this.#source
+    if (this.#source !== undefined) request.source ??= this.#source
 
-    // fitting first lets the input schema supply its default;
-    // an operation that takes no input still has to send an explicit null
     this.#contract.fit(request)
 
+    // an operation that takes no input still has to send an explicit null
     request.input ??= null
 
     // avoid validation on the recipient's side
@@ -33,34 +34,28 @@ export class Call extends Connector {
 
     const context = current()
 
-    if (context !== undefined)
-      request.telemetry = encode(context)
+    if (context !== undefined) request.telemetry = encode(context)
 
     const reply = await this.#transmitter.request(request)
 
     if (reply === null) return null
     else if (reply instanceof Readable) return reply
     else {
-      if (reply.exception !== undefined)
-        throw reply.exception
+      if (reply.exception !== undefined) throw reply.exception
 
-      if (reply.error !== undefined)
-        return new RemoteError(reply.error)
-      else
-        return reply.output
+      if (reply.error !== undefined) return new RemoteError(reply.error)
+      else return reply.output
     }
   }
 
-  explain () {
+  public explain(): any {
     return this.#contract.discovery
   }
 }
 
-
-
 // the remote error as a value: every property it carries, and nothing else enumerable
 class RemoteError extends Error {
-  constructor (error) {
+  public constructor(error: object) {
     super()
 
     Object.assign(this, error)

package/{src/cascade.js → source/cascade.ts}

@@ -1,22 +1,20 @@
 import { Connector } from './connector.js'
+import type { Algorithm } from './types/bridges.js'
 
 export class Cascade extends Connector {
-  // #bridges
-  #last
+  readonly #last: Algorithm
 
-  constructor (bridges, preflight) {
+  public constructor(bridges: Algorithm[], preflight?: Connector) {
     super()
 
     // this.#bridges = bridges
     this.#last = bridges[bridges.length - 1]
 
-    if (preflight === undefined)
-      this.depends(bridges)
-    else
-      this.depends(bridges).depends(preflight)
+    if (preflight === undefined) this.depends(bridges)
+    else this.depends(bridges).depends(preflight)
   }
 
-  async run (...args) {
+  public async run(...args: [any, any?]): Promise<any> {
     // const reply = {}
     //
     // for (const bridge of this.#bridges) {

package/{src/component.js → source/component.ts}

@@ -1,20 +1,25 @@
 import assert from 'node:assert'
-import { console, current, decode, run } from 'openspan'
+import { console, current, decode, run, type SpanOptions } from 'openspan'
 import { Connector } from './connector.js'
+import type { Locator } from './locator.js'
+import type { Request } from './types/request.js'
 
-export class Component extends Connector {
-  locator
+/** What a component holds one of per endpoint: an operation, or the call that stands for it. */
+export interface Invocable extends Connector {
+  invoke: (request: Request) => Promise<any>
+}
+
+export class Component<O extends Invocable = Invocable> extends Connector {
+  public readonly locator: Locator
 
-  /** @protected */
-  operations
+  protected readonly operations: Record<string, O>
 
-  /** @protected */
-  kind = 'server'
+  protected kind: 'server' | 'client' = 'server'
 
-  /** @type {Record<string, object>} span options per endpoint */
-  #spans = {}
+  /** span options per endpoint */
+  readonly #spans: Record<string, SpanOptions> = {}
 
-  constructor (locator, operations) {
+  public constructor(locator: Locator, operations: Record<string, O>) {
     super()
 
     this.locator = locator
@@ -23,28 +28,27 @@ export class Component extends Connector {
     Object.values(operations).forEach((operation) => this.depends(operation))
   }
 
-  async invoke (endpoint, request) {
+  public async invoke<T = any>(endpoint: string, request?: Request): Promise<T> {
     if (!(endpoint in this.operations))
       // `assert.fail`, not `assert.ok`: the message is built only when it is needed
       assert.fail(`Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
     // if the request carries no telemetry, the trace starts here
     const remote = request?.telemetry === undefined ? null : decode(request.telemetry)
-    const task = () => this.process(endpoint, request)
+    const task = async (): Promise<any> => this.#process(endpoint, request)
 
-    if (remote === null)
-      return task()
-    else
-      return run(remote, task)
+    if (remote === null) return task()
+    else return run(remote, task)
   }
 
-  /** @private */
-  async process (endpoint, request) {
-    return console.span(this.span(endpoint), async () => {
-      const reply = await this.operations[endpoint].invoke(request)
+  async #process(endpoint: string, request?: Request): Promise<any> {
+    return console.span(this.#span(endpoint), async () => {
+      const reply = await this.operations[endpoint].invoke(request as Request)
 
       if (reply?.exception !== undefined) {
-        current().status = 'error'
+        const span = current()
+
+        if (span !== undefined) span.status = 'error'
 
         console.error('Failed to execute operation', {
           endpoint: `${this.locator.id}.${endpoint}`,
@@ -60,9 +64,8 @@ export class Component extends Connector {
    * The span of an endpoint never changes, so it is built once. Not in the constructor:
    * `kind` is a field of the subclass, and those are assigned after this one is built.
    *
-   * @private
    */
-  span (endpoint) {
+  #span(endpoint: string): SpanOptions {
     let options = this.#spans[endpoint]
 
     if (options === undefined) {
@@ -70,8 +73,7 @@ export class Component extends Connector {
 
       // the server span is emitted by the component itself, while the client span
       // belongs to the calling service and inherits it from the context
-      if (this.kind === 'server')
-        options.service = this.locator.id
+      if (this.kind === 'server') options.service = this.locator.id
 
       this.#spans[endpoint] = options
     }

package/{src/composition.js → source/composition.ts}

@@ -2,7 +2,13 @@ import { console } from 'openspan'
 import { Connector } from './connector.js'
 
 export class Composition extends Connector {
-  constructor (expositions, producers, receivers, tenants) {
+  // eslint-disable-next-line max-params
+  public constructor(
+    expositions: Connector[],
+    producers: Connector[],
+    receivers: Connector[],
+    tenants: Connector[]
+  ) {
     super()
 
     if (expositions.length > 0) this.depends(expositions)
@@ -11,11 +17,11 @@ export class Composition extends Connector {
     if (tenants.length > 0) this.depends(tenants)
   }
 
-  async open () {
+  protected override async open(): Promise<void> {
     console.info('Composition complete')
   }
 
-  async dispose () {
+  protected override async dispose(): Promise<void> {
     console.info('Composition shutdown complete')
   }
 }

package/{src/connector.js → source/connector.ts}

@@ -1,28 +1,17 @@
 import { console } from 'openspan'
+import type { Locator } from './locator.js'
 
-/**
- * Abstract connections hierarchy
- * @implements {toa.core.Connector}
- */
+/** Abstract connections hierarchy */
 export class Connector {
-  /** @type {Array<Connector>} */
-  #dependencies = []
+  #dependencies: Connector[] = []
+  #links: Connector[] = []
+  #connecting: Promise<void> | undefined
+  #disconnecting: Promise<void> | undefined
 
-  /** @type {Array<Connector>} */
-  #links = []
+  public readonly id: string
+  public connected: boolean = false
 
-  /** @type {Promise} */
-  #connecting
-
-  /** @type {Promise} */
-  #disconnecting
-
-  /** @type {string} */
-  id
-  /** @type {boolean} */
-  connected = false
-
-  constructor () {
+  public constructor() {
     this.id = this.constructor.name + '#' + Math.random().toString(36).substring(2, 8)
   }
 
@@ -31,12 +20,9 @@ export class Connector {
    *
    * See .connect() and .disconnect()
    *
-   * @param connector {Connector | any | Array<Connector | any>}
-   * @returns {Connector}
    */
-  depends (connector) {
-    /** @type {Connector} */
-    let next
+  public depends(connector: Connector | Connector[]): Connector {
+    let next: Connector
 
     if (connector instanceof Array) {
       if (connector.length === 0) throw new Error('Connectors array must not be empty')
@@ -62,10 +48,8 @@ export class Connector {
    *
    * See .connect() and .disconnect()
    *
-   * @param connector {Connector}
-   * @returns {void}
    */
-  link (connector) {
+  public link(connector: Connector): void {
     this.#links.push(connector)
   }
 
@@ -76,9 +60,8 @@ export class Connector {
    *
    * Method is idempotent
    *
-   * @returns {Promise<void>}
    */
-  async connect () {
+  public async connect(): Promise<void> {
     if (this.#connecting) return this.#connecting
 
     this.#disconnecting = undefined
@@ -89,12 +72,17 @@ export class Connector {
     }
 
     // anonymous grouping nodes are not worth a span
-    this.#connecting = TRACE_BOOT && this.constructor.name !== 'Connector'
-      ? console.span({
-        name: `connect ${this.constructor.name}`,
-        attributes: { id: this.locator?.id ?? this.id }
-      }, work)
-      : work()
+    this.#connecting =
+      TRACE_BOOT && this.constructor.name !== 'Connector'
+        ? console.span(
+            {
+              name: `connect ${this.constructor.name}`,
+              // a connector that has a locator is named by it; a grouping node has none
+              attributes: { id: (this as { locator?: Locator }).locator?.id ?? this.id }
+            },
+            work
+          )
+        : work()
 
     try {
       await this.#connecting
@@ -112,10 +100,8 @@ export class Connector {
    *
    * Method is idempotent
    *
-   * @param [interrupt] {boolean}
-   * @returns {Promise<void>}
    */
-  async disconnect (interrupt) {
+  public async disconnect(interrupt?: boolean): Promise<void> {
     // a connector that has not finished connecting has nothing to close, and
     // awaiting a connection that may never settle outlives any grace period
     const pending = interrupt === true || this.connected === false
@@ -149,7 +135,7 @@ export class Connector {
 
       clearInterval(interval)
 
-      await Promise.all(this.#dependencies.map(connector => connector.disconnect()))
+      await Promise.all(this.#dependencies.map((connector) => connector.disconnect()))
 
       await this.dispose()
     })()
@@ -157,33 +143,28 @@ export class Connector {
     await this.#disconnecting
   }
 
-  async reconnect () {
+  public async reconnect(): Promise<void> {
     await this.disconnect()
     await this.connect()
   }
 
-  debug (node = {}) {
+  public debug(node: Record<string, any> = {}): Record<string, any> {
     node[this.id] = { connected: this.connected }
 
-    if (this.#dependencies.length > 0) for (const connector of this.#dependencies) connector.debug?.(node[this.id])
+    if (this.#dependencies.length > 0)
+      for (const connector of this.#dependencies) connector.debug?.(node[this.id])
 
     return node
   }
 
-  /**
-   * Called on connection
-   */
-  async open () {}
+  /** Called on connection */
+  protected open(): Promise<void> | void {}
 
-  /**
-   * Called on disconnection
-   */
-  async close () {}
+  /** Called on disconnection */
+  protected close(): Promise<void> | void {}
 
-  /**
-   * Called after self and dependants disconnection is complete
-   */
-  async dispose () {}
+  /** Called after self and dependants disconnection is complete */
+  protected dispose(): Promise<void> | void {}
 }
 
 const DELAY = 5000