Skip to content

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.md
index 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-03
diff --git a/src/core/cycle/derived-write-through.ts b/src/core/cycle/derived-write-through.ts
index 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: str
if (!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.ts
index 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, PublicCategor
export 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.ts
index 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.ts
index 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 | undef
if (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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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);