@toa.io/boot 1.0.0-alpha.3 → 1.0.0-alpha.300

package/CHANGELOG.md

@@ -0,0 +1,124 @@
+# 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.300](https://github.com/toa-io/toa/compare/v1.0.0-alpha.299...v1.0.0-alpha.300) (2026-09-11)
+
+* feat(boot)!: a process is a thing, and an extension may keep something in one ([528d6cd](https://github.com/toa-io/toa/commit/528d6cdd307b45a6c30b6a184d7e06b3328cecf8))
+* feat(core)!: an operation may ask to run once ([dca616c](https://github.com/toa-io/toa/commit/dca616cb380a7a389e277875d3bd5ca55a6e4d45))
+
+### Features
+
+* **core:** a call carries what it is, and a chain of them carries it down ([ebd7769](https://github.com/toa-io/toa/commit/ebd776984a79adb9bf4a97b680128be1efab856f))
+* **core:** a call may name the process it goes to, and wait for a set time ([7d8adb2](https://github.com/toa-io/toa/commit/7d8adb2772a95ff45ae5374efdedfb5a857fbbe9))
+
+### BREAKING CHANGES
+
+* `Storage.store`, `.upsert` and `.ensure` take one more
+  argument, and `Storage` has two more members. A connector that ignores them
+  works exactly as it did; a component that asks it for `once` is refused at
+  boot. See migrations/299.md.
+* a composition booted directly has no readiness probe. Readiness is
+  the process's, and a composition is not a process. `stage.workload` boots one where a
+  suite needs it.
+
+
+# [1.0.0-alpha.299](https://github.com/toa-io/toa/compare/v1.0.0-alpha.298...v1.0.0-alpha.299) (2026-09-10)
+
+### Features
+
+* **bindings.amqp:** a binding carries a channel, addressed by label ([17cf178](https://github.com/toa-io/toa/commit/17cf1782d1c47d033c02f99947b766eb9d45df75))
+* **convergence:** deployments of one context converge ([8a70343](https://github.com/toa-io/toa/commit/8a70343cf6953aab58d4a25bac215508ff8d9a37))
+* **core:** an outbox row is published to destinations ([cfb77b4](https://github.com/toa-io/toa/commit/cfb77b4826ff0f9560769a0996981e143d6525af))
+
+
+# [1.0.0-alpha.298](https://github.com/toa-io/toa/compare/v1.0.0-alpha.297...v1.0.0-alpha.298) (2026-09-08)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.297](https://github.com/toa-io/toa/compare/v1.0.0-alpha.296...v1.0.0-alpha.297) (2026-09-08)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.296](https://github.com/toa-io/toa/compare/v1.0.0-alpha.295...v1.0.0-alpha.296) (2026-09-08)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.295](https://github.com/toa-io/toa/compare/v1.0.0-alpha.294...v1.0.0-alpha.295) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.294](https://github.com/toa-io/toa/compare/v1.0.0-alpha.293...v1.0.0-alpha.294) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.293](https://github.com/toa-io/toa/compare/v1.0.0-alpha.292...v1.0.0-alpha.293) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.292](https://github.com/toa-io/toa/compare/v1.0.0-alpha.291...v1.0.0-alpha.292) (2026-09-07)
+
+### Features
+
+* **definitions:** the version of Toa is the definitions package's ([3d0272e](https://github.com/toa-io/toa/commit/3d0272ea0ab862f4b6c2e58a2f003f92d0f8a87f))
+* **definitions:** what a package declares is read from one package ([7052341](https://github.com/toa-io/toa/commit/70523411b5d9e2b204c999aa02365173f3bb518d))
+* **norm:** a package's definition is read by one resolver ([bffd41c](https://github.com/toa-io/toa/commit/bffd41c8d18c42786b0bf321623088b9dabc4724))
+
+
+# [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
+
+### BREAKING CHANGES
+
+* a component that read `process.env.TOA_*` reads `context` instead;
+  `echo(input)` no longer substitutes from the environment; a bash operation sees no
+  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
+
+
+# [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [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)
+
+### Bug Fixes
+
+* **boot:** a discovery belongs to the connection that made it ([48e1c8f](https://github.com/toa-io/toa/commit/48e1c8f668b1853134ae9fb2349c485e6da66c28))

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/boot",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.300",
+  "type": "module",
   "description": "Toa Boot",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -20,15 +21,15 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.3",
-    "@toa.io/filesystem": "1.0.0-alpha.3",
-    "@toa.io/generic": "1.0.0-alpha.3",
-    "@toa.io/norm": "1.0.0-alpha.3",
-    "@toa.io/schema": "1.0.0-alpha.3",
-    "dotenv": "16.1.1"
+    "@toa.io/atomicity": "1.0.0-alpha.300",
+    "@toa.io/core": "1.0.0-alpha.300",
+    "@toa.io/definitions": "1.0.0-alpha.300",
+    "@toa.io/generic": "1.0.0-alpha.292",
+    "@toa.io/norm": "1.0.0-alpha.300",
+    "@toa.io/schemas": "1.0.0-alpha.299",
+    "clone-deep": "4.0.1",
+    "dotenv": "17.4.2",
+    "openspan": "1.0.0-alpha.293"
   },
-  "devDependencies": {
-    "clone-deep": "4.0.1"
-  },
-  "gitHead": "e36ac7871fc14d15863aaf8f9bbdeace8bdfa9f0"
+  "gitHead": "f91131a9aeb29aa271f177c4055ddcf0cda8c75e"
 }

package/src/atom.js

@@ -0,0 +1,41 @@
+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 {import('@toa.io/core/types').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 {import('@toa.io/core/types').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,9 @@
-'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/inbound.js

@@ -0,0 +1,11 @@
+import { factory } from './factory.js'
+
+// eslint-disable-next-line max-params
+export const inbound = async (binding, channel, uris, label, sink) => {
+  const instance = await factory(binding)
+
+  if (instance.inbound === undefined)
+    throw new Error(`Binding '${binding}' does not consume a channel`)
+
+  return instance.inbound(channel, uris, label, sink)
+}

package/src/bindings/index.js

@@ -1,13 +1,7 @@
-'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 { inbound } from './inbound.js'
+export { outbound } from './outbound.js'
+export { produce } from './produce.js'
+export { receive } from './receive.js'

package/src/bindings/outbound.js

@@ -0,0 +1,10 @@
+import { factory } from './factory.js'
+
+export const outbound = async (binding, channel, uris) => {
+  const instance = await factory(binding)
+
+  if (instance.outbound === undefined)
+    throw new Error(`Binding '${binding}' does not publish a channel`)
+
+  return instance.outbound(channel, uris)
+}

package/src/bindings/produce.js

@@ -1,28 +1,50 @@
-'use strict'
+import { definition } from '@toa.io/norm'
+import { LOOP } from './constants.js'
+import { factory } from './factory.js'
+
+export const produce = async (component, operations) => {
+  const local = []
+  const other = []
+  const stateful = addressed(operations)
+
+  for (const [binding, endpoints] of group(operations)) {
+    const made = await factory(binding)
+    const carried = stateful.filter((endpoint) => endpoints.includes(endpoint))
+    const producer = made.producer(component.locator, endpoints, component, carried)
+    const { properties } = (await definition(binding)).module
+
+    if (properties.local === true) local.push(producer)
+    else other.push(producer)
+  }
 
-const { LOOP } = require('./constants')
-const { factory } = require('./factory')
+  return { local, other }
+}
 
-const produce = (component, operations) => group(operations, (factory, endpoints) =>
-  factory.producer(component.locator, endpoints, component))
+/** The endpoints that take addressed calls only. */
+const addressed = (operations) =>
+  operations === undefined
+    ? []
+    : Object.entries(operations)
+        .filter(([, operation]) => operation.stateful === true)
+        .map(([endpoint]) => endpoint)
 
-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,34 @@
-'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,14 @@
-'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)
-}
+  const stateful = definition.stateful === true
 
-exports.call = call
+  return new Call(transmission, contract, `${locator.id}.${endpoint}`, source, stateful)
+}

package/src/cascade.js

@@ -1,16 +1,19 @@
-'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 +25,15 @@ 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