vercel-labs / vercel-labs/native

Design: add incremental atomic binary file-writer effects

Open
#263 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Zig
Stars
7.7k
Forks
314
Avg merge
5h
Merged PRs (30d)
13

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing writeFile effect and the reliable paired audio-stream proposal that supersedes #254/#257. Define the lifecycle, permissions, sandbox behavior, replay records, backpressure, shutdown handling, and atomic commit or abort behavior. Done means the design resolves these decisions without adding audio capture or codec-specific writing.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript, zig
Domain
desktop
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.