@toa.io/boot 1.0.0-alpha.28 → 1.0.0-alpha.283

package/CHANGELOG.md

@@ -0,0 +1,188 @@
+# 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.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))
+* **exposition:** declare the errors the built-in components return ([27200c3](https://github.com/toa-io/toa/commit/27200c348ab09068d58c52c3e83208cb29cd7290))
+
+
+# [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)
+
+### Bug Fixes
+
+* **boot:** declare host, and build extensions with it in the step definitions ([915d957](https://github.com/toa-io/toa/commit/915d9571823358f8fca6fe19ef3aabd1b62e5605))
+
+### 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/boot
+
+
+
+
+
+# [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))
+* what the loader resolves, and what it will not ([1b8a02f](https://github.com/toa-io/toa/commit/1b8a02ff0a5e0f18ee62e3f71bc81116f86f9af1))
+
+
+# [1.0.0-alpha.274](https://github.com/toa-io/toa/compare/v1.0.0-alpha.273...v1.0.0-alpha.274) (2026-09-02)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [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/boot
+
+
+
+
+
+# [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
+
+* **amqp:** keep a receiver apart from the producers it delivers into ([4c2f43e](https://github.com/toa-io/toa/commit/4c2f43ebde68ba76a1fd277fe2a3305be1b622ef))
+* **amqp:** tear a receiver down before its producers, and drop the split ([e6c1154](https://github.com/toa-io/toa/commit/e6c1154024df22f7a470c47c1a79bd170fe7e3b2))
+
+
+* refactor(atomicity)!: take the lock manager from the stash ([4fd91eb](https://github.com/toa-io/toa/commit/4fd91eb2fdb68f7b87aaf16d182794bbc567ba57))
+* 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
+
+* **core:** give every component an atom aspect ([b501b9c](https://github.com/toa-io/toa/commit/b501b9cd3d5f5408d9faa71213e953fe2792cf9f))
+
+
+### BREAKING CHANGES
+
+* `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>
+* `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)
+
+
+### Performance Improvements
+
+* **boot:** stop paying for what a composition does not need to start ([1619c27](https://github.com/toa-io/toa/commit/1619c2743072f4706939ce72f3074e615d26a91e))
+* **openspan:** create a span only when something records it ([a6efb0e](https://github.com/toa-io/toa/commit/a6efb0eed38393f4c169b067f23d7447f0169bca))
+
+
+
+
+
+# [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)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [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/boot
+
+
+
+
+
+# [1.0.0-alpha.263](https://github.com/toa-io/toa/compare/v1.0.0-alpha.262...v1.0.0-alpha.263) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [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)
+
+
+### Bug Fixes
+
+* **boot:** let the composition own the process discovery ([2201e88](https://github.com/toa-io/toa/commit/2201e8852517fd1d2822c775c9b126eb60399580))
+
+
+### 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)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.256](https://github.com/toa-io/toa/compare/v1.0.0-alpha.255...v1.0.0-alpha.256) (2026-08-23)
+
+**Note:** Version bump only for package @toa.io/boot

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/boot",
-  "version": "1.0.0-alpha.28",
+  "version": "1.0.0-alpha.283",
+  "type": "module",
   "description": "Toa Boot",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -20,13 +21,14 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.28",
-    "@toa.io/filesystem": "1.0.0-alpha.28",
-    "@toa.io/generic": "1.0.0-alpha.28",
-    "@toa.io/norm": "1.0.0-alpha.28",
-    "@toa.io/schema": "1.0.0-alpha.28",
+    "@toa.io/atomicity": "1.0.0-alpha.283",
+    "@toa.io/core": "1.0.0-alpha.283",
+    "@toa.io/generic": "1.0.0-alpha.283",
+    "@toa.io/norm": "1.0.0-alpha.283",
+    "@toa.io/schemas": "1.0.0-alpha.283",
     "clone-deep": "4.0.1",
-    "dotenv": "16.1.1"
+    "dotenv": "17.4.2",
+    "openspan": "1.0.0-alpha.277"
   },
-  "gitHead": "89c3b7d1314e357c9e33df8d95f8d46954cd3bcf"
+  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
 }

package/src/atom.js

@@ -0,0 +1,37 @@
+import { Connector } from '@toa.io/core'
+
+import * as boot from './index.js'
+
+/**
+ * The atom as a system aspect. Every component has `context.atom`, with nothing declared in its
+ * manifest and nothing of its own to configure.
+ *
+ * @implements {toa.core.extensions.Aspect}
+ */
+class Aspect extends Connector {
+  name = 'atom'
+
+  #atom
+
+  constructor (atom) {
+    super()
+
+    this.#atom = atom
+
+    this.depends(atom)
+  }
+
+  // the methods are named rather than forwarded, so that the connector's lifecycle is not
+  // reachable from an algorithm
+  invoke (method, ...args) {
+    switch (method) {
+      case 'slots': return this.#atom.slots(...args)
+      case 'meter': return this.#atom.meter(...args)
+      case 'lock': return this.#atom.lock(...args)
+      default: throw new Error(`Atom aspect has no '${method}' method`)
+    }
+  }
+}
+
+/** @param {string} group */
+export const atom = (group) => new Aspect(boot.atomicity(group))

package/src/atomicity.js

@@ -0,0 +1,11 @@
+import { Factory } from '@toa.io/atomicity'
+
+/**
+ * What the replicas of one group decide together. Every component has one, whether or not there
+ * is anything to coordinate through: without a Redis nothing is owned and nothing is metered —
+ * see the connector's readme.
+ *
+ * @param {string} group
+ * @returns {toa.core.atomicity.Atom}
+ */
+export const atomicity = (group) => new Factory().atom(group)

package/src/bindings/broadcast.js

@@ -1,7 +1,4 @@
-'use strict'
+import { factory } from './factory.js'
 
-const { factory } = require('./factory')
-
-const broadcast = (channel, group, binding = '@toa.io/bindings.amqp') => factory(binding).broadcast(channel, group)
-
-exports.broadcast = broadcast
+export const broadcast = async (channel, group, binding = '@toa.io/bindings.amqp') =>
+  (await factory(binding)).broadcast(channel, group)

package/src/bindings/constants.js

@@ -1,3 +1 @@
-'use strict'
-
-exports.LOOP = '@toa.io/bindings.loop'
+export const LOOP = '@toa.io/bindings.loop'

package/src/bindings/consume.js

@@ -1,9 +1,6 @@
-'use strict'
+import { LOOP } from './constants.js'
+import { factory } from './factory.js'
 
-const { LOOP } = require('./constants')
-const { factory } = require('./factory')
-
-const consume = (locator, endpoint, bindings) =>
-  [LOOP].concat(bindings).map((binding) => factory(binding).consumer(locator, endpoint))
-
-exports.consume = consume
+export const consume = async (locator, endpoint, bindings) =>
+  await Promise.all([LOOP].concat(bindings).map(async (binding) =>
+    (await factory(binding)).consumer(locator, endpoint)))

package/src/bindings/emit.js

@@ -1,7 +1,4 @@
-'use strict'
+import { factory } from './factory.js'
 
-const { factory } = require('./factory')
-
-const emit = (binding, locator, label) => factory(binding).emitter(locator, label)
-
-exports.emit = emit
+export const emit = async (binding, locator, label) =>
+  (await factory(binding)).emitter(locator, label)

package/src/bindings/factory.js

@@ -1,15 +1,11 @@
-'use strict'
-
 let instances = {}
 
-const factory = (binding) => {
-  if (instances[binding] === undefined) instances[binding] = new (require(binding).Factory)()
+// the promise is what is remembered, so two components cannot each make a factory
+export const factory = async (binding) => {
+  instances[binding] ??= import(binding).then(({ Factory }) => new Factory())
 
-  return instances[binding]
+  return await instances[binding]
 }
 
 // for testing purposes
-const reset = () => (instances = {})
-
-exports.factory = factory
-exports.reset = reset
+export const reset = () => (instances = {})

package/src/bindings/index.js

@@ -1,13 +1,5 @@
-'use strict'
-
-const { broadcast } = require('./broadcast')
-const { consume } = require('./consume')
-const { emit } = require('./emit')
-const { produce } = require('./produce')
-const { receive } = require('./receive')
-
-exports.broadcast = broadcast
-exports.consume = consume
-exports.emit = emit
-exports.produce = produce
-exports.receive = receive
+export { broadcast } from './broadcast.js'
+export { consume } from './consume.js'
+export { emit } from './emit.js'
+export { produce } from './produce.js'
+export { receive } from './receive.js'

package/src/bindings/produce.js

@@ -1,28 +1,41 @@
-'use strict'
-
-const { LOOP } = require('./constants')
-const { factory } = require('./factory')
+import { LOOP } from './constants.js'
+import { factory } from './factory.js'
+
+export const produce = async (component, operations) => {
+  const local = []
+  const other = []
+
+  for (const [binding, endpoints] of group(operations)) {
+    const made = await factory(binding)
+    const producer = made.producer(component.locator, endpoints, component)
+    const { properties } = await import(binding)
+
+    if (properties.local === true)
+      local.push(producer)
+    else
+      other.push(producer)
+  }
 
-const produce = (component, operations) => group(operations, (factory, endpoints) =>
-  factory.producer(component.locator, endpoints, component))
+  return { local, other }
+}
 
-const group = (operations, callback) => {
+/** The endpoints each binding carries, as entries. */
+const group = (operations) => {
   const map = {}
 
-  for (const [endpoint, operation] of Object.entries(operations)) {
-    // noinspection JSUnresolvedVariable
-    const bindings = global.TOA_INTEGRATION_BINDINGS_LOOP_DISABLED
-      ? operation.bindings
-      : [LOOP].concat(operation.bindings)
+  if (operations !== undefined)
+    for (const [endpoint, operation] of Object.entries(operations)) {
+      // noinspection JSUnresolvedVariable
+      const bindings = global.TOA_INTEGRATION_BINDINGS_LOOP_DISABLED
+        ? operation.bindings
+        : [LOOP].concat(operation.bindings)
 
-    for (const binding of bindings) {
-      if (!map[binding]) map[binding] = []
+      for (const binding of bindings) {
+        if (!map[binding]) map[binding] = []
 
-      map[binding].push(endpoint)
+        map[binding].push(endpoint)
+      }
     }
-  }
 
-  return Object.entries(map).map(([binding, endpoints]) => callback(factory(binding), endpoints))
+  return Object.entries(map)
 }
-
-exports.produce = produce

package/src/bindings/receive.js

@@ -1,7 +1,4 @@
-'use strict'
+import { factory } from './factory.js'
 
-const { factory } = require('./factory')
-
-const receive = (binding, locator, label, group, receiver) => factory(binding).receiver(locator, label, group, receiver)
-
-exports.receive = receive
+export const receive = async (binding, locator, label, group, receiver) =>
+  (await factory(binding)).receiver(locator, label, group, receiver)

package/src/bridge.js

@@ -1,28 +1,35 @@
-'use strict'
-
-const algorithm = (bridge, path, endpoint, context) => {
-  const algorithm = resolve(bridge).algorithm(path, endpoint, context)
+export async function algorithm (bridge, path, endpoint, context) {
+  const factory = await resolve(bridge)
+  const algorithm = await factory.algorithm(path, endpoint, context)
 
   algorithm.depends(context)
 
   return algorithm
 }
 
-const event = (bridge, path, label, context) => resolve(bridge).event(path, label, context)
-const receiver = (bridge, path, label) => resolve(bridge).receiver(path, label)
+export const event = async (bridge, path, label, context) =>
+  (await resolve(bridge)).event(path, label, context)
 
-const factories = {}
+export const receiver = async (bridge, path, label) =>
+  (await resolve(bridge)).receiver(path, label)
 
-const resolve = (bridge) => {
-  if (factories[bridge] === undefined) {
-    const { Factory } = require(bridge)
+export const guard = async (bridge, path, label, context) =>
+  (await resolve(bridge)).guard(path, label, context)
 
-    factories[bridge] = new Factory()
-  }
+export async function rc (bridge, path, context) {
+  const factory = await resolve(bridge)
 
-  return factories[bridge]
+  if (factory.rc === undefined)
+    return
+
+  return factory.rc(path, context)
 }
 
-exports.algorithm = algorithm
-exports.event = event
-exports.receiver = receiver
+const factories = {}
+
+// the promise is what is remembered, so two boots cannot each make a factory
+const resolve = async (bridge) => {
+  factories[bridge] ??= import(bridge).then(({ Factory }) => new Factory())
+
+  return await factories[bridge]
+}

package/src/call.js

@@ -1,15 +1,12 @@
-'use strict'
+import { Call, Transmission } from '@toa.io/core'
 
-const { Call, Transmission } = require('@toa.io/core')
+import * as boot from './index.js'
 
-const boot = require('./index')
-
-const call = (locator, endpoint, definition, entity) => {
-  const consumers = boot.bindings.consume(locator, endpoint, definition.bindings)
+// eslint-disable-next-line max-params
+export const call = async (locator, endpoint, definition, entity, source) => {
+  const consumers = await boot.bindings.consume(locator, endpoint, definition.bindings)
   const transmission = new Transmission(consumers)
   const contract = boot.contract.request(definition, entity)
 
-  return new Call(transmission, contract)
+  return new Call(transmission, contract, source)
 }
-
-exports.call = call

package/src/cascade.js

@@ -1,16 +1,14 @@
-'use strict'
+import { Cascade } from '@toa.io/core'
 
-const { Cascade } = require('@toa.io/core')
+import * as boot from './index.js'
 
-const boot = require('./index')
-
-const cascade = (manifest, endpoint, definition, context) => {
+export async function cascade (manifest, endpoint, definition, context, preflight) {
   const bridges = []
 
   if (definition.forward) endpoint = definition.forward
 
   if (definition.bridge) {
-    const bridge = boot.bridge.algorithm(definition.bridge, manifest.path, endpoint, context)
+    const bridge = await boot.bridge.algorithm(definition.bridge, manifest.path, endpoint, context)
 
     bridges.unshift(bridge)
   }
@@ -22,12 +20,10 @@ const cascade = (manifest, endpoint, definition, context) => {
 
     if (operation === undefined) continue
 
-    const bridge = boot.bridge.algorithm(operation.bridge, prototype.path, endpoint, context)
+    const bridge = await boot.bridge.algorithm(operation.bridge, prototype.path, endpoint, context)
 
     bridges.unshift(bridge)
   }
 
-  return new Cascade(bridges)
+  return new Cascade(bridges, preflight)
 }
-
-exports.cascade = cascade

package/src/component.js

@@ -1,48 +1,72 @@
-'use strict'
-
-const { remap } = require('@toa.io/generic')
-const {
-  Component,
-  Locator,
-  State,
-  entities
-} = require('@toa.io/core')
-const { Schema } = require('@toa.io/schema')
-
-const boot = require('./index')
-
-/**
- * @param {toa.norm.Component} manifest
- * @returns {Promise<toa.core.Component>}
- */
-const component = async (manifest) => {
-  boot.extensions.load(manifest)
+import { Component, Locator, State, entities } from '@toa.io/core'
+import * as schemas from '@toa.io/schemas'
 
+import * as boot from './index.js'
+import { span } from './span.js'
+
+export const component = async (manifest) => {
   const locator = new Locator(manifest.name, manifest.namespace)
-  const storage = boot.storage(manifest)
+
+  return span(`component ${locator.id}`, () => create(manifest, locator))
+}
+
+const create = async (manifest, locator) => {
+  await boot.extensions.load(manifest)
+
+  // the storage is told whether there will be an outbox, so the events come first
+  const events = boot.events(manifest)
+  const storage = await boot.storage(manifest, events !== undefined)
   const context = await boot.context(manifest)
-  const emission = boot.emission(manifest.events, locator, context)
+  const emission = await boot.emission(events, locator, context)
+  const outbox = boot.outbox(manifest, storage, emission)
 
   let state
 
   if (manifest.entity !== undefined) {
-    const schema = new Schema(manifest.entity.schema)
-    const entity = new entities.Factory(schema)
+    const schema = schemas.schema(manifest.entity.schema)
+    const guards = await boot.guards(manifest, context)
+    const entity = new entities.Factory(schema, guards)
 
-    state = new State(storage, entity, emission, manifest.entity.associated)
+    state = new State(storage, entity, outbox, manifest.entity.associated)
   }
 
-  const operations = manifest.operations === undefined
-    ? {}
-    : remap(manifest.operations, (definition, endpoint) =>
-      boot.operation(manifest, endpoint, definition, context, state))
-
+  const phases = await boot.rc(manifest, context)
+  const operations = await bootOperations(manifest, context, state, phases?.preflight)
   const component = new Component(locator, operations)
 
   if (storage) component.depends(storage)
-  if (emission) component.depends(emission)
 
-  return boot.extensions.component(component)
+  // the outbox owns the emission and the storage, so it drains before either goes down
+  if (outbox) component.depends(outbox)
+  else if (emission) component.depends(emission)
+
+  const decorated = boot.extensions.component(component)
+
+  if (phases?.settle !== undefined)
+    decorated.settle = phases.settle
+
+  // a dependency closes after its dependant, so the component is already closed
+  // when the RC releases what it opened
+  if (phases?.dispose !== undefined)
+    decorated.depends(phases.dispose)
+
+  return decorated
 }
 
-exports.component = component
+async function bootOperations (manifest, context, state, preflight) {
+  if (manifest.operations === undefined)
+    return {}
+
+  const entries = Object.entries(manifest.operations)
+
+  // each one loads its algorithm from disk and compiles its contracts
+  const booted = await Promise.all(entries.map(([endpoint, definition]) =>
+    boot.operation(manifest, endpoint, definition, context, state, preflight)))
+
+  const operations = {}
+
+  for (let i = 0; i < entries.length; i++)
+    operations[entries[i][0]] = booted[i]
+
+  return operations
+}