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:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user