@voxgig/sdkgen 4.8.2 → 4.9.0

package/project/.sdk/tm/ts/src/feature/secrets/plugin/Host.ts

@@ -0,0 +1,1132 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Host.ts)
+// Source: https://github.com/voxgig/plugin @ b48ae643eb0eb56c5ebe3198da98cecdf6a7f7fc  [tag: sdk-20260907-0029-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* The host: the lifecycle state machine (§5), extension points (§6),
+ * and resource capture (§8).
+ *
+ * TWO RULES SHAPE EVERY METHOD BELOW.
+ *
+ * Transitions are SEQUENTIAL (§5.2). One at a time, in call order,
+ * never interleaved; a transition triggered from inside a lifecycle
+ * callback is `plugin_reentrant`. A hard rule, because it is the only
+ * way the semantics can be identical in Go, in Ruby and in
+ * single-threaded JavaScript.
+ *
+ * Reconciliation is EAGER (§18's portability budget). A transition
+ * settles by running the state machine to a fixed point, not by
+ * suspending on a promise. Every port must be able to do the same, and
+ * fourteen of them will not have JavaScript's event loop. */
+
+import { Status, Instance, OrderBlock, fail } from './Types'
+import { canonref, tryref, parseref, formatref } from './Ref'
+import { Catalog, Definition, makecatalog } from './Catalog'
+import { resolveorder, Binding, Pin } from './Order'
+import { Spec, Bound, Mode, emit as fanout, compose, provider as pickone } from './Point'
+import { Exported, resolveexport } from './Export'
+import { Provided, Required, Candidate, resolvecapability } from './Capability'
+import { normalizeconfig, resolveoptions } from './Config'
+import {
+  Node, checkcycle, gatesactivation, requirements, restartsonloss,
+} from './Depend'
+
+export type PointSpec = Spec
+
+export type HostOptions = {
+  catalog?: Catalog
+  reserved?: string[]
+  keys?: { instance?: string, default?: string }
+  defaults?: { [name: string]: any }
+  profile?: string
+  points?: { [point: string]: PointSpec }
+  /** §11.3. `restart` (the default) treats provider replacement as an
+   * ordinary runtime operation: deactivate the old store, activate the
+   * new one, and everything that depended on it rides through, having
+   * released the old one's resources in between.
+   *
+   * `hold` is the strict reading — deactivating a required instance is
+   * `plugin_dependency_held`, naming the holders. NOT the default,
+   * because a station that cannot swap a provider without a restart
+   * has lost the argument for having a plugin system. */
+  dependency?: 'restart' | 'hold'
+}
+
+type Live = {
+  ref: string
+  def: Definition
+  status: Status
+  pos: number
+  seq: number
+  options: any
+  state: any
+  order?: OrderBlock
+  /** §11.4's ALWAYS-RELUCTANT rebinding, made concrete: the provider
+   * ref this instance's activation actually selected, per requirement
+   * name. "A satisfied requirement is not re-bound while it stays
+   * satisfied" is a statement about a REMEMBERED choice — recomputing
+   * `providersof(r)[0]` on every question silently re-points a live
+   * consumer at any better-ranked newcomer, and then losing the
+   * provider it was really using does not restart it. Captured at
+   * activate, cleared on the way out. */
+  selected: { [name: string]: string }
+  /** §9.6's `active: false` — "declares it and bars it: it appears in
+   * `host.list()`, and `activate` and `ready` on it fail rather than
+   * quietly doing nothing". THE BAR OUTLIVES THE APPLY THAT SET IT: a
+   * flag consulted only while `apply` ran let a later direct `ready`
+   * bring the instance live, which is the config-switch it exists to
+   * be silently ignored. */
+  barred?: boolean
+  /** Requirements this instance declared but has not been given. */
+  unmet: string[]
+  /** Resources the instance scope holds, newest last — unwound in
+   * REVERSE, because that is the only order in which teardown mirrors
+   * setup (§8.3). */
+  scope: (() => void)[]
+  /** Declared in `define`, inserted only when activation SUCCEEDS
+   * (§8.1). Holding them until then is what makes a failed activate
+   * leave nothing behind. */
+  bindings: Bound[]
+  /** Set when this instance is itself a host (§6.5). */
+  inner?: any
+  /** Declared in `define`, and VISIBLE while merely `loaded` (§11):
+   * they are data, and hiding them would make the loaded state useless
+   * for introspection. */
+  exports: { [key: string]: any }
+  provides: Provided[]
+}
+
+export type Host = ReturnType<typeof makehost>
+
+export function makehost(options?: HostOptions) {
+  const dependency = (options && options.dependency) || 'restart'
+  /** Set for the duration of a bulk teardown, so `held` knows this is a
+   * coordinated operation rather than an ad-hoc deactivation. */
+  let coordinated = false
+
+  const opts = options || {}
+  const catalog = opts.catalog || makecatalog()
+  const reserved = opts.reserved || []
+  const points = opts.points || {}
+
+  const inst: { [ref: string]: Live } = {}
+  const log: string[] = []
+  /** §14: the lifecycle event record. `seq` distinguishes ONE
+   * INCARNATION of stripe$test from the next, which is the whole reason
+   * it is not `pos` (§4 rule 4). */
+  const events: { ref: string, event: string, seq: number, status: Status }[] = []
+  let seqn = 0
+  let open = 0
+  let intransition = false
+  /** WHICH callback is running, not merely that one is. §8.1 puts
+   * resource capture in `activate` and §8.3 says `inst.release` outside
+   * `activate` is `plugin_release_scope` — and `intransition` alone
+   * cannot tell `activate` from `define`, so it admitted an acquire in
+   * `define` whose scope `unload` would never unwind. */
+  let phase: string | null = null
+
+  // --- observation -------------------------------------------------
+
+  /** Introspection NEVER advances the state (§5.2). A status page must
+   * not be a way to accidentally import twenty packages. */
+  const list = (): { [ref: string]: Status } => {
+    const out: { [ref: string]: Status } = {}
+    for (const r of Object.keys(inst).sort()) out[r] = inst[r].status
+    return out
+  }
+
+  const instance = (ref: string): Live | undefined => inst[canonref(ref)]
+
+  const observable = (result?: any) => ({
+    status: list(),
+    open,
+    log: log.slice(),
+    result: undefined === result ? null : result,
+  })
+
+  // --- the state machine -------------------------------------------
+
+  function guard(): void {
+    if (intransition) {
+      fail('plugin_reentrant', 'transition attempted from inside a lifecycle callback')
+    }
+  }
+
+  function need(ref: string): Live {
+    const r = canonref(ref)
+    const e = inst[r]
+    if (!e) fail('plugin_not_loaded', 'no such instance: ' + r, { ref: r })
+    return e
+  }
+
+  function checkreserved(ref: string): void {
+    if (0 === reserved.length) return
+    if (-1 !== reserved.indexOf(parseref(ref).name)) {
+      fail('plugin_ref_reserved', 'ref is reserved by the host: ' + ref, { ref })
+    }
+  }
+
+  function run(e: Live, cb: keyof Definition, at: string): void {
+    const fn = e.def[cb] as any
+    log.push(e.ref + ':' + at)
+    events.push({ ref: e.ref, event: at, seq: e.seq, status: e.status })
+    if ('function' !== typeof fn) return
+    intransition = true
+    phase = at
+    try {
+      fn(api(e))
+    }
+    catch (err: any) {
+      // §12: `plugin_define_failed` and its three siblings are "a
+      // callback raised; wraps the cause". AN ERROR THAT ALREADY
+      // CARRIES A CODE KEEPS IT — the code is the error's identity, and
+      // a plugin that raised `store_unreachable` must not have it
+      // rewritten. Only a code-less error is wrapped, which is the
+      // ordinary case for a callback that let a library error escape.
+      if (err && err.code) throw err
+      fail('plugin_' + at + '_failed',
+        e.ref + ' raised in ' + at + ': ' + (err && err.message),
+        { ref: e.ref, cause: err && err.message })
+    }
+    finally {
+      intransition = false
+      phase = null
+    }
+  }
+
+  /** What a definition's callbacks see. Deliberately not the internal
+   * record: a plugin that could reach `status` could also write it. */
+  function api(e: Live) {
+    return {
+      ref: e.ref,
+      name: parseref(e.ref).name,
+      tag: parseref(e.ref).tag,
+      options: e.options,
+      state: e.state,
+      /** Foreign resources the host did not hand out are registered
+       * explicitly (§8.3); host calls are recorded automatically. */
+      release: (fn: () => void) => {
+        // §8.3: "`inst.release` outside `activate` is
+        // `plugin_release_scope`". `intransition` is true in `define`
+        // too, and a scope entry registered there is never unwound —
+        // `unload` on a merely `loaded` instance does not call `unwind`,
+        // because a loaded instance is not supposed to hold anything.
+        if ('activate' !== phase) {
+          fail('plugin_release_scope', 'release called outside activate')
+        }
+        // SYMMETRIC WITH `acquire`, and it has to be: `open` counts the
+        // resources CURRENTLY HELD, so an entry that is registered and
+        // then unwound must leave the count where it found it.
+        // Incrementing on registration and never decrementing made
+        // every `release` a permanent leak in the counter — invisible
+        // only because no corpus entry used `release` at all, which is
+        // the gap `resource/scope#release-counts` now closes.
+        let done = false
+        e.scope.push(() => { if (!done) { done = true; open -= 1; fn() } })
+        open += 1
+      },
+      /** The synthetic counter the driver owns, so "what is open" is
+       * data rather than an assertion each port words differently.
+       *
+       * Returns its own release, so a plugin can hand one back early.
+       * The scope still holds the entry and unwinding it twice is a
+       * no-op — releasing early must not make teardown wrong. */
+      acquire: (): (() => void) => {
+        // §8.1: resources are "acquired during `activate` — the scope's
+        // actual job". Same reason as `release` above.
+        if ('activate' !== phase) {
+          fail('plugin_release_scope', 'acquire called outside activate')
+        }
+        let done = false
+        const rel = () => { if (!done) { done = true; open -= 1 } }
+        e.scope.push(rel)
+        open += 1
+        return rel
+      },
+      host: () => self,
+
+      /** Bind into a host point. Declared in `define`; the host inserts
+       * it only after `activate` returns successfully (§8.1), which is
+       * why a failing activate leaves no live binding behind. */
+      bind: (point: string, fn: any, band?: number) => {
+        // §12's `plugin_bind_scope`: "binding declared outside
+        // `define`". §8.1 puts binding declaration in `define` and
+        // insertion at a SUCCESSFUL activate, and the guard was the
+        // half that never got written — so a binding added from
+        // `activate` went live without being part of the loaded
+        // definition, and a deactivate/activate cycle appended it
+        // again. The code was in the table before anything raised it.
+        if ('define' !== phase) {
+          fail('plugin_bind_scope', 'bind called outside define: ' + point,
+            { ref: e.ref, point })
+        }
+        if (undefined === points[point]) {
+          fail('plugin_point_unknown', 'no such point: ' + point, { point })
+        }
+        e.bindings.push({ ref: e.ref, point, fn, band: band || 0 })
+      },
+
+      /** Published for other plugins and for the application (§11). */
+      export: (key: string, value: any) => { e.exports[key] = value },
+
+      /** What this instance can do for others (§11.1). */
+      provides: (p: Provided) => { e.provides.push(p) },
+
+      /** Where this binding landed (§6.6) — the plugin-side counterpart
+       * to a host pin. Station found that a plugin can need to KNOW it
+       * is in the right place: its middleware must sit immediately
+       * outside the base transport or its "wire truth" events are
+       * fiction.
+       *
+       * THE HOST DOES NOT POLICE THIS; it just makes the fact
+       * available. A plugin that requires a position it did not get
+       * fails loudly rather than reporting nonsense — and that is the
+       * plugin's call, because only it knows what its position means.
+       * Verification tells a plugin it was misplaced; a pin (§7) stops
+       * the misplacement from being expressible at all. The two are not
+       * substitutes. */
+      position: (point: string) => {
+        const ranked = order(point)
+        const index = ranked.indexOf(e.ref)
+        return {
+          index,
+          count: ranked.length,
+          // §6.2 composes b1(b2(b3(base))) with the FIRST binding
+          // OUTERMOST, so these are not index 0 and index count-1 the
+          // other way round. Getting this backwards is the exact error
+          // the positional pin vocabulary exists to prevent.
+          outermost: 0 === index,
+          innermost: index === ranked.length - 1,
+        }
+      },
+
+      /** AN INSTANCE MAY ITSELF BE A HOST (§6.5), and THE OUTER ONE
+       * OWNS THE INNER ONE'S LIFETIME. Registering the teardown in the
+       * instance scope is what makes that true rather than aspirational:
+       * the inner host closes when the outer instance deactivates, in
+       * the same reverse unwind as every other resource. */
+      nest: (nestopts?: HostOptions) => {
+        if (!intransition) {
+          fail('plugin_release_scope', 'nest called outside a lifecycle callback')
+        }
+        const inner = makehost(nestopts)
+        e.scope.push(() => inner.close())
+        e.inner = inner
+        return inner
+      },
+    }
+  }
+
+  /** AUTO-TAGGING IS EXPLICIT (§4 rule 3). `declare('stripe', {tag:
+   * '?'})` assigns the LOWEST UNUSED POSITIVE INTEGER tag and returns
+   * the assigned pair. Without `'?'`, a collision is an error.
+   *
+   * It needs a host because it must know what is already declared,
+   * which is why it cannot live in the pure `ref` section — the
+   * correction P1.7 made to §15.3. */
+  function autotag(name: string): string {
+    for (let n = 1; ; n++) {
+      const cand = formatref(name, String(n))
+      if (undefined === inst[cand]) return cand
+    }
+  }
+
+  type DeclareSpec = {
+    definition?: string, options?: any, order?: OrderBlock,
+    pos?: number, tag?: string,
+    /** §9.1: "The host declares those instances itself, after the user
+     * merge, and always wins." Set ONLY by `hostdeclare`. */
+    hostowned?: boolean,
+  }
+
+  function declare(ref: string, spec?: DeclareSpec): Live {
+    if (spec && '?' === spec.tag) {
+      ref = autotag(parseref(canonref(ref)).name)
+    }
+    const r = canonref(ref)
+    if (!(spec && spec.hostowned)) checkreserved(r)
+    const s = spec || {}
+    const defname = s.definition || parseref(r).name
+    const def = catalog.get(defname)
+    if (!def) {
+      fail('plugin_unknown_definition', 'not in catalog: ' + defname, { name: defname })
+    }
+
+    const existing = inst[r]
+    if (existing) {
+      // §4 rule 1: a pair addresses at most one instance. Re-declaring
+      // the SAME definition is the idempotent case; a different one is
+      // a duplicate, not a silent overwrite (seneca) and not an
+      // impossibility (sdkgen).
+      if (existing.def.name !== def.name) {
+        fail('plugin_ref_duplicate', 'instance already declared: ' + r, { ref: r })
+      }
+      return existing
+    }
+
+    const e: Live = {
+      ref: r, def, status: 'declared',
+      pos: undefined === s.pos ? Object.keys(inst).length : s.pos,
+      seq: seqn++,
+      options: s.options || {},
+      state: {}, order: s.order, unmet: [], scope: [],
+      bindings: [], exports: {}, provides: [], selected: {},
+    }
+    inst[r] = e
+    return e
+  }
+
+  function load(ref: string, spec?: any): Live {
+    guard()
+    const e = declare(ref, spec)
+    if ('declared' !== e.status) return e   // idempotent in the trivial direction
+    if (spec && spec.options) e.options = spec.options
+    try {
+      run(e, 'define', 'define')
+    }
+    catch (err: any) {
+      e.status = 'failed'
+      throw err
+    }
+    e.status = 'loaded'
+
+    // AT LOAD, and before anything runs: a cycle through
+    // restart-causing requirements does not settle, and the only safe
+    // time to report a non-terminating reconcile is before it starts
+    // (§11.3). `provides` is populated by `define`, which has just run,
+    // so this is the first moment the graph is complete.
+    try { checkcycle(graphnodes()) }
+    catch (err: any) {
+      e.status = 'failed'
+      throw err
+    }
+    return e
+  }
+
+  /** The requirement graph as plain data, for the pure detector. */
+  function graphnodes(): Node[] {
+    return Object.keys(inst).sort().map((r) => ({
+      ref: r,
+      provides: inst[r].provides.map((p) => p.name),
+      requires: requirements(inst[r].options),
+    }))
+  }
+
+  function activate(ref: string): Live {
+    guard()
+    const e = need(ref)
+    if ('live' === e.status) return e        // no-op returning success
+    if ('failed' === e.status) {
+      fail('plugin_bad_state', 'instance has failed: ' + e.ref, { ref: e.ref })
+    }
+    // §9.6: `active: false` bars the instance from running, and the bar
+    // is on the INSTANCE rather than on the apply that set it. `ready`
+    // reaches this through `activate`, which is why one guard covers
+    // both verbs the design names.
+    if (e.barred) {
+      fail('plugin_inactive', 'instance is barred by active: false: ' + e.ref,
+        { ref: e.ref })
+    }
+    if ('declared' === e.status) load(e.ref)
+
+    // A declared requirement that is not live means `pending`:
+    // activation is a STANDING REQUEST, not a one-shot event.
+    if (0 < unmetof(e).length) {
+      e.unmet = unmetof(e)
+      e.status = 'pending'
+      return e
+    }
+
+    try {
+      run(e, 'activate', 'activate')
+    }
+    catch (err: any) {
+      // Unwind whatever the partial activation captured, in reverse.
+      unwind(e)
+      e.status = 'failed'
+      throw err
+    }
+    // §11.4: THE SELECTION IS MADE HERE, once, and remembered. Every
+    // later question — the cascade, `hold`, `unmet` — reads it back
+    // rather than re-ranking, which is what "always-reluctant" means.
+    for (const r of requirements(e.options)) chosen(e, r, true)
+    e.status = 'live'
+    reconcile()
+    return e
+  }
+
+  function deactivate(ref: string): Live {
+    guard()
+    const e = need(ref)
+    if ('loaded' === e.status || 'declared' === e.status) return e
+
+    // §5.2: `unload` is THE ONLY TRANSITION OUT OF `failed`. Falling
+    // through here ran the definition's `deactivate` on an instance that
+    // never completed activation and, if that callback happened to
+    // succeed, returned it to `loaded` — from where it could be
+    // activated again, which is precisely what `failed` exists to
+    // prevent.
+    if ('failed' === e.status) {
+      fail('plugin_bad_state', 'instance has failed: ' + e.ref, { ref: e.ref })
+    }
+
+    if ('pending' === e.status) {
+      // DEACTIVATING A PENDING INSTANCE RUNS NO CALLBACK (§5.2). It
+      // never reached activate, so it holds no scope and no live
+      // bindings; running the definition's deactivate there would be
+      // teardown without matching setup, which plugins are not written
+      // to survive and which could fail an instance that had done
+      // nothing wrong. It cannot fail.
+      e.status = 'loaded'
+      e.unmet = []
+      return e
+    }
+
+    held(e)
+    cascade(e)
+
+    try {
+      run(e, 'deactivate', 'deactivate')
+    }
+    catch (err: any) {
+      unwind(e)
+      e.status = 'failed'
+      throw err
+    }
+    releasecheck(e, unwind(e))
+    e.status = 'loaded'
+    reconcile()
+    return e
+  }
+
+  function unload(ref: string): void {
+    guard()
+    const e = need(ref)
+    if ('live' === e.status || 'pending' === e.status) {
+      if ('live' === e.status) {
+        held(e)
+        cascade(e)
+        try {
+          run(e, 'deactivate', 'deactivate')
+        }
+        catch (err: any) {
+          // §5.2: ANY failure during a transition lands the instance in
+          // `failed`, with the scope STILL FULLY UNWOUND. An earlier
+          // draft let the raise propagate straight out of `unload`,
+          // which left the instance `live` and its scope untouched —
+          // reporting a failure while leaking exactly the resources the
+          // failure was about, and leaving an instance whose bindings
+          // were never removed still participating in every point.
+          unwind(e)
+          e.status = 'failed'
+          throw err
+        }
+        releasecheck(e, unwind(e))
+      }
+      e.status = 'loaded'
+    }
+    if ('loaded' === e.status || 'failed' === e.status) {
+      try { run(e, 'close', 'close') }
+      finally { delete inst[e.ref] }
+      return
+    }
+    delete inst[e.ref]
+  }
+
+  function ready(ref: string): Live {
+    // Runs the whole forward path in one call (§5.1). §15.2's verb list
+    // omits this; §5.1 defines it and §15.3's `declare` row requires the
+    // corpus to pin it, so the list was incomplete rather than
+    // excluding it (DOCS.md §4.2).
+    guard()
+    const r = canonref(ref)
+    if (!inst[r]) declare(r)
+    if ('declared' === inst[r].status) load(r)
+    return activate(r)
+  }
+
+  /** Bindings go live only when activation succeeds (§8.1), so the
+   * teardown is the exact inverse: reverse order, always.
+   *
+   * Returns the errors the scope raised. §8.3: "A failing release does
+   * not stop the rest. Every entry runs, in reverse order, whatever any
+   * of them does; the errors are collected and raised as one
+   * `plugin_release_failed`." An earlier draft swallowed them, which
+   * left the host reporting a clean `loaded` for an instance that may
+   * still be holding what it failed to give back. */
+  /** A selection belongs to ONE activation (§11.4). Leaving `live` by
+   * any door drops it, so the next activation ranks afresh — keeping it
+   * would make a consumer prefer a provider it never actually ran
+   * against. */
+  function unwind(e: Live): any[] {
+    e.selected = {}
+    const errors: any[] = []
+    for (let i = e.scope.length - 1; 0 <= i; i--) {
+      try { e.scope[i]() } catch (err) { errors.push(err) }
+    }
+    e.scope = []
+    return errors
+  }
+
+  /** §8.3: "A failed release ends the instance in `failed`, exactly as a
+   * failed callback does (§5.2) — a release that raised may have leaked,
+   * and an instance that may be holding resources it cannot account for
+   * must not be reactivated." */
+  function releasecheck(e: Live, errors: any[]): void {
+    if (0 === errors.length) return
+    e.status = 'failed'
+    const causes = errors.map((x) => (x && x.message) || String(x))
+    fail('plugin_release_failed',
+      'release failed for ' + e.ref + ': ' + causes.join('; '),
+      { ref: e.ref, cause: causes })
+  }
+
+  /** A REQUIREMENT IS ON A CAPABILITY, not on a ref (§11.1) — it is a
+   * dependency on something that can do the job, and which instance is
+   * doing it is exactly the configuration detail a plugin must not care
+   * about. A bare string is shorthand for `{name}`.
+   *
+   * A ref satisfies too, because a host that genuinely needs a specific
+   * instance should not have to invent a capability for it. */
+  function unmetof(e: Live): string[] {
+    return requirements(e.options)
+      .filter(gatesactivation)
+      .filter((r) => 0 === providersof(r).length)
+      .map((r) => r.name)
+  }
+
+  /** §11.4's always-reluctant selection, and the ONE place a provider
+   * is chosen for a live instance.
+   *
+   * "A satisfied requirement is not re-bound while it stays satisfied."
+   * So: if this instance already selected a provider for `req` and that
+   * provider is STILL among the candidates, it keeps it — a
+   * better-ranked newcomer does not take it. Otherwise the rank
+   * decides, and the choice is remembered.
+   *
+   * `remember` is false for the questions asked ABOUT an instance
+   * rather than BY it — introspection must not create a binding. */
+  function chosen(e: Live, req: Required, remember: boolean): string | undefined {
+    const cands = providersof(req)
+    if (0 === cands.length) return undefined
+    const held = e.selected[req.name]
+    if (undefined !== held && cands.some((c) => c.ref === held)) return held
+    if (remember) e.selected[req.name] = cands[0].ref
+    return cands[0].ref
+  }
+
+  /** The instance currently SELECTED for each of this one's
+   * restart-causing requirements. A BINDING IS TO AN INSTANCE, not to a
+   * capability (§11.1), and that is what decides behaviour when the
+   * bound provider leaves while another match remains: the selected one
+   * going away restarts a `static` consumer even though a survivor is
+   * available. It is not silently re-pointed — `static` is the plugin
+   * saying in writing that it cannot survive a provider swap, and a
+   * survivor being available does not make the swap survivable. */
+  function boundproviders(e: Live): string[] {
+    const out: string[] = []
+    for (const r of requirements(e.options)) {
+      if (!restartsonloss(r)) continue
+      const ref = chosen(e, r, false)
+      if (undefined !== ref && -1 === out.indexOf(ref)) out.push(ref)
+    }
+    return out
+  }
+
+  /** Live instances whose selected provider is `ref` and which would be
+   * restarted by losing it. */
+  function consumersof(ref: string): string[] {
+    return Object.keys(inst).sort().filter((r) => {
+      const c = inst[r]
+      return r !== ref && 'live' === c.status &&
+        -1 !== boundproviders(c).indexOf(ref)
+    })
+  }
+
+  /** §11.3's `hold` asks a DIFFERENT question from the cascade, and
+   * reading it off `consumersof` answered the cascade's.
+   *
+   * The cascade wants the edges that RESTART — mandatory-static and
+   * optional-static — because that is what it has to walk. `hold` says
+   * "deactivating a REQUIRED instance is `plugin_dependency_held`", and
+   * `required` is cardinality: `gatesactivation`, not
+   * `restartsonloss`. The two sets differ in both directions and each
+   * difference was a real bug.
+   *
+   * A MANDATORY-DYNAMIC consumer was excluded, so the strictest policy
+   * let a provider go that a live consumer could not do without —
+   * `dynamic` promises the consumer survives a SWAP, and under `hold`
+   * there is no swap, so it goes back to `pending`, which is precisely
+   * what `hold` exists to prevent.
+   *
+   * An OPTIONAL-STATIC consumer was included, so `hold` refused a
+   * deactivation on behalf of an instance that had said in writing it
+   * does not need the thing. Disruptive, yes — it restarts — but the
+   * policy's word is `required`, and an optional requirement is the
+   * plugin declaring the provider is not. */
+  function holdersof(ref: string): string[] {
+    return Object.keys(inst).sort().filter((r) => {
+      const c = inst[r]
+      if (r === ref || 'live' !== c.status) return false
+      for (const req of requirements(c.options)) {
+        if (!gatesactivation(req)) continue
+        if (chosen(c, req, false) === ref) return true
+      }
+      return false
+    })
+  }
+
+  function providersof(req: Required): Candidate[] {
+    const cands: Candidate[] = []
+    // ASK WHETHER THE NAME IS A REF, do not assume it. A requirement
+    // name is a CAPABILITY name first (§11.1) and capability names are
+    // free-form, so `2fa` and `my cap` are legal ones that no ref could
+    // be called — and `canonref` RAISES on those, which made a perfectly
+    // legal document kill the host right here. `tryref` answers
+    // `undefined` instead, and still canonicalizes when it is a ref
+    // (§4 rule 5), which is what lets `dep$` find `dep`.
+    const asref = tryref(req.name)
+    for (const ref of Object.keys(inst).sort()) {
+      const t = inst[ref]
+      if ('live' !== t.status) continue
+      // A ref satisfies directly.
+      if (ref === asref) {
+        cands.push({ ref, pos: t.pos, provides: { name: req.name } })
+        continue
+      }
+      for (const p of t.provides) {
+        if (p.name === req.name) cands.push({ ref, pos: t.pos, provides: p })
+      }
+    }
+    return resolvecapability(req, cands)
+  }
+
+  /** CONSUMERS GO DOWN FIRST, NOT AFTERWARDS (§11.3).
+   *
+   * The cascade is part of the provider's own deactivation and runs
+   * BEFORE the provider's `deactivate` callback and scope unwind, so a
+   * consumer's teardown can still call the thing it depends on —
+   * flushing a buffer to the store it is about to lose is exactly what
+   * a `deactivate` callback is for, and a cascade that fired after the
+   * provider was already gone would make that impossible.
+   *
+   * Order: consumers deepest-first, then the provider. `unload` and
+   * `close` inherit it, UNDER EITHER DEPENDENCY POLICY, which is what
+   * makes apply's reverse-load-order teardown safe even when a document
+   * happens to list a consumer before its provider. */
+  function cascade(provider: Live, seen?: { [ref: string]: true }): void {
+    const done = seen || {}
+    if (done[provider.ref]) return
+    done[provider.ref] = true
+
+    for (const r of consumersof(provider.ref)) {
+      const c = inst[r]
+      if ('live' !== c.status) continue
+      cascade(c, done)                     // deepest-first
+      let bad = false
+      try { run(c, 'deactivate', 'deactivate') } catch (err) { bad = true }
+      const errors = unwind(c)
+      if (bad || 0 < errors.length) {
+        // §5.2: ANY failure during a transition lands the instance in
+        // `failed`, and a cascaded consumer is not an exception.
+        // Marking it `pending` instead handed it straight back to
+        // `reconcile`, which would activate it again the moment the
+        // provider returned — the one thing `failed` exists to stop.
+        c.status = 'failed'
+        continue
+      }
+      c.status = 'pending'
+      c.unmet = unmetof(c)
+    }
+  }
+
+  /** The hold check is A GUARD ON AD-HOC DEACTIVATION, NOT ON
+   * COORDINATED TEARDOWN. In a bulk operation that is removing the
+   * holders too — `close()`, or an `apply` plan whose own steps
+   * deactivate them — it is suspended for exactly those holders, and
+   * the teardown still runs consumers before providers.
+   *
+   * Otherwise `close()` under `hold` would raise on the first provider
+   * it reached whenever a document happened to list a consumer after
+   * it, which is the policy refusing to allow the one teardown it has
+   * no reason to object to. */
+  function held(e: Live): void {
+    if ('hold' !== dependency) return
+    if (coordinated) return
+    const holders = holdersof(e.ref)
+    if (0 === holders.length) return
+    fail('plugin_dependency_held',
+      'instance is required by live consumers: ' + e.ref,
+      { ref: e.ref, holders })
+  }
+
+  /** EAGER reconciliation: run to a fixed point rather than scheduling.
+   *
+   * Two directions, and both are the reason `pending` exists.
+   * Activation is a STANDING REQUEST, not a one-shot event: a pending
+   * instance whose requirement arrives activates without being asked
+   * again, and a LIVE instance whose requirement is lost goes back to
+   * pending — recursively, through its own consumers. */
+  function reconcile(): void {
+    let moved = true
+    let rounds = 0
+    while (moved) {
+      moved = false
+      if (1000 < ++rounds) break
+
+      // Losses first, so a cascade settles in one pass rather than
+      // alternating with re-activations.
+      for (const r of Object.keys(inst).sort()) {
+        const e = inst[r]
+        if ('live' !== e.status) continue
+        const lost = requirements(e.options)
+          .filter(gatesactivation)
+          .filter((q) => 0 === providersof(q).length)
+        if (0 === lost.length) continue
+        // POLICY IS PER REQUIREMENT, not per instance (§11.3): only the
+        // definition that has the requirement knows what it can cope
+        // with, and one instance may hold both a `static` and a
+        // `dynamic` one. A `dynamic` requirement whose provider is gone
+        // leaves the consumer LIVE and notified; it is a statement
+        // about surviving a swap, so it does not restart here.
+        if (lost.every((q) => !restartsonloss(q))) continue
+        let bad = false
+        try { run(e, 'deactivate', 'deactivate') } catch (err) { bad = true }
+        const errors = unwind(e)
+        if (bad || 0 < errors.length) {
+          e.status = 'failed'
+          moved = true
+          continue
+        }
+        e.status = 'pending'
+        e.unmet = unmetof(e)
+        moved = true
+      }
+
+      for (const r of Object.keys(inst).sort()) {
+        const e = inst[r]
+        if ('pending' !== e.status) continue
+        if (0 < unmetof(e).length) continue
+        try {
+          run(e, 'activate', 'activate')
+          e.status = 'live'
+          e.unmet = []
+          moved = true
+        }
+        catch (err) {
+          unwind(e)
+          e.status = 'failed'
+          moved = true
+        }
+      }
+    }
+  }
+
+  // --- ordering ----------------------------------------------------
+
+  function order(point?: string): string[] {
+    // Sorted by declaration SEQUENCE, which is what makes the §7 sort's
+    // fall-through deterministic in a language whose maps have no
+    // insertion order. §7 breaks ties by `pos`; two instances CAN share
+    // one — `declare` defaults `pos` to the registry size, so an unload
+    // followed by a fresh declare reuses a surviving instance's — and
+    // past that the canonical was falling through to `Object.keys`.
+    // `seq` is that order, made explicit. Found by review of the go
+    // port.
+    const bindings: Binding[] = Object.keys(inst)
+      .filter((r) => 'live' === inst[r].status)
+      .sort((a, b) => inst[a].seq - inst[b].seq)
+      .map((r) => ({ ref: r, pos: inst[r].pos, order: inst[r].order }))
+    const spec = point ? points[point] : undefined
+    return resolveorder(bindings, spec && spec.pin)
+  }
+
+  // --- points ------------------------------------------------------
+
+  /** Live bindings on a point, in resolved order. Recomputed on any
+   * change to the live set (§7) rather than cached at startup — the bug
+   * a host discovers only when something deactivates in production. */
+  function bound(point: string): Bound[] {
+    const ranked = order(point)
+    const out: Bound[] = []
+    for (const ref of ranked) {
+      const e = inst[ref]
+      // The band is the INSTANCE's ordering block (§7), stamped by the
+      // host. A plugin passing its own would be ranking itself above
+      // the order its document declared.
+      const band = (e.order && 'number' === typeof e.order.band) ? e.order.band : 0
+      for (const b of e.bindings) {
+        if (b.point === point) out.push({ ...b, band })
+      }
+    }
+    return out
+  }
+
+  function emit(point: string, arg?: any): any {
+    const spec = points[point]
+    if (undefined === spec) fail('plugin_point_unknown', 'no such point: ' + point, { point })
+    if (spec.kind && 'hook' !== spec.kind) {
+      fail('plugin_point_kind', 'point is not a hook: ' + point, { point, kind: spec.kind })
+    }
+    return fanout(bound(point), (spec.mode || 'emit') as Mode, arg)
+  }
+
+  function call(point: string, ...args: any[]): any {
+    const spec = points[point]
+    if (undefined === spec) fail('plugin_point_unknown', 'no such point: ' + point, { point })
+    if ('chain' !== spec.kind) {
+      fail('plugin_point_kind', 'point is not a chain: ' + point, { point, kind: spec.kind })
+    }
+    const base = spec.base || ((x: any) => x)
+    return compose(bound(point), base)(...args)
+  }
+
+  function provide(point: string, ...args: any[]): any {
+    const spec = points[point]
+    if (undefined === spec) fail('plugin_point_unknown', 'no such point: ' + point, { point })
+    if ('provider' !== spec.kind) {
+      fail('plugin_point_kind', 'point is not a provider: ' + point, { point, kind: spec.kind })
+    }
+    const pick = pickone(bound(point), spec)
+    if (!pick.winner) return spec.default
+    return pick.winner.fn(...args)
+  }
+
+  /** The losers are VISIBLE rather than silently ignored (§6.3). */
+  function shadowed(point: string): string[] {
+    const spec = points[point]
+    if (undefined === spec) return []
+    return pickone(bound(point), spec).shadowed
+  }
+
+  function exports(spec: string): any {
+    const all: Exported[] = []
+    for (const ref of Object.keys(inst).sort()) {
+      const e = inst[ref]
+      // Exports of a `loaded` (not live) instance are VISIBLE (§11).
+      if ('declared' === e.status || 'failed' === e.status) continue
+      for (const k of Object.keys(e.exports)) all.push({ ref, key: k, value: e.exports[k] })
+    }
+    return resolveexport(spec, all)
+  }
+
+  /** The live providers of a capability, best-first (§11.1). */
+  function capability(name: string): string[] {
+    const cands: Candidate[] = []
+    for (const ref of Object.keys(inst).sort()) {
+      const e = inst[ref]
+      if ('live' !== e.status) continue
+      for (const p of e.provides) {
+        if (p.name === name) cands.push({ ref, pos: e.pos, provides: p })
+      }
+    }
+    return resolvecapability({ name }, cands).map((c) => c.ref)
+  }
+
+  // --- documents ---------------------------------------------------
+
+  /** §9.6: "load what is missing, UNLOAD WHAT IS GONE, patch what
+   * changed, and move activation state to match", with the stated
+   * ordering — "deactivations and unloads first (reverse load order),
+   * then loads, then activations in load order".
+   *
+   * THREE PHASES, NOT ONE INTERLEAVED LOOP, and both halves matter. An
+   * earlier draft walked the document once, unloading and activating per
+   * ref, which (a) never looked at instances the new document had
+   * DROPPED, so an integration removed from a config reload stayed live
+   * with its bindings and resources — the case this method exists for —
+   * and (b) activated the first instance before the second was declared,
+   * which is not the order §9.6 states. */
+  function apply(doc: any, profile?: string): void {
+    guard()
+    const norm = normalizeconfig({
+      doc, profile: profile || opts.profile,
+      keys: opts.keys, reserved,
+    })
+
+    const want = norm.order
+    const optionsof: { [ref: string]: any } = {}
+    for (const ref of want) {
+      optionsof[ref] = resolveoptions({
+        ref, doc, profile: profile || opts.profile,
+        shape: shapeof(ref),
+        hostdefaults: opts.defaults && opts.defaults[parseref(ref).name],
+      })
+    }
+
+    /** Should this ref be LIVE after the apply? False for a ref the
+     * document declares lazy or inactive AND for one it does not name at
+     * all — which is what makes "unload what is gone" and "unload what
+     * was toggled off" one rule rather than two. */
+    const wantlive = (ref: string): boolean => {
+      const ent = norm.instance[ref]
+      return undefined !== ent && ent.active && 'eager' === ent.start
+    }
+
+    // --- phase 1: deactivations and unloads, in REVERSE load order ---
+    //
+    // Two populations, and the second is the one that was missing: refs
+    // the document no longer names at all, and refs it now names as lazy
+    // or inactive. Toggling back to lazy or inactive returns an instance
+    // to `declared` BY UNLOADING IT (§9.6) — there is no loaded->declared
+    // transition and there should not be one, because an instance that
+    // has run `define` has state and bindings that only `close` can
+    // properly undo.
+    const drop: string[] = []
+    for (const ref of Object.keys(inst)) {
+      if ('declared' === inst[ref].status) continue
+      if (!wantlive(ref)) drop.push(ref)
+    }
+    // Reverse load order: highest `pos` first, ref-descending for a tie,
+    // so a consumer declared after its provider goes down first.
+    drop.sort((a, b) => (inst[b].pos - inst[a].pos) || (a < b ? 1 : a > b ? -1 : 0))
+    for (const ref of drop) unload(ref)
+
+    // --- phase 2: declare and patch EVERYTHING, in load order --------
+    for (const ref of want) {
+      const ent: Instance = norm.instance[ref]
+      // NO OPTIONS HERE, and the omission is the fix rather than an
+      // oversight. `declare` ADOPTS the options map it is handed as the
+      // instance's own, so passing the resolved map made target and
+      // source THE SAME MAP in the refill three lines below — which
+      // cleared its own source and left a first-time instance with no
+      // options at all. A second apply of the same document filled them
+      // in, because by then `declare` returned the existing entry and
+      // the two maps were distinct. `declare` makes its own empty map
+      // and the refill fills it, so both paths are now one path.
+      declare(ref, { order: ent.order, pos: ent.pos })
+      // The bar is REASSERTED ON EVERY APPLY, in both directions — a
+      // document that turns the instance back on clears it, which is
+      // the whole point of a config switch.
+      inst[ref].barred = !ent.active
+      // REFILL rather than REBIND. A definition's callbacks close over
+      // the options map they were handed at `define`; replacing the
+      // reference here would leave every binding reading the values the
+      // first apply gave it, and a re-applied document would silently do
+      // nothing. Clearing and refilling the same map is portable to every
+      // language, unlike a getter or an interception hook — which the
+      // §18 portability budget forbids anyway.
+      refill(inst[ref].options, optionsof[ref])
+      inst[ref].order = ent.order
+      inst[ref].pos = ent.pos
+    }
+
+    // --- phase 3: loads, in load order -------------------------------
+    //
+    // ONLY THE EAGER, ACTIVE ONES. §9.6: "`apply` declares everything
+    // and activates only what asked for it… A document of twenty lazy
+    // instances is therefore twenty map entries and no executed code."
+    for (const ref of want) {
+      if (wantlive(ref)) load(ref)
+    }
+
+    // --- phase 4: activations, in load order -------------------------
+    //
+    // Separate from the loads because §9.6 names them separately, and
+    // the difference is observable: every `define` runs before the first
+    // `activate`, so a plugin cannot see a half-built registry.
+    //
+    // Activation order does not have to be dependency-sorted (§9.6):
+    // under §11 activation is a standing request, so a consumer
+    // activated before its provider sits in `pending` until the provider
+    // arrives a few lines later in the same plan.
+    for (const ref of want) {
+      if (wantlive(ref)) activate(ref)
+    }
+  }
+
+  function shapeof(ref: string): any {
+    const def = catalog.get(parseref(ref).name)
+    return def && def.shape
+  }
+
+  function setoptions(ref: string, patch: any): void {
+    guard()
+    const e = need(ref)
+    const previous = { ...e.options }
+    refill(e.options, resolveoptions({
+      ref: e.ref, shape: shapeof(e.ref), doc: {}, patch: merge(previous, patch),
+    }))
+    if ('live' === e.status) {
+      if ('function' === typeof e.def.reconfigure) {
+        intransition = true
+        try { e.def.reconfigure(api(e), e.options, previous) }
+        finally { intransition = false }
+      }
+      else {
+        // Always correct and sometimes expensive; `reconfigure` exists
+        // to make the common case cheap (§9.4).
+        deactivate(e.ref)
+        activate(e.ref)
+      }
+    }
+  }
+
+  /** Empty the target and refill it, so callers holding the reference
+   * see the new values. */
+  function refill(target: any, source: any): void {
+    for (const k of Object.keys(target)) delete target[k]
+    for (const k of Object.keys(source || {})) target[k] = source[k]
+  }
+
+  function merge(a: any, b: any): any {
+    const out: any = {}
+    for (const k of Object.keys(a || {})) out[k] = a[k]
+    for (const k of Object.keys(b || {})) out[k] = b[k]
+    return out
+  }
+
+  function close(): void {
+    // A bulk teardown removing the holders too, so `hold` is suspended
+    // for exactly those holders (§11.3) - while the consumers-first
+    // cascade still runs, which is the half that matters.
+    coordinated = true
+    try { for (const r of Object.keys(inst).sort().reverse()) unload(r) }
+    finally { coordinated = false }
+  }
+
+  /** The same record §6.6 gives a plugin about itself, reachable from
+   * outside for the corpus. A plugin asks via `inst.position(point)`. */
+  function positionof(ref: string, point: string): any {
+    const e = inst[canonref(ref)]
+    if (!e) fail('plugin_not_loaded', 'no such instance: ' + ref, { ref })
+    const ranked = order(point)
+    const index = ranked.indexOf(e.ref)
+    return {
+      index, count: ranked.length,
+      outermost: 0 === index,
+      innermost: index === ranked.length - 1,
+    }
+  }
+
+  /** §9.1: a host that reserves a name MUST still be able to declare
+   * the instance it reserved — "The host declares those instances
+   * itself, after the user merge, and always wins."
+   *
+   * Without this, `reserved` was a feature that made its own purpose
+   * impossible: every path to `declare` was barred, including the
+   * embedding host's, so reserving `station` meant station could never
+   * install the adapter it had reserved the name for.
+   *
+   * THE BOUNDARY IS BY METHOD, NOT BY CALLER, and that is a real limit
+   * rather than an oversight. No language here can tell the embedding
+   * host from a plugin holding the same host object — and a plugin that
+   * holds it can already call `close()`. What reservation protects is
+   * CONFIGURATION: documents, profile overlays, `VOXGIG_PLUGIN_*`,
+   * construction options and ordinary `declare`/`load`/`options` calls.
+   * That is what §9.1 lists, and all of it still goes through the
+   * check. */
+  function hostdeclare(ref: string, spec?: DeclareSpec): Live {
+    guard()
+    return declare(ref, { ...(spec || {}), hostowned: true })
+  }
+
+  const self = {
+    catalog, list, instance, order, observable, hostdeclare,
+    trace: () => events.slice(),
+    autotag, positionof,
+    emit, call, provider: provide, shadowed, exports, capability,
+    declare, load, activate, deactivate, unload, ready, apply, close,
+    options: setoptions,
+    define: (def: Definition) => catalog.add(def),
+  }
+  return self
+}