May 6, 2026 · In Review · parameter-encoding-and-binding

Experiment 126: Wide UTF-8 Batch Parameter Packing

Date: 2026-05-06

Status: In Review

Direction:parameter-encoding-and-binding

Problem

Experiment 125 proved that wide ASCII-heavy batches still had removable

per-string utf8.encode allocation after exp 113's direct matrix encoder:

the accepted fast path writes ASCII code units directly into the native

parameter payload tail and falls back to the generic encoder for non-ASCII.

That left the exact follow-up called out in exp 125's future notes: before

generalizing the string encoder, benchmark a non-ASCII-heavy workload

directly. The generic fallback still allocates one temporary Uint8List per

non-ASCII string cell, then copies those bytes into the same native batch

payload buffer.

External contract checks:

• Dart's Utf8Encoder.convert encodes unpaired surrogate code units as

U+FFFD: https://api.dart.dev/dart-convert/Utf8Encoder/convert.html

• SQLite sqlite3_bind_text accepts an explicit byte length; embedded NULs

are preserved when the length is non-negative:

https://www.sqlite.org/c3ref/bind_blob.html

• SQLite permits NUL characters in stored strings, though its CLI and some SQL

functions display surprising truncated views:

https://www.sqlite.org/nulinstr.html

Hypothesis

For large wide non-ASCII batches, a guarded direct UTF-8 writer can skip the

temporary per-string Uint8List allocations and write UTF-8 bytes directly

into the already-allocated native parameter buffer. The fast path should

improve Unicode/emoji-heavy 8- and 20-parameter batch shapes while keeping the

existing ASCII path first and preserving Dart's malformed-surrogate semantics.

Accept if Unicode/emoji wide batches improve clearly, narrow/small controls

stay neutral, release write-suite rows do not show a targeted regression, and

round-trip tests cover multibyte text plus embedded NULs. Reject if the manual

UTF-8 scan/write cost erases the allocation win or the correctness surface

becomes fragile.

Approach

The existing exp 125 guard remains the entry point:

• paramCount >= 8
• totalCount >= 8192
• the first row contains at least one string

allocateBatchParams still tries the ASCII path first. Only when the batch

contains a non-ASCII string does it use the new direct UTF-8 path:

1. Measure UTF-8 byte length without allocating encoded lists.
2. Allocate the same native [structs][payload bytes] buffer as the generic

path.

1. Write UTF-8 bytes directly into the payload tail, including surrogate-pair

handling and replacement-character encoding for unpaired surrogates.

1. Bind the exact byte length through the existing C-side sqlite3_bind_text

call.

The focused benchmark now supports --text-mode=unicode|emoji|nul so future

experiments can reproduce the non-ASCII path instead of inferring from the

ASCII release row.

Results

Focused command:

 dart run benchmark/experiments/batch_param_flatten.dart --iterations=50 --text-mode=unicode dart run benchmark/experiments/batch_param_flatten.dart --iterations=50 --text-mode=emoji 

Focused p50 wall time:

Small/narrow controls stayed neutral:

Release write-suite same-day guardrail:

Validation:

 dart analyze --fatal-infos lib/src/native/resqlite_bindings.dart benchmark/experiments/batch_param_flatten.dart test/database_test.dart dart test test/database_test.dart --timeout 60s dart run build_runner build --delete-conflicting-outputs dart run benchmark/suites/writes.dart 

All passed. build_runner printed the existing warning that

--delete-conflicting-outputs has been removed and ignored.

Decision

Accept for review. The non-ASCII direct writer clears the target workload:

large wide Unicode batches improve 13-17%, and emoji-heavy batches improve

13-28%. The ASCII release suite remains on exp 125's first-choice path and

shows no targeted regression in same-day guardrails.

This preserves the lean public API and keeps the optimization private to the

batch parameter encoder. Correctness coverage now includes multibyte strings,

emoji/surrogate-pair text, blobs, and embedded NUL text on the guarded wide

batch path.

Future Notes

Do not broaden this past large wide batches without a new benchmark. The win is

still from removing per-string temporary allocation in batch parameter packing;

small/narrow writes remain on the generic path because the scan/write overhead

does not have enough allocation work to amortize.

The remaining parameter-encoding questions are blob-heavy batch shapes and

whether any production workload needs broader embedded-NUL guarantees beyond

the batch path tested here.