@alexkroman1/aai-cli 6.4.0 → 6.5.0

package/dist/scaffold/package.json

@@ -13,8 +13,8 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^6.4.0",
-    "@alexkroman1/aai-ui": "^6.4.0",
+    "@alexkroman1/aai": "^6.5.0",
+    "@alexkroman1/aai-ui": "^6.5.0",
     "@workflow/world-postgres": "4.3.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -23,7 +23,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^6.4.0",
+    "@alexkroman1/aai-cli": "^6.5.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

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

@@ -17,7 +17,7 @@
  * the decoder happily transcribes into confident nonsense.
  */
 
-import { stubStepFetch, stubUploads } from "@alexkroman1/aai/testing";
+import { stubReporter, stubStepFetch, stubUploads } from "@alexkroman1/aai/testing";
 import { readUpload } from "@alexkroman1/aai/utils";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { FatalError, RetryableError } from "workflow";
@@ -30,7 +30,9 @@ import {
   clock,
   mergeTranscript,
   splitRecording,
+  stitchChunks,
   stitchTranscript,
+  TRANSCRIPT_STREAM,
   transcribeSegment,
 } from "./workflows/transcribe.ts";
 import {
@@ -421,6 +423,52 @@ describe("stitchTranscript", () => {
   });
 });
 
+describe("stitchChunks — what the PAGE renders while a run is going", () => {
+  const chunk = (index: number, text: string) => ({
+    index,
+    startMs: index * 1000,
+    endMs: (index + 1) * 1000,
+    text,
+  });
+
+  test("orders by index, because chunks arrive as the segments settle", () => {
+    // The one thing a live reader definitely does not have is arrival order: the
+    // segments are transcribed concurrently, so chunk 2 routinely precedes 1.
+    expect(stitchChunks([chunk(2, "gamma"), chunk(0, "alpha"), chunk(1, "beta")])).toBe(
+      "alpha beta gamma",
+    );
+  });
+
+  test("stitches the seams the same way the finished run does", () => {
+    // The whole reason the page imports the run's own function: a live
+    // transcript that de-duplicated differently would read as the model having
+    // changed its mind between the last poll and the result.
+    const parts = ["we should ship it on Friday", "ship it on Friday if the tests pass"];
+    expect(stitchChunks(parts.map((text, index) => chunk(index, text)))).toBe(
+      stitchTranscript(parts),
+    );
+  });
+
+  test("keeps both pieces around a HOLE rather than seaming across it", () => {
+    // A partial list is the ordinary case here, and two pieces that were never
+    // adjacent share no overlap — so the live text reads with a jump in it until
+    // the missing segment lands, instead of quietly losing a sentence.
+    expect(stitchChunks([chunk(0, "alpha beta"), chunk(2, "epsilon zeta")])).toBe(
+      "alpha beta epsilon zeta",
+    );
+  });
+
+  test("does not mutate the caller's list, which is React state", () => {
+    const chunks = [chunk(1, "beta"), chunk(0, "alpha")];
+    stitchChunks(chunks);
+    expect(chunks.map((one) => one.index)).toEqual([1, 0]);
+  });
+
+  test("renders nothing out of nothing", () => {
+    expect(stitchChunks([])).toBe("");
+  });
+});
+
 describe("clock", () => {
   test("renders a position a reader can find in the recording", () => {
     expect(clock(0)).toBe("0:00");
@@ -525,6 +573,30 @@ describe("transcribeSegment", () => {
     expect(decoded).toContain("RIFF");
   });
 
+  test("EMITS the segment's words as it lands, into the transcript stream", async () => {
+    // What makes the run's answer streamable rather than only its narration: the
+    // page stitches whatever has arrived, so the transcript renders growing
+    // instead of appearing when the last segment does. The reporter is the SDK's
+    // published slot, which is the same seam `report()` goes through.
+    const reported = stubReporter();
+    stubs.push(reported.restore);
+    stubProvider();
+
+    await transcribeSegment(UPLOAD_ID, FORMAT, SEGMENT);
+
+    // The timestamps ride along for the READER — a partial transcript has holes
+    // in it, and "0:00–0:01" is what explains a jump.
+    expect(reported.emitted).toEqual([
+      {
+        namespace: TRANSCRIPT_STREAM,
+        chunk: { index: 0, startMs: 0, endMs: 1000, text: "hello there" },
+      },
+    ]);
+    // And the narration is still its own stream: lines a page prints verbatim
+    // cannot share a channel with objects.
+    expect(reported.lines.some((line) => line.startsWith("Transcribing"))).toBe(true);
+  });
+
   test("fails FATALLY with no API key rather than retrying five times", async () => {
     vi.stubEnv("ASSEMBLYAI_API_KEY", "");
     stubProvider();

package/dist/templates/transcription-workflow/api-help.tsx

@@ -136,6 +136,14 @@ const ROUTES: readonly { route: string; does: string }[] = [
     route: "PUT  /workflows/uploads/:id",
     does: "store a file under YOUR id, readable as it arrives",
   },
+  {
+    route: "POST /workflows/uploads/:id/parts",
+    does: "declare an upload its parts fill in · ?total=<bytes>",
+  },
+  {
+    route: "PUT  /workflows/uploads/:id/parts",
+    does: "one window of it · ?offset=<byte>, sent concurrently",
+  },
   { route: "GET  /workflows/uploads/:id", does: "read the bytes back · Range honoured" },
   { route: "GET  /workflows/uploads/:id/info", does: "name, bytes stored so far, and complete" },
 ];

package/dist/templates/transcription-workflow/client.tsx

@@ -42,15 +42,52 @@
  * because they take the same input and return the same shape, and the only thing
  * the page chooses is which HOOK submits it.
  *
- * `useWorkflowStream` is the streaming half: it cuts the file with the cutter this
- * template supplies (`cut-wav.ts`, which is `workflows/wav.ts` run in the browser),
- * uploads each part under one group token, and wakes the run as each lands.
- * `useWorkflowSubmit` is the classic half and is unchanged.
+ * `useWorkflowStream` is the streaming half: it mints the upload id, starts the run
+ * on it, sends the file, and wakes the run when the bytes land. `useWorkflowSubmit`
+ * is the classic half and is unchanged.
  *
  * Streaming is the DEFAULT because it is faster on any real recording. The classic
- * path stays selectable because it is the shape to read first, and because it is
- * the one that works on a file this browser cannot parse — the cutter needs a WAV
- * header, where the server-side flow reaches the same conclusion in its first step.
+ * path stays selectable because it is the shape to read first.
+ *
+ * ## The third control is about the UPLOAD, not the flow
+ *
+ * "Split the file across connections" (`parallel`) is orthogonal to the three modes
+ * and applies to all of them, which is why it is a checkbox beside the radios
+ * rather than a fourth option. A single request moves a file at one connection's
+ * throughput, which over any distance is a fraction of the link — so the SDK cuts
+ * the file into megabyte-aligned parts and sends four at once. Nothing about the
+ * workflow changes: the agent reassembles them, `readUpload` reads the same
+ * windows, and the streaming flow still watches the file grow (what it polls is the
+ * CONTIGUOUS prefix, which is honest whether one connection or four are filling
+ * it).
+ *
+ * It is selectable rather than always-on for the reason the modes are: this is the
+ * template where a reader runs both over the same recording and sees what each
+ * costs. It also degrades on its own — a small file, or an agent deployed before
+ * the `/parts` routes existed, sends the single request instead — so leaving it on
+ * is safe.
+ *
+ * ## The transcript ARRIVES, rather than appearing at the end
+ *
+ * A run's `output` exists only when its last segment does, so a page with only
+ * that shows a status line for the whole fan-out and then everything at once — on
+ * a 97-minute recording, minutes of it. Each segment is emitted the moment it
+ * lands (`emit(TRANSCRIPT_STREAM, …)` in `workflows/transcribe.ts`) and
+ * `useWorkflowProgress` reads that stream, so the panel renders the transcript
+ * growing.
+ *
+ * Three things make it honest rather than decorative:
+ *
+ * - **The page stitches with the RUN's own function.** `stitchChunks` is
+ *   `workflows/stitch.ts`, imported by both, so the live text and the stored one
+ *   cannot drift into two different transcripts of one recording.
+ * - **It is a SEPARATE stream from the progress log.** `report()`'s lines go to
+ *   the default one, which `<WorkflowProgress>` renders verbatim; objects in
+ *   there would come out as `[object Object]` between the sentences.
+ * - **The finished run wins.** Once `output` exists the panel renders that
+ *   instead — it is the authoritative text, counted and measured, and a live
+ *   transcript that stayed on screen beside it would be a second answer with no
+ *   way to tell which was current.
  *
  * ## Two waits, two bars
  *
@@ -77,6 +114,7 @@ import {
   page,
   SubmitButton,
   UploadProgressBar,
+  useWorkflowProgress,
   useWorkflowRuns,
   useWorkflowStream,
   useWorkflowSubmit,
@@ -84,9 +122,16 @@ import {
   WorkflowProgress,
   type WorkflowRun,
 } from "@alexkroman1/aai-ui";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import type { transcribe } from "./agent.ts";
 import { ApiHelp } from "./api-help.tsx";
+import {
+  clock,
+  countWords,
+  stitchChunks,
+  TRANSCRIPT_STREAM,
+  type TranscriptChunk,
+} from "./workflows/stitch.ts";
 
 /**
  * What a finished run reports.
@@ -142,12 +187,16 @@ const HISTORY_LIMIT = 10;
 
 function TranscriptionDesk() {
   const [mode, setMode] = useState<Mode>("streaming");
+  // Whether the browser cuts the recording up and sends the pieces at once. One
+  // piece of state for all three hooks, because it describes the UPLOAD and every
+  // mode has one — see the module doc.
+  const [parallel, setParallel] = useState(true);
   // ALL THREE hooks are called every render, because a hook may not be conditional —
   // and that costs nothing here: none of them does anything until its `submit` is
   // called, and `useWorkflowRun` underneath them holds no id until then either.
-  const streamed = useWorkflowStream<Transcript>(WORKFLOWS.streaming);
-  const stored = useWorkflowSubmit<Transcript>(WORKFLOWS.classic);
-  const batched = useWorkflowSubmit<Transcript>(WORKFLOWS.batch);
+  const streamed = useWorkflowStream<Transcript>(WORKFLOWS.streaming, { parallel });
+  const stored = useWorkflowSubmit<Transcript>(WORKFLOWS.classic, { parallel });
+  const batched = useWorkflowSubmit<Transcript>(WORKFLOWS.batch, { parallel });
   // The batch flow uploads the same way the classic one does — the id comes from the
   // store — so it is the SAME hook against a different workflow. Only the streaming
   // mode needs the other one, because only it needs the id before the bytes.
@@ -184,6 +233,8 @@ function TranscriptionDesk() {
 
       <ModePicker mode={mode} onPick={setMode} disabled={pending} />
 
+      <UploadPicker parallel={parallel} onPick={setParallel} disabled={pending} />
+
       {/* No mapping: the collected values already match the input schema. All three
           workflows declare `recording` as an upload, so the same picker serves every
           mode — how the bytes travel is not a question to ask a person. */}
@@ -256,6 +307,49 @@ function ModePicker({
   );
 }
 
+/**
+ * How the recording travels, as one checkbox.
+ *
+ * Beside the mode radios rather than among them because it answers a different
+ * question — those pick the WORKFLOW, this picks how its input gets there — and
+ * every mode is uploading a file either way.
+ *
+ * Disabled mid-submission for the same reason the radios are: the bytes are
+ * already moving, and a control that looks live while changing nothing is worse
+ * than one that is plainly unavailable.
+ */
+function UploadPicker({
+  parallel,
+  onPick,
+  disabled,
+}: {
+  parallel: boolean;
+  onPick: (next: boolean) => void;
+  disabled: boolean;
+}) {
+  return (
+    <fieldset className="flex flex-col gap-3" disabled={disabled}>
+      <legend className="text-sm font-medium uppercase tracking-[1.2px]">Upload</legend>
+      <label className="flex items-start gap-3 text-sm">
+        <input
+          type="checkbox"
+          className="mt-1"
+          name="parallel"
+          checked={parallel}
+          onChange={(event) => onPick(event.target.checked)}
+        />
+        <span className="flex flex-col gap-0.5">
+          <span>Split the file across connections</span>
+          <span className="text-xs opacity-70">
+            Sends the recording as several parts at once instead of in one request, which is most of
+            the wait on a long file. Falls back to the single request on a small one.
+          </span>
+        </span>
+      </label>
+    </fieldset>
+  );
+}
+
 /**
  * Every recent run, newest first, with its transcript one click away.
  *
@@ -338,6 +432,11 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onClear?: ()
           finished run up in the panel below shows how it got there. */}
       <WorkflowProgress runId={run.runId} />
 
+      {/* While it runs, the transcript so far. Unguarded on the run's status
+          beyond this: the component renders nothing until a segment has landed,
+          and stops the moment there is an `output` to render instead. */}
+      {!isTerminal(run) && <LiveTranscript runId={run.runId} />}
+
       {/* Discriminated on `status`, so `output` and `error` are reachable
           without a cast — the reason a snapshot is a union rather than a flat
           object with optional fields. */}
@@ -356,6 +455,45 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onClear?: ()
   );
 }
 
+/**
+ * The transcript as it arrives, stitched from the segments that have landed.
+ *
+ * The other half of `<WorkflowProgress>` above it: that one renders what the run
+ * SAYS about itself, this one renders what it has produced. Both are the same
+ * mechanism — a run's output stream — separated by the namespace, which is what
+ * lets this one be typed.
+ *
+ * It renders NOTHING until a segment lands, so a page can mount it unguarded:
+ * before the first chunk there is nothing to say that the progress log is not
+ * already saying better.
+ *
+ * The count is derived from the stitched text rather than summed per chunk,
+ * because the seams overlap — adding up the segments would over-count every one
+ * of them by a couple of seconds' worth of words.
+ */
+function LiveTranscript({ runId }: { runId: string }) {
+  const { progress } = useWorkflowProgress<TranscriptChunk>(runId, {
+    namespace: TRANSCRIPT_STREAM,
+  });
+  // Memoized on the ARRAY, which the hook appends to per read: stitching is a
+  // seam search per segment, and a fan-out re-renders this panel on every
+  // progress poll whether or not anything arrived.
+  const transcript = useMemo(() => stitchChunks(progress), [progress]);
+  if (progress.length === 0) return null;
+
+  // The furthest point reached, not the count: segments land out of order, so
+  // "6 segments" says nothing about how much of the recording is covered.
+  const covered = Math.max(...progress.map((chunk) => chunk.endMs));
+  return (
+    <div className="flex flex-col gap-2">
+      <p className="text-xs opacity-60">
+        {countWords(transcript)} words so far · through {clock(covered)}
+      </p>
+      <pre className="whitespace-pre-wrap text-sm leading-relaxed opacity-80">{transcript}</pre>
+    </div>
+  );
+}
+
 /**
  * A duration a person can read.
  *

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

@@ -40,7 +40,8 @@
  *
  * That is also why the step that does it is the step the DevKit retries: a streaming
  * body is consumed once, so a retry has to re-read the upload from the start, which
- * it does.
+ * it does. One window of READ-AHEAD keeps the store and the socket busy at the same
+ * time; `windows` carries the argument.
  */
 
 import { throwFatalStepError, toStepError } from "@alexkroman1/aai/step-errors";
@@ -100,8 +101,13 @@ const MAX_POLLS = 360;
 export async function transcribeBatchFlow(input: { recording: string }): Promise<Transcript> {
   "use workflow";
 
-  const startedAt = await startClock();
-  const { audioUrl } = await uploadToProvider(input.recording);
+  // Both at once: the clock does not depend on the upload, and issuing them
+  // together costs one round trip instead of two before a byte moves. Their issue
+  // order is still decided by this line rather than by which lands first.
+  const [startedAt, { audioUrl }] = await Promise.all([
+    startClock(),
+    uploadToProvider(input.recording),
+  ]);
   const job = await createJob(audioUrl);
 
   for (let poll = 0; poll < MAX_POLLS; poll += 1) {
@@ -241,17 +247,33 @@ export async function readTranscript(
 }
 
 /**
- * The stored upload as a sequence of windows.
+ * The stored upload as a sequence of windows, with the next one already in flight.
  *
  * A generator rather than one `readUpload`, because the whole point is that the file
  * is never held: each window is read, sent, and dropped. `readUpload` clamps to what
  * is stored, so the loop ends on the real end of the file even if `size` moved.
+ *
+ * **One window of READ-AHEAD**, which is the whole concurrency available here: the
+ * consumer is a socket and the producer is the app's own store, and read-then-send
+ * makes them strictly alternate — the store idles while bytes go out, and the socket
+ * idles while the next window is fetched. Starting the next read before yielding the
+ * current window overlaps them, so a gigabyte upload pays the larger of the two
+ * rather than their sum. Exactly one, not a queue: a deeper buffer holds more of a
+ * file this generator exists to avoid holding, and there is nothing to gain past
+ * keeping both ends busy.
  */
 async function* windows(uploadId: string, size: number): AsyncGenerator<Uint8Array> {
-  for (let at = 0; at < size; at += UPLOAD_WINDOW_BYTES) {
-    const slice = await readUpload(uploadId, { start: at, end: at + UPLOAD_WINDOW_BYTES });
-    if (slice.bytes.length === 0) return;
-    yield slice.bytes;
+  const read = (at: number): Promise<Uint8Array> =>
+    readUpload(uploadId, { start: at, end: at + UPLOAD_WINDOW_BYTES }).then((slice) => slice.bytes);
+  let at = 0;
+  let next = at < size ? read(at) : undefined;
+  while (next !== undefined) {
+    const bytes = await next;
+    if (bytes.length === 0) return;
+    at += UPLOAD_WINDOW_BYTES;
+    // Issued BEFORE the yield, so the store is fetching while the socket sends.
+    next = at < size ? read(at) : undefined;
+    yield bytes;
   }
 }
 

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

@@ -0,0 +1,133 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Joining segment transcripts back into one — and the only module here the PAGE
+ * imports.
+ *
+ * That is the whole reason it exists as its own file. Segments are transcribed
+ * one per step and each one is emitted the moment it lands (`emit("transcript",
+ * …)` in `transcribe.ts`), so the page can render the answer growing rather than
+ * a spinner — and to render it, the page has to do exactly what `mergeTranscript`
+ * does at the end: put the pieces in order and drop the words the overlap made
+ * duplicates.
+ *
+ * Two copies of that would drift, and they would drift INVISIBLY: a live
+ * transcript that stitches differently from the stored one reads as the model
+ * having changed its mind. So the seam logic is here, imported by the run and by
+ * the browser, with nothing else in the module — no directive, no I/O, no SDK
+ * import — so pulling it into the client bundle costs a few hundred bytes.
+ *
+ * `wav.ts` and `sync-api.ts` sit under `workflows/` on the same terms: the WDK
+ * builder scans this directory and transforms only what carries a directive.
+ */
+
+/**
+ * The stream a run publishes its segments into as they land.
+ *
+ * Declared HERE because it is the one string the run and the page have to agree
+ * on: a step emits into it and `client.tsx` subscribes by it, and a typo is a
+ * panel that renders nothing with nothing saying why. Both sync flows write it;
+ * the async flow has one segment and nothing to stream.
+ */
+export const TRANSCRIPT_STREAM = "transcript";
+
+/**
+ * One segment as it goes over {@link TRANSCRIPT_STREAM}.
+ *
+ * Its own type rather than the step's journaled result widened, because the two
+ * have different readers: `mergeTranscript` needs an index and words, while
+ * somebody watching a partial transcript needs to know WHICH part of the
+ * recording each piece is — the list has holes in it until the run finishes, and
+ * "0:00–1:30" beside a paragraph is what explains a jump.
+ */
+export type TranscriptChunk = {
+  index: number;
+  /** Where this piece starts in the recording. */
+  startMs: number;
+  /** Where it ends. */
+  endMs: number;
+  text: string;
+};
+
+/** Most words {@link stitchTranscript} will look back over to find a repeated seam. */
+const MAX_SEAM_WORDS = 40;
+
+/** A word, stripped of the punctuation the decoder added, for seam comparison. */
+function seamKey(word: string): string {
+  return word.toLowerCase().replace(/[^\p{L}\p{N}']/gu, "");
+}
+
+/**
+ * Join segment transcripts, dropping the words the overlap made duplicates.
+ *
+ * Segments overlap by `SEGMENT_OVERLAP_SECONDS` (see `wav.ts` for why), so the
+ * last few words of one segment are the first few of the next — verbatim when
+ * the decoder heard them the same way, which is the common case because it heard
+ * the same audio. This finds the longest such run and removes one copy.
+ *
+ * Comparison is on `seamKey`, not the raw words: the two passes punctuate
+ * differently at their own edges (one ends a sentence where the other is
+ * mid-clause), so `"today."` and `"today"` are the same word and a raw compare
+ * finds no seam at all. The text KEPT is the raw text — only the match is
+ * normalized.
+ *
+ * A missed seam repeats a few words, which a reader can see and forgive. A
+ * false one would delete speech, so the search is bounded at
+ * {@link MAX_SEAM_WORDS} and always prefers the LONGEST match: a single repeated
+ * "the" is not evidence of anything, and requiring the longest run is what stops
+ * it counting as one when a longer match is available.
+ *
+ * **A gap is not a seam, which is what makes this safe to run on a PARTIAL
+ * list.** The page stitches whatever segments have arrived, and while a run is in
+ * flight that list has holes in it — segment 4 may land before segment 3. Two
+ * pieces that were never adjacent share no overlap, so no seam is found and both
+ * are kept whole: the live text reads with a jump in it until the missing piece
+ * arrives, rather than quietly losing a sentence.
+ */
+export function stitchTranscript(parts: readonly string[]): string {
+  const merged: string[] = [];
+  for (const part of parts) {
+    const next = part.split(/\s+/).filter(Boolean);
+    if (next.length === 0) continue;
+    if (merged.length === 0) {
+      merged.push(...next);
+      continue;
+    }
+    merged.push(...next.slice(seamLength(merged, next)));
+  }
+  return merged.join(" ");
+}
+
+/** How many leading words of `next` repeat the tail of `merged`. */
+function seamLength(merged: readonly string[], next: readonly string[]): number {
+  const limit = Math.min(MAX_SEAM_WORDS, merged.length, next.length);
+  // Longest first, so a short accidental match never wins over a real seam.
+  for (let length = limit; length > 0; length--) {
+    const tail = merged.slice(merged.length - length);
+    if (tail.every((word, at) => seamKey(word) === seamKey(next[at] ?? ""))) return length;
+  }
+  return 0;
+}
+
+/**
+ * Order the chunks that have arrived and stitch them — what the PAGE renders.
+ *
+ * Sorted here rather than by the caller because arrival order is the one thing a
+ * live reader definitely does not have: segments are transcribed concurrently and
+ * each is emitted the moment it lands, so chunk 4 routinely precedes chunk 3.
+ *
+ * A COPY, because the caller's list is React state.
+ */
+export function stitchChunks(chunks: readonly TranscriptChunk[]): string {
+  return stitchTranscript([...chunks].sort((a, b) => a.index - b.index).map((chunk) => chunk.text));
+}
+
+/** Words in a string. The run and the page count them the same way. */
+export function countWords(text: string): number {
+  return text.split(/\s+/).filter(Boolean).length;
+}
+
+/** `m:ss` for the progress log — a byte offset means nothing to a reader. */
+export function clock(ms: number): string {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}

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

@@ -101,17 +101,25 @@
  * shape and is never slower, which is why the page offers both rather than replacing
  * one with the other.
  *
- * ## And a batch has to finish before the next poll
+ * ## A ROUND has to finish before the next poll
  *
- * The DevKit correlates a journal entry to a step call by ISSUE ORDER, which is what
- * rules out a work-stealing pool — `mapInBatches`'s own doc carries the argument. So
- * a segment that becomes readable while a batch is running waits for that batch. On
- * a slow uplink that costs nothing (segments arrive slower than they transcribe); on
- * a fast one it is why the two flows converge rather than the streaming one winning.
+ * Everything the body decides comes from a journaled poll, so the set of segments it
+ * fans out over is fixed for the length of that fan-out: one that becomes readable
+ * while a round is in flight waits for the round. That is a smaller wait than it was
+ * — `mapConcurrent` is a window over a cursor rather than sequential batches, so a
+ * round now ends when its LAST segment lands rather than at the sum of each batch's
+ * slowest — but it is not zero, and it is why the two flows converge on a fast
+ * uplink rather than the streaming one winning. On a slow uplink it costs nothing:
+ * segments arrive slower than they transcribe.
+ *
+ * Feeding new segments into a running fan-out would remove it and is deliberately
+ * not done: which items are in flight would then depend on when bytes arrived, and
+ * the DevKit correlates a journal entry to a step call by ISSUE ORDER. A round is
+ * what keeps that order a pure function of journaled values.
  */
 
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
-import { mapInBatches, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import { mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
 import {
   clock,
@@ -209,10 +217,11 @@ export async function transcribeStreamFlow(input: { recording: string }) {
         lastSize = at.size;
         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 `mapInBatches` issues its
-        // calls in array order. THE SAME STEP the classic flow uses.
+        // `ready` is derived from a journaled poll, and `mapConcurrent` issues its
+        // calls in list order. THE SAME STEP the classic flow uses, so a segment
+        // transcribed here reaches the page's live transcript identically.
         parts.push(
-          ...(await mapInBatches(
+          ...(await mapConcurrent(
             ready,
             segmentConcurrency((plan as StreamPlan).format),
             (segment) => transcribeSegment(input.recording, (plan as StreamPlan).format, segment),

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

@@ -44,17 +44,28 @@
  *   app's own upload store and the run carries only its id; each step reads
  *   exactly its own window with `readUpload`. Sixty steps therefore move the
  *   recording once between them, not sixty times.
- * - **The fan-out is bounded by `mapInBatches`, and the bound is not a detail.**
+ * - **The fan-out is bounded by `mapConcurrent`, and the bound is not a detail.**
  *   The DevKit correlates a journal entry to a step call by the ORDER the call
- *   was issued in, so a work-stealing pool — which issues its next call only
- *   when a previous one settles — puts the calls in a different order on a
- *   replay than it did on the first execution. That primitive is sequential
- *   batches of `Promise.all` for exactly that reason; its module doc carries the
- *   argument.
+ *   was issued in, so the primitive keeps a WINDOW over a cursor that only ever
+ *   hands out the next index — the Nth call issued is segment N-1 however the
+ *   calls settle. Its module doc carries the argument; what matters here is that
+ *   there is no barrier, so a slow segment costs only itself.
+ * - **The transcript STREAMS as it is produced.** Each segment is emitted the
+ *   moment it lands (`emit(TRANSCRIPT_STREAM, …)`), so the page renders the
+ *   answer growing rather than a status line and then everything at once. That is
+ *   the difference a fan-out can make to a reader and a run output cannot: an
+ *   `output` exists only when the last segment does.
  */
 
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
-import { mapInBatches, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import { emit, mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import {
+  clock,
+  countWords,
+  stitchTranscript,
+  TRANSCRIPT_STREAM,
+  type TranscriptChunk,
+} from "./stitch.ts";
 import { elapsed, timed, transcribeWav } from "./sync-api.ts";
 import {
   bytesPerSecond,
@@ -117,14 +128,16 @@ export const BYTES_IN_FLIGHT = 640 * 1024 * 1024;
  * The widest fan-out, however small the segments are.
  *
  * Because {@link BYTES_IN_FLIGHT} stops being the binding constraint once segments
- * are small — 16 kHz mono would divide out to 173 — and something else takes over
- * before that helps. `mapInBatches` is a barrier rather than a work-stealing pool,
- * deliberately, because the DevKit correlates a journal entry to a step call by the
- * order the call was issued in: a batch's wall time is therefore its SLOWEST request
- * and a run's is the sum of those, so depth is paid at p100 and the tail widens with
- * it (p95/p50 measured 1.1x at 20 concurrent against 1.5x at 320, max/p50 reaching
- * 6.7x — 5.2s against 35.0s). A `503` carrying `retry-after: 1` is exactly such a
- * straggler, which is why overshooting is cheap in BILLING and not in latency.
+ * are small — 16 kHz mono would divide out to 173 — and the endpoint's own tail
+ * takes over before that helps: p95/p50 measured 1.1x at 20 concurrent against
+ * 1.5x at 320, with max/p50 reaching 6.7x (5.2s against 35.0s). A `503` carrying
+ * `retry-after: 1` is exactly such a straggler.
+ *
+ * **That tail used to be paid once per ROUND, and is not any more.** `mapConcurrent`
+ * was `mapInBatches` — sequential batches of `Promise.all` — so a batch's wall time
+ * was its slowest member and a run's was the sum of those. It is a window over a
+ * cursor now: a straggler holds up nothing but itself, and the numbers below were
+ * measured under the old barrier, so they are if anything pessimistic.
  *
  * 32 is the measured knee over 65 segments (1h37m of 48 kHz stereo), one concurrency
  * per run, through this workflow:
@@ -142,6 +155,10 @@ export const BYTES_IN_FLIGHT = 640 * 1024 * 1024;
  * also inert below a threshold — at 90-second segments, 32 only binds past 48
  * minutes of audio — so on a typical recording the whole fan-out is in flight
  * either way and this number changes nothing.
+ *
+ * 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.
  */
 export const MAX_SEGMENT_CONCURRENCY = 32;
 
@@ -155,7 +172,7 @@ export const MAX_SEGMENT_CONCURRENCY = 32;
  *
  * Safe to call from a workflow BODY: `format` arrives from a journaled step result,
  * so a replay derives the same width from the same bytes — which is what keeps
- * `mapInBatches` issuing its calls in the order the journal recorded them.
+ * `mapConcurrent` issuing its calls in the order the journal recorded them.
  *
  * Overshooting stays recoverable whatever this returns: a `503` carries
  * `retry-after` and `toStepError` below honours it, so the run completes having paid
@@ -178,9 +195,6 @@ export function segmentConcurrency(format: WavFormat): number {
  */
 const HEADER_PROBE_BYTES = 64 * 1024;
 
-/** Most words `stitchTranscript` will look back over to find a repeated seam. */
-const MAX_SEAM_WORDS = 40;
-
 /**
  * What a finished run reports, whichever flow produced it.
  *
@@ -201,7 +215,7 @@ export type Transcript = {
   transcript: string;
 };
 
-/** What one segment's request came back with. */
+/** What one segment's request came back with — the STEP's result, journaled. */
 export type SegmentTranscript = {
   index: number;
   text: string;
@@ -216,15 +230,18 @@ export type SegmentTranscript = {
 export async function transcribeFlow(input: { recording: string }) {
   "use workflow";
 
-  const startedAt = await startClock();
-  const plan = await splitRecording(input.recording);
+  // 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
+  // right — which is what a replay reproduces.
+  const [startedAt, plan] = await Promise.all([startClock(), splitRecording(input.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
   // already journaled, so the resume replays those for free and re-issues only
   // 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 mapInBatches(plan.segments, segmentConcurrency(plan.format), (segment) =>
+  const parts = await mapConcurrent(plan.segments, segmentConcurrency(plan.format), (segment) =>
     transcribeSegment(input.recording, plan.format, segment),
   );
 
@@ -309,6 +326,17 @@ export async function transcribeSegment(
   // The LATENCY, which is what says whether the concurrency bound or the endpoint
   // is the thing limiting the run — see `timed`'s doc.
   await report(`Transcribed ${clock(segment.startMs)}–${clock(segment.endMs)} in ${elapsed(ms)}.`);
+  // And the WORDS, into their own stream, which is what makes this run's answer
+  // streamable rather than only its narration: the page stitches whatever has
+  // arrived and renders the transcript growing, minutes before `output` exists.
+  // Its own namespace because `report`'s stream carries sentences a page prints
+  // verbatim — see `emit`'s doc.
+  await emit(TRANSCRIPT_STREAM, {
+    index: segment.index,
+    startMs: segment.startMs,
+    endMs: segment.endMs,
+    text,
+  } satisfies TranscriptChunk);
   return { index: segment.index, text };
 }
 
@@ -337,7 +365,7 @@ export async function mergeTranscript(
 
   await report(`Stitching ${parts.length} segment${parts.length === 1 ? "" : "s"} together.`);
 
-  // `mapInBatches` resolves in ITEM order however the calls settled, so this is
+  // `mapConcurrent` resolves in ITEM order however the calls settled, so this is
   // already ordered — sorted anyway, because the merge is where an ordering
   // mistake would be invisible rather than loud.
   const ordered = [...parts].sort((a, b) => a.index - b.index);
@@ -358,7 +386,7 @@ export async function mergeTranscript(
   };
 }
 
-// ---- Pure helpers -----------------------------------------------------------
+// ---- The run's own clock ----------------------------------------------------
 
 /**
  * When the run started, as epoch ms.
@@ -380,66 +408,17 @@ export async function startClock(): Promise<number> {
   return Date.now();
 }
 
-/** A word, stripped of the punctuation the decoder added, for seam comparison. */
-function seamKey(word: string): string {
-  return word.toLowerCase().replace(/[^\p{L}\p{N}']/gu, "");
-}
-
-/**
- * Join segment transcripts, dropping the words the overlap made duplicates.
- *
- * Segments overlap by `SEGMENT_OVERLAP_SECONDS` (see `wav.ts` for why), so the
- * last few words of one segment are the first few of the next — verbatim when
- * the decoder heard them the same way, which is the common case because it heard
- * the same audio. This finds the longest such run and removes one copy.
- *
- * Comparison is on `seamKey`, not the raw words: the two passes punctuate
- * differently at their own edges (one ends a sentence where the other is
- * mid-clause), so `"today."` and `"today"` are the same word and a raw compare
- * finds no seam at all. The text KEPT is the raw text — only the match is
- * normalized.
- *
- * A missed seam repeats a few words, which a reader can see and forgive. A
- * false one would delete speech, so the search is bounded at
- * `MAX_SEAM_WORDS` and always prefers the LONGEST match: a single repeated
- * "the" is not evidence of anything, and requiring the longest run is what stops
- * it counting as one when a longer match is available.
- */
-export function stitchTranscript(parts: readonly string[]): string {
-  const merged: string[] = [];
-  for (const part of parts) {
-    const next = part.split(/\s+/).filter(Boolean);
-    if (next.length === 0) continue;
-    if (merged.length === 0) {
-      merged.push(...next);
-      continue;
-    }
-    merged.push(...next.slice(seamLength(merged, next)));
-  }
-  return merged.join(" ");
-}
-
-/** How many leading words of `next` repeat the tail of `merged`. */
-function seamLength(merged: readonly string[], next: readonly string[]): number {
-  const limit = Math.min(MAX_SEAM_WORDS, merged.length, next.length);
-  // Longest first, so a short accidental match never wins over a real seam.
-  for (let length = limit; length > 0; length--) {
-    const tail = merged.slice(merged.length - length);
-    if (tail.every((word, at) => seamKey(word) === seamKey(next[at] ?? ""))) return length;
-  }
-  return 0;
-}
-
-/** Words in a string. Exported so the streaming flow reports the same number. */
-export function countWords(text: string): number {
-  return text.split(/\s+/).filter(Boolean).length;
-}
-
-/** `m:ss` for the progress log — a byte offset means nothing to a reader. */
-export function clock(ms: number): string {
-  const seconds = Math.max(0, Math.round(ms / 1000));
-  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
-}
+// `clock` and `countWords` are re-exported rather than re-declared: `stream.ts`
+// and `batch.ts` already import them from this module, and the split that let the
+// PAGE stitch a partial transcript should not ripple through every flow.
+export {
+  clock,
+  countWords,
+  stitchChunks,
+  stitchTranscript,
+  TRANSCRIPT_STREAM,
+  type TranscriptChunk,
+} from "./stitch.ts";
 
 // ---- I/O helpers ------------------------------------------------------------
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -44,8 +44,8 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.2.1",
     "zod": "^4.4.3",
-    "@alexkroman1/aai": "6.4.0",
-    "@alexkroman1/aai-ui": "6.4.0"
+    "@alexkroman1/aai": "6.5.0",
+    "@alexkroman1/aai-ui": "6.5.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",