@junoflow/testkit 0.13.0 → 0.15.0

package/README.md

@@ -285,27 +285,30 @@ 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.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        |
+`flowHarness({ manifest, flow, now?, timezone?, solar?, series? })` 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.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.tasks()`                                    | every `tasks.<b>` command; `open` answers `opened: true`, rid `test-rid-<n>`, the first time a key opens in a run; `untilDone` never fires |
+| `h.series(key, fixture)`                       | what `series.<key>.get()` reads; replaces the key's fixture (see [Series](#series))                                                        |
+| `h.seriesView(key, spec, result)`              | what `series.<key>.view(spec)` answers, for a spec equal by value                                                                          |
+| `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, series                          |
 
 `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
@@ -314,6 +317,61 @@ modifiers are not evaluated. `h.now(iso)` without an offset is wall time in
 `h.timezone()`; a wall time the timezone skips or repeats is refused, so give
 one near a DST change an offset.
 
+### Series
+
+A `series` binding reads from a fixture, given per key as the `series` option or
+with `h.series(key, fixture)`:
+
+```ts
+const h = flowHarness({
+  manifest,
+  flow,
+  series: {
+    temperature: [
+      { from: '2026-11-01T12:00:00Z', to: '2026-11-01T13:00:00Z', value: 14 },
+      { from: '2026-11-01T13:00:00Z', to: '2026-11-01T14:00:00Z', value: 16 },
+    ],
+  },
+});
+h.seriesView(
+  'temperature',
+  {
+    highest: {
+      for: '2h',
+      contiguous: true,
+      from: { at: '12:00' },
+      to: { at: '18:00' },
+    },
+  },
+  {
+    available: true,
+    value: false,
+    spans: [{ from: '2026-11-01T13:00:00Z', to: '2026-11-01T15:00:00Z' }],
+  }
+);
+```
+
+A fixture is an array of `{from, to, value}` (a `Date` or an RFC 3339 string for
+each bound, sorted and non-overlapping), or
+`{intervals, published_at?, issued_at?, covered_until?}`. `get(range?)` answers
+the intervals overlapping `[from, to)`, the instants spelled as the host spells
+them (RFC 3339 UTC, `2026-11-01T12:00:00Z`), and the stamps from the fixture or
+`null`. A `get()` of a key with no fixture fails, naming `h.series`.
+
+**`view()` is stubbed, never evaluated.** The host evaluates a view with cron
+and solar edges in the site's timezone, and a copy here would be a second
+implementation of it. `h.seriesView(key, spec, result)` says what a view
+answers: `result` is a `SeriesViewResult` (fields left out read `false`, `null`
+and `[]`) or a function of the spec returning one, and it matches a spec equal
+by value (key order does not matter). A `view()` nothing stubbed fails naming
+the spec and the binding. Fixtures and stubs are kept across `reset()`.
+
+A key the manifest does not bind fails in the host's words:
+`series binding "cost" is not declared in this flow's series; it declares "temperature"`
+(`this app's` in an app), as do a bound that is not an instant
+(`series "price": from "yesterday" is not an RFC 3339 instant`) and an empty
+range (`series "price": from must be before to`).
+
 ### Scenarios
 
 `h.scenario(s)` applies a whole world at once, through the setters above and
@@ -493,22 +551,23 @@ it('a read-only handler cannot claim', async () => {
 });
 ```
 
-`appHarness({ manifest, app, now?, timezone?, solar? })` returns:
-
-| Member                                         | Does                                                                             |
-| ---------------------------------------------- | -------------------------------------------------------------------------------- |
-| `h.call(name, input?)`                         | call a declared handler; resolves to its result after a JSON round trip          |
-| `h.events()`                                   | every emit that passed, as `{event, payload}`, in emit order                     |
-| `h.scenario(s)`                                | set the world from one JSON object, as `flowHarness`'s                           |
-| `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)`                             | seed a `read` binding                                                            |
-| `h.stateCalls()`                               | `claim` and `release`, 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.credentials(values)`                        | set `ctx.credentials` by declared id                                             |
-| `h.logs()`                                     | `[{ level, message, data }]`                                                     |
-| `h.conformance()`                              | handlers declared vs implemented, both ways; `[]` when they agree                |
-| `h.reset()`                                    | clear recordings, answers and seeds; keep clock, timezone, solar, credentials    |
+`appHarness({ manifest, app, now?, timezone?, solar?, series? })` returns:
+
+| Member                                         | Does                                                                                  |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `h.call(name, input?)`                         | call a declared handler; resolves to its result after a JSON round trip               |
+| `h.events()`                                   | every emit that passed, as `{event, payload}`, in emit order                          |
+| `h.scenario(s)`                                | set the world from one JSON object, as `flowHarness`'s                                |
+| `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)`                             | seed a `read` binding                                                                 |
+| `h.stateCalls()`                               | `claim` and `release`, 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.credentials(values)`                        | set `ctx.credentials` by declared id                                                  |
+| `h.series(key, f)` / `h.seriesView(key, s, r)` | a series fixture and a view stub, as `flowHarness`'s ([Series](#series))              |
+| `h.logs()`                                     | `[{ level, message, data }]`                                                          |
+| `h.conformance()`                              | handlers declared vs implemented, both ways; `[]` when they agree                     |
+| `h.reset()`                                    | clear recordings, answers and seeds; keep clock, timezone, solar, credentials, series |
 
 `h.scenario(s)` takes the flow scenario's keys except `llm`, `questions`,
 `unreachable` and `flow_version`, which it refuses, and ignores `trigger`,
@@ -516,9 +575,9 @@ it('a read-only handler cannot claim', async () => {
 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
-never aborted. The binding handles, answers and clock are the ones `flowHarness`
-uses, with the same strictness.
+`states`, `controls`, `series`, `targets`, `credentials` and `events`.
+`ctx.signal` is never aborted. The binding handles, answers and clock are the
+ones `flowHarness` uses, with the same strictness.
 
 ### What fails
 

package/package.json

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

package/src/app.js

@@ -1,6 +1,7 @@
 import { fail } from './assert.js';
 import { createBindings, createWorld, jsonCopy } from './bindings.js';
 import { applyScenario } from './scenario.js';
+import { createSeriesBindings } from './series-read.js';
 import { compile, describeErrors } from './schema.js';
 
 /** The only key an app's default export carries (BaseApp in app-api.d.ts). */
@@ -21,7 +22,14 @@ const APP_KEYS = ['handlers'];
  * clock, the sun, a target call and a control command fail unless the test
  * answered them.
  */
-export function appHarness({ manifest, app, now, timezone, solar } = {}) {
+export function appHarness({
+  manifest,
+  app,
+  now,
+  timezone,
+  solar,
+  series,
+} = {}) {
   if (!manifest || typeof manifest !== 'object') {
     fail(
       "appHarness({ manifest, app }): manifest is required — import manifest from '../manifest.json'"
@@ -42,6 +50,9 @@ export function appHarness({ manifest, app, now, timezone, solar } = {}) {
     scoped: false,
   });
 
+  // ctx.series, answered from h.series fixtures and h.seriesView stubs.
+  const seriesBindings = createSeriesBindings(manifest, () => h, { app: true });
+
   // What handlers did. Cleared by reset().
   const rec = { logs: [], events: [] };
 
@@ -127,10 +138,12 @@ export function appHarness({ manifest, app, now, timezone, solar } = {}) {
     targets: bindings.h.targets,
     controls: bindings.h.controls,
     credentials: bindings.h.credentials,
+    series: seriesBindings.h.series,
+    seriesView: seriesBindings.h.seriesView,
 
     /**
      * Clears recordings, answers and seeded states; keeps the clock,
-     * timezone, solar and credentials.
+     * timezone, solar, credentials, series and view stubs.
      */
     reset() {
       rec.logs.length = 0;
@@ -141,6 +154,7 @@ export function appHarness({ manifest, app, now, timezone, solar } = {}) {
   };
 
   world.init({ now, timezone, solar });
+  seriesBindings.init(series);
 
   /** One call's ctx, exactly the members app-entrypoint.ts builds. */
   function buildContext(run, handler, readOnly) {
@@ -170,6 +184,7 @@ export function appHarness({ manifest, app, now, timezone, solar } = {}) {
       controls: b.controls,
       targets: b.targets,
       credentials: b.credentials,
+      series: seriesBindings.ctx(refuse),
       events: eventsProxy(refuse, handler, readOnly),
     };
   }

package/src/ask.js

@@ -24,7 +24,14 @@ const OPTION_KEY = /^[a-z][a-zA-Z0-9]*$/;
 export const TEST_CHANNEL = 'test:channel';
 
 /** What h.questions.answer takes for an answer. */
-const ANSWER_FIELDS = ['by', 'answer', 'channel', 'text', 'interpreted'];
+const ANSWER_FIELDS = [
+  'by',
+  'answer',
+  'channel',
+  'text',
+  'interpreted',
+  'user',
+];
 
 const runes = (s) => [...s].length;
 
@@ -152,9 +159,6 @@ export function parseQuestion(opts, people) {
   ) {
     return { error: 'ask: freeText must be "exact" or "interpret"' };
   }
-  if (o.requireSignIn === true) {
-    return { error: 'ask: requireSignIn is not available yet' };
-  }
   return { question: q };
 }
 
@@ -217,9 +221,11 @@ export function createPeople(manifest, harness) {
       /**
        * 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?, text?, interpreted? }` or `'unanswered'`.
-       * `channel: 'page'` is an answer from the answer page; `text` a written
-       * reply as written, and `interpreted: true` one the site's LLM mapped.
+       * `{ by, answer, channel?, text?, interpreted?, user? }` or
+       * `'unanswered'`. `channel: 'page'` is an answer from the answer page;
+       * `text` a written reply as written, and `interpreted: true` one the
+       * site's LLM mapped; `channel: 'inbox'` an answer given in Juno, whose
+       * `user` is who pressed the button (on a recipient's behalf, not `by`).
        */
       answer(key, value) {
         if (typeof key !== 'string' || key === '') {
@@ -236,7 +242,7 @@ export function createPeople(manifest, harness) {
             typeof value.answer === 'string';
           if (!ok) {
             fail(
-              `h.questions.answer('${key}', …) — expected { by, answer, channel?, text?, interpreted? } or 'unanswered', got ${JSON.stringify(value)}`
+              `h.questions.answer('${key}', …) — expected { by, answer, channel?, text?, interpreted?, user? } or 'unanswered', got ${JSON.stringify(value)}`
             );
           }
           for (const k of Object.keys(value)) {
@@ -246,7 +252,7 @@ export function createPeople(manifest, harness) {
               );
             }
           }
-          for (const k of ['channel', 'text']) {
+          for (const k of ['channel', 'text', 'user']) {
             if (value[k] !== undefined && typeof value[k] !== 'string') {
               fail(
                 `h.questions.answer('${key}', …) — ${k} is a string; got ${JSON.stringify(value[k])}`
@@ -263,6 +269,11 @@ export function createPeople(manifest, harness) {
               `h.questions.answer('${key}', …) — interpreted needs the text the LLM read`
             );
           }
+          if (value.user !== undefined && value.channel !== 'inbox') {
+            fail(
+              `h.questions.answer('${key}', …) — user is set only for an answer given in Juno; pass channel: 'inbox' with it`
+            );
+          }
           declared(`h.questions.answer('${key}', …)`, value.by);
           value = { ...value };
         }
@@ -313,13 +324,20 @@ export function createPeople(manifest, harness) {
               `h.questions.answer('${key}', …) — "${answer.by}" was not asked (to: ${q.to.join(', ')})`
             );
           }
+          // Only an answer given in Juno counts (plan-ask-3 Decision 7): the
+          // host refuses a channel's answered report and the answer page.
+          if (opts.requireSignIn === true && answer.channel !== 'inbox') {
+            refuse(
+              `h.questions.answer('${key}', …) — this question needs a signed-in answer in Juno; pass channel: 'inbox'`
+            );
+          }
           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(', ')})`
             );
           }
-          // The host's AnsweredValue, in its field order: text and
-          // interpreted only when set.
+          // The host's AnsweredValue, in its field order: text,
+          // interpreted and user only when set.
           value = {
             outcome: 'answered',
             answer: answer.answer,
@@ -327,6 +345,7 @@ export function createPeople(manifest, harness) {
             channel: answer.channel ?? TEST_CHANNEL,
             ...(answer.text !== undefined && { text: answer.text }),
             ...(answer.interpreted && { interpreted: true }),
+            ...(answer.user !== undefined && { user: answer.user }),
             at: rfc3339(instant() ?? Date.now()),
           };
         }

package/src/flow.js

@@ -10,6 +10,8 @@ import { flowConformance } from './flow-conformance.js';
 import { createHandleTable } from './handles.js';
 import { names } from './names.js';
 import { applyScenario } from './scenario.js';
+import { createSeriesBindings } from './series-read.js';
+import { createTasks } from './tasks.js';
 import { createWebhookEndpoints } from './webhooks.js';
 
 /**
@@ -22,7 +24,14 @@ import { createWebhookEndpoints } from './webhooks.js';
  * not declare fails here, and so does any read of the world — the clock, the
  * sun, a step.llm — that the test did not answer.
  */
-export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
+export function flowHarness({
+  manifest,
+  flow,
+  now,
+  timezone,
+  solar,
+  series,
+} = {}) {
   if (!manifest || typeof manifest !== 'object') {
     fail(
       "flowHarness({ manifest, flow }): manifest is required — import manifest from '../manifest.json'"
@@ -51,8 +60,12 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
   };
   // Chainable setters on the binding half return the harness itself.
   const bindings = createBindings(manifest, () => h);
+  // ctx.series, answered from h.series fixtures and h.seriesView stubs.
+  const seriesBindings = createSeriesBindings(manifest, () => h);
   // ctx.ask and ctx.notify, and h.questions / h.notifications / h.unreachable.
   const people = createPeople(manifest, () => h);
+  // ctx.tasks, and h.tasks.
+  const tasks = createTasks(manifest);
   // ctx.webhooks is keyed by the webhook ids the triggers name, each once.
   const webhooks = createWebhookEndpoints(
     [
@@ -172,6 +185,8 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
 
     ...bindings.h,
     ...people.h,
+    ...seriesBindings.h,
+    ...tasks.h,
 
     /**
      * Sets ctx.webhooks['<id>'].url. Every webhook a trigger names starts at a
@@ -184,12 +199,13 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
     },
 
     /**
-     * Clears recordings, answers (questions and unreachable people included),
+     * Clears recordings (task commands included), answers (questions and unreachable people included),
      * seeded states, the scenario's event and scoped memory; keeps the clock,
-     * timezone, solar, credentials and webhook URLs.
+     * timezone, solar, credentials, webhook URLs, series and view stubs.
      */
     reset() {
       people.reset();
+      tasks.reset();
       rec.steps.length = 0;
       rec.logs.length = 0;
       rec.llm.clear();
@@ -201,6 +217,7 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
   };
 
   world.init({ now, timezone, solar });
+  seriesBindings.init(series);
 
   /**
    * One run's ctx, as buildContext in sdk/src/context.ts builds it. Built per
@@ -245,6 +262,8 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
     return {
       event: flattenTriggerEvent({ trigger, payload }),
       ...bindings.ctx(refuse, {}, handles),
+      series: seriesBindings.ctx(refuse),
+      tasks: tasks.ctx(refuse, handles),
       webhooks: webhooks.ctx(),
 
       step: {

package/src/handles.js

@@ -230,6 +230,15 @@ export function createHandleTable({ refuse, instant, render, harnessName }) {
       return open(call, args, { label: opts?.label }, 'press');
     },
 
+    /**
+     * tasks.<b>.untilDone: never fires, like after — no task closes in a
+     * test.
+     */
+    taskHandle(call, args) {
+      const [opts] = args;
+      return open(call, args, { label: opts?.label }, 'task');
+    },
+
     /**
      * targets.<flow>.start|startAll. The harness runs no child, so a run
      * handle fires at open with the value the test's answer makes, or is the

package/src/index.d.ts

@@ -27,6 +27,15 @@ export interface ManifestConfigSlot {
   enum?: string[];
 }
 
+/** One interval of a published series, as h.series() shows it. */
+export interface SeriesStep {
+  /** ISO 8601 UTC, inclusive. */
+  from: string;
+  /** ISO 8601 UTC, exclusive. */
+  to: string;
+  value: unknown;
+}
+
 /** The parsed contents of manifest.json. */
 export interface Manifest {
   name: string;
@@ -62,6 +71,27 @@ export interface Manifest {
       [k: string]: unknown;
     }
   >;
+  /**
+   * Series this integration publishes with ctx.series.publish. Keyed by the
+   * local name; the host scopes it to `<install>:<name>`.
+   */
+  series?: Record<
+    string,
+    {
+      type?: string;
+      name?: string;
+      description?: string;
+      keywords?: string[];
+      values?: string[];
+      min?: number;
+      max?: number;
+      unit?: string;
+      accumulates?: boolean;
+      forecast?: boolean;
+      keep?: string;
+      [k: string]: unknown;
+    }
+  >;
   /** Lifecycle hooks, from the closed vocabulary Juno defines — today, `activated`. */
   hooks?: Record<
     string,
@@ -285,6 +315,12 @@ export interface Harness {
   findings(): RecordedFinding[];
   /** Values ctx.states.publish has sent so far, keyed by local name. */
   states(): Record<string, unknown>;
+  /**
+   * Each series ctx.series.publish has written, keyed by local name: the
+   * merged step function the host would hold, sorted by `from`. A series
+   * never published is absent. Cleared by reset().
+   */
+  series(): Record<string, SeriesStep[]>;
   /** 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(). */
@@ -362,6 +398,8 @@ export interface FlowManifest {
   credentials?: string[];
   /** The people ctx.ask and ctx.notify may name. */
   people?: string[];
+  /** Keyed by binding name: the series `<install>:<name>` it reads. */
+  series?: Record<string, { series: string }>;
   [k: string]: unknown;
 }
 
@@ -379,6 +417,38 @@ export interface FlowModule<
   triggers: Handlers;
 }
 
+/** One interval of a series fixture: [from, to), a Date or RFC 3339 bound. */
+export interface SeriesFixtureInterval {
+  from: Date | string;
+  to: Date | string;
+  value: unknown;
+}
+
+/**
+ * What series.<key>.get() reads: the intervals (sorted, non-overlapping), or
+ * those with the stamps get() reports — each null when left out.
+ */
+export type SeriesFixture =
+  | SeriesFixtureInterval[]
+  | {
+      intervals: SeriesFixtureInterval[];
+      published_at?: string | Date | null;
+      issued_at?: string | Date | null;
+      covered_until?: string | Date | null;
+    };
+
+/**
+ * What series.<key>.view(spec) answers when h.seriesView stubs it. Fields
+ * left out read false, null and [] as the SDK fills them.
+ */
+export interface SeriesViewAnswer {
+  available?: boolean;
+  value?: number | string | boolean | null;
+  reason?: string | null;
+  until?: string | null;
+  spans?: Array<{ from: string; to: string }>;
+}
+
 /** What ctx.solar() answers; see SolarResult in the flow's types. */
 export interface SolarAnswer {
   above_horizon?: boolean;
@@ -401,8 +471,8 @@ export interface FlowHarnessOptions<
   now?: string;
   /** As h.timezone(); UTC when omitted. */
   timezone?: string;
-  /** As h.solar(). */
-  solar?: SolarAnswer;
+  /** As h.series(), per binding key. */
+  series?: Record<string, SeriesFixture>;
 }
 
 export interface TriggerOptions {
@@ -457,6 +527,23 @@ export interface RecordedControlCall {
   until?: string;
 }
 
+/**
+ * One ctx.tasks command, as the SDK sends it: a Date as its ISO string,
+ * absent options left out.
+ */
+export interface RecordedTaskCommand {
+  binding: string;
+  verb: 'open' | 'snooze' | 'complete' | 'cancel';
+  key?: string;
+  at?: string;
+  within?: string;
+  until?: string;
+  reason?: string;
+  data?: unknown;
+  outcome?: 'success' | 'failed';
+  note?: string;
+}
+
 /** What a control command answers. Fields left out take the SDK's defaults. */
 export interface ControlAnswer {
   outcome?: string;
@@ -585,13 +672,19 @@ export type QuestionAnswer =
       answer: string;
       /**
        * `<install>:<channel>` the answer came through, `'page'` for the
-       * answer page; `test:channel` when omitted.
+       * answer page, `'inbox'` for an answer given in Juno; `test:channel`
+       * when omitted.
        */
       channel?: string;
       /** A written reply, as the person wrote it. */
       text?: string;
       /** The site's LLM mapped `text` onto `answer` (freeText: 'interpret'). */
       interpreted?: true;
+      /**
+       * Who pressed the button, for `channel: 'inbox'` only: a username. On an
+       * answer given on a recipient's behalf it is not `by`.
+       */
+      user?: string;
     }
   | 'unanswered';
 
@@ -626,8 +719,8 @@ 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, text?, interpreted?, at }`
-   * (text and interpreted passed through when given), `at` being
+   * open with `{ outcome: 'answered', answer, by, channel, text?, interpreted?, user?, at }`
+   * (text, interpreted and user passed through when given), `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
@@ -700,16 +793,39 @@ export interface FlowHarness {
   notifications(): RecordedNotification[];
   /** People ctx.notify reports unreachable (no contact the message may use). */
   unreachable(...ids: string[]): FlowHarness;
+  /**
+   * Every ctx.tasks command, in order. open answers `{opened: true, key, rid:
+   * 'test-rid-<n>', url: 'test:ping'}` the first time a key is opened in a
+   * run and `opened: false` with the same rid after; the other verbs answer
+   * nothing. Cleared by reset().
+   */
+  tasks(): RecordedTaskCommand[];
   /**
    * 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;
+  /**
+   * Sets what series.<key>.get(range?) reads, replacing the key's fixture.
+   * get() answers the intervals overlapping the range, instants spelled as
+   * the host spells them (RFC 3339 UTC). Kept across reset().
+   */
+  series(key: string, fixture: SeriesFixture): FlowHarness;
+  /**
+   * Says what series.<key>.view(spec) answers, for a spec equal by value.
+   * Views are stubbed, never evaluated: an unstubbed view() fails naming the
+   * spec and the binding. Kept across reset().
+   */
+  seriesView(
+    key: string,
+    spec: object,
+    result: SeriesViewAnswer | ((spec: any) => SeriesViewAnswer)
+  ): 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.
+   * timezone, solar, credentials, webhook URLs, series and view stubs.
    */
   reset(): FlowHarness;
 }
@@ -739,6 +855,7 @@ export interface AppManifest {
   credentials?: string[];
   /** Keyed by event name; `payload` is the JSON Schema an emit is held to. */
   events?: Record<string, { payload?: object; [k: string]: unknown }>;
+  series?: FlowManifest['series'];
   [k: string]: unknown;
 }
 
@@ -770,6 +887,8 @@ export interface AppHarnessOptions<
   timezone?: string;
   /** As h.solar(). */
   solar?: SolarAnswer;
+  /** As h.series(), per binding key. */
+  series?: Record<string, SeriesFixture>;
 }
 
 /** One ctx.events.<event>.emit that passed the host's checks. */
@@ -826,9 +945,17 @@ export interface AppHarness {
   readonly controls: FlowControls;
   /** Sets ctx.credentials by declared id. Kept across reset(). */
   credentials(values: Record<string, string>): AppHarness;
+  /** As FlowHarness.series. */
+  series(key: string, fixture: SeriesFixture): AppHarness;
+  /** As FlowHarness.seriesView. */
+  seriesView(
+    key: string,
+    spec: object,
+    result: SeriesViewAnswer | ((spec: any) => SeriesViewAnswer)
+  ): AppHarness;
   /**
    * Clears recordings, answers and seeded states; keeps the clock, timezone,
-   * solar and credentials.
+   * solar, credentials, series and view stubs.
    */
   reset(): AppHarness;
 }

package/src/index.js

@@ -1,5 +1,6 @@
 import { fail } from './assert.js';
 import { setFinding } from './findings.js';
+import { publishSeries, renderSeries } from './series.js';
 import { names } from './names.js';
 import { conformance } from './conformance.js';
 import { createHttpMock, withFetch } from './http.js';
@@ -42,6 +43,9 @@ export function harness({ manifest, integration } = {}) {
     // publish of the same name overwrites rather than accumulates — h.states()
     // is the current picture, not a log.
     publishedStates: new Map(),
+    // The step function each series holds after what ctx.series.publish sent,
+    // keyed by local name — merged as the host merges it, not a log.
+    publishedSeries: new Map(),
     // 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,
@@ -252,6 +256,12 @@ export function harness({ manifest, integration } = {}) {
     findings: () => state.findings.map((f) => ({ ...f })),
     /** Values ctx.states.publish has sent so far, keyed by local name. */
     states: () => Object.fromEntries(state.publishedStates),
+    /**
+     * Each series ctx.series.publish has written, keyed by local name: the
+     * merged step function the host would hold, intervals sorted by from, with
+     * from/to as ISO UTC strings. A series never published is absent.
+     */
+    series: () => renderSeries(state.publishedSeries),
     /**
      * The last report ctx.status.set sent, or null when the handler never
      * reported — absence is a legitimate outcome, not an empty report.
@@ -288,6 +298,7 @@ export function harness({ manifest, integration } = {}) {
       state.emitted.length = 0;
       state.logs.length = 0;
       state.publishedStates.clear();
+      state.publishedSeries.clear();
       state.status = null;
       state.reports.length = 0;
       state.replies.length = 0;
@@ -499,6 +510,11 @@ function buildContext(manifest, state, webhooks) {
         publishStates(manifest, state, values);
       },
     },
+    series: {
+      async publish(values, options) {
+        publishSeries(manifest, state.publishedSeries, values, options);
+      },
+    },
     status: {
       async set(report) {
         setStatus(state, report);

package/src/series-read.js

@@ -0,0 +1,262 @@
+import { fail } from './assert.js';
+import { jsonCopy } from './bindings.js';
+import { goTime, parseTime } from './series.js';
+
+/**
+ * A flow's or an app's `series` bindings, in process: ctx.series.<key>.get()
+ * answered from the test's fixture and ctx.series.<key>.view() from its stubs.
+ *
+ * get() copies the host (internal/executor/series.go's SeriesGet): the range
+ * bounds' refusals, word for word, and the overlap filter — an interval is in
+ * [from, to) unless it ends at or before from or starts at or after to. The
+ * instants come back as the host spells them, RFC 3339 in UTC with no trailing
+ * zero fraction. published_at, issued_at and covered_until are the fixture's
+ * metadata, or null: the harness has no store to stamp a publish and no clock
+ * it may read unasked.
+ *
+ * view() is stubbed, never evaluated: a view with a cron or solar edge in a
+ * site zone is the host's code, and a second implementation here would
+ * disagree with it the first time either changed. h.seriesView(key, spec,
+ * result) says what a view answers, matched by deep equality on the spec as it
+ * crosses the wire (after JSON), and an unstubbed view() fails naming it.
+ *
+ * The refusal for a key the manifest does not bind is ResolveSeriesBinding's,
+ * byte for byte (`this flow's` / `this app's`).
+ */
+export function createSeriesBindings(manifest, harness, { app = false } = {}) {
+  const bindings = manifest.series ?? {};
+  const harnessName = app ? 'appHarness' : 'flowHarness';
+  // key → { intervals: [{from, to, value}] in ms, published_at, issued_at, covered_until }
+  const fixtures = new Map();
+  // key → [{ spec (JSON text), result }]
+  const stubs = new Map();
+
+  function undeclared(name) {
+    const whose = app ? "this app's" : "this flow's";
+    const keys = Object.keys(bindings).sort();
+    const declared = keys.length
+      ? keys.map((k) => JSON.stringify(k)).join(', ')
+      : 'none';
+    return `series binding ${JSON.stringify(name)} is not declared in ${whose} series; it declares ${declared}`;
+  }
+
+  function declaredKey(name, where) {
+    if (!Object.hasOwn(bindings, name)) fail(`${where} — ${undeclared(name)}`);
+  }
+
+  const h = {
+    /**
+     * Sets what series.<key>.get() reads: an array of intervals
+     * `{from, to, value}` (Date or RFC 3339 bounds, sorted, non-overlapping),
+     * or `{intervals, published_at?, issued_at?, covered_until?}`. Replaces
+     * the key's fixture; kept across reset().
+     */
+    series(key, fixture) {
+      declaredKey(key, `h.series('${key}', …)`);
+      fixtures.set(key, parseFixture(key, fixture));
+      return harness();
+    },
+
+    /**
+     * Says what series.<key>.view(spec) answers: a SeriesViewResult (fields
+     * left out read false / null / []) or a function of the spec returning
+     * one. Matched by deep equality on the spec; a later stub for an equal
+     * spec replaces the earlier. Kept across reset().
+     */
+    seriesView(key, spec, result) {
+      declaredKey(key, `h.seriesView('${key}', …)`);
+      const text = canonical(
+        spec ?? {},
+        `h.seriesView('${key}', …) — the spec`
+      );
+      const list = (stubs.get(key) ?? []).filter((s) => s.spec !== text);
+      list.push({ spec: text, result });
+      stubs.set(key, list);
+      return harness();
+    },
+  };
+
+  /** ctx.series for one run; refuse is the run's recording fail(). */
+  function ctx(refuse) {
+    return new Proxy(
+      {},
+      {
+        get(_own, prop) {
+          if (typeof prop !== 'string') return undefined;
+          return handle(prop, refuse);
+        },
+      }
+    );
+  }
+
+  function handle(binding, refuse) {
+    const q = JSON.stringify(binding);
+    return {
+      async get(range) {
+        if (!Object.hasOwn(bindings, binding)) refuse(undeclared(binding));
+        // seriesHandle in sdk/src/context.ts: a Date sent as its ISO string.
+        const fromText = boundText(range?.from);
+        const toText = boundText(range?.to);
+        const from = bound(binding, 'from', fromText, refuse);
+        const to = bound(binding, 'to', toText, refuse);
+        if (from !== null && to !== null && !(from < to)) {
+          refuse(`series ${q}: from must be before to`);
+        }
+        const fx = fixtures.get(binding);
+        if (!fx) {
+          refuse(
+            `series.${binding}.get() was called but the test gave no series — ` +
+              `h.series('${binding}', [{ from, to, value }, …]), or ${harnessName}({ series: { ${binding}: […] } })`
+          );
+        }
+        return {
+          series_id: bindings[binding].series ?? '',
+          published_at: fx.published_at,
+          issued_at: fx.issued_at,
+          covered_until: fx.covered_until,
+          intervals: fx.intervals
+            .filter(
+              (iv) =>
+                !(from !== null && iv.to <= from) &&
+                !(to !== null && iv.from >= to)
+            )
+            .map((iv) => ({
+              from: goTime(iv.from),
+              to: goTime(iv.to),
+              value: jsonCopy(iv.value),
+            })),
+        };
+      },
+
+      async view(spec) {
+        if (!Object.hasOwn(bindings, binding)) refuse(undeclared(binding));
+        const text = canonical(
+          spec ?? {},
+          `series.${binding}.view(…) — the spec`,
+          refuse
+        );
+        const stub = (stubs.get(binding) ?? []).find((s) => s.spec === text);
+        if (!stub) {
+          refuse(
+            `series.${binding}.view(${text}) was not stubbed — ` +
+              `h.seriesView('${binding}', ${text}, { available: true, value, … }). ` +
+              'The harness does not evaluate views; say what this one answers'
+          );
+        }
+        const r =
+          typeof stub.result === 'function'
+            ? await stub.result(JSON.parse(text))
+            : stub.result;
+        const out =
+          jsonCopy(r ?? {}, `h.seriesView('${binding}', …) — the result`) ?? {};
+        // seriesHandle's defaults for a field the host sent as null.
+        return {
+          available: out.available ?? false,
+          value: out.value ?? null,
+          reason: out.reason ?? null,
+          until: out.until ?? null,
+          spans: out.spans ?? [],
+        };
+      },
+    };
+  }
+
+  /** Applies the harness option `series`, through h.series. */
+  function init(series) {
+    for (const [key, fixture] of Object.entries(series ?? {})) {
+      h.series(key, fixture);
+    }
+  }
+
+  return { h, ctx, init };
+}
+
+function boundText(v) {
+  if (v === undefined) return '';
+  return v instanceof Date ? v.toISOString() : v;
+}
+
+// seriesBound in internal/executor/series.go: empty is unbounded.
+function bound(binding, field, text, refuse) {
+  if (text === '') return null;
+  const ms = parseTime(text);
+  if (ms === null) {
+    refuse(
+      `series ${JSON.stringify(binding)}: ${field} ${JSON.stringify(String(text))} is not an RFC 3339 instant`
+    );
+  }
+  return ms;
+}
+
+/**
+ * The spec as the wire carries it, with object keys sorted so two specs equal
+ * by value compare equal as text.
+ */
+function canonical(spec, what, refuse = fail) {
+  const copy = jsonCopy(spec, what, refuse);
+  return JSON.stringify(sortKeys(copy));
+}
+
+function sortKeys(v) {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === 'object') {
+    return Object.fromEntries(
+      Object.keys(v)
+        .sort()
+        .map((k) => [k, sortKeys(v[k])])
+    );
+  }
+  return v;
+}
+
+const FIXTURE_META = ['published_at', 'issued_at', 'covered_until'];
+
+function parseFixture(key, fixture) {
+  const where = `h.series('${key}', …)`;
+  let list = fixture;
+  const meta = { published_at: null, issued_at: null, covered_until: null };
+  if (!Array.isArray(fixture)) {
+    if (!fixture || typeof fixture !== 'object') {
+      fail(
+        `${where} takes an array of { from, to, value }, or { intervals, published_at?, issued_at?, covered_until? }`
+      );
+    }
+    for (const k of Object.keys(fixture)) {
+      if (k !== 'intervals' && !FIXTURE_META.includes(k)) {
+        fail(
+          `${where} — "${k}" is not a fixture field (have: intervals, ${FIXTURE_META.join(', ')})`
+        );
+      }
+    }
+    for (const k of FIXTURE_META) {
+      if (fixture[k] === undefined || fixture[k] === null) continue;
+      const ms = parseTime(fixture[k]);
+      if (ms === null) fail(`${where} — ${k} is not an RFC 3339 timestamp`);
+      meta[k] = goTime(ms);
+    }
+    list = fixture.intervals ?? [];
+  }
+  if (!Array.isArray(list)) fail(`${where} — intervals must be an array`);
+  const intervals = list.map((iv, i) => {
+    const from = parseTime(iv?.from);
+    if (from === null) {
+      fail(`${where} — interval ${i}: from is not an RFC 3339 timestamp`);
+    }
+    const to = parseTime(iv?.to);
+    if (to === null) {
+      fail(`${where} — interval ${i}: to is not an RFC 3339 timestamp`);
+    }
+    if (!(from < to)) fail(`${where} — interval ${i}: from must be before to`);
+    return {
+      from,
+      to,
+      value: jsonCopy(iv.value, `${where} — interval ${i}'s value`),
+    };
+  });
+  intervals.forEach((iv, i) => {
+    if (i > 0 && iv.from < intervals[i - 1].to) {
+      fail(`${where} — interval ${i} starts before interval ${i - 1} ends`);
+    }
+  });
+  return { ...meta, intervals };
+}

package/src/series.js

@@ -0,0 +1,168 @@
+import { fail } from './assert.js';
+
+/**
+ * ctx.series.publish, in process: the refusals and the span arithmetic the
+ * host applies (internal/integrations/external's seriesBatch and
+ * internal/series.Store.Publish), copied rather than shared because the
+ * testkit cannot import the Go side. Every refusal is the host's sentence,
+ * byte for byte, so a test that expects one sees what production throws.
+ *
+ * `published` maps a local name to its step function: intervals
+ * `{from, to, value}` with from/to in epoch milliseconds, sorted and
+ * non-overlapping. The whole batch is validated before any series changes.
+ *
+ * Not copied: value validation against the declaration (its wording names Go
+ * types), the interval-count limits, and retention — the harness has no clock
+ * that moves, so nothing ages out.
+ */
+export function publishSeries(manifest, published, values, options = {}) {
+  const declared = manifest.series ?? {};
+  const install = manifest.id ?? manifest.name;
+
+  let issuedAt = null;
+  if (options?.issuedAt !== undefined) {
+    issuedAt = parseTime(options.issuedAt);
+    if (issuedAt === null) fail('issued_at is not an RFC 3339 timestamp');
+  }
+
+  // The adapter: names, then timestamps, in sorted name order.
+  const batch = new Map();
+  const entries = Object.entries(values ?? {})
+    .filter(([, data]) => data !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  for (const [name, data] of entries) {
+    if (!Object.prototype.hasOwnProperty.call(declared, name)) {
+      fail(`series "${name}" is not declared by ${install}`);
+    }
+    const intervals = (data.intervals ?? []).map((iv, i) => {
+      const from = parseTime(iv.from);
+      if (from === null) {
+        fail(
+          `series "${name}": interval ${i}: from is not an RFC 3339 timestamp`
+        );
+      }
+      const to = parseTime(iv.to);
+      if (to === null) {
+        fail(
+          `series "${name}": interval ${i}: to is not an RFC 3339 timestamp`
+        );
+      }
+      return { from, to, value: iv.value };
+    });
+    let span = null;
+    if (data.span !== undefined) {
+      const from = parseTime(data.span.from);
+      if (from === null) {
+        fail(`series "${name}": span: from is not an RFC 3339 timestamp`);
+      }
+      const to = parseTime(data.span.to);
+      if (to === null) {
+        fail(`series "${name}": span: to is not an RFC 3339 timestamp`);
+      }
+      span = { from, to };
+    }
+    batch.set(name, { intervals, span });
+  }
+
+  // The store: the forecast rule over the whole batch first, then each series.
+  for (const name of batch.keys()) {
+    if (declared[name].forecast === true && issuedAt === null) {
+      fail(`series "${name}" is a forecast: the publish needs issuedAt`);
+    }
+  }
+  const next = new Map();
+  for (const [name, { intervals, span: explicit }] of batch) {
+    intervals.forEach((iv, i) => {
+      if (!(iv.from < iv.to)) {
+        fail(`series "${name}": interval ${i}: from must be before to`);
+      }
+      if (i > 0 && iv.from < intervals[i - 1].to) {
+        fail(
+          `series "${name}": interval ${i} starts before interval ${i - 1} ends`
+        );
+      }
+    });
+    let span;
+    if (explicit) {
+      if (!(explicit.from < explicit.to)) {
+        fail(`series "${name}": span: from must be before to`);
+      }
+      intervals.forEach((iv, i) => {
+        if (iv.from < explicit.from || iv.to > explicit.to) {
+          fail(
+            `series "${name}": interval ${i} is outside the span ` +
+              `${goTime(explicit.from)} → ${goTime(explicit.to)}`
+          );
+        }
+      });
+      span = explicit;
+    } else if (intervals.length === 0) {
+      fail(`series "${name}": no intervals and no span: nothing to replace`);
+    } else if (declared[name].forecast === true) {
+      span = { from: intervals[0].from, to: Infinity };
+    } else {
+      span = {
+        from: intervals[0].from,
+        to: intervals[intervals.length - 1].to,
+      };
+    }
+    next.set(name, replace(published.get(name) ?? [], span, intervals));
+  }
+  for (const [name, steps] of next) published.set(name, steps);
+}
+
+/**
+ * replace is Store.Publish's: everything outside span kept, an interval
+ * straddling an edge cut there keeping its outside part, then the incoming
+ * intervals, sorted by from. `span.to` is Infinity for an unbounded span.
+ */
+export function replace(steps, span, incoming) {
+  const out = [];
+  for (const iv of steps) {
+    if (iv.to <= span.from || iv.from >= span.to) {
+      out.push(iv);
+      continue;
+    }
+    if (iv.from < span.from)
+      out.push({ from: iv.from, to: span.from, value: iv.value });
+    if (iv.to > span.to)
+      out.push({ from: span.to, to: iv.to, value: iv.value });
+  }
+  out.push(...incoming.map((iv) => ({ ...iv })));
+  out.sort((a, b) => a.from - b.from);
+  return out;
+}
+
+/** A step function as h.series() shows it: ISO UTC strings, copies. */
+export function renderSeries(published) {
+  const out = {};
+  for (const [name, steps] of published) {
+    out[name] = steps.map((iv) => ({
+      from: new Date(iv.from).toISOString(),
+      to: new Date(iv.to).toISOString(),
+      value: iv.value,
+    }));
+  }
+  return out;
+}
+
+// What Go's time.Parse(time.RFC3339Nano, …) accepts, near enough: a full date,
+// a 'T', a time with optional fraction, and 'Z' or a numeric offset.
+const RFC3339 =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+/** A Date or RFC 3339 string → epoch ms, or null when it is neither. */
+export function parseTime(t) {
+  if (t instanceof Date) {
+    const ms = t.getTime();
+    return Number.isNaN(ms) ? null : ms;
+  }
+  if (typeof t !== 'string' || !RFC3339.test(t)) return null;
+  const ms = Date.parse(t);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+/** An instant as Go's RFC3339Nano renders it in UTC: no trailing zero fraction. */
+export function goTime(ms) {
+  return new Date(ms).toISOString().replace(/\.?0+Z$/, 'Z');
+}

package/src/tasks.js

@@ -0,0 +1,126 @@
+import { jsonCopy } from './bindings.js';
+import { names } from './names.js';
+
+// The tasks half of the flow harness: ctx.tasks.<binding>.open / snooze /
+// complete / cancel, and h.tasks(), which reads back what was sent.
+//
+// There is no task here, so nothing is opened: open answers as the host would
+// for work nobody has opened yet — `{opened: true, key, rid: 'test-rid-<n>',
+// url: 'test:ping'}` the first time a key is opened in a run, and `opened:
+// false` with the same rid after — and the other verbs answer nothing, as
+// they do on the host, which makes them idempotent on key. The rid counts
+// opens that opened something, from 1, per run.
+
+const VERBS = ['open', 'snooze', 'complete', 'cancel'];
+// A flow's handle also waits: untilDone, on the run's handle table.
+const FLOW_VERBS = [...VERBS, 'untilDone'];
+
+/** An instant as the SDK sends it: a Date as its ISO string. */
+const instant = (t) => (t instanceof Date ? t.toISOString() : t);
+
+export function createTasks(manifest) {
+  const tasks = manifest.tasks ?? {};
+  const records = [];
+
+  /**
+   * One run's ctx.tasks. Built per run: which keys are open is per run.
+   * handles is the run's handle table, which gives every binding untilDone.
+   */
+  function ctx(refuse, handles) {
+    const opened = new Map(); // key → rid
+    const handle = (binding) => {
+      const command = (verb, fields) => {
+        const call = { binding, verb };
+        for (const [k, v] of Object.entries(fields)) {
+          if (v !== undefined) call[k] = v;
+        }
+        if (Object.hasOwn(call, 'data')) {
+          call.data = jsonCopy(
+            call.data,
+            `tasks.${binding}.${verb}() data`,
+            refuse
+          );
+        }
+        records.push(call);
+        return call;
+      };
+      const h = {
+        async open(opts) {
+          const call = command('open', {
+            key: opts?.key,
+            at: instant(opts?.at),
+            within: opts?.within,
+            reason: opts?.reason,
+            data: opts?.data,
+          });
+          const key = call.key ?? '';
+          const first = !opened.has(key);
+          if (first) opened.set(key, `test-rid-${opened.size + 1}`);
+          return { opened: first, key, rid: opened.get(key), url: 'test:ping' };
+        },
+        async snooze(opts) {
+          // The host's refusal, worded as the host words it.
+          if (opts?.until === undefined) {
+            refuse(`tasks.${binding}.snooze(): until is required`);
+          }
+          command('snooze', { key: opts?.key, until: instant(opts.until) });
+        },
+        async complete(opts) {
+          command('complete', {
+            key: opts?.key,
+            outcome: opts?.outcome,
+            note: opts?.note,
+          });
+        },
+        async cancel(opts) {
+          command('cancel', { key: opts?.key, reason: opts?.reason });
+        },
+      };
+      if (handles) {
+        h.untilDone = (...args) =>
+          handles.taskHandle(`tasks.${binding}.untilDone`, args);
+      }
+      const verbs = handles ? FLOW_VERBS : VERBS;
+      return new Proxy(h, {
+        get(own, prop) {
+          if (typeof prop !== 'string' || prop === 'then') return undefined;
+          if (!verbs.includes(prop)) {
+            refuse(
+              `ctx.tasks.${binding}.${prop} — not a task verb (have: ${verbs.join(', ')})`
+            );
+          }
+          return own[prop];
+        },
+      });
+    };
+    return new Proxy(
+      {},
+      {
+        get(_own, prop) {
+          if (typeof prop !== 'string' || prop === 'then') return undefined;
+          if (!Object.hasOwn(tasks, prop)) {
+            refuse(
+              `ctx.tasks.${prop} — "${prop}" is not declared in manifest.json (have: ${names(tasks)})`
+            );
+          }
+          return handle(prop);
+        },
+      }
+    );
+  }
+
+  return {
+    ctx,
+    h: {
+      /**
+       * Every task command, in order: `{binding, verb, key?, at?, within?,
+       * until?, reason?, data?, outcome?, note?}`, the options as the SDK
+       * sends them (a Date as its ISO string, absent ones left out).
+       */
+      tasks: () => records.map((r) => jsonCopy(r, 'a task command')),
+    },
+    reset() {
+      records.length = 0;
+    },
+  };
+}