@alexkroman1/aai-cli 9.1.0 → 10.0.0

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

@@ -35,6 +35,32 @@
  * transcript of most of a recording and report success. The stall is what
  * {@link MAX_IDLE_POLLS} is for, and it FAILS the run rather than finishing it.
  *
+ * ## A poll reads THREE numbers, and each answers a different question
+ *
+ * `size` is the CONTIGUOUS PREFIX, `stored` is every byte that has landed, and
+ * `ranges` is where those bytes are. They are one number only for a whole-file
+ * upload; under the browser's default fan-out they diverge completely, and reading
+ * the wrong one is two separate bugs:
+ *
+ * - **Readiness on the prefix alone made this flow a no-op.** The client sends
+ *   `UPLOAD_PART_CONCURRENCY` windows of `UPLOAD_PART_BYTES` at once, so every part
+ *   of any recording that fits in one round shares the uplink and they all finish
+ *   together. The prefix cannot move until the FIRST part completes, which is
+ *   within a second of the last. Measured on a deployed agent, a 27 MB recording at
+ *   0.9 MB/s: `size` was 0 at every poll for 45 seconds and then the whole file, so
+ *   the run planned nothing, transcribed nothing, and did its entire fan-out after
+ *   the upload — the classic flow, with extra steps. `segmentStored` reads `ranges`
+ *   instead, and `readUpload` clamps to the run a read starts in rather than to the
+ *   prefix, so a window that has landed is a window this flow can work on.
+ * - **The stall test on the prefix would then FAIL a healthy upload.** A parts
+ *   upload moving at full speed reports the same prefix at every poll, which is
+ *   indistinguishable from a dead client — so past {@link MAX_IDLE_POLLS} the run
+ *   abandons an upload that is still arriving. It reads `stored`, which grows with
+ *   every window whatever order they land in.
+ *
+ * `size` keeps the two jobs only it can do: the header probe (which reads from byte
+ * zero) and the finished recording's duration.
+ *
  * ## It really does overlap, and the granularity is a SEGMENT
  *
  * Watched directly — the same 10-minute recording at 2 MB/s, polling the upload's
@@ -60,9 +86,12 @@
  *
  * - a segment is `SEGMENT_SECONDS + SEGMENT_OVERLAP_SECONDS` of audio — ~17.6 MB at
  *   48 kHz stereo, which is ~9s of a 2 MB/s uplink;
- * - the store publishes `size` a `UPLOAD_CHUNK_BYTES` chunk at a time (1 MiB), so the
- *   view a poll reads is at most a megabyte stale;
- * - the body sleeps {@link POLL_INTERVAL} between polls when nothing is ready, cut
+ * - the store publishes bytes an `UPLOAD_PART_BYTES` window at a time (8 MiB), so the
+ *   view a poll reads is up to a window stale. This paragraph said 1 MiB, naming
+ *   `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_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
@@ -138,10 +167,16 @@
  * what keeps that order a pure function of journaled values.
  */
 
-import { mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/step";
+import type { WorkflowCtx } from "@alexkroman1/aai";
+import {
+  mapConcurrent,
+  readUpload,
+  report,
+  type UploadRange,
+  uploadInfo,
+} from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
-import { formatDuration, plural } from "@alexkroman1/aai/utils";
-import { sleep } from "workflow";
+import { formatDuration, omitUndefined, plural } from "@alexkroman1/aai/utils";
 import {
   fatalOnUnsupported,
   mergeTranscript,
@@ -160,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.
  *
@@ -179,10 +237,41 @@ const MAX_IDLE_POLLS = 60;
 
 /** What one poll of the upload found. */
 export type UploadProgressView = {
-  /** Bytes stored so far. */
+  /**
+   * The CONTIGUOUS PREFIX — how far the file can be read from byte zero.
+   *
+   * Not how much has arrived: see {@link UploadProgressView.stored}. It is what
+   * the header probe and the final duration are measured against, because both
+   * want a length rather than a coverage map.
+   */
   size: number;
   /** Whether that is all of them. The ONLY field an exit may be decided on. */
   complete: boolean;
+  /**
+   * Total bytes landed, prefix and windows ahead of it alike.
+   *
+   * The one number a STALL may be judged on. `size` cannot be: a fan-out lands
+   * its windows out of order, so the prefix stays at zero through an upload that
+   * is moving at full speed and {@link MAX_IDLE_POLLS} would call it dead.
+   */
+  stored: number;
+  /**
+   * The windows that have landed, when the upload arrived as parts.
+   *
+   * Absent for a whole-file write, whose bytes are the prefix and nothing else.
+   * This is what makes a segment readable before the windows in front of it
+   * 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. */
@@ -198,26 +287,39 @@ 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.
   const done = new Set<number>();
   const parts: SegmentTranscript[] = [];
   let idlePolls = 0;
-  let lastSize = -1;
+  // The prefix at the last poll, which is what the final duration is measured
+  // from — and deliberately NOT what the stall test reads; see `lastStored`.
+  let lastSize = 0;
+  // Total bytes landed at the last poll. A fan-out lands its windows out of
+  // 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.
+    lastSize = at.size;
 
     // The header has to be present before anything can be planned, and it is the
     // 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) {
@@ -229,11 +331,11 @@ export async function transcribeStreamFlow(input: { recording: string }) {
       const ready = plan.segments.filter(
         (segment) =>
           !done.has(segment.index) &&
-          (segment.end <= at.size || (at.complete && segment.start < at.size)),
+          (segmentStored(segment, at) || (at.complete && segment.start < at.size)),
       );
       if (ready.length > 0) {
         idlePolls = 0;
-        lastSize = at.size;
+        lastStored = at.stored;
         for (const segment of ready) done.add(segment.index);
         // One step per segment, bounded, in an order a replay reproduces exactly —
         // `ready` is derived from a journaled poll, and `mapConcurrent` issues its
@@ -243,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
@@ -259,23 +367,32 @@ export async function transcribeStreamFlow(input: { recording: string }) {
 
     // Nothing to work on, so this view is current and the exit can be trusted.
     if (at.complete && plan && done.size >= expectedSegments(plan, at.size)) break;
-    // A stall, not an ending — see MAX_IDLE_POLLS.
-    if (at.size === lastSize) idlePolls += 1;
+    // A stall, not an ending — see MAX_IDLE_POLLS. Judged on `stored` rather than
+    // on the prefix: under the browser's default fan-out the prefix does not move
+    // at all until the first window lands, so a run reading it would call a
+    // healthy upload abandoned five minutes in and fail.
+    if (at.stored === lastStored) idlePolls += 1;
     else {
       idlePolls = 0;
-      lastSize = at.size;
+      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 });
-  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,
+    ),
   );
 }
 
@@ -289,10 +406,167 @@ 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 };
+  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.
+    ...omitUndefined({ ranges: info.ranges }),
+  };
+}
+
+/**
+ * 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.
+ *
+ * `ranges` COVERS the prefix when it is present (it is every window the record
+ * holds, merged), so this is the larger of the two rather than their sum — adding
+ * them would double-count the prefix and make a stalled upload look like it was
+ * still growing, which is the one thing {@link MAX_IDLE_POLLS} must not be lied
+ * to about.
+ */
+export function storedBytes(size: number, ranges: readonly UploadRange[] | undefined): number {
+  if (!ranges) return size;
+  return Math.max(
+    size,
+    ranges.reduce((total, range) => total + (range.end - range.start), 0),
+  );
+}
+
+/**
+ * Whether every byte of `segment` is stored, wherever in the file it landed.
+ *
+ * The prefix answers most of this — a whole-file upload has no windows and a
+ * finished one is covered end to end — and the `ranges` arm is what makes the
+ * streaming flow work against the browser's DEFAULT upload. That fan-out puts
+ * `UPLOAD_PART_CONCURRENCY` windows on the link at once, so they finish together
+ * and the prefix is zero until the last moment; measured on a deployed agent, a
+ * 27 MB recording at 0.9 MB/s reported `size: 0` for 45 of its 45 seconds. Read
+ * only the prefix and the run has nothing to do until the upload is over, which
+ * is the entire wait this flow exists to remove.
+ *
+ * A window has to be covered WHOLE by one run: `readUpload` clamps to the run a
+ * read starts in, so a segment straddling a hole would come back short and be
+ * transcribed as a fragment. `rangesOf` merges adjacent windows, so a run really
+ * is a contiguous stretch and one containment test is the whole check.
+ */
+export function segmentStored(segment: Segment, at: UploadProgressView): boolean {
+  if (segment.end <= at.size) return true;
+  return (at.ranges ?? []).some(
+    (range) => range.start <= segment.start && segment.end <= range.end,
+  );
 }
 
 /**
@@ -310,8 +584,6 @@ export async function probeUpload(id: string): Promise<UploadProgressView> {
  * 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)) {
@@ -354,9 +626,10 @@ 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.size} byte(s) stored and still incomplete. ` +
-      `Nothing new arrived for ${MAX_IDLE_POLLS} polls — the uploader stopped.`,
+    `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 ` +
+      "uploader stopped.",
   );
 }

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

@@ -63,16 +63,19 @@
  *   `output` exists only when the last segment does.
  */
 
+import type { WorkflowCtx } from "@alexkroman1/aai";
 import {
   emit,
   encodeWav,
   mapConcurrent,
   readUpload,
   report,
+  requireCompleteUpload,
   uploadInfo,
 } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
 import { countWords, formatDuration, plural } from "@alexkroman1/aai/utils";
+import { downsampleSegment, requestFormat } from "./downsample.ts";
 import { normalizeRecording } from "./normalize.ts";
 import { stitchTranscript, TRANSCRIPT_STREAM, type TranscriptChunk } from "./stitch.ts";
 import { elapsed, timed, transcribeWav } from "./sync-api.ts";
@@ -168,15 +171,18 @@ export const BYTES_IN_FLIGHT = 640 * 1024 * 1024;
  * The table above was measured under the old per-round barrier. Re-measuring it is
  * worth doing before this number moves again: the window makes a wide fan-out
  * cheaper at the tail, which if anything argues for a HIGHER knee. *
- * **What EXECUTES at this width is the world's call, not this number's.**
+ * **What EXECUTES at this width is the engine's call, not this number's.**
  * `mapConcurrent` bounds how many step calls the body has in flight; how many
- * run at once is the workflow world's worker concurrency, which on the
- * `DATABASE_URL` path defaults to three — so on a default deployment a width
- * above three is inert while still costing a queued job per item. That makes
- * this the FAR SIDE's knee and the width to use once an operator has raised
- * the ceiling, not a promise about a stock deployment. See "The WINDOW is not
- * the concurrency" in `@alexkroman1/aai/step`'s `mapConcurrent`; the numbers
- * above were measured against the endpoint and say nothing about that layer.
+ * run at once is `DEFAULT_STEP_CONCURRENCY` (`aai-runtime`), which is **16** —
+ * measured against a real microVM at Modal's guaranteed reservation, where a
+ * concurrent segment of 48 kHz stereo costs 26.1 MB. So a width above 16 is
+ * inert on a stock deployment while still costing a queued job per item, and
+ * this number is the FAR SIDE's knee: the one to use once an operator has
+ * raised `AAI_WORKFLOW_STEP_CONCURRENCY` for a larger guest. It was three,
+ * inherited from graphile-worker and never measured, which made every number
+ * in the table above unreachable. See "The WINDOW is not the concurrency" in
+ * `@alexkroman1/aai/step`'s `mapConcurrent`; the numbers above were measured
+ * against the endpoint and say nothing about that layer.
  */
 export const MAX_SEGMENT_CONCURRENCY = 32;
 
@@ -199,7 +205,13 @@ export const MAX_SEGMENT_CONCURRENCY = 32;
  * `stepFetch` pins.
  */
 export function segmentConcurrency(format: WavFormat): number {
-  const perSegment = bytesPerSecond(format) * (SEGMENT_SECONDS + SEGMENT_OVERLAP_SECONDS);
+  // The format that will be SENT, not the one that was cut. The budget is bytes
+  // UPLOADING and `transcribeSegment` normalizes each window first, so asking the
+  // source format would price a 48 kHz stereo segment at 17.66 MB when 2.94 MB
+  // goes on the wire — six times too cautious, and drifting the moment either
+  // side of that pair changes. Both derive it from `requestFormat`.
+  const perSegment =
+    bytesPerSecond(requestFormat(format)) * (SEGMENT_SECONDS + SEGMENT_OVERLAP_SECONDS);
   if (perSegment <= 0) return MAX_SEGMENT_CONCURRENCY;
   return Math.max(1, Math.min(MAX_SEGMENT_CONCURRENCY, Math.floor(BYTES_IN_FLIGHT / perSegment)));
 }
@@ -236,9 +248,7 @@ export type SegmentTranscript = {
  * The input is what `POST /workflows/runs` carries — see `agent.ts` for the
  * schema it is validated against before a run exists.
  */
-export async function transcribeFlow(input: { recording: string }) {
-  "use workflow";
-
+export async function transcribeFlow(input: { recording: string }, ctx: WorkflowCtx) {
   // Both at once: neither needs the other, and issued together they are one
   // round trip instead of two before any audio is read. The ORDER is still a
   // pure function of this line — the two calls go out synchronously, left to
@@ -247,12 +257,20 @@ export async function transcribeFlow(input: { recording: string }) {
   // The clock starts before the conversion rather than after it, because a
   // reader comparing the three flows over one file is comparing what the desk
   // COST them, and re-encoding an m4a is part of that.
-  const [startedAt, ready] = await Promise.all([startClock(), normalizeRecording(input.recording)]);
+  // `maxAttempts: 6` was `normalizeRecording.maxRetries = 5`. More than the
+  // default 3, and not because a conversion is flaky — a corrupt file fails
+  // identically forever, and `throwFfmpegStepError` is what stops the engine
+  // 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.
+  const [startedAt, ready] = await Promise.all([
+    ctx.step("startClock", () => startClock()),
+    ctx.step("normalizeRecording", () => normalizeRecording(input.recording), { maxAttempts: 6 }),
+  ]);
 
   // `ready.recording` from here on, not `input.recording`: a converted file is a
   // DIFFERENT upload, and cutting the original by offsets planned against the
   // converted one is a fan-out of garbage that still reports success.
-  const plan = await splitRecording(ready.recording);
+  const plan = await ctx.step("splitRecording", () => splitRecording(ready.recording));
 
   // One step per segment, bounded, in an order a replay reproduces exactly.
   // A failed segment fails the RUN, deliberately: every sibling that finished is
@@ -260,13 +278,20 @@ export async function transcribeFlow(input: { recording: string }) {
   // what is missing, where catching here to salvage a partial transcript would
   // return a recording with a silent hole in it and report success.
   const parts = await mapConcurrent(plan.segments, segmentConcurrency(plan.format), (segment) =>
-    transcribeSegment(ready.recording, plan.format, segment),
+    // `maxAttempts: 6` was `transcribeSegment.maxRetries = 5` — more than the
+    // default 3 because a rate limit is the expected failure here, and a segment
+    // that 429s is not a segment that is wrong.
+    ctx.step("transcribeSegment", () => transcribeSegment(ready.recording, plan.format, segment), {
+      maxAttempts: 6,
+    }),
   );
 
   // The ORIGINAL id, and only here: `mergeTranscript` uses it for the filename a
   // reader sees, and `standup.m4a` is the recording they uploaded — where the
   // converted copy is an artifact of how the desk works.
-  return await mergeTranscript(input.recording, plan.durationMs, parts, startedAt);
+  return await ctx.step("mergeTranscript", () =>
+    mergeTranscript(input.recording, plan.durationMs, parts, startedAt),
+  );
 }
 
 /**
@@ -283,10 +308,14 @@ export async function splitRecording(uploadId: string): Promise<{
   segments: Segment[];
   durationMs: number;
 }> {
-  "use step";
-
+  // The whole file, refused if it is still arriving. `info.size` is the readable
+  // PREFIX, and it is what the segment plan's width is derived from — so against a
+  // half-arrived recording this planned a fan-out over the first half and the run
+  // returned a transcript of it, reporting success. `stream.ts` is the flow for a
+  // recording that is still landing; this one wants all of it.
+  const stored = await requireCompleteUpload(uploadId);
   const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
-  const format = fatalOnUnsupported(() => parseWav(head.bytes, head.info.size));
+  const format = fatalOnUnsupported(() => parseWav(head.bytes, stored.size));
   const segments = fatalOnUnsupported(() => planSegments(format));
   const durationMs = segments.at(-1)?.endMs ?? 0;
 
@@ -308,8 +337,6 @@ export async function transcribeSegment(
   format: WavFormat,
   segment: Segment,
 ): Promise<SegmentTranscript> {
-  "use step";
-
   // One line per segment, which is what makes the fan-out legible to a page: the
   // status is `running` for the whole thing, so without this a sixty-segment
   // recording and a one-segment recording look identical while they run.
@@ -338,9 +365,29 @@ export async function transcribeSegment(
   // template's: a `WavFormat` is structurally a `PcmFormat`, and 22 lines of
   // `DataView` writes with a comment about which of the two declared lengths a
   // decoder trusts is not a thing worth a second copy of.
+  // Down to 16 kHz mono BEFORE the header goes on, because the endpoint's budget
+  // is 30 seconds of wall clock and that covers the upload. At 48 kHz stereo this
+  // window is 17.66 MB and the same audio is 2.94 MB normalized — six times the
+  // bytes against a fixed deadline, which is what turns a slow segment into a
+  // `504 request exceeded 30.0s` and then into a failed run. Inert on the classic
+  // flow, where `normalizeRecording` already converted the whole file; see
+  // `downsample.ts` for why the streaming flow cannot do the same.
+  //
+  // Through `fatalOnUnsupported` for the same reason `planStreamed` reads its
+  // header through it: `parseWav` admits any bit depth whose block align is
+  // positive, and `downsampleSegment` can serve only four of them — so a
+  // recording the desk could cut but cannot send raises
+  // `UnsupportedRecordingError` here, and a plain throw would spend all six
+  // attempts re-reading this window out of the upload store to arrive at the
+  // identical answer. BOTH flows can reach it, which is newer than it looks:
+  // the check used to hang off the resampler, so a 12-bit recording already at
+  // 16 kHz mono — light for both flows, and therefore converted by neither —
+  // sailed past it into an unclassified `RangeError` from `encodeWav`.
+  const light = fatalOnUnsupported(() => downsampleSegment(audio.bytes, format));
+
   const { value: text, ms } = await timed(() =>
     transcribeWav(
-      encodeWav(audio.bytes, format),
+      encodeWav(light.bytes, light.format),
       `segment-${segment.index}.wav`,
       `Segment ${segment.index} (${formatDuration(segment.startMs)})`,
     ),
@@ -364,12 +411,6 @@ export async function transcribeSegment(
   return { index: segment.index, text };
 }
 
-/**
- * Retries beyond the default 3, because a rate limit is the expected failure and
- * a segment that 429s is not a segment that is wrong.
- */
-transcribeSegment.maxRetries = 5;
-
 /**
  * Stitch the segments into one transcript.
  *
@@ -385,8 +426,6 @@ export async function mergeTranscript(
   parts: readonly SegmentTranscript[],
   startedAt: number,
 ): Promise<Transcript> {
-  "use step";
-
   await report(`Stitching ${parts.length} ${plural(parts.length, "segment")} together.`);
 
   // `mapConcurrent` resolves in ITEM order however the calls settled, so this is
@@ -427,8 +466,6 @@ export async function mergeTranscript(
  * which needs one number measured one way.
  */
 export async function startClock(): Promise<number> {
-  "use step";
-
   return Date.now();
 }