@alexkroman1/aai-cli 6.10.0 → 6.11.0

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

@@ -8,13 +8,12 @@
  * the two ways to arrange that. The async API has no such cap. You submit a job, it
  * answers with an id in milliseconds, and the transcript is ready minutes later.
  *
- * So this flow is four steps and no arithmetic:
+ * So this flow is three steps and no arithmetic:
  *
  * ```text
  *   uploadToProvider   one step   →  the file, streamed, and the URL it answered
  *   createJob          one step   →  the transcript id
- *   pollTranscript     one step + a durable sleep, until it is done
- *   readTranscript     one step   →  the text
+ *   pollTranscript     one step + a durable sleep, until the text comes back
  * ```
  *
  * **It is here to be compared against the other two, and it usually wins.** No
@@ -24,6 +23,21 @@
  * inside: the latency is the provider's queue rather than your fan-out, and there is
  * nothing to report between "submitted" and "done" except the job's own status.
  *
+ * ## 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
+ * 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.
+ *
+ * What stays here is what a dependency cannot decide: how many steps to cut the job
+ * into, and therefore what is journaled and what a retry repeats. That is also
+ * structural rather than stylistic — the Workflow DevKit's builder transforms
+ * exactly the files under this `workflows/` directory, so a `"use step"` shipped
+ * inside the SDK would be transformed by nothing and would run inline with no
+ * journal and no retry, silently.
+ *
  * ## The one thing that makes this a WORKFLOW rather than a request
  *
  * The wait. A job takes minutes, and nothing about an HTTP request survives minutes:
@@ -32,66 +46,35 @@
  * shape and its module doc carries the argument; this is the same pattern with the
  * poll bounded by attempts rather than by a deadline.
  *
- * ## The upload STREAMS out of our own store
+ * ## Three steps, not four, and the fourth was a wasted round trip
  *
- * `readUpload` hands back bytes, and a two-hour recording is not a value this process
- * can hold — so the body sent to `/v2/upload` is an async iterable of windows, which
- * `stepFetch` accepts precisely for this. Nothing is buffered beyond one window.
- *
- * That is also why the step that does it is the step the DevKit retries: a streaming
- * body is consumed once, so a retry has to re-read the upload from the start, which
- * it does. One window of READ-AHEAD keeps the store and the socket busy at the same
- * time; `windows` carries the argument.
+ * This used to poll `GET /v2/transcript/:id` for a status and then fetch the
+ * identical URL a second time to read the text the poll already had in its hand.
+ * {@link pollTranscript} answers with the transcript, so a finished job costs one
+ * request rather than two and the value journaled by the last poll IS the result.
  */
 
-import { throwFatalStepError, toStepError } from "@alexkroman1/aai/step-errors";
-import { readUpload, report, stepFetch, uploadInfo } from "@alexkroman1/aai/utils";
+import { throwStepError } from "@alexkroman1/aai/step-errors";
+import {
+  report,
+  stepTranscribePoll,
+  stepTranscribeSubmit,
+  stepTranscribeUpload,
+  TRANSCRIBE_API,
+  uploadInfo,
+} from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
-import { apiKeyOrFatal } from "./sync-api.ts";
 import { countWords, startClock, type Transcript } from "./transcribe.ts";
 
-/** The async API's base. */
-const API = "https://api.assemblyai.com";
-
-/**
- * The models this desk asks for, best first.
- *
- * `speech_models`, PLURAL and an array. The singular `speech_model` is deprecated on
- * the async API and answers **400** for any current model name — which is how this
- * was found: the first live run of this flow failed on it, and the API said so in
- * exactly those words. Note the streaming API still uses the singular field, so the
- * two are not interchangeable and neither is "the" spelling.
- *
- * Omitting it entirely is also legal and routes to the default; naming it is what
- * pins the model so a default change does not silently move this template's output.
- */
-const MODELS = ["universal-3-5-pro"];
-
-/** How much of our stored upload one outbound window carries. */
-const UPLOAD_WINDOW_BYTES = 4 * 1024 * 1024;
-
-/** How long a single request may take. The upload is not one of these — see below. */
-const REQUEST_TIMEOUT_MS = 60_000;
-
-/**
- * How long the upload leg may take.
- *
- * Its own budget because it is the one request whose duration is a function of the
- * FILE rather than of the service: a gigabyte at 8 MB/s is over two minutes, and a
- * deadline sized for a JSON round trip would cancel exactly the uploads this flow
- * exists to handle.
- */
-const UPLOAD_TIMEOUT_MS = 30 * 60_000;
-
 /** How long between polls of a submitted job. */
 const POLL_INTERVAL = "10s";
 
 /**
  * Polls before the run gives up on a job.
  *
- * At {@link POLL_INTERVAL} this is an hour, which is well past what the async API
- * takes for any recording it accepts. Bounded rather than endless because a job that
- * never leaves `queued` is a run that would otherwise be replayed forever.
+ * At {@link POLL_INTERVAL} this is an hour, well past what the async API takes for
+ * any recording it accepts. Bounded rather than endless because a job that never
+ * leaves `queued` is a run that would otherwise be replayed forever.
  */
 const MAX_POLLS = 360;
 
@@ -109,15 +92,15 @@ export async function transcribeBatchFlow(input: { recording: string }): Promise
   const job = await createJob(audioUrl);
 
   for (let poll = 0; poll < MAX_POLLS; poll += 1) {
-    const status = await pollTranscript(job.id);
-    if (status.done) return await readTranscript(input.recording, job.id, startedAt);
+    const progress = await pollTranscript(input.recording, job.id, startedAt);
+    if (progress.done) return progress.transcript;
     await sleep(POLL_INTERVAL);
   }
   // A plain throw: this is the BODY, where the fatal/retryable distinction has
   // nothing to apply to — see `stream.ts`'s `abandon` for the same reasoning.
   throw new Error(
     `Transcript ${job.id} was still unfinished after ${MAX_POLLS} polls. It is not lost — ` +
-      `read it directly with GET ${API}/v2/transcript/${job.id}.`,
+      `read it directly with GET ${TRANSCRIBE_API}/v2/transcript/${job.id}.`,
   );
 }
 
@@ -134,28 +117,17 @@ export async function transcribeBatchFlow(input: { recording: string }): Promise
  * So the URL is journaled after all. The risk that made that look wrong is real but
  * 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.
  */
 export async function uploadToProvider(uploadId: string): Promise<{ audioUrl: string }> {
   "use step";
 
-  const apiKey = apiKeyOrFatal();
   const stored = await uploadInfo(uploadId);
   await report(`Uploading ${stored.name || uploadId} (${mb(stored.size)}) to the async API.`);
-
-  const uploaded = await stepFetch(`${API}/v2/upload`, {
-    method: "POST",
-    headers: { Authorization: apiKey, "Content-Type": "application/octet-stream" },
-    // An async iterable, not bytes: this file may be gigabytes, and nothing here holds
-    // more than one window of it. See the module doc.
-    body: windows(uploadId, stored.size),
-    signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
-  });
-  if (!uploaded.ok) throw await failure(uploaded, "Upload");
-  const { upload_url: audioUrl } = (await uploaded.json()) as { upload_url?: string };
-  if (!audioUrl) {
-    return throwFatalStepError(new Error("The async API accepted the upload but named no URL."));
-  }
-  return { audioUrl };
+  return await stepTranscribeUpload(uploadId).catch(throwStepError);
 }
 
 /** Retries beyond the default 3: an upload is the one call here worth another attempt. */
@@ -165,125 +137,55 @@ uploadToProvider.maxRetries = 5;
 export async function createJob(audioUrl: string): Promise<{ id: string }> {
   "use step";
 
-  const created = await stepFetch(`${API}/v2/transcript`, {
-    method: "POST",
-    headers: { Authorization: apiKeyOrFatal(), "Content-Type": "application/json" },
-    body: JSON.stringify({ audio_url: audioUrl, speech_models: MODELS }),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-  });
-  if (!created.ok) throw await failure(created, "Submit");
-  const { id } = (await created.json()) as { id?: string };
-  if (!id) return throwFatalStepError(new Error("The async API created no transcript id."));
-
-  await report(`Submitted transcript ${id}.`);
-  return { id };
+  const job = await stepTranscribeSubmit(audioUrl).catch(throwStepError);
+  await report(`Submitted — job ${job.id}.`);
+  return job;
 }
 
 /**
- * Ask once whether the job has finished.
+ * Ask once whether the job has finished, and read it when it has.
  *
  * `done` rather than the raw status, because the BODY branches on it and a body must
- * not be the place a provider's vocabulary is interpreted — a new status string would
- * otherwise be read as "not done yet" forever. A failed job is a terminal failure
- * here, not a `done: true` the caller has to re-check.
+ * not be where a provider's vocabulary is interpreted — a new status string would
+ * otherwise read as "not done yet" forever. A failed job is a terminal failure
+ * inside the SDK call, not a `done: true` the caller has to re-check.
  */
-export async function pollTranscript(id: string): Promise<{ done: boolean; status: string }> {
-  "use step";
-
-  const res = await stepFetch(`${API}/v2/transcript/${id}`, {
-    headers: { Authorization: apiKeyOrFatal() },
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-  });
-  if (!res.ok) throw await failure(res, `Transcript ${id}`);
-  const body = (await res.json()) as { status?: string; error?: string };
-  const status = body.status ?? "unknown";
-  if (status === "error") {
-    // The provider has decided; no number of polls changes it.
-    return throwFatalStepError(
-      new Error(
-        `The async API could not transcribe that recording: ${body.error ?? "no reason given"}`,
-      ),
-    );
-  }
-  await report(`Transcript ${id} is ${status}.`);
-  return { done: status === "completed", status };
-}
-
-/** Read the finished transcript, and report it the way both sync flows do. */
-export async function readTranscript(
+export async function pollTranscript(
   uploadId: string,
   id: string,
   startedAt: number,
-): Promise<Transcript> {
+): Promise<{ done: false } | { done: true; transcript: Transcript }> {
   "use step";
 
-  const res = await stepFetch(`${API}/v2/transcript/${id}`, {
-    headers: { Authorization: apiKeyOrFatal() },
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-  });
-  if (!res.ok) throw await failure(res, `Transcript ${id}`);
-  const body = (await res.json()) as { text?: string; audio_duration?: number };
-  const transcript = (body.text ?? "").trim();
-  const stored = await uploadInfo(uploadId);
+  const progress = await stepTranscribePoll(id).catch(throwStepError);
+  if (!progress.done) {
+    await report(`Transcript ${id} is ${progress.status}.`);
+    return { done: false };
+  }
 
+  const stored = await uploadInfo(uploadId);
+  const transcript = progress.transcript.text;
   return {
-    source: stored.name || uploadId,
-    // ONE, and it is not a fudge: the async API transcribed the recording in one
-    // piece, which is the difference this flow is here to show. A reader comparing
-    // the three sees 7 segments, 7 segments, and 1.
-    segments: 1,
-    // The provider's own measurement, in seconds — the only one of the three flows
-    // that does not have to derive this from byte offsets.
-    durationMs: Math.round((body.audio_duration ?? 0) * 1000),
-    // Wall clock, the same way both sync flows measure it — see `startClock`. For
-    // this flow it is mostly the provider's queue, which is exactly the thing a
-    // reader comparing the three wants to see.
-    elapsedMs: Date.now() - startedAt,
-    words: countWords(transcript),
-    transcript,
+    done: true,
+    transcript: {
+      source: stored.name || uploadId,
+      // ONE, and it is not a fudge: the async API transcribed the recording in one
+      // piece, which is the difference this flow is here to show. A reader comparing
+      // the three sees 7 segments, 7 segments, and 1.
+      segments: 1,
+      // The provider's own measurement — the only one of the three flows that does
+      // not have to derive this from byte offsets.
+      durationMs: progress.transcript.durationMs,
+      // Wall clock, the same way both sync flows measure it — see `startClock`. For
+      // this flow it is mostly the provider's queue, which is exactly the thing a
+      // reader comparing the three wants to see.
+      elapsedMs: Date.now() - startedAt,
+      words: countWords(transcript),
+      transcript,
+    },
   };
 }
 
-/**
- * The stored upload as a sequence of windows, with the next one already in flight.
- *
- * A generator rather than one `readUpload`, because the whole point is that the file
- * is never held: each window is read, sent, and dropped. `readUpload` clamps to what
- * is stored, so the loop ends on the real end of the file even if `size` moved.
- *
- * **One window of READ-AHEAD**, which is the whole concurrency available here: the
- * consumer is a socket and the producer is the app's own store, and read-then-send
- * makes them strictly alternate — the store idles while bytes go out, and the socket
- * idles while the next window is fetched. Starting the next read before yielding the
- * current window overlaps them, so a gigabyte upload pays the larger of the two
- * rather than their sum. Exactly one, not a queue: a deeper buffer holds more of a
- * file this generator exists to avoid holding, and there is nothing to gain past
- * keeping both ends busy.
- */
-async function* windows(uploadId: string, size: number): AsyncGenerator<Uint8Array> {
-  const read = (at: number): Promise<Uint8Array> =>
-    readUpload(uploadId, { start: at, end: at + UPLOAD_WINDOW_BYTES }).then((slice) => slice.bytes);
-  let at = 0;
-  let next = at < size ? read(at) : undefined;
-  while (next !== undefined) {
-    const bytes = await next;
-    if (bytes.length === 0) return;
-    at += UPLOAD_WINDOW_BYTES;
-    // Issued BEFORE the yield, so the store is fetching while the socket sends.
-    next = at < size ? read(at) : undefined;
-    yield bytes;
-  }
-}
-
-/** A failed call, classified for the DevKit — see `sync-api.ts` for the three-way rule. */
-async function failure(res: Response, what: string): Promise<Error> {
-  const body = (await res.json().catch(() => ({}))) as { error?: string };
-  return toStepError(
-    res,
-    `${what} failed: HTTP ${res.status}${body.error ? ` — ${body.error}` : ""}`,
-  );
-}
-
 /** 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

@@ -0,0 +1,343 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The step that makes the rest of the desk possible on a real file: whatever was
+ * uploaded, converted to the one format the arithmetic works on.
+ *
+ * `wav.ts` explains why this desk cuts linear-PCM WAV and nothing else — a byte
+ * offset is only a timestamp when every sample is the same size — and for a long
+ * time the remedy for anything else was a SENTENCE telling the caller to run
+ * `ffmpeg -i in.m4a -c:a pcm_s16le out.wav` on their own machine first. Every
+ * recording anyone actually has is an `.m4a` off a phone or an `.mp3` out of a
+ * conferencing tool, so that sentence was the desk's real front door, and it
+ * opened onto the user's shell. The platform installs ffmpeg in every guest
+ * image; this file is the desk using it.
+ *
+ * ```text
+ *   normalizeRecording   one step   →  an upload id the rest of the flow can cut
+ * ```
+ *
+ * ## `parseWav` is asked as a QUESTION
+ *
+ * The obvious implementation probes the file with `ffprobe` and passes it
+ * through when the codec looks like PCM. It is wrong in a way that only shows up
+ * on a Windows recorder's output: a `WAVE_FORMAT_EXTENSIBLE` file reports
+ * `pcm_s16le` to ffprobe and is refused by {@link parseWav}, whose encoding
+ * check reads the format tag ffprobe does not surface. The desk would convert
+ * nothing and then fail to cut it.
+ *
+ * So the test is {@link parseWav} ITSELF, run against the same
+ * {@link HEADER_PROBE_BYTES} window `splitRecording` will use. A throw is the
+ * signal to convert. That makes the pass-through decision and the cut decision
+ * the same decision by construction — there is no second opinion to disagree —
+ * and it means the desk fixes anything the parser rejects for any reason,
+ * including a 192 kHz 32-bit stereo WAV that trips
+ * {@link MAX_BYTES_PER_SECOND}, which downsampling genuinely repairs.
+ *
+ * The fast path costs one 64 KB read and no subprocess at all: a WAV that was
+ * already cuttable is returned by the id it came in under, so nothing is copied
+ * and nothing is re-encoded.
+ *
+ * ## 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.
+ */
+
+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 { HEADER_PROBE_BYTES, parseWav, UnsupportedRecordingError } from "./wav.ts";
+
+/**
+ * The rate everything is converted TO.
+ *
+ * 16 kHz because that is what speech models are trained at — a higher rate
+ * carries no information the decoder uses and costs proportional bytes in a
+ * fan-out whose width is bounded by bytes in flight (`BYTES_IN_FLIGHT` in
+ * `transcribe.ts`). A converted two-hour recording is 230 MB of 16 kHz mono
+ * against 1.4 GB of 48 kHz stereo, which is the difference between a fan-out
+ * that saturates on width and one that saturates on the queue.
+ */
+export const NORMALIZED_SAMPLE_RATE = 16_000;
+
+/**
+ * Channels everything is converted TO.
+ *
+ * Mono, and it is a real loss rather than a free win: a stereo call recording
+ * with one party per channel is exactly the file where the channels are the most
+ * interesting thing about it, and downmixing throws that away. This desk
+ * transcribes rather than diarizes, so it takes the 2x saving; a desk that wants
+ * the speakers apart splits the channels first and transcribes each one.
+ */
+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.
+ *
+ * Well past what the work takes — ffmpeg decodes and resamples faster than
+ * 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}.
+ */
+const CONVERT_TIMEOUT_MS = 15 * 60_000;
+
+/** What the flow is handed: the id to cut, and whether it had to be made. */
+export type NormalizedRecording = {
+  /**
+   * The upload id every later step reads.
+   *
+   * The SAME id that came in when the file was already cuttable, and a new one
+   * when it was converted — which is why the flow threads this rather than its
+   * own input from here on.
+   */
+  recording: string;
+  /** Whether ffmpeg ran. Reported, so a reader can tell a fast path from a slow one. */
+  converted: boolean;
+};
+
+/**
+ * Make sure the recording is something the desk can cut, converting if not.
+ *
+ * A step, for the ordinary two reasons — it does I/O, and its RESULT is what
+ * every later step addresses — plus one specific to what it produces: the
+ * conversion writes a file, and journaling the id means a resumed run reads the
+ * file that already exists instead of paying for a second one.
+ */
+export async function normalizeRecording(uploadId: string): Promise<NormalizedRecording> {
+  "use step";
+
+  const stored = await uploadInfo(uploadId);
+  const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
+
+  if (cuttable(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.`);
+    return { recording: uploadId, converted: false };
+  }
+
+  // Named before any work starts, because everything below is minutes of it on a
+  // long recording and a run that says nothing until the conversion finishes looks
+  // 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.`,
+  );
+
+  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",
+    });
+
+    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 });
+  }
+}
+
+/**
+ * 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
+ * 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.
+ */
+normalizeRecording.maxRetries = 5;
+
+/**
+ * Whether `splitRecording` will be able to read this header.
+ *
+ * The question, not a guess at it — see the module doc. Only
+ * {@link UnsupportedRecordingError} is answered `false`: anything else thrown by
+ * the parser is a bug in the parser, and swallowing it here would turn that into
+ * a mysterious re-encode of a file that was fine.
+ */
+export function cuttable(head: Uint8Array, totalBytes: number): boolean {
+  try {
+    parseWav(head, totalBytes);
+    return true;
+  } catch (err: unknown) {
+    if (err instanceof UnsupportedRecordingError) return false;
+    throw err;
+  }
+}
+
+/**
+ * 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));
+  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`;
+}