Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Doctor's lost-write checks finish on large brains and never report ok after a partial scan (GST-2779) (#9417)

Garry Tane998829fa317
diff --git a/behavior-changes.d/doctor_git_gap_unknown_gbra541.md b/behavior-changes.d/doctor_git_gap_unknown_gbra541.md
new file mode 100644
index 0000000000..6c334f706d
--- /dev/null
+++ b/behavior-changes.d/doctor_git_gap_unknown_gbra541.md
@@ -0,0 +1 @@
+`gbrain doctor` now reads the 800 most recently changed pages of each source in db_ahead_of_git and strict_facts_outside_git, and says how far back it looked; `gbrain sources git-gap <source-id>` still reads every page. A census that runs out of its time budget or cannot run, and in strict_facts_outside_git a fenced fact on a page older than that window, now report warn with health unknown instead of ok, and git_index_lag does the same when it cannot read the lag. An agent that pages on `doctor --fail-on warn` may see these checks warn where they used to pass; run `gbrain sources git-gap <source-id>` for the full count.
diff --git a/changelog.d/capy-gbra-541-doctor-scale.md b/changelog.d/capy-gbra-541-doctor-scale.md
new file mode 100644
index 0000000000..c3bbdfe197
--- /dev/null
+++ b/changelog.d/capy-gbra-541-doctor-scale.md
@@ -0,0 +1,11 @@
+**Doctor's Git checks now finish on large brains, and a check that could not see everything says health unknown instead of ok.**
+
+### Changed
+- `db_ahead_of_git` and `strict_facts_outside_git` read the 800 most recently changed pages of each source instead of every page, and their messages say how far back they looked. `gbrain sources git-gap <source-id>` still reads every page.
+- When that census runs out of its time budget or cannot run, `db_ahead_of_git`, `strict_facts_outside_git` and `git_index_lag` now report a warning with health unknown instead of ok.
+- Doctor runs the checks that catch lost writes before its full scans.
+
+### Fixed
+- `strict_facts_outside_git` no longer says every fact has a Git home when a fenced fact sits on a page older than that window. It reports health unknown, and `gbrain sources git-gap <source-id>` counts the whole source.
+
+<!-- behavior-change: doctor_git_gap_unknown_gbra541 -->
diff --git a/docs/architecture/key-files/commands-2.md b/docs/architecture/key-files/commands-2.md
index 71de2dfa2f..e7c2c574a1 100644
--- a/docs/architecture/key-files/commands-2.md
+++ b/docs/architecture/key-files/commands-2.md
@@ -41,7 +41,7 @@ Doctor's embedding-dimension warning treats existing chunks as existing data eve
Size ceiling: `scripts/module-size-limits.tsv` (per-change raise history: `git log -p` on that file). The ceiling covers the façade: re-exports, `Check`/`DoctorReport` and report scoring, the `buildChecks` flag parse, `runDoctor`, output rendering and `--locks`; every check block lives in a registry entry under `doctor/checks/*` (refactor wave 1 W4 doctor), remediation in `doctor/remediate.ts`, wave checks in `doctor/wave-checks.ts`.
- `src/commands/doctor/check-fix.ts` (+ `heartbeat.ts`, `checks/harness-wiring.ts`, `checks/agent-contract.ts`) — doctor speaks agent contract v1. `Check` carries optional `fix` (stored `Action`; `computeDoctorReport` renders it for the report's transport via `finalizeCheckFixes`, redacted on http), `fix_unavailable_reason` (`check_errored`, `operator_judgement`, `no_safe_automatic_fix`, `unstructured` for legacy prose-only warns), `severity: 'info'` and `readiness_state`; `schema_version` stays 2 and status stays `ok | warn | fail`. Capabilities that are off by choice or not applicable yet (keyless embeddings and their staleness/vector checks, opt-in takes, no serve running, 0 pages, never-cycled empty or <24 h sources, backup before 25 pages+facts or 7 days via `backupCoachingDue`) report `ok` + `info` with the enable command as `fix`; the report adds `capped_by: ['embeddings_disabled']` and, when the `connection` check is present and not ok, `unknown_scores: ['brain']`. `top_issues[]` gain `action` (the rendered fix) beside the legacy `fix` string. `checkError(name, what, err)` is the one "Could not …" shape (a `gbrain db-repair` fix when the error classifies as DB access). `gbrain doctor --only <check>[,…] [--json]` (`parseOnlyChecks`, `onlyNeedsEngine`, CLI `runDoctorOnly`) runs only the entries that emit those names plus the connection lane, engine-free when every name is a filesystem check, else `connectEngine({ probeOnly: true })`; unknown names exit 2 with the valid list; a requested check that produced nothing reports `info`/`not_applicable` (or `check_errored` after an early stop). It is every doctor fix's `verify`. `harness_wiring` reads the gbrain registration from `~/.claude.json` (+ receipt `.mcp.json`), Codex `config.toml` and `opencode.json`; under `--only harness_wiring` it smoke-tests it (live serve lock owner → `wired_running`; else spawn the registered argv, 15 s, initialize + tools/list + `recall`; `gbrain_status` replies reported with their reason/fix); it writes nothing. #6453: with no PGLite lock, an HTTP registration gets a credential-free 3 s GET of `/health` (`probeHttpRegistration`): gbrain `ok` → `wired_running` + `mcp_access: 'unverified'`; refused loopback `http:` → `http_serve_missing` + fix; else `http_serve_unreachable`/`http_serve_unhealthy`, no fix. `redactRegistrationUrl` strips userinfo, query and fragment from every printed URL (`test/harness-wiring-redaction-6453.test.ts`). `agent_contract` reads the whole size-bounded log (`readAgentContractEvents(Infinity)`, 7-day window) and warns on `internal_error`/suggestion-less envelopes, consent refusals, `derived_cap_exhausted` and `json_document_missing`, with the user-only `consent.preapprove.*` command as fix. `throttleDoctorHeartbeat`: piped doctor progress emits at most one heartbeat per 5 s. Tests: `test/doctor-status-set.test.ts`, `test/doctor-harness-smoke.test.ts`, `test/doctor-day-zero.test.ts` (keyless init then doctor: 0 WARN, health ≥ 90), `test/doctor-remote-parity.test.ts` (run_doctor and CLI agree per shared check; run_doctor renders fixes for its transport). `harness_wiring` with no registration drops each detected harness a plugin lane covers (`enabledPluginLanes`; all → `ok` `plugin_lane_enabled`, not smoke-tested) or whose receipt-recorded config it cannot read (#7422; all → `info` `registration_recorded`); the warning names the rest. Claude Code detection also honors `CLAUDE_CONFIG_DIR`.
-- `src/commands/doctor/registry.ts` + `src/commands/doctor/context.ts` — the doctor check registry (refactor wave 1, W4 doctor). `DOCTOR_CHECK_REGISTRY` lists 126 `DoctorEntry` records `{ name, emits, run(ctx) -> Promise<Check[] | STOP_DOCTOR> }` in output order; `runDoctorRegistry(ctx)` runs them, returns the checks gathered so far on `STOP_DOCTOR`, and otherwise finishes the DB-checks progress phase. The run is one `withGitListingCache` scope (`src/core/git-visible-files.ts`), so entries that list the same source checkout (frontmatter scan, fence census, slug collisions) share one `git ls-files` per listing and one "not a git repository" verdict per directory (`ls-files`, `discoverGitRoot`, the census HEAD probe; any repository-changing `sync-git.ts` command or `invalidateGitListingCache()` drops the scope's memo: `test/git-listing-memo.serial.test.ts`). Execution groups: filesystem-first entries (the resolver-health entry applies `--fix` before it scans), the no-engine connection lane plus a STOP when `--fast` or no engine, the live connection entry plus a STOP when `getStats` failed, then the DB entries, which take the engine via `connectedEngine(ctx)`. `DoctorContext` carries the parsed flags (`jsonOutput`, `fastMode`, `doFix`, `dryRun`, `scope`, `orphanRatioSourceId`, `args`), `engine`, `dbSource`, `connectError`, `progress`, the skills-dir resolution and the cross-entry values `autoFixReport`, `schemaVersion`, `connectionFailed`, each written by the entry that computes it. Entry modules (one `run*` function per former `buildChecks` block, moved verbatim): `checks/skill-group.ts`, `local-runtime.ts`, `supervisor-health.ts`, `local-audits.ts`, `db-connection.ts` (also `pgbouncerPrepareCheck`, `classifiedConnectionCheck` — a live serve owner warns with the exclusive two-step fix, a `pglite_busy` reason `legacy_owner_unverified` fails with details.reason and the refusal's ask_user preview fix, anything else is classified for `db-repair` — and the two STOP gates), `schema-health.ts`, `embedding-health.ts`, `graph-health.ts`, `data-integrity.ts`, `content-quality.ts`, `knowledge-health.ts`, `queue-assets.ts`, `sync-search.ts`; `checks/legacy-token-grants.ts` (F3) emits `legacy_token_grant_shape` (info: active tokens still on the JSONB-only grant shape, fix `gbrain auth rescope --migrate-legacy`) and `legacy_token_grant_drift` (warn: per-token drifted axes with the two adopt commands); `checks/grant-new-ops.ts` (D4) emits `grant_new_ops_available` (warn: active clients and tokens whose operation snapshot or stored surface keeps operations their scopes allow out of reach, with proven blockers apart from inferred grant age, per-grant names in details, and an ask_user fix whose rescope argv differs for tokens and clients; `--operations all` is a disclosed choice, never the fix); `checks/upgrade-health.ts` holds `checkUpgradeErrors` / `checkSelfUpgradeHealth` / `upgradeErrorResolved` (re-exported by the façade). A pre-gate entry declares the names it only emits with a connected engine in `engineChecks` (#6303), so `onlyNeedsEngine` connects for `--only` of them; `test/doctor-only-engine-checks.test.ts` is the drift guard. To add a check: add an entry in the topic module, place it in `DOCTOR_CHECK_REGISTRY` where its output belongs, and categorize every emitted name in `src/core/doctor-categories.ts`. Tests: `test/doctor-registry.test.ts` (category contract with FAIL/Why/Fix/See, `emits[]` equals the AST walk, STOP positions), `test/doctor-mode-matrix.serial.test.ts` (entries run, STOP point, engine calls and `--fix` mutations per mode), and the W0 goldens `test/doctor-registry-golden.test.ts` (the AST walker follows `runDoctorRegistry` into the registry), `test/doctor-early-stop-golden.serial.test.ts`, `test/doctor-json-golden.test.ts`.
+- `src/commands/doctor/registry.ts` + `src/commands/doctor/context.ts` — the doctor check registry (refactor wave 1, W4 doctor). `DOCTOR_CHECK_REGISTRY` lists 126 `DoctorEntry` records `{ name, emits, run(ctx) -> Promise<Check[] | STOP_DOCTOR> }` in output order; `runDoctorRegistry(ctx)` runs them, returns the checks gathered so far on `STOP_DOCTOR`, and otherwise finishes the DB-checks progress phase. The run is one `withGitListingCache` scope (`src/core/git-visible-files.ts`), so entries that list the same source checkout (frontmatter scan, fence census, slug collisions) share one `git ls-files` per listing and one "not a git repository" verdict per directory (`ls-files`, `discoverGitRoot`, the census HEAD probe; any repository-changing `sync-git.ts` command or `invalidateGitListingCache()` drops the scope's memo: `test/git-listing-memo.serial.test.ts`). Execution groups: filesystem-first entries (the resolver-health entry applies `--fix` before it scans), the no-engine connection lane plus a STOP when `--fast` or no engine, the live connection entry plus a STOP when `getStats` failed, then the DB entries, which take the engine via `connectedEngine(ctx)`. GBRA-541: the entries that emit `LOST_WRITE_CHECKS` (`git_index_lag`, `db_ahead_of_git`, `strict_facts_outside_git`, `owner_host_stale`, `uncommitted_sync_deletions`) sit right after the privacy check, before the full scans, so slow scans on a large brain cannot use up the budget first (`test/doctor-entry-deadline-6803.test.ts`). `DoctorContext` carries the parsed flags (`jsonOutput`, `fastMode`, `doFix`, `dryRun`, `scope`, `orphanRatioSourceId`, `args`), `engine`, `dbSource`, `connectError`, `progress`, the skills-dir resolution and the cross-entry values `autoFixReport`, `schemaVersion`, `connectionFailed`, each written by the entry that computes it. Entry modules (one `run*` function per former `buildChecks` block, moved verbatim): `checks/skill-group.ts`, `local-runtime.ts`, `supervisor-health.ts`, `local-audits.ts`, `db-connection.ts` (also `pgbouncerPrepareCheck`, `classifiedConnectionCheck` — a live serve owner warns with the exclusive two-step fix, a `pglite_busy` reason `legacy_owner_unverified` fails with details.reason and the refusal's ask_user preview fix, anything else is classified for `db-repair` — and the two STOP gates), `schema-health.ts`, `embedding-health.ts`, `graph-health.ts`, `data-integrity.ts`, `content-quality.ts`, `knowledge-health.ts`, `queue-assets.ts`, `sync-search.ts`; `checks/legacy-token-grants.ts` (F3) emits `legacy_token_grant_shape` (info: active tokens still on the JSONB-only grant shape, fix `gbrain auth rescope --migrate-legacy`) and `legacy_token_grant_drift` (warn: per-token drifted axes with the two adopt commands); `checks/grant-new-ops.ts` (D4) emits `grant_new_ops_available` (warn: active clients and tokens whose operation snapshot or stored surface keeps operations their scopes allow out of reach, with proven blockers apart from inferred grant age, per-grant names in details, and an ask_user fix whose rescope argv differs for tokens and clients; `--operations all` is a disclosed choice, never the fix); `checks/upgrade-health.ts` holds `checkUpgradeErrors` / `checkSelfUpgradeHealth` / `upgradeErrorResolved` (re-exported by the façade). A pre-gate entry declares the names it only emits with a connected engine in `engineChecks` (#6303), so `onlyNeedsEngine` connects for `--only` of them; `test/doctor-only-engine-checks.test.ts` is the drift guard. To add a check: add an entry in the topic module, place it in `DOCTOR_CHECK_REGISTRY` where its output belongs, and categorize every emitted name in `src/core/doctor-categories.ts`. Tests: `test/doctor-registry.test.ts` (category contract with FAIL/Why/Fix/See, `emits[]` equals the AST walk, STOP positions), `test/doctor-mode-matrix.serial.test.ts` (entries run, STOP point, engine calls and `--fix` mutations per mode), and the W0 goldens `test/doctor-registry-golden.test.ts` (the AST walker follows `runDoctorRegistry` into the registry), `test/doctor-early-stop-golden.serial.test.ts`, `test/doctor-json-golden.test.ts`.
- `src/commands/doctor/` — the doctor module directory behind the `doctor.ts` façade. `checks/` holds the check functions, grouped by concern (`core-health.ts`, `queue-jobs.ts`, `extraction-sync.ts` (its `sync_freshness` check excludes sources disabled by `isSyncDisabledConfig` and adds `--no-pull` to its sync hint on a managed brain; `content_hash_duplicates` prescribes `GBRAIN_SOURCE=<id> gbrain delete <bare-slug> --force` per wrong-root pair, naming each source when pairs span several, and never a hard purge; `cycle_freshness` in `consolidation-cycle.ts` still monitors their maintenance; its `atom_provenance_drift` check scopes drift to page-bound atoms and splits it into `source_changed` / `source_gone`; atoms with no `source_slug` — transcript-origin `source_path`-only rows, hashed over a file, with page liveness unresolvable by slug — count as their own `slug_unbound`, outside the drift total and the WARN ratio), `graph-embedding.ts`, `search-eval.ts`, `calibration.ts`, `consolidation-cycle.ts`, `pglite-worker.ts`, `routing-federation.ts` (`source_routing_health` exempts zero-page skill-pack sources), `verbs-reflex.ts`, `stale-mentions.ts`, `timeline-history.ts` (`timeline_history`: database-only timeline rows, bounded to 2,000 pages / 10 s per run, cursor in config `doctor.timeline_history.scan:<sources>` so runs finish a pass (a clean pass stays `ok` until a newer row; `doctor-timeline-history-cursor-5821.test.ts`), exact-or-lower-bound counts (lower bound past 10,000 found pages), non-round-trippable rows informational, repair `gbrain repair timeline`; segmented pages counted apart (`segmented_*`), no repair advice), `derived-visibility.ts` (`derived_visibility`: atoms and synthesized concepts without explicit visibility or looser than their origin (an origin a rename moved counts through `slug_rename_history`, GST-2687), one exact aggregate, repair `gbrain repair visibility`), `engine-fit.ts` — the last carrying `pglite_scale` + the engine-free `db_repair_recurrence` over the db-repair receipts); `schema-pack-checks.ts`, `report-remote.ts`, `bootstrap-checks.ts`, and `skill-checks.ts` are the four tail-cluster modules (schema-pack checks, the remote/thin-client doctor report, bootstrap checks, skill checks). `harness-hook-checks.ts` (`harnessHookCarrierChecks`, called from `bootstrap_harness_health`) reads each receipt-named Claude Code hook carrier read-only: an event wired more than once by this install warns `harness_hook_duplicates` with a consented re-run carrying the install's `--project`/`--no-capture` choices, a lookalike it did not write warns `harness_hook_unowned` (operator judgement), an unparseable carrier warns naming the file, and entries the host stripped of their marker are an `ok` info row; `plugin_lane_collision` iterates `enabledPluginLanes`. `multiSourceDriftCheck` is the one local/remote `multi_source_drift` verdict: on a managed brain (`managedPersistenceEnabled`) its sync advice names `--no-pull` and drops `--include-gitignored`, unmanaged wording is unchanged, and any skipped source keeps it warn/not_verified. `src/core/multi-source-drift.ts` derives a `git-root`-pinned source's slug prefix from its git toplevel (realpaths, empty at the repo root) and skips only a source whose toplevel cannot be resolved (`git_root_skipped`). It drops every walked path sync would refuse (`unsyncableReason(prefix + relPath)`: metafiles such as root `AGENTS.md`/`CLAUDE.md`, pruned dirs, malformed names) before probing, so a same-slug page on `default` is not reported for a file sync never imports (#6681). `graph-health.ts` `graph_coverage`, like onboard's link and timeline coverage, is `ok` (not applicable, with the count) below `MIN_ENTITY_PAGES_FOR_COVERAGE` (5) eligible entity pages. `graph_coverage` and `orphan_ratio` count the entity types the active schema pack declares (#4772, `src/core/schema-pack/entity-types.ts`, resolved per source: brain-wide for `graph_coverage`, the asked source for `orphan_ratio --source`); a pack that does not load makes `graph_coverage` a warn naming the pack (never the old hardcoded list) and `orphan_ratio` answers with an "entity count unknown" caveat instead of a vacuous ok. All are re-exported by the façade. Structural guards that pin doctor source text load it through `test/helpers/doctor-source.ts`: `doctorSource()` concatenates the façade plus every `src/commands/doctor/**/*.ts` (façade first, then sorted) so a module move can never take a pinned string out of a guard's sight; `doctorFileSource(rel)` reads one named file for positional/ordering assertions; the helper also feeds the `doctor-source-helper` detector in `scripts/classify-tests.ts`. `facadeExpansion` in `scripts/generate-flag-registry.ts` keeps this directory on the doctor command's flag-scan surface. Two read-only derived-data checks live beside them: `timeline-orphans.ts` (`timeline_orphans`, samples 500 pages for rows an earlier page version produced that the current text no longer does; fix is `gbrain extract timeline --prune-orphans`) and `slug-collisions.ts` (`slug_collisions`, walks each live source checkout with `collectSyncableFiles` and reports paths that map to one slug plus the indexed one; sources without a checkout are skipped). `checks/graph-embedding.ts` `checkJunkEntityHubs` (#6158) splits connector contact pages (frontmatter `google_contact_id` or a connector source kind) into `details.connector_twins` with their main-brain `canonical_twin`, never calls them extractor-minted or offers `junk_hub_exempt`, and carries `fix_unavailable_reason: 'operator_judgement'` while the defer-to-twin policy is open.
diff --git a/docs/architecture/key-files/core-persistence-git.md b/docs/architecture/key-files/core-persistence-git.md
index f99c6f810c..3c3b8ca204 100644
--- a/docs/architecture/key-files/core-persistence-git.md
+++ b/docs/architecture/key-files/core-persistence-git.md
@@ -6,7 +6,7 @@ The managed Git writer (`gbrain sources refresh`), git-canonical memory (the git
- `src/core/persistence/{worktree-refresh,worktree-refresh-schema}.ts` — `gbrain sources refresh` (F0), the one sanctioned managed Git writer. `persistence_worktree_refreshes` holds one row per refresh with a partial unique index (one active refresh per worktree; its 23505 maps to `refresh_in_progress`). `refreshWorktree` prechecks with no database state (managed, owner host, upstream, no active refresh, no recovery, no unexhausted managed-sync cursor, hardened `git fetch` bounded by `sources.refresh_fetch_timeout_ms`, ancestry, dirty paths intersected with the incoming diff), then: `draining` (inserted under `withTopologyLocks` + `lockTopologyRows`; admission in `journal.ts` refuses `worktree_refreshing` for every request with that `worktree_id`, and `assertManagedSyncAllowed` refuses a managed sync before discovery), poll until no queued/running/recovering request, no queued/running `git`/`withdrawal-mirror` effect and no recovery record remain (else `refresh_drain_timeout`, aborted), `fenced` (both native locks held, rechecked in one transaction; `refreshFenceClear` stops request and effect claims), HEAD verified (#8617: a `refresh_source_changed` for a moved HEAD or work that arrived after the drain check is retried once in the same run from a fresh precheck; a second refusal returns the first with the retry's cause appended), dirt rechecked, `git merge --ff-only`, HEAD verified again (a HEAD that descends from the target after a successful merge, with no member synced off it, counts as merged: a plain-git commit landed in between; a refused fast-forward whose HEAD only gained commits on the start commit aborts `refresh_source_changed`, GST-1674), then one transaction `merged` + upstream observation + `syncing`; native locks are released and the managed `--no-pull` sync runs per member in one budget (`sources.refresh_sync_budget_ms`; past it a member is `deferred`) (only `managed_sync_*` `submit_job` admissions pass during `syncing`); `completed` when every member's `last_commit` is the target or descends from it, or with `outcome.sync_blocked` / `sync_deferred` when a member blocks or is deferred. A per-worktree `refresh-<worktree>.lock` held for the whole run proves liveness: `resumeWorktreeRefreshes` (called from `recoverSourceTopologies` on every consumer topology scan) touches interrupted `draining`/`fenced`/`merged` rows whose lock is free and applies the section 1.5 table (draining or fenced at the old HEAD abort; so does a fenced row whose merge started (`outcome.merge_started_at`, epoch ms) and whose HEAD descends from the old HEAD without the target, when the reflogs of HEAD and its branch show no move to the target since then (git refused the fast-forward, GST-1674; no readable reflog stays `recovery_required`); HEAD at the verified target moves to `syncing`; anything else is `recovery_required`, which admission refuses with `refresh_recovery_required`). Admission also completes a `syncing` row whose members all reached the target. #7679: each row records its holder (`outcome.holder`: host id, hostname, pid, process start; `previous_holder` after a recovery adopts it). A row whose lock is free is orphaned: `resumeWorktreeRefreshes` also completes an orphaned `syncing` row once every member's `last_commit` reached the target or a descendant, and a plain `gbrain sources refresh` on the owner host finishes any orphaned non-`recovery_required` row through the `--resume` path (`adoptOrphanedRefresh` + `resumeHeld`) before its own refresh, reporting it as `recovered`. A holder recorded on another host is never adopted. `refreshHolderReport` (writer status `worktree_refreshes`, sync status `worktree_refresh`) names the holder, `liveness` (`live` / `orphaned` / `unknown` off the lock's host) and a fix naming `--resume`. While the worktree's newest refresh is `aborted`, every run (tick, `--resume`, `--abandon`, even one its precheck refuses) ends by running the managed `--no-pull` sync of each member behind the checkout HEAD (`syncAfterUnfinishedRefresh`, listed in `synced`), so a write held for an import that refresh fenced off is decided in that run, not at a later refresh. `--resume` converges and runs the member syncs; `--abandon` lifts a fence only with HEAD back at the start commit or on a row recovery would abort (a HEAD moved before the merge, or a refused merge, GST-1674), and never on a `recovery_required` row once a member is past it (`membersPastStart`: a `last_commit` that is not it or an ancestor, GST-1457: the next sync would soft-delete what it synced; or a managed-sync import or delete admitted after the row's `barrier_sequence`, GST-1465: a pass stopped before its stamp), checking and aborting under every member's drain lease (`underMemberLeases`, so a pass in flight refuses `sync_drain_lease_held`), and `--resume` finishes a `recovery_required` row only at a HEAD that contains every member commit on that refresh's line (`adoptsHead`, which `--abandon` also reads to name `--resume` instead of a reset). `keepPagesWayOut` names the way out (GST-1472): a fast-forward to the newest member commit on the target's line, a merge of member commits on diverged lines (ask the user), or a fetch when git cannot place a member commit (`ancestry` tells exit 1 from a failure); the refusals also name the revert route for a deliberate rollback (GST-1477), and off the owner host writer status names no step. `gbrain sources writer status` lists active refreshes as `worktree_refreshes` (state, heads, the next command). Doctor `worktree_refresh_stuck` lists rows active over 15 minutes. CLI body: `src/commands/sources-refresh.ts` (#7685: `--json` prints a refusal's structured `fix` when it has one; `refresh_in_progress` carries the writer-status read); while a resident PGLite owner (`gbrain serve`, stdio MCP) holds the database, `src/commands/sources-refresh-delegate.ts` runs the refresh inside it through the `writer_refresh` administration operation (trusted CLI registration only) and prints the same result or refusal. The consumer's idle probe applies `refreshFenceClear` to effects like the claims, so a fenced worktree's queued effects do not wake it. Tests: `test/persistence-worktree-refresh.test.ts`, `test/persistence-worktree-refresh-restart.test.ts` (child-process crash after merge, and after a refused merge), `test/worktree-refresh-orphan-7679.test.ts` (SIGKILL mid-syncing, live-holder no-steal), `test/oversize-hold-rescreen-8072.test.ts` (budget), `test/refresh-barrier-held-after-abort.test.ts` (the sync after an aborted refresh), Postgres via `test/e2e/worktree-refresh-*postgres.test.ts`, owner delegation in `test/persistence-sync-stdio-owner.test.ts`.
- `src/core/persistence/refresh-barrier.ts` (+ deferred admission and claim in `journal.ts`, migration v292 `src/core/schema-migrations/v292-refresh-write-barrier.ts`) — the refresh write barrier (`docs/designs/REFRESH_WRITE_BARRIER.md`, `docs/guides/write-refusals.md#deferred-writes`). Off by default (`persistence.refresh_barrier`). With it on, a single page or memory write that reaches a worktree during a refresh is journaled in state `deferred` (tied to `deferred_refresh_id`) and answered pending instead of refused `worktree_refreshing`. Only a claim that declares the barrier moves a deferred row, and only after its refresh is released. `deferredReplayRefusal` re-checks the write's authority and reads the refresh's `old_head..target_head` diff with git, so a file the refresh changed ends `revision_conflict` with nothing applied. A write still waiting past `persistence.refresh_barrier_max_wait_ms` (15 minutes) ends `refresh_barrier_expired`. A write during a refresh in `recovery_required` defers too, and since GST-1582 there is no per-refresh cap (`persistence.refresh_barrier_max_deferred` is no longer read). A write whose page file holds a committed change sync has not imported yet is held with `deferred_import_from` (migration v294) instead of refused `pending_import`, and ends `pending_import_expired` past the wait limit (or four wait limits, at least four hours, after admission when it is held again and again). GST-1623: either kind of deferred write ends `revision_conflict` when a later write to its page committed first, and a refresh-deferred write is checked against its refresh before an import hold, which then clears `deferred_refresh_id`. `refresh-retry-hint.ts` derives `worktree_refreshing`'s `retry_after_ms` from the worktree's refresh history. `gbrain upgrade --check-downgrade` exits 3 `downgrade_blocked_deferred_writes` while any deferred write is unfinished. Tests: `test/refresh-write-barrier.test.ts`, `test/refresh-barrier-state-audit.test.ts`.
-- `src/core/persistence/git-gap.ts` + `src/commands/sources-git-gap.ts` + `src/commands/doctor/checks/db-ahead-of-git.ts` — git-canonical memory, wave G1 (`docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census`), read-only. `declaredDatabaseOnly` is the one predicate for pages that may not have a tracked file, tested in order: a read-only mirror source, a private page (`isPrivatePage`), an alias-private page (`isDerivationPrivate`), lineage-private (computed in SQL from `privatePagesFilterFragment`), `database_only_reason`, a `storage.db_only` prefix (`isSourceDbOnlySlug`, refusing an invalid gbrain.yml), a never-filed derive-phase page (page-prepare.ts `isNeverFiledDerivedPage`: no `source_path`/`source_uri` under `DERIVE_PHASE_DB_ONLY_DEFAULTS`), a path the checkout's Git ignores (`ignoredPaths`: filter-free `check-ignore -z --stdin`, tracked files never reported, exit 1 = none, null when Git cannot answer). The equality contract compares a committed blob with the page's export view (`readExportPage`, withdrawals overlaid; the census reads a batch's views with `readExportPages`, the same snapshots in two statements, #7617): an inline blob parsed as reconcile parses a canonical file, aligned with the stored type, subtype and #6429 stamp and compared by `reconcileCanonical` digest; a segmented page by the Git blob id of its streamed export. HEAD is read with hardened plumbing only (`readHeadTree`: one `ls-tree -r -l -z --full-tree` under the source's directory; `readBlobs`: `cat-file --batch` in calls of at most 64 MiB) and the working tree by hashing raw bytes (`worktreeBlobOid`), never `git status`/`git diff`, so no repository filter, textconv or fsmonitor runs. `gbrain sources git-gap <id> [--sample n] [--json]` (trusted local CLI, not an MCP op) puts every live page in one state (`equal`, `database_ahead`, `git_ahead` when the sync import record's `blob_oid`/`disk_blob_oid` differs from HEAD, else folded into `database_ahead` and counted in `database_ahead_without_import_record`, split by content evidence in `direction_evidence`, `declared_database_only` per class, `undeclared_database_only`, `worktree_only`, `unparseable`, `unsafe_path`), reports the working tree separately, and counts rows with no Git home (unfenced active facts, fenced facts on a missing page or a page without a committed file, links whose `link_source` is not in `DERIVED_LINK_SOURCES`, timeline rows on pages without a file), open `sync-hold` records by code and parked effect targets by kind and code. Each 256-page batch reads in its own read-only transaction. Doctor `db_ahead_of_git` runs the census per non-archived source whose directory is a Git checkout (others are only counted) under `GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS` (default 10 s) and the entry deadline; it is always `ok` (informational) and lists totals only with each source's `live_pages` (counted in SQL before the scan), a source the budget stopped or never reached as partial (`PARTIAL, <read> of <live> live page(s) read`). Tests: `test/git-gap-census.test.ts` (PGLite and Postgres).
+- `src/core/persistence/git-gap.ts` + `src/commands/sources-git-gap.ts` + `src/commands/doctor/checks/db-ahead-of-git.ts` — git-canonical memory, wave G1 (`docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census`), read-only. `declaredDatabaseOnly` is the one predicate for pages that may not have a tracked file, tested in order: a read-only mirror source, a private page (`isPrivatePage`), an alias-private page (`isDerivationPrivate`), lineage-private (computed in SQL from `privatePagesFilterFragment`), `database_only_reason`, a `storage.db_only` prefix (`isSourceDbOnlySlug`, refusing an invalid gbrain.yml), a never-filed derive-phase page (page-prepare.ts `isNeverFiledDerivedPage`: no `source_path`/`source_uri` under `DERIVE_PHASE_DB_ONLY_DEFAULTS`), a path the checkout's Git ignores (`ignoredPaths`: filter-free `check-ignore -z --stdin`, tracked files never reported, exit 1 = none, null when Git cannot answer). The equality contract compares a committed blob with the page's export view (`readExportPage`, withdrawals overlaid; the census reads a batch's views with `readExportPages`, the same snapshots in two statements, #7617): an inline blob parsed as reconcile parses a canonical file, aligned with the stored type, subtype and #6429 stamp and compared by `reconcileCanonical` digest; a segmented page by the Git blob id of its streamed export. HEAD is read with hardened plumbing only (`readHeadTree`: one `ls-tree -r -l -z --full-tree` under the source's directory; `readBlobs`: `cat-file --batch` in calls of at most 64 MiB) and the working tree by hashing raw bytes (`worktreeBlobOid`), never `git status`/`git diff`, so no repository filter, textconv or fsmonitor runs. `gbrain sources git-gap <id> [--sample n] [--json]` (trusted local CLI, not an MCP op) puts every live page in one state (`equal`, `database_ahead`, `git_ahead` when the sync import record's `blob_oid`/`disk_blob_oid` differs from HEAD, else folded into `database_ahead` and counted in `database_ahead_without_import_record`, split by content evidence in `direction_evidence`, `declared_database_only` per class, `undeclared_database_only`, `worktree_only`, `unparseable`, `unsafe_path`), reports the working tree separately, and counts rows with no Git home (unfenced active facts, fenced facts on a missing page or a page without a committed file, links whose `link_source` is not in `DERIVED_LINK_SOURCES`, timeline rows on pages without a file), open `sync-hold` records by code and parked effect targets by kind and code. Each 256-page batch reads in its own read-only transaction. Doctor `db_ahead_of_git` runs the census per non-archived source whose directory is a Git checkout (others are only counted) under `GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS` (default 10 s) and the entry deadline; the census reads the `DOCTOR_GIT_GAP_NEWEST` (800) most recently changed live pages per source (`censusGitGap` option `newest`, keyed by `updated_at`; the census records `newest` and `newest_since`, the oldest `updated_at` it read) and the message states that window (`checked the <n> most recently changed of <live> live page(s), back to <time>`). The gap is informational (never a warning); a source the budget stopped or never reached (`PARTIAL, <read> of <live> live page(s) read`) or one that could not be compared makes the check the unknown convention (`warn`, `health: unknown`), never ok (GBRA-541). It lists totals only with each source's `live_pages` (counted in SQL before the scan). Tests: `test/git-gap-census.test.ts` (PGLite and Postgres).
- `src/core/persistence/git-declared.ts` + `src/core/persistence/git-canonical-schema.ts` (migration `git_canonical_declared`) — git-canonical memory, wave G7a: the declared database-only classes of a strict source (`sources.config.canonical = "git"`, default off). `strictPageClass` judges a page by its slug and prior file (`declaredPathClass`: `db_only_prefix` for a `storage.db_only` dir, `derive_folder` for a never-filed derive-phase page; G3's indexer reads the same function) and then its rendered content (`privacyClass`: `private`, `alias_private`, or `lineage_private` from the same SQL remote reads use, `privatePagesFilterFragment`, over the page's own values). `page-prepare.ts` `prepareFileTarget` asks it before it builds a strict file target: a declared page gets no target (no file, no door commit, no Git effect), an untracked ignored target is `git_ignored`, a page turning private gets the removal of the file it still has in the worktree or at HEAD, and a path whose `filter` attribute is `lfs` passes `assertLfsTarget` only with `storage.git_lfs` and a checkout that configures the LFS filter (`git_lfs_not_enabled`). `preparePrivateTransition` (page-prepare.ts) is that removal for other writers (GBRA-60, connector imports #7971). In `publishMutation` and `publishGroup`, `assertNoPrivateCommit` refuses a file target carrying a private page's bytes before anything is written (`git_private_commit_refused`; a group rolls back whole), and `declareStrictPublication` (after apply, before the door commit) refuses a declared page's file or an undeclared file-less page (`git_home_required`), stamps `pages.database_only_reason` and, for a privacy class, clears `source_path`/`source_uri` in the transaction of the door commit that removed the file. A managed import builds its own file target, so it meets only these publication checks. `assertStrictGitHome` is the refusal for writers with no file form yet (G4, G5). The managed writer guard (`writer-guard-schema.ts`) refuses rows of a strict source unless the writer declares `gbrain.git_protocol` (`withCoordinatedWrite` does), behind the `git_canonical_brain.strict_sources` counter kept by `sources` triggers (`git_protocol_required`, mapped in `publication-failure.ts`). The guard reads its state as the writing role and fails closed: a hidden or missing `persistence_brain` or `git_canonical_brain` row, or a source or page row hidden by row-level security, raises `writer_coordinator_required` (`managed_writer_guard:unreadable_state`), and the counter refuses a recount under RLS on `sources` (`test/writer-fence-fail-closed-7636.test.ts`). The census (`git-gap.ts`) adds `database_only_source` (a source with no checkout) and maps the stamped reasons to their own classes. Tests: `test/git-canonical-declared-g7a.test.ts` (both engines).
- `src/core/persistence/checkout-state.ts` (`readCheckoutState`) — Q1: a canonical checkout against its last fetched upstream, read-only and time-bounded (no fetch): ahead/behind, `diverged`, each commit the upstream lacks (sha, author, date, subject, paths; at most 20) and porcelain counts. `sources writer status` reports it as `checkouts`; doctor `git_convergence` adds the commits and counts for a managed checkout and warns at once on a diverged one.
- `src/core/persistence/git-door.ts`: G2, the door of git-canonical memory. A source with `sources.config.canonical = "git"` (strict, default off; set by `gbrain sources canonical <id> --to git --apply --expect <hash>`, `git-conversion.ts`) commits each published file before its database row. `publishMutation` (`coordinator.ts`) and `publishGroup` (`group-publish.ts`, one commit per group, after its lane turn) call `commitThroughDoor` under the writer lock, between the file rename and the transaction commit. It commits by plumbing without the checkout's index: `hash-object -w` per file, the trees along the changed paths rebuilt from HEAD (`cat-file tree`, `hash-object -w -t tree`), `commit-tree` with `commitGitTargets`' message, `update-ref` compare-and-swap (one rebuild if the branch moved, then a refusal), then `update-index --cacheinfo` for exactly the published paths (an entry someone staged during the write is left as it is, and the write says its commit landed). That refresh runs under Git's own index lock: `syncIndex` creates `<index>.lock` exclusively (an existing lock the #6932 proof finds abandoned is reclaimed under the caller's writer lock through `reclaimAbandonedIndexLock` in `effect-git.ts` and taken again; any other existing lock refuses with the landed failure, which says why it was not reclaimed), compares the entries, updates a hard-linked copy of the index through `GIT_INDEX_FILE`, and renames the copy onto the lock and the lock onto the index, so no writer that takes the lock can stage between the compare and the write; it also sweeps dead processes' index copies (#7755), retries win32 renames (#7756); detached HEAD and unborn branches refuse typed. Each `DoorFile` carries its planned state (`planned`: the sha256 of the bytes the publication wrote, or null for a removal), and the door commits exactly that state or nothing: the file must hash to the plan before and after `hash-object -w` (else `git_target_changed`: nothing is committed and the edit stays on disk; the write is held in recovery as `unexpected_file_bytes` when the file holds neither its bytes nor the version before it, and fails with nothing held when the file holds the version before it), and each target's index entry must equal HEAD's (else `git_index_conflict`, index untouched). An entry that still holds the version its path's last commit replaced (an interrupted door refresh) counts as clean: the write restores it to HEAD and reports the paths as `outcome.persistence.git_index_restored` and the `git_index_restored` notice (`indexRestoredNotice`, emitted by `page-mutations.ts` `emitFenceNotice`). The step deadline is sized from one stat of the index (`gitStepTimeoutMs`), and `refuseIgnored` asks `check-ignore` only about new targets `ignore-rules.ts` cannot clear. Door commits are not coalesced across single writes (each holds its worktree lock exclusively and the consumer runs one per root); a batch commits once through publishGroup. The publication stamps the commit as `outcome.persistence.git_commit` (`git_state: committed`); a target Git refuses rolls the publication back. The Git effect carries `push_only` and joins the push without staging (`effects.ts`). The recovery record carries `door` (checkout and starting HEAD); `recoverPublication` keeps a file whose commit landed (`doorCommitLanded`) instead of restoring it, and the replay completes against it: `replayAfterDoorCommit` in `publishMutation` and the strict exceptions in `page-prepare.ts` (own bytes committed, or a removal HEAD already holds). Old binaries ignore `door`; strict stays off until conversion fences them. Tests: `test/git-door-strict-gbra133.test.ts` (both engines), `test/git-door-plumbing-gbra133.test.ts`, `test/git-door-planned-state.test.ts`, `test/git-door-write-cost.test.ts`, `test/git-door-index-lock-7742.test.ts` (both engines); per-write overhead bench `scripts/bench/door-write-overhead.ts` (opt-in, smoke `test/bench-door-write-overhead.test.ts`).
diff --git a/docs/designs/GIT_CANONICAL_MEMORY.md b/docs/designs/GIT_CANONICAL_MEMORY.md
index 7c4a9c0318..e6e4c5ff11 100644
--- a/docs/designs/GIT_CANONICAL_MEMORY.md
+++ b/docs/designs/GIT_CANONICAL_MEMORY.md
@@ -94,7 +94,7 @@ G8a ships it as `gbrain sources canonical <source-id> --to git|mixed [--dry-run
## The git-gap census
-`gbrain sources git-gap <source-id> [--sample n] [--json]` is the read-only preview conversion will bind to, and doctor `db_ahead_of_git` reports its totals per source with a Git checkout (informational in G1: always ok). It compares every live page with the blob committed at HEAD, read with hardened plumbing (`ls-tree`, `cat-file --batch`, `check-ignore`), so no repository filter, textconv or hook runs. It never reads `git status` or `git diff`. Each page lands in exactly one state:
+`gbrain sources git-gap <source-id> [--sample n] [--json]` is the read-only preview conversion will bind to, and doctor `db_ahead_of_git` reports its totals per source with a Git checkout (informational in G1: the gap never warns; doctor reads the 800 most recently changed pages per source and says how far back it looked, and a census it could not finish is health unknown, never ok). It compares every live page with the blob committed at HEAD, read with hardened plumbing (`ls-tree`, `cat-file --batch`, `check-ignore`), so no repository filter, textconv or hook runs. It never reads `git status` or `git diff`. Each page lands in exactly one state:
| State | Meaning | What conversion does with it |
|---|---|---|
diff --git a/docs/guides/git-canonical.md b/docs/guides/git-canonical.md
index c01fcc8af5..73a18875d8 100644
--- a/docs/guides/git-canonical.md
+++ b/docs/guides/git-canonical.md
@@ -301,9 +301,9 @@ database-only classes, the write receipts or the other operational records.
| Where | What it tells you |
|---|---|
-| `gbrain doctor` → `git_index_lag` | Per strict source, how many commits and seconds the index trails HEAD. It warns once the oldest unindexed commit is older than 900 s (`GBRAIN_DOCTOR_GIT_INDEX_LAG_WARN_SECONDS`), and its fix is `gbrain sync --source <id> --no-pull`. Until then, search and reads show the older version. |
-| `gbrain doctor` → `strict_facts_outside_git` | Per strict source, the facts with no Git home, the facts held on a holding page for more than 30 days, and held facts that cannot move (with the reason, or the candidate pages of a bare name). It warns when any is non-zero, and its fix is the read-only preview of [`gbrain repair facts-home`](repair.md#facts-home). A source that is not strict is not judged. |
-| `gbrain doctor` → `db_ahead_of_git` | The git-gap totals for every source with a checkout, strict or not, with each source's live pages (a scan the budget stopped reads `PARTIAL, <read> of <live> live page(s) read`). Informational: always ok. Bounded by `GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS` (10 s by default). |
+| `gbrain doctor` → `git_index_lag` | Per strict source, how many commits and seconds the index trails HEAD. It warns once the oldest unindexed commit is older than 900 s (`GBRAIN_DOCTOR_GIT_INDEX_LAG_WARN_SECONDS`), and its fix is `gbrain sync --source <id> --no-pull`. Until then, search and reads show the older version. A lag it cannot read is a warning with health unknown, never ok. |
+| `gbrain doctor` → `strict_facts_outside_git` | Per strict source, the facts with no Git home, the facts held on a holding page for more than 30 days, and held facts that cannot move (with the reason, or the candidate pages of a bare name). It warns when any is non-zero, and its fix is the read-only preview of [`gbrain repair facts-home`](repair.md#facts-home). Its page walk covers the same 800 most recently changed pages as `db_ahead_of_git` and names that window; a census the budget stopped or could not run, or a fenced fact on a page older than the window, is a warning with health unknown, never ok. A source that is not strict is not judged. |
+| `gbrain doctor` → `db_ahead_of_git` | The git-gap totals for every source with a checkout, strict or not, over the 800 most recently changed pages of each source, with how far back that reached (`checked the 800 most recently changed of <live> live page(s), back to <time>`); `gbrain sources git-gap <id>` reads every page. The gap is informational and never warns; a scan the budget stopped (`PARTIAL, <read> of <live> live page(s) read`) or a source that could not be compared is a warning with health unknown, never ok. Bounded by `GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS` (10 s by default). |
| `gbrain sources git-gap <id> [--sample n] [--json]` | Each page's state against HEAD: `equal`, `database_ahead`, `git_ahead`, declared or undeclared database-only, `worktree_only`, `unparseable`, `unsafe_path`, with a sample of paths, the source's `live_pages`, and `direction_evidence` for differing pages with no import record. Read-only. |
| `gbrain sources reindex <id> --from-git` | A preview of every database version Git would replace, bound to HEAD by a hash; `--apply --expect <hash>` runs that pass. Use it to re-derive a strict source's index on purpose. |
| `gbrain sync status --source <id> --json` | The sync pass that indexes commits: state, reason and the last error. |
diff --git a/src/commands/doctor/checks/db-ahead-of-git.ts b/src/commands/doctor/checks/db-ahead-of-git.ts
index 2efc613217..e7f4310c46 100644
--- a/src/commands/doctor/checks/db-ahead-of-git.ts
+++ b/src/commands/doctor/checks/db-ahead-of-git.ts
@@ -2,17 +2,23 @@
* `db_ahead_of_git` (git-canonical memory, wave G1, docs/designs/GIT_CANONICAL_MEMORY.md): for each source with a
* checkout, the totals of the read-only git-gap census (`gbrain sources git-gap`, commands/sources-git-gap.ts): pages
* equal to their committed blob at HEAD, database_ahead or git_ahead of it, declared or undeclared database-only, only in
- * the working tree, unparseable. Informational in this release: always ok whatever the gap, because nothing converts a
- * source yet. Bounded by `GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS` (default 10 s) and the entry's deadline; a source the budget
- * stopped or never reached is listed as partial; a source whose directory is not a Git checkout is only counted. Totals
- * only, never a slug or path.
+ * the working tree, unparseable. Informational in this release: ok whatever the gap, because nothing converts a source yet.
+ * GBRA-541: the census reads the `DOCTOR_GIT_GAP_NEWEST` most recently changed live pages per source (an uncommitted
+ * database write is among them) and states that window as the oldest `updated_at` it read; `gbrain sources git-gap` reads
+ * them all. Bounded by `GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS` (default 10 s) and the entry's deadline; a source the budget
+ * stopped or never reached, or one the census could not read, makes the check the unknown convention (`warn`,
+ * `health: unknown`), never ok. A source whose directory is not a Git checkout is only counted. Totals only, never a
+ * slug or path.
*/
import { existsSync } from 'node:fs';
import type { Check } from '../../doctor.ts';
import { scanDeadline } from '../budget.ts';
+import { boundUnknownDetails } from '../bounded-unknown.ts';
import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';
import { censusGitGap, GIT_GAP_DOCS, type GitGapCensus } from '../../sources-git-gap.ts';
import { isGitCheckout } from '../../../core/persistence/git-gap.ts';
+import { currentStatementDeadline } from '../../../core/statement-deadline.ts';
+import type { BrainEngine } from '../../../core/engine.ts';
/** `GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS` (default 10 s): the wall-clock bound of the census across every source. */
export function gitGapScanTimeoutMs(): number {
@@ -20,7 +26,35 @@ export function gitGapScanTimeoutMs(): number {
return Number.isFinite(n) && n > 0 ? n : 10_000;
}
-type SourceTotals = Pick<GitGapCensus, 'source_id' | 'complete' | 'pages' | 'live_pages' | 'states' | 'declared' | 'worktree'>;
+/**
+ * GBRA-541: the most recently changed live pages per source the doctor census reads: about half the 10 s scan bound (800
+ * pages took 4.7 to 5.4 s on a synthetic 300,000-page Postgres brain, 4 cores); `gbrain sources git-gap <id>` reads every page.
+ */
+export const DOCTOR_GIT_GAP_NEWEST = 800;
+
+type SourceTotals = Pick<GitGapCensus, 'source_id' | 'complete' | 'pages' | 'live_pages' | 'newest' | 'newest_since' | 'states' | 'declared' | 'worktree'>;
+
+/**
+ * The doctor's newest-pages census of one source, read once per run: a complete census is kept in the run's memo, so
+ * `strict_facts_outside_git` reuses the one `db_ahead_of_git` read instead of walking the same pages again. A partial
+ * one is never kept.
+ */
+export async function doctorGitGapCensus(engine: BrainEngine, sourceId: string, deadlineAt: number): Promise<GitGapCensus> {
+ const memo = currentStatementDeadline()?.memo;
+ const key = `git_gap_census:${sourceId}`;
+ const kept = memo?.get(key) as Promise<GitGapCensus> | undefined;
+ if (kept) return kept;
+ const census = await censusGitGap(engine, sourceId, { sample: 0, deadlineAt, newest: DOCTOR_GIT_GAP_NEWEST });
+ if (census.complete) memo?.set(key, Promise.resolve(census));
+ return census;
+}
+
+/** What a doctor census covered: every live page, or the newest window back to its oldest `updated_at`. */
+export function censusWindow(source: Pick<GitGapCensus, 'complete' | 'pages' | 'live_pages' | 'newest_since'>): string {
+ if (!source.complete) return `PARTIAL, ${source.pages} of ${source.live_pages} live page(s) read`;
+ if (source.pages >= source.live_pages) return `${source.live_pages} live page(s)`;
+ return `checked the ${source.pages} most recently changed of ${source.live_pages} live page(s), back to ${source.newest_since}`;
+}
const nonzero = (record: Record<string, number>) => Object.entries(record).filter(([, n]) => n > 0).map(([k, n]) => `${n} ${k}`).join(', ') || 'no pages';
@@ -36,26 +70,27 @@ async function runDbAheadOfGit(ctx: DoctorContext): Promise<Check[]> {
for (const row of withCheckout) {
if (Date.now() >= deadlineAt) { unread.push(row.id); continue; }
try {
- const { source_id, complete, pages, live_pages, states, declared, worktree } = await censusGitGap(engine, row.id, { sample: 0, deadlineAt });
- sources.push({ source_id, complete, pages, live_pages, states, declared, worktree });
+ const { source_id, complete, pages, live_pages, newest, newest_since, states, declared, worktree } = await doctorGitGapCensus(engine, row.id, deadlineAt);
+ sources.push({ source_id, complete, pages, live_pages, newest, newest_since, states, declared, worktree });
} catch (error) {
errors.push({ source_id: row.id, message: error instanceof Error ? error.message : String(error) });
}
}
const partial = [...sources.filter(source => !source.complete).map(source => source.source_id), ...unread];
+ const unknown = partial.length > 0 || errors.length > 0;
const details = { informational: true, sources, partial_sources: partial, errors, sources_without_git_checkout: rows.length - withCheckout.length,
- timeout_ms: gitGapScanTimeoutMs(), docs: GIT_GAP_DOCS };
- const listed = sources.map(source => `${source.source_id}: ${source.complete ? `${source.live_pages} live page(s)` : `PARTIAL, ${source.pages} of ${source.live_pages} live page(s) read`}, ${nonzero(source.states)}`);
+ newest: DOCTOR_GIT_GAP_NEWEST, timeout_ms: gitGapScanTimeoutMs(), docs: GIT_GAP_DOCS, ...(partial.length ? boundUnknownDetails('git_gap_timeout') : errors.length ? { health: 'unknown' } : {}) };
+ const listed = sources.map(source => `${source.source_id}: ${censusWindow(source)}, ${nonzero(source.states)}`);
const message = withCheckout.length
- ? `Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout.${listed.length ? ` ${listed.join('; ')}.` : ''}`
+ ? `${unknown ? 'Health unknown, not clear (a source was not read in full or could not be compared):' : 'Informational, nothing to do:'} the database compared with the commit at HEAD, per source with a Git checkout.${listed.length ? ` ${listed.join('; ')}.` : ''}`
+ `${unread.length ? ` Not reached within the ${details.timeout_ms / 1000}s budget: ${unread.join(', ')}.` : ''}`
+ `${errors.length ? ` Could not compare: ${errors.map(e => `${e.source_id} (${e.message})`).join('; ')}.` : ''}`
+ ` Page detail: gbrain sources git-gap <source-id>.`
: 'No source has a Git checkout, so there is no commit to compare the database with.';
- checks.push({ name: 'db_ahead_of_git', status: 'ok', details, message });
+ checks.push({ name: 'db_ahead_of_git', status: unknown ? 'warn' : 'ok', details, message });
} catch (error) {
- checks.push({ name: 'db_ahead_of_git', status: 'ok', details: { informational: true, health: 'unknown', docs: GIT_GAP_DOCS },
- message: `Informational: the git-gap census could not run (${error instanceof Error ? error.message : String(error)}); run gbrain sources git-gap <source-id> for one source.` });
+ checks.push({ name: 'db_ahead_of_git', status: 'warn', details: { informational: true, health: 'unknown', docs: GIT_GAP_DOCS },
+ message: `Health unknown, not clear: the git-gap census could not run (${error instanceof Error ? error.message : String(error)}); run gbrain sources git-gap <source-id> for one source.` });
}
return checks;
}
diff --git a/src/commands/doctor/checks/git-index-lag.ts b/src/commands/doctor/checks/git-index-lag.ts
index 7496c8125e..8c5979a1dc 100644
--- a/src/commands/doctor/checks/git-index-lag.ts
+++ b/src/commands/doctor/checks/git-index-lag.ts
@@ -4,7 +4,8 @@
* commit a finished sync pass indexed (`sources.last_commit`) and the seconds since the oldest of them was committed
* (sync-freshness.ts `readGitBehind`). Warns when that oldest commit is older than
* `GBRAIN_DOCTOR_GIT_INDEX_LAG_WARN_SECONDS` (default 900) or the source was never indexed; the fix is the sync that indexes
- * it. A source that is not strict is not read. Counts and seconds only, never a sha or path.
+ * it. A source that is not strict is not read; a lag that cannot be read at all is the unknown convention (`warn`,
+ * `health: unknown`), never ok. Counts and seconds only, never a sha or path.
*/
import { existsSync } from 'node:fs';
import type { Check } from '../../doctor.ts';
@@ -60,7 +61,7 @@ async function runGitIndexLag(ctx: DoctorContext): Promise<Check[]> {
why: `Indexes the commits of ${first} that the database has not read yet; the sync reads committed blobs only and Git wins. Repeat for each source in details.sources.`,
verify: doctorVerify('git_index_lag') } });
} catch (error) {
- checks.push({ name: 'git_index_lag', status: 'ok', details: { health: 'unknown', docs: DOCS },
+ checks.push({ name: 'git_index_lag', status: 'warn', details: { health: 'unknown', docs: DOCS },
message: `Could not read the index lag of strict sources (${error instanceof Error ? error.message : String(error)}); gbrain sources status --json shows each source's watermark.` });
}
return checks;
diff --git a/src/commands/doctor/checks/strict-facts-outside-git.ts b/src/commands/doctor/checks/strict-facts-outside-git.ts
index a3e38de3be..8fb3a73ea4 100644
--- a/src/commands/doctor/checks/strict-facts-outside-git.ts
+++ b/src/commands/doctor/checks/strict-facts-outside-git.ts
@@ -5,17 +5,21 @@
* them, or a bare name two pages match, named as candidates). Ok when all are 0. Otherwise a warning with the
* counts by group (facts/facts-home.ts), any `held_fact_unmovable` rows with their reason, and the read-only preview of
* `gbrain repair facts-home` as the fix. A source that is not strict is not judged (its database keeps such facts by
- * design); `db_ahead_of_git` stays informational. Bounded by the same budget as the census (`GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS`).
+ * design); `db_ahead_of_git` stays informational. Bounded by the same budget as the census (`GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS`); the page walk reads
+ * the `DOCTOR_GIT_GAP_NEWEST` most recently changed pages per source and the message states that window (GBRA-541). A census the
+ * budget stopped, or one that could not run, is the unknown convention (`warn`, `health: unknown`), never ok, and so is a fenced fact on a
+ * page older than the window, whose file the census did not look for.
*/
import type { Check } from '../../doctor.ts';
import { scanDeadline } from '../budget.ts';
+import { boundUnknownDetails } from '../bounded-unknown.ts';
import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';
import { doctorVerify } from '../check-fix.ts';
-import { censusGitGap, factsWithoutGitHome } from '../../sources-git-gap.ts';
+import { factsWithoutGitHome } from '../../sources-git-gap.ts';
import { FACTS_HOME_DOCS, factsHomePreviewCommand, scanFactsHome, type FactsHomeGroup } from '../../../core/facts/facts-home.ts';
-import { gitGapScanTimeoutMs } from './db-ahead-of-git.ts';
+import { censusWindow, doctorGitGapCensus, gitGapScanTimeoutMs } from './db-ahead-of-git.ts';
-interface SourceFacts { source_id: string; complete: boolean; outside_git: number; held_over_30_days: number; groups: Partial<Record<FactsHomeGroup, number>>;
+interface SourceFacts { source_id: string; complete: boolean; window: string; outside_git: number; facts_on_unread_pages: number; held_over_30_days: number; groups: Partial<Record<FactsHomeGroup, number>>;
held_fact_unmovable: Array<{ code: 'held_fact_unmovable'; fact_id: number; entity_slug: string | null; reason: string }> }
async function runStrictFactsOutsideGit(ctx: DoctorContext): Promise<Check[]> {
@@ -32,9 +36,10 @@ async function runStrictFactsOutsideGit(ctx: DoctorContext): Promise<Check[]> {
const deadlineAt = scanDeadline(ctx, gitGapScanTimeoutMs());
const sources: SourceFacts[] = [];
for (const row of rows) {
- const census = await censusGitGap(engine, row.id, { sample: 0, deadlineAt });
+ const census = await doctorGitGapCensus(engine, row.id, deadlineAt);
const scan = await scanFactsHome(engine, row.id);
- sources.push({ source_id: row.id, complete: census.complete, outside_git: factsWithoutGitHome(census.rows_without_git_home),
+ sources.push({ source_id: row.id, complete: census.complete, window: censusWindow(census), outside_git: factsWithoutGitHome(census.rows_without_git_home),
+ facts_on_unread_pages: census.facts_on_unread_pages ?? 0,
held_over_30_days: scan.counts.held_over_30_days,
groups: Object.fromEntries(Object.entries(scan.counts).filter(([, n]) => n > 0)),
held_fact_unmovable: scan.rows.filter(r => r.group === 'held_fact_unmovable').slice(0, 20)
@@ -42,9 +47,23 @@ async function runStrictFactsOutsideGit(ctx: DoctorContext): Promise<Check[]> {
}
const details = { sources, docs: FACTS_HOME_DOCS };
const flagged = sources.filter(source => source.outside_git > 0 || source.held_over_30_days > 0 || source.held_fact_unmovable.length > 0);
+ const partial = sources.filter(source => !source.complete);
+ if (!flagged.length && partial.length) {
+ checks.push({ name: 'strict_facts_outside_git', status: 'warn', details: { ...details, ...boundUnknownDetails('git_gap_timeout') },
+ message: `Health unknown, not clear: the census of ${partial.map(s => `${s.source_id} (${s.window})`).join(', ')} stopped at its ${gitGapScanTimeoutMs() / 1000}s budget, so facts on pages it did not read were not judged. `
+ + 'Count every page with gbrain sources git-gap <source-id>.' });
+ return checks;
+ }
+ const unread = sources.filter(source => source.facts_on_unread_pages > 0);
+ if (!flagged.length && unread.length) {
+ checks.push({ name: 'strict_facts_outside_git', status: 'warn', details: { ...details, ...boundUnknownDetails('git_gap_newest') },
+ message: `Health unknown, not clear: ${unread.map(s => `${s.source_id} has ${s.facts_on_unread_pages} fenced fact(s) on pages older than its census window (${s.window})`).join('; ')}, so whether those pages have a committed file was not checked. `
+ + 'Count every page with gbrain sources git-gap <source-id>.' });
+ return checks;
+ }
if (!flagged.length) {
checks.push({ name: 'strict_facts_outside_git', status: 'ok', details,
- message: `Every fact of each strict source has a Git home and none has been held for more than 30 days: ${sources.map(s => `${s.source_id}${s.complete ? '' : ' (census partial)'}`).join(', ')}.` });
+ message: `Every fact of each strict source has a Git home and none has been held for more than 30 days: ${sources.map(s => `${s.source_id} (${s.window})`).join(', ')}.` });
return checks;
}
const describe = (source: SourceFacts) => `${source.source_id}: ${source.outside_git} fact(s) without a Git home${source.complete ? '' : ' (census partial)'}, `
@@ -58,7 +77,7 @@ async function runStrictFactsOutsideGit(ctx: DoctorContext): Promise<Check[]> {
why: `Lists the facts of ${first} without a Git home by group, read-only; its --apply --expect <hash> writes the ones it can to memory/unattributed. Repeat for each source in details.sources.`,
verify: doctorVerify('strict_facts_outside_git') } });
} catch (error) {
- checks.push({ name: 'strict_facts_outside_git', status: 'ok', details: { health: 'unknown', docs: FACTS_HOME_DOCS },
+ checks.push({ name: 'strict_facts_outside_git', status: 'warn', details: { health: 'unknown', docs: FACTS_HOME_DOCS },
message: `Could not count the facts of strict sources without a Git home (${error instanceof Error ? error.message : String(error)}); gbrain sources git-gap <source-id> counts them for one source.` });
}
return checks;
diff --git a/src/commands/doctor/registry.ts b/src/commands/doctor/registry.ts
index 8d6df54752..96d175ff9a 100644
--- a/src/commands/doctor/registry.ts
+++ b/src/commands/doctor/registry.ts
@@ -244,6 +244,12 @@ export const DOCTOR_CHECK_REGISTRY: readonly DoctorEntry[] = [
pgvectorEntry,
// #7276: the privacy check next, with its own entry budget, before any full scan.
derivedVisibilityEntry,
+ // GBRA-541: then the checks that catch a lost write (LOST_WRITE_CHECKS), bounded, before any full scan uses the budget.
+ gitIndexLagEntry,
+ dbAheadOfGitEntry,
+ strictFactsOutsideGitEntry,
+ ownerHostStaleEntry,
+ uncommittedSyncDeletionsEntry,
memberAccessEntry,
folderAccessEntry,
unlabeledPeopleFoldersEntry,
@@ -349,7 +355,6 @@ export const DOCTOR_CHECK_REGISTRY: readonly DoctorEntry[] = [
derivedOriginParkedEntry,
derivationPurgeSweepsEntry,
missingRecordedFilesEntry,
- uncommittedSyncDeletionsEntry,
unindexedFilesEntry,
overwrittenEditsEntry,
rowsBehindEntry,
@@ -358,17 +363,11 @@ export const DOCTOR_CHECK_REGISTRY: readonly DoctorEntry[] = [
managedSyncConvergenceEntry,
// #7160: title-prefixed person pages next to the unprefixed page (read-only, preview-first).
personTitleDuplicatesEntry,
- // Git-canonical G1: the read-only git-gap census totals per source with a checkout (informational, always ok).
- dbAheadOfGitEntry,
- // Git-canonical G3: how far each strict source's index trails the commit at HEAD.
- gitIndexLagEntry,
- strictFactsOutsideGitEntry,
// GST-1601: the one-sided local edits adopted in the last 24 h per source (informational, always ok).
localEditAdoptionsEntry,
// GBRA-221: live fence rows on imported pages whose body is outside-authored text (review only).
outsideContentFencesEntry,
- // GBRA-248 W0: writes waiting on a long-quiet owner host, and a file plane that disables embeddings over a database with vectors.
- ownerHostStaleEntry,
+ // GBRA-248 W0: a file plane that disables embeddings over a database with vectors (owner_host_stale runs with LOST_WRITE_CHECKS).
embeddingPlaneDisagreementEntry,
// #6770: MCP request-log size and the opt-in retention prune (read-only; the enable fix asks the user).
mcpRequestLogRetentionEntry,
@@ -389,6 +388,14 @@ export const CHEAP_INCIDENT_CHECKS: ReadonlySet<string> = new Set([
'sync_landing_gaps',
]);
+/**
+ * GBRA-541: checks that catch a write the database holds and Git does not (or that waits on a host that never commits it):
+ * written-but-uncommitted pages and facts, an index behind its commits, writes held on a quiet owner, deletions Git never
+ * held. Each is bounded, and every entry that emits one runs right after the privacy check, before the full scans, so a
+ * large brain's slow scans cannot use up the budget first (test/doctor-entry-deadline-6803.test.ts).
+ */
+export const LOST_WRITE_CHECKS: ReadonlySet<string> = new Set(['git_index_lag', 'db_ahead_of_git', 'strict_facts_outside_git', 'owner_host_stale', 'uncommitted_sync_deletions']);
+
const CONNECTION_LANE: ReadonlySet<DoctorEntry> = new Set([offlineConnectionEntry, dbChecksGateEntry, connectionEntry, connectionGateEntry]);
/** Every check name the registry can emit (the `--only` vocabulary). */
diff --git a/src/commands/sources-git-gap.ts b/src/commands/sources-git-gap.ts
index c19a57e3e3..d0c39f4424 100644
--- a/src/commands/sources-git-gap.ts
+++ b/src/commands/sources-git-gap.ts
@@ -57,8 +57,14 @@ export interface GitGapCensus {
head: string | null;
/** False when a doctor budget stopped the page scan; the counts cover the pages read so far. */
complete: boolean;
- /** Pages the scan read; equals `live_pages` only when `complete`. */
+ /** Pages the scan read; equals `live_pages` only when `complete` and the scan was not capped by `newest`. */
pages: number;
+ /** The cap of a census that read only the newest live pages by `updated_at` (doctor); absent for a full census. */
+ newest?: number;
+ /** With `newest`: the oldest `updated_at` among the pages it selected, so a reader sees how far back it looked (null: no page). */
+ newest_since?: string | null;
+ /** With `newest`: fenced fact rows on live pages outside that window, whose file the census did not look for. */
+ facts_on_unread_pages?: number;
/** The source's live pages, counted in SQL before the scan, so a partial scan's `pages` reads against the whole source. */
live_pages: number;
states: Record<PageState, number>;
@@ -142,7 +148,7 @@ const refuse = (message: string, suggestion: string) => new OperationError('stor
* page (a page read with `evidence` comes without it, after the scan). `evidence` (d4) reads which side moved for the
* pages that differ with no import record, in one history walk after the scan; a scan the deadline stopped reads none.
*/
-export async function censusGitGap(engine: BrainEngine, sourceId: string, opts: { sample: number; deadlineAt?: number; collect?: GitGapCollect; evidence?: boolean }): Promise<GitGapCensus> {
+export async function censusGitGap(engine: BrainEngine, sourceId: string, opts: { sample: number; deadlineAt?: number; collect?: GitGapCollect; evidence?: boolean; newest?: number }): Promise<GitGapCensus> {
await resolveSourceId(engine, sourceId, undefined, { skipLocalSignals: true });
const [source] = await engine.executeRaw<{ local_path: string | null; incarnation: string }>('SELECT local_path, incarnation::text AS incarnation FROM sources WHERE id=$1', [sourceId]);
const root = source?.local_path && existsSync(source.local_path) ? source.local_path : null;
@@ -163,18 +169,34 @@ export async function censusGitGap(engine: BrainEngine, sourceId: string, opts:
const pending: Unrecorded[] = [];
// G7a: a source with no checkout is a database-only source, one declared class for all its pages (outside strict mode).
const policy = { mirror, databaseOnlySource: root === null, dbOnly: (slug: string) => root !== null && isSourceDbOnlySlug(root, slug, 'refuse'), ignored: new Set<string>() };
- for (let cursor = '0'; ;) {
+ let newest: string[] | null = null;
+ if (opts.newest !== undefined) {
+ const { rows, unread } = await engine.transaction(async tx => {
+ await tx.executeRaw('SET TRANSACTION READ ONLY');
+ const rows = await tx.executeRaw<{ id: string; updated_at: string }>(`SELECT id::text, to_char(updated_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS updated_at
+ FROM pages WHERE source_id=$1 AND deleted_at IS NULL ORDER BY updated_at DESC, id DESC LIMIT $2`, [sourceId, opts.newest]);
+ const [unread] = await tx.executeRaw<{ n: number }>(`SELECT count(*)::int AS n FROM facts f
+ JOIN pages p ON p.source_id=f.source_id AND p.slug=f.source_markdown_slug AND p.deleted_at IS NULL
+ WHERE f.source_id=$1 AND f.row_num IS NOT NULL AND NOT (p.id = ANY($2::bigint[]))`, [sourceId, rows.map(row => row.id)]);
+ return { rows, unread: Number(unread?.n ?? 0) };
+ });
+ newest = rows.map(row => row.id);
+ Object.assign(census, { newest: opts.newest, newest_since: rows.at(-1)?.updated_at ?? null, facts_on_unread_pages: unread });
+ }
+ for (let cursor = '0', offset = 0; ;) {
if (opts.deadlineAt !== undefined && Date.now() >= opts.deadlineAt) { census.complete = false; break; }
const done = await engine.transaction(async tx => {
await tx.executeRaw('SET TRANSACTION READ ONLY');
const batch = await tx.executeRaw<Key>(`SELECT id::text, slug, source_id, source_path, octet_length(source_path) AS source_path_bytes, source_uri, withheld_source_path, type, frontmatter,
database_only_reason, body_storage='segmented' AS segmented, knowledge_revision::text AS revision, NOT ${privacyPartSql('pages')} AS lineage_private
- FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND pages.id > $2::bigint ORDER BY pages.id LIMIT ${BATCH}`, [sourceId, cursor]);
+ FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND ${newest ? 'pages.id = ANY($2::bigint[])' : 'pages.id > $2::bigint'} ORDER BY pages.id LIMIT ${BATCH}`,
+ [sourceId, newest ? newest.slice(offset, offset + BATCH) : cursor]);
if (batch.length) {
await censusBatch(tx, batch, census, { checkout, policy, incarnation: source!.incarnation, sample: opts.sample, collect: opts.collect, pending: opts.evidence ? pending : undefined });
cursor = batch[batch.length - 1]!.id;
}
- return batch.length < BATCH;
+ offset += BATCH;
+ return newest ? offset >= newest.length : batch.length < BATCH;
});
if (done) break;
}
diff --git a/test/doctor-entry-deadline-6803.test.ts b/test/doctor-entry-deadline-6803.test.ts
index 37cbd1f343..ae499143ab 100644
--- a/test/doctor-entry-deadline-6803.test.ts
+++ b/test/doctor-entry-deadline-6803.test.ts
@@ -26,7 +26,7 @@ import postgres from '#postgres';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { buildChecks, type Check } from '../src/commands/doctor.ts';
-import { CHEAP_INCIDENT_CHECKS, DOCTOR_CHECK_REGISTRY, runDoctorRegistry } from '../src/commands/doctor/registry.ts';
+import { CHEAP_INCIDENT_CHECKS, DOCTOR_CHECK_REGISTRY, LOST_WRITE_CHECKS, runDoctorRegistry } from '../src/commands/doctor/registry.ts';
import { connectionGateEntry } from '../src/commands/doctor/checks/db-connection.ts';
import { frontmatterEntry } from '../src/commands/doctor/checks/content-quality.ts';
import { homeDirInWorktreeEntry } from '../src/commands/doctor/checks/local-audits.ts';
@@ -103,6 +103,18 @@ test('C2: every entry that emits a cheap incident check runs before the first fu
expect([...CHEAP_INCIDENT_CHECKS].filter((n) => !emitted.has(n))).toEqual([]);
});
+test('GBRA-541: every entry that emits a lost-write check runs right after the privacy check, before the full scans', () => {
+ const gate = DOCTOR_CHECK_REGISTRY.indexOf(connectionGateEntry);
+ const after = DOCTOR_CHECK_REGISTRY.slice(gate + 1);
+ const lostWrite = (e: DoctorEntry) => e.emits.some((n) => LOST_WRITE_CHECKS.has(n));
+ const early = (e: DoctorEntry) => e.tier === 'ops' || e.emits.some((n) => CHEAP_INCIDENT_CHECKS.has(n) || n === 'derived_visibility') || lostWrite(e);
+ const firstOther = after.findIndex((e) => !early(e));
+ expect(firstOther).toBeGreaterThan(0);
+ expect(after.slice(firstOther).filter(lostWrite).map((e) => e.name)).toEqual([]);
+ const emitted = new Set(DOCTOR_CHECK_REGISTRY.flatMap((e) => e.emits));
+ expect([...LOST_WRITE_CHECKS].filter((n) => !emitted.has(n))).toEqual([]);
+});
+
test('#8979: a local probe that hangs is killed at its entry deadline instead of blocking the run past it', async () => {
const bin = mkdtempSync(join(tmpdir(), 'gbrain-8979-bin-'));
const pids = join(bin, 'pids');
diff --git a/test/doctor-strict-facts-outside-git.test.ts b/test/doctor-strict-facts-outside-git.test.ts
index 9d0da8e29a..fc98b9b6f5 100644
--- a/test/doctor-strict-facts-outside-git.test.ts
+++ b/test/doctor-strict-facts-outside-git.test.ts
@@ -14,9 +14,11 @@ import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import type { DoctorContext } from '../src/commands/doctor/context.ts';
import { strictFactsOutsideGitEntry } from '../src/commands/doctor/checks/strict-facts-outside-git.ts';
+import { DOCTOR_GIT_GAP_NEWEST } from '../src/commands/doctor/checks/db-ahead-of-git.ts';
import { durableGitRepo } from './helpers/git-publication.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
+import { withEnv } from './helpers/with-env.ts';
const gitRepo = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };
const check = async (engine: BrainEngine) => ((await strictFactsOutsideGitEntry.run({ engine, progress: { heartbeat() {} }, args: [] } as unknown as DoctorContext)) as Array<Record<string, any>>)
@@ -46,4 +48,31 @@ for (const backend of testBackends()) describe(`[${backend}] doctor strict_facts
expect(result.fix).toMatchObject({ argv: ['gbrain', 'repair', 'facts-home', '--source', 'default', '--json'], consent: [], actor: 'agent' });
expect(result.details.sources).toMatchObject([{ source_id: 'default', outside_git: 1, groups: { entity_page_missing: 1 } }]);
}, { databaseUrl, setup: gitRepo }), 180_000);
+
+ test('GBRA-541: a strict source whose census the budget stopped is health unknown, never ok', () => managedBrain(async ({ engine }) => {
+ await engine.executeRaw(`UPDATE sources SET config = config || '{"canonical":"git"}'::jsonb WHERE id='default'`);
+ const result = (await withEnv({ GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS: '1' }, () => strictFactsOutsideGitEntry.run({ engine, progress: { heartbeat() {} }, args: [],
+ entryDeadlineAt: Date.now() } as unknown as DoctorContext)) as Array<Record<string, any>>).find(c => c.name === 'strict_facts_outside_git')!;
+ expect(result.status).toBe('warn');
+ expect(result.details).toMatchObject({ health: 'unknown', reason: 'bound', bound: 'git_gap_timeout' });
+ expect(result.message).toContain('Health unknown, not clear');
+ }, { databaseUrl, setup: gitRepo }), 180_000);
+
+ test('GBRA-541: a fenced fact on a page older than the census window is health unknown, never ok', () => managedBrain(async ({ engine }) => {
+ await engine.executeRaw(`UPDATE sources SET config = config || '{"canonical":"git"}'::jsonb WHERE id='default'`);
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
+ try {
+ await engine.executeRaw(`INSERT INTO pages(source_id, slug, type, title, compiled_truth, timeline, frontmatter, updated_at)
+ VALUES ('default', 'notes/porch-repair', 'note', 'Porch repair', 'plain text', '', '{}'::jsonb, now() - make_interval(days => 30))`);
+ await engine.executeRaw(`INSERT INTO pages(source_id, slug, type, title, compiled_truth, timeline, frontmatter)
+ SELECT 'default', 'notes/n-' || g, 'note', 'n', 'plain text', '', '{}'::jsonb FROM generate_series(1, ${DOCTOR_GIT_GAP_NEWEST}) g`);
+ await engine.insertFact({ fact: 'The porch repair is booked for May.', kind: 'fact', entity_slug: 'notes/porch-repair', visibility: 'world', source: 'legacy import' } as never, { source_id: 'default' });
+ await engine.executeRaw(`UPDATE facts SET row_num=1, source_markdown_slug='notes/porch-repair' WHERE source_id='default' AND fact='The porch repair is booked for May.'`);
+ } finally { await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1'); }
+ const result = await check(engine);
+ expect(result.status).toBe('warn');
+ expect(result.details).toMatchObject({ health: 'unknown', reason: 'bound', bound: 'git_gap_newest' });
+ expect(result.details.sources).toMatchObject([{ source_id: 'default', complete: true, facts_on_unread_pages: 1 }]);
+ expect(result.message).toContain('1 fenced fact(s) on pages older than');
+ }, { databaseUrl, setup: gitRepo }), 180_000);
});
diff --git a/test/fixtures/goldens/doctor/content-pglite-human.json b/test/fixtures/goldens/doctor/content-pglite-human.json
index 1d15c1f7ed..1e97a1777d 100644
--- a/test/fixtures/goldens/doctor/content-pglite-human.json
+++ b/test/fixtures/goldens/doctor/content-pglite-human.json
@@ -79,6 +79,11 @@
" [OK] links_link_source_check: links_link_source_check has the v114 kebab-case gate",
" [OK] pglite_scale: PGLite at 5 pages — comfortable below the 1000-page threshold",
" [OK] derived_visibility: Every derived page and fact carries a visibility no looser than its source, and no page relies on a privacy alias alone.",
+ " [OK] git_index_lag: No source is strict (git-canonical), so no index trails a commit.",
+ " [OK] db_ahead_of_git: Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 5 live page(s), 5 equal. Page detail: gbrain sources git-gap <source-id>.",
+ " [OK] strict_facts_outside_git: No source is strict (git-canonical), so no fact is required to have a Git home.",
+ " [OK] owner_host_stale: No managed write is waiting on an owner host.",
+ " [OK] uncommitted_sync_deletions: No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
" [INFO] access_readers_malformed: Not applicable: no page names readers and no member exists.",
" [INFO] access_unknown_readers: Not applicable: no page names readers and no member exists.",
" [INFO] access_recent_narrowings: Not applicable: no page names readers and no member exists.",
@@ -269,18 +274,13 @@
" [OK] derived_origin_parked: No soft-deleted page is kept from the purge to keep a page derived from it private.",
" [OK] derivation_purge_sweeps: No fact purge has a sweep of stored derivation results pending or stalled.",
" [INFO] missing_recorded_files: Not applicable: no source is a classic checkout on this host (managed sources are checked by ghost_pages).",
- " [OK] uncommitted_sync_deletions: No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
" [INFO] unindexed_files: Unindexed files are not known for default (not computed yet), notes (not computed yet). The maintenance phase unindexed_files computes them on each run and continues an incomplete scan; to compute them now, run gbrain sources retry-held <id> --unindexed.",
" [OK] sync_overwritten_db_edits: No page shows a database edit that a sync import overwrote.",
" [INFO] sync_rows_behind_checkpoint: Not applicable: no managed source has a checkout and a sync checkpoint here (a repo-less brain keeps its pages in the database, which is the record).",
" [OK] sync_config_keys: No retired sync config key is stored on this brain.",
" [OK] person_title_duplicates: No title-prefixed person page pairs with an unprefixed page (0 titled page(s) examined).",
- " [OK] db_ahead_of_git: Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 5 live page(s), 5 equal. Page detail: gbrain sources git-gap <source-id>.",
- " [OK] git_index_lag: No source is strict (git-canonical), so no index trails a commit.",
- " [OK] strict_facts_outside_git: No source is strict (git-canonical), so no fact is required to have a Git home.",
" [OK] local_edit_adoptions: No local edit was adopted in the last 24 h.",
" [OK] outside_content_fences: No fact, take or link is indexed from a fence on an imported email, calendar, GitHub or transcript page.",
- " [OK] owner_host_stale: No managed write is waiting on an owner host.",
" [OK] embedding_plane_disagreement: The config file disables embeddings and the database holds no vectors.",
" [INFO] mcp_request_log_retention: The MCP request log holds 0 row(s) (0.0 MB); request-log retention is off, so it keeps every request.",
" [INFO] storage_manifest: No storage shelf and no interim storage records on this brain.",
diff --git a/test/fixtures/goldens/doctor/content-pglite-json.json b/test/fixtures/goldens/doctor/content-pglite-json.json
index 99b8750947..07a44f5741 100644
--- a/test/fixtures/goldens/doctor/content-pglite-json.json
+++ b/test/fixtures/goldens/doctor/content-pglite-json.json
@@ -1004,6 +1004,134 @@
"name": "derived_visibility",
"status": "ok"
},
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
+ "sources": [],
+ "warn_seconds": 900
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no index trails a commit.",
+ "name": "git_index_lag",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
+ "errors": [],
+ "informational": true,
+ "newest": 800,
+ "partial_sources": [],
+ "sources": [
+ {
+ "complete": true,
+ "declared": {
+ "alias_private": 0,
+ "database_only": 0,
+ "database_only_source": 0,
+ "db_only_prefix": 0,
+ "derive_folder": 0,
+ "git_ignored": 0,
+ "lineage_private": 0,
+ "mirror_source": 0,
+ "private": 0
+ },
+ "live_pages": 5,
+ "newest": 800,
+ "newest_since": "<ts>",
+ "pages": 5,
+ "source_id": "notes",
+ "states": {
+ "database_ahead": 0,
+ "declared_database_only": 0,
+ "equal": 5,
+ "git_ahead": 0,
+ "undeclared_database_only": 0,
+ "unparseable": 0,
+ "unsafe_path": 0,
+ "worktree_only": 0
+ },
+ "worktree": {
+ "absent": 0,
+ "clean": 0,
+ "deleted": 0,
+ "modified": 5,
+ "untracked": 0
+ }
+ }
+ ],
+ "sources_without_git_checkout": 1,
+ "timeout_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 5 live page(s), 5 equal. Page detail: gbrain sources git-gap <source-id>.",
+ "name": "db_ahead_of_git",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/guides/repair.md#facts-home",
+ "sources": []
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
+ "name": "strict_facts_outside_git",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "count": 0,
+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",
+ "stale": [],
+ "stale_after_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No managed write is waiting on an owner host.",
+ "name": "owner_host_stale",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "by_source": [
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "default",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "notes",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ }
+ ],
+ "count": 0,
+ "docs": "docs/guides/repair.md#uncommitted-deletions",
+ "exact": true,
+ "other_writer_count": 0,
+ "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
+ "samples": [],
+ "truncated": false
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
+ "name": "uncommitted_sync_deletions",
+ "status": "ok"
+ },
{
"category": "brain",
"elapsed_ms": "<volatile>",
@@ -3787,44 +3915,6 @@
"severity": "info",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "by_source": [
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "default",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "notes",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- }
- ],
- "count": 0,
- "docs": "docs/guides/repair.md#uncommitted-deletions",
- "exact": true,
- "other_writer_count": 0,
- "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
- "samples": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
- "name": "uncommitted_sync_deletions",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -3990,80 +4080,6 @@
"name": "person_title_duplicates",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
- "errors": [],
- "informational": true,
- "partial_sources": [],
- "sources": [
- {
- "complete": true,
- "declared": {
- "alias_private": 0,
- "database_only": 0,
- "database_only_source": 0,
- "db_only_prefix": 0,
- "derive_folder": 0,
- "git_ignored": 0,
- "lineage_private": 0,
- "mirror_source": 0,
- "private": 0
- },
- "live_pages": 5,
- "pages": 5,
- "source_id": "notes",
- "states": {
- "database_ahead": 0,
- "declared_database_only": 0,
- "equal": 5,
- "git_ahead": 0,
- "undeclared_database_only": 0,
- "unparseable": 0,
- "unsafe_path": 0,
- "worktree_only": 0
- },
- "worktree": {
- "absent": 0,
- "clean": 0,
- "deleted": 0,
- "modified": 5,
- "untracked": 0
- }
- }
- ],
- "sources_without_git_checkout": 1,
- "timeout_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 5 live page(s), 5 equal. Page detail: gbrain sources git-gap <source-id>.",
- "name": "db_ahead_of_git",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
- "sources": [],
- "warn_seconds": 900
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no index trails a commit.",
- "name": "git_index_lag",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/guides/repair.md#facts-home",
- "sources": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
- "name": "strict_facts_outside_git",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -4087,19 +4103,6 @@
"name": "outside_content_fences",
"status": "ok"
},
- {
- "category": "ops",
- "details": {
- "count": 0,
- "docs": "docs/guides/troubleshooting.md#owner-host-stale",
- "stale": [],
- "stale_after_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No managed write is waiting on an owner host.",
- "name": "owner_host_stale",
- "status": "ok"
- },
{
"category": "brain",
"details": {
diff --git a/test/fixtures/goldens/doctor/hot-checks-pglite-json.json b/test/fixtures/goldens/doctor/hot-checks-pglite-json.json
index eada6c5acc..3ca4865288 100644
--- a/test/fixtures/goldens/doctor/hot-checks-pglite-json.json
+++ b/test/fixtures/goldens/doctor/hot-checks-pglite-json.json
@@ -1075,6 +1075,144 @@
"name": "derived_visibility",
"status": "ok"
},
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
+ "sources": [],
+ "warn_seconds": 900
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no index trails a commit.",
+ "name": "git_index_lag",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
+ "errors": [],
+ "informational": true,
+ "newest": 800,
+ "partial_sources": [],
+ "sources": [
+ {
+ "complete": true,
+ "declared": {
+ "alias_private": 0,
+ "database_only": 0,
+ "database_only_source": 0,
+ "db_only_prefix": 0,
+ "derive_folder": 0,
+ "git_ignored": 0,
+ "lineage_private": 0,
+ "mirror_source": 0,
+ "private": 0
+ },
+ "live_pages": 19,
+ "newest": 800,
+ "newest_since": "<ts>",
+ "pages": 19,
+ "source_id": "notes",
+ "states": {
+ "database_ahead": 4,
+ "declared_database_only": 0,
+ "equal": 11,
+ "git_ahead": 0,
+ "undeclared_database_only": 0,
+ "unparseable": 4,
+ "unsafe_path": 0,
+ "worktree_only": 0
+ },
+ "worktree": {
+ "absent": 0,
+ "clean": 18,
+ "deleted": 0,
+ "modified": 1,
+ "untracked": 0
+ }
+ }
+ ],
+ "sources_without_git_checkout": 2,
+ "timeout_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 19 live page(s), 11 equal, 4 database_ahead, 4 unparseable. Page detail: gbrain sources git-gap <source-id>.",
+ "name": "db_ahead_of_git",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/guides/repair.md#facts-home",
+ "sources": []
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
+ "name": "strict_facts_outside_git",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "count": 0,
+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",
+ "stale": [],
+ "stale_after_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No managed write is waiting on an owner host.",
+ "name": "owner_host_stale",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "by_source": [
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "default",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "notes",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "plain",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ }
+ ],
+ "count": 0,
+ "docs": "docs/guides/repair.md#uncommitted-deletions",
+ "exact": true,
+ "other_writer_count": 0,
+ "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
+ "samples": [],
+ "truncated": false
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
+ "name": "uncommitted_sync_deletions",
+ "status": "ok"
+ },
{
"category": "brain",
"elapsed_ms": "<volatile>",
@@ -4026,54 +4164,6 @@
"severity": "info",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "by_source": [
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "default",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "notes",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "plain",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- }
- ],
- "count": 0,
- "docs": "docs/guides/repair.md#uncommitted-deletions",
- "exact": true,
- "other_writer_count": 0,
- "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
- "samples": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
- "name": "uncommitted_sync_deletions",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -4254,80 +4344,6 @@
"name": "person_title_duplicates",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
- "errors": [],
- "informational": true,
- "partial_sources": [],
- "sources": [
- {
- "complete": true,
- "declared": {
- "alias_private": 0,
- "database_only": 0,
- "database_only_source": 0,
- "db_only_prefix": 0,
- "derive_folder": 0,
- "git_ignored": 0,
- "lineage_private": 0,
- "mirror_source": 0,
- "private": 0
- },
- "live_pages": 19,
- "pages": 19,
- "source_id": "notes",
- "states": {
- "database_ahead": 4,
- "declared_database_only": 0,
- "equal": 11,
- "git_ahead": 0,
- "undeclared_database_only": 0,
- "unparseable": 4,
- "unsafe_path": 0,
- "worktree_only": 0
- },
- "worktree": {
- "absent": 0,
- "clean": 18,
- "deleted": 0,
- "modified": 1,
- "untracked": 0
- }
- }
- ],
- "sources_without_git_checkout": 2,
- "timeout_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 19 live page(s), 11 equal, 4 database_ahead, 4 unparseable. Page detail: gbrain sources git-gap <source-id>.",
- "name": "db_ahead_of_git",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
- "sources": [],
- "warn_seconds": 900
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no index trails a commit.",
- "name": "git_index_lag",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/guides/repair.md#facts-home",
- "sources": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
- "name": "strict_facts_outside_git",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -4351,19 +4367,6 @@
"name": "outside_content_fences",
"status": "ok"
},
- {
- "category": "ops",
- "details": {
- "count": 0,
- "docs": "docs/guides/troubleshooting.md#owner-host-stale",
- "stale": [],
- "stale_after_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No managed write is waiting on an owner host.",
- "name": "owner_host_stale",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -6390,71 +6393,209 @@
"refreshes": []
},
"elapsed_ms": "<volatile>",
- "message": "No worktree refresh is stuck.",
- "name": "worktree_refresh_stuck",
+ "message": "No worktree refresh is stuck.",
+ "name": "worktree_refresh_stuck",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "columns": [],
+ "extra_columns": [],
+ "page_child_source_columns": [],
+ "runbook": "docs/guides/write-refusals.md#managed-guard-page-children"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Guarded tables carry only the columns gbrain creates.",
+ "name": "managed_guard_schema_drift",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "guard_refusals": 0,
+ "runbook": "docs/guides/write-refusals.md#managed-guard-page-children",
+ "trigger_refusals": 0,
+ "unclassified_p0001": 0,
+ "window_days": 7
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No write was refused by a database guard in the last 7 days.",
+ "name": "publication_refusals",
+ "status": "ok"
+ },
+ {
+ "category": "meta",
+ "elapsed_ms": "<volatile>",
+ "message": "links_link_source_check has the v114 kebab-case gate",
+ "name": "links_link_source_check",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "elapsed_ms": "<volatile>",
+ "message": "PGLite at 20 pages — comfortable below the 1000-page threshold",
+ "name": "pglite_scale",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "alias_pages_without_visibility": 0,
+ "count": "exact",
+ "fact_ids_truncated": false,
+ "looser_atoms": 0,
+ "looser_concepts": 0,
+ "looser_events": 0,
+ "remotely_readable_fact_ids": [],
+ "repair": "visibility",
+ "truncated": false,
+ "unstamped_atoms": 0,
+ "unstamped_concepts": 0,
+ "world_facts_from_private_sources": 0,
+ "world_facts_remotely_readable": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Every derived page and fact carries a visibility no looser than its source, and no page relies on a privacy alias alone.",
+ "name": "derived_visibility",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
+ "sources": [],
+ "warn_seconds": 900
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no index trails a commit.",
+ "name": "git_index_lag",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
+ "errors": [],
+ "informational": true,
+ "newest": 800,
+ "partial_sources": [],
+ "sources": [
+ {
+ "complete": true,
+ "declared": {
+ "alias_private": 0,
+ "database_only": 0,
+ "database_only_source": 0,
+ "db_only_prefix": 0,
+ "derive_folder": 0,
+ "git_ignored": 0,
+ "lineage_private": 0,
+ "mirror_source": 0,
+ "private": 0
+ },
+ "live_pages": 19,
+ "newest": 800,
+ "newest_since": "<ts>",
+ "pages": 19,
+ "source_id": "notes",
+ "states": {
+ "database_ahead": 4,
+ "declared_database_only": 0,
+ "equal": 11,
+ "git_ahead": 0,
+ "undeclared_database_only": 0,
+ "unparseable": 4,
+ "unsafe_path": 0,
+ "worktree_only": 0
+ },
+ "worktree": {
+ "absent": 0,
+ "clean": 18,
+ "deleted": 0,
+ "modified": 1,
+ "untracked": 0
+ }
+ }
+ ],
+ "sources_without_git_checkout": 2,
+ "timeout_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 19 live page(s), 11 equal, 4 database_ahead, 4 unparseable. Page detail: gbrain sources git-gap <source-id>.",
+ "name": "db_ahead_of_git",
"status": "ok"
},
{
- "category": "ops",
+ "category": "brain",
"details": {
- "columns": [],
- "extra_columns": [],
- "page_child_source_columns": [],
- "runbook": "docs/guides/write-refusals.md#managed-guard-page-children"
+ "docs": "docs/guides/repair.md#facts-home",
+ "sources": []
},
"elapsed_ms": "<volatile>",
- "message": "Guarded tables carry only the columns gbrain creates.",
- "name": "managed_guard_schema_drift",
+ "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
+ "name": "strict_facts_outside_git",
"status": "ok"
},
{
"category": "ops",
"details": {
- "guard_refusals": 0,
- "runbook": "docs/guides/write-refusals.md#managed-guard-page-children",
- "trigger_refusals": 0,
- "unclassified_p0001": 0,
- "window_days": 7
+ "count": 0,
+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",
+ "stale": [],
+ "stale_after_ms": "<volatile>"
},
"elapsed_ms": "<volatile>",
- "message": "No write was refused by a database guard in the last 7 days.",
- "name": "publication_refusals",
- "status": "ok"
- },
- {
- "category": "meta",
- "elapsed_ms": "<volatile>",
- "message": "links_link_source_check has the v114 kebab-case gate",
- "name": "links_link_source_check",
- "status": "ok"
- },
- {
- "category": "ops",
- "elapsed_ms": "<volatile>",
- "message": "PGLite at 20 pages — comfortable below the 1000-page threshold",
- "name": "pglite_scale",
+ "message": "No managed write is waiting on an owner host.",
+ "name": "owner_host_stale",
"status": "ok"
},
{
"category": "brain",
"details": {
- "alias_pages_without_visibility": 0,
- "count": "exact",
- "fact_ids_truncated": false,
- "looser_atoms": 0,
- "looser_concepts": 0,
- "looser_events": 0,
- "remotely_readable_fact_ids": [],
- "repair": "visibility",
- "truncated": false,
- "unstamped_atoms": 0,
- "unstamped_concepts": 0,
- "world_facts_from_private_sources": 0,
- "world_facts_remotely_readable": 0
+ "by_source": [
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "default",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "notes",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "plain",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ }
+ ],
+ "count": 0,
+ "docs": "docs/guides/repair.md#uncommitted-deletions",
+ "exact": true,
+ "other_writer_count": 0,
+ "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
+ "samples": [],
+ "truncated": false
},
"elapsed_ms": "<volatile>",
- "message": "Every derived page and fact carries a visibility no looser than its source, and no page relies on a privacy alias alone.",
- "name": "derived_visibility",
+ "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
+ "name": "uncommitted_sync_deletions",
"status": "ok"
},
{
@@ -9420,54 +9561,6 @@
"severity": "info",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "by_source": [
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "default",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "notes",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "plain",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- }
- ],
- "count": 0,
- "docs": "docs/guides/repair.md#uncommitted-deletions",
- "exact": true,
- "other_writer_count": 0,
- "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
- "samples": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
- "name": "uncommitted_sync_deletions",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -9648,80 +9741,6 @@
"name": "person_title_duplicates",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
- "errors": [],
- "informational": true,
- "partial_sources": [],
- "sources": [
- {
- "complete": true,
- "declared": {
- "alias_private": 0,
- "database_only": 0,
- "database_only_source": 0,
- "db_only_prefix": 0,
- "derive_folder": 0,
- "git_ignored": 0,
- "lineage_private": 0,
- "mirror_source": 0,
- "private": 0
- },
- "live_pages": 19,
- "pages": 19,
- "source_id": "notes",
- "states": {
- "database_ahead": 4,
- "declared_database_only": 0,
- "equal": 11,
- "git_ahead": 0,
- "undeclared_database_only": 0,
- "unparseable": 4,
- "unsafe_path": 0,
- "worktree_only": 0
- },
- "worktree": {
- "absent": 0,
- "clean": 18,
- "deleted": 0,
- "modified": 1,
- "untracked": 0
- }
- }
- ],
- "sources_without_git_checkout": 2,
- "timeout_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 19 live page(s), 11 equal, 4 database_ahead, 4 unparseable. Page detail: gbrain sources git-gap <source-id>.",
- "name": "db_ahead_of_git",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
- "sources": [],
- "warn_seconds": 900
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no index trails a commit.",
- "name": "git_index_lag",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/guides/repair.md#facts-home",
- "sources": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
- "name": "strict_facts_outside_git",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -9745,19 +9764,6 @@
"name": "outside_content_fences",
"status": "ok"
},
- {
- "category": "ops",
- "details": {
- "count": 0,
- "docs": "docs/guides/troubleshooting.md#owner-host-stale",
- "stale": [],
- "stale_after_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No managed write is waiting on an owner host.",
- "name": "owner_host_stale",
- "status": "ok"
- },
{
"category": "brain",
"details": {
diff --git a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
index a5f739ca2d..81a448602a 100644
--- a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
+++ b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
@@ -1071,6 +1071,144 @@
"name": "derived_visibility",
"status": "ok"
},
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
+ "sources": [],
+ "warn_seconds": 900
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no index trails a commit.",
+ "name": "git_index_lag",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
+ "errors": [],
+ "informational": true,
+ "newest": 800,
+ "partial_sources": [],
+ "sources": [
+ {
+ "complete": true,
+ "declared": {
+ "alias_private": 0,
+ "database_only": 0,
+ "database_only_source": 0,
+ "db_only_prefix": 0,
+ "derive_folder": 0,
+ "git_ignored": 0,
+ "lineage_private": 0,
+ "mirror_source": 0,
+ "private": 0
+ },
+ "live_pages": 19,
+ "newest": 800,
+ "newest_since": "<ts>",
+ "pages": 19,
+ "source_id": "notes",
+ "states": {
+ "database_ahead": 4,
+ "declared_database_only": 0,
+ "equal": 11,
+ "git_ahead": 0,
+ "undeclared_database_only": 0,
+ "unparseable": 4,
+ "unsafe_path": 0,
+ "worktree_only": 0
+ },
+ "worktree": {
+ "absent": 0,
+ "clean": 18,
+ "deleted": 0,
+ "modified": 1,
+ "untracked": 0
+ }
+ }
+ ],
+ "sources_without_git_checkout": 2,
+ "timeout_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 19 live page(s), 11 equal, 4 database_ahead, 4 unparseable. Page detail: gbrain sources git-gap <source-id>.",
+ "name": "db_ahead_of_git",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/guides/repair.md#facts-home",
+ "sources": []
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
+ "name": "strict_facts_outside_git",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "count": 0,
+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",
+ "stale": [],
+ "stale_after_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No managed write is waiting on an owner host.",
+ "name": "owner_host_stale",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "by_source": [
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "default",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "notes",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "plain",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ }
+ ],
+ "count": 0,
+ "docs": "docs/guides/repair.md#uncommitted-deletions",
+ "exact": true,
+ "other_writer_count": 0,
+ "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
+ "samples": [],
+ "truncated": false
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
+ "name": "uncommitted_sync_deletions",
+ "status": "ok"
+ },
{
"category": "brain",
"elapsed_ms": "<volatile>",
@@ -4032,54 +4170,6 @@
"severity": "info",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "by_source": [
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "default",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "notes",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "plain",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- }
- ],
- "count": 0,
- "docs": "docs/guides/repair.md#uncommitted-deletions",
- "exact": true,
- "other_writer_count": 0,
- "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
- "samples": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
- "name": "uncommitted_sync_deletions",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -4260,80 +4350,6 @@
"name": "person_title_duplicates",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
- "errors": [],
- "informational": true,
- "partial_sources": [],
- "sources": [
- {
- "complete": true,
- "declared": {
- "alias_private": 0,
- "database_only": 0,
- "database_only_source": 0,
- "db_only_prefix": 0,
- "derive_folder": 0,
- "git_ignored": 0,
- "lineage_private": 0,
- "mirror_source": 0,
- "private": 0
- },
- "live_pages": 19,
- "pages": 19,
- "source_id": "notes",
- "states": {
- "database_ahead": 4,
- "declared_database_only": 0,
- "equal": 11,
- "git_ahead": 0,
- "undeclared_database_only": 0,
- "unparseable": 4,
- "unsafe_path": 0,
- "worktree_only": 0
- },
- "worktree": {
- "absent": 0,
- "clean": 18,
- "deleted": 0,
- "modified": 1,
- "untracked": 0
- }
- }
- ],
- "sources_without_git_checkout": 2,
- "timeout_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 19 live page(s), 11 equal, 4 database_ahead, 4 unparseable. Page detail: gbrain sources git-gap <source-id>.",
- "name": "db_ahead_of_git",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
- "sources": [],
- "warn_seconds": 900
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no index trails a commit.",
- "name": "git_index_lag",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/guides/repair.md#facts-home",
- "sources": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
- "name": "strict_facts_outside_git",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -4357,19 +4373,6 @@
"name": "outside_content_fences",
"status": "ok"
},
- {
- "category": "ops",
- "details": {
- "count": 0,
- "docs": "docs/guides/troubleshooting.md#owner-host-stale",
- "stale": [],
- "stale_after_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No managed write is waiting on an owner host.",
- "name": "owner_host_stale",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -6371,90 +6374,228 @@
"true_up_clamped": 0
},
"elapsed_ms": "<volatile>",
- "message": "Receipt-bytes counters match the receipts they account for (2 scope(s)).",
- "name": "persistence_counter_drift",
+ "message": "Receipt-bytes counters match the receipts they account for (2 scope(s)).",
+ "name": "persistence_counter_drift",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "effects": [],
+ "exact": true,
+ "git_push_holds": [],
+ "inspected": 0,
+ "parked_effects": 0,
+ "parked_groups": [],
+ "truncated": false
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No Git or withdrawal effect is parked.",
+ "name": "parked_effects",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "refreshes": []
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No worktree refresh is stuck.",
+ "name": "worktree_refresh_stuck",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "columns": [],
+ "extra_columns": [],
+ "page_child_source_columns": [],
+ "runbook": "docs/guides/write-refusals.md#managed-guard-page-children"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Guarded tables carry only the columns gbrain creates.",
+ "name": "managed_guard_schema_drift",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "guard_refusals": 0,
+ "runbook": "docs/guides/write-refusals.md#managed-guard-page-children",
+ "trigger_refusals": 0,
+ "unclassified_p0001": 0,
+ "window_days": 7
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No write was refused by a database guard in the last 7 days.",
+ "name": "publication_refusals",
+ "status": "ok"
+ },
+ {
+ "category": "meta",
+ "elapsed_ms": "<volatile>",
+ "message": "links_link_source_check has the v114 kebab-case gate",
+ "name": "links_link_source_check",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "alias_pages_without_visibility": 0,
+ "count": "exact",
+ "fact_ids_truncated": false,
+ "looser_atoms": 0,
+ "looser_concepts": 0,
+ "looser_events": 0,
+ "remotely_readable_fact_ids": [],
+ "repair": "visibility",
+ "truncated": false,
+ "unstamped_atoms": 0,
+ "unstamped_concepts": 0,
+ "world_facts_from_private_sources": 0,
+ "world_facts_remotely_readable": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Every derived page and fact carries a visibility no looser than its source, and no page relies on a privacy alias alone.",
+ "name": "derived_visibility",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
+ "sources": [],
+ "warn_seconds": 900
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no index trails a commit.",
+ "name": "git_index_lag",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
+ "errors": [],
+ "informational": true,
+ "newest": 800,
+ "partial_sources": [],
+ "sources": [
+ {
+ "complete": true,
+ "declared": {
+ "alias_private": 0,
+ "database_only": 0,
+ "database_only_source": 0,
+ "db_only_prefix": 0,
+ "derive_folder": 0,
+ "git_ignored": 0,
+ "lineage_private": 0,
+ "mirror_source": 0,
+ "private": 0
+ },
+ "live_pages": 19,
+ "newest": 800,
+ "newest_since": "<ts>",
+ "pages": 19,
+ "source_id": "notes",
+ "states": {
+ "database_ahead": 4,
+ "declared_database_only": 0,
+ "equal": 11,
+ "git_ahead": 0,
+ "undeclared_database_only": 0,
+ "unparseable": 4,
+ "unsafe_path": 0,
+ "worktree_only": 0
+ },
+ "worktree": {
+ "absent": 0,
+ "clean": 18,
+ "deleted": 0,
+ "modified": 1,
+ "untracked": 0
+ }
+ }
+ ],
+ "sources_without_git_checkout": 2,
+ "timeout_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 19 live page(s), 11 equal, 4 database_ahead, 4 unparseable. Page detail: gbrain sources git-gap <source-id>.",
+ "name": "db_ahead_of_git",
"status": "ok"
},
{
"category": "brain",
"details": {
- "effects": [],
- "exact": true,
- "git_push_holds": [],
- "inspected": 0,
- "parked_effects": 0,
- "parked_groups": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No Git or withdrawal effect is parked.",
- "name": "parked_effects",
- "status": "ok"
- },
- {
- "category": "ops",
- "details": {
- "refreshes": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No worktree refresh is stuck.",
- "name": "worktree_refresh_stuck",
- "status": "ok"
- },
- {
- "category": "ops",
- "details": {
- "columns": [],
- "extra_columns": [],
- "page_child_source_columns": [],
- "runbook": "docs/guides/write-refusals.md#managed-guard-page-children"
+ "docs": "docs/guides/repair.md#facts-home",
+ "sources": []
},
"elapsed_ms": "<volatile>",
- "message": "Guarded tables carry only the columns gbrain creates.",
- "name": "managed_guard_schema_drift",
+ "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
+ "name": "strict_facts_outside_git",
"status": "ok"
},
{
"category": "ops",
"details": {
- "guard_refusals": 0,
- "runbook": "docs/guides/write-refusals.md#managed-guard-page-children",
- "trigger_refusals": 0,
- "unclassified_p0001": 0,
- "window_days": 7
+ "count": 0,
+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",
+ "stale": [],
+ "stale_after_ms": "<volatile>"
},
"elapsed_ms": "<volatile>",
- "message": "No write was refused by a database guard in the last 7 days.",
- "name": "publication_refusals",
- "status": "ok"
- },
- {
- "category": "meta",
- "elapsed_ms": "<volatile>",
- "message": "links_link_source_check has the v114 kebab-case gate",
- "name": "links_link_source_check",
+ "message": "No managed write is waiting on an owner host.",
+ "name": "owner_host_stale",
"status": "ok"
},
{
"category": "brain",
"details": {
- "alias_pages_without_visibility": 0,
- "count": "exact",
- "fact_ids_truncated": false,
- "looser_atoms": 0,
- "looser_concepts": 0,
- "looser_events": 0,
- "remotely_readable_fact_ids": [],
- "repair": "visibility",
- "truncated": false,
- "unstamped_atoms": 0,
- "unstamped_concepts": 0,
- "world_facts_from_private_sources": 0,
- "world_facts_remotely_readable": 0
+ "by_source": [
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "default",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "notes",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ },
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "plain",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ }
+ ],
+ "count": 0,
+ "docs": "docs/guides/repair.md#uncommitted-deletions",
+ "exact": true,
+ "other_writer_count": 0,
+ "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
+ "samples": [],
+ "truncated": false
},
"elapsed_ms": "<volatile>",
- "message": "Every derived page and fact carries a visibility no looser than its source, and no page relies on a privacy alias alone.",
- "name": "derived_visibility",
+ "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
+ "name": "uncommitted_sync_deletions",
"status": "ok"
},
{
@@ -9430,54 +9571,6 @@
"severity": "info",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "by_source": [
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "default",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "notes",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- },
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "plain",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- }
- ],
- "count": 0,
- "docs": "docs/guides/repair.md#uncommitted-deletions",
- "exact": true,
- "other_writer_count": 0,
- "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
- "samples": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
- "name": "uncommitted_sync_deletions",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -9658,80 +9751,6 @@
"name": "person_title_duplicates",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
- "errors": [],
- "informational": true,
- "partial_sources": [],
- "sources": [
- {
- "complete": true,
- "declared": {
- "alias_private": 0,
- "database_only": 0,
- "database_only_source": 0,
- "db_only_prefix": 0,
- "derive_folder": 0,
- "git_ignored": 0,
- "lineage_private": 0,
- "mirror_source": 0,
- "private": 0
- },
- "live_pages": 19,
- "pages": 19,
- "source_id": "notes",
- "states": {
- "database_ahead": 4,
- "declared_database_only": 0,
- "equal": 11,
- "git_ahead": 0,
- "undeclared_database_only": 0,
- "unparseable": 4,
- "unsafe_path": 0,
- "worktree_only": 0
- },
- "worktree": {
- "absent": 0,
- "clean": 18,
- "deleted": 0,
- "modified": 1,
- "untracked": 0
- }
- }
- ],
- "sources_without_git_checkout": 2,
- "timeout_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "Informational, nothing to do: the database compared with the commit at HEAD, per source with a Git checkout. notes: 19 live page(s), 11 equal, 4 database_ahead, 4 unparseable. Page detail: gbrain sources git-gap <source-id>.",
- "name": "db_ahead_of_git",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
- "sources": [],
- "warn_seconds": 900
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no index trails a commit.",
- "name": "git_index_lag",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/guides/repair.md#facts-home",
- "sources": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
- "name": "strict_facts_outside_git",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -9755,19 +9774,6 @@
"name": "outside_content_fences",
"status": "ok"
},
- {
- "category": "ops",
- "details": {
- "count": 0,
- "docs": "docs/guides/troubleshooting.md#owner-host-stale",
- "stale": [],
- "stale_after_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No managed write is waiting on an owner host.",
- "name": "owner_host_stale",
- "status": "ok"
- },
{
"category": "brain",
"details": {
diff --git a/test/fixtures/goldens/doctor/json-pglite-degraded.json b/test/fixtures/goldens/doctor/json-pglite-degraded.json
index 4a53ffcd9e..9aab8ebddb 100644
--- a/test/fixtures/goldens/doctor/json-pglite-degraded.json
+++ b/test/fixtures/goldens/doctor/json-pglite-degraded.json
@@ -917,6 +917,87 @@
"name": "derived_visibility",
"status": "ok"
},
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
+ "sources": [],
+ "warn_seconds": 900
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no index trails a commit.",
+ "name": "git_index_lag",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
+ "errors": [],
+ "informational": true,
+ "newest": 800,
+ "partial_sources": [],
+ "sources": [],
+ "sources_without_git_checkout": 1,
+ "timeout_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source has a Git checkout, so there is no commit to compare the database with.",
+ "name": "db_ahead_of_git",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/guides/repair.md#facts-home",
+ "sources": []
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
+ "name": "strict_facts_outside_git",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "count": 0,
+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",
+ "stale": [],
+ "stale_after_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No managed write is waiting on an owner host.",
+ "name": "owner_host_stale",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "by_source": [
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "default",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ }
+ ],
+ "count": 0,
+ "docs": "docs/guides/repair.md#uncommitted-deletions",
+ "exact": true,
+ "other_writer_count": 0,
+ "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
+ "samples": [],
+ "truncated": false
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
+ "name": "uncommitted_sync_deletions",
+ "status": "ok"
+ },
{
"category": "brain",
"elapsed_ms": "<volatile>",
@@ -3477,34 +3558,6 @@
"severity": "info",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "by_source": [
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "default",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- }
- ],
- "count": 0,
- "docs": "docs/guides/repair.md#uncommitted-deletions",
- "exact": true,
- "other_writer_count": 0,
- "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
- "samples": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
- "name": "uncommitted_sync_deletions",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -3652,45 +3705,6 @@
"name": "person_title_duplicates",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
- "errors": [],
- "informational": true,
- "partial_sources": [],
- "sources": [],
- "sources_without_git_checkout": 1,
- "timeout_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No source has a Git checkout, so there is no commit to compare the database with.",
- "name": "db_ahead_of_git",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
- "sources": [],
- "warn_seconds": 900
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no index trails a commit.",
- "name": "git_index_lag",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/guides/repair.md#facts-home",
- "sources": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
- "name": "strict_facts_outside_git",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -3714,19 +3728,6 @@
"name": "outside_content_fences",
"status": "ok"
},
- {
- "category": "ops",
- "details": {
- "count": 0,
- "docs": "docs/guides/troubleshooting.md#owner-host-stale",
- "stale": [],
- "stale_after_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No managed write is waiting on an owner host.",
- "name": "owner_host_stale",
- "status": "ok"
- },
{
"category": "brain",
"details": {
diff --git a/test/fixtures/goldens/doctor/json-pglite-fresh.json b/test/fixtures/goldens/doctor/json-pglite-fresh.json
index 69a82219f1..dc3d6a6dd7 100644
--- a/test/fixtures/goldens/doctor/json-pglite-fresh.json
+++ b/test/fixtures/goldens/doctor/json-pglite-fresh.json
@@ -964,6 +964,87 @@
"name": "derived_visibility",
"status": "ok"
},
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
+ "sources": [],
+ "warn_seconds": 900
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no index trails a commit.",
+ "name": "git_index_lag",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
+ "errors": [],
+ "informational": true,
+ "newest": 800,
+ "partial_sources": [],
+ "sources": [],
+ "sources_without_git_checkout": 1,
+ "timeout_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source has a Git checkout, so there is no commit to compare the database with.",
+ "name": "db_ahead_of_git",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/guides/repair.md#facts-home",
+ "sources": []
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
+ "name": "strict_facts_outside_git",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "count": 0,
+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",
+ "stale": [],
+ "stale_after_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No managed write is waiting on an owner host.",
+ "name": "owner_host_stale",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "by_source": [
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "default",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ }
+ ],
+ "count": 0,
+ "docs": "docs/guides/repair.md#uncommitted-deletions",
+ "exact": true,
+ "other_writer_count": 0,
+ "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
+ "samples": [],
+ "truncated": false
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
+ "name": "uncommitted_sync_deletions",
+ "status": "ok"
+ },
{
"category": "brain",
"elapsed_ms": "<volatile>",
@@ -3520,34 +3601,6 @@
"severity": "info",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "by_source": [
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "default",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- }
- ],
- "count": 0,
- "docs": "docs/guides/repair.md#uncommitted-deletions",
- "exact": true,
- "other_writer_count": 0,
- "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
- "samples": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
- "name": "uncommitted_sync_deletions",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -3695,45 +3748,6 @@
"name": "person_title_duplicates",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
- "errors": [],
- "informational": true,
- "partial_sources": [],
- "sources": [],
- "sources_without_git_checkout": 1,
- "timeout_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No source has a Git checkout, so there is no commit to compare the database with.",
- "name": "db_ahead_of_git",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
- "sources": [],
- "warn_seconds": 900
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no index trails a commit.",
- "name": "git_index_lag",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/guides/repair.md#facts-home",
- "sources": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
- "name": "strict_facts_outside_git",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -3757,19 +3771,6 @@
"name": "outside_content_fences",
"status": "ok"
},
- {
- "category": "ops",
- "details": {
- "count": 0,
- "docs": "docs/guides/troubleshooting.md#owner-host-stale",
- "stale": [],
- "stale_after_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No managed write is waiting on an owner host.",
- "name": "owner_host_stale",
- "status": "ok"
- },
{
"category": "brain",
"details": {
diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.json
index dc0443e18c..4d7807f88b 100644
--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json
+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json
@@ -960,6 +960,87 @@
"name": "derived_visibility",
"status": "ok"
},
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
+ "sources": [],
+ "warn_seconds": 900
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no index trails a commit.",
+ "name": "git_index_lag",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
+ "errors": [],
+ "informational": true,
+ "newest": 800,
+ "partial_sources": [],
+ "sources": [],
+ "sources_without_git_checkout": 1,
+ "timeout_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source has a Git checkout, so there is no commit to compare the database with.",
+ "name": "db_ahead_of_git",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/guides/repair.md#facts-home",
+ "sources": []
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
+ "name": "strict_facts_outside_git",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "count": 0,
+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",
+ "stale": [],
+ "stale_after_ms": "<volatile>"
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No managed write is waiting on an owner host.",
+ "name": "owner_host_stale",
+ "status": "ok"
+ },
+ {
+ "category": "brain",
+ "details": {
+ "by_source": [
+ {
+ "checked": 0,
+ "other_writer": 0,
+ "source_id": "default",
+ "status": "known",
+ "sync_deleted": 0,
+ "tombstones": 0,
+ "truncated": false,
+ "unknown": 0
+ }
+ ],
+ "count": 0,
+ "docs": "docs/guides/repair.md#uncommitted-deletions",
+ "exact": true,
+ "other_writer_count": 0,
+ "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
+ "samples": [],
+ "truncated": false
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
+ "name": "uncommitted_sync_deletions",
+ "status": "ok"
+ },
{
"category": "brain",
"elapsed_ms": "<volatile>",
@@ -3526,34 +3607,6 @@
"severity": "info",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "by_source": [
- {
- "checked": 0,
- "other_writer": 0,
- "source_id": "default",
- "status": "known",
- "sync_deleted": 0,
- "tombstones": 0,
- "truncated": false,
- "unknown": 0
- }
- ],
- "count": 0,
- "docs": "docs/guides/repair.md#uncommitted-deletions",
- "exact": true,
- "other_writer_count": 0,
- "purged": "Pages already purged cannot be restored by this command; only a backup (pg_dump, or gbrain backup create taken before the purge) can bring them back.",
- "samples": [],
- "truncated": false
- },
- "elapsed_ms": "<volatile>",
- "message": "No soft-deleted page was removed by a sync while Git never held its file (0 tombstone(s) checked).",
- "name": "uncommitted_sync_deletions",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -3701,45 +3754,6 @@
"name": "person_title_duplicates",
"status": "ok"
},
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census",
- "errors": [],
- "informational": true,
- "partial_sources": [],
- "sources": [],
- "sources_without_git_checkout": 1,
- "timeout_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No source has a Git checkout, so there is no commit to compare the database with.",
- "name": "db_ahead_of_git",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/designs/GIT_CANONICAL_MEMORY.md#the-model",
- "sources": [],
- "warn_seconds": 900
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no index trails a commit.",
- "name": "git_index_lag",
- "status": "ok"
- },
- {
- "category": "brain",
- "details": {
- "docs": "docs/guides/repair.md#facts-home",
- "sources": []
- },
- "elapsed_ms": "<volatile>",
- "message": "No source is strict (git-canonical), so no fact is required to have a Git home.",
- "name": "strict_facts_outside_git",
- "status": "ok"
- },
{
"category": "brain",
"details": {
@@ -3763,19 +3777,6 @@
"name": "outside_content_fences",
"status": "ok"
},
- {
- "category": "ops",
- "details": {
- "count": 0,
- "docs": "docs/guides/troubleshooting.md#owner-host-stale",
- "stale": [],
- "stale_after_ms": "<volatile>"
- },
- "elapsed_ms": "<volatile>",
- "message": "No managed write is waiting on an owner host.",
- "name": "owner_host_stale",
- "status": "ok"
- },
{
"category": "brain",
"details": {
diff --git a/test/fixtures/goldens/doctor/registry-build-checks.json b/test/fixtures/goldens/doctor/registry-build-checks.json
index 8e8e6c5dc0..df8166a97a 100644
--- a/test/fixtures/goldens/doctor/registry-build-checks.json
+++ b/test/fixtures/goldens/doctor/registry-build-checks.json
@@ -369,6 +369,26 @@
"category": "brain",
"name": "derived_visibility"
},
+ {
+ "category": "brain",
+ "name": "git_index_lag"
+ },
+ {
+ "category": "brain",
+ "name": "db_ahead_of_git"
+ },
+ {
+ "category": "brain",
+ "name": "strict_facts_outside_git"
+ },
+ {
+ "category": "ops",
+ "name": "owner_host_stale"
+ },
+ {
+ "category": "brain",
+ "name": "uncommitted_sync_deletions"
+ },
{
"category": "brain",
"name": "access_readers_malformed"
@@ -1161,10 +1181,6 @@
"category": "brain",
"name": "missing_recorded_files"
},
- {
- "category": "brain",
- "name": "uncommitted_sync_deletions"
- },
{
"category": "brain",
"name": "unindexed_files"
@@ -1189,18 +1205,6 @@
"category": "brain",
"name": "person_title_duplicates"
},
- {
- "category": "brain",
- "name": "db_ahead_of_git"
- },
- {
- "category": "brain",
- "name": "git_index_lag"
- },
- {
- "category": "brain",
- "name": "strict_facts_outside_git"
- },
{
"category": "brain",
"name": "local_edit_adoptions"
@@ -1209,10 +1213,6 @@
"category": "brain",
"name": "outside_content_fences"
},
- {
- "category": "ops",
- "name": "owner_host_stale"
- },
{
"category": "brain",
"name": "embedding_plane_disagreement"
diff --git a/test/git-gap-census.test.ts b/test/git-gap-census.test.ts
index 26b9d1ce86..735a6cfdf6 100644
--- a/test/git-gap-census.test.ts
+++ b/test/git-gap-census.test.ts
@@ -13,7 +13,8 @@ import { gitBlobOid } from '../src/core/persistence/digest.ts';
import { recordSyncImportProvenance } from '../src/core/persistence/sync-holds.ts';
import { compareInlineExportFile, compareSegmentedExportBlob, declaredDatabaseOnly, ignoredPaths } from '../src/core/persistence/git-gap.ts';
import { censusGitGap, describeGitGap, parseGitGapArgs } from '../src/commands/sources-git-gap.ts';
-import { dbAheadOfGitEntry } from '../src/commands/doctor/checks/db-ahead-of-git.ts';
+import { censusWindow, dbAheadOfGitEntry, doctorGitGapCensus, DOCTOR_GIT_GAP_NEWEST } from '../src/commands/doctor/checks/db-ahead-of-git.ts';
+import { withStatementDeadline } from '../src/core/statement-deadline.ts';
import { OperationError } from '../src/core/ops/contract.ts';
import { createSegmentedPage } from './helpers/segmented-page.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
@@ -389,7 +390,64 @@ for (const backend of testBackends()) describe(`git-gap census (git-canonical G1
expect(check!.message).not.toContain('notes/');
const [late] = await withEnv({ GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS: '1' }, () =>
dbAheadOfGitEntry.run({ engine, progress: { heartbeat: () => {} }, entryDeadlineAt: Date.now() } as never)) as Array<{ status: string; details: any }>;
- expect(late).toMatchObject({ status: 'ok', details: { partial_sources: ['default'] } });
+ expect(late).toMatchObject({ status: 'warn', details: { partial_sources: ['default'], health: 'unknown', reason: 'bound', bound: 'git_gap_timeout' } });
+ });
+
+ test('GBRA-541: a doctor census the budget stopped or could not run is health unknown, never ok', async () => {
+ const root = tempDir('git-gap-doctor-stopped-');
+ git(root, 'init', '-q');
+ await useCheckout(root);
+ await engine.putPage('notes/a', { type: 'note', title: 'A', compiled_truth: 'Body A.', timeline: '' });
+ put(root, 'notes/a.md', await rendered('notes/a'));
+ commitAll(root, 'init');
+ const [late] = await withEnv({ GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS: '1' }, () =>
+ dbAheadOfGitEntry.run({ engine, progress: { heartbeat: () => {} }, entryDeadlineAt: Date.now() } as never)) as Array<{ status: string; message: string; details: any }>;
+ expect(late!.status).toBe('warn');
+ expect(late!.details).toMatchObject({ health: 'unknown', reason: 'bound' });
+ expect(late!.message).toContain('Health unknown, not clear');
+ const failing = { executeRaw: async () => { throw new Error('connection reset'); } };
+ const [errored] = await dbAheadOfGitEntry.run({ engine: failing, progress: { heartbeat: () => {} } } as never) as Array<{ status: string; details: any }>;
+ expect(errored).toMatchObject({ status: 'warn', details: { health: 'unknown' } });
+ });
+
+ test('GBRA-541: the newest-pages census reads only the most recently changed pages and names how far back it looked', async () => {
+ const root = tempDir('git-gap-newest-');
+ git(root, 'init', '-q');
+ await useCheckout(root);
+ for (const slug of ['notes/a', 'notes/b', 'notes/c', 'notes/d']) {
+ await engine.putPage(slug, { type: 'note', title: slug, compiled_truth: `Body of ${slug}.`, timeline: '' });
+ put(root, `${slug}.md`, await rendered(slug));
+ }
+ commitAll(root, 'init');
+ await engine.putPage('notes/a', { type: 'note', title: 'notes/a', compiled_truth: 'Written to the database, never committed.', timeline: '' });
+ await engine.executeRaw("UPDATE pages SET updated_at = now() - make_interval(days => 10) WHERE source_id='default' AND slug IN ('notes/b','notes/c')");
+ await engine.executeRaw("UPDATE pages SET updated_at = now() - make_interval(days => 2) WHERE source_id='default' AND slug='notes/d'");
+ await engine.executeRaw("UPDATE pages SET updated_at = now() WHERE source_id='default' AND slug='notes/a'");
+ const census = await censusGitGap(engine, 'default', { sample: 0, newest: 2 });
+ expect(census).toMatchObject({ complete: true, pages: 2, live_pages: 4, newest: 2, states: { database_ahead: 1, equal: 1 } });
+ const [since] = await engine.executeRaw<{ at: string }>("SELECT to_char(updated_at AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS\"Z\"') AS at FROM pages WHERE source_id='default' AND slug='notes/d'");
+ expect(census.newest_since).toBe(since!.at);
+ expect(censusWindow(census)).toBe(`checked the 2 most recently changed of 4 live page(s), back to ${since!.at}`);
+ expect(censusWindow(await censusGitGap(engine, 'default', { sample: 0, newest: 10 }))).toBe('4 live page(s)');
+ expect((await censusGitGap(engine, 'default', { sample: 0 })).newest).toBeUndefined();
+ });
+
+ test('GBRA-541: one doctor run reads a source\'s complete newest-pages census once and never keeps a partial one', async () => {
+ const root = tempDir('git-gap-memo-');
+ git(root, 'init', '-q');
+ await useCheckout(root);
+ await engine.putPage('notes/a', { type: 'note', title: 'A', compiled_truth: 'Body A.', timeline: '' });
+ put(root, 'notes/a.md', await rendered('notes/a'));
+ commitAll(root, 'init');
+ const memo = new Map<string, Promise<unknown>>();
+ const scope = () => ({ startedAt: Date.now(), deadlineAt: null, expired: false, memo });
+ const partial = await withStatementDeadline(scope(), () => doctorGitGapCensus(engine, 'default', Date.now() - 1));
+ expect(partial.complete).toBe(false);
+ expect(memo.size).toBe(0);
+ const first = await withStatementDeadline(scope(), () => doctorGitGapCensus(engine, 'default', Date.now() + 60_000));
+ const second = await withStatementDeadline(scope(), () => doctorGitGapCensus(engine, 'default', Date.now() + 60_000));
+ expect(first).toMatchObject({ complete: true, pages: 1, newest: DOCTOR_GIT_GAP_NEWEST });
+ expect(second).toBe(first);
});
});