Files
aevolution/docs/adr/0126-postgres-parameter-bound-for-cellular-traces.md
T
dingoandClaude Opus 5.5 5b255ad940 Let a PostgreSQL parameter carry a whole cellular trace
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>
2026-10-14 06:42:27 -04:00

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.