Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): write a renamed file's destination once (#2100)

Nick Gomez88bbec08201d
diff --git a/.changeset/rename-writes-destination-once.md b/.changeset/rename-writes-destination-once.md
new file mode 100644
index 000000000..04a80bb59
--- /dev/null
+++ b/.changeset/rename-writes-destination-once.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Renaming a file no longer rewrites the destination when the move already placed the final bytes there. A managed rename moves the file and then writes the reconciled content; previously that second write was unconditional, so a rename that did not change the file's content still wrote the destination twice. The rename spine now skips the rewrite when the reconciled content already matches what is on disk, so a no-content-change rename writes the destination exactly once. Renames that rewrite wiki-link references still write the destination twice — the move places the old bytes, then the link rewrite overwrites them — because that second write is doing real work.
diff --git a/packages/app/tests/integration/rename-write-amplification.test.ts b/packages/app/tests/integration/rename-write-amplification.test.ts
new file mode 100644
index 000000000..60e21be29
--- /dev/null
+++ b/packages/app/tests/integration/rename-write-amplification.test.ts
@@ -0,0 +1,196 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getMetrics, resetMetrics } from '@inkeep/open-knowledge-server';
+import { trace } from '@opentelemetry/api';
+import {
+ BasicTracerProvider,
+ InMemorySpanExporter,
+ type ReadableSpan,
+ SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import {
+ awaitFileWatcherIndexed,
+ createTestClient,
+ createTestServer,
+ getServerState,
+ pollUntil,
+ type TestServer,
+ wait,
+} from './test-harness';
+
+let spanExporter = new InMemorySpanExporter();
+let tracerProvider: BasicTracerProvider | null = null;
+
+beforeEach(() => {
+ trace.disable();
+ spanExporter = new InMemorySpanExporter();
+ tracerProvider = new BasicTracerProvider({
+ spanProcessors: [new SimpleSpanProcessor(spanExporter)],
+ });
+ trace.setGlobalTracerProvider(tracerProvider);
+});
+
+afterEach(async () => {
+ await tracerProvider?.shutdown();
+ trace.disable();
+ tracerProvider = null;
+});
+
+function destBasename(span: ReadableSpan): string {
+ const p = span.attributes?.['fs.path'];
+ if (typeof p !== 'string') return '';
+ return p.split('/').pop() ?? '';
+}
+
+function fullWritesTo(spans: ReadableSpan[], basename: string): ReadableSpan[] {
+ return spans.filter(
+ (s) =>
+ (s.name === 'fs.renameSync' || s.name === 'fs.writeFileSync' || s.name === 'fs.rename') &&
+ destBasename(s) === basename,
+ );
+}
+
+function countByOp(spans: ReadableSpan[]): Record<string, number> {
+ const out: Record<string, number> = {};
+ for (const s of spans) out[s.name] = (out[s.name] ?? 0) + 1;
+ return out;
+}
+
+async function renamePath(server: TestServer, fromPath: string, toPath: string): Promise<number> {
+ const res = await fetch(`${server.baseUrl}/api/rename-path`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ kind: 'file',
+ fromPath,
+ toPath,
+ agentId: 'agent-rename-amp',
+ agentName: 'RenameAmp',
+ }),
+ });
+ return res.status;
+}
+
+describe('rename write-amplification — no-content-change rename writes destination once', () => {
+ test('open provider, no self-link, no edit: destination written exactly once', async () => {
+ const server = await createTestServer({ debounce: 200, maxDebounce: 1000 });
+ let client: Awaited<ReturnType<typeof createTestClient>> | undefined;
+ try {
+ writeFileSync(join(server.contentDir, 'alpha.md'), '# Hello\n\nworld\n', 'utf-8');
+ await awaitFileWatcherIndexed(server, 'alpha');
+
+ client = await createTestClient(server.port, 'alpha');
+ await pollUntil(() => getServerState(server, 'alpha') !== null, 8000, 25);
+ await wait(700); // settle initial load/observers; NO edit performed
+
+ spanExporter.reset();
+ resetMetrics();
+
+ expect(await renamePath(server, 'alpha.md', 'bravo.md')).toBe(200);
+ await wait(2000); // post-rename reconcile window
+
+ const spans = spanExporter.getFinishedSpans();
+ const bWrites = fullWritesTo(spans, 'bravo.md');
+ console.log(
+ '[no-change] full writes to bravo.md =',
+ bWrites.length,
+ 'byOp =',
+ JSON.stringify(countByOp(bWrites)),
+ '| persistenceDiskWrites =',
+ getMetrics().persistenceDiskWrites,
+ );
+
+ expect(bWrites.length).toBe(1);
+ expect(getMetrics().persistenceDiskWrites).toBe(0);
+ } finally {
+ await client?.cleanup();
+ await server.cleanup();
+ }
+ }, 30_000);
+
+ test('no open provider (control), no edit: destination written exactly once', async () => {
+ const server = await createTestServer({ debounce: 200, maxDebounce: 1000 });
+ try {
+ writeFileSync(join(server.contentDir, 'gamma.md'), '# Hello\n\nworld\n', 'utf-8');
+ await awaitFileWatcherIndexed(server, 'gamma');
+ await wait(400); // deliberately no provider opened
+
+ spanExporter.reset();
+ resetMetrics();
+
+ expect(await renamePath(server, 'gamma.md', 'delta.md')).toBe(200);
+ await wait(2000);
+
+ const dWrites = fullWritesTo(spanExporter.getFinishedSpans(), 'delta.md');
+ console.log(
+ '[control] full writes to delta.md =',
+ dWrites.length,
+ 'byOp =',
+ JSON.stringify(countByOp(dWrites)),
+ );
+
+ expect(dWrites.length).toBe(1);
+ expect(getMetrics().persistenceDiskWrites).toBe(0);
+ } finally {
+ await server.cleanup();
+ }
+ }, 30_000);
+
+ test('content DOES change (self-link rewrite): destination ends with correct bytes', async () => {
+ const server = await createTestServer({ debounce: 200, maxDebounce: 1000 });
+ let client: Awaited<ReturnType<typeof createTestClient>> | undefined;
+ try {
+ writeFileSync(join(server.contentDir, 'alpha.md'), '# Self\n\nlink to [[alpha]]\n', 'utf-8');
+ await awaitFileWatcherIndexed(server, 'alpha');
+
+ client = await createTestClient(server.port, 'alpha');
+ await pollUntil(() => getServerState(server, 'alpha') !== null, 8000, 25);
+ await wait(700);
+
+ expect(await renamePath(server, 'alpha.md', 'bravo.md')).toBe(200);
+ await wait(2000);
+
+ const bravoFinal = readFileSync(join(server.contentDir, 'bravo.md'), 'utf-8');
+ console.log('[content-change] final bravo.md =', JSON.stringify(bravoFinal));
+ expect(bravoFinal).toContain('[[bravo]]');
+ expect(bravoFinal).not.toContain('[[alpha]]');
+ } finally {
+ await client?.cleanup();
+ await server.cleanup();
+ }
+ }, 30_000);
+
+ test('doc with backlinks: the renamed destination is written exactly once', async () => {
+ const server = await createTestServer({ debounce: 200, maxDebounce: 1000 });
+ try {
+ writeFileSync(join(server.contentDir, 'target.md'), '# Target\n\nbody\n', 'utf-8');
+ writeFileSync(join(server.contentDir, 'referrer.md'), '# Ref\n\nsee [[target]]\n', 'utf-8');
+ await awaitFileWatcherIndexed(server, 'target');
+ await awaitFileWatcherIndexed(server, 'referrer');
+ await wait(500);
+
+ spanExporter.reset();
+ resetMetrics();
+
+ expect(await renamePath(server, 'target.md', 'renamed.md')).toBe(200);
+ await wait(2000);
+
+ const spans = spanExporter.getFinishedSpans();
+ const renamedWrites = fullWritesTo(spans, 'renamed.md');
+ console.log(
+ '[backlinks] full writes to renamed.md =',
+ renamedWrites.length,
+ 'byOp =',
+ JSON.stringify(countByOp(renamedWrites)),
+ );
+
+ expect(renamedWrites.length).toBe(1);
+ expect(readFileSync(join(server.contentDir, 'referrer.md'), 'utf-8')).toContain(
+ '[[renamed]]',
+ );
+ } finally {
+ await server.cleanup();
+ }
+ }, 30_000);
+});
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index c110cc311..2dec9f57e 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -1571,6 +1571,12 @@ function createCaseOnlyRenameTempPath(sourcePath: string): string {
throw new Error('Unable to allocate temporary path for case-only rename');
}
+function writeFileIfContentDiffers(filePath: string, content: string): void {
+ const current = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : null;
+ if (current === content) return;
+ tracedWriteFileSync(filePath, content, 'utf-8');
+}
+
function renamePathOnDisk(sourcePath: string, destinationPath: string): void {
tracedMkdirSync(dirname(destinationPath), { recursive: true });
if (!pathsDifferOnlyByCase(sourcePath, destinationPath)) {
@@ -2205,7 +2211,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
const filePath = safeContentPath(toDocName, contentDir);
const liveContent = liveContents.get(fromDocName);
if (typeof liveContent === 'string') {
- tracedWriteFileSync(filePath, liveContent, 'utf-8');
+ writeFileIfContentDiffers(filePath, liveContent);
}
const finalContent =
@@ -2259,7 +2265,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
function writeManagedRenameDocumentToDisk(docName: string, markdown: string): void {
const filePath = resolveContentEntryPath(contentDir, 'file', docName);
tracedMkdirSync(dirname(filePath), { recursive: true });
- tracedWriteFileSync(filePath, markdown, 'utf-8');
+ writeFileIfContentDiffers(filePath, markdown);
registerWrite(filePath, contentHash(markdown));
setReconciledBase(docName, markdown);
@@ -2688,7 +2694,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
});
let rewrittenDocs: ManagedRenameRewrittenDoc[] = [];
await withManagedRenameRecovery(projectDir ?? contentDir, recoveryJournal, async () => {
- tracedWriteFileSync(sourcePath, sourceContent, 'utf-8');
+ writeFileIfContentDiffers(sourcePath, sourceContent);
registerWrite(sourcePath, contentHash(sourceContent));
const renamedWithGit = await renameTrackedPathInGit(