@alexkroman1/aai-cli 9.0.2 → 9.1.0

package/dist/scaffold/package.json

@@ -14,9 +14,9 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^9.0.2",
-    "@alexkroman1/aai-runtime": "^9.0.2",
-    "@alexkroman1/aai-ui": "^9.0.2",
+    "@alexkroman1/aai": "^9.1.0",
+    "@alexkroman1/aai-runtime": "^9.1.0",
+    "@alexkroman1/aai-ui": "^9.1.0",
     "@workflow/world-postgres": "4.3.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -26,7 +26,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^9.0.2",
+    "@alexkroman1/aai-cli": "^9.1.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

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

@@ -31,7 +31,13 @@ import { FatalError, RetryableError } from "workflow";
 import { z } from "zod";
 import agentDef, { transcribe, transcribeBatch, transcribeStream } from "./agent.ts";
 import { createJob, pollTranscript, uploadToProvider } from "./workflows/batch.ts";
-import { cuttable, normalizeRecording } from "./workflows/normalize.ts";
+import {
+  cuttable,
+  heavierThanNormalized,
+  NORMALIZED_CHANNELS,
+  NORMALIZED_SAMPLE_RATE,
+  normalizeRecording,
+} from "./workflows/normalize.ts";
 import { expectedSegments, planStreamed, probeUpload } from "./workflows/stream.ts";
 import {
   mergeTranscript,
@@ -897,6 +903,59 @@ describe("normalizing the recording", () => {
     expect(cuttable(dense, 44 + 32_000)).toBe(false);
   });
 
+  test("48 kHz stereo is cuttable and still too heavy to cut as it is", () => {
+    // The file that broke a real run. It parses, it cuts, and every 92-second
+    // segment of it is 17.7 MB against 2.94 MB normalized — six times the upload
+    // per request, against a sync endpoint that deadlines at 30s. `cuttable`
+    // cannot see that, which is the whole reason there are two predicates.
+    const heavy = wavFile({ sampleRate: 48_000, channels: 2, bitsPerSample: 16 }, 32_000);
+    expect(cuttable(heavy, 44 + 32_000)).toBe(true);
+    expect(heavierThanNormalized(heavy, 44 + 32_000)).toBe(true);
+  });
+
+  test.each([
+    ["a higher rate alone", { sampleRate: 44_100, channels: 1, bitsPerSample: 16 }],
+    ["more channels alone", { sampleRate: 16_000, channels: 2, bitsPerSample: 16 }],
+  ])("%s is enough to convert", (_label, fmt) => {
+    // Either axis on its own, because the segment cost is their PRODUCT — a file
+    // that is only wide or only fast still costs a multiple of the target.
+    expect(heavierThanNormalized(wavFile(fmt, 32_000), 44 + 32_000)).toBe(true);
+  });
+
+  test("the normalize target itself is not heavier than itself", () => {
+    // The predicate has to be false at the fixed point or the fast path is dead
+    // and every recording pays an ffmpeg pass that produces its own input.
+    const target = {
+      sampleRate: NORMALIZED_SAMPLE_RATE,
+      channels: NORMALIZED_CHANNELS,
+      bitsPerSample: 16,
+    };
+    expect(heavierThanNormalized(wavFile(target, 32_000), 44 + 32_000)).toBe(false);
+  });
+
+  test("a rate BELOW the target is left alone rather than upsampled", () => {
+    // 8 kHz telephony audio. Converting it would invent no information and cost a
+    // full pass over the recording, so the comparison is `>` and not `!==`.
+    const narrow = wavFile({ sampleRate: 8000, channels: 1, bitsPerSample: 16 }, 32_000);
+    expect(heavierThanNormalized(narrow, 44 + 32_000)).toBe(false);
+  });
+
+  test("a heavy WAV is CONVERTED, and the line says why rather than lying", async () => {
+    // The report used to read "not a WAV we can cut" on every conversion, which
+    // for this file contradicts the thing the caller uploaded. The conversion
+    // itself is out of tier (it spawns ffmpeg), so what is asserted is that the
+    // fast path was declined and the reason given is the weight.
+    publishRecording(
+      wavFile({ sampleRate: 48_000, channels: 2, bitsPerSample: 16 }, 32_000),
+      "workshop.wav",
+    );
+    const reporter = installStubReporter();
+    await normalizeRecording(UPLOAD_ID).catch(() => undefined);
+    const said = reporter.lines.join(" ");
+    expect(said).not.toContain("already linear-PCM WAV");
+    expect(said).toContain("heavier per second than 16 kHz mono");
+  });
+
   test("an already-cuttable recording keeps the id it came in under", async () => {
     // The property that matters: no second upload, so the fan-out reads the file
     // the caller stored. A step that copied it would double the storage every run

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

@@ -33,9 +33,18 @@
  * including a 192 kHz 32-bit stereo WAV that trips
  * {@link MAX_BYTES_PER_SECOND}, which downsampling genuinely repairs.
  *
- * The fast path costs one 64 KB read and no subprocess at all: a WAV that was
- * already cuttable is returned by the id it came in under, so nothing is copied
- * and nothing is re-encoded.
+ * The fast path costs one 64 KB read and no subprocess at all: a WAV that is
+ * already cuttable AND already light enough is returned by the id it came in
+ * under, so nothing is copied and nothing is re-encoded.
+ *
+ * ## Cuttable is not the same as worth cutting
+ *
+ * {@link parseWav} succeeding is necessary and not sufficient. A 48 kHz stereo
+ * WAV parses and cuts perfectly and is six times the bytes per request that the
+ * same audio is at {@link NORMALIZED_SAMPLE_RATE} mono — which the sync
+ * endpoint's 30-second deadline turns from a cost into a failure. So the fast
+ * path is gated on {@link heavierThanNormalized} as well, and that predicate's
+ * own doc carries the measurement.
  *
  * ## File → file, not bytes → bytes
  *
@@ -130,7 +139,7 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
   const stored = await uploadInfo(uploadId);
   const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
 
-  if (cuttable(head.bytes, stored.size)) {
+  if (cuttable(head.bytes, stored.size) && !heavierThanNormalized(head.bytes, stored.size)) {
     // No subprocess, no copy, no second upload. The overwhelmingly common case
     // for a desk whose form says WAV, and the reason the check is a 64 KB read.
     await report(`${stored.name || uploadId} is already linear-PCM WAV — cutting it as it is.`);
@@ -141,8 +150,16 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
   // long recording and a run that says nothing until the conversion finishes looks
   // stuck. It is also the line that distinguishes "this file needs converting" from
   // the fast path above.
+  // WHY it is being converted, because there are now two reasons and they look
+  // nothing alike to a reader watching the log: a file the parser refused, and a
+  // WAV that is fine but too heavy to cut at this rate. Reporting "not a WAV we
+  // can cut" for the second one is a line that contradicts the file they
+  // uploaded.
   await report(
-    `Converting ${stored.name || uploadId} (${formatBytes(stored.size)}) — not a WAV we can cut.`,
+    `Converting ${stored.name || uploadId} (${formatBytes(stored.size)}) — ` +
+      (cuttable(head.bytes, stored.size)
+        ? `heavier per second than ${NORMALIZED_SAMPLE_RATE / 1000} kHz mono.`
+        : "not a WAV we can cut."),
   );
 
   // The temp directory's lifetime is this lexical scope, and the `finally` inside
@@ -238,6 +255,44 @@ export function cuttable(head: Uint8Array, totalBytes: number): boolean {
   }
 }
 
+/**
+ * Whether cutting this file AS IS would make every request too heavy.
+ *
+ * {@link cuttable} asks whether `splitRecording` CAN read the header; this asks
+ * whether it SHOULD. They are different questions and the answers point opposite
+ * ways for one common file: a 48 kHz stereo recording parses perfectly and cuts
+ * perfectly, and each 92-second segment of it is 17.7 MB against the 2.94 MB the
+ * same segment is once normalized. The sync endpoint deadlines a request at 30s,
+ * 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
+ * is discarded and re-billed on the resume).
+ *
+ * This is NOT the "second opinion" the module doc warns about. That warning is
+ * about the pass-through decision disagreeing with the CUT decision — passing
+ * through something `splitRecording` then cannot read. This predicate can only
+ * ever send MORE files to ffmpeg, never fewer, and what comes back is 16 kHz mono
+ * by construction, so the two decisions still cannot disagree.
+ *
+ * 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. Note this deliberately does NOT look at
+ * `bitsPerSample` — `wavEncodeArgs` emits `pcm_s16le`, so a 24- or 32-bit file at
+ * 16 kHz mono really would shrink, but that is a 1.5-2x saving on a file already
+ * inside the budget, and converting it costs an ffmpeg pass over the whole
+ * recording. Revisit if a 32-bit mono source ever shows up in practice.
+ *
+ * Safe to call only where {@link cuttable} has already answered `true` — it
+ * re-parses the same window and a rejected header would throw here rather than
+ * answering.
+ */
+export function heavierThanNormalized(head: Uint8Array, totalBytes: number): boolean {
+  const format = parseWav(head, totalBytes);
+  return format.sampleRate > NORMALIZED_SAMPLE_RATE || format.channels > NORMALIZED_CHANNELS;
+}
+
 /** `41:20 of aac`, or as much of that as ffprobe would say. */
 function describeSource(codec: string | undefined, durationSec: number | undefined): string {
   const length =

package/package.json

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