Add L0 contiguous-buffer BinaryWriter

[intech]

Summary

Replaces the chunk-list + scratch-array state in BinaryWriter with a
single growable Uint8Array plus an integer-offset stack for fork()/
join() framing. Ports the OpenTelemetry PR #6390 ProtobufWriter
pattern into the general-purpose protobuf-es writer while preserving
all 20 public methods (signatures and wire-byte output are identical).

Implementation follows the pinned design decisions in
analysis/p1-t1-l0-design-spec.md (13 decisions, D1-D13).

Pinned decisions applied

• D1/D2/D3: single Uint8Array, 1,024-byte initial capacity, 2x growth
• D4/D5/D6: placeholder-and-shift fork/join via copyWithin; the
  stack holds integer offsets only (no per-fork object allocation)
• D7: single-pass ASCII probe in string() with UTF-8 fallback
• D8: finish() returns buf.subarray(0, pos) — no copy. A lazy-reset
  flag keeps the returned slice stable if the writer is reused.
• D10: removed the legacy protected buf: number[] field
• D11: cached DataView, rebuilt on grow
• D13: int64 family uses a typeof tri-dispatch (number/bigint/string)
  with fallback to protoInt64.enc/uEnc for out-of-range or invalid
  inputs (error-message parity is maintained)

Additive L0 API

Three new public instance methods exposed for upcoming L1/L2 consumers:

• ensureCapacity(n: number): void — grow the backing buffer to hold
  n more bytes
• currentOffset(): number — return the current write position
• patchVarint32At(offset: number, value: number): void — back-patch
  an unsigned 32-bit varint at a previously reserved offset

Measurements

Node.js 25.8, 100-span ExportTraceRequest fixture (37,547 bytes on
the wire), .tmp/l0-bench/.

Workload	Baseline	L0	Delta
toBinary 100 spans	525 ops/s	2,278 ops/s	+334%
toBinary SimpleMessage (KeyValue)	733,279 ops/s	783,726 ops/s	+7%
B/op 100 spans (5-run median)	6,338 B	7,616 B	+20% (see note)

Memory note. The per-encode heap delta varies heavily across runs
as minor-GC timing shifts (baseline ranges 3k-42k B; L0 ranges 7k-15k
B). L0 allocations from the writer itself dropped dramatically (no
more 3,917 per-encode Uint8Array wrappers), but steady-state encode
memory is now dominated by reflection dispatch allocations
(ReflectMessage iterators, KeyValue attribute maps). The
≤1,500 B/op gate in the design spec targets post-Tier-B numbers; this
PR unblocks the throughput gate but defers the memory gate to the
reflection-layer work (P1-T2b follow-up).

Gates (per analysis/p1-t1-l0-design-spec.md §7)

• Byte-parity — OTel fixture round-trip produces byte-identical
  output before and after (.tmp/l0-bench/verify-correctness.ts
  reports bytesIdentical: true)
• ≥+30% ops/s OTel — actual +334% (2,278 vs 525)
• ≤1,500 B/op memory — blocked by reflection dispatch; writer
  allocations dropped as designed, but the global heap delta needs
  Tier-B work to clear the gate
• No SimpleMessage regression — +7% (well within ±10%)
• finish + raw combined self-time ≤10% — measured 0.05% on
  L0 vs. 29.92% baseline (Node 25.8.1, 100-span OTel fixture,
  30k iterations, 100 µs sampling). Full report:
  analysis/p1-t2b-profile-verification.md. See
  gate-#5 verification comment.

Breaking notes

• Removed the undocumented protected buf: number[] field. No internal
  consumer (to-binary.ts, size-delimited.ts, extensions.ts)
  touches it; external subclassers must migrate to the public API
  (raw(), ensureCapacity()).
• finish() now returns a Uint8Array subarray view that aliases the
  writer's backing buffer. A lazy-reset flag swaps the buffer on the
  next write, so reuse works the same as the legacy writer — but
  callers must not mutate the returned slice while the writer is still
  in use.

Test plan

• All 2,823 existing tests in @bufbuild/protobuf-test pass
• All 187 tests in @bufbuild/protoplugin-test pass
• All 4 tests in @bufbuild/protoplugin-example pass
• 52 new L0-specific tests added in binary-encoding-l0.test.ts,
  covering:
  • ensureCapacity growth edges (1,024 → 4,096 → 100,000 B)
  • Placeholder-and-shift at every varint-size boundary (0, 1, 127,
    128, 16,383, 16,384, 2,097,151, 2,097,152)
  • 10-deep nested fork/join round-trip
  • join() without matching fork() throws
  • string() ASCII fast-path and UTF-8 fallback (empty, ASCII,
    long ASCII > initial capacity, é, emoji, mixed)
  • int64 tri-dispatch parity (number / bigint / string) for every
    family method (uint64, fixed64, int64, sfixed64)
  • Additive API contracts (currentOffset, ensureCapacity,
    patchVarint32At)
  • finish() returns a stable view even after reuse

Scope

Internal PR within the Connectum-Framework/protobuf-es fork.
Foundation for L1 (schema plans) and L2 (specialized writers).

Single-revert rollback if needed: git revert <merge-sha> restores
the chunk-based writer in one action (no dual implementation to
maintain, per spec §9).

Follow-ups tracked as P1-T2b:

• CPU profile capture to close gate prototype(protobuf): template-based per-schema encoder (H3A) #5 formally
• Reflection-layer memory reduction to close gate prototype(protobuf): two-pass size estimator (+6.28x encode, -54% memory) #3

[intech]

P1-T2b — Gate #5 formally verified ✅

CPU-profile comparison captured on the OTel 100-span ExportTraceRequest
fixture (32,926 B wire size, 30 k reflective toBinary iterations, Node
25.8.1 with --cpu-prof at 100 µs sampling).

finish + raw combined self-time

Branch	Total samples	finish + raw hits	Combined self-time
main (baseline)	77,389	23,161	29.92 %
feat/l0-contiguous-writer	18,495	11	0.05 %

Gate #5 target: ≤ 10 % — measured 0.05 %. PASS (600× headroom).

Extended finish + raw + fork + join view: baseline 31.49 % → L0 2.34 %.

Throughput observed during profiling

main 414 ops/s → L0 1,767 ops/s (+327 %) — consistent with the
+334 % reported from .tmp/l0-bench/ in the PR body.

Top baseline hotspots eliminated

• finish 14.97 % → below profile cutoff
• raw 14.94 % → 0 hits in L0
• fixed64 3.50 % → 0.30 % (no more per-call new Uint8Array(8))
• TextEncoder.encode 27.73 % → absorbed by the inlined ASCII fast-path
  in L0's string() (remaining work tracked under the string frame
  itself at 11.86 %, and absolute hit count dropped ~10×)

New dominant hotspots in L0 (next-step vectors)

• Reflection (ReflectMessageImpl, assertOwn, values,
  get sortedFields, unsafeIsSet) — 29.66 % combined → L1
  schema-plan work
• Dispatch (writeMessageField, writeFields, writeField,
  writeListField, writeScalar) — 19.10 % → L2 specialized
  writers (codegen)
• string UTF-8 path — 11.86 %
• GC — 2.10 % (vs. 1.34 % baseline; the relative share rose only
  because the rest of the pipeline got faster)

Full report and methodology: analysis/p1-t2b-profile-verification.md
(includes the jq commands needed to reproduce every number).

Profiles preserved at:

• .tmp/p1-t2b-profile/baseline-main.cpuprofile (906 KB)
• .tmp/p1-t2b-profile/l0.cpuprofile (362 KB)

---

Gate summary after P1-T2b

• Byte-parity — verified in PR (verify-correctness.ts)
• ≥ +30 % ops/s OTel — +334 % measured in PR (+327 % re-confirmed here)
• ≤ 1,500 B/op memory — deferred to reflection-layer work (P1-T2c)
• No SimpleMessage regression — +7 % in PR
• finish + raw ≤ 10 % self-time — 0.05 % measured (this report)