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>
This commit is contained in:
dingo
2026-10-14 06:42:27 -04:00
co-authored by Claude Opus 5.5
parent 66632f53b3
commit 5b255ad940
4 changed files with 50 additions and 2 deletions
@@ -0,0 +1,44 @@
# 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.
+1
View File
@@ -26,6 +26,7 @@
- [ADR-0123: Dev cellular region and life-allocator provisioning](0123-dev-cellular-region-and-life-allocator-provisioning.md) - moves DEV to cellular region 100/2 at schema v33 and has the owner provisioner create a world's life allocator once at an audited start.
- [ADR-0124: Cellular engulfment and detritus](0124-cellular-engulfment-and-detritus.md) - resolves engulfment of a sufficiently smaller contacted cell and deposits every corpse's inventory into the patch grid as absorbable detritus, under cellular rules 3.
- [ADR-0125: Cellular budding and wildlife descendants](0125-cellular-budding-and-wildlife-descendants.md) - M11.5: a bud is v10 action kind 3, paid from the parent's reserve (ADR-0032 investment plus a 30 s provision), placed touching the parent, identified in a region namespace above 2^63, carrying the parent's genome; unowned wildlife driven by a pure deterministic controller whose intentions ride the trace.
- [ADR-0126: PostgreSQL parameter bound for cellular traces](0126-postgres-parameter-bound-for-cellular-traces.md) - each query parameter may hold 4 MiB of text (was 4 KiB, ADR-0059), so every admitted cellular trace (64 ticks of 256 lives as hex bytea) reaches the database in one atomic publication.
- [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows.
+1 -1
View File
@@ -35,7 +35,7 @@ No hidden threads, pool, transaction replay or automatic reconnect. Connections
and queries take 1..30000ms deadlines on a steady clock. Remote hostaddr must be
numeric, host supplies TLS identity, CA file is explicit, TLS verify-full required.
Local sockets require no PGHOSTADDR/PGSERVICE override. GSS negotiation is disabled.
Query SQL <=16KiB, <=16 parameters of <=4KiB, response <=128 rows/16 columns/64KiB
Query SQL <=16KiB, <=16 parameters of <=4MiB (ADR-0126; 4KiB before cellular traces), response <=128 rows/16 columns/64KiB
decoded values; single-row mode prevents accumulating a whole result set. A single
server field is allocated by libpq before its length can be checked: this is not
an arbitrary-query memory sandbox. Only trusted bounded persistence SQL is admitted.
+4 -1
View File
@@ -101,8 +101,11 @@ bool wait(PGconn* c, short events, Clock::time_point deadline) {
return false;
}
}
// ADR-0126: a parameter holds at most 4 MiB of text, enough for the largest cellular trace
// (64 ticks of 256 lives) as a hex bytea; it was 4 KiB before profile-4 traces.
constexpr std::size_t max_parameter_bytes = std::size_t{4} * 1024 * 1024;
bool bounded(const std::string& s) {
return s.size() <= 4096 && s.find('\0') == std::string::npos;
return s.size() <= max_parameter_bytes && s.find('\0') == std::string::npos;
}
bool duration(std::chrono::milliseconds t) {
return t.count() > 0 && t.count() <= 30000;