Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Admission refusals name the same one-year value as doctor: 7-day mean while the scope admitted that week (GST-2107)

garrytan9db54ae3cf89
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6f0576dc1a..fa9a1a56cb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,8 +18,9 @@ identifiers and attribution are available in the pre-removal Git revision
- `src/core/persistence/capacity-snapshot.ts`: `write_capacity_low` says the write was saved and names doctor's read-only check (actor `agent`) as its fix, with no cap raise in the notice.
- `src/core/persistence/capacity-forecast.ts`: `recommended_limit` (doctor `persistence_capacity`, the notice snapshot, `gbrain sync status` and `/metrics`) covers one more year at the 7-day mean gross and net rates instead of the larger of the mean and the last 24 hours.
+- `src/core/persistence/limits.ts`: `oneYearCapacity` (every `write_quota_exhausted`, `write_quota_insufficient` and background-pause refusal, and doctor's fallback) uses the scope's 7-day window over the forecast's window length while the scope admitted anything that week, and keeps the latest-1,000 sample for a scope idle all week; the compacted-size SQL moves to `receipt-bytes.ts` so both reads count the same net bytes.
- Docs: `docs/guides/write-refusals.md` (`write_capacity_low` row), `docs/guides/concurrent-writes.md` (the notice, the mean-rate value, and returning a raised `persistence.receipt_retention_days` to the default before raising a cap), `docs/guides/repair.md` (unset the 90-day retention once a failed-writes recovery is done), `docs/architecture/key-files/core-persistence-capacity.md`.
-- Tests: `test/persistence-capacity-notices.test.ts` (the notice's fix and wording; a burst of 28 admissions in the last day over a 10-a-day week recommends the mean-rate value, ids exactly and receipt bytes under the mean-rate ceiling).
+- Tests: `test/persistence-capacity-notices.test.ts` (the notice's fix and wording; a burst of 28 admissions in the last day over a 10-a-day week recommends the mean-rate value, ids exactly and receipt bytes under the mean-rate ceiling; after 1,000 admissions in one hour on a 100-a-week principal, a real `write_quota_exhausted` refusal names exactly the value doctor recommends, ids and receipt bytes, on PGLite and Postgres).
## [0.60.620.0] - 2026-11-09
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 141206108b..ad480cd214 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1489,7 +1489,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.618.0', id: 'refresh_replan_own_commits_8828', text: 'A `gbrain sources refresh` whose checkout HEAD moved while it waited for writes admitted before its fence no longer refuses `refresh_source_changed` when every commit since its start is one of gbrain\'s own (in the commit ledger) and the upstream branch holds them: it takes HEAD as its start and fast-forwards to the upstream. A HEAD move that includes a commit gbrain did not make, or gbrain\'s commits the upstream does not hold yet, still refuses as before.' },
{ 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: '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.' },
+ { 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.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/persistence/capacity-forecast.ts b/src/core/persistence/capacity-forecast.ts
index aa06d7b7a9..00ea17955f 100644
--- a/src/core/persistence/capacity-forecast.ts
+++ b/src/core/persistence/capacity-forecast.ts
@@ -24,7 +24,7 @@ import type { SqlEngine } from './model.ts';
import { DEFAULT_JOURNAL_LIMITS, type JournalLimits } from './model.ts';
import { DEFAULT_RECEIPT_RETENTION_DAYS, journalLimitKey, parseJournalConfigValue, readJournalLimits, RECEIPT_RETENTION_KEY, recommendedLimit } from './limits.ts';
import { BACKGROUND_PAUSE_KEY, backgroundPauseShare } from './admission-origin.ts';
-import { COMPACTED_HEADROOM_BYTES } from './receipt-bytes.ts';
+import { COMPACTED_RECEIPT_BYTES_SQL } from './receipt-bytes.ts';
export const CAPACITY_WARN_DAYS_KEY = 'persistence.capacity.warn_days';
export const CAPACITY_FAIL_DAYS_KEY = 'persistence.capacity.fail_days';
@@ -134,8 +134,7 @@ async function principalDays(engine: SqlEngine, key: string, net: string): Promi
return rows.map(row => toDay({ ...row, scope: key }));
}
-const NET_SQL = (r: string, e: string) => `LEAST(${r}.terminal_reservation,octet_length(${r}.authority::text)+COALESCE(octet_length(${r}.outcome::text),0)
- +COALESCE(octet_length(${r}.error_detail::text),0)+COALESCE(octet_length(${r}.client_request_id),0)+COALESCE(${e}.bytes,0)+${COMPACTED_HEADROOM_BYTES})`;
+const NET_SQL = COMPACTED_RECEIPT_BYTES_SQL;
/** The configured days-to-exhaustion thresholds every capacity finding uses. */
export async function readCapacityThresholds(engine: SqlEngine): Promise<{ warnDays: number; failDays: number }> {
diff --git a/src/core/persistence/limits.ts b/src/core/persistence/limits.ts
index 29473667c8..04993f8962 100644
--- a/src/core/persistence/limits.ts
+++ b/src/core/persistence/limits.ts
@@ -1,7 +1,7 @@
import { opError, type OperationError } from '../ops/contract.ts';
import { PAGE_BODY_CONFIG_KEYS, pageRecoveryBytes, segmentedPageCeiling } from '../page-body/limits.ts';
import { DEFAULT_JOURNAL_LIMITS, principalKey, type JournalLimits, type Principal, type SqlEngine } from './model.ts';
-import { COMPACTED_HEADROOM_BYTES, RECEIPT_RESERVATION_FLOOR } from './receipt-bytes.ts';
+import { COMPACTED_HEADROOM_BYTES, COMPACTED_RECEIPT_BYTES_SQL, EFFECT_BYTES_SQL, RECEIPT_RESERVATION_FLOOR } from './receipt-bytes.ts';
/** Fallback compacted receipt size when no receipt is sampled; a compacted put_page measures about 3.9 KB. */
export const RETAINED_RECEIPT_BYTES = 4096;
@@ -68,24 +68,41 @@ export function recommendedLimit(resource: CapacityResource, used: number, limit
return resource === 'terminal_bytes' ? Math.ceil(value / 1024 ** 2) * 1024 ** 2 : value;
}
+/** Newest admissions a one-year read walks for the 7-day window (the walk reads the sequence index newest first). */
+const WINDOW_WALK_ROWS = 200_000;
/**
- * A cumulative cap value that covers one more year at the scope's recent
- * admission rate (sampled from its latest 1,000 admissions), never less than
- * double the current cap. Receipt bytes use the sample's measured
- * reservations: what its receipts reserve now while the retention window
- * holds them, and their compacted size after (capacity-forecast.ts
- * `recommendedLimit`, the formula doctor uses too).
+ * A cumulative cap value that covers one more year, never less than double the current cap. GST-2107: while the scope
+ * admitted anything in the last 7 days it uses the window's mean rates over the window `readCapacityForecast` uses
+ * (7 days, or the brain's age, at least a day), so an admission refusal names the same value as doctor and one bulk hour
+ * is not projected for a year. A scope idle for a week is sized from its latest 1,000 admissions, however old. Receipt
+ * bytes use measured reservations: what receipts reserve while the retention window holds them, and their compacted size
+ * after (`recommendedLimit`).
*/
export async function oneYearCapacity(engine:SqlEngine,scope:string,setting:'LifetimeIds'|'TerminalBytes',used:number,limit:number):Promise<number> {
const principal=/^principal:([^:]+):(.+)$/.exec(scope);
- const [sample]=await engine.executeRaw<{admissions:number;age_seconds:number|null;gross:number|null;net:number|null}>(`SELECT count(*)::int AS admissions,
- EXTRACT(EPOCH FROM (now()-min(created_at)))::float8 AS age_seconds,avg(terminal_reservation)::float8 AS gross,
- avg(LEAST(terminal_reservation,octet_length(authority::text)+COALESCE(octet_length(outcome::text),0)+COALESCE(octet_length(error_detail::text),0)+${COMPACTED_HEADROOM_BYTES}))::float8 AS net
- FROM (SELECT created_at,terminal_reservation,authority,outcome,error_detail FROM persistence_requests
- ${principal ? 'WHERE principal_kind=$1 AND principal_id=$2' : ''} ORDER BY sequence DESC LIMIT 1000) recent`,
+ const where=principal ? 'WHERE principal_kind=$1 AND principal_id=$2' : '';
+ const [sample]=await engine.executeRaw<{admissions:number;age_seconds:number|null;gross:number|null;net:number|null;
+ window_ids?:number|null;window_gross?:number|null;window_net?:number|null;window_span_days?:number|null;brain_age_days?:number|null}>(`WITH recent AS (
+ SELECT id,created_at,terminal_reservation,authority,outcome,error_detail,client_request_id FROM persistence_requests ${where} ORDER BY sequence DESC LIMIT 1000),
+ w AS (SELECT * FROM (SELECT id,created_at,terminal_reservation,authority,outcome,error_detail,client_request_id FROM persistence_requests ${where}
+ ORDER BY sequence DESC LIMIT ${WINDOW_WALK_ROWS}) walk WHERE created_at>now()-interval '7 days'),
+ e AS (SELECT request_id,SUM(${EFFECT_BYTES_SQL}) AS bytes FROM persistence_effects WHERE request_id IN (SELECT id FROM w) GROUP BY request_id)
+ SELECT (SELECT count(*)::int FROM recent) AS admissions,(SELECT EXTRACT(EPOCH FROM (now()-min(created_at)))::float8 FROM recent) AS age_seconds,
+ (SELECT avg(terminal_reservation)::float8 FROM recent) AS gross,
+ (SELECT avg(LEAST(terminal_reservation,octet_length(authority::text)+COALESCE(octet_length(outcome::text),0)+COALESCE(octet_length(error_detail::text),0)+${COMPACTED_HEADROOM_BYTES}))::float8 FROM recent) AS net,
+ (SELECT count(*)::int FROM w) AS window_ids,(SELECT EXTRACT(EPOCH FROM now()-min(created_at))/86400 FROM w)::float8 AS window_span_days,(SELECT COALESCE(SUM(terminal_reservation),0)::float8 FROM w) AS window_gross,
+ (SELECT COALESCE(SUM(${COMPACTED_RECEIPT_BYTES_SQL('w', 'e')}),0)::float8 FROM w LEFT JOIN e ON e.request_id=w.id) AS window_net,
+ (SELECT EXTRACT(EPOCH FROM now()-created_at)/86400 FROM persistence_requests ORDER BY sequence LIMIT 1)::float8 AS brain_age_days`,
principal ? [principal[1],principal[2]] : []);
- const perDay=sample.admissions/Math.max(1/24,(sample.age_seconds ?? 0)/86_400);
const retention=await readReceiptRetentionDays(engine).catch(()=>DEFAULT_RECEIPT_RETENTION_DAYS);
+ const windowIds=Number(sample.window_ids ?? 0);
+ if(windowIds>0) {
+ // A week busier than the walk reads the walk's own span, so the rate is never diluted over days it did not read.
+ const windowDays=windowIds>=WINDOW_WALK_ROWS ? Math.max(1/24,Number(sample.window_span_days ?? 0)) : Math.min(7,Math.max(1,Number(sample.brain_age_days ?? 7)));
+ return setting==='LifetimeIds' ? recommendedLimit('lifetime_ids',used,limit,{perDay:windowIds/windowDays},retention)
+ : recommendedLimit('terminal_bytes',used,limit,{perDay:Number(sample.window_gross)/windowDays,netPerDay:Number(sample.window_net)/windowDays},retention);
+ }
+ const perDay=sample.admissions/Math.max(1/24,(sample.age_seconds ?? 0)/86_400);
const measured=(value:number|null|undefined,fallback:number)=>Number.isFinite(Number(value)) && Number(value)>0 ? Number(value) : fallback;
return setting==='LifetimeIds' ? recommendedLimit('lifetime_ids',used,limit,{perDay},retention)
: recommendedLimit('terminal_bytes',used,limit,{perDay:perDay*measured(sample.gross,RECEIPT_RESERVATION_FLOOR),netPerDay:perDay*measured(sample.net,RETAINED_RECEIPT_BYTES)},retention);
diff --git a/src/core/persistence/receipt-bytes.ts b/src/core/persistence/receipt-bytes.ts
index a4e8ba4217..38b9e9fd6c 100644
--- a/src/core/persistence/receipt-bytes.ts
+++ b/src/core/persistence/receipt-bytes.ts
@@ -8,6 +8,12 @@ export const RECEIPT_HEADROOM_BYTES = 4096;
export const COMPACTED_HEADROOM_BYTES = 1024;
/** Space an admission reserves beyond its intent and authority: the outcome, error, effect rows and headroom a completion may add. */
export const RECEIPT_COMPLETION_BYTES = 12_288;
+/**
+ * A request row `r`'s reservation once compacted, with `e.bytes` its effect rows' bytes (a LEFT JOIN, so null is none): what
+ * the capacity forecast and the one-year value count as the net, retained rate.
+ */
+export const COMPACTED_RECEIPT_BYTES_SQL = (r: string, e: string) => `LEAST(${r}.terminal_reservation,octet_length(${r}.authority::text)+COALESCE(octet_length(${r}.outcome::text),0)
+ +COALESCE(octet_length(${r}.error_detail::text),0)+COALESCE(octet_length(${r}.client_request_id),0)+COALESCE(${e}.bytes,0)+${COMPACTED_HEADROOM_BYTES})`;
/** Bytes one effect row holds on its receipt; the SQL twin of `effectBytes`. */
export const EFFECT_BYTES_SQL = 'octet_length(data::text)+octet_length(kind)+1024';
diff --git a/test/persistence-capacity-notices.test.ts b/test/persistence-capacity-notices.test.ts
index 946441f102..ec345ceea2 100644
--- a/test/persistence-capacity-notices.test.ts
+++ b/test/persistence-capacity-notices.test.ts
@@ -16,7 +16,7 @@ import { declarePersistenceProtocol } from '../src/core/persistence/protocol.ts'
import { renderCapacityMetrics } from '../src/commands/serve-http-metrics.ts';
import { NOTICE_CODES } from '../src/core/error-registry.ts';
import { readCapacityForecast } from '../src/core/persistence/capacity-forecast.ts';
-import { recommendedLimit } from '../src/core/persistence/limits.ts';
+import { oneYearCapacity, recommendedLimit } from '../src/core/persistence/limits.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';
@@ -125,6 +125,31 @@ for (const kind of testBackends()) {
expect(row('terminal_bytes').recommended_limit).toBeLessThanOrEqual(ceiling);
});
+ check('after a burst the admission refusal names the same one-year value as doctor (GST-2107)', async engine => {
+ await engine.setConfig('persistence.limits.principal_outstanding', '5000');
+ await engine.setConfig('persistence.limits.brain_outstanding', '5000');
+ const fixture = await requestFixture(engine);
+ const ids: string[] = [];
+ for (let i = 0; i < 1101; i++) ids.push((await fixture.admit(`dense-${i}`)).id);
+ // One admission before the window, 100 over the week before the last day, then 1,000 in the last hour: the latest
+ // 1,000 admissions are all burst, while the 7-day mean is 1,100 / 7 a day.
+ await engine.transaction(async tx => {
+ await declarePersistenceProtocol(tx);
+ await tx.executeRaw("UPDATE persistence_requests SET created_at=now()-interval '10 days' WHERE id=$1::uuid", [ids[0]]);
+ 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');
+ 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);
+ const doctor = forecast.rows.find(r => r.scope.startsWith('principal:') && r.resource === 'lifetime_ids')!;
+ expect(doctor.recommended_limit).toBe(Math.ceil(1101 + (1100 / 7) * 365));
+ expect(Number(refusal!.fix!.argv!.at(-1))).toBe(doctor.recommended_limit);
+ const principal = forecast.rows.find(r => r.scope.startsWith('principal:'))!.scope;
+ const terminal = forecast.rows.find(r => r.scope === principal && r.resource === 'terminal_bytes')!;
+ expect(await oneYearCapacity(engine, principal, 'TerminalBytes', terminal.used, terminal.limit)).toBe(terminal.recommended_limit);
+ });
+
check('writes within a minute share one snapshot; the next minute reads again', async engine => {
await requestFixture(engine).then(r => r.admit('one'));
await engine.setConfig('persistence.limits.principal_lifetime_ids', '1000');