Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Save edits on re-created renamed doc names (PRD-9321, PRD-9329) (#6196)

Andrew Mikofalvyec38e7322bef
diff --git a/.changeset/reoccupied-doc-name-saves.md b/.changeset/reoccupied-doc-name-saves.md
new file mode 100644
index 000000000..881417b9d
--- /dev/null
+++ b/.changeset/reoccupied-doc-name-saves.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Edits to a page re-created at a path that was renamed, moved or removed outside the app are now saved to disk, instead of being reported as saved while only kept in memory. Agent writes to a path that is still gone now fail with a `doc-removed` error.
diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx
index 6d599f77e..0670e8f5b 100644
--- a/docs/content/reference/mcp.mdx
+++ b/docs/content/reference/mcp.mdx
@@ -122,7 +122,7 @@ A write that first detects the stale file during its final disk flush returns a
A `reconcile` conflict also carries a `reason`: `merged-with-markers`, `refused-conflict-markers`, `refused-no-base`, `refused-too-large`, `disk-markers`, or `stale-external-write`. On that last reason the compatibility field `conflictKind` is `stale-external-write`. Every other row uses `conflictKind: "git"`.
-A write to a document whose file has been deleted returns `urn:ok:error:doc-removed` (409): the edit reached collaborative state, but the disk write was refused rather than recreating the removed file. This is not retryable — the document is gone. Re-create it with `write` if you still want the content.
+A write to a document whose file was deleted, renamed or moved on disk returns `urn:ok:error:doc-removed` (409): the edit reached collaborative state, but the disk write was refused. Retrying the same write does not help, and the `detail` says which case applies. If the file was deleted, re-create the document with `write` if you still want the content. If it was renamed or moved outside the app, the `detail` names its new path: re-read the document there and re-apply your change. If a different file now sits at the old path and has not been loaded into the document, only a reload of that document from disk clears the refusal, so tell the user instead of retrying.
A write whose document path cannot be resolved inside the content directory returns `urn:ok:error:path-escape` (400): the edit reached collaborative state, but the disk write was refused. This covers a symlink cycle at the document's own path, a link resolving outside the content directory, and a link resolving into a `.git` folder, an OpenKnowledge config folder itself, or its machine-local state. It is not retryable — repair the path on disk before writing this content again.
diff --git a/packages/app/tests/integration/reoccupied-doc-name-persistence.test.ts b/packages/app/tests/integration/reoccupied-doc-name-persistence.test.ts
new file mode 100644
index 000000000..3a2a1685f
--- /dev/null
+++ b/packages/app/tests/integration/reoccupied-doc-name-persistence.test.ts
@@ -0,0 +1,290 @@
+import { execSync } from 'node:child_process';
+import {
+ mkdirSync,
+ mkdtempSync,
+ realpathSync,
+ renameSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ensureProjectGit } from '@inkeep/open-knowledge-server';
+import { afterEach, describe, expect, test } from 'vitest';
+import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';
+import { post } from './rename-rebinding.test-helper.ts';
+import {
+ awaitFileWatcherIndexed,
+ createInspectableServer,
+ createTestClient,
+ createTestServer,
+ pollUntil,
+ readTestDoc,
+ type TestClient,
+ type TestServer,
+} from './test-harness.ts';
+
+const BODY = [
+ '# Index',
+ '',
+ '| Name | Note |',
+ '| --- | --- |',
+ '| alpha | one |',
+ '| omega | two |',
+ '',
+].join('\n');
+
+const RECREATED_BODY = [
+ '# Index',
+ '',
+ '| Name | Note |',
+ '| --- | --- |',
+ '| recreated | new |',
+ '| omega | two |',
+ '',
+].join('\n');
+
+let server: TestServer | undefined;
+const clients: TestClient[] = [];
+const cleanups: Array<() => Promise<void> | void> = [];
+
+afterEach(async () => {
+ while (clients.length > 0)
+ await clients
+ .pop()
+ ?.cleanup()
+ .catch(() => {});
+ await server?.cleanup().catch(() => {});
+ server = undefined;
+ while (cleanups.length > 0) await cleanups.pop()?.();
+});
+
+async function startWithOpenDoc(
+ docName: string,
+ otherDocs: Record<string, string> = {},
+): Promise<TestServer> {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-reoccupied-name-'));
+ writeFileSync(join(dir, `${docName}.md`), BODY, 'utf-8');
+ for (const [name, body] of Object.entries(otherDocs)) {
+ writeFileSync(join(dir, `${name}.md`), body, 'utf-8');
+ }
+ const started = await createTestServer({ contentDir: dir });
+ await awaitFileWatcherIndexed(started, docName);
+ const client = await createTestClient(started.port, docName, { skipInvariantWatcher: true });
+ clients.push(client);
+ await pollUntil(() => client.ytext.toString().includes('| omega |'), 15_000);
+ return started;
+}
+
+function diskPath(docName: string): string {
+ if (!server) throw new Error('server not started');
+ return join(server.contentDir, `${docName}.md`);
+}
+
+function lifecycleStatus(docName: string): unknown {
+ return server?.instance.hocuspocus.documents.get(docName)?.getMap('lifecycle').get('status');
+}
+
+function residentSource(docName: string): string | undefined {
+ return server?.instance.hocuspocus.documents.get(docName)?.getText('source').toString();
+}
+
+async function renameAwayOnDisk(docName: string, movedTo: string): Promise<void> {
+ renameSync(diskPath(docName), diskPath(movedTo));
+ await pollUntil(() => lifecycleStatus(docName) === 'renamed', 30_000, 100, 'the rename freeze');
+}
+
+async function expectOnDisk(contentDir: string, docName: string, text: string): Promise<void> {
+ await pollUntil(
+ () => readTestDoc(contentDir, docName).includes(text),
+ 30_000,
+ 100,
+ `${docName}.md on disk to contain ${JSON.stringify(text)}`,
+ );
+}
+
+function writeAsAgent(port: number, docName: string, markdown: string) {
+ return post(port, '/api/agent-write-md', {
+ docName,
+ markdown,
+ position: 'replace',
+ agentId: 'reoccupied-name-test',
+ });
+}
+
+function insertRowBeforeOmega(port: number, docName: string, row: string) {
+ return post(port, '/api/agent-patch', {
+ docName,
+ find: '| omega |',
+ replace: `${row}\n| omega |`,
+ agentId: 'reoccupied-name-test',
+ });
+}
+
+function git(cwd: string, args: string): string {
+ return execSync(`git ${args}`, {
+ cwd,
+ env: {
+ ...process.env,
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_AUTHOR_NAME: 'test',
+ GIT_AUTHOR_EMAIL: '[email protected]',
+ GIT_COMMITTER_NAME: 'test',
+ GIT_COMMITTER_EMAIL: '[email protected]',
+ },
+ encoding: 'utf-8',
+ stdio: ['ignore', 'pipe', 'ignore'],
+ }).trim();
+}
+
+describe('a document name re-occupied after an on-disk rename keeps persisting edits', () => {
+ test('a file re-created on disk replaces the frozen content and takes agent edits (PRD-9321)', async () => {
+ server = await startWithOpenDoc('Index');
+
+ await renameAwayOnDisk('Index', 'Index-backup');
+ writeFileSync(diskPath('Index'), RECREATED_BODY, 'utf-8');
+ await pollUntil(
+ () => residentSource('Index') === RECREATED_BODY,
+ 30_000,
+ 100,
+ 'the re-created file to replace the frozen content',
+ );
+
+ const edit = await insertRowBeforeOmega(server.port, 'Index', '| after-recreate | b |');
+ expect(edit.status).toBe(200);
+ await expectOnDisk(server.contentDir, 'Index', '| after-recreate | b |');
+ expect(readTestDoc(server.contentDir, 'Index')).toContain('| recreated | new |');
+ }, 120_000);
+
+ test('a page re-created through create-page starts from its new file and persists edits (PRD-9329)', async () => {
+ server = await startWithOpenDoc('Post');
+
+ await renameAwayOnDisk('Post', 'Post-moved');
+ const created = await post(server.port, '/api/create-page', { path: 'Post.md' });
+ expect(created.status).toBeLessThan(300);
+ expect(residentSource('Post')).toBe('');
+
+ const write = await writeAsAgent(server.port, 'Post', '# Typed after re-create\n');
+ expect(write.status).toBe(200);
+ await expectOnDisk(server.contentDir, 'Post', '# Typed after re-create');
+ }, 120_000);
+
+ test('a managed rename onto the frozen name takes over that name and persists edits', async () => {
+ server = await startWithOpenDoc('Note', { Draft: RECREATED_BODY });
+
+ await renameAwayOnDisk('Note', 'Note-moved');
+ const renamed = await post(server.port, '/api/rename-path', {
+ kind: 'file',
+ fromPath: 'Draft.md',
+ toPath: 'Note.md',
+ });
+ expect(renamed.status).toBe(200);
+ await pollUntil(
+ () => residentSource('Note') === RECREATED_BODY,
+ 15_000,
+ 100,
+ 'the renamed file to replace the frozen content',
+ );
+
+ const edit = await insertRowBeforeOmega(server.port, 'Note', '| after-managed-rename | c |');
+ expect(edit.status).toBe(200);
+ await expectOnDisk(server.contentDir, 'Note', '| after-managed-rename | c |');
+ }, 120_000);
+
+ test('an agent write to a renamed-away name that is still absent is refused with its new path', async () => {
+ server = await startWithOpenDoc('Gone');
+
+ await renameAwayOnDisk('Gone', 'Gone-moved');
+
+ const write = await writeAsAgent(server.port, 'Gone', '# Written to the old name\n');
+ expect(write.status).toBe(409);
+ expect(write.body).toMatchObject({
+ type: 'urn:ok:error:doc-removed',
+ title: 'Edit applied in memory; disk write refused because the document was renamed.',
+ detail: expect.stringContaining('re-read the document at Gone-moved'),
+ });
+ expect(readTestDoc(server.contentDir, 'Gone')).toBe('');
+ }, 120_000);
+});
+
+describe('switching back to a branch that has a tombstoned document', () => {
+ test.runIf(process.platform !== 'win32')(
+ 'lets edits to that document reach disk again',
+ async () => {
+ const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-branch-switch-revive-')));
+ cleanups.push(() => rmSync(contentDir, { recursive: true, force: true }));
+ await ensureProjectGit(contentDir);
+ configureTestGitRepository(contentDir);
+ mkdirSync(join(contentDir, '.ok', 'local'), { recursive: true });
+ writeFileSync(join(contentDir, '.ok', 'local', 'private.md'), '# Private\n', 'utf-8');
+ writeFileSync(join(contentDir, 'note.md'), '# Note\n\nOn main.\n', 'utf-8');
+ writeFileSync(join(contentDir, 'other.md'), '# Other\n\nOn main.\n', 'utf-8');
+ git(contentDir, 'add note.md other.md');
+ git(contentDir, 'commit -m main');
+ git(contentDir, 'checkout -b feature');
+ git(contentDir, 'rm -q note.md');
+ symlinkSync('.ok/local/private.md', join(contentDir, 'note.md'));
+ writeFileSync(join(contentDir, 'other.md'), '# Other\n\nOn feature.\n', 'utf-8');
+ git(contentDir, 'add note.md other.md');
+ git(contentDir, 'commit -m feature');
+ git(contentDir, 'checkout main');
+
+ const inspectable = await createInspectableServer({
+ contentDir,
+ keepContentDir: true,
+ gitEnabled: true,
+ commitDebounceMs: 500,
+ });
+ cleanups.push(() => inspectable.shutdown());
+ const opened = new Map<string, TestClient>();
+ for (const docName of ['note', 'other']) {
+ const client = await createTestClient(inspectable.port, docName, {
+ skipInvariantWatcher: true,
+ });
+ clients.push(client);
+ opened.set(docName, client);
+ await pollUntil(() => client.ytext.toString().includes('On main.'), 10_000, 50);
+ }
+ const serverDoc = (docName: string) => inspectable.instance.hocuspocus.documents.get(docName);
+ const serverText = (docName: string): string =>
+ serverDoc(docName)?.getText('source').toString() ?? '';
+
+ git(contentDir, 'checkout feature');
+ const noteStatus = () => serverDoc('note')?.getMap('lifecycle').get('status');
+ await pollUntil(() => serverText('other').includes('On feature.'), 15_000, 50);
+ await pollUntil(() => noteStatus() === 'deleted-upstream', 15_000, 50, 'the tombstone');
+ const noteText = opened.get('note')?.ytext;
+ noteText?.insert(noteText.length, '\nTyped while tombstoned.\n');
+ await pollUntil(
+ () => serverText('note').includes('Typed while tombstoned.'),
+ 15_000,
+ 50,
+ 'the tombstoned edit to reach the server',
+ );
+
+ git(contentDir, 'checkout main');
+ await pollUntil(() => serverText('other').includes('On main.'), 15_000, 50);
+ await pollUntil(
+ () =>
+ !inspectable.instance.durabilityState.isBatchInProgress() &&
+ noteStatus() === undefined &&
+ serverText('note') === '# Note\n\nOn main.\n',
+ 15_000,
+ 50,
+ 'the branch switch to finish with note revived to its file content',
+ );
+ expect(readTestDoc(contentDir, 'note')).toBe('# Note\n\nOn main.\n');
+
+ const edit = await post(inspectable.port, '/api/agent-patch', {
+ docName: 'note',
+ find: 'On main.',
+ replace: 'Edited after switching back.',
+ agentId: 'reoccupied-name-test',
+ });
+ expect(edit.status).toBe(200);
+ await expectOnDisk(contentDir, 'note', 'Edited after switching back.');
+ },
+ 120_000,
+ );
+});
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index a3ba7550e..5cf92b54a 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -201,6 +201,7 @@ import {
isPersistenceExcludedDoc,
isSystemDoc,
} from './cc1-broadcast.ts';
+import type { RemovalLifecycleStatus } from './conflict-kinds.ts';
import {
isReservedProjectStatePath,
listManagedDocNamesUnderFolder,
@@ -232,6 +233,7 @@ import {
import {
type ReconcileBeforeWriteResult,
reconcileDiskBeforeAgentWrite,
+ reviveFrozenResidentDoc,
} from './external-change.ts';
import { extractActorIdentity } from './extract-actor-identity.ts';
import {
@@ -1406,11 +1408,28 @@ export interface CommentDocHooks {
}
function removedDocProblem(failure: StoreFailure) {
- return {
- type: 'urn:ok:error:doc-removed' as const,
- title: 'Edit applied in memory; disk write refused because the document is no longer on disk.',
- detail: `${failure.message}. Retrying will not help: re-create the document before writing this content again.`,
- } satisfies BatchEntryError;
+ switch (failure.removal?.kind) {
+ case 'path-occupied':
+ return {
+ type: 'urn:ok:error:doc-removed' as const,
+ title:
+ 'Edit applied in memory; disk write refused because the file now at this path is not loaded into the document.',
+ detail: `${failure.message}. Retrying will not help until the server reloads this document from disk, for example after Open Knowledge restarts; tell the user instead of retrying.`,
+ } satisfies BatchEntryError;
+ case 'renamed':
+ return {
+ type: 'urn:ok:error:doc-removed' as const,
+ title: 'Edit applied in memory; disk write refused because the document was renamed.',
+ detail: `${failure.message}. Retrying will not help: re-read the document at ${failure.removal.renamedTo} and re-apply your change there.`,
+ } satisfies BatchEntryError;
+ case undefined:
+ return {
+ type: 'urn:ok:error:doc-removed' as const,
+ title:
+ 'Edit applied in memory; disk write refused because the document is no longer on disk.',
+ detail: `${failure.message}. Retrying will not help: re-create the document before writing this content again.`,
+ } satisfies BatchEntryError;
+ }
}
function pathFaultProblem(failure: StoreFailure) {
@@ -2270,7 +2289,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
async function captureAndCloseDocuments(
docNames: string[],
- lifecycleStatus: 'deleted-upstream' | 'renamed',
+ lifecycleStatus: RemovalLifecycleStatus,
): Promise<Map<string, string>> {
const liveContents = new Map<string, string>();
@@ -2305,6 +2324,18 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
return liveContents;
}
+ function reviveFrozenResident(docName: string, content: string): void {
+ reviveFrozenResidentDoc(
+ durabilityState,
+ hocuspocus,
+ docName,
+ content,
+ options.resolveEmbed,
+ undefined,
+ getBridgeLossReporter?.(),
+ );
+ }
+
function syncRenamedDocsToDisk(
renamed: RenamedDocMapping[],
liveContents: ReadonlyMap<string, string>,
@@ -2325,6 +2356,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
if (typeof finalContent === 'string') {
registerWrite(filePath, contentHash(finalContent));
+ reviveFrozenResident(toDocName, finalContent);
}
}
}
diff --git a/packages/server/src/conflict-authority.ts b/packages/server/src/conflict-authority.ts
index 3328d7eb6..4d196aa02 100644
--- a/packages/server/src/conflict-authority.ts
+++ b/packages/server/src/conflict-authority.ts
@@ -13,6 +13,7 @@ import {
holdsMarkersOnDisk,
isConflictKind,
isReconcileReason,
+ isRemovalLifecycleStatus,
type LifecycleView,
type ReconcileReason,
type ResolveStrategy,
@@ -667,10 +668,10 @@ export class ConflictAuthority implements ConflictReader {
lifecycleOf(document: Y.Doc, docName: string): LifecycleView | null {
const map = document.getMap('lifecycle');
const status = map.get('status');
- if (status === 'deleted-upstream') return { status: 'deleted-upstream' };
- if (status === 'renamed') {
+ if (isRemovalLifecycleStatus(status)) {
+ if (status === 'deleted-upstream') return { status };
const newPath = map.get('newPath');
- return { status: 'renamed', newPath: typeof newPath === 'string' ? newPath : '' };
+ return { status, newPath: typeof newPath === 'string' ? newPath : '' };
}
const entry = this.byDocName.get(docName);
if (entry === undefined) return null;
diff --git a/packages/server/src/conflict-kinds.ts b/packages/server/src/conflict-kinds.ts
index 9caad0500..e595a4a64 100644
--- a/packages/server/src/conflict-kinds.ts
+++ b/packages/server/src/conflict-kinds.ts
@@ -66,6 +66,26 @@ type _ExhaustiveFreezingLifecycleStatus =
];
const _exhaustiveFreezingLifecycleStatus: _ExhaustiveFreezingLifecycleStatus = true;
+const REMOVAL_LIFECYCLE_STATUSES = [
+ 'deleted-upstream',
+ 'renamed',
+] as const satisfies readonly FreezingLifecycleStatus[];
+
+export type RemovalLifecycleStatus = (typeof REMOVAL_LIFECYCLE_STATUSES)[number];
+
+type _ExhaustiveRemovalLifecycleStatus =
+ Exclude<FreezingLifecycleStatus, RemovalLifecycleStatus | 'conflict'> extends never
+ ? true
+ : [
+ 'A freezing lifecycle status is neither a conflict nor a removal:',
+ Exclude<FreezingLifecycleStatus, RemovalLifecycleStatus | 'conflict'>,
+ ];
+const _exhaustiveRemovalLifecycleStatus: _ExhaustiveRemovalLifecycleStatus = true;
+
+export function isRemovalLifecycleStatus(value: unknown): value is RemovalLifecycleStatus {
+ return (REMOVAL_LIFECYCLE_STATUSES as readonly unknown[]).includes(value);
+}
+
export function isConflictKind(value: unknown): value is ConflictKind {
return (CONFLICT_KINDS as readonly unknown[]).includes(value);
}
diff --git a/packages/server/src/document-durability-state.ts b/packages/server/src/document-durability-state.ts
index 0e794de1a..d4df9d571 100644
--- a/packages/server/src/document-durability-state.ts
+++ b/packages/server/src/document-durability-state.ts
@@ -14,8 +14,13 @@ import { contentHash } from './version-hash.ts';
export interface StoreFailure {
code?: string;
message: string;
+ removal?: StoreFailureRemoval;
}
+export type StoreFailureRemoval =
+ | { kind: 'renamed'; renamedTo: string }
+ | { kind: 'path-occupied' };
+
export interface StoreAttemptToken {
readonly docName: string;
readonly generation: number;
diff --git a/packages/server/src/external-change.ts b/packages/server/src/external-change.ts
index 841bdfaa7..4a1021e4b 100644
--- a/packages/server/src/external-change.ts
+++ b/packages/server/src/external-change.ts
@@ -22,10 +22,11 @@ import {
isEditableTextDoc,
isExcalidrawDoc,
isMermaidDoc,
+ isPersistenceExcludedDoc,
isSystemDoc,
} from './cc1-broadcast.ts';
import { type ConflictAuthority, isDocInConflict } from './conflict-authority.ts';
-import type { ReconcileReason } from './conflict-kinds.ts';
+import { isRemovalLifecycleStatus, type ReconcileReason } from './conflict-kinds.ts';
import { safeContentPath } from './content-path.ts';
import { recordContributor } from './contributor-tracker.ts';
import { applyDiskContentToDoc, FILE_WATCHER_ORIGIN } from './disk-content-intake.ts';
@@ -142,6 +143,50 @@ export function applyExternalChange(
durabilityState.setReconciledBase(docName, content);
}
+export type FrozenResidentRevival = 'not-frozen' | 'revived' | 'failed';
+
+export function reviveFrozenResidentDoc(
+ durabilityState: DocumentDurabilityState,
+ hocuspocus: Hocuspocus,
+ docName: string,
+ content: string,
+ resolveEmbed?: (basename: string, sourcePath: string) => string | null,
+ resolveSize?: (basename: string, sourcePath: string) => number | null,
+ bridgeLossReporter?: BridgeDeriveLossReporter,
+): FrozenResidentRevival {
+ if (isPersistenceExcludedDoc(docName)) return 'not-frozen';
+ const resident = hocuspocus.documents.get(docName);
+ if (!resident) return 'not-frozen';
+ const lifecycle = resident.getMap('lifecycle');
+ const status = lifecycle.get('status');
+ if (!isRemovalLifecycleStatus(status)) return 'not-frozen';
+ const replacedInMemoryContent = resident.getText('source').toString() !== content;
+ try {
+ applyExternalChange(
+ durabilityState,
+ hocuspocus,
+ docName,
+ content,
+ resolveEmbed,
+ resolveSize,
+ bridgeLossReporter,
+ );
+ } catch (err) {
+ getLogger('reconcile').error(
+ { err: redactedErrorSummary(err), docName, status },
+ `[reconcile] could not revive ${docName}: it stays ${status} and keeps refusing stores until the server reloads it`,
+ );
+ return 'failed';
+ }
+ lifecycle.delete('status');
+ lifecycle.delete('newPath');
+ getLogger('reconcile').info(
+ { docName, status, replacedInMemoryContent },
+ `[reconcile] revived ${docName}: its name is occupied on disk again, so the ${status} freeze no longer applies`,
+ );
+ return 'revived';
+}
+
export function createExternalChangeHandler(
durabilityState: DocumentDurabilityState,
hocuspocus: Hocuspocus,
diff --git a/packages/server/src/http/folder-template-routes.ts b/packages/server/src/http/folder-template-routes.ts
index ba4a431d8..8c10d1713 100644
--- a/packages/server/src/http/folder-template-routes.ts
+++ b/packages/server/src/http/folder-template-routes.ts
@@ -32,6 +32,7 @@ import { composeAndWriteRawBody } from '../bridge-intake.ts';
import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
import type { ConflictAuthority } from '../conflict-authority.ts';
import { DocInConflictError, respondDocInConflict } from '../conflict-errors.ts';
+import type { RemovalLifecycleStatus } from '../conflict-kinds.ts';
import { enrichDirectory } from '../content/enrichment.ts';
import {
applyFolderFrontmatterPatch,
@@ -115,7 +116,7 @@ export interface FolderTemplateRouteDeps {
registerWrittenDocInFileIndex: (docName: string, content: string) => void;
captureAndCloseDocuments: (
docNames: string[],
- lifecycleStatus: 'deleted-upstream' | 'renamed',
+ lifecycleStatus: RemovalLifecycleStatus,
) => Promise<Map<string, string>>;
renameTrackedPathInGit: (
projectDir: string | undefined,
diff --git a/packages/server/src/http/skills-document-routes.ts b/packages/server/src/http/skills-document-routes.ts
index c2ca736de..a160a5ff6 100644
--- a/packages/server/src/http/skills-document-routes.ts
+++ b/packages/server/src/http/skills-document-routes.ts
@@ -37,6 +37,7 @@ import {
import type { AgentSessionManager } from '../agent-sessions.ts';
import { composeAndWriteRawBody } from '../bridge-intake.ts';
import { isLinkIndexExcludedDoc } from '../cc1-broadcast.ts';
+import type { RemovalLifecycleStatus } from '../conflict-kinds.ts';
import {
applySkillDelete,
applySkillDirNameSync,
@@ -179,7 +180,7 @@ export interface SkillsDocumentRouteDeps {
) => ReturnType<typeof extractActorIdentity>;
captureAndCloseDocuments: (
docNames: string[],
- lifecycleStatus: 'deleted-upstream' | 'renamed',
+ lifecycleStatus: RemovalLifecycleStatus,
) => Promise<Map<string, string>>;
log: PinoLogger;
commitOkArtifactWrite: (context: string) => Promise<unknown>;
diff --git a/packages/server/src/http/skills-file-routes.ts b/packages/server/src/http/skills-file-routes.ts
index 709372042..8814a16c4 100644
--- a/packages/server/src/http/skills-file-routes.ts
+++ b/packages/server/src/http/skills-file-routes.ts
@@ -16,6 +16,7 @@ import {
} from '@inkeep/open-knowledge-core';
import type { AgentSessionManager } from '../agent-sessions.ts';
import { composeAndWriteRawBody } from '../bridge-intake.ts';
+import type { RemovalLifecycleStatus } from '../conflict-kinds.ts';
import {
applySkillBundleFileDelete,
applySkillBundleFileRename,
@@ -113,7 +114,7 @@ export interface SkillsFileRouteDeps {
) => ReturnType<typeof extractActorIdentity>;
captureAndCloseDocuments: (
docNames: string[],
- lifecycleStatus: 'deleted-upstream' | 'renamed',
+ lifecycleStatus: RemovalLifecycleStatus,
) => Promise<Map<string, string>>;
log: PinoLogger;
commitOkArtifactWrite: (context: string) => Promise<unknown>;
diff --git a/packages/server/src/persistence-removed-doc-publish.test.ts b/packages/server/src/persistence-removed-doc-publish.test.ts
index 6a554035c..f548dfd76 100644
--- a/packages/server/src/persistence-removed-doc-publish.test.ts
+++ b/packages/server/src/persistence-removed-doc-publish.test.ts
@@ -425,4 +425,119 @@ describe('persistence publish guard — a removed document is never republished'
expect(readFileSync(docPath, 'utf-8')).toContain('pending edit');
});
+
+ describe('a document frozen as deleted or renamed', () => {
+ function freeze(status: 'deleted-upstream' | 'renamed', newPath?: string): void {
+ document.transact(() => {
+ const lifecycle = document.getMap('lifecycle');
+ lifecycle.set('status', status);
+ if (newPath !== undefined) lifecycle.set('newPath', newPath);
+ });
+ }
+
+ test('stays quiet when a skipped store drops nothing', async () => {
+ writeFileSync(docPath, SEEDED, 'utf-8');
+ const persistence = persistenceWith();
+ await loadFromDisk(persistence);
+ rmSync(docPath);
+ freeze('deleted-upstream');
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ await store(persistence);
+
+ expect(refusalEvents(warn)).toEqual([]);
+ expect(existsSync(docPath)).toBe(false);
+ });
+
+ test('counts and warns an editor edit dropped on a deleted document', async () => {
+ writeFileSync(docPath, SEEDED, 'utf-8');
+ const persistence = persistenceWith();
+ await loadFromDisk(persistence);
+ rmSync(docPath);
+ freeze('deleted-upstream');
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const before = getMetrics().persistenceStoreRemovedDocCount;
+
+ document.transact(() => appendUnflushedEdit(document), BROWSER_ORIGIN);
+ await store(persistence);
+
+ expect(existsSync(docPath)).toBe(false);
+ expect(getMetrics().persistenceStoreRemovedDocCount).toBe(before + 1);
+ expect(refusalEvents(warn).at(-1)?.reason).toBe('deleted-upstream');
+ expect(durabilityState.takeStoreFailure(docName)).toBeNull();
+ });
+
+ test('counts and warns an editor edit dropped on a renamed document that lost its base', async () => {
+ writeFileSync(docPath, SEEDED, 'utf-8');
+ const persistence = persistenceWith();
+ await loadFromDisk(persistence);
+ renameSync(docPath, join(tmpDir, 'renamed-doc.md'));
+ freeze('renamed', 'renamed-doc');
+ durabilityState.deleteReconciledBase(docName);
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ await store(persistence);
+ expect(refusalEvents(warn)).toEqual([]);
+
+ document.transact(() => appendUnflushedEdit(document), BROWSER_ORIGIN);
+ await store(persistence);
+
+ expect(refusalEvents(warn).at(-1)?.reason).toBe('renamed');
+ expect(existsSync(docPath)).toBe(false);
+ });
+
+ test('tells an agent write on a deleted document that the file is gone', async () => {
+ writeFileSync(docPath, SEEDED, 'utf-8');
+ const persistence = persistenceWith();
+ await loadFromDisk(persistence);
+ rmSync(docPath);
+ freeze('deleted-upstream');
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ document.transact(() => appendUnflushedEdit(document), BROWSER_ORIGIN);
+ durabilityState.markAgentWriteStore(docName);
+ await store(persistence);
+
+ const failure = durabilityState.takeStoreFailure(docName);
+ expect(failure?.code).toBe('OK_DOC_REMOVED');
+ expect(failure?.message).toContain('is no longer on disk');
+ expect(failure?.removal).toBeUndefined();
+ });
+
+ test('tells an agent write on a renamed document where it moved', async () => {
+ writeFileSync(docPath, SEEDED, 'utf-8');
+ const persistence = persistenceWith();
+ await loadFromDisk(persistence);
+ renameSync(docPath, join(tmpDir, 'renamed-doc.md'));
+ freeze('renamed', 'renamed-doc');
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ document.transact(() => appendUnflushedEdit(document), BROWSER_ORIGIN);
+ durabilityState.markAgentWriteStore(docName);
+ await store(persistence);
+
+ const failure = durabilityState.takeStoreFailure(docName);
+ expect(failure?.code).toBe('OK_DOC_REMOVED');
+ expect(failure?.removal).toEqual({ kind: 'renamed', renamedTo: 'renamed-doc' });
+ });
+
+ test('never points an agent at the moved file when a new file already sits at the old path', async () => {
+ writeFileSync(docPath, SEEDED, 'utf-8');
+ const persistence = persistenceWith();
+ await loadFromDisk(persistence);
+ renameSync(docPath, join(tmpDir, 'renamed-doc.md'));
+ writeFileSync(docPath, 'a new file\n', 'utf-8');
+ freeze('renamed', 'renamed-doc');
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ document.transact(() => appendUnflushedEdit(document), BROWSER_ORIGIN);
+ durabilityState.markAgentWriteStore(docName);
+ await store(persistence);
+
+ const failure = durabilityState.takeStoreFailure(docName);
+ expect(failure?.code).toBe('OK_DOC_REMOVED');
+ expect(failure?.removal).toEqual({ kind: 'path-occupied' });
+ expect(readFileSync(docPath, 'utf-8')).toBe('a new file\n');
+ });
+ });
});
diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.ts
index 3c2389ef5..fc60b4a46 100644
--- a/packages/server/src/persistence.ts
+++ b/packages/server/src/persistence.ts
@@ -43,7 +43,12 @@ import {
} from './cc1-broadcast.ts';
import { type ConfigPersistenceCtx, loadConfigDoc, storeConfigDoc } from './config-persistence.ts';
import type { ConflictAuthority } from './conflict-authority.ts';
-import type { FreezingLifecycleStatus, LifecycleView } from './conflict-kinds.ts';
+import {
+ type FreezingLifecycleStatus,
+ isRemovalLifecycleStatus,
+ type LifecycleView,
+ type RemovalLifecycleStatus,
+} from './conflict-kinds.ts';
import { isWithinContentDir, safeContentPath } from './content-path.ts';
import type { ContributorEntry } from './contributor-tracker.ts';
import {
@@ -67,6 +72,7 @@ import {
OK_PATH_UNRESOLVABLE,
OK_STORE_REFUSED,
type StoreFailure,
+ type StoreFailureRemoval,
} from './document-durability-state.ts';
import { refuseStaleExternalWrite } from './external-change.ts';
import { contentHash, registerWrite } from './file-watcher.ts';
@@ -426,7 +432,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
const view = options?.lifecycleOf?.(document, documentName);
if (view === undefined) {
const status = document.getMap('lifecycle').get('status');
- return status === 'deleted-upstream' || status === 'renamed' ? status : null;
+ return isRemovalLifecycleStatus(status) ? status : null;
}
return view === null ? null : view.status;
};
@@ -467,6 +473,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
const QUIESCENCE_MAX_DEFER = 8;
const persistenceDeferCounts = new Map<string, number>();
+ const frozenStoreBaselines = new Map<string, string>();
const gitEnabled = options?.gitEnabled ?? true;
const commitDebounceMs = options?.commitDebounceMs ?? 15_000;
@@ -1257,26 +1264,64 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
base: string | undefined,
candidate: string,
callerAwaitingFlush: boolean,
+ frozen?: { status: RemovalLifecycleStatus; removal: StoreFailureRemoval | undefined },
): void {
incrementPersistenceStoreRemovedDoc();
console.warn(
JSON.stringify({
event: 'persistence-store-removed-doc',
'doc.name': documentName,
- reason: options?.isRecentlyRemoved?.(documentName) ? 'recently-removed' : 'file-absent',
+ reason:
+ frozen?.status ??
+ (options?.isRecentlyRemoved?.(documentName) ? 'recently-removed' : 'file-absent'),
baseBytes: base?.length ?? null,
candidateBytes: candidate.length,
}),
);
if (callerAwaitingFlush) {
- durabilityState.recordStoreFailure(documentName, {
- code: OK_DOC_REMOVED,
- message: `${documentName} is no longer on disk, so the store was refused rather than recreating the removed file`,
- });
+ durabilityState.recordStoreFailure(
+ documentName,
+ frozen?.removal?.kind === 'path-occupied'
+ ? {
+ code: OK_DOC_REMOVED,
+ message: `${documentName} was ${frozen.status === 'renamed' ? 'renamed' : 'deleted'} on disk and the file now at its path has not been loaded into it, so the store was refused rather than overwriting that file`,
+ removal: frozen.removal,
+ }
+ : frozen?.removal?.kind === 'renamed'
+ ? {
+ code: OK_DOC_REMOVED,
+ message: `${documentName} was renamed to ${frozen.removal.renamedTo} on disk, so the store was refused rather than recreating the file under its old name`,
+ removal: frozen.removal,
+ }
+ : {
+ code: OK_DOC_REMOVED,
+ message: `${documentName} is no longer on disk, so the store was refused rather than recreating the removed file`,
+ },
+ );
}
persistenceDeferCounts.delete(documentName);
}
+ function frozenPathOccupied(documentName: string): boolean {
+ try {
+ return existsSync(safeContentPath(documentName, contentDir));
+ } catch {
+ return false;
+ }
+ }
+
+ function frozenRemovalOf(
+ document: Y.Doc,
+ documentName: string,
+ status: RemovalLifecycleStatus,
+ ): StoreFailureRemoval | undefined {
+ if (frozenPathOccupied(documentName)) return { kind: 'path-occupied' };
+ const newPath = document.getMap('lifecycle').get('newPath');
+ return status === 'renamed' && typeof newPath === 'string' && newPath !== ''
+ ? { kind: 'renamed', renamedTo: newPath }
+ : undefined;
+ }
+
function documentHadFileOnDisk(documentName: string, base: string | undefined): boolean {
return base !== undefined || docsWithFileObservedOnDisk.has(documentName);
}
@@ -1319,11 +1364,25 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
{ attributes: { 'doc.name': documentName } },
async () => {
const lifecycleStatus = frozenStatusOf(document, documentName);
+ if (!isRemovalLifecycleStatus(lifecycleStatus)) frozenStoreBaselines.delete(documentName);
if (lifecycleStatus !== null) {
log.info(
{ documentName, lifecycleStatus },
`[persistence] Skipped store for ${documentName}: lifecycle=${lifecycleStatus}`,
);
+ if (isRemovalLifecycleStatus(lifecycleStatus)) {
+ const callerAwaitingFlush = durabilityState.consumeAgentWriteStore(documentName);
+ const base = durabilityState.getReconciledBase(documentName);
+ const candidate = document.getText('source').toString();
+ const baseline = base ?? frozenStoreBaselines.get(documentName);
+ if (baseline === undefined) frozenStoreBaselines.set(documentName, candidate);
+ if (callerAwaitingFlush || (baseline !== undefined && candidate !== baseline)) {
+ refuseRemovedDocPublish(documentName, base, candidate, callerAwaitingFlush, {
+ status: lifecycleStatus,
+ removal: frozenRemovalOf(document, documentName, lifecycleStatus),
+ });
+ }
+ }
persistenceDeferCounts.delete(documentName);
tripwireResetFailedDocs.delete(documentName);
return;
@@ -2034,6 +2093,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
async onLoadDocument({ document, documentName, context: _context }) {
docsWithSettledWrite.delete(documentName);
docsWithFileObservedOnDisk.delete(documentName);
+ frozenStoreBaselines.delete(documentName);
if (isSystemDoc(documentName)) return;
if (isConfigDoc(documentName)) {
loadConfigDoc(document, documentName, configPersistenceCtx);
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index ed738d6b1..198fc9c67 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -74,7 +74,6 @@ import {
CC1Broadcaster,
isConfigDoc,
isManagedArtifactDoc,
- isPersistenceExcludedDoc,
isReservedForUserTree,
SYSTEM_DOC_NAME,
} from './cc1-broadcast.ts';
@@ -144,8 +143,10 @@ import {
import {
applyExternalChange,
FILE_WATCHER_ORIGIN,
+ type FrozenResidentRevival,
redactedErrorSummary,
refuseStaleExternalWrite,
+ reviveFrozenResidentDoc,
serializeYDocSource,
wireReasonForRefusal,
} from './external-change.ts';
@@ -2328,7 +2329,7 @@ export function createServer(options: ServerOptions): ServerInstance {
}
break;
case 'create':
- restoreRenamedDocumentOnCreate(event.docName, event.content);
+ reviveFrozenResident(event.docName, event.content);
scheduleIndexRegeneration(event.docName);
break;
case 'conflict':
@@ -2505,22 +2506,6 @@ export function createServer(options: ServerOptions): ServerInstance {
return serializeYDocSource(document);
}
- function restoreRenamedDocumentOnCreate(docName: string, content: string): void {
- if (isPersistenceExcludedDoc(docName)) return;
- const document = hocuspocus.documents.get(docName);
- if (!document) return;
- const lifecycle = document.getMap('lifecycle');
- if (lifecycle.get('status') !== 'renamed') return;
-
- document.transact(() => {
- applyDiskContentToDoc(document, content, resolveEmbed, docName, resolveSize);
- lifecycle.delete('status');
- lifecycle.delete('newPath');
- }, FILE_WATCHER_ORIGIN);
- setReconciledBase(docName, content);
- log.info({ docName }, `[reconcile] create: cleared stale renamed lifecycle on ${docName}`);
- }
-
const applyToDoc = (docName: string, content: string): void =>
applyExternalChange(
durabilityState,
@@ -2532,6 +2517,17 @@ export function createServer(options: ServerOptions): ServerInstance {
bridgeLossReporter,
);
+ const reviveFrozenResident = (docName: string, content: string): FrozenResidentRevival =>
+ reviveFrozenResidentDoc(
+ durabilityState,
+ hocuspocus,
+ docName,
+ content,
+ resolveEmbed,
+ resolveSize,
+ bridgeLossReporter,
+ );
+
const refreshLoadedEmbeds = (
needle: string,
context: { reason: 'startup' } | { reason: 'asset-event'; assetBasename: string },
@@ -2801,7 +2797,7 @@ export function createServer(options: ServerOptions): ServerInstance {
switch (event.kind) {
case 'create': {
log.info({ docName: event.docName }, `[reconcile] create: ${event.docName}`);
- restoreRenamedDocumentOnCreate(event.docName, event.content);
+ reviveFrozenResident(event.docName, event.content);
await derivedDocumentIndex.recordDiskUpsert(event.docName, event.content);
signalChannel('files');
scheduleIndexRegeneration(event.docName);
@@ -2829,6 +2825,10 @@ export function createServer(options: ServerOptions): ServerInstance {
await derivedDocumentIndex.recordDiskUpsert(docName, theirs);
return;
}
+ if (reviveFrozenResident(docName, theirs) !== 'not-frozen') {
+ await derivedDocumentIndex.recordDiskUpsert(docName, theirs);
+ return;
+ }
const base = getReconciledBase(docName);
const ours = serializeDoc(docName) ?? base ?? '';
@@ -3063,17 +3063,7 @@ export function createServer(options: ServerOptions): ServerInstance {
const document = hocuspocus.documents.get(oldDocName);
if (document && document !== loadedBeforeIndex) freezeAsRenamed(document);
- const resident = hocuspocus.documents.get(newDocName);
- if (resident && resident.getMap('lifecycle').get('status') === 'renamed') {
- const residentLifecycle = resident.getMap('lifecycle');
- residentLifecycle.delete('status');
- residentLifecycle.delete('newPath');
- applyToDoc(newDocName, content);
- log.info(
- { newDocName },
- `[reconcile] rename: cleared stale renamed lifecycle on ${newDocName}`,
- );
- }
+ reviveFrozenResident(newDocName, content);
await sessionManager.closeAllForDoc(oldDocName);
const closedConnections = document?.getConnectionsCount() ?? 0;
@@ -4574,7 +4564,15 @@ export function createServer(options: ServerOptions): ServerInstance {
rescueUnflushedEditsBeforeTeardown(docName, newBranch, 'branch-switch', true);
}
}
- applyToDoc(docName, diskContent);
+ const revival = reviveFrozenResident(docName, diskContent);
+ if (revival === 'failed') {
+ log.error(
+ { docName },
+ `[branch-switch] failed to reset ${docName}: it stays frozen`,
+ );
+ continue;
+ }
+ if (revival === 'not-frozen') applyToDoc(docName, diskContent);
setReconciledBase(docName, diskContent);
log.info({ docName }, `[branch-switch] reset: ${docName}`);
} catch (e) {