@alexkroman1/aai-cli 13.2.0 → 14.0.0

package/dist/templates/podcast-digest/workflows/feeds.ts

@@ -64,9 +64,9 @@
  * parsing. It is the section below's subject, not this one's.
  */
 
-import { type FeedItem, pageMetadata, parseFeed } from "@alexkroman1/aai/html";
-import { report } from "@alexkroman1/aai/step";
-import { FatalError, stepFetchOk } from "@alexkroman1/aai/step-errors";
+import { type FeedItem, type ParsedFeed, pageMetadata, parseFeed } from "@alexkroman1/aai/html";
+import { mapConcurrent, stepReport } from "@alexkroman1/aai/step";
+import { FatalError, stepFetchOrFail } from "@alexkroman1/aai/step-errors";
 import { isRecord, omitUndefined, safeJsonParse } from "@alexkroman1/aai/utils";
 import { z } from "zod";
 
@@ -74,19 +74,32 @@ import { z } from "zod";
 const REQUEST_TIMEOUT_MS = 30_000;
 
 /**
- * A show, reduced to what the rest of the run needs — plus the body, when
- * resolving it already had to download one.
+ * How many pasted links are resolved at once.
  *
- * `xml` is the difference between one request per feed and two. Both web paths
- * fetch the feed to decide whether it IS a feed (`looksLikePodcastFeed`), and
- * without somewhere to put that body the reader downloads the identical
- * document a second time. The Apple and Spotify paths resolve a URL without
- * ever reading the feed, so they leave it unset and the reader fetches once.
+ * Small because the far side is Apple and Spotify, who rate-limit, and because
+ * a digest is a handful of shows rather than a fan-out — the win is turning N
+ * sequential round trips into a couple of overlapped ones, not saturating a
+ * link.
+ */
+const RESOLVE_CONCURRENCY = 4;
+
+/**
+ * A show, reduced to what the rest of the run needs — plus the PARSE, when
+ * resolving it already had to do one.
+ *
+ * `parsed` is the difference between one request per feed and two, and between
+ * one parse and three. Both web paths fetch the feed to decide whether it IS a
+ * feed, and without somewhere to put the result the reader downloads and
+ * re-parses the identical document. Re-parsing is the more expensive half:
+ * `parseFeed` builds a DOM and runs `htmlToText` over every item's title AND
+ * description, and a podcast feed routinely carries 300+ entries of HTML show
+ * notes. The Apple and Spotify paths resolve a URL without ever reading the
+ * feed, so they leave it unset and the reader fetches once.
  */
 export type PodcastFeed = {
   feedUrl: string;
   title: string;
-  xml?: string;
+  parsed?: ParsedFeed;
 };
 
 /** One episode with audio attached — the unit everything downstream works on. */
@@ -114,12 +127,17 @@ export async function discoverEpisodes(
   podcastChannels: string,
   maxEpisodes: number,
 ): Promise<Episode[]> {
-  await report("Finding recent podcast episodes.");
+  await stepReport("Finding recent podcast episodes.");
   const links = parsePodcastChannels(podcastChannels);
   if (links.length === 0) throw new FatalError("Add at least one podcast link.");
 
-  const feeds: PodcastFeed[] = [];
-  for (const url of links) feeds.push(await resolvePodcastFeed(url));
+  // Overlapped, not sequential: each resolution is one to three HTTP round
+  // trips with a 30s ceiling, and the links are independent. Bounded rather
+  // than a bare `Promise.all` because Apple and Spotify both rate-limit — and
+  // legal here because this whole function is a STEP BODY (`ctx.step` wraps it
+  // in `digest.ts`), so the journal's name+occurrence rule does not apply to
+  // what happens inside it.
+  const feeds = await mapConcurrent(links, RESOLVE_CONCURRENCY, resolvePodcastFeed);
 
   const episodes = (await Promise.all(feeds.map((feed) => readPodcastFeed(feed))))
     .flat()
@@ -154,7 +172,10 @@ async function resolvePodcastFeed(url: string): Promise<PodcastFeed> {
  */
 async function resolveWebPodcastFeed(url: string): Promise<PodcastFeed> {
   const body = await fetchText(url);
-  if (looksLikePodcastFeed(body)) return feedFrom(url, body);
+  // Parsed ONCE and carried: the "is this a feed" test, the channel title and
+  // the item list are three reads of one parse, not three parses.
+  const direct = parseFeed(body);
+  if (carriesAudio(direct)) return feedFrom(url, direct);
 
   const discovered = discoverFeedUrl(body, url);
   if (!discovered) {
@@ -167,9 +188,9 @@ async function resolveWebPodcastFeed(url: string): Promise<PodcastFeed> {
   // The advertised URL is verified rather than trusted: plenty of pages point
   // `application/rss+xml` at a blog feed with no audio in it, and finding that
   // out here names the page, where finding it out later names an empty digest.
-  // The body is carried forward rather than re-fetched — see `PodcastFeed.xml`.
-  const verified = await fetchText(discovered);
-  if (!looksLikePodcastFeed(verified)) {
+  // The parse is carried forward rather than redone — see `PodcastFeed.parsed`.
+  const verified = parseFeed(await fetchText(discovered));
+  if (!carriesAudio(verified)) {
     throw new FatalError(`The feed at ${discovered} does not look like a podcast RSS feed.`);
   }
   return feedFrom(discovered, verified);
@@ -236,8 +257,9 @@ async function resolveSpotifyPodcastFeed(url: string): Promise<PodcastFeed> {
 
 /** Every item in the feed that has audio attached, newest first by the caller. */
 async function readPodcastFeed(feed: PodcastFeed): Promise<Episode[]> {
-  const xml = feed.xml ?? (await fetchText(feed.feedUrl));
-  const parsed = parseFeed(xml);
+  // Already parsed on the web paths; the Apple and Spotify paths resolve a URL
+  // without ever reading the feed, so this is where those two download it.
+  const parsed = feed.parsed ?? parseFeed(await fetchText(feed.feedUrl));
   // `parsed.title` is the CHANNEL's, which is the whole reason to parse: the
   // `indexOf` read this replaces took the first `<title>` at any depth.
   const podcastTitle = parsed?.title ?? feed.title;
@@ -393,17 +415,23 @@ export function titleMatchesSpotify(
   );
 }
 
-/** A feed document that actually carries audio — both halves are required. */
-export function looksLikePodcastFeed(xml: string): boolean {
-  const parsed = parseFeed(xml);
-  // `parseFeed` answering at all is the "is this a feed" half, and it is
-  // stricter than the `<rss` test it replaces in the direction that matters:
-  // an HTML page mentioning `<rss` in prose is not a feed. It is also wider
-  // where being wide is right — an Atom podcast feed has no `<rss` root and
-  // was refused outright.
+/**
+ * A parse that actually carries audio — both halves are required.
+ *
+ * `parseFeed` answering at all is the "is this a feed" half, and it is stricter
+ * than the `<rss` test it replaces in the direction that matters: an HTML page
+ * mentioning `<rss` in prose is not a feed. It is also wider where being wide is
+ * right — an Atom podcast feed has no `<rss` root and was refused outright.
+ */
+function carriesAudio(parsed: ParsedFeed | undefined): parsed is ParsedFeed {
   return parsed?.items.some((item) => item.enclosureUrl !== undefined) ?? false;
 }
 
+/** {@link carriesAudio} over a document that has not been parsed yet. */
+export function looksLikePodcastFeed(xml: string): boolean {
+  return carriesAudio(parseFeed(xml));
+}
+
 /** The first feed a page advertises, resolved against the page's own URL. */
 export function discoverFeedUrl(html: string, pageUrl: string): string | undefined {
   // `pageMetadata` reads `<link>` off a parse, so attribute ORDER stops
@@ -441,11 +469,11 @@ function publishedAt(episode: Episode): number {
   return Number.isNaN(parsed) ? 0 : parsed;
 }
 
-function feedFrom(feedUrl: string, body: string): PodcastFeed {
+function feedFrom(feedUrl: string, parsed: ParsedFeed): PodcastFeed {
   return {
     feedUrl,
-    title: parseFeed(body)?.title ?? hostOf(feedUrl),
-    xml: body,
+    title: parsed.title ?? hostOf(feedUrl),
+    parsed,
   };
 }
 
@@ -529,7 +557,7 @@ function appleResults(body: unknown): AppleResult[] {
 /**
  * Every outbound call in this file, with one timeout and one failure policy.
  *
- * `stepFetchOk` is `stepFetch` plus the non-2xx branch — see its own doc. Three
+ * `stepFetchOrFail` is `stepFetch` plus the non-2xx branch — see its own doc. Three
  * things come with it that a bare `fetch` here would each have to re-derive:
  * HTTP/1.1 (so a rate limit arrives as a `503` with `Retry-After` rather than
  * an h2 stream reset carrying no status), the transient/terminal verdict the
@@ -537,7 +565,7 @@ function appleResults(body: unknown): AppleResult[] {
  * the iTunes endpoints is the difference between "403" and a sentence.
  */
 async function fetchText(url: string): Promise<string> {
-  const response = await stepFetchOk(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  const response = await stepFetchOrFail(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
   return await response.text();
 }
 

package/dist/templates/podcast-digest/workflows/slack.ts

@@ -7,7 +7,7 @@
  * webhook shapes and the branch between them, Block Kit assembly, mrkdwn
  * escaping, the 4xx/5xx split and the advice each refusal deserves. All of it
  * is `@alexkroman1/aai/channels` now — `slackChannel()` names the destination,
- * `sendToChannelClassified` posts and classifies — and what is left here is the
+ * `sendToChannelOrFail` posts and classifies — and what is left here is the
  * part that is actually about podcasts: turning episode digests into a
  * {@link ChannelMessage}.
  *
@@ -22,13 +22,13 @@
  * The step BOUNDARY is not here — only a body holds a `ctx`, and the call this
  * file is reached through is `ctx.step("postDigest", …)` in `digest.ts`. What
  * stays here is what a step DOES: the digest rendered as a `ChannelMessage` and
- * one `sendToChannelClassified` call. Deciding which steps exist is the
+ * one `sendToChannelOrFail` call. Deciding which steps exist is the
  * template's job; what happens inside one is the SDK's.
  */
 
 import { type ChannelMessage, slackChannel } from "@alexkroman1/aai/channels";
-import { report } from "@alexkroman1/aai/step";
-import { sendToChannelClassified } from "@alexkroman1/aai/step-errors";
+import { stepReport } from "@alexkroman1/aai/step";
+import { sendToChannelOrFail } from "@alexkroman1/aai/step-errors";
 import type { EpisodeDigest } from "./digest.ts";
 
 /** Everything the message needs, so rendering can stay a pure function. */
@@ -46,14 +46,14 @@ export type SlackDigestInput = {
  *
  * It is three lines because the interesting decisions moved. `slackChannel()` builds
  * the descriptor, {@link renderDigestMessage} says what the message contains,
- * and `sendToChannelClassified` does the render-post-classify round — throwing
+ * and `sendToChannelOrFail` does the render-post-classify round — throwing
  * a `FatalError` on a 4xx (a revoked webhook and a wrong variable name answer
  * identically on every retry, so retrying only delays the real error) and a
  * `RetryableError` carrying Slack's own `Retry-After` on a 5xx.
  */
 export async function sendDigestToSlack(input: SlackDigestInput): Promise<string> {
-  await report("Posting the digest to Slack.");
-  return await sendToChannelClassified(
+  await stepReport("Posting the digest to Slack.");
+  return await sendToChannelOrFail(
     slackChannel({ webhookUrl: input.slackWebhookUrl, textParam: input.slackWorkflowTextParam }),
     renderDigestMessage(input),
   );

package/dist/templates/recap-workflow/agent.eval.test.ts

@@ -40,7 +40,7 @@
 //
 //     What no eval here can show is a delivery RESUMING a run, so no case claims
 //     it. The answered arm is `agent.test.ts`'s, through
-//     `createWorkflowCtx({ hooks })`, which is the only tier that can send a
+//     `createWorkflowContext({ hooks })`, which is the only tier that can send a
 //     payload at all; a real HTTP POST to the public callback route is
 //     `aai-cli`'s `dev-workflow.scenario.test.ts`'s, and is not yet written.
 //   * **The provider is scripted, in BOTH modes**, through `stepFetch`'s
@@ -62,7 +62,7 @@
  * this file SHIPS — see `agent.test.ts`.
  */
 import agentDef from "virtual:aai/agent";
-import { stubGatewayRoute } from "@alexkroman1/aai/testing";
+import { routeStepFetch, type StepRoute, stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import {
   describeToolCalls,
@@ -138,22 +138,30 @@ function stubProvider(options: { hold?: boolean; ending?: Ending } = {}): Script
   const gate = Promise.withResolvers<void>();
   const model = stubGatewayRoute(RECAP_JSON);
   let polls = 0;
-  const stub = installStubStepFetch(async (request) => {
-    const recapped = model.route(request);
-    if (recapped) return recapped;
+  // Two legs: the model, then the provider's job API. Anything neither answers is a
+  // finding, which is `routeStepFetch`'s default rather than this file's throw.
+  // Annotated, so the leg's contract is visible where it is written: answer the
+  // requests you recognise, `undefined` for everything else, and let
+  // `routeStepFetch` decide what an unrecognised one means.
+  const provider: StepRoute = (request) => {
     if (request.method === "POST") return { body: { id: TRANSCRIPT_ID, status: "queued" } };
     // The compensation. A real DELETE removes the transcript from the account,
     // which is what makes "a failed run leaves nothing behind" a claim rather
     // than a comment — so the assertion that matters is that this was CALLED.
     if (request.method === "DELETE") return { body: {} };
-    if (request.method === "GET") {
-      polls += 1;
-      if (options.hold === true && polls === 1) await gate.promise;
-      return options.ending === "error"
-        ? { body: { status: "error", error: "that recording could not be decoded" } }
-        : { body: { status: "completed", text: TRANSCRIPT_TEXT, audio_duration: 254 } };
-    }
-    throw new Error(`unexpected step request in an eval: ${request.method} ${request.url}`);
+    if (request.method !== "GET") return;
+    polls += 1;
+    return options.ending === "error"
+      ? { body: { status: "error", error: "that recording could not be decoded" } }
+      : { body: { status: "completed", text: TRANSCRIPT_TEXT, audio_duration: 254 } };
+  };
+  const route = routeStepFetch([model.route, provider]);
+  const stub = installStubStepFetch(async (request) => {
+    const answered = route(request);
+    // Held AFTER routing, so the poll this returns is the one the script owed
+    // it — and `polls` has already counted this request.
+    if (options.hold === true && request.method === "GET" && polls === 1) await gate.promise;
+    return answered;
   });
   return { calls: stub.calls, release: () => gate.resolve() };
 }

package/dist/templates/recap-workflow/agent.test.ts

@@ -33,7 +33,7 @@
  * **The branch this file used to name as its biggest gap no longer exists.** It
  * was `recapFlow`'s `if (isWorkflowSuspend(err)) throw err;` — the guard whose
  * absence had once deleted the transcript the run was waiting for — and it was
- * unpinnable here by construction, since `createWorkflowCtx`'s `sleep` is
+ * unpinnable here by construction, since `createWorkflowContext`'s `sleep` is
  * RECORDED and its `waitFor` answers out of `hooks`, so no wait it serves ever
  * suspended. A wait now hands the body a promise that never settles, so a
  * suspension cannot reach a `catch` at all and there is no branch left to test:
@@ -47,7 +47,7 @@ import type { WorkflowClient } from "@alexkroman1/aai";
 import {
   createRunSnapshot,
   createToolContext,
-  createWorkflowCtx,
+  createWorkflowContext,
   parseSchemaInput,
   schemaInputIssues,
   stubGatewayRoute,
@@ -55,7 +55,7 @@ import {
 } from "@alexkroman1/aai/testing";
 import {
   installStubStepFetch,
-  mockWorkflows,
+  installStubWorkflows,
   installStubGateway as stubGateway,
 } from "@alexkroman1/aai/testing/vitest";
 import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
@@ -89,14 +89,14 @@ const run = toolRunner(agentDef);
 /**
  * A `ctx.workflows` that records `start` and answers the lookups from a fixture.
  *
- * `mockWorkflows` (`@alexkroman1/aai/testing/vitest`) is the whole thing — a
+ * `installStubWorkflows` (`@alexkroman1/aai/testing/vitest`) is the whole thing — a
  * `vi.fn` per method over one `runs` list, with `stream`/`streamTail` left
  * rejecting because `recap_progress` reads progress through `lastLine` and
  * composing those two by hand is the hazard `lastLine` exists to remove. What
  * is local is only which workflow this desk declares.
  */
 function stubWorkflows(runs: WorkflowRunSnapshot[] = []): WorkflowClient {
-  return mockWorkflows({ runs, names: ["recap"] });
+  return installStubWorkflows({ runs, names: ["recap"] });
 }
 
 /** A finished recap, as the workflow's output reaches the tools. */
@@ -116,7 +116,13 @@ function finishedOutput(over: { kept?: boolean; answered?: boolean } = {}) {
 
 describe("the agent declares its workflow", () => {
   test("under the name ctx.workflows.start resolves it by", () => {
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["recap"]);
+    // `toContain` rather than an exact key list: a second workflow is an
+    // invited edit and must not redden a test the author did not write. The
+    // NAME is still pinned, deliberately — this key is a STRING to everything
+    // outside this file (the REST route, `ctx.workflows.get`, a schedule), so
+    // renaming it is a runtime 404 rather than a compile error, and nothing
+    // else says so.
+    expect(Object.keys(agentDef.workflows ?? {})).toContain("recap");
     expect(agentDef.workflows?.recap).toBe(recap);
   });
 
@@ -143,14 +149,21 @@ describe("the agent declares its workflow", () => {
   });
 
   test("discovers every tool in tools/, by file name", () => {
-    // Discovered, not declared: every name here is a file in `tools/`.
-    expect(Object.keys(agentDef.tools).sort()).toEqual([
-      "cancel_recap",
-      "keep_transcript",
-      "recap_progress",
-      "recap_status",
-      "request_recap",
-    ]);
+    // Discovered, not declared: every name here is a file in `tools/`. Asserted
+    // with `arrayContaining`, because dropping a file into `tools/` is the
+    // cheapest edit this template invites and an exact list would turn it into
+    // a failing test in somebody else's project. What still fails is a tool
+    // going MISSING — which is what a broken discovery looks like, and it looks
+    // identical to a template that never had tools.
+    expect(Object.keys(agentDef.tools)).toEqual(
+      expect.arrayContaining([
+        "cancel_recap",
+        "keep_transcript",
+        "recap_progress",
+        "recap_status",
+        "request_recap",
+      ]),
+    );
   });
 });
 
@@ -386,7 +399,7 @@ describe("cancel_recap", () => {
  *
  * Published into `stepFetch`'s OWN slot, not over `globalThis.fetch`. Every
  * request in this file goes through `stepFetch` — `request()` and
- * `discardTranscript` reach it directly, `stepTranscribeSubmitClassified`
+ * `discardTranscript` reach it directly, `stepTranscribeSubmitOrFail`
  * through the SDK — and `step-fetch.ts` falls back to `globalThis.fetch` only
  * when nothing is published. A global stub therefore passed while exercising a
  * path production never takes; every sibling template already stubs the slot,
@@ -673,7 +686,7 @@ describe("summarize", () => {
     // The policy is an argument to `ctx.step` now, so it is observable only at
     // the call. `runSteps: false` and a skeleton of results: the subject is what
     // the body ASKED FOR.
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       runSteps: false,
       results: {
         submitRecording: { id: "t_1" },
@@ -711,7 +724,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
       { status: "processing" },
       { status: "completed", text: "Done.", audio_duration: 60 },
     ]);
-    const state = await awaitTranscript("t_1", createWorkflowCtx());
+    const state = await awaitTranscript("t_1", createWorkflowContext());
     expect(state).toMatchObject({ status: "completed", text: "Done." });
     expect(polls()).toBe(3);
   });
@@ -720,13 +733,15 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // `error` is terminal: polling a failed job to the bound would spend twenty
     // minutes learning what the first answer already said.
     const polls = stubStatuses([{ status: "error", error: "Transcoding failed" }]);
-    await expect(awaitTranscript("t_1", createWorkflowCtx())).rejects.toThrow(/Transcoding failed/);
+    await expect(awaitTranscript("t_1", createWorkflowContext())).rejects.toThrow(
+      /Transcoding failed/,
+    );
     expect(polls()).toBe(1);
   });
 
   test("gives up at the bound rather than polling a stuck job forever", async () => {
     stubStatuses([{ status: "processing" }]);
-    await expect(awaitTranscript("t_1", createWorkflowCtx())).rejects.toThrow(/Gave up/);
+    await expect(awaitTranscript("t_1", createWorkflowContext())).rejects.toThrow(/Gave up/);
   });
 
   /** A job still `processing` for `polls` turns, then completed. */
@@ -745,7 +760,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // the constant promises is eight sleeps, so the earliest honest turn to say
     // it is the ninth. Here the job finishes on that ninth poll, two minutes in
     // and not a second over, so the caller is told nothing.
-    const ctx = createWorkflowCtx();
+    const ctx = createWorkflowContext();
     stubSlowJob(8);
 
     await awaitTranscript("t_1", ctx);
@@ -760,7 +775,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // two minutes of waiting behind it — so the note goes out, and the eleven
     // polls after it say nothing more. A note per poll would be a caller told
     // the same sentence every fifteen seconds.
-    const ctx = createWorkflowCtx();
+    const ctx = createWorkflowContext();
     stubSlowJob(20);
 
     await awaitTranscript("t_1", ctx);
@@ -775,7 +790,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
   // cases are the REGRESSION guard for this section: the poll-only arm has to
   // keep behaving exactly as it did before there was a callback at all.
   //
-  // `createWorkflowCtx` is the only tier that can drive the answered branch:
+  // `createWorkflowContext` is the only tier that can drive the answered branch:
   // its `waitFor` reads `hooks` by token, so supplying a payload IS the delivery
   // landing and omitting one IS the window closing. The eval tier cannot —
   // nothing there can signal — so it only ever sees the fallback, which is
@@ -793,7 +808,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
       { status: "processing" },
       { status: "completed", text: "Done.", audio_duration: 60 },
     ]);
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       hooks: { [NUDGE]: { transcript_id: "t_1", status: "completed" } },
     });
 
@@ -818,7 +833,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
       { status: "processing" },
       { status: "completed", text: "The real transcript.", audio_duration: 60 },
     ]);
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       hooks: { [NUDGE]: { transcript_id: "t_1", status: "completed", text: "A LIE." } },
     });
 
@@ -837,7 +852,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // read as a failed run and answer by deleting the transcript. So the wait
     // may not be inside the loop, and this is what pins that: twenty turns, ONE
     // `waitFor`, and every other wait a plain sleep.
-    const ctx = createWorkflowCtx({ hooks: { [NUDGE]: {} } });
+    const ctx = createWorkflowContext({ hooks: { [NUDGE]: {} } });
     stubSlowJob(20);
 
     await awaitTranscript("t_1", ctx, NUDGE);
@@ -856,7 +871,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
       { status: "processing" },
       { status: "completed", text: "Done.", audio_duration: 60 },
     ]);
-    const ctx = createWorkflowCtx();
+    const ctx = createWorkflowContext();
 
     const state = await awaitTranscript("t_1", ctx, NUDGE);
 
@@ -872,7 +887,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // window — so whichever arm a run is on, a caller hears the sentence at the
     // same point. The note goes out at the TOP of a poll, so attempt 2 is the
     // first turn with a whole closed window behind it.
-    const ctx = createWorkflowCtx();
+    const ctx = createWorkflowContext();
     stubSlowJob(20);
 
     await awaitTranscript("t_1", ctx, NUDGE);
@@ -891,7 +906,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // The mirror of the case above, and what stops the note being a thing every
     // callback run says: the delivery lands, attempt 2 finds the job done, and
     // nobody is told a recording is a long one.
-    const ctx = createWorkflowCtx({ hooks: { [NUDGE]: {} } });
+    const ctx = createWorkflowContext({ hooks: { [NUDGE]: {} } });
     stubSlowJob(1);
 
     await awaitTranscript("t_1", ctx, NUDGE);
@@ -917,7 +932,9 @@ describe("askWhetherToKeep — the expense port", () => {
    * What is pinned is unchanged: the three outcomes and the safe default.
    */
   const gateCtx = (answer?: { keep: boolean }) =>
-    createWorkflowCtx(answer === undefined ? {} : { hooks: { [retentionToken("s_1")]: answer } });
+    createWorkflowContext(
+      answer === undefined ? {} : { hooks: { [retentionToken("s_1")]: answer } },
+    );
 
   test("keeps the transcript when the caller says to, and deletes nothing", async () => {
     const provider = installStubStepFetch();
@@ -989,7 +1006,7 @@ describe("compensate — the saga port", () => {
         { label: "first", undo: async () => void order.push("first") },
       ],
       "because",
-      createWorkflowCtx(),
+      createWorkflowContext(),
     );
     expect(order).toEqual(["second", "first"]);
   });
@@ -1011,7 +1028,7 @@ describe("compensate — the saga port", () => {
           { label: "fine", undo: async () => void order.push("fine") },
         ],
         "because",
-        createWorkflowCtx(),
+        createWorkflowContext(),
       ),
     ).resolves.toBeUndefined();
     expect(order).toEqual(["fine"]);
@@ -1022,7 +1039,7 @@ describe("compensate — the saga port", () => {
     // run that narrated an unwind it did not perform would be lying to the
     // caller reading its progress.
     await expect(
-      compensate([], "nothing was acquired", createWorkflowCtx()),
+      compensate([], "nothing was acquired", createWorkflowContext()),
     ).resolves.toBeUndefined();
   });
 });