The adapter bounded each parameter to 4 KiB of text (ADR-0059), and a cellular publication sends its replay trace as one hex bytea parameter, so a 64-tick batch or a one-tick batch of about 85 lives was refused client-side as "invalid". CI run 372 hit this in the M11.4c-1 publication test. ADR-0126 raises the bound to 4 MiB, enough for the largest trace the codec admits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
45 lines
2.1 KiB
Markdown
45 lines
2.1 KiB
Markdown
# ADR-0126: PostgreSQL parameter bound for cellular traces
|
|
|
|
## Status
|
|
|
|
Accepted (2026-10-14). Amends the per-parameter bound of
|
|
[ADR-0059](0059-postgresql-bootstrap.md) (restated in ADR-0063).
|
|
|
|
## Context
|
|
|
|
ADR-0059 bounded every query parameter to 4 KiB of text. Byte strings travel as
|
|
hex `bytea` text, so a parameter held at most about 2 KiB of data. That was enough
|
|
for lineage and primitive publications, but a profile-4 cellular publication sends
|
|
its whole replay trace as one parameter: 112 header bytes, then per tick 16 bytes
|
|
plus 24 per life (and 40 per birth or mutation). A 64-tick trace of one life is
|
|
about 2.7 KiB, and a one-tick trace passes the bound at roughly 85 lives. The
|
|
adapter refused these client-side as `bounds`, which the lease store reports as
|
|
`invalid`, before anything reached the database. CI found this when the M11.4c-1
|
|
publication test first published a 64-tick feeding batch; M11.5 budding makes
|
|
populations of that size reachable in a live region.
|
|
|
|
## Decision
|
|
|
|
Each parameter may hold up to 4 MiB of text. The largest cellular trace the codec
|
|
admits (`max_cellular_batch_bytes`: 64 ticks of 256 lives with births and
|
|
mutations, about 1.7 MB) is about 3.4 MiB as hex, so every encodable trace fits.
|
|
The other bounds are unchanged: SQL text 16 KiB, at most 16 parameters, responses of
|
|
at most 128 rows, 16 columns and 64 KiB per decoded value, one outstanding
|
|
statement, and bounded I/O deadlines.
|
|
|
|
## Alternatives
|
|
|
|
- **Split traces across several parameters or statements:** rejected. A
|
|
publication must stay one atomic call carrying the exact bytes the manifest
|
|
digests.
|
|
- **Keep 4 KiB and cap cellular batches or populations to fit:** rejected. It would
|
|
limit a region to about 85 lives and make publication fail as wildlife grows.
|
|
- **Send binary parameters:** possible later. It halves the size but changes every
|
|
call site's encoding, which this fix does not need.
|
|
|
|
## Consequences
|
|
|
|
A runtime call can now send up to 64 MiB in the worst case (16 parameters at the
|
|
bound), still only for trusted, bounded persistence SQL. Cellular publications of
|
|
any admitted size reach the database, where the SQL checks remain the authority.
|