Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): make doc deletions durable (no resurrection) (#2416)
Nick Gomezdbde6417aee4
diff --git a/.changeset/delete-durability-no-resurrection.md b/.changeset/delete-durability-no-resurrection.mdnew file mode 100644index 000000000..69c38c787--- /dev/null+++ b/.changeset/delete-durability-no-resurrection.md@@ -0,0 +1,24 @@+---+"@inkeep/open-knowledge": patch+---++Deleted docs now stay deleted. Two long-standing gaps let a deleted or+renamed-away markdown file silently re-materialize on disk with its old+content:++- Deleting or renaming through the app, the HTTP API, or the MCP `delete`+ tool could race a pending autosave — the store fired after the file was+ removed and rewrote it at the old path (external `rm` was already+ protected; the in-app paths were not). Every teardown path now marks the+ doc as no-longer-tracking-disk before connections close, so late stores+ are suppressed instead of resurrecting the file.+- Deletions did not survive a server restart: every anti-resurrection+ guard was in-memory, so a browser tab (or any client) still holding the+ doc's cached state would be admitted after a restart and re-create the+ file — including files deleted while the server was stopped. Removals+ are now journaled durably under `.ok/local/`, reloaded at boot, and+ files that vanished during downtime are detected and tombstoned at the+ next start. Rename redirects for stale tabs also survive restarts now.++Re-creating a doc on purpose (new file at the same path, `create-page`,+agent writes) keeps working exactly as before.diff --git a/packages/app/tests/integration/delete-durability.test.ts b/packages/app/tests/integration/delete-durability.test.tsnew file mode 100644index 000000000..134463a39--- /dev/null+++ b/packages/app/tests/integration/delete-durability.test.ts@@ -0,0 +1,450 @@+/**+ * Delete/rename durability — a removed doc must STAY removed.+ *+ * Pins two invariants behind the field report of "resurrecting" docs+ * (deleted markdown files re-materializing on disk with their original+ * content):+ *+ * 1. Teardown-spine store suppression. The API delete/rename spine+ * (`captureAndCloseDocuments`) unloads the Y.Doc while a debounced+ * persistence store can still be pending. Hocuspocus force-flushes a+ * pending store when a doc's last connection closes and never cancels+ * an armed debounce timer on unload — so without a lifecycle tombstone+ * on the doc (the watcher's external-delete path sets one before+ * unloading; the API spine must too) that store fires against the+ * destroyed-but-readable Y.Doc and rewrites the file that was just+ * removed.+ * 2. Deletion durability across restart. Every anti-resurrection guard is+ * per-process; after a restart a client that still holds the doc's Yjs+ * state (a browser tab's y-indexeddb cache in production) union-syncs+ * full content into the fresh empty doc and persistence re-creates the+ * file — including for files deleted while the server was down.+ *+ * All tests drive real inputs through public interfaces (WS client edits,+ * HTTP API, real files on disk) and assert on the user-visible outcome+ * (on-disk file state). Per-test docNames via randomUUID (STOP rule).+ */++import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { existsSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';+import { setTimeout as wait } from 'node:timers/promises';+import { HocuspocusProvider } from '@hocuspocus/provider';+import { parseAuthRejectionWire } from '@inkeep/open-knowledge-server';+import * as Y from 'yjs';+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';+import {+ createRestartableServer,+ createTestClient,+ createTestServer,+ getServerState,+ type RestartableServer,+ type TestServer,+} from './test-harness';++/**+ * Assert a file stays absent for the whole watch window. Any appearance is+ * a resurrection — fail immediately with the elapsed time for diagnosis.+ */+async function assertStaysAbsent(filePath: string, windowMs: number): Promise<void> {+ const start = Date.now();+ while (Date.now() - start < windowMs) {+ if (existsSync(filePath)) {+ throw new Error(+ `file resurrected ${Date.now() - start}ms after removal: ${filePath}\n` ++ `content: ${JSON.stringify(readFileSync(filePath, 'utf-8').slice(0, 120))}`,+ );+ }+ await wait(100);+ }+}++async function writeMd(port: number, docName: string, markdown: string): Promise<void> {+ const res = await fetch(`http://127.0.0.1:${port}/api/agent-write-md`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ docName, markdown, position: 'replace' }),+ });+ if (!res.ok) throw new Error(`agent-write-md failed for ${docName}: ${res.status}`);+}++async function deletePath(port: number, path: string): Promise<number> {+ const res = await fetch(`http://127.0.0.1:${port}/api/delete-path`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ kind: 'file', path }),+ });+ return res.status;+}++async function renamePath(port: number, fromPath: string, toPath: string): Promise<number> {+ const res = await fetch(`http://127.0.0.1:${port}/api/rename-path`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ kind: 'file', fromPath, toPath }),+ });+ return res.status;+}++/** Connect a bare provider (stand-in for a browser tab) and wait for sync. */+async function connectBareClient(+ port: number,+ docName: string,+ doc: Y.Doc,+): Promise<HocuspocusProvider> {+ const provider = new HocuspocusProvider({+ url: `ws://127.0.0.1:${port}/collab`,+ name: docName,+ document: doc,+ });+ await new Promise<void>((resolve, reject) => {+ const timer = setTimeout(+ () => reject(new Error(`initial sync timed out for ${docName}`)),+ 10_000,+ );+ provider.on('synced', () => {+ clearTimeout(timer);+ resolve();+ });+ });+ return provider;+}++/**+ * Connect a bare provider expecting the removal guard to reject it; return+ * the typed rejection parsed from the wire reason. Fails when the connection+ * is unexpectedly admitted (synced) instead.+ */+async function expectAuthRejection(+ port: number,+ docName: string,+): Promise<ReturnType<typeof parseAuthRejectionWire>> {+ const doc = new Y.Doc();+ const provider = new HocuspocusProvider({+ url: `ws://127.0.0.1:${port}/collab`,+ name: docName,+ document: doc,+ });+ try {+ const reason = await new Promise<string>((resolve, reject) => {+ const timer = setTimeout(+ () => reject(new Error(`authenticationFailed did not fire for ${docName}`)),+ 15_000,+ );+ provider.on('authenticationFailed', (payload: { reason: string }) => {+ clearTimeout(timer);+ resolve(payload.reason);+ });+ provider.on('synced', () => {+ clearTimeout(timer);+ reject(new Error(`connection to ${docName} was unexpectedly admitted`));+ });+ });+ return parseAuthRejectionWire(reason);+ } finally {+ provider.destroy();+ doc.destroy();+ }+}++/**+ * Wait until the doc is quiescent (past the persistence quiescence gate)+ * while the wide store debounce is still pending — the window where a+ * teardown must suppress the armed store rather than rely on the+ * non-quiescence skip.+ */+async function waitIntoArmedQuiescentWindow(): Promise<void> {+ await wait(1200);+}++// ════════════════════════════════════════════════════════════════════════════+// Invariant 1 — teardown-spine store suppression (single server, wide+// debounce so a pending store is deterministically armed at teardown time)+// ════════════════════════════════════════════════════════════════════════════++describe('delete/rename durability — in-flight edit at teardown', () => {+ let server: TestServer;++ beforeAll(async () => {+ server = await createTestServer({ debounce: 2000, maxDebounce: 10_000 });+ }, HARNESS_BOOT_TIMEOUT_MS);++ afterAll(async () => {+ await server.cleanup();+ });++ /**+ * The delete flavor of the spine invariant. NOTE: the resurrecting write+ * races the handler's unlink — this harness rig consistently wins the+ * benign ordering (store write lands before the unlink), so on unfixed+ * code this test passes by rig timing rather than by suppression; the+ * production rig loses the race deterministically (field report + the+ * diagnosis repro against a real `ok start` server). The rename test+ * below pins the same spine contract deterministically in CI; this test+ * stands as the delete-flavor regression pin.+ *+ */+ test('API delete during an in-flight edit stays deleted', async () => {+ const docName = `del-armed-${crypto.randomUUID()}`;+ const filePath = join(server.contentDir, `${docName}.md`);+ await writeMd(server.port, docName, '# Victim\n\nbody\n');++ const client = await createTestClient(server.port, docName);+ try {+ // A real user edit through the WS path arms the debounced store.+ const marker = `edit-${crypto.randomUUID()}`;+ client.ytext.insert(client.ytext.length, `\n${marker}\n`);+ const armed = Date.now();+ while (true) {+ const state = getServerState(server, docName);+ if (state?.ytext.toString().includes(marker)) break;+ if (Date.now() - armed > 5000) throw new Error('server never received the edit');+ await wait(25);+ }+ await waitIntoArmedQuiescentWindow();++ // Delete while the store is still pending (debounce=2000ms).+ expect(await deletePath(server.port, docName)).toBe(200);+ expect(existsSync(filePath)).toBe(false);++ // The pending store must not rewrite the file — neither via the+ // last-connection-closed flush nor via the surviving debounce timer.+ await assertStaysAbsent(filePath, 3500);+ } finally {+ await client.cleanup();+ }+ }, 40_000);++ test('API rename during an in-flight edit does not resurrect the old path', async () => {+ const fromName = `ren-armed-${crypto.randomUUID()}`;+ const toName = `ren-armed-${crypto.randomUUID()}`;+ const fromPath = join(server.contentDir, `${fromName}.md`);+ const toPath = join(server.contentDir, `${toName}.md`);+ await writeMd(server.port, fromName, '# Migrant\n\nbody\n');++ const client = await createTestClient(server.port, fromName);+ try {+ const marker = `edit-${crypto.randomUUID()}`;+ client.ytext.insert(client.ytext.length, `\n${marker}\n`);+ const armed = Date.now();+ while (true) {+ const state = getServerState(server, fromName);+ if (state?.ytext.toString().includes(marker)) break;+ if (Date.now() - armed > 5000) throw new Error('server never received the edit');+ await wait(25);+ }+ await waitIntoArmedQuiescentWindow();++ expect(await renamePath(server.port, fromName, toName)).toBe(200);++ // The new path carries the doc (including the in-flight edit — the+ // spine snapshots live content); the old path must never come back.+ expect(existsSync(toPath)).toBe(true);+ expect(readFileSync(toPath, 'utf-8')).toContain(marker);+ await assertStaysAbsent(fromPath, 3500);+ } finally {+ await client.cleanup();+ }+ }, 40_000);+});++// ════════════════════════════════════════════════════════════════════════════+// Invariant 2 — deletion durability across restart (same-port restart with a+// live client holding the doc's full Yjs state, like a browser tab's IDB)+// ════════════════════════════════════════════════════════════════════════════++describe('delete durability — across server restart with a stale client', () => {+ test('API delete survives a restart when a stale client reconnects', async () => {+ let rs: RestartableServer = await createRestartableServer();+ const docName = `restart-del-${crypto.randomUUID()}`;+ const filePath = join(rs.contentDir, `${docName}.md`);+ const marker = `cached-${crypto.randomUUID()}`;+ await writeMd(rs.port, docName, `# Cached\n\n${marker}\n`);++ const clientDoc = new Y.Doc();+ const provider = await connectBareClient(rs.port, docName, clientDoc);+ try {+ expect(clientDoc.getText('source').toString()).toContain(marker);++ expect(await deletePath(rs.port, docName)).toBe(200);+ expect(existsSync(filePath)).toBe(false);++ // Restart on the same port. The client keeps its Y.Doc (full content)+ // and auto-reconnects — production shape: a browser tab whose+ // y-indexeddb cache holds the deleted doc.+ rs = await rs.killAndRestartOnSamePort({ downtimeMs: 800 });++ // The deletion must hold: the reconnecting client's cached state must+ // not be admitted as a first write that re-creates the file.+ await assertStaysAbsent(filePath, 6000);+ } finally {+ provider.destroy();+ clientDoc.destroy();+ await rs.shutdown();+ }+ }, 60_000);++ /**+ * A journaled rename-redirect must survive the boot deleted-while-down+ * inference — never get downgraded to a hard delete. The stale state this+ * constructs is real: watcher-observed renames persist the backlink cache+ * on a debounced save (API renames save directly), so a rename landing+ * inside the debounce window before a shutdown leaves the persisted cache+ * still holding the OLD docName while the removal journal (flushed+ * synchronously on destroy) correctly holds `renamed`. At the next boot+ * the inference sees the old name as "gone from disk"; it must not+ * clobber the strictly-more-informative journaled redirect (mirror of the+ * watcher unpaired-delete peek-guard). The test reproduces the window+ * deterministically by restoring the server-authored pre-rename cache+ * bytes after shutdown — byte-identical to what the un-flushed debounce+ * leaves behind.+ *+ */+ test('journaled rename-redirect survives the boot deleted-while-down inference (no downgrade to doc-deleted)', async () => {+ const contentDirHolder: { dir: string | null } = { dir: null };+ let rs: RestartableServer | null = await createRestartableServer({ keepContentDir: true });+ contentDirHolder.dir = rs.contentDir;+ const oldName = `pre-restart-ren-${crypto.randomUUID()}`;+ const newName = `pre-restart-ren-${crypto.randomUUID()}`;+ try {+ await writeMd(rs.port, oldName, '# Migrant\n\nbody\n');++ // Steady state: the persisted backlink cache knows the OLD name.+ const cachePath = join(rs.contentDir, '.ok', 'local', 'cache', 'main', 'backlinks.json');+ const cacheDeadline = Date.now() + 10_000;+ while (true) {+ if (existsSync(cachePath) && readFileSync(cachePath, 'utf-8').includes(oldName)) break;+ if (Date.now() > cacheDeadline) throw new Error('backlink cache never persisted the doc');+ await wait(100);+ }+ const staleCacheBytes = readFileSync(cachePath);++ // Rename (journals `renamed`; destroy flushes it), shut down, then+ // restore the pre-rename cache bytes — the on-disk state a rename+ // inside the debounced-save window leaves behind.+ expect(await renamePath(rs.port, oldName, newName)).toBe(200);+ const port = rs.port;+ await rs.shutdown();+ rs = null;+ writeFileSync(cachePath, staleCacheBytes);++ rs = await createRestartableServer({+ contentDir: contentDirHolder.dir,+ keepContentDir: true,+ port,+ });++ // The old path stays gone and a stale tab is redirected — not+ // hard-rejected. Exercise the FULL WS dispatch chain (a real provider+ // connect) and assert on the typed rejection fields.+ expect(existsSync(join(rs.contentDir, `${oldName}.md`))).toBe(false);+ expect(existsSync(join(rs.contentDir, `${newName}.md`))).toBe(true);++ const rejection = await expectAuthRejection(rs.port, oldName);+ expect(rejection.kind).toBe('rename-redirect');+ expect(rejection.payload).toBe(newName);+ } finally {+ if (rs) await rs.shutdown();+ if (contentDirHolder.dir) rmSync(contentDirHolder.dir, { recursive: true, force: true });+ }+ }, 60_000);++ /**+ * The inverse boot case: a file RE-CREATED at a removed docName while the+ * server was down means the durable tombstone is stale — disk is truth at+ * boot. Without the origin-existence sweep, the journaled rename-redirect+ * would misdirect connections away from a doc whose file exists.+ *+ */+ test('a doc re-created at the old path while the server was down is admitted after boot', async () => {+ const contentDirHolder: { dir: string | null } = { dir: null };+ let rs: RestartableServer | null = await createRestartableServer({ keepContentDir: true });+ contentDirHolder.dir = rs.contentDir;+ const oldName = `downtime-recreate-${crypto.randomUUID()}`;+ const newName = `downtime-recreate-${crypto.randomUUID()}`;+ const recreatedMarker = `recreated-${crypto.randomUUID()}`;+ try {+ await writeMd(rs.port, oldName, '# Original\n\nbody\n');+ // Rename journals the redirect; destroy flushes it durably.+ expect(await renamePath(rs.port, oldName, newName)).toBe(200);+ const port = rs.port;+ await rs.shutdown();+ rs = null;++ // While the server is down, the user re-creates a file at the OLD path.+ writeFileSync(+ join(contentDirHolder.dir, `${oldName}.md`),+ `# Recreated\n\n${recreatedMarker}\n`,+ );++ rs = await createRestartableServer({+ contentDir: contentDirHolder.dir,+ keepContentDir: true,+ port,+ });++ // The re-created doc must be reachable — a real client connects, is+ // admitted, and syncs the re-created content (no stale redirect).+ const clientDoc = new Y.Doc();+ const provider = await connectBareClient(rs.port, oldName, clientDoc);+ try {+ const deadline = Date.now() + 10_000;+ while (!clientDoc.getText('source').toString().includes(recreatedMarker)) {+ if (Date.now() > deadline)+ throw new Error('admitted client never saw re-created content');+ await wait(100);+ }+ } finally {+ provider.destroy();+ clientDoc.destroy();+ }+ } finally {+ if (rs) await rs.shutdown();+ if (contentDirHolder.dir) rmSync(contentDirHolder.dir, { recursive: true, force: true });+ }+ }, 60_000);++ test('external rm during downtime survives the next start when a stale client reconnects', async () => {+ let rs: RestartableServer = await createRestartableServer();+ const docName = `downtime-del-${crypto.randomUUID()}`;+ const filePath = join(rs.contentDir, `${docName}.md`);+ const marker = `cached-${crypto.randomUUID()}`;+ await writeMd(rs.port, docName, `# Cached\n\n${marker}\n`);++ const clientDoc = new Y.Doc();+ const provider = await connectBareClient(rs.port, docName, clientDoc);+ try {+ expect(clientDoc.getText('source').toString()).toContain(marker);++ // Steady-state precondition: the deleted-while-down inference reads+ // the persisted backlink cache as the last-known doc set, and the+ // cache save is debounced — wait for the doc to land in the persisted+ // cache (as it long since has for any real deployment) before+ // crashing.+ const cachePath = join(rs.contentDir, '.ok', 'local', 'cache', 'main', 'backlinks.json');+ const cacheDeadline = Date.now() + 10_000;+ while (true) {+ if (existsSync(cachePath) && readFileSync(cachePath, 'utf-8').includes(docName)) break;+ if (Date.now() > cacheDeadline) {+ throw new Error('backlink cache never persisted the doc');+ }+ await wait(100);+ }++ // Crash the server, delete the file while it is DOWN (the server+ // never observes the unlink), then restart on the same port.+ const restarting = rs.killAndRestartOnSamePort({ downtimeMs: 900 });+ await wait(250);+ unlinkSync(filePath);+ rs = await restarting;++ // The deletion performed during downtime must hold across the boot:+ // the reconnecting client's cached state must not re-create the file.+ await assertStaysAbsent(filePath, 6000);+ } finally {+ provider.destroy();+ clientDoc.destroy();+ await rs.shutdown();+ }+ }, 60_000);+});diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex 4d2af0b6d..6f3e69974 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -3462,7 +3462,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {};}- async function captureAndCloseDocuments(docNames: string[]): Promise<Map<string, string>> {+ async function captureAndCloseDocuments(+ docNames: string[],+ lifecycleStatus: 'deleted-upstream' | 'renamed',+ ): Promise<Map<string, string>> {const liveContents = new Map<string, string>();for (const docName of docNames) {@@ -3472,6 +3475,22 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {}}+ // Mark every loaded doc as no-longer-tracking-disk BEFORE any teardown.+ // Ordering is load-bearing: closing a doc's last connection makes+ // Hocuspocus force-flush a pending debounced store (and unload never+ // cancels an armed debounce timer, nor does the delete purge+ // deferred-store or straggler agent-session stores) — each of those+ // late stores serializes the still-populated Y.Doc and rewrites the+ // path this teardown is about to remove. `storeDocumentNow`'s+ // lifecycle guard skips them all once the marker is set; the raw+ // Y.Map set (no transact) mirrors the watcher reconcile's sibling+ // convention in server-factory.ts.+ for (const docName of docNames) {+ const document = hocuspocus.documents.get(docName);+ if (!document) continue;+ document.getMap('lifecycle').set('status', lifecycleStatus);+ }+for (const docName of docNames) {await sessionManager.closeAllForDoc(docName).catch((err) => {console.warn(`[file-ops] Failed to close agent session for ${docName}:`, err);@@ -4000,7 +4019,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {if (recentlyRemovedDocs && !isSystemDoc(sourceDocName) && !isConfigDoc(sourceDocName)) {recentlyRemovedDocs.setDeleted(sourceDocName);}- const liveContents = await captureAndCloseDocuments([sourceDocName]);+ const liveContents = await captureAndCloseDocuments([sourceDocName], 'renamed');const liveContent = liveContents.get(sourceDocName);const sourceContent =typeof liveContent === 'string' ? liveContent : readFileSync(sourcePath, 'utf-8');@@ -4398,7 +4417,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {renameFolderIndexEntries(fromPath, toPath);}- const liveContents = await captureAndCloseDocuments([...renameMap.keys()]);+ const liveContents = await captureAndCloseDocuments([...renameMap.keys()], 'renamed');// Test-only crash-injection seam. Production builds with// NODE_ENV !== 'test' AND OK_TEST_RENAME_FAULT unset elide the@@ -10268,7 +10287,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {}}- await captureAndCloseDocuments(deletedDocNames);+ await captureAndCloseDocuments(deletedDocNames, 'deleted-upstream');// Populate the per-process LRU cache BEFORE the disk delete so any// connection that observes the file gone via the watcher also sees the@@ -10448,7 +10467,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {return;}- await captureAndCloseDocuments(deletedDocNames);+ await captureAndCloseDocuments(deletedDocNames, 'deleted-upstream');if (recentlyRemovedDocs) {for (const docName of deletedDocNames) {@@ -13543,7 +13562,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// file, so the managed-artifact persistence branch can't re-store// (resurrect) it on a later unload. Same spine doc-delete + skill-delete// use; no-op when the doc was never opened.- await captureAndCloseDocuments([templateDocNameFor(validated.folderRel, name)]);+ await captureAndCloseDocuments(+ [templateDocNameFor(validated.folderRel, name)],+ 'deleted-upstream',+ );const deleteInput: Parameters<typeof applyTemplateDelete>[0] = {projectDir: validated.resolvedContentDir,@@ -13629,9 +13651,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// Tear down the live source `__template__` doc (if open) BEFORE the// git-mv relocates the file — otherwise its persistence branch would// re-store at the now-stale from-path, resurrecting the moved template.- await captureAndCloseDocuments([- templateDocNameFor(fromValidated.folderRel, body.fromName),- ]);+ await captureAndCloseDocuments(+ [templateDocNameFor(fromValidated.folderRel, body.fromName)],+ 'renamed',+ );const result = await applyTemplateMove({projectDir: fromValidated.resolvedContentDir,@@ -14309,7 +14332,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// NOT `__skill__/project/<name>` — closing the wrong doc leaves the open// content doc to resurrect the just-deleted source, which is what made// the project↔global round-trip drop the skill. No-op when unopened.- await captureAndCloseDocuments([skillLiveDocName(scope, name)]);+ await captureAndCloseDocuments([skillLiveDocName(scope, name)], 'deleted-upstream');const result = applySkillDelete({ skillsRoot, name });if (!result.ok) {@@ -14388,7 +14411,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// the now-stale fromName path, resurrecting the moved-away skill. Project// skills are content docs, not `__skill__/project/<name>`. The// destination doc loads fresh from disk on next open.- await captureAndCloseDocuments([skillLiveDocName(body.scope, body.fromName)]);+ await captureAndCloseDocuments([skillLiveDocName(body.scope, body.fromName)], 'renamed');const result = await applySkillMove({skillsRoot,@@ -14978,7 +15001,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// A project `.md` reference is a live content doc — tear it down BEFORE// removing the file so its persistence branch can't resurrect it.if (isProjectMdReference(scope, kind, rel)) {- await captureAndCloseDocuments([projectRefContentDocName(name, rel)]);+ await captureAndCloseDocuments([projectRefContentDocName(name, rel)], 'deleted-upstream');}const result = applySkillBundleFileDelete({ skillsRoot, name, relPath: rel });diff --git a/packages/server/src/backlink-index.test.ts b/packages/server/src/backlink-index.test.tsindex 387edd5b9..7fb5dc2b0 100644--- a/packages/server/src/backlink-index.test.ts+++ b/packages/server/src/backlink-index.test.ts@@ -1307,7 +1307,7 @@ describe('reconcileWithDisk', () => {const reloaded = new BacklinkIndex({ projectDir, contentDir });expect(await reloaded.loadFromDisk()).toBe(true);const diff = await reloaded.reconcileWithDisk();- expect(diff).toEqual({ added: 0, updated: 0, deleted: 0 });+ expect(diff).toEqual({ added: 0, updated: 0, deleted: 0, deletedDocNames: [] });// Backlinks should still be intact after a no-op reconcile.expect(reloaded.getBacklinks('beta')).toEqual([@@ -1377,6 +1377,9 @@ describe('reconcileWithDisk', () => {const diff = await reloaded.reconcileWithDisk();expect(diff.added).toBe(1);expect(diff.deleted).toBe(1);+ // The deleted-while-down doc is surfaced by name so boot can arm the+ // removal guard against stale-client resurrection.+ expect(diff.deletedDocNames).toEqual(['beta']);// gamma was indexed and links to alphaexpect(reloaded.getBacklinks('alpha')).toEqual([diff --git a/packages/server/src/backlink-index.ts b/packages/server/src/backlink-index.tsindex 19c080e9d..0966fb257 100644--- a/packages/server/src/backlink-index.ts+++ b/packages/server/src/backlink-index.ts@@ -1774,8 +1774,18 @@ export class BacklinkIndex {added: number;updated: number;deleted: number;+ /**+ * DocNames dropped because their file is gone from disk (global skill+ * bundle nodes excluded — they live outside contentDir). Includes docs+ * known only via graph keys, not just the mtime snapshot: docs created+ * since the last full rebuild/reconcile have graph entries but no+ * snapshot entry. Feeds the boot-time deleted-while-down tombstoning,+ * which applies its own doc-kind filters at the populate site.+ */+ deletedDocNames: string[];}> {- if (!existsSync(this.contentDir)) return { added: 0, updated: 0, deleted: 0 };+ if (!existsSync(this.contentDir))+ return { added: 0, updated: 0, deleted: 0, deletedDocNames: [] };const storedMtimes = this.mtimesByBranch.get(branch) ?? new Map<string, number>();const rawDocs: Array<{ docName: string; filePath: string }> = [];@@ -1846,6 +1856,7 @@ export class BacklinkIndex {// upgrade path where storedMtimes is empty but the loaded graph state may// still hold entries for since-deleted files.let deleted = 0;+ const deletedDocNames: string[] = [];const allKnownDocs = new Set([...storedMtimes.keys(), ...this.getState(branch).forward.keys()]);for (const docName of allKnownDocs) {// Global skill bundle nodes live OUTSIDE contentDir and are owned by the@@ -1855,11 +1866,12 @@ export class BacklinkIndex {if (!currentDocSet.has(docName)) {this.deleteDocument(docName, branch);deleted++;+ deletedDocNames.push(docName);}}this.mtimesByBranch.set(branch, newMtimes);- return { added, updated, deleted };+ return { added, updated, deleted, deletedDocNames };}/**diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.tsindex 4431c0dcb..429c69e08 100644--- a/packages/server/src/metrics.ts+++ b/packages/server/src/metrics.ts@@ -22,6 +22,8 @@ export interface ReconciliationMetrics {conflictCount: number;batchCount: number;upstreamImportCount: number;+ /** Stores that wrote a doc the removal cache still records as removed. */+ persistenceStoreRemovedDocCount: number;rescueBufferCount: number;branchSwitchCount: number;parkCount: number;@@ -363,6 +365,7 @@ const counters: ReconciliationMetrics = {conflictCount: 0,batchCount: 0,upstreamImportCount: 0,+ persistenceStoreRemovedDocCount: 0,rescueBufferCount: 0,branchSwitchCount: 0,parkCount: 0,@@ -433,6 +436,10 @@ export function incrementUpstreamImport(): void {counters.upstreamImportCount++;}+export function incrementPersistenceStoreRemovedDoc(): void {+ counters.persistenceStoreRemovedDocCount++;+}+export function incrementRescueBuffer(): void {counters.rescueBufferCount++;}@@ -710,6 +717,7 @@ export function resetMetrics(): void {counters.conflictCount = 0;counters.batchCount = 0;counters.upstreamImportCount = 0;+ counters.persistenceStoreRemovedDocCount = 0;counters.rescueBufferCount = 0;counters.branchSwitchCount = 0;counters.parkCount = 0;diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.tsindex cd16b1ede..2e235b73e 100644--- a/packages/server/src/persistence.ts+++ b/packages/server/src/persistence.ts@@ -77,6 +77,7 @@ import {incrementPersistenceReconciliationFailures,incrementPersistenceSanityCheckSerializeFailures,incrementPersistenceSkipNonQuiescent,+ incrementPersistenceStoreRemovedDoc,} from './metrics.ts';import { isWithinDir, toPosix } from './path-utils.ts';import { classifyDuplication } from './persistence-tripwire.ts';@@ -365,6 +366,14 @@ export interface PersistenceOptions {* without coupling the test contract to the function's stack frame).*/mdManager?: MarkdownManager;+ /**+ * Probe into the removal cache (`RecentlyRemovedDocs`). Diagnostic only:+ * when a store is about to write a doc the cache still records as+ * removed, the write is logged + counted so a resurrection is visible in+ * logs instead of being silently re-adopted as a self-write. Enforcement+ * stays with the lifecycle guard + the removal-redirect auth guard.+ */+ isRecentlyRemoved?: (docName: string) => boolean;/*** No-project ephemeral single-file mode (the `ok <file>` open). When `true`,* the `onStoreDocument` no-op gate ALSO suppresses a write whose normalized@@ -1782,6 +1791,16 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis}}+ if (options?.isRecentlyRemoved?.(documentName)) {+ incrementPersistenceStoreRemovedDoc();+ console.warn(+ JSON.stringify({+ event: 'persistence-store-removed-doc',+ 'doc.name': documentName,+ }),+ );+ }+const tmpPath = `${canonicalPath}.tmp.${crypto.randomUUID()}`;try {// Test-only fault-injection seam. Production builds withdiff --git a/packages/server/src/recently-removed-docs.ts b/packages/server/src/recently-removed-docs.tsindex bd62c7996..619c7ea34 100644--- a/packages/server/src/recently-removed-docs.ts+++ b/packages/server/src/recently-removed-docs.ts@@ -36,6 +36,14 @@ export interface RecentlyRemovedDocsHooks {onEviction?: () => void;/** Called after every set / delete with the post-mutation `size`. */onSizeChange?: (size: number) => void;+ /**+ * Called after every mutation that changed the entry set (set, delete,+ * eviction — never `get` promotion). Single wiring point for the durable+ * removal journal: every populate/invalidate site (rename spine, delete+ * handler, watcher reconcile, watcher-add invalidation, auth-guard+ * self-heal) is covered here without scattering persistence calls.+ */+ onMutate?: () => void;/** Injected for tests; defaults to `Date.now`. */now?: () => number;}@@ -45,12 +53,14 @@ export class RecentlyRemovedDocs {private readonly capacity: number;private readonly onEviction: (() => void) | undefined;private readonly onSizeChange: ((size: number) => void) | undefined;+ private readonly onMutate: (() => void) | undefined;private readonly now: () => number;constructor(capacity: number = DEFAULT_CAPACITY, hooks: RecentlyRemovedDocsHooks = {}) {this.capacity = Math.max(0, Math.floor(capacity));this.onEviction = hooks.onEviction;this.onSizeChange = hooks.onSizeChange;+ this.onMutate = hooks.onMutate;this.now = hooks.now ?? Date.now;}@@ -97,6 +107,7 @@ export class RecentlyRemovedDocs {delete(docName: string): void {if (this.map.delete(docName)) {this.onSizeChange?.(this.map.size);+ this.onMutate?.();}}@@ -104,6 +115,22 @@ export class RecentlyRemovedDocs {return this.map.size;}+ /**+ * Snapshot of all entries in insertion (LRU → MRU) order. Consumed by the+ * removal-journal writer; does not promote.+ */+ entries(): Array<[string, RemovalEntry]> {+ return [...this.map.entries()];+ }++ /**+ * Re-insert a previously-recorded entry verbatim (journal reload) —+ * unlike `setDeleted`/`setRenamed`, preserves the original `addedAt`.+ */+ restore(docName: string, entry: RemovalEntry): void {+ this.put(docName, entry);+ }+private put(docName: string, entry: RemovalEntry): void {// Capacity 0 means caching is disabled — accept and immediately drop so// hooks remain consistent (size always 0, no entries reachable).@@ -120,5 +147,6 @@ export class RecentlyRemovedDocs {this.onEviction?.();}this.onSizeChange?.(this.map.size);+ this.onMutate?.();}}diff --git a/packages/server/src/removed-docs-journal.test.ts b/packages/server/src/removed-docs-journal.test.tsnew file mode 100644index 000000000..0226263c7--- /dev/null+++ b/packages/server/src/removed-docs-journal.test.ts@@ -0,0 +1,110 @@+import { describe, expect, test } from 'bun:test';+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { dirname, join } from 'node:path';+import { RecentlyRemovedDocs } from './recently-removed-docs.ts';+import {+ loadRemovedDocsJournal,+ removedDocsJournalPath,+ saveRemovedDocsJournal,+} from './removed-docs-journal.ts';++function makeProjectDir(): string {+ return mkdtempSync(join(tmpdir(), 'ok-removed-docs-journal-'));+}++describe('removed-docs journal — round trip', () => {+ test('save + load preserves entries, kinds, targets, timestamps, and order', () => {+ const projectDir = makeProjectDir();+ const cache = new RecentlyRemovedDocs(10, { now: () => 1111 });+ cache.setDeleted('notes/gone');+ cache.setRenamed('old-name', 'new-name');++ saveRemovedDocsJournal(projectDir, cache.entries());+ const loaded = loadRemovedDocsJournal(projectDir);++ expect(loaded).toEqual([+ ['notes/gone', { kind: 'deleted', addedAt: 1111 }],+ ['old-name', { kind: 'renamed', newDocName: 'new-name', addedAt: 1111 }],+ ]);+ });++ test('restore() re-populates a cache verbatim (addedAt preserved, unlike setDeleted)', () => {+ const projectDir = makeProjectDir();+ const original = new RecentlyRemovedDocs(10, { now: () => 2222 });+ original.setDeleted('doomed');+ saveRemovedDocsJournal(projectDir, original.entries());++ const reloaded = new RecentlyRemovedDocs(10, { now: () => 9999 });+ for (const [docName, entry] of loadRemovedDocsJournal(projectDir)) {+ reloaded.restore(docName, entry);+ }++ expect(reloaded.get('doomed')).toEqual({ kind: 'deleted', addedAt: 2222 });+ });++ test('missing journal file loads as empty', () => {+ expect(loadRemovedDocsJournal(makeProjectDir())).toEqual([]);+ });++ test('corrupt JSON loads as empty instead of throwing', () => {+ const projectDir = makeProjectDir();+ const path = removedDocsJournalPath(projectDir);+ mkdirSync(dirname(path), { recursive: true });+ writeFileSync(path, '{not json', 'utf-8');+ expect(loadRemovedDocsJournal(projectDir)).toEqual([]);+ });++ test('unknown version or malformed entries are dropped, valid ones kept', () => {+ const projectDir = makeProjectDir();+ const path = removedDocsJournalPath(projectDir);+ mkdirSync(dirname(path), { recursive: true });++ writeFileSync(path, JSON.stringify({ version: 99, entries: [] }), 'utf-8');+ expect(loadRemovedDocsJournal(projectDir)).toEqual([]);++ writeFileSync(+ path,+ JSON.stringify({+ version: 1,+ entries: [+ { docName: 'ok-entry', kind: 'deleted', addedAt: 5 },+ { docName: '', kind: 'deleted', addedAt: 5 },+ { docName: 'no-kind', addedAt: 5 },+ { docName: 'renamed-no-target', kind: 'renamed', addedAt: 5 },+ 'not-an-object',+ ],+ }),+ 'utf-8',+ );+ expect(loadRemovedDocsJournal(projectDir)).toEqual([+ ['ok-entry', { kind: 'deleted', addedAt: 5 }],+ ]);+ });+});++describe('RecentlyRemovedDocs — onMutate hook (journal wiring point)', () => {+ test('fires on set, delete, and restore — not on get/has/peek/entries', () => {+ let mutations = 0;+ const cache = new RecentlyRemovedDocs(10, { onMutate: () => mutations++ });++ cache.setDeleted('a');+ expect(mutations).toBe(1);+ cache.setRenamed('b', 'c');+ expect(mutations).toBe(2);+ cache.restore('d', { kind: 'deleted', addedAt: 1 });+ expect(mutations).toBe(3);++ cache.get('a');+ cache.has('a');+ cache.peek('a');+ cache.entries();+ expect(mutations).toBe(3);++ cache.delete('a');+ expect(mutations).toBe(4);+ // Deleting a missing key changes nothing — no mutation signal.+ cache.delete('a');+ expect(mutations).toBe(4);+ });+});diff --git a/packages/server/src/removed-docs-journal.ts b/packages/server/src/removed-docs-journal.tsnew file mode 100644index 000000000..5ef597f9d--- /dev/null+++ b/packages/server/src/removed-docs-journal.ts@@ -0,0 +1,96 @@+/**+ * Durable form of the `RecentlyRemovedDocs` cache at+ * `<projectDir>/.ok/local/removed-docs.json`.+ *+ * Every anti-resurrection signal (removal LRU, per-doc lifecycle markers,+ * reconciledBase) is otherwise per-process — after a restart the server+ * retains zero memory that a deletion or rename ever happened, while+ * clients (a browser tab's y-indexeddb cache) still hold the doc's full+ * Yjs state and would be admitted as a legitimate first write, re-creating+ * the file. Persisting the cache keeps the removal-redirect guard armed+ * across restarts. Stale entries are harmless: the guard is+ * file-existence-first for `deleted` entries (a re-created file drops the+ * entry and admits), and `/api/create-page` plus the watcher `add` arm+ * invalidate eagerly.+ */++import { existsSync, readFileSync } from 'node:fs';+import { dirname, join } from 'node:path';+import { getLocalDir } from './config/paths.ts';+import { tracedMkdirSync, tracedRenameSync, tracedWriteFileSync } from './fs-traced.ts';+import { getLogger } from './logger.ts';+import type { RemovalEntry } from './recently-removed-docs.ts';++const log = getLogger('removed-docs-journal');++const REMOVED_DOCS_JOURNAL_FILENAME = 'removed-docs.json';++interface RemovedDocsJournalV1 {+ version: 1;+ entries: Array<{ docName: string } & RemovalEntry>;+}++export function removedDocsJournalPath(projectDir: string): string {+ return join(getLocalDir(projectDir), REMOVED_DOCS_JOURNAL_FILENAME);+}++function isJournalEntry(value: unknown): value is { docName: string } & RemovalEntry {+ if (typeof value !== 'object' || value === null) return false;+ const entry = value as Record<string, unknown>;+ if (typeof entry.docName !== 'string' || entry.docName.length === 0) return false;+ if (typeof entry.addedAt !== 'number') return false;+ if (entry.kind === 'deleted') return true;+ if (entry.kind === 'renamed') return typeof entry.newDocName === 'string';+ return false;+}++/**+ * Read the persisted removal entries, oldest-first (LRU order preserved so+ * re-populating the cache reproduces the same eviction order). Missing+ * file → empty. Corrupt / wrong-shape file → warn and empty — the guard+ * degrades to today's per-process behavior rather than blocking boot.+ */+export function loadRemovedDocsJournal(projectDir: string): Array<[string, RemovalEntry]> {+ const path = removedDocsJournalPath(projectDir);+ if (!existsSync(path)) return [];+ try {+ const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<RemovedDocsJournalV1>;+ if (parsed.version !== 1 || !Array.isArray(parsed.entries)) {+ log.warn({ path }, '[removed-docs-journal] unrecognized journal shape — ignoring');+ return [];+ }+ const entries: Array<[string, RemovalEntry]> = [];+ for (const raw of parsed.entries) {+ if (!isJournalEntry(raw)) continue;+ const { docName, ...entry } = raw;+ entries.push([docName, entry as RemovalEntry]);+ }+ return entries;+ } catch (err) {+ log.warn({ path, err }, '[removed-docs-journal] failed to read journal — ignoring');+ return [];+ }+}++/**+ * Atomically persist the cache snapshot (tmp + rename for POSIX atomicity so+ * a crash mid-write can't leave a truncated journal). The fixed `.tmp` suffix+ * is safe here — one server per contentDir (`server.lock`) and the debounce+ * coalesces saves, so there is never a concurrent writer — matching the+ * single-writer journal discipline (`managed-rename-journal`), not+ * persistence's UUID-suffixed tmp (which exists for concurrent writers).+ */+export function saveRemovedDocsJournal(+ projectDir: string,+ entries: ReadonlyArray<[string, RemovalEntry]>,+): void {+ const path = removedDocsJournalPath(projectDir);+ const journal: RemovedDocsJournalV1 = {+ version: 1,+ entries: entries.map(([docName, entry]) => ({ docName, ...entry })),+ };+ tracedMkdirSync(dirname(path), { recursive: true });+ const tmpPath = `${path}.tmp`;+ tracedWriteFileSync(tmpPath, JSON.stringify(journal), 'utf-8');+ tracedRenameSync(tmpPath, path);+}diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex c85c4df6a..3586125a1 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -61,7 +61,7 @@ import { createConflictLifecycleSeedExtension } from './conflict-lifecycle-seed.import { resolveProjectTemplates } from './content/templates-resolver.ts';import { type ContentFilter, createContentFilter } from './content-filter.ts';import { dropPendingDocs, recordContributor } from './contributor-tracker.ts';-import { docNameToRelativePath, stripDocExtension } from './doc-extensions.ts';+import { docNameToRelativePath, getDocExtension, stripDocExtension } from './doc-extensions.ts';import { runDocLineageGuard } from './doc-lineage-guard.ts';import {DEFAULT_EMBEDDINGS_DIMENSIONS,@@ -140,6 +140,7 @@ import { loadPrincipal } from './principal.ts';import { RecentlyRemovedDocs } from './recently-removed-docs.ts';import { reconcile } from './reconciliation.ts';import { runRemovalRedirectGuard } from './removal-redirect-guard.ts';+import { loadRemovedDocsJournal, saveRemovedDocsJournal } from './removed-docs-journal.ts';import {gcRenameLog,loadRenameLogIndex,@@ -865,19 +866,70 @@ export function createServer(options: ServerOptions): ServerInstance {}, BACKLINK_SAVE_DEBOUNCE_MS);}- // Per-process LRU cache of docNames renamed away or deleted since boot.- // Read by `removalRedirectGuard` (registered below) to reject WebSocket+ // LRU cache of docNames renamed away or deleted, durable across restarts+ // via the removal journal at `.ok/local/removed-docs.json`. Read by+ // `removalRedirectGuard` (registered below) to reject WebSocket// connections to stale docNames before any Y.Doc work runs (the single// enforcement point that prevents IDB-resync from recreating the file at- // the OLD path). Populated by the rename spine + delete handler in- // `api-extension.ts` and by the watcher reconcile callbacks below;- // invalidated by `/api/create-page` and the watcher 'add' event.- // Declared at createServer scope so `handleDiskEvent` and the api- // extension factory both close over the same instance.+ // the OLD path — including after a server restart, when the reconnecting+ // client's cached Yjs state would otherwise be admitted as a legitimate+ // first write). Populated by the rename spine + delete handler in+ // `api-extension.ts`, the watcher reconcile callbacks below, and the+ // boot-time deleted-while-down inference in `initAsync`; invalidated by+ // `/api/create-page` and the watcher 'add' event. Declared at+ // createServer scope so `handleDiskEvent` and the api extension factory+ // both close over the same instance.+ const REMOVED_DOCS_JOURNAL_SAVE_DEBOUNCE_MS = 2000;+ let removedDocsJournalTimer: ReturnType<typeof setTimeout> | null = null;+ // Suppresses journal echo-writes while the boot reload below re-populates+ // the cache from the journal itself. The reload → `writable = true` flip+ // must stay synchronous: an `await` in that gap would let a cache mutation+ // fire `onMutate` while writes are still suppressed and be dropped from the+ // next debounced save.+ let removedDocsJournalWritable = false;+ const writeRemovedDocsJournalNow = (): void => {+ try {+ saveRemovedDocsJournal(projectDir, recentlyRemovedDocs.entries());+ } catch (err) {+ log.warn({ err }, '[removed-docs-journal] failed to persist removal journal');+ }+ };+ const scheduleRemovedDocsJournalSave = (): void => {+ if (!removedDocsJournalWritable || removedDocsJournalTimer !== null) return;+ removedDocsJournalTimer = setTimeout(() => {+ removedDocsJournalTimer = null;+ writeRemovedDocsJournalNow();+ }, REMOVED_DOCS_JOURNAL_SAVE_DEBOUNCE_MS);+ };const recentlyRemovedDocs = new RecentlyRemovedDocs(undefined, {onEviction: () => incrementRecentlyRemovedDocsEviction(),onSizeChange: (size) => setRecentlyRemovedDocsSize(size),+ onMutate: scheduleRemovedDocsJournalSave,});+ // Gate note: runtime populate sites filter `isSystemDoc || isConfigDoc`+ // (managed-artifact docs can legitimately be renamed/deleted at runtime),+ // while reload and boot-tombstoning use the broader `isReservedForUserTree`+ // — managed artifacts are excluded here because their reconcile ownership+ // (skill/template heal) re-creates files at boot, which would immediately+ // fight a restored tombstone.+ for (const [journaledDocName, entry] of loadRemovedDocsJournal(projectDir)) {+ if (isReservedForUserTree(journaledDocName)) continue;+ // Journal contents are disk input — refuse unsafe names outright.+ if (!isSafeDocName(journaledDocName)) continue;+ // Disk is truth at boot: a file re-created at the removed docName while+ // the server was down makes the entry stale — restoring it would reject+ // or misdirect connections to a doc that exists. The extension registry+ // isn't seeded yet, so probe the supported source extensions literally;+ // the post-seed-walk sweep in `initAsync` re-checks with real on-disk+ // extensions as the authoritative pass.+ const recreated = ['.md', '.mdx'].some((ext) => {+ const candidate = resolve(contentDir, `${journaledDocName}${ext}`);+ return isWithinDir(candidate, resolve(contentDir)) && existsSync(candidate);+ });+ if (recreated) continue;+ recentlyRemovedDocs.restore(journaledDocName, entry);+ }+ removedDocsJournalWritable = true;// Lambda-callback shape mirrors `onDiskFlush` (`persistenceOpts`) — keeps// the watcher reconcile cases free of direct cache references and avoids// extending `signalChannel`'s union for a per-event side effect.@@ -1082,6 +1134,10 @@ export function createServer(options: ServerOptions): ServerInstance {// Closure-deferred: `syncEngine`/`semanticSearch` resolve at call time,// always after their assignment.onConfigPersisted: applyPersistedConfigToConsumers,+ // Diagnostic-only probe: surfaces any store that writes a doc the+ // removal cache still records as removed (a resurrection would+ // otherwise register as a benign self-write and be invisible).+ isRecentlyRemoved: (docName) => recentlyRemovedDocs.has(docName),mdManager: options.mdManager,};@@ -1128,13 +1184,17 @@ export function createServer(options: ServerOptions): ServerInstance {// name, but the editor shows the old content" because no fresh// `onLoadDocument` runs to read the new (empty) file from disk.//- // The pending-work check is also bypassed: the file is being unlinked,- // so any pending `onStoreDocument` debounce for this doc is operating- // on bytes that will never be reachable again. `captureAndCloseDocuments`- // unconditionally snapshots `liveContents` for both renames and deletes- // before closing; the rename path reapplies the snapshot via- // `syncRenamedDocsToDisk`, the delete path discards it because the file- // is unlinked.+ // The pending-work check is also bypassed. Pending `onStoreDocument`+ // work for this doc is not lost silently: `captureAndCloseDocuments`+ // sets the lifecycle marker BEFORE closing connections, so the+ // last-connection-close flush, any debounce timer that survives this+ // unload, and deferred-store replays are all skipped by+ // `storeDocumentNow`'s lifecycle guard rather than resurrecting the+ // just-removed path. `captureAndCloseDocuments` also unconditionally+ // snapshots `liveContents` for both renames and deletes before+ // closing; the rename path reapplies the snapshot via+ // `syncRenamedDocsToDisk`, the delete path discards it because the+ // file is unlinked.if (forceUnloadSet.has(document)) {return true;}@@ -2300,6 +2360,27 @@ export function createServer(options: ServerOptions): ServerInstance {backlinkSaveTimer = null;}+ // Flush the removal journal synchronously — a tombstone recorded just+ // before shutdown must survive the restart or a reconnecting stale+ // client resurrects the doc. Failure feeds `phaseErrors`: this flush is+ // the last chance to persist the tombstone, and the structured shutdown+ // summary is what an operator inspects when a lone warn scrolls away.+ if (removedDocsJournalTimer !== null) {+ clearTimeout(removedDocsJournalTimer);+ removedDocsJournalTimer = null;+ }+ if (removedDocsJournalWritable) {+ try {+ saveRemovedDocsJournal(projectDir, recentlyRemovedDocs.entries());+ } catch (err) {+ log.warn(+ { err },+ '[removed-docs-journal] failed to persist removal journal during shutdown',+ );+ phaseErrors.push({ phase: 'removed-docs-journal-flush', error: String(err) });+ }+ }+// Wait for async init to complete before cleanup — prevents leaked watcher// subscriptions if destroy() is called during startup (e.g., Ctrl+C).// Bounded to 5s so destroy() doesn't hang indefinitely if init is stuck@@ -3143,7 +3224,43 @@ export function createServer(options: ServerOptions): ServerInstance {if (cacheLoaded) {const diff = await backlinkIndex.reconcileWithDisk(branch);if (diff.added > 0 || diff.updated > 0 || diff.deleted > 0) {- log.info(diff, '[backlinks] startup reconcile: offline changes applied');+ log.info(+ { added: diff.added, updated: diff.updated, deleted: diff.deleted },+ '[backlinks] startup reconcile: offline changes applied',+ );+ }+ // Files deleted while the server was down leave no tombstone —+ // the delete was never observed, so nothing stops a reconnecting+ // client that still holds the doc's Yjs state from re-creating+ // the file as a "legitimate first write". The reconcile's+ // deleted set is exactly the last-known content docs whose file+ // vanished during downtime; arm the removal guard for each (the+ // journal hook makes the inference durable, and the guard's+ // file-existence-first self-heal admits any legitimate+ // re-creation).+ let tombstonedOffline = 0;+ for (const deletedDocName of diff.deletedDocNames) {+ // Same doc-kind gate as every other populate site:+ // `isReservedForUserTree` excludes synthetic, config, and+ // managed-artifact docs — none may enter the removal cache.+ // (Managed artifacts live under `.ok/` outside the content+ // walk and have their own reconcile ownership.)+ if (isReservedForUserTree(deletedDocName)) continue;+ // A journaled rename-redirect is strictly more informative+ // than an inferred flat delete — a rename inside the+ // debounced backlink-save window leaves the persisted cache+ // stale with the old name, so the inference sees it as+ // deleted-while-down. Refuse the downgrade (mirrors the+ // watcher unpaired-delete peek-guard above).+ if (recentlyRemovedDocs.peek(deletedDocName)?.kind === 'renamed') continue;+ recentlyRemovedDocs.setDeleted(deletedDocName);+ tombstonedOffline++;+ }+ if (tombstonedOffline > 0) {+ log.info(+ { count: tombstonedOffline },+ '[removal-guard] tombstoned docs deleted while the server was down',+ );}} else {await backlinkIndex.rebuildFromDisk(branch);@@ -3180,6 +3297,37 @@ export function createServer(options: ServerOptions): ServerInstance {startWatcher(contentDir, onDiskEvent, contentFilter),);recordBootPhase('seedWalkMs', Math.round(performance.now() - seedWalkStartMono));++ // Origin-existence self-heal for journaled removal entries. Disk is+ // truth at boot: a file re-created at a removed docName while the+ // server was down means the durable tombstone (or rename redirect) is+ // stale — keeping it would misdirect or reject connections to a doc+ // that exists. The runtime guard self-heals `deleted` entries at auth+ // time, but `renamed` chain-walks trust the cache (the git-mv syscall+ // window makes runtime existence checks unsafe there); at boot no+ // move is in flight, so existence is authoritative. Runs after the+ // seed walk so `getDocExtension` resolves real on-disk extensions.+ {+ const sweepContentDir = resolve(contentDir);+ let healedJournalEntries = 0;+ for (const [removedDocName] of recentlyRemovedDocs.entries()) {+ if (!isSafeDocName(removedDocName)) continue;+ const filePath = resolve(+ sweepContentDir,+ `${removedDocName}${getDocExtension(removedDocName)}`,+ );+ if (isWithinDir(filePath, sweepContentDir) && existsSync(filePath)) {+ recentlyRemovedDocs.delete(removedDocName);+ healedJournalEntries++;+ }+ }+ if (healedJournalEntries > 0) {+ log.info(+ { count: healedJournalEntries },+ '[removal-guard] dropped journaled removal entries whose file re-appeared while the server was down',+ );+ }+ }// Re-init tagIndex once the watcher has settled. The earlier `init()`// in the synchronous boot path covers the cold-start case; this second// pass picks up any disk content that landed between constructor time