Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
feat(doctor,repair): sync_rows_behind_checkpoint and gbrain repair rows-behind (#8071)
garrytan3e6e96e2a370
diff --git a/docs/architecture/key-files/canonical-reconciliation-continued.md b/docs/architecture/key-files/canonical-reconciliation-continued.mdnew file mode 100644index 0000000000..b8115e90b7--- /dev/null+++ b/docs/architecture/key-files/canonical-reconciliation-continued.md@@ -0,0 +1,8 @@+# Canonical reconciliation (continued)++[Subsystem index](../KEY_FILES.md) · [Previous entries](canonical-reconciliation.md). Read only the entries relevant to your change.+Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.++- `src/core/persistence/rows-behind.ts` — #8071: `scanRowsBehind(engine, sourceId, { deadlineAt })` finds live Markdown pages of a managed source whose row holds an older version of its file than `sources.last_commit`, with no hold. It reads the checkpoint tree from Git (`readHeadTree(root, commit)`), compares each page in id batches of 256 with the committed blob (`compareInlineExportFile`, or `compareSegmentedExportBlob` for a page stored in segments) and confirms a difference with `prepareRepairPublication`; direction comes from the page's sync import record (`behind` when its revision is the recorded one, `unproven` without a record, `database_moved` skipped). A blob over `SYNC_READ_BOUND` is never read and reported with `file_too_large`. Owner host only; a repo-less brain is `not_applicable`.+- `src/commands/doctor/checks/rows-behind.ts` — doctor `sync_rows_behind_checkpoint` (BRAIN, after `sync_overwritten_db_edits`): per source counts and first slugs from `scanRowsBehind`; `warn` on `behind` rows with the read-only `gbrain repair rows-behind --source <id> --json` preview as the fix; `unknown` (info) when the `GBRAIN_DOCTOR_ROWS_BEHIND_TIMEOUT_MS` budget (default 10 s) stopped a scan or a checkout is unreadable; not applicable (ok) off the owner host and on repo-less brains.+- `src/core/repair/rows-behind.ts` — `gbrain repair rows-behind --source <id>`: explicit-only, preview-bound (`--apply --expect <hash>`, `--include-ambiguous` adds rows with no import record). `reimport` submits the committed bytes through `submitManagedFileRepair`; `hold:<code>` writes the hold sync would have written (`writeGitHold`). Refused off the owner host (`not_owner_host`). Never runs on upgrade. Tests: `test/rows-behind-checkpoint-8071.test.ts` (PGLite and Postgres via `test/e2e/rows-behind-checkpoint-8071-postgres.test.ts`).diff --git a/docs/architecture/key-files/canonical-reconciliation.md b/docs/architecture/key-files/canonical-reconciliation.mdindex 7c7beb65aa..60eda1f55b 100644--- a/docs/architecture/key-files/canonical-reconciliation.md+++ b/docs/architecture/key-files/canonical-reconciliation.md@@ -1,6 +1,6 @@# Canonical reconciliation-See [generations](generations.md).+See [generations](generations.md) and [continued entries](canonical-reconciliation-continued.md).- `src/commands/sync-diagnostics.ts` + `src/core/persistence/{sync-run,verb-errors}.ts` — bounded source/slug/path/reason diagnostics derive from immutable managed-sync receipts, including when the local failure ledger is unavailable. Direct and resident-owner JSON carry the same receipt; human memory errors lead with the specific write reason without widening frozen v1 error codes. Pending requests retain their original UUID, terminal corrections require a new UUID, and neither retry nor line-ending diagnostics bypasses raw-byte or skip guards.diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex bf1d4dc2fd..601054f1bb 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -164,6 +164,7 @@ work behind exits 0, so scripts should also check `results[].complete`.| `file-drift` | `maintenance_write_drift` | Explicit-only, preview-bound. Resolves pages whose canonical file differs from the database copy (`source_changed` / `file_database_drift`) through canonical reconciliation, preferring the file or the database copy within reconcile's protections. `--all-drifted` refuses mixed drift classes unless `--class` keeps one; `--only`/`--skip` narrow by canonical file path glob. Opt-in `storage.keep_db` lets the owner host's resident consumer resolve drift under declared prefixes with the database copy. A page whose file is gone from the last commit: `--prefer database` recreates the file, `--prefer file` soft-deletes the page ([deleted canonical files](#deleted-canonical-files)). See [file drift](#file-drift). | Protected metadata, the tag union and protected takes or private fact rows, listed per page as `exceptions`; pages changed after the preview (`changed_since_preview`). || `ghost-pages` | `ghost_pages` | Explicit-only, preview-bound, destructive consent. Soft-deletes live pages whose canonical file is missing on the owner host (ghost pages: every write refuses `canonical_file_missing` and no sync can import a file that is not there), through `delete_page` bound to the previewed owner, path and revision. `--apply --expect <hash> --yes`. See [ghost pages](#ghost-pages). | Declared db_only and never-filed derived pages (never listed); a page whose file came back before the apply (`file_restored`); pages changed after the preview (`changed_since_preview`). || `uncommitted-deletions` | `uncommitted_sync_deletions` | Explicit-only, preview-bound, consent. Restores soft-deleted pages a managed sync removed before #7130 although Git never held their recorded file (`.gitignore` excludes it, or no commit holds it and it is not on the disk), one `restore_page` with `detach` each, published database-only: the page comes back live, forgets its recorded file, and no file is written. `--apply --expect <hash> --yes`. See [uncommitted deletions](#uncommitted-deletions). | Pages another writer deleted (listed, restored only with `--include-ambiguous`); tombstones whose file Git once committed or that is on the disk again; paths Git could not answer for (`unknown`); purged pages (only a backup brings them back). |+| `rows-behind` | `sync_rows_behind_checkpoint` | Explicit-only, preview-bound. Re-imports live pages of a managed source whose row holds an older version of its file than the sync checkpoint (`sources.last_commit`) says was imported, with no hold (#8071), from the file as committed at the checkpoint, through the managed file repair (no file is written). A file whose import is refused, or that is over the sync read bound, is held with that code instead. `--source <id>`, then `--apply --expect <hash>`. See [rows behind the checkpoint](#rows-behind). | Rows with no import record (`excluded:unproven`, joined with `--include-ambiguous`), rows with an uncommitted working-tree edit (`excluded:worktree_differs`), rows whose import would keep page data the file does not carry (`excluded:import_overlay`); rows that moved after the preview (`changed_since_preview`). || `receipt-compaction` | `persistence_capacity` (terminal bytes) | Explicit-only, preview-bound, destructive consent. Compacts terminal write receipts now instead of on the idle maintenance tick (#6696): the intent and error message are dropped, the outcome, error code and detail stay, and the unused reservation returns to the receipt-bytes counters. `--older-than <72h\|30d>` is floored at the configured retention unless `--force`; committed receipts only unless `--include-failures`. No admission, so it runs at a full cap. See [receipt compaction](#receipt-compaction). | `failures_kept`: failed, conflict and cancelled receipts left without `--include-failures`. Receipts of a run whose sync cursor is still open, and the newest sync receipt of each worktree, are never listed. || `aliases` | `dangling_aliases` (orphaned rows) | Explicit-only. Deletes free-text page aliases and slug redirects whose target page has no row at all (a page purged before purge removed its aliases, #6619, or a hard-deleted page), each target rechecked under its page lock; a coordinated maintenance write on a managed brain. A redirect from an old name of a page that still exists is never touched. See [aliases](#aliases). | `soft_deleted_target`: aliases of a soft-deleted page, kept for `gbrain restore` and removed when the page is purged. || `rename-identity` | `rename_identity_downgrades` | Explicit-only, preview-bound, destructive consent. For an inexact Git rename that sync split into a delete plus an add (#6729): carries the old page's identity (id, version history, timeline, links, facts, aliases) onto the new slug, imports the new file onto it as an edit and retires the provisional page; or, with `--close`, settles the pair and moves nothing. `--slug <new-slug>` (and `--from <old-slug>`) names one pair; `--apply --expect <hash> --yes`. See [rename identity](#rename-identity). | `fact_rows_collide` (a fence row of the old page the new file does not keep with the same claim); `managed_remedy_unavailable` (a carry on a managed source; `--close` is the remedy there); pages changed after the preview (`changed_since_preview`). |@@ -1400,6 +1401,69 @@ stopped part way (`--limit`, a time budget) resumes over the rest of the sameapproved set when rerun. The repair runs only when named, never on upgrade orfrom a maintenance cycle.+<a id="rows-behind"></a>+### Rows behind the checkpoint++A managed sync records the commit it imported as the source's checkpoint+(`sources.last_commit`) and decides that a file needs nothing from the file's+import record. When that record names the current blob while the page row+still holds an older version of the file (#8071), every later sync reports the+source up to date, and search and reads keep returning the old text. The page+is live and has no hold, so the landing checks pass it.++Doctor `sync_rows_behind_checkpoint` finds these rows. On each managed+source's owner host it compares every live Markdown page with its file read+from Git at the checkpoint commit (never the working tree, never the import+record): an inline page byte for byte through the export view, a page stored+in segments by streamed hash. It then confirms each difference with the+importer itself, so a row that importing the committed file would leave+unchanged is current. A row is reported only when its revision is the one its+last sync import wrote. A row the database changed since that import belongs+to [file drift](#file-drift) and is not reported here. A row with no import+record is counted as `unproven` and does not warn. Held paths, paths a later+commit changed (the next sync imports them) and declared database-only pages+are skipped. A file over the sync read bound is never read; its row is+reported with the `file_too_large` refusal sync would hold it with. The scan+is bounded by `GBRAIN_DOCTOR_ROWS_BEHIND_TIMEOUT_MS` (default 10 s); a scan+the budget stopped, or a checkout Git cannot read, is `unknown`, never a+clean `ok`. Off the owner host, on a source without a checkout or a+checkpoint, and on a repo-less brain (the database is the record there) the+check is `ok` and not applicable.++To re-import them, preview, then apply after the user agrees:++```bash+gbrain repair rows-behind --source default # preview: each row, its path, the checkpoint blob and the action, with a hash+gbrain repair rows-behind --source default --apply --expect <hash>+```++The preview writes nothing. Each row in the set has one action:++- `reimport`: the committed file is imported through the managed file+ repair, the same screen, preparation and projections a sync import uses,+ bound to the page revision and the previewed result. The file on disk+ already holds those bytes, so no file is written.+- `hold:<code>`: importing the committed file is refused (for example a+ malformed fence), or the file is over the read bound+ (`hold:file_too_large`). The apply opens the hold sync would have opened,+ with the refusal's code and message, and the usual+ [held files](#held-files) steps clear it.++Listed but left out of the set: rows with no import record+(`excluded:unproven`, joined with `--include-ambiguous`), rows whose+working-tree file differs from the committed one (`excluded:worktree_differs`:+commit the edit and sync), and rows whose import would keep page data the+file does not carry (`excluded:import_overlay`; resolve them with+`gbrain repair file-drift --source <id> --slug <slug> --prefer file`). A row+whose page, owner, checkpoint or file changed since the preview is skipped+`changed_since_preview`; a wrong or stale hash refuses+[`preview_changed`](#preview-changed). Off the owner host the preview and+the apply refuse [`not_owner_host`](error-codes.md#not_owner_host), and a+repo-less source lists nothing. One preview lists at most 1,000 rows; when+more are behind it says so, and the next preview after the apply lists the+rest. The repair runs only when named, never on upgrade, from `--all` or+from a maintenance cycle.+<a id="legacy-twins"></a>### Legacy twinsdiff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsvindex d80fca694b..587b0e14d2 100644--- a/scripts/module-size-limits.tsv+++ b/scripts/module-size-limits.tsv@@ -47,4 +47,4 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: linksrc/core/search/evidence-delivery.ts 1755 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move); +7 GBRA-205: EvidencePlan.titleHeader and DeliveryMeta.title_header (interface fields cannot move) and the titles option on the header loader (logic in search/evidence-date.ts; the query budget key lives in search/evidence-packing.ts); +11 #7600: assemble_evidence quotes conversation rows and capEvidenceToBudget counts the quote fence (logic in search/transcript-quote.ts); +2 GBRA-156 /ship review: the cut-path admission and title room count the quote fence; +2 GBRA-156 /ship review pass 2: capEvidenceToBudget counts the fence only for the paths that fence (quote flag; recall counts the text as returned)src/commands/config.ts 1524 ratchet new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal)src/commands/mcp-expose.ts 1519 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts); +7 GBRA-199: --surface help lines, surfaceChosen option field and the advertise pass-through (registrationAdvertise in core/mcp-registration.ts)-src/core/behavior-change-notice.ts 1570 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope)+src/core/behavior-change-notice.ts 1571 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +1 GBRA-250 #8071 rows_behind_checkpoint_8071 row (since TBD until the merge slot)diff --git a/src/commands/doctor/checks/rows-behind.ts b/src/commands/doctor/checks/rows-behind.tsnew file mode 100644index 0000000000..7303d2f073--- /dev/null+++ b/src/commands/doctor/checks/rows-behind.ts@@ -0,0 +1,79 @@+/**+ * #8071 `sync_rows_behind_checkpoint`: live pages of a managed source whose row holds an older version of its file than+ * the source's sync checkpoint (`sources.last_commit`) says was imported, with no hold (`persistence/rows-behind.ts`).+ * Landing checks pass such a row (it exists and is not held); this one compares its content with the file read from Git+ * at the checkpoint commit and confirms the difference with the importer.+ *+ * warn when any source has a `behind` row: per-source counts, the first slugs and the read-only preview+ * `gbrain repair rows-behind --source <id>`. Rows with no import record (`unproven`) are counted and never warn. ok when+ * every source read completely and none is behind; a scan the budget stopped, or a checkout Git cannot read, is info+ * `unknown` (never a clean ok). Not applicable (ok, info) on a brain without managed sync, a source without a checkout or+ * checkpoint (a repo-less brain) and off the owner host. Bounded by `GBRAIN_DOCTOR_ROWS_BEHIND_TIMEOUT_MS` (default 10 s)+ * and the entry's deadline. Read-only.+ */+import type { Check } from '../../doctor.ts';+import { scanDeadline } from '../budget.ts';+import { agentFix, checkError, infoCheck } from '../check-fix.ts';+import { connectedEngine, doctorSourceIds, type DoctorContext, type DoctorEntry } from '../context.ts';+import { ROWS_BEHIND_DOCS, scanRowsBehind, type RowsBehindScan } from '../../../core/persistence/rows-behind.ts';++const SAMPLES = 10;++/** `GBRAIN_DOCTOR_ROWS_BEHIND_TIMEOUT_MS` (default 10 s): the wall-clock bound of the scan across every source. */+export function rowsBehindScanTimeoutMs(): number {+ const n = parseInt(process.env.GBRAIN_DOCTOR_ROWS_BEHIND_TIMEOUT_MS ?? '', 10);+ return Number.isFinite(n) && n > 0 ? n : 10_000;+}++async function runRowsBehind(ctx: DoctorContext): Promise<Check[]> {+ const checks: Check[] = [];+ try {+ const engine = connectedEngine(ctx);+ const deadlineAt = scanDeadline(ctx, rowsBehindScanTimeoutMs());+ const ids = doctorSourceIds(ctx) ?? (await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE archived IS NOT TRUE ORDER BY id')).map(row => row.id);+ const scans: RowsBehindScan[] = [];+ for (const id of ids) scans.push(await scanRowsBehind(engine, id, { deadlineAt }));+ const known = scans.filter(scan => scan.status === 'known');+ const count = known.reduce((sum, scan) => sum + scan.behind_count, 0);+ const unproven = known.reduce((sum, scan) => sum + scan.unproven_count, 0);+ const partial = known.filter(scan => !scan.complete);+ const unknown = scans.filter(scan => scan.status === 'unknown');+ const details = { count, unproven, docs: ROWS_BEHIND_DOCS, timeout_ms: rowsBehindScanTimeoutMs(),+ sources: scans.map(scan => ({ source_id: scan.source_id, status: scan.status, ...(scan.reason ? { reason: scan.reason } : {}), checkpoint: scan.checkpoint, complete: scan.complete,+ pages: scan.pages, behind: scan.behind_count, unproven: scan.unproven_count, counts: scan.counts,+ samples: (ctx.remote ? [] : scan.behind).slice(0, SAMPLES).map(row => row.slug), unproven_samples: (ctx.remote ? [] : scan.unproven).slice(0, SAMPLES).map(row => row.slug) })) };+ const unprovenNote = unproven ? ` ${unproven} more row(s) differ from their checkpoint file but have no import record, so the side that moved is unknown; gbrain repair rows-behind --source <id> --include-ambiguous lists and re-imports them.` : '';+ if (count) {+ const found = known.filter(scan => scan.behind_count);+ checks.push({ name: 'sync_rows_behind_checkpoint', status: 'warn', details,+ message: `${count}${partial.length ? '+' : ''} page(s) hold an older version of their file than the sync checkpoint says was imported, with no hold `+ + `(${found.map(scan => `${scan.source_id}: ${scan.behind_count}${ctx.remote ? '' : `, e.g. ${scan.behind.slice(0, 3).map(row => row.slug).join(', ')}`}`).join('; ')}). `+ + `Search and reads return the old text, and no later sync re-imports them. Preview the re-import with gbrain repair rows-behind --source ${found[0]!.source_id}; it writes nothing.${unprovenNote}`,+ fix: agentFix(['gbrain', 'repair', 'rows-behind', '--source', found[0]!.source_id, '--json'],+ 'Read-only preview: lists each row behind its checkpoint file and what the re-import would do (or the hold it would open), and prints the apply command with its hash.',+ 'sync_rows_behind_checkpoint', { docs: ROWS_BEHIND_DOCS }) });+ return checks;+ }+ if (unknown.length || partial.length) {+ checks.push(infoCheck('sync_rows_behind_checkpoint', `Rows behind the sync checkpoint are unknown for ${[...unknown.map(scan => `${scan.source_id} (${scan.reason})`),+ ...partial.map(scan => `${scan.source_id} (stopped after ${scan.pages} page(s) at the ${details.timeout_ms / 1000} s budget)`)].join(', ')}; this is not a clean result. `+ + `The full read: gbrain repair rows-behind --source <id> (writes nothing).${unprovenNote}`, 'unknown', undefined, details));+ return checks;+ }+ if (!known.length) {+ const reasons = [...new Set(scans.map(scan => scan.reason ?? 'not_applicable'))];+ checks.push(infoCheck('sync_rows_behind_checkpoint', reasons.includes('not_owner_host')+ ? 'Not applicable on this host: rows are compared with the checkpoint commit in each source\'s checkout on its canonical owner host (run doctor there).'+ : '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).',+ 'not_applicable', undefined, { ...details, reasons }));+ return checks;+ }+ checks.push({ name: 'sync_rows_behind_checkpoint', status: 'ok', details,+ message: `Every file-backed page holds its file as of the sync checkpoint (${known.reduce((sum, scan) => sum + scan.pages, 0)} page(s) read).${unprovenNote}` });+ } catch (error) {+ checks.push(checkError('sync_rows_behind_checkpoint', 'compare pages with their files at the sync checkpoint', error, { details: { count: 'unknown', docs: ROWS_BEHIND_DOCS } }));+ }+ return checks;+}++export const rowsBehindEntry: DoctorEntry = { name: 'sync_rows_behind_checkpoint', emits: ['sync_rows_behind_checkpoint'], run: runRowsBehind };diff --git a/src/commands/doctor/registry.ts b/src/commands/doctor/registry.tsindex bd397e15ca..1afe369810 100644--- a/src/commands/doctor/registry.ts+++ b/src/commands/doctor/registry.ts@@ -140,6 +140,7 @@ import { derivationPurgeSweepsEntry } from './checks/derivation-purge-sweeps.ts'import { missingRecordedFilesEntry } from './checks/missing-recorded-files.ts';import { uncommittedSyncDeletionsEntry } from './checks/uncommitted-sync-deletions.ts';import { overwrittenEditsEntry } from './checks/overwritten-edits.ts';+import { rowsBehindEntry } from './checks/rows-behind.ts';import { managedSyncMovementEntry } from './checks/managed-sync-movement.ts';import { managedSyncLatencyEntry } from './checks/managed-sync-latency.ts';import { commitNotifierEntry } from './checks/commit-notifier.ts';@@ -293,6 +294,7 @@ export const DOCTOR_CHECK_REGISTRY: readonly DoctorEntry[] = [uncommittedSyncDeletionsEntry,unindexedFilesEntry,overwrittenEditsEntry,+ rowsBehindEntry,syncConfigKeysEntry,// #6712 PR 4a: the read-only convergence shadow (deep tier: a full level read per source).managedSyncConvergenceEntry,diff --git a/src/commands/repair.ts b/src/commands/repair.tsindex 58ba5a32b5..d42445ea5c 100644--- a/src/commands/repair.ts+++ b/src/commands/repair.ts@@ -85,6 +85,7 @@ export const REPAIR_HELP = `Usage: gbrain repair [<kind>] [--apply] [--source <igbrain repair ghost-pages --source <id> [--apply --expect <preview-hash> --yes] [--json]gbrain repair legacy-twins --source <id> [--apply --expect <preview-hash> --yes] [--json]gbrain repair uncommitted-deletions --source <id> [--after <page-id>] [--include-ambiguous] [--apply --expect <preview-hash> --yes] [--json]+ gbrain repair rows-behind --source <id> [--include-ambiguous] [--apply --expect <preview-hash>] [--json]gbrain repair generations --kind <kind> [--mode restore|release-held] (--run <id> | --since <ISO-8601|7d> | --key <owner> | --generation <id> | --held)[--source <id>] [--apply --expect <preview-hash> --yes] [--json]gbrain repair url-clone-fences [--source <id>] [--apply --expect <preview-hash> --yes] [--json]@@ -187,6 +188,7 @@ Malformed facts/takes fences (preview, apply, undo): docs/guides/repair.md#fenceA write recovery blocked on unexpected_file_bytes: docs/guides/repair.md#stuck-recovery.Live pages whose canonical file is missing (ghost pages): docs/guides/repair.md#ghost-pages.Pages a sync soft-deleted although Git never held their file (restore before the purge; purged pages need a backup): docs/guides/repair.md#uncommitted-deletions.+Pages a managed sync's checkpoint moved past with an older version of their file: docs/guides/repair.md#rows-behind.A sources add --url clone whose pull stops at pull_blocked_local_changes: docs/guides/repair.md#url-clone-fences.Renames whose identity sync did not keep (rename-identity): docs/guides/live-sync.md#renaming-a-page.`;diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex a834798000..31acc0d134 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1372,6 +1372,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.514.0', id: 'storage_ignored_dirs_8015', text: 'When gbrain.yml lists a deprecated `supabase_only` next to canonical keys (which ignores it), a managed sync now holds only the missing-file pages under the ignored directories `db_only` does not already cover, and deletes other missing-file pages as usual; it used to hold every missing-file page of the source. `gbrain storage status` now names those directories, and the deprecation warning no longer points to a `gbrain doctor --fix` rename that does not exist. A `db_only` or `supabase_only` line whose inline value the parser refuses (a missing comma, a nested list, a bare scalar) now counts as unresolved even when another key resolves, so missing-file pages are held rather than deleted.' },{ since: '0.60.514.0', id: 'company_db_only_keep_8014', text: 'A company-brain source now keeps a live page under a declared `storage.db_only` directory when its file is not in the approved manifest, and keeps every such page while its gbrain.yml storage section is invalid, as other managed sources do; it used to delete them. The decision reads gbrain.yml at the approved commit, never the working tree.' },{ since: '0.60.514.0', id: 'redaction_marker_not_credential_7997', text: 'The transcript `labeled_credential` detector no longer reads an importer redaction marker (`login **<REDACTED:user-pattern>**`) as a typed user/password pair, so a correctly redacted page clears `gbrain transcripts audit-secrets`; a password written beside a marker is still found. The audit detector version moves to 3, so `gbrain doctor` asks for a fresh audit once.' },+ { since: 'TBD', id: 'rows_behind_checkpoint_8071', text: 'New doctor check `sync_rows_behind_checkpoint` and explicit-only repair kind `gbrain repair rows-behind --source <id>` (#8071): on each managed source\'s owner host, doctor compares every live Markdown page with its file read from Git at the sync checkpoint (`sources.last_commit`) and warns about rows that hold an older version with no hold, which no later sync re-imports because the import record names the current file. The repair previews each row with its path, checkpoint blob and action and writes nothing; `--apply --expect <hash>` re-imports the committed file through the managed import (no file is written), or opens the hold sync would have opened when that import is refused or the file is over the read bound. Rows with no import record join only with `--include-ambiguous`. Bounded by `GBRAIN_DOCTOR_ROWS_BEHIND_TIMEOUT_MS` (default 10 s); not applicable on repo-less brains and off the owner host. It never runs on upgrade or automatically.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/doctor-categories.ts b/src/core/doctor-categories.tsindex 47a09a31b7..46095b0ed1 100644--- a/src/core/doctor-categories.ts+++ b/src/core/doctor-categories.ts@@ -250,6 +250,8 @@ export const BRAIN_CHECK_NAMES: ReadonlySet<string> = new Set(['sync_landing_gaps',// #6712: live pages whose database-only edit an incremental sync overwrote without a hold (doctor/checks/overwritten-edits.ts).'sync_overwritten_db_edits',+ // #8071: rows a managed sync's checkpoint moved past, compared with the file at the checkpoint commit (doctor/checks/rows-behind.ts).+ 'sync_rows_behind_checkpoint',// #7891: provenance stamps and trust markers a write removed before #7892 (doctor/checks/provenance-stamp-drift.ts).'provenance_stamp_drift','unified_multimodal_coverage',diff --git a/src/core/persistence/file-repair.ts b/src/core/persistence/file-repair.tsindex aad2518489..3dac43e0bb 100644--- a/src/core/persistence/file-repair.ts+++ b/src/core/persistence/file-repair.ts@@ -216,8 +216,8 @@ export interface RepairPublicationInput {export type RepairPublication =| { status: 'refused'; refusal: ContentRefusal }- /** Importing these bytes would store something other than the file says (retained tags, a withdrawal, sanitization). */- | { status: 'overlay' }+ /** Importing these bytes would store something other than the file says (retained tags, a withdrawal, sanitization); `noop`: the page already holds that result. */+ | { status: 'overlay'; noop: boolean }| { status: 'ready'; ready: PreparedContentImport; digest: string; fields: ReturnType<typeof canonicalRepairFields>; renamedType?: string };/**@@ -248,7 +248,7 @@ export async function prepareRepairPublication(engine: BrainEngine, input: Repaiconst renamedType = renamed && parsedInput.typeExplicit !== true ? parsedInput.type : undefined;const tags = [...new Set([...(input.base?.tags ?? []), ...prepared.parsedPage.tags])].sort();const fields = canonicalRepairFields({ ...prepared.parsedPage, type: renamedType ?? prepared.parsedPage.type }, tags);- if (digest(canonicalRepairFields(parsed, parsed.tags)) !== digest(fields)) return { status: 'overlay' };+ if (digest(canonicalRepairFields(parsed, parsed.tags)) !== digest(fields)) return { status: 'overlay', noop: prepared.noop };return { status: 'ready', ready: prepared, digest: digest(fields), fields, ...(renamedType ? { renamedType } : {}) };}diff --git a/src/core/persistence/git-gap.ts b/src/core/persistence/git-gap.tsindex 6e84ecc167..34276b6210 100644--- a/src/core/persistence/git-gap.ts+++ b/src/core/persistence/git-gap.ts@@ -180,16 +180,16 @@ export function isGitCheckout(root: string): boolean {}/**- * HEAD of the checkout at `root`, listed once with `ls-tree -r -l -z --full-tree` under the source's directory. Null when- * Git cannot answer (not a checkout, a failed or truncated read).+ * HEAD of the checkout at `root` (or the commit `rev` names), listed once with `ls-tree -r -l -z --full-tree` under the+ * source's directory. Null when Git cannot answer (not a checkout, an unknown commit, a failed or truncated read).*/-export async function readHeadTree(root: string): Promise<HeadTree | null> {+export async function readHeadTree(root: string, rev = 'HEAD'): Promise<HeadTree | null> {const top = gitLine(root, ['rev-parse', '--show-toplevel']);const format = gitLine(root, ['rev-parse', '--show-object-format']);if (top === null || (format !== 'sha1' && format !== 'sha256')) return null;const gitRoot = realpathSync(top), real = realpathSync(root);- const head = hardenedGitSync(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], GIT_LIMITS);- if (!head.ok) return head.reason === 'exit' && head.status === 1 ? { gitRoot, format, commit: null, blobs: new Map() } : null;+ const head = hardenedGitSync(root, ['rev-parse', '--verify', '--quiet', `${rev}^{commit}`], GIT_LIMITS);+ if (!head.ok) return rev === 'HEAD' && head.reason === 'exit' && head.status === 1 ? { gitRoot, format, commit: null, blobs: new Map() } : null;const commit = head.stdout.toString('utf8').trim();const scope = real === gitRoot ? '' : real.slice(gitRoot.length + 1);const blobs = new Map<string, TreeBlob>();diff --git a/src/core/persistence/preview-approval.ts b/src/core/persistence/preview-approval.tsindex a62a4236e2..0712d905aa 100644--- a/src/core/persistence/preview-approval.ts+++ b/src/core/persistence/preview-approval.ts@@ -40,7 +40,7 @@ export const PREVIEW_APPROVAL_OP = 'repair-approval';/** The default `purgeStaleCheckpoints` TTL; an older approved set may already be gone. */export const APPROVAL_MAX_AGE_DAYS = 7;-export type PreviewApprovalCommand = 'authorize-legacy' | 'jobs-cancel' | 'stale-atoms' | 'atoms-restore' | 'extractor-facts' | 'conversation-labels' | 'captured-facts' | 'redacted-facts' | 'loop-facts' | 'ontology-facts' | 'facts-rehome' | 'consolidate-ties' | 'duplicate-facts' | 'failed-writes' | 'split-facts' | 'frontmatter' | 'fences' | 'slug-conflicts' | 'managed-sync-orphans' | 'frontmatter-keys' | 'file-drift' | 'stuck-recovery' | 'ghost-pages' | 'origin-twins' | 'receipt-compaction' | 'accepted-takes' | 'rename-identity' | 'overwritten-edits' | 'legacy-twins' | 'missing-tables' | 'segmented-mirror' | 'uncommitted-deletions' | 'visibility' | 'generations' | 'fact-claim-dates' | 'timeline-order' | 'provenance' | 'secret-spans';+export type PreviewApprovalCommand = 'authorize-legacy' | 'jobs-cancel' | 'stale-atoms' | 'atoms-restore' | 'extractor-facts' | 'conversation-labels' | 'captured-facts' | 'redacted-facts' | 'loop-facts' | 'ontology-facts' | 'facts-rehome' | 'consolidate-ties' | 'duplicate-facts' | 'failed-writes' | 'split-facts' | 'frontmatter' | 'fences' | 'slug-conflicts' | 'managed-sync-orphans' | 'frontmatter-keys' | 'file-drift' | 'stuck-recovery' | 'ghost-pages' | 'origin-twins' | 'receipt-compaction' | 'accepted-takes' | 'rename-identity' | 'overwritten-edits' | 'legacy-twins' | 'missing-tables' | 'segmented-mirror' | 'uncommitted-deletions' | 'visibility' | 'generations' | 'fact-claim-dates' | 'timeline-order' | 'provenance' | 'secret-spans' | 'rows-behind';export interface ApprovedSetKey {command: PreviewApprovalCommand;diff --git a/src/core/persistence/rows-behind.ts b/src/core/persistence/rows-behind.tsnew file mode 100644index 0000000000..625b507388--- /dev/null+++ b/src/core/persistence/rows-behind.ts@@ -0,0 +1,216 @@+/**+ * #8071: rows a managed sync's checkpoint moved past. `sources.last_commit` says every file of the source is imported as of+ * that commit; a sync that advanced it without importing a changed file (and recorded the file as imported) leaves the+ * row on an older version with no hold, and every later sync reports the source up to date. Landing checks see a live,+ * unheld row and pass.+ *+ * `scanRowsBehind` compares each live Markdown page of a managed source with its file at the checkpoint commit, read+ * from Git (never the working tree, never the import record's word): the export view against the committed blob+ * (git-gap.ts `compareInlineExportFile`; a page stored in segments by streamed hash, `compareSegmentedExportBlob`), and a+ * differing row is confirmed by the importer itself (`prepareRepairPublication`, no writes): a row the import of the+ * checkpoint bytes would leave unchanged is current. Direction comes from the page's import record: a row whose revision+ * is the one its last sync import produced (the database has not moved since) is `behind`; one the database moved since+ * is `database_moved` and not reported (file-drift's territory); one with no record (or a record without a revision) is+ * `unproven`, listed apart. Not reported either: held paths (the hold already says it), paths with no blob at the+ * checkpoint, non-Markdown pages, declared database-only pages, and paths that changed between the checkpoint and HEAD+ * (the next sync imports them).+ *+ * Bounded: the checkpoint tree is listed once (and HEAD's only when it differs), pages are read in id batches of+ * ROWS_BEHIND_BATCH in read-only transactions, committed blobs are read in bounded `cat-file --batch` calls, and a blob+ * over the sync read bound (SYNC_READ_BOUND, the page ceiling) is never read: its row is reported with the+ * `file_too_large` refusal sync would hold it with. A deadline stops the scan between batches (`complete: false`).+ * Applies only on the owner host of a managed source with a checkout and a checkpoint; everything else, a repo-less+ * brain included, is `not_applicable` with its reason. Read-only. Readers: doctor `sync_rows_behind_checkpoint` and+ * `gbrain repair rows-behind`.+ */+import { realpathSync } from 'node:fs';+import { relative, sep } from 'node:path';+import type { BrainEngine } from '../engine.ts';+import { readExportPages, readExportWithdrawals, type ExportWithdrawal } from '../export-snapshot.ts';+import { canonicalPath, sourceContext } from '../ghost-pages.ts';+import { privatePagesFilterFragment, readHonorAliases } from '../search/private-visibility.ts';+import { scannerSourcePath } from '../write-through.ts';+import { managedPersistenceEnabled } from './ownership.ts';+import { compareInlineExportFile, compareSegmentedExportBlob, declaredDatabaseOnly, readBlobs, readHeadTree, type ExportFileComparison, type TreeBlob } from './git-gap.ts';+import { prepareRepairPublication, repairScreenConfig } from './file-repair.ts';+import { SYNC_READ_BOUND } from './sync-blobs.ts';+import { heldGitPaths, readSyncImportProvenances } from './sync-holds.ts';+import { isSourceDbOnlySlug } from './source-storage.ts';++export const ROWS_BEHIND_BATCH = 256;+/** Rows one scan lists per class; counts go on past it (`truncated`). */+export const ROWS_BEHIND_LIST_LIMIT = 1000;+export const ROWS_BEHIND_DOCS = 'docs/guides/repair.md#rows-behind';++/** Why a row is not reported, counted per scan. */+export type RowsBehindSkip = 'held' | 'database_moved' | 'changed_after_checkpoint' | 'no_file_at_checkpoint' | 'not_markdown' | 'declared_database_only'+ | 'not_regular_file' | 'unsafe_path' | 'unconfirmed' | 'current';++export interface RowBehind {+ slug: string;+ page_id: number;+ /** The page revision the scan read; a repair is bound to it. */+ revision: string;+ /** Source-root-relative file path (the hold key). */+ path: string;+ /** The page's recorded origin. */+ source_path: string;+ /** The file's blob at the checkpoint and its size. */+ blob: string;+ size: number;+ /** `recorded`: the page's import record holds this revision; `none`: no record proves the database did not move. */+ record: 'recorded' | 'none';+ /** The import of the checkpoint file is refused (sync would hold it): the code, reason and message a hold carries. */+ refusal?: { code: string; reason?: string; key?: string; line?: number; message: string };+ /** The import would keep page data the file does not carry, so it cannot be applied as the exact file bytes. */+ overlay?: true;+ /** The digest of the page the import of the checkpoint bytes publishes (`prepareRepairPublication`). */+ digest?: string;+}++export interface RowsBehindScan {+ source_id: string;+ status: 'known' | 'unknown' | 'not_applicable';+ reason?: string;+ checkpoint: string | null;+ head: string | null;+ /** False when the deadline stopped the scan; the counts cover the pages read. */+ complete: boolean;+ /** Live file-backed pages read. */+ pages: number;+ behind: RowBehind[];+ unproven: RowBehind[];+ /** More rows than ROWS_BEHIND_LIST_LIMIT in a class; `behind_count` / `unproven_count` keep counting. */+ truncated: boolean;+ behind_count: number;+ unproven_count: number;+ counts: Partial<Record<RowsBehindSkip, number>>;+}++type Key = { id: string; slug: string; source_id: string; source_path: string; source_uri: string | null; withheld_source_path: string | null; type: string;+ frontmatter: unknown; database_only_reason: string | null; segmented: boolean; lineage_private: boolean; revision: string };++const empty = (sourceId: string, status: RowsBehindScan['status'], reason?: string): RowsBehindScan => ({ source_id: sourceId, status, ...(reason ? { reason } : {}),+ checkpoint: null, head: null, complete: status !== 'unknown', pages: 0, behind: [], unproven: [], truncated: false, behind_count: 0, unproven_count: 0, counts: {} });++const isMarkdown = (path: string) => /\.mdx?$/i.test(path);++export async function scanRowsBehind(engine: BrainEngine, sourceId: string, opts: { deadlineAt?: number; listLimit?: number } = {}): Promise<RowsBehindScan> {+ if (!(await managedPersistenceEnabled(engine))) return empty(sourceId, 'not_applicable', 'not_managed');+ const context = await sourceContext(engine, sourceId);+ if (!context.ok) return empty(sourceId, context.status, context.reason);+ const [source] = await engine.executeRaw<{ last_commit: string | null }>('SELECT last_commit FROM sources WHERE id=$1', [sourceId]);+ if (!source?.last_commit) return empty(sourceId, 'not_applicable', 'no_checkpoint');+ const root = context.root;+ try { isSourceDbOnlySlug(root, '', 'refuse'); } catch { return empty(sourceId, 'unknown', 'invalid_source_config'); }+ const checkpoint = await readHeadTree(root, source.last_commit);+ if (!checkpoint?.commit) return { ...empty(sourceId, 'unknown', 'checkpoint_unreadable'), checkpoint: source.last_commit };+ const headRead = await readHeadTree(root, 'HEAD');+ const head = headRead?.commit === checkpoint.commit ? checkpoint : headRead;+ if (!head) return { ...empty(sourceId, 'unknown', 'head_unreadable'), checkpoint: checkpoint.commit };+ await readHonorAliases(engine);+ const scope = relative(checkpoint.gitRoot, realpathSync(root)).split(sep).join('/');+ const gitPath = (rel: string) => scope ? `${scope}/${rel}` : rel;+ const policy = { mirror: false, databaseOnlySource: false, dbOnly: (slug: string) => isSourceDbOnlySlug(root, slug, 'refuse'), ignored: new Set<string>() };+ const scan: RowsBehindScan = { ...empty(sourceId, 'known'), checkpoint: checkpoint.commit, head: head.commit };+ const limit = opts.listLimit ?? ROWS_BEHIND_LIST_LIMIT;+ const count = (why: RowsBehindSkip) => { scan.counts[why] = (scan.counts[why] ?? 0) + 1; };+ const screen = await repairScreenConfig(engine, sourceId);+ const withdrawals: ExportWithdrawal[] = await readExportWithdrawals(engine, sourceId);+ const incarnation = context.owner.source_incarnation;+ for (let cursor = '0'; ;) {+ if (opts.deadlineAt !== undefined && Date.now() >= opts.deadlineAt) { scan.complete = false; break; }+ const candidates: Array<{ key: Key; rel: string; blob: TreeBlob; record: RowBehind['record']; content: Buffer | null; compared: ExportFileComparison | null }> = [];+ 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, source_uri, withheld_source_path, type, frontmatter, database_only_reason,+ body_storage='segmented' AS segmented, knowledge_revision::text AS revision, NOT ${privatePagesFilterFragment('pages')} AS lineage_private+ FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND source_path IS NOT NULL AND pages.id > $2::bigint ORDER BY pages.id LIMIT ${ROWS_BEHIND_BATCH}`, [sourceId, cursor]);+ if (!batch.length) return true;+ cursor = batch[batch.length - 1]!.id;+ const rows: Array<{ key: Key; rel: string; blob: TreeBlob }> = [];+ for (const key of batch) {+ scan.pages++;+ const path = canonicalPath(context, key);+ if (!path) { count('unsafe_path'); continue; }+ const rel = relative(root, path).split(sep).join('/');+ if (rel.startsWith('../') || rel === '..') { count('unsafe_path'); continue; }+ if (!isMarkdown(rel)) { count('not_markdown'); continue; }+ const frontmatter = typeof key.frontmatter === 'string' ? JSON.parse(key.frontmatter) : key.frontmatter;+ if (declaredDatabaseOnly({ ...key, frontmatter }, rel, policy)) { count('declared_database_only'); continue; }+ const blob = checkpoint.blobs.get(gitPath(rel));+ if (!blob) { count('no_file_at_checkpoint'); continue; }+ if (blob.mode !== '100644' && blob.mode !== '100755') { count('not_regular_file'); continue; }+ rows.push({ key, rel, blob });+ }+ if (!rows.length) return batch.length < ROWS_BEHIND_BATCH;+ const held = await heldGitPaths(tx, sourceId, incarnation, rows.map(row => row.rel));+ const records = await readSyncImportProvenances(tx, sourceId, incarnation, rows.map(row => Number(row.key.id)));+ const compare: typeof rows = [];+ for (const row of rows) {+ if (held.has(row.rel)) { count('held'); continue; }+ const record = records.get(Number(row.key.id));+ if (record?.revision != null && String(record.revision) !== row.key.revision) { count('database_moved'); continue; }+ if (head !== checkpoint && head.blobs.get(gitPath(row.rel))?.oid !== row.blob.oid) { count('changed_after_checkpoint'); continue; }+ compare.push(row);+ }+ const readable = compare.filter(row => row.blob.size <= SYNC_READ_BOUND);+ const bytes = await readBlobs(root, readable.filter(row => !row.key.segmented).map(row => row.blob));+ if (!bytes) throw new Error(`Git could not read committed files of source ${sourceId} at ${checkpoint.commit}`);+ const snapshots = await readExportPages(tx, readable.map(row => row.key), withdrawals);+ const byId = new Map(snapshots.map(snapshot => [String(snapshot.page.id), snapshot]));+ for (const row of compare) {+ const recordState: RowBehind['record'] = records.get(Number(row.key.id))?.revision != null ? 'recorded' : 'none';+ if (row.blob.size > SYNC_READ_BOUND) { candidates.push({ ...row, record: recordState, content: null, compared: null }); continue; }+ const snapshot = byId.get(row.key.id);+ if (!snapshot) continue;+ const compared = row.key.segmented ? await compareSegmentedExportBlob(tx, snapshot, withdrawals, row.blob, checkpoint.format)+ : compareInlineExportFile(bytes.get(row.blob.oid)!, scannerSourcePath(root, `${root}/${row.rel}`, context.mode), snapshot);+ if (compared.state === 'equal') { count('current'); continue; }+ candidates.push({ ...row, record: recordState, content: bytes.get(row.blob.oid) ?? null, compared });+ }+ return batch.length < ROWS_BEHIND_BATCH;+ });+ for (const candidate of candidates) {+ const row = await confirm(engine, sourceId, root, screen, candidate);+ if (typeof row === 'string') { count(row); continue; }+ const list = row.record === 'recorded' ? scan.behind : scan.unproven;+ if (row.record === 'recorded') scan.behind_count++; else scan.unproven_count++;+ if (list.length < limit) list.push(row); else scan.truncated = true;+ }+ if (done) break;+ }+ return scan;+}++/**+ * A differing row confirmed by the importer: what the import of the checkpoint bytes would do to it. `current` when the+ * import is a no-op (the row holds that version after all); `unconfirmed` when the confirmation cannot run or the page+ * moved while it was read (never repaired; the next scan reads it again).+ */+async function confirm(engine: BrainEngine, sourceId: string, root: string, screen: Awaited<ReturnType<typeof repairScreenConfig>>,+ candidate: { key: Key; rel: string; blob: TreeBlob; record: RowBehind['record']; content: Buffer | null }): Promise<RowBehind | 'current' | 'unconfirmed'> {+ const { key, rel, blob, record } = candidate;+ const base: RowBehind = { slug: key.slug, page_id: Number(key.id), revision: key.revision, path: rel, source_path: key.source_path, blob: blob.oid, size: blob.size, record };+ if (candidate.content === null && blob.size > SYNC_READ_BOUND) {+ return { ...base, refusal: { code: 'file_too_large', message: `File too large (${blob.size} bytes; the sync read bound is the ${SYNC_READ_BOUND}-byte page ceiling), so it was not read.` } };+ }+ const bytes = candidate.content ?? (await readBlobs(root, [{ oid: blob.oid, size: blob.size, mode: blob.mode }]))?.get(blob.oid) ?? null;+ const content = bytes?.toString('utf8') ?? null;+ if (content === null || !Buffer.from(content).equals(bytes!)) return 'unconfirmed';+ try {+ const snapshot = await engine.readPageSnapshot(key.slug, { sourceId, includeDeleted: true });+ if (!snapshot || String(snapshot.page.id) !== key.id || snapshot.revision !== key.revision) return 'unconfirmed';+ const publication = await prepareRepairPublication(engine, { sourceId, slug: key.slug, sourcePath: key.source_path, path: rel, root, content, snapshot, base: snapshot, ...screen });+ if (publication.status === 'refused') {+ const { code, message } = publication.refusal;+ const reason = 'reason' in publication.refusal ? publication.refusal.reason : undefined;+ const where = publication.refusal as { key?: string; line?: number };+ return { ...base, refusal: { code, message, ...(reason ? { reason: String(reason) } : {}), ...(where.key ? { key: where.key } : {}), ...(where.line !== undefined ? { line: where.line } : {}) } };+ }+ if (publication.status === 'overlay') return publication.noop ? 'current' : { ...base, overlay: true };+ return publication.ready.noop ? 'current' : { ...base, digest: publication.digest };+ } catch {+ return 'unconfirmed';+ }+}diff --git a/src/core/repair/core.ts b/src/core/repair/core.tsindex 1f53ca7e86..fb46aa58e3 100644--- a/src/core/repair/core.ts+++ b/src/core/repair/core.ts@@ -51,7 +51,7 @@ import { classifyItemFailure, ItemRun, type ItemFailure } from '../item-failure.import type { ProgressReporter } from '../progress.ts';import type { GenerationsSelection } from '../generations/repair.ts';-export const REPAIR_KINDS = ['timeline', 'visibility', 'safe-chunks', 'contextual-mode', 'connector-checkpoints', 'request-indexes', 'connector-fences', 'take-supersession', 'accepted-takes', 'orphan-bindings', 'embedding-effects', 'attribution-backfill', 'planner-stats', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'extractor-facts', 'conversation-labels', 'captured-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'fences', 'slug-conflicts', 'timeline-comments', 'timeline-order', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'uncommitted-deletions', 'generations', 'fact-claim-dates', 'provenance', 'secret-spans'] as const;+export const REPAIR_KINDS = ['timeline', 'visibility', 'safe-chunks', 'contextual-mode', 'connector-checkpoints', 'request-indexes', 'connector-fences', 'take-supersession', 'accepted-takes', 'orphan-bindings', 'embedding-effects', 'attribution-backfill', 'planner-stats', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'extractor-facts', 'conversation-labels', 'captured-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'fences', 'slug-conflicts', 'timeline-comments', 'timeline-order', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'uncommitted-deletions', 'generations', 'fact-claim-dates', 'provenance', 'secret-spans', 'rows-behind'] as const;export type RepairKind = typeof REPAIR_KINDS[number];export interface RepairScope { brain_id: string; source_ids: string[] }diff --git a/src/core/repair/registry.ts b/src/core/repair/registry.tsindex ebe06d611e..719d1edac1 100644--- a/src/core/repair/registry.ts+++ b/src/core/repair/registry.ts@@ -86,6 +86,7 @@ import { uncommittedDeletionsRepair, UNCOMMITTED_DELETIONS_CONSENT_TEXT } from 'import { factClaimDatesRepair } from './fact-claim-dates.ts';import { provenanceRepair } from './provenance.ts';import { secretSpansRepair } from './secret-spans.ts';+import { rowsBehindRepair } from './rows-behind.ts';import { generationsRepair, generationsSelectionArgv, type GenerationsSelection } from '../generations/repair.ts';import { restoreDaysHint } from '../generations/config.ts';import { ERROR_CATALOGUE, catalogueError } from '../error-catalogue.ts';@@ -581,6 +582,16 @@ const SPECS: Record<RepairKind, Omit<RepairKindSpec, 'kind'>> = {+ 'page, then re-scans it. Database only: no file write, no Git commit, and a sync hold stays, so held pages are redacted where they are stored. '+ 'History (page versions, receipts, Git) is kept. Trusted local CLI only; runs only when named; never on upgrade.',},+ 'rows-behind': {+ handler: rowsBehindRepair, embeds: 'effect', checks: ['sync_rows_behind_checkpoint'], explicit_only: true, preview_bound: true,+ summary: 'Re-import the rows a managed sync\'s checkpoint moved past (#8071): the page holds an older version of its file than the commit '+ + 'sources.last_commit says was imported, with no hold, so no later sync re-imports it. Needs --source; refused off the canonical owner host '+ + '(not_owner_host). The preview compares each row with the file read from Git at the checkpoint (confirmed by the importer), lists each row '+ + 'with its path, blob and action and writes nothing: reimport (the committed bytes through the managed import; no file is written), or '+ + 'hold:<code> when that import is refused or the file is over the sync read bound (the hold sync would have opened). Rows with no import record '+ + 'join only with --include-ambiguous; rows with an uncommitted working-tree edit are left out. --apply --expect <hash> applies exactly that set. '+ + 'Runs only when named; never on upgrade.',+ },'generations': {handler: generationsRepair, embeds: 'effect', checks: ['generation_retirements', 'generation_held', 'generation_pending'], explicit_only: true, preview_bound: true, consent: 'destructive',consentText: {diff --git a/src/core/repair/rows-behind.ts b/src/core/repair/rows-behind.tsnew file mode 100644index 0000000000..55a7513e7d--- /dev/null+++ b/src/core/repair/rows-behind.ts@@ -0,0 +1,184 @@+/**+ * `gbrain repair rows-behind --source <id> [--include-ambiguous] [--apply --expect <hash>]` (#8071): re-import the rows a+ * managed sync's checkpoint moved past (`persistence/rows-behind.ts`: the row holds an older version of its file than+ * `sources.last_commit`, with no hold), from the file as committed at the checkpoint.+ *+ * Explicit-only and preview-bound: the preview (on the source's canonical owner host only) lists each row with its path,+ * the checkpoint blob and what the apply does, saves the set under its hash and writes nothing. `reimport`: the checkpoint+ * bytes are imported through the managed file repair (`submitManagedFileRepair`: the same screen, preparation and+ * projections a managed sync import uses, bound to the page revision and the previewed result; the file on disk already+ * holds those bytes, so no file is written, and the import record is rewritten). `hold:<code>`: the import of the+ * checkpoint file is refused (or it is over the sync read bound), so the apply opens the hold sync would have opened, with+ * the refusal's code and message. Left out of the set and listed: rows with no import record (`excluded:unproven`, joined+ * by --include-ambiguous), rows whose working-tree file differs from the checkpoint blob (`excluded:worktree_differs`: an+ * uncommitted edit; commit it and sync), and rows whose import would keep page data the file does not carry+ * (`excluded:import_overlay`). `--apply --expect <hash>` applies exactly that set; a row whose page, checkpoint or file+ * changed since is `changed_since_preview`. Never runs on upgrade, from --all or from the remediation plan.+ */+import { createHash } from 'node:crypto';+import { readFileSync } from 'node:fs';+import { join } from 'node:path';+import type { BrainEngine } from '../engine.ts';+import { opError, OperationError, type OperationContext } from '../ops/contract.ts';+import { readFix } from '../ops/op-fix.ts';+import { RECOVERY_VERSION } from '../markdown.ts';+import { sourceContext, type GhostOwner } from '../ghost-pages.ts';+import { acceptedPendingReceipt } from '../persistence/accepted-pending.ts';+import { prepareRepairPublication, repairScreenConfig, submitManagedFileRepair } from '../persistence/file-repair.ts';+import { readBlobs } from '../persistence/git-gap.ts';+import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';+import { ROWS_BEHIND_DOCS, scanRowsBehind, type RowBehind } from '../persistence/rows-behind.ts';+import { SYNC_READ_BOUND } from '../persistence/sync-blobs.ts';+import { readGitHold, writeGitHold, type GitHoldRecord } from '../persistence/sync-holds.ts';+import { afterCursor, repairRequestId, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairScope } from './core.ts';++export const rowsBehindPreviewCommand = (sourceId: string) => `gbrain repair rows-behind --source ${sourceId}`;+const previewFix = (sourceId: string) => readFix('Previews the rows behind the sync checkpoint again; writes nothing.', { argv: ['gbrain', 'repair', 'rows-behind', '--source', sourceId, '--json'] });++type Action = 'reimport' | 'hold';+interface Selection { source_ids: string[]; include_ambiguous: boolean }+interface ApprovedRow extends RowBehind { source_id: string; checkpoint: string; action: Action; owner: GhostOwner; selection: Selection }+interface RowItem extends RepairItem { row: ApprovedRow; hash: string; last: boolean }++const sha256 = (bytes: Buffer) => createHash('sha256').update(bytes).digest('hex');+const sameOwner = (a: GhostOwner | undefined, b: GhostOwner) => !!a && a.host_id === b.host_id && a.worktree_id === b.worktree_id+ && a.owner_epoch === b.owner_epoch && a.source_incarnation === b.source_incarnation;++function notOwnerHost(sourceId: string): OperationError {+ return opError('not_owner_host', `Rows behind the sync checkpoint of source ${sourceId} can only be checked and re-imported on its canonical owner host.`,+ `This host does not own source ${sourceId}'s active canonical worktree, so it cannot read the checkpoint commit; nothing was listed or changed. Run ${rowsBehindPreviewCommand(sourceId)} on the owner host (writer status names it).`,+ { fix: readFix('Shows the source\'s canonical binding and owner host, read-only.', { argv: ['gbrain', 'sources', 'writer', 'status', '--source', sourceId, '--json'] }), docs: ROWS_BEHIND_DOCS });+}++const hashParts = (scope: RepairScope, owner: GhostOwner | null, selection: Selection, checkpoint: string | null, rows: Array<Pick<ApprovedRow, 'slug' | 'revision' | 'blob' | 'action' | 'digest'>>) =>+ ({ kind: 'rows-behind-v1', brain_id: scope.brain_id, selection, owner, checkpoint, rows: rows.map(row => [row.slug, row.revision, row.blob, row.action, row.digest ?? null]) });++const item = (row: ApprovedRow, hash: string, index: number, last: boolean): RowItem =>+ ({ cursor: { phase: 0, id: index + 1 }, source_id: row.source_id, slug: row.slug, chars: 0, action: row.action === 'hold' ? `hold:${row.refusal!.code}` : 'reimport', row, hash, last });++/** The committed bytes of a blob, or null when Git cannot read it. */+async function blobBytes(root: string, row: Pick<RowBehind, 'blob' | 'size'>): Promise<Buffer | null> {+ return (await readBlobs(root, [{ oid: row.blob, size: row.size, mode: '100644' }]))?.get(row.blob) ?? null;+}++/** Whether the working-tree file holds exactly the checkpoint bytes. */+function worktreeMatches(root: string, path: string, bytes: Buffer): boolean {+ try { return sha256(readFileSync(join(root, path))) === sha256(bytes); } catch { return false; }+}++export const rowsBehindRepair: RepairHandler = {+ kind: 'rows-behind',+ embeds: true,+ outcomeItemsLimit: 1000,+ async plan(engine, scope, after, opts): Promise<RepairPlan> {+ if (scope.source_ids.length !== 1) {+ throw opError('invalid_params', 'gbrain repair rows-behind needs --source <id>.',+ 'Rows are compared with the checkpoint commit in each source\'s own checkout on its canonical owner host; name one source, e.g. gbrain repair rows-behind --source default.',+ { fix: readFix('Lists the registered sources.', { argv: ['gbrain', 'sources', 'list', '--json'] }), docs: ROWS_BEHIND_DOCS });+ }+ const sourceId = scope.source_ids[0]!;+ const command = rowsBehindPreviewCommand(sourceId);+ const selection: Selection = { source_ids: scope.source_ids, include_ambiguous: opts?.includeAmbiguous === true };+ const context = await sourceContext(engine, sourceId);+ if (!context.ok && context.reason === 'not_owner_host') throw notOwnerHost(sourceId);+ const owner = context.ok ? context.owner : null;+ if (opts?.apply) {+ if (!opts.expect) {+ throw opError('invalid_params', 'gbrain repair rows-behind --apply re-imports only the set a preview printed.',+ `Preview first: ${command} — then run the apply command it prints: ${command} --apply --expect <preview-hash>`, { fix: previewFix(sourceId), docs: ROWS_BEHIND_DOCS });+ }+ const approved = await loadApprovedSet<ApprovedRow>(engine, { command: 'rows-behind', hash: opts.expect, previewCommand: command,+ emptyHash: async () => previewHash(hashParts(scope, owner, selection, (await scanRowsBehind(engine, sourceId)).checkpoint, [])) });+ if (approved.items.some(row => JSON.stringify(row.selection) !== JSON.stringify(selection) || !owner || !sameOwner(owner, row.owner))) throw previewChangedError(opts.expect, command);+ const items = approved.items.map((row, index) => item(row, opts.expect!, index, index === approved.items.length - 1));+ return { items: items.filter(entry => afterCursor(entry.cursor, after)), preview_hash: opts.expect, residuals: {} };+ }+ const scan = await scanRowsBehind(engine, sourceId);+ if (scan.status !== 'known' || !context.ok) {+ const hash = previewHash(hashParts(scope, owner, selection, scan.checkpoint, []));+ return { items: [], preview_hash: hash, residuals: {}, warnings: [`Source ${sourceId} was not compared (${scan.reason ?? 'not_applicable'}): ${scan.status === 'unknown'+ ? 'its checkout or the checkpoint commit could not be read on this host; fix the checkout and preview again'+ : 'it has no managed checkout with a sync checkpoint here (a repo-less source keeps its pages in the database, which is the record)'}; nothing is listed.`],+ details: { docs: ROWS_BEHIND_DOCS, status: scan.status, reason: scan.reason ?? null } };+ }+ const selected: ApprovedRow[] = [];+ const listing: NonNullable<RepairPlan['listing']> = [];+ const describe = (row: RowBehind) => `${row.path} at checkpoint ${scan.checkpoint!.slice(0, 12)} is blob ${row.blob.slice(0, 12)}; the page (revision ${row.revision}) holds an older version`;+ for (const row of [...scan.behind, ...scan.unproven]) {+ const entry = `${sourceId}:${row.slug}`;+ if (row.record === 'none' && !selection.include_ambiguous) { listing.push({ item: entry, class: 'excluded:unproven', detail: `${describe(row)}; no import record proves the database did not move since, so it joins only with --include-ambiguous` }); continue; }+ if (row.overlay) { listing.push({ item: entry, class: 'excluded:import_overlay', detail: `${describe(row)}; importing it would keep page data the file does not carry (tags, a withdrawal or sanitized text), so it is not re-imported here; gbrain repair file-drift --source ${sourceId} --slug ${row.slug} --prefer file resolves it` }); continue; }+ if (row.refusal) {+ selected.push({ ...row, source_id: sourceId, checkpoint: scan.checkpoint!, action: 'hold', owner: context.owner, selection });+ listing.push({ item: entry, class: `hold:${row.refusal.code}`, detail: `${describe(row)}; its import is refused (${row.refusal.code}: ${row.refusal.message}), so the apply holds the file as sync would` });+ continue;+ }+ const bytes = await blobBytes(context.root, row);+ if (!bytes || !worktreeMatches(context.root, row.path, bytes)) { listing.push({ item: entry, class: 'excluded:worktree_differs', detail: `${describe(row)}; the working-tree file differs from the committed one (an uncommitted edit): commit it and run gbrain sync --source ${sourceId}` }); continue; }+ selected.push({ ...row, source_id: sourceId, checkpoint: scan.checkpoint!, action: 'reimport', owner: context.owner, selection });+ listing.push({ item: entry, class: 'reimport', detail: `${describe(row)}; the apply imports the committed file through the managed import` });+ }+ const hash = previewHash(hashParts(scope, owner, selection, scan.checkpoint, selected));+ if (selected.length) await saveApprovedSet<ApprovedRow>(engine, { command: 'rows-behind', hash }, selected);+ const warnings = [+ ...(scan.truncated ? [`More rows are behind than one preview lists (${scan.behind_count} behind, ${scan.unproven_count} without a record); apply this set, then preview again for the rest.`] : []),+ ];+ return { items: selected.map((row, index) => item(row, hash, index, index === selected.length - 1)), preview_hash: hash, listing, ...(warnings.length ? { warnings } : {}),+ residuals: { ...scan.counts, pages: scan.pages, behind: scan.behind_count, unproven: scan.unproven_count },+ details: { docs: ROWS_BEHIND_DOCS, checkpoint: scan.checkpoint, head: scan.head, rows: selected.map(({ slug, path, blob, action, record, refusal }) => ({ slug, path, blob, action, record, ...(refusal ? { refusal: refusal.code } : {}) })) } };+ },+ async apply(ctx, entry, opts): Promise<RepairItemOutcome> {+ const { row, hash, last } = entry as RowItem;+ try {+ return await applyRow(ctx, row, opts?.embed !== false);+ } finally {+ if (last) await clearApprovedSet(ctx.engine, { command: 'rows-behind', hash });+ }+ },+ render(details) {+ return [` checkpoint ${String(details.checkpoint ?? '').slice(0, 12)}; each re-import goes through the managed import of the committed file (no file is written); guide: ${details.docs}`];+ },+};++const changed = (reason: string, detail: Record<string, unknown> = {}): RepairItemOutcome =>+ ({ applied: false, outcome: 'changed_since_preview', reason, detail: { ...detail, next: 'run gbrain repair rows-behind again for a new preview' } });++async function applyRow(ctx: OperationContext, row: ApprovedRow, embed: boolean): Promise<RepairItemOutcome> {+ const engine: BrainEngine = ctx.engine;+ const context = await sourceContext(engine, row.source_id);+ if (!context.ok || !sameOwner(context.owner, row.owner)) return changed('owner_changed');+ const [source] = await engine.executeRaw<{ last_commit: string | null }>('SELECT last_commit FROM sources WHERE id=$1', [row.source_id]);+ if (source?.last_commit !== row.checkpoint) return changed('checkpoint_moved', { checkpoint: source?.last_commit ?? null });+ const snapshot = await engine.readPageSnapshot(row.slug, { sourceId: row.source_id, includeDeleted: true });+ if (!snapshot || Number(snapshot.page.id) !== row.page_id || snapshot.revision !== row.revision || snapshot.page.deleted_at != null) return changed('page_moved');+ if (await readGitHold(engine, row.source_id, row.owner.source_incarnation, row.path)) return { applied: false, outcome: 'already_held' };+ const bytes = row.size > SYNC_READ_BOUND ? null : await blobBytes(context.root, row);+ const content = bytes?.toString('utf8') ?? null;+ const screen = await repairScreenConfig(engine, row.source_id);+ const publication = content === null ? null+ : await prepareRepairPublication(engine, { sourceId: row.source_id, slug: row.slug, sourcePath: row.source_path, path: row.path, root: context.root, content, snapshot, base: snapshot, ...screen });+ if (row.action === 'hold') {+ if (publication && publication.status !== 'refused') return changed('import_no_longer_refused');+ const refusal = row.refusal!;+ const held: Omit<GitHoldRecord, 'version' | 'held_at' | 'updated_at'> = { source_id: row.source_id, incarnation: row.owner.source_incarnation, path: row.path, source_path: row.source_path,+ slug: row.slug, page_id: row.page_id, code: refusal.code as GitHoldRecord['code'], message: refusal.message, upstream_version: bytes ? sha256(bytes) : null,+ observed_at: new Date().toISOString(), run_id: null, mode: 'managed',+ meta: { recovery_version: RECOVERY_VERSION, ...(refusal.reason ? { reason: refusal.reason as GitHoldRecord['meta']['reason'] } : {}), ...(refusal.key ? { key: refusal.key } : {}), ...(refusal.line !== undefined ? { line: refusal.line } : {}), blob_oid: row.blob } };+ await engine.transaction(tx => writeGitHold(tx, held));+ return { applied: true, outcome: 'held', detail: { path: row.path, code: refusal.code, checkpoint: row.checkpoint, blob: row.blob } };+ }+ if (!bytes || !content || !worktreeMatches(context.root, row.path, bytes)) return changed('worktree_differs');+ if (publication?.status !== 'ready' || publication.digest !== row.digest) return changed('result_changed');+ const local = { ...ctx, remote: false, sourceId: row.source_id } as OperationContext;+ const requestId = await repairRequestId(local, 'rows-behind', { source_id: row.source_id, slug: row.slug }, `${row.revision}:${row.blob}`);+ try {+ const outcome = await submitManagedFileRepair(local, { sourceId: row.source_id, requestId, slug: row.slug, path: row.path, sourcePath: row.source_path, content,+ beforeHash: sha256(bytes), resultDigest: row.digest!, expected_revision: row.revision, noEmbed: !embed });+ return { applied: true, outcome: 'reimported', detail: { request_id: requestId, path: row.path, checkpoint: row.checkpoint, blob: row.blob, status: outcome.status, hold_cleared: outcome.hold_cleared === true } };+ } catch (error) {+ if (acceptedPendingReceipt(error) || !(error instanceof OperationError)) throw error;+ if (['changed_since_preview', 'revision_conflict', 'page_identity_changed', 'page_not_found', 'source_changed'].includes(error.code)) return changed(error.code, { request_id: requestId });+ if (error.code === 'sync_in_progress') return { applied: false, outcome: 'skipped', reason: 'sync_in_progress', detail: { request_id: requestId, message: error.message } };+ throw error;+ }+}diff --git a/test/e2e/rows-behind-checkpoint-8071-postgres.test.ts b/test/e2e/rows-behind-checkpoint-8071-postgres.test.tsnew file mode 100644index 0000000000..dbbebecee9--- /dev/null+++ b/test/e2e/rows-behind-checkpoint-8071-postgres.test.ts@@ -0,0 +1,3 @@+import { registerPostgresTests } from '../helpers/test-backends.ts';++await registerPostgresTests(() => import('../rows-behind-checkpoint-8071.test.ts'));diff --git a/test/fix-wave-5-integration.test.ts b/test/fix-wave-5-integration.test.tsindex 064a316e54..dd6ce8ebb9 100644--- a/test/fix-wave-5-integration.test.ts+++ b/test/fix-wave-5-integration.test.ts@@ -201,7 +201,7 @@ for (const backend of testBackends()) {'uncommitted-deletions': 'gbrain repair uncommitted-deletions',// GBRA-161: the generations preview carries its ledger kind and the restore window, so the printed command runs as is.generations: 'gbrain repair generations --kind atom --since 30d', 'fact-claim-dates': 'gbrain repair fact-claim-dates',- provenance: 'gbrain repair provenance', 'secret-spans': 'gbrain repair secret-spans' };+ provenance: 'gbrain repair provenance', 'secret-spans': 'gbrain repair secret-spans', 'rows-behind': 'gbrain repair rows-behind' };// The post-upgrade banner names both findings with the kind's read-only preview.const banner = await postUpgradeRecoveryBanner(engine, 'host');diff --git a/test/fixtures/goldens/doctor/content-pglite-human.json b/test/fixtures/goldens/doctor/content-pglite-human.jsonindex 1fffff2345..c1afaab7ab 100644--- a/test/fixtures/goldens/doctor/content-pglite-human.json+++ b/test/fixtures/goldens/doctor/content-pglite-human.json@@ -232,6 +232,7 @@" [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 equal. Page detail: gbrain sources git-gap <source-id>.",diff --git a/test/fixtures/goldens/doctor/content-pglite-json.json b/test/fixtures/goldens/doctor/content-pglite-json.jsonindex 399d3d1fc0..ceffbfa26f 100644--- a/test/fixtures/goldens/doctor/content-pglite-json.json+++ b/test/fixtures/goldens/doctor/content-pglite-json.json@@ -3531,6 +3531,52 @@"name": "sync_overwritten_db_edits","status": "ok"},+ {+ "category": "brain",+ "details": {+ "count": 0,+ "docs": "docs/guides/repair.md#rows-behind",+ "reasons": [+ "no_checkpoint"+ ],+ "sources": [+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "default",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "notes",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ }+ ],+ "timeout_ms": "<volatile>",+ "unproven": 0+ },+ "elapsed_ms": "<volatile>",+ "message": "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).",+ "name": "sync_rows_behind_checkpoint",+ "readiness_state": "not_applicable",+ "severity": "info",+ "status": "ok"+ },{"category": "meta","details": {diff --git a/test/fixtures/goldens/doctor/hot-checks-pglite-json.json b/test/fixtures/goldens/doctor/hot-checks-pglite-json.jsonindex aab53fdfa5..779d49aa3a 100644--- a/test/fixtures/goldens/doctor/hot-checks-pglite-json.json+++ b/test/fixtures/goldens/doctor/hot-checks-pglite-json.json@@ -3754,6 +3754,62 @@"name": "sync_overwritten_db_edits","status": "ok"},+ {+ "category": "brain",+ "details": {+ "count": 0,+ "docs": "docs/guides/repair.md#rows-behind",+ "sources": [+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "default",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": "1c068d3facec1879b1763dd6f98d3849133473da",+ "complete": true,+ "counts": {+ "current": 18,+ "database_moved": 1+ },+ "pages": 19,+ "samples": [],+ "source_id": "notes",+ "status": "known",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "plain",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ }+ ],+ "timeout_ms": "<volatile>",+ "unproven": 0+ },+ "elapsed_ms": "<volatile>",+ "message": "Every file-backed page holds its file as of the sync checkpoint (19 page(s) read).",+ "name": "sync_rows_behind_checkpoint",+ "status": "ok"+ },{"category": "meta","details": {@@ -8535,6 +8591,62 @@"name": "sync_overwritten_db_edits","status": "ok"},+ {+ "category": "brain",+ "details": {+ "count": 0,+ "docs": "docs/guides/repair.md#rows-behind",+ "sources": [+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "default",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": "1c068d3facec1879b1763dd6f98d3849133473da",+ "complete": true,+ "counts": {+ "current": 18,+ "database_moved": 1+ },+ "pages": 19,+ "samples": [],+ "source_id": "notes",+ "status": "known",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "plain",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ }+ ],+ "timeout_ms": "<volatile>",+ "unproven": 0+ },+ "elapsed_ms": "<volatile>",+ "message": "Every file-backed page holds its file as of the sync checkpoint (19 page(s) read).",+ "name": "sync_rows_behind_checkpoint",+ "status": "ok"+ },{"category": "meta","details": {diff --git a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json b/test/fixtures/goldens/doctor/hot-checks-postgres-json.jsonindex 2ef292748e..5a698fd9fa 100644--- a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json+++ b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json@@ -3757,6 +3757,62 @@"name": "sync_overwritten_db_edits","status": "ok"},+ {+ "category": "brain",+ "details": {+ "count": 0,+ "docs": "docs/guides/repair.md#rows-behind",+ "sources": [+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "default",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": "1c068d3facec1879b1763dd6f98d3849133473da",+ "complete": true,+ "counts": {+ "current": 18,+ "database_moved": 1+ },+ "pages": 19,+ "samples": [],+ "source_id": "notes",+ "status": "known",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "plain",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ }+ ],+ "timeout_ms": "<volatile>",+ "unproven": 0+ },+ "elapsed_ms": "<volatile>",+ "message": "Every file-backed page holds its file as of the sync checkpoint (19 page(s) read).",+ "name": "sync_rows_behind_checkpoint",+ "status": "ok"+ },{"category": "meta","details": {@@ -8539,6 +8595,62 @@"name": "sync_overwritten_db_edits","status": "ok"},+ {+ "category": "brain",+ "details": {+ "count": 0,+ "docs": "docs/guides/repair.md#rows-behind",+ "sources": [+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "default",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": "1c068d3facec1879b1763dd6f98d3849133473da",+ "complete": true,+ "counts": {+ "current": 18,+ "database_moved": 1+ },+ "pages": 19,+ "samples": [],+ "source_id": "notes",+ "status": "known",+ "unproven": 0,+ "unproven_samples": []+ },+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "plain",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ }+ ],+ "timeout_ms": "<volatile>",+ "unproven": 0+ },+ "elapsed_ms": "<volatile>",+ "message": "Every file-backed page holds its file as of the sync checkpoint (19 page(s) read).",+ "name": "sync_rows_behind_checkpoint",+ "status": "ok"+ },{"category": "meta","details": {diff --git a/test/fixtures/goldens/doctor/json-pglite-degraded.json b/test/fixtures/goldens/doctor/json-pglite-degraded.jsonindex 119a317be6..e874a59509 100644--- a/test/fixtures/goldens/doctor/json-pglite-degraded.json+++ b/test/fixtures/goldens/doctor/json-pglite-degraded.json@@ -3233,6 +3233,39 @@"name": "sync_overwritten_db_edits","status": "ok"},+ {+ "category": "brain",+ "details": {+ "count": 0,+ "docs": "docs/guides/repair.md#rows-behind",+ "reasons": [+ "no_checkpoint"+ ],+ "sources": [+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "default",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ }+ ],+ "timeout_ms": "<volatile>",+ "unproven": 0+ },+ "elapsed_ms": "<volatile>",+ "message": "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).",+ "name": "sync_rows_behind_checkpoint",+ "readiness_state": "not_applicable",+ "severity": "info",+ "status": "ok"+ },{"category": "meta","details": {diff --git a/test/fixtures/goldens/doctor/json-pglite-fresh.json b/test/fixtures/goldens/doctor/json-pglite-fresh.jsonindex 1bdc34428d..8d22e4e79a 100644--- a/test/fixtures/goldens/doctor/json-pglite-fresh.json+++ b/test/fixtures/goldens/doctor/json-pglite-fresh.json@@ -3276,6 +3276,39 @@"name": "sync_overwritten_db_edits","status": "ok"},+ {+ "category": "brain",+ "details": {+ "count": 0,+ "docs": "docs/guides/repair.md#rows-behind",+ "reasons": [+ "no_checkpoint"+ ],+ "sources": [+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "default",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ }+ ],+ "timeout_ms": "<volatile>",+ "unproven": 0+ },+ "elapsed_ms": "<volatile>",+ "message": "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).",+ "name": "sync_rows_behind_checkpoint",+ "readiness_state": "not_applicable",+ "severity": "info",+ "status": "ok"+ },{"category": "meta","details": {diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.jsonindex 107359436b..2f4a9851e0 100644--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json@@ -3279,6 +3279,39 @@"name": "sync_overwritten_db_edits","status": "ok"},+ {+ "category": "brain",+ "details": {+ "count": 0,+ "docs": "docs/guides/repair.md#rows-behind",+ "reasons": [+ "no_checkpoint"+ ],+ "sources": [+ {+ "behind": 0,+ "checkpoint": null,+ "complete": true,+ "counts": {},+ "pages": 0,+ "reason": "no_checkpoint",+ "samples": [],+ "source_id": "default",+ "status": "not_applicable",+ "unproven": 0,+ "unproven_samples": []+ }+ ],+ "timeout_ms": "<volatile>",+ "unproven": 0+ },+ "elapsed_ms": "<volatile>",+ "message": "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).",+ "name": "sync_rows_behind_checkpoint",+ "readiness_state": "not_applicable",+ "severity": "info",+ "status": "ok"+ },{"category": "meta","details": {diff --git a/test/fixtures/goldens/doctor/registry-build-checks.json b/test/fixtures/goldens/doctor/registry-build-checks.jsonindex 8a88f77037..6cb9022e48 100644--- a/test/fixtures/goldens/doctor/registry-build-checks.json+++ b/test/fixtures/goldens/doctor/registry-build-checks.json@@ -993,6 +993,10 @@"category": "brain","name": "sync_overwritten_db_edits"},+ {+ "category": "brain",+ "name": "sync_rows_behind_checkpoint"+ },{"category": "meta","name": "sync_config_keys"diff --git a/test/repair-explicit-only.test.ts b/test/repair-explicit-only.test.tsindex eb3f353068..8462f162d8 100644--- a/test/repair-explicit-only.test.ts+++ b/test/repair-explicit-only.test.ts@@ -24,7 +24,7 @@ import { REPAIR_HELP, parseRepairArgs, runRepairCommand } from '../src/commands/import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';import { withEnv } from './helpers/with-env.ts';-const EXPLICIT: RepairKind[] = ['accepted-takes', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'extractor-facts', 'conversation-labels', 'captured-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'timeline-comments', 'timeline-order', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'uncommitted-deletions', 'generations', 'fact-claim-dates', 'provenance', 'secret-spans'];+const EXPLICIT: RepairKind[] = ['accepted-takes', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'extractor-facts', 'conversation-labels', 'captured-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'timeline-comments', 'timeline-order', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'uncommitted-deletions', 'generations', 'fact-claim-dates', 'provenance', 'secret-spans', 'rows-behind'];// GBRA-161: the generations preview carries its ledger kind and the restore window, so the printed command runs as is.const PREVIEW = (kind: RepairKind): string => kind === 'generations' ? 'gbrain repair generations --kind atom --since 30d' : `gbrain repair ${kind}`;let engine: PGLiteEngine;diff --git a/test/rows-behind-checkpoint-8071.test.ts b/test/rows-behind-checkpoint-8071.test.tsnew file mode 100644index 0000000000..b6acef524d--- /dev/null+++ b/test/rows-behind-checkpoint-8071.test.ts@@ -0,0 +1,248 @@+/**+ * #8071 (detection and repair half): a managed source whose checkpoint (`sources.last_commit`) moved past a commit while+ * the rows of the files that commit changed kept their old text, with no hold.+ *+ * The bug state is seeded the way a sync that skipped the import leaves it: the file is rewritten and committed, the+ * checkpoint is moved to that commit outside the owner's write guards, and the page's import record names the+ * checkpoint's blob: as `disk_blob_oid` next to the old `blob_oid` (the record a publication that re-read the moved+ * working file leaves, the root cause), or as both. An honest record that still names only the old blob is healed by the+ * next sync on its own; a record naming the new blob makes every later sync report up_to_date. The row keeps its old text.+ *+ * Protects:+ * - doctor `sync_rows_behind_checkpoint` compares each row with the file at the checkpoint commit (not the record, not+ * the working tree) and warns with the count and the preview command; a plain sync does not heal the row;+ * - `gbrain repair rows-behind` previews the rows (writes nothing), applies exactly the previewed set through the managed+ * import of the checkpoint's bytes, and the check is clean afterwards;+ * - a database edit made since the last import, a held path and a path changed after the checkpoint are not behind; a+ * row with no import record is listed apart and joins the set only with --include-ambiguous;+ * - a checkpoint file the import refuses is held with the refusal's code instead of imported;+ * - repo-less: a brain with no checkout reports not_applicable (ok) and the preview lists nothing.+ *+ * PGLite always; Postgres too when DATABASE_URL is set (test/e2e wrapper).+ */+import { describe, expect, test } from 'bun:test';+import { execFileSync } from 'node:child_process';+import { randomUUID } from 'node:crypto';+import { mkdirSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';+import type { BrainEngine } from '../src/core/engine.ts';+import type { OperationContext } from '../src/core/ops/contract.ts';+import { performManagedSync } from '../src/core/persistence/sync-run.ts';+import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';+import { readGitHold, SYNC_IMPORT_PROVENANCE_OP, writeGitHold } from '../src/core/persistence/sync-holds.ts';+import { resolveRepairScope, type RepairKind } from '../src/core/repair/core.ts';+import { EXPLICIT_REPAIR_REGISTRY, repairRunner } from '../src/core/repair/registry.ts';+import { scanRowsBehind } from '../src/core/persistence/rows-behind.ts';+import { rowsBehindEntry } from '../src/commands/doctor/checks/rows-behind.ts';+import { categorizeCheck } from '../src/core/doctor-categories.ts';+import { RECOVERY_VERSION } from '../src/core/markdown.ts';+import { SYNC_READ_BOUND } from '../src/core/persistence/sync-blobs.ts';+import { managedBrain } from './helpers/managed-brain.ts';+import { isolatedSharedSkillsEngine } from './helpers/shared-skills-engine.ts';+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';+import { waitFor } from './helpers/wait-for.ts';+import { withEnv } from './helpers/with-env.ts';++const KIND = 'rows-behind' as RepairKind;+const CHECK = 'sync_rows_behind_checkpoint';+const logger = { info() {}, warn() {}, error() {} };+const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();+const commit = (root: string, message: string) => { git(root, 'add', '-A'); git(root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', message); };+const note = (slug: string, body: string) => `---\ntype: concept\ntitle: ${slug}\n---\n\n${body}\n`;+const OPTS = { sourceId: 'default', noPull: true, noEmbed: true, noExtract: true };+const SLUGS = ['notes/a', 'notes/b', 'notes/c', 'notes/d', 'notes/e'];+const setup = ({ root }: { root: string }) => {+ mkdirSync(join(root, 'notes'), { recursive: true }); git(root, 'init', '-q');+ for (const slug of SLUGS) writeFileSync(join(root, `${slug}.md`), note(slug, `The committed body of ${slug}.`));+ commit(root, 'notes');+};++const incarnationOf = async (engine: BrainEngine) => (await engine.executeRaw<{ incarnation: string }>("SELECT incarnation::text FROM sources WHERE id='default'"))[0]!.incarnation;+const pageOf = async (engine: BrainEngine, slug: string) => (await engine.executeRaw<{ id: number; revision: string; body: string }>(+ "SELECT id, knowledge_revision::text AS revision, compiled_truth AS body FROM pages WHERE source_id='default' AND slug=$1", [slug]))[0]!;+const recordOf = async (engine: BrainEngine, slug: string) => (await engine.executeRaw<{ record: Record<string, unknown> }>('SELECT completed_keys->0 AS record FROM op_checkpoints WHERE op=$1 AND fingerprint=$2',+ [SYNC_IMPORT_PROVENANCE_OP, `default:${await incarnationOf(engine)}:${(await pageOf(engine, slug)).id}`]))[0]?.record ?? null;+const doctor = async (engine: BrainEngine) => (await rowsBehindEntry.run({ engine, tier: 'standard' } as never) as Array<Record<string, any>>)[0]!;+const repair = async (engine: BrainEngine, opts: { apply?: boolean; expect?: string; includeAmbiguous?: boolean } = {}) => (await repairRunner(engine, { apply: opts.apply === true, logger }))+ .run(KIND, await resolveRepairScope(engine, 'default'), { explicit: true, sourceFlag: 'default', expect: opts.expect, includeAmbiguous: opts.includeAmbiguous });+const listing = (plan: { listing?: Array<{ item: string; class: string }> }) => (plan.listing ?? []).map(entry => [entry.item, entry.class]).sort();++/** Writes outside the owner's write guards, as only its publications may (the checkpoint and the import record). */+async function unguarded(engine: BrainEngine, write: () => Promise<void>): Promise<void> {+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');+ try { await write(); } finally { await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1'); }+}++/**+ * Commits new contents for each slug's file, then moves the checkpoint to that commit without importing it. `record`:+ * `checkpoint` rewrites the page's import record to name the new blob as both blobs; `disk` names the old blob as+ * `blob_oid` and the new one as `disk_blob_oid` (the record a publication that re-read the moved working file leaves,+ * #8071 root cause); `none` deletes it (a page last imported before records existed).+ */+async function seedBehind(engine: BrainEngine, root: string, files: Record<string, { content: string; record: 'checkpoint' | 'disk' | 'none' }>): Promise<string> {+ for (const [slug, file] of Object.entries(files)) writeFileSync(join(root, `${slug}.md`), file.content);+ commit(root, 'rewrite');+ const head = git(root, 'rev-parse', 'HEAD');+ const incarnation = await incarnationOf(engine);+ await unguarded(engine, async () => {+ await engine.executeRaw("UPDATE sources SET last_commit=$1 WHERE id='default'", [head]);+ for (const [slug, file] of Object.entries(files)) {+ const fingerprint = `default:${incarnation}:${(await pageOf(engine, slug)).id}`;+ if (file.record === 'none') { await engine.executeRaw('DELETE FROM op_checkpoints WHERE op=$1 AND fingerprint=$2', [SYNC_IMPORT_PROVENANCE_OP, fingerprint]); continue; }+ const blob = git(root, 'rev-parse', `HEAD:${slug}.md`);+ const imported = file.record === 'disk' ? git(root, 'rev-parse', `HEAD~1:${slug}.md`) : blob;+ await engine.executeRaw(`UPDATE op_checkpoints SET completed_keys = jsonb_set(completed_keys, '{0}', completed_keys->0 || jsonb_build_object('blob_oid', $3::text, 'disk_blob_oid', $4::text))+ WHERE op=$1 AND fingerprint=$2`, [SYNC_IMPORT_PROVENANCE_OP, fingerprint, imported, blob]);+ }+ });+ return head;+}++async function putDatabaseOnly(engine: BrainEngine, ctx: OperationContext, slug: string, body: string): Promise<void> {+ await engine.setConfig('sync.write_through', 'false');+ try {+ const requestId = randomUUID();+ await submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: requestId, expected_revision: (await pageOf(engine, slug)).revision, content: note(slug, body) } });+ await waitFor(async () => (await engine.executeRaw<{ state: string }>('SELECT state FROM persistence_requests WHERE request_id=$1::uuid', [requestId]))[0]?.state === 'committed', { timeoutMs: 30_000 });+ } finally { await engine.setConfig('sync.write_through', 'true'); }+}++for (const backend of testBackends()) describe(`[${backend}] #8071: rows behind the sync checkpoint`, () => {+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;++ test('a row the checkpoint moved past is reported, previewed without writing, re-imported, and the check is clean', () => managedBrain(async ({ engine, root }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ const before = await pageOf(engine, 'notes/a');+ const oldBlob = git(root, 'rev-parse', 'HEAD:notes/a.md');+ const head = await seedBehind(engine, root, { 'notes/a': { content: note('notes/a', 'The redacted body of notes/a.'), record: 'disk' } });+ const newBlob = git(root, 'rev-parse', 'HEAD:notes/a.md');+ expect(await recordOf(engine, 'notes/a')).toMatchObject({ blob_oid: oldBlob, disk_blob_oid: newBlob });++ // Nothing heals it: the next sync trusts the record and reports the source caught up.+ expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date');+ expect((await pageOf(engine, 'notes/a')).body).toContain('The committed body of notes/a.');++ const scan = await scanRowsBehind(engine, 'default');+ expect(scan).toMatchObject({ status: 'known', checkpoint: head, complete: true });+ expect(scan.behind.map(row => [row.slug, row.path])).toEqual([['notes/a', 'notes/a.md']]);++ const warned = await doctor(engine);+ expect(categorizeCheck(CHECK)).toBe('brain');+ expect(warned).toMatchObject({ name: CHECK, status: 'warn', details: { count: 1, sources: [{ source_id: 'default', checkpoint: head, behind: 1, samples: ['notes/a'] }] } });+ expect(warned.message).toContain('gbrain repair rows-behind --source default');+ expect(warned.fix.argv).toEqual(['gbrain', 'repair', 'rows-behind', '--source', 'default', '--json']);++ expect(EXPLICIT_REPAIR_REGISTRY.map(spec => spec.kind)).toContain(KIND);+ const requestsBefore = (await engine.executeRaw('SELECT 1 FROM persistence_requests')).length;+ const preview = await repair(engine);+ expect(listing(preview)).toEqual([['default:notes/a', 'reimport']]);+ expect(preview.affected).toBe(1);+ expect(await pageOf(engine, 'notes/a')).toEqual(before);+ expect((await engine.executeRaw('SELECT 1 FROM persistence_requests')).length).toBe(requestsBefore);++ const applied = await repair(engine, { apply: true, expect: preview.preview_hash });+ expect(applied.outcome_items?.map(item => [item.item, item.outcome])).toEqual([['default:notes/a', 'reimported']]);+ expect((await pageOf(engine, 'notes/a')).body).toContain('The redacted body of notes/a.');+ // The re-import rewrites the stale record: it names the bytes the row now holds and no longer the old blob.+ const rewritten = await recordOf(engine, 'notes/a');+ expect(rewritten).toMatchObject({ disk_blob_oid: newBlob });+ expect([rewritten?.blob_oid, rewritten?.disk_blob_oid]).not.toContain(oldBlob);+ expect(await doctor(engine)).toMatchObject({ name: CHECK, status: 'ok', details: { count: 0 } });+ expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date');+ expect((await pageOf(engine, 'notes/a')).body).toContain('The redacted body of notes/a.');+ // The rewritten record no longer matches a later commit's blob, so the next sync imports it.+ writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'A later body of notes/a.'));+ commit(root, 'later');+ await performManagedSync(engine, OPTS);+ expect((await pageOf(engine, 'notes/a')).body).toContain('A later body of notes/a.');+ expect(await doctor(engine)).toMatchObject({ name: CHECK, status: 'ok', details: { count: 0 } });+ }, { databaseUrl, setup }), 240_000);++ test('a database edit since the import, a held path and a later commit are not behind; a row without a record needs --include-ambiguous', () => managedBrain(async ({ engine, ctx, root }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ await putDatabaseOnly(engine, ctx, 'notes/b', 'A database-only edit of notes/b.');+ await seedBehind(engine, root, {+ 'notes/c': { content: note('notes/c', 'The redacted body of notes/c.'), record: 'checkpoint' },+ 'notes/d': { content: note('notes/d', 'The redacted body of notes/d.'), record: 'none' },+ 'notes/e': { content: note('notes/e', 'The redacted body of notes/e.'), record: 'checkpoint' },+ });+ const c = await pageOf(engine, 'notes/c');+ const incarnation = await incarnationOf(engine);+ await engine.transaction(tx => writeGitHold(tx, { source_id: 'default', incarnation, path: 'notes/c.md', source_path: 'notes/c.md', slug: 'notes/c',+ page_id: Number(c.id), code: 'file_drift', message: 'held for the test', upstream_version: null, observed_at: new Date().toISOString(), run_id: null, mode: 'managed', meta: { recovery_version: RECOVERY_VERSION } }));+ // notes/e changes again after the checkpoint: the next sync imports it, so it is not reported behind.+ writeFileSync(join(root, 'notes/e.md'), note('notes/e', 'A later body of notes/e.'));+ commit(root, 'later');++ const scan = await scanRowsBehind(engine, 'default');+ expect(scan.behind).toEqual([]);+ expect(scan.unproven.map(row => row.slug)).toEqual(['notes/d']);+ expect(scan.counts).toMatchObject({ held: 1, database_moved: 1, changed_after_checkpoint: 1 });+ expect(await doctor(engine)).toMatchObject({ status: 'ok', details: { count: 0, unproven: 1 } });++ const preview = await repair(engine);+ expect(listing(preview)).toEqual([['default:notes/d', 'excluded:unproven']]);+ expect(preview.affected).toBe(0);+ const widened = await repair(engine, { includeAmbiguous: true });+ expect(listing(widened)).toEqual([['default:notes/d', 'reimport']]);+ const applied = await repair(engine, { apply: true, expect: widened.preview_hash, includeAmbiguous: true });+ expect(applied.outcome_items?.map(item => [item.item, item.outcome])).toEqual([['default:notes/d', 'reimported']]);+ expect((await pageOf(engine, 'notes/d')).body).toContain('The redacted body of notes/d.');+ expect((await pageOf(engine, 'notes/b')).body).toContain('A database-only edit of notes/b.');+ expect((await pageOf(engine, 'notes/c')).body).toContain('The committed body of notes/c.');+ }, { databaseUrl, setup }), 240_000);++ test('a checkpoint file the import refuses is held with the refusal code instead of imported', () => managedBrain(async ({ engine, root }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ await seedBehind(engine, root, { 'notes/a': { content: '---\ntype: concept\ntitle: [unclosed\n---\n\nThe redacted body of notes/a.\n', record: 'checkpoint' } });+ expect((await doctor(engine))).toMatchObject({ status: 'warn', details: { count: 1 } });+ const preview = await repair(engine);+ expect(listing(preview)).toEqual([['default:notes/a', 'hold:invalid_frontmatter']]);+ const applied = await repair(engine, { apply: true, expect: preview.preview_hash });+ expect(applied.outcome_items?.map(item => [item.item, item.outcome])).toEqual([['default:notes/a', 'held']]);+ expect((await readGitHold(engine, 'default', await incarnationOf(engine), 'notes/a.md'))?.code).toBe('invalid_frontmatter');+ expect((await pageOf(engine, 'notes/a')).body).toContain('The committed body of notes/a.');+ expect(await doctor(engine)).toMatchObject({ status: 'ok', details: { count: 0 } });+ }, { databaseUrl, setup }), 240_000);++ test('a page stored in segments is compared by hash and re-imported; a file over the read bound is held file_too_large without being read', () => managedBrain(async ({ engine, root }) => {+ const big = (marker: string) => note('notes/big', Array.from({ length: 30_000 }, (_, i) => `${marker} line ${i} of a large page body.`).join('\n'));+ writeFileSync(join(root, 'notes/big.md'), big('Committed')); commit(root, 'big');+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ expect((await engine.executeRaw<{ storage: string }>("SELECT body_storage AS storage FROM pages WHERE source_id='default' AND slug='notes/big'"))[0]!.storage).toBe('segmented');+ await seedBehind(engine, root, {+ 'notes/big': { content: big('Redacted'), record: 'checkpoint' },+ 'notes/a': { content: note('notes/a', 'x'.repeat(SYNC_READ_BOUND + 1)), record: 'checkpoint' },+ });+ const scan = await scanRowsBehind(engine, 'default');+ expect(scan.behind.map(row => [row.slug, row.refusal?.code ?? null]).sort()).toEqual([['notes/a', 'file_too_large'], ['notes/big', null]]);+ const preview = await repair(engine);+ expect(listing(preview)).toEqual([['default:notes/a', 'hold:file_too_large'], ['default:notes/big', 'reimport']]);+ const applied = await repair(engine, { apply: true, expect: preview.preview_hash });+ expect(applied.outcome_items?.map(item => [item.item, item.outcome]).sort()).toEqual([['default:notes/a', 'held'], ['default:notes/big', 'reimported']]);+ expect(await readGitHold(engine, 'default', await incarnationOf(engine), 'notes/a.md')).toMatchObject({ code: 'file_too_large', upstream_version: null });+ const live = (marker: string) => engine.executeRaw<{ n: number }>(+ "SELECT count(*)::int AS n FROM page_body_manifest m JOIN pages p ON p.id = m.page_id JOIN page_segment_texts t ON t.source_id = m.source_id AND t.sha256 = m.sha256 WHERE p.source_id = 'default' AND p.slug = 'notes/big' AND m.gen_to IS NULL AND m.staging_id IS NULL AND position(convert_to($1, 'UTF8') in t.body) > 0",+ [marker],+ ).then(rows => rows[0]!.n);+ expect(await live('Committed line 0 of')).toBe(0);+ expect(await live('Redacted line 0 of')).toBeGreaterThan(0);+ expect((await scanRowsBehind(engine, 'default')).behind).toEqual([]);+ expect(await doctor(engine)).toMatchObject({ status: 'ok', details: { count: 0 } });+ }, { databaseUrl, setup }), 240_000);++ test('repo-less: a brain with no checkout is not applicable and the preview lists nothing', async () => {+ const home = (await import('node:fs')).mkdtempSync(join((await import('node:os')).tmpdir(), 'gbrain-rows-behind-'));+ await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {+ const { engine, close } = await isolatedSharedSkillsEngine(databaseUrl);+ try {+ await engine.putPage('notes/a', { type: 'concept', title: 'notes/a', compiled_truth: 'A page only the database holds.' }, { sourceId: 'default' });+ expect(await scanRowsBehind(engine, 'default')).toMatchObject({ status: 'not_applicable' });+ expect(await doctor(engine)).toMatchObject({ name: CHECK, status: 'ok', readiness_state: 'not_applicable' });+ const preview = await repair(engine);+ expect(preview.affected).toBe(0);+ expect(preview.listing ?? []).toEqual([]);+ } finally { await close(); }+ });+ }, 120_000);+});