Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Retention pass keeps a caller refusal failed-writes can still replay (GBRA-108)
garrytanaad210db682c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cca65de440..9f9b3bda14 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,15 +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.+**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 that `gbrain repair failed-writes` could still replay now keeps its intent at any age, until a later write resolves it or you drop it with `gbrain repair receipt-compaction --include-failures`; the retention pass used to drop it after 30 days. 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`.+- `src/core/persistence/journal.ts`, `terminal-classify.ts`: the retention pass skips `UNRESOLVED_CALLER_REFUSAL_SQL` receipts (a writer-guard or `source_changed` refusal of a caller's `put_page`, `add_timeline_entry` or `remember` that no later request wrote, removed or repeated); `gbrain repair failed-writes` reads the same refusal predicates from there.+- Docs: `docs/guides/repair.md` (refused writes keep their intent until resolved; no retention raise needed for a recovery), `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; the retention pass keeps a 40-day-old replayable drift or guard refusal and compacts a resolved one and a non-replayable failure (red before: the drift refusal was compacted); 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.diff --git a/docs/architecture/key-files/core-persistence-capacity.md b/docs/architecture/key-files/core-persistence-capacity.mdindex a13fee187f..af85abc3d7 100644--- a/docs/architecture/key-files/core-persistence-capacity.md+++ b/docs/architecture/key-files/core-persistence-capacity.md@@ -9,7 +9,7 @@ Cumulative write caps (permanent request ids, receipt bytes; opt-in since GBRA-1- `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`, `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/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. The retention pass (`compactWriteReceiptsDetailed`) skips `terminal-classify.ts` `UNRESOLVED_CALLER_REFUSAL_SQL` (a caller refusal `repair failed-writes` could still replay, GBRA-108). `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`.diff --git a/docs/guides/concurrent-writes.md b/docs/guides/concurrent-writes.mdindex 20183453b1..087b97eaf0 100644--- a/docs/guides/concurrent-writes.md+++ b/docs/guides/concurrent-writes.md@@ -886,7 +886,11 @@ work; it does not discard an accepted request to make room. Terminal diagnosticcompaction has a default eligibility threshold of 30 days and preserves replay IDs, digests, terminaloutcomes, and frozen memory-verb result fields. Pending/recovering requests arenot evicted, and receipts with unfinished effects stay retained without-blocking compaction of later receipts. Lifetime IDs and replay protection are+blocking compaction of later receipts. A caller's refused write that+`gbrain repair failed-writes` could still replay (a writer-guard or+`source_changed` refusal of a `put_page`, `add_timeline_entry` or+`remember` that no later request wrote, removed or repeated) keeps its intent+at any age; `gbrain repair receipt-compaction --include-failures` drops it explicitly. Lifetime IDs and replay protection arenot silently reset.Each admission reserves at least 16 KiB of receipt bytes. When the request@@ -981,8 +985,9 @@ off), the resident consumer's compaction pass also compacts receipts older thanof producers that write again from current content (maintenance pages andmanaged sync, file import, reconcile and file repair page writes). Jobreceipts (`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+intent until the retention window (a caller's replayable refusal until a+later write resolves it): `gbrain repair failed-writes` replays a caller's+refused write from it, conversation facts resubmit a frozenextraction, atom retries and connector held-item retries read it. Receiptswith 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.diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex 7d4e592f1f..839bb1b3a0 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -2641,8 +2641,10 @@ gbrain older than v0.60.38.0 refuses writes it should allow. And a write endscopy differed at publication, as every write did on a brain whose v0.13.1grandfather `validate: false` stamp lived only in the database (#6429, fixedin v0.60.157.0: that stamp is no longer read as a file edit). Each refused-write keeps a receipt with its full intent until receipt compaction-(`persistence.receipt_retention_days`, 30 days by default). `gbrain repair+write keeps a receipt with its full intent until a later request writes,+removes or repeats it: receipt compaction skips such a refused caller write+however old it is, and `gbrain repair receipt-compaction --include-failures`+is the explicit way to drop one. `gbrain repairfailed-writes` submits those writes again. It is explicit-only andpreview-bound, and needs v0.60.38.0 or later (`gbrain doctor --json` reportsschema version 197 or later). Doctor's `lost_caller_writes` counts the@@ -2664,11 +2666,9 @@ me the list, then apply after I agree."* The agent runs `gbrain repairfailed-writes` and, after you agree, the printed apply command.```bash-gbrain config set persistence.receipt_retention_days 90 # keep the receipts while you recovergbrain repair failed-writes --source <id> # preview: every refused write with its classgbrain repair failed-writes --source <id> --apply --expect <hash>gbrain repair failed-writes --source <id> # replayed writes now read already_written-gbrain config unset persistence.receipt_retention_days # recovered: back to 30 days, so receipts stop holding write capacity 3x longer```Candidates are failed receipts refused by the guard (`writer_coordinator_required`,diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex c33e0e2fc1..c34cb535fb 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1490,7 +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: '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 the retention pass no longer drops a caller\'s refused write that `gbrain repair failed-writes` could still replay (it waits until a later write resolves it, or `gbrain repair receipt-compaction --include-failures` drops it), 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/persistence/journal.ts b/src/core/persistence/journal.tsindex 81c25b01a7..44079a575c 100644--- a/src/core/persistence/journal.ts+++ b/src/core/persistence/journal.ts@@ -9,6 +9,7 @@ import type { Action } from '../agent-output.ts';import { digest, jsonBytes, requireUuid } from './digest.ts';import { authorizeWrite } from './authority.ts';import { journalLimitKey, oneYearCapacity, readJournalLimits, readReceiptRetentionDays } from './limits.ts';+import { UNRESOLVED_CALLER_REFUSAL_SQL } from './terminal-classify.ts';import { outstandingCapacityDetail, retryWriteAdmission, waitOutRefreshFence } from './admission-retry.ts';import { PreadmitBrainChanged } from './preadmit-cache.ts';import { pipelined } from '../page-state/transactions.ts';@@ -1246,6 +1247,7 @@ export async function compactWriteReceiptsDetailed(engine: BrainEngine, retentioWHERE state IN ('committed','conflict','failed','cancelled') AND recovery IS NULL AND NOT compactedAND completed_at < now()-($1::double precision*interval '1 day')AND NOT EXISTS (SELECT 1 FROM persistence_effects e WHERE e.request_id=r.id AND e.state<>'committed')+ AND NOT ${UNRESOLVED_CALLER_REFUSAL_SQL('r')}${OPEN_SYNC_CURSOR_EXCLUSION('r')}${NEWEST_SYNC_RECEIPT_EXCLUSION('r')}ORDER BY sequence LIMIT 100`, [retentionDays]);diff --git a/src/core/persistence/terminal-classify.ts b/src/core/persistence/terminal-classify.tsindex 05c129cbb7..0e80ab0b91 100644--- a/src/core/persistence/terminal-classify.ts+++ b/src/core/persistence/terminal-classify.ts@@ -398,6 +398,22 @@ export function terminalKnockOnSql(alias: string): string {/** Page removals: a later one supersedes any earlier write of the page. */export const PAGE_REMOVAL_OPERATIONS: readonly string[] = ['delete_page', 'purge_page'];+/** The writes `gbrain repair failed-writes` replays: a caller's own `put_page` (no owner `kind`), `add_timeline_entry` and `remember`. */+export const CALLER_REPLAYABLE_OPERATIONS: readonly string[] = ['put_page', 'add_timeline_entry', 'remember'];+/** A writer-guard refusal (no publication ran). */+export const GUARD_REFUSAL_SQL = (r: string) => `(${r}.state='failed' AND (${r}.error_code='writer_coordinator_required'+ OR (${r}.error_code='storage_error' AND ${r}.error_message LIKE 'Publication failed (P0001)%')))`;+/** #6429: a refusal from prepareFileTarget (page-prepare.ts); the receipt keeps the code, not the refusal's detail. */+export const DRIFT_REFUSAL_SQL = (r: string) => `(${r}.state='conflict' AND ${r}.error_code='source_changed')`;+/**+ * GBRA-108: a caller's refused write that `gbrain repair failed-writes` could still replay: no later request wrote, removed or+ * repeated it (`supersessionSql`). The retention pass keeps its intent until then; `gbrain repair receipt-compaction+ * --include-failures` is the operator's explicit drop.+ */+export const UNRESOLVED_CALLER_REFUSAL_SQL = (r: string) => `((${GUARD_REFUSAL_SQL(r)} OR ${DRIFT_REFUSAL_SQL(r)})+ AND ${r}.operation IN (${CALLER_REPLAYABLE_OPERATIONS.map(op => `'${op}'`).join(',')}) AND NOT (${r}.operation='put_page' AND ${r}.intent ? 'kind')+ AND NOT EXISTS (SELECT 1 FROM persistence_requests c WHERE ${supersessionSql(r, 'c')}))`;+/*** The supersession rule of `gbrain repair failed-writes`, as a predicate over a candidate later request `c` of the* failed request `r` (both `persistence_requests` aliases): the same intent committed, failed or still pending; a laterdiff --git a/src/core/repair/failed-writes.ts b/src/core/repair/failed-writes.tsindex 447394ed01..9277eb7ea3 100644--- a/src/core/repair/failed-writes.ts+++ b/src/core/repair/failed-writes.ts@@ -60,21 +60,19 @@ import { factsAbsorbWriteKey, factsRetryDeadCommand } from '../facts/dead-absorbimport { readFactsBackstopJobPage } from '../persistence/effect-facts.ts';import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';import { resolveEntitySlugWithSource } from '../entities/resolve.ts';-import { dispositionOf, PAGE_REMOVAL_OPERATIONS, supersessionOrderSql, supersessionSql } from '../persistence/terminal-classify.ts';+import { CALLER_REPLAYABLE_OPERATIONS, dispositionOf, DRIFT_REFUSAL_SQL, GUARD_REFUSAL_SQL, PAGE_REMOVAL_OPERATIONS, supersessionOrderSql, supersessionSql } from '../persistence/terminal-classify.ts';import { isStatementTimeout } from '../persistence/bounded-reads.ts';import { readRequestIndexStates } from '../persistence/checkpoint-validation.ts';import { PERSISTENCE_REQUEST_REPLAY_ID_INDEX, PERSISTENCE_REQUEST_SLUG_SEQUENCE_INDEX } from '../persistence/schema.ts';import { StatementDeadlineError, withStatementDeadline } from '../statement-deadline.ts';import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairScope } from './core.ts';-const REPLAYABLE = ['put_page', 'add_timeline_entry', 'remember'];+const REPLAYABLE = [...CALLER_REPLAYABLE_OPERATIONS];const REMEMBER_PREPARED_KEYS = ['entity_slug', 'fence', 'valid_from', 'valid_until', 'entity_inferred', 'entity_warning', 'visibility_defaulted'];const REMOTE_PREPARED_KEYS = ['source_kind', 'source_uri', 'ingested_via'];const PAGE_REMOVALS = PAGE_REMOVAL_OPERATIONS;-const GUARD_REFUSAL = `(r.state='failed' AND (r.error_code='writer_coordinator_required'- OR (r.error_code='storage_error' AND r.error_message LIKE 'Publication failed (P0001)%')))`;-/** #6429: a refusal from prepareFileTarget (page-prepare.ts); the receipt keeps the code, not the refusal's detail. */-const DRIFT_REFUSAL = `(r.state='conflict' AND r.error_code='source_changed')`;+const GUARD_REFUSAL = GUARD_REFUSAL_SQL('r');+const DRIFT_REFUSAL = DRIFT_REFUSAL_SQL('r');/** #7602: a managed fact request refused because its entity page moved; extraction re-admits these since, but older ones stayed refused. */const FACTS_MOVED_REFUSAL = `(r.operation='extract_facts' AND r.state='conflict' AND r.error_code='revision_conflict'AND r.error_message IN (${FACTS_ENTITY_MOVED_MESSAGES.map(message => `'${message.replaceAll("'", "''")}'`).join(',')}))`;diff --git a/test/persistence-opt-in-caps.test.ts b/test/persistence-opt-in-caps.test.tsindex 4ae270bbc1..4a1b822841 100644--- a/test/persistence-opt-in-caps.test.ts+++ b/test/persistence-opt-in-caps.test.ts@@ -122,6 +122,33 @@ for (const kind of testBackends()) {expect(rows['young-committed']).toMatchObject({ compacted: false, has_intent: true });});+ check('the retention pass keeps a refused caller write that failed-writes can still replay until a later request resolves it', async engine => {+ const requests = await requestFixture(engine);+ for (const slug of ['drifted', 'guarded', 'resolved', 'other-failure']) await requests.publish(await requests.admit(slug));+ await settleEffects(engine);+ const id = async (slug: string) => (await engine.executeRaw<{ id: string }>('SELECT id FROM persistence_requests WHERE slug=$1 ORDER BY sequence LIMIT 1', [slug]))[0]!.id;+ // Refusals `gbrain repair failed-writes` replays: a file/database drift and a writer guard on a caller's own page write.+ await editRequest(engine, await id('drifted'), "state='conflict',error_code='source_changed'");+ await editRequest(engine, await id('guarded'), "state='failed',error_code='writer_coordinator_required'");+ await editRequest(engine, await id('resolved'), "state='conflict',error_code='source_changed'");+ // A refusal failed-writes does not replay.+ await editRequest(engine, await id('other-failure'), "state='failed',error_code='example_failure'");+ await age(engine, 40);+ // A later committed write of the page resolves its refusal.+ const later = await requests.admit('resolved');+ await editRequest(engine, later.id, "state='committed',completed_at=now(),error_code=NULL");+ await settleEffects(engine);+ await engine.setConfig(RECEIPT_TARGET_KEY, '0');+ await runCompactionPass(engine, { hostId: 'host-a' });+ const rows = await receipts(engine);+ const first = (slug: string) => rows.find(r => r.slug === slug)!;+ expect(first('drifted')).toMatchObject({ compacted: false, has_intent: true });+ expect(first('guarded')).toMatchObject({ compacted: false, has_intent: true });+ expect(first('resolved')).toMatchObject({ compacted: true });+ expect(first('other-failure')).toMatchObject({ compacted: true });+ // Explicitly dropping it stays the operator's call (gbrain repair receipt-compaction --include-failures).+ });+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');diff --git a/test/persistence-publication-refusal-5974.test.ts b/test/persistence-publication-refusal-5974.test.tsindex e7612a92b1..86278553dc 100644--- a/test/persistence-publication-refusal-5974.test.ts+++ b/test/persistence-publication-refusal-5974.test.ts@@ -16,7 +16,7 @@ import type { BrainEngine } from '../src/core/engine.ts';import type { OperationContext } from '../src/core/ops/contract.ts';import { registerLocalWriter } from '../src/core/persistence/identity.ts';import { submissionAuthority } from '../src/core/persistence/authority.ts';-import { admitWrite, claimNextWrite, compactWriteReceipts, receiptFor, type WriteAdmission } from '../src/core/persistence/journal.ts';+import { admitWrite, claimNextWrite, COMPACTABLE_STATES, compactReceipt, compactWriteReceipts, receiptFor, type WriteAdmission } from '../src/core/persistence/journal.ts';import { publishMutation } from '../src/core/persistence/coordinator.ts';import { claimWorktree } from '../src/core/persistence/ownership.ts';import { databaseRefusal, publicFailureDetail } from '../src/core/persistence/publication-failure.ts';@@ -107,7 +107,9 @@ describe('#5974 database refusal diagnostics', () => {expect(failure.next_action).toBe(DATABASE_REFUSAL_HINT);await engine.executeRaw("UPDATE persistence_requests SET completed_at=now()-interval '400 days' WHERE id=$1::uuid", [done.id]);- await compactWriteReceipts(engine, 1);+ // GBRA-108: the retention pass keeps a caller refusal failed-writes could still replay; the explicit compaction drops it.+ expect(await compactWriteReceipts(engine, 1)).toBe(0);+ expect(await compactReceipt(engine, done, { states: COMPACTABLE_STATES })).toMatchObject({ freed_bytes: expect.any(Number) });const [compacted] = await engine.executeRaw<{ compacted: boolean; error_message: string | null; error_detail: unknown }>('SELECT compacted,error_message,error_detail FROM persistence_requests WHERE id=$1::uuid', [done.id]);expect(compacted.compacted).toBe(true);