Motivation
Reliable byte streams such as paired audio capture need an efficient way to persist large outputs without retaining the entire payload in application memory. The existing writeFile effect replaces a whole file from one bounded byte array and is not suitable for hour-long PCM data or application-generated WAV files.
Design goal
Add generic, incremental, atomic binary file-writer effects usable from Zig and transpiled TypeScript. This should be a filesystem capability, not an audio-capture sink.
Candidate lifecycle:
- Open a keyed sibling temporary output without replacing an existing destination.
- Append bytes incrementally.
- Write at an explicit offset so formats such as WAV can finalize headers.
- Commit atomically after synchronization.
- Abort and remove temporary state.
- Bound queued writes and report backpressure or I/O failure explicitly.
- Finalize or abort safely during application shutdown.
The design must enforce manifest filesystem permission, define sandbox behavior, use fixed replay-safe command/result records, and decide how session replay validates writes without mutating the replay host.
Motivating consumers
- Application-generated WAV from reliable paired audio chunks.
- Incremental downloads and exports.
- Large logs or generated binary artifacts.
Out of scope for this ticket
- Audio capture or device APIs.
- A WAV encoder or codec-specific writer.
- Unbounded in-memory buffering.
This is a follow-up to the reliable paired audio-stream proposal that supersedes #254/#257; it is not required to land the stream primitive itself.
Motivation
Reliable byte streams such as paired audio capture need an efficient way to persist large outputs without retaining the entire payload in application memory. The existing
writeFileeffect replaces a whole file from one bounded byte array and is not suitable for hour-long PCM data or application-generated WAV files.Design goal
Add generic, incremental, atomic binary file-writer effects usable from Zig and transpiled TypeScript. This should be a filesystem capability, not an audio-capture sink.
Candidate lifecycle:
The design must enforce manifest filesystem permission, define sandbox behavior, use fixed replay-safe command/result records, and decide how session replay validates writes without mutating the replay host.
Motivating consumers
Out of scope for this ticket
This is a follow-up to the reliable paired audio-stream proposal that supersedes #254/#257; it is not required to land the stream primitive itself.