diff --git a/docs/adr/0126-postgres-parameter-bound-for-cellular-traces.md b/docs/adr/0126-postgres-parameter-bound-for-cellular-traces.md new file mode 100644 index 0000000..16da719 --- /dev/null +++ b/docs/adr/0126-postgres-parameter-bound-for-cellular-traces.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 4f709e0..d1404b0 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/infrastructure/POSTGRESQL.md b/docs/infrastructure/POSTGRESQL.md index a8f5c0d..6ea2d4a 100644 --- a/docs/infrastructure/POSTGRESQL.md +++ b/docs/infrastructure/POSTGRESQL.md @@ -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. diff --git a/src/persistence/postgres.cpp b/src/persistence/postgres.cpp index f00898b..a0f9081 100644 --- a/src/persistence/postgres.cpp +++ b/src/persistence/postgres.cpp @@ -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;