Files
aevolution/docs/adr/0126-postgres-parameter-bound-for-cellular-traces.md
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

2.1 KiB

ADR-0126: PostgreSQL parameter bound for cellular traces

Status

Accepted (2026-10-14). Amends the per-parameter bound of ADR-0059 (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.