Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
GBRA-217 A2: docs (reasons from Git, purge and reasons), key files, Postgres arm row, tools-json golden
garrytan7f0dad5fc2da
diff --git a/docs/architecture/key-files/page-history.md b/docs/architecture/key-files/page-history.mdindex 6c7dcb200d..207b1b74eb 100644--- a/docs/architecture/key-files/page-history.md+++ b/docs/architecture/key-files/page-history.md@@ -5,3 +5,6 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGELPage-write reasons: admission, the snapshot column, the Git trailer and the remote read projection.- `src/core/persistence/change-reason.ts` — GBRA-217 page-write reasons ([page history](../../guides/page-history.md#reasons)). `admitChangeReason` canonicalises a `reason` (one line, at most 500 code points) and refuses `change_reason_rejected` (`reason_too_long`, `reason_contains_secret` via `scanTextSpans`) before admission, so no journal row ever holds a refused reason; `page-mutations.ts` runs it before `callerIntent`, so the canonical reason joins replay identity, and `page-batch.ts` runs it per item (all or nothing). `withChangeReason` wraps a page preparer in `service.ts`: its apply stamps `page_versions.change_reason` on the snapshots that transaction created for the page, and, for a world-visible page whose file is published, appends `gbrain-reason: <path>: <text>` to `prepared.file.commit` (a `GitCommitNote` with `trailers[]`), which both the door (`commitThroughDoor`) and the effect commit (`commitMessage`, one trailer line each, `commitMessageArgs` switching to `-F` over 8 KiB) read after apply. The outcome's `reason_recorded.git` is `committed` (strict), `queued`, `private`, `not_file_backed`, `no_repository` (repo-less) or `none`; `settledReasonRecorded` turns `queued` into `superseded` with a `reason_not_committed` notice on the receipt when the Git effect was superseded. Read side: `replacedBecauseSql` in `engine-sql/pages.ts` (remote readers see a reason only when the successor snapshot is world-visible and not `successor_pruned`, which the prunes in `page-state/versions.ts` set). Tests: `test/page-change-reason-gbra217.test.ts`, `test/page-change-reason-git-gbra217.test.ts`, `test/page-change-reason-mcp-gbra217.test.ts`.+- `src/core/reason-trailers.ts` — GBRA-217 reasons read back from Git ([reasons from Git](../../guides/page-history.md#reasons-from-git)). `readReasonTrailers` streams one `git log` through `hardenedGitStream` with `REASON_LOG_OPTIONS` (`hardened-git.ts`: `-z --first-parent --diff-merges=first-parent --root --name-only --no-renames` and a `%x00%H%x00%(trailers:key=gbrain-reason,valueonly,unfold)` format; no pathspec, no grep), parses records as they stream and stops at a commit cap. `scanSyncReasons` maps each repository path to its newest first-parent commit's trailer (canonicalised by `canonicalChangeReason`, over-long ones counted as malformed, secrets via `scanTextSpans` reported by commit and path, `reason_purge_tombstones` pairs skipped) and counts touches per path; `importHistoryFor` turns that into the `VersionHistory` an import passes to `createVersion` (more than one commit, or a failed or capped scan, sets `historyGap`). `gitTopLevel` returns null outside a repository, so a repo-less or plain-folder source runs no scan. `reasonScanNotices` builds `reason_scan_failed` / `reason_scan_capped` / `reason_trailer_secret`. `cachedSyncReasonScan` shares one scan per (source, root, range) for managed preparations; purge clears it. `scanTrailersCarrying` is purge's read (cap 200,000, or the user's `--reason-scan-limit`). Caps 10,000 (sync) and 200,000 (purge), 120 s timeout. Seams: `__setReasonScanCapsForTests`, `__setReasonGitStreamForTests`. Test: `test/reason-trailers-gbra217.test.ts` (both engines).+- `src/commands/sync/reasons.ts` + `src/core/persistence/sync-reasons.ts` — the sync wiring. Classic: `incremental.ts` scans `last_commit..pin` once per pass when it imports or renames files (not for a company brain), `full.ts` scans the whole history only when the source already has pages, and `imports.ts` / `renames.ts` / `runImport` pass each file's `history` to `importFile`; `withReasonNotices` puts the notices and `reason_trailers_malformed` on the `SyncResult` (`sync/run.ts` renders them). Managed: `sync-prepare.ts` calls `managedFileHistory` (claim step `reason_scan`) only when the page exists, and `performManagedPass` adds the pass's notices through `withManagedReasonNotices`. Content never waits on the scan.+- `src/core/facts/purge-reasons.ts` — A7 ([purge and reasons](../../guides/page-history.md#purge-and-reasons)). `scanPurgeTrailers` runs before the purge transaction (no checkout: nothing to scan; a failed read refuses `reason_purge_scan_failed`, `fix.next = wait`; over the cap `reason_purge_scan_capped`, ask_user with `--reason-scan-limit`). Inside the transaction `redactGitEffectReasons` rewrites `commit_line` / `commit_trailers` / legacy `commit_trailer` on queued, failed and committed git effects (a running one refuses `purge_blocked_pending_recovery`) and `recordReasonTombstones` rechecks `head..HEAD` and inserts text-free `reason_purge_tombstones` rows. `purge.ts` `redactPageVersions` sets a quoting `change_reason` to `[purged]`; `purge-verify.ts` checks it and reports pushed commits as the `git_commit_messages` residual.diff --git a/docs/guides/memory-boundaries.md b/docs/guides/memory-boundaries.mdindex cfe6e81c81..1e9699c771 100644--- a/docs/guides/memory-boundaries.md+++ b/docs/guides/memory-boundaries.md@@ -409,7 +409,9 @@ and [isolated local backup guide](in-agent-setup.md#6-back-up-the-complete-localA write's [reason](page-history.md#reasons) is stored with the page's historyand, when the page's file reaches Git, in the commit message. A purge removesthe database copies it covers, but a commit already pushed keeps its message-text, just as it keeps the file's earlier contents.+text, just as it keeps the file's earlier contents. Purge records those commits+so no later sync stores the reason again ([purge and+reasons](page-history.md#purge-and-reasons)).`forget` **expires**: the fact stops being recalled, cannot be saved again inthe same source and visibility, and its row is struck in the page's Markdown.diff --git a/docs/guides/page-history.md b/docs/guides/page-history.mdindex a241738575..2cde438559 100644--- a/docs/guides/page-history.md+++ b/docs/guides/page-history.md@@ -92,8 +92,9 @@ you make yourself can give a reason the same way:git commit --trailer "gbrain-reason: policies/refunds.md: Client asked for the 30-day window."```-A pushed commit message cannot be changed, so treat a reason like any other-text you push. There is no operation to add a reason to a past write.+A sync reads these trailers back into page history ([reasons from+Git](#reasons-from-git)). A pushed commit message cannot be changed, so treat a+reason like any other text you push. There is no operation to add a reason to a past write.### Repo-less brains@@ -114,6 +115,99 @@ the replacing version was later pruned (large pages keep a few versions), itsvisibility can no longer be checked and the reason is withheld from remotecallers. Remote reasons go through the same text sanitizer as version bodies.+## Reasons from Git++When `gbrain sync` imports a changed file from a Git checkout, it reads the+`gbrain-reason` trailers of the commits it is importing and stores the+file's reason on the version that import archives. A commit you make yourself+with `git commit --trailer "gbrain-reason: <path>: <text>"` therefore shows up+in `get_versions` as `replaced_because`, the same as a reason given to+`put_page`.++How a sync picks the reason for a file:++- It reads the commits between the last synced commit and the new one along the+ first-parent line, which is the history the checked-out branch came from. A+ merge counts as changing every file it changed relative to its first parent.+- The newest of those commits that changed the file decides. Its trailer for+ that file is the reason. If it has none, the version gets no reason, so an+ older reason is never shown against newer text.+- A merge that resolved a conflict decides with its own trailer, so put the+ trailer in the merge message. A commit on a merged side branch never decides,+ whether its edit was kept or discarded.+- The trailer names the file by its path in the repository (or under the+ source's folder when the source is a subfolder), then `: ` and the text. A+ trailer that names no file its commit changed is skipped and counted in the+ sync result's `reason_trailers_malformed`.+- A reason from Git gets the same cleanup and limits as a written reason. One+ longer than 500 characters is skipped and counted the same way.+- A file's first import creates its page and archives nothing, so it stores no+ reason, as with a page's first write.++When one sync imports more than one commit for a file, the versions in between+were never stored. The sync marks the page as having a gap in its history, so+readers of old versions know some are missing.++A trailer already in Git that looks like a credential is not stored. The sync+prints the `reason_trailer_secret` notice, which names the commit and the file,+never the value. Rotate that credential: Git history keeps the commit message.++If reading the trailers fails (a Git error, or more than two minutes), the sync+prints `reason_scan_failed`. If the range holds more than 10,000 commits, it+prints `reason_scan_capped` instead of reading them. Either way the content is+imported, because reasons never hold up content. Every version that sync+archives stores no reason, and each page it changed is marked with a history+gap. This release does not backfill reasons for that range: the sync still+moves its last synced commit forward, and a later sync does not read the range+again. The reasons are still in Git, and the notice's command lists them:++```bash+git log --first-parent --format='%H %(trailers:key=gbrain-reason,valueonly)' <range>+```++A commit and file that a purge has tombstoned (below) never gives a reason+again, not even on a full re-import.++A source with no Git checkout (a repo-less brain, or a folder imported with+`gbrain import`) reads no trailers, prints none of these notices and marks no+gap. Its reasons come only from the writes that carry them.++## Purge and reasons++`gbrain forget <id> --purge` ([expire versus purge](memory-boundaries.md#purge))+reaches every copy of a reason that quotes the claim:++- **Versions.** The reason is replaced with `[purged]` on every version that+ carries it, inline and segmented alike, and counted in+ `removed.page_versions`.+- **Queued and kept Git commits.** The source's Git effects whose commit message+ would quote the claim, whether queued, failed or kept after they ran, are+ redacted in the same transaction: the line becomes `[purged]` and the trailer+ that quotes it is dropped (`removed.persistence_effects`). If one is being+ written right now, the purge stops with `purge_blocked_pending_recovery`;+ retry once it finishes.+- **Commits already in the repository.** Purge never rewrites Git history, so a+ pushed commit keeps its message text, as it keeps the file's earlier+ contents. Before it deletes anything, purge reads the `gbrain-reason` trailers+ on the source's first-parent history up to `HEAD` (up to 200,000 commits) and+ records each commit and file whose reason quotes the claim. The record holds+ no text. No later sync, cold re-import or re-derive stores that reason again.+ The receipt counts these in `removed.reason_purge_tombstones` and lists the+ commits under the `git_commit_messages` residual.++Purge refuses before it changes anything when it cannot read that history:++- `reason_purge_scan_failed`: reading the trailers failed (a Git error or a+ timeout). Nothing was changed; wait, then run the same purge again.+- `reason_purge_scan_capped`: the history is longer than 200,000 commits. Your+ agent asks you to choose: purge now and check only the newest commits, with+ `--reason-scan-limit <n>` set to the number you pick, or stop. With a limit, a+ reason in an older commit is not tombstoned and a re-import could store it+ again; the receipt says so.++On a source with no Git checkout there is no history to read, so purge redacts+the database copies and never raises either refusal.+## Choosing how to record a changeA reason explains an edit to one document. Pick the shape that matches whatdiff --git a/test/fixtures/goldens/cli/tools-json.json b/test/fixtures/goldens/cli/tools-json.jsonindex 0f55a875dc..2ce2fe99be 100644--- a/test/fixtures/goldens/cli/tools-json.json+++ b/test/fixtures/goldens/cli/tools-json.json@@ -2,8 +2,8 @@"golden": {"exitCode": 0,"stderr": "",- "stdoutBytes": 264473,- "stdoutSha256": "f5647f0a0d45a36ed8685afa000792cef233379d012eeceec6fa2f9366d1b0ee",+ "stdoutBytes": 265594,+ "stdoutSha256": "8151ee27ee0fbd9cd271ced0d710c63172ec96af3d57fb4fe50e7f6398ae2843","toolNames": ["remember","entity",@@ -613,6 +613,7 @@"expected_revision": "string?","force": "boolean?","ingested_via": "string?",+ "reason": "string?","request_id": "string?","slug": "string","source_id": "string?",@@ -660,6 +661,10 @@"description": "Server-set remotely.","type": "string"},+ "reason": {+ "description": "Why this change, one line (max 500 chars); kept in page history.",+ "type": "string"+ },"request_id": {"description": "Reuse only to retry.","type": "string"@@ -1056,6 +1061,7 @@"parameters": {"edits": "array","expected_revision": "string",+ "reason": "string?","request_id": "string?","slug": "string","source_id": "string?",@@ -1090,6 +1096,10 @@"description": "From get_page include_content:true.","type": "string"},+ "reason": {+ "description": "Why this change, one line (max 500 chars); kept in page history.",+ "type": "string"+ },"request_id": {"description": "Reuse only to retry.","type": "string"@@ -1246,6 +1256,10 @@"description": "Revision read; omit to create.","type": "string"},+ "reason": {+ "description": "Why this change, one line (max 500 chars); kept in page history.",+ "type": "string"+ },"slug": {"description": "Page slug.","type": "string"@@ -2979,7 +2993,7 @@"scope": "read"},{- "description": "Page version history, newest snapshot first: metadata only (id, snapshot_at, title, type, tags, frontmatter) for the newest 20 versions by default. Pass include_body: true for each version's compiled_truth and timeline, and a larger limit (at most 100 over MCP) for older versions. Trusted local and admin callers also get written_by and archived_by (who wrote each snapshot and whose write archived it). revert_version takes the id field.",+ "description": "Page version history, newest snapshot first: metadata only (id, snapshot_at, title, type, tags, frontmatter) for the newest 20 versions by default. Pass include_body: true for each version's compiled_truth and timeline, and a larger limit (at most 100 over MCP) for older versions. Trusted local and admin callers also get written_by and archived_by (who wrote each snapshot and whose write archived it). replaced_because is the reason given for the write that replaced the snapshot (null when none was given). revert_version takes the id field.","idempotent": true,"local_only": false,"mutating": false,@@ -3036,6 +3050,7 @@"parameters": {"expected_revision": "string?","force": "boolean?",+ "reason": "string?","request_id": "string?","slug": "string","source_id": "string?",@@ -3052,6 +3067,10 @@"description": "Ignore the revision.","type": "boolean"},+ "reason": {+ "description": "Why this change, one line (max 500 chars); kept in page history.",+ "type": "string"+ },"request_id": {"description": "Reuse only to retry.","type": "string"@@ -6971,6 +6990,7 @@"id": "number?","match": "string?","reason": "string?",+ "reason_scan_limit": "number?","request_id": "string?","source_id": "string?","status": "boolean?",@@ -7011,6 +7031,10 @@"description": "Optional short reason stored in the text-free purge ledger.","type": "string"},+ "reason_scan_limit": {+ "description": "Check only the newest N commits for change reasons quoting the claim (after a reason_purge_scan_capped refusal, with the user's choice); older commits are not tombstoned.",+ "type": "number"+ },"request_id": {"description": "Reuse only to retry.","type": "string"diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txtindex 858931c537..7137cffef0 100644--- a/test/postgres-unit-arms.txt+++ b/test/postgres-unit-arms.txt@@ -413,6 +413,7 @@ test/purge-missing-cache-6911.test.tstest/purge-read-surfaces.test.tstest/purge-sync-tombstone-hold-7130.test.tstest/read-meta-diag.test.ts+test/reason-trailers-gbra217.test.tstest/recall-page-fill.test.tstest/receipt-compaction-newest-sync-gbra130.test.tstest/reconcile-clears-stalled-hold-7364.test.ts