@alexkroman1/aai-cli 9.2.0 → 10.0.0

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

@@ -0,0 +1,273 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Making one REQUEST light, where `normalize.ts` makes the whole FILE cuttable.
+ *
+ * The two look like the same job and are not, and the difference is the reason
+ * this module exists at all:
+ *
+ * | | `normalize.ts` | this |
+ * | --- | --- | --- |
+ * | fixes | a recording the desk cannot CUT | a request the endpoint cannot FINISH |
+ * | works on | the whole file, via ffmpeg | one segment's bytes, in process |
+ * | needs | every byte to have arrived | only the segment's own window |
+ * | produces | a new upload | a request body, thrown away after |
+ *
+ * `normalizeRecording` reads the entire recording out of the store, runs ffmpeg
+ * over it and writes a second upload back. That is exactly right for the classic
+ * flow, and it is unavailable to the streaming one by construction: a file that
+ * is still arriving is not a file ffmpeg can transcode, and waiting for the last
+ * byte before converting would give up the whole property `stream.ts` exists to
+ * demonstrate. So the streaming desk needs the byte saving WITHOUT the whole-file
+ * pass, and a segment it has already cut is linear PCM it can resample itself.
+ *
+ * ## Why it is worth doing at all
+ *
+ * The sync endpoint deadlines a request at **30 seconds**, wall clock, and that
+ * budget covers the upload as well as the transcription. A 92-second segment of
+ * 48 kHz 16-bit stereo is **17.66 MB**; the same audio at
+ * {@link NORMALIZED_SAMPLE_RATE} mono is **2.94 MB**. Six times the bytes per
+ * request, against a fixed deadline, is not a slower run — it is a run that dies:
+ *
+ * ```text
+ *   HTTP 504 — request exceeded 30.0s
+ *   sync.assemblyai.com did not answer: ConnectTimeoutError (timeout: 10000ms)
+ * ```
+ *
+ * Both of those are from one real 50-minute stereo recording, where half the
+ * segments landed and three burned all six attempts. A 504 is transient, so every
+ * one of them is retried the full six times before the body throws — and when it
+ * does, every sibling still in flight is discarded and re-billed on the resume.
+ *
+ * ## It is a BOX FILTER, and that is a real trade
+ *
+ * Averaging each output frame's window of input frames is a low-pass filter and a
+ * decimation in one pass, which is the cheap end of resampling. It is genuinely
+ * better than taking every Nth sample — that folds everything above the new
+ * Nyquist straight back into the speech band — but it is not what ffmpeg's
+ * `swr` does, and at 48 kHz -> 16 kHz it attenuates the top of the kept band by
+ * about a third and leaves the first alias image around -12 dB.
+ *
+ * That is the honest cost, and the classic flow does not pay it: `normalize.ts`
+ * has the whole file and uses ffmpeg. This is the streaming flow's option,
+ * chosen because 8 kHz of slightly soft speech transcribes and a request that
+ * never finishes does not. A desk that cares more about the top octave than
+ * about the tail latency should run the classic flow.
+ *
+ * ## Pure, and deliberately so
+ *
+ * Nothing here reaches a `node:` builtin or an SDK subpath that does. `stream.ts`
+ * is compiled as a `node:vm` Script with no `require` (see `normalize.ts`'s module
+ * doc), so a module it imports at module scope may not drag one in — which is why
+ * the normalize TARGETS live here, the pure module, and `normalize.ts` imports
+ * them rather than the other way round.
+ */
+
+import type { PcmFormat } from "@alexkroman1/aai/step";
+import { blockAlign, UnsupportedRecordingError, type WavFormat } 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`) and whose requests are bounded by a 30-second deadline. 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;
+
+/**
+ * Whether sending this format AS IS would make every request too heavy.
+ *
+ * The format-level half of `normalize.ts`'s `heavierThanNormalized`, which asks
+ * the same question of an unparsed header. Both are here rather than there
+ * because the streaming flow answers it from a format it already has and must
+ * not import a module that reaches ffmpeg.
+ *
+ * Compared against the normalize targets rather than against a byte budget of
+ * its own: the question is literally "would converting make this smaller", and
+ * anything at or below {@link NORMALIZED_SAMPLE_RATE} /
+ * {@link NORMALIZED_CHANNELS} would only be re-encoded into itself.
+ *
+ * It deliberately does NOT look at `bitsPerSample`, matching the whole-file
+ * predicate so the two flows cannot disagree about which files are heavy. A
+ * 24-bit file at 16 kHz mono really would shrink, but that is a 1.5-2x saving
+ * on a file already inside the budget.
+ */
+export function heavierThanNormalizedFormat(
+  format: Pick<WavFormat, "sampleRate" | "channels">,
+): boolean {
+  return format.sampleRate > NORMALIZED_SAMPLE_RATE || format.channels > NORMALIZED_CHANNELS;
+}
+
+/**
+ * One segment's PCM, resampled to something the endpoint can swallow in 30s.
+ *
+ * Returns the input UNCHANGED when it is already light — same array, same
+ * format, no copy — so this is inert on the classic flow, where
+ * `normalizeRecording` has already converted the whole file, and on any
+ * recording that arrived at 16 kHz mono to begin with. That inertness is what
+ * lets `transcribeSegment` call it unconditionally and both flows share the one
+ * step.
+ *
+ * @param bytes - The segment's window, interleaved little-endian linear PCM.
+ *   A ragged tail is truncated to whole frames: `dataEnd` is clamped to the
+ *   file's real size, which no recorder guarantees is frame-aligned.
+ * @param from - The recording's format, from `parseWav`.
+ *
+ * @returns The bytes to send and the format to write a header with — always
+ *   16-bit mono once anything was done, because there is one output path and a
+ *   narrower one saves nothing worth a second.
+ *
+ * @throws {UnsupportedRecordingError} for a bit depth `parseWav` admits and this
+ *   cannot serve, and for a window holding no whole frame. Both are checked
+ *   BEFORE the fast path, so the LIGHT path answers them too — see the two
+ *   guards below. Terminal, which is right: each answers the same way forever.
+ */
+export function downsampleSegment(
+  bytes: Uint8Array,
+  from: Pick<WavFormat, "sampleRate" | "channels" | "bitsPerSample">,
+): { bytes: Uint8Array; format: PcmFormat } {
+  // Both guards run before the fast path, and that is the fix rather than an
+  // ordering preference: they ask what can be SENT, which the light path does
+  // as much as the heavy one. Hung off the resampler they only ever ran when
+  // there was resampling to do, so a recording already at 16 kHz mono took the
+  // identity path below with its samples never once looked at — and a 12-bit
+  // one then died in `encodeWav` on an UNCLASSIFIED `RangeError`, worth six
+  // attempts against a file no attempt can fix, while a 64-bit one passed that
+  // check and went on the wire mislabelled.
+  const bind = sampleReaderFor(from);
+  const frame = blockAlign(from);
+  const inFrames = Math.floor(bytes.length / frame);
+  // A CALLER ERROR, and stated as one. `readUpload` clamps a window to what is
+  // stored, so the streaming flow can hand a short read down here; with no whole
+  // frame the averaging window below is zero wide, `total / 0` is `NaN`, and
+  // `setInt16` writes that as a 0 — a two-byte WAV of silence, transcribed and
+  // reported as if it were audio. There is no honest empty result to return
+  // either: the endpoint is being asked to decode nothing.
+  if (inFrames === 0) {
+    throw new UnsupportedRecordingError(
+      `That segment holds ${bytes.length} byte(s), which is under one ${frame}-byte frame — ` +
+        "there is no audio in it to transcribe.",
+    );
+  }
+
+  const format = requestFormat(from);
+  if (format === from) return { bytes, format };
+
+  const ratio = from.sampleRate / format.sampleRate;
+  const outFrames = Math.max(1, Math.floor(inFrames / ratio));
+
+  const read = bind(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+  const out = new Uint8Array(outFrames * 2);
+  const wrote = new DataView(out.buffer);
+  const sampleBytes = from.bitsPerSample / 8;
+
+  for (let i = 0; i < outFrames; i++) {
+    // The window this output frame averages. Half-open, at least one frame wide
+    // however the ratio divides — a zero-wide window is a division by zero, and
+    // a non-integer ratio (44.1 kHz -> 16 kHz is 2.75625) produces windows of
+    // two different widths, which is the box filter tracking the true rate
+    // rather than drifting off it.
+    const lo = Math.floor(i * ratio);
+    const hi = Math.min(inFrames, Math.max(lo + 1, Math.floor((i + 1) * ratio)));
+
+    // Every channel of every frame in the window, in one accumulator: the
+    // low-pass and the downmix are the same average, so doing them separately
+    // would be two passes for one answer.
+    let total = 0;
+    for (let f = lo; f < hi; f++) {
+      const at = f * frame;
+      for (let c = 0; c < from.channels; c++) total += read(at + c * sampleBytes);
+    }
+    // No clamp: an average of values already inside the 16-bit range is inside
+    // it, and `Math.round` cannot carry one out.
+    wrote.setInt16(i * 2, Math.round(total / ((hi - lo) * from.channels)), true);
+  }
+
+  return { bytes: out, format };
+}
+
+/**
+ * The format that will go ON THE WIRE for a recording in `from`.
+ *
+ * Returns `from` ITSELF — identity, not a copy — when nothing needs doing, which
+ * is what {@link downsampleSegment} tests to take its fast path. That identity is
+ * load-bearing rather than an optimisation: the alternative is two places deciding
+ * "is this heavy" and the resampler disagreeing with the fast path about one
+ * edge case.
+ *
+ * Exported because `segmentConcurrency` (`transcribe.ts`) divides a byte budget by
+ * a segment's cost, and that budget is bytes UPLOADING — so it has to be asked of
+ * what is SENT rather than of what was cut. Deriving both from this is what stops
+ * the width and the resampler drifting apart.
+ */
+export function requestFormat(
+  from: Pick<WavFormat, "sampleRate" | "channels" | "bitsPerSample">,
+): Pick<WavFormat, "sampleRate" | "channels" | "bitsPerSample"> {
+  if (!heavierThanNormalizedFormat(from)) return from;
+  return {
+    // Never UP. An 8 kHz stereo recording needs the downmix and not the rate, and
+    // resampling it to 16 kHz would invent bytes to pay a deadline with.
+    sampleRate: Math.min(from.sampleRate, NORMALIZED_SAMPLE_RATE),
+    channels: NORMALIZED_CHANNELS,
+    bitsPerSample: 16,
+  };
+}
+
+/**
+ * How to read one sample of this format, as a number on the 16-bit scale.
+ *
+ * Chosen ONCE rather than switched per sample: a 92-second stereo segment is
+ * 8.8 million frames, so the branch is the difference between a closure call and
+ * a jump table 17.6 million times over.
+ *
+ * TWO stages, and the split is what lets one switch serve both paths. The depth
+ * is settled here — including the REFUSAL — and the view is bound after, because
+ * a light-path call has no view to bind and still owes that refusal: the four
+ * depths this can read are also the four the request can carry, since `encodeWav`
+ * rejects anything that is not a whole number of bytes and the endpoint decodes
+ * what the header describes.
+ *
+ * `parseWav` admits only `WAVE_FORMAT_PCM`, so every depth here is a signed
+ * little-endian integer — except 8-bit, which RIFF specifies as UNSIGNED and
+ * centred on 128. That asymmetry is the one thing in this function worth
+ * knowing; reading an 8-bit file as signed is a transcript of loud static.
+ */
+function sampleReaderFor(
+  from: Pick<WavFormat, "bitsPerSample">,
+): (view: DataView) => (at: number) => number {
+  switch (from.bitsPerSample) {
+    case 8:
+      return (view) => (at) => (view.getUint8(at) - 128) * 256;
+    case 16:
+      return (view) => (at) => view.getInt16(at, true);
+    case 24:
+      // `getInt8` on the top byte is what sign-extends: the low two are read
+      // unsigned and OR'd under it, then the whole thing is shifted down to the
+      // 16-bit scale by an ARITHMETIC shift, which preserves that sign.
+      return (view) => (at) =>
+        (view.getUint8(at) | (view.getUint8(at + 1) << 8) | (view.getInt8(at + 2) << 16)) >> 8;
+    case 32:
+      return (view) => (at) => view.getInt32(at, true) >> 16;
+    default:
+      throw new UnsupportedRecordingError(
+        `That WAV holds ${from.bitsPerSample}-bit samples, which this desk can cut but cannot ` +
+          "send: a request carries 8-, 16-, 24- or 32-bit linear PCM. Re-encode it with " +
+          "`-c:a pcm_s16le`.",
+      );
+  }
+}

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

@@ -71,34 +71,22 @@
 
 import { basename, extname, join } from "node:path";
 import { probeMedia, runFfmpeg, wavEncodeArgs } from "@alexkroman1/aai/ffmpeg";
-import { readUpload, report, uploadInfo } from "@alexkroman1/aai/step";
+import { readUpload, report, requireCompleteUpload } from "@alexkroman1/aai/step";
 import { throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
 import { readUploadToFile, withTempDir, writeUploadFromFile } from "@alexkroman1/aai/step-files";
 import { formatBytes, formatDuration } from "@alexkroman1/aai/utils";
+import {
+  heavierThanNormalizedFormat,
+  NORMALIZED_CHANNELS,
+  NORMALIZED_SAMPLE_RATE,
+} from "./downsample.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;
+// Re-exported rather than re-declared: they are still this module's vocabulary —
+// the `runFfmpeg` call below converts TO them — and they live in `downsample.ts`
+// only because the streaming flow needs them from a module that reaches no
+// `node:` builtin. See that file's module doc.
+export { NORMALIZED_CHANNELS, NORMALIZED_SAMPLE_RATE } from "./downsample.ts";
 
 /**
  * How long a conversion may run before it is killed.
@@ -134,9 +122,10 @@ export type NormalizedRecording = {
  * 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);
+  // `requireCompleteUpload`, not `uploadInfo`: `size` is the readable PREFIX, and
+  // every judgement below — cuttable, heavier-per-second, the byte count copied to
+  // disk — is about the WHOLE file.
+  const stored = await requireCompleteUpload(uploadId);
   const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
 
   if (cuttable(head.bytes, stored.size) && !heavierThanNormalized(head.bytes, stored.size)) {
@@ -226,17 +215,6 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
   );
 }
 
-/**
- * Retries beyond the default 3.
- *
- * Not because a conversion is flaky — a corrupt file fails identically forever,
- * and `throwFfmpegStepError` is what stops the DevKit retrying that. It is the
- * two I/O halves that are worth another attempt: this step reads a whole
- * recording out of the store and writes a whole one back, and either can lose a
- * connection on a file this size.
- */
-normalizeRecording.maxRetries = 5;
-
 /**
  * Whether `splitRecording` will be able to read this header.
  *
@@ -266,7 +244,7 @@ export function cuttable(head: Uint8Array, totalBytes: number): boolean {
  * so six times the upload per request is the difference between segments landing
  * in single digits and segments landing at 22-28s — which is not a slow run, it
  * is a run where the first straggler past 30s takes the whole thing down (a
- * segment burns `maxRetries`, the body throws, and every sibling still in flight
+ * segment burns its attempts, the body throws, and every sibling still in flight
  * is discarded and re-billed on the resume).
  *
  * This is NOT the "second opinion" the module doc warns about. That warning is
@@ -289,8 +267,7 @@ export function cuttable(head: Uint8Array, totalBytes: number): boolean {
  * answering.
  */
 export function heavierThanNormalized(head: Uint8Array, totalBytes: number): boolean {
-  const format = parseWav(head, totalBytes);
-  return format.sampleRate > NORMALIZED_SAMPLE_RATE || format.channels > NORMALIZED_CHANNELS;
+  return heavierThanNormalizedFormat(parseWav(head, totalBytes));
 }
 
 /** `41:20 of aac`, or as much of that as ffprobe would say. */

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

@@ -91,7 +91,7 @@
  *   `UPLOAD_CHUNK_BYTES`, which is the chunk a range READ is served in and not the
  *   unit a write publishes: `putWindows` cuts a body into `UPLOAD_PART_BYTES`
  *   windows so one byte layout serves every route an upload can arrive by;
- * - the body sleeps {@link POLL_INTERVAL} between polls when nothing is ready, cut
+ * - the body sleeps {@link POLL_INTERVAL_MS} between polls when nothing is ready, cut
  *   short by the client's wake.
  *
  * 9s + one poll is the 14s above. Nothing here can go below a segment without a
@@ -167,6 +167,7 @@
  * what keeps that order a pure function of journaled values.
  */
 
+import type { WorkflowCtx } from "@alexkroman1/aai";
 import {
   mapConcurrent,
   readUpload,
@@ -176,7 +177,6 @@ import {
 } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
 import { formatDuration, omitUndefined, plural } from "@alexkroman1/aai/utils";
-import { sleep } from "workflow";
 import {
   fatalOnUnsupported,
   mergeTranscript,
@@ -195,14 +195,37 @@ import {
   type WavFormat,
 } from "./wav.ts";
 
-/** How long the body waits between polls when nothing new has arrived. */
-const POLL_INTERVAL = "5s";
+/**
+ * The LONGEST the body waits between polls, and its fallback when it cannot do
+ * better.
+ *
+ * It used to be the only interval, and on a slow uplink that is most of what this
+ * flow was still leaving on the table. A poll answers "has the next segment
+ * landed"; a flat interval answers it on average half an interval late, once per
+ * segment, for the whole upload — 20 segments of a 30-minute recording is ~50s of
+ * pure waiting added to a run whose entire point is to finish as the bytes arrive.
+ *
+ * So it is a CEILING now: {@link nextPollDelay} sleeps until the next segment
+ * should have landed, and falls back here when there is nothing to predict from.
+ */
+const POLL_INTERVAL_MS = 5000;
+
+/**
+ * The shortest the body will sleep.
+ *
+ * A poll is one cheap step (the body's own note above the `continue` says so), but
+ * it is not free — it is a journal write and, on the platform, a step execution —
+ * so a rate estimate that comes out near zero must not turn the loop into a spin.
+ * 250ms is under the latency of any single segment's transcription, so nothing is
+ * waiting on this.
+ */
+const MIN_POLL_INTERVAL_MS = 250;
 
 /**
  * Consecutive polls with NO new bytes before the run gives up.
  *
  * An upload that died stays incomplete forever, so without a bound the run polls for
- * as long as the world will replay it. At {@link POLL_INTERVAL} this is five minutes
+ * as long as the world will replay it. At {@link POLL_INTERVAL_MS} this is five minutes
  * of silence — far longer than any stall a live uplink produces, and short enough
  * that the failure reaches whoever is watching.
  *
@@ -240,6 +263,15 @@ export type UploadProgressView = {
    * arrive — see the readiness test in the body.
    */
   ranges?: readonly UploadRange[];
+  /**
+   * When this view was taken, as the step that took it saw the clock.
+   *
+   * Journaled, which is the only reason the body may read a clock at all: the
+   * sleep below is derived from the RATE between two of these, and a value the
+   * body sampled itself would make that derivation diverge on a replay. Same rule
+   * as every other field here — see the body's own note on why its state is legal.
+   */
+  observedAt: number;
 };
 
 /** The cut, derived once from the header. */
@@ -255,10 +287,8 @@ export type StreamPlan = {
  * an upload id exactly as in the classic flow; what differs is that the client chose
  * it and the bytes are still on their way.
  */
-export async function transcribeStreamFlow(input: { recording: string }) {
-  "use workflow";
-
-  const startedAt = await startClock();
+export async function transcribeStreamFlow(input: { recording: string }, ctx: WorkflowCtx) {
+  const startedAt = await ctx.step("startClock", () => startClock());
   let plan: StreamPlan | undefined;
   // Body state, and legal because every value in it came out of a journaled step
   // result — a replay rebuilds the identical sets in the identical order.
@@ -272,9 +302,14 @@ export async function transcribeStreamFlow(input: { recording: string }) {
   // order, so this is the only number that distinguishes an upload that has
   // stopped from one whose prefix has not caught up yet.
   let lastStored = -1;
+  /**
+   * The previous poll, so {@link nextPollDelay} has two journaled samples to take
+   * a rate from. Body state for the same reason the rest is: it came out of a step.
+   */
+  let previous: UploadProgressView | undefined;
 
   for (;;) {
-    const at = await probeUpload(input.recording);
+    const at = await ctx.step("probeUpload", () => probeUpload(input.recording));
     // Every poll, because this is only ever read at the END — the run breaks out
     // on a `complete` view, whose prefix is the whole file. Updating it inside a
     // branch is how it used to end up describing whichever poll last had work.
@@ -284,7 +319,7 @@ export async function transcribeStreamFlow(input: { recording: string }) {
     // first thing to arrive. `complete` also qualifies, for a recording shorter
     // than the probe window.
     if (!plan && (at.size >= HEADER_PROBE_BYTES || at.complete)) {
-      plan = await planStreamed(input.recording);
+      plan = await ctx.step("planStreamed", () => planStreamed(input.recording));
     }
 
     if (plan) {
@@ -310,7 +345,13 @@ export async function transcribeStreamFlow(input: { recording: string }) {
           ...(await mapConcurrent(
             ready,
             segmentConcurrency((plan as StreamPlan).format),
-            (segment) => transcribeSegment(input.recording, (plan as StreamPlan).format, segment),
+            (segment) =>
+              // `maxAttempts: 6` was `transcribeSegment.maxRetries = 5`.
+              ctx.step(
+                "transcribeSegment",
+                () => transcribeSegment(input.recording, (plan as StreamPlan).format, segment),
+                { maxAttempts: 6 },
+              ),
           )),
         );
         // Straight back to the top WITHOUT sleeping, and this line was measured
@@ -336,16 +377,22 @@ export async function transcribeStreamFlow(input: { recording: string }) {
       lastStored = at.stored;
     }
     if (idlePolls > MAX_IDLE_POLLS) abandon(input.recording, at);
-    await sleep(POLL_INTERVAL);
+    // Sleep until the next segment should HAVE landed, rather than for a fixed
+    // interval — see `nextPollDelay`. Both arguments are journaled step results,
+    // so a replay computes the same delay from the same two samples.
+    await ctx.sleep(nextPollDelay(at, previous, plan, done));
+    previous = at;
   }
 
   const finished = plan;
-  if (!finished) abandon(input.recording, { size: 0, complete: false, stored: 0 });
-  return await mergeTranscript(
-    input.recording,
-    offsetToMs(finished.format, Math.min(finished.format.dataEnd, lastSize)),
-    parts,
-    startedAt,
+  if (!finished) abandon(input.recording, { size: 0, stored: 0 });
+  return await ctx.step("mergeTranscript", () =>
+    mergeTranscript(
+      input.recording,
+      offsetToMs(finished.format, Math.min(finished.format.dataEnd, lastSize)),
+      parts,
+      startedAt,
+    ),
   );
 }
 
@@ -359,13 +406,15 @@ export async function transcribeStreamFlow(input: { recording: string }) {
  * from.
  */
 export async function probeUpload(id: string): Promise<UploadProgressView> {
-  "use step";
-
   const info = await uploadInfo(id);
   return {
     size: info.size,
     complete: info.complete,
     stored: storedBytes(info.size, info.ranges),
+    // Legal HERE and nowhere else in this flow: a step's internals are not
+    // replayed, only its result — which is what makes a step the place a clock
+    // belongs. See `sync-api.ts`'s `timed` for the same rule.
+    observedAt: Date.now(),
     // `omitUndefined` rather than a spread, because a journaled step result is
     // compared on replay and `{ ranges: undefined }` is not `{}` once it has been
     // through JSON.
@@ -373,6 +422,112 @@ export async function probeUpload(id: string): Promise<UploadProgressView> {
   };
 }
 
+/**
+ * How long to wait before asking again — the time the NEXT segment still needs.
+ *
+ * The flat {@link POLL_INTERVAL_MS} this replaced is wrong in both directions on a
+ * slow uplink: too long when a segment is seconds away, and equally too long when
+ * it is a minute away, so the run discovers work late and then asks again pointlessly.
+ * Two consecutive polls give a byte RATE, the plan gives the byte offset the next
+ * un-transcribed segment needs, and the difference is a wait with a reason.
+ *
+ * Every input is a journaled step result — both views, and a plan derived from one —
+ * so a replay computes the identical delay. That is the whole reason
+ * {@link UploadProgressView.observedAt} exists rather than the body reading a clock.
+ *
+ * It is deliberately an ESTIMATE with a floor and a ceiling rather than a promise.
+ * Undershooting costs one extra cheap poll; overshooting is bounded by
+ * {@link POLL_INTERVAL_MS}, so a rate that collapses mid-upload degrades to exactly
+ * the old behaviour instead of stalling. Note the estimate is only ever used to
+ * SLEEP: readiness is still decided by {@link segmentStored} against a real view, so
+ * a wrong guess here can waste a poll and can never transcribe a partial segment.
+ */
+export function nextPollDelay(
+  at: UploadProgressView,
+  previous: UploadProgressView | undefined,
+  plan: StreamPlan | undefined,
+  done: ReadonlySet<number>,
+): number {
+  // No previous sample, or a clock that did not advance: nothing to derive a rate
+  // from. The first sleep of every run takes this arm.
+  const elapsedMs = previous ? at.observedAt - previous.observedAt : 0;
+  if (!previous || elapsedMs <= 0) return POLL_INTERVAL_MS;
+  const bytesPerMs = (at.stored - previous.stored) / elapsedMs;
+  // A stalled or shrinking upload has no arrival to predict. `MAX_IDLE_POLLS` is
+  // what ends that run; this only declines to guess about it.
+  if (bytesPerMs <= 0) return POLL_INTERVAL_MS;
+  // Before the header is read there is no plan, so what is being waited for is the
+  // probe window itself — small, and usually one part away. It is measured against
+  // the PREFIX because that is what the probe reads: from byte zero. Never against
+  // `stored`, which counts every window that has landed wherever it landed — the
+  // module doc's third section is about exactly that divergence, and under the
+  // browser's default fan-out `HEADER_PROBE_BYTES - stored` goes NEGATIVE before
+  // the header this arm is waiting for has arrived at all, collapsing the sleep to
+  // its floor. The RATE above is still `stored`'s, which is right: that one is a
+  // throughput, and throughput is what every window contributes to.
+  //
+  // The plan arm asks {@link segmentStored}'s own question instead of subtracting
+  // an offset, because that test does not read the prefix either. Measuring a
+  // segment against `size` saturates for the whole upload — 45 seconds of `size: 0`
+  // on the measured 27 MB recording — so every segment's sleep came back as the
+  // flat POLL_INTERVAL_MS this function exists to replace.
+  const remaining = plan ? bytesUntilNextSegment(plan, done, at) : HEADER_PROBE_BYTES - at.size;
+  // Every segment is already stored: the loop is waiting on `complete`, which is a
+  // flag the uploader sets rather than bytes to extrapolate.
+  if (remaining === undefined) return POLL_INTERVAL_MS;
+  if (remaining <= 0) return MIN_POLL_INTERVAL_MS;
+  return Math.min(
+    POLL_INTERVAL_MS,
+    Math.max(MIN_POLL_INTERVAL_MS, Math.ceil(remaining / bytesPerMs)),
+  );
+}
+
+/**
+ * How many bytes away the NEAREST un-transcribed segment is from being readable.
+ *
+ * The nearest rather than the earliest, and that is the `ranges` arm's doing: a
+ * fan-out lands its windows out of order, so the next segment the loop can act on
+ * is whichever one is closest to covered — not the first one in the file. They are
+ * the same segment for a whole-file upload, where coverage is a prefix and the
+ * least distance belongs to the lowest `end`.
+ *
+ * `undefined` when there is nothing left to wait for.
+ */
+function bytesUntilNextSegment(
+  plan: StreamPlan,
+  done: ReadonlySet<number>,
+  at: UploadProgressView,
+): number | undefined {
+  let nearest: number | undefined;
+  for (const segment of plan.segments) {
+    if (done.has(segment.index)) continue;
+    const missing = bytesUntilStored(segment, at);
+    if (nearest === undefined || missing < nearest) nearest = missing;
+  }
+  return nearest;
+}
+
+/**
+ * The bytes {@link segmentStored} still wants before it answers `true`.
+ *
+ * Derived from the same two readings that test uses, which is the whole point: a
+ * remainder taken from anything else predicts an arrival the readiness test will
+ * not agree with. Two ways for the window to be covered, so two candidates and the
+ * smaller wins — the PREFIX growing to `segment.end`, or the run that already
+ * holds `segment.start` growing to the same place. A run starting AFTER the
+ * segment does can never cover it alone (`rangesOf` merges the adjacent ones), so
+ * it is not a candidate at all and such a segment is left waiting on the prefix.
+ */
+function bytesUntilStored(segment: Segment, at: UploadProgressView): number {
+  if (segmentStored(segment, at)) return 0;
+  let missing = segment.end - at.size;
+  for (const range of at.ranges ?? []) {
+    if (range.start > segment.start) continue;
+    missing = Math.min(missing, segment.end - range.end);
+  }
+  return missing;
+}
+
 /**
  * How many bytes have landed in total, prefix and detached windows alike.
  *
@@ -429,8 +584,6 @@ export function segmentStored(segment: Segment, at: UploadProgressView): boolean
  * which is what the classic flow is for.
  */
 export async function planStreamed(id: string): Promise<StreamPlan> {
-  "use step";
-
   const head = await readUpload(id, { end: HEADER_PROBE_BYTES });
   const format = fatalOnUnsupported(() => parseWav(head.bytes, Number.POSITIVE_INFINITY));
   if (!Number.isFinite(format.dataEnd)) {
@@ -473,7 +626,7 @@ export function expectedSegments(plan: StreamPlan, size: number): number {
  * should happen here, and dressing it up as a step error would suggest a retry
  * policy with nothing to apply to.
  */
-function abandon(id: string, at: UploadProgressView): never {
+function abandon(id: string, at: Pick<UploadProgressView, "size" | "stored">): never {
   throw new Error(
     `Gave up waiting for ${id}: ${at.stored} byte(s) stored, ${at.size} readable from the ` +
       `start, and still incomplete. Nothing new arrived for ${MAX_IDLE_POLLS} polls — the ` +