@alexkroman1/aai-cli 6.11.0 → 7.0.0

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

@@ -26,7 +26,7 @@
  * ## The endpoint is the SDK's; the STEPS are ours
  *
  * `stepTranscribeUpload` / `stepTranscribeSubmit` / `stepTranscribePoll` on
- * `@alexkroman1/aai/utils` own the URL, the raw-key auth, the windowed streaming
+ * `@alexkroman1/aai/step` own the URL, the raw-key auth, the windowed streaming
  * upload, the PLURAL `speech_models` field and the failure classification. This file
  * used to spell all of that out, and so did `spoken-summary` — the same ~200 lines
  * twice, reworded, identical in behaviour, and drifting apart at the edges.
@@ -54,17 +54,15 @@
  * request rather than two and the value journaled by the last poll IS the result.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
+import { report, TRANSCRIBE_API, uploadInfo } from "@alexkroman1/aai/step";
 import {
-  report,
-  stepTranscribePoll,
-  stepTranscribeSubmit,
-  stepTranscribeUpload,
-  TRANSCRIBE_API,
-  uploadInfo,
-} from "@alexkroman1/aai/utils";
+  stepTranscribePollClassified,
+  stepTranscribeSubmitClassified,
+  stepTranscribeUploadClassified,
+} from "@alexkroman1/aai/step-errors";
+import { countWords, formatBytes } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
-import { countWords, startClock, type Transcript } from "./transcribe.ts";
+import { startClock, type Transcript } from "./transcribe.ts";
 
 /** How long between polls of a submitted job. */
 const POLL_INTERVAL = "10s";
@@ -118,16 +116,20 @@ export async function transcribeBatchFlow(input: { recording: string }): Promise
  * 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.
  *
- * `.catch(throwStepError)` 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.
+ * The `Classified` 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 }> {
   "use step";
 
   const stored = await uploadInfo(uploadId);
-  await report(`Uploading ${stored.name || uploadId} (${mb(stored.size)}) to the async API.`);
-  return await stepTranscribeUpload(uploadId).catch(throwStepError);
+  await report(
+    `Uploading ${stored.name || uploadId} (${formatBytes(stored.size)}) to the async API.`,
+  );
+  return await stepTranscribeUploadClassified(uploadId);
 }
 
 /** Retries beyond the default 3: an upload is the one call here worth another attempt. */
@@ -137,7 +139,7 @@ uploadToProvider.maxRetries = 5;
 export async function createJob(audioUrl: string): Promise<{ id: string }> {
   "use step";
 
-  const job = await stepTranscribeSubmit(audioUrl).catch(throwStepError);
+  const job = await stepTranscribeSubmitClassified(audioUrl);
   await report(`Submitted — job ${job.id}.`);
   return job;
 }
@@ -157,7 +159,7 @@ export async function pollTranscript(
 ): Promise<{ done: false } | { done: true; transcript: Transcript }> {
   "use step";
 
-  const progress = await stepTranscribePoll(id).catch(throwStepError);
+  const progress = await stepTranscribePollClassified(id);
   if (!progress.done) {
     await report(`Transcript ${id} is ${progress.status}.`);
     return { done: false };
@@ -185,8 +187,3 @@ export async function pollTranscript(
     },
   };
 }
-
-/** A size a person can read, because the number that matters is the scale. */
-function mb(bytes: number): string {
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}

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

@@ -39,39 +39,33 @@
  *
  * ## File → file, not bytes → bytes
  *
- * `transcodeToWav(bytes)` is one line and is the wrong call here, twice over:
- *
- * - **The output would be buffered.** Piped stdout is capped
- *   (`DEFAULT_MAX_FFMPEG_OUTPUT_BYTES`, 64 MiB), which is about an hour of
- *   16 kHz mono — and this desk exists for the two-hour recording.
- * - **The input could not be READ.** A pipe cannot seek, and an `.m4a` written
- *   by a phone usually carries its `moov` index at the END of the file, so
- *   ffmpeg fails on the flagship input with `moov atom not found`. That is the
- *   one caveat `@alexkroman1/aai/ffmpeg`'s own doc names, and this is the case
- *   it names it for.
- *
- * So the recording is materialized to a temp file in windows, converted file to
- * file, and streamed back into the upload store. Nothing here holds a whole
- * recording in memory at any point, which is the property that makes the step
- * work on the input it was written for.
- *
- * ## A temp file cannot cross a step boundary
- *
- * Everything above happens in ONE step, and that is structural rather than
- * tidy. A step is journaled by its RETURN VALUE and may be dispatched into a
- * different process than its neighbours, so a path in a return value is a path
- * that is replayed after the file behind it is gone. What crosses the boundary
- * is an upload ID; the temp directory is created and removed inside the step
- * that uses it.
+ * `transcodeToWav(bytes)` is one line and is the wrong call here, and
+ * `@alexkroman1/aai/step-files` is the three functions that replace it —
+ * `readUploadToFile`, `withTempDir` and `writeUploadFromFile`. Its module doc
+ * carries the whole argument (a pipe cannot seek, so an `.m4a` with a trailing
+ * `moov` index fails; piped output is capped at 64 MiB, half an hour of this
+ * desk's audio) plus the rule that a temp file may not outlive its step. This
+ * step is the case those were written for.
+ *
+ * ## Everything node-shaped is named from inside the step BODY
+ *
+ * `@alexkroman1/aai/ffmpeg` and `@alexkroman1/aai/step-files` both reach a
+ * `node:` builtin, and a name this module holds at MODULE scope keeps its import
+ * in the workflow bundle — which is compiled as a `node:vm` Script with no
+ * `require`. Every name they bind is referenced only inside
+ * {@link normalizeRecording}'s body, which the workflow transform removes along
+ * with the imports it is the only user of. A module-scope FUNCTION naming one is
+ * what breaks a run at replay; this template used to carry a whole
+ * `ffmpeg-verdict.ts` because of it, and `throwFfmpegStepError` — which reaches
+ * no `node:` builtin at all — is what dissolved the boundary.
  */
 
-import { mkdtemp, open, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import { basename, extname, join } from "node:path";
-import { isFfmpegError, probeMedia, runFfmpeg, wavEncodeArgs } from "@alexkroman1/aai/ffmpeg";
-import { throwFatalStepError, throwStepError } from "@alexkroman1/aai/step-errors";
-import { readUpload, report, uploadInfo, writeUpload } from "@alexkroman1/aai/utils";
-import { clock } from "./stitch.ts";
+import { probeMedia, runFfmpeg, wavEncodeArgs } from "@alexkroman1/aai/ffmpeg";
+import { readUpload, report, uploadInfo } 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";
 import { HEADER_PROBE_BYTES, parseWav, UnsupportedRecordingError } from "./wav.ts";
 
 /**
@@ -97,16 +91,6 @@ export const NORMALIZED_SAMPLE_RATE = 16_000;
  */
 export const NORMALIZED_CHANNELS = 1;
 
-/**
- * Bytes moved per `readUpload` while materializing, and per write while storing.
- *
- * 8 MiB is large enough that a two-hour recording is a few hundred round trips
- * rather than tens of thousands, and small enough that the step's resident set
- * is a constant that does not depend on the recording. The number this must NOT
- * be is "the whole file", which is the shape every first draft of this step has.
- */
-const WINDOW_BYTES = 8 * 1024 * 1024;
-
 /**
  * How long a conversion may run before it is killed.
  *
@@ -114,7 +98,7 @@ const WINDOW_BYTES = 8 * 1024 * 1024;
  * realtime by two orders of magnitude, so a two-hour recording is under a
  * minute — and the reason for a bound at all is a file that makes a decoder
  * pathological rather than one that is merely long. A `timeout` is retryable
- * and an `exit` is not; see {@link classifyFfmpeg}.
+ * and an `exit` is not; `throwFfmpegStepError` decides.
  */
 const CONVERT_TIMEOUT_MS = 15 * 60_000;
 
@@ -158,72 +142,78 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
   // stuck. It is also the line that distinguishes "this file needs converting" from
   // the fast path above.
   await report(
-    `Converting ${stored.name || uploadId} (${mb(stored.size)}) — not a WAV we can cut.`,
+    `Converting ${stored.name || uploadId} (${formatBytes(stored.size)}) — not a WAV we can cut.`,
   );
 
-  const dir = await mkdtemp(join(tmpdir(), "aai-normalize-"));
-  try {
-    const source = join(dir, "source");
-    const converted = join(dir, "converted.wav");
-
-    await materialize(uploadId, stored.size, source);
-
-    // What it WAS, for the progress line. Worth one ffprobe: "converted 41
-    // minutes of aac" is a line that explains the run's shape, where
-    // "converted the recording" leaves a reader wondering what the desk decided.
-    // On a temp file rather than a pipe, so a trailing index is readable.
-    const info = await probeMedia(source, { timeoutMs: CONVERT_TIMEOUT_MS }).catch(classifyFfmpeg);
-    await report(
-      `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",
-        "-i",
-        source,
-        ...wavEncodeArgs({
-          sampleRate: NORMALIZED_SAMPLE_RATE,
-          channels: NORMALIZED_CHANNELS,
-        }),
-        converted,
-      ],
-      { timeoutMs: CONVERT_TIMEOUT_MS },
-    ).catch(classifyFfmpeg);
-
-    const written = await writeUpload(chunks(converted), {
-      // Named after the ORIGINAL, so a download reads as the recording it came
-      // from. The extension has to change with the bytes: a file served as
-      // `audio/wav` under a `.m4a` name is one no player will open.
-      name: `${basename(stored.name || uploadId, extname(stored.name || uploadId))}.wav`,
-      type: "audio/wav",
-    });
+  // The temp directory's lifetime is this lexical scope, and the `finally` inside
+  // `withTempDir` is what makes that true on the failure paths too: a guest's disk
+  // is small and a step that leaves a copy of every recording it touched fills it.
+  return await withTempDir(
+    async (dir) => {
+      const source = join(dir, "source");
+      const converted = join(dir, "converted.wav");
+
+      await readUploadToFile(uploadId, source, { size: stored.size });
+
+      // What it WAS, for the progress line. Worth one ffprobe: "converted 41
+      // minutes of aac" is a line that explains the run's shape, where
+      // "converted the recording" leaves a reader wondering what the desk decided.
+      // On a temp file rather than a pipe, so a trailing index is readable.
+      const info = await probeMedia(source, { timeoutMs: CONVERT_TIMEOUT_MS }).catch(
+        throwFfmpegStepError,
+      );
+      await report(
+        `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",
+          "-i",
+          source,
+          ...wavEncodeArgs({
+            sampleRate: NORMALIZED_SAMPLE_RATE,
+            channels: NORMALIZED_CHANNELS,
+          }),
+          converted,
+        ],
+        { timeoutMs: CONVERT_TIMEOUT_MS },
+      ).catch(throwFfmpegStepError);
+
+      const written = await writeUploadFromFile(converted, {
+        // Named after the ORIGINAL, so a download reads as the recording it came
+        // from. The extension has to change with the bytes: a file served as
+        // `audio/wav` under a `.m4a` name is one no player will open.
+        name: `${basename(stored.name || uploadId, extname(stored.name || uploadId))}.wav`,
+        type: "audio/wav",
+      });
 
-    await report(`Converted to ${mb(written.size)} of WAV (from ${mb(stored.size)}).`);
-    return { recording: written.id, converted: true };
-  } finally {
-    // Always, including on the failure paths above: a guest's disk is small and
-    // a step that leaves a copy of every recording it touched fills it. `force`
-    // so a conversion that never created its output does not fail HERE and
-    // replace the real error with this one.
-    await rm(dir, { recursive: true, force: true });
-  }
+      await report(
+        `Converted to ${formatBytes(written.size)} of WAV (from ${formatBytes(stored.size)}).`,
+      );
+      return { recording: written.id, converted: true };
+    },
+    // Named after the pipeline: the directory is gone by the time anyone looks,
+    // so the prefix's real audience is a person reading `ls /tmp` during a run
+    // that hung, and the spec that asserts nothing was left behind.
+    { prefix: "aai-normalize-" },
+  );
 }
 
 /**
  * Retries beyond the default 3.
  *
  * Not because a conversion is flaky — a corrupt file fails identically forever,
- * and {@link classifyFfmpeg} is what stops the DevKit retrying that. It is the
+ * and `throwFfmpegStepError` is what stops the DevKit retrying that. It is the
  * two I/O halves that are worth another attempt: this step reads a whole
  * recording out of the store and writes a whole one back, and either can lose a
  * connection on a file this size.
@@ -248,96 +238,10 @@ export function cuttable(head: Uint8Array, totalBytes: number): boolean {
   }
 }
 
-/**
- * Turn an ffmpeg failure into the DevKit's verdict.
- *
- * The whole reason `FfmpegError.kind` exists, used the way it was meant to be:
- * an `exit` is ffmpeg having read the file and refused it, so every retry
- * re-reads the same bytes and reaches the same conclusion while burning the
- * budget a real transient needs. A `timeout` or an `aborted` is worth another
- * attempt, and a `missing-binary` is `aai dev` on a laptop with no ffmpeg —
- * fatal, and already carrying the install instructions in its message.
- *
- * **The retryable arm goes through `throwStepError` even though it classifies
- * nothing**, and that is deliberate rather than a leftover. `toStepError` reaches
- * a verdict from a `Response` or from an SDK error that already carries one; an
- * `FfmpegError` is neither, so it is rethrown UNCHANGED — which the DevKit treats
- * as retryable by default, the outcome this arm wants. Writing
- * `new RetryableError(...)` here instead would replace ffmpeg's own message and
- * its `argv` with a sentence, and the argv is the thing you paste into a shell.
- * So the call reads as the decision it is: everything this function does not
- * declare terminal keeps its retries.
- *
- * Exported for its spec. It is the one decision in this file a unit test can
- * reach — everything around it spawns a subprocess — and it is also the one worth
- * reaching: getting it backwards means either five re-reads of a corrupt file or
- * no second attempt at a conversion that was merely slow.
- */
-export function classifyFfmpeg(err: unknown): never {
-  if (isFfmpegError(err) && (err.kind === "timeout" || err.kind === "aborted")) {
-    return throwStepError(err);
-  }
-  return throwFatalStepError(err);
-}
-
-/**
- * Write an upload to a local path, a window at a time.
- *
- * The `readUpload` window is the same primitive `transcribeSegment` cuts with;
- * what differs is only that this one walks the whole file in order. A `for` loop
- * rather than a fan-out deliberately — the bytes land in one file at one offset
- * each, so concurrency buys nothing here and costs the memory the windows are
- * there to bound.
- */
-async function materialize(uploadId: string, size: number, path: string): Promise<void> {
-  const handle = await open(path, "w");
-  try {
-    for (let at = 0; at < size; at += WINDOW_BYTES) {
-      const slice = await readUpload(uploadId, {
-        start: at,
-        end: Math.min(at + WINDOW_BYTES, size),
-      });
-      await handle.write(slice.bytes);
-    }
-  } finally {
-    await handle.close();
-  }
-}
-
-/**
- * A local file as the stream `writeUpload` takes.
- *
- * A generator rather than `readFile`, for the reason the windows exist: the
- * converted WAV is the largest thing this step touches, and handing the store an
- * `AsyncIterable` is what keeps it off the heap.
- *
- * The `.slice()` is load-bearing. One buffer is reused across reads, so yielding
- * a view of it hands the consumer memory the next read overwrites — a bug whose
- * symptom is a stored file made of the LAST chunk repeated, and which does not
- * reproduce whenever the consumer happens to copy before the next iteration.
- */
-async function* chunks(path: string): AsyncIterable<Uint8Array> {
-  const handle = await open(path, "r");
-  try {
-    const buffer = new Uint8Array(WINDOW_BYTES);
-    for (;;) {
-      const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
-      if (bytesRead === 0) return;
-      yield buffer.subarray(0, bytesRead).slice();
-    }
-  } finally {
-    await handle.close();
-  }
-}
-
 /** `41:20 of aac`, or as much of that as ffprobe would say. */
 function describeSource(codec: string | undefined, durationSec: number | undefined): string {
-  const length = durationSec === undefined ? undefined : clock(Math.round(durationSec * 1000));
+  const length =
+    durationSec === undefined ? undefined : formatDuration(Math.round(durationSec * 1000));
   if (length !== undefined && codec !== undefined) return `${length} of ${codec}`;
   return length ?? codec ?? "the recording";
 }
-
-/** A size a person can read, because the number that matters is the scale. */
-function mb(bytes: number): string {
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}

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

@@ -120,14 +120,3 @@ function seamLength(merged: readonly string[], next: readonly string[]): number
 export function stitchChunks(chunks: readonly TranscriptChunk[]): string {
   return stitchTranscript([...chunks].sort((a, b) => a.index - b.index).map((chunk) => chunk.text));
 }
-
-/** Words in a string. The run and the page count them the same way. */
-export function countWords(text: string): number {
-  return text.split(/\s+/).filter(Boolean).length;
-}
-
-/** `m:ss` for the progress log — a byte offset means nothing to a reader. */
-export function clock(ms: number): string {
-  const seconds = Math.max(0, Math.round(ms / 1000));
-  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
-}

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

@@ -138,11 +138,11 @@
  * what keeps that order a pure function of journaled values.
  */
 
+import { mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
-import { mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import { formatDuration, plural } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
 import {
-  clock,
   fatalOnUnsupported,
   mergeTranscript,
   type SegmentTranscript,
@@ -324,9 +324,8 @@ export async function planStreamed(id: string): Promise<StreamPlan> {
   }
   const segments = fatalOnUnsupported(() => planSegments(format));
   await report(
-    `Planned ${clock(segments.at(-1)?.endMs ?? 0)} of audio as ${segments.length} segment${
-      segments.length === 1 ? "" : "s"
-    } while it uploads.`,
+    `Planned ${formatDuration(segments.at(-1)?.endMs ?? 0)} of audio as ` +
+      `${segments.length} ${plural(segments.length, "segment")} while it uploads.`,
   );
   return { format, segments };
 }

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

@@ -4,7 +4,7 @@
  *
  * This module used to BE the endpoint: the URL, the model header, the raw-key auth,
  * the deadline, the multipart shape and the three-way failure classification. All of
- * that is `stepTranscribeSync` on `@alexkroman1/aai/utils` — the same request, with
+ * that is `stepTranscribeSync` on `@alexkroman1/aai/step` — the same request, with
  * `transcription-workflow`'s own hard-won details (the unprefixed key, the
  * `X-AAI-Model` header, `stepFetch` rather than `fetch` so a fan-out's rate limit
  * arrives as a status rather than as a stream reset) carried into it.
@@ -18,8 +18,7 @@
  * the same shape). It is called FROM steps, so it inherits their environment.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
-import { stepTranscribeSync } from "@alexkroman1/aai/utils";
+import { stepTranscribeSyncClassified } from "@alexkroman1/aai/step-errors";
 
 /**
  * Time one transcription, so the progress log carries LATENCY.
@@ -55,8 +54,9 @@ export function elapsed(ms: number): string {
  * callers arrive at that differently: one re-attaches a header to a window it
  * read, the other is handed parts that already carry one.
  *
- * `.catch(throwStepError)` 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
+ * `stepTranscribeSyncClassified` — 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
  * SECOND (that class's own default), and a `RetryableError` carrying `retryAfter`
  * waits exactly as long as the far side asked. The last matters here because a whole
@@ -72,6 +72,6 @@ export async function transcribeWav(
   filename: string,
   label: string,
 ): Promise<string> {
-  const { text } = await stepTranscribeSync(bytes, { filename, label }).catch(throwStepError);
+  const { text } = await stepTranscribeSyncClassified(bytes, { filename, label });
   return text;
 }

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

@@ -41,7 +41,7 @@
  * ## Three properties this leans on
  *
  * - **A step can read the agent's env now.** `stepEnv`/`requireStepEnv`
- *   (`@alexkroman1/aai/utils`) is what makes any of this real: a step is
+ *   (`@alexkroman1/aai/step`) is what makes any of this real: a step is
  *   dispatched separately from the agent bundle and is handed no `ToolContext`,
  *   so before that seam existed no step anywhere could authenticate an outbound
  *   call, and every workflow template's I/O was a fixture saying so.
@@ -63,16 +63,18 @@
  *   `output` exists only when the last segment does.
  */
 
+import {
+  emit,
+  encodeWav,
+  mapConcurrent,
+  readUpload,
+  report,
+  uploadInfo,
+} from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
-import { emit, mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import { countWords, formatDuration, plural } from "@alexkroman1/aai/utils";
 import { normalizeRecording } from "./normalize.ts";
-import {
-  clock,
-  countWords,
-  stitchTranscript,
-  TRANSCRIPT_STREAM,
-  type TranscriptChunk,
-} from "./stitch.ts";
+import { stitchTranscript, TRANSCRIPT_STREAM, type TranscriptChunk } from "./stitch.ts";
 import { elapsed, timed, transcribeWav } from "./sync-api.ts";
 import {
   bytesPerSecond,
@@ -84,7 +86,6 @@ import {
   type Segment,
   UnsupportedRecordingError,
   type WavFormat,
-  wavWithHeader,
 } from "./wav.ts";
 
 /**
@@ -281,7 +282,7 @@ export async function splitRecording(uploadId: string): Promise<{
   const durationMs = segments.at(-1)?.endMs ?? 0;
 
   await report(
-    `Split ${clock(durationMs)} of audio into ${segments.length} segment${segments.length === 1 ? "" : "s"}.`,
+    `Split ${formatDuration(durationMs)} of audio into ${segments.length} ${plural(segments.length, "segment")}.`,
   );
   return { format, segments, durationMs };
 }
@@ -308,7 +309,7 @@ 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 ${clock(segment.startMs)}–${clock(segment.endMs)}.`);
+  await report(`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
@@ -321,20 +322,25 @@ export async function transcribeSegment(
   // answers better — and getting it wrong is a whole transcript in the wrong
   // language. Add one back only for a desk that really knows.
   //
-  // `wavWithHeader` is what makes a WINDOW decodable: the endpoint decodes each
+  // `encodeWav` is what makes a WINDOW decodable: the endpoint decodes each
   // request independently, so a slice of the middle of a recording is a headerless
   // tail until one is put back on it. The streaming flow needs no equivalent — its
-  // parts were cut with a header each.
+  // parts were cut with a header each. The header is the SDK's rather than this
+  // template's: a `WavFormat` is structurally a `PcmFormat`, and 22 lines of
+  // `DataView` writes with a comment about which of the two declared lengths a
+  // decoder trusts is not a thing worth a second copy of.
   const { value: text, ms } = await timed(() =>
     transcribeWav(
-      wavWithHeader(format, audio.bytes),
+      encodeWav(audio.bytes, format),
       `segment-${segment.index}.wav`,
-      `Segment ${segment.index} (${clock(segment.startMs)})`,
+      `Segment ${segment.index} (${formatDuration(segment.startMs)})`,
     ),
   );
   // 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(`Transcribed ${clock(segment.startMs)}–${clock(segment.endMs)} in ${elapsed(ms)}.`);
+  await report(
+    `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.
@@ -372,7 +378,7 @@ export async function mergeTranscript(
 ): Promise<Transcript> {
   "use step";
 
-  await report(`Stitching ${parts.length} segment${parts.length === 1 ? "" : "s"} together.`);
+  await report(`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
@@ -417,12 +423,13 @@ export async function startClock(): Promise<number> {
   return Date.now();
 }
 
-// `clock` and `countWords` are re-exported rather than re-declared: `stream.ts`
-// and `batch.ts` already import them from this module, and the split that let the
-// PAGE stitch a partial transcript should not ripple through every flow.
+// 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 {
-  clock,
-  countWords,
   stitchChunks,
   stitchTranscript,
   TRANSCRIPT_STREAM,
@@ -434,9 +441,8 @@ export {
 /**
  * Run a `wav.ts` helper, turning its "cannot cut this" into a terminal failure.
  *
- * Exported for the same reason `countWords` is: `stream.ts` plans with the same
- * `wav.ts` helpers and owes the same classification, and it had this byte for
- * byte.
+ * Exported because `stream.ts` plans with the same `wav.ts` helpers and owes the
+ * same classification, and it had this byte for byte.
  */
 export function fatalOnUnsupported<T>(read: () => T): T {
   try {