buffer: one byte-access API; perry-ffi stops writing at cell+8 (B1)

[proggeramlug]

Refs #11919. Buffer slice B1 of BUFFER-DESIGN.md; owner decision 85.

Removes: every native extension's raw write at cell+8. perry-ffi::alloc_buffer now copies through js_perry_bytes_copy and BufferHeader is opaque, so an extension can't derive a payload address from it. 14 runtime/stdlib raw writers move onto one access API: buffer/access.rs, bun_compat, child_process, dgram, embedded, fs, node_v8, tls, typedarray (duplicate resolvers unified), and stdlib ethers, tls and zlib.

Adds: buffer::bytes, a single API for byte access:

• a scoped borrow that needs a no_gc token and ends before any allocation or JS;
• an owner-thread pin that roots the owner, defers the native release on detach, and keeps process-shared SharedArrayBuffer headers read-only;
• allocation and copying.

The C ABI js_perry_bytes_{borrow,pin,unpin,new,copy,adopt} lives in native_payload_abi.rs, under the payload digest shared with draft #12064. There is no new header size, table, cache, latch, placement threshold or codegen rule. A source ratchet (scripts/check_buffer_layout.py) blocks new raw-layout sites.

Tests (current main merged):

• runtime 5,159/0;
• codegen: all pass;
• stdlib 255 pass, with the same 2 thread-exit failures as main;
• ext-zlib 17/0;
• FFI 74/0.

Witnesses cover a moving collection during a pin, detach lifetime, spans across every current placement, NativeArena disposal, a native-backed allocation through the alloc_buffer ABI, and two agents pinning a shared buffer. Each has a child sabotage that turns it red: restoring the cell+8 copy, dropping the owner root, freeing on detach, and corrupting each converted producer.

Known limit: pin refuses engine-owned foreign memory, the wasm memory.grow case. Borrowing still covers it.

Program A/B: in the comment below.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 8f4b47e9-0a1f-4179-a110-ecbda545a56b

📥 Commits

Reviewing files that changed from the base of the PR and between c85c2db and 96cc204.

📒 Files selected for processing (59)

• .github/workflows/test.yml
• changelog.d/PENDING-buffer-b1.md
• crates/perry-ext-ethers/src/lib.rs
• crates/perry-ext-http/src/agent/tls_compat.rs
• crates/perry-ext-http/src/client_outgoing.rs
• crates/perry-ext-http/src/server/http2_settings.rs
• crates/perry-ext-http/src/server/https_server.rs
• crates/perry-ext-http/src/server/server/upgrade_tests.rs
• crates/perry-ext-http/src/server/types.rs
• crates/perry-ext-http/src/server/upgrade.rs
• crates/perry-ext-http/src/tls_client.rs
• crates/perry-ext-net/src/jsvalue.rs
• crates/perry-ext-sharp/src/lib.rs
• crates/perry-ext-streams/src/lib.rs
• crates/perry-ext-ws/src/lib.rs
• crates/perry-ext-zlib/src/lib.rs
• crates/perry-ext-zlib/src/stream.rs
• crates/perry-ffi/src/buffer.rs
• crates/perry-ffi/src/bytes.rs
• crates/perry-ffi/src/error.rs
• crates/perry-ffi/src/lib.rs
• crates/perry-ffi/src/native_payload.rs
• crates/perry-ffi/src/types.rs
• crates/perry-runtime/src/buffer/access.rs
• crates/perry-runtime/src/buffer/bytes.rs
• crates/perry-runtime/src/buffer/header.rs
• crates/perry-runtime/src/buffer/mod.rs
• crates/perry-runtime/src/bun_compat/mod.rs
• crates/perry-runtime/src/child_process/value_util.rs
• crates/perry-runtime/src/dgram/net.rs
• crates/perry-runtime/src/embedded.rs
• crates/perry-runtime/src/fs/mod.rs
• crates/perry-runtime/src/gc/fromspace_scan.rs
• crates/perry-runtime/src/gc/tests/buffer_bytes.rs
• crates/perry-runtime/src/gc/tests/fromspace_scan.rs
• crates/perry-runtime/src/gc/tests/mod.rs
• crates/perry-runtime/src/gc/types.rs
• crates/perry-runtime/src/lib.rs
• crates/perry-runtime/src/native_arena.rs
• crates/perry-runtime/src/native_payload_abi.rs
• crates/perry-runtime/src/node_v8.rs
• crates/perry-runtime/src/tls.rs
• crates/perry-runtime/src/tls/b1_output_tests.rs
• crates/perry-runtime/src/typedarray/mod.rs
• crates/perry-runtime/src/typedarray_view.rs
• crates/perry-stdlib/src/buffer_b1_test_support.rs
• crates/perry-stdlib/src/ethers.rs
• crates/perry-stdlib/src/ethers/b1_output_tests.rs
• crates/perry-stdlib/src/lib.rs
• crates/perry-stdlib/src/tls.rs
• crates/perry-stdlib/src/tls/b1_output_tests.rs
• crates/perry-stdlib/src/zlib.rs
• crates/perry-stdlib/src/zlib/b1_output_tests.rs
• scripts/buffer_b1_build.sh
• scripts/buffer_b1_gap.py
• scripts/buffer_b1_validate.py
• scripts/buffer_layout_baseline.json
• scripts/check_buffer_layout.py
• scripts/check_buffer_layout.sh

 ___________________________________________________
< Your TODOs are starting to look like a manifesto. >
 ---------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[proggeramlug]

Rebased onto main c85c2db (#12104 streams, #12105 statepoints), head 96cc204. The payload ABI is reconciled to v2: the family descriptor names a PayloadVTable, so there is one descriptor, with separate byte-span and stream digests. #12096's new size_of::() in fromspace_scan now goes through buffer_payload_size (caught by the layout ratchet).

Checks on head:

• release build and fmt pass;
• check_buffer_layout: 148 sites, 0 new;
• buffer tests 214, ffi 47+5, fromspace_scan 7: all pass;
• gap subset buffer/typed/dataview/arraybuffer/zlib/crypto/tls: 103/103;
• earlier merged check (main 81e65f3): runtime 5164/0, codegen clean, 107-test gap subset with 0 regressions, all programs match node, instructions within ±0.05% (worker_heavy +0.84%, inside its scheduling spread), typed kernels identical.

tsc RSS (+2.1 MB median, THP off, n=5): file-backed code pages. Anonymous memory is flat to −1 MB, and arena_live and GC counts are identical. Section sizes are identical apart from 512 B less .text; .perry_src is at the same offset. The extra resident pages are in the binary's r-xp mapping (65.0 → 68.6 MB). Explained under PERF_POLICY rule 2.