@junoflow/testkit 0.10.0 → 0.12.0

package/src/index.d.ts

@@ -67,6 +67,18 @@ export interface Manifest {
     string,
     { description?: string; timeout?: string; [k: string]: unknown }
   >;
+  /** Ways this integration offers to reach a person, by channel key. */
+  channels?: Record<
+    string,
+    {
+      name?: string;
+      description?: string;
+      kind?: string;
+      address?: string;
+      answers?: string[];
+      [k: string]: unknown;
+    }
+  >;
   [k: string]: unknown;
 }
 
@@ -85,6 +97,39 @@ export interface IntegrationModule {
   schedules?: Record<string, (event: ScheduleEvent, ctx: never) => unknown>;
   listener?: (ctx: never) => unknown;
   hooks?: Record<string, (ctx: never) => unknown>;
+  channels?: Record<
+    string,
+    {
+      deliver: (attempt: never, ctx: never) => unknown;
+      withdraw?: (attempt: never, ctx: never) => unknown;
+    }
+  >;
+}
+
+/**
+ * The attempt a channel's deliver/withdraw receives — the integration's own
+ * `Attempt` type, restated loosely here as the rest of this file is.
+ */
+export interface ChannelAttempt {
+  id: string;
+  kind: 'ask' | 'notify';
+  address: string;
+  mode: 'keypad' | 'buttons' | 'text' | 'acknowledge' | 'link' | 'notify';
+  urgency: 'urgent' | 'normal' | 'low';
+  message: string;
+  options: { key: string; label: string; digit: number }[];
+  render: { text: string; speech: string };
+  link: string | null;
+  deadline: string | null;
+}
+
+/** One ctx.channels.report call, as the harness recorded it. */
+export interface RecordedReport {
+  attemptId: string;
+  status: 'reached' | 'failed' | 'ended' | 'answered';
+  digit?: number;
+  option?: string;
+  reason?: string;
 }
 
 export interface WebhookRequestInit {
@@ -93,6 +138,10 @@ export interface WebhookRequestInit {
   query?: Record<string, string>;
   /** A string is sent as-is; anything else is JSON.stringify'd. */
   body?: unknown;
+  /**
+   * Defaults to what the host builds: the slot's ctx.webhooks URL, then
+   * subpath and query — or "/" when the slot's URL is null.
+   */
   url?: string;
   subpath?: string;
 }
@@ -185,6 +234,12 @@ export interface ListenOptions {
 export interface Harness {
   config(values: Record<string, unknown>): Harness;
   credentials(values: Record<string, string>): Harness;
+  /**
+   * Sets ctx.webhooks.<slot>.url by declared slot. Every slot starts at a
+   * stand-in URL (https://juno.test/webhooks/test-<slot>); null is what the
+   * host sends with no public URL or no webhook bound. Kept across reset().
+   */
+  webhookUrls(values: Record<string, string | null>): Harness;
   action(name: string, params?: unknown): Promise<unknown>;
   webhook(
     name: string,
@@ -193,6 +248,24 @@ export interface Harness {
   schedule(name: string, event?: ScheduleEvent): Promise<void>;
   /** Runs a declared lifecycle hook (e.g. `activated`) with the same context a schedule gets. */
   hook(name: string): Promise<void>;
+  /**
+   * Runs a declared channel's deliver with an attempt and resolves to the
+   * attempt used. The fixture: `id` `'attempt-1'`, `mode` the channel's first
+   * `answers` (a notification, with no options and no deadline, when it
+   * declares none), one option `{key: 'ack', label: 'OK', digit: 1}`, a
+   * placeholder address of the channel's address kind, rendered text equal to
+   * the message, `link: null`, `deadline` ten minutes from now. Any field can
+   * be overridden.
+   */
+  deliver(
+    channel: string,
+    attempt?: Partial<ChannelAttempt>
+  ): Promise<ChannelAttempt>;
+  /** Runs a declared channel's withdraw; a no-op when it has none, as in production. */
+  withdraw(
+    channel: string,
+    attempt?: Partial<ChannelAttempt>
+  ): Promise<ChannelAttempt>;
   listen(options?: ListenOptions): Promise<void>;
   /** The integration's KV, as an ordinary Map. */
   readonly store: Map<string, unknown>;
@@ -201,6 +274,8 @@ export interface Harness {
   states(): Record<string, unknown>;
   /** The last ctx.status.set report, or null when the handler never reported. */
   status(): RecordedStatus | null;
+  /** What ctx.channels.report sent, in order. Cleared by reset(). */
+  reports(): RecordedReport[];
   emitted(): EmittedEvent[];
   logs(): LogEntry[];
   /** Manifest-vs-module problems; empty when they agree. */
@@ -265,6 +340,8 @@ export interface FlowManifest {
     [k: string]: unknown;
   }>;
   credentials?: string[];
+  /** The people ctx.ask and ctx.notify may name. */
+  people?: string[];
   [k: string]: unknown;
 }
 
@@ -346,10 +423,10 @@ export interface RecordedStateCall {
 export interface RecordedTargetCall {
   target: string;
   action: string;
-  /** What the SDK sends: `{}` when an action is called bare, `null` for an invoke without input. */
+  /** What the SDK sends: `{}` when an action is called bare, `null` for an invoke or start without input. */
   params: unknown;
-  /** invoke/invokeAll only, when given. */
-  opts?: { timeout?: string };
+  /** invoke/invokeAll/start/startAll only, when given. */
+  opts?: { timeout?: string; label?: string };
 }
 
 export interface RecordedControlCall {
@@ -373,6 +450,13 @@ export interface FlowTargets {
    * Answers `binding.method` (`kitchenSpeaker.ttsCloudSay`, `child.invoke`):
    * a value, or a function of the params (an invoke's input) returning one.
    * An action with no result is answered with `undefined`, explicitly.
+   *
+   * A flow target's `child.start` answer is the callee's value (its start
+   * handle fires at open with it as an InvokeResult; `{ $error }` makes a
+   * failed one), and a label target's `notifiers.startAll` answer is the
+   * results array. invoke and invokeAll answer from their own key when set,
+   * else from start's and startAll's. A start answer must not be a promise:
+   * the handle opens at once.
    */
   answer(
     key: string,
@@ -438,6 +522,89 @@ export interface Scenario {
   expect?: unknown;
   /** Flows: the version a recorded run ran. Not applied. */
   flow_version?: number;
+  /** Flows only: as h.questions.answer, keyed by label or `ask#N`. */
+  questions?: Record<string, QuestionAnswer>;
+  /** Flows only: as h.unreachable. */
+  unreachable?: string[];
+}
+
+/**
+ * A handle a handler opened with ctx.after, ctx.at, ctx.all, ctx.ask,
+ * state.<b>.when|becomes|changes or targets.<i>.untilEvent. The harness has no
+ * clock that moves and no bus, so a handle fires only where the engine fires
+ * it at open: an `at` at or before h.now(), a `when` without `for` whose
+ * binding's seeded value already matches (fired at h.now(), or the wall clock
+ * with none set), a question the test answered, and an `all` whose members
+ * all fired at open. An `after`, a `becomes`, a `changes`, a `for` hold, an
+ * `untilEvent` and an unanswered question stay `open` until cancelled or the
+ * run ends; cancelling an `all`'s member cancels the `all`.
+ */
+export interface RecordedHandle {
+  /** `__h_N__`, from 0 in each run, as the shim numbers them. */
+  id: string;
+  /**
+   * What the host records: `timer` for ctx.after and ctx.at, `state` for a
+   * state binding's when/becomes/changes, `event` for untilEvent, `all` for
+   * ctx.all, `run` for a flow target's start/startAll (and so the child of an
+   * invoke/invokeAll, whose timer is a `timer`), `press` for a control
+   * binding's untilPressed, `question` for ctx.ask.
+   */
+  kind: 'timer' | 'state' | 'event' | 'all' | 'run' | 'press' | 'question';
+  label: string | undefined;
+  status: 'open' | 'fired' | 'cancelled';
+}
+
+/**
+ * How a question is answered in a test: by a recipient, with one of its option
+ * keys, through `channel` (default `'test:channel'`) — or `'unanswered'`, every
+ * round over.
+ */
+export type QuestionAnswer =
+  | { by: string; answer: string; channel?: string }
+  | 'unanswered';
+
+/** A question a handler asked, as the host stores it: defaults applied. */
+export interface AskedQuestion {
+  /** The question's handle, `__h_N__`. */
+  id: string;
+  label: string | undefined;
+  to: string[];
+  question: string;
+  /** Key → label, in the order written (the keypad's order). */
+  options: Record<string, string>;
+  mode: 'sequence' | 'all';
+  rounds: number;
+  escalateAfter: string;
+  urgency: 'urgent' | 'normal' | 'low';
+  /** null: every channel kind. */
+  via: string[] | null;
+}
+
+/** A notification a handler sent, defaults applied. */
+export interface RecordedNotification {
+  to: string[];
+  message: string;
+  urgency: 'urgent' | 'normal' | 'low';
+  /** null: every channel kind. */
+  via: string[] | null;
+  link: string | null;
+}
+
+export interface FlowQuestions {
+  /**
+   * Answers the question whose `label` is key — or `ask#N`, the Nth ask of the
+   * trigger (from 1), for one without a label. An answer fires the question at
+   * open with `{ outcome: 'answered', answer, by, channel, at }`, `at` being
+   * h.now() (or the wall clock with none set); `by` must be one of its `to`
+   * and `answer` one of its option keys. `'unanswered'` fires it with
+   * `{ outcome: 'unanswered', attempts: to.length * rounds }` — the host does
+   * not count a recipient no contact could reach, and the harness has no
+   * contacts, so it counts every one. A question left unanswered stays open,
+   * so a wait on it alone refuses, as every wait nothing can answer does.
+   */
+  answer(key: string, value: QuestionAnswer): FlowHarness;
+  /** Every question asked, in order. A refused ask is not one. */
+  asked(): AskedQuestion[];
 }
 
 export interface FlowHarness {
@@ -472,6 +639,11 @@ export interface FlowHarness {
   ): FlowHarness;
   /** Every step.run and step.llm, in order. */
   steps(): RecordedStep[];
+  /**
+   * The last h.trigger's handles, in open order. One still open when the run
+   * ended reads `cancelled`, as the engine closes it.
+   */
+  handles(): RecordedHandle[];
   logs(): FlowLogEntry[];
   /** Triggers declared vs implemented, both ways; empty when they agree. */
   conformance(): string[];
@@ -487,8 +659,24 @@ export interface FlowHarness {
   /** Sets ctx.credentials by declared id. Kept across reset(). */
   credentials(values: Record<string, string>): FlowHarness;
   /**
-   * Clears recordings, answers, seeded states, the scenario's event and
-   * scoped memory; keeps the clock, timezone, solar and credentials.
+   * ctx.ask, answered. ask applies the host's refusals that need only the
+   * manifest (the people grant, every field's limits) with the host's words.
+   */
+  readonly questions: FlowQuestions;
+  /** Every ctx.notify, in order. Each answers `{ unreachable: [] }` unless h.unreachable named someone. */
+  notifications(): RecordedNotification[];
+  /** People ctx.notify reports unreachable (no contact the message may use). */
+  unreachable(...ids: string[]): FlowHarness;
+  /**
+   * Sets ctx.webhooks['<id>'].url for a webhook id a trigger names. Each starts
+   * at a stand-in URL (https://juno.test/webhooks/test-<id>); null is what the
+   * host sends with no public URL. Kept across reset().
+   */
+  webhookUrls(values: Record<string, string | null>): FlowHarness;
+  /**
+   * Clears recordings, answers (questions and unreachable people included),
+   * seeded states, the scenario's event and scoped memory; keeps the clock,
+   * timezone, solar, credentials and webhook URLs.
    */
   reset(): FlowHarness;
 }

package/src/index.js

@@ -4,6 +4,7 @@ import { names } from './names.js';
 import { conformance } from './conformance.js';
 import { createHttpMock, withFetch } from './http.js';
 import { assertValid } from './schema.js';
+import { createWebhookEndpoints } from './webhooks.js';
 
 /** How long h.listen waits before aborting, when nothing else says. */
 const DEFAULT_LISTEN_TIMEOUT_MS = 1000;
@@ -44,6 +45,11 @@ export function harness({ manifest, integration } = {}) {
     // The last ctx.status.set report, or null before the first. One slot, not
     // a list: the host replaces the report on every write.
     status: null,
+    // What ctx.channels.report sent, in order. Cleared by reset().
+    reports: [],
+    // The attempts h.deliver/h.withdraw handed a channel, by id: a report on
+    // one of them is checked against its options the way the host checks it.
+    attempts: new Map(),
     // ctx.signal for every surface but the listener, which brings its own.
     // Never aborted here: the host aborts it on a timeout or a shutdown, and a
     // test has neither.
@@ -51,7 +57,11 @@ export function harness({ manifest, integration } = {}) {
   };
 
   const http = createHttpMock();
-  const ctx = buildContext(manifest, state);
+  const webhooks = createWebhookEndpoints(
+    Object.keys(manifest.webhooks ?? {}),
+    'a webhook slot in manifest.json'
+  );
+  const ctx = buildContext(manifest, state, webhooks);
 
   const h = {
     /** Merge values into ctx.config. Rejects a slot the manifest never declared. */
@@ -68,6 +78,16 @@ export function harness({ manifest, integration } = {}) {
       return h;
     },
 
+    /**
+     * Sets ctx.webhooks.<slot>.url. Every declared slot starts at a stand-in
+     * URL; null is what the host sends with no public URL or no webhook bound.
+     * Kept across reset().
+     */
+    webhookUrls(values = {}) {
+      webhooks.set(values);
+      return h;
+    },
+
     async action(name, params) {
       const declared = manifest.actions?.[name];
       if (!declared) {
@@ -94,7 +114,7 @@ export function harness({ manifest, integration } = {}) {
       }
       const handler = requireHandler(integration, 'webhooks', name, 'webhook');
       assertRequiredSlots(manifest, state);
-      const req = buildWebhookRequest(request);
+      const req = buildWebhookRequest(request, webhooks.url(name));
 
       const result = await withFetch(http.fetch, () =>
         handler(req, emitting(ctx, manifest, state))
@@ -147,6 +167,23 @@ export function harness({ manifest, integration } = {}) {
       }
     },
 
+    /**
+     * Runs a declared channel's deliver with an attempt — a fixture one, with
+     * any field overridden — exactly as the host would, and resolves to the
+     * attempt it used. Reports land in h.reports().
+     */
+    async deliver(channel, attempt) {
+      return runChannelHook(channel, 'deliver', attempt);
+    },
+
+    /**
+     * Runs a declared channel's withdraw, as when the question the attempt
+     * carried closes. A channel without withdraw is a no-op, as in production.
+     */
+    async withdraw(channel, attempt) {
+      return runChannelHook(channel, 'withdraw', attempt);
+    },
+
     /**
      * Runs the listener until `until` holds, then aborts and waits for it to
      * unwind. A listener that ignores its abort signal fails here rather than
@@ -220,6 +257,8 @@ export function harness({ manifest, integration } = {}) {
         ...state.status,
         ...(state.status.details && { details: { ...state.status.details } }),
       },
+    /** What ctx.channels.report sent, in order. */
+    reports: () => state.reports.map((r) => ({ ...r })),
     /** Events the handler put on the bus, in order. */
     emitted: () => state.emitted.slice(),
     /** Everything the handler logged, with its level. */
@@ -235,21 +274,140 @@ export function harness({ manifest, integration } = {}) {
       state.logs.length = 0;
       state.publishedStates.clear();
       state.status = null;
+      state.reports.length = 0;
+      state.attempts.clear();
       state.store.clear();
       http.reset();
       return h;
     },
   };
 
+  async function runChannelHook(channel, hook, overrides) {
+    const declared = manifest.channels?.[channel];
+    if (!declared) {
+      fail(
+        `channel "${channel}" is not declared in manifest.json (have: ${names(manifest.channels)})`
+      );
+    }
+    const handlers = integration.channels?.[channel];
+    if (typeof handlers?.deliver !== 'function') {
+      fail(
+        `channel "${channel}" is declared in manifest.json but the default export does not implement its deliver`
+      );
+    }
+    assertRequiredSlots(manifest, state);
+    const attempt = { ...fixtureAttempt(declared), ...overrides };
+    state.attempts.set(attempt.id, attempt);
+
+    const handler = handlers[hook];
+    // withdraw is optional: the SDK completes a missing one as a no-op.
+    if (handler === undefined && hook === 'withdraw') return attempt;
+    if (typeof handler !== 'function') {
+      fail(`channel "${channel}"'s ${hook} is not a function`);
+    }
+    const result = await withFetch(http.fetch, () =>
+      handler(attempt, emitting(ctx, manifest, state))
+    );
+    if (result !== undefined) {
+      fail(
+        `channel "${channel}"'s ${hook} returned a value; a channel handler reports through ctx and returns nothing`
+      );
+    }
+    return attempt;
+  }
+
   return h;
 }
 
+/** A placeholder address per manifest.AddressKinds. */
+const ADDRESS_PLACEHOLDERS = {
+  phone: '+46700000000',
+  email: 'person@example.test',
+  text: 'test-address',
+};
+
+/**
+ * The attempt h.deliver hands a channel unless the test says otherwise: a
+ * one-option question in the channel's first answer mode, or a notification
+ * when the channel declares no answers — the only thing such a channel can
+ * carry. Rendered text is the message itself, as it is for every mode but
+ * keypad.
+ */
+function fixtureAttempt(channel) {
+  const mode = channel.answers?.[0] ?? 'notify';
+  const notify = mode === 'notify';
+  const message = notify ? 'This is a test notification.' : 'Is this a test?';
+  return {
+    id: 'attempt-1',
+    kind: notify ? 'notify' : 'ask',
+    address: ADDRESS_PLACEHOLDERS[channel.address] ?? 'test-address',
+    mode,
+    urgency: 'normal',
+    message,
+    options: notify ? [] : [{ key: 'ack', label: 'OK', digit: 1 }],
+    render: { text: message, speech: message },
+    link: null,
+    deadline: notify ? null : new Date(Date.now() + 10 * 60_000).toISOString(),
+  };
+}
+
+const REPORT_STATUSES = ['reached', 'failed', 'ended', 'answered'];
+
+/**
+ * The one call behind ctx.channels.report, applying the host's refusals that
+ * need no database: an install with no channels, the status vocabulary,
+ * exactly one of digit or option, and — for an attempt this harness handed out
+ * — a digit or option the attempt has. An id the harness never issued is
+ * recorded, not refused: a webhook test reports on a reference it made up, and
+ * the host's "was not issued" check needs the attempt rows a test does not
+ * have.
+ */
+function reportChannel(manifest, state, attemptId, report) {
+  const install = manifest.id ?? manifest.name;
+  if (Object.keys(manifest.channels ?? {}).length === 0) {
+    fail(`channel.report: ${install} declares no channels`);
+  }
+  const { status, digit, option, reason } = report ?? {};
+  if (!REPORT_STATUSES.includes(status)) {
+    fail(
+      `channel.report: status "${status}" must be reached, failed, ended or answered`
+    );
+  }
+  if (status === 'answered') {
+    if ((digit === undefined) === (option === undefined)) {
+      fail('channel.report: answered needs exactly one of digit or option');
+    }
+    const options = state.attempts.get(attemptId)?.options;
+    if (options && digit !== undefined) {
+      if (!Number.isInteger(digit) || digit < 1 || digit > options.length) {
+        fail(
+          `channel.report: digit ${digit} is not an option (1–${options.length})`
+        );
+      }
+    }
+    if (options && option !== undefined) {
+      if (!options.some((o) => o.key === option)) {
+        fail(
+          `channel.report: option "${option}" is not one of ${options.map((o) => o.key).join(', ')}`
+        );
+      }
+    }
+  }
+  state.reports.push({
+    attemptId,
+    status,
+    ...(digit !== undefined && { digit }),
+    ...(option !== undefined && { option }),
+    ...(reason !== undefined && { reason }),
+  });
+}
+
 /**
  * The base context, matching what integration-entrypoint.ts builds. Handlers
  * cannot tell the difference, which is the only way a test here means anything
  * about how the code runs there.
  */
-function buildContext(manifest, state) {
+function buildContext(manifest, state, webhooks) {
   const log = (message, data) =>
     state.logs.push({ level: 'debug', message, data });
   log.info = (message, data) =>
@@ -262,6 +420,11 @@ function buildContext(manifest, state) {
   return {
     config: state.config,
     credentials: state.credentials,
+    // A getter, so a URL set after the harness was built is what the next
+    // invocation reads — the host resolves it per invocation too.
+    get webhooks() {
+      return webhooks.ctx();
+    },
     log,
     // Present on every surface, as in production. A non-listener test never
     // aborts it, which is also true of an invocation that finishes in time;
@@ -305,6 +468,11 @@ function buildContext(manifest, state) {
         setStatus(state, report);
       },
     },
+    channels: {
+      async report(attemptId, report) {
+        reportChannel(manifest, state, attemptId, report);
+      },
+    },
   };
 }
 
@@ -468,7 +636,10 @@ function requireHandler(integration, surface, name, kind) {
   return handler;
 }
 
-function buildWebhookRequest(request) {
+// url defaults to what the host would build: the slot's URL, then the subpath
+// and the query string — so a signature over the URL verifies in a test as it
+// does in production. With no URL for the slot it stays '/'.
+function buildWebhookRequest(request, slotURL) {
   const body =
     typeof request.body === 'string'
       ? request.body
@@ -480,12 +651,18 @@ function buildWebhookRequest(request) {
     query: request.query ?? {},
     body,
     json: parseJSONOrNull(body),
-    url: request.url ?? '/',
+    url: request.url ?? requestURL(slotURL, request),
     subpath: request.subpath ?? '',
     form: parseFormOrNull(headers, body),
   };
 }
 
+function requestURL(slotURL, request) {
+  if (slotURL === null) return '/';
+  const query = new URLSearchParams(request.query ?? {}).toString();
+  return slotURL + (request.subpath ?? '') + (query ? `?${query}` : '');
+}
+
 // The host's rule: lower-cased content-type, media type
 // application/x-www-form-urlencoded (a charset parameter is ignored), first
 // value per key — else null.

package/src/scenario.js

@@ -11,9 +11,10 @@ import { fail } from './assert.js';
  * - `event` is kept by flowHarness for an event-less `h.trigger(name)`.
  * - `flow_version` is the version a recorded run ran, which a fixture made
  *   from that run carries.
- * - An app has no trigger, event or step.llm. It ignores `trigger` and
- *   `event`, so one scenario can describe both, and `llm` is unknown to it:
- *   an answer it would never read is a mistake, not a no-op.
+ * - An app has no trigger, event, step.llm, ask or notify. It ignores
+ *   `trigger` and `event`, so one scenario can describe both, and `llm`,
+ *   `questions` and `unreachable` are unknown to it: an answer it would never
+ *   read is a mistake, not a no-op.
  */
 const SHARED = {
   trigger: null,
@@ -33,6 +34,16 @@ const KEYS = {
   flow: {
     ...SHARED,
     llm: (h, v) => answerAll(v, 'llm', (k, a) => h.llm(k, a)),
+    questions: (h, v) =>
+      answerAll(v, 'questions', (k, a) => h.questions.answer(k, a)),
+    unreachable: (h, v) => {
+      if (!Array.isArray(v)) {
+        fail(
+          `h.scenario — "unreachable" lists person ids; got ${JSON.stringify(v)}`
+        );
+      }
+      h.unreachable(...v);
+    },
     flow_version: null,
   },
   app: SHARED,

package/src/webhooks.js

@@ -0,0 +1,41 @@
+import { fail } from './assert.js';
+
+/**
+ * The URL a webhook has until a test sets one: shaped like Juno's
+ * (`<public URL>/webhooks/<token>`), so a handler's happy path — the one where
+ * the site has a public URL and the webhook is bound — is what runs by default.
+ */
+export function defaultWebhookURL(key) {
+  return `https://juno.test/webhooks/test-${key}`;
+}
+
+/**
+ * ctx.webhooks and the h.webhookUrls() that sets it. keys are what the host
+ * would send: an integration's declared slots, or the webhook ids a flow's
+ * triggers name. Like credentials, the URLs are a fixture: kept across reset().
+ */
+export function createWebhookEndpoints(keys, describe) {
+  const urls = new Map(keys.map((k) => [k, defaultWebhookURL(k)]));
+  return {
+    /** Sets URLs by key; null is the host's answer with no public URL or no binding. */
+    set(values = {}) {
+      for (const [key, url] of Object.entries(values)) {
+        if (!urls.has(key)) {
+          fail(
+            `h.webhookUrls — "${key}" is not ${describe} (have: ${[...urls.keys()].join(', ') || '(none)'})`
+          );
+        }
+        if (url !== null && typeof url !== 'string') {
+          fail(
+            `h.webhookUrls — "${key}" must be a URL string or null, got ${JSON.stringify(url)}`
+          );
+        }
+        urls.set(key, url);
+      }
+    },
+    url: (key) => urls.get(key) ?? null,
+    /** A fresh object per invocation, as init sends one per run. */
+    ctx: () =>
+      Object.fromEntries([...urls].map(([key, url]) => [key, { url }])),
+  };
+}