Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdxindex 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 aA `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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): Persisconst 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): Persisconst 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): Persisbase: 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): Persisasync 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.tsindex 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) {