@junoflow/testkit 0.3.0 → 0.9.0

package/src/bindings.js

@@ -0,0 +1,726 @@
+import { fail } from './assert.js';
+import { setFinding } from './findings.js';
+import { names } from './names.js';
+import {
+  assertISO,
+  assertTimezone,
+  resolveInstant,
+  timeResult,
+} from './time.js';
+
+/** The verbs each kind of state binding grants (StateBinding in internal/manifest). */
+const STATE_VERBS = {
+  read: ['get'],
+  read_write: ['get', 'set'],
+  slot: ['claim', 'release'],
+  signal: ['signal', 'retract'],
+};
+const ALL_STATE_VERBS = Object.values(STATE_VERBS).flat();
+
+/** Every control handle carries all four; the host refuses one the type does not take. */
+const CONTROL_VERBS = ['press', 'activate', 'extend', 'release'];
+
+/** Integrations the broker serves itself; none of their actions is read-only. */
+const BUILT_IN_INTEGRATIONS = ['homeassistant', 'mqtt'];
+
+/**
+ * The binding half of flowHarness and appHarness: the state handles, ctx.targets,
+ * ctx.controls, ctx.findings and ctx.credentials, and the h.* calls that seed,
+ * answer and read them back.
+ *
+ * Every handle is keyed by what the source says: a binding name,
+ * `binding.method`, `binding.verb`, a slug.
+ * Never a state id or a control id — the test speaks the source's vocabulary,
+ * and the host's resolution of it is not under test.
+ *
+ * `statesRoot` is the ctx member the state handles hang off, as refusals
+ * spell it (a flow's `state`, an app's `states`); `scoped` says whether that
+ * member carries scoped(), which only a flow has.
+ */
+export function createBindings(
+  manifest,
+  harness,
+  { statesRoot = 'state', scoped = true } = {}
+) {
+  const states = manifest.states ?? {};
+  const targets = manifest.targets ?? {};
+  const controls = manifest.controls ?? {};
+  const credentialIDs = manifest.credentials ?? [];
+  // A flow manifest lists findings; setFinding looks them up by slug.
+  const findingDecls = {
+    findings: Array.isArray(manifest.findings)
+      ? Object.fromEntries(manifest.findings.map((f) => [f.slug, f]))
+      : (manifest.findings ?? {}),
+  };
+
+  // Credentials are a fixture, like the clock: kept across reset().
+  const credentials = {};
+
+  const rec = {
+    values: new Map(),
+    stateCalls: [],
+    scoped: new Map(),
+    claims: new Set(),
+    signals: new Set(),
+    targetAnswers: createAnswers(),
+    targetCalls: [],
+    controlAnswers: createAnswers(),
+    controlCalls: [],
+    findings: [],
+  };
+
+  const h = {
+    /** Seeds read and read_write bindings by name. */
+    states(values = {}) {
+      for (const [name, value] of Object.entries(values)) {
+        valueBinding(name, 'h.states');
+        rec.values.set(name, jsonCopy(value, `h.states — "${name}"`));
+      }
+      return harness();
+    },
+
+    /** A value binding's current value: seeded, or the last set(). */
+    state(name) {
+      valueBinding(name, 'h.state');
+      return jsonCopy(rec.values.get(name));
+    },
+
+    /** Every set, claim, release, signal and retract, in order. */
+    stateCalls: () => rec.stateCalls.map((c) => ({ ...c })),
+
+    targets: {
+      /**
+       * What `binding.method` answers: a value, or a function of the params
+       * (the input, for invoke) whose return is the result.
+       */
+      answer(key, answer) {
+        const [binding, method] = splitKey(key, 'h.targets.answer', 'method');
+        if (!targets[binding]) {
+          fail(
+            `h.targets.answer('${key}') — target "${binding}" is not declared in manifest.json (have: ${names(targets)})`
+          );
+        }
+        const methods = targetMethods(targets[binding]);
+        if (!methods.includes(method)) {
+          fail(
+            `h.targets.answer('${key}') — target "${binding}" has no method "${method}" (have: ${methods.join(', ') || '(none)'})`
+          );
+        }
+        rec.targetAnswers.set(key, answer, 'h.targets.answer');
+        return h.targets;
+      },
+      /** Every target call, in order, inside step.run or not. */
+      calls: () => rec.targetCalls.map((c) => ({ ...c })),
+    },
+
+    controls: {
+      /** What `binding.verb` answers: a ControlResult, or a function returning one. */
+      answer(key, answer) {
+        const [binding, verb] = splitKey(key, 'h.controls.answer', 'verb');
+        if (!controls[binding]) {
+          fail(
+            `h.controls.answer('${key}') — control "${binding}" is not declared in manifest.json (have: ${names(controls)})`
+          );
+        }
+        if (!CONTROL_VERBS.includes(verb)) {
+          fail(
+            `h.controls.answer('${key}') — "${verb}" is not a control verb (have: ${CONTROL_VERBS.join(', ')})`
+          );
+        }
+        rec.controlAnswers.set(key, answer, 'h.controls.answer');
+        return h.controls;
+      },
+      calls: () => rec.controlCalls.map((c) => ({ ...c })),
+    },
+
+    /** Findings as the host collapses them; a cleared instance stays, not standing. */
+    findings: () => rec.findings.map((f) => ({ ...f })),
+
+    /** Sets ctx.credentials by declared id. */
+    credentials(values = {}) {
+      for (const id of Object.keys(values)) {
+        if (!credentialIDs.includes(id)) {
+          fail(
+            `h.credentials — "${id}" is not declared in manifest.json credentials (have: ${credentialIDs.join(', ') || '(none)'})`
+          );
+        }
+      }
+      Object.assign(credentials, values);
+      return harness();
+    },
+  };
+
+  /**
+   * The ctx members for one run; refuse is the run's recording fail().
+   *
+   * policy is what the host refuses on this run. `{ readOnly: true, handler }`
+   * is an app handler declared read_only, and refuses what the host refuses
+   * it, in the host's words: claim, release, a control command, and a call on
+   * a built-in target. Everything else is the caller's to refuse.
+   */
+  function ctx(refuse, policy = {}) {
+    const readOnly = policy.readOnly
+      ? (what) =>
+          refuse(
+            `read-only handler ${JSON.stringify(policy.handler)} cannot ${what}`
+          )
+      : () => {};
+    return {
+      [statesRoot]: stateProxy(refuse, readOnly),
+      targets: namedProxy(
+        targets,
+        (name) =>
+          `ctx.targets.${name} — "${name}" is not declared in manifest.json (have: ${names(targets)})`,
+        (name, target) => targetHandle(refuse, name, target, policy),
+        refuse
+      ),
+      controls: namedProxy(
+        controls,
+        (name) =>
+          `ctx.controls.${name} — "${name}" is not declared in manifest.json (have: ${names(controls)})`,
+        (name) => controlHandle(refuse, name, readOnly),
+        refuse
+      ),
+      findings: {
+        open: async (slug, opts) => finding(refuse, slug, true, opts),
+        clear: async (slug, opts) => finding(refuse, slug, false, opts),
+        set: async (slug, standing, opts) =>
+          finding(refuse, slug, standing === true, opts),
+      },
+      credentials: credentialsProxy(refuse),
+    };
+  }
+
+  function reset() {
+    rec.values.clear();
+    rec.stateCalls.length = 0;
+    rec.scoped.clear();
+    rec.claims.clear();
+    rec.signals.clear();
+    rec.targetAnswers.clear();
+    rec.targetCalls.length = 0;
+    rec.controlAnswers.clear();
+    rec.controlCalls.length = 0;
+    rec.findings.length = 0;
+  }
+
+  // ─── states ────────────────────────────────────────────────────────────────
+
+  /** Fails unless name is a declared read or read_write binding; returns its kind. */
+  function valueBinding(name, where) {
+    const binding = states[name];
+    if (!binding) {
+      fail(
+        `${where} — "${name}" is not declared in manifest.json states (have: ${names(states)})`
+      );
+    }
+    const kind = bindingKind(binding);
+    if (kind !== 'read' && kind !== 'read_write') {
+      fail(
+        `${where} — "${name}" is a ${kind} binding (${grant(binding)} in manifest.json) and holds no value; only a read or read_write binding has one`
+      );
+    }
+    return kind;
+  }
+
+  function stateProxy(refuse, readOnly) {
+    const own = {};
+    if (scoped) {
+      own.scoped = async (name, initial) => {
+        const held = rec.scoped.get(name);
+        const current =
+          held !== undefined && held !== null ? jsonCopy(held) : initial;
+        const setter = async (value) => {
+          rec.scoped.set(name, jsonCopy(value, `scoped "${name}"`, refuse));
+          return value;
+        };
+        return [current, setter];
+      };
+    }
+    return new Proxy(own, {
+      get(own, prop) {
+        if (typeof prop !== 'string' || prop === 'then') return undefined;
+        if (Object.hasOwn(own, prop)) return own[prop];
+        const binding = states[prop];
+        if (!binding) {
+          refuse(
+            `ctx.${statesRoot}.${prop} — "${prop}" is not declared in manifest.json (have: ${names(states)})`
+          );
+        }
+        return stateHandle(refuse, readOnly, prop, binding);
+      },
+    });
+  }
+
+  /**
+   * All six verbs, as the SDK's bindingHandle has them; a verb the binding was
+   * not granted is refused here, as the host refuses it, rather than left for
+   * the generated types to have caught.
+   */
+  function stateHandle(refuse, readOnly, name, binding) {
+    const where = `ctx.${statesRoot}.${name}`;
+    const kind = bindingKind(binding);
+    const granted = STATE_VERBS[kind];
+    const guard = (verb) => {
+      if (!granted.includes(verb)) {
+        refuse(
+          `${where}.${verb}() — "${name}" is a ${kind} binding (${grant(binding)} in manifest.json) and grants ${granted.join(', ')} only`
+        );
+      }
+    };
+    const record = (call) => rec.stateCalls.push({ binding: name, ...call });
+    const needTTL = (verb, opts) => {
+      if (typeof opts?.ttl !== 'string' || opts.ttl === '') {
+        refuse(
+          `${where}.${verb}() needs { ttl }, e.g. ${verb}(${verb === 'claim' ? 'value, ' : ''}{ ttl: '30m' })`
+        );
+      }
+    };
+
+    const handle = {
+      async get() {
+        guard('get');
+        if (!rec.values.has(name)) {
+          refuse(
+            `${where}.get() — the test gave "${name}" no value; seed it with h.states({ ${name}: … })`
+          );
+        }
+        return jsonCopy(rec.values.get(name));
+      },
+      async set(value) {
+        guard('set');
+        const copy = jsonCopy(value, `${where}.set()`, refuse);
+        rec.values.set(name, copy);
+        record({ verb: 'set', value: copy });
+      },
+      // The layer stack is the server's, so a claim or a signal changes no
+      // value here. What it answers is computed from what this harness saw.
+      async claim(value, opts) {
+        // The host refuses a read-only handler's claim before it looks at
+        // the binding, so this comes first.
+        readOnly('claim states');
+        guard('claim');
+        needTTL('claim', opts);
+        rec.claims.add(name);
+        record({
+          verb: 'claim',
+          value: jsonCopy(value, `${where}.claim()`, refuse),
+          opts: { ...opts },
+        });
+        return { status: 'winning' };
+      },
+      async release() {
+        readOnly('release states');
+        guard('release');
+        const released = rec.claims.delete(name) ? 1 : 0;
+        record({ verb: 'release' });
+        return { released };
+      },
+      async signal(opts) {
+        guard('signal');
+        needTTL('signal', opts);
+        rec.signals.add(name);
+        record({ verb: 'signal', opts: { ...opts } });
+      },
+      async retract() {
+        guard('retract');
+        const retracted = rec.signals.delete(name) ? 1 : 0;
+        record({ verb: 'retract' });
+        return { retracted };
+      },
+    };
+    return verbProxy(
+      handle,
+      ALL_STATE_VERBS,
+      (prop) =>
+        `${where}.${prop} — not a state verb; "${name}" grants ${granted.join(', ')}`,
+      refuse
+    );
+  }
+
+  // ─── targets ───────────────────────────────────────────────────────────────
+
+  function targetHandle(refuse, name, target, policy) {
+    const handle = {};
+    for (const method of targetMethods(target)) {
+      handle[method] = async (params, opts) => {
+        // The broker's refusal. An integration action's read_only is the
+        // integration manifest's to say, which the harness does not have, so
+        // only a built-in target can be refused here.
+        if (
+          policy.readOnly &&
+          BUILT_IN_INTEGRATIONS.includes(target?.integration)
+        ) {
+          refuse(
+            `read-only handler ${JSON.stringify(policy.handler)} cannot invoke target ${JSON.stringify(name)}: a built-in ${target.integration} target is never read-only`
+          );
+        }
+        const isInvoke = method === 'invoke' || method === 'invokeAll';
+        // What the SDK sends: an action's params default to {}, an invoke's
+        // input to null.
+        const sent = jsonCopy(
+          isInvoke ? (params ?? null) : (params ?? {}),
+          `ctx.targets.${name}.${method}()`,
+          refuse
+        );
+        const call = { target: name, action: method, params: sent };
+        if (isInvoke && opts !== undefined) call.opts = { ...opts };
+        rec.targetCalls.push(call);
+        return answerFor(
+          refuse,
+          rec.targetAnswers,
+          `${name}.${method}`,
+          `target call ${name}.${method} was not answered — h.targets.answer('${name}.${method}', result)`,
+          sent
+        );
+      };
+    }
+    return verbProxy(
+      handle,
+      Object.keys(handle),
+      (prop) =>
+        `ctx.targets.${name}.${prop} — target "${name}" has no method "${prop}" (have: ${Object.keys(handle).join(', ') || '(none)'})`,
+      refuse
+    );
+  }
+
+  // ─── controls ──────────────────────────────────────────────────────────────
+
+  function controlHandle(refuse, name, readOnly) {
+    const command = async (verb, fields) => {
+      readOnly('command controls');
+      const call = { binding: name, verb };
+      for (const [k, v] of Object.entries(fields)) {
+        if (v !== undefined) call[k] = v;
+      }
+      rec.controlCalls.push(call);
+      const { binding: _b, verb: _v, ...args } = call;
+      const r = await answerFor(
+        refuse,
+        rec.controlAnswers,
+        `${name}.${verb}`,
+        `control command ${name}.${verb} was not answered — h.controls.answer('${name}.${verb}', result)`,
+        args
+      );
+      // controlHandle's normalisation of the host's answer.
+      return {
+        outcome: r?.outcome ?? 'unchanged',
+        active: r?.active === true,
+        value: r?.value ?? null,
+        expires_at: r?.expires_at ?? null,
+      };
+    };
+    const handle = {
+      press: () => command('press', {}),
+      // One runtime signature for a select's activate(option, opts) and a
+      // switch's activate(opts), as in the SDK.
+      activate: (valueOrOpts, opts) => {
+        const value = typeof valueOrOpts === 'string' ? valueOrOpts : undefined;
+        const o = typeof valueOrOpts === 'string' ? opts : valueOrOpts;
+        return command('activate', { value, for: o?.for, until: o?.until });
+      },
+      extend: () => command('extend', {}),
+      release: () => command('release', {}),
+    };
+    return verbProxy(
+      handle,
+      CONTROL_VERBS,
+      (prop) =>
+        `ctx.controls.${name}.${prop} — not a control verb (have: ${CONTROL_VERBS.join(', ')})`,
+      refuse
+    );
+  }
+
+  // ─── findings and credentials ──────────────────────────────────────────────
+
+  function finding(refuse, slug, standing, opts) {
+    try {
+      return setFinding(findingDecls, rec, slug, standing, opts ?? {});
+    } catch (err) {
+      refuse(err.message);
+    }
+  }
+
+  function credentialsProxy(refuse) {
+    // The target is the live map, so Object.keys and `in` see what is set.
+    return new Proxy(credentials, {
+      get(held, id) {
+        if (typeof id !== 'string' || id === 'then') return undefined;
+        if (!credentialIDs.includes(id)) {
+          refuse(
+            `ctx.credentials.${id} — "${id}" is not declared in manifest.json (have: ${credentialIDs.join(', ') || '(none)'})`
+          );
+        }
+        if (!Object.hasOwn(held, id)) {
+          refuse(
+            `ctx.credentials.${id} — the test set no value for it; set it with h.credentials({ ${id}: '…' })`
+          );
+        }
+        return held[id];
+      },
+    });
+  }
+
+  return { h, ctx, reset };
+}
+
+/** The fields ctx.solar() answers with, and the SDK's default for each. */
+const SOLAR_DEFAULTS = {
+  above_horizon: false,
+  elevation: 0,
+  azimuth: 0,
+  rising: false,
+  next_rising: null,
+  next_setting: null,
+};
+
+/**
+ * The world half both harnesses share: h.now, h.timezone and h.solar, and the
+ * ctx.now() and ctx.solar() that answer from them and from nothing else.
+ *
+ * `harnessName` is what a refusal tells the author to pass the fixture to
+ * (`flowHarness({ now })`). What the test said about the world is kept across
+ * reset(): a clock set once for a file is a fixture, not a recording.
+ */
+export function createWorld(harnessName, harness) {
+  const world = { now: undefined, timezone: 'UTC', solar: undefined };
+
+  const h = {
+    /** Freezes ctx.now() at iso: an instant, or wall time in h.timezone(). */
+    now(iso) {
+      assertISO(iso);
+      world.now = iso;
+      return harness();
+    },
+
+    /** The site timezone ctx.now() reads in; UTC unless set. */
+    timezone(tz) {
+      assertTimezone(tz);
+      world.timezone = tz;
+      return harness();
+    },
+
+    /** What ctx.solar() answers. Fields left out take the SDK's defaults. */
+    solar(values) {
+      for (const key of Object.keys(values ?? {})) {
+        if (!(key in SOLAR_DEFAULTS)) {
+          fail(
+            `h.solar — "${key}" is not a SolarResult field (have: ${names(SOLAR_DEFAULTS)})`
+          );
+        }
+      }
+      world.solar = { ...SOLAR_DEFAULTS, ...values };
+      return harness();
+    },
+  };
+
+  /** ctx.now and ctx.solar for one run; refuse is the run's recording fail(). */
+  function ctx(refuse) {
+    return {
+      now() {
+        if (world.now === undefined) {
+          refuse(
+            "ctx.now() was called but the test set no clock — h.now('2026-10-04T18:42:00') " +
+              `(wall time in h.timezone(), default UTC), or ${harnessName}({ now })`
+          );
+        }
+        return timeResult(
+          resolveInstant(world.now, world.timezone),
+          world.timezone
+        );
+      },
+
+      async solar() {
+        if (world.solar === undefined) {
+          refuse(
+            'ctx.solar() was called but the test said nothing about the sun — ' +
+              `h.solar({ above_horizon: true, elevation: 12, … }), or ${harnessName}({ solar })`
+          );
+        }
+        return { ...world.solar };
+      },
+    };
+  }
+
+  /** Applies the harness options' now, timezone and solar, in that order. */
+  function init({ now, timezone, solar }) {
+    if (now !== undefined) h.now(now);
+    if (timezone !== undefined) h.timezone(timezone);
+    if (solar !== undefined) h.solar(solar);
+  }
+
+  return { h, ctx, init };
+}
+
+/**
+ * The methods buildTargets in sdk/src/context.ts gives a target, in its order
+ * of checks: a flow target by flow_id or label first, then mqtt, then Home
+ * Assistant (getState plus one camelCased method per service), then anything
+ * else (each action verbatim).
+ */
+export function targetMethods(target) {
+  if (target?.flow?.flow_id) return ['invoke'];
+  if (target?.flow?.label) return ['invokeAll'];
+  if (target?.integration === 'mqtt') return ['publish'];
+  if (target?.integration === 'homeassistant') {
+    return ['getState', ...(target.actions ?? []).map(actionToMethodName)];
+  }
+  return [...(target?.actions ?? [])];
+}
+
+/** actionToMethodName in sdk/src/context.ts: "tts.cloud_say" → "ttsCloudSay". */
+export function actionToMethodName(action) {
+  return action.replace(/[._]([a-zA-Z])/g, (_, c) => c.toUpperCase());
+}
+
+function bindingKind(binding) {
+  if (binding.slot) return 'slot';
+  if (binding.signal) return 'signal';
+  return binding.access === 'read_write' ? 'read_write' : 'read';
+}
+
+/** The manifest field that made the grant, as the author wrote it. */
+function grant(binding) {
+  if (binding.slot) return `slot: "${binding.slot}"`;
+  if (binding.signal) return `signal: "${binding.signal}"`;
+  return `access: "${binding.access ?? 'read'}"`;
+}
+
+/** A Proxy over a manifest map: a declared name builds its handle, any other is refused. */
+function namedProxy(declared, message, build, refuse) {
+  return new Proxy(
+    {},
+    {
+      get(_own, prop) {
+        if (typeof prop !== 'string' || prop === 'then') return undefined;
+        if (!Object.hasOwn(declared, prop)) refuse(message(prop));
+        return build(prop, declared[prop]);
+      },
+    }
+  );
+}
+
+/** A handle whose unknown members are refused rather than undefined. */
+function verbProxy(handle, verbs, message, refuse) {
+  return new Proxy(handle, {
+    get(own, prop) {
+      if (typeof prop !== 'string' || prop === 'then') return undefined;
+      if (!verbs.includes(prop)) refuse(message(prop));
+      return own[prop];
+    },
+  });
+}
+
+/** The test's answer for key, called with args when it is a function. */
+async function answerFor(refuse, answers, key, unanswered, args) {
+  if (!answers.has(key)) refuse(unanswered);
+  const result = await answers.resolve(key, args, refuse);
+  // A result crosses the socket as JSON; what the handler gets is a copy.
+  return jsonCopy(result, `the answer for ${key}`, refuse);
+}
+
+/**
+ * A registry of answers by key (`binding.method`, `binding.verb`, a step id)
+ * that knows the scenario's two reserved forms, wherever the answer came from:
+ *
+ * - `{ $replay: [a, b, …] }` answers calls in order, and refuses one past the
+ *   end;
+ * - `{ $error: message }` makes the call throw `new Error(message)`, as the
+ *   shim throws for a capability call the host answered with an error. It is
+ *   the handler's to catch, not a refusal.
+ *
+ * Only an object whose sole key is `$replay` or `$error` is either; anything
+ * else, including a function, is an answer as before. Setting a key again
+ * starts its $replay over.
+ */
+export function createAnswers() {
+  const answers = new Map();
+  // How many calls each key has answered since it was set; $replay reads it.
+  const calls = new Map();
+
+  return {
+    set(key, answer, where) {
+      checkAnswerForm(answer, `${where}('${key}')`);
+      answers.set(key, answer);
+      calls.delete(key);
+    },
+    has: (key) => answers.has(key),
+    /** The answer for one call: its $replay item, $error thrown, a function called. */
+    async resolve(key, args, refuse) {
+      let answer = answers.get(key);
+      const n = (calls.get(key) ?? 0) + 1;
+      calls.set(key, n);
+      if (reservedForm(answer) === '$replay') {
+        const items = answer.$replay;
+        if (n > items.length) {
+          refuse(
+            `${key} answered ${items.length} call${items.length === 1 ? '' : 's'} in the scenario; this was call ${n}`
+          );
+        }
+        answer = items[n - 1];
+      }
+      if (reservedForm(answer) === '$error') throw new Error(answer.$error);
+      return typeof answer === 'function' ? await answer(args) : answer;
+    },
+    clear() {
+      answers.clear();
+      calls.clear();
+    },
+  };
+}
+
+/** '$replay' or '$error' when answer is that reserved form, otherwise undefined. */
+function reservedForm(answer) {
+  if (answer === null || typeof answer !== 'object' || Array.isArray(answer)) {
+    return undefined;
+  }
+  const keys = Object.keys(answer);
+  if (keys.length !== 1) return undefined;
+  return keys[0] === '$replay' || keys[0] === '$error' ? keys[0] : undefined;
+}
+
+/** Fails, at the setter, on a $replay or $error that cannot answer anything. */
+function checkAnswerForm(answer, where) {
+  const form = reservedForm(answer);
+  if (form === '$error' && typeof answer.$error !== 'string') {
+    fail(
+      `${where} — $error takes the error's message, a string; got ${JSON.stringify(answer.$error)}`
+    );
+  }
+  if (form === '$replay') {
+    if (!Array.isArray(answer.$replay)) {
+      fail(
+        `${where} — $replay takes an array of answers, one per call; got ${JSON.stringify(answer.$replay)}`
+      );
+    }
+    answer.$replay.forEach((item, i) => {
+      if (reservedForm(item) === '$replay') {
+        fail(`${where} — $replay item ${i} is itself a $replay`);
+      }
+      checkAnswerForm(item, `${where} $replay item ${i}`);
+    });
+  }
+}
+
+/** A JSON round trip, as the wire does it; undefined stays undefined. */
+export function jsonCopy(value, what, failWith = fail) {
+  if (value === undefined) return undefined;
+  let json;
+  try {
+    json = JSON.stringify(value);
+  } catch (err) {
+    failWith(`${what ?? 'value'} is not JSON-serializable: ${err}`);
+  }
+  return json === undefined ? undefined : JSON.parse(json);
+}
+
+/** Splits 'binding.rest' at the first dot. */
+function splitKey(key, where, what) {
+  const dot = typeof key === 'string' ? key.indexOf('.') : -1;
+  if (dot <= 0 || dot === key.length - 1) {
+    fail(
+      `${where}(${JSON.stringify(key)}) — expected 'binding.${what}', e.g. 'kitchenSpeaker.ttsCloudSay'`
+    );
+  }
+  return [key.slice(0, dot), key.slice(dot + 1)];
+}