@alexkroman1/aai-cli 6.10.1 → 7.0.0

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

@@ -17,16 +17,23 @@
  * the decoder happily transcribes into confident nonsense.
  */
 
-import { stubReporter, stubStepFetch, stubUploads } from "@alexkroman1/aai/testing";
-import { omitUndefined, readUpload } from "@alexkroman1/aai/utils";
-import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { readdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { readUpload } from "@alexkroman1/aai/step";
+import {
+  installStubReporter,
+  installStubStepFetch,
+  installStubTranscribe,
+  installStubUploads,
+} from "@alexkroman1/aai/testing/vitest";
+import { beforeEach, describe, expect, test, vi } from "vitest";
 import { FatalError, RetryableError } from "workflow";
 import { z } from "zod";
 import agentDef, { transcribe, transcribeBatch, transcribeStream } from "./agent.ts";
-import { createJob, pollTranscript, readTranscript, uploadToProvider } from "./workflows/batch.ts";
-import { planStreamed, probeUpload } from "./workflows/stream.ts";
+import { createJob, pollTranscript, uploadToProvider } from "./workflows/batch.ts";
+import { cuttable, normalizeRecording } from "./workflows/normalize.ts";
+import { expectedSegments, planStreamed, probeUpload } from "./workflows/stream.ts";
 import {
-  clock,
   mergeTranscript,
   splitRecording,
   stitchChunks,
@@ -45,12 +52,8 @@ import {
   SEGMENT_SECONDS,
   UnsupportedRecordingError,
   type WavFormat,
-  wavWithHeader,
 } from "./workflows/wav.ts";
 
-/** Where the sync endpoint lives — the one URL these stubs answer differently. */
-const SYNC_ORIGIN = "https://sync.assemblyai.com";
-
 /** The id every spec below uploads under. */
 const UPLOAD_ID = "upl_test";
 
@@ -72,16 +75,12 @@ const STARTED_AT = 1_000_000;
  * bytes with no server, no database and no HTTP.
  */
 function publishRecording(bytes: Uint8Array, name = "standup.wav") {
-  restore = stubUploads({ [UPLOAD_ID]: { bytes, name, type: "audio/wav" } });
+  // `installStubUploads` rather than `stubUploads`: the fake registers its own
+  // `onTestFinished`, which is what replaced the three hand-kept restore
+  // registries this file used to carry.
+  installStubUploads({ [UPLOAD_ID]: { bytes, name, type: "audio/wav" } });
 }
 
-/** Unpublished between specs — a slot left behind reaches the next file. */
-let restore: (() => void) | undefined;
-afterEach(() => {
-  restore?.();
-  restore = undefined;
-});
-
 /** 16 kHz mono 16-bit — one second of audio is 32,000 bytes. */
 const MONO_16K = { sampleRate: 16_000, channels: 1, bitsPerSample: 16 } as const;
 
@@ -143,8 +142,8 @@ describe("the agent declares its three workflows and nothing else", () => {
     // every flow, and the streaming one differs only in that the CLIENT chose the id
     // and PUT the file to it. A divergence here would mean the form had to ask a
     // person how the bytes should travel.
-    for (const flow of [transcribe, transcribeStream, transcribeBatch]) {
-      expect(flow.uploads).toEqual(["recording"]);
+    for (const wf of [transcribe, transcribeStream, transcribeBatch]) {
+      expect(wf.uploads).toEqual(["recording"]);
     }
   });
 
@@ -371,24 +370,6 @@ describe("planSegments decides the fan-out's width", () => {
   });
 });
 
-describe("wavWithHeader", () => {
-  test("writes a header the endpoint can read the rate back out of", () => {
-    const samples = new Uint8Array(3200).fill(7);
-    const out = wavWithHeader({ ...MONO_16K, dataStart: 44, dataEnd: 3244 }, samples);
-    const view = new DataView(out.buffer);
-
-    expect(String.fromCharCode(...out.subarray(0, 4))).toBe("RIFF");
-    expect(String.fromCharCode(...out.subarray(8, 12))).toBe("WAVE");
-    expect(view.getUint32(24, true)).toBe(MONO_16K.sampleRate);
-    expect(view.getUint16(22, true)).toBe(MONO_16K.channels);
-    // The two lengths, which are what a decoder trusts: RIFF counts everything
-    // after itself, `data` counts only the samples.
-    expect(view.getUint32(4, true)).toBe(36 + samples.length);
-    expect(view.getUint32(40, true)).toBe(samples.length);
-    expect(out.subarray(44)).toEqual(samples);
-  });
-});
-
 describe("stitchTranscript", () => {
   test("removes the words the overlap made duplicates", () => {
     expect(
@@ -468,13 +449,6 @@ describe("stitchChunks — what the PAGE renders while a run is going", () => {
   });
 });
 
-describe("clock", () => {
-  test("renders a position a reader can find in the recording", () => {
-    expect(clock(0)).toBe("0:00");
-    expect(clock(65_000)).toBe("1:05");
-  });
-});
-
 describe("splitRecording", () => {
   test("plans the segments and reports the duration", async () => {
     const seconds = 200;
@@ -524,49 +498,40 @@ describe("transcribeSegment", () => {
   /**
    * Publishes the recording and answers the sync endpoint.
    *
-   * `stubStepFetch`, not `vi.stubGlobal("fetch", …)`: the step calls `stepFetch`,
-   * which reaches a published slot rather than the global — see
-   * `sdk/step-fetch.ts` for why it has to (HTTP/1.1, so a batch of segments gets
-   * a socket each instead of N streams on one connection). Stubbing the global
-   * still passes, because an unpublished slot falls back to it, and would be
-   * asserting against a path production does not take.
+   * `installStubTranscribe` routes AssemblyAI's four legs off the SDK's own
+   * endpoint constants, so this file no longer re-types the wire — and it fills a
+   * published `stepFetch` rather than `vi.stubGlobal("fetch", …)`, because the
+   * step calls `stepFetch`, which reaches a published slot rather than the global
+   * (see `sdk/step-fetch.ts` for why it has to: HTTP/1.1, so a batch of segments
+   * gets a socket each instead of N streams on one connection). Stubbing the
+   * global still passes, because an unpublished slot falls back to it, and would
+   * be asserting against a path production does not take.
+   *
+   * A refusal is staged as a STATUS, which is what makes the classification specs
+   * below a test of the SDK's reading of it rather than of an error a fake minted.
    */
-  function stubProvider(
-    sync: { status?: number; body?: unknown; headers?: Record<string, string> } = {},
-  ) {
+  function stubProvider(failure?: { status: number; message: string; retryAfterSeconds?: number }) {
     publishRecording(new Uint8Array(FORMAT.dataEnd));
-    const stub = stubStepFetch(() => ({
-      status: sync.status ?? 200,
-      body: sync.body ?? { text: "hello there" },
-      ...omitUndefined({ headers: sync.headers }),
-    }));
-    stubs.push(stub.restore);
-    return stub.calls;
+    return installStubTranscribe({
+      text: "hello there",
+      failure: failure === undefined ? undefined : { leg: "sync", ...failure },
+    }).calls;
   }
 
-  /** Unpublished per test — a live one answers the next file's steps. */
-  const stubs: (() => void)[] = [];
-  afterEach(() => {
-    for (const restore of stubs.splice(0)) restore();
-  });
-
-  test("sends the segment as a WAV, with the key and the model header", async () => {
+  test("sends the segment as a WAV named after its index", async () => {
+    // What the SYNC endpoint's request looks like — the URL, the raw-key auth, the
+    // multipart envelope — is the SDK's contract and `sdk/step-transcribe*.test.ts`
+    // owns it. What is left here is this template's: it re-attaches a header to a
+    // window it read, and it names the part after the segment.
     const calls = stubProvider();
     const result = await transcribeSegment(UPLOAD_ID, FORMAT, SEGMENT);
 
     expect(result).toEqual({ index: 0, text: "hello there" });
-    const sync = calls.find((call) => call.url.startsWith(SYNC_ORIGIN));
-    // The raw key: this endpoint takes it unprefixed, and `Bearer ` in front of
-    // it is a 401 that reads like a wrong key.
-    expect(sync?.headers.Authorization).toBe("sk-test");
-    expect(sync?.headers["X-AAI-Model"]).toBe("universal-3-5-pro");
-    // BYTES, and multipart — `stepFetch` takes no `FormData`, which is the
-    // point: a branded object handed to a fetch from another undici realm goes
-    // out as the string `[object FormData]`. `multipartBody` builds the envelope.
-    expect(sync?.headers["Content-Type"]).toMatch(/^multipart\/form-data; boundary=/);
-    const body = sync?.body;
-    expect(body).toBeInstanceOf(Uint8Array);
-    const decoded = new TextDecoder().decode(body as Uint8Array);
+    const sent = calls.find((call) => call.leg === "sync")?.body;
+    // Narrowed by a failing assertion rather than a cast: `expect.fail` returns
+    // `never`, and a body that is not bytes is a finding rather than a type error.
+    if (!(sent instanceof Uint8Array)) return expect.fail("the sync leg carries bytes");
+    const decoded = new TextDecoder().decode(sent);
     expect(decoded).toContain('name="audio"; filename="segment-0.wav"');
     // The WAV really rides in the part, header and all.
     expect(decoded).toContain("RIFF");
@@ -577,8 +542,7 @@ describe("transcribeSegment", () => {
     // page stitches whatever has arrived, so the transcript renders growing
     // instead of appearing when the last segment does. The reporter is the SDK's
     // published slot, which is the same seam `report()` goes through.
-    const reported = stubReporter();
-    stubs.push(reported.restore);
+    const reported = installStubReporter();
     stubProvider();
 
     await transcribeSegment(UPLOAD_ID, FORMAT, SEGMENT);
@@ -608,7 +572,7 @@ describe("transcribeSegment", () => {
     // `RetryableError` carrying `retryAfter` is the difference between draining
     // the 429s and re-collecting them `SEGMENT_CONCURRENCY` at a time on a
     // backoff the server did not choose.
-    stubProvider({ status: 429, body: { detail: "slow down" }, headers: { "Retry-After": "30" } });
+    stubProvider({ status: 429, message: "slow down", retryAfterSeconds: 30 });
     const failure = await transcribeSegment(UPLOAD_ID, FORMAT, SEGMENT).catch(
       (err: unknown) => err,
     );
@@ -620,14 +584,14 @@ describe("transcribeSegment", () => {
   });
 
   test("retries a rate limit that named no delay", async () => {
-    stubProvider({ status: 429, body: { detail: "slow down" } });
+    stubProvider({ status: 429, message: "slow down" });
     await expect(transcribeSegment(UPLOAD_ID, FORMAT, SEGMENT)).rejects.toBeInstanceOf(
       RetryableError,
     );
   });
 
   test("fails FATALLY on a rejected request, naming what the endpoint said", async () => {
-    stubProvider({ status: 400, body: { error_code: "audio_too_short", message: "too short" } });
+    stubProvider({ status: 400, message: "too short" });
     await expect(transcribeSegment(UPLOAD_ID, FORMAT, SEGMENT)).rejects.toThrow(
       /HTTP 400 — too short/,
     );
@@ -687,7 +651,7 @@ describe("the streaming flow", () => {
   function publishPartial(stored: number, declared: number, complete = false) {
     const bytes = new Uint8Array(44 + stored);
     bytes.set(wavFile(MONO_16K, declared), 0);
-    restore = stubUploads({
+    installStubUploads({
       [UPLOAD_ID]: { bytes, name: "standup.wav", type: "audio/wav", complete },
     });
   }
@@ -721,12 +685,12 @@ describe("the streaming flow", () => {
     // the file has finished — which is exactly what `transcribe` is for.
     const bytes = new Uint8Array(44 + 100);
     bytes.set(wavFile(MONO_16K, 100, { declaredDataSize: 0 }), 0);
-    restore = stubUploads({ [UPLOAD_ID]: { bytes, complete: false } });
+    installStubUploads({ [UPLOAD_ID]: { bytes, complete: false } });
     await expect(planStreamed(UPLOAD_ID)).rejects.toThrow(/declares no data length/);
   });
 
   test("planStreamed refuses a file that is not a WAV, terminally", async () => {
-    restore = stubUploads({ [UPLOAD_ID]: { bytes: new Uint8Array(2000), complete: false } });
+    installStubUploads({ [UPLOAD_ID]: { bytes: new Uint8Array(2000), complete: false } });
     // Fatal, not retryable: three more attempts read the same bytes.
     await expect(planStreamed(UPLOAD_ID)).rejects.toBeInstanceOf(FatalError);
   });
@@ -757,21 +721,20 @@ describe("the async flow", () => {
     vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
   });
 
-  const batchStubs: (() => void)[] = [];
-  afterEach(() => {
-    for (const undo of batchStubs.splice(0)) undo();
-  });
-
-  /** Answer the async API, recording what was sent. */
-  function stubBatch(answer: (url: string) => { status?: number; body?: unknown }) {
-    const stub = stubStepFetch((req) => answer(req.url));
-    batchStubs.push(stub.restore);
-    return stub.calls;
+  /**
+   * Answer the async API, recording what was sent.
+   *
+   * `installStubTranscribe` routes the three legs off the SDK's own endpoint
+   * constants — so a spec cannot pass because the fake and the step agree on a
+   * typo — and it restores itself when the test ends.
+   */
+  function stubBatch(options: Parameters<typeof installStubTranscribe>[0] = {}) {
+    return installStubTranscribe({ audioUrl: "https://cdn.example/abc", ...options }).calls;
   }
 
   test("uploadToProvider streams the file and answers with the provider's URL", async () => {
     publishRecording(new Uint8Array(5000), "standup.wav");
-    const calls = stubBatch(() => ({ body: { upload_url: "https://cdn.example/abc" } }));
+    const calls = stubBatch();
     await expect(uploadToProvider(UPLOAD_ID)).resolves.toEqual({
       audioUrl: "https://cdn.example/abc",
     });
@@ -780,9 +743,9 @@ describe("the async flow", () => {
 
   test("the file is STREAMED, so a step never holds a whole recording", async () => {
     publishRecording(new Uint8Array(5000), "standup.wav");
-    const calls = stubBatch(() => ({ body: { upload_url: "https://cdn.example/abc" } }));
+    const calls = stubBatch();
     await uploadToProvider(UPLOAD_ID);
-    // `stubStepFetch` drains a streaming body into bytes, so what this asserts is that
+    // The fake drains a streaming body into bytes, so what this asserts is that
     // every byte went out — the streaming is what keeps a gigabyte off the heap, and
     // the bytes arriving intact is what says the windowing is right.
     const sent = calls[0]?.body;
@@ -795,7 +758,7 @@ describe("the async flow", () => {
     // thing five times and re-uploaded 24 MB on each attempt. The split is what makes
     // a retry of the cheap half cost the cheap half.
     publishRecording(new Uint8Array(5000));
-    const calls = stubBatch(() => ({ status: 400, body: { error: "bad field" } }));
+    const calls = stubBatch({ failure: { leg: "submit", status: 400, message: "bad field" } });
     await expect(createJob("https://cdn.example/abc")).rejects.toBeInstanceOf(FatalError);
     // One call, and it is not the upload.
     expect(calls).toHaveLength(1);
@@ -804,7 +767,7 @@ describe("the async flow", () => {
 
   test("createJob asks for `speech_models`, plural — the singular field is a 400", async () => {
     publishRecording(new Uint8Array(10));
-    const calls = stubBatch(() => ({ body: { id: "tr_1" } }));
+    const calls = stubBatch({ jobIdPrefix: "tr_" });
     await expect(createJob("https://cdn.example/abc")).resolves.toEqual({ id: "tr_1" });
     const sent = JSON.parse(String(calls[0]?.body)) as Record<string, unknown>;
     // The async API deprecated `speech_model` and answers 400 for any current model
@@ -816,48 +779,62 @@ describe("the async flow", () => {
 
   test("a job the provider gave up on is TERMINAL, not polled forever", async () => {
     publishRecording(new Uint8Array(10));
-    stubBatch(() => ({ body: { status: "error", error: "audio too quiet" } }));
+    stubBatch({ jobError: "audio too quiet" });
     // The provider has decided; no number of polls changes it, so this must not come
     // back as "not done yet".
-    await expect(pollTranscript("tr_1")).rejects.toBeInstanceOf(FatalError);
+    await expect(pollTranscript(UPLOAD_ID, "tr_1", STARTED_AT)).rejects.toBeInstanceOf(FatalError);
   });
 
   test("pollTranscript answers `done` on completed and not before", async () => {
     publishRecording(new Uint8Array(10));
-    stubBatch(() => ({ body: { status: "processing" } }));
-    await expect(pollTranscript("tr_1")).resolves.toEqual({ done: false, status: "processing" });
+    stubBatch({ pendingPolls: 1 });
+    await expect(pollTranscript(UPLOAD_ID, "tr_1", STARTED_AT)).resolves.toEqual({ done: false });
   });
 
   test("an unknown status is NOT done, so a new one cannot end a run early", async () => {
     publishRecording(new Uint8Array(10));
-    stubBatch(() => ({ body: {} }));
-    await expect(pollTranscript("tr_1")).resolves.toMatchObject({ done: false });
+    // Raw rather than `stubTranscribe`: a body with no status at all is not a
+    // shape the fake can stage, and it is the whole point of this spec.
+    installStubStepFetch(() => ({ body: {} }));
+    await expect(pollTranscript(UPLOAD_ID, "tr_1", STARTED_AT)).resolves.toMatchObject({
+      done: false,
+    });
   });
 
-  test("readTranscript reports the provider's own duration and ONE segment", async () => {
+  test("a completed poll carries the transcript — ONE request, not two", async () => {
     publishRecording(new Uint8Array(10), "standup.wav");
-    stubBatch(() => ({ body: { text: "  hello there  ", audio_duration: 12.5 } }));
-    await expect(readTranscript(UPLOAD_ID, "tr_1", STARTED_AT)).resolves.toMatchObject({
-      source: "standup.wav",
-      // Not a fudge: the async API transcribed the recording in one piece, which is
-      // the difference this flow is here to show.
-      segments: 1,
-      durationMs: 12_500,
-      words: 2,
-      transcript: "hello there",
+    // It used to poll for a status and then fetch the identical URL again for the
+    // text the poll already had in its hand.
+    const calls = stubBatch({ text: "  hello there  ", durationSec: 12.5 });
+    await expect(pollTranscript(UPLOAD_ID, "tr_1", STARTED_AT)).resolves.toMatchObject({
+      done: true,
+      transcript: {
+        source: "standup.wav",
+        // Not a fudge: the async API transcribed the recording in one piece, which is
+        // the difference this flow is here to show.
+        segments: 1,
+        durationMs: 12_500,
+        words: 2,
+        transcript: "hello there",
+      },
     });
+    expect(calls).toHaveLength(1);
   });
 
   test("a rate limit is RETRYABLE, so a busy minute does not fail the run", async () => {
     publishRecording(new Uint8Array(10));
-    stubBatch(() => ({ status: 429, body: { error: "slow down" } }));
-    await expect(pollTranscript("tr_1")).rejects.toBeInstanceOf(RetryableError);
+    stubBatch({ failure: { leg: "poll", status: 429, message: "slow down" } });
+    await expect(pollTranscript(UPLOAD_ID, "tr_1", STARTED_AT)).rejects.toBeInstanceOf(
+      RetryableError,
+    );
   });
 
   test("all three flows report the same SHAPE, which is what lets one page render any", async () => {
     publishRecording(new Uint8Array(10), "standup.wav");
-    stubBatch(() => ({ body: { text: "hi", audio_duration: 1 } }));
-    const batched = await readTranscript(UPLOAD_ID, "tr_1", STARTED_AT);
+    stubBatch({ text: "hi", durationSec: 1 });
+    const progress = await pollTranscript(UPLOAD_ID, "tr_1", STARTED_AT);
+    if (!progress.done) return expect.fail("the stub reports a completed job");
+    const batched = progress.transcript;
     // One key set, so the page's summary line renders every flow's output. A field on
     // one flow and not the others is a panel that shows it for some runs and not
     // others, with nothing saying why.
@@ -873,3 +850,149 @@ describe("the async flow", () => {
     expect(batched.elapsedMs).toBeGreaterThan(0);
   });
 });
+
+describe("normalizing the recording", () => {
+  /**
+   * The CONVERSION is not driven here, and the reason is the tier rather than the
+   * code: it spawns ffmpeg and writes a temp file, neither of which a unit test
+   * may do. What is reachable is everything that DECIDES — whether a file needs
+   * converting at all, and how a conversion's failure is classified — and those
+   * are the two places a mistake is silent. A file wrongly passed through fails
+   * later in `splitRecording` with a message about a header; a `timeout`
+   * classified as fatal is a run that gives up on work that would have finished.
+   */
+  test("a canonical WAV is cuttable, so the desk converts nothing", () => {
+    expect(cuttable(wavFile(MONO_16K, 32_000), 44 + 32_000)).toBe(true);
+  });
+
+  test("an extra chunk before the samples is still cuttable", () => {
+    // The `LIST`-chunk case, which is the reason the probe window is 64 KB rather
+    // than 44 bytes: a file the walk CAN read must not be re-encoded.
+    const head = wavFile(MONO_16K, 32_000, { extraChunk: "recorder" });
+    expect(cuttable(head, head.length + 32_000)).toBe(true);
+  });
+
+  test("an m4a is not, which is what puts ffmpeg in the path", () => {
+    // An MPEG-4 `ftyp` box — what a phone recording really starts with.
+    const m4a = new Uint8Array([
+      0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x4d, 0x34, 0x41, 0x20, 0, 0, 0, 0,
+    ]);
+    expect(cuttable(m4a, 4_000_000)).toBe(false);
+  });
+
+  test("a WAV whose encoding is not linear PCM is not", () => {
+    // The case an `ffprobe`-based check gets WRONG, which is why the check is
+    // `parseWav` itself: this file reports a PCM codec to ffprobe and is refused
+    // by the parser, so a probe would pass it through and the cut would fail.
+    const extensible = wavFile(MONO_16K, 32_000);
+    new DataView(extensible.buffer).setUint16(20, 0xff_fe, true);
+    expect(cuttable(extensible, 44 + 32_000)).toBe(false);
+  });
+
+  test("a WAV too dense to cut is not, and downsampling is what repairs it", () => {
+    // Past `MAX_BYTES_PER_SECOND`, so `parseWav` refuses it — and a conversion to
+    // 16 kHz mono makes it cuttable, which is a fix the desk gets for free from
+    // asking the parser rather than asking about the codec.
+    const dense = wavFile({ sampleRate: 4_000_000, channels: 8, bitsPerSample: 32 }, 32_000);
+    expect(cuttable(dense, 44 + 32_000)).toBe(false);
+  });
+
+  test("an already-cuttable recording keeps the id it came in under", async () => {
+    // The property that matters: no second upload, so the fan-out reads the file
+    // the caller stored. A step that copied it would double the storage every run
+    // pays for and would still report success.
+    publishRecording(wavFile(MONO_16K, 32_000), "standup.wav");
+    const reporter = installStubReporter();
+    await expect(normalizeRecording(UPLOAD_ID)).resolves.toEqual({
+      recording: UPLOAD_ID,
+      converted: false,
+    });
+    expect(reporter.lines.join(" ")).toContain("already linear-PCM WAV");
+  });
+
+  // The ffmpeg VERDICT is no longer tested here, and its absence is the change
+  // rather than a gap: `throwFfmpegStepError` on `@alexkroman1/aai/step-errors`
+  // owns it now, with every arm pinned in `sdk/step-errors.test.ts` — a refused
+  // file, a missing binary, a timeout rethrown UNCHANGED so its `argv` survives,
+  // and a cause that is not an ffmpeg failure at all. What stays above is what is
+  // still this desk's: WHICH files it decides to convert.
+});
+
+describe("expectedSegments", () => {
+  /** A plan over 16 kHz mono, cut into three 90-second segments. */
+  const PLAN = {
+    format: { ...MONO_16K, dataStart: 44, dataEnd: 44 + 270 * 32_000 },
+    segments: [0, 1, 2].map((index) => ({
+      index,
+      start: 44 + index * 90 * 32_000,
+      end: 44 + (index + 1) * 90 * 32_000,
+      startMs: index * 90_000,
+      endMs: (index + 1) * 90_000,
+    })),
+  };
+
+  test("counts every segment once the whole recording has arrived", () => {
+    expect(expectedSegments(PLAN, PLAN.format.dataEnd)).toBe(3);
+  });
+
+  test("ignores segments that start past the end of a SHORT upload", () => {
+    // The failure this guards is a run that never ENDS rather than one that fails:
+    // the plan came from the header's declared length, so a recording that came up
+    // short has segments beginning past the last byte, and waiting for them is
+    // waiting for audio nobody is going to send.
+    expect(expectedSegments(PLAN, 44 + 100 * 32_000)).toBe(2);
+    expect(expectedSegments(PLAN, 44 + 1)).toBe(1);
+  });
+
+  test("an upload with nothing in it expects no segments at all", () => {
+    expect(expectedSegments(PLAN, 0)).toBe(0);
+  });
+});
+
+describe("the conversion, up to the spawn", () => {
+  /**
+   * Reaches the point where ffmpeg would run and stops there, DETERMINISTICALLY.
+   *
+   * `AAI_FFPROBE_PATH` names the binary the SDK resolves, so pointing it at a path
+   * that does not exist produces `kind: "missing-binary"` on every machine — one
+   * where ffmpeg is installed, one where it is not, and CI's Linux leg alike. A
+   * test that instead relied on ffmpeg being ABSENT would pass on a laptop and
+   * behave differently in CI.
+   *
+   * What it covers is the whole step up to the subprocess: reading the header,
+   * deciding the file needs converting, and materializing it to a temp file. Plus
+   * the behaviour a developer actually meets — `aai dev` with no ffmpeg is the one
+   * place dev/prod parity is partial, and it must fail FATALLY with an installable
+   * remedy rather than burn five attempts on a binary that will not appear.
+   */
+  test("materializes the recording, then fails fatally with no ffprobe", async () => {
+    vi.stubEnv("AAI_FFPROBE_PATH", "/nonexistent/aai-test/ffprobe");
+    vi.stubEnv("AAI_FFMPEG_PATH", "/nonexistent/aai-test/ffmpeg");
+    // An m4a `ftyp` box, so `cuttable` says no and the conversion path is taken.
+    publishRecording(
+      new Uint8Array([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x4d, 0x34, 0x41, 0x20]),
+      "standup.m4a",
+    );
+    const reporter = installStubReporter();
+    // Fatal, not retryable: four more attempts find the same missing binary, and
+    // the message already carries the install instructions.
+    await expect(normalizeRecording(UPLOAD_ID)).rejects.toThrow(/ffprobe/);
+    await expect(normalizeRecording(UPLOAD_ID)).rejects.toBeInstanceOf(FatalError);
+    // It got as far as deciding the file needs converting — the failure is the
+    // binary, not the input.
+    expect(reporter.lines.join(" ")).toContain("standup.m4a");
+    expect(normalizeRecording.maxRetries).toBe(5);
+  });
+
+  test("leaves no temp directory behind when the conversion fails", async () => {
+    // The `finally`, on the path that matters: a guest's disk is small, and a step
+    // that leaked a directory per failed run would fill it.
+    vi.stubEnv("AAI_FFPROBE_PATH", "/nonexistent/aai-test/ffprobe");
+    const leaked = (names: string[]) => names.filter((n) => n.startsWith("aai-normalize-"));
+    const before = leaked(await readdir(tmpdir()));
+    publishRecording(new Uint8Array([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70]), "standup.m4a");
+    installStubReporter();
+    await expect(normalizeRecording(UPLOAD_ID)).rejects.toBeInstanceOf(FatalError);
+    expect(leaked(await readdir(tmpdir()))).toEqual(before);
+  });
+});

package/dist/templates/transcription-workflow/agent.ts

@@ -16,15 +16,19 @@
  * - **`ASSEMBLYAI_API_KEY` in the agent env** — `.env` under `aai dev`,
  *   `aai secret put ASSEMBLYAI_API_KEY` once deployed. `requiredEnv` below is
  *   what makes a deploy check for it rather than letting the first run find out.
- *   A step reads it with `requireStepEnv`; see `@alexkroman1/aai/utils`.
+ *   A step reads it with `requireStepEnv`; see `@alexkroman1/aai/step`.
  * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
  *   `DATABASE_URL` under `aai dev`). REQUIRED here, unlike most workflow apps:
  *   a run survives without it, but an UPLOAD's record is a row, so the form
  *   below refuses by name until storage is on.
- * - **A linear-PCM WAV.** The cutting is arithmetic over byte offsets, which is
- *   only possible on uncompressed audio; `workflows/wav.ts` says so in more
- *   detail, and an unsupported file fails the run by name with the `ffmpeg`
- *   line that fixes it.
+ * - **ffmpeg, under `aai dev` only.** A deployed guest's image installs it; on a
+ *   laptop it is whatever is on `PATH` (or `AAI_FFMPEG_PATH`). The `transcribe`
+ *   flow needs it for anything that is not already a linear-PCM WAV, because the
+ *   cutting is arithmetic over byte offsets and that is only possible on
+ *   uncompressed audio — `workflows/normalize.ts` is the conversion and
+ *   `workflows/wav.ts` is why it has to happen. A WAV needs no ffmpeg at all,
+ *   and `transcribeStream` never uses it: a recording that is still uploading is
+ *   not something a decoder can be pointed at.
  *
  * ## The recording is UPLOADED, and the run carries its id
  *
@@ -49,7 +53,8 @@
  * | client sends | `POST /uploads` | `PUT /uploads/<id>` | `POST /uploads` |
  * | shape | plan, fan out, merge | poll, fan out, merge | submit, poll, read |
  * | client hook | `useWorkflowSubmit` | `useWorkflowStream` | `useWorkflowSubmit` |
- * | accepts | linear-PCM WAV | linear-PCM WAV | **any audio** |
+ * | accepts | **any audio** | linear-PCM WAV | **any audio** |
+ * | converts first | when it must | never | not needed |
  * | segments | 7 for 10 minutes | 7 | **1** |
  *
  * The first two are the same fan-out arranged two ways, and the difference between
@@ -102,7 +107,12 @@ export const transcribe = workflow({
   input: z.object({
     // A plain string, because an upload id is what the run really receives. What
     // makes it a file picker rather than a text box is the `uploads` line below.
-    recording: z.string().describe("A linear-PCM WAV recording (16-bit or 8-bit, any rate)"),
+    //
+    // It says "any recording" now, and that is the whole of what
+    // `workflows/normalize.ts` bought: this used to name linear-PCM WAV and mean
+    // it, so the desk's real front door was a sentence telling the caller to run
+    // ffmpeg themselves. The cut still needs WAV — the run makes one.
+    recording: z.string().describe("Any recording — WAV, MP3, M4A, or a video's audio track"),
   }),
   // The one line that makes the form take a file: `<WorkflowFields>` renders a
   // picker for this property, `useWorkflowSubmit` stores the chosen file, and
@@ -128,6 +138,10 @@ export const transcribe = workflow({
 export const transcribeStream = workflow({
   description: "Transcribe a recording while it is still uploading",
   input: z.object({
+    // Still WAV, and this is the one flow where that is not a limitation to be
+    // fixed: it cuts the recording while the bytes are arriving, and a partial
+    // file is not something ffmpeg can transcode. `transcribe` converts because
+    // it has the whole file before it plans anything.
     recording: z.string().describe("A linear-PCM WAV recording (16-bit or 8-bit, any rate)"),
   }),
   uploads: ["recording"],