Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Make receipt write caps opt-in; housekeeping compacts receipts above a storage target (GBRA-108)
garrytancee9176abd56
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8417be4762..cca65de440 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,6 +12,16 @@ identifiers and attribution are available in the pre-removal Git revision## [Unreleased]+**gbrain's own write bookkeeping no longer caps your writes.** Every accepted write leaves a receipt, and gbrain used to cap how many request ids and how many receipt bytes one writer and one brain could hold (2,000,000 / 8,000,000 ids, 16 GiB / 64 GiB). Near those caps, background writers paused at 80% and every write receipt carried a low-capacity warning; at the cap, `remember`, `put_page` and sync refused with `write_quota_exhausted` until someone on the brain host raised a number. Nothing about your data needed that: a cap only stopped writes. Both caps are now off unless the operator sets one. Receipt storage is kept in check by housekeeping instead: while reserved receipt bytes pass `persistence.housekeeping.receipt_target_bytes` (default 8 GiB), the compaction pass also compacts committed and cancelled receipts older than 7 days, plus refusals that gbrain's own producers will write again from current content, and doctor `persistence_capacity` tells the brain host's operator. A refused write you made keeps its intent until the retention window ends, so a replay still has it, and an explicit `persistence.receipt_retention_days` is left as set.++### Itemized changes++- `src/core/persistence/model.ts`, `limits.ts`: `principal_lifetime_ids`, `brain_lifetime_ids`, `principal_terminal_bytes` and `brain_terminal_bytes` default to no cap; a value set with `gbrain config set` is enforced as before (refusal at the cap, background pause at its line). New key `persistence.housekeeping.receipt_target_bytes` (0 turns housekeeping and its warning off).+- `src/core/persistence/compaction-pass.ts`: `housekeepReceipts` compacts up to 100 receipts older than 7 days per pass: settled page writes, and refused maintenance pages and managed sync, file import, reconcile and file repair page writes. Job receipts, connector writes and every other refusal (a caller's write, conversation facts, atom members, connector items) keep their intent until the retention window while the brain is over the target and the retention is the default, with every exclusion of the retention pass; the pass record counts them as `early`.+- `src/commands/doctor/checks/persistence-capacity.ts`: with no cap set, `ok` says so and `warn` fires above the target with the read-only `gbrain repair receipt-compaction --json` preview (actor `host_admin`); `details.housekeeping` reports target, stored bytes and an explicit retention. The forecast, capacity notices, repair capacity rows and `persistence_request_growth` cover only caps that are set, so the `/metrics` `gbrain_write_capacity_*` gauges are exported only for a cap you set; an alert on them needs a cap.+- Docs: `docs/guides/concurrent-writes.md` (limits table, receipt housekeeping, growth model as sizing for a cap you set), `docs/guides/write-refusals.md`.+- Tests: `test/persistence-opt-in-caps.test.ts` (counters at the old default caps admit background and interactive writes with no notice and no raise; a set cap still refuses; housekeeping above the target takes week-old settled page writes and refused maintenance and sync writes, and keeps a caller's refused write, a refused conversation-facts job, a committed job and young receipts; a 40-day synthetic run never holds more than a week of uncompacted committed receipts; doctor's operator warning), `test/persistence-capacity.test.ts` (key count); the capacity forecast, notice and read-wave tests set the cap they exercise; the doctor goldens show the uncapped default and `details.housekeeping`.+**A write that saved now says so when it carries a low-capacity warning, and the warning no longer asks the user to raise a write cap by tens of gigabytes.** When a cumulative write cap (receipt bytes or request ids) was at 80% or forecast to run out within 30 days, every write receipt's `write_capacity_low` notice ended with `actor: host_admin` and `next: tell_user_to_run: gbrain config set persistence.limits.principal_terminal_bytes <value>`. An agent that read only the end of a successful `remember` took that for a refusal and told its user the memory was not saved. The value was also oversized: it projected the last 24 hours for a whole year, so one bulk sync day could recommend several times the current cap. The notice now opens with "This write was saved and writes still work", its fix is the read-only `gbrain doctor --only persistence_capacity --json`, and the one-more-year value uses the 7-day mean rate. Days-to-exhaustion warnings still react to a bulk day. Doctor's finding keeps the `gbrain config set` command for the brain host's operator.### Itemized changesdiff --git a/docs/architecture/key-files/core-persistence-capacity.md b/docs/architecture/key-files/core-persistence-capacity.mdindex b1e7effefe..a13fee187f 100644--- a/docs/architecture/key-files/core-persistence-capacity.md+++ b/docs/architecture/key-files/core-persistence-capacity.md@@ -1,6 +1,6 @@# Core Persistence: write capacity-Cumulative write caps (permanent request ids, receipt bytes) and the paths that keep them honest (#6696). Guide: [concurrent writes, growth model and quota](../../guides/concurrent-writes.md#growth-model).+Cumulative write caps (permanent request ids, receipt bytes; opt-in since GBRA-108, `DEFAULT_JOURNAL_LIMITS` holds `Infinity` and rows of an unset cap are left out of diagnostics, the forecast and repair capacity) and the paths that keep them honest (#6696). Guide: [concurrent writes, growth model and quota](../../guides/concurrent-writes.md#growth-model).- `src/core/persistence/receipt-bytes.ts` — `receiptReservation({intent, authority}, extra)`: what an admission reserves (serialized intent and authority plus `RECEIPT_COMPLETION_BYTES` 12 KiB, never below `RECEIPT_RESERVATION_FLOOR` 16 KiB) on single, group and caller-overridden paths (`journal.ts` takes the larger of a caller's value and the formula); `reservationForRetained` is the same estimate from bytes alone (the sync preflight); `retainedReceiptBytes` is what a terminal or compacted row keeps, shared with `intent-redaction.ts` and compaction; `EFFECT_BYTES_SQL` and `TRUE_UP_CLAMP_SQL` (counts clamped decrements under `persistence.true_up.clamped`).- `src/core/persistence/receipt-true-up.ts` — `trueUpRequests(engine, ids)`: after the settling transaction commits, in its own short transaction, locks the brain and principal counters in key order, then a compare-and-set on each request row (still `terminal_reservation` as read, no queued or running effect, same effect bytes) shrinks it to `retainedReceiptBytes` and releases the difference. Idempotent; never touches `updated_at`. Called from the effect runner (`effects.ts`, every claimed request), `embedding-settlement.ts`, `embedding-noop-settle.ts` (the `embed --stale` bulk settle), `effect-retry.ts` (reconciled) and `backup/snapshot.ts` (restore). `test/persistence-true-up-sites.test.ts` fails on an effect state-change site that is not wired. `sweepCompactedReservations` is the bounded one-shot pass over receipts compacted with their full reservation (cursor `persistence.true_up.compacted_through`, `done` at the end).@@ -9,11 +9,11 @@ Cumulative write caps (permanent request ids, receipt bytes) and the paths that- `src/core/persistence/capacity-forecast.ts` — `readCapacityForecast`: per principal, one statement walks `persistence_requests_principal` newest first until `created_at` leaves the 7-day window and buckets by day; gross and net (compacted) receipt rates, `days_to_exhaustion` (at the larger of the 7-day mean and the last 24 hours), `basis` (`:legacy_under_reserved` while receipts admitted before the intent-sized reservation remain), `recommended_limit` (one more year at the 7-day mean, GST-2107, so one bulk day is not projected for a year). `light` skips the reclaim read and table size. Thresholds `persistence.capacity.warn_days` (30) and `fail_days` (7).- `src/core/engine-key.ts` + `src/core/engine-root.ts` — the key every per-engine cache uses. `engineKey(engine)` returns the engine itself through the `ENGINE_ROOT` symbol (each engine stores itself there; a page-transaction clone inherits it, forwarding proxies and a recovered degraded engine return it), and otherwise walks a page-transaction clone, a read-through view or a statement-deadline wrapper (`engineCacheKey`) to the engine behind it. A process with mounted brains keeps one entry per brain in the search telemetry writer (`getTelemetryWriter(engine)`), `search.track_retrieval`, minion admission policy, `mcp.strict_params` last-known-good, publication ceiling, `write_capacity_low` throttle, `search.hnsw_iterative_scan` and `search.vector_legacy_guard`, and a transaction or view shares its engine's entry. A one-brain process behaves as before. Test: `test/engine-keyed-caches.test.ts`.- `src/core/persistence/capacity-snapshot.ts` — `cachedCapacitySnapshot`: one light forecast per engine per 60 s, shared by every caller; `capacityNotices` builds `write_capacity_low` (kind `info`, muteable; it says the write was saved and its fix is the read-only doctor check, GST-2107; hourly per engine and scope on write and sync receipts, `scopes` limits a remote caller to the brain and its own principal) and `write_capacity_backpressure` (once per pause start). Read by `mcp/dispatch.ts`, `cli/main.ts`, `commands/sync/{run,operator}.ts`, `cycle.ts` and the admin `/metrics` gauges in `serve-http-metrics.ts`. #6803: the cache keys on the real engine (`engineCacheKey`), the shared fetch is bounded at `CAPACITY_FETCH_BOUND_MS` (10 s) and a timed-out fetch is never cached; `capacitySnapshotWithin` (sync status, write and sync receipts: `CAPACITY_READ_WAIT_MS`, 1.5 s) returns `unknown` for that call alone, and `capacityNotices` on an unknown snapshot returns no notice and leaves throttle and pause state as it was. Test: `test/capacity-bounded-read-6803.test.ts`.-- `src/core/persistence/compaction-pass.ts` — `runCompactionPass`, the consumer's idle and volume maintenance: `compactWriteReceiptsDetailed`, one sweep step, and the `persistence.maintenance.last_compaction` record (`at`, `host_id`, `compacted`, `freed_bytes`, `skipped_by_reason`). Each step resumes from the timer queue (`journal.ts` `yieldToEventLoop`), as do the consumer's maintenance chain, the per-table queue `VACUUM` and the effects drain passes (`NOOP_SETTLE_BATCH` 50), so on PGLite a request waits behind one step at most. `journal.ts` `compactReceipt` compacts one receipt in its own transaction (counters first, `lock_timeout` 2 s, `statement_timeout` 15 s) and skips open managed-sync runs (`OPEN_SYNC_CURSOR_EXCLUSION`) and the newest sync receipt per worktree (`newestSyncReceipt`).+- `src/core/persistence/compaction-pass.ts` — `runCompactionPass`, the consumer's idle and volume maintenance: `compactWriteReceiptsDetailed`, `housekeepReceipts` (GBRA-108: above `persistence.housekeeping.receipt_target_bytes` with the default retention, up to 100 receipts older than `HOUSEKEEPING_FLOOR_DAYS` that `EARLY_SQL` admits: settled non-job, non-connector writes and refused maintenance or managed sync page writes; counted as `early`), one sweep step, and the `persistence.maintenance.last_compaction` record (`at`, `host_id`, `compacted`, `freed_bytes`, `skipped_by_reason`). Each step resumes from the timer queue (`journal.ts` `yieldToEventLoop`), as do the consumer's maintenance chain, the per-table queue `VACUUM` and the effects drain passes (`NOOP_SETTLE_BATCH` 50), so on PGLite a request waits behind one step at most. `journal.ts` `compactReceipt` compacts one receipt in its own transaction (counters first, `lock_timeout` 2 s, `statement_timeout` 15 s) and skips open managed-sync runs (`OPEN_SYNC_CURSOR_EXCLUSION`) and the newest sync receipt per worktree (`newestSyncReceipt`).- `src/core/repair/receipt-compaction.ts` — `gbrain repair receipt-compaction`: explicit-only, preview-bound, destructive consent, `publication: 'projection'`; `--older-than` (the `pages purge-deleted` grammar) floored at the configured retention unless `--force`, committed only unless `--include-failures`; the approved set binds an absolute cutoff and the newest sequence. Test: `test/repair-receipt-compaction.test.ts`.- `src/core/persistence/refusal-breaker.ts` — `assertRefusalBreakerClosed`: `submitMaintenance` refuses before admission after `persistence.maintenance.refusal_breaker_threshold` (3; 0 off) same-code terminal refusals in 24 h for the same request `digest` (source, slug, intent with its revision and planner); `listSuppressedWrites` feeds doctor `maintenance_write_drift`. The ghost case (`canonical_file_missing`, tagged by `page-prepare.ts`, kept in `error_detail.origin`, returned by `liveFileDrift`) refuses before admission in `prepared-maintenance.ts`. Test: `test/maintenance-ghost-breaker-6696.test.ts`.- Sync: `sync-run.ts` `preflightSyncCapacity` refuses `write_quota_insufficient` before a run's first admission; `sync-drain.ts` stops a later cap refusal `resumable` / `capacity_paused` (`drain.capacity_pause`). Test: `test/sync-capacity-preflight.test.ts`.-- Doctor: `persistence_capacity` (forecast), `persistence_compaction` and `persistence_counter_drift` (`src/commands/doctor/checks/persistence-compaction.ts`; one-statement comparison of counters with request and lifecycle reservations). Test: `test/doctor-persistence-compaction.test.ts`.+- Doctor: `persistence_capacity` (forecast of set caps; with none set, receipt storage against the housekeeping target, an operator warning that never blocks a write; `test/persistence-opt-in-caps.test.ts`), `persistence_compaction` and `persistence_counter_drift` (`src/commands/doctor/checks/persistence-compaction.ts`; one-statement comparison of counters with request and lifecycle reservations). Test: `test/doctor-persistence-compaction.test.ts`.## Publication costdiff --git a/docs/guides/concurrent-writes.md b/docs/guides/concurrent-writes.mdindex e370035b4a..20183453b1 100644--- a/docs/guides/concurrent-writes.md+++ b/docs/guides/concurrent-writes.md@@ -866,14 +866,18 @@ automatic expiry walker still coordinates each expired source separately.from a pending or uncertain administrative result and repeat the same command,arguments, and `--request-id` after recovery.-Default admission limits are enforced atomically:+Default admission limits are enforced atomically. The two cumulative ones,+lifetime request IDs and terminal receipt bytes, are opt-in: gbrain's own+receipt bookkeeping never refuses, pauses or throttles a write unless the+operator sets one ([receipt housekeeping](#receipt-housekeeping) keeps the+storage in check instead).| Reservation | Per principal | Per brain || --- | ---: | ---: || Outstanding requests | 100 | 1,000 |-| Queued intent bytes | 32 MiB | 256 MiB |-| Lifetime request IDs | 2,000,000 | 8,000,000 |-| Terminal receipt reservation | 16 GiB | 64 GiB |+| Queued intent bytes | 64 MiB | 256 MiB |+| Lifetime request IDs | no cap unless set | no cap unless set |+| Terminal receipt reservation | no cap unless set | no cap unless set || Recovery bytes | — | 1 GiB, also 256 MiB per worktree (with `pages.segmented_storage on`: twice `pages.max_bytes` plus 2 MiB, at least 256 MiB) |Completion space is reserved at admission. Beforeimage/recovery bytes are@@ -891,9 +895,10 @@ the same statement to what the receipt keeps (its intent, authority, outcome,error, effects and 4 KiB of slack), so a `remember`, a maintenance write or aconflict gives most of its 16 KiB back at once; a page write whose embedding orGit effect is still queued keeps its reservation until compaction. A compacted-receipt keeps about 4 KiB. The cumulative defaults cover one principal-admitting 5,000 writes a day for at least a year ([growth model](#growth-model)).-Every limit and the retention window are brain-wide database settings:+receipt keeps about 4 KiB. A cap you set on lifetime IDs or receipt bytes+refuses at the cap and pauses background producers at 80% of it; the+[growth model](#growth-model) sizes one. Every limit and the retention window+are brain-wide database settings:```bashgbrain config set persistence.limits.principal_lifetime_ids 500000@@ -901,13 +906,15 @@ gbrain config set persistence.limits.principal_terminal_bytes 3221225472gbrain config set persistence.receipt_retention_days 7```-**Say to your agent:** *"Doctor says my brain is near its write capacity. Raise the limit it names."*+**Say to your agent:** *"Is anything in my brain's write bookkeeping limiting my writes?"*Keys are `persistence.limits.<limit>` for `principal_outstanding`,`brain_outstanding`, `principal_intent_bytes`, `brain_intent_bytes`,`principal_lifetime_ids`, `brain_lifetime_ids`, `principal_terminal_bytes`,`brain_terminal_bytes`, `brain_recovery_bytes` and `worktree_recovery_bytes`,-each a nonnegative integer. `gbrain doctor` (`persistence_capacity`) forecasts+each a nonnegative integer; `gbrain config unset` removes a cumulative cap+again. With no cumulative cap set, `gbrain doctor` (`persistence_capacity`)+reports receipt storage against the housekeeping target. With one set, it forecastseach cumulative cap from the full last-7-day admission aggregate: it warns whena principal or the brain uses 80% of its lifetime IDs or receipt bytes or wouldrun out within `persistence.capacity.warn_days` (30) days, and fails at 95% or@@ -923,8 +930,9 @@ permanent replay protection.<a id="growth-model"></a>### Growth model-The defaults come from this model, sized for an autopilot brain that admits-5,000 requests a day for 365 days. Configured values are never changed.+Size a cap you choose to set from this model, which covers an autopilot brain+that admits 5,000 requests a day for 365 days (the old defaults, before+GBRA-108 made both caps opt-in). Configured values are never changed.- **Request IDs** are permanent, so they grow by the admission rate:5,000 × 365 = 1,825,000. The principal default is 2,000,000; the brain@@ -961,6 +969,28 @@ gbrain doctor --only persistence_capacity,persistence_request_growth --json**Say to your agent:** *"How many days of write capacity does my brain have left?"*+<a id="receipt-housekeeping"></a>+### Receipt housekeeping++Receipt storage grows with the retention window times the admission rate,+plus about 4 KiB per compacted receipt, which keeps its request ID replayable.+While the brain's reserved receipt bytes pass+`persistence.housekeeping.receipt_target_bytes` (default 8 GiB; 0 turns it+off), the resident consumer's compaction pass also compacts receipts older than+7 days, oldest first, up to 100 a pass: settled page writes, and the refusals+of producers that write again from current content (maintenance pages and+managed sync, file import, reconcile and file repair page writes). Job+receipts (`submit_job`), connector writes and every other refusal keep their+intent until the retention window: `gbrain repair failed-writes` replays a+caller's refused write from it, conversation facts resubmit a frozen+extraction, atom retries and connector held-item retries read it. Receipts+with unfinished effects, an open sync or a recovery are kept as before. An explicit `persistence.receipt_retention_days`+is the operator's choice, and housekeeping leaves it alone.++While storage stays above the target, `persistence_capacity` warns the brain+host's operator (`actor: host_admin`) with the read-only+`gbrain repair receipt-compaction --json` preview. Writes are not affected.+<a id="counter-drift"></a>### Counter drift and compaction health@@ -989,8 +1019,8 @@ Two read-only doctor checks watch the receipt-bytes accounting:<a id="quota-near-exhaustion"></a>### Quota near exhaustion-When `persistence_capacity` warns or fails, or a write is refused with-`write_quota_exhausted`:+This applies only to a cap the operator set. When `persistence_capacity`+names one, or a write is refused with `write_quota_exhausted`:1. Read the finding: `gbrain doctor --only persistence_capacity --json`.`details.resources[]` names the scope, resource, days left and `basis`;@@ -1012,7 +1042,7 @@ window part of the recommended value, so `gbrain config unsetpersistence.receipt_retention_days` (back to 30 days) is the smaller step oncethe recovery is done.-**Warnings before the wall.** A cap at or past 80%, or one that runs out+**Warnings before the wall.** A cap you set that is at or past 80%, or one that runs outwithin `persistence.capacity.warn_days` (default 30), adds the`[gbrain notice write_capacity_low]` notice (kind `info`). It rides a writethat succeeded, so it opens with "This write was saved" and its fix is the@@ -1027,7 +1057,7 @@ producers pause and `[gbrain notice write_capacity_backpressure]` (kind`degraded`) fires once when the pause starts. Every notice reads a capacitysnapshot that refreshes at most once a minute; no write computes a forecast.-**Alerting (hosted operators).** The admin `/metrics` endpoint exports+**Alerting (hosted operators).** For a cap you set, the admin `/metrics` endpoint exports`gbrain_write_capacity_used`, `gbrain_write_capacity_limit` and`gbrain_write_capacity_days_to_exhaustion`, labelled `scope` and `resource`(`lifetime_ids` or `terminal_bytes`), from the same snapshot. The publicdiff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex 305c2fbf2f..debb4d5cc9 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -117,7 +117,7 @@ of making a duplicate.| <a id="fence_unrenderable"></a>`fence_unrenderable` | `fence_unrenderable` | A legacy fact row (an active `facts` row with no fence row number) was not adopted into its page's `## Facts` fence because the fence codec reads the rendered row back as something other than the stored fact: a whitespace-only claim comes back empty, `~~x~~` comes back struck, a literal `<br>` comes back as a line break, or another column changes. Surrounding whitespace and CRLF line endings are the one accepted difference: such a row is adopted and `facts.fact` takes the fence's text. A second legacy row whose normalized claim, source and visibility the page already carries is left too (`duplicate_claim`; a private and a world row with one text are two facts and both adopt). The cycle and the v0.32.2 migration print `FACTS_FENCE_FAILED: <slug> (fence_unrenderable: N row(s), <class>)`; doctor `fence_integrity` lists the pages, fact ids and reason classes under `unrenderable_legacy_facts` (never the claim text). The same code refuses a planned adoption whose rendered fence does not read back as its facts; that is a gbrain planning defect, not caller input. The planner runs the publisher's own read-back check on the whole rendered fence first, so such a page is reported as unadoptable (class `whole_fence`) instead of being submitted. A managed adoption refused in the last day is not resubmitted: the cycle reports it as class `prior_refusal` with the refused request id (`gbrain write-request -- <id>` reads it), and a direct `submitFactFenceAdoption` call refuses with `The same fact-fence adoption was already refused.`. It is retried a day after the refusal, or at once by a build whose adoption planner revision changed. Unadopted rows hold only their own page: the phantom-redirect pass skips a phantom that owns one and redirects the others. Before v0.60.218.0 the planner could reuse a leftover fence row (one with no database owner) whose visibility differed from the legacy fact's. On a managed brain the publisher refused that page here every cycle, so no private fact was published as world. An unmanaged brain had no such check: it fenced the fact into the leftover row, and the same cycle's reconcile copied that row's visibility into the fact, so a private fact could become world. The current planner never reuses a leftover row for a fact with a different visibility unless the fact is private, and re-renders a reused row from the fact. To count what an older build left in the writer table, run the read-only `scripts/diagnose/fence-adoption-census.sql` on the brain host against the brain's Postgres database (its header shows the `psql` command). | Nothing to fix in the page: the rows stay active and searchable, nothing is lost, and their pages skip destructive fact reconciliation until the rows are adopted. Report the pages and reason classes with the gbrain version. Never `forget_fact` a row to clear the count. || <a id="reconcile-private-facts"></a>reconcile private facts | `permission_denied` | `gbrain sources reconcile --apply` (and its preview) found a `## Facts` row that would edit, renumber or change the visibility of a stored private fact, copy a stored private claim into a row under another visibility, or copy a stored private row's context (24 characters or longer) verbatim into a world row. A row is identified by its row number and claim, so a world row that only shares a private row's claim is not a private row and publishes. The refusal names the row number, never its text. It guards against verbatim copies only; reworded text is not detected, so it is not a confidentiality proof. Sources are not compared, because rows share provenance such as "Slack import". Nothing was written. | Read the stored page with the printed `gbrain get --source <id> -- <slug>`, keep the named row as stored in the file (or remove the copied text), then run a fresh `gbrain sources reconcile <id> <slug> --preview` and apply it. Change private facts with `remember` and `forget`. || <a id="maintenance_backpressure"></a>`maintenance_backpressure` (exit 12) | `maintenance_backpressure` | A managed maintenance run (`gbrain extract-conversation-facts`, its cycle phase or job) publishes each page as its own request, under the same local CLI writer your own CLI writes use. Before the run it counts the requests the whole run plans; before each page's model work it checks again. It stops admitting once the writer's outstanding requests, reserved receipt bytes (`persistence.limits.principal_terminal_bytes`; each request reserves 16 KiB until its receipt compacts after the retention window) or permanent request ids (`persistence.limits.principal_lifetime_ids`; never freed) would pass 80% of their limit, so the last 20% stays free for your other writes. The message names the resource. Pages already published keep their facts and nothing is half-written. | Outstanding requests: read them with `gbrain sources writer status --source <id> --json`; a resident `gbrain serve`, or the next CLI run, publishes them, then rerun the same command. Receipt bytes or request ids: run the smaller batch the message prints (`gbrain extract-conversation-facts --source-id <id> --limit <n>`), or wait for receipts to compact; raising the named `persistence.limits.*` key is the user's call. |-| <a id="write_quota_exhausted"></a>`write_quota_exhausted` (exit 12) | `write_quota_exhausted` | A cumulative write cap is full: permanent request ids (`persistence.limits.principal_lifetime_ids` or `brain_lifetime_ids`, `reason: lifetime_ids`) or reserved receipt bytes (`principal_terminal_bytes` or `brain_terminal_bytes`, `reason: terminal_bytes`). `begin_page_upload` refuses the same way at the staged-upload caps: staged bytes (`principal_staged_bytes` or `brain_staged_bytes`, `reason: staged_bytes`) or open sessions (`principal_uploads`, `reason: open_uploads`); those free when a session commits, aborts or expires, so `abort_page_upload` on an abandoned session also helps. `detail` names the limit key. Waiting does not help: ids are permanent and receipt bytes free only as receipts compact. Nothing changed. | Run the `fix` on the brain host: `gbrain config set <key> <value>` (the value covers about one more year at the current rate; undo with `gbrain config unset <key>`), then retry with the same `request_id`. For receipt bytes with reclaimable slack, `gbrain repair receipt-compaction` second previews the retained bytes compaction would free (ids: only the raise helps). Verify with `gbrain doctor --only persistence_capacity --json`. [Runbook](concurrent-writes.md#quota-near-exhaustion). |+| <a id="write_quota_exhausted"></a>`write_quota_exhausted` (exit 12) | `write_quota_exhausted` | A cumulative write cap the operator set is full (these caps are off unless set): permanent request ids (`persistence.limits.principal_lifetime_ids` or `brain_lifetime_ids`, `reason: lifetime_ids`) or reserved receipt bytes (`principal_terminal_bytes` or `brain_terminal_bytes`, `reason: terminal_bytes`). `begin_page_upload` refuses the same way at the staged-upload caps: staged bytes (`principal_staged_bytes` or `brain_staged_bytes`, `reason: staged_bytes`) or open sessions (`principal_uploads`, `reason: open_uploads`); those free when a session commits, aborts or expires, so `abort_page_upload` on an abandoned session also helps. `detail` names the limit key. Waiting does not help: ids are permanent and receipt bytes free only as receipts compact. Nothing changed. | Run the `fix` on the brain host: `gbrain config set <key> <value>` (the value covers about one more year at the current rate; undo with `gbrain config unset <key>`), then retry with the same `request_id`. For receipt bytes with reclaimable slack, `gbrain repair receipt-compaction` second previews the retained bytes compaction would free (ids: only the raise helps). Verify with `gbrain doctor --only persistence_capacity --json`. [Runbook](concurrent-writes.md#quota-near-exhaustion). || <a id="upload_not_found"></a>`upload_not_found` | `upload_not_found` | An upload call (`upload_page_part`, `get_page_upload`, `commit_page_upload`, `abort_page_upload`) named a session this connection cannot use: no such `upload_id`, another connection's session, a source outside your grant or since re-created, a page deleted or re-created since begin (for mode `create`, a page now at the slug), or an aborted session. Every case gets the same answer, so an `upload_id` reveals nothing. Nothing was written. | Begin a new upload with `begin_page_upload` and a new `request_id`, then send its parts from part 0. || <a id="upload_expired"></a>`upload_expired` | `upload_expired` | The upload session passed its idle deadline (`persistence.limits.upload_idle_seconds`, 1 hour since its last part) or its hard deadline (`upload_max_seconds`, 24 hours since begin) before it was committed. Its parts were discarded and its staged bytes released; nothing was written. | Run the `fix`: `begin_page_upload` again with a new `request_id` and send every part from part 0. An expired session never resumes. || <a id="upload_protected_content"></a>`upload_protected_content` (`reason`: `takes`, `facts` or `timeline`) | `upload_protected_content` | A remote `commit_page_upload` replacing a page with content over 24 MiB was refused: the page holds a takes fence that remote reads hide (`takes`), a facts fence with a row remote reads hide (a non-world row, or a fence that does not parse: `facts`), or timeline rows (`timeline`). put_page keeps the hidden fence and rows and checks which timeline rows its content omits by comparing whole bodies; a body this size is never held whole, so the upload refuses instead of dropping them. The session was discarded and its staged bytes released; nothing was written. | `takes` or `facts`: replace the page with content of at most 24 MiB through put_page (which carries the fence or the hidden rows over), or ask the user to write it on the brain host. `timeline`: upload again and commit with `drop_timeline: true` only if deleting every timeline entry is intended; otherwise send at most 24 MiB through put_page. |@@ -126,7 +126,7 @@ of making a duplicate.| <a id="part_splits_code_point"></a>`part_splits_code_point` | `part_splits_code_point` | An `upload_page_part` text starts or ends with half of a surrogate pair, which has no UTF-8 encoding on its own. The part was not stored. | Move the cut before the high surrogate so the pair travels in one part, then send the part again. || <a id="write_quota_insufficient"></a>`write_quota_insufficient` (exit 12) | `write_quota_insufficient` | A bulk run (a managed sync catch-up, a reclone, a repair) estimated from its manifest more new receipts (ids and 16 KiB reservations) than the capacity left before its producer's pause line, so it did not start. Other writes still work. | Run the `gbrain config set <key> <value>` the message prints on the brain host, then rerun the same command. Verify with `gbrain doctor --only persistence_capacity --json`. || <a id="write_capacity_low"></a>`write_capacity_low` (notice) | `write_capacity_low` | Not a refusal: a `[gbrain notice]` on write receipts, `sync` receipts, `gbrain sync status` and autopilot cycle output when a cumulative cap is at or past 80% or would run out within `persistence.capacity.warn_days` (30) days at its 7-day rate. Receipts carry it at most once an hour per engine and scope; `sync status` and doctor carry it every time. The write that carries it was saved; the notice says so first and its fix is the read-only `gbrain doctor --only persistence_capacity --json`, never a cap raise. The structured `capacity` object in `gbrain sync status` names the scope, resource, days left and the config command. | Nothing to redo. Read the forecast with `gbrain doctor --only persistence_capacity --json` and follow the [runbook](concurrent-writes.md#quota-near-exhaustion) on the brain host; a raised `persistence.receipt_retention_days` comes back to the default before any cap raise. |-| <a id="write_capacity_backpressure"></a>`write_capacity_backpressure` (exit 12) | `write_capacity_backpressure` | A background producer (managed maintenance, conversation facts, an autopilot cycle phase, an autopilot catch-up sync) stopped admitting because a cumulative cap of its writer or the brain is past `persistence.capacity.background_pause_pct` (default 0.8). Interactive writes (`remember`, `put_page`, `edit_page`, an operator's `gbrain sync`, an approved `gbrain repair`) keep the remainder. No receipt was written. `reason` names the resource. Doctor `persistence_capacity` names the paused producers. | Depends on `reason`. `lifetime_ids`: ids are never freed, so only the brain host's `gbrain config set <key> <value>` from the `fix` resumes background work; waiting does not. `terminal_bytes`: the same reversible raise resumes it at once, or it resumes by itself as retained receipts compact. Verify with `gbrain doctor --only persistence_capacity --json`. |+| <a id="write_capacity_backpressure"></a>`write_capacity_backpressure` (exit 12) | `write_capacity_backpressure` | A background producer (managed maintenance, conversation facts, an autopilot cycle phase, an autopilot catch-up sync) stopped admitting because a cumulative cap the operator set on its writer or the brain is past `persistence.capacity.background_pause_pct` (default 0.8). Interactive writes (`remember`, `put_page`, `edit_page`, an operator's `gbrain sync`, an approved `gbrain repair`) keep the remainder. No receipt was written. `reason` names the resource. Doctor `persistence_capacity` names the paused producers. | Depends on `reason`. `lifetime_ids`: ids are never freed, so only the brain host's `gbrain config set <key> <value>` from the `fix` resumes background work; waiting does not. `terminal_bytes`: the same reversible raise resumes it at once, or it resumes by itself as retained receipts compact. Verify with `gbrain doctor --only persistence_capacity --json`. |### Other error codesdiff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsvindex d24bb144b8..ed12caa615 100644--- a/scripts/module-size-limits.tsv+++ b/scripts/module-size-limits.tsv@@ -47,4 +47,4 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: linksrc/core/search/evidence-delivery.ts 1759 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move); +7 GBRA-205: EvidencePlan.titleHeader and DeliveryMeta.title_header (interface fields cannot move) and the titles option on the header loader (logic in search/evidence-date.ts; the query budget key lives in search/evidence-packing.ts); +11 #7600: assemble_evidence quotes conversation rows and capEvidenceToBudget counts the quote fence (logic in search/transcript-quote.ts); +2 GBRA-156 /ship review: the cut-path admission and title room count the quote fence; +2 GBRA-156 /ship review pass 2: capEvidenceToBudget counts the fence only for the paths that fence (quote flag; recall counts the text as returned); +4 GST-687: page evidence and the extractive fallback quote below-owner-tier text for untrusted readers (untrusted flag; logic in search/transcript-quote.ts)src/commands/config.ts 1526 ratchet +1 GBRA-216: recall.* config set value refusal (facts/recall-config.ts); +1 GBRA-216: config set refuses a dream.claim_conflicts.mode other than propose|off (refusal in facts/claim-conflicts.ts); new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal)src/commands/mcp-expose.ts 1519 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts); +7 GBRA-199: --surface help lines, surfaceChosen option field and the advertise pass-through (registrationAdvertise in core/mcp-registration.ts)-src/core/behavior-change-notice.ts 1689 ratchet +4 train R: #7491/#7492 keyword_identifier_probe and keyword_slug_handles rows and their comment, #7175 keyword phrase row; the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +1 GBRA-156 #7593: private_pages_granted_sources row (re-summed at the 0.60.527.0 merge: 1574 + 1); +3 GBRA-200 comment, write-grant refusal and degraded-stamp rows (re-summed at the 0.60.562.0 merge: 1615 + 3); +2 GBRA-280 get_page selector-precedence row and comment (re-summed at the 0.60.569.0 merge: 1619 + 2); the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 row; +1 #8059 quoted_fence_marker_8059 row; +2 GBRA-247 #8009 provenance_repair_held_8009 and #7982 pass_transient_streak_7982 rows; +4 GBRA-247 #7973 plain_directory_sync_7973, #7988 managed_marker_own_directory_7988, #7985 former_binding_parked_group_7985 and settle_effects_retire_7985 rows Train S merge: 1570 base + 5 (master since the #8077 base) + 13 (#8077) = 1588.; +2 GST-687 remote_quotes_unverified_text_gst687 row and its comment (re-summed at the gate-ahead on train S 0.60.534.0: 1588 + 2); +2 #8377: the quote fence follow-ups row and its comment; +2 #8384: the quote fence follow-ups 2 row and its comment; +2 #8384 wave 3: the quote fence follow-ups 3 row and its comment; +5 GBRA-218 train M rows (A1 member_read_access_gbra218 and member_access_hatch_scope_gbra218, B shared_agent_audience_gbra231, A2 folder_access_rules_gbra218, folder_access_scoped_role_gbra218), re-summed at the train M merge of master v0.60.541.0: 1596 + 5 = 1601 measured; +3 GST-359 train C rows (C1 qm_attested_actor_gst359, C2 member_facts_gst359, D qm_memory_provider_gst359), re-summed at the train C merge of master v0.60.543.0: 1601 + 3 = 1604 measured; +2 #8424: hook_launcher_8424 row and its comment (rows are data and cannot move), re-summed at the #8418 v0.60.546.0 merge: 1604 + 2 = 1606 measured; +2 #8426: mcp_lane_launcher_8426 row and its comment (rows are data and cannot move); +2 GST-927: empty_nonstring_args_gst927 row and its comment, re-summed at the gate-ahead on master v0.60.550.0 plus #8420: 1610 measured; +2 GBRA-283 Wave A (#8460): engine_keyed_caches_gbra283 row and its comment (rows are data and cannot move); +2 GBRA-287: segmented_freeze_hold_gbra287 and segmented_reexport_gbra287 rows (rows are data and cannot move); +1 GST-1209: segmented_tiling_gst1209 row (rows are data and cannot move); +1 GST-1251: skillopt_loop_deprecated_gst1251 row (rows are data and cannot move); +1 GST-1209 follow-up: untiled_hold_repair_gst1209 row (rows are data and cannot move); +1 GBRA-283 B3a: embedded_scope_required_gbra283 row (rows are data and cannot move); re-summed at the train R merge with v0.60.574.0: 1623 + 4; +2 GST-1387: refresh_fence_refusal_gst1387 row and its comment (rows are data and cannot move); re-summed at the memory train #8481 merge with v0.60.578.0 (1643 measured); +3 GBRA-253 #8109 rows (frontmatter_drift_write_8109, contacts_activity_advance_8109, contact_rows_dedupe_8109; rows are data and cannot move), re-summed at the master v0.60.581.0 merge: 1643 + 3 = 1646 measured; +3 #8123 part C rows: sync_write_through_off_writeback_7084, managed_sync_dry_run_counts_7087, frontmatter_missing_source_dir_7889 (since TBD until the merge slot; re-summed at the 0.60.583.0 merge: 1646 + 3); +4 PR B commit_ledger_prb, doctor_foreign_writers_prb and sources_guard_prb rows and their comment (rows are data and cannot move; since TBD until the merge slot); +1 PR B #8615: file_drift_held_needs_prefer_8615 row; +1 PR B #8617: refresh_source_changed_retry_8617 row; +1 PR B #8662: commit_push_checkout_not_a_source_8662 row (since TBD until the merge slot; rows are data and cannot move); +2 PR B refresh_barrier_prb and commit_push_base_prb rows (re-summed: 1658 measured); +3 convergence PR A: the wave comment and two rows (conversion_content_evidence_pr_a, git_gap_live_pages_pr_a; since TBD until the merge slot; rows are data and cannot move); re-summed at the gate-ahead on master v0.60.592.0 plus #8711: 1658 + 3 = 1661 measured; +4 GST-1094/GST-900 rows (memory_recall scope-read, member-bound acting_user, recall max_chars, unknown_param _meta-only) and +1 qm_scope_writes_gst1113 and +1 recall_question_terms_gst1304 rows (rows are data and cannot move), re-summed at the 0.60.595.0 slot merge: 1661 + 6; +1 GST-1582 refresh_barrier_import_gst1582 row (since TBD until the merge slot; rows are data and cannot move); +2 GST-1601 source_changed_origin_gst1601 and adopt_local_edits_gst1601 rows (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.596.0 merge: 1668 + 2; +1 GST-1623 refresh_barrier_capacity_gst1623 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.599.0 merge: 1670 + 1; +2 GBRA-224 W1 release_channel_stable_default row and its comment; +1 GST-1623 refresh_barrier_later_write_gst1623 row (#8765; rows are data and cannot move); +5 #8766 GST-1623 items 4/6-9 and #8755: the wave comment and four rows (doctor_foreign_writers_partial_gst1623, commit_push_enclosing_repo_gst1623, owner_guard_fail_closed_gst1623, adopt_local_edits_hardening_8755) and +1 managed_sync_kind_reserved_8765 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on master v0.60.608.0 plus #8798: 1674 + 6; +1 GST-1853 refresh_barrier_aborted_refresh_sync_gst1853 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.613.0 merge: 1680 + 1; +1 GST-1674 refresh_refused_merge_recovery_gst1674 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.614.0 merge: 1681 + 1; +1 #8824/#8826/#8767: adopt_local_edits_replay_markers_8824 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8837: 1682 + 1; +1 url_source_origin row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8834: 1683 + 1; +1 #8828: the refresh_replan_own_commits_8828 row (1684 + 1 at the 0.60.618.0 slot); +1 the managed commit-push unpublished-count row; +1 the refresh publish-diverged default row; +1 GST-2051 ungranted_member_writes_gst2051 row (since TBD until the merge slot; rows are data and cannot move); +1 GST-2107: the write_capacity_low_saved_gst2107 row (since TBD until the merge slot; rows are data and cannot move)+src/core/behavior-change-notice.ts 1690 ratchet +4 train R: #7491/#7492 keyword_identifier_probe and keyword_slug_handles rows and their comment, #7175 keyword phrase row; the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +1 GBRA-156 #7593: private_pages_granted_sources row (re-summed at the 0.60.527.0 merge: 1574 + 1); +3 GBRA-200 comment, write-grant refusal and degraded-stamp rows (re-summed at the 0.60.562.0 merge: 1615 + 3); +2 GBRA-280 get_page selector-precedence row and comment (re-summed at the 0.60.569.0 merge: 1619 + 2); the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 row; +1 #8059 quoted_fence_marker_8059 row; +2 GBRA-247 #8009 provenance_repair_held_8009 and #7982 pass_transient_streak_7982 rows; +4 GBRA-247 #7973 plain_directory_sync_7973, #7988 managed_marker_own_directory_7988, #7985 former_binding_parked_group_7985 and settle_effects_retire_7985 rows Train S merge: 1570 base + 5 (master since the #8077 base) + 13 (#8077) = 1588.; +2 GST-687 remote_quotes_unverified_text_gst687 row and its comment (re-summed at the gate-ahead on train S 0.60.534.0: 1588 + 2); +2 #8377: the quote fence follow-ups row and its comment; +2 #8384: the quote fence follow-ups 2 row and its comment; +2 #8384 wave 3: the quote fence follow-ups 3 row and its comment; +5 GBRA-218 train M rows (A1 member_read_access_gbra218 and member_access_hatch_scope_gbra218, B shared_agent_audience_gbra231, A2 folder_access_rules_gbra218, folder_access_scoped_role_gbra218), re-summed at the train M merge of master v0.60.541.0: 1596 + 5 = 1601 measured; +3 GST-359 train C rows (C1 qm_attested_actor_gst359, C2 member_facts_gst359, D qm_memory_provider_gst359), re-summed at the train C merge of master v0.60.543.0: 1601 + 3 = 1604 measured; +2 #8424: hook_launcher_8424 row and its comment (rows are data and cannot move), re-summed at the #8418 v0.60.546.0 merge: 1604 + 2 = 1606 measured; +2 #8426: mcp_lane_launcher_8426 row and its comment (rows are data and cannot move); +2 GST-927: empty_nonstring_args_gst927 row and its comment, re-summed at the gate-ahead on master v0.60.550.0 plus #8420: 1610 measured; +2 GBRA-283 Wave A (#8460): engine_keyed_caches_gbra283 row and its comment (rows are data and cannot move); +2 GBRA-287: segmented_freeze_hold_gbra287 and segmented_reexport_gbra287 rows (rows are data and cannot move); +1 GST-1209: segmented_tiling_gst1209 row (rows are data and cannot move); +1 GST-1251: skillopt_loop_deprecated_gst1251 row (rows are data and cannot move); +1 GST-1209 follow-up: untiled_hold_repair_gst1209 row (rows are data and cannot move); +1 GBRA-283 B3a: embedded_scope_required_gbra283 row (rows are data and cannot move); re-summed at the train R merge with v0.60.574.0: 1623 + 4; +2 GST-1387: refresh_fence_refusal_gst1387 row and its comment (rows are data and cannot move); re-summed at the memory train #8481 merge with v0.60.578.0 (1643 measured); +3 GBRA-253 #8109 rows (frontmatter_drift_write_8109, contacts_activity_advance_8109, contact_rows_dedupe_8109; rows are data and cannot move), re-summed at the master v0.60.581.0 merge: 1643 + 3 = 1646 measured; +3 #8123 part C rows: sync_write_through_off_writeback_7084, managed_sync_dry_run_counts_7087, frontmatter_missing_source_dir_7889 (since TBD until the merge slot; re-summed at the 0.60.583.0 merge: 1646 + 3); +4 PR B commit_ledger_prb, doctor_foreign_writers_prb and sources_guard_prb rows and their comment (rows are data and cannot move; since TBD until the merge slot); +1 PR B #8615: file_drift_held_needs_prefer_8615 row; +1 PR B #8617: refresh_source_changed_retry_8617 row; +1 PR B #8662: commit_push_checkout_not_a_source_8662 row (since TBD until the merge slot; rows are data and cannot move); +2 PR B refresh_barrier_prb and commit_push_base_prb rows (re-summed: 1658 measured); +3 convergence PR A: the wave comment and two rows (conversion_content_evidence_pr_a, git_gap_live_pages_pr_a; since TBD until the merge slot; rows are data and cannot move); re-summed at the gate-ahead on master v0.60.592.0 plus #8711: 1658 + 3 = 1661 measured; +4 GST-1094/GST-900 rows (memory_recall scope-read, member-bound acting_user, recall max_chars, unknown_param _meta-only) and +1 qm_scope_writes_gst1113 and +1 recall_question_terms_gst1304 rows (rows are data and cannot move), re-summed at the 0.60.595.0 slot merge: 1661 + 6; +1 GST-1582 refresh_barrier_import_gst1582 row (since TBD until the merge slot; rows are data and cannot move); +2 GST-1601 source_changed_origin_gst1601 and adopt_local_edits_gst1601 rows (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.596.0 merge: 1668 + 2; +1 GST-1623 refresh_barrier_capacity_gst1623 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.599.0 merge: 1670 + 1; +2 GBRA-224 W1 release_channel_stable_default row and its comment; +1 GST-1623 refresh_barrier_later_write_gst1623 row (#8765; rows are data and cannot move); +5 #8766 GST-1623 items 4/6-9 and #8755: the wave comment and four rows (doctor_foreign_writers_partial_gst1623, commit_push_enclosing_repo_gst1623, owner_guard_fail_closed_gst1623, adopt_local_edits_hardening_8755) and +1 managed_sync_kind_reserved_8765 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on master v0.60.608.0 plus #8798: 1674 + 6; +1 GST-1853 refresh_barrier_aborted_refresh_sync_gst1853 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.613.0 merge: 1680 + 1; +1 GST-1674 refresh_refused_merge_recovery_gst1674 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.614.0 merge: 1681 + 1; +1 #8824/#8826/#8767: adopt_local_edits_replay_markers_8824 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8837: 1682 + 1; +1 url_source_origin row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8834: 1683 + 1; +1 #8828: the refresh_replan_own_commits_8828 row (1684 + 1 at the 0.60.618.0 slot); +1 the managed commit-push unpublished-count row; +1 the refresh publish-diverged default row; +1 GST-2051 ungranted_member_writes_gst2051 row (since TBD until the merge slot; rows are data and cannot move); +1 GST-2107: the write_capacity_low_saved_gst2107 row (since TBD until the merge slot; rows are data and cannot move); +1 GBRA-108: the opt_in_receipt_caps_gbra108 BEHAVIOR_CHANGES rowdiff --git a/src/commands/doctor/checks/persistence-capacity.ts b/src/commands/doctor/checks/persistence-capacity.tsindex a5ff8f1a50..ffbee15f65 100644--- a/src/commands/doctor/checks/persistence-capacity.ts+++ b/src/commands/doctor/checks/persistence-capacity.ts@@ -1,7 +1,7 @@import type { BrainEngine } from '../../../core/engine.ts';import type { Check } from '../../doctor.ts';import { capacityDiagnostics } from '../../../core/persistence/diagnostics.ts';-import { oneYearCapacity, readJournalLimits } from '../../../core/persistence/limits.ts';+import { HOUSEKEEPING_FLOOR_DAYS, oneYearCapacity, readJournalLimits, readReceiptTargetBytes, RECEIPT_RETENTION_KEY, RECEIPT_TARGET_KEY } from '../../../core/persistence/limits.ts';import type { CapacityForecast } from '../../../core/persistence/capacity-forecast.ts';import { doctorCapacityForecast, forecastOrNull } from '../capacity-memo.ts';import { capacityVerify } from '../../../core/persistence/capacity-view.ts';@@ -35,6 +35,10 @@ export async function checkPersistenceCapacity(engine: BrainEngine): Promise<Checonst limits = await readJournalLimits(engine);const forecast: CapacityForecast | null = await doctorCapacityForecast(engine, { limits }).catch(forecastOrNull);const pause = await readBackgroundPauseShare(engine);+ const target = await readReceiptTargetBytes(engine);+ const [retention] = await engine.executeRaw<{ value: string }>('SELECT value FROM config WHERE key=$1', [RECEIPT_RETENTION_KEY]);+ const stored = Number(counters.find(row => row.key === 'brain')?.terminal_bytes ?? 0);+ const housekeeping = { target_bytes: target, used_bytes: stored, over_target: target > 0 && stored > target, explicit_retention_days: retention ? Number(retention.value) : null };const cumulative = capacityDiagnostics(counters, limits).filter(row => row.resource === 'lifetime_ids' || row.resource === 'terminal_bytes');const outstanding = [];for (const row of capacityDiagnostics(counters, limits)) {@@ -71,7 +75,7 @@ export async function checkPersistenceCapacity(engine: BrainEngine): Promise<Che}const anyPaused = resources.some(r => r.background_paused);const commands = [...needed].map(([key, value]) => `gbrain config set ${key} ${value}`);- const details = { exact: true, inspected: counters.length, truncated: false, resources, outstanding, commands, verify: VERIFY, docs: DOCS,+ const details = { exact: true, inspected: counters.length, truncated: false, resources, outstanding, commands, housekeeping, verify: VERIFY, docs: DOCS,background_pause_pct: Math.round(pause * 100), paused_producers: anyPaused ? [...BACKGROUND_PRODUCERS] : [],forecast: forecast ? { thresholds: forecast.thresholds, window_days: forecast.window_days, retention_days: forecast.retention_days,table_bytes: forecast.table_bytes, rows: forecast.rows } : { health: 'unknown' } };@@ -85,6 +89,17 @@ export async function checkPersistenceCapacity(engine: BrainEngine): Promise<Checonsent: [], actor: 'host_admin', requires_exclusive: false, verify: capacityVerify(), docs: DOCS,why: `Read-only: names the requests${holder ? ` source ${holder.source_id}` : ''} holds and why they have not settled (a refused write ends terminally and frees its slot).` },message: `${held}Run on the brain host: ${holder ? `gbrain sources writer status --source ${holder.source_id} --json` : 'gbrain sources writer status --json'}, then verify with ${VERIFY}.` };+ // GBRA-108: receipt storage over the housekeeping target is the host operator's to look at; it never refuses or pauses a write.+ if (!resources.length && housekeeping.over_target) return { name: 'persistence_capacity', status: 'warn', details,+ fix: { argv: ['gbrain', 'repair', 'receipt-compaction', '--json'], consent: [], actor: 'host_admin', requires_exclusive: false, verify: capacityVerify(), docs: DOCS,+ why: 'Previews the receipts an explicit compaction would take and the bytes it would free; it compacts nothing.' },+ message: `Receipt storage holds ${stored} reserved bytes, above the housekeeping target of ${target} (${RECEIPT_TARGET_KEY}). Writes are not affected: receipt storage never refuses or pauses a write unless the operator sets a cap. `+ + (housekeeping.explicit_retention_days !== null+ ? `Housekeeping leaves receipts to the retention you set (${RECEIPT_RETENTION_KEY} = ${housekeeping.explicit_retention_days} days). `+ : `Housekeeping compacts settled receipts, and refusals gbrain's own producers write again, older than ${HOUSEKEEPING_FLOOR_DAYS} days while storage is above the target; what stays is newer receipts, refusals whose intent a replay or retry reads, job receipts, receipts an open sync or recovery holds, and compacted receipts that keep request ids idempotent. `)+ + `On the brain host, gbrain repair receipt-compaction --json previews what an explicit compaction would free and compacts nothing; a larger target, or 0, quiets this warning.` };+ if (!resources.length && !cumulative.length) return { name: 'persistence_capacity', status: 'ok', details,+ message: `No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds ${stored} reserved bytes${target > 0 ? `, under the housekeeping target of ${target}` : ''}.` };if (!resources.length) return { name: 'persistence_capacity', status: 'ok', details,message: thresholds ? `Managed write capacity is below ${thresholds.warn_pct}% of every cumulative limit and none runs out within ${thresholds.warn_days} days at its 7-day rate.`: 'Managed write capacity is below 80% of every cumulative limit.' };diff --git a/src/commands/doctor/checks/persistence-requests.ts b/src/commands/doctor/checks/persistence-requests.tsindex 99f4635414..8056e11d01 100644--- a/src/commands/doctor/checks/persistence-requests.ts+++ b/src/commands/doctor/checks/persistence-requests.ts@@ -89,6 +89,7 @@ export async function requestGrowthCheck(engine: BrainEngine): Promise<Check> {WHERE created_at >= now() - interval '${WINDOW_DAYS} days'`, principal ? [principal[1], principal[2]] : []);const setting = principal ? 'principalLifetimeIds' : 'brainLifetimeIds';const used = Number(counter.lifetime_ids), limit = limits[setting];+ if (!Number.isFinite(limit)) continue;const windowDays = sample.admissions >= SAMPLE && sample.oldest? Math.max(1 / 24, (now - Date.parse(sample.oldest)) / 86_400_000) : WINDOW_DAYS;const perDay = sample.admissions / windowDays;diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 44f6c51375..c33e0e2fc1 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1490,6 +1490,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.619.0', id: 'managed_commit_push_unpublished_gst1923', text: 'On a managed checkout, `gbrain git commit-push -m <msg> -- <paths>` now reports how many commits the upstream lacks as last fetched (`unpublished` in `--json`, `null` when there is no upstream) and says nothing was pushed, instead of answering `nothing to commit; <remote>/<branch> at -` and logging `[push] ok-already-on-remote` for a commit that already existed. It writes no push-log line on a managed checkout. It still never pushes there; `gbrain git commit-push --push-only --keep-checkout --path <checkout>` publishes.' },{ since: '0.60.620.0', id: 'refresh_publish_diverged_default_gbra386', text: 'A diverged managed checkout now publishes its local commits on `gbrain sources refresh` by default when the worktree\'s Git durability is on: `sources.refresh_publish_diverged` unset now means on there (it used to mean off), merged with the upstream in memory, never rebased or forced. The refresh publish first scans what the local commits add (messages, added lines, merge resolutions) and refuses the new `publish_secret_found` naming the file, line and rule, never the value, when one looks like a secret; `gbrain git commit-push --push-only --scan-secrets` runs the same gate. Unset with durability not on still refuses, naming `gbrain sources writer git-durability <source> --enable`; `false` turns it off.' },{ since: '0.60.621.0', id: 'ungranted_member_writes_gst2051', text: 'A token or OAuth client bound to a member (`gbrain auth rescope --member <id>`) whose write source is `default` (no `--sources`, `--sources default`, or an OAuth client at its registration default) writes where every credential without a source grant reads. A page it creates there is now written with `readable_by: [member:<id>]`, so other members and unbound tokens no longer read it; rewriting it without `readable_by` keeps those readers, naming readers widens it, an edit to an existing page with no readers leaves it shared, and `POST /ingest` refuses such a credential. Pages derived from such a page (atoms, chronicle events, `derived_from` pages, a synthesized concept using it) are readable by no remote caller, the writer included; a page teammates should read names its readers when created, because every other remote credential, unbound tokens included, gets page_not_found writing a slug a member created until the operator adds readable_by on the brain host. Credentials writing to another source and unbound credentials are unchanged, and pages written before the upgrade keep their readers (`gbrain access who-can-read <slug>`).' },+ { since: 'TBD', id: 'opt_in_receipt_caps_gbra108', text: 'gbrain\'s own receipt bookkeeping no longer refuses, pauses or throttles writes by default: the cumulative caps on permanent request ids and reserved receipt bytes (`persistence.limits.{principal,brain}_{lifetime_ids,terminal_bytes}`, 2,000,000 / 8,000,000 ids and 16 GiB / 64 GiB before) apply only when set, so `write_quota_exhausted`, `write_quota_insufficient`, `write_capacity_backpressure`, `write_capacity_low` and a sync\'s `capacity_paused` happen only under a cap the operator chose. Instead, while reserved receipt bytes pass `persistence.housekeeping.receipt_target_bytes` (default 8 GiB, 0 off) and the retention is the default, the compaction pass also compacts settled page writes and refused maintenance and managed sync page writes older than 7 days (job receipts, connector writes and every other refusal keep their intent until the retention window), the `/metrics` `gbrain_write_capacity_*` gauges appear only for a cap that is set, and doctor `persistence_capacity` warns the host operator. A cap already set is unchanged; `gbrain config unset` removes one.' },{ since: 'TBD', id: 'write_capacity_low_saved_gst2107', text: 'The `write_capacity_low` notice a write receipt carries now opens with "This write was saved" and its fix is the read-only `gbrain doctor --only persistence_capacity --json` (actor agent) instead of a `gbrain config set` cap raise for the user, so an agent reading the end of a successful write no longer reports it as refused. The one-more-year value doctor, the notice snapshot and `/metrics` recommend now uses the 7-day mean rate, so one bulk day is no longer projected for a year; days-to-exhaustion still uses the larger of the mean and the last 24 hours. A `write_quota_exhausted`, `write_quota_insufficient` or background-pause refusal names the same value doctor does instead of sizing the year from the latest 1,000 admissions.' },];diff --git a/src/core/config.ts b/src/core/config.tsindex aeeea74b96..6b932a036c 100644--- a/src/core/config.ts+++ b/src/core/config.ts@@ -1811,7 +1811,7 @@ export const KNOWN_CONFIG_KEYS: readonly string[] = ['persistence.limits.principal_lifetime_ids', 'persistence.limits.brain_lifetime_ids','persistence.limits.principal_terminal_bytes', 'persistence.limits.brain_terminal_bytes','persistence.limits.brain_recovery_bytes', 'persistence.limits.worktree_recovery_bytes', 'persistence.limits.principal_staged_bytes', 'persistence.limits.brain_staged_bytes', 'persistence.limits.principal_uploads', 'persistence.limits.upload_idle_seconds', 'persistence.limits.upload_max_seconds',- 'persistence.receipt_retention_days', 'persistence.unbound_write', 'persistence.max_claim_ms', // #5254: persistence/unbound-source.ts; #6176: persistence/claim-phase.ts+ 'persistence.receipt_retention_days', 'persistence.housekeeping.receipt_target_bytes', 'persistence.unbound_write', 'persistence.max_claim_ms', // #5254: persistence/unbound-source.ts; #6176: persistence/claim-phase.ts'persistence.sync_preparation_ms', 'persistence.maintenance_preparation_ms', 'persistence.preparation_ceiling_ms', 'persistence.max_preparation_attempts', 'persistence.preparation_deadlines', 'persistence.max_transient_retries', // #6278: persistence/preparation-budget.ts, switches.ts; transient-retry.ts'persistence.publication_ceiling_ms', 'persistence.terminal_failures.window_days', 'persistence.terminal_failures.spike_factor', 'persistence.terminal_failures.spike_min', // #6405: persistence/sync-drain.ts (in-pass publication ceiling); #6650: persistence/terminal-failures.ts'persistence.capacity.warn_days', 'persistence.capacity.fail_days', 'persistence.capacity.background_pause_pct', // #6696: persistence/capacity-forecast.ts, admission-origin.tsdiff --git a/src/core/persistence/capacity-forecast.ts b/src/core/persistence/capacity-forecast.tsindex 00ea17955f..2745fb8dba 100644--- a/src/core/persistence/capacity-forecast.ts+++ b/src/core/persistence/capacity-forecast.ts@@ -193,6 +193,7 @@ export async function readCapacityForecast(engine: SqlEngine & { kind?: string }for (const resource of ['lifetime_ids', 'terminal_bytes'] as const) {const setting = `${prefix}${resource === 'lifetime_ids' ? 'LifetimeIds' : 'TerminalBytes'}` as keyof JournalLimits;const limit = limits[setting] ?? DEFAULT_JOURNAL_LIMITS[setting];+ if (!Number.isFinite(limit)) continue;const used = Number(counter[resource]);const ids = resource === 'lifetime_ids';const perDay = Math.max(total(ids ? 'ids' : 'gross') / windowDays, total(ids ? 'recent_ids' : 'recent_gross'));diff --git a/src/core/persistence/compaction-pass.ts b/src/core/persistence/compaction-pass.tsindex 6f9a4faef5..5536dcd767 100644--- a/src/core/persistence/compaction-pass.ts+++ b/src/core/persistence/compaction-pass.ts@@ -11,7 +11,10 @@* phase=compaction` line on stderr when the owner is `serve`.*/import type { BrainEngine } from '../engine.ts';-import { compactWriteReceiptsDetailed, yieldToEventLoop, type ReceiptCompactionResult } from './journal.ts';+import { compactReceipt, compactWriteReceiptsDetailed, NEWEST_SYNC_RECEIPT_EXCLUSION, OPEN_SYNC_CURSOR_EXCLUSION, yieldToEventLoop, type ReceiptCompactionResult } from './journal.ts';+import { getCode } from '../retry-matcher.ts';+import type { WriteRequest } from './model.ts';+import { HOUSEKEEPING_FLOOR_DAYS, readReceiptTargetBytes, RECEIPT_RETENTION_KEY } from './limits.ts';import { sweepCompactedReservations } from './receipt-true-up.ts';export const LAST_COMPACTION_KEY = 'persistence.maintenance.last_compaction';@@ -19,17 +22,21 @@ export const COMPACTION_STALE_HOURS_KEY = 'persistence.maintenance.compaction_stexport const DEFAULT_COMPACTION_STALE_HOURS = 24;const RECORD_EVERY_MS = 60 * 60_000;-export interface CompactionRecord extends ReceiptCompactionResult { at: string; host_id: string }+/** `early`: receipts of `compacted` that housekeeping took before the default retention (GBRA-108). */+export interface CompactionRecord extends ReceiptCompactionResult { at: string; host_id: string; early: number }const recordedAt = new WeakMap<object, number>();export async function runCompactionPass(engine: BrainEngine, opts: { hostId: string; notice?: boolean; now?: number }): Promise<CompactionRecord> {const result = await compactWriteReceiptsDetailed(engine);await yieldToEventLoop();+ const early = await housekeepReceipts(engine);+ for (const [reason, n] of Object.entries(early.skipped_by_reason)) result.skipped_by_reason[reason] = (result.skipped_by_reason[reason] ?? 0) + n;+ await yieldToEventLoop();const swept = await sweepCompactedReservations(engine);await yieldToEventLoop();const now = opts.now ?? Date.now();- const record: CompactionRecord = { at: new Date(now).toISOString(), host_id: opts.hostId, compacted: result.compacted,- freed_bytes: result.freed_bytes + swept.freed_bytes, skipped_by_reason: result.skipped_by_reason };+ const record: CompactionRecord = { at: new Date(now).toISOString(), host_id: opts.hostId, compacted: result.compacted + early.compacted,+ freed_bytes: result.freed_bytes + early.freed_bytes + swept.freed_bytes, skipped_by_reason: result.skipped_by_reason, early: early.compacted };if (record.compacted > 0 || record.freed_bytes > 0 || now - (recordedAt.get(engine) ?? -Infinity) >= RECORD_EVERY_MS) {// The record is a report: a refused config write (a read-only or fenced brain) never fails the maintenance tick.if (await engine.setConfig(LAST_COMPACTION_KEY, JSON.stringify(record)).then(() => true, () => false)) recordedAt.set(engine, now);@@ -41,6 +48,49 @@ export async function runCompactionPass(engine: BrainEngine, opts: { hostId: strreturn record;}+/**+ * What housekeeping may compact early (GBRA-108). Settled receipts, except `submit_job` ones (atom retries, generation+ * members and synthesis postprocess read their committed intents) and connector writes (a later retry's `retryOf` resolves+ * an earlier refusal). Refused receipts only where the producer writes again from current content and nothing reads the+ * intent: managed sync, file import, reconcile and file repair page writes, and maintenance pages. Every other refusal keeps+ * its intent until the retention window: a caller's write (`gbrain repair failed-writes` replays it), conversation facts+ * (the frozen extraction), atom members, connector items (their held-retry pointer).+ */+const EARLY_SQL = (r: string) => `((${r}.state IN ('committed','cancelled') AND ${r}.operation<>'submit_job' AND COALESCE(${r}.intent->>'kind','') NOT LIKE 'connector_%')+ OR (${r}.state IN ('failed','conflict') AND ((${r}.operation='put_page' AND (${r}.intent->>'kind' LIKE 'managed_sync_%'+ OR ${r}.intent->>'kind' IN ('managed_file_import','canonical_reconcile','managed_file_repair')))+ OR (${r}.operation='submit_job' AND ${r}.intent->>'kind'='managed_maintenance_page'))))`;+/**+ * GBRA-108: while the brain's reserved receipt bytes pass `persistence.housekeeping.receipt_target_bytes` and the retention is+ * the default, one batch of receipts older than HOUSEKEEPING_FLOOR_DAYS that `EARLY_SQL` admits compacts early, oldest first.+ * An explicit retention is the operator's and is kept, and every exclusion of the retention pass applies (`compactReceipt`+ * rechecks state, age, effects and sync under its lock; operation and intent never change once a request ends).+ */+export async function housekeepReceipts(engine: BrainEngine): Promise<ReceiptCompactionResult> {+ const result: ReceiptCompactionResult = { compacted: 0, freed_bytes: 0, skipped_by_reason: {} };+ const [target, [state]] = await Promise.all([readReceiptTargetBytes(engine), engine.executeRaw<{ retention: string | null; used: string | null; cutoff: string }>(+ `SELECT (SELECT value FROM config WHERE key=$1) AS retention,(SELECT terminal_bytes::text FROM persistence_counters WHERE key='brain') AS used,+ to_char((now()-($2::double precision*interval '1 day')) AT TIME ZONE 'UTC','YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS cutoff`, [RECEIPT_RETENTION_KEY, HOUSEKEEPING_FLOOR_DAYS])]);+ if (!state || state.retention !== null || target === 0 || Number(state.used ?? 0) <= target) return result;+ const states = ['committed', 'cancelled', 'failed', 'conflict'];+ const rows = await engine.executeRaw<Pick<WriteRequest, 'id' | 'principal_kind' | 'principal_id'>>(`SELECT id,principal_kind,principal_id FROM persistence_requests r+ WHERE state=ANY($1::text[]) AND recovery IS NULL AND NOT compacted AND completed_at < $2::timestamptz+ AND ${EARLY_SQL('r')}+ AND NOT EXISTS (SELECT 1 FROM persistence_effects e WHERE e.request_id=r.id AND e.state<>'committed')+ ${OPEN_SYNC_CURSOR_EXCLUSION('r')}+ ${NEWEST_SYNC_RECEIPT_EXCLUSION('r')}+ ORDER BY sequence LIMIT 100`, [states, state.cutoff]);+ for (const row of rows) {+ const done = await compactReceipt(engine, row, { states, completedBefore: state.cutoff }).catch(error => {+ if (['55P03', '57014'].includes(getCode(error) ?? '')) return { skipped: 'lock_timeout' };+ throw error;+ });+ if ('skipped' in done) result.skipped_by_reason[done.skipped] = (result.skipped_by_reason[done.skipped] ?? 0) + 1;+ else { result.compacted++; result.freed_bytes += done.freed_bytes; }+ }+ return result;+}+/** The last recorded pass, or null when none was recorded (or the record does not parse). */export async function readLastCompaction(engine: Pick<BrainEngine, 'getConfig'>): Promise<CompactionRecord | null> {const raw = await engine.getConfig(LAST_COMPACTION_KEY);diff --git a/src/core/persistence/diagnostics.ts b/src/core/persistence/diagnostics.tsindex c3c9996b79..85e4912c47 100644--- a/src/core/persistence/diagnostics.ts+++ b/src/core/persistence/diagnostics.ts@@ -127,7 +127,7 @@ export function capacityDiagnostics(counters: Counter[], limits: JournalLimits): [['outstanding_count', `${scope}Outstanding`], ['intent_bytes', `${scope}IntentBytes`],['lifetime_ids', `${scope}LifetimeIds`], ['terminal_bytes', `${scope}TerminalBytes`],...(scope === 'brain' ? [['recovery_bytes', 'brainRecoveryBytes'] as const] : [])];- return resources.map(([resource, setting]) => {+ return resources.filter(([, setting]) => Number.isFinite(limits[setting])).map(([resource, setting]) => {const used = Number(counter[resource]), limit = limits[setting];const approaching = limit === 0 ? used > 0 : used >= limit * 0.8;return { scope: counter.key, resource, used, limit, remaining: Math.max(0, limit - used),diff --git a/src/core/persistence/limits.ts b/src/core/persistence/limits.tsindex 04993f8962..0ae0b9dda0 100644--- a/src/core/persistence/limits.ts+++ b/src/core/persistence/limits.ts@@ -8,13 +8,25 @@ export const RETAINED_RECEIPT_BYTES = 4096;export const RECEIPT_RETENTION_KEY = 'persistence.receipt_retention_days';export const DEFAULT_RECEIPT_RETENTION_DAYS = 30;+/**+ * GBRA-108: while the brain's reserved receipt bytes pass this target, housekeeping compacts settled receipts and re-derivable+ * producer refusals older than HOUSEKEEPING_FLOOR_DAYS instead of waiting out the default retention (compaction-pass.ts+ * `EARLY_SQL`; an explicit retention is kept as set), and doctor tells the host operator. 0 turns both off. Never a write refusal.+ */+export const RECEIPT_TARGET_KEY = 'persistence.housekeeping.receipt_target_bytes';+export const DEFAULT_RECEIPT_TARGET_BYTES = 8 * 1024 ** 3;+export const HOUSEKEEPING_FLOOR_DAYS = 7;+export async function readReceiptTargetBytes(engine:SqlEngine):Promise<number> {+ const [row]=await engine.executeRaw<{value:string}>('SELECT value FROM config WHERE key=$1',[RECEIPT_TARGET_KEY]);+ return row ? parseJournalConfigValue(RECEIPT_TARGET_KEY,row.value) : DEFAULT_RECEIPT_TARGET_BYTES;+}export function journalLimitKey(key:keyof JournalLimits):string {return `persistence.limits.${key.replace(/[A-Z]/g,letter=>`_${letter.toLowerCase()}`)}`;}/** Every database config key the persistence journal reads. */export const JOURNAL_CONFIG_KEYS: readonly string[] = [- ...(Object.keys(DEFAULT_JOURNAL_LIMITS) as Array<keyof JournalLimits>).map(journalLimitKey), RECEIPT_RETENTION_KEY,+ ...(Object.keys(DEFAULT_JOURNAL_LIMITS) as Array<keyof JournalLimits>).map(journalLimitKey), RECEIPT_RETENTION_KEY, RECEIPT_TARGET_KEY,];export function parseJournalConfigValue(key:string,value:string):number {if(!/^(0|[1-9]\d*)$/.test(value) || !Number.isSafeInteger(Number(value))) {@@ -51,7 +63,7 @@ export async function readJournalLimits(engine:SqlEngine & { kind?: string },oveconst value=configured.get(journalLimitKey(key));if(value!==undefined) limits[key]=parseJournalConfigValue(journalLimitKey(key),value);if(overrides?.[key]!==undefined) limits[key]=overrides[key]!;- if(!Number.isSafeInteger(limits[key]) || limits[key]<0) throw new TypeError(`Invalid journal limit: ${key}`);+ if((!Number.isSafeInteger(limits[key]) || limits[key]<0) && !(limits[key]===Infinity && DEFAULT_JOURNAL_LIMITS[key]===Infinity)) throw new TypeError(`Invalid journal limit: ${key}`);}return limits;}diff --git a/src/core/persistence/model.ts b/src/core/persistence/model.tsindex 45e938d87a..ba9d801fd5 100644--- a/src/core/persistence/model.ts+++ b/src/core/persistence/model.ts@@ -180,9 +180,9 @@ export interface JournalLimits {export const DEFAULT_JOURNAL_LIMITS: Readonly<JournalLimits> = Object.freeze({principalOutstanding: 100, brainOutstanding: 1000,principalIntentBytes: 64 * 1024 ** 2, brainIntentBytes: 256 * 1024 ** 2,- // #6696 (A2): sized for 5,000 admissions a day for a year (docs/guides/concurrent-writes.md#growth-model).- principalLifetimeIds: 2_000_000, brainLifetimeIds: 8_000_000,- principalTerminalBytes: 16 * 1024 ** 3, brainTerminalBytes: 64 * 1024 ** 3,+ // GBRA-108: the cumulative caps are opt-in (Infinity until persistence.limits.* sets one); housekeeping and doctor bound receipt storage.+ principalLifetimeIds: Infinity, brainLifetimeIds: Infinity,+ principalTerminalBytes: Infinity, brainTerminalBytes: Infinity,brainRecoveryBytes: 1024 ** 3, worktreeRecoveryBytes: 256 * 1024 ** 2,});export type SqlEngine = Pick<BrainEngine, 'executeRaw'>;diff --git a/src/core/repair/core.ts b/src/core/repair/core.tsindex 12f0d04f7e..b6ff69b610 100644--- a/src/core/repair/core.ts+++ b/src/core/repair/core.ts@@ -282,7 +282,7 @@ export async function capacity(ctx: OperationContext) {return ([['lifetime_ids', `${scope}LifetimeIds`], ['terminal_bytes', `${scope}TerminalBytes`]] as const).map(([resource, setting]) => ({scope: key, resource, used: Number(row?.[resource] ?? 0), limit: limits[setting], stop_at: Math.floor(limits[setting] * STOP_RATIO),config_key: journalLimitKey(setting),- }));+ })).filter(row => Number.isFinite(row.limit));});}diff --git a/test/fixtures/goldens/doctor/content-pglite-human.json b/test/fixtures/goldens/doctor/content-pglite-human.jsonindex 4e25de0931..4b30cc0ada 100644--- a/test/fixtures/goldens/doctor/content-pglite-human.json+++ b/test/fixtures/goldens/doctor/content-pglite-human.json@@ -54,7 +54,7 @@" [INFO] harness_wiring: No agent harness was detected. Wire one when the user picks an agent app."," [OK] agent_contract: No agent dead ends in the last 7 days (0 non-success event(s) logged)."," [OK] connection: Connected, 5 pages",- " [OK] persistence_capacity: Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ " [OK] persistence_capacity: No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 115490 reserved bytes, under the housekeeping target of 8589934592."," [OK] persistence_terminal_failures: No terminal write failures in the last 7 d."," [OK] managed_sync_not_moving: No managed sync is pending."," [OK] managed_sync_blocked: No managed sync run is blocked.",diff --git a/test/fixtures/goldens/doctor/content-pglite-json.json b/test/fixtures/goldens/doctor/content-pglite-json.jsonindex 63bb1b5937..493dd6e5a2 100644--- a/test/fixtures/goldens/doctor/content-pglite-json.json+++ b/test/fixtures/goldens/doctor/content-pglite-json.json@@ -487,82 +487,7 @@"exact": true,"forecast": {"retention_days": 30,- "rows": [- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 8000000,- "max_day_7d": 7,- "pct": 0,- "per_day_7d": 7,- "recommended_limit": 16000000,- "resource": "lifetime_ids",- "scope": "brain",- "spike_day": null,- "status": "ok",- "used": 7,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.brain_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 68719476736,- "max_day_7d": 115490,- "net_per_day_7d": 22378,- "pct": 0,- "per_day_7d": 115490,- "reclaimable_bytes": 16318,- "recommended_limit": 137438953472,- "resource": "terminal_bytes",- "scope": "brain",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 115490,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 2000000,- "max_day_7d": 7,- "pct": 0,- "per_day_7d": 7,- "recommended_limit": 4000000,- "resource": "lifetime_ids",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "used": 7,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.principal_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 17179869184,- "max_day_7d": 115490,- "net_per_day_7d": 22378,- "pct": 0,- "per_day_7d": 115490,- "reclaimable_bytes": 16318,- "recommended_limit": 34359738368,- "resource": "terminal_bytes",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 115490,- "window_days": 1- }- ],+ "rows": [],"table_bytes": "<volatile>","thresholds": {"fail_days": 7,@@ -572,6 +497,12 @@},"window_days": 1},+ "housekeeping": {+ "explicit_retention_days": null,+ "over_target": false,+ "target_bytes": 8589934592,+ "used_bytes": 115490+ },"inspected": 2,"outstanding": [],"paused_producers": [],@@ -580,7 +511,7 @@"verify": "gbrain doctor --only persistence_capacity --json"},"elapsed_ms": "<volatile>",- "message": "Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ "message": "No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 115490 reserved bytes, under the housekeeping target of 8589934592.","name": "persistence_capacity","status": "ok"},@@ -691,6 +622,7 @@"last_compaction": {"at": "<ts>","compacted": 0,+ "early": 0,"freed_bytes": 0,"host_id": "<uuid>","skipped_by_reason": {}@@ -1510,30 +1442,7 @@"docs": "docs/guides/repair.md#request-growth","rows": 6,"rows_exact": true,- "scopes": [- {- "admissions_in_window": 6,- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 7,- "limit": 8000000,- "per_day": 1,- "scope": "brain",- "window_days": 7- },- {- "admissions_in_window": 6,- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 7,- "limit": 2000000,- "per_day": 1,- "scope": "principal:local_cli:<uuid>",- "window_days": 7- }- ],+ "scopes": [],"verify": "gbrain doctor --json (check persistence_request_growth)","window_days": 7},diff --git a/test/fixtures/goldens/doctor/hot-checks-pglite-json.json b/test/fixtures/goldens/doctor/hot-checks-pglite-json.jsonindex 0bf4f033b0..06cda5126b 100644--- a/test/fixtures/goldens/doctor/hot-checks-pglite-json.json+++ b/test/fixtures/goldens/doctor/hot-checks-pglite-json.json@@ -488,82 +488,7 @@"exact": true,"forecast": {"retention_days": 30,- "rows": [- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 8000000,- "max_day_7d": 24,- "pct": 0,- "per_day_7d": 24,- "recommended_limit": 16000000,- "resource": "lifetime_ids",- "scope": "brain",- "spike_day": null,- "status": "ok",- "used": 24,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.brain_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 68719476736,- "max_day_7d": 197727,- "net_per_day_7d": 58864,- "pct": 0,- "per_day_7d": 197727,- "reclaimable_bytes": 138863,- "recommended_limit": 137438953472,- "resource": "terminal_bytes",- "scope": "brain",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 197727,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 2000000,- "max_day_7d": 24,- "pct": 0,- "per_day_7d": 24,- "recommended_limit": 4000000,- "resource": "lifetime_ids",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "used": 24,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.principal_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 17179869184,- "max_day_7d": 197727,- "net_per_day_7d": 58864,- "pct": 0,- "per_day_7d": 197727,- "reclaimable_bytes": 138863,- "recommended_limit": 34359738368,- "resource": "terminal_bytes",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 197727,- "window_days": 1- }- ],+ "rows": [],"table_bytes": "<volatile>","thresholds": {"fail_days": 7,@@ -573,6 +498,12 @@},"window_days": 1},+ "housekeeping": {+ "explicit_retention_days": null,+ "over_target": false,+ "target_bytes": 8589934592,+ "used_bytes": 197727+ },"inspected": 2,"outstanding": [],"paused_producers": [],@@ -581,7 +512,7 @@"verify": "gbrain doctor --only persistence_capacity --json"},"elapsed_ms": "<volatile>",- "message": "Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ "message": "No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 197727 reserved bytes, under the housekeeping target of 8589934592.","name": "persistence_capacity","status": "ok"},@@ -692,6 +623,7 @@"last_compaction": {"at": "<ts>","compacted": 0,+ "early": 0,"freed_bytes": 0,"host_id": "<uuid>","skipped_by_reason": {}@@ -1607,30 +1539,7 @@"docs": "docs/guides/repair.md#request-growth","rows": 22,"rows_exact": true,- "scopes": [- {- "admissions_in_window": 22,- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 24,- "limit": 8000000,- "per_day": 3,- "scope": "brain",- "window_days": 7- },- {- "admissions_in_window": 22,- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 24,- "limit": 2000000,- "per_day": 3,- "scope": "principal:local_cli:<uuid>",- "window_days": 7- }- ],+ "scopes": [],"verify": "gbrain doctor --json (check persistence_request_growth)","window_days": 7},@@ -5585,82 +5494,7 @@"exact": true,"forecast": {"retention_days": 30,- "rows": [- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 8000000,- "max_day_7d": 24,- "pct": 0,- "per_day_7d": 24,- "recommended_limit": 16000000,- "resource": "lifetime_ids",- "scope": "brain",- "spike_day": null,- "status": "ok",- "used": 24,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.brain_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 68719476736,- "max_day_7d": 197727,- "net_per_day_7d": 58864,- "pct": 0,- "per_day_7d": 197727,- "reclaimable_bytes": 138863,- "recommended_limit": 137438953472,- "resource": "terminal_bytes",- "scope": "brain",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 197727,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 2000000,- "max_day_7d": 24,- "pct": 0,- "per_day_7d": 24,- "recommended_limit": 4000000,- "resource": "lifetime_ids",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "used": 24,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.principal_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 17179869184,- "max_day_7d": 197727,- "net_per_day_7d": 58864,- "pct": 0,- "per_day_7d": 197727,- "reclaimable_bytes": 138863,- "recommended_limit": 34359738368,- "resource": "terminal_bytes",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 197727,- "window_days": 1- }- ],+ "rows": [],"table_bytes": "<volatile>","thresholds": {"fail_days": 7,@@ -5670,6 +5504,12 @@},"window_days": 1},+ "housekeeping": {+ "explicit_retention_days": null,+ "over_target": false,+ "target_bytes": 8589934592,+ "used_bytes": 197727+ },"inspected": 2,"outstanding": [],"paused_producers": [],@@ -5678,7 +5518,7 @@"verify": "gbrain doctor --only persistence_capacity --json"},"elapsed_ms": "<volatile>",- "message": "Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ "message": "No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 197727 reserved bytes, under the housekeeping target of 8589934592.","name": "persistence_capacity","status": "ok"},@@ -5789,6 +5629,7 @@"last_compaction": {"at": "<ts>","compacted": 0,+ "early": 0,"freed_bytes": 0,"host_id": "<uuid>","skipped_by_reason": {}@@ -6704,30 +6545,7 @@"docs": "docs/guides/repair.md#request-growth","rows": 22,"rows_exact": true,- "scopes": [- {- "admissions_in_window": 22,- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 24,- "limit": 8000000,- "per_day": 3,- "scope": "brain",- "window_days": 7- },- {- "admissions_in_window": 22,- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 24,- "limit": 2000000,- "per_day": 3,- "scope": "principal:local_cli:<uuid>",- "window_days": 7- }- ],+ "scopes": [],"verify": "gbrain doctor --json (check persistence_request_growth)","window_days": 7},diff --git a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json b/test/fixtures/goldens/doctor/hot-checks-postgres-json.jsonindex 8efd132b9c..47ae41aad6 100644--- a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json+++ b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json@@ -482,82 +482,7 @@"exact": true,"forecast": {"retention_days": 30,- "rows": [- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 8000000,- "max_day_7d": 24,- "pct": 0,- "per_day_7d": 24,- "recommended_limit": 16000000,- "resource": "lifetime_ids",- "scope": "brain",- "spike_day": null,- "status": "ok",- "used": 24,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.brain_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 68719476736,- "max_day_7d": 198780,- "net_per_day_7d": 58870,- "pct": 0,- "per_day_7d": 198780,- "reclaimable_bytes": 139910,- "recommended_limit": 137438953472,- "resource": "terminal_bytes",- "scope": "brain",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 198780,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 2000000,- "max_day_7d": 24,- "pct": 0,- "per_day_7d": 24,- "recommended_limit": 4000000,- "resource": "lifetime_ids",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "used": 24,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.principal_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 17179869184,- "max_day_7d": 198780,- "net_per_day_7d": 58870,- "pct": 0,- "per_day_7d": 198780,- "reclaimable_bytes": 139910,- "recommended_limit": 34359738368,- "resource": "terminal_bytes",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 198780,- "window_days": 1- }- ],+ "rows": [],"table_bytes": "<volatile>","thresholds": {"fail_days": 7,@@ -567,6 +492,12 @@},"window_days": 1},+ "housekeeping": {+ "explicit_retention_days": null,+ "over_target": false,+ "target_bytes": 8589934592,+ "used_bytes": 198780+ },"inspected": 2,"outstanding": [],"paused_producers": [],@@ -575,7 +506,7 @@"verify": "gbrain doctor --only persistence_capacity --json"},"elapsed_ms": "<volatile>",- "message": "Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ "message": "No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 198780 reserved bytes, under the housekeeping target of 8589934592.","name": "persistence_capacity","status": "ok"},@@ -686,6 +617,7 @@"last_compaction": {"at": "<ts>","compacted": 0,+ "early": 0,"freed_bytes": 0,"host_id": "<uuid>","skipped_by_reason": {}@@ -1599,30 +1531,7 @@"docs": "docs/guides/repair.md#request-growth","rows": 22,"rows_exact": false,- "scopes": [- {- "admissions_in_window": 22,- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 24,- "limit": 8000000,- "per_day": 3,- "scope": "brain",- "window_days": 7- },- {- "admissions_in_window": 22,- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 24,- "limit": 2000000,- "per_day": 3,- "scope": "principal:local_cli:<uuid>",- "window_days": 7- }- ],+ "scopes": [],"verify": "gbrain doctor --json (check persistence_request_growth)","window_days": 7},@@ -5580,82 +5489,7 @@"exact": true,"forecast": {"retention_days": 30,- "rows": [- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 8000000,- "max_day_7d": 24,- "pct": 0,- "per_day_7d": 24,- "recommended_limit": 16000000,- "resource": "lifetime_ids",- "scope": "brain",- "spike_day": null,- "status": "ok",- "used": 24,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.brain_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 68719476736,- "max_day_7d": 198780,- "net_per_day_7d": 58870,- "pct": 0,- "per_day_7d": 198780,- "reclaimable_bytes": 139910,- "recommended_limit": 137438953472,- "resource": "terminal_bytes",- "scope": "brain",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 198780,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 2000000,- "max_day_7d": 24,- "pct": 0,- "per_day_7d": 24,- "recommended_limit": 4000000,- "resource": "lifetime_ids",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "used": 24,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.principal_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 17179869184,- "max_day_7d": 198780,- "net_per_day_7d": 58870,- "pct": 0,- "per_day_7d": 198780,- "reclaimable_bytes": 139910,- "recommended_limit": 34359738368,- "resource": "terminal_bytes",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 198780,- "window_days": 1- }- ],+ "rows": [],"table_bytes": "<volatile>","thresholds": {"fail_days": 7,@@ -5665,6 +5499,12 @@},"window_days": 1},+ "housekeeping": {+ "explicit_retention_days": null,+ "over_target": false,+ "target_bytes": 8589934592,+ "used_bytes": 198780+ },"inspected": 2,"outstanding": [],"paused_producers": [],@@ -5673,7 +5513,7 @@"verify": "gbrain doctor --only persistence_capacity --json"},"elapsed_ms": "<volatile>",- "message": "Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ "message": "No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 198780 reserved bytes, under the housekeeping target of 8589934592.","name": "persistence_capacity","status": "ok"},@@ -5784,6 +5624,7 @@"last_compaction": {"at": "<ts>","compacted": 0,+ "early": 0,"freed_bytes": 0,"host_id": "<uuid>","skipped_by_reason": {}@@ -6697,30 +6538,7 @@"docs": "docs/guides/repair.md#request-growth","rows": 22,"rows_exact": false,- "scopes": [- {- "admissions_in_window": 22,- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 24,- "limit": 8000000,- "per_day": 3,- "scope": "brain",- "window_days": 7- },- {- "admissions_in_window": 22,- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 24,- "limit": 2000000,- "per_day": 3,- "scope": "principal:local_cli:<uuid>",- "window_days": 7- }- ],+ "scopes": [],"verify": "gbrain doctor --json (check persistence_request_growth)","window_days": 7},diff --git a/test/fixtures/goldens/doctor/json-pglite-degraded.json b/test/fixtures/goldens/doctor/json-pglite-degraded.jsonindex 5dc7b9d4bb..567e119b94 100644--- a/test/fixtures/goldens/doctor/json-pglite-degraded.json+++ b/test/fixtures/goldens/doctor/json-pglite-degraded.json@@ -469,82 +469,7 @@"exact": true,"forecast": {"retention_days": 30,- "rows": [- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 8000000,- "max_day_7d": 1,- "pct": 0,- "per_day_7d": 1,- "recommended_limit": 16000000,- "resource": "lifetime_ids",- "scope": "brain",- "spike_day": null,- "status": "ok",- "used": 1,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.brain_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 68719476736,- "max_day_7d": 19163,- "net_per_day_7d": 2845,- "pct": 0,- "per_day_7d": 19163,- "reclaimable_bytes": 16318,- "recommended_limit": 137438953472,- "resource": "terminal_bytes",- "scope": "brain",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 19163,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 2000000,- "max_day_7d": 1,- "pct": 0,- "per_day_7d": 1,- "recommended_limit": 4000000,- "resource": "lifetime_ids",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "used": 1,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.principal_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 17179869184,- "max_day_7d": 19163,- "net_per_day_7d": 2845,- "pct": 0,- "per_day_7d": 19163,- "reclaimable_bytes": 16318,- "recommended_limit": 34359738368,- "resource": "terminal_bytes",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 19163,- "window_days": 1- }- ],+ "rows": [],"table_bytes": "<volatile>","thresholds": {"fail_days": 7,@@ -554,6 +479,12 @@},"window_days": 1},+ "housekeeping": {+ "explicit_retention_days": null,+ "over_target": false,+ "target_bytes": 8589934592,+ "used_bytes": 19163+ },"inspected": 2,"outstanding": [],"paused_producers": [],@@ -562,7 +493,7 @@"verify": "gbrain doctor --only persistence_capacity --json"},"elapsed_ms": "<volatile>",- "message": "Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ "message": "No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 19163 reserved bytes, under the housekeeping target of 8589934592.","name": "persistence_capacity","status": "ok"},@@ -673,6 +604,7 @@"last_compaction": {"at": "<ts>","compacted": 0,+ "early": 0,"freed_bytes": 0,"host_id": "<uuid>","skipped_by_reason": {}@@ -1387,30 +1319,7 @@"docs": "docs/guides/repair.md#request-growth","rows": 1,"rows_exact": true,- "scopes": [- {- "admissions_in_window": 1,- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 1,- "limit": 8000000,- "per_day": 0,- "scope": "brain",- "window_days": 7- },- {- "admissions_in_window": 1,- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 1,- "limit": 2000000,- "per_day": 0,- "scope": "principal:local_cli:<uuid>",- "window_days": 7- }- ],+ "scopes": [],"verify": "gbrain doctor --json (check persistence_request_growth)","window_days": 7},diff --git a/test/fixtures/goldens/doctor/json-pglite-fresh.json b/test/fixtures/goldens/doctor/json-pglite-fresh.jsonindex fe956f3135..1022bd152a 100644--- a/test/fixtures/goldens/doctor/json-pglite-fresh.json+++ b/test/fixtures/goldens/doctor/json-pglite-fresh.json@@ -472,82 +472,7 @@"exact": true,"forecast": {"retention_days": 30,- "rows": [- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 8000000,- "max_day_7d": 1,- "pct": 0,- "per_day_7d": 1,- "recommended_limit": 16000000,- "resource": "lifetime_ids",- "scope": "brain",- "spike_day": null,- "status": "ok",- "used": 1,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.brain_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 68719476736,- "max_day_7d": 19163,- "net_per_day_7d": 2845,- "pct": 0,- "per_day_7d": 19163,- "reclaimable_bytes": 16318,- "recommended_limit": 137438953472,- "resource": "terminal_bytes",- "scope": "brain",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 19163,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 2000000,- "max_day_7d": 1,- "pct": 0,- "per_day_7d": 1,- "recommended_limit": 4000000,- "resource": "lifetime_ids",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "used": 1,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.principal_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 17179869184,- "max_day_7d": 19163,- "net_per_day_7d": 2845,- "pct": 0,- "per_day_7d": 19163,- "reclaimable_bytes": 16318,- "recommended_limit": 34359738368,- "resource": "terminal_bytes",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 19163,- "window_days": 1- }- ],+ "rows": [],"table_bytes": "<volatile>","thresholds": {"fail_days": 7,@@ -557,6 +482,12 @@},"window_days": 1},+ "housekeeping": {+ "explicit_retention_days": null,+ "over_target": false,+ "target_bytes": 8589934592,+ "used_bytes": 19163+ },"inspected": 2,"outstanding": [],"paused_producers": [],@@ -565,7 +496,7 @@"verify": "gbrain doctor --only persistence_capacity --json"},"elapsed_ms": "<volatile>",- "message": "Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ "message": "No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 19163 reserved bytes, under the housekeeping target of 8589934592.","name": "persistence_capacity","status": "ok"},@@ -676,6 +607,7 @@"last_compaction": {"at": "<ts>","compacted": 0,+ "early": 0,"freed_bytes": 0,"host_id": "<uuid>","skipped_by_reason": {}@@ -1443,30 +1375,7 @@"docs": "docs/guides/repair.md#request-growth","rows": 1,"rows_exact": true,- "scopes": [- {- "admissions_in_window": 1,- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 1,- "limit": 8000000,- "per_day": 0,- "scope": "brain",- "window_days": 7- },- {- "admissions_in_window": 1,- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 1,- "limit": 2000000,- "per_day": 0,- "scope": "principal:local_cli:<uuid>",- "window_days": 7- }- ],+ "scopes": [],"verify": "gbrain doctor --json (check persistence_request_growth)","window_days": 7},diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.jsonindex 4c4b47af54..41445e52cb 100644--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json@@ -466,82 +466,7 @@"exact": true,"forecast": {"retention_days": 30,- "rows": [- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 8000000,- "max_day_7d": 1,- "pct": 0,- "per_day_7d": 1,- "recommended_limit": 16000000,- "resource": "lifetime_ids",- "scope": "brain",- "spike_day": null,- "status": "ok",- "used": 1,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.brain_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 68719476736,- "max_day_7d": 19163,- "net_per_day_7d": 2845,- "pct": 0,- "per_day_7d": 19163,- "reclaimable_bytes": 16318,- "recommended_limit": 137438953472,- "resource": "terminal_bytes",- "scope": "brain",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 19163,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history",- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 2000000,- "max_day_7d": 1,- "pct": 0,- "per_day_7d": 1,- "recommended_limit": 4000000,- "resource": "lifetime_ids",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "used": 1,- "window_days": 1- },- {- "basis": "aggregate_1d_short_history:gross_then_net",- "config_key": "persistence.limits.principal_terminal_bytes",- "days_to_exhaustion": null,- "exhaustion_date": null,- "limit": 17179869184,- "max_day_7d": 19163,- "net_per_day_7d": 2845,- "pct": 0,- "per_day_7d": 19163,- "reclaimable_bytes": 16318,- "recommended_limit": 34359738368,- "resource": "terminal_bytes",- "scope": "principal:local_cli:<uuid>",- "spike_day": null,- "status": "ok",- "under_reserved_receipts": 0,- "used": 19163,- "window_days": 1- }- ],+ "rows": [],"table_bytes": "<volatile>","thresholds": {"fail_days": 7,@@ -551,6 +476,12 @@},"window_days": 1},+ "housekeeping": {+ "explicit_retention_days": null,+ "over_target": false,+ "target_bytes": 8589934592,+ "used_bytes": 19163+ },"inspected": 2,"outstanding": [],"paused_producers": [],@@ -559,7 +490,7 @@"verify": "gbrain doctor --only persistence_capacity --json"},"elapsed_ms": "<volatile>",- "message": "Managed write capacity is below 80% of every cumulative limit and none runs out within 30 days at its 7-day rate.",+ "message": "No cumulative write cap is set (the default), so receipt storage never refuses or pauses a write; it holds 19163 reserved bytes, under the housekeeping target of 8589934592.","name": "persistence_capacity","status": "ok"},@@ -670,6 +601,7 @@"last_compaction": {"at": "<ts>","compacted": 0,+ "early": 0,"freed_bytes": 0,"host_id": "<uuid>","skipped_by_reason": {}@@ -1435,30 +1367,7 @@"docs": "docs/guides/repair.md#request-growth","rows": 0,"rows_exact": false,- "scopes": [- {- "admissions_in_window": 1,- "config_key": "persistence.limits.brain_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 1,- "limit": 8000000,- "per_day": 0,- "scope": "brain",- "window_days": 7- },- {- "admissions_in_window": 1,- "config_key": "persistence.limits.principal_lifetime_ids",- "days_to_exhaustion": null,- "exhaustion_date": null,- "lifetime_ids": 1,- "limit": 2000000,- "per_day": 0,- "scope": "principal:local_cli:<uuid>",- "window_days": 7- }- ],+ "scopes": [],"verify": "gbrain doctor --json (check persistence_request_growth)","window_days": 7},diff --git a/test/persistence-capacity-forecast.test.ts b/test/persistence-capacity-forecast.test.tsindex f9ba04cfa5..9406c34f4b 100644--- a/test/persistence-capacity-forecast.test.ts+++ b/test/persistence-capacity-forecast.test.ts@@ -101,6 +101,8 @@ for (const kind of testBackends()) {FROM persistence_requests t, generate_series(1,$2) WHERE t.id=$1::uuid`, [template.id, count]);}});+ // GBRA-108: the forecast covers a cap the operator set.+ await engine.setConfig('persistence.limits.principal_lifetime_ids', '2000000');const row = await principalIds(engine);expect(row.per_day_7d).toBe(Math.round(10_499 / 7));expect(row.max_day_7d).toBeGreaterThanOrEqual(10_000);@@ -114,6 +116,7 @@ for (const kind of testBackends()) {await declarePersistenceProtocol(tx);await tx.executeRaw(`UPDATE persistence_requests SET state='failed',completed_at=now(),intent=jsonb_build_object('body',repeat('x',100000)) WHERE id=$1::uuid`, [admitted.id]);});+ await engine.setConfig('persistence.limits.principal_terminal_bytes', String(16 * 1024 ** 3));const bytes = (await readCapacityForecast(engine)).rows.find(r => r.scope.startsWith('principal:') && r.resource === 'terminal_bytes')!;expect(bytes.under_reserved_receipts).toBe(1);expect(bytes.basis).toContain(':legacy_under_reserved');diff --git a/test/persistence-capacity-notices.test.ts b/test/persistence-capacity-notices.test.tsindex ec345ceea2..1b561098ba 100644--- a/test/persistence-capacity-notices.test.ts+++ b/test/persistence-capacity-notices.test.ts@@ -139,6 +139,7 @@ for (const kind of testBackends()) {await tx.executeRaw("UPDATE persistence_requests SET created_at=now()-interval '2 days' WHERE id=ANY($1::uuid[])", [ids.slice(1, 101)]);});await engine.setConfig('persistence.limits.principal_lifetime_ids', '1101');+ await engine.setConfig('persistence.limits.principal_terminal_bytes', String(16 * 1024 ** 3));const refusal = await fixture.admit('one-more').then(() => null, (error: { code?: string; fix?: { argv?: string[] } }) => error);expect(refusal).toMatchObject({ code: 'write_quota_exhausted', reason: 'lifetime_ids' });const forecast = await readCapacityForecast(engine);diff --git a/test/persistence-capacity.test.ts b/test/persistence-capacity.test.tsindex 13329f632b..bcb7ea801e 100644--- a/test/persistence-capacity.test.ts+++ b/test/persistence-capacity.test.ts@@ -11,7 +11,7 @@ import { KNOWN_CONFIG_KEYS } from '../src/core/config.ts';import { capacityWarnsAndRefusalNamesTheKey, compactionSkipsUnfinishedReceipts } from './helpers/w5-scenarios.ts';test('every journal config key is registered for `gbrain config set`', () => {- expect(JOURNAL_CONFIG_KEYS).toHaveLength(11);+ expect(JOURNAL_CONFIG_KEYS).toHaveLength(12);for (const key of JOURNAL_CONFIG_KEYS) expect(KNOWN_CONFIG_KEYS).toContain(key);});diff --git a/test/persistence-opt-in-caps.test.ts b/test/persistence-opt-in-caps.test.tsnew file mode 100644index 0000000000..4ae270bbc1--- /dev/null+++ b/test/persistence-opt-in-caps.test.ts@@ -0,0 +1,168 @@+/**+ * GBRA-108: gbrain's own receipt bookkeeping never refuses, pauses or throttles a write by default. The cumulative caps+ * (permanent request ids, reserved receipt bytes) are opt-in; housekeeping compacts settled receipts early while receipt+ * storage is above its target, never a failed or conflicted receipt whose intent a replay needs; doctor tells the brain+ * host's operator when storage stays above the target. Both backends.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import type { BrainEngine } from '../src/core/engine.ts';+import { withAdmissionOrigin } from '../src/core/persistence/admission-origin.ts';+import { runCompactionPass } from '../src/core/persistence/compaction-pass.ts';+import { __resetCapacityNoticesForTests, capacityNotices } from '../src/core/persistence/capacity-snapshot.ts';+import { declarePersistenceProtocol } from '../src/core/persistence/protocol.ts';+import { RECEIPT_TARGET_KEY, readJournalLimits } from '../src/core/persistence/limits.ts';+import { checkPersistenceCapacity } from '../src/commands/doctor/checks/persistence-capacity.ts';+import { editRequest, freshBrainFactory, requestFixture } from './helpers/persistence-request-fixture.ts';+import { testBackends } from './helpers/test-backends.ts';+import { withEnv } from './helpers/with-env.ts';++const databaseUrl = process.env.DATABASE_URL;+const OLD_DEFAULTS = { principal_lifetime_ids: 2_000_000, brain_lifetime_ids: 8_000_000, principal_terminal_bytes: 16 * 1024 ** 3, brain_terminal_bytes: 64 * 1024 ** 3 };++async function raw(engine: BrainEngine, sql: string, params: unknown[] = []) {+ await engine.transaction(async tx => { await declarePersistenceProtocol(tx); await tx.executeRaw(sql, params); });+}+/** Elapsed time: every request and effect moves `days` into the past. */+const age = (engine: BrainEngine, days: number) => raw(engine, `UPDATE persistence_requests SET created_at=created_at-($1::double precision*interval '1 day'),+ completed_at=completed_at-($1::double precision*interval '1 day')`, [days]);+const settleEffects = (engine: BrainEngine) => raw(engine, "UPDATE persistence_effects SET state='committed',error_code=NULL WHERE state<>'committed'");+const receipts = (engine: BrainEngine) => engine.executeRaw<{ slug: string; state: string; compacted: boolean; has_intent: boolean; age_days: number }>(+ `SELECT slug,state,compacted,intent IS NOT NULL AND intent::text<>'null' AS has_intent,EXTRACT(EPOCH FROM now()-completed_at)::float8/86400 AS age_days+ FROM persistence_requests ORDER BY sequence`);+const brainBytes = async (engine: BrainEngine) => Number((await engine.executeRaw<{ n: string }>("SELECT terminal_bytes::text AS n FROM persistence_counters WHERE key='brain'"))[0]!.n);++for (const kind of testBackends()) {+ describe(`opt-in receipt caps ${kind}`, () => {+ let factory: Awaited<ReturnType<typeof freshBrainFactory>>;+ let scratch: string;+ beforeAll(async () => {+ scratch = mkdtempSync(join(tmpdir(), 'gbrain-opt-in-caps-'));+ factory = await freshBrainFactory(kind, databaseUrl);+ }, 120_000);+ afterAll(async () => {+ await factory?.dispose();+ if (scratch) rmSync(scratch, { recursive: true, force: true });+ });+ const check = (name: string, fn: (engine: BrainEngine) => Promise<void>) => test(name, async () => {+ const engine = await factory.fresh();+ await withEnv({ GBRAIN_HOME: scratch, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, () => fn(engine));+ }, 240_000);++ check('an unset cap is no cap: writes past the old defaults are admitted, background ones too, and nothing says to raise a limit', async engine => {+ const requests = await requestFixture(engine);+ await requests.admit('first');+ // Counters at the old default caps: before GBRA-108 the next write refused write_quota_exhausted (and background+ // writes paused at 80% with write_capacity_backpressure).+ await raw(engine, `UPDATE persistence_counters SET lifetime_ids=CASE WHEN key='brain' THEN $1::bigint ELSE $2::bigint END,+ terminal_bytes=CASE WHEN key='brain' THEN $3::bigint ELSE $4::bigint END WHERE key='brain' OR key LIKE 'principal:%'`,+ [OLD_DEFAULTS.brain_lifetime_ids, OLD_DEFAULTS.principal_lifetime_ids, OLD_DEFAULTS.brain_terminal_bytes, OLD_DEFAULTS.principal_terminal_bytes]);+ expect((await requests.admit('background')).slug).toBe('background');+ expect((await withAdmissionOrigin('interactive', () => requests.admit('interactive'))).slug).toBe('interactive');+ const limits = await readJournalLimits(engine);+ for (const key of ['principalLifetimeIds', 'brainLifetimeIds', 'principalTerminalBytes', 'brainTerminalBytes'] as const) expect(limits[key]).toBe(Infinity);+ await engine.setConfig(RECEIPT_TARGET_KEY, '0');+ const doctor = await checkPersistenceCapacity(engine);+ expect(doctor.status).toBe('ok');+ expect(doctor.details).toMatchObject({ resources: [], commands: [] });+ expect(JSON.stringify(doctor)).not.toContain('persistence.limits.');+ __resetCapacityNoticesForTests();+ expect(await capacityNotices(engine, { throttle: false, now: Date.now() + 10 * 60_000 })).toEqual([]);+ });++ check('a cap the operator sets is still enforced', async engine => {+ const requests = await requestFixture(engine);+ await requests.admit('a');+ await engine.setConfig('persistence.limits.principal_lifetime_ids', '1');+ expect(await withAdmissionOrigin('interactive', () => requests.admit('b')).then(() => null, error => error))+ .toMatchObject({ code: 'write_quota_exhausted', detail: 'principal_lifetime_ids' });+ });++ check('above the target, housekeeping compacts settled receipts and re-derivable producer refusals older than a week, and keeps every intent a replay or retry reads', async engine => {+ const requests = await requestFixture(engine);+ const slugs = ['old-committed', 'old-failed', 'old-conflict', 'old-maintenance-failed', 'old-sync-failed', 'old-facts-failed', 'old-job-committed', 'young-committed'];+ for (const slug of slugs) await requests.publish(await requests.admit(slug));+ await settleEffects(engine);+ const [failed] = await engine.executeRaw<{ id: string }>("SELECT id FROM persistence_requests WHERE slug='old-failed'");+ const [conflict] = await engine.executeRaw<{ id: string }>("SELECT id FROM persistence_requests WHERE slug='old-conflict'");+ await editRequest(engine, failed!.id, "state='failed',error_code='example_failure'");+ await editRequest(engine, conflict!.id, "state='conflict',error_code='revision_conflict'");+ const id = async (slug: string) => (await engine.executeRaw<{ id: string }>('SELECT id FROM persistence_requests WHERE slug=$1', [slug]))[0]!.id;+ // Refusals gbrain's own producers write again from current content: a maintenance page and a managed sync import.+ await editRequest(engine, await id('old-maintenance-failed'), `operation='submit_job',state='conflict',error_code='source_changed',intent=intent||'{"kind":"managed_maintenance_page"}'::jsonb`);+ await editRequest(engine, await id('old-sync-failed'), `state='failed',error_code='example_failure',intent=intent||'{"kind":"managed_sync_import"}'::jsonb`);+ // A producer that recovers from its refused intent (the frozen extraction), and a settled job whose intent later runs read.+ await editRequest(engine, await id('old-facts-failed'), `operation='submit_job',state='failed',error_code='example_failure',intent=intent||'{"kind":"managed_conversation_facts"}'::jsonb`);+ await editRequest(engine, await id('old-job-committed'), `operation='submit_job',intent=intent||'{"kind":"managed_atom_page"}'::jsonb`);+ await age(engine, 10);+ await raw(engine, "UPDATE persistence_requests SET completed_at=now()-interval '2 days' WHERE slug='young-committed'");+ // Under the target (the default) nothing inside the 30-day retention is touched.+ await runCompactionPass(engine, { hostId: 'host-a' });+ expect((await receipts(engine)).filter(r => r.compacted)).toEqual([]);+ // An explicit retention is the operator's choice: housekeeping leaves it alone even above the target.+ await engine.setConfig(RECEIPT_TARGET_KEY, '1');+ await engine.setConfig('persistence.receipt_retention_days', '30');+ await runCompactionPass(engine, { hostId: 'host-a' });+ expect((await receipts(engine)).filter(r => r.compacted)).toEqual([]);+ await engine.executeRaw("DELETE FROM config WHERE key='persistence.receipt_retention_days'");+ const before = await brainBytes(engine);+ const pass = await runCompactionPass(engine, { hostId: 'host-a' });+ expect(pass).toMatchObject({ compacted: 3, early: 3 });+ expect(await brainBytes(engine)).toBeLessThan(before);+ const rows = Object.fromEntries((await receipts(engine)).map(r => [r.slug, r]));+ expect(rows['old-committed']).toMatchObject({ compacted: true });+ expect(rows['old-maintenance-failed']).toMatchObject({ compacted: true, has_intent: false });+ expect(rows['old-sync-failed']).toMatchObject({ compacted: true, has_intent: false });+ expect(rows['old-facts-failed']).toMatchObject({ compacted: false, has_intent: true });+ expect(rows['old-job-committed']).toMatchObject({ compacted: false, has_intent: true });+ expect(rows['old-failed']).toMatchObject({ compacted: false, has_intent: true });+ expect(rows['old-conflict']).toMatchObject({ compacted: false, has_intent: true });+ expect(rows['young-committed']).toMatchObject({ compacted: false, has_intent: true });+ });++ check('a long synthetic run: storage above the target keeps a week of settled receipts, failed intents wait for the retention, writes never refuse', async engine => {+ const requests = await requestFixture(engine);+ await engine.setConfig(RECEIPT_TARGET_KEY, '1');+ const perDay = 3;+ let peak = 0;+ for (let day = 0; day < 40; day++) {+ for (let i = 0; i < perDay; i++) await requests.publish(await requests.admit(`d${day}-${i}`));+ await settleEffects(engine);+ if (day % 10 === 0) {+ const [row] = await engine.executeRaw<{ id: string }>('SELECT id FROM persistence_requests WHERE slug=$1', [`d${day}-0`]);+ await editRequest(engine, row!.id, "state='failed',error_code='example_failure'");+ }+ await age(engine, 1);+ await runCompactionPass(engine, { hostId: 'host-a' });+ const rows = await receipts(engine);+ const fat = rows.filter(r => r.state === 'committed' && !r.compacted);+ expect(Math.max(0, ...fat.map(r => r.age_days))).toBeLessThanOrEqual(7.01);+ peak = Math.max(peak, fat.length);+ }+ const rows = await receipts(engine);+ expect(rows).toHaveLength(40 * perDay);+ // Uncompacted settled receipts never pass a week of admissions, however long the run.+ expect(peak).toBeLessThanOrEqual(8 * perDay);+ // Housekeeping never takes a failed receipt early: it keeps its intent until the 30-day retention pass, as before.+ const failed = rows.filter(r => r.state === 'failed');+ expect(failed).toHaveLength(4);+ for (const row of failed) expect(row).toMatchObject(row.age_days > 30 ? { compacted: true } : { compacted: false, has_intent: true });+ });++ check('doctor warns the host operator, without blocking anything, while receipt storage stays above the target', async engine => {+ const requests = await requestFixture(engine);+ await requests.publish(await requests.admit('page'));+ expect((await checkPersistenceCapacity(engine)).status).toBe('ok');+ await engine.setConfig(RECEIPT_TARGET_KEY, '1');+ const warning = await checkPersistenceCapacity(engine);+ expect(warning.status).toBe('warn');+ expect(warning.message).toContain('Writes are not affected');+ expect(warning.message).toContain(RECEIPT_TARGET_KEY);+ expect(warning.message).not.toContain('persistence.limits.');+ expect(warning.fix).toMatchObject({ actor: 'host_admin', argv: ['gbrain', 'repair', 'receipt-compaction', '--json'] });+ expect(warning.details).toMatchObject({ housekeeping: { target_bytes: 1, over_target: true } });+ });+ });+}diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txtindex a23cbc2a41..a45441cda9 100644--- a/test/postgres-unit-arms.txt+++ b/test/postgres-unit-arms.txt@@ -428,6 +428,7 @@ test/persistence-managed-lifecycle.test.tstest/persistence-managed-sync.test.tstest/persistence-manifest-git-scope.test.tstest/persistence-memory-mutations.test.ts+test/persistence-opt-in-caps.test.tstest/persistence-owner-activity.test.tstest/persistence-page-authority.test.tstest/persistence-physical-root-device.test.tsdiff --git a/test/read-waves-gbra133.test.ts b/test/read-waves-gbra133.test.tsindex 6014fa48fb..0353653ecc 100644--- a/test/read-waves-gbra133.test.ts+++ b/test/read-waves-gbra133.test.ts@@ -74,6 +74,8 @@ for (const kind of testBackends()) {check('the capacity forecast issues its reads together: two waves with a principal counter, not one per read', async engine => {const requests = await requestFixture(engine);await requests.admit('gbra133-forecast');+ // GBRA-108: a principal row exists for a cap the operator set.+ await engine.setConfig('persistence.limits.principal_lifetime_ids', '2000000');const baseline = await readCapacityForecast(engine);const { result, waves } = await recordWaves(engine, () => readCapacityForecast(engine));expect(waves).toBeLessThanOrEqual(2);