[Major] · Operability

Child stderr is now captured but fed only to log.debug, which is a no-op unless --debug is passed. Combined with the change at line 154-156, a default (non-debug) user now sees strictly less than before this PR.

Why: the observable outcome for a non-debug user is identical to the old 'ignore' — Failed to make bytecode X-Y for file Z with zero indication of cause — even though Pkg: Cached data not produced. is now captured and then discarded. The pipe is paid for and returns nothing to the people who actually hit the failure. This is the one behaviour change in the PR that makes diagnosis harder rather than easier.

Fix: buffer a bounded tail of the child's stderr per child and attach it to the onClose/onError message, rather than only log.debug-ing it.

(Minor, same line: data.toString().trim() runs on every stderr chunk even when log.debugMode is false — log.debug early-returns, but only after the decode already happened. Cheap to guard.)

[Major] · Operability

Demoting the unexpected-close output from an unconditional console.log to log.debug removes the last diagnostic a non-debug user had on this path.

Why: dropping the raw binary dump is right — it was ugly and could spew non-text to stdout. But the replacement is invisible without --debug, so ${cmd} closed unexpectedly now arrives with no context at all. Same root cause as the stderr routing at line 119-123.

Fix: keep it out of the default stdout stream, but surface a trimmed, printable-safe snippet in the error itself so it reaches users who aren't running with --debug.

[Major] · Design/API

A protocol violation exits 2, which onClose renders as the same generic Failed to make bytecode ... for file ${snap} as an ordinary "this file just won't compile".

Why: downstream (lib/producer.ts:487-505), --fallback-to-source was designed for the latter. A desynced pipe would silently degrade every remaining file to plain source behind log.warn lines — producing a green build that ships source instead of bytecode, with no way for the caller to tell a corrupt channel from an uncompilable file. A framing bug that should never happen becomes invisible in CI.

Fix: make the protocol error distinguishable from a compile failure — a dedicated exit code or a typed error — so producer.ts can abort loudly instead of degrading quietly.

The same guard on the body header (line 23-26) has no test, unlike its snap-side twin.

[Minor] · Performance

Buffer.concat([stdin, data]) on every chunk re-copies the whole accumulated buffer, making frame reassembly O(n²) in total bytes. The parent's stdout = Buffer.concat([stdout, data]) has the same shape.

Why: a 1MB body in 64KB chunks copies ~8.7MB (~8.7x); 5MB copies ~202MB (~40x). This runs once per JS file across a multi-thousand-file build. Pre-existing — flagging it because the PR rewrote this exact loop and kept the pattern.

Fix: accumulate chunks in an array and concat once when a complete frame is available, or track a write offset into a pre-sized buffer. Reasonable as a follow-up rather than in this PR.

[Minor] · Performance

subarray returns a view over the same backing ArrayBuffer, so a few leftover bytes keep the entire concatenated allocation reachable until the next data event reassigns stdin.

Why: bounded, but the retention scales with frame size — worst case a 256MB backing store held alive by a handful of slack bytes. The correctness of the fix isn't affected (the next Buffer.concat reallocates); this is purely transient memory.

Fix: copy the remainder into a fresh right-sized buffer when the consumed prefix is large relative to what's left.

[Nit] · Design/API

The [Buffer, Buffer, Buffer, Buffer] return type leaks the frame layout into the signature and pins callers to arity; Buffer[] (or a single concatenated Buffer) says the same thing. The only consumer immediately does for (const chunk of requestChunks).

Entirely optional.

[Major] · DRY / Codebase Fit

parseBlobFrames is a fourth hand-rolled implementation of this protocol — and it's written correctly: it loops over multiple frames and rejects negative sizes. The shipped parser it's validating against (lib/fabricator.ts:160-171) does neither.

Why: the regression test asserts the child's output against a parser that doesn't exist in production, so a regression in the real parent decoder cannot be caught here. The correct logic lives only in the test file. That gap is the clearest signal that the hardening should be applied in both directions.

Fix: extract the "accumulate → validate header against the shared max → slice frame → keep remainder" step into one function used by both the parent's onData and this test. The child script is the one place that must keep its own inline copy, since it has to be self-contained source text.

[Minor] · Tests

Asserting on the exact stderr string couples the test to a log message, and a piped-stderr write immediately before process.exit(2) can truncate.

Why: I measured 0/100 losses on Linux for a message this short (and 40/40 truncation at 200KB), so the risk is low — but Node documents pipe writes as async on macOS and this repo's matrix includes macos-latest. A flaky assertion on a log string isn't worth the coverage it adds over line 107.

Fix: assert.equal(code, 2) already proves the guard fired and distinguishes it from every other exit path. Dropping the assert.match loses nothing.

[Minor] · Tests + Correctness

write(A) immediately followed by end(B) on a pipe is routinely coalesced into a single read on the child side, so the partial-header resume path (the break at lib/fabricator.ts:21/28) may never actually execute — only the multi-frame path is deterministic here.

Why: the test's stated purpose is cross-boundary splitting, but the split isn't guaranteed to survive to the child. It would still pass if the resume logic were broken.

Fix: await the first blob (or at least a tick) before writing the tail, so the two chunks are guaranteed to arrive as separate data events.

While here: splitAt = 3 only exercises one offset. I fuzzed all 119 and the implementation is correct — but a loop over a handful of offsets (including inside the size header) would lock that in.

[Minor] · Tests

Only the snap size header rejection is tested; the body size header guard (lib/fabricator.ts:23-26) has no coverage despite being part of the same fix.

Why: the two guards are symmetric but independent — the body one sits behind an extra break at line 21, so it's on a different path, and a regression there wouldn't be caught.

Fix: send a valid snap frame followed by a -1 body size and assert exit code 2. Also worth adding: zero-length snap and zero-length body, which the current cases don't touch.

No timeout wraps either of the child-process promises in this file — if a child hangs, the test hangs rather than failing.