Skip to content

Commit 71d675b

Browse files
luisleo526claude
andcommitted
live ledger: admit a commit by the pages it really dirtied, refuse nothing that fits, and keep service mode as it was
The reservation multiplied a worst-case B-tree path cost per mutation before BEGIN, so one input with one action reserved about 36 MB and a 1 GiB budget refused an input with about 30 actions at under 5% real usage: a false refusal. - Admission now happens immediately before COMMIT: a finite-budget connection runs with cache_spill off, the page cache is sampled after every trigger, split and overflow allocation as an upper bound on all the pages the transaction touches, and the commit is admitted or refused before the first WAL write; a refusal unwinds through the rollback and leaves the file unchanged. The cost is that the dirty pages stay in memory until COMMIT, which the documentation states. Unlimited runs keep normal spilling. The reservation function takes an extra payload margin and returns the admission callback a writer attaches to its transaction, so the checkpoint writer can use it. - The service-mode budget requirement ships off (today's behaviour) behind its one named function; --ledger-unbounded stays implemented; the three unrelated e2e edits that added it are reverted. The CHANGELOG says service mode does not require a budget in this release. - The migration reserves what it writes, the offline redeliver path goes through the reservation, new rows commit 1, 10 and 100 actions under a small budget, initialise a ledger under 64 MB and upgrade a base-written ledger under a finite budget; the documentation gives the measured order of the headroom and the one-way migration. This rewrites passages introduced by c9bfb29 and 792b229: the sentences that described the reservation before BEGIN and "deliberately exceeds" growth, the "Its independent slack ceiling for the two-event input fixture is" sentence, and the statement that service mode requires a budget. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent 792b229 commit 71d675b

10 files changed

Lines changed: 455 additions & 222 deletions

‎CHANGELOG.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,17 @@ diagnostics keys, described below.
3939
### Live ledger resource control
4040

4141
- Ledger writes now reserve payload and SQLite overhead before growth and
42-
refuse a whole transaction with a typed storage-budget failure. Service mode
43-
requires a positive `--max-ledger-bytes` or explicit `--ledger-unbounded`;
44-
ordinary runs keep their unlimited default.
42+
refuse a whole transaction with a typed storage-budget failure. Service and
43+
ordinary runs keep their unlimited default in this release; requiring a
44+
service budget remains a pending policy decision. The `--ledger-unbounded`
45+
opt-out is available for that policy. Offline redelivery accepts the same
46+
`--max-ledger-bytes` budget.
4547
- Delivery status uses transactional counters and oldest-pending indexes,
4648
keeping status work independent of action and attempt history. Existing
47-
ledgers acquire verified summaries in an automatic migration.
49+
ledgers acquire verified summaries in an automatic, one-way migration;
50+
earlier runners cannot open the migrated database. The summaries add one
51+
row and up to three partial-index entries per action, plus per-target rows
52+
and indexes.
4853

4954
### Run profile in the report diagnostics
5055

‎docs/live-ledger-budget.md‎

Lines changed: 151 additions & 94 deletions
Large diffs are not rendered by default.

‎runner/README.md‎

Lines changed: 41 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -171,28 +171,47 @@ pineforge-live probe --status-file status.json --max-age 3 --ready
171171
abandoned attempt.
172172
- Run/offline-redelivery exits: **0** normal completion or graceful signal
173173
stop; **1** fatal initialization, input, storage-I/O or internal failure;
174-
**2** offline redelivery with selected failed/pending actions; **3** run
175-
stopped at its storage budget. `actions --follow` retains exit 130 on a
176-
signal. A supervisor's grace period must allow message computation/commit
174+
**2** offline redelivery with selected failed/pending actions; **3** run or
175+
offline redelivery stopped at its storage budget. `actions --follow` retains
176+
exit 130 on a signal. A supervisor's grace period must allow message computation/commit
177177
(plus, after a fatal error or a storage-budget stop, the delivery drain); there is no claim that arbitrary strategy code is
178178
interruptible. Container liveness probes can detect a stalled control loop.
179179
- `--max-ledger-bytes N` budgets database + WAL + SHM bytes (0 disables it;
180-
default 0; integer 0..INT64_MAX). With `--status-file` (service mode), an
181-
omitted or zero budget is refused at startup with `run_request_invalid`
182-
unless `--ledger-unbounded` explicitly opts out. Ordinary runs retain the
183-
unlimited default. A positive budget remains effective even with the opt-out.
184-
Before each write transaction, the runner reserves payload bytes and
185-
conservative SQLite row/index, WAL, checkpoint and SHM overhead. Insufficient
186-
space refuses the whole transaction before writing, carries `used`,
187-
`requested` and `limit` in a typed `scratch_capacity_exceeded` failure, removes
180+
default 0; integer 0..INT64_MAX). Service mode (`--status-file`) also retains
181+
the unlimited default in this release: it does not require a budget.
182+
Requiring one remains a pending policy decision, controlled by
183+
`service_requires_ledger_budget`. The `--ledger-unbounded` opt-out is
184+
implemented for that policy; a positive budget still applies with the opt-out.
185+
With a finite budget, SQL changes stay in SQLite's page cache until admission
186+
immediately before COMMIT. The runner reserves each accounted page once,
187+
plus WAL, checkpoint and SHM overhead. Insufficient space rolls back the whole
188+
transaction before database/WAL growth, carries `used`,
189+
`requested` and `limit` in a typed `scratch_capacity_exceeded` failure
190+
(`resource: layout` names the ledger budget here), removes
188191
readiness and exits 3. Earlier committed inputs, actions and reports stay
189192
intact. Delivery is cancelled on an admission refusal; unfinished attempts
190193
remain recoverable. The existing post-growth check and
191194
`storage_below_budget` readiness field remain in use. An actual I/O failure
192195
exits 1. Initialization and migrations also need admission space; a refusal
193196
there can precede status publication. No automatic pruning or report
194-
retention policy is applied. See [ledger budget accounting](../docs/live-ledger-budget.md)
195-
for the reservation formula and its conservative headroom.
197+
retention policy is applied.
198+
199+
Headroom is approximately twice the accounted SQLite page bytes, plus any
200+
earlier WAL pages still owed to the main file, at most one sector of frame
201+
padding per WAL/checkpoint allowance, and SHM region rounding. For a 32-page
202+
bound, no earlier checkpoint debt, a WAL-index bound of 64 KiB and an existing
203+
32 KiB SHM file, the next write needs **428,320 bytes at 4 KiB pages** or
204+
**4,359,760 bytes at 64 KiB pages**, beyond current usage. A 2 MiB allocation
205+
bound needs **4,383,520 / 4,359,760 bytes**, respectively, under the same
206+
conditions. These numbers come from the
207+
[reservation formula](../docs/live-ledger-budget.md). The exact minimum budget
208+
for a write is `used + requested`; it varies with the transaction and checkpoint
209+
debt. **64 MB (64,000,000 bytes)** is a workable fresh-ledger budget for short
210+
ordinary inputs at both page sizes; the test covers initialization and
211+
1/10/100-action inputs. Large payloads and history need additional space.
212+
Auto-vacuum or disabled SQLite allocation tracking uses the whole logical page
213+
count as the bound; the accounting guide states the larger headroom and the
214+
finite-budget migration rule.
196215

197216
### Live redelivery control files
198217

@@ -243,13 +262,22 @@ retained; the oldest are removed during polling. Durable audit stays in SQLite,
243262
not the acknowledgment files. The control directory is outside the
244263
ledger budget. Without `--control-dir`, `redeliver` remains offline, reads only
245264
the selected target's secret and refuses while the runner holds the lock.
265+
Offline redelivery accepts `--max-ledger-bytes N` (default 0, unlimited);
266+
attempts and results use the same admission as `run`. Live submissions use the
267+
running owner's budget.
246268

247269
The additive ledger tables/columns are migrated while holding its writer lock.
248270
Delivery counts and oldest-pending indexes are rebuilt once from the existing
249271
rows and verified in that migration transaction. Later delivery and status work
250272
uses the summaries and indexes; status visits targets rather than historical
251273
actions or attempts. Counters update in the same transaction as their source
252274
rows, including failed redelivery and legacy acknowledgements.
275+
Permanent summary storage adds one `delivery_state` row per action and up to
276+
three partial-index entries for pending, unsent and oldest-pending lookup.
277+
The row and oldest index copy the target name. `delivery_targets` adds one
278+
row, a primary-key index entry and an eligible pending-index entry per distinct
279+
target, shared by its actions. These grow alongside the original action and
280+
attempt history; there is no pruning.
253281
This is a one-way runner upgrade: back up the ledger before upgrading; earlier
254282
runner versions cannot open the migrated database. Strategy/deployment identity
255283
and historical action payload bytes remain unchanged.

‎runner/main.cpp‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ void help() {
9494
" pineforge-live probe --status-file PATH --max-age S [--ready]\n"
9595
" pineforge-live redeliver --ledger L --deployment D --target T [--from N] [--failed-only]\n"
9696
"Add --control-dir PATH to redeliver to request resending from a running runner.\n"
97-
"Without --control-dir redeliver is offline and requires the ledger lock.\n";
97+
"Offline redeliver requires the ledger lock and accepts --max-ledger-bytes N (default 0, unlimited).\n";
9898
}
9999
std::uint64_t unsigned_arg(const std::string &s) {
100100
return Json::number(s).integer<std::uint64_t>();
@@ -1234,7 +1234,7 @@ int probe_command(int argc, char** argv) {
12341234
int ledger_command(int argc, char** argv) {
12351235
const std::string command = argv[1];
12361236
std::string path, target, deployment, control_dir;
1237-
std::uint64_t after = 0, from = 1;
1237+
std::uint64_t after = 0, from = 1, max_ledger_bytes = 0;
12381238
std::optional<std::uint64_t> at_input;
12391239
bool follow = false, failed_only = false;
12401240
std::set<std::string> seen;
@@ -1252,6 +1252,11 @@ int ledger_command(int argc, char** argv) {
12521252
else if (command == "redeliver" && option == "--from") from = unsigned_arg(value);
12531253
else if (command == "redeliver" && option == "--target") target = value;
12541254
else if (command == "redeliver" && option == "--control-dir") control_dir = value;
1255+
else if (command == "redeliver" && option == "--max-ledger-bytes") {
1256+
max_ledger_bytes = unsigned_arg(value);
1257+
if (max_ledger_bytes > static_cast<std::uint64_t>(INT64_MAX))
1258+
throw std::runtime_error("ledger budget exceeds supported range");
1259+
}
12551260
else throw std::runtime_error("unknown option: " + option);
12561261
}
12571262
if (path.empty()) throw std::runtime_error("ledger is required");
@@ -1282,6 +1287,8 @@ int ledger_command(int argc, char** argv) {
12821287
return stopped ? 130 : 0;
12831288
}
12841289
if (target.empty()) throw std::runtime_error("redeliver requires target");
1290+
if (!control_dir.empty() && seen.count("--max-ledger-bytes"))
1291+
throw std::runtime_error("live redelivery uses the running owner's ledger budget; --max-ledger-bytes is for offline redelivery");
12851292
const auto document = view.routing_document();
12861293
if (document.empty()) throw std::runtime_error("resume this phase-A ledger with run before redelivering");
12871294
auto routing = restore_routes(document);
@@ -1304,7 +1311,7 @@ int ledger_command(int argc, char** argv) {
13041311
else ++position;
13051312
}
13061313
auto targets = routing.load_secrets();
1307-
Ledger ledger(path, view.identity());
1314+
Ledger ledger(path, view.identity(), max_ledger_bytes);
13081315
auto events = view.redelivery_events(target, from, failed_only);
13091316
const auto selected = events.size();
13101317
std::set<std::string> selected_ids;

0 commit comments

Comments
 (0)