@voxgig/sdkgen 4.8.2 → 4.8.3

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

@@ -0,0 +1,344 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Config.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* The declarative document (§9): normalization, and the ten-level
+ * precedence ladder.
+ *
+ * TWO FUNCTIONS, AND THE SPLIT BETWEEN THEM IS FORCED.
+ *
+ * `normalizeconfig` normalizes STRUCTURE and ENTRY KEYS. It does not
+ * merge options, and cannot: §9.4 makes merge behaviour a property of
+ * the definition's option SHAPE, which normalization has never seen. A
+ * normalizer that flattened the option layers would make
+ * `$MERGE: append` unimplementable at load time, because the layers it
+ * must concatenate would already be collapsed.
+ *
+ * `resolveoptions` applies the ladder, and it is the only place that
+ * knows the shape. */
+
+import { Normalized, Instance, fail } from './Types'
+import { canonref, parseref } from './Ref'
+
+// ---------------------------------------------------------------------
+// normalizeconfig
+// ---------------------------------------------------------------------
+
+export type NormalizeInput = {
+  doc: any
+  profile?: string
+  /** §9.1: a host may rename `instance` and `default` into its own
+   * vocabulary. */
+  keys?: { instance?: string, default?: string }
+  /** §9.1: refs the host declares itself and always wins on. */
+  reserved?: string[]
+}
+
+export function normalizeconfig(input: NormalizeInput): Normalized {
+  const doc = (input && input.doc) || {}
+  const keys = (input && input.keys) || {}
+  const ikey = keys.instance || 'instance'
+  const dkey = keys.default || 'default'
+  const reserved = (input && input.reserved) || []
+  const profile = input && input.profile
+
+  // The rename is applied at TWO PLACES AND NO OTHERS: the document
+  // root, and every profile.<name> overlay root (§9.1). A rename applied
+  // only at the root would leave `profile.prod.sdk` untranslated and
+  // silently drop every environment override the host depends on.
+  // Recursing further would be worse: option data is the definition's.
+  const baseinst = doc[ikey]
+  const basedef = doc[dkey] || {}
+
+  const overlay = profile && doc.profile && doc.profile[profile]
+  const overinst = overlay ? overlay[ikey] : undefined
+  const overdef = (overlay && overlay[dkey]) || {}
+
+  // Entry layers, base then overlay, each as {ref -> entry} plus the
+  // order the form implies.
+  const base = entries(baseinst)
+  const over = entries(overinst)
+
+  for (const r of Object.keys(base.map)) checkreserved(r, reserved)
+  for (const r of Object.keys(over.map)) checkreserved(r, reserved)
+  for (const n of Object.keys(basedef)) checkreserved(n, reserved)
+  for (const n of Object.keys(overdef)) checkreserved(n, reserved)
+
+  // A PARTIAL ARRAY IS NOT A FILTER (§9.1). sdkgen learned this the hard
+  // way: deriving order from a partial array silently dropped
+  // config-activated features. Refs in the base but absent from the
+  // overlay still load, in sorted position AFTER the listed ones. A
+  // profile may also INTRODUCE a ref the base never declared.
+  const order: string[] = []
+  for (const r of over.order) if (-1 === order.indexOf(r)) order.push(r)
+  // The remainder keeps the BASE's own order — array position for the
+  // array form, sorted refs for the map form. Re-sorting here would
+  // discard an array document's positional order entirely, which is the
+  // one thing the array form exists to express.
+  for (const r of base.order) if (-1 === order.indexOf(r)) order.push(r)
+
+  const instance: { [ref: string]: Instance } = {}
+  for (let i = 0; i < order.length; i++) {
+    const ref = order[i]
+    const b = base.map[ref]
+    const o = over.map[ref]
+
+    // MERGE THE ENTRIES AS AUTHORED, THEN APPLY DEFAULTS TO THE RESULT
+    // (§9.3). A safety rule, not a tidiness one: if the overlay had its
+    // defaults filled in before merging it would carry a synthesized
+    // active:true and overwrite a base's false — silently re-enabling a
+    // deliberately disabled integration in production.
+    const active = pick(o, 'active', pick(b, 'active', true))
+    const start = pick(o, 'start', pick(b, 'start', 'eager'))
+    const ord = pick(o, 'order', pick(b, 'order', undefined))
+
+    // Option layers, levels 3-6, IN LADDER ORDER. Never merged here.
+    const layers: any[] = []
+    const nm = parseref(ref).name
+    if (basedef[nm] && undefined !== basedef[nm].options) layers.push(basedef[nm].options)
+    if (b && undefined !== b.options) layers.push(b.options)
+    if (overdef[nm] && undefined !== overdef[nm].options) layers.push(overdef[nm].options)
+    if (o && undefined !== o.options) layers.push(o.options)
+
+    const ent: Instance = { pos: i, active, start, optionlayers: layers }
+    if (undefined !== ord) ent.order = ord
+    instance[ref] = ent
+  }
+
+  // `default` DECLARES NOTHING (§9.3). It is a base for every instance
+  // of that definition; it does not create one, and an entry for a name
+  // with no instances is inert rather than an error — which is what
+  // makes a shared library of defaults shippable.
+  const defout: { [name: string]: any } = {}
+  for (const n of Object.keys(basedef)) defout[n] = basedef[n]
+  for (const n of Object.keys(overdef)) defout[n] = overdef[n]
+
+  return { instance, order, default: defout }
+}
+
+/** Byte-wise, NOT locale-aware and NOT case-folded. All-lowercase refs
+ * sort identically under all three, so only mixed input discriminates:
+ * '@' is 0x40, uppercase 0x41-0x5A, lowercase 0x61-0x7A. */
+function bytewise(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0
+}
+
+function pick(src: any, key: string, dflt: any): any {
+  return src && undefined !== src[key] ? src[key] : dflt
+}
+
+/** Both document forms reduce to {ref -> entry} plus the order the form
+ * implies: array POSITION for the array form, sorted refs for the map
+ * form. */
+function entries(src: any): { map: { [ref: string]: any }, order: string[] } {
+  const map: { [ref: string]: any } = {}
+  const order: string[] = []
+  if (null == src) return { map, order }
+
+  if (Array.isArray(src)) {
+    for (const item of src) {
+      const ref = canonref(item.ref)
+      map[ref] = item
+      order.push(ref)
+    }
+  }
+  else {
+    // Map-form refs arrive as KEYS, through a different path than an
+    // array element's `ref` field — and must canonicalize the same way.
+    for (const key of Object.keys(src)) {
+      map[canonref(key)] = src[key]
+    }
+    order.push(...Object.keys(map).sort(bytewise))
+  }
+  return { map, order }
+}
+
+/** §9.1: reservation is all-or-nothing per NAME, so the tagged forms go
+ * too. A configuration surface that can disable the thing reading it is
+ * not a surface, it is a trap. */
+function checkreserved(ref: string, reserved: string[]): void {
+  if (0 === reserved.length) return
+  const name = parseref(ref).name
+  if (-1 !== reserved.indexOf(name)) {
+    fail('plugin_ref_reserved', 'ref is reserved by the host: ' + ref, { ref })
+  }
+}
+
+// ---------------------------------------------------------------------
+// resolveoptions — §9.3's ten levels, and §9.4's merge directives
+// ---------------------------------------------------------------------
+
+export type ResolveInput = {
+  ref: string
+  /** Level 1 — the definition's option shape. Also carries the $MERGE
+   * directives, which is why merging cannot happen without it. */
+  shape?: any
+  hostdefaults?: any       // 2
+  doc?: any                // 3-6
+  profile?: string
+  env?: any                // 7
+  hostoptions?: any        // 8
+  loadoptions?: any        // 9
+  patch?: any              // 10
+}
+
+export function resolveoptions(input: ResolveInput): any {
+  const shape = input.shape || {}
+  checkshape(shape)
+
+  const ref = canonref(input.ref)
+  const name = parseref(ref).name
+  const doc = input.doc || {}
+  const overlay = input.profile && doc.profile && doc.profile[input.profile]
+
+  // ONE ordered merge, lowest to highest. Levels 3-6 are not two
+  // namespaces collapsed separately and composed afterwards: that
+  // inverts the rule that PROFILE SPECIFICITY OUTRANKS DEFINITION
+  // SPECIFICITY, so a prod per-definition default would lose to a base
+  // instance value.
+  const layers = [
+    defaultsof(shape),                          // 1
+    input.hostdefaults,                         // 2
+    optsof(doc.default, name),                  // 3
+    optsof(doc.instance, ref),                  // 4
+    optsof(overlay && overlay.default, name),   // 5
+    optsof(overlay && overlay.instance, ref),   // 6
+    input.env,                                  // 7
+    input.hostoptions,                          // 8
+    input.loadoptions,                          // 9
+    input.patch,                                // 10
+  ]
+
+  let out: any = {}
+  for (const layer of layers) {
+    if (null == layer) continue
+    out = mergeone(out, layer, shape)
+  }
+  return out
+}
+
+/** The shape's non-directive values are the level-1 defaults. */
+function defaultsof(shape: any): any {
+  const out: any = {}
+  for (const k of Object.keys(shape)) {
+    const v = shape[k]
+    if (v && 'object' === typeof v && !Array.isArray(v) && undefined !== v.$MERGE) continue
+    out[k] = v
+  }
+  return out
+}
+
+function optsof(src: any, key: string): any {
+  if (null == src) return undefined
+  // The array form is equivalent to the map form (§9.1).
+  if (Array.isArray(src)) {
+    for (const item of src) {
+      if (canonref(item.ref) === key) return item.options
+    }
+    return undefined
+  }
+  for (const k of Object.keys(src)) {
+    if (canonref(k) === key) return src[k].options
+  }
+  return undefined
+}
+
+/** Merge ONE layer onto the accumulator, honouring the shape's
+ * directives. The directive holds at EVERY precedence level, not only
+ * between document levels — §9.4 makes it a property of the shape,
+ * which does not know which layer a value arrived from. */
+function mergeone(base: any, over: any, shape: any): any {
+  if (null == over) return base
+  if (!isMap(base) || !isMap(over)) return clone(over)
+
+  const out: any = {}
+  for (const k of Object.keys(base)) out[k] = base[k]
+
+  for (const k of Object.keys(over)) {
+    const directive = shape && shape[k] ? shape[k].$MERGE : undefined
+    const b = out[k]
+    const o = over[k]
+
+    if ('replace' === directive) {
+      out[k] = clone(o)
+    }
+    else if ('append' === directive) {
+      const bl = Array.isArray(b) ? b : []
+      const ol = Array.isArray(o) ? o : [o]
+      out[k] = bl.concat(ol)
+    }
+    else if (directive && 'object' === typeof directive && undefined !== directive.deep) {
+      out[k] = deepto(b, o, directive.deep)
+    }
+    else {
+      // Library default: deep for maps, REPLACE for lists. struct.merge
+      // is element-wise by index, which for option maps is nearly always
+      // wrong — ["a"] over ["x","y","z"] yielding ["a","y","z"] is the
+      // defect station hit on secrets.providers.
+      out[k] = (isMap(b) && isMap(o)) ? mergeone(b, o, undefined) : clone(o)
+    }
+  }
+  return out
+}
+
+/** Merge N levels below this key, replace below that. */
+function deepto(base: any, over: any, n: number): any {
+  if (n <= 0) return clone(over)
+  if (!isMap(base) || !isMap(over)) return clone(over)
+  const out: any = {}
+  for (const k of Object.keys(base)) out[k] = base[k]
+  for (const k of Object.keys(over)) {
+    out[k] = deepto(out[k], over[k], n - 1)
+  }
+  return out
+}
+
+/** §9.4: N is an integer of at least 1, and everything else is an error.
+ *
+ * `{"deep": 0}` is rejected DESPITE having an obvious reading, because
+ * "replace at this key" already has a spelling and two spellings for one
+ * behaviour is the defect class this repo exists to avoid. Without the
+ * stated domain each port picks its own reading — reject, replace,
+ * unlimited merge, or clamp to 1 — and the same document resolves
+ * differently per language. */
+const MERGE_WORDS = ['replace', 'append']
+
+export function checkshape(shape: any): void {
+  if (!isMap(shape)) return
+  for (const k of Object.keys(shape)) {
+    const v = shape[k]
+    if (!isMap(v) || undefined === v.$MERGE) continue
+    const d = v.$MERGE
+
+    if ('string' === typeof d) {
+      if (-1 === MERGE_WORDS.indexOf(d)) {
+        fail('plugin_shape_invalid',
+          'invalid $MERGE directive at ' + k + ': ' + d, { key: k, directive: d })
+      }
+      continue
+    }
+    if (isMap(d) && undefined !== d.deep) {
+      const n = d.deep
+      if ('number' !== typeof n || !Number.isInteger(n) || n < 1) {
+        fail('plugin_shape_invalid',
+          'invalid $MERGE deep at ' + k + ': ' + JSON.stringify(n), { key: k, directive: d })
+      }
+      continue
+    }
+    fail('plugin_shape_invalid',
+      'invalid $MERGE directive at ' + k + ': ' + JSON.stringify(d), { key: k, directive: d })
+  }
+}
+
+function isMap(v: any): boolean {
+  return null != v && 'object' === typeof v && !Array.isArray(v)
+}
+
+function clone(v: any): any {
+  if (Array.isArray(v)) return v.map(clone)
+  if (isMap(v)) {
+    const out: any = {}
+    for (const k of Object.keys(v)) out[k] = clone(v[k])
+    return out
+  }
+  return v
+}

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

@@ -0,0 +1,205 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Depend.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* Dependency cardinality, policy, and the restart graph (§11.3).
+ *
+ * TWO AXES, BOTH DECLARED BY THE DEFINITION THAT HAS THE REQUIREMENT,
+ * because only it knows what it can cope with:
+ *
+ *                | static (default)          | dynamic
+ *   -------------|---------------------------|--------------------------
+ *   mandatory    | unmet -> pending;         | unmet -> pending;
+ *   (default)    | lost  -> pending,         | lost  -> STAYS LIVE,
+ *                |          recursively      |          notified
+ *   -------------|---------------------------|--------------------------
+ *   optional:true| never gates activation;   | never gates activation;
+ *                | a change deactivates and  | a change is a
+ *                | reactivates               | notification, nothing else
+ *
+ * `dynamic` means the plugin has said, IN WRITING, that it can survive
+ * its provider being swapped underneath it. It is not the default
+ * because most plugins cannot, and the cost of wrongly assuming they
+ * can is a live instance holding a dead reference.
+ *
+ * The rebinding-preference axis is deliberately omitted. OSGi has
+ * reluctant vs greedy and it is a knob every author must understand to
+ * read anyone else's component; we take always-reluctant. Three axes
+ * were more than the model can carry across twenty ports. */
+
+import { Required } from './Capability'
+import { tryref } from './Ref'
+import { fail } from './Types'
+
+/** A bare string is shorthand for `{name}`. */
+export function normrequire(r: any): Required {
+  return ('string' === typeof r ? { name: r } : (r || {})) as Required
+}
+
+/** The requirements a definition declared, normalized.
+ *
+ * BOTH AXES ARE READ AT TWO LEVELS, AND THE PER-REQUIREMENT ONE WINS.
+ *
+ * The instance-level `policy` and `optional` list are how a DOCUMENT
+ * states the axis without editing the definition, and they apply to
+ * every requirement. The per-requirement form is the one §11.1's object
+ * syntax exists for, and it is strictly more expressive: an instance
+ * that is `static` on its store and `dynamic` on its metrics cannot be
+ * written at all at the instance level, and that is the ordinary case
+ * rather than an exotic one.
+ *
+ * `optional` unions rather than overriding — both spellings are
+ * statements that this requirement need not gate activation, and there
+ * is no reading under which one of them means "actually, mandatory". */
+export function requirements(options: any): Required[] {
+  const raw: any[] = (options && options.requires) || []
+  const marked: string[] = (options && options.optional) || []
+  const fallback = options && options.policy
+  return raw.map(normrequire).map((r) => {
+    const out: Required = { ...r }
+    if (r.optional || -1 !== marked.indexOf(r.name)) { out.optional = true }
+    if (undefined === out.policy && undefined !== fallback) {
+      out.policy = fallback
+    }
+    return out
+  })
+}
+
+/** Does losing this requirement's SELECTED provider restart the
+ * consumer? The mandatory ones under `static`, and the `static`
+ * optional ones — both make a capability change deactivate and
+ * reactivate. `dynamic` never restarts: mandatory-dynamic stays live
+ * and is notified, optional-dynamic is a notification and nothing
+ * else. */
+export function restartsonloss(r: Required): boolean {
+  return 'dynamic' !== (r.policy || 'static')
+}
+
+/** Does an unmet requirement keep the consumer out of `live`?
+ *
+ * Cardinality alone decides this, NOT policy. `dynamic` is a statement
+ * about surviving a SWAP, not about starting without the thing at all —
+ * a mandatory-dynamic consumer still waits in `pending` for its first
+ * provider. Conflating the two would let a plugin that declared it can
+ * cope with replacement activate with nothing to call. */
+export function gatesactivation(r: Required): boolean {
+  return true !== r.optional
+}
+
+/** Edges that can cause a restart, which is exactly the set a cycle
+ * must be detected over (§11.3).
+ *
+ * Those are the mandatory requirements AND THE `static` OPTIONAL ONES,
+ * because both make a capability change deactivate and reactivate the
+ * consumer — and a cycle of restarts does not settle: A comes up, B
+ * restarts, which changes B's capability, which restarts A,
+ * indefinitely.
+ *
+ * ONLY `dynamic` OPTIONAL EDGES ARE EXCLUDED, and they are the ones the
+ * exclusion was for: two plugins that optionally and dynamically
+ * consume each other's capabilities both activate happily, neither
+ * gates on the other, and each is merely notified when the other
+ * appears. Nothing restarts, so nothing oscillates.
+ *
+ * An earlier draft of §11.3 excluded EVERY optional edge and thereby
+ * admitted the non-terminating case it was trying to permit. */
+export function restartcausing(r: Required): boolean {
+  return gatesactivation(r) || restartsonloss(r)
+}
+
+export type Node = {
+  ref: string
+  provides: string[]
+  requires: Required[]
+}
+
+/** A cycle through restart-causing requirements is
+ * `plugin_dependency_cycle`, detected AT LOAD — before anything runs,
+ * because the failure it describes is a non-terminating reconcile and
+ * the only safe time to report that is before it starts.
+ *
+ * The graph is over capabilities, not refs: an edge runs from a
+ * consumer to EVERY node that provides what it needs, because any of
+ * them could be the one selected and a cycle through any is a cycle.
+ * A node also satisfies its own name as a ref (§11.1), which is why the
+ * ref is a provider of itself here. */
+export function dependencycycle(nodes: Node[]): string[] | null {
+  // TWO INDEXES, NOT ONE MERGED MAP. Capability names and refs are
+  // matched differently — a capability by its exact name, a ref through
+  // the canonical spelling (§4 rule 5) — and a single map keyed by both
+  // can only do one of them. Keyed by both and looked up raw, as this
+  // was, a cycle spelled `a$`/`b$` found no providers and EVADED the
+  // load-time check that exists to catch a non-terminating reconcile:
+  // the same graph, written two ways, gave two answers.
+  const bycap: { [cap: string]: string[] } = {}
+  const isref: { [ref: string]: boolean } = {}
+  for (const n of nodes) {
+    isref[n.ref] = true
+    for (const cap of n.provides) {
+      (bycap[cap] = bycap[cap] || []).push(n.ref)
+    }
+  }
+
+  const edges: { [ref: string]: string[] } = {}
+  for (const n of nodes) {
+    const out: string[] = []
+    for (const r of n.requires) {
+      if (!restartcausing(r)) continue
+      const from: string[] = (bycap[r.name] || []).slice()
+      // A node satisfies its own name AS A REF (§11.1), canonically —
+      // exactly what `providersof` does at runtime, so the load-time
+      // graph and the running one agree about what an edge is.
+      const asref = tryref(r.name)
+      if (undefined !== asref && isref[asref] && -1 === from.indexOf(asref)) {
+        from.push(asref)
+      }
+      for (const p of from) {
+        if (p !== n.ref && -1 === out.indexOf(p)) out.push(p)
+      }
+    }
+    edges[n.ref] = out.sort()
+  }
+
+  // Iterative DFS with an explicit stack: twenty ports, and several of
+  // them have no recursion budget worth relying on.
+  const WHITE = 0, GREY = 1, BLACK = 2
+  const colour: { [ref: string]: number } = {}
+  for (const n of nodes) colour[n.ref] = WHITE
+
+  for (const start of Object.keys(edges).sort()) {
+    if (WHITE !== colour[start]) continue
+    const path: string[] = []
+    const stack: { ref: string, i: number }[] = [{ ref: start, i: 0 }]
+    colour[start] = GREY
+    path.push(start)
+
+    while (0 < stack.length) {
+      const top = stack[stack.length - 1]
+      const next = edges[top.ref][top.i++]
+      if (undefined === next) {
+        colour[top.ref] = BLACK
+        stack.pop()
+        path.pop()
+        continue
+      }
+      if (GREY === colour[next]) {
+        // Report the cycle itself, not the walk that found it.
+        return path.slice(path.indexOf(next)).concat([next])
+      }
+      if (BLACK === colour[next]) continue
+      colour[next] = GREY
+      path.push(next)
+      stack.push({ ref: next, i: 0 })
+    }
+  }
+  return null
+}
+
+/** Raise on a cycle, naming it. Separate from the detector so the
+ * detector stays pure and corpus-testable. */
+export function checkcycle(nodes: Node[]): void {
+  const cycle = dependencycycle(nodes)
+  if (null != cycle) {
+    fail('plugin_dependency_cycle',
+      'requirements cycle: ' + cycle.join(' -> '), { cycle })
+  }
+}

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

@@ -0,0 +1,138 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Env.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+/* Environment overrides (§9.5) — level 7 of the ladder.
+ *
+ * One prefix, so nothing drifts: `VOXGIG_PLUGIN_*`.
+ *
+ *   VOXGIG_PLUGIN_PROFILE            the profile name
+ *   VOXGIG_PLUGIN_<REF>_<PATH>       one option
+ *   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+ *
+ * THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING
+ * OTHERWISE. Ref and path are upper-snake with `$` -> `__` and `.` ->
+ * `_`. But `_` is legal in a name and in a tag, and the mapping folds
+ * case, so `retry$fast` and `retry__fast` both encode to `RETRY__FAST`,
+ * as do `Retry$fast` and `retry$Fast`.
+ *
+ * Rather than restrict a grammar the rest of the stack already uses,
+ * the host DETECTS THE COLLISION: it encodes every ref it holds, and a
+ * key two refs claim is `plugin_env_ambiguous`, naming both. The
+ * affected pair stays configurable by document and by API, just not by
+ * environment — which is the honest trade.
+ *
+ * Pure: a function over a string map and a ref set. The corpus tests it
+ * without touching a real environment. */
+
+import { fail } from './Types'
+import { canonref, parseref } from './Ref'
+
+const PREFIX = 'VOXGIG_PLUGIN_'
+
+export type EnvResult = {
+  profile?: string
+  options: { [ref: string]: any }
+  active: string[]
+  inactive: string[]
+}
+
+export type EnvInput = {
+  env: { [k: string]: string }
+  /** Every ref the host holds. Needed because the encoding is lossy:
+   * without the set there is no way to know where the ref ends and the
+   * path begins in `RETRY__FAST_MIN_DELAY`. */
+  refs?: string[]
+  reserved?: string[]
+}
+
+/** `retry$fast` -> `RETRY__FAST`. */
+export function encoderef(ref: string): string {
+  return ref.replace(/\$/g, '__').replace(/\./g, '_').toUpperCase()
+}
+
+export function applyenv(input: EnvInput): EnvResult {
+  const env = (input && input.env) || {}
+  const refs = ((input && input.refs) || []).map(canonref)
+  const reserved = (input && input.reserved) || []
+  const out: EnvResult = { options: {}, active: [], inactive: [] }
+
+  // Encode every ref the host holds, and refuse a key that two of them
+  // claim. Done up front so the collision is reported even when no
+  // environment variable exercises it — a latent ambiguity is still an
+  // ambiguity, and finding it at deploy time is the failure this exists
+  // to prevent.
+  const byencoded: { [enc: string]: string[] } = {}
+  for (const r of refs) {
+    const e = encoderef(r)
+    ;(byencoded[e] || (byencoded[e] = [])).push(r)
+  }
+  for (const e of Object.keys(byencoded).sort()) {
+    if (1 < byencoded[e].length) {
+      const pair = byencoded[e].slice().sort()
+      fail('plugin_env_ambiguous',
+        'refs collide in the environment encoding as ' + e + ': ' + pair.join(', '),
+        { encoded: e, refs: pair })
+    }
+  }
+
+  // Longest encoded ref first, so `retry$fast` wins over `retry` on
+  // `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+  const encoded = Object.keys(byencoded).sort((a, b) => b.length - a.length)
+
+  for (const key of Object.keys(env).sort()) {
+    if (!key.startsWith(PREFIX)) continue
+    const rest = key.substring(PREFIX.length)
+
+    if ('PROFILE' === rest) { out.profile = env[key]; continue }
+
+    if ('ACTIVE' === rest || 'INACTIVE' === rest) {
+      for (const r of split(env[key])) {
+        const c = canonref(r)
+        // The reservation covers EVERY input layer (§9.1).
+        // VOXGIG_PLUGIN_INACTIVE=station is easier to set than editing
+        // a config file, and INACTIVE has the final word — so guarding
+        // documents alone would leave the one lever this mechanism
+        // exists to deny wide open.
+        checkreserved(c, reserved)
+        if ('ACTIVE' === rest) out.active.push(c)
+        else out.inactive.push(c)
+      }
+      continue
+    }
+
+    const enc = encoded.find((e) => rest === e || rest.startsWith(e + '_'))
+    if (undefined === enc) continue      // not for any ref this host holds
+    const ref = byencoded[enc][0]
+    checkreserved(ref, reserved)
+
+    if (rest === enc) continue           // a ref with no path sets nothing
+    const path = rest.substring(enc.length + 1).toLowerCase().split('_')
+
+    let node = out.options[ref] || (out.options[ref] = {})
+    for (let i = 0; i < path.length - 1; i++) {
+      node = node[path[i]] || (node[path[i]] = {})
+    }
+    node[path[path.length - 1]] = parsevalue(env[key])
+  }
+
+  return out
+}
+
+function split(v: string): string[] {
+  return String(v).split(',').map((s) => s.trim()).filter((s) => 0 < s.length)
+}
+
+function checkreserved(ref: string, reserved: 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 })
+  }
+}
+
+/** Values parse as JSON, FALLING BACK TO STRING — so `8080` is a
+ * number, `true` is a boolean, `{"a":1}` is a map, and `hello` is the
+ * string it looks like rather than a parse error. */
+function parsevalue(v: string): any {
+  try { return JSON.parse(v) }
+  catch (err) { return v }
+}