@toa.io/userland 1.0.0-alpha.305 → 1.0.0-alpha.307

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 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.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/userland
+
+
+
+
+
+# [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)
+
+* feat(boot)!: a process can be halted and come back ([7196fa5](https://github.com/toa-io/toa/commit/7196fa51a9c882e84c3767a4fdd329fd2df319f5))
+
+### BREAKING CHANGES
+
+* `Host` gains `gate` and `halt`, and `Factory.service` may answer a gate. An
+  extension that gates nothing keeps its connections through a halt.
+
+
 # [1.0.0-alpha.305](https://github.com/toa-io/toa/compare/v1.0.0-alpha.304...v1.0.0-alpha.305) (2026-09-13)
 
 **Note:** Version bump only for package @toa.io/userland

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/userland",
-  "version": "1.0.0-alpha.305",
+  "version": "1.0.0-alpha.307",
   "type": "module",
   "description": "Toa development kit",
   "homepage": "https://toa.io",
@@ -32,12 +32,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@toa.io/boot": "1.0.0-alpha.305",
-    "@toa.io/core": "1.0.0-alpha.305",
+    "@toa.io/boot": "1.0.0-alpha.307",
+    "@toa.io/core": "1.0.0-alpha.306",
     "@toa.io/generic": "1.0.0-alpha.304",
-    "@toa.io/norm": "1.0.0-alpha.305",
+    "@toa.io/norm": "1.0.0-alpha.307",
     "@toa.io/schemas": "1.0.0-alpha.304",
-    "@toa.io/storages.null": "1.0.0-alpha.305"
+    "@toa.io/storages.null": "1.0.0-alpha.306"
   },
-  "gitHead": "6a28476303826e2484cc2ea6306efee6f19fb594"
+  "gitHead": "d5f4b2e97e315ba8ab657039d0407565c96e34bc"
 }

package/stage/src/index.js

@@ -1,7 +1,9 @@
 export { manifest } from './manifest.js'
+export { map } from './map.js'
 export { component } from './component.js'
 export { composition, composition as compose } from './composition.js'
 export { workload } from './workload.js'
 export { service as serve } from './service.js'
 export { remote } from './remote.js'
+export { halt, restore } from './quiescence.js'
 export { shutdown } from './shutdown.js'

package/stage/src/map.js

@@ -0,0 +1,15 @@
+import * as boot from '@toa.io/boot'
+
+/**
+ * Which version of each component a lookup made in this process asks for.
+ *
+ * A composition staged here is given none unless a test states one, and a lookup with no version
+ * goes to the name every version of a component answers on — which is what a run outside a
+ * deployment gets.
+ *
+ * @param {Record<string, string> | undefined} versions
+ * @returns {void}
+ */
+export const map = (versions) => {
+  boot.map.use(versions)
+}

package/stage/src/quiescence.js

@@ -0,0 +1,16 @@
+import { state } from './state.js'
+
+/**
+ * Stops what everything staged does of its own accord, holding every connection open — what a
+ * process does when it is told to go quiet. A component's `stop` run command runs here.
+ */
+export const halt = async () => {
+  for (const composition of state.compositions) await composition.halt()
+  for (const workload of state.workloads) await workload.halt()
+}
+
+/** Starts it again, running the `resume` command. */
+export const restore = async () => {
+  for (const composition of state.compositions) await composition.restore()
+  for (const workload of state.workloads) await workload.restore()
+}

package/stage/src/shutdown.js

@@ -1,4 +1,5 @@
 import { state } from './state.js'
+import { map } from './map.js'
 
 /** @type {toa.stage.Shutdown} */
 export const shutdown = async () => {
@@ -17,5 +18,8 @@ export const shutdown = async () => {
 
   await Promise.all(disconnections)
 
+  // whatever a test stated is not carried into the next one
+  map(undefined)
+
   state.reset()
 }

package/stage/src/workload.js

@@ -1,15 +1,51 @@
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
 import * as boot from '@toa.io/boot'
+import { Connector } from '@toa.io/core'
+import { shortcuts } from '@toa.io/norm'
 import { state } from './state.js'
 
+// a shortcut resolves to a package name, which is not a path
+const require = createRequire(import.meta.url)
+
+/** The services, made against this process rather than against no process. */
+const create = async (references, workload) => {
+  const services = []
+
+  for (const reference of references) {
+    const path = shortcuts.resolve(reference)
+    const { Factory } = await import(pathToFileURL(require.resolve(path)).href)
+    const service = await new Factory(boot.host(workload)).service()
+
+    if (service !== null) services.push(service)
+  }
+
+  return services
+}
+
 /**
- * A process, as `toa compose` runs one: the composition, and whatever the extensions keep in
- * a process beside it — the readiness probe.
+ * A process, as `toa compose` runs one: the composition behind a gate, whatever services it
+ * was told to run beside it, and whatever the extensions keep in a process — the readiness
+ * probe, the ear a halt arrives at.
  *
  * `composition` is the other way to boot the same components, and the difference is the point
- * of this one: what belongs to a process is here and not there.
+ * of this one: what belongs to a process is here and not there. So is what a halt takes,
+ * which is why a service that has to be halted is run from here rather than staged apart.
  */
-export const workload = async (paths, options) => {
-  const workload = new boot.Workload(async () => await boot.composition(paths, options))
+export const workload = async (paths, options, services = []) => {
+  const workload = new boot.Workload(async (workload) => {
+    const composition = workload.gate(
+      async () => await boot.composition(paths, options)
+    )
+
+    if (services.length === 0) return composition
+
+    const root = new Connector()
+
+    root.depends([composition, ...(await create(services, workload))])
+
+    return root
+  })
 
   await workload.connect()
 

package/stage/test/boot.mock.js

@@ -8,6 +8,7 @@ const connector = () => ({
   link: mock.fn()
 })
 
+export const map = { use: mock.fn() }
 export const manifest = mock.fn(async () => generate())
 export const component = mock.fn(async () => connector())
 export const composition = mock.fn(async () => connector())

package/stage/types/index.d.ts

@@ -5,6 +5,9 @@ import type * as _boot from '@toa.io/boot'
 
 export function manifest(path: string): Promise<_norm.Component>
 
+/** which version of each component a lookup made in this process asks for */
+export function map(versions: Record<string, string> | undefined): void
+
 export function component(path: string): Promise<_core.Component>
 
 export function composition(