@toa.io/boot 1.0.0-alpha.297 → 1.0.0-alpha.299

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 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.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/boot",
-  "version": "1.0.0-alpha.297",
+  "version": "1.0.0-alpha.299",
   "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.293",
-    "@toa.io/core": "1.0.0-alpha.293",
-    "@toa.io/definitions": "1.0.0-alpha.297",
+    "@toa.io/atomicity": "1.0.0-alpha.299",
+    "@toa.io/core": "1.0.0-alpha.299",
+    "@toa.io/definitions": "1.0.0-alpha.299",
     "@toa.io/generic": "1.0.0-alpha.292",
-    "@toa.io/norm": "1.0.0-alpha.297",
-    "@toa.io/schemas": "1.0.0-alpha.293",
+    "@toa.io/norm": "1.0.0-alpha.299",
+    "@toa.io/schemas": "1.0.0-alpha.299",
     "clone-deep": "4.0.1",
     "dotenv": "17.4.2",
     "openspan": "1.0.0-alpha.293"
   },
-  "gitHead": "52959bba83817238725f50553d45afde1f231af1"
+  "gitHead": "2ba95b16f2cf06f82d6ff8d436761e843e5e4b43"
 }

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,5 +1,7 @@
 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/component.js

@@ -19,12 +19,17 @@ 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
+  // the storage is told whether there will be an outbox, so what it publishes to comes first:
+  // its own events, and whatever an extension adds
   const events = boot.events(manifest)
-  const storage = await boot.storage(manifest, events !== undefined)
+  const destinations = await boot.extensions.destinations(manifest)
+  const storage = await boot.storage(
+    manifest,
+    events !== undefined || destinations.length > 0
+  )
   const context = await boot.context(manifest)
   const emission = await boot.emission(events, locator, context)
-  const outbox = boot.outbox(manifest, storage, emission)
+  const outbox = boot.outbox(manifest, storage, emission, destinations)
 
   let state
 

package/src/extensions/destinations.js

@@ -0,0 +1,27 @@
+import { instance } from './resolve.js'
+
+/**
+ * Where a committed state change of this component goes, beside its own events. An extension
+ * that contributes one gives the component an outbox whether or not it declares an event, so
+ * this is read before the storage is made.
+ *
+ * @param {toa.norm.Component} manifest
+ * @returns {Promise<import('@toa.io/core/types').outbox.Destination[]>}
+ */
+export const destinations = async (manifest) => {
+  const destinations = []
+
+  if (manifest.extensions === undefined) return destinations
+
+  for (const [name, declaration] of Object.entries(manifest.extensions)) {
+    const factory = instance(name, manifest.path)
+
+    if (factory.destination === undefined) continue
+
+    const destination = await factory.destination(manifest.locator, declaration, manifest)
+
+    if (destination !== undefined) destinations.push(destination)
+  }
+
+  return destinations
+}

package/src/extensions/index.js

@@ -1,6 +1,7 @@
 export { aspects } from './aspects.js'
 export { component } from './component.js'
 export { context } from './context.js'
+export { destinations } from './destinations.js'
 export { emitter } from './emitter.js'
 export { load } from './load.js'
 export { manage } from './manage.js'

package/src/extensions/storage.js

@@ -2,13 +2,14 @@ import { instances } from './instances.js'
 
 /**
  * @param {import('@toa.io/core/types').storages.Storage} storage
+ * @param {import('@toa.io/core').Locator} locator whose storage it is
  * @returns {import('@toa.io/core/types').storages.Storage}
  */
-export const storage = (storage) => {
+export const storage = (storage, locator) => {
   let decorated = storage
 
   for (const factory of Object.values(instances)) {
-    if (factory.storage !== undefined) decorated = factory.storage(decorated)
+    if (factory.storage !== undefined) decorated = factory.storage(decorated, locator)
   }
 
   return decorated

package/src/host.js

@@ -11,5 +11,7 @@ export const host = () => ({
   broadcast: boot.bindings.broadcast,
   composition: boot.composition,
   receive: boot.receive,
-  atom: boot.atomicity
+  atom: boot.atomicity,
+  outbound: boot.bindings.outbound,
+  inbound: boot.bindings.inbound
 })

package/src/manifest.js

@@ -1,9 +1,9 @@
 import clone from 'clone-deep'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { basename, join } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 import { merge } from '@toa.io/generic'
-import { component as load, revive, NORMALIZED } from '@toa.io/norm'
+import { component as load, definition, revive, NORMALIZED } from '@toa.io/norm'
 import { Locator } from '@toa.io/core'
 
 import { span } from './span.js'
@@ -33,17 +33,66 @@ export const manifest = async (path, options = {}) => {
 }
 
 /**
- * What the build wrote, where it wrote one. An image carries the manifest a build normalised;
- * a workspace has no such file and is read as it always was.
+ * A manifest already normalised, where there is one, and the sources read where there is not.
+ *
+ * A component of an application's own comes with the manifest its build wrote beside it. A
+ * component an extension ships comes with none — its package is published once, long before
+ * any image is built — but `@toa.io/definitions` carries the digest of those manifests, which
+ * a deploy has read for as long as it has been unable to install the extension. A service runs
+ * them from the package, so it reads the same digest rather than reading their sources again.
+ *
+ * Only a workspace normalises, then, which is the one place a source can have changed since.
  *
  * @param {string} path
  */
 async function read(path) {
   const file = join(path, NORMALIZED)
 
-  if (!existsSync(file)) return await load(path)
+  if (existsSync(file)) return revive(JSON.parse(await readFile(file, 'utf8')), path)
 
-  return revive(JSON.parse(await readFile(file, 'utf8')), path)
+  return (await digested(path)) ?? (await load(path))
 }
 
+/**
+ * What the digest holds for a component of an extension's own, by the directory it is in.
+ *
+ * An extension ships its components in `components/` beside its manifest and nowhere else, so
+ * that is the whole of what is looked for: anything else — an application's own component, a
+ * fixture in a workspace — is read from its sources.
+ *
+ * @param {string} path
+ * @returns {Promise<object | undefined>}
+ */
+async function digested(path) {
+  const directory = dirname(path)
+
+  if (basename(directory) !== COMPONENTS) return undefined
+
+  const root = dirname(directory)
+  const manifest = join(root, MANIFEST)
+
+  if (!existsSync(manifest)) return undefined
+
+  const { name } = JSON.parse(readFileSync(manifest, 'utf8'))
+
+  // the digest is of what Toa ships, and a package it does not define has none
+  if (name === undefined || !name.startsWith(SCOPE)) return undefined
+
+  const { module } = await definition(name)
+  const { labels, manifests } = module.components?.() ?? {}
+
+  if (manifests === undefined) return undefined
+
+  // a chart names a component's workload the way the digest labels it
+  const index = labels.indexOf(basename(path).replace('.', '-'))
+
+  return index === -1 ? undefined : revive(manifests[index], path)
+}
+
+const SCOPE = '@toa.io/'
+
+const COMPONENTS = 'components'
+
+const MANIFEST = 'package.json'
+
 const DEFAULTS = {}

package/src/manifest.test.js

@@ -1,7 +1,7 @@
 import { it, mock } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { mkdtemp, writeFile } from 'node:fs/promises'
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { generate } from 'randomstring'
@@ -10,6 +10,8 @@ const NORMALIZED = 'manifest.toa.json'
 
 let normalised = 0
 
+const digest = { labels: ['identity-basic'], manifests: [{ name: 'basic', namespace: 'identity' }] }
+
 mock.module('@toa.io/norm', {
   namedExports: {
     component: () => {
@@ -17,7 +19,9 @@ mock.module('@toa.io/norm', {
 
       return mockComponent()
     },
-    definition: async () => ({ module: {} }),
+    definition: async (reference) => ({
+      module: reference === '@toa.io/extensions.exposition' ? { components: () => digest } : {}
+    }),
     revive: (declared, path) => ({ ...declared, path }),
     NORMALIZED
   }
@@ -58,6 +62,39 @@ it('should read what the build wrote, and not normalize', async () => {
   assert.strictEqual(read.locator.id, 'todos.tasks')
 })
 
+it('should read the digest for a component an extension ships, and not normalize', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'toa-manifest-test'))
+  const component = join(root, 'components', 'identity.basic')
+
+  await mkdir(component, { recursive: true })
+  await writeFile(
+    join(root, 'package.json'),
+    JSON.stringify({ name: '@toa.io/extensions.exposition' })
+  )
+
+  const before = normalised
+  const read = await manifest(component)
+
+  assert.strictEqual(normalised, before, 'the component was normalized')
+  assert.strictEqual(read.path, component)
+  assert.strictEqual(read.locator.id, 'identity.basic')
+})
+
+it('should normalize a component that only looks like one an extension ships', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'toa-manifest-test'))
+  const component = join(root, 'components', 'identity.basic')
+
+  await mkdir(component, { recursive: true })
+  // an application's own package, which the digest knows nothing about
+  await writeFile(join(root, 'package.json'), JSON.stringify({ name: 'acme' }))
+
+  const before = normalised
+
+  await manifest(component)
+
+  assert.strictEqual(normalised, before + 1)
+})
+
 function mockComponent() {
   return { name: generate(), namespace: generate() }
 }

package/src/outbox.js

@@ -3,15 +3,20 @@ import { Outbox } from '@toa.io/core'
 import * as boot from './index.js'
 
 /**
- * A component with no declared events has nothing to publish and therefore no outbox — the
- * static check that keeps the common case free of a transaction.
+ * A component with nothing to publish to has no outbox — the static check that keeps the
+ * common case free of a transaction. Its own events are one destination; an extension may
+ * contribute others, and a component that declares no event at all has an outbox where one of
+ * those is there.
  *
  * @param {toa.norm.Component} manifest
  * @param {import('@toa.io/core/types').storages.Storage} [storage]
  * @param {import('@toa.io/core').Emission} [emission]
+ * @param {import('@toa.io/core/types').outbox.Destination[]} [contributed]
  */
-export const outbox = (manifest, storage, emission) => {
-  if (emission === undefined) return
+export const outbox = (manifest, storage, emission, contributed = []) => {
+  const destinations = emission === undefined ? contributed : [emission, ...contributed]
 
-  return new Outbox(emission, storage, boot.atomicity(manifest.locator.id), {})
+  if (destinations.length === 0) return
+
+  return new Outbox(destinations, storage, boot.atomicity(manifest.locator.id), {})
 }

package/src/storage.js

@@ -33,7 +33,7 @@ export const storage = async (manifest, outbox) => {
         `which storage '${manifest.entity.storage}' does not apply`
     )
 
-  return extensions.storage(storage)
+  return extensions.storage(storage, manifest.locator)
 }
 
 async function load(component) {