@toa.io/boot 1.0.0-alpha.306 → 1.0.0-alpha.308

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.308](https://github.com/toa-io/toa/compare/v1.0.0-alpha.307...v1.0.0-alpha.308) (2026-09-15)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
+# [1.0.0-alpha.307](https://github.com/toa-io/toa/compare/v1.0.0-alpha.306...v1.0.0-alpha.307) (2026-09-15)
+
+**Note:** Version bump only for package @toa.io/boot
+
+
+
+
+
 # [1.0.0-alpha.306](https://github.com/toa-io/toa/compare/v1.0.0-alpha.305...v1.0.0-alpha.306) (2026-09-14)
 
 * refactor(core)!: name the quiesce hooks pause and unpause ([6e4e5f5](https://github.com/toa-io/toa/commit/6e4e5f55d43f03ea95ca8bbdaae57b949564dfa2))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/boot",
-  "version": "1.0.0-alpha.306",
+  "version": "1.0.0-alpha.308",
   "type": "module",
   "description": "Toa Boot",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,15 +21,15 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/atomicity": "1.0.0-alpha.306",
-    "@toa.io/core": "1.0.0-alpha.306",
-    "@toa.io/definitions": "1.0.0-alpha.306",
+    "@toa.io/atomicity": "1.0.0-alpha.308",
+    "@toa.io/core": "1.0.0-alpha.308",
+    "@toa.io/definitions": "1.0.0-alpha.308",
     "@toa.io/generic": "1.0.0-alpha.304",
-    "@toa.io/norm": "1.0.0-alpha.306",
+    "@toa.io/norm": "1.0.0-alpha.308",
     "@toa.io/schemas": "1.0.0-alpha.304",
     "clone-deep": "4.0.1",
     "dotenv": "17.4.2",
     "openspan": "1.0.0-alpha.305"
   },
-  "gitHead": "0693d180a8053a7d07dca879dac2a3c4784d6d45"
+  "gitHead": "66eb0d54032f60e6ead9e13fd9e21fb60c611277"
 }

package/src/composition.js

@@ -24,104 +24,88 @@ export async function composition(paths, options) {
       components: manifests.map((manifest) => manifest.locator.id)
     })
 
+    // what this process composes it knows, and the map it was given says the same
+    await boot.map.compose(manifests)
+
     const tenants = await span(
       'create tenants',
       async () => await Promise.all(manifests.map(boot.extensions.tenants))
     )
 
-    const expositions = await span(
-      'expose discovery',
-      async () => await Promise.all(manifests.map(boot.discovery.expose))
+    const components = await span(
+      'create components',
+      async () => await Promise.all(manifests.map(boot.component))
     )
 
-    try {
-      const components = await span(
-        'create components',
-        async () => await Promise.all(manifests.map(boot.component))
-      )
-
-      const groups = await Promise.all(
-        components.map(
-          async (component, index) =>
-            await boot.bindings.produce(component, manifests[index].operations)
-        )
+    const groups = await Promise.all(
+      components.map(
+        async (component, index) =>
+          await boot.bindings.produce(component, manifests[index].operations)
       )
+    )
 
-      const receivers = await span(
-        'create receivers',
-        async () =>
-          await Promise.all(
-            components.map((component, index) =>
-              boot.receivers(manifests[index], component)
-            )
+    const receivers = await span(
+      'create receivers',
+      async () =>
+        await Promise.all(
+          components.map((component, index) =>
+            boot.receivers(manifests[index], component)
           )
-      )
-
-      const producers = []
-      const settles = []
-      const readies = []
+        )
+    )
 
-      for (let i = 0; i < components.length; i++) {
-        const { local, other } = groups[i]
-        const { settle, ready } = components[i]
-        const serving = [...local, ...other]
+    const producers = []
+    const settles = []
+    const readies = []
 
-        producers.push(...serving)
+    for (let i = 0; i < components.length; i++) {
+      const { local, other } = groups[i]
+      const { settle, ready } = components[i]
+      const serving = [...local, ...other]
 
-        /*
-         * A receiver turns an event into a call to an operation of its own component, and
-         * that call is served by these — the loop producer first, the broker's if it has
-         * already gone. They are siblings under the composition otherwise, so a receiver
-         * still draining a delivery would be left calling something already torn down.
-         */
-        // one at a time: `depends` given an array links the group it makes rather than its
-        // members, and it is the members whose teardown has to wait for this one
-        for (const receiver of receivers[i])
-          for (const producer of serving) receiver.depends(producer)
+      producers.push(...serving)
 
-        /*
-         * The broker producers serve the stateful endpoints under the process's name, and the
-         * name is held once they are open — before then a call to it is refused. `ready` is where
-         * a component hands the name out, so it waits for every producer and receiver of its own.
-         */
-        if (ready !== undefined) {
-          for (const producer of serving) ready.depends(producer)
+      /*
+       * A receiver turns an event into a call to an operation of its own component, and
+       * that call is served by these — the loop producer first, the broker's if it has
+       * already gone. They are siblings under the composition otherwise, so a receiver
+       * still draining a delivery would be left calling something already torn down.
+       */
+      // one at a time: `depends` given an array links the group it makes rather than its
+      // members, and it is the members whose teardown has to wait for this one
+      for (const receiver of receivers[i])
+        for (const producer of serving) receiver.depends(producer)
 
-          for (const receiver of receivers[i]) ready.depends(receiver)
+      /*
+       * The broker producers serve the stateful endpoints under the process's name, and the
+       * name is held once they are open — before then a call to it is refused. `ready` is where
+       * a component hands the name out, so it waits for every producer and receiver of its own.
+       */
+      if (ready !== undefined) {
+        for (const producer of serving) ready.depends(producer)
 
-          readies.push(ready)
-        }
+        for (const receiver of receivers[i]) ready.depends(receiver)
 
-        if (settle === undefined) continue
+        readies.push(ready)
+      }
 
-        if (local.length > 0) settle.depends(local)
+      if (settle === undefined) continue
 
-        for (const producer of other) producer.depends(settle)
+      if (local.length > 0) settle.depends(local)
 
-        for (const receiver of receivers[i]) receiver.depends(settle)
+      for (const producer of other) producer.depends(settle)
 
-        settles.push(settle)
-      }
+      for (const receiver of receivers[i]) receiver.depends(settle)
 
-      const composition = new Composition(
-        expositions.flat(),
-        producers.concat(settles, readies),
-        receivers.flat(),
-        tenants.flat()
-      )
+      settles.push(settle)
+    }
 
-      /*
-       * A lookup that is never answered holds a connection open, and whoever
-       * awaits it has nothing to disconnect — the remote it would belong to does
-       * not exist yet. The composition owns the process's discovery instead, so
-       * an unanswered lookup cannot outlive it.
-       */
-      composition.depends(await boot.discovery.discovery())
+    const composition = new Composition(
+      producers.concat(settles, readies),
+      receivers.flat(),
+      tenants.flat()
+    )
 
-      return boot.extensions.manage(composition)
-    } catch (exception) {
-      await Promise.all(expositions.flat().map((connector) => connector.disconnect(true)))
-      throw exception
-    }
+    return boot.extensions.manage(composition)
   })
 }

package/src/context.js

@@ -3,7 +3,7 @@ import { Context, Locator } from '@toa.io/core'
 import * as boot from './index.js'
 
 export const context = async (manifest) => {
-  const local = await boot.remote(manifest.locator, undefined, { manifest })
+  const local = await boot.remote(manifest.locator, undefined, { contract: manifest })
   const aspects = boot.extensions.aspects(manifest)
 
   // a system aspect: it is there in every component, declared by none of them

package/src/host.js

@@ -12,7 +12,7 @@ import * as boot from './index.js'
  */
 export const host = (workload) => ({
   // an extension knows a version only where something told it one; see `Remotes` in exposition
-  remote: (locator, source, version) => boot.remote(locator, source, { version }),
+  remote: (locator, source, contract) => boot.remote(locator, source, { contract }),
   broadcast: boot.bindings.broadcast,
   composition: boot.composition,
   receive: boot.receive,

package/src/index.js

@@ -4,7 +4,6 @@ export { load as env } from './env.js'
 export * as bindings from './bindings/index.js'
 export * as bridge from './bridge.js'
 export * as contract from './contract.js'
-export * as discovery from './discovery.js'
 export * as extensions from './extensions/index.js'
 
 export { call } from './call.js'

package/src/map.js

@@ -1,40 +1,85 @@
+import assert from 'node:assert'
 import { readFile } from 'node:fs/promises'
+import * as core from '@toa.io/core'
 
 /**
- * Which version of a component this process asks what that component provides.
+ * What this process was given about the components it calls: the contract of the version each of
+ * them runs.
  *
- * Held as the file it was given rather than as what the file said, and read at every lookup: a
- * deployment rewrites it under a running process, and a process may first call a peer long after
- * that peer was replaced. A lookup happens once per peer, so this is a read per peer.
+ * Held as the file it was given rather than as what the file said, and read at every call for
+ * one: a deployment rewrites it under a running process, and a process may first call a peer
+ * long after that peer was replaced. A contract is read once per peer, so this is a read per
+ * peer.
  *
- * @type {string | Record<string, string> | undefined}
+ * @type {string | Record<string, import('@toa.io/core').Contract> | undefined}
  */
 let source
 
 /**
- * @param {string | Record<string, string> | undefined} value the file, or the map itself
+ * What this process composes, which it knows from the sources it booted from. What the map
+ * states wins: two compositions of one locator run in one process while a rollout is staged,
+ * and the map is what says which of them a caller is held to.
+ *
+ * @type {Record<string, import('@toa.io/core').Contract>}
+ */
+let composed = {}
+
+/**
+ * @param {string | Record<string, import('@toa.io/core').Contract> | undefined} value the file, or the map itself
  */
 export const use = (value) => {
   source = value
 }
 
 /**
- * The version of a component, where this process was given a map that names one. Absent, a
- * lookup goes to the name every version of that component serves.
+ * Forgets what this process composed, which is what a test does between one composition and
+ * the next: a component that is no longer composed is one nothing states.
+ */
+export const forget = () => {
+  composed = {}
+}
+
+/**
+ * What this process composes, stated by the boot that composes it — and held to the map it was
+ * given a file of, which one `toa deploy` writes with the images it deploys: the two differ only
+ * where the map was not written again. What a test states instead is what that test means, and
+ * is not checked.
+ *
+ * @param {toa.norm.Component[]} manifests
+ * @returns {Promise<void>}
+ */
+export const compose = async (manifests) => {
+  const file = typeof source === 'string' ? await read(source) : undefined
+
+  for (const manifest of manifests) {
+    const stated = file?.[manifest.locator.id]
+
+    assert.ok(
+      stated === undefined || stated.version === manifest.version,
+      `'${manifest.locator.id}' is composed at a version the component map does not state. ` +
+        'Run `toa map`.'
+    )
+
+    composed[manifest.locator.id] = core.contract.component(manifest)
+  }
+}
+
+/**
+ * What a component provides: what the map states of it, or what this process composes.
  *
  * @param {string} id
- * @returns {Promise<string | undefined>}
+ * @returns {Promise<import('@toa.io/core').Contract | undefined>}
  */
-export const version = async (id) => {
-  if (source === undefined) return undefined
-  if (typeof source !== 'string') return source[id]
+export const contract = async (id) => {
+  if (source === undefined) return composed[id]
+  if (typeof source !== 'string') return source[id] ?? composed[id]
 
-  return (await read(source))[id]
+  return (await read(source))[id] ?? composed[id]
 }
 
 /**
  * @param {string} path
- * @returns {Promise<Record<string, string>>}
+ * @returns {Promise<Record<string, import('@toa.io/core').Contract>>}
  */
 async function read(path) {
   let contents

package/src/receivers.js

@@ -8,7 +8,7 @@ export const receivers = async (manifest, component) => {
   if (manifest.receivers === undefined) return []
 
   const receivers = []
-  const local = await boot.remote(manifest.locator, undefined, { manifest })
+  const local = await boot.remote(manifest.locator, undefined, { contract: manifest })
 
   for (const [label, definition] of Object.entries(manifest.receivers)) {
     const locator = Locator.parse(label)
@@ -67,9 +67,15 @@ export async function receive(label, group, callback) {
  */
 async function resolveBinding(locator, label) {
   const event = label.split('.').pop()
-  const version = await boot.map.version(locator.id)
-  const discovery = await boot.discovery.discovery()
-  const { events } = await discovery.lookup(locator, version)
+  const contract = await boot.map.contract(locator.id)
+
+  assert.ok(
+    contract !== undefined,
+    `The component map states nothing of '${locator.id}', whose event '${label}' receives. ` +
+      'Run `toa map`.'
+  )
+
+  const { events, version } = contract
 
   assert.ok(
     events?.[event] !== undefined,

package/src/remote.js

@@ -1,5 +1,4 @@
-import { console } from 'openspan'
-import { Remote } from '@toa.io/core'
+import { Remote, exceptions } from '@toa.io/core'
 import { remap } from '@toa.io/generic'
 
 import * as boot from './index.js'
@@ -7,40 +6,29 @@ import * as boot from './index.js'
 /**
  * @param {import('@toa.io/core').Locator} locator
  * @param {import('@toa.io/core/types').Source} [source] the origin stamped on every call made through this remote
- * @param {{ manifest?: toa.norm.Component, version?: string }} [options]
- *   `manifest` skips discovery where it is already known; `version` is which version of the
- *   component answers, where the caller knows one — the gateway, from the branch it merged.
- *   Absent, the map this process was given says, and absent that too, whichever version answers.
+ * @param {{ contract?: import('@toa.io/core').Contract }} [options]
+ *   `contract` is what the caller already has — a manifest of its own is one, and so is what a
+ *   tenant announced — and absent it, what the map this process was given states.
  */
 export const remote = async (locator, source, options = {}) => {
-  let { manifest } = options
-  let discovery
+  const contract = options.contract ?? (await boot.map.contract(locator.id))
 
-  if (manifest === undefined) {
-    const version = options.version ?? (await boot.map.version(locator.id))
-
-    console.debug('Lookup', { locator: locator.id, version })
-
-    discovery = await boot.discovery.discovery()
-    manifest = await discovery.lookup(locator, version)
-  }
+  if (contract === undefined)
+    throw new exceptions.UnstatedException(
+      `Cannot call '${locator.id}': the component map states nothing of it. Run \`toa map\`.`
+    )
 
   // a call binds its consumers, which are loaded rather than required
   const calls =
-    manifest.operations === undefined
+    contract.operations === undefined
       ? {}
       : await settle(
-          remap(manifest.operations, (definition, endpoint) =>
-            boot.call(locator, endpoint, definition, manifest.entity, source)
+          remap(contract.operations, (definition, endpoint) =>
+            boot.call(locator, endpoint, definition, contract.entity, source)
           )
         )
 
-  const remote = new Remote(locator, calls)
-
-  // ensure discovery shutdown
-  if (discovery !== undefined) remote.depends(discovery)
-
-  return remote
+  return new Remote(locator, calls)
 }
 
 /** An object whose values are promises, as an object of what they resolve to. */

package/types/index.d.ts

@@ -1,9 +1,29 @@
 import type * as core from '@toa.io/core'
 import type * as types from '@toa.io/core/types'
+import type * as norm from '@toa.io/norm/types'
 import * as composition from './composition.d.ts'
 
 export * as bindings from './bindings.d.ts'
 
+export async function manifest(
+  path: string,
+  options?: composition.Options
+): Promise<norm.Manifest>
+
+/** What this process was given about the components it calls. */
+export namespace map {
+  /** the file to read it from, or the map itself */
+  function use(value: string | Record<string, core.Contract> | undefined): void
+
+  /** what this process composes, stated by the boot that composes it */
+  function compose(manifests: norm.Manifest[]): Promise<void>
+
+  /** forgets what this process composed */
+  function forget(): void
+
+  function contract(id: string): Promise<core.Contract | undefined>
+}
+
 export async function composition(
   paths: string[],
   options?: composition.Options

package/src/discovery.js

@@ -1,75 +0,0 @@
-import { Discovery, Exposition } from '@toa.io/core'
-
-import * as boot from './index.js'
-
-let promise
-let instance = null
-
-/**
- * The process's discovery, for as long as it is connected.
- *
- * A disconnected one is replaced rather than reused. A lookup becomes a dependency of the
- * discovery that made it and nothing takes one back, so an instance carried across a
- * disconnection would reconnect every call it has ever made beside the ones the composition now
- * booting asks for — and every disconnection after that would walk all of them again.
- */
-export const discovery = async () => {
-  while (true) {
-    if (instance === null) {
-      instance = new Discovery(lookup)
-      promise = instance.connect()
-    }
-
-    const current = instance
-
-    await promise
-
-    if (current.connected) return current
-
-    // whoever replaced it first wins, and the loop reads what they left
-    if (instance === current) instance = null
-  }
-}
-
-const lookup = async (locator, version) => {
-  const call = await boot.call(locator, endpoint(version), { bindings: BINDINGS })
-
-  await call.connect()
-
-  return call
-}
-
-/**
- * Where a lookup of a named version of a component is answered. Absent a version, the name every
- * version of it answers on, which is what a caller with no map asks.
- *
- * @param {string} [version]
- * @returns {string}
- */
-export const endpoint = (version) =>
-  version === undefined ? ENDPOINT : ENDPOINT + SEPARATOR + version
-
-/**
- * Both names, always: the versioned one is what a caller that knows which version it wants asks,
- * and the shared one is what everything else asks — a caller outside the deployment, a process of
- * a runtime that has never heard of this.
- */
-export const expose = async (manifest) => {
-  const exposition = new Exposition(manifest.locator, manifest)
-  const operations = {
-    [ENDPOINT]: { bindings: BINDINGS },
-    [endpoint(manifest.version)]: { bindings: BINDINGS }
-  }
-  const { local, other } = await boot.bindings.produce(exposition, operations)
-  const producers = local.concat(other)
-
-  await Promise.all(producers.map((producer) => producer.connect()))
-
-  return producers
-}
-
-const BINDINGS = ['@toa.io/bindings.amqp']
-const ENDPOINT = '.lookup'
-
-/** the runtime's own, as `..tasks` and `..instances` are */
-const SEPARATOR = '..'