Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: sources canonical in the multi-source guide; memory trace range and sync use; withhold stamp order in the writer inventory

garrytan9fd9e69c8ff5
diff --git a/docs/architecture/canonical-writers.tsv b/docs/architecture/canonical-writers.tsv
index ade2f870ca..700ea4c446 100644
--- a/docs/architecture/canonical-writers.tsv
+++ b/docs/architecture/canonical-writers.tsv
@@ -282,4 +282,4 @@ src/core/repair/url-clone-fences.ts 3 engine_guard GBRA-130 C-2: unmanaged brain
src/core/repair/visibility.ts 1 coordinator `gbrain repair visibility --apply` (GBRA-159) only tightens database-only active facts from world to private when their source page is private. On a managed brain the UPDATE runs only inside the managed_maintenance_tighten_fact_visibility publication (owner-checked by maintenancePreflight, page key locked); an unmanaged brain runs it in one maintenanceTransaction. The UPDATE rechecks visibility='world', row_num IS NULL and expired_at IS NULL under the row lock. Fenced rows are never updated here: they change in the page through a revision-bound put_page.
src/core/facts/file-body-guard.ts 1 engine_guard #6982 replaceStoredBody mirrors a checkout file body over the page row only inside its caller's maintenanceTransaction, after re-reading the row under a row lock and confirming it still equals the body the caller compared, and saves a page_versions row first; on a managed brain the canonical table trigger refuses the write outside the coordinator.
src/core/persistence/git-declared.ts 4 coordinator GBRA-95 G7a declareStrictPublication stamps or clears pages.database_only_reason (and drops source_path/source_uri for a page turning private, keeping the path in withheld_source_path, which the publication that writes the file again clears) inside the guarded publication transaction of publishMutation and publishGroup, after the door commit removed the file; it writes no content.
-src/core/persistence/git-conversion.ts 4 contract G8a sources canonical (trusted local CLI, managed brains, preview-bound apply): stamps database_only_reason=git_ignored on pages whose parked Git effect targets an ignored path, in one transaction that declares the persistence protocol and locks the effect row; #7618: stamps a withheld private page's class and moves source_path to withheld_source_path in the transaction after the door commit that removed its file (G7a's private transition, under the protocol declaration); and sets or clears sources.config.canonical last in the transaction that records the conversion; it writes no page content, and adoption files are committed through commitThroughDoor before any database change.
+src/core/persistence/git-conversion.ts 4 contract G8a sources canonical (trusted local CLI, managed brains, preview-bound apply): stamps database_only_reason=git_ignored on pages whose parked Git effect targets an ignored path, in one transaction that declares the persistence protocol and locks the effect row; #7618: stamps a withheld private page's class and moves source_path to withheld_source_path in its own transaction before the door commit that removes its file (G7a's private transition, under the protocol declaration; stamped first, so no sync reads the removal as a deletion); and sets or clears sources.config.canonical last in the transaction that records the conversion; it writes no page content, and adoption files are committed through commitThroughDoor before any database change.
diff --git a/docs/designs/GIT_CANONICAL_MEMORY.md b/docs/designs/GIT_CANONICAL_MEMORY.md
index 737c40911c..febfe91f5b 100644
--- a/docs/designs/GIT_CANONICAL_MEMORY.md
+++ b/docs/designs/GIT_CANONICAL_MEMORY.md
@@ -90,7 +90,7 @@ G8a ships it as `gbrain sources canonical <source-id> --to git|mixed [--dry-run
| parked effects | Retried once, or, for targets Git ignores, the page is stamped `git_ignored` (declared) in the same transaction that marks each parked target `declared: git_ignored`; the target stays as a record and the next preview no longer lists it. |
| discard | Refused: `git_conversion_blocked` names each category (both sides moved, a both-sides drift hold, an unknown-side drift hold whose row differs from the committed file, a database edit Git deleted, an uncommitted working-tree edit that differs from HEAD and the export, an ignored target, a target whose ignore status Git cannot read (`ignore_status_unknown`: beyond a symlink, outside the checkout, a failed check; only that path is refused), unparseable, unsafe path, segmented page, export mismatch, or a row a strict pass would overwrite unplanned). There is no override. |
-`--apply --expect <hash>` re-plans and refuses `preview_changed` on any difference, adopts group by group (a crash leaves the source mixed and the rerun preview lists only what is left), withholds group by group, settles the parked effects, rechecks what a strict pass would overwrite, clears the holds only after that recheck passes, runs the full strict-equivalent pass, then sets `canonical: git` in the transaction that records the conversion. Writes can land between that pass and the flag, so it runs one genuine strict pass and previews again: the conversion is complete only when nothing is left; otherwise it reports `git_conversion_incomplete` with what remains and the source stays strict, because Git wins. Where durability applies the apply pushes its door commits itself, after the groups and once at the end; a push that does not land leaves them local, the receipt says so, and the next page write's push-only effect sends them. The apply prints a progress line per phase and every 10 seconds on stderr, and SIGTERM, SIGINT or SIGHUP prints a partial report (phase, groups committed, items scanned, canonical state); `GBRAIN_MEMORY_TRACE` adds a memory trace. `--to mixed` removes the flag and changes nothing else; Git keeps every door commit.
+`--apply --expect <hash>` re-plans and refuses `preview_changed` on any difference, adopts group by group (a crash leaves the source mixed and the rerun preview lists only what is left), withholds group by group, settles the parked effects, rechecks what a strict pass would overwrite, clears the holds only after that recheck passes, runs the full strict-equivalent pass, then sets `canonical: git` in the transaction that records the conversion. Writes can land between that pass and the flag, so it runs one genuine strict pass and previews again: the conversion is complete only when nothing is left; otherwise it reports `git_conversion_incomplete` with what remains and the source stays strict, because Git wins. Where durability applies the apply pushes its door commits itself, after the groups and once at the end; a push that does not land leaves them local, the receipt says so, and the next page write's push-only effect sends them. The apply prints a progress line per phase and every 10 seconds on stderr, and SIGTERM, SIGINT or SIGHUP prints a partial report (phase, groups committed, items scanned, canonical state); `GBRAIN_MEMORY_TRACE=<seconds>` (1 to 3600) adds a memory line on stderr every that many seconds, and `gbrain sync` honors it too. `--to mixed` removes the flag and changes nothing else; Git keeps every door commit.
## The git-gap census
diff --git a/docs/guides/multi-source-brains.md b/docs/guides/multi-source-brains.md
index 9d77b0fc88..80165ba23e 100644
--- a/docs/guides/multi-source-brains.md
+++ b/docs/guides/multi-source-brains.md
@@ -324,6 +324,11 @@ gbrain sources set-sync <id> <on|off> [--dry-run] [--expect <on|off>]
gbrain sources host-repo <id> --dir <path> [--push-remote <url>] [--dry-run | --expect <plan_hash>]
Managed brains: host a new, empty source in a bare
repository under <path> (see below). Previews without --expect.
+gbrain sources canonical <id> --to git|mixed [--dry-run | --apply --expect <hash>] [--json]
+ Managed brains: convert a source to git-canonical or back
+ to mixed. Previews without --apply; the apply prints progress
+ on stderr and, if stopped, where it stopped
+ (docs/designs/GIT_CANONICAL_MEMORY.md#conversion).
```
### Hosted repositories