Corvus Bytes To Bytes

Bytes-to-bytes: killing record<->document string seams

A record<->document string seam is the most expensive allocation anti-pattern in this codebase and the one most often re-introduced. It is a value that arrives as bytes, is materialized into a managed string (or List<string> / Dictionary<string,…> / a per-row POCO), and is then written back out as bytes — a u-turn through the managed heap. Both ends are bytes; the string is pure overhead, plus a closure if a non-static builder lambda is involved.

The cost is real and measured: a per-row row-security scan was 25.78 KB -> 1.56 KB (0.06x) once the filter walked the persisted UTF-8 instead of SecurityTagSet.ToList() per row; a directory grantee projection was 5.88 KB -> 2.01 KB (0.34x) once value/label flowed as spans instead of GetString.

The genuine-leaf proof (run this BEFORE you write a string)

The words "genuine leaf", "marginal", "admin-rare", "low-frequency", "pragmatic", "good enough", "consistency win", "too fragile", "edge case", "one X's worth" are red flags: they are usually a justification reached for first, to license skipping the bytes mechanism. Before any of them excuses a managed string on a warm/hot path, write a two-ended trace and check both ends:

If EITHER end is bytes/spans and a documented mechanism exists, it is NOT a leaf — it is work you are avoiding. A "constructed" value (e.g. first + " " + last, a prefix + dimension key) is never a leaf: assemble it into a pooled/stack UTF-8 buffer, not a string. The mechanism always exists:

When the excuse is "too fragile" / "edge case" (a self-imposed invariant)

Sometimes the string (or the List + per-item concat that builds it) isn't defended as a leaf but as too risky to remove — "the sort has a '-' vs '.' edge case needing a careful comparer", "I'd have to reproduce the exact output bytes", "it's only one row's worth". That difficulty is almost always self-imposed: it comes from preserving the existing code's incidental output shape (an entry/element order, a container layout, an insertion order), not from the task itself. Before you skip it: (1) name the exact invariant making it fragile; (2) read the consumer — the reader, the sink, the comparer — and check whether it actually requires that invariant. An order-independent reader (finds entries by name/key, not position), a sink that re-normalises/re-canonicalises, or a content-addressed-by-hash artifact does not. When no consumer requires it, the invariant is incidental — drop it and the clean low-alloc form falls out. Example: WorkflowPackage.PackPooled sorts sources by key in a pooled scratch array and emits a fixed bucket order (workflow, sources, metadata), writing each entry name as UTF-8 directly ("sources/"u8 + key + ".json"u8, length back-patched) — instead of reproducing the old full-name sort, which removed the List + per-source name string outright (PackCanonicalPackage 0.73 -> 0.49 KB, scales per source). Treating incidental output shape as a contract is the anchoring-on-existing-code failure (deriving the replacement from what the old code happened to do) applied to behaviour instead of style.

Opaque tokens are a carrier seam too ("store-minted, so it stays a string" is a rationalization)

An opaque pagination/continuation token round-trips between two UTF-8 ends — emitted into a JSON response, carried back in the next JSON request (a CTJ JsonString) — so "it is store-minted, not domain data, so it stays a string" is a genuine-leaf rationalization: both ends are bytes. Encode it bytes-native with System.Buffers.Text.Base64Url (GetEncodedLength + EncodeToUtf8 straight into the destination; GetMaxDecodedLength + DecodeFromUtf8 from the request's pageToken.GetUtf8String().Span) — no EncodeToString/DecodeFromChars char detour, and no per-part ToString()/concat/GetBytes (assemble the key into a stackalloc/ArrayPool UTF-8 buffer with a separator byte). The token must survive into the response, but owned ≠ GC: pool it in a disposable carrier rather than minting a string (the only necessarily-GC form). The cross-root request→store JsonString is bridged with JsonString.From(...) (free rewrap). The lifetime that governs emitting it is the deferred-body rule — see corvus-ctj-handler-implementation.