Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Note the entity-page fact gate and the quarantined-history filter in the reference docs

garrytan774eca18e0a9
diff --git a/docs/architecture/key-files/belief-ledger.md b/docs/architecture/key-files/belief-ledger.md
index 51201758d0..3b9e6ad571 100644
--- a/docs/architecture/key-files/belief-ledger.md
+++ b/docs/architecture/key-files/belief-ledger.md
@@ -14,7 +14,7 @@ Design: [BELIEF_LEDGER.md](../../designs/BELIEF_LEDGER.md). Operator surface: `g
- `src/core/belief/coverage-report.ts` — readers: `coverageIntervals` (restore marks carry purge-mirror's `archived_at`, `purge_replay`, `replays`), `coverageAt` (refuses `coverage_from` before the slug's cut, found under the slug or its page lifetime, and `coverage_gap` in a stopped span or a restore gap; an interval holding a purge whose derivation walk was truncated is not certified, `uncertified_reason: 'truncated_walk'`, its requests in `truncated_walks`), `beliefEventVisibility` (an unmarked publication is `unproven` until a commit mark or a later event of the page proves it). Drift: `scanBeliefDrift` (sampled, or deep; read-only, it mints no lifetime) compares each slug's current `state_hash` with its newest non-backfill event; `reconcileBeliefDrift` appends `reconcile` events (the slug interval stays uncertified). `orphanLifetimes` and `unmarkedPublications`/`fillCommitMarks` read a recent window unless `deep`; `cycleBeliefReconcile` for the extract phase.
- `src/core/belief/projection-point.ts` — `unmanagedBeliefPoint` (and `withUnmanagedBeliefs` for one transaction): the legacy import, `extract_facts` fence reconcile, takes reextract and the derived link writers (`derived-links.ts`, the remote auto-links effect, attendance repair) lock their sorted page keys and run in an `unmanaged` batch, then mark the commit. Every other unmanaged writer is found by drift.
- `src/core/belief/backfill.ts` — `backfillBeliefHistory`: marked history from `page_versions` only (git is not read), origin `backfill`, historical time in `source_time`, recorded_at the run time; a purge during the run retries (`belief_stale_preparation`), and the summary event says whether pruned versions left it incomplete. A version whose own frontmatter is private (or a pinned question) publishes private events; a carrying field a purge registered from a retained version (`registerVersionCarriers`) is appended as the marker.
-- `src/core/belief/history.ts` — the one history reader (`readBeliefHistory`); remote callers see only events that were world-visible when recorded on a page visible now, failing closed.
+- `src/core/belief/history.ts` — the one history reader (`readBeliefHistory`); remote callers see only events that were world-visible when recorded on a page visible now, failing closed; a quarantined page's fact and take events are hidden from them too (#6259).
- `src/core/belief/page-at-time.ts` — W2 page-at-time (BELIEF_LEDGER.md section 10): `readPageAtTime` replays a slug's page events of every lifetime into validity intervals under the section 5.3 visibility rule (a straddling write refuses `known_as_of_unproven`), refuses `coverage_from` / `coverage_gap` from `coverageAt`, and pairs each closed interval with the preimage version the next transition wrote (by revision, in order); the open head reads the live page. A body no version holds is disclosed (`body_reason`), never borrowed. Purge-redacted events carry no revision, so a purged lifetime splits only on slug and deleted state. `remoteMayRead` applies history.ts's remote rule per interval.
- `src/core/belief/preimages.ts` — the preimage invariant (BELIEF_LEDGER.md section 14 item 8): a revision-moving publication leaves a version of its `revision_before`. `missingPreimages` is the in-batch check `finalizeBeliefEvents` runs under `NODE_ENV=test` (off with `GBRAIN_BELIEF_PREIMAGE_CHECK=0`); `preimageGaps` is doctor's production scan (large and segmented pages exempt).
- `src/core/belief/changes.ts` — W4 weekly change diff (BELIEF_LEDGER.md section 15): `beliefChanges` reads the window through `readBeliefHistory` (`recordedAfter`/`recordedUntil`, then `subjectKeys` up to `since` for each subject's value before), nets each subject end to end, reads a subject with no earlier event from the page body at `since` (`before_known: false` when no body answers), lists a page created in the window with its creation body's fence rows, flags a `dream`-inferred link end `upper_bound`, and skips backfill and baseline events. Remote callers get world fence rows only where `remoteMayRead` passes. Served by `delta {beliefs: true}` and `gbrain beliefs changes`.
diff --git a/docs/architecture/key-files/core-search-1.md b/docs/architecture/key-files/core-search-1.md
index 198dd347ac..720e437589 100644
--- a/docs/architecture/key-files/core-search-1.md
+++ b/docs/architecture/key-files/core-search-1.md
@@ -65,7 +65,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/search/modes-report.ts` — `buildModesReport(engine)` → `SearchModesReport` (`schema_version: 2`), the read-only dashboard behind `gbrain search modes` and the `search_modes` MCP op: `active_mode` + validity, the per-knob `resolved` attribution (`attributeKnob` over `KNOB_DESCRIPTIONS`, including the five `reranker_*` knobs), the three frozen `bundles`, `config_keys`, and `reranker_readiness` — `{model, enabled, ready, required_key, key_present, self_hosted, fix}` from `rerankerReadinessForEngine` + `describeRerankerFix` (a thrown readiness check still yields a `ready: false` verdict whose `fix` says to run `gbrain doctor`; the block never vanishes silently). `redactReadinessForRemote(report)` is what the `search_modes` op returns when `ctx.remote !== false`: `required_key`, `key_present` and `fix` are dropped and `self_hosted` is forced false — which env vars exist on the host is fingerprinting data and the fix names them; `ready` stays because it is observable anyway (reranked results carry `rerank_score`). `src/commands/search.ts:formatModesText` renders the runtime `Reranker:` line (`off (resolved) — …` / `<model> (enabled) — <KEY> present` / `<model> (enabled but NOT running) — <fix>`) and a per-bundle `reranker=… topNIn=… autocut=…` line. Pinned by `test/modes-report-reranker.test.ts`. The CLI dashboard leads with command-specific expansion: `query` follows the mode's expansion default (off in all modes) unless the call passes `expand`, while `search` is off. It discloses provider prerequisites/text flow and distinguishes retained bundle configuration from effective command behavior.
-- `src/core/search/private-visibility.ts` — shared page-visibility resolver and SQL predicates. Explicit local trust disables page filtering; operator env/config opt-outs keep their semantics; failed config reads enforce privacy. `privatePagesFilterFragment` authorizes concrete page rows and `isPrivatePage` is its row-side twin: explicit `private` hides a page, absent visibility is world for ordinary pages and private for extracted atoms (`type = 'atom'`) and synthesized concepts (`type = 'concept'` with `synthesized_by`), because their origin may be a private page or transcript. The page predicate also follows derived origins: an atom whose `source_slug` page is explicitly private, and a synthesized concept with a private input atom (or an input whose origin is private) over `concept-provenance` edges, are private whatever their own field says, so a later private flip of an origin reaches derived pages before any repair. Chronicle events follow `event.depth` (fail closed). Declared lineage matches `derived_from` slugs with `= ANY(ARRAY(...))`, not `IN (SELECT ... jsonb_array_elements_text(...))`: same rows, but the planner priced the IN form as a 100-row semi-join per page and pushed every read carrying the rule past `jit_above_cost` (`test/e2e/private-visibility-plan-postgres.test.ts`). `privateSnapshotFilterFragment` is the same rule on a row's own frontmatter for `page_versions`. `effectiveVisibility(origin)` (transcript or missing origin private, page origin per the read rule) and `strictestVisibility` are used by both `extract_atoms` paths, concept synthesis and `gbrain repair visibility`. Remote publication rechecks (`persistence/page-visibility.ts`) and the alias-inject recheck in `hybrid.ts` use the same rule. Tests: `test/private-visibility.test.ts`, `test/derived-page-visibility.test.ts` (PGLite and Postgres); link origins and timeline projections use independent ID-based predicates. `privateProvenanceFilterFragment` hides a fact whose provenance page (`source_markdown_slug`) is private; the fact-list reads in `engine-sql/facts.ts` (by entity, since, keyset, session, supersessions, trajectory) apply it behind `FactListOpts.excludePrivate` / `TrajectoryOpts.excludePrivate`, which every remote fact surface resolves with `resolveExcludePrivatePages` (`test/remote-fact-list-private-provenance.test.ts`, both engines). Remote fact writes apply the same predicate behind an `excludePrivate` option: `forget` (`guardRemoteForget`, the row lock in `persistence/memory-mutations.ts`, `recordFactWithdrawal`, `similarActiveAfterForget`) and `remember` (`decideSingleFact`'s exact and cosine arms, `decideReplacement`), so a fact remote reads hide is `not_found` to a remote write and never matched as its duplicate (`test/remote-fact-write-private-provenance.test.ts`, both engines). Legacy slug-set helpers only enumerate names; they never authorize another row's data. `ops/context.ts:readPolicyOpts` combines canonical source precedence, resolved privacy and holder permissions. Both engines filter content/history/graph/identity/analytics before limits or aggregation; current and historical visibility are checked independently while page privacy is enforced. Semantic response caching remains disabled, so visibility-key folding alone never authorizes reuse.
+- `src/core/search/private-visibility.ts` — shared page-visibility resolver and SQL predicates. Explicit local trust disables page filtering; operator env/config opt-outs keep their semantics; failed config reads enforce privacy. `privatePagesFilterFragment` authorizes concrete page rows and `isPrivatePage` is its row-side twin: explicit `private` hides a page, absent visibility is world for ordinary pages and private for extracted atoms (`type = 'atom'`) and synthesized concepts (`type = 'concept'` with `synthesized_by`), because their origin may be a private page or transcript. The page predicate also follows derived origins: an atom whose `source_slug` page is explicitly private, and a synthesized concept with a private input atom (or an input whose origin is private) over `concept-provenance` edges, are private whatever their own field says, so a later private flip of an origin reaches derived pages before any repair. Chronicle events follow `event.depth` (fail closed). Declared lineage matches `derived_from` slugs with `= ANY(ARRAY(...))`, not `IN (SELECT ... jsonb_array_elements_text(...))`: same rows, but the planner priced the IN form as a 100-row semi-join per page and pushed every read carrying the rule past `jit_above_cost` (`test/e2e/private-visibility-plan-postgres.test.ts`). `privateSnapshotFilterFragment` is the same rule on a row's own frontmatter for `page_versions`. `effectiveVisibility(origin)` (transcript or missing origin private, page origin per the read rule) and `strictestVisibility` are used by both `extract_atoms` paths, concept synthesis and `gbrain repair visibility`. Remote publication rechecks (`persistence/page-visibility.ts`) and the alias-inject recheck in `hybrid.ts` use the same rule. Tests: `test/private-visibility.test.ts`, `test/derived-page-visibility.test.ts` (PGLite and Postgres); link origins and timeline projections use independent ID-based predicates. `privateProvenanceFilterFragment` hides a fact whose provenance page (`source_markdown_slug`) is private; the fact-list reads in `engine-sql/facts.ts` (by entity, since, keyset, session, supersessions, trajectory) apply it behind `FactListOpts.excludePrivate` / `TrajectoryOpts.excludePrivate`, which every remote fact surface resolves with `resolveExcludePrivatePages` (`test/remote-fact-list-private-provenance.test.ts`, both engines). `privateEntityFilterForCaller` adds the entity-page gate (a fact whose `entity_slug` page the caller cannot read is hidden) and `privateFactFilterForCaller` combines both gates for recall, the entity card, contested claims, attribution, saved-fact matching, entity facts and the proactive brief (`test/fact-reads-page-access.test.ts`). Remote fact writes apply the same predicate behind an `excludePrivate` option: `forget` (`guardRemoteForget`, the row lock in `persistence/memory-mutations.ts`, `recordFactWithdrawal`, `similarActiveAfterForget`) and `remember` (`decideSingleFact`'s exact and cosine arms, `decideReplacement`), so a fact remote reads hide is `not_found` to a remote write and never matched as its duplicate (`test/remote-fact-write-private-provenance.test.ts`, both engines). Legacy slug-set helpers only enumerate names; they never authorize another row's data. `ops/context.ts:readPolicyOpts` combines canonical source precedence, resolved privacy and holder permissions. Both engines filter content/history/graph/identity/analytics before limits or aggregation; current and historical visibility are checked independently while page privacy is enforced. Semantic response caching remains disabled, so visibility-key folding alone never authorizes reuse.
- `src/core/search/projection-readiness.ts` — one statement probes visible unsealed pages: ready, projection_pending, by_design (protected/archived only, if none pending) or unknown; LIMIT 1 arms use the v161 pending index. Cached per scope by DB generation (page clock, pages filenode, archive flags, no open tx); `GBRAIN_PROJECTION_READINESS_CACHE=0` disables.