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

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 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.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))
+* feat(boot)!: a process can be halted and come back ([7196fa5](https://github.com/toa-io/toa/commit/7196fa51a9c882e84c3767a4fdd329fd2df319f5))
+
+### Bug Fixes
+
+* **boot:** declare what a workload does with a quiesce ([0e1521d](https://github.com/toa-io/toa/commit/0e1521d7abae3a3860a29978d267927d814c1d3a))
+* **boot:** keep a halted process alive until it comes back ([3d3cc23](https://github.com/toa-io/toa/commit/3d3cc23835f836f9f98b1d9a448090a2b0d473c8))
+
+### Features
+
+* **boot:** let a process go quiet and be let go again ([0fc3e66](https://github.com/toa-io/toa/commit/0fc3e66f217ab45e85f70271ab0768232b3fa088))
+* **boot:** quiet a tree before taking it down ([7a339ca](https://github.com/toa-io/toa/commit/7a339caea4499509b55daf91061fc9836c0f6e68))
+* **bridges.node:** let a component stop what it started and start it again ([d10d5d1](https://github.com/toa-io/toa/commit/d10d5d16fcd181e717d9d2cef4c7814ae8f2a93f))
+
+### BREAKING CHANGES
+
+* `Host.halt` is `Host.stop`.
+* `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)
+
+### Features
+
+* **core:** refuse a call that writes, made under a request that only reads ([92951d0](https://github.com/toa-io/toa/commit/92951d0f7b95bd5b838097dd6a42db5586968d0b))
+
+
 # [1.0.0-alpha.304](https://github.com/toa-io/toa/compare/v1.0.0-alpha.303...v1.0.0-alpha.304) (2026-09-13)
 
 **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.304",
+  "version": "1.0.0-alpha.306",
   "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.304",
-    "@toa.io/core": "1.0.0-alpha.304",
-    "@toa.io/definitions": "1.0.0-alpha.304",
+    "@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/generic": "1.0.0-alpha.304",
-    "@toa.io/norm": "1.0.0-alpha.304",
+    "@toa.io/norm": "1.0.0-alpha.306",
     "@toa.io/schemas": "1.0.0-alpha.304",
     "clone-deep": "4.0.1",
     "dotenv": "17.4.2",
-    "openspan": "1.0.0-alpha.304"
+    "openspan": "1.0.0-alpha.305"
   },
-  "gitHead": "a95a5a5a64922b11b23142d4acbcee1331ed31aa"
+  "gitHead": "0693d180a8053a7d07dca879dac2a3c4784d6d45"
 }

package/src/call.js

@@ -1,4 +1,4 @@
-import { Call, Transmission } from '@toa.io/core'
+import { Call, safe, Transmission } from '@toa.io/core'
 
 import * as boot from './index.js'
 
@@ -10,5 +10,19 @@ export const call = async (locator, endpoint, definition, entity, source) => {
 
   const stateful = definition.stateful === true
 
-  return new Call(transmission, contract, `${locator.id}.${endpoint}`, source, stateful)
+  /*
+   * An endpoint beginning with `.` is the runtime's own rather than an operation — a lookup, an
+   * exposition — so the safety of operations has nothing to say about it. `Component.invoke`
+   * counts it as no hop in a call chain for the same reason.
+   */
+  const readable = endpoint[0] === '.' || safe(definition.type)
+
+  return new Call(
+    transmission,
+    contract,
+    `${locator.id}.${endpoint}`,
+    source,
+    stateful,
+    readable
+  )
 }

package/src/component.js

@@ -74,6 +74,9 @@ const create = async (manifest, locator) => {
   // when the RC releases what it opened
   if (phases?.dispose !== undefined) decorated.depends(phases.dispose)
 
+  // a dependency of the component, so the walk that stops a tree reaches it there
+  if (phases?.quiescence !== undefined) decorated.depends(phases.quiescence)
+
   return decorated
 }
 

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, { manifest })
   const aspects = boot.extensions.aspects(manifest)
 
   // a system aspect: it is there in every component, declared by none of them

package/src/discovery.js

@@ -31,17 +31,35 @@ export const discovery = async () => {
   }
 }
 
-const lookup = async (locator) => {
-  const call = await boot.call(locator, ENDPOINT, { bindings: BINDINGS })
+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 } }
+  const operations = {
+    [ENDPOINT]: { bindings: BINDINGS },
+    [endpoint(manifest.version)]: { bindings: BINDINGS }
+  }
   const { local, other } = await boot.bindings.produce(exposition, operations)
   const producers = local.concat(other)
 
@@ -52,3 +70,6 @@ export const expose = async (manifest) => {
 
 const BINDINGS = ['@toa.io/bindings.amqp']
 const ENDPOINT = '.lookup'
+
+/** the runtime's own, as `..tasks` and `..instances` are */
+const SEPARATOR = '..'

package/src/host.js

@@ -1,17 +1,29 @@
+import { Gate } from '@toa.io/core'
+
 import * as boot from './index.js'
 
 /**
+ * @param {import('./workload.js').Workload} [workload] the process, where there is one
+ *
  * What the process hosting an extension provides to it. The counterpart of a component's
  * context: an extension reaches the core through this and through nothing else.
  *
  * @returns {import('@toa.io/core/types').extensions.Host}
  */
-export const host = () => ({
-  remote: boot.remote,
+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 }),
   broadcast: boot.bindings.broadcast,
   composition: boot.composition,
   receive: boot.receive,
   atom: boot.atomicity,
   outbound: boot.bindings.outbound,
-  inbound: boot.bindings.inbound
+  inbound: boot.bindings.inbound,
+
+  // a composition booted outside a process — by a scenario, by `toa call` — has no workload, so
+  // its gates are ones nothing ever takes down and a halt asked of it is nobody's to perform
+  gate: (build) => workload?.gate(build) ?? new Gate(build),
+  quiesce: async () => await workload?.quiesce(),
+  cancel: async () => await workload?.cancel(),
+  stop: (seconds) => workload?.stop(seconds)
 })

package/src/index.js

@@ -18,6 +18,7 @@ export { inbox } from './inbox.js'
 export { outbox } from './outbox.js'
 export { atomicity } from './atomicity.js'
 export { atom } from './atom.js'
+export * as map from './map.js'
 export { manifest } from './manifest.js'
 export { operation } from './operation.js'
 export { receivers, receive } from './receivers.js'

package/src/map.js

@@ -0,0 +1,53 @@
+import { readFile } from 'node:fs/promises'
+
+/**
+ * Which version of a component this process asks what that component provides.
+ *
+ * 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.
+ *
+ * @type {string | Record<string, string> | undefined}
+ */
+let source
+
+/**
+ * @param {string | Record<string, string> | 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.
+ *
+ * @param {string} id
+ * @returns {Promise<string | undefined>}
+ */
+export const version = async (id) => {
+  if (source === undefined) return undefined
+  if (typeof source !== 'string') return source[id]
+
+  return (await read(source))[id]
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<Record<string, string>>}
+ */
+async function read(path) {
+  let contents
+
+  try {
+    contents = await readFile(path, 'utf8')
+  } catch (cause) {
+    throw new Error(`Cannot read the component map '${path}'`, { cause })
+  }
+
+  try {
+    return JSON.parse(contents)
+  } catch (cause) {
+    throw new Error(`The component map '${path}' is not JSON`, { cause })
+  }
+}

package/src/receivers.js

@@ -1,3 +1,4 @@
+import assert from 'node:assert'
 import { Receiver, Locator } from '@toa.io/core'
 
 import * as boot from './index.js'
@@ -7,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, { manifest })
 
   for (const [label, definition] of Object.entries(manifest.receivers)) {
     const locator = Locator.parse(label)
@@ -58,14 +59,23 @@ export async function receive(label, group, callback) {
 }
 
 /**
+ * Which transport carries an event, as the component whose event it is declares it.
+ *
  * @param {import('@toa.io/core').Locator} locator
  * @param {string} label
  * @return {Promise<string>}
  */
 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)
+  const { events } = await discovery.lookup(locator, version)
+
+  assert.ok(
+    events?.[event] !== undefined,
+    `'${locator.id}'${version === undefined ? '' : ` at version ${version}`} declares no ` +
+      `event '${event}', which is what '${label}' receives`
+  )
 
   return events[event].binding
 }

package/src/remote.js

@@ -7,16 +7,22 @@ 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 {toa.norm.Component} [manifest] skips discovery when the manifest is already known
+ * @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.
  */
-export const remote = async (locator, source, manifest) => {
+export const remote = async (locator, source, options = {}) => {
+  let { manifest } = options
   let discovery
 
   if (manifest === undefined) {
-    console.debug('Lookup', { locator: locator.id })
+    const version = options.version ?? (await boot.map.version(locator.id))
 
-    discovery = await boot.discovery.discovery(locator)
-    manifest = await discovery.lookup(locator)
+    console.debug('Lookup', { locator: locator.id, version })
+
+    discovery = await boot.discovery.discovery()
+    manifest = await discovery.lookup(locator, version)
   }
 
   // a call binds its consumers, which are loaded rather than required

package/src/workload.js

@@ -1,4 +1,5 @@
-import { Connector } from '@toa.io/core'
+import { console } from 'openspan'
+import { Connector, Gate, deliveries, halting } from '@toa.io/core'
 import { PREDEFINED } from '@toa.io/definitions'
 
 import { resolve } from './extensions/resolve.js'
@@ -22,6 +23,16 @@ export class Workload extends Connector {
   /** @type {import('@toa.io/core/types').extensions.Resident[]} */
   #residents = []
 
+  /** @type {import('@toa.io/core').Gate[]} */
+  #gates = []
+
+  /** @type {NodeJS.Timeout | null} */
+  #timer = null
+
+  #halting = false
+
+  #quiesced = false
+
   /**
    * @param {(workload: Workload) => Promise<import('@toa.io/core').Connector>} build
    *   what the command runs, called once
@@ -32,13 +43,87 @@ export class Workload extends Connector {
     this.#build = build
   }
 
+  /**
+   * A part of this tree a halt takes down and builds again. Handed to extensions as
+   * `Host.gate`, and used by the handlers for what the command runs.
+   *
+   * @param {() => Promise<import('@toa.io/core').Connector>} build
+   * @returns {import('@toa.io/core').Gate}
+   */
+  gate(build) {
+    const gate = new Gate(build)
+
+    this.#gates.push(gate)
+
+    return gate
+  }
+
+  /**
+   * Whether what a halt takes down is up. False from the moment a halt begins until the rebuild
+   * has landed, so whoever watches one watches the thing itself rather than a clock beside it.
+   */
+  running() {
+    return !this.#halting && this.#gates.every((gate) => gate.holding())
+  }
+
+  /**
+   * Whether this process is quiet: it does nothing of its own accord, and holds everything it
+   * had open. What a halt does before it decides whether to go down.
+   */
+  quiescent() {
+    return this.#quiesced
+  }
+
+  /**
+   * Stops what this process does of its own accord and holds open everything it has: the
+   * gateway answers `503`, the clocks stop, and each component gets its `pause`. Nothing
+   * closes, so nothing has to be built again to undo it.
+   *
+   * Awaited, unlike `stop`: whoever asks for this goes on to watch what the deployment does
+   * next, and that is only worth watching once this process has gone quiet.
+   */
+  async quiesce() {
+    if (this.#halting || this.#quiesced || !this.connected) return
+
+    this.#quiesced = true
+
+    await this.halt()
+  }
+
+  /** Undoes a quiesce. Nothing was taken down, so nothing is built again. */
+  async cancel() {
+    if (this.#halting || !this.#quiesced) return
+
+    this.#quiesced = false
+
+    await this.restore()
+  }
+
+  /**
+   * Stops this process for `seconds`, then builds it again.
+   *
+   * Returns before anything closes, on the next tick rather than in the caller's own: whoever
+   * asks for this is a consumer callback more often than not, and a connection waits for the
+   * message being handled before it closes, so a teardown awaited inside that callback would be
+   * waiting on the callback that is waiting on it.
+   *
+   * @param {number} seconds
+   */
+  stop(seconds) {
+    if (this.#halting || !this.connected) return
+
+    this.#halting = true
+
+    setImmediate(() => void this.#cycle(seconds))
+  }
+
   async open() {
     /*
      * Connected here rather than declared as dependencies, because what they are is read from
      * the extensions and a connector's dependencies are walked before `open` runs. The probe
      * goes up before the build so that it answers while the build is still happening.
      */
-    this.#residents = await residents()
+    this.#residents = await residents(this)
 
     for (const resident of this.#residents) {
       this.depends(resident)
@@ -54,6 +139,118 @@ export class Workload extends Connector {
 
     for (const resident of this.#residents) await resident.complete?.()
   }
+
+  async close() {
+    if (this.#timer !== null) {
+      clearTimeout(this.#timer)
+      this.#timer = null
+    }
+  }
+
+  /**
+   * @param {number} seconds
+   */
+  async #cycle(seconds) {
+    /*
+     * The window is measured from here rather than from where the teardown ends.
+     *
+     * A teardown takes as long as what it drains, so a process that started counting afterwards
+     * would be down for a window beginning where everyone else's ended. Counting from the signal
+     * means every process comes back at one instant however long its own teardown took, and one
+     * whose teardown outran the window comes back at once with nothing left to wait for.
+     */
+    const resumesAt = Date.now() + seconds * 1000
+
+    halting.begin()
+
+    console.warn('Halting', { seconds })
+
+    this.#quiesced = true
+
+    /*
+     * Quiet first, then down. A source stopped before the drain begins is work that never
+     * starts, so what the teardown waits for is only what was already in hand — and a component
+     * gets its `pause` while it is still whole, which is the one moment it can release what the
+     * runtime cannot see.
+     */
+    await this.halt()
+
+    /*
+     * Whoever called this stop saw the deployment still, and this process was not: what it is
+     * handling has written no edge yet. Nothing is abandoned — the teardown waits for every
+     * one of these — but it is the one thing that makes a halt take longer than it says, so
+     * it is said out loud.
+     */
+    const inflight = deliveries.inflight()
+
+    if (inflight > 0) console.warn('Halting with deliveries in flight', { inflight })
+
+    await this.#down(seconds)
+
+    const remaining = resumesAt - Date.now()
+
+    if (remaining <= 0) {
+      // said out loud: for as long as it took, this process was neither halted nor working
+      console.warn('Halted late, the teardown outran the window', {
+        seconds,
+        over: Math.round(-remaining / 1000)
+      })
+
+      return await this.#resume()
+    }
+
+    console.warn('Halted', { seconds })
+
+    /*
+     * Referenced, unlike every other timer the runtime keeps: a halted process holds nothing
+     * at all — no connection, no listening socket that is not unreferenced — so this is the
+     * only thing left to keep it alive. Unreferenced, the process would exit here rather than
+     * come back, and whatever restarts it would bring up a process that never heard of the
+     * halt. `close` clears it, so it holds nothing open against a shutdown.
+     */
+    this.#timer = setTimeout(() => void this.#resume(), remaining)
+  }
+
+  /**
+   * In reverse: a gate an extension made is below the one that holds what the command runs.
+   *
+   * @param {number} [seconds] how long they stay down, where they are coming back
+   */
+  async #down(seconds) {
+    for (const gate of [...this.#gates].reverse()) await gate.down(seconds)
+  }
+
+  /**
+   * Building again is building, and nothing about it is special: the same function of the same
+   * arguments, against the same infrastructure, as at boot. So it is tried once, and a failure
+   * ends the process the way a boot failure ends it. Anything else would be a second, weaker
+   * path to being up, one that could paper over a rebuild that does not work, which is precisely
+   * what there is to find out.
+   */
+  async #resume() {
+    this.#timer = null
+
+    try {
+      for (const gate of this.#gates) await gate.up()
+    } catch (error) {
+      console.error('Resume failed', { message: error?.message })
+
+      await this.disconnect().catch((failure) => {
+        console.error('Shutdown after a failed resume failed', { message: failure?.message })
+      })
+
+      process.exit(1)
+    }
+
+    await this.restore()
+
+    this.#quiesced = false
+    this.#halting = false
+
+    halting.end()
+
+    console.info('Resumed')
+  }
 }
 
 /**
@@ -65,7 +262,7 @@ export class Workload extends Connector {
  *
  * @returns {Promise<import('@toa.io/core/types').extensions.Resident[]>}
  */
-async function residents() {
+async function residents(workload) {
   const { instances } = await import('./extensions/instances.js')
 
   await Promise.all(Object.keys(PREDEFINED).map(async (name) => await resolve(name)))
@@ -75,7 +272,7 @@ async function residents() {
   for (const factory of Object.values(instances)) {
     if (factory.resident === undefined) continue
 
-    const resident = await factory.resident(host())
+    const resident = await factory.resident(host(workload))
 
     if (resident !== null && resident !== undefined) residents.push(resident)
   }

package/src/workload.test.js

@@ -0,0 +1,321 @@
+import { describe, it, before, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { Connector } from '@toa.io/core'
+import { environment, timeout } from '@toa.io/generic'
+
+/*
+ * The probe binds a port and the halt listener reaches a broker, and this suite is about
+ * neither: what it exercises is the workload's own lifecycle, so the extensions that would
+ * contribute a resident are off. `TOA_INTROSPECTION` is unset, so introspection's is `null`.
+ */
+environment.set('TOA_TELEMETRY_READY', 'false')
+
+let Workload
+
+before(async () => {
+  ;({ Workload } = await import('./workload.js'))
+})
+
+let sequence
+
+beforeEach(() => {
+  sequence = []
+})
+
+class TestConnector extends Connector {
+  #label
+
+  constructor(label) {
+    super()
+    this.#label = label
+  }
+
+  async open() {
+    sequence.push(`+${this.#label}`)
+  }
+
+  async close() {
+    sequence.push(`-${this.#label}`)
+  }
+
+  async dispose() {
+    sequence.push(`*${this.#label}`)
+  }
+}
+
+/** One that has something to stop doing, which most connectors have not. */
+class QuietConnector extends Connector {
+  #label
+
+  constructor(label) {
+    super()
+    this.#label = label
+  }
+
+  async pause() {
+    sequence.push(`~${this.#label}`)
+  }
+
+  async unpause() {
+    sequence.push(`^${this.#label}`)
+  }
+}
+
+/** Waits for a condition the halt reaches on its own timers. */
+async function until(condition, limit = 2000) {
+  const deadline = Date.now() + limit
+
+  while (Date.now() < deadline) {
+    if (condition()) return
+
+    await timeout(5)
+  }
+
+  assert.fail('condition was not reached')
+}
+
+describe('Workload', () => {
+  it('should connect what the command built', async () => {
+    const workload = new Workload(async () => new TestConnector('a'))
+
+    await workload.connect()
+
+    assert.deepStrictEqual(sequence, ['+a'])
+
+    await workload.disconnect()
+  })
+
+  it('should take down what a gate holds, and leave the rest connected', async () => {
+    let built = 0
+
+    const workload = new Workload(async (workload) => {
+      const gate = workload.gate(async () => {
+        built++
+
+        return new TestConnector('gated')
+      })
+      const root = new Connector()
+
+      root.depends([gate, new TestConnector('above')])
+
+      return root
+    })
+
+    await workload.connect()
+
+    assert.deepStrictEqual(sequence.sort(), ['+above', '+gated'])
+
+    sequence = []
+
+    // a hundredth of a second, so the window is over before the assertions are
+    workload.stop(0.01)
+
+    // `-gated` and not `-above`: what a gate holds is closed, and nothing else is
+    await until(() => sequence.includes('*gated'))
+
+    assert.deepStrictEqual(sequence, ['-gated', '*gated'])
+
+    await until(() => built === 2)
+
+    assert.deepStrictEqual(sequence, ['-gated', '*gated', '+gated'])
+
+    await workload.disconnect()
+  })
+
+  it('should build again rather than reconnect', async () => {
+    const held = []
+
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => {
+        const connector = new TestConnector('a')
+
+        held.push(connector)
+
+        return connector
+      })
+    )
+
+    await workload.connect()
+
+    workload.stop(0.01)
+
+    await until(() => held.length === 2)
+
+    assert.notEqual(held[0], held[1])
+
+    await workload.disconnect()
+  })
+
+  it('should return before anything is closed', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new TestConnector('a'))
+    )
+
+    await workload.connect()
+
+    sequence = []
+    workload.stop(0.01)
+
+    // the caller is a consumer callback: the teardown must not have begun under it
+    assert.deepStrictEqual(sequence, [])
+
+    await until(() => sequence.includes('+a'))
+    await workload.disconnect()
+  })
+
+  it('should make one cycle of two overlapping halts', async () => {
+    let built = 0
+
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => {
+        built++
+
+        return new TestConnector('a')
+      })
+    )
+
+    await workload.connect()
+
+    workload.stop(0.01)
+    workload.stop(0.01)
+
+    await until(() => built === 2)
+    await timeout(50)
+
+    assert.equal(built, 2)
+
+    await workload.disconnect()
+  })
+
+  it('should not halt what is not connected', async () => {
+    const workload = new Workload(async () => new TestConnector('a'))
+
+    workload.stop(0.01)
+
+    await timeout(30)
+
+    assert.deepStrictEqual(sequence, [])
+  })
+
+  it('should quiesce what it holds, closing nothing', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new QuietConnector('a'))
+    )
+
+    await workload.connect()
+
+    sequence = []
+
+    await workload.quiesce()
+
+    assert.deepStrictEqual(sequence, ['~a'])
+    assert.equal(workload.quiescent(), true)
+
+    // nothing was taken down, so the process is still working as far as anyone watching it
+    assert.equal(workload.running(), true)
+
+    await workload.disconnect()
+  })
+
+  it('should undo a quiesce without building anything', async () => {
+    let built = 0
+
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => {
+        built++
+
+        return new QuietConnector('a')
+      })
+    )
+
+    await workload.connect()
+    await workload.quiesce()
+
+    sequence = []
+
+    await workload.cancel()
+
+    assert.deepStrictEqual(sequence, ['^a'])
+    assert.equal(workload.quiescent(), false)
+    assert.equal(built, 1)
+
+    await workload.disconnect()
+  })
+
+  it('should take down a process that is already quiet', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => {
+        const root = new Connector()
+
+        root.depends([new QuietConnector('q'), new TestConnector('a')])
+
+        return root
+      })
+    )
+
+    await workload.connect()
+    await workload.quiesce()
+
+    sequence = []
+    workload.stop(0.01)
+
+    await until(() => sequence.includes('+a'))
+
+    // quieted once, on the quiesce, and not again on the way down
+    assert.deepStrictEqual(sequence, ['-a', '*a', '+a'])
+
+    await workload.disconnect()
+  })
+
+  it('should not let a cancel undo a stop', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new TestConnector('a'))
+    )
+
+    await workload.connect()
+
+    sequence = []
+    workload.stop(0.01)
+
+    await workload.cancel()
+
+    // it goes down and comes back: a cancel is for a quiesce, and this is past one
+    await until(() => sequence.includes('+a'))
+
+    assert.deepStrictEqual(sequence, ['-a', '*a', '+a'])
+
+    await workload.disconnect()
+  })
+
+  it('should keep the process alive while it is halted', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new TestConnector('a'))
+    )
+
+    await workload.connect()
+
+    // long enough that the process would have to be held open for it
+    workload.stop(10)
+
+    await until(() => sequence.includes('*a'))
+
+    // a halted process holds nothing else: unreferenced, this timer would let it exit
+    assert.ok(
+      process.getActiveResourcesInfo().includes('Timeout'),
+      'nothing keeps the process alive until the rebuild'
+    )
+
+    await workload.disconnect()
+  })
+
+  it('should take the gates down on its own disconnection', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new TestConnector('a'))
+    )
+
+    await workload.connect()
+    await workload.disconnect()
+
+    assert.deepStrictEqual(sequence, ['+a', '-a', '*a'])
+  })
+})

package/types/index.d.ts

@@ -32,4 +32,22 @@ export function host(): types.extensions.Host
 /** A process, as a connector: what the command built, and what the extensions keep in one. */
 export class Workload extends core.Connector {
   constructor(build: (workload: Workload) => Promise<core.Connector>)
+
+  /** A part of this process a halt takes down and builds again. */
+  gate(build: () => Promise<core.Connector>): core.Gate
+
+  /** Whether what a halt takes down is up. */
+  running(): boolean
+
+  /** Whether this process is quiet: it does nothing of its own accord and holds everything. */
+  quiescent(): boolean
+
+  /** Stops what this process does of its own accord, holding open everything it has. */
+  quiesce(): Promise<void>
+
+  /** Undoes a quiesce. */
+  cancel(): Promise<void>
+
+  /** Stops this process for `seconds`, then builds it again. */
+  stop(seconds: number): void
 }