Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(sync): keep page-body hold rows out of receipt classification; derived writes skip segmented pages in write-through (GBRA-287 /ship review)
garrytan7bf2f8a372d8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f99e874547..e6233aec75 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -21,13 +21,13 @@ A full sync's DB-only reconcile (#2426) now re-exports a page stored in segments- `src/core/page-state/import-guard.ts` (`sameCanonicalImport`): a stored body left unread (over 24 MiB) differs from any parsed body, as `sameContentAnyKeyOrder` already said, instead of reading the throwing getter.- `src/core/persistence/sync-screen.ts` (`frozenImportScreenInput`): the freeze screen reads the page snapshot (and a rename's base) through `materializedSnapshot`.- `src/core/persistence/sync-entry-fault.ts` (`freezeFaultHold`): `page_body_segmented` and `page_body_rows_unreadable` thrown while freezing one entry hold that entry `page_write_failed` (origin `freeze`, `write_failure.code` the page-body code) instead of stopping the run. The item breaker still applies.-- `src/core/persistence/sync-fault-class.ts`, `public-category.ts`, `sync-status.ts` (`holdVerdict`): rows for both codes (`page_body_segmented`: upgrade, a person; `page_body_rows_unreadable`: retry, the segment-table grant), applied to a `page_write_failed` hold whose `write_failure.code` names one; `last_error.request_id` is `null` for a failure no request was admitted for.+- `src/core/persistence/sync-fault-class.ts`, `public-category.ts`, `sync-status.ts` (`holdVerdict`): `freeze_page_body_segmented` (upgrade, a person) and `freeze_page_body_rows_unreadable` (retry, the segment-table grant) rows, applied to a `page_write_failed` hold whose `write_failure.code` names the page-body code; a write receipt with either bare code keeps its class (a caller refusal, a gbrain defect); `last_error.request_id` is `null` for a failure no request was admitted for.- `src/core/write-through.ts` (`writePageThrough`): a page stored in segments is measured from its segments (`unreadPageFile`) and checked against the pre-push scan cap before `source_path` is bound, then streamed (`stageStreamedContent`, which refuses bytes that changed since the measure) on the engine it was given, so a caller inside a transaction (an owner repair) works, keeping the existing file's mode, and renamed over the target after the file-changed check; frontmatter overrides on such a page are refused with an error result.- `src/core/persistence/page-prepare.ts` (`fileMatchesSnapshot`): a segmented snapshot is compared read back whole, so the freeze drift screen no longer reads a format-only difference as drift.-- `src/core/cycle/derived-write-through.ts` (`writeDerivedFile`): a generated page stored in segments is skipped (`segmented_page`), since the batch rollback compares file strings.+- `src/core/cycle/derived-write-through.ts` (`writeDerivedFile`): a generated page stored in segments is skipped (`segmented_page`, `writePageThrough`'s `inlineOnly`), since the batch rollback compares file strings.- `src/commands/sync/full.ts`: the DB-only re-export no longer refuses segmented pages, and each failed re-export is returned in `reexport_failures` (slug, path, code, message, fix).- `src/core/page-body/body-tiling.ts` (`readTiledManifest`), `ingest.ts`, `read-range.ts`, `projection.ts`, `segment-rewrite.ts`: a live read names its generation first and checks that generation's rows against that generation's size; a live read whose generation a publish retired meanwhile reads the new live generation (up to 3 attempts).-- Tests: `test/large-pages/managed-sync-segmented-freeze.test.ts` (the live-checkout freeze, with its inline twin, and a page whose rows don't tile held while the rest of the commit imports), `test/sync-reconcile-db-only-segmented.test.ts` (2 MiB and over-24 MiB re-exports byte-equal to `gbrain export`, one failing page listed while the run advances, a plain-directory source, a write inside a transaction keeping the file's mode, a file over the scan cap left unbound, the derived skip), `test/segmented-read-concurrent-publish.test.ts` (a forced publish between a reader's statements). Every case but the plain-directory one fails on master.+- Tests: `test/large-pages/managed-sync-segmented-freeze.test.ts` (the live-checkout freeze, with its inline twin, and a page whose rows don't tile held while the rest of the commit imports), `test/sync-reconcile-db-only-segmented.test.ts` (2 MiB and over-24 MiB re-exports byte-equal to `gbrain export`, one failing page listed while the run advances, a plain-directory source, a write inside a transaction keeping the file's mode, frontmatter overrides refused, a file over the scan cap left unbound, the derived skip), `test/segmented-fault-classes-gbra287.test.ts` (hold and receipt classes), `test/segmented-read-concurrent-publish.test.ts` (a forced publish between a reader's statements). Every case but the plain-directory one fails on master.## [0.60.559.0] - 2026-11-03diff --git a/src/core/cycle/derived-write-through.ts b/src/core/cycle/derived-write-through.tsindex 9b170a9363..357b7bb2a5 100644--- a/src/core/cycle/derived-write-through.ts+++ b/src/core/cycle/derived-write-through.ts@@ -116,11 +116,10 @@ async function writeDerivedFile(engine: BrainEngine, slug: string, sourceId: strif (!file.ok) return { written: false, skipped: 'file_database_drift' };expectedFileBytes = file.expectedFileBytes;}- const [row] = await engine.executeRaw<{ source_path: string | null; body_storage: string }>(- 'SELECT source_path, body_storage FROM pages WHERE source_id = $1 AND slug = $2 AND deleted_at IS NULL', [sourceId, slug]);- // A page stored in segments has its file streamed without a string the batch rollback could compare (`after`).- if (row?.body_storage === 'segmented') return { written: false, skipped: 'segmented_page' };- const result = await writePageThrough(engine, slug, { sourceId, expectedFileBytes, deferCommit: true });+ const [row] = await engine.executeRaw<{ source_path: string | null }>(+ 'SELECT source_path FROM pages WHERE source_id = $1 AND slug = $2 AND deleted_at IS NULL', [sourceId, slug]);+ // inlineOnly: a page stored in segments has its file streamed without a string the batch rollback could compare (`after`).+ const result = await writePageThrough(engine, slug, { sourceId, expectedFileBytes, deferCommit: true, inlineOnly: true });if (result.error) console.error(`[write-through] ${slug}: ${result.error}`);if (!result.written || !result.path) return result;noteWritten(resolved.target.writeRoot, result.path);diff --git a/src/core/persistence/public-category.ts b/src/core/persistence/public-category.tsindex b7c9814f34..3907b6a8e1 100644--- a/src/core/persistence/public-category.ts+++ b/src/core/persistence/public-category.ts@@ -35,7 +35,7 @@ export const PUBLIC_BY_TERMINAL: Readonly<Record<TerminalCategory, PublicCategorexport const PUBLIC_BY_CODE: Readonly<Record<string, PublicCategory>> = {worktree_dirty: 'drift', file_drift: 'drift', file_drift_unknown: 'drift', source_changed: 'drift', pinned_git_worktree_conflict: 'drift',concurrent_write: 'conflict', revision_conflict: 'conflict', page_identity_changed: 'conflict', legacy_slug_conflict: 'conflict', origin_conflict: 'conflict', origin_conflict_decision: 'conflict', page_identity_decision: 'conflict',- settle_mismatch: 'defect', page_write_failed: 'defect', page_body_segmented: 'defect', page_body_rows_unreadable: 'storage',+ settle_mismatch: 'defect', page_write_failed: 'defect', freeze_page_body_segmented: 'defect', freeze_page_body_rows_unreadable: 'storage',invalid_fence: 'content_refused', invalid_frontmatter: 'content_refused', frontmatter_slug_conflict: 'content_refused', rename_held: 'content_refused',rename_identity_unreadable: 'content_refused', rename_reconcile_failed: 'conflict',file_too_large: 'content_refused', content_rejected: 'content_refused', managed_image_sync_unsupported: 'content_refused',diff --git a/src/core/persistence/sync-fault-class.ts b/src/core/persistence/sync-fault-class.tsindex e6c61858e6..e4a65decdb 100644--- a/src/core/persistence/sync-fault-class.ts+++ b/src/core/persistence/sync-fault-class.ts@@ -54,7 +54,8 @@ const ESCALATE_AFTER = `${HOLD_ATTEMPTS_NEEDS_HUMAN} failed attempts over ${HOLD/*** GBRA-287: a stored page body a freeze could not read (`page_body_segmented`: a whole-body read of a page stored in* segments; `page_body_rows_unreadable`: segment rows that do not tile the body) is that page's fault, never the run's.- * It is held `page_write_failed` (origin `freeze`) with this code in `meta.write_failure.code`, which classifies the hold.+ * It is held `page_write_failed` (origin `freeze`) with this code in `meta.write_failure.code`; the hold is classified by the+ * `freeze_<code>` row (holdVerdict).*/export const PAGE_BODY_FAULT_CODES: ReadonlySet<string> = new Set(['page_body_segmented', 'page_body_rows_unreadable']);@@ -96,10 +97,11 @@ export const SYNC_FAULT_TABLE: ReadonlyArray<SyncFaultRule> = [{ code: 'settle_mismatch', class: 'page', safe_actions: ['none'], needs_human: true, escalate: 'always: the pass cannot tell why the path does not settle',human_reason: 'Sync settled this file three passes in a row but it never read settled afterwards; read gbrain doctor --json and gbrain sources writer status <source> (read-only), fix what they name, then run gbrain sources retry-held <source> to re-test it.' },// GBRA-130 A-6: one path's write failed the same unclassifiable way on repeated attempts; held so the rest of the source moves.- // GBRA-287: a stored page body a sync path could not read: whole (a page stored in segments), or at all (rows that do not tile it).- { code: 'page_body_segmented', class: 'page', safe_actions: ['upgrade'], needs_human: true, escalate: 'always: a sync path read a page stored in segments whole',+ // GBRA-287: a freeze hold whose stored page body a sync path could not read: whole (a page stored in segments), or at all+ // (rows that do not tile it). Keyed by detail codes no receipt carries, so a write receipt with the bare code keeps its class.+ { code: 'freeze_page_body_segmented', class: 'page', safe_actions: ['upgrade'], needs_human: true, escalate: 'always: a sync path read a page stored in segments whole',human_reason: 'A sync path read this page stored in segments as one string, so its file is held and the rest of the source synced; upgrade gbrain, then run gbrain sources retry-held <source>, and report it with the gbrain version if it stays held.' },- { code: 'page_body_rows_unreadable', class: 'page', safe_actions: ['retry'], needs_human: false, escalate: 'the page stays unreadable across syncs (a grant or row-level security policy hides its segment rows)',+ { code: 'freeze_page_body_rows_unreadable', class: 'page', safe_actions: ['retry'], needs_human: false, escalate: 'the page stays unreadable across syncs (a grant or row-level security policy hides its segment rows)',human_reason: 'Give the role that reads the brain the same access to page_body_manifest and page_segment_texts it has to pages, then run gbrain sources retry-held <source>.' },{ code: 'page_write_failed', class: 'page', safe_actions: ['upgrade'], needs_human: true, escalate: 'always: the writer cannot place the failure',human_reason: 'The write of this file keeps failing with an error gbrain cannot classify (an owner exception or an unplaced refusal); read its receipt (gbrain write-request <request_id>), report it with the gbrain version or fix the file when the error names its content, then run gbrain sources retry-held <source>.' },diff --git a/src/core/persistence/sync-status.ts b/src/core/persistence/sync-status.tsindex a24befaa27..14d0d40e7a 100644--- a/src/core/persistence/sync-status.ts+++ b/src/core/persistence/sync-status.ts@@ -310,7 +310,7 @@ export function holdVerdict(record: GitHoldRecord, auto: FenceAutoRepair | undefif (record.code === 'page_identity_changed') return classifySyncFault({ code: record.code, detail: 'page_identity_decision', ...escalation });if (record.code === 'file_drift' && fileDriftSide(record.meta) === 'unknown') return classifySyncFault({ code: record.code, detail: 'file_drift_unknown', ...escalation });const bodyFault = record.code === 'page_write_failed' ? record.meta.write_failure?.code : undefined;- if (bodyFault && PAGE_BODY_FAULT_CODES.has(bodyFault)) return classifySyncFault({ code: record.code, detail: bodyFault, ...escalation });+ if (bodyFault && PAGE_BODY_FAULT_CODES.has(bodyFault)) return classifySyncFault({ code: record.code, detail: `freeze_${bodyFault}`, ...escalation });const disposition = contentHoldDisposition(record, auto);if (disposition.action !== 'listed' || disposition.state === 'owner') return classifySyncFault({ code: record.code, ...escalation, ...content });const verdict = classifySyncFault({ code: record.code, ...escalation, detail: disposition.reason, ...content });diff --git a/src/core/write-through.ts b/src/core/write-through.tsindex 0f6aa8f38f..1203cd0c42 100644--- a/src/core/write-through.ts+++ b/src/core/write-through.ts@@ -103,7 +103,7 @@ export interface WriteThroughResult {* - over_push_scan_cap: the rendered file is over the pre-push secret-scan* cap (PUSH_SCAN_MAX_FILE_BYTES), so committing it would block every push.*/- skipped?: 'disabled_by_config' | 'url_clone' | 'no_repo_configured' | 'repo_not_found' | 'source_repo_belongs_to_other_source' | 'page_not_found_after_write' | 'path_escapes_source_root' | 'case_insensitive_collision' | 'file_changed' | 'over_push_scan_cap';+ skipped?: 'disabled_by_config' | 'url_clone' | 'no_repo_configured' | 'repo_not_found' | 'source_repo_belongs_to_other_source' | 'page_not_found_after_write' | 'path_escapes_source_root' | 'case_insensitive_collision' | 'file_changed' | 'over_push_scan_cap' | 'segmented_page';/** Caller-visible advisory when a permitted DB-only outcome is still risky. */warning?: string;/** Set when the render/write/rename itself threw (EACCES, ENOTDIR, disk full). */@@ -114,6 +114,8 @@ export interface WritePageThroughOpts {sourceId?: string;/** Merged over the page's own frontmatter at render time (e.g. provenance). */frontmatterOverrides?: Record<string, unknown>;+ /** Skip a page stored in segments (`segmented_page`): the caller compares the written file as a string (derived writes). */+ inlineOnly?: boolean;logger?: WriteThroughLogger;/*** The file bytes the caller read before writing the database row (null:@@ -469,6 +471,7 @@ export async function writePageThrough(}const segmented = isSegmentedPage(writtenPage);+ if (segmented && opts.inlineOnly) return { written: false, skipped: 'segmented_page' };if (segmented && opts.frontmatterOverrides) {return { written: false, error: `page ${slug} is stored in segments, and its file is streamed as gbrain export writes it, without frontmatter overrides` };}diff --git a/test/segmented-fault-classes-gbra287.test.ts b/test/segmented-fault-classes-gbra287.test.tsnew file mode 100644index 0000000000..b7f9cbe4d0--- /dev/null+++ b/test/segmented-fault-classes-gbra287.test.ts@@ -0,0 +1,32 @@+/**+ * GBRA-287: how the two stored-page-body fault codes are classified.+ *+ * 1. Protects: a managed-sync freeze hold naming `page_body_segmented` reads upgrade / a person, and one naming+ * `page_body_rows_unreadable` reads retry / no person (the `freeze_<code>` rows), while a write receipt carrying+ * either bare code keeps the class it had before (a caller refusal, a gbrain defect): the hold rows never leak into+ * receipt diagnosis (`gbrain write-request`, writer failures, doctor).+ * 2. Fails when: the hold rows are keyed by the bare codes (receipts turn into sync faults), or holdVerdict stops+ * reading `meta.write_failure.code` (the holds read as an unplaced page_write_failed).+ * 3. Pure.+ */+import { describe, expect, test } from 'bun:test';+import { classifyTerminal } from '../src/core/persistence/terminal-classify.ts';+import { holdVerdict } from '../src/core/persistence/sync-status.ts';++const receipt = (error_code: string) => classifyTerminal({ request_id: 'r', source_id: 'default', slug: 'notes/a', operation: 'put_page', state: 'failed',+ error_code, error_message: 'x', recovery: false } as never);+const freezeHold = (code: string) => ({ source_id: 'default', path: 'notes/a.md', slug: 'notes/a', code: 'page_write_failed', held_at: new Date().toISOString(),+ meta: { attempts: 1, write_failure: { code, origin: 'freeze', error_class: code, errno: null, request_id: null, attempts: 1, gbrain_version: 'x' } } }) as never;++describe('GBRA-287: page-body fault classes', () => {+ test('a write receipt with a bare page-body code keeps its class', () => {+ expect(receipt('page_body_segmented')).toMatchObject({ category: 'caller_refusal', needs_human: false, public_category: 'content_refused' });+ expect(receipt('page_body_rows_unreadable')).toMatchObject({ category: 'gbrain_defect', needs_human: true });+ });++ test('a freeze hold is classified by the page-body code it names', () => {+ expect(holdVerdict(freezeHold('page_body_segmented'), undefined)).toMatchObject({ safe_actions: ['upgrade'], needs_human: true });+ expect(holdVerdict(freezeHold('page_body_rows_unreadable'), undefined)).toMatchObject({ safe_actions: ['retry'], needs_human: false });+ expect(holdVerdict(freezeHold('storage_error'), undefined).human_reason).toContain('gbrain write-request');+ });+});diff --git a/test/sync-reconcile-db-only-segmented.test.ts b/test/sync-reconcile-db-only-segmented.test.tsindex 0a5bb10d79..8151a19658 100644--- a/test/sync-reconcile-db-only-segmented.test.ts+++ b/test/sync-reconcile-db-only-segmented.test.ts@@ -154,6 +154,16 @@ describe('GBRA-287: full-sync re-export of a DB-only page stored in segments', (expect(stagingLeft(repoPath)).toEqual([]);}, 180_000);+ test('write-through of a segmented page with frontmatter overrides returns an error and writes nothing', async () => {+ expect(['first_sync', 'synced']).toContain((await fullSync()).status);+ await dbOnlySegmented('memories/big', 2 * 1024 * 1024);+ const result = await writePageThrough(engine, 'memories/big', { sourceId: 'default', frontmatterOverrides: { provenance: 'example' } });+ expect(result).toMatchObject({ written: false });+ expect(result.error).toContain('stored in segments');+ expect(existsSync(join(repoPath, 'memories/big.md'))).toBe(false);+ expect(stagingLeft(repoPath)).toEqual([]);+ }, 180_000);+test('a segmented page whose file would pass the pre-push scan cap is skipped before its source_path is bound', async () => {expect(['first_sync', 'synced']).toContain((await fullSync()).status);await dbOnlySegmented('memories/huger', PUSH_SCAN_MAX_FILE_BYTES + 256 * 1024);