Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 alpha
expect(reloaded.getBacklinks('alpha')).toEqual([
diff --git a/packages/server/src/backlink-index.ts b/packages/server/src/backlink-index.ts
index 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.ts
index 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.ts
index 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 with
diff --git a/packages/server/src/recently-removed-docs.ts b/packages/server/src/recently-removed-docs.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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