# Decision: lossless compressed native capture staging

Status: accepted
Action: implement

## Context and evidence

- Objective: eight real-engine product videos, 16:9 and approximately 60 Hz,
  without recording I/O undermining authoritative runtime behavior.
- Scope: local recording tooling and native client capture lifecycle. No
  deployment, production storage format or Package authority changes.
- Baseline: the intentionally dirty 2026-09-24 Windows workspace; per-run
  inputs and publication digests are stored under
  `target/practical-scenarios-20260924`. Capture code owns this change.
- A 1600x900 40-second sequence held approximately 14 GB of raw frame data.
  Concurrent staging saturated the shared E:/G: Samsung 870 QVO disk; a sampled
  queue depth was 10. Local control requests timed out during that workload.
  D: is a separate HDD, but its measured 22 MB/s made raw staging slower.
- The environment also produced intermittent local Wrangler proxy failures.
  Disk contention is demonstrated; it has not been proven to explain every
  proxy failure. Failed runs remain failures and are not product evidence.
  A later recovery attempt recorded `ProxyController: Error inside ProxyWorker`
  with `Network connection lost`, followed by lease-renewal failure and correct
  native authority shutdown. The suite therefore uses the existing direct
  workerd host, with the same Worker source and real local storage bindings.
  Publication and durable server recovery passed through that host before its
  use for replacement recordings. This isolates the development proxy rather
  than asserting a proven underlying network/disk root cause.
- An earlier size request silently fell through a two-value environment parser
  and captured the larger monitor size. Explicit dimensions now parse within
  320x180 through 3840x2160, and invalid values fail clearly.

## Alternatives and selection

| Option | Constraints and benefit | Cost / recovery | Disposition |
| --- | --- | --- | --- |
| Keep raw PJFRAME1 and serialize all work | No new format; known recovery | High disk volume and slow eight-scene turnaround | Retained as default compatibility path |
| Compress sealed staging records losslessly after cadence | Same pixels, time, bounded RAM and durable stage | Small versioned reader/writer change; old reader retained | Chosen opt-in for the suite |
| Analyze RAM directly and remove durable raw staging | Least disk work | Changes crash/analysis recovery contract and evidence ordering | Not chosen |
| Replace native capture with screen video tooling | Easy presentation export | Loses per-frame native receipts and world correlation | Not chosen |

Use the existing `image` PNG implementation with fast lossless compression in
PJFRAME2. The header payload length describes encoded bytes; metadata still
declares decoded dimensions and native channel order. The loader checks both
before allocating the decoded image. BGRA is swizzled at the same existing
boundary. The opt-in is `PAJAMA_CAPTURE_COMPRESSED_STAGE=1`; the suite combines
it with bounded RAM staging so compression occurs after the live cadence.

## Execution and acceptance

- Preserve slot numbers, wall-clock timestamps, reports and exact RGBA output.
  Keep the 16 GiB RAM/session guard, frame and metadata limits, atomic stage
  records, stage sealing, analysis checkpoint and fail-closed terminal state.
- Preserve PJFRAME1 reads and the original non-compressed default.
- After the last GPU mapping is harvested and Finalize is queued, an
  auto-exit recording only polls writer completion. It no longer renders an
  already-complete sequence. Interactive recording without auto-exit continues
  to render normally.
- Thirty capture tests passed, including compressed RGBA/BGRA round trips,
  truncation rejection, old native staging, manifest ordering, namespace
  changes and the GPU-to-writer handoff. Three window lifecycle/size tests
  passed earlier. Logs live with the suite validation artifacts.
- Every delivered video must additionally pass native manifest completion,
  timestamp validation, a full FFmpeg decode and visual review. Neither unit
  tests nor a successful encode alone certify an application scenario.
- No publication bypass is involved. An interrupted recording retains its
  existing unsuccessful/partial status; the harness retries into a fresh run
  directory rather than relabeling a partial sequence.

## Outcome and reuse

The first compressed camp run staged 2,400 main-camera frames in 3,348,549,913
bytes and measured about 60.0 Hz, compared with roughly 14 GB of uncompressed
staging. PNG analysis remains offline and is still a meaningful part of total
production time. Exact cadence, stalls and remaining failures are recorded in
each final video's proof rather than inferred from this one scene.

Overlapping three runs later produced one 127 ms main-camera interval in a
recovery opening sequence (1,170 of 1,200 requested slots). That sequence was
excluded from final gallery selection and recovery was scheduled again in
isolation. The suite now defaults to one job. The exporter computes frame
intervals directly; an empty native `gaps` list alone is insufficient evidence
of uninterrupted cadence.
The isolated replacement sampled all 1,200 frames in each recovery segment;
the buffered-frame journal measured maximum intervals of approximately 23 ms
and 25 ms. Final admission additionally requires the completed native manifests
and decoded videos.

Reuse for bounded local native captures with sufficient RAM. Revalidate on
different GPU/monitor DPI, unsupported dimensions, long recordings, storage
changes, or a changed image codec. This does not claim unlimited recording
duration, crash recovery from RAM, or MMO-scale server performance.