Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Stop rename-path waiting on a shadow-history commit (PRD-9066) (#5774)

Andrew Mikofalvyb2836cc793cb
diff --git a/.changeset/prd-9066-rename-without-history-wait.md b/.changeset/prd-9066-rename-without-history-wait.md
new file mode 100644
index 000000000..f8409af4c
--- /dev/null
+++ b/.changeset/prd-9066-rename-without-history-wait.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Renaming or moving files no longer waits for version history to save before it completes, so moving many files in a row is faster.
diff --git a/packages/app/tests/integration/rename-history.test.ts b/packages/app/tests/integration/rename-history.test.ts
index e083af828..9bacb7290 100644
--- a/packages/app/tests/integration/rename-history.test.ts
+++ b/packages/app/tests/integration/rename-history.test.ts
@@ -11,6 +11,7 @@ import {
import {
agentWriteMd,
createRestartableServer,
+ createTestClient,
pollUntil,
type RestartableServer,
wait,
@@ -461,7 +462,7 @@ describe('Timeline rename-history mitigation — integration', () => {
expect(bHistory.entries.map((e) => e.sha)).not.toContain(newAWipSha);
}, 90_000);
- test('rename → full chain visible immediately on /api/history (spine drains contributors before response)', async () => {
+ test('rename → full chain visible on the first /api/history read after the rename', async () => {
const server = await bootServer();
await agentWriteMdAndAwaitWip(server, '# A v1\n', {
@@ -480,11 +481,6 @@ describe('Timeline rename-history mitigation — integration', () => {
.status,
).toBe(200);
- const entries = readRenameLogEntries(server);
- const entry = entries.find((e) => e.from === 'a' && e.to === 'b');
- expect(entry).toBeDefined();
- expect(entry?.commitSha).toMatch(/^[0-9a-f]{40}$/);
-
const fullQuery = await getHistory(server.port, 'b');
expect(fullQuery.entries.map((e) => e.sha)).toContain(preWipSha);
}, 60_000);
@@ -610,7 +606,10 @@ describe('Timeline rename-history mitigation — integration', () => {
expect(renameRes.status).toBe(200);
expect(renameRes.body.renamed).toHaveLength(3);
- const entries = readRenameLogEntries(server);
+ const entries = await pollForBackfill(
+ server,
+ ['a', 'b', 'c'].map((name) => ({ from: `src-folder/${name}`, to: `dst-folder/${name}` })),
+ );
const folderEntries = entries.filter(
(e) => e.from.startsWith('src-folder/') && e.to.startsWith('dst-folder/'),
);
@@ -652,7 +651,7 @@ describe('Timeline rename-history mitigation — integration', () => {
});
expect(renameRes.status).toBe(200);
- const entries = readRenameLogEntries(server);
+ const entries = await pollForBackfill(server, [{ from: 'summary-a', to: 'summary-b' }]);
const entry = entries.find((e) => e.from === 'summary-a' && e.to === 'summary-b');
expect(entry?.commitSha).toMatch(/^[0-9a-f]{40}$/);
const renameSha = entry?.commitSha ?? '';
@@ -713,8 +712,12 @@ describe('Timeline rename-history mitigation — integration', () => {
expect(versionRes.body.content).toContain('original body');
}, 60_000);
- test('pure rename without subsequent edit → commitSha backfilled before /api/rename-path response returns', async () => {
- const server = await bootServer();
+ test('pure rename with no later request → commitSha backfilled without waiting for the commit debounce', async () => {
+ const server = await createRestartableServer({
+ gitEnabled: true,
+ commitDebounceMs: 600_000,
+ });
+ cleanups.push(() => server.shutdown());
writeFileSync(join(server.contentDir, 'pure-a.md'), '# Pure A\n', 'utf-8');
await pollUntil(async () => {
const res = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
@@ -731,6 +734,7 @@ describe('Timeline rename-history mitigation — integration', () => {
});
expect(renameRes.status).toBe(200);
+ await pollForBackfill(server, [{ from: 'pure-a', to: 'pure-b' }]);
const jsonlPath = renameLogPath(resolveShadowDir(server.contentDir));
const raw = readFileSync(jsonlPath, 'utf-8');
const lines = raw.split('\n').filter((l) => l.length > 0);
@@ -741,6 +745,76 @@ describe('Timeline rename-history mitigation — integration', () => {
expect(matching[0].commitSha).toMatch(/^[0-9a-f]{40}$/);
}, 60_000);
+ test('rename followed at once by a graceful restart keeps the pre-rename history', async () => {
+ const first = await createRestartableServer({
+ gitEnabled: true,
+ commitDebounceMs: 600_000,
+ });
+ cleanups.push(() => first.shutdown());
+ await agentWriteMdAndAwaitWip(first, '# Restart v1\n', {
+ docName: 'restart-a',
+ position: 'replace',
+ ...AGENT,
+ });
+ const preRenameShas = await getWipShas(first, 'restart-a');
+ expect(preRenameShas.size).toBeGreaterThan(0);
+ await crossSecondBoundary();
+
+ expect(
+ (
+ await renamePath(first.port, {
+ kind: 'file',
+ fromPath: 'restart-a.md',
+ toPath: 'restart-b.md',
+ ...AGENT,
+ })
+ ).status,
+ ).toBe(200);
+
+ const second = await first.shutdownAndRestartOnSamePort({ downtimeMs: 0 });
+ cleanups.push(() => second.shutdown());
+
+ const postRestartShas = await getWipShas(second, 'restart-b');
+ expect([...postRestartShas]).toEqual(expect.arrayContaining([...preRenameShas]));
+ }, 90_000);
+
+ test('POST /api/rollback right after a rename restores a pre-rename commit under the new name', async () => {
+ const server = await bootServer();
+ await agentWriteMdAndAwaitWip(server, '# Poem v1\n\nfirst stanza\n', {
+ docName: 'poem',
+ position: 'replace',
+ ...AGENT,
+ });
+ const [preRenameSha] = await getWipShas(server, 'poem');
+ expect(preRenameSha).toMatch(/^[0-9a-f]{40}$/);
+ if (!preRenameSha) throw new Error('preRenameSha unset');
+ await agentWriteMdAndAwaitWip(server, '\nsecond stanza\n', {
+ docName: 'poem',
+ position: 'append',
+ ...AGENT,
+ });
+ await crossSecondBoundary();
+
+ expect(
+ (
+ await renamePath(server.port, {
+ kind: 'file',
+ fromPath: 'poem.md',
+ toPath: 'verse.md',
+ ...AGENT,
+ })
+ ).status,
+ ).toBe(200);
+
+ const verseClient = await createTestClient(server.port, 'verse');
+ cleanups.push(() => verseClient.cleanup());
+ const rb = await rollback(server.port, { docName: 'verse', commitSha: preRenameSha, ...AGENT });
+ expect(rb.status).toBe(200);
+ const versePath = join(server.contentDir, 'verse.md');
+ await pollUntil(() => !readFileSync(versePath, 'utf-8').includes('second stanza'), 10_000, 25);
+ expect(readFileSync(versePath, 'utf-8')).toContain('first stanza');
+ }, 60_000);
+
test('1000-doc folder rename completes within budget; jsonl size stays under hard cap', async () => {
const server = await bootServer();
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index bf9831ec9..c1e95ad9f 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -5214,7 +5214,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
contentFilter,
signalChannel,
conflicts,
- flushContributors,
+ commitOkArtifactWrite,
fileOpsService,
assetService,
extractAgentIdentity,
@@ -5372,6 +5372,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
computeLintViolations,
log,
flushDocToGit,
+ commitOkArtifactWrite,
isSafeDocName,
shadowRef,
getPrincipal,
diff --git a/packages/server/src/http/agent-write-routes.test.ts b/packages/server/src/http/agent-write-routes.test.ts
index 07cecf11d..472fc73d1 100644
--- a/packages/server/src/http/agent-write-routes.test.ts
+++ b/packages/server/src/http/agent-write-routes.test.ts
@@ -56,6 +56,7 @@ function buildGroup(overrides: Partial<Deps> = {}) {
computeLintViolations: notDispatched,
log: loggerFactory.getLogger('test'),
flushDocToGit: notDispatched,
+ commitOkArtifactWrite: notDispatched,
isSafeDocName: notDispatched,
shadowRef: undefined,
getPrincipal: undefined,
diff --git a/packages/server/src/http/agent-write-routes.ts b/packages/server/src/http/agent-write-routes.ts
index 920f29422..90d39b8ea 100644
--- a/packages/server/src/http/agent-write-routes.ts
+++ b/packages/server/src/http/agent-write-routes.ts
@@ -210,6 +210,7 @@ export interface AgentWriteRouteDeps {
) => Promise<LintViolationWarning[]>;
log: import('../logger.ts').PinoLogger;
flushDocToGit: (docName: string, label: string) => void;
+ commitOkArtifactWrite: (context: string) => Promise<unknown>;
isSafeDocName: (docName: string) => boolean;
shadowRef: ShadowRef | undefined;
getPrincipal: (() => Principal | null) | undefined;
@@ -254,6 +255,7 @@ export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroup
computeLintViolations,
log,
flushDocToGit,
+ commitOkArtifactWrite,
isSafeDocName,
shadowRef,
getPrincipal,
@@ -1499,6 +1501,7 @@ export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroup
const sg = shadowGit(shadow);
const t0 = Date.now();
try {
+ await commitOkArtifactWrite('rollback-read');
const renameLogIndex = getOrLoadRenameLogIndex(shadow.gitDir);
const ancestorCache = createAncestorShaSetCache();
const branch = getCurrentBranch?.() ?? 'main';
diff --git a/packages/server/src/http/file-ops-routes.test.ts b/packages/server/src/http/file-ops-routes.test.ts
index eec5c824a..5867c7dbb 100644
--- a/packages/server/src/http/file-ops-routes.test.ts
+++ b/packages/server/src/http/file-ops-routes.test.ts
@@ -24,7 +24,7 @@ function buildGroup(overrides: Partial<Deps> = {}) {
contentFilter: undefined,
signalChannel: undefined,
conflicts: createTestConflictAuthority(makeTempDir('file-ops-routes-authority-')),
- flushContributors: undefined,
+ commitOkArtifactWrite: () => Promise.resolve(),
fileOpsService: {} as FileOpsService,
assetService: {} as AssetService,
extractAgentIdentity: () => {
@@ -161,3 +161,44 @@ describe('create-page path-resolution error classification', () => {
);
});
});
+
+describe('rename-path history commit', () => {
+ function buildRenameGroup() {
+ const commits: string[] = [];
+ const group = buildGroup({
+ docNameForFileOperationPath: (_contentDir, path) => path.replace(/\.md$/, ''),
+ isValidRelativeContentPath: () => true,
+ renameAttributionCounter: () =>
+ ({ add: () => {} }) as unknown as ReturnType<Deps['renameAttributionCounter']>,
+ commitOkArtifactWrite: (context) => {
+ commits.push(context);
+ return new Promise<never>(() => {});
+ },
+ _performManagedRenameForDocs: () =>
+ Promise.resolve({
+ renamed: [{ fromDocName: 'a', toDocName: 'b' }],
+ renamedAssets: [],
+ rewrittenDocs: [],
+ }),
+ _performAssetRename: () =>
+ Promise.resolve({
+ renamedAssets: [{ fromPath: 'a.png', toPath: 'b.png' }],
+ rewrittenDocs: [],
+ }),
+ });
+ const resolved = group.table.resolve('/api/rename-path');
+ if (!resolved?.dispatch) throw new Error('rename-path did not resolve to a dispatch handler');
+ return { dispatch: resolved.dispatch, commits };
+ }
+
+ test.each([
+ { kind: 'file', fromPath: 'a.md', toPath: 'b.md' },
+ { kind: 'asset', fromPath: 'a.png', toPath: 'b.png' },
+ ])('$kind rename responds while its history commit is still running', async (body) => {
+ const { dispatch, commits } = buildRenameGroup();
+ const { res, captured } = makeRes();
+ await dispatch(makeReq('/api/rename-path', body), res);
+ expect(captured.status).toBe(200);
+ expect(commits).toEqual(['rename-path']);
+ });
+});
diff --git a/packages/server/src/http/file-ops-routes.ts b/packages/server/src/http/file-ops-routes.ts
index 28ccbf084..2850628bd 100644
--- a/packages/server/src/http/file-ops-routes.ts
+++ b/packages/server/src/http/file-ops-routes.ts
@@ -270,7 +270,7 @@ export interface FileOpsRouteDeps {
contentFilter: ContentFilter | undefined;
signalChannel: ((channel: 'files' | 'lint-config' | 'comments') => void) | undefined;
conflicts: ConflictAuthority;
- flushContributors: (() => Promise<void>) | undefined;
+ commitOkArtifactWrite: (context: string) => Promise<unknown>;
fileOpsService: FileOpsService;
assetService: AssetService;
extractAgentIdentity: (body: Record<string, unknown>) => {
@@ -353,7 +353,7 @@ export function createFileOpsRoutes(deps: FileOpsRouteDeps): ApiRouteGroup {
contentFilter,
signalChannel,
conflicts,
- flushContributors,
+ commitOkArtifactWrite,
fileOpsService,
assetService,
extractAgentIdentity,
@@ -1035,16 +1035,7 @@ export function createFileOpsRoutes(deps: FileOpsRouteDeps): ApiRouteGroup {
attribution_kind: actor.kind,
});
- if (flushContributors) {
- try {
- await flushContributors();
- } catch (flushErr) {
- log.warn(
- { err: flushErr },
- '[rename-path] flushContributors failed after asset rename (commitSha backfill may be deferred)',
- );
- }
- }
+ void commitOkArtifactWrite('rename-path');
successResponse(
res,
@@ -1185,16 +1176,7 @@ export function createFileOpsRoutes(deps: FileOpsRouteDeps): ApiRouteGroup {
attribution_kind: actor.kind,
});
- if (flushContributors) {
- try {
- await flushContributors();
- } catch (flushErr) {
- log.warn(
- { err: flushErr },
- '[rename-path] flushContributors failed (commitSha backfill may be deferred)',
- );
- }
- }
+ void commitOkArtifactWrite('rename-path');
successResponse(
res,
diff --git a/packages/server/src/http/history-routes.test.ts b/packages/server/src/http/history-routes.test.ts
index 30de62d22..862c65879 100644
--- a/packages/server/src/http/history-routes.test.ts
+++ b/packages/server/src/http/history-routes.test.ts
@@ -1,8 +1,16 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
import { isValidBranchName } from '@inkeep/open-knowledge-core';
-import { describe, expect, test } from 'vitest';
+import { afterEach, describe, expect, test } from 'vitest';
import { makeCaptureRes, makeSyntheticReq } from '../composition-rig.test-helper.ts';
import { loggerFactory } from '../logger.ts';
-import type { ShadowHandle, ShadowRef } from '../shadow-repo.ts';
+import {
+ appendRenameLogEntry,
+ getOrLoadRenameLogIndex,
+ resetRenameLogIndexCache,
+} from '../rename-log.ts';
+import { initShadowRepo, type ShadowHandle, type ShadowRef } from '../shadow-repo.ts';
import { createHistoryRoutes } from './history-routes.ts';
type Deps = Parameters<typeof createHistoryRoutes>[0];
@@ -188,3 +196,57 @@ describe('GET /api/history branch admission — names git rejects that the contr
},
);
});
+
+describe('GET /api/history/:sha settles pending history only for a pending rename', () => {
+ const tmpDirs: string[] = [];
+
+ afterEach(() => {
+ resetRenameLogIndexCache();
+ for (const dir of tmpDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+ });
+
+ test.each([
+ { log: 'an empty rename log', commitSha: undefined, settles: 0 },
+ { log: 'only a committed rename', commitSha: 'b'.repeat(40), settles: 0 },
+ { log: 'a rename awaiting its commit', commitSha: '', settles: 1 },
+ ])('with $log, the read settles $settles time(s)', async ({ commitSha, settles }) => {
+ const projectDir = mkdtempSync(join(tmpdir(), 'ok-history-version-'));
+ tmpDirs.push(projectDir);
+ resetRenameLogIndexCache();
+ const shadow = await initShadowRepo(projectDir);
+ if (commitSha !== undefined) {
+ appendRenameLogEntry(
+ shadow.gitDir,
+ {
+ v: 1,
+ from: 'alpha',
+ to: 'beta',
+ at: new Date().toISOString(),
+ commitSha,
+ branch: 'main',
+ groupId: 'alpha-beta',
+ kind: 'file',
+ actor: { writerId: 'agent-mover', displayName: 'Mover' },
+ },
+ getOrLoadRenameLogIndex(shadow.gitDir),
+ shadow,
+ );
+ }
+ const contexts: string[] = [];
+ const { table } = buildGroup({
+ shadowRef: { current: shadow },
+ safeDocPath: (docName) => ({ path: `${docName}.md` }),
+ commitOkArtifactWrite: (context) => {
+ contexts.push(context);
+ return Promise.resolve();
+ },
+ });
+ const path = `/api/history/${'a'.repeat(40)}`;
+ const dispatch = table.resolve(path)?.dispatch;
+ if (!dispatch) throw new Error(`${path} did not resolve to a dispatch handler`);
+ const { res } = makeCaptureRes();
+ await dispatch(makeSyntheticReq({ url: `${path}?docName=beta` }), res);
+
+ expect(contexts).toEqual(Array(settles).fill('history-version-read'));
+ });
+});
diff --git a/packages/server/src/http/history-routes.ts b/packages/server/src/http/history-routes.ts
index 7caab578e..81111d87b 100644
--- a/packages/server/src/http/history-routes.ts
+++ b/packages/server/src/http/history-routes.ts
@@ -9,6 +9,7 @@ import { getLogger, type PinoLogger } from '../logger.ts';
import {
createAncestorShaSetCache,
getOrLoadRenameLogIndex,
+ pendingRenameLogEntries,
resolveDocPathAtCommit,
} from '../rename-log.ts';
import { type ShadowRef, shadowGit } from '../shadow-repo.ts';
@@ -229,6 +230,9 @@ export function createHistoryRoutes(deps: HistoryRouteDeps): HistoryRoutes {
}
try {
+ if (pendingRenameLogEntries(getOrLoadRenameLogIndex(shadow.gitDir)).size > 0) {
+ await commitOkArtifactWrite('history-version-read');
+ }
const renameLogIndex = getOrLoadRenameLogIndex(shadow.gitDir);
const ancestorCache = createAncestorShaSetCache();
const historicalPath = await resolveDocPathAtCommit(
diff --git a/packages/server/src/persistence-rename-backfill.test.ts b/packages/server/src/persistence-rename-backfill.test.ts
new file mode 100644
index 000000000..dc340fdaa
--- /dev/null
+++ b/packages/server/src/persistence-rename-backfill.test.ts
@@ -0,0 +1,108 @@
+import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { recordContributor, swapContributors } from './contributor-tracker.ts';
+import { createPersistenceExtension } from './persistence.ts';
+import {
+ appendRenameLogEntry,
+ getOrLoadRenameLogIndex,
+ loadRenameLogIndex,
+ type RenameLogEntry,
+ resetRenameLogIndexCache,
+} from './rename-log.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+
+const commitHooks = vi.hoisted(() => ({
+ beforeWriterCommit: undefined as undefined | (() => void),
+}));
+
+vi.mock('./shadow-repo.ts', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('./shadow-repo.ts')>();
+ return {
+ ...actual,
+ commitWipFromTree: (...args: Parameters<typeof actual.commitWipFromTree>) => {
+ const hook = commitHooks.beforeWriterCommit;
+ commitHooks.beforeWriterCommit = undefined;
+ hook?.();
+ return actual.commitWipFromTree(...args);
+ },
+ };
+});
+
+const WRITER = { id: 'agent-mover', name: 'Mover' };
+
+let tmpDir: string;
+let contentDir: string;
+let shadow: ShadowHandle;
+
+beforeEach(async () => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-rename-backfill-'));
+ contentDir = join(tmpDir, 'content');
+ mkdirSync(contentDir, { recursive: true });
+ shadow = await initShadowRepo(tmpDir);
+ swapContributors();
+ resetRenameLogIndexCache();
+});
+
+afterEach(() => {
+ commitHooks.beforeWriterCommit = undefined;
+ swapContributors();
+ resetRenameLogIndexCache();
+ rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function renameOnDisk(from: string, to: string): void {
+ renameSync(join(contentDir, `${from}.md`), join(contentDir, `${to}.md`));
+ const entry: RenameLogEntry = {
+ v: 1,
+ from,
+ to,
+ at: new Date().toISOString(),
+ commitSha: '',
+ branch: 'main',
+ groupId: `${from}-${to}`,
+ kind: 'file',
+ actor: { writerId: WRITER.id, displayName: WRITER.name },
+ };
+ appendRenameLogEntry(shadow.gitDir, entry, getOrLoadRenameLogIndex(shadow.gitDir), shadow);
+ recordContributor(to, WRITER.id, WRITER.name, WRITER.id, undefined, undefined, undefined, [
+ { from, to },
+ ]);
+}
+
+async function treePaths(sha: string): Promise<string[]> {
+ const listing = await shadowGit(shadow).raw('ls-tree', '-r', '--name-only', sha);
+ return listing.split('\n').filter((line) => line.length > 0);
+}
+
+describe('rename-log commitSha backfill', () => {
+ test('a history commit only claims renames that were on disk when its tree was built', async () => {
+ writeFileSync(join(contentDir, 'alpha.md'), '# alpha\n');
+ writeFileSync(join(contentDir, 'gamma.md'), '# gamma\n');
+ const persistence = createPersistenceExtension({
+ contentDir,
+ projectDir: tmpDir,
+ contentRoot: 'content',
+ shadowRef: { current: shadow },
+ commitDebounceMs: 600_000,
+ });
+
+ renameOnDisk('alpha', 'beta');
+ commitHooks.beforeWriterCommit = () => renameOnDisk('gamma', 'delta');
+ await persistence.flushContributors();
+ await persistence.flushContributors();
+
+ const entries = [...loadRenameLogIndex(shadow.gitDir).byTo.values()];
+ expect(entries.map((e) => `${e.from}->${e.to}`).sort()).toEqual([
+ 'alpha->beta',
+ 'gamma->delta',
+ ]);
+ for (const entry of entries) {
+ expect(entry.commitSha, `${entry.from}->${entry.to}`).toMatch(/^[0-9a-f]{40}$/);
+ expect(await treePaths(entry.commitSha), `${entry.from}->${entry.to}`).toContain(
+ `content/${entry.to}.md`,
+ );
+ }
+ });
+});
diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.ts
index 81a4078af..3c2389ef5 100644
--- a/packages/server/src/persistence.ts
+++ b/packages/server/src/persistence.ts
@@ -124,7 +124,11 @@ import {
import { toPosix } from './path-utils.ts';
import { classifyDuplication } from './persistence-tripwire.ts';
import { assertProjectContentScope, NestedProjectScopeError } from './project-content-scope.ts';
-import { backfillRenameLogCommitSha, getOrLoadRenameLogIndex } from './rename-log.ts';
+import {
+ backfillRenameLogCommitSha,
+ getOrLoadRenameLogIndex,
+ pendingRenameLogEntries,
+} from './rename-log.ts';
import { getConvergedFragmentWitness, OBSERVER_SYNC_ORIGIN } from './server-observers.ts';
import type { ShadowRef, WriterIdentity } from './shadow-repo.ts';
import {
@@ -498,6 +502,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
const shadow = shadowRef?.current;
if (shadow) {
const snapshot = swapContributors();
+ const claimableRenames = pendingRenameLogEntries(getOrLoadRenameLogIndex(shadow.gitDir));
const branch = getCurrentBranch?.() ?? 'main';
if (snapshot.size === 0) {
@@ -528,6 +533,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
SERVICE_WRITER.id,
sha,
getOrLoadRenameLogIndex(shadow.gitDir),
+ claimableRenames,
);
} catch (err) {
log.warn({ err }, '[rename-log] service-writer backfill failed');
@@ -611,6 +617,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
writerId,
sha,
getOrLoadRenameLogIndex(shadow.gitDir),
+ claimableRenames,
);
} catch (err) {
log.warn({ err }, '[rename-log] backfill failed; will retry next commit');
diff --git a/packages/server/src/removal-guard-watcher-update.test.ts b/packages/server/src/removal-guard-watcher-update.test.ts
new file mode 100644
index 000000000..233f21510
--- /dev/null
+++ b/packages/server/src/removal-guard-watcher-update.test.ts
@@ -0,0 +1,92 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import {
+ HocuspocusAuthRejection,
+ type HocuspocusAuthRejectionReason,
+} from './auth-token-schema.ts';
+import type { DiskEvent } from './file-watcher.ts';
+import { createServer, type ServerInstance } from './server-factory.ts';
+
+const watcher = vi.hoisted(() => ({
+ deliver: null as null | ((event: DiskEvent) => Promise<void>),
+}));
+
+vi.mock('./file-watcher.ts', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('./file-watcher.ts')>();
+ return {
+ ...actual,
+ startWatcher: (
+ ...[contentDir, onDiskEvent, ...rest]: Parameters<typeof actual.startWatcher>
+ ) => {
+ watcher.deliver = onDiskEvent;
+ return actual.startWatcher(contentDir, onDiskEvent, ...rest);
+ },
+ };
+});
+
+const fixtures: string[] = [];
+
+afterEach(() => {
+ watcher.deliver = null;
+ for (const fixture of fixtures.splice(0)) rmSync(fixture, { recursive: true, force: true });
+});
+
+async function guardOutcome(
+ server: ServerInstance,
+ documentName: string,
+): Promise<HocuspocusAuthRejectionReason | 'admitted'> {
+ const guard = server.hocuspocus.configuration.extensions.find(
+ (extension) => (extension as { __kind?: string }).__kind === 'removal-redirect-guard',
+ ) as { onAuthenticate: (payload: { documentName: string }) => Promise<void> } | undefined;
+ if (!guard) throw new Error('expected the removal-redirect guard on hocuspocus');
+ try {
+ await guard.onAuthenticate({ documentName });
+ return 'admitted';
+ } catch (err) {
+ if (err instanceof HocuspocusAuthRejection) return err.kind;
+ throw err;
+ }
+}
+
+describe('removal guard and watcher updates', () => {
+ test('a watcher update at a renamed-away name stops redirecting that name', async () => {
+ const contentDir = mkdtempSync(join(tmpdir(), 'ok-removal-update-'));
+ const home = mkdtempSync(join(tmpdir(), 'ok-removal-update-home-'));
+ fixtures.push(contentDir, home);
+ const server = createServer({
+ contentDir,
+ quiet: true,
+ gitEnabled: false,
+ configHomedirOverride: home,
+ skipStateManifestCheck: true,
+ });
+ try {
+ await server.ready;
+ const deliver = watcher.deliver;
+ if (!deliver) throw new Error('expected the server to start a watcher');
+
+ writeFileSync(join(contentDir, 'successor.md'), '# Successor\n');
+ await deliver({
+ kind: 'rename',
+ oldPath: join(contentDir, 'original.md'),
+ newPath: join(contentDir, 'successor.md'),
+ oldDocName: 'original',
+ newDocName: 'successor',
+ content: '# Successor\n',
+ });
+ expect(await guardOutcome(server, 'original')).toBe('rename-redirect');
+
+ await deliver({
+ kind: 'update',
+ path: join(contentDir, 'original.md'),
+ docName: 'original',
+ content: '# Recreated\n',
+ });
+ expect(await guardOutcome(server, 'original')).toBe('admitted');
+ } finally {
+ await server.destroy();
+ }
+ });
+});
diff --git a/packages/server/src/rename-log.test.ts b/packages/server/src/rename-log.test.ts
index 65df0ac86..9d22df684 100644
--- a/packages/server/src/rename-log.test.ts
+++ b/packages/server/src/rename-log.test.ts
@@ -19,6 +19,7 @@ import {
gcRenameLog,
loadRenameLogIndex,
MAX_PREDECESSOR_CHAIN_DEPTH,
+ pendingRenameLogEntries,
RENAME_LOG_HARD_CAP_BYTES,
type RenameLogEntry,
renameLogPath,
@@ -832,7 +833,13 @@ describe('backfillRenameLogCommitSha (US-007)', () => {
});
appendRenameLogEntry(shadowDir, e, index);
- const result = backfillRenameLogCommitSha(shadowDir, 'agent-claude-1', sha, index);
+ const result = backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-claude-1',
+ sha,
+ index,
+ pendingRenameLogEntries(index),
+ );
expect(result.updated).toBe(1);
expect(index.byTo.get('b')?.commitSha).toBe(sha);
@@ -848,11 +855,32 @@ describe('backfillRenameLogCommitSha (US-007)', () => {
});
appendRenameLogEntry(shadowDir, e, index);
- const result = backfillRenameLogCommitSha(shadowDir, 'agent-claude-1', 'c'.repeat(40), index);
+ const result = backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-claude-1',
+ 'c'.repeat(40),
+ index,
+ pendingRenameLogEntries(index),
+ );
expect(result.updated).toBe(0);
expect(index.byTo.get('essays/auth')?.commitSha).toBe('b'.repeat(40));
});
+ test('leaves entries appended after the claimable snapshot pending', () => {
+ const index = createEmptyIndex();
+ const actor = { writerId: 'agent-1', displayName: 'A' };
+ appendRenameLogEntry(shadowDir, entry({ from: 'a', to: 'b', commitSha: '', actor }), index);
+ const claimable = pendingRenameLogEntries(index);
+ appendRenameLogEntry(shadowDir, entry({ from: 'c', to: 'd', commitSha: '', actor }), index);
+
+ const sha = 'e'.repeat(40);
+ const result = backfillRenameLogCommitSha(shadowDir, 'agent-1', sha, index, claimable);
+ expect(result.updated).toBe(1);
+ const reloaded = loadRenameLogIndex(shadowDir);
+ expect(reloaded.byTo.get('b')?.commitSha).toBe(sha);
+ expect(reloaded.byTo.get('d')?.commitSha).toBe('');
+ });
+
test('does not update entries with mismatched writerId', () => {
const index = createEmptyIndex();
const e = entry({
@@ -863,7 +891,13 @@ describe('backfillRenameLogCommitSha (US-007)', () => {
});
appendRenameLogEntry(shadowDir, e, index);
- const result = backfillRenameLogCommitSha(shadowDir, 'agent-claude-1', 'c'.repeat(40), index);
+ const result = backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-claude-1',
+ 'c'.repeat(40),
+ index,
+ pendingRenameLogEntries(index),
+ );
expect(result.updated).toBe(0);
expect(index.byTo.get('b')?.commitSha).toBe('');
});
@@ -918,7 +952,13 @@ describe('backfillRenameLogCommitSha (US-007)', () => {
);
const sha = 'f'.repeat(40);
- const result = backfillRenameLogCommitSha(shadowDir, 'agent-1', sha, index);
+ const result = backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-1',
+ sha,
+ index,
+ pendingRenameLogEntries(index),
+ );
expect(result.updated).toBe(3);
for (const to of ['b/x', 'b/y', 'b/z']) {
expect(index.byTo.get(to)?.commitSha).toBe(sha);
@@ -937,8 +977,14 @@ describe('backfillRenameLogCommitSha (US-007)', () => {
index,
);
const sha = 'a'.repeat(40);
- backfillRenameLogCommitSha(shadowDir, 'agent-1', sha, index);
- const second = backfillRenameLogCommitSha(shadowDir, 'agent-1', sha, index);
+ backfillRenameLogCommitSha(shadowDir, 'agent-1', sha, index, pendingRenameLogEntries(index));
+ const second = backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-1',
+ sha,
+ index,
+ pendingRenameLogEntries(index),
+ );
expect(second.updated).toBe(0);
});
@@ -959,7 +1005,13 @@ describe('backfillRenameLogCommitSha (US-007)', () => {
expect(pre.chain).toEqual([{ path: 'b', renameCommit: null }]);
expect(pre.skipped).toBe(1);
- backfillRenameLogCommitSha(shadowDir, 'agent-1', 'a'.repeat(40), index);
+ backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-1',
+ 'a'.repeat(40),
+ index,
+ pendingRenameLogEntries(index),
+ );
const post = expandPredecessors('b', 'main', index);
expect(post.chain).toEqual([
@@ -1467,7 +1519,13 @@ describe('backfillRenameLogCommitSha SHA validation', () => {
if (msg.includes('rejected invalid commitSha')) warned = true;
});
try {
- const result = backfillRenameLogCommitSha(shadowDir, 'agent-x', '', index);
+ const result = backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-x',
+ '',
+ index,
+ pendingRenameLogEntries(index),
+ );
expect(result.updated).toBe(0);
expect(index.byTo.get('essays/auth')?.commitSha).toBe('');
} finally {
@@ -1485,7 +1543,13 @@ describe('backfillRenameLogCommitSha SHA validation', () => {
);
const warnSpy = vi.spyOn(getLogger('rename-log'), 'warn').mockImplementation(() => {});
try {
- const result = backfillRenameLogCommitSha(shadowDir, 'agent-x', 'abc123', index);
+ const result = backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-x',
+ 'abc123',
+ index,
+ pendingRenameLogEntries(index),
+ );
expect(result.updated).toBe(0);
} finally {
warnSpy.mockRestore();
@@ -1502,7 +1566,13 @@ describe('backfillRenameLogCommitSha SHA validation', () => {
);
const warnSpy = vi.spyOn(getLogger('rename-log'), 'warn').mockImplementation(() => {});
try {
- const result = backfillRenameLogCommitSha(shadowDir, 'agent-x', 'g'.repeat(40), index);
+ const result = backfillRenameLogCommitSha(
+ shadowDir,
+ 'agent-x',
+ 'g'.repeat(40),
+ index,
+ pendingRenameLogEntries(index),
+ );
expect(result.updated).toBe(0);
} finally {
warnSpy.mockRestore();
diff --git a/packages/server/src/rename-log.ts b/packages/server/src/rename-log.ts
index 6b3f7e6be..887dd37c5 100644
--- a/packages/server/src/rename-log.ts
+++ b/packages/server/src/rename-log.ts
@@ -750,11 +750,20 @@ function rewriteJsonlAtomically(shadowDir: string, index: RenameLogIndex): void
}
}
+export function pendingRenameLogEntries(index: RenameLogIndex): ReadonlySet<RenameLogEntry> {
+ const pending = new Set<RenameLogEntry>();
+ for (const entry of index.byTo.values()) {
+ if (entry.commitSha === '') pending.add(entry);
+ }
+ return pending;
+}
+
export function backfillRenameLogCommitSha(
shadowDir: string,
writerId: string,
commitSha: string,
index: RenameLogIndex,
+ claimable: ReadonlySet<RenameLogEntry>,
): { updated: number } {
if (!/^[0-9a-f]{40}$/.test(commitSha)) {
log.warn(
@@ -764,9 +773,10 @@ export function backfillRenameLogCommitSha(
return { updated: 0 };
}
let updated = 0;
- for (const entry of index.byTo.values()) {
+ for (const entry of claimable) {
if (entry.commitSha !== '') continue;
if (entry.actor.writerId !== writerId) continue;
+ if (index.byTo.get(entry.to) !== entry) continue;
entry.commitSha = commitSha;
updated += 1;
}
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 30101878f..5b48e0da1 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -2789,6 +2789,7 @@ export function createServer(options: ServerOptions): ServerInstance {
case 'update': {
const { docName, content: theirs } = event;
+ onUpstreamAdd(docName);
if (indexedMetadataChanged(event.previousIndexedFields, theirs, docName)) {
scheduleIndexRegeneration(docName);
}