@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/templates/transcription-workflow/run-panel.tsx

@@ -21,6 +21,7 @@
 import { countWords, formatDuration, plural } from "@alexkroman1/aai/utils";
 import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
+  Facts,
   isTerminal,
   useWorkflowProgress,
   WORKFLOW_STATUS_LABELS,
@@ -136,7 +137,7 @@ export function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onCle
           above, and the reason both exist: the status is `running` for the whole
           fan-out, so a sixty-segment recording and a one-segment recording look
           identical while they run. These lines come from the run itself
-          (`report()` in `workflows/transcribe.ts`), and they REPLAY, so looking a
+          (`stepReport()` in `workflows/transcribe.ts`), and they REPLAY, so looking a
           finished run up in the panel below shows how it got there. */}
       <WorkflowProgress runId={run.runId} />
 
@@ -150,15 +151,25 @@ export function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onCle
           object with optional fields. */}
       {run.status === "completed" && (
         <>
-          <p className="text-xs opacity-60">
-            {run.output.segments} {plural(run.output.segments, "segment")} ·{" "}
-            {formatDuration(run.output.durationMs)} of audio · took{" "}
-            {formatDuration(run.output.elapsedMs)} · {run.output.words} words
-          </p>
+          <Facts
+            size="xs"
+            items={[
+              `${run.output.segments} ${plural(run.output.segments, "segment")}`,
+              `${formatDuration(run.output.durationMs)} of audio`,
+              `took ${formatDuration(run.output.elapsedMs)}`,
+              `${run.output.words} words`,
+            ]}
+          />
           <pre className="whitespace-pre-wrap text-sm leading-relaxed">{run.output.transcript}</pre>
         </>
       )}
-      {run.status === "failed" && <p className="text-red-600">{run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error in
+          `client.tsx`: this is the outcome the reader waited minutes for. */}
+      {run.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          {run.error}
+        </p>
+      )}
     </section>
   );
 }
@@ -186,17 +197,26 @@ function LiveTranscript({ runId }: { runId: string }) {
   // Memoized on the ARRAY, which the hook appends to per read: stitching is a
   // seam search per segment, and a fan-out re-renders this panel on every
   // progress poll whether or not anything arrived.
-  const transcript = useMemo(() => stitchChunks(progress), [progress]);
+  //
+  // The word count and the coverage are derived in the SAME memo, not below
+  // it: both are functions of `progress` alone, and `countWords` rescans a
+  // transcript that reaches ~14k words on a feature-length recording.
+  //
+  // `covered` is the furthest point reached, not the count: segments land out
+  // of order, so "6 segments" says nothing about how much is covered.
+  const { transcript, words, covered } = useMemo(() => {
+    const stitched = stitchChunks(progress);
+    return {
+      transcript: stitched,
+      words: countWords(stitched),
+      covered: progress.reduce((furthest, chunk) => Math.max(furthest, chunk.endMs), 0),
+    };
+  }, [progress]);
   if (progress.length === 0) return null;
 
-  // The furthest point reached, not the count: segments land out of order, so
-  // "6 segments" says nothing about how much of the recording is covered.
-  const covered = Math.max(...progress.map((chunk) => chunk.endMs));
   return (
     <div className="flex flex-col gap-2">
-      <p className="text-xs opacity-60">
-        {countWords(transcript)} words so far · through {formatDuration(covered)}
-      </p>
+      <Facts size="xs" items={[`${words} words so far`, `through ${formatDuration(covered)}`]} />
       <pre className="whitespace-pre-wrap text-sm leading-relaxed opacity-80">{transcript}</pre>
     </div>
   );

package/dist/templates/transcription-workflow/total-latency.tsx

@@ -15,6 +15,7 @@
  */
 
 import { formatDuration } from "@alexkroman1/aai/utils";
+import { Facts } from "@alexkroman1/aai-ui";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 /**
@@ -29,12 +30,17 @@ const STOPWATCH_TICK_MS = 250;
 /** What {@link useTotalLatency} reports. */
 export type TotalLatency = {
   /**
-   * Milliseconds since the submit — ticking while the submission is in flight,
-   * frozen at the finish, and undefined before the first one.
+   * The mark the clock started at, or undefined before the first submit.
+   *
+   * The raw mark rather than an elapsed duration, and that is the load-bearing
+   * part: an elapsed number is stale the instant it is computed, so a page
+   * holding one has to re-render to keep it true — which is what used to drive
+   * the whole tree at 4 Hz. {@link TotalLatency} turns these two marks into a
+   * duration, and only that section re-renders.
    */
-  elapsedMs: number | undefined;
-  /** Whether the clock is still running, which is what makes the label honest. */
-  running: boolean;
+  startedAt: number | undefined;
+  /** The elapsed time at the moment the run settled, once it has. */
+  frozenMs: number | undefined;
   /** Start (or restart) the clock. Called from the form's own submit handler. */
   start: () => void;
   /** Drop it, for a panel that no longer describes the submission it timed. */
@@ -53,7 +59,10 @@ export type TotalLatency = {
  *
  * - **The interval re-renders; it does not accumulate.** The elapsed time is read
  *   from the clock at render, so a tick the tab throttled or dropped cannot make
- *   the number lag behind real time.
+ *   the number lag behind real time. The interval lives in {@link TotalLatency}
+ *   rather than here, because a hook called from the page makes its ticks the
+ *   PAGE's re-renders — the form, the upload bar, the run panel and the whole
+ *   history list, four times a second, to move one duration string.
  * - **`performance.now()`, not `Date.now()`.** It is monotonic, so a clock
  *   correction (NTP, a laptop waking up) cannot make a transcription look
  *   instant — or negative.
@@ -61,8 +70,6 @@ export type TotalLatency = {
 export function useTotalLatency(inFlight: boolean): TotalLatency {
   const [startedAt, setStartedAt] = useState<number | undefined>(undefined);
   const [frozenMs, setFrozenMs] = useState<number | undefined>(undefined);
-  // Re-render trigger only — see the doc above.
-  const [, tick] = useState(0);
   // Whether `inFlight` has been seen true since the last `start()`. Without it,
   // a start that lands one render before the submission reports itself in flight
   // would freeze the clock at zero instead of running it.
@@ -72,8 +79,7 @@ export function useTotalLatency(inFlight: boolean): TotalLatency {
     if (startedAt === undefined || frozenMs !== undefined) return;
     if (inFlight) {
       began.current = true;
-      const id = setInterval(() => tick((n) => n + 1), STOPWATCH_TICK_MS);
-      return () => clearInterval(id);
+      return;
     }
     // Measured here rather than at render, so the frozen number is the one at the
     // moment the run settled rather than whenever this page next drew.
@@ -93,8 +99,8 @@ export function useTotalLatency(inFlight: boolean): TotalLatency {
   }, []);
 
   return {
-    elapsedMs: frozenMs ?? (startedAt === undefined ? undefined : performance.now() - startedAt),
-    running: startedAt !== undefined && frozenMs === undefined,
+    startedAt,
+    frozenMs,
     start,
     clear,
   };
@@ -114,17 +120,31 @@ export function useTotalLatency(inFlight: boolean): TotalLatency {
  * notices it finished. Clamped at zero, because the two numbers come from two
  * different clocks on two different machines and a few milliseconds the wrong way
  * would otherwise print a negative.
+ *
+ * The stopwatch interval lives HERE rather than in {@link useTotalLatency}, so a
+ * running clock re-renders this section and nothing else.
  */
 export function TotalLatency({
-  elapsedMs,
-  running,
+  startedAt,
+  frozenMs,
   runMs,
 }: {
-  elapsedMs: number | undefined;
-  running: boolean;
+  startedAt: number | undefined;
+  frozenMs: number | undefined;
   runMs: number | undefined;
 }) {
-  if (elapsedMs === undefined) return null;
+  // Re-render trigger only: the elapsed time is read from the clock below, so a
+  // tick the tab throttled or dropped cannot make the number lag real time.
+  const [, tick] = useState(0);
+  const running = startedAt !== undefined && frozenMs === undefined;
+  useEffect(() => {
+    if (!running) return;
+    const id = setInterval(() => tick((n) => n + 1), STOPWATCH_TICK_MS);
+    return () => clearInterval(id);
+  }, [running]);
+
+  if (startedAt === undefined) return null;
+  const elapsedMs = frozenMs ?? performance.now() - startedAt;
   const outside = runMs === undefined ? undefined : Math.max(0, elapsedMs - runMs);
   return (
     <section className="flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1 rounded-md border px-5 py-3">
@@ -134,9 +154,15 @@ export function TotalLatency({
       <span className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
         <span className="text-sm tabular-nums">{formatDuration(elapsedMs)}</span>
         {runMs !== undefined && outside !== undefined && (
-          <span className="text-xs tabular-nums opacity-60">
-            {formatDuration(outside)} before the run · {formatDuration(runMs)} inside it
-          </span>
+          <Facts
+            size="xs"
+            as="span"
+            className="tabular-nums"
+            items={[
+              `${formatDuration(outside)} before the run`,
+              `${formatDuration(runMs)} inside it`,
+            ]}
+          />
         )}
       </span>
     </section>

package/dist/templates/transcription-workflow/workflows/batch.ts

@@ -53,12 +53,12 @@
  * request rather than two and the value journaled by the last poll IS the result.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { report, TRANSCRIBE_API, uploadInfo } from "@alexkroman1/aai/step";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { stepReport, stepUploadInfo, TRANSCRIBE_API } from "@alexkroman1/aai/step";
 import {
-  stepTranscribePollClassified,
-  stepTranscribeSubmitClassified,
-  stepTranscribeUploadClassified,
+  stepTranscribePollOrFail,
+  stepTranscribeSubmitOrFail,
+  stepTranscribeUploadOrFail,
 } from "@alexkroman1/aai/step-errors";
 import { countWords, formatBytes } from "@alexkroman1/aai/utils";
 import type { Transcript } from "./transcribe.ts";
@@ -78,7 +78,7 @@ const MAX_POLLS = 360;
 /** Transcribe a recording through the async API. */
 export async function transcribeBatchFlow(
   input: { recording: string },
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<Transcript> {
   // Both at once: the clock does not depend on the upload, and issuing them
   // together costs one round trip instead of two before a byte moves. Their issue
@@ -122,24 +122,24 @@ export async function transcribeBatchFlow(
  * far smaller: if it expires before the next step runs, the run fails and a fresh one
  * re-uploads — which is what would have happened anyway, once, instead of five times.
  *
- * The `Classified` callers on `@alexkroman1/aai/step-errors` are the SDK's own
+ * The `OrFail` callers on `@alexkroman1/aai/step-errors` are the SDK's own
  * `stepTranscribe*` plus `throwStepError` and nothing else, which is what turns the
  * SDK's `TranscribeError` into the DevKit's verdict: a missing key and a 400 stop, a
  * 429 waits as long as the service asked. Every step here ends the same way for the
  * same reason.
  */
 export async function uploadToProvider(uploadId: string): Promise<{ audioUrl: string }> {
-  const stored = await uploadInfo(uploadId);
-  await report(
+  const stored = await stepUploadInfo(uploadId);
+  await stepReport(
     `Uploading ${stored.name || uploadId} (${formatBytes(stored.size)}) to the async API.`,
   );
-  return await stepTranscribeUploadClassified(uploadId);
+  return await stepTranscribeUploadOrFail(uploadId);
 }
 
 /** Create the transcription job, and answer with the id that outlives this run. */
 export async function createJob(audioUrl: string): Promise<{ id: string }> {
-  const job = await stepTranscribeSubmitClassified(audioUrl);
-  await report(`Submitted — job ${job.id}.`);
+  const job = await stepTranscribeSubmitOrFail(audioUrl);
+  await stepReport(`Submitted — job ${job.id}.`);
   return job;
 }
 
@@ -156,13 +156,13 @@ export async function pollTranscript(
   id: string,
   startedAt: number,
 ): Promise<{ done: false } | { done: true; transcript: Transcript }> {
-  const progress = await stepTranscribePollClassified(id);
+  const progress = await stepTranscribePollOrFail(id);
   if (!progress.done) {
-    await report(`Transcript ${id} is ${progress.status}.`);
+    await stepReport(`Transcript ${id} is ${progress.status}.`);
     return { done: false };
   }
 
-  const stored = await uploadInfo(uploadId);
+  const stored = await stepUploadInfo(uploadId);
   const transcript = progress.transcript.text;
   return {
     done: true,

package/dist/templates/transcription-workflow/workflows/downsample.ts

@@ -152,7 +152,7 @@ export function downsampleSegment(
   const bind = sampleReaderFor(from);
   const frame = blockAlign(from);
   const inFrames = Math.floor(bytes.length / frame);
-  // A CALLER ERROR, and stated as one. `readUpload` clamps a window to what is
+  // A CALLER ERROR, and stated as one. `stepReadUpload` clamps a window to what is
   // stored, so the streaming flow can hand a short read down here; with no whole
   // frame the averaging window below is zero wide, `total / 0` is `NaN`, and
   // `setInt16` writes that as a 0 — a two-byte WAV of silence, transcribed and

package/dist/templates/transcription-workflow/workflows/normalize.ts

@@ -70,8 +70,8 @@
  */
 
 import { basename, extname, join } from "node:path";
-import { probeMedia, runFfmpeg, wavEncodeArgs } from "@alexkroman1/aai/ffmpeg";
-import { readUpload, report, requireCompleteUpload } from "@alexkroman1/aai/step";
+import { ffmpegBaseArgs, probeMedia, runFfmpeg, wavEncodeArgs } from "@alexkroman1/aai/ffmpeg";
+import { stepReadUpload, stepReport, stepRequireCompleteUpload } from "@alexkroman1/aai/step";
 import { throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
 import { readUploadToFile, withTempDir, writeUploadFromFile } from "@alexkroman1/aai/step-files";
 import { formatBytes, formatDuration } from "@alexkroman1/aai/utils";
@@ -122,16 +122,16 @@ export type NormalizedRecording = {
  * file that already exists instead of paying for a second one.
  */
 export async function normalizeRecording(uploadId: string): Promise<NormalizedRecording> {
-  // `requireCompleteUpload`, not `uploadInfo`: `size` is the readable PREFIX, and
+  // `stepRequireCompleteUpload`, not `stepUploadInfo`: `size` is the readable PREFIX, and
   // every judgement below — cuttable, heavier-per-second, the byte count copied to
   // disk — is about the WHOLE file.
-  const stored = await requireCompleteUpload(uploadId);
-  const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
+  const stored = await stepRequireCompleteUpload(uploadId);
+  const head = await stepReadUpload(uploadId, { end: HEADER_PROBE_BYTES });
 
   if (cuttable(head.bytes, stored.size) && !heavierThanNormalized(head.bytes, stored.size)) {
     // No subprocess, no copy, no second upload. The overwhelmingly common case
     // for a desk whose form says WAV, and the reason the check is a 64 KB read.
-    await report(`${stored.name || uploadId} is already linear-PCM WAV — cutting it as it is.`);
+    await stepReport(`${stored.name || uploadId} is already linear-PCM WAV — cutting it as it is.`);
     return { recording: uploadId, converted: false };
   }
 
@@ -144,7 +144,7 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
   // WAV that is fine but too heavy to cut at this rate. Reporting "not a WAV we
   // can cut" for the second one is a line that contradicts the file they
   // uploaded.
-  await report(
+  await stepReport(
     `Converting ${stored.name || uploadId} (${formatBytes(stored.size)}) — ` +
       (cuttable(head.bytes, stored.size)
         ? `heavier per second than ${NORMALIZED_SAMPLE_RATE / 1000} kHz mono.`
@@ -164,7 +164,7 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
       // `STEP_FILE_READ_CONCURRENCY` of them. Passing `size` means "I am judging
       // completeness myself", which is what a body polling a still-arriving
       // upload needs and is the opposite of what happened above: this step has
-      // already called `requireCompleteUpload`, so the file IS whole and the
+      // already called `stepRequireCompleteUpload`, so the file IS whole and the
       // windows may land in any order. Omitting it lets `readUploadToFile`
       // establish that for itself and fan out. The cost is one metadata round
       // trip, against the dozens of window reads it overlaps.
@@ -177,22 +177,18 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
       const info = await probeMedia(source, { timeoutMs: CONVERT_TIMEOUT_MS }).catch(
         throwFfmpegStepError,
       );
-      await report(
+      await stepReport(
         `It is ${describeSource(info.audio?.codec, info.durationSec)} — re-encoding to ` +
           `${NORMALIZED_SAMPLE_RATE / 1000} kHz mono WAV.`,
       );
 
       await runFfmpeg(
         [
-          // The argv is the caller's, verbatim — `runFfmpeg` adds nothing. So the
-          // standing flags are here: quiet, non-interactive, overwrite. `-nostdin`
-          // matters most in a guest, where there is no terminal and an ffmpeg that
-          // decides to read stdin is a process that never exits.
-          "-hide_banner",
-          "-loglevel",
-          "error",
-          "-nostdin",
-          "-y",
+          // The argv is the caller's, verbatim — `runFfmpeg` adds nothing — so
+          // the standing flags are the caller's too. This copy used to omit
+          // `-nostats`, which is the one that keeps ffmpeg's progress spam from
+          // evicting the error out of the captured stderr tail.
+          ...ffmpegBaseArgs(),
           "-i",
           source,
           ...wavEncodeArgs({
@@ -212,7 +208,7 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
         type: "audio/wav",
       });
 
-      await report(
+      await stepReport(
         `Converted to ${formatBytes(written.size)} of WAV (from ${formatBytes(stored.size)}).`,
       );
       return { recording: written.id, converted: true };

package/dist/templates/transcription-workflow/workflows/stream.ts

@@ -22,7 +22,7 @@
  * first byte with `complete: false` and its `size` grows as bytes land.
  *
  * The reader needed almost nothing for this, which is why this flow is so close to
- * the other one: `readUpload` already clamped its window to what is stored (so a
+ * the other one: `stepReadUpload` already clamped its window to what is stored (so a
  * plan computed from a header could end one byte past the file), and that clamp is
  * exactly "read what has arrived". So `transcribeSegment` below is `transcribe.ts`'s
  * OWN step, unchanged, called on windows this body has checked are present.
@@ -50,7 +50,7 @@
  *   0.9 MB/s: `size` was 0 at every poll for 45 seconds and then the whole file, so
  *   the run planned nothing, transcribed nothing, and did its entire fan-out after
  *   the upload — the classic flow, with extra steps. `segmentStored` reads `ranges`
- *   instead, and `readUpload` clamps to the run a read starts in rather than to the
+ *   instead, and `stepReadUpload` clamps to the run a read starts in rather than to the
  *   prefix, so a window that has landed is a window this flow can work on.
  * - **The stall test on the prefix would then FAIL a healthy upload.** A parts
  *   upload moving at full speed reports the same prefix at every poll, which is
@@ -167,13 +167,13 @@
  * what keeps that order a pure function of journaled values.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 import {
   mapConcurrent,
-  readUpload,
-  report,
+  stepReadUpload,
+  stepReport,
+  stepUploadInfo,
   type UploadRange,
-  uploadInfo,
 } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
 import { formatDuration, omitUndefined, plural } from "@alexkroman1/aai/utils";
@@ -308,7 +308,7 @@ export type StreamPlan = {
  * an upload id exactly as in the classic flow; what differs is that the client chose
  * it and the bytes are still on their way.
  */
-export async function transcribeStreamFlow(input: { recording: string }, ctx: WorkflowCtx) {
+export async function transcribeStreamFlow(input: { recording: string }, ctx: WorkflowContext) {
   // `ctx.now()`, not a step: the engine journals the read under its own key, so
   // every walk of this line sees the instant the first one did.
   const startedAt = await ctx.now();
@@ -364,7 +364,7 @@ export async function transcribeStreamFlow(input: { recording: string }, ctx: Wo
       // A segment is READY when its whole window is stored — except once the upload
       // is complete, where `at.size` is the true total and the plan came from the
       // header's DECLARED length: a recording that came up short leaves a final
-      // segment ending past the file, and `readUpload` clamping is what makes that
+      // segment ending past the file, and `stepReadUpload` clamping is what makes that
       // the right answer rather than an error.
       const ready = plan.segments.filter(
         (segment) =>
@@ -443,7 +443,7 @@ export async function transcribeStreamFlow(input: { recording: string }, ctx: Wo
  * from.
  */
 export async function probeUpload(id: string): Promise<UploadProgressView> {
-  const info = await uploadInfo(id);
+  const info = await stepUploadInfo(id);
   return {
     size: info.size,
     complete: info.complete,
@@ -609,7 +609,7 @@ export function storedBytes(size: number, ranges: readonly UploadRange[] | undef
  * only the prefix and the run has nothing to do until the upload is over, which
  * is the entire wait this flow exists to remove.
  *
- * A window has to be covered WHOLE by one run: `readUpload` clamps to the run a
+ * A window has to be covered WHOLE by one run: `stepReadUpload` clamps to the run a
  * read starts in, so a segment straddling a hole would come back short and be
  * transcribed as a fragment. `rangesOf` merges adjacent windows, so a run really
  * is a contiguous stretch and one containment test is the whole check.
@@ -636,7 +636,7 @@ export function segmentStored(segment: Segment, at: UploadProgressView): boolean
  * which is what the classic flow is for.
  */
 export async function planStreamed(id: string): Promise<StreamPlan> {
-  const head = await readUpload(id, { end: HEADER_PROBE_BYTES });
+  const head = await stepReadUpload(id, { end: HEADER_PROBE_BYTES });
   const format = fatalOnUnsupported(() => parseWav(head.bytes, Number.POSITIVE_INFINITY));
   if (!Number.isFinite(format.dataEnd)) {
     return throwFatalStepError(
@@ -647,7 +647,7 @@ export async function planStreamed(id: string): Promise<StreamPlan> {
     );
   }
   const segments = fatalOnUnsupported(() => planSegments(format));
-  await report(
+  await stepReport(
     `Planned ${formatDuration(segments.at(-1)?.endMs ?? 0)} of audio as ` +
       `${segments.length} ${plural(segments.length, "segment")} while it uploads.`,
   );

package/dist/templates/transcription-workflow/workflows/sync-api.ts

@@ -18,7 +18,7 @@
  * the same shape). It is called FROM steps, so it inherits their environment.
  */
 
-import { stepTranscribeSyncClassified } from "@alexkroman1/aai/step-errors";
+import { stepTranscribeSyncOrFail } from "@alexkroman1/aai/step-errors";
 
 /**
  * Time one transcription, so the progress log carries LATENCY.
@@ -57,7 +57,7 @@ export function elapsed(ms: number): string {
  * concatenated straight into the request body rather than into an intermediate
  * buffer that doubles the segment's footprint.
  *
- * `stepTranscribeSyncClassified` — the SDK's own `stepTranscribeSync` plus
+ * `stepTranscribeSyncOrFail` — the SDK's own `stepTranscribeSync` plus
  * `throwStepError`, and nothing else — is the whole of what this adds to the SDK
  * call, and it is where the three-way call is made: a `FatalError` stops the DevKit retrying
  * something that will answer the same way, a bare `RetryableError` retries in ONE
@@ -75,6 +75,6 @@ export async function transcribeWav(
   filename: string,
   label: string,
 ): Promise<string> {
-  const { text } = await stepTranscribeSyncClassified(bytes, { filename, label });
+  const { text } = await stepTranscribeSyncOrFail(bytes, { filename, label });
   return text;
 }

package/dist/templates/transcription-workflow/workflows/transcribe.ts

@@ -48,7 +48,7 @@
  * - **The audio is addressed by BYTE RANGE, never carried.** A workflow's input
  *   is journaled and replayed on every resume, so the recording lives in the
  *   app's own upload store and the run carries only its id; each step reads
- *   exactly its own window with `readUpload`. Sixty steps therefore move the
+ *   exactly its own window with `stepReadUpload`. Sixty steps therefore move the
  *   recording once between them, not sixty times.
  * - **The fan-out is bounded by `mapConcurrent`, and the bound is not a detail.**
  *   The DevKit correlates a journal entry to a step call by the ORDER the call
@@ -57,20 +57,20 @@
  *   calls settle. Its module doc carries the argument; what matters here is that
  *   there is no barrier, so a slow segment costs only itself.
  * - **The transcript STREAMS as it is produced.** Each segment is emitted the
- *   moment it lands (`emit(TRANSCRIPT_STREAM, …)`), so the page renders the
+ *   moment it lands (`stepEmit(TRANSCRIPT_STREAM, …)`), so the page renders the
  *   answer growing rather than a status line and then everything at once. That is
  *   the difference a fan-out can make to a reader and a run output cannot: an
  *   `output` exists only when the last segment does.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 import {
-  emit,
   mapConcurrent,
-  readUpload,
-  report,
-  requireCompleteUpload,
-  uploadInfo,
+  stepEmit,
+  stepReadUpload,
+  stepReport,
+  stepRequireCompleteUpload,
+  stepUploadInfo,
   wavHeader,
 } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
@@ -248,7 +248,7 @@ export type SegmentTranscript = {
  * The input is what `POST /workflows/runs` carries — see `agent.ts` for the
  * schema it is validated against before a run exists.
  */
-export async function transcribeFlow(input: { recording: string }, ctx: WorkflowCtx) {
+export async function transcribeFlow(input: { recording: string }, ctx: WorkflowContext) {
   // Both at once: neither needs the other, and issued together they are one
   // round trip instead of two before any audio is read. The ORDER is still a
   // pure function of this line — the two calls go out synchronously, left to
@@ -313,13 +313,13 @@ export async function splitRecording(uploadId: string): Promise<{
   // half-arrived recording this planned a fan-out over the first half and the run
   // returned a transcript of it, reporting success. `stream.ts` is the flow for a
   // recording that is still landing; this one wants all of it.
-  const stored = await requireCompleteUpload(uploadId);
-  const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
+  const stored = await stepRequireCompleteUpload(uploadId);
+  const head = await stepReadUpload(uploadId, { end: HEADER_PROBE_BYTES });
   const format = fatalOnUnsupported(() => parseWav(head.bytes, stored.size));
   const segments = fatalOnUnsupported(() => planSegments(format));
   const durationMs = segments.at(-1)?.endMs ?? 0;
 
-  await report(
+  await stepReport(
     `Split ${formatDuration(durationMs)} of audio into ${segments.length} ${plural(segments.length, "segment")}.`,
   );
   return { format, segments, durationMs };
@@ -345,12 +345,14 @@ export async function transcribeSegment(
   // calls together, so their lines interleave by completion — the page renders a
   // log, not a sequence, and `segment.index` is what puts the TRANSCRIPT back in
   // order.
-  await report(`Transcribing ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`);
+  await stepReport(
+    `Transcribing ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`,
+  );
 
   // `[start, end)`, the same half-open pair `planSegments` produced — the store
   // owns the conversion to HTTP's inclusive range, so there is no `- 1` here to
   // get wrong.
-  const audio = await readUpload(uploadId, { start: segment.start, end: segment.end });
+  const audio = await stepReadUpload(uploadId, { start: segment.start, end: segment.end });
 
   // The audio and nothing else. A `config` part carrying `language_code` used
   // to ride along, and it is gone with the picker that fed it: the model detects
@@ -401,15 +403,15 @@ export async function transcribeSegment(
   );
   // The LATENCY, which is what says whether the concurrency bound or the endpoint
   // is the thing limiting the run — see `timed`'s doc.
-  await report(
+  await stepReport(
     `Transcribed ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)} in ${elapsed(ms)}.`,
   );
   // And the WORDS, into their own stream, which is what makes this run's answer
   // streamable rather than only its narration: the page stitches whatever has
   // arrived and renders the transcript growing, minutes before `output` exists.
-  // Its own namespace because `report`'s stream carries sentences a page prints
-  // verbatim — see `emit`'s doc.
-  await emit(TRANSCRIPT_STREAM, {
+  // Its own namespace because `stepReport`'s stream carries sentences a page prints
+  // verbatim — see `stepEmit`'s doc.
+  await stepEmit(TRANSCRIPT_STREAM, {
     index: segment.index,
     startMs: segment.startMs,
     endMs: segment.endMs,
@@ -422,7 +424,7 @@ export async function transcribeSegment(
  * Stitch the segments into one transcript.
  *
  * A step rather than a pure call in the body, and the reason is the narration:
- * the body replays from the top on every resume, so a `report()` written there
+ * the body replays from the top on every resume, so a `stepReport()` written there
  * is re-emitted on each one. Journaling the finished transcript also means a
  * caller re-reading a completed run gets the same bytes rather than a value
  * recomputed from parts.
@@ -433,7 +435,7 @@ export async function mergeTranscript(
   parts: readonly SegmentTranscript[],
   startedAt: number,
 ): Promise<Transcript> {
-  await report(`Stitching ${parts.length} ${plural(parts.length, "segment")} together.`);
+  await stepReport(`Stitching ${parts.length} ${plural(parts.length, "segment")} together.`);
 
   // `mapConcurrent` resolves in ITEM order however the calls settled, so this is
   // already ordered — sorted anyway, because the merge is where an ordering
@@ -443,7 +445,7 @@ export async function mergeTranscript(
 
   // The FILENAME, not the id: the page prints this, and `upl_9f3…` tells a
   // reader nothing about which recording they are looking at.
-  const source = (await uploadInfo(uploadId)).name || uploadId;
+  const source = (await stepUploadInfo(uploadId)).name || uploadId;
   return {
     source,
     segments: parts.length,
@@ -457,19 +459,6 @@ export async function mergeTranscript(
   };
 }
 
-// Re-exported rather than re-declared: `stream.ts` and `batch.ts` already import
-// these from this module, and the split that let the PAGE stitch a partial
-// transcript should not ripple through every flow. `clock` and `countWords` used
-// to be in this list and are `formatDuration`/`countWords` on
-// `@alexkroman1/aai/utils` now — a run narrates itself and the page renders the
-// same run, so those two were a private copy of a formatter the SDK ships.
-export {
-  stitchChunks,
-  stitchTranscript,
-  TRANSCRIPT_STREAM,
-  type TranscriptChunk,
-} from "./stitch.ts";
-
 // ---- I/O helpers ------------------------------------------------------------
 
 /**