Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Keep a caller's explicit type over a retype stamp, and treat the retired grandfather stamp as derived (GST-2568)
garrytan2d0028124485
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 11d2a838ab..8fefa036b1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,8 +16,9 @@ identifiers and attribution are available in the pre-removal Git revision**A page that differs from its file only by what gbrain itself wrote is no longer held as file drift.** A schema-pack retype changes a page's type in the database and keeps the old type as `legacy_type` (plus an optional `subtype`) without touching the file. A file that still named the old type then read as a different page, and a later mass rewrite of the files, or a page imported before import records existed, turned that into a `file_drift` hold that needed a person. Sync now reads such a file with the stored retype stamp kept, so nothing differs. A real database edit (a label, a body change) is still held.-- **Existing holds of that kind release by themselves.** The next sync after upgrading re-screens each held `file_drift` page that is not a deletion once, releases the ones that now agree with no page write and no commit, and says how many (`Released N held file(s) that no longer need a decision.`, JSON `holds_released`). On a seeded source of 3,000 holds, 99% of them normalisation-only, one sync released 2,970 and left the 30 real differences held, in about 27 s on PGLite and 61 s on Postgres; the next sync took about 0.1 s.-- **A later commit over a page that only gained derived keys imports.** When the page side changed only by keys gbrain derives (a stored reserved `type` key or a `validate: false` stamp) and someone commits a body edit to the file, sync imports the file instead of holding it.+- **Existing holds of that kind release by themselves.** The next sync after upgrading re-screens each held `file_drift` page that is not a deletion once, releases the ones that now agree with no commit and no change to any page's body, type or stamps (a retype stamp releases with no page write at all; a stale stored copy of the `type` key is normalised away), and says how many (`Released N held file(s) that no longer need a decision.`, JSON `holds_released`). On a seeded source of 3,000 holds, 99% of them normalisation-only, one sync released 2,970 and left the 30 real differences held, in about 27 s on PGLite and 61 s on Postgres; the next sync took about 0.1 s.+- **A later commit over a page that only gained derived keys imports.** When the page side changed only by keys gbrain derives (a stored copy of the reserved `type` key, stated or inferred from the path, or the retired grandfather's database-only `validate: false`) and someone commits a body edit to the file, sync imports the file instead of holding it, and the stamp stays.+- **A write that names the type a retype replaced still takes it.** Only a file reading keeps a retype's stamp; a `put_page` with an explicit `type:` is stored as written.- **A page whose file is gone under a `gbrain.yml` `db_only` folder is no drift.** An existing deleted-side hold there now releases.- **`gbrain repair file-drift` compares without a winner.** Any selection without `--prefer` lists, per page, what differs, which side is newer (the file's last commit against the page's `updated_at`) and what a repair would do, and writes nothing. A `--prefer` preview with no side names that comparison as its fix.- **`--prefer file` never drops a newer page in bulk.** A `--held`, `--all-drifted` or `--request` preview lists a page edited after its file's last commit as `kept_newer_page` and leaves it held; naming the page with `--slug` still resolves it, with a warning naming the edit it drops. A page whose file is gone is never deleted by a comparison (GST-2568).diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex aa2c82d3db..34acdeaba1 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -3417,8 +3417,9 @@ as sync imports it (`README.md` for slug `readme`); the apply records thatpath. A sync re-screens a held page that changed since it was held even whenGit did not move. A gbrain that compares file drift differently (GST-2568) hasthe next sync re-screen every held `file_drift` page that is not a deletion-once: a page that now agrees with its file is released with no write and no-commit, and the sync prints `Released N held file(s) that no longer need a+once: a page that now agrees with its file is released with no commit and no+change to its body, type or stamps (a stale stored copy of the `type` key is+normalised away), and the sync prints `Released N held file(s) that no longer need adecision.` (JSON `holds_released`). A page a read-only mirror stored database-only (`mirror_read_only`)is compared with the file at its slug path once its source is writable again;the apply records that path and clears the stamp.diff --git a/src/core/import-file.ts b/src/core/import-file.tsindex 26508e73a7..2c44b2984b 100644--- a/src/core/import-file.ts+++ b/src/core/import-file.ts@@ -488,7 +488,7 @@ export async function importFromContent(// put (get_page → edit body → put_page without `type:`) silently regressed// a curated type to the path-inferred default ('concept' for bare slugs).// Explicit frontmatter type stays an override; new pages still infer. The stored subtype and grandfather stamp are kept too.- if (existing) alignWithStored(parsed, existing, false);+ if (existing) alignWithStored(parsed, existing, false, opts.sourcePath !== undefined);else resolveParsedSubtype(parsed, existing);// Alias-footgun visibility: an explicit frontmatter `type:` that is an// ALIAS of a canonical pack type (or entirely undeclared) is storeddiff --git a/src/core/persistence/align-stored.ts b/src/core/persistence/align-stored.tsindex 9117c8cd2f..f3cb1c8434 100644--- a/src/core/persistence/align-stored.ts+++ b/src/core/persistence/align-stored.ts@@ -5,10 +5,12 @@ import { resolveParsedSubtype, type ParsedMarkdown } from '../markdown.ts';* `type:` (or whose type was only inferred from its path, #6605) keeps the stored type, and the subtype is resolved* against that type, so the stored subtype is kept too, and so is the grandfather stamp (#6429). Import over an existing* page (import-file.ts), the write guard (page-prepare.ts) and reconcile (reconcile-state.ts, reconcile-prepare.ts) share it.- * A file that still names the type a schema-pack retype replaced keeps the retyped page's type and stamp (`keepRetypeStamp`).+ * A file that still names the type a schema-pack retype replaced keeps the retyped page's type and stamp (`keepRetypeStamp`);+ * content a caller writes with no file behind it (import-file.ts without `sourcePath`: `put_page`) passes `retypeStamp` false and is+ * read as written, so an explicit type there still wins.*/-export function alignWithStored(parsed: ParsedMarkdown, stored: { type: string; frontmatter?: Record<string, unknown> | null }, inferred: boolean): void {- if (!keepRetypeStamp(parsed, stored) && (inferred || !parsed.typeExplicit)) parsed.type = stored.type as ParsedMarkdown['type'];+export function alignWithStored(parsed: ParsedMarkdown, stored: { type: string; frontmatter?: Record<string, unknown> | null }, inferred: boolean, retypeStamp = true): void {+ if (!(retypeStamp && keepRetypeStamp(parsed, stored)) && (inferred || !parsed.typeExplicit)) parsed.type = stored.type as ParsedMarkdown['type'];resolveParsedSubtype(parsed, stored);keepGrandfatherStamp(parsed.frontmatter, stored);}diff --git a/src/core/persistence/sync-run.ts b/src/core/persistence/sync-run.tsindex ea7490a03a..863ff28eac 100644--- a/src/core/persistence/sync-run.ts+++ b/src/core/persistence/sync-run.ts@@ -1309,7 +1309,7 @@ async function performManagedPass(engine: BrainEngine, opts: SyncOpts, slice?: {const fences = fencesNormalizedReport(state.sourceId, cursor?.counts.fences, state.remote === true);// #7199: a pass that synced but held files a person must decide does not read as plain synced.const humanHeld = report.held_needs_human && !synced.reason && ['synced', 'first_sync', 'up_to_date'].includes(synced.status);- const released = await releasedHoldCount(engine, state.sourceId, holdsBefore);+ const released = await releasedHoldCount(engine, state.sourceId, holdsBefore).catch(() => 0);return { ...synced, ...report, ...(released ? { holds_released: released } : {}), ...(humanHeld ? { reason: 'held_needs_human' as const } : {}), ...(!state.remote && cursor?.convertedFromFailed?.length ? { converted_from_failed: cursor.convertedFromFailed } : {}),...(recovered ? { recovered_frontmatter: recovered } : {}), ...(fences ? { fences_normalized: fences } : {}) };} catch {diff --git a/src/core/repair/file-drift-compare.ts b/src/core/repair/file-drift-compare.tsindex af16150383..745198961b 100644--- a/src/core/repair/file-drift-compare.ts+++ b/src/core/repair/file-drift-compare.ts@@ -10,7 +10,7 @@* here either; both are `needs_human` with the reason.*/import { execFileSync } from '../spawn.ts';-import { gitChildEnv } from '../git-env.ts';+import { GIT_READ_ENV, gitChildEnv } from '../git-env.ts';import { relative, sep } from 'node:path';import type { BrainEngine } from '../engine.ts';import type { ParsedPage } from '../import-file.ts';@@ -43,7 +43,7 @@ export function driftDifference(file: ParsedPage, database: ParsedPage): { diffe/** The file's last commit time at HEAD and whether its working-tree bytes differ from HEAD; a Git failure reads as no evidence. */export function fileCommitEvidence(root: string, path: string): { committed_at: string | null; uncommitted: boolean } {- const git = (args: string[]) => execFileSync('git', ['-C', root, ...args], { env: gitChildEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();+ const git = (args: string[]) => execFileSync('git', ['-C', root, ...args], { env: gitChildEnv(GIT_READ_ENV), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();try {return { committed_at: git(['log', '-1', '--format=%cI', 'HEAD', '--', path]) || null, uncommitted: git(['status', '--porcelain', '--', path]) !== '' };} catch { return { committed_at: null, uncommitted: false }; }@@ -75,8 +75,8 @@ export async function readDriftEvidence(engine: BrainEngine, sourceId: string, sexport function newerPageParagraph(sourceId: string, slug: string, evidence: DriftEvidence): string {const what = evidence.differs === 'both' ? 'body and frontmatter' : evidence.differs === 'body' ? 'body' : `frontmatter (${evidence.keys.join(', ')})`;return `page ${slug} changed after its file was last committed (page updated ${evidence.page_updated_at}, ${evidence.path} committed ${evidence.file_committed_at}) and its ${what} differs, `- + `so letting the file win would drop that database edit; it stays held for a person. Keep the page with gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer database `- + `(rewrites the file from the page), or carry the edit into the file, commit it and run gbrain sync --source ${sourceId}.`;+ + `so letting the file win may drop a database edit; it stays held for a person. updated_at also moves on gbrain's own writes (a retype), so read both sides first. `+ + `To keep the file, run gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer file; to keep the page, run it with --prefer database (rewrites the file from the page) or carry the edit into the file, commit it and run gbrain sync --source ${sourceId}.`;}/** One selected page, compared: a held page by its hold, any other by its slug. Never writes. */diff --git a/test/file-drift-normalisation-gst2568.test.ts b/test/file-drift-normalisation-gst2568.test.tsindex aab6c7eb5b..3afce25776 100644--- a/test/file-drift-normalisation-gst2568.test.ts+++ b/test/file-drift-normalisation-gst2568.test.ts@@ -13,17 +13,23 @@* `holds_released`; a real difference is screened again and stays held;* - a later deliberate commit over a page that changed only by derived keys (a retype's stamp, a stored reserved key, the* grandfather `validate: false`) imports; a page whose body also changed in the database stays held;+ * - the retired grandfather's database-only `validate: false` and a stored `type` key (stated or path-inferred) are derived: an+ * older hold over them releases and a later commit imports, while a database label still holds;* - a live page whose file is gone under a gbrain.yml `db_only` folder or a `sync.exclude` path is no drift: no hold, an* existing hold releases, and the page stays;* - item 3: `repair file-drift --held` without `--prefer` compares each hold (what differs, which side is newer, what a* repair would do) and writes nothing; an apply without `--prefer` refuses with a `fix` naming that comparison;* - item 4: `--prefer file` never drops a page edited after its file's last commit in bulk (`kept_newer_page`, the hold* stays), names the drop in a warning when one `--slug` asks for it, and the comparison never proposes deleting a page- * whose file is gone.+ * whose file is gone;+ * - a caller's write (put_page, import) that names the type a retype replaced still takes that type: only a file reading keeps+ * the retype's stamp.* PGLite always; Postgres too when DATABASE_URL is set. Holds exist only where sync imports a Git checkout, so there is no* repo-less arm.*/-import { expect, test } from 'bun:test';+import { afterAll, beforeAll, expect, test } from 'bun:test';+import { importFromContent } from '../src/core/import-file.ts';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';import { execFileSync } from 'node:child_process';import { mkdirSync, rmSync, writeFileSync } from 'node:fs';import { join } from 'node:path';@@ -46,6 +52,7 @@ const OPTS = { sourceId: 'default', noPull: true, noEmbed: true, noExtract: trueconst logger = { info() {}, warn() {}, error() {} };const commitAll = (root: string, message: string) => { git(root, 'add', '-A'); git(root, 'commit', '-qm', message); };const doc = (type: string, title: string, body: string, extra = '') => `---\ntype: ${type}\ntitle: ${title}\n${extra}---\n\n${body}\n`;+const untyped = (title: string, body: string) => `---\ntitle: ${title}\n---\n\n${body}\n`;const coordinated = (engine: BrainEngine, sql: string, params: unknown[] = []) =>engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () => tx.executeRaw(sql, params), TEST_WRITE_ATTRIBUTION));const holds = async (engine: BrainEngine) => (await engine.executeRaw<{ r: { path: string; code: string; meta: { side?: string; drift_version?: number } } }>(@@ -163,6 +170,29 @@ for (const backend of testBackends()) {for (const slug of ['private/kept', 'excluded/kept']) expect((await row(engine, slug)).deleted).toBe(false);}, { databaseUrl, setup: setupWith({ 'private/kept': doc('concept', 'private/kept', 'A private body.'), 'excluded/kept': doc('concept', 'excluded/kept', 'An excluded body.') }) }), 180_000);+ test(`GST-2568 [${backend}]: a retired grandfather stamp and a stored type key are derived, not drift: an old hold releases, a later commit imports, a label still holds`, () => managedBrain(async ({ engine, root }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ // The retired v0.13.1 grandfather wrote `validate: false` to the database only, with no version row; older imports also kept+ // the page's type (stated, or inferred from the path for a file with no `type:`) as a frontmatter key the file never had.+ await coordinated(engine, "UPDATE pages SET frontmatter = frontmatter || jsonb_build_object('validate', false, 'type', type) WHERE source_id='default'");+ await coordinated(engine, "UPDATE pages SET frontmatter = frontmatter || '{\"label\": \"x\"}'::jsonb WHERE source_id='default' AND slug='notes/labelled'");+ await legacy(engine);+ await seedHold(engine, 'notes/stamped', { sides: 'unknown', side: 'unknown', drift_version: 2 });+ files(root, { 'notes/inferred': untyped('notes/inferred', 'An edited body.'), 'notes/labelled': untyped('notes/labelled', 'An edited body.') });+ commitAll(root, 'edit two bodies');+ const head = git(root, 'rev-parse', 'HEAD');+ const result = await performManagedSync(engine, OPTS);+ expect([await holds(engine), result.holds_released]).toEqual([['notes/labelled.md file_drift unknown'], 1]);+ // The release may normalise the stored copy of the reserved key away; the body, type and stamp stay.+ const stamped = await row(engine, 'notes/stamped');+ expect([stamped.type, stamped.body, stamped.frontmatter.validate]).toEqual(['concept', 'The first body.', false]);+ const inferred = await row(engine, 'notes/inferred');+ expect([inferred.body, inferred.frontmatter.validate]).toEqual(['An edited body.', false]);+ expect((await row(engine, 'notes/labelled')).body).toBe('The first body.');+ expect([git(root, 'rev-parse', 'HEAD'), git(root, 'status', '--porcelain')]).toEqual([head, '']);+ }, { databaseUrl, setup: setupWith({ 'notes/stamped': doc('concept', 'notes/stamped', 'The first body.'),+ 'notes/inferred': untyped('notes/inferred', 'The first body.'), 'notes/labelled': untyped('notes/labelled', 'The first body.') }) }), 180_000);+/** Four held pages: same (a retype's stamp only), newer-file, newer-page (each differs in body), gone (its file left Git). */async function heldPages(engine: BrainEngine, root: string): Promise<void> {expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');@@ -213,3 +243,18 @@ for (const backend of testBackends()) {expect(single.warnings?.join(' ')).toContain('drops a database edit newer than its file');}, { databaseUrl, setup: heldSetup }), 240_000);}++let engine: PGLiteEngine;+beforeAll(async () => {+ engine = new PGLiteEngine();+ await engine.connect({});+ await engine.initSchema();+});+afterAll(async () => { await engine.disconnect(); });++test('GST-2568: a caller that writes the type a retype replaced takes it; the retype stamp is kept only for a file reading', async () => {+ await importFromContent(engine, 'notes/caller', doc('civic', 'notes/caller', 'A body.'), { noEmbed: true });+ await engine.executeRaw("UPDATE pages SET type='note', frontmatter = frontmatter || '{\"legacy_type\": \"civic\"}'::jsonb WHERE slug='notes/caller'");+ await importFromContent(engine, 'notes/caller', doc('civic', 'notes/caller', 'A body, edited.'), { noEmbed: true });+ expect((await row(engine, 'notes/caller')).type).toBe('civic');+}, 60_000);