@alexkroman1/aai-cli 6.10.1 → 6.11.0

package/dist/templates/call-audit/agent.test.ts

@@ -0,0 +1,965 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Specs for the audit desk's declaration, its ffmpeg argv, the two analyses it
+ * reads back, and where it decides to cut.
+ *
+ * **The pipeline is not driven end to end here, and that is the tier rather than
+ * a gap.** A unit test may not spawn a subprocess or write a file, so the three
+ * steps that run ffmpeg cannot be. What CAN be — and what this file therefore
+ * spends most of its lines on — is everything those steps decide, because
+ * `media.ts` exists precisely to hold it: the argv is a pure function, so it is a
+ * value to assert on rather than a string buried in a step; and both analyses are
+ * parsed by pure functions, so ffmpeg's real output can be a fixture.
+ *
+ * The fixtures below are **captured from ffmpeg 6.1.1**, verbatim, by running the
+ * argv these functions build. That matters more than it usually would: every field
+ * here is a string ffmpeg chose (`"input_i" : "-16.19"`, tabs and spaces included),
+ * so a fixture somebody typed from the documentation would be a spec that passes
+ * against a parser no real recording can satisfy.
+ *
+ * What the ffmpeg steps get instead is the two things a spec can still reach: the
+ * argv they will run, and the classification of a failure — which is where a
+ * mistake is silent, since a `timeout` called fatal is a run that gives up on work
+ * that would have finished.
+ */
+
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FfmpegError } from "@alexkroman1/aai/ffmpeg";
+import { stubReporter, stubSpeech, stubStepFetch, stubUploads } from "@alexkroman1/aai/testing";
+import { installStubGateway } from "@alexkroman1/aai/testing/vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { FatalError, RetryableError } from "workflow";
+import agentDef, { audit } from "./agent.ts";
+import {
+  countWords,
+  joinSegments,
+  now,
+  SEGMENT_CONCURRENCY,
+  transcribeSegment,
+} from "./workflows/audit.ts";
+import { analyse, classifyFfmpeg, ingestRecording } from "./workflows/ingest.ts";
+import {
+  ANALYSIS_FORMAT,
+  BYTES_PER_SECOND,
+  clock,
+  durationSeconds,
+  type Loudness,
+  MAX_SEGMENT_SECONDS,
+  MediaAnalysisError,
+  MIN_SILENCE_SECONDS,
+  masterArgs,
+  measureLoudnessArgs,
+  normalizeArgs,
+  parseLoudness,
+  parseSilences,
+  planSegments,
+  type Silence,
+  speechFraction,
+} from "./workflows/media.ts";
+import { narrate, summarize } from "./workflows/summarize.ts";
+import { fileChunks, materializeUpload, withTempDir } from "./workflows/temp-media.ts";
+
+/** The id every spec below uploads under. */
+const UPLOAD_ID = "upl_test";
+
+/**
+ * `loudnorm`'s first pass, exactly as ffmpeg 6.1.1 printed it to stderr.
+ *
+ * Kept verbatim — the leading log line, the blank line, the tab indentation, and
+ * every value as a STRING. Two of those are load-bearing: the parser has to FIND
+ * the block rather than assume the text starts with it, and it has to coerce
+ * strings rather than read numbers.
+ */
+const LOUDNORM_STDERR = `[Parsed_loudnorm_0 @ 0x558882c84140]
+{
+\t"input_i" : "-16.19",
+\t"input_tp" : "-7.42",
+\t"input_lra" : "4.80",
+\t"input_thresh" : "-26.34",
+\t"output_i" : "-16.13",
+\t"output_tp" : "-7.48",
+\t"output_lra" : "4.80",
+\t"output_thresh" : "-26.26",
+\t"normalization_type" : "dynamic",
+\t"target_offset" : "0.13"
+}
+`;
+
+/**
+ * What `ametadata=mode=print:file=…` wrote for a 20-second recording, verbatim.
+ *
+ * Two things about it are the whole reason `parseSilences` is not a two-line
+ * regex, and both were verified rather than assumed:
+ *
+ * - The event times are NOT the frame's `pts_time`. `silence_start=3` sits on a
+ *   frame at 3.599, because the filter needed 0.6s of silence to be sure.
+ * - The LAST event has no `silence_end`. The recording ended during a pause, so
+ *   the filter never saw the sound come back.
+ */
+const SILENCE_LOG = `frame:155  pts:158720  pts_time:3.59909
+lavfi.silence_start=3
+frame:215  pts:220160  pts_time:4.99229
+lavfi.silence_end=5.00005
+lavfi.silence_duration=2.00005
+frame:370  pts:378880  pts_time:8.59138
+lavfi.silence_start=7.99998
+frame:430  pts:440320  pts_time:9.98458
+lavfi.silence_end=10
+lavfi.silence_duration=2.00007
+frame:585  pts:599040  pts_time:13.5837
+lavfi.silence_start=13
+frame:645  pts:660480  pts_time:14.9769
+lavfi.silence_end=15
+lavfi.silence_duration=2.00007
+frame:801  pts:820224  pts_time:18.5992
+lavfi.silence_start=18
+`;
+
+/**
+ * Bytes the real normalize pass wrote for the recording {@link SILENCE_LOG} came
+ * from, and the exact seconds that is.
+ *
+ * Not 20 seconds: AAC carries encoder priming samples, so decoding a nominally
+ * 20-second file yields 20.015625. The difference is small and it is the whole
+ * reason `planSegments` takes a byte count — see `durationSeconds`.
+ */
+const REAL_PCM_BYTES = 640_500;
+const EXACT_SECONDS = durationSeconds(REAL_PCM_BYTES);
+
+/** The measurement above, parsed — the input the second pass's argv is built from. */
+const MEASURED: Loudness = {
+  inputLufs: -16.19,
+  inputTruePeak: -7.42,
+  inputRange: 4.8,
+  inputThreshold: -26.34,
+  targetOffset: 0.13,
+};
+
+/**
+ * The bytes one stubbed request carried, ASSERTED rather than cast.
+ *
+ * A `throw` returns `never`, so this narrows without an `as Uint8Array` — and the
+ * cast is what a first draft reaches for, which Biome then rejects as unsafe
+ * optional chaining, because a missing call would throw on `.byteLength` rather
+ * than fail with a message. A typed seam is the repo's remedy for a concentration
+ * of identical casts, and two is where it starts paying.
+ *
+ * A bare `throw` rather than `expect.fail`, which is the shape the repo prefers in
+ * a test BODY and which Biome's `noMisplacedAssertion` forbids in a helper — an
+ * assertion outside a `test()` is a real hazard, and here the throw is doing type
+ * narrowing rather than making a claim.
+ */
+function sentBytes(body: unknown): Uint8Array {
+  if (!(body instanceof Uint8Array)) {
+    throw new TypeError("the stub records a Uint8Array request body");
+  }
+  return body;
+}
+
+/** A pause at each of `starts`, each exactly long enough to be a candidate. */
+function pauses(...starts: number[]): Silence[] {
+  return starts.map((startSec) => ({ startSec, endSec: startSec + MIN_SILENCE_SECONDS }));
+}
+
+/** Slots left published reach the next file, so every one is released here. */
+const restores: (() => void)[] = [];
+afterEach(() => {
+  while (restores.length > 0) restores.pop()?.();
+});
+
+beforeEach(() => {
+  // The step env, which is where `requireStepEnv`, `stepSpeak` and the gateway
+  // read the key. `vi.stubEnv` rather than an assignment: `unstubEnvs` undoes it
+  // before every test, so nothing here has to remember to put it back.
+  vi.stubEnv("ASSEMBLYAI_API_KEY", "test-key");
+});
+
+describe("the declaration", () => {
+  test("is a workflow app with the one workflow the page starts by name", () => {
+    // The page calls `api.start("audit", …)`, so a rename here is a runtime 400
+    // rather than a compile error. This is what pins it.
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["audit"]);
+    expect(agentDef.page).toBe("static");
+  });
+
+  test("declares no providers and exactly the one credential its steps read", () => {
+    // A workflow app has no session, so nothing else in its config could name one
+    // — and one AssemblyAI key covers transcription, the model and the voice.
+    // Note what is NOT here: ffmpeg. `requiredEnv` checks the environment, and a
+    // binary on `PATH` is not an environment variable.
+    expect(agentDef.requiredEnv).toEqual(["ASSEMBLYAI_API_KEY"]);
+  });
+
+  test("takes the recording as an UPLOAD, which is what makes the form a file picker", () => {
+    expect(audit.uploads).toEqual(["recording"]);
+  });
+
+  test("offers real voice ids, so the synthesis cannot fail silently in band", async () => {
+    // A wrong voice is accepted by the socket and refused in band, so the schema
+    // is the only thing that can catch one. The list is read from the SDK catalog.
+    expect(
+      (await audit.input?.["~standard"].validate({ recording: UPLOAD_ID, voice: "not-a-voice" }))
+        ?.issues,
+    ).toBeTruthy();
+    expect(
+      (await audit.input?.["~standard"].validate({ recording: UPLOAD_ID, voice: "jane" }))?.issues,
+    ).toBeUndefined();
+  });
+
+  test("accepts a recording with no voice chosen, so the SDK default applies", async () => {
+    expect(
+      (await audit.input?.["~standard"].validate({ recording: UPLOAD_ID }))?.issues,
+    ).toBeUndefined();
+  });
+});
+
+describe("the ffmpeg argv", () => {
+  test("every invocation is quiet, non-interactive, and overwrites", () => {
+    // `-nostdin` is the one that matters in a guest: an ffmpeg that decides to
+    // read stdin is a process that never exits.
+    for (const argv of [
+      measureLoudnessArgs("in.m4a"),
+      normalizeArgs("in.m4a", MEASURED, "out.pcm", "silence.txt"),
+      masterArgs("spoken.wav", "out.mp3"),
+    ]) {
+      expect(argv).toEqual(expect.arrayContaining(["-hide_banner", "-nostats", "-nostdin", "-y"]));
+    }
+  });
+
+  test("the measure pass writes no audio and asks for JSON", () => {
+    const argv = measureLoudnessArgs("in.m4a");
+    // `-f null -` is what makes this cost a decode and produce five numbers.
+    expect(argv.slice(-3)).toEqual(["-f", "null", "-"]);
+    expect(argv.join(" ")).toContain("print_format=json");
+  });
+
+  test("the measure pass runs at `info`, because that is where the JSON is printed", () => {
+    // The failure this pins is silent: at `-loglevel error` the pass still runs
+    // and still succeeds, and prints nothing at all — which reads as a parser bug.
+    const argv = measureLoudnessArgs("in.m4a");
+    expect(argv[argv.indexOf("-loglevel") + 1]).toBe("info");
+  });
+
+  test("the normalize pass stays quiet, because its analysis goes to a FILE", () => {
+    const argv = normalizeArgs("in.m4a", MEASURED, "out.pcm", "silence.txt");
+    expect(argv[argv.indexOf("-loglevel") + 1]).toBe("error");
+    // `ametadata` writes the path directly rather than through the log, which is
+    // the property that lets this pass be both silent and complete.
+    expect(argv.join(" ")).toContain("ametadata=mode=print:file=silence.txt");
+  });
+
+  test("the normalize pass feeds back every measured value", () => {
+    // A missing `measured_*` makes loudnorm silently run a ONE-pass normalization
+    // instead — no error, just a different result — so all five are pinned.
+    const filter = normalizeArgs("in.m4a", MEASURED, "out.pcm", "silence.txt").join(" ");
+    expect(filter).toContain("measured_I=-16.19");
+    expect(filter).toContain("measured_TP=-7.42");
+    expect(filter).toContain("measured_LRA=4.8");
+    expect(filter).toContain("measured_thresh=-26.34");
+    expect(filter).toContain("offset=0.13");
+    // One constant gain rather than a moving one, so speech does not pump.
+    expect(filter).toContain("linear=true");
+  });
+
+  test("the normalize pass writes HEADERLESS PCM in the analysis format", () => {
+    // The decision the whole template rests on: `-f s16le`, not `-f wav`, so byte
+    // zero is second zero and nothing has to parse a RIFF chunk list.
+    const argv = normalizeArgs("in.m4a", MEASURED, "out.pcm", "silence.txt");
+    expect(argv.slice(-3)).toEqual(["-f", "s16le", "out.pcm"]);
+    expect(argv[argv.indexOf("-ar") + 1]).toBe(String(ANALYSIS_FORMAT.sampleRate));
+    expect(argv[argv.indexOf("-ac") + 1]).toBe(String(ANALYSIS_FORMAT.channels));
+    expect(argv[argv.indexOf("-c:a") + 1]).toBe("pcm_s16le");
+  });
+
+  test("the filter chain is ONE argv element, so its commas never meet a shell", () => {
+    // `runFfmpeg` spawns without a shell, which is what makes an unquoted filter
+    // graph safe — and what would break if this were ever assembled into a string.
+    const argv = normalizeArgs("in.m4a", MEASURED, "out.pcm", "silence.txt");
+    const filter = argv[argv.indexOf("-af") + 1] ?? "";
+    expect(filter).toContain(",silencedetect=");
+    expect(filter.startsWith("loudnorm=")).toBe(true);
+  });
+
+  test("the mastering pass encodes MP3, which is the point of running it", () => {
+    const argv = masterArgs("spoken.wav", "out.mp3");
+    expect(argv[argv.indexOf("-c:a") + 1]).toBe("libmp3lame");
+    expect(argv.at(-1)).toBe("out.mp3");
+  });
+});
+
+describe("reading the loudness measurement", () => {
+  test("parses ffmpeg's own block, strings and all", () => {
+    expect(parseLoudness(LOUDNORM_STDERR)).toEqual(MEASURED);
+  });
+
+  test("finds the block after whatever info-level chatter preceded it", () => {
+    // The pass runs at `-loglevel info`, so the captured stderr tail holds stream
+    // descriptions and a muxing-overhead line before the JSON.
+    const noisy = `  Stream #0:0(und): Audio: pcm_s16le, 192000 Hz, mono\nsize=N/A time=00:00:17.20\n${LOUDNORM_STDERR}`;
+    expect(parseLoudness(noisy)).toEqual(MEASURED);
+  });
+
+  test("takes the LAST block, so a retried pass reads its own numbers", () => {
+    const twice = LOUDNORM_STDERR + LOUDNORM_STDERR.replace('"-16.19"', '"-20.50"');
+    expect(parseLoudness(twice).inputLufs).toBe(-20.5);
+  });
+
+  test("names the missing `-loglevel info` when nothing was printed", () => {
+    // The most likely way this breaks, so the message says how to fix it rather
+    // than reporting a parse failure.
+    expect(() => parseLoudness("size=N/A time=00:00:17.20\n")).toThrow(MediaAnalysisError);
+    expect(() => parseLoudness("")).toThrow(/-loglevel info/);
+  });
+
+  test("names the KEY when a value is missing or unparseable", () => {
+    // A silent `NaN` would flow into the second pass's argv as the literal text
+    // `NaN` and come back as an ffmpeg option-parsing error about a filter.
+    const missing = LOUDNORM_STDERR.replace('"input_tp" : "-7.42",', "");
+    expect(() => parseLoudness(missing)).toThrow(/input_tp/);
+  });
+
+  test("refuses a block that is not JSON at all", () => {
+    expect(() => parseLoudness("[loudnorm] {not json}")).toThrow(MediaAnalysisError);
+  });
+});
+
+describe("reading the pauses", () => {
+  test("parses every event ffmpeg logged, and closes the unterminated one", () => {
+    // The trailing `silence_start=18` has no `silence_end` — the recording ended
+    // during the pause. It is closed at the duration, which is why this function
+    // takes one.
+    expect(parseSilences(SILENCE_LOG, EXACT_SECONDS)).toEqual([
+      { startSec: 3, endSec: 5.000_05 },
+      { startSec: 7.999_98, endSec: 10 },
+      { startSec: 13, endSec: 15 },
+      { startSec: 18, endSec: EXACT_SECONDS },
+    ]);
+  });
+
+  test("reads the EVENT time, not the frame's", () => {
+    // `silence_start=3` sits on a frame at `pts_time:3.59909`. Reading the frame
+    // would put every cut 0.6s late and lose the word before it.
+    const [first] = parseSilences(SILENCE_LOG, EXACT_SECONDS);
+    expect(first?.startSec).toBe(3);
+  });
+
+  test("an empty log is no pauses, not a failure", () => {
+    // Verified against ffmpeg 6.1: `ametadata` creates the file at filter-init, so
+    // a recording with no pause in it leaves an empty log rather than none.
+    expect(parseSilences("", 30)).toEqual([]);
+  });
+
+  test("a pause that never ended before a recording that already did is dropped", () => {
+    // `durationSec` is measured from the PCM byte count and the log from the same
+    // pass, so they agree — but a zero-length pause would produce a cut candidate
+    // at the very end, which `planSegments` would then have to reject.
+    expect(parseSilences("lavfi.silence_start=30\n", 30)).toEqual([]);
+  });
+
+  test("an end without a start is ignored rather than inventing a pause at zero", () => {
+    expect(parseSilences("lavfi.silence_end=4\n", 30)).toEqual([]);
+  });
+
+  test("a truncated numeric value is skipped rather than read as NaN", () => {
+    // A `NaN` boundary would make every downstream comparison false, so the cut
+    // planner would silently fall back to blind cuts for the whole recording.
+    expect(parseSilences("lavfi.silence_start=\nlavfi.silence_end=4\n", 30)).toEqual([]);
+  });
+});
+
+describe("planning where to cut", () => {
+  test("a recording inside the cap is one segment, whatever its pauses", () => {
+    // Nothing to decide, and the pauses must not tempt the planner into cutting: a
+    // request per pause would be dozens of requests for a two-minute call.
+    const segments = planSegments(pauses(10, 20, 30), 60 * BYTES_PER_SECOND);
+    expect(segments).toHaveLength(1);
+    expect(segments[0]).toMatchObject({ index: 0, startByte: 0, startMs: 0, endMs: 60_000 });
+    expect(segments[0]?.endByte).toBe(60 * BYTES_PER_SECOND);
+  });
+
+  test("cuts at the LAST pause that still fits, not the first", () => {
+    // Greedy from the front, so segments are as long as the cap allows — the
+    // alternative is twice as many requests for the same audio.
+    const segments = planSegments(pauses(30, 60, 100), 150 * BYTES_PER_SECOND);
+    // The pause at 100 spans 100–100.6, so its midpoint is 100.3.
+    expect(segments.map((s) => s.endMs)).toEqual([100_300, 150_000]);
+  });
+
+  test("the cut is the pause's MIDPOINT, so neither side is clipped", () => {
+    // Cutting at the start clips the decay of the word before; cutting at the end
+    // clips the attack of the word after.
+    const segments = planSegments([{ startSec: 100, endSec: 101 }], 150 * BYTES_PER_SECOND);
+    expect(segments[0]?.endMs).toBe(100_500);
+  });
+
+  test("segments are contiguous and non-overlapping, which is what deletes the stitcher", () => {
+    const segments = planSegments(pauses(50, 100, 160, 210), 260 * BYTES_PER_SECOND);
+    expect(segments.length).toBeGreaterThan(1);
+    for (const [i, segment] of segments.entries()) {
+      if (i === 0) continue;
+      expect(segment.startByte).toBe(segments[i - 1]?.endByte);
+      expect(segment.startMs).toBe(segments[i - 1]?.endMs);
+    }
+    expect(segments[0]?.startByte).toBe(0);
+    expect(segments.at(-1)?.endByte).toBe(260 * BYTES_PER_SECOND);
+  });
+
+  test("no segment exceeds the endpoint's cap", () => {
+    const segments = planSegments(pauses(20, 40, 61, 130, 200), 400 * BYTES_PER_SECOND);
+    for (const segment of segments) {
+      expect(segment.endMs - segment.startMs).toBeLessThanOrEqual(MAX_SEGMENT_SECONDS * 1000);
+    }
+  });
+
+  test("an unbroken monologue falls back to a blind cut, and SAYS so", () => {
+    // The case the pretty invariant cannot serve. Refusing it would be the worse
+    // trade, so it degrades to exactly what `transcription-workflow` does — and
+    // reports it, because a mangled word at a seam is otherwise a mystery.
+    const segments = planSegments([], 300 * BYTES_PER_SECOND);
+    expect(segments).toHaveLength(3);
+    expect(segments.map((s) => s.endMs)).toEqual([110_000, 220_000, 300_000]);
+    expect(segments.map((s) => s.cutInSpeech)).toEqual([true, true, false]);
+  });
+
+  test("a cut that landed in a pause is NOT reported as a blind cut", () => {
+    const segments = planSegments(pauses(100), 150 * BYTES_PER_SECOND);
+    expect(segments.map((s) => s.cutInSpeech)).toEqual([false, false]);
+  });
+
+  test("a tail too short to be worth a request joins its predecessor", () => {
+    // The endpoint refuses audio under 80ms, and a 0.4-second tail holds at most one
+    // word — but the word is a word, so it is merged rather than dropped. A pause at
+    // 150 leaves the predecessor well short of the cap, which is what makes the merge
+    // legal; see the cap test below for when it is not.
+    const segments = planSegments(pauses(150), 200.5 * BYTES_PER_SECOND);
+    expect(segments).toHaveLength(2);
+    expect(segments.at(-1)?.endMs).toBe(200_500);
+  });
+
+  test("a short tail is NOT absorbed into a segment already at the cap", () => {
+    // The greedy loop leaves a final segment of at most `MAX_SEGMENT_SECONDS`, so
+    // merging a sub-second tail into a predecessor already at the cap would make one
+    // 110.5 seconds long — inside the endpoint's own 120-second limit, and outside
+    // the bound this module promises. A short final request is the cheaper mistake,
+    // and it is still an order of magnitude above the 80ms the endpoint refuses.
+    const segments = planSegments([], 110.5 * BYTES_PER_SECOND);
+    expect(segments).toHaveLength(2);
+    for (const segment of segments) {
+      expect(segment.endMs - segment.startMs).toBeLessThanOrEqual(MAX_SEGMENT_SECONDS * 1000);
+    }
+    // Still contiguous, still covering the whole recording.
+    expect(segments[0]?.endByte).toBe(segments[1]?.startByte);
+    expect(segments.at(-1)?.endMs).toBe(110_500);
+  });
+
+  test("every byte offset lands on a sample-frame boundary", () => {
+    // A byte offset mid-sample shifts every sample after it by one byte, which is
+    // not a click — it is white noise the decoder transcribes into confident
+    // nonsense.
+    const frame = (ANALYSIS_FORMAT.channels * ANALYSIS_FORMAT.bitsPerSample) / 8;
+    for (const segment of planSegments(pauses(37.333, 88.777, 150.5), 200 * BYTES_PER_SECOND)) {
+      expect(segment.startByte % frame).toBe(0);
+      expect(segment.endByte % frame).toBe(0);
+    }
+  });
+
+  test("an empty recording plans nothing rather than one empty request", () => {
+    expect(planSegments([], 0)).toEqual([]);
+  });
+
+  test("the real 20-second capture is one segment covering all of it", () => {
+    // End to end over the captured fixture, which is the case a reader can check
+    // against the numbers in `SILENCE_LOG`.
+    const silences = parseSilences(SILENCE_LOG, EXACT_SECONDS);
+    const segments = planSegments(silences, REAL_PCM_BYTES);
+    expect(segments).toHaveLength(1);
+    expect(segments[0]?.cutInSpeech).toBe(false);
+  });
+
+  test("the last segment never addresses a byte the file does not have", () => {
+    // The twelve-byte bug this API shape exists to prevent: planning from a
+    // duration rounded to whole milliseconds put `endByte` at 640,512 for a
+    // 640,500-byte file. `readUpload` clamps a window to the stored size, so
+    // nothing threw — the plan was simply describing audio that does not exist.
+    // Found by running the real argv against a real ffmpeg, which is the only
+    // place a twelve-byte error was ever going to surface.
+    for (const bytes of [REAL_PCM_BYTES, 32_001, 999_999, 2]) {
+      const segments = planSegments(parseSilences(SILENCE_LOG, durationSeconds(bytes)), bytes);
+      expect(segments.at(-1)?.endByte ?? 0).toBeLessThanOrEqual(bytes);
+    }
+  });
+});
+
+describe("what the page is told about the recording", () => {
+  test("speech is the complement of the pauses", () => {
+    // 20 seconds with 8 of pause in it.
+    expect(
+      Math.round(
+        speechFraction(
+          [
+            { startSec: 3, endSec: 5 },
+            { startSec: 8, endSec: 10 },
+            { startSec: 13, endSec: 15 },
+            { startSec: 18, endSec: 20 },
+          ],
+          20,
+        ) * 100,
+      ),
+    ).toBe(60);
+  });
+
+  test("a recording of pure silence is 0% speech, and one with no pause is 100%", () => {
+    expect(speechFraction([{ startSec: 0, endSec: 30 }], 30)).toBe(0);
+    expect(speechFraction([], 30)).toBe(1);
+  });
+
+  test("a zero-length recording answers 0 rather than dividing by it", () => {
+    expect(speechFraction([], 0)).toBe(0);
+  });
+
+  test("the clock grows an hours field only when there is one", () => {
+    expect(clock(0)).toBe("0:00");
+    expect(clock(9000)).toBe("0:09");
+    expect(clock(249_000)).toBe("4:09");
+    expect(clock(3_849_000)).toBe("1:04:09");
+  });
+});
+
+describe("joining the segments", () => {
+  /** Two segments whose shared boundary is `cutInSpeech` on the first. */
+  function pair(cutInSpeech: boolean) {
+    return [
+      { index: 0, startByte: 0, endByte: 10, startMs: 0, endMs: 10, cutInSpeech },
+      { index: 1, startByte: 10, endByte: 20, startMs: 10, endMs: 20, cutInSpeech: false },
+    ];
+  }
+
+  test("a cut made in a pause becomes a paragraph break", () => {
+    // The plan knows where the turn boundaries are, so the transcript can show
+    // them. This is the one place `cutInSpeech` changes an output, not a report.
+    expect(
+      joinSegments(pair(false), [
+        { index: 0, text: "Good morning." },
+        { index: 1, text: "Let us begin." },
+      ]),
+    ).toBe("Good morning.\n\nLet us begin.");
+  });
+
+  test("a blind cut is joined with a space, because it landed mid-sentence", () => {
+    expect(
+      joinSegments(pair(true), [
+        { index: 0, text: "the number was" },
+        { index: 1, text: "roughly four" },
+      ]),
+    ).toBe("the number was roughly four");
+  });
+
+  test("puts the parts in index order however they arrived", () => {
+    // `mapConcurrent` resolves in item order, so this is belt and braces — a merge
+    // is where an ordering mistake would be invisible rather than loud.
+    expect(
+      joinSegments(pair(true), [
+        { index: 1, text: "second" },
+        { index: 0, text: "first" },
+      ]),
+    ).toBe("first second");
+  });
+
+  test("a segment that transcribed to nothing leaves no stray separator", () => {
+    // A stretch that is all room tone comes back empty, and a naive join would
+    // leave a leading or doubled break in the transcript.
+    expect(
+      joinSegments(pair(false), [
+        { index: 0, text: "" },
+        { index: 1, text: "words" },
+      ]),
+    ).toBe("words");
+  });
+
+  test("counts words, or none for an empty transcript", () => {
+    expect(countWords("  two  words ")).toBe(2);
+    expect(countWords("   ")).toBe(0);
+  });
+});
+
+describe("transcribing one segment", () => {
+  /**
+   * One second of stored PCM, and a sync endpoint that answers.
+   *
+   * `stubStepFetch`, not `vi.stubGlobal("fetch", …)`: the step calls `stepFetch`,
+   * which reaches a published slot rather than the global. Stubbing the global
+   * still passes, because an unpublished slot falls back to it, and would be
+   * asserting against a path production does not take.
+   */
+  function stubProvider(answer: { status?: number; body?: unknown } = {}) {
+    restores.push(
+      stubUploads({
+        [UPLOAD_ID]: {
+          bytes: new Uint8Array(BYTES_PER_SECOND),
+          name: "call.pcm",
+          type: "application/octet-stream",
+        },
+      }),
+      stubReporter().restore,
+    );
+    const stub = stubStepFetch(() => ({
+      status: answer.status ?? 200,
+      body: answer.body ?? { text: "hello there" },
+    }));
+    restores.push(stub.restore);
+    return stub.calls;
+  }
+
+  const SEGMENT = {
+    index: 0,
+    startByte: 0,
+    endByte: BYTES_PER_SECOND,
+    startMs: 0,
+    endMs: 1000,
+    cutInSpeech: false,
+  };
+
+  test("puts a WAV header back on the headerless span before sending it", async () => {
+    // The endpoint decodes each request independently, so a slice of raw PCM is
+    // meaningless bytes until a header says what they are. `encodeWav` is the SDK's
+    // — this template deliberately carries no copy of it.
+    const calls = stubProvider();
+    await expect(transcribeSegment(UPLOAD_ID, SEGMENT)).resolves.toEqual({
+      index: 0,
+      text: "hello there",
+    });
+
+    // Inside a multipart body, so the header is not at byte zero — what matters is
+    // that it is there at all, and immediately followed by `WAVE`.
+    const sent = new TextDecoder("latin1").decode(sentBytes(calls[0]?.body));
+    expect(sent).toContain("RIFF");
+    expect(sent.indexOf("WAVE")).toBe(sent.indexOf("RIFF") + 8);
+  });
+
+  test("sends the whole span, header included, and nothing else", async () => {
+    const calls = stubProvider();
+    await transcribeSegment(UPLOAD_ID, SEGMENT);
+    // 44 bytes of canonical header plus one second of audio, inside a multipart
+    // body — so the request is strictly larger than the span and close to it.
+    const size = sentBytes(calls[0]?.body).byteLength;
+    expect(size).toBeGreaterThan(BYTES_PER_SECOND);
+    expect(size).toBeLessThan(BYTES_PER_SECOND + 2000);
+  });
+
+  test("a rate limit is RETRYABLE, so one busy minute does not fail the run", async () => {
+    // The expected failure of a 32-wide fan-out, and the reason this step's
+    // `maxRetries` is above the default.
+    stubProvider({ status: 429, body: { error: "slow down" } });
+    await expect(transcribeSegment(UPLOAD_ID, SEGMENT)).rejects.toBeInstanceOf(RetryableError);
+    expect(transcribeSegment.maxRetries).toBe(5);
+  });
+
+  test("a rejected request is FATAL, so it is not asked five more times", async () => {
+    stubProvider({ status: 400, body: { error: "that is not audio" } });
+    await expect(transcribeSegment(UPLOAD_ID, SEGMENT)).rejects.toBeInstanceOf(FatalError);
+  });
+
+  test("the fan-out width is a constant, because the format is", () => {
+    // The payoff of normalizing: a segment is at most 3.5 MB whatever was
+    // uploaded, so there is no byte budget to divide — see the constant's doc.
+    expect(SEGMENT_CONCURRENCY).toBe(32);
+    expect(MAX_SEGMENT_SECONDS * BYTES_PER_SECOND * SEGMENT_CONCURRENCY).toBeLessThan(
+      640 * 1024 * 1024,
+    );
+  });
+});
+
+describe("auditing the transcript", () => {
+  test("asks for a script as well as lists, and keeps both", async () => {
+    // The two-summaries decision: a voice reading a bullet list says "one. two.
+    // three." with no connective tissue, so the schema demands sentences too.
+    restores.push(stubReporter().restore);
+    // The stub answers with TEXT, because that is what a gateway returns — and
+    // `stepGenerateJson` parsing it is part of what this exercises.
+    installStubGateway(
+      JSON.stringify({
+        headline: "Renewal call with Northwind",
+        risks: ["Nobody owns the migration date"],
+        actions: ["Ana to send revised pricing"],
+        spoken: "The renewal is close, but the migration date has no owner yet.",
+      }),
+    );
+
+    const summary = await summarize("… transcript …", "call.m4a", 600_000);
+    expect(summary.headline).toBe("Renewal call with Northwind");
+    expect(summary.risks).toEqual(["Nobody owns the migration date"]);
+    expect(summary.spoken).toContain("migration date");
+  });
+
+  test("an empty risk list is an ANSWER, not a retry", async () => {
+    // A schema that demanded a risk would get an invented one, which is worse than
+    // silence on a call that really had none.
+    restores.push(stubReporter().restore);
+    installStubGateway(
+      JSON.stringify({
+        headline: "Weekly standup",
+        risks: [],
+        actions: [],
+        spoken: "Nothing was decided and nothing is blocked.",
+      }),
+    );
+    await expect(summarize("…", "standup.wav", 60_000)).resolves.toMatchObject({ risks: [] });
+  });
+
+  test("a reply with no spoken script is a RETRY rather than silence", async () => {
+    // `spoken` is required rather than defaulted precisely so this fails: a default
+    // would turn a missing field into half a second of audio nobody notices.
+    restores.push(stubReporter().restore);
+    installStubGateway(JSON.stringify({ headline: "A call", risks: [], actions: [] }));
+    await expect(summarize("…", "call.m4a", 60_000)).rejects.toThrow();
+  });
+});
+
+describe("classifying a failure", () => {
+  /** An `FfmpegError` of one kind, with the argv a reader would want. */
+  function failed(kind: "exit" | "timeout" | "aborted" | "missing-binary") {
+    return new FfmpegError({
+      kind,
+      message: `ffmpeg ${kind}`,
+      binary: "ffmpeg",
+      argv: ["-i", "source"],
+    });
+  }
+
+  test("a file ffmpeg REFUSED is fatal, so it is not attempted five times", () => {
+    // `exit` means ffmpeg read the file and would read it the same way again.
+    expect(() => classifyFfmpeg(failed("exit"))).toThrow(FatalError);
+  });
+
+  test("no ffmpeg at all is fatal — a retry cannot install one", () => {
+    // The `aai dev` case, whose message already carries the install instructions.
+    expect(() => classifyFfmpeg(failed("missing-binary"))).toThrow(FatalError);
+  });
+
+  test("a run that timed out keeps its retries, and its argv", () => {
+    // Rethrown UNCHANGED rather than wrapped, which is what `toStepError` does with
+    // an error carrying no verdict — and the DevKit's default for anything that is
+    // not a `FatalError` is to retry. Asserting the class survives is asserting the
+    // diagnosis does: `argv` is the command you paste into a shell.
+    for (const kind of ["timeout", "aborted"] as const) {
+      const err = failed(kind);
+      expect(() => classifyFfmpeg(err)).toThrow(err);
+      expect(() => classifyFfmpeg(err)).not.toThrow(FatalError);
+    }
+  });
+
+  test("something that is not an ffmpeg failure at all is fatal", () => {
+    expect(() => classifyFfmpeg(new Error("no space left on device"))).toThrow(FatalError);
+  });
+
+  test("an analysis this desk cannot read is fatal, because a retry reads it again", () => {
+    // ffmpeg SUCCEEDED and printed something unrecognized — a renamed key, a lost
+    // `-loglevel info`. Every retry runs the same binary and prints the same thing.
+    expect(() =>
+      analyse(() => {
+        throw new MediaAnalysisError("no JSON block");
+      }),
+    ).toThrow(FatalError);
+  });
+
+  test("an analysis helper's OTHER failures are not swallowed", () => {
+    // Only `MediaAnalysisError` is a verdict. Anything else is a bug in the parser,
+    // and turning that into a terminal step failure would hide it.
+    const bug = new TypeError("cannot read properties of undefined");
+    expect(() =>
+      analyse(() => {
+        throw bug;
+      }),
+    ).toThrow(bug);
+  });
+});
+
+describe("the run's clock", () => {
+  test("is a STEP, so a replay does not re-measure it", async () => {
+    // A `Date.now()` in the body returns a different value on every replay, and
+    // every duration derived from it would be a different duration.
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(1_700_000_000_000);
+      await expect(now()).resolves.toBe(1_700_000_000_000);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("the mastered narration", () => {
+  test("is not driven here, and the spec says why rather than pretending", () => {
+    // `narrate` speaks, writes a temp file, spawns ffmpeg and stores the result. A
+    // unit test may do none of those, so what is covered is `masterArgs` above and
+    // the classification below — and `stubSpeech` is imported to make the omission
+    // deliberate rather than an oversight: filling only that slot would leave the
+    // step failing on the subprocess, which is a test of the tier, not the code.
+    expect(typeof stubSpeech).toBe("function");
+    expect(masterArgs("in.wav", "out.mp3").at(-1)).toBe("out.mp3");
+  });
+});
+
+describe("moving bytes between the store and a local file", () => {
+  /**
+   * These DO touch the filesystem, which the unit tier otherwise avoids — and the
+   * exception is deliberate rather than a slip. A temp directory is hermetic, costs
+   * milliseconds, and is the only way to exercise the one bug this module is written
+   * to prevent: `fileChunks` reuses one buffer across reads, so yielding a view of
+   * it rather than a copy hands the consumer memory the next read overwrites. That
+   * failure produces a stored file made of the LAST chunk repeated, and it does not
+   * reproduce whenever the consumer happens to copy before the next iteration — so
+   * a mock consumer would not see it and only real bytes will.
+   *
+   * `aai-cli`'s unit specs take the same exception through their own `withTempDir`.
+   */
+  test("withTempDir gives the work a private directory and removes it after", async () => {
+    let seen: string | undefined;
+    await withTempDir(async (dir) => {
+      seen = dir;
+      await writeFile(join(dir, "probe"), "x");
+      await expect(stat(join(dir, "probe"))).resolves.toBeTruthy();
+    });
+    expect(seen).toBeTruthy();
+    // Gone. A guest's disk is small, and a step that left a copy of every recording
+    // it touched would fill it.
+    await expect(stat(seen ?? "")).rejects.toThrow();
+  });
+
+  test("the directory is removed even when the work THROWS", async () => {
+    let seen: string | undefined;
+    const boom = new Error("the conversion failed");
+    await expect(
+      withTempDir((dir) => {
+        seen = dir;
+        throw boom;
+      }),
+    ).rejects.toThrow(boom);
+    await expect(stat(seen ?? "")).rejects.toThrow();
+  });
+
+  test("materializeUpload writes the stored bytes to a path, in order", async () => {
+    // The upload store is the seam that makes this testable at all: `readUpload`
+    // reads a process-wide slot rather than dialling anything.
+    const bytes = new Uint8Array(4096).map((_, at) => at % 251);
+    restores.push(stubUploads({ [UPLOAD_ID]: { bytes, name: "call.m4a" } }));
+
+    await withTempDir(async (dir) => {
+      const path = join(dir, "source");
+      // A small window, so the loop really runs four times — at the real 8 MiB one
+      // a 4 KB upload would exercise a single pass and prove nothing about it.
+      await materializeUpload(UPLOAD_ID, bytes.byteLength, path, 1024);
+      expect(new Uint8Array(await readFile(path))).toEqual(bytes);
+    });
+  });
+
+  test("an empty upload materializes an empty file rather than failing", async () => {
+    restores.push(stubUploads({ [UPLOAD_ID]: { bytes: new Uint8Array(0) } }));
+    await withTempDir(async (dir) => {
+      const path = join(dir, "source");
+      await materializeUpload(UPLOAD_ID, 0, path);
+      expect((await stat(path)).size).toBe(0);
+    });
+  });
+
+  test("fileChunks yields the file's real bytes, not a reused buffer", async () => {
+    // The aliasing bug, and the reason these specs touch a disk. Verified to CATCH
+    // it: deleting the `.slice()` in `fileChunks` fails this test.
+    await withTempDir(async (dir) => {
+      const path = join(dir, "audio.pcm");
+      const bytes = new Uint8Array(5000).map((_, at) => (at * 7) % 251);
+      await writeFile(path, bytes);
+
+      // A 1 KB window over 5 KB of bytes, so there are five reads through ONE
+      // buffer. That is what makes the aliasing reachable; collecting the chunks and
+      // concatenating afterwards is what makes it visible, since every earlier chunk
+      // would then read as the last one.
+      const collected: Uint8Array[] = [];
+      for await (const chunk of fileChunks(path, 1024)) collected.push(chunk);
+
+      const rejoined = new Uint8Array(collected.reduce((n, c) => n + c.byteLength, 0));
+      let at = 0;
+      for (const chunk of collected) {
+        rejoined.set(chunk, at);
+        at += chunk.byteLength;
+      }
+      expect(rejoined).toEqual(bytes);
+    });
+  });
+
+  test("fileChunks over an empty file yields nothing rather than one empty chunk", async () => {
+    await withTempDir(async (dir) => {
+      const path = join(dir, "empty");
+      await writeFile(path, new Uint8Array(0));
+      const collected: Uint8Array[] = [];
+      for await (const chunk of fileChunks(path)) collected.push(chunk);
+      expect(collected).toEqual([]);
+    });
+  });
+});
+
+describe("the ffmpeg steps, up to the spawn", () => {
+  /**
+   * These reach the point where ffmpeg would run and stop there, DETERMINISTICALLY
+   * — which is the trick that makes them unit tests rather than scenario tests.
+   *
+   * `AAI_FFMPEG_PATH` / `AAI_FFPROBE_PATH` name the binary the SDK resolves, so
+   * pointing them 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
+   * here and behave differently in CI, which is the green-locally/red-in-CI
+   * asymmetry this repo is built to avoid.
+   *
+   * What they cover is everything before the subprocess — reading the upload,
+   * materializing it, building the argv — plus the classification of the failure.
+   * They also pin the behaviour a developer actually meets: `aai dev` on a laptop
+   * with no ffmpeg is the one place dev/prod parity is partial, and it must fail
+   * FATALLY with an installable remedy rather than retry four times.
+   */
+  beforeEach(() => {
+    vi.stubEnv("AAI_FFMPEG_PATH", "/nonexistent/aai-test/ffmpeg");
+    vi.stubEnv("AAI_FFPROBE_PATH", "/nonexistent/aai-test/ffprobe");
+  });
+
+  test("ingestRecording materializes the upload, then fails fatally with no ffprobe", async () => {
+    restores.push(
+      stubUploads({
+        [UPLOAD_ID]: { bytes: new Uint8Array(2048), name: "call.m4a", type: "audio/mp4" },
+      }),
+      stubReporter().restore,
+    );
+    // Fatal, not retryable: four more attempts find the same missing binary, and the
+    // message already carries the install instructions.
+    await expect(ingestRecording(UPLOAD_ID)).rejects.toBeInstanceOf(FatalError);
+    // And the retry budget is still raised, for the I/O halves that ARE transient.
+    expect(ingestRecording.maxRetries).toBe(5);
+  });
+
+  test("narrate speaks first, then fails fatally with no ffmpeg to master with", async () => {
+    // `stepSpeak` runs — the synthesis is not what is broken here — so this also
+    // pins the ORDER: a step that mastered before speaking would fail without ever
+    // calling the voice service.
+    const speech = stubSpeech();
+    restores.push(speech.restore, stubReporter().restore, stubUploads({}, { writable: true }));
+
+    await expect(narrate("Read this back.", "jane")).rejects.toBeInstanceOf(FatalError);
+    expect(speech.calls.length).toBe(1);
+    expect(speech.calls[0]?.text).toBe("Read this back.");
+  });
+
+  test("the temp directory is gone even though the mastering pass failed", async () => {
+    // The `finally` in `withTempDir`, on the path that matters: a guest's disk is
+    // small, and a step that leaked a directory per failed run would fill it.
+    const before = await readdir(tmpdir());
+    const speech = stubSpeech();
+    restores.push(speech.restore, stubReporter().restore, stubUploads({}, { writable: true }));
+
+    await expect(narrate("Read this back.")).rejects.toBeInstanceOf(FatalError);
+    const after = await readdir(tmpdir());
+    expect(after.filter((name) => name.startsWith("aai-call-audit-"))).toEqual(
+      before.filter((name) => name.startsWith("aai-call-audit-")),
+    );
+  });
+});