@junoflow/testkit 0.10.0 → 0.12.0

package/README.md

@@ -47,24 +47,28 @@ plain form works.
 
 `harness({ manifest, integration })` returns:
 
-| Member                                 | Does                                                                     |
-| -------------------------------------- | ------------------------------------------------------------------------ |
-| `h.config(values)`                     | set non-credential slots (manifest defaults are already applied)         |
-| `h.credentials(values)`                | set credential slots                                                     |
-| `h.action(name, params)`               | run an action, returns its result                                        |
-| `h.webhook(name, request?)`            | run a webhook; `request` defaults to `POST /` with an empty body         |
-| `h.schedule(name, event?)`             | run a schedule handler                                                   |
-| `h.hook(name)`                         | run a declared lifecycle hook (e.g. `activated`)                         |
-| `h.listen({ until, events, timeout })` | run the listener until the condition holds, then abort                   |
-| `h.store`                              | the KV, as a plain `Map` (`get`/`set`/`delete` all land here)            |
-| `h.findings()`                         | what `ctx.findings` asserted, as `{slug, key, severity, text, standing}` |
-| `h.states()`                           | values `ctx.states.publish` has sent, keyed by local name                |
-| `h.status()`                           | the last `ctx.status.set` report, or `null` if it never reported         |
-| `h.emitted()`                          | `[{ event, payload }]`, in order                                         |
-| `h.logs()`                             | `[{ level, message, data }]`                                             |
-| `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                        |
-| `h.http`                               | the request mock, below                                                  |
-| `h.reset()`                            | clear recorded state, keeping config and credentials                     |
+| Member                                 | Does                                                                                                                   |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `h.config(values)`                     | set non-credential slots (manifest defaults are already applied)                                                       |
+| `h.credentials(values)`                | set credential slots                                                                                                   |
+| `h.webhookUrls(values)`                | set `ctx.webhooks.<slot>.url`; each slot starts at `https://juno.test/webhooks/test-<slot>`, `null` is "no public URL" |
+| `h.action(name, params)`               | run an action, returns its result                                                                                      |
+| `h.webhook(name, request?)`            | run a webhook; `request` defaults to a `POST` with an empty body, to the slot's URL                                    |
+| `h.schedule(name, event?)`             | run a schedule handler                                                                                                 |
+| `h.hook(name)`                         | run a declared lifecycle hook (e.g. `activated`)                                                                       |
+| `h.deliver(channel, attempt?)`         | run a declared channel's `deliver` with a fixture attempt (any field overridable); resolves to the attempt             |
+| `h.withdraw(channel, attempt?)`        | run its `withdraw`; a no-op when the channel has none                                                                  |
+| `h.listen({ until, events, timeout })` | run the listener until the condition holds, then abort                                                                 |
+| `h.store`                              | the KV, as a plain `Map` (`get`/`set`/`delete` all land here)                                                          |
+| `h.findings()`                         | what `ctx.findings` asserted, as `{slug, key, severity, text, standing}`                                               |
+| `h.states()`                           | values `ctx.states.publish` has sent, keyed by local name                                                              |
+| `h.status()`                           | the last `ctx.status.set` report, or `null` if it never reported                                                       |
+| `h.reports()`                          | what `ctx.channels.report` sent, as `{attemptId, status, digit?, option?, reason?}`                                    |
+| `h.emitted()`                          | `[{ event, payload }]`, in order                                                                                       |
+| `h.logs()`                             | `[{ level, message, data }]`                                                                                           |
+| `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                                                                      |
+| `h.http`                               | the request mock, below                                                                                                |
+| `h.reset()`                            | clear recorded state, keeping config and credentials                                                                   |
 
 ### `h.http`
 
@@ -102,13 +106,13 @@ production it hangs the supervisor on shutdown instead.
 ### `h.conformance()`
 
 Checks the manifest and the module against each other: every declared surface
-implemented (actions, webhooks, schedules, hooks), nothing undeclared exported,
-a `listener` function exactly when the manifest declares a `listener` section,
-every hook name inside Juno's closed vocabulary, and every schema compiling.
-`states` is a manifest declaration, not a handler surface, so it plays no part
-here — see [`h.states()`](#hstates) instead. Returns all problems rather than
-the first — "you declared six actions and implemented four" is one fix, not four
-runs.
+implemented (actions, webhooks, schedules, hooks, and a `deliver` for every
+channel), nothing undeclared exported, a `listener` function exactly when the
+manifest declares a `listener` section, every hook name inside Juno's closed
+vocabulary, and every schema compiling. `states` is a manifest declaration, not
+a handler surface, so it plays no part here — see [`h.states()`](#hstates)
+instead. Returns all problems rather than the first — "you declared six actions
+and implemented four" is one fix, not four runs.
 
 ### `h.findings()`
 
@@ -177,6 +181,33 @@ hook reports through ctx and returns nothing" is what production says too.
 `h.conformance()` also rejects a hook name outside Juno's closed vocabulary
 (today, only `activated`), which is the check that catches a typo before deploy.
 
+### `h.deliver(channel, attempt?)` and `h.reports()`
+
+```ts
+const attempt = await h.deliver('call');
+expect(h.http.requests[0].body).toContain(attempt.id);
+
+await h.webhook('callEvents', { body: { ref: attempt.id, digit: 1 } });
+expect(h.reports()).toEqual([
+  { attemptId: 'attempt-1', status: 'answered', digit: 1 },
+]);
+```
+
+The fixture attempt is `id: 'attempt-1'`, in the channel's first `answers` mode,
+with one option `{ key: 'ack', label: 'OK', digit: 1 }`, a placeholder address
+of the channel's address kind, `render.text`/`render.speech` equal to the
+message, `link: null` and a deadline ten minutes out. A channel that declares no
+`answers` gets a notification instead (`kind` and `mode` `notify`, no options,
+no deadline). Pass any field to override it.
+
+A `deliver` or `withdraw` that returns a value **fails the test**, as it fails
+in production. `ctx.channels.report` is on every surface; the refusals Juno
+applies without its attempt rows fail the test too — an install with no
+channels, an unknown status, `answered` without exactly one of `digit` and
+`option`, and, for an attempt `h.deliver` handed out, a digit or option the
+attempt does not have. A report on an id the harness never issued is recorded
+rather than refused, so a webhook test can report on a reference it made up.
+
 ## What the harness is faithful about
 
 - `ctx.store` round-trips values through JSON, because the real store does. A
@@ -234,22 +265,25 @@ it('greets when someone is home', async () => {
 
 `flowHarness({ manifest, flow, now?, timezone?, solar? })` returns:
 
-| Member                                         | Does                                                                                        |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `h.trigger(name, { event })`                   | run a declared trigger; resolves to the handler's return value                              |
-| `h.scenario(s)`                                | set the world from one JSON object (below)                                                  |
-| `h.now(iso)` / `h.timezone(tz)` / `h.solar(v)` | what `ctx.now()` and `ctx.solar()` answer; the timezone is `UTC` unless set                 |
-| `h.states(values)` / `h.state(name)`           | seed a `read` or `read_write` binding; read its current value                               |
-| `h.stateCalls()`                               | `set`, `claim`, `release`, `signal`, `retract`, as `{binding, verb, value?, opts?}`         |
-| `h.targets.answer(key, a)` / `.calls()`        | answer `binding.method` with a value or a function of the params; the calls made            |
-| `h.controls.answer(key, a)` / `.calls()`       | answer `binding.verb`; the commands made                                                    |
-| `h.llm(id, answer)`                            | answer `step.llm(id, …)`; `id#N` answers only that occurrence                               |
-| `h.steps()`                                    | every `step.run` and `step.llm`, as `{id, output}`; repeats are `id`, `id#1`, `id#2`        |
-| `h.findings()`                                 | `{slug, key, severity, text, standing}`, collapsed by `(slug, key)` as the host does        |
-| `h.credentials(values)`                        | set `ctx.credentials` by declared id                                                        |
-| `h.logs()`                                     | `[{ level, message, data }]`                                                                |
-| `h.conformance()`                              | triggers declared vs implemented, both ways; `[]` when they agree                           |
-| `h.reset()`                                    | clear recordings, answers, seeds and scoped state; keep clock, timezone, solar, credentials |
+| Member                                         | Does                                                                                                             |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `h.trigger(name, { event })`                   | run a declared trigger; resolves to the handler's return value                                                   |
+| `h.scenario(s)`                                | set the world from one JSON object (below)                                                                       |
+| `h.now(iso)` / `h.timezone(tz)` / `h.solar(v)` | what `ctx.now()` and `ctx.solar()` answer; the timezone is `UTC` unless set                                      |
+| `h.states(values)` / `h.state(name)`           | seed a `read` or `read_write` binding; read its current value                                                    |
+| `h.stateCalls()`                               | `set`, `claim`, `release`, `signal`, `retract`, as `{binding, verb, value?, opts?}`                              |
+| `h.targets.answer(key, a)` / `.calls()`        | answer `binding.method` with a value or a function of the params; the calls made                                 |
+| `h.controls.answer(key, a)` / `.calls()`       | answer `binding.verb`; the commands made                                                                         |
+| `h.llm(id, answer)`                            | answer `step.llm(id, …)`; `id#N` answers only that occurrence                                                    |
+| `h.steps()`                                    | every `step.run` and `step.llm`, as `{id, output}`; repeats are `id`, `id#1`, `id#2`                             |
+| `h.findings()`                                 | `{slug, key, severity, text, standing}`, collapsed by `(slug, key)` as the host does                             |
+| `h.credentials(values)`                        | set `ctx.credentials` by declared id                                                                             |
+| `h.webhookUrls(values)`                        | set `ctx.webhooks['<id>'].url`; each starts at `https://juno.test/webhooks/test-<id>`, `null` is "no public URL" |
+| `h.questions.answer(key, v)` / `.asked()`      | answer `ask` by label (or `ask#N`); the questions asked, defaults applied (below)                                |
+| `h.notifications()` / `h.unreachable(...ids)`  | every `notify` as `{to, message, urgency, via, link}`; the people `notify` reports unreachable                   |
+| `h.logs()`                                     | `[{ level, message, data }]`                                                                                     |
+| `h.conformance()`                              | triggers declared vs implemented, both ways; `[]` when they agree                                                |
+| `h.reset()`                                    | clear recordings, answers, seeds and scoped state; keep clock, timezone, solar, credentials, webhook URLs        |
 
 `h.trigger(name, { event })` sets `event.trigger` and spreads the payload you
 give onto the event, as the sandbox does. An array (a `batch` run) stays under
@@ -277,10 +311,11 @@ it('replays run 42', async () => {
 
 Its keys are `now`, `timezone`, `solar`, `states`, `credentials`, `targets`
 (`"binding.method": answer`), `controls` (`"binding.verb": answer`), `llm`
-(`"stepId": answer`) and `event`, which an `h.trigger(name)` with no `{ event }`
-runs with; an explicit event, even `null`, wins. `trigger`, `expect` and
-`flow_version` are carried and not applied. A key left out sets nothing; an
-unknown key fails. The `Scenario` type is exported.
+(`"stepId": answer`), `questions` (`"label": answer`), `unreachable` (person
+ids) and `event`, which an `h.trigger(name)` with no `{ event }` runs with; an
+explicit event, even `null`, wins. `trigger`, `expect` and `flow_version` are
+carried and not applied. A key left out sets nothing; an unknown key fails. The
+`Scenario` type is exported.
 
 Two answer forms are reserved, in a scenario and in `h.targets.answer`,
 `h.controls.answer` and `h.llm` alike:
@@ -294,6 +329,89 @@ Two answer forms are reserved, in a scenario and in `h.targets.answer`,
 `expect` filled in from what the run did; see the flow testing docs ("Replaying
 a run").
 
+### Handles
+
+`ctx.after`, `ctx.at` and `ctx.wait` behave as on the server, except that the
+harness's clock does not move: it cannot suspend, so a timer never fires while a
+handler waits. An `at` whose instant is at or before `h.now()` fires the moment
+it opens, with `value` `null` and `firedAt` that instant; an `after` never does.
+A `wait` listing a fired handle returns it — the earliest `firedAt`, ties to the
+earlier position — so a flow that waits on something already due runs to
+completion:
+
+```ts
+it('skips the wait when the morning has already come', async () => {
+  h.now('2026-10-26T07:00:00Z');
+  await h.trigger('nightly');
+  expect(h.handles()).toEqual([
+    { id: '__h_0__', kind: 'timer', label: 'morning', status: 'fired' },
+  ]);
+});
+```
+
+State and event handles follow the same rule, firing only where the server would
+fire them as they open. `state.<b>.when(match)` without `for` fires at once when
+the binding's seeded value already matches, with that value and `firedAt`
+`h.now()`; `becomes`, `changes`, a `for` hold and `targets.<i>.untilEvent` never
+fire, since the harness has no history of changes or events to look back on:
+
+```ts
+h.states({ door: 'closed' });
+// await wait([state.door.when('closed'), after('1m')]) returns the when
+```
+
+`controls.<b>.untilPressed()` never fires either: nothing presses in a test.
+
+A child-run handle fires at open from its answer, because the harness starts no
+child. `targets.<f>.start(input)` fires with the `<f>.start` answer wrapped as
+`{ flow_id, run_id: 'harness', ok: true, value }`, or `ok: false` with the
+answer's `$error` as `error`; `targets.<l>.startAll(input)` fires with the
+`<l>.startAll` answer whole, an array of those results. An unanswered `start` or
+`startAll` fails like an unanswered target call. `invoke` and `invokeAll` answer
+from their own key when the test set one, and otherwise from the `.start` /
+`.startAll` answer, so one answer serves a flow that switches between them:
+
+```ts
+h.targets.answer('report.start', { lines: 3 });
+// using r = targets.report.start({ day: 'mon' }) → r fires at open, r.value.ok
+// await targets.report.invoke({ day: 'mon' }) → { lines: 3 }
+```
+
+`all([...])` fires at open when every member already has, with their values in
+order, and is cancelled when a member is.
+
+`h.handles()` lists the last run's handles in open order as
+`{ id, kind, label, status }` (`kind` is `timer`, `state`, `event`, `run`,
+`press`, `question` or `all`); one still open when the run ended reads
+`cancelled`, as the engine closes it. An `at` with no clock set fails, as
+`ctx.now()` does. A bad duration or instant, and a 101st open handle, fail with
+the server's message at the next `wait` or when the handler returns.
+
+### Questions and notifications
+
+`ctx.ask` opens a `question` handle, which fires at open when the test answered
+it: by its `label`, or `ask#N` (the Nth `ask` of the trigger, from 1) for one
+without. `{ by, answer, channel? }` fires it with
+`{ outcome: 'answered', answer, by, channel, at }` — `channel` defaults to
+`'test:channel'`, `at` is `h.now()` — and `'unanswered'` with
+`{ outcome: 'unanswered', attempts: to.length * rounds }`. The server does not
+count a recipient none of whose contacts could carry the question; the harness
+has no contacts, so it counts them all. A question with no answer stays open, so
+a wait on it alone fails as any wait nothing can answer does. There is no
+timeline: an answer that arrives after a call has rung needs a clock that moves.
+
+```ts
+h.questions.answer('samtal', { by: 'partner', answer: 'ack' });
+// using called = ask({ …, label: 'samtal' }) → called fires at open
+expect(h.questions.asked()[0]).toMatchObject({ label: 'samtal', rounds: 5 });
+```
+
+`ctx.notify` records `{ to, message, urgency, via, link }` (defaults applied;
+`via` and `link` `null` when absent) and answers `{ unreachable: [] }`, or the
+recipients `h.unreachable(...ids)` named, in the manifest's order. Both refuse
+what the server refuses from the manifest alone — a person not in `people`, a
+field out of range — with the server's words.
+
 ### What fails
 
 Strict where a permissive double would pass a broken flow. Each of these fails
@@ -304,8 +422,9 @@ the test, naming what was asked for and how to supply it:
   that seeds or answers it;
 - a state verb the binding was not granted (`set` on a `read` binding, `get` on
   a slot), and `get` on a binding the test did not seed;
-- `ctx.sleep(…)` and `ctx.waitForEvent(…)`:
-  `a handler cannot suspend in a test: sleep("5m")`;
+- a `ctx.wait(…)` none of whose handles has fired, and so every `ctx.sleep(…)`
+  (`sleep(d)` is `wait([after(d)])`):
+  `a handler cannot suspend in a test: wait([after("5m")])`;
 - `ctx.now()`, `ctx.solar()`, a target call, a control command or a `step.llm`
   the test did not answer, e.g.
   `target call kitchenSpeaker.ttsCloudSay was not answered — h.targets.answer('kitchenSpeaker.ttsCloudSay', result)`.
@@ -369,10 +488,10 @@ it('a read-only handler cannot claim', async () => {
 | `h.conformance()`                              | handlers declared vs implemented, both ways; `[]` when they agree                |
 | `h.reset()`                                    | clear recordings, answers and seeds; keep clock, timezone, solar, credentials    |
 
-`h.scenario(s)` takes the flow scenario's keys except `llm` and `flow_version`,
-which it refuses, and ignores `trigger`, `event` and `expect`, so one scenario
-can serve both. `$replay` and `$error` answer targets and controls as they do in
-a flow test.
+`h.scenario(s)` takes the flow scenario's keys except `llm`, `questions`,
+`unreachable` and `flow_version`, which it refuses, and ignores `trigger`,
+`event` and `expect`, so one scenario can serve both. `$replay` and `$error`
+answer targets and controls as they do in a flow test.
 
 The handler's `ctx` is the app sandbox's: `log`, `now`, `solar`, `signal`,
 `states`, `controls`, `targets`, `credentials` and `events`. `ctx.signal` is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/testkit",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Test harnesses for Juno integrations, flows and apps",
   "license": "MIT",
   "repository": {

package/src/ask.js

@@ -0,0 +1,338 @@
+import { fail } from './assert.js';
+import { isPositiveDuration, rfc3339 } from './handles.js';
+
+// The people half of the flow harness: ctx.ask and ctx.notify, and the h.*
+// calls that answer questions and read back what was asked and sent.
+//
+// The refusals are the host's that need only the manifest — internal/ask's
+// ParseSpec and ParseNotify, in their order and with their strings. What
+// needs the people store (a person deleted since the flow was committed, which
+// contacts serve which urgency) is not under test: there are no contacts here.
+
+const MAX_RECIPIENTS = 20;
+const MAX_QUESTION_RUNES = 500;
+const MAX_MESSAGE_RUNES = 1000;
+const MAX_OPTIONS = 9;
+const MAX_LABEL_RUNES = 40;
+const MAX_ROUNDS = 10;
+
+const URGENCIES = ['urgent', 'normal', 'low'];
+const VIA_KINDS = ['call', 'sms', 'push', 'chat', 'email', 'inbox'];
+const OPTION_KEY = /^[a-z][a-zA-Z0-9]*$/;
+
+/** The channel an answer came through when the test names none. */
+export const TEST_CHANNEL = 'test:channel';
+
+const runes = (s) => [...s].length;
+
+/** handlekind's quotedNames: sorted, quoted, "none" when empty. */
+function quotedNames(ids) {
+  if (!ids.length) return 'none';
+  return [...ids]
+    .sort()
+    .map((n) => JSON.stringify(n))
+    .join(', ');
+}
+
+/** checkTo: the size, repeats, and that the manifest declares each person. */
+function checkTo(prefix, to, people) {
+  if (!Array.isArray(to) || to.length < 1 || to.length > MAX_RECIPIENTS) {
+    return `${prefix}: to needs 1 to ${MAX_RECIPIENTS} people`;
+  }
+  for (let i = 0; i < to.length; i++) {
+    if (to.slice(0, i).includes(to[i])) {
+      return `${prefix}: to lists ${JSON.stringify(to[i])} twice`;
+    }
+  }
+  for (const id of to) {
+    if (!people.includes(id)) {
+      return `${prefix}: person ${JSON.stringify(id)} is not declared in this flow's people; it declares ${quotedNames(people)}`;
+    }
+  }
+  return null;
+}
+
+function checkUrgency(prefix, u) {
+  if (u === undefined) return [null, 'normal'];
+  if (!URGENCIES.includes(u)) {
+    return [`${prefix}: urgency must be "urgent", "normal" or "low"`];
+  }
+  return [null, u];
+}
+
+/** An empty via reads as absent, as the host reads it: every kind. */
+function checkVia(prefix, via) {
+  for (const k of via ?? []) {
+    if (!VIA_KINDS.includes(k)) {
+      return [
+        `${prefix}: via ${JSON.stringify(k)} is not a channel kind; use call, sms, push, chat, email or inbox`,
+      ];
+    }
+  }
+  return [null, via?.length ? [...via] : null];
+}
+
+/**
+ * ParseSpec in internal/ask/spec.go, over what the SDK would send: the
+ * refusal, or the question as `h.questions.asked()` reports it, defaults
+ * applied.
+ */
+export function parseQuestion(opts, people) {
+  const o = opts ?? {};
+  const toErr = checkTo('ask', o.to, people);
+  if (toErr) return { error: toErr };
+  const question = typeof o.question === 'string' ? o.question : '';
+  const n = runes(question.trim());
+  if (n === 0 || n > MAX_QUESTION_RUNES) {
+    return {
+      error: `ask: question must be 1 to ${MAX_QUESTION_RUNES} characters`,
+    };
+  }
+  // The SDK sends Object.entries(options) as an array; integer-like keys,
+  // which that reorders, fail the key pattern below.
+  const entries = Object.entries(o.options ?? {});
+  if (entries.length < 1 || entries.length > MAX_OPTIONS) {
+    return { error: `ask: options needs 1 to ${MAX_OPTIONS} answers` };
+  }
+  for (let i = 0; i < entries.length; i++) {
+    const [key, label] = entries[i];
+    if (!OPTION_KEY.test(key)) {
+      return {
+        error: `ask: option key ${JSON.stringify(key)} must be lowerCamelCase (e.g. "yes", "notNow")`,
+      };
+    }
+    const ln = typeof label === 'string' ? runes(label.trim()) : 0;
+    if (ln === 0 || ln > MAX_LABEL_RUNES) {
+      return {
+        error: `ask: option ${JSON.stringify(key)} needs a label of 1 to ${MAX_LABEL_RUNES} characters`,
+      };
+    }
+  }
+
+  const q = {
+    to: [...o.to],
+    question,
+    options: Object.fromEntries(entries),
+    mode: 'sequence',
+    rounds: 1,
+    escalateAfter: '10m',
+    urgency: 'normal',
+    via: null,
+  };
+  if (o.mode !== undefined) {
+    if (o.mode !== 'sequence' && o.mode !== 'all') {
+      return { error: 'ask: mode must be "sequence" or "all"' };
+    }
+    q.mode = o.mode;
+  }
+  if (o.rounds !== undefined) {
+    if (!Number.isInteger(o.rounds) || o.rounds < 1 || o.rounds > MAX_ROUNDS) {
+      return { error: `ask: rounds must be 1 to ${MAX_ROUNDS}` };
+    }
+    q.rounds = o.rounds;
+  }
+  if (o.escalateAfter !== undefined) q.escalateAfter = o.escalateAfter;
+  if (!isPositiveDuration(q.escalateAfter)) {
+    return {
+      error: `ask: escalateAfter ${JSON.stringify(q.escalateAfter)} is not a duration (e.g. "2m", "1h")`,
+    };
+  }
+  let err;
+  [err, q.urgency] = checkUrgency('ask', o.urgency);
+  if (err) return { error: err };
+  [err, q.via] = checkVia('ask', o.via);
+  if (err) return { error: err };
+  if (
+    o.freeText !== undefined &&
+    o.freeText !== 'exact' &&
+    o.freeText !== 'interpret'
+  ) {
+    return { error: 'ask: freeText must be "exact" or "interpret"' };
+  }
+  if (o.requireSignIn === true) {
+    return { error: 'ask: requireSignIn is not available yet' };
+  }
+  return { question: q };
+}
+
+/** ParseNotify in internal/ask/spec.go: the refusal, or the notification. */
+export function parseNotify(opts, people) {
+  const o = opts ?? {};
+  const toErr = checkTo('notify', o.to, people);
+  if (toErr) return { error: toErr };
+  const message = typeof o.message === 'string' ? o.message : '';
+  const n = runes(message.trim());
+  if (n === 0 || n > MAX_MESSAGE_RUNES) {
+    return {
+      error: `notify: message must be 1 to ${MAX_MESSAGE_RUNES} characters`,
+    };
+  }
+  const note = { to: [...o.to], message, urgency: 'normal', via: null };
+  let err;
+  [err, note.urgency] = checkUrgency('notify', o.urgency);
+  if (err) return { error: err };
+  [err, note.via] = checkVia('notify', o.via);
+  if (err) return { error: err };
+  note.link = null;
+  if (o.link !== undefined) {
+    let ok = false;
+    try {
+      const u = new URL(o.link);
+      ok = (u.protocol === 'http:' || u.protocol === 'https:') && !!u.host;
+    } catch {
+      ok = false;
+    }
+    if (!ok) return { error: 'notify: link must be an http or https URL' };
+    note.link = o.link;
+  }
+  return { notification: note };
+}
+
+/**
+ * The ask/notify half of a flow harness. `manifest.people` is the grant.
+ * Answers and recordings live here and are cleared by reset().
+ */
+export function createPeople(manifest, harness) {
+  const people = Array.isArray(manifest.people) ? manifest.people : [];
+  const rec = {
+    answers: new Map(),
+    asked: [],
+    notifications: [],
+    unreachable: new Set(),
+  };
+
+  const declared = (where, id) => {
+    if (!people.includes(id)) {
+      fail(
+        `${where} — person ${JSON.stringify(id)} is not declared in manifest.json's people (have: ${people.join(', ') || '(none)'})`
+      );
+    }
+  };
+
+  const h = {
+    questions: {
+      /**
+       * Answers the question whose label is `key` — or `ask#N`, the Nth ask
+       * of the trigger (from 1), for an unlabelled one — with
+       * `{ by, answer, channel? }` or `'unanswered'`.
+       */
+      answer(key, value) {
+        if (typeof key !== 'string' || key === '') {
+          fail(
+            `h.questions.answer(key, …) — key is a question's label, or ask#N for the Nth unlabelled ask; got ${JSON.stringify(key)}`
+          );
+        }
+        if (value !== 'unanswered') {
+          const ok =
+            value !== null &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            typeof value.by === 'string' &&
+            typeof value.answer === 'string';
+          if (!ok) {
+            fail(
+              `h.questions.answer('${key}', …) — expected { by, answer, channel? } or 'unanswered', got ${JSON.stringify(value)}`
+            );
+          }
+          for (const k of Object.keys(value)) {
+            if (!['by', 'answer', 'channel'].includes(k)) {
+              fail(
+                `h.questions.answer('${key}', …) — "${k}" is not part of an answer (have: by, answer, channel)`
+              );
+            }
+          }
+          declared(`h.questions.answer('${key}', …)`, value.by);
+          value = { ...value };
+        }
+        rec.answers.set(key, value);
+        return harness();
+      },
+
+      /** Every question the handlers asked, in order, defaults applied. */
+      asked: () => rec.asked.map((q) => structuredClone(q)),
+    },
+
+    /** Every notification the handlers sent, in order, defaults applied. */
+    notifications: () => rec.notifications.map((n) => structuredClone(n)),
+
+    /** The people notify answers as unreachable (no usable contact). */
+    unreachable(...ids) {
+      for (const id of ids) declared('h.unreachable', id);
+      for (const id of ids) rec.unreachable.add(id);
+      return harness();
+    },
+  };
+
+  /**
+   * ctx.ask and ctx.notify for one run. `handles` is the run's table,
+   * `refuse` its recording fail(), `instant` the harness clock.
+   */
+  function ctx(refuse, handles, instant) {
+    let asks = 0;
+    return {
+      ask(opts) {
+        asks++;
+        const key = opts?.label ?? `ask#${asks}`;
+        const parsed = parseQuestion(opts, people);
+        if (parsed.error) {
+          return handles.questionHandle('ask', [opts], {
+            label: opts?.label,
+            error: parsed.error,
+          });
+        }
+        const q = parsed.question;
+        let value;
+        const answer = rec.answers.get(key);
+        if (answer === 'unanswered') {
+          value = { outcome: 'unanswered', attempts: q.to.length * q.rounds };
+        } else if (answer !== undefined) {
+          if (!q.to.includes(answer.by)) {
+            refuse(
+              `h.questions.answer('${key}', …) — "${answer.by}" was not asked (to: ${q.to.join(', ')})`
+            );
+          }
+          if (!Object.hasOwn(q.options, answer.answer)) {
+            refuse(
+              `h.questions.answer('${key}', …) — "${answer.answer}" is not one of the question's options (have: ${Object.keys(q.options).join(', ')})`
+            );
+          }
+          value = {
+            outcome: 'answered',
+            answer: answer.answer,
+            by: answer.by,
+            channel: answer.channel ?? TEST_CHANNEL,
+            at: rfc3339(instant() ?? Date.now()),
+          };
+        }
+        const handle = handles.questionHandle('ask', [opts], {
+          label: opts.label,
+          value,
+        });
+        rec.asked.push({ id: handle.id, label: opts.label, ...q });
+        return handle;
+      },
+
+      async notify(opts) {
+        const parsed = parseNotify(opts, people);
+        if (parsed.error) refuse(parsed.error);
+        const note = parsed.notification;
+        rec.notifications.push(note);
+        // The host lists the unreachable in the manifest's order.
+        return {
+          unreachable: people.filter(
+            (p) => note.to.includes(p) && rec.unreachable.has(p)
+          ),
+        };
+      },
+    };
+  }
+
+  function reset() {
+    rec.answers.clear();
+    rec.asked.length = 0;
+    rec.notifications.length = 0;
+    rec.unreachable.clear();
+  }
+
+  return { h, ctx, reset };
+}