Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs(#6961): key-files entry for import-chunk-reuse covers requireRecordedInput

garrytan7a8dcd6c5cde
diff --git a/docs/architecture/key-files/files-and-sync-2.md b/docs/architecture/key-files/files-and-sync-2.md
index 3bf572f4ce..2f9415cd8f 100644
--- a/docs/architecture/key-files/files-and-sync-2.md
+++ b/docs/architecture/key-files/files-and-sync-2.md
@@ -9,7 +9,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/sync-git.ts:resolveSlugByPathOrSourcePath` — Resolves a slug by `pages.source_path` first (returns the stored slug for frontmatter-fallback pages whose path doesn't derive a slug), then falls back to `resolveSlugForPath(path)`. Three call sites: the un-syncable cleanup (which passes `opts.sourceId`), and the bare no-`sourceId` delete and rename-source paths; when `sourceId` IS set the delete and rename loops batch through `engine.resolveSlugsByPaths` instead. The `source_path` lookup is scoped to the DEFAULT source on the bare path, matching every write that path performs (`updateSlug`, `deletePage`, the rename bookkeeping repair are all default-scoped) — an unscoped lookup could return a row from another source sharing the `source_path`, and the rename loop consumes this value directly as its cheap-move source slug. Without the helper, emoji-only / Thai / Arabic filenames whose slug came from frontmatter would orphan on delete/rename (that path would compute the wrong path-derived slug). Best-effort query — pre-migration brains fall through to the legacy path.
-- `src/core/import-chunk-reuse.ts` — `reuseStoredChunkVectors`: A13 vector reuse for one markdown page import, shared by the inline import (before its transaction, to decide which chunks reach the provider) and every import's transaction (under the page lock, `importFromContent` in `import-file.ts`). It copies each stored vector the reuse gate admits onto its matching new chunk and maps the chunk to the stored row id when that row already holds exactly what the chunk would insert, so the import keeps it in place and deletes and writes only the rest; with `keepUnembedded` (the in-transaction pass) an identical never-embedded row stays under a new chunk that carries no vector either. Inline, `--no-embed` and prepared imports all keep rows; a prepared import reuses nothing from a page stored under per-chunk synopsis. Pinned by `test/import-inline-chunk-keep.test.ts` (both engines) and `test/persistence-edit-embedding-reuse.test.ts`. `reuseSegmentChunkVectors` (Wave B) reads only the rows of the retired occurrences with their vectors and applies the same gate and `chunk_source\0chunk_text` plan, so an unchanged chunk inside a rewritten tail keeps its vector.
+- `src/core/import-chunk-reuse.ts` — `reuseStoredChunkVectors`: A13 vector reuse for one markdown page import, shared by the inline import (before its transaction, to decide which chunks reach the provider) and every import's transaction (under the page lock, `importFromContent` in `import-file.ts`). It copies each stored vector the reuse gate admits onto its matching new chunk and maps the chunk to the stored row id when that row already holds exactly what the chunk would insert, so the import keeps it in place and deletes and writes only the rest; with `keepUnembedded` (the in-transaction pass) an identical never-embedded row stays under a new chunk that carries no vector either. Inline, `--no-embed` and prepared imports all keep rows; a prepared import reuses nothing from a page stored under per-chunk synopsis. With `requireRecordedInput` (set by `importFromContent` when the old or new body holds a protected fence, #6961) only a stored vector with a recorded embedding input is admitted, never the legacy raw-text match. Pinned by `test/fenced-embed-reuse-6961.test.ts`, `test/import-inline-chunk-keep.test.ts` (both engines) and `test/persistence-edit-embedding-reuse.test.ts`. `reuseSegmentChunkVectors` (Wave B) reads only the rows of the retired occurrences with their vectors and applies the same gate and `chunk_source\0chunk_text` plan, so an unchanged chunk inside a rewritten tail keeps its vector.
- `src/core/sync-policy.ts` — `isSyncDisabledConfig(config)`: the one predicate for `config.syncEnabled === false` ("excluded from AUTOMATIC/bulk sync"), unwrapping PGLite's JSON-string config scalar via `parseSourceConfig`. Read by the `sync --all` fan-out filter (`src/commands/sync.ts`), autopilot's per-source freshness dispatcher (`src/commands/autopilot.ts`, skip before `queue.add('sync')`) and the full-cycle fan-out (`src/commands/autopilot-fanout.ts`, which drops the `sync` phase + pull from a disabled source's `autopilot-cycle` payload but keeps lint/backlinks/extract and the freshness stamp) and the `sync_enabled` column of `buildSyncStatusReport` (`src/core/sync-status-report.ts`, whose callers pass RAW `SELECT config` rows — a JSON string on PGLite — so a raw cast there contradicted the fan-out filter). Doctor's `checkSyncFreshness` also applies this predicate, including the legacy query fallback: disabled sources contribute neither warnings nor freshness counts; only boolean `false` disables, not the string `'false'`. `checkCycleFreshness` still monitors their maintenance cycles. Pinned by `test/doctor-sync-policy.test.ts` and `test/doctor-cycle-freshness.test.ts`. Deliberately does NOT gate `performSync()`: an explicit `gbrain sync --source <id>` still runs; `sync-cost-gate.ts` keeps its own inline check because it also feeds the explicit single-source cost preview. Pinned by `test/sync-policy.test.ts`, the `#4399` cases in `test/autopilot-fanout-wiring.test.ts` (source-text) and `test/autopilot-fanout.test.ts` (stubbed dispatch).
- `src/core/sync-applicability.ts` — agent-first operator wave E4. `syncContentDirectory(engine, {sourceId, repoPath})` resolves the sync root exactly as `performSync` does and returns it when it is a gbrain-owned content directory (under `<GBRAIN_HOME>/.gbrain/content/`, or an owned `--content-root` recorded in the shared-skills setup receipt) with no `.git` at the root; null otherwise (fail-open). `assertSyncAnchorAbsolute` refuses `sync_anchor_relative` (`syncAnchorRelativeError`: exit 3, an `ask_user` fix naming `gbrain sources set-path <id> <absolute-directory>`, or `gbrain config set sync.repo_path` with no source) when the stored anchor (`sources.local_path`, else `sync.repo_path`) is relative and no absolute or different `repoPath` was passed; single-source and `--all` CLI syncs refuse it before the cost gate walks the directory, and a cycle whose directory matches no source checks `default` and fails its sync phase with that code. A path absolute only on another operating system (a Windows drive path read on Linux or macOS) gets the same code with a `set-path`-only fix, since `--clear` refuses it. `src/core/sync-anchor.ts` never proves ownership from a relative anchor: `isAnchorOwnedSyncPath`, `ownsSourceSyncAnchor` and `sourceCommitAnchorAllowed` treat it as not owned, and for `default` the commit-anchor check skips a relative `sync.repo_path` and judges the row's `local_path`, so an explicit absolute `--repo` never advances the commit anchor of a source whose stored path is relative. `performSync` calls `assertSyncApplicable` first (the anchor check, then the content-directory check), so a content-directory source refuses with `sync_not_applicable` (reason `content_directory`, fix `gbrain import <dir> [--no-embed] --source <id>`, `git init` named only as an ask-the-user option) before the managed path or the legacy #2964 anchor self-heal could `git init` it. `sync --all` skips these sources with one line; the dream cycle's sync phase reports them `skipped` (`details.reason: sync_not_applicable`). The CLI `sync` record renders fix-carrying OperationErrors through `renderCliError` (`src/cli/commands/sync.ts`). Pinned by `test/sync-applicability.test.ts` and `test/sync-relative-anchor-refusal-7630.test.ts`.
- `src/core/sync-upstream.ts` — upstream observation for remote-tracking sources (#5255/#5176). `observeUpstream(root, syncedCommit)` reads the checkout's `@{upstream}` commit, the newer of the `FETCH_HEAD` and upstream-ref reflog mtimes (the last fetch, pull or push by any process) and `rev-list --count` of upstream commits the synced commit lacks; `recordUpstreamObservation` (called by `performSync` in `src/commands/sync/perform.ts` after every non-dry-run legacy or managed sync, best-effort) writes them to `sources.upstream_checked_at` / `upstream_commit` / `upstream_behind`, which `managed_writer_guard` does not protect. `upstreamFreshness` is doctor `sync_freshness`'s separate "upstream checked" verdict (a `remote_url` source with no observation or one at least 24 h old is upstream unknown; any observed upstream lead is behind), DB-only so remote doctor runs it. `managedPullWarning` / `UpstreamRefresh` back the cycle sync phase (`runPhaseSync` in `src/core/cycle.ts`), which runs a managed `pull: true` as no-pull and reports `details.upstream_refresh` (`pulled|failed|skipped_managed|not_requested`) plus a `managed_pull_skipped` warning when the checkout tracks an upstream. A managed brain's fix (the warning and doctor's behind/unknown verdict) is `gbrain sources refresh <source>`; an unmanaged one's is `gbrain sync --source <source>`. Tests: `test/managed-cycle-pull-upstream.test.ts`, the pull row of `test/managed-phase-matrix.test.ts`.