Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Incremental sync rename lane (refactor wave 1, W4 sync): cheap `updateSlug`
* renames with an observed fallback to add + reconcile (#3056), guarded by
* the tracked-file liveness index (#3583) and `<rename:…>` sentinels.
*/
import { existsSync } from 'fs';
import { join } from 'path';
import { softDeleteSyncPages } from '../../core/company-brain/profile.ts';
import { serr } from '../../core/console-prefix.ts';
import { DELETE_BATCH_SIZE } from '../../core/engine-constants.ts';
import { importFile, isImageFilePath as isImageImportPath, importImageFile } from '../../core/import-file.ts';
import { maintenanceTransaction } from '../../core/persistence/attribution.ts';
import type { BrainEngine } from '../../core/engine.ts';
import { movePageIdReferences, moveSlugBindings, recordRenameAlias } from '../../core/page-state/rename-alias.ts';
import { renamePageOntoSlug } from './rename-collision.ts';
import { workingTreeIdentityHead } from '../../core/sync-rename-identity.ts';
import {
resolveSlugsForRemovedPaths,
refusedRemovedPathMessage,
resolveRemovedPathSlug,
isPathSafe,
} from '../../core/sync-git.ts';
import {
DEFAULT_SOURCE_ID,
resolveSlugForPath,
loadSyncFailures,
renameSentinelPath,
sanitizePathForDisplay,
renameReconcileErrorMessage,
} from '../../core/sync.ts';
import type { SyncResult } from '../sync.ts';
import { trackedSlugIndex, activeSlugsBySourcePath } from './rename-reconcile.ts';
import type { TrackedSlugIndex } from './rename-reconcile.ts';
import { clearLegacyHold, holdRefusedImport, holdRenameDestination, noteScreenedImport, recordLegacyHold, type LegacyHolds } from './holds.ts';
import { classifyItemFailure } from '../../core/item-failure.ts';
import { partial, noteTypeWarning, markCompleted } from './sync-run.ts';
import { fileHistory } from './reasons.ts';
import type { SyncPlan, SyncRun, SyncProgress } from './sync-run.ts';
import { noteCommittedProgress } from '../../core/forward-progress.ts';
import { recordFallbackRename } from '../../core/belief/identity.ts';
import { markBeliefCommits } from '../../core/belief/append.ts';
type RenamePlan = Pick<SyncPlan, 'opts' | 'filtered' | 'manifest' | 'lastCommit' | 'pin' | 'gitContextRoot' | 'modePath' | 'syncImportRoot' | 'syncActivePack' | 'holds' | 'reasons'>;
type RenameContext = {
renameOpts: { sourceId: string } | undefined;
slugLiveness: (s: string, from: string) => 'live' | 'stale' | 'unknown';
renameOldSlugs: Map<string, Set<string>>;
fromSlugByPath: Map<string, string>;
renameSentinelAlreadyOpen: (to: string) => boolean;
noEmbed: boolean;
};
/** The rename drain. Returns a partial result when the run aborts mid-drain. */
export async function runRenamesPhase(
run: SyncRun,
plan: RenamePlan,
progress: SyncProgress,
noEmbed: boolean,
): Promise<SyncResult | undefined> {
const { engine, completed } = run;
const { opts, filtered, manifest, gitContextRoot, lastCommit, modePath } = plan;
// Process renames (updateSlug preserves page_id, chunks, embeddings).
// SP-5: both old and new slugs use resolveSlugForPath so a .ts → .ts
// rename (code→code), .md → .md (markdown→markdown), or cross-kind rename
// all resolve to the right slug shape for each side.
//
// v0.41.19.0 (T4): pre-batched slug resolution per Phase 3 of the plan.
// Renames' per-file cost is dominated by importFile() (file IO + chunking
// + embedding), so the per-iteration updateSlug + importFile loop stays;
// only the upfront slug-resolve N+1 gets batched. The try/catch around
// updateSlug for slug-doesn't-exist preserves verbatim.
// v0.42.x (#1794): resume-filter renames on the destination path.
const renamesToDo = filtered.renamed.filter(r => !completed.has(r.to));
if (renamesToDo.length > 0) {
progress.start('sync.renames', renamesToDo.length);
// v0.18.0+ multi-source: scope updateSlug so the rename only touches the
// source-A row, not every same-slug row across sources (which would
// either sweep them all OR violate (source_id, slug) UNIQUE).
const renameOpts = opts.sourceId ? { sourceId: opts.sourceId } : undefined;
// #3583 review: lazily-built (at most once per run) tracked-file slug
// index for the live-row filter in the reconcile below. A throw from the
// index build surfaces inside the reconcile's own try/catch, where it
// records the `<rename:…>` sentinel — fail-closed, never a guessed delete.
// Liveness = tracked in the git index, deliberately NOT "present on
// disk": sync's ground truth is git, and in a sparse/partial checkout a
// tracked file is intentionally absent from the working tree — an
// on-disk check would misclassify its live page as stale and delete it,
// the same failure shape this filter exists to prevent.
// Three-way verdict, not boolean: when the index is incomplete (an
// unreadable fallback-regime file — see trackedSlugIndex), an index miss
// proves nothing, so the row is spared as 'unknown' rather than deleted.
let treeSlugIndex: TrackedSlugIndex | undefined;
const slugLiveness = (s: string, from: string): 'live' | 'stale' | 'unknown' => {
// lastCommit = the commit the brain reflects; its blob is one of the
// consulted content states (see fallbackSlugsForFile). Anchor paths
// are keyed through modePath so they compare against `from` under
// #4342 source-root mode too.
treeSlugIndex ??= trackedSlugIndex(gitContextRoot, lastCommit, modePath);
if (treeSlugIndex.slugs.has(s)) {
// #4597: when the ONLY liveness proof is the anchor blob at THIS
// rename's own from-path, that proof is the pre-rename state of the
// file just re-imported at `to` (the reconcile only runs once the
// destination materialized) — the exact duplicate it exists to
// remove. Sparing it checkpointed the rename as converged, so the
// duplicate never re-entered an incremental diff. Any current-tree
// hit, or anchor proof from a DIFFERENT path (the #3583 data-loss
// shapes), still spares the row.
const onlyAt = treeSlugIndex.anchorOnlyPaths.get(s);
if (!onlyAt || ![...onlyAt].every(p => p === from)) return 'live';
}
return treeSlugIndex.complete ? 'stale' : 'unknown';
};
// #3583 review (GATE6): the old slug of EVERY rename in this diff. A
// row can be CARRIED by a different rename in the same diff whose
// destination derives no slug (ordinary path → exotic path, frontmatter
// absent): no current path, blob, or anchor state names its slug, but
// the rename pair itself proves the content is still tracked. The
// reconcile of rename R therefore spares candidates that are ANOTHER
// rename's old slug; R's OWN old slug stays deletable — that is
// exactly the duplicate the reconcile exists to remove once the
// destination materializes. Built over the RAW manifest — not the
// scope/exclude/resume-filtered list — so a carried row is protected
// even when its own rename was filtered out of processing (an
// --exclude'd or out-of-scope destination still proves the content is
// tracked; registration is purely spare-side).
// Each from-path maps to a SET of slugs, never one: source_path is
// non-unique, so a DB resolve can return an UNRELATED row's slug
// (stale bookkeeping naming the same path) and silently displace the
// path-derived slug the carried-spare depends on — the carried row
// then lost its protection and the GATE6 delete came back. The set
// always holds the path-derived slug (when the path derives one)
// PLUS every active row's slug under that source_path; registration
// is purely spare-side, so over-inclusion only delays a cleanup.
// Spare-side only: a resolve failure merely shrinks the DB half of the
// set, and the path-derived entries still protect the carried row.
let dbSlugsByFrom = new Map<string, string[]>();
try {
dbSlugsByFrom = await activeSlugsBySourcePath(
engine, manifest.renamed.map(r => r.from), opts.sourceId ?? DEFAULT_SOURCE_ID,
opts.signal,
);
} catch { /* see above — both consumers degrade safely */ }
const renameOldSlugs = new Map<string, Set<string>>();
for (const r of manifest.renamed) {
const shapes = new Set<string>();
const derived = resolveSlugForPath(r.from);
if (derived !== '') shapes.add(derived);
for (const s of dbSlugsByFrom.get(r.from) ?? []) shapes.add(s);
renameOldSlugs.set(r.from, shapes);
}
// T4: pre-resolve ALL `from` slugs in batches before iterating. Falls
// back to the guarded per-path resolver when sourceId is unset. For
// large rename commits (rare but possible: prefix sweep, reorganization),
// this drops the slug-resolve round-trips from O(renames) to O(renames/500).
//
// #3942: routed through resolveSlugsForRemovedPaths (same guarded
// resolver the delete lane uses) instead of a raw resolveSlugsByPaths +
// unguarded resolveSlugForPath fallback — a re-slugified fallback can
// name a page whose recorded origin is a DIFFERENT file (e.g. a
// trailing-hyphen collision). A refused from-path gets no entry in
// fromSlugByPath, so the rename below skips the cheap updateSlug and
// falls through to add + reconcile instead of repointing that page.
const fromSlugByPath = new Map<string, string>();
if (opts.sourceId) {
const sid = opts.sourceId;
const fromPaths = renamesToDo.map(r => r.from);
for (let i = 0; i < fromPaths.length; i += DELETE_BATCH_SIZE) {
if (opts.signal?.aborted) {
progress.finish();
return await partial(run, plan, 'timeout');
}
const batch = fromPaths.slice(i, i + DELETE_BATCH_SIZE);
const resolution = await resolveSlugsForRemovedPaths(engine, batch, sid);
for (const r of resolution.refused) serr(refusedRemovedPathMessage(r));
for (const [p, s] of resolution.slugs) fromSlugByPath.set(p, s);
}
}
// Is a `<rename:…>` sentinel for this destination already open from an
// earlier run? Read once per run: the ledger is only rewritten at the
// gate, after this loop.
const openRenameSentinels = new Set(
loadSyncFailures()
.filter(f => f.source_id === (opts.sourceId ?? DEFAULT_SOURCE_ID) && f.state === 'open')
.map(f => f.path),
);
const renameSentinelAlreadyOpen = (to: string): boolean =>
openRenameSentinels.has(renameSentinelPath(to));
const ctx: RenameContext = { renameOpts, slugLiveness, renameOldSlugs, fromSlugByPath, renameSentinelAlreadyOpen, noEmbed };
for (const { from, to, identityHead } of renamesToDo) {
const aborted = await applyRename(run, plan, ctx, progress, from, to, identityHead);
if (aborted) return aborted;
}
progress.finish();
}
return undefined;
}
/** One rename: cheap updateSlug, destination re-import, reconcile, sentinel and checkpoint bookkeeping. */
async function applyRename(
run: SyncRun,
plan: RenamePlan,
ctx: RenameContext,
progress: SyncProgress,
from: string,
to: string,
identityHead?: string,
): Promise<SyncResult | undefined> {
const { engine, failedFiles, succeededPaths, pagesAffected, deletedSlugs } = run;
const { opts, gitContextRoot, syncImportRoot, syncActivePack, holds, reasons } = plan;
const { renameOpts, fromSlugByPath, noEmbed } = ctx;
// v0.41.13.0 (T2 / D-V4-2): per-iteration abort check. Renames call
// importFile() at line 1173-style sites which can be slow on big files;
// refactor commits with 200+ renames must respect --timeout.
if (opts.signal?.aborted) {
progress.finish();
return await partial(run, plan, 'timeout');
}
// T4: the batch-resolved slug for `from` (see fromSlugByPath above). A
// refused/unresolved from-path has no entry, so this is undefined
// rather than falling back to an unverified derived slug.
//
// #3942: the no-sourceId lane is scoped to DEFAULT_SOURCE_ID (not
// left unscoped) — updateSlug below only ever touches the
// default-scoped row (renameOpts is undefined here, and updateSlug
// defaults its own sourceId to 'default'), so the read that decides
// what to rename must agree with that scope. An unscoped resolve
// could otherwise return a DIFFERENT source's row sharing this
// source_path, licensing the wrong (or a foreign) slug for a
// default-scoped rename.
const oldSlug = opts.sourceId
? fromSlugByPath.get(from)
: await resolveRemovedPathSlug(engine, from, DEFAULT_SOURCE_ID, serr);
// The new path doesn't yet have a row, so resolve from path only.
const newSlug = resolveSlugForPath(to);
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- `to` is a git-diff rename path; the joined path is read only after the same isPathSafe(filePath, gitContextRoot) realpath containment check the import below applies
const filePath = join(syncImportRoot, to);
// #6729: a dirty-tree rename keeps its page only for the bytes its verdict read; a file edited since then is left
// for the next sync to re-check, and nothing moves.
if (identityHead !== undefined && workingTreeIdentityHead(syncImportRoot, to) !== identityHead) {
failedFiles.push({ path: to, error: `${to} changed after sync confirmed it keeps the page of ${from}; nothing moved. Run gbrain sync again to re-check it.` });
serr(` [sync] rename ${sanitizePathForDisplay(from)} -> ${sanitizePathForDisplay(to)}: the file changed after its identity was confirmed; nothing moved, the next sync re-checks it.`);
progress.tick(1, newSlug);
return undefined;
}
// #5988 (E13): a destination the import would refuse is screened before the
// old page's slug or origin moves; it is held and the old page stays whole.
if (isPathSafe(filePath, gitContextRoot) && await holdRenameDestination(engine, holds, { from, to, filePath, oldSlug, activePack: syncActivePack })) {
await markCompleted(run, to);
progress.tick(1, newSlug);
return undefined;
}
// #3056: the cheap rename is OBSERVED, not assumed. A zero-row UPDATE
// doesn't throw, and a thrown collision used to be swallowed by an
// empty catch — both fell through to importFile, which created/updated
// the row at the new path while the old row stayed behind live.
// #5431 (W14 P1.8): the unique violation is classified instead. A
// tombstone destination is merged (the tombstone re-keyed purge-style,
// the page moves with its id), a live destination falls through to the
// reconcile below, and any other error fails the file without a
// checkpoint. `source_path` is repaired inside the rename transaction
// (#3583 gate13: the cheap rename never rewrote it, the unchanged-content
// reimport writes nothing, and the full-sync purge read the stale path as
// a removed file and deleted the LIVE renamed page). The scope is the one
// updateSlug uses: no sourceId means the DEFAULT source, never every
// source (gate 14).
let renameApplied = false;
if (oldSlug !== undefined) {
try {
renameApplied = await renamePageOntoSlug(engine, { sourceId: renameOpts?.sourceId ?? DEFAULT_SOURCE_ID, oldSlug, newSlug, to }) === 'renamed';
} catch (e: unknown) {
const msg = e instanceof Error ? e.message : String(e);
failedFiles.push({ path: to, error: `rename ${from} -> ${to} failed before any row moved: ${msg}` });
serr(` [sync] rename ${sanitizePathForDisplay(from)} -> ${sanitizePathForDisplay(to)} failed: ${msg}`);
progress.tick(1, newSlug);
return undefined;
}
}
// Reimport at new path (picks up content changes). Wrapped to match the
// deletes/adds loops: a malformed renamed file is recorded to failedFiles
// and skipped, NOT thrown uncaught. importFile still throws on content
// sanity-block, duplicate-slug, and missing-link endpoints; an uncaught
// throw here crashes the whole sync mid-run and freezes the checkpoint,
// defeating --skip-failed. A `skipped` result carrying an error is also
// captured so the failure is recorded rather than silently dropped.
// Paths from git diff are relative to gitContextRoot — except under
// #4342's 'source-root' mode, where the filtered manifest (this loop's
// source) was remapped scope-relative; the join base moves with it.
// NAV-1 TOCTOU: refuse a destination that realpath-resolves outside the
// repo (committed symlink pointing out).
let importResult: Awaited<ReturnType<typeof importFile>> | undefined;
// #2683 residual: a failed destination import (status 'error' OR a
// throw) must not checkpoint `to` — the resume filter would skip the
// rename forever, leaving the target permanently unimported.
let importErrored = false;
if (existsSync(filePath) && isPathSafe(filePath, gitContextRoot)) {
try {
// #2683: dispatch renamed images to importImageFile (binary bytes
// through importFile threw UTF-8 errors). Same gate as import.ts.
const result = isImageImportPath(to) && process.env.GBRAIN_EMBEDDING_MULTIMODAL === 'true'
? await importImageFile(engine, filePath, to, { noEmbed, sourceId: opts.sourceId })
: await importFile(engine, filePath, to, { noEmbed, sourceId: opts.sourceId, activePack: syncActivePack, history: fileHistory(reasons, filePath) });
importResult = result;
noteTypeWarning(run, result.type_warning);
noteScreenedImport(holds, to, result);
if (await holdRefusedImport(engine, holds, to, filePath, result)) importResult = undefined;
else if (result.status === 'imported') run.chunksCreated += result.chunks;
else if (result.status === 'skipped' && result.skip_reason === 'malformed_path') {
// Informational skip — a bracket/control-char filename can never
// import; counting it as a failure would gate the bookmark forever.
serr(` Skipped (malformed filename): ${sanitizePathForDisplay(to)}`);
} else if (result.status === 'skipped' && (result as { error?: string }).error) {
// An errored skip (frontmatter slug-authority rejection, invalid
// YAML, symlink refusal, oversize file, ...) means the
// destination never materialized — same as status 'error' below,
// this must gate the success sentinel + markCompleted(to), or a
// resumed sync would treat the rename as permanently done.
importErrored = true;
failedFiles.push({ path: to, error: String((result as { error?: string }).error) });
} else if (result.status === 'error') {
// importImageFile (and importFile's frontmatter gate) report
// failures as status 'error', which no branch above recorded —
// the rename silently succeeded with a dead target.
importErrored = true;
failedFiles.push({ path: to, error: String((result as { error?: string }).error ?? 'import error') });
}
} catch (e: unknown) {
const msg = e instanceof Error ? e.message : String(e);
if (!await holdRefusedImport(engine, holds, to, filePath, { status: 'error', error: msg })) {
importErrored = true;
failedFiles.push({ path: to, error: msg });
}
}
if (!importErrored && importResult) await clearLegacyHold(engine, holds, to);
}
const reconcileFailed = await reconcileRenameFallback(run, plan, ctx, from, to, newSlug, renameApplied, importResult);
// Converged (cheap rename, clean reconcile, or nothing to reconcile):
// clear any `<rename:…>` sentinel a previous failing run recorded.
// A run that spared an UNPROVABLE row reaches here too — that is the
// accepted cost of never deleting without proof — EXCEPT when this
// rename already had a sentinel open, which the reconcile turns into
// a failure above precisely so this line cannot retire it. #2683
// residual (#4496): a failed destination import likewise cannot retire
// the sentinel — the rename did not converge.
if (!reconcileFailed && !importErrored) succeededPaths.push(renameSentinelPath(to));
pagesAffected.push(newSlug);
deletedSlugs.delete(newSlug); // #1284: rename landed on a previously-deleted slug → embeddable again
// A failed reconcile OR a failed destination import must NOT checkpoint:
// banking `to` would make the resume filter skip this rename on the
// retry run — a permanent duplicate (reconcile) or a permanently
// unimported target (import error) — the exact bug class being fixed.
if (!reconcileFailed && !importErrored) { await markCompleted(run, to); noteCommittedProgress(); }
progress.tick(1, newSlug);
return undefined;
}
/**
* #5431: the stale old row's identity follows the page to the row now live at
* `newSlug`, in one transaction: `old -> new` is recorded as a slug alias so
* `[[old]]` keeps resolving, slug-keyed rows (facts, withdrawals, declared
* aliases) move, and page-id-keyed rows (edges, timeline, versions) move with
* duplicates on their unique keys dropped from the stale side.
*/
export async function carryRenameIdentity(engine: BrainEngine, sourceId: string, staleSlug: string, newSlug: string): Promise<void> {
const rows = await engine.executeRaw<{ slug: string; id: number | string }>(
'SELECT slug, id FROM pages WHERE source_id = $1 AND slug = ANY($2::text[])', [sourceId, [staleSlug, newSlug]]);
const from = rows.find(r => r.slug === staleSlug), to = rows.find(r => r.slug === newSlug);
if (!from || !to || from.id === to.id) return;
const publication = await maintenanceTransaction(engine, async tx => {
await tx.lockPageKeys([{ sourceId, slug: staleSlug }, { sourceId, slug: newSlug }]);
return recordFallbackRename(tx, { sourceId, staleSlug, newSlug, fromPageId: Number(from.id), toPageId: Number(to.id) }, async () => {
await recordRenameAlias(tx, sourceId, staleSlug, newSlug);
await moveSlugBindings(tx, sourceId, staleSlug, newSlug);
await movePageIdReferences(tx, Number(from.id), Number(to.id));
});
});
if (publication) await markBeliefCommits(engine, [publication]).catch(() => undefined);
}
/** The reconcile's own "cannot prove the old row stale" verdict: the one throw that keeps the `<rename:…>` sentinel by design. */
class RenameStalenessUnprovable extends Error {}
/**
* GBRA-133 S-67: holds `to` as `rename_reconcile_failed` when finding the stale rows threw something other than the
* unprovable verdict or a transient database error (a connection, a timeout, a lock), which a later run retries. The hold records
* the cause's class and code only, never its message (it can quote content). False when it does not apply.
*/
async function holdUnexpectedReconcileFailure(engine: BrainEngine, holds: LegacyHolds | null, input: { from: string; to: string; error: unknown }): Promise<boolean> {
if (!holds?.active || input.error instanceof RenameStalenessUnprovable) return false;
const classified = classifyItemFailure(input.error);
if (classified.scope === 'run' || classified.code === 'statement_timeout' || classified.code === 'lock_timeout') return false;
const name = input.error instanceof Error ? input.error.name : typeof input.error;
const code = (input.error as { code?: unknown } | null)?.code;
const cause = `${name}${typeof code === 'string' && /^[\w.-]{1,40}$/.test(code) ? ` ${code}` : ''}`;
try {
await recordLegacyHold(engine, holds, { path: input.to, upstreamVersion: null, refusal: { code: 'rename_reconcile_failed',
message: `${input.to} was renamed from ${input.from} and imported, but removing the old page failed unexpectedly (${cause}), so the old page was kept and may be a duplicate.` } });
return true;
} catch {
return false;
}
}
/**
* #3056: when the cheap rename did not apply, the rename fell back to add
* semantics; remove the stale old row once the destination materialized.
* Returns true when the reconcile failed (the `<rename:…>` sentinel was
* recorded and the rename must not checkpoint).
*/
async function reconcileRenameFallback(
run: SyncRun,
plan: Pick<SyncPlan, 'opts' | 'holds'>,
ctx: Pick<RenameContext, 'slugLiveness' | 'renameOldSlugs' | 'renameSentinelAlreadyOpen'>,
from: string,
to: string,
newSlug: string,
renameApplied: boolean,
importResult: Awaited<ReturnType<typeof importFile>> | undefined,
): Promise<boolean> {
const { engine, failedFiles, deletedSlugs } = run;
const { opts } = plan;
const { slugLiveness, renameOldSlugs, renameSentinelAlreadyOpen } = ctx;
// #3056 reconcile: the rename fell back to add semantics, so the row
// that still represents the OLD path is the stale half of the rename
// (git reported the old path gone; a plain delete of that path would
// remove this row). Two safety rails, both from the #3252 review:
//
// 1. Delete only after the destination demonstrably materialized —
// `imported`, or an errorless `skipped` AT the new slug. Identity
// dedup can skip against the OLD row (result.slug === oldSlug),
// in which case nothing landed at newSlug and deleting the old
// row would destroy the only copy.
// 2. Locate the stale row POSITIVELY by `source_path = from`, never
// by the oldSlug guess — after a collision, a path-derived
// fallback slug could name an unrelated (e.g. manually curated)
// row. No source_path match → nothing is deleted (code pages
// imported before `importCodeFile` wrote `source_path` (#4900)
// still carry NULL until their next import and fall back safely
// to leaving the old row rather than guessing).
//
// A failed delete records a `<rename:…>` SENTINEL (not an ordinary
// path failure): the gate hard-blocks the bookmark, and — unlike a
// plain path row — the auto-skip valve can never chronic-skip it after
// N attempts, which would advance the bookmark and make a transient
// delete outage a permanent duplicate. The sentinel clears through the
// ordinary success path once the rename converges on a later run.
let reconcileFailed = false;
if (!renameApplied && importResult !== undefined) {
const destMaterialized = importResult.status === 'imported' ||
(importResult.status === 'skipped' && !importResult.error && importResult.slug === newSlug);
if (destMaterialized) {
// Hoisted above the try so the failure record can name the exact
// row `gbrain delete` should remove when the DELETE itself failed
// (still unknown — recorded as `?` — when the probe threw first).
//
// ACTIVE rows only, considering EVERY row with the old path:
// source_path is non-unique, and a one-row resolve could hand back
// a soft-deleted row while a live duplicate sharing the path hides
// behind it (#3479 review). Skipping already-soft-deleted rows is
// also what makes `gbrain delete` (a soft delete) the documented
// operator exit from a permanent delete-failure wedge (blocker 1):
// retrying the hard delete against a row the operator already
// removed would just re-fail and keep the sync blocked.
// Rows whose CURRENT slug a working-tree file still derives to are
// LIVE, not stale, and are filtered out before any delete (#3583
// review) — so `staleSlug` below (and the sentinel/remedy text it
// feeds) can only ever name a genuinely-stale row.
let staleSlug: string | undefined;
let deleting = false;
try {
const active = await activeSlugsBySourcePath(
engine, [from], opts.sourceId ?? DEFAULT_SOURCE_ID,
);
// #3583 review (data-loss blocker): `source_path = from` also
// matches LIVE pages — after an ordinary cheap rename the
// surviving row keeps the OLD path (updateSlug never rewrites
// source_path; an unchanged-content re-import writes nothing).
// Delete only rows whose CURRENT slug no tracked file derives
// to; spare the rest — 'live' when a tracked file still derives
// to the slug, 'unknown' when staleness could not be proven.
const candidates = (active.get(from) ?? []).filter(s => s !== newSlug);
const staleSlugs: string[] = [];
const unprovable: string[] = [];
for (const s of candidates) {
// Carried by ANOTHER rename in this diff (see renameOldSlugs):
// its content is still tracked even when no slug state names
// it anymore — never a reconcile target of THIS rename.
let carriedByOtherRename = false;
for (const [rFrom, rOldSlugs] of renameOldSlugs) {
if (rFrom !== from && rOldSlugs.has(s)) { carriedByOtherRename = true; break; }
}
if (carriedByOtherRename) {
serr(
` [sync] rename reconcile: skipping row ${s} — another rename in ` +
`this diff still carries it (source_path ${from} is stale bookkeeping).`,
);
continue;
}
const verdict = slugLiveness(s, from);
if (verdict === 'live') {
serr(
` [sync] rename reconcile: skipping live row ${s} — a tracked ` +
`file still derives to it (source_path ${from} is stale bookkeeping).`,
);
} else if (verdict === 'unknown') {
// An unreadable tracked file could own this slug, so the row
// is NOT deleted. What happens to the RENAME depends on
// whether it was already unresolved (see the check after this
// loop): a first unprovable run is accepted and banks
// normally — the usual cause is a live row whose slug merely
// could not be read (content filter, shallow clone, sparse
// checkout, over-size file), where nothing is pending — but a
// rename that already carries an open sentinel is not
// retired on this evidence.
unprovable.push(s);
serr(
` [sync] rename reconcile: cannot prove row ${s} stale — an ` +
`unreadable tracked file could still own this slug, so it is ` +
`spared rather than deleted.`,
);
} else {
// Established bookkeeping cleanup (#3056 → gate 6): a stale
// claimant is exactly the duplicate the reconcile exists to
// remove once the destination materialized.
staleSlugs.push(s);
}
}
if (staleSlugs.length > 0) {
deleting = true;
// Delete every genuinely-stale active row still carrying the
// old path — with a non-unique source_path there can be more
// than one, and the rename is checkpointed after this loop, so
// a survivor would never be retried (#3479 review, the ORDER BY
// finding).
//
// Post-review note: the `slugLiveness(s)` verdict above and this
// `deletePage` are not one atomic operation — `deletePage` takes
// only `slug`, not a row id or updated_at, so it can't express
// "delete iff still the row I just proved stale". Under
// `performSync`'s per-source writer lock this window is closed
// for every normal caller (no other sync/import for this source
// can run concurrently); it only opens for a write that bypasses
// the lock entirely (e.g. a direct `put_page` racing this run).
// Closing it for real needs a conditional DELETE (id/source_path/
// updated_at) added to `BrainEngine.deletePage` on both engines —
// out of scope for this fix; tracked as a known gap rather than
// silently assumed safe.
for (const s of staleSlugs) {
staleSlug = s;
// #5431: the stale row is the renamed page's old identity; its
// edges, timeline and versions move to the row that materialized
// at the destination (deduplicated on the links key) before the
// row itself is soft-deleted.
await carryRenameIdentity(engine, opts.sourceId ?? DEFAULT_SOURCE_ID, s, newSlug);
// #4587: soft-delete the stale claimant (72h recovery) —
// candidates come from activeSlugsBySourcePath, so every s
// is an ACTIVE row and the flip always applies. Same scope
// fallback updateSlug/renameOpts use ('default' when the
// caller threads no sourceId).
await softDeleteSyncPages(engine, [s], { sourceId: opts.sourceId ?? DEFAULT_SOURCE_ID });
deletedSlugs.add(s); // never hand a deleted slug to auto-embed
serr(` [sync] rename reconciled: soft-deleted stale row ${s} (recoverable 72h; ${from} -> ${to} fell back to add).`);
}
} else if (candidates.length > 0) {
serr(` [sync] rename fallback: every active row with source_path ${from} was spared (live or unprovable); nothing stale to reconcile.`);
} else {
serr(` [sync] rename fallback: no active row has source_path ${from}; nothing left to reconcile.`);
}
if (unprovable.length > 0 && renameSentinelAlreadyOpen(to)) {
// Provably-stale rows above were still removed; these were not
// provable either way. On its own that is an accepted cost (see
// the verdict comment). But an EARLIER run already recorded a
// `<rename:…>` sentinel for this rename, so convergence has been
// denied before — and falling through would hand that sentinel
// to the success path, which the gate clears before it decides.
// Clearing a non-convergence marker requires proof of
// convergence, and 'unprovable' is not proof.
// Deliberately NOT named: `staleSlug` feeds the sentinel's
// "stale row X" slot and the blocked-run remedy tells the
// operator to `gbrain delete X`. An unprovable row may well be
// LIVE — that is the whole reason it was spared — so naming one
// here would tell the operator to delete a page this very code
// just refused to delete. Clearing it also drops whatever
// actionable slug an earlier failure had recorded. `undefined`
// renders as `?`, which is the truth: not known.
staleSlug = undefined;
throw new RenameStalenessUnprovable(
`staleness unprovable for ${unprovable.length} row(s) ` +
`(${unprovable.join(', ')}): the tracked-file slug index is ` +
`incomplete, so no index miss proves a row stale, and this ` +
`rename was already unresolved. Fix or remove the unreadable ` +
`tracked file and re-run.`,
);
}
} catch (e: unknown) {
// GBRA-133 S-67: a failed delete keeps the sentinel (#3056/#3479: it converges, or `gbrain delete` is its exit), as do
// the unprovable verdict and a transient database error; any other throw while finding the stale rows is
// deterministic, so this rename is held and the rest of the source syncs.
if (!deleting && await holdUnexpectedReconcileFailure(engine, plan.holds, { from, to, error: e })) return false;
reconcileFailed = true;
failedFiles.push({
path: renameSentinelPath(to),
error: renameReconcileErrorMessage(
from, staleSlug, e instanceof Error ? e.message : String(e),
),
});
}
} else {
serr(
` [sync] rename fallback: ${from} -> ${to} did not materialize at ${newSlug} ` +
`(import ${importResult.status}); old row left in place.`,
);
}
}
return reconcileFailed;
}