@toa.io/core 1.0.0-alpha.28 → 1.0.0-alpha.282

package/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Change Log
+
+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.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)
+
+**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,7 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.28",
+  "version": "1.0.0-alpha.282",
+  "type": "module",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -20,14 +21,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@rsql/parser": "1.2.4",
-    "@toa.io/console": "1.0.0-alpha.28",
-    "@toa.io/generic": "1.0.0-alpha.28",
-    "@toa.io/yaml": "1.0.0-alpha.28",
-    "error-value": "0.3.0"
+    "@rsql/parser": "1.6.0",
+    "@toa.io/generic": "1.0.0-alpha.282",
+    "js-yaml": "5.4.1",
+    "openspan": "1.0.0-alpha.277",
+    "uuid": "14.0.2"
   },
-  "devDependencies": {
-    "clone-deep": "4.0.1"
-  },
-  "gitHead": "89c3b7d1314e357c9e33df8d95f8d46954cd3bcf"
+  "gitHead": "4007c814725dd015d3bbebb9a28e28a247645c4f"
 }

package/src/assignment.js

@@ -1,8 +1,6 @@
-'use strict'
+import { Operation } from './operation.js'
 
-const { Operation } = require('./operation')
-
-class Assignment extends Operation {
+export class Assignment extends Operation {
   async acquire (store) {
     store.scope = this.scope.changeset(store.request.query)
     store.state = store.scope.get()
@@ -12,14 +10,15 @@ class Assignment extends Operation {
     const {
       scope,
       state,
-      reply
+      reply,
+      request
     } = store
 
     if (reply.error !== undefined) return
 
     scope.set(state)
 
-    const output = await this.scope.apply(scope)
+    const output = await this.scope.apply(scope, request.input)
 
     // assignment returns new state by default
     if (store.reply.output === undefined) {
@@ -27,5 +26,3 @@ class Assignment extends Operation {
     }
   }
 }
-
-exports.Assignment = Assignment

package/src/call.js

@@ -1,28 +1,41 @@
-'use strict'
+import { Readable } from 'node:stream'
+import { current, encode } from 'openspan'
+import { Connector } from './connector.js'
 
-const { Readable } = require('node:stream')
-const { Connector } = require('./connector')
-const { Err } = require('error-value')
-
-class Call extends Connector {
+export class Call extends Connector {
   #transmitter
   #contract
+  #source
 
-  constructor (transmitter, contract) {
+  constructor (transmitter, contract, source) {
     super()
 
     this.#transmitter = transmitter
     this.#contract = contract
+    this.#source = source
 
     this.depends(transmitter)
   }
 
   async invoke (request = {}) {
+    // the caller may have attributed the call itself, as the node bridge does
+    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)
 
+    request.input ??= null
+
     // avoid validation on the recipient's side
     request.authentic = true
 
+    const context = current()
+
+    if (context !== undefined)
+      request.telemetry = encode(context)
+
     const reply = await this.#transmitter.request(request)
 
     if (reply === null) return null
@@ -32,11 +45,24 @@ class Call extends Connector {
         throw reply.exception
 
       if (reply.error !== undefined)
-        return Err(reply.error.code, reply.error)
+        return new RemoteError(reply.error)
       else
         return reply.output
     }
   }
+
+  explain () {
+    return this.#contract.discovery
+  }
 }
 
-exports.Call = Call
+
+
+// the remote error as a value: every property it carries, and nothing else enumerable
+class RemoteError extends Error {
+  constructor (error) {
+    super()
+
+    Object.assign(this, error)
+  }
+}

package/src/cascade.js

@@ -1,19 +1,19 @@
-'use strict'
+import { Connector } from './connector.js'
 
-const { merge } = require('@toa.io/generic')
-const { Connector } = require('./connector')
-
-class Cascade extends Connector {
-  #bridges
+export class Cascade extends Connector {
+  // #bridges
   #last
 
-  constructor (bridges) {
+  constructor (bridges, preflight) {
     super()
 
-    this.#bridges = bridges
+    // this.#bridges = bridges
     this.#last = bridges[bridges.length - 1]
 
-    this.depends(bridges)
+    if (preflight === undefined)
+      this.depends(bridges)
+    else
+      this.depends(bridges).depends(preflight)
   }
 
   async run (...args) {
@@ -32,5 +32,3 @@ class Cascade extends Connector {
     return this.#last.execute(...args)
   }
 }
-
-exports.Cascade = Cascade

package/src/component.js

@@ -1,41 +1,81 @@
-'use strict'
+import assert from 'node:assert'
+import { console, current, decode, run } from 'openspan'
+import { Connector } from './connector.js'
 
-const { console } = require('@toa.io/console')
-const { Connector } = require('./connector')
-const { NotImplementedException } = require('./exceptions')
-
-/**
- * @implements {toa.core.Component}
- */
-class Component extends Connector {
+export class Component extends Connector {
   locator
 
-  #operations
+  /** @protected */
+  operations
+
+  /** @protected */
+  kind = 'server'
+
+  /** @type {Record<string, object>} span options per endpoint */
+  #spans = {}
 
   constructor (locator, operations) {
     super()
 
     this.locator = locator
-    this.#operations = operations
+    this.operations = operations
 
     Object.values(operations).forEach((operation) => this.depends(operation))
   }
 
-  async open () {
-    console.info(`Runtime '${this.locator.id}' connected`)
+  async invoke (endpoint, request) {
+    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)
+
+    if (remote === null)
+      return task()
+    else
+      return run(remote, task)
   }
 
-  async dispose () {
-    console.info(`Runtime '${this.locator.id}' disconnected`)
+  /** @private */
+  async process (endpoint, request) {
+    return console.span(this.span(endpoint), async () => {
+      const reply = await this.operations[endpoint].invoke(request)
+
+      if (reply?.exception !== undefined) {
+        current().status = 'error'
+
+        console.error('Failed to execute operation', {
+          endpoint: `${this.locator.id}.${endpoint}`,
+          exception: reply.exception
+        })
+      }
+
+      return reply
+    })
   }
 
-  async invoke (endpoint, request) {
-    if (!(endpoint in this.#operations)) {
-      throw new NotImplementedException(`Endpoint '${endpoint}' not found in '${this.locator.id}'`)
+  /**
+   * 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) {
+    let options = this.#spans[endpoint]
+
+    if (options === undefined) {
+      options = { name: `${this.locator.id}.${endpoint}`, kind: this.kind }
+
+      // 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
+
+      this.#spans[endpoint] = options
     }
 
-    return this.#operations[endpoint].invoke(request)
+    return options
   }
 }
-
-exports.Component = Component

package/src/composition.js

@@ -1,9 +1,7 @@
-'use strict'
+import { console } from 'openspan'
+import { Connector } from './connector.js'
 
-const { console } = require('@toa.io/console')
-const { Connector } = require('./connector')
-
-class Composition extends Connector {
+export class Composition extends Connector {
   constructor (expositions, producers, receivers, tenants) {
     super()
 
@@ -21,5 +19,3 @@ class Composition extends Connector {
     console.info('Composition shutdown complete')
   }
 }
-
-exports.Composition = Composition

package/src/connector.js

@@ -1,13 +1,10 @@
-'use strict'
-
-const { console } = require('@toa.io/console')
-const { newid } = require('@toa.io/generic')
+import { console } from 'openspan'
 
 /**
  * Abstract connections hierarchy
  * @implements {toa.core.Connector}
  */
-class Connector {
+export class Connector {
   /** @type {Array<Connector>} */
   #dependencies = []
 
@@ -26,7 +23,7 @@ class Connector {
   connected = false
 
   constructor () {
-    this.id = this.constructor.name + '#' + newid().substring(0, 8)
+    this.id = this.constructor.name + '#' + Math.random().toString(36).substring(2, 8)
   }
 
   /**
@@ -86,12 +83,18 @@ class Connector {
 
     this.#disconnecting = undefined
 
-    console.debug(`Connecting '${this.id}' with ${this.#dependencies.length} dependencies...`)
-
-    this.#connecting = (async () => {
+    const work = async () => {
       await Promise.all(this.#dependencies.map((connector) => connector.connect()))
       await this.open()
-    })()
+    }
+
+    // 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()
 
     try {
       await this.#connecting
@@ -100,8 +103,6 @@ class Connector {
       await this.disconnect(true)
       throw e
     }
-
-    console.debug(`Connector '${this.id}' connected`)
   }
 
   /**
@@ -115,7 +116,11 @@ class Connector {
    * @returns {Promise<void>}
    */
   async disconnect (interrupt) {
-    if (interrupt !== true) await this.#connecting
+    // 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
+
+    if (!pending) await this.#connecting
 
     if (this.#disconnecting) return this.#disconnecting
 
@@ -123,19 +128,24 @@ class Connector {
 
     if (linked && interrupt !== true) return
 
-    this.connected = false
-    this.#connecting = undefined
-
     this.#disconnecting = (async () => {
       const start = +new Date()
 
       const interval = setInterval(() => {
         const delay = +new Date() - start
 
-        if (delay > DELAY) console.warn(`Connector ${this.id} still disconnecting (${delay})`)
+        if (delay > DELAY)
+          console.warn(`Connector ${this.id} still disconnecting (${delay})`)
       }, DELAY)
 
-      if (interrupt !== true) await this.close()
+      if (!pending) await this.close()
+
+      // said once the closing is done rather than when it starts: a dependant that is
+      // still closing is still using what it depends on, and the check above reads this
+      // of every dependant. Saying it early lets the first to start tear down a shared
+      // dependency under the others.
+      this.connected = false
+      this.#connecting = undefined
 
       clearInterval(interval)
 
@@ -145,8 +155,6 @@ class Connector {
     })()
 
     await this.#disconnecting
-
-    console.debug(`Connector '${this.id}' disconnected`)
   }
 
   async reconnect () {
@@ -179,5 +187,4 @@ class Connector {
 }
 
 const DELAY = 5000
-
-exports.Connector = Connector
+const TRACE_BOOT = process.env.TOA_BOOT_TRACE === '1'

package/src/context.js

@@ -1,12 +1,13 @@
-'use strict'
-
-const { Connector } = require('./connector')
+import { Connector } from './connector.js'
 
 /**
  * @implements {toa.core.Context}
  */
-class Context extends Connector {
+export class Context extends Connector {
+  env
+  name
   aspects
+  locator
 
   #local
   #discover
@@ -15,7 +16,10 @@ class Context extends Connector {
   constructor (local, discover, aspects = []) {
     super()
 
+    this.env = process.env.TOA_ENV
+    this.name = process.env.TOA_CONTEXT
     this.aspects = aspects
+    this.locator = local?.locator
 
     this.#local = local
     this.#discover = discover
@@ -51,5 +55,3 @@ class Context extends Connector {
     return remote
   }
 }
-
-exports.Context = Context

package/src/contract/contract.js

@@ -0,0 +1,18 @@
+import { SystemException } from '../exceptions.js'
+
+export class Contract {
+  schema
+
+  constructor (schema) {
+    this.schema = schema
+  }
+
+  fit (value) {
+    const error = this.schema.fit(value)
+
+    if (error !== null)
+      throw new this.constructor.Exception(error, value)
+  }
+
+  static Exception = SystemException
+}

package/src/contract/index.js

@@ -1,7 +1,2 @@
-'use strict'
-
-const { Request } = require('./request')
-const { Reply } = require('./reply')
-
-exports.Request = Request
-exports.Reply = Reply
+export { Request } from './request.js'
+export { Reply } from './reply.js'