Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): recycle-window edit loss on disconnect and server restart (#2777)
Nick Gomez32ae04d8180d
diff --git a/.changeset/recycle-window-edit-loss.md b/.changeset/recycle-window-edit-loss.mdnew file mode 100644index 000000000..51227a8f3--- /dev/null+++ b/.changeset/recycle-window-edit-loss.md@@ -0,0 +1,7 @@+---+"@inkeep/open-knowledge": patch+---++Edits typed while the connection drops are no longer lost when the document recycles++Typing right after the editor lost its server connection (for example after switching windows) could silently destroy that edit: a short debounce timer recycles idle disconnected documents, and it only checked for unsynced edits when it was armed, not when it fired. An edit typed inside that window rode into the teardown; if the server identity changed before the next sync (an app update relaunch does exactly this), the edit was gone permanently. The recycle now re-checks for unsynced edits at fire time and leaves dirty documents alone, and the server-restart recovery replays a preserved edit at content level so it also survives a server identity change instead of being parked as an unresolvable CRDT delta.diff --git a/packages/app/src/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.tsindex 45b9789c5..0be84b339 100644--- a/packages/app/src/editor/provider-pool.ts+++ b/packages/app/src/editor/provider-pool.ts@@ -1,7 +1,14 @@import { HocuspocusProvider } from '@hocuspocus/provider';-import { LINEAGE_EPOCH_KEY, MarkdownManager } from '@inkeep/open-knowledge-core';+import {+ LINEAGE_EPOCH_KEY,+ MarkdownManager,+ normalizeBridge,+ prependFrontmatter,+ stripFrontmatter,+} from '@inkeep/open-knowledge-core';import type { HocuspocusAuthRejectionReason } from '@inkeep/open-knowledge-server';import { getSchema } from '@tiptap/core';+import { yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';import * as Y from 'yjs';import { buildAuthToken } from '../lib/auth-token';import { readNumericOverride } from '../lib/perf/env-override';@@ -475,10 +482,27 @@ export class ProviderPool {* Unsynced-edit buffer captured per-doc during a `server-instance-mismatch`* recycle. Populated right before `clearData()` wipes IDB; drained at the* fresh provider's FIRST post-recycle `synced` event when the replay- * listener applies the bytes back to the Y.Doc. In-memory only — a tab- * crash inside the recycle window loses the buffer (accepted trade-off).+ * listener restores the edit. In-memory only — a tab crash inside the+ * recycle window loses the buffer (accepted trade-off).+ *+ * `delta` is the raw unsynced Yjs update relative to the last acked+ * baseline. It CANNOT integrate into the post-restart doc on its own:+ * the restarted server rebuilds every Y.Doc from markdown under a fresh+ * clientID, so the delta's left/right origins reference item IDs that no+ * longer exist and `Y.applyUpdate` parks the structs in `pendingStructs`+ * forever. `fullState` (the complete pre-recycle doc) exists so the+ * replay can reconstruct the edit at CONTENT level instead: rebuild the+ * old doc in a throwaway replica, work out which CRDT surface holds the+ * un-drained edit, and splice the recovered content into the fresh+ * Y.Text as an ordinary client edit. `fullState` is null when the doc+ * exceeded the buffer cap — the replay then falls back to the legacy+ * delta apply (which at worst leaves the structs pending, today's+ * behavior).*/- private readonly bufferedUpdates = new Map<string, Uint8Array>();+ private readonly bufferedUpdates = new Map<+ string,+ { delta: Uint8Array; fullState: Uint8Array | null }+ >();/*** Per-docName `closeAndClearPersistence` in-flight tracking. Drives the* delete-then-recreate-same-docname coordination: while a clear is in@@ -1762,6 +1786,21 @@ export class ProviderPool {if (entry.kind !== 'active') return;entry.pendingRecycleTimer = null;if (this.entries.get(docName) !== entry) return;+ // Re-check for unsynced local edits at FIRE time, not just arm+ // time. An edit typed inside the debounce window makes the doc+ // dirty, and this plain-recycle path has no buffer-and-replay+ // (that exists only for `server-instance-mismatch`) — recycling a+ // dirty doc destroys the edit permanently whenever the server+ // identity changes before resync (auto-update relaunch is a+ // first-class trigger). Skip instead: the provider's backoff+ // keeps reconnecting, a same-identity reconnect syncs the edit,+ // an identity change routes through the mismatch path's+ // buffer-and-replay, and a later clean disconnect re-arms the+ // timer so resource reclamation still happens.+ if (provider.unsyncedChanges > 0) {+ mark('ok/pool/recycle-skipped-unsynced', { docName });+ return;+ }this.recycleDisconnectedEntry(docName);}, this.recycleDebounceMs);}@@ -2024,13 +2063,24 @@ export class ProviderPool {// rejection and so the next sync can proceed.this.bufferedUpdates.delete(docName);try {- Y.applyUpdate(provider.document, current, TAB_REPLAY_ORIGIN);+ if (+ current.fullState !== null &&+ this.replayBufferedContent(docName, provider, current.fullState)+ ) {+ return;+ }+ // Delta-only fallback (full state over cap, replica rebuild threw,+ // or content divergence made the surface attribution ambiguous).+ // The raw delta usually parks in `pendingStructs` on a rebuilt doc+ // — kept as the terminal fallback so this path never REGRESSES+ // relative to the pre-content-replay behavior.+ Y.applyUpdate(provider.document, current.delta, TAB_REPLAY_ORIGIN);} catch (err: unknown) {const errorName = err instanceof Error ? err.name : 'non-error-throw';this.emitStructuredClientRecoveryEvent({event: 'ok-buffer-replay-failed',...this.recoveryTelemetryBase(docName, staleClaimAtReplayInstall),- replayByteLength: current.byteLength,+ replayByteLength: current.delta.byteLength,errorName,errorMessage: err instanceof Error ? err.message : String(err),});@@ -2217,7 +2267,14 @@ export class ProviderPool {continue;}if (unsynced.byteLength > 0) {- this.bufferedUpdates.set(docName, unsynced);+ // Full pre-recycle state rides along so the replay can recover the+ // edit at content level (see `bufferedUpdates` doc comment). Docs+ // whose full state exceeds the cap keep the delta-only fallback.+ const fullState = Y.encodeStateAsUpdate(poolEntry.provider.document);+ this.bufferedUpdates.set(docName, {+ delta: unsynced,+ fullState: fullState.byteLength > MAX_BUFFER_BYTES ? null : fullState,+ });}}@@ -2323,6 +2380,101 @@ export class ProviderPool {this.mismatchInFlight = inflight;}+ /**+ * Content-level buffer replay for the `server-instance-mismatch` recycle.+ *+ * The raw unsynced delta cannot integrate into the post-restart doc (the+ * rebuilt doc has fresh item IDs — see the `bufferedUpdates` doc comment),+ * so the edit is reconstructed as CONTENT: rebuild the pre-recycle doc in+ * a throwaway replica, decide which CRDT surface holds the un-drained+ * edit by comparing each surface against the fresh server content+ * (whichever surface still matches the server IS the base), and splice+ * the recovered document string into the fresh Y.Text as an ordinary+ * client edit. Server Observer B derives the fragment from Y.Text, so a+ * single-surface write is sufficient and cannot double-apply.+ *+ * Returns true when the replay is complete (including "nothing to+ * restore"); false when the surface attribution is ambiguous (both+ * surfaces diverge from the server — concurrent server-side change or+ * mixed-mode edits) or the replica rebuild failed, in which case the+ * caller falls back to the legacy delta apply.+ */+ private replayBufferedContent(+ docName: string,+ provider: HocuspocusProvider,+ fullState: Uint8Array,+ ): boolean {+ const replica = new Y.Doc();+ try {+ Y.applyUpdate(replica, fullState);+ const oursYtext = replica.getText('source').toString();+ const fragJson = yXmlFragmentToProseMirrorRootNode(+ replica.getXmlFragment('default'),+ getEditorSchema(),+ ).toJSON();+ const mdMgr = new MarkdownManager({ extensions: sharedExtensions });+ const oursFragBody = mdMgr.serialize(fragJson);+ const { frontmatter: oursFm, body: oursYtextBody } = stripFrontmatter(oursYtext);+ const theirs = provider.document.getText('source').toString();+ const { body: theirsBody } = stripFrontmatter(theirs);+ const theirsNorm = normalizeBridge(theirsBody);+ const ytextClean = normalizeBridge(oursYtextBody) === theirsNorm;+ const fragClean = normalizeBridge(oursFragBody) === theirsNorm;+ if (ytextClean && fragClean) return true;+ let ours: string;+ if (ytextClean) {+ // Un-drained WYSIWYG edit: the fragment moved while Y.Text stayed+ // at the acked base the server rebuilt from disk.+ ours = prependFrontmatter(oursFm, oursFragBody);+ } else if (fragClean) {+ // Unacked source-mode edit: Y.Text moved, fragment still at base.+ ours = oursYtext;+ } else {+ this.emitStructuredClientRecoveryEvent({+ event: 'ok-buffer-replay-diverged',+ ...this.recoveryTelemetryBase(docName),+ });+ return false;+ }+ if (ours !== theirs) {+ // Minimal splice (common prefix/suffix trim) keeps untouched bytes+ // untouched — Y.Text is byte-sacred outside the recovered edit+ // (precedent #57).+ const maxScan = Math.min(ours.length, theirs.length);+ let prefix = 0;+ while (prefix < maxScan && ours[prefix] === theirs[prefix]) prefix += 1;+ let suffix = 0;+ while (+ suffix < maxScan - prefix &&+ ours[ours.length - 1 - suffix] === theirs[theirs.length - 1 - suffix]+ ) {+ suffix += 1;+ }+ const ytext = provider.document.getText('source');+ provider.document.transact(() => {+ ytext.delete(prefix, theirs.length - prefix - suffix);+ ytext.insert(prefix, ours.slice(prefix, ours.length - suffix));+ }, TAB_REPLAY_ORIGIN);+ }+ this.emitStructuredClientRecoveryEvent({+ event: 'ok-buffer-replay-content-applied',+ ...this.recoveryTelemetryBase(docName),+ surface: ytextClean ? 'fragment' : 'ytext',+ });+ return true;+ } catch (err: unknown) {+ this.emitStructuredClientRecoveryEvent({+ event: 'ok-buffer-replay-content-failed',+ ...this.recoveryTelemetryBase(docName),+ errorName: err instanceof Error ? err.name : 'non-error-throw',+ errorMessage: err instanceof Error ? err.message : String(err),+ });+ return false;+ } finally {+ replica.destroy();+ }+ }+/*** Resolve when the current `server-instance-mismatch` recycle (clearData +* `recycleAllEntries`) has settled. Resolves immediately when no recycle is@@ -2614,7 +2766,7 @@ export class ProviderPool {* keeps these out of production call sites by convention.*/__test_seedBufferedUpdate(docName: string, update: Uint8Array): void {- this.bufferedUpdates.set(docName, update);+ this.bufferedUpdates.set(docName, { delta: update, fullState: null });}__test_bufferedUpdatesSize(): number {return this.bufferedUpdates.size;@@ -2623,7 +2775,7 @@ export class ProviderPool {return this.bufferedUpdates.has(docName);}__test_getBufferedUpdate(docName: string): Uint8Array | undefined {- return this.bufferedUpdates.get(docName);+ return this.bufferedUpdates.get(docName)?.delta;}/** Set the active document. Must already be open. */diff --git a/packages/app/tests/integration/provider-pool-recycle-window-loss.test.ts b/packages/app/tests/integration/provider-pool-recycle-window-loss.test.tsnew file mode 100644index 000000000..7c9508ad3--- /dev/null+++ b/packages/app/tests/integration/provider-pool-recycle-window-loss.test.ts@@ -0,0 +1,246 @@+import './idb-preload';+import { writeFileSync } from 'node:fs';+import { join } from 'node:path';+import { setTimeout as wait } from 'node:timers/promises';+import { afterEach, describe, expect, test } from 'vitest';+import * as Y from 'yjs';+import { ProviderPool } from '../../src/editor/provider-pool';+import { createRestartableServer, pollUntil, seedPoolServerInstanceId } from './test-harness';++/**+ * Disconnect-recycle window vs local edits.+ *+ * `onDisconnect` (provider-pool.ts) checks `provider.unsyncedChanges === 0`+ * when ARMING the debounced recycle timer AND re-checks it inside the timer+ * closure at FIRE time. The fire-time re-check is load-bearing: an edit+ * typed inside the debounce window makes the doc dirty, and the plain+ * recycle path has no buffer-and-replay (that exists only for+ * `server-instance-mismatch`) — without the re-check, the recycle destroys+ * the edit permanently whenever the server identity changes before resync.+ *+ * Pinned contract: a dirty entry is never torn down by the plain recycle;+ * the edit survives both identity-changed reconnects (via the mismatch+ * path's buffer-and-replay) and identity-stable offline windows (edit stays+ * live in the un-recycled doc), and a clean entry still recycles normally.+ */++const SEED = `# Seed++Adeline: 1652++## TODO++- item one+`;++const cleanups: Array<() => Promise<void> | void> = [];++afterEach(async () => {+ while (cleanups.length > 0) {+ await cleanups.pop()?.();+ }+}, 30_000);++describe('disconnect-recycle window vs local edit', () => {+ test('an edit typed during the armed recycle-debounce window survives the recycle', async () => {+ let server = await createRestartableServer();+ cleanups.push(() => server.shutdown());++ const docName = `recycle-window-${crypto.randomUUID()}`;+ const pool = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {+ // Short debounce so the window is testable; production is 4000ms.+ recycleDebounceMs: 250,+ });+ cleanups.push(() => pool.dispose());+ await seedPoolServerInstanceId(server, pool);++ writeFileSync(join(server.contentDir, `${docName}.md`), SEED, 'utf-8');+ pool.open(docName);+ pool.setActive(docName);+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 10_000, 50);++ const firstProvider = pool.getActive()?.provider;+ if (!firstProvider) throw new Error('no active provider after seed');++ // Disconnect with a clean provider — the recycle timer arms because+ // `unsyncedChanges === 0` holds NOW.+ server.killNetwork();+ await pollUntil(() => pool.getActive()?.syncState === 'disconnected', 5_000, 20);++ // Type INSIDE the armed window (before the 250ms timer fires). This is+ // the customer motion: window blur drops the socket, the user types on+ // return before the (background-clamped) timer has fired.+ const MARKER = 'RW-LOCAL-EDIT-MARKER-c41d';+ const doc = firstProvider.document;+ const paragraph = new Y.XmlElement('paragraph');+ const xtext = new Y.XmlText();+ xtext.applyDelta([{ insert: MARKER }]);+ paragraph.insert(0, [xtext]);+ doc.getXmlFragment('default').push([paragraph]);+ expect(firstProvider.unsyncedChanges).toBeGreaterThan(0);++ // Let the armed timer fire.+ await wait(700);+ const recycled = pool.getActive()?.provider !== firstProvider;++ // Bring the server back on the same port and let the pool re-sync.+ server = await server.killAndRestartOnSamePort({ downtimeMs: 300 });+ cleanups.unshift(() => server.shutdown());+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);+ // Allow any deferred persistence hydration / replay to land.+ await wait(1_000);++ const finalText =+ pool.getActive()?.provider.document.getXmlFragment('default').toString() ?? '';+ const finalSource = pool.getActive()?.provider.document.getText('source').toString() ?? '';++ // Diagnostic context on failure.+ console.info(+ JSON.stringify({+ event: 'recycle-window-loss-diagnostic',+ recycled,+ markerInFragment: finalText.includes(MARKER),+ markerInSource: finalSource.includes(MARKER),+ }),+ );++ // Correct behavior: the local edit survives the disconnect + recycle.+ expect(finalText.includes(MARKER) || finalSource.includes(MARKER)).toBe(true);+ // No double-apply: the marker lands at most once per CRDT surface even+ // though IDB rehydration and mismatch buffer-and-replay both ran.+ expect(finalText.split(MARKER).length - 1).toBeLessThanOrEqual(1);+ expect(finalSource.split(MARKER).length - 1).toBeLessThanOrEqual(1);+ }, 40_000);++ /**+ * Same identity-changed motion, source-mode surface: the unsynced edit+ * lives in Y.Text (W2) instead of the XmlFragment. Pins the symmetric+ * branch of the content-level replay (fragment is the clean base, Y.Text+ * carries the edit).+ *+ */+ test('a source-mode edit typed during the window survives a server-identity change', async () => {+ let server = await createRestartableServer();+ cleanups.push(() => server.shutdown());++ const docName = `recycle-window-src-${crypto.randomUUID()}`;+ const pool = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {+ recycleDebounceMs: 250,+ });+ cleanups.push(() => pool.dispose());+ await seedPoolServerInstanceId(server, pool);++ writeFileSync(join(server.contentDir, `${docName}.md`), SEED, 'utf-8');+ pool.open(docName);+ pool.setActive(docName);+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 10_000, 50);++ const firstProvider = pool.getActive()?.provider;+ if (!firstProvider) throw new Error('no active provider after seed');++ server.killNetwork();+ await pollUntil(() => pool.getActive()?.syncState === 'disconnected', 5_000, 20);++ const MARKER = 'RW-SOURCE-EDIT-MARKER-9a3b';+ const ytext = firstProvider.document.getText('source');+ firstProvider.document.transact(() => {+ ytext.insert(ytext.length, `\n${MARKER}\n`);+ });+ expect(firstProvider.unsyncedChanges).toBeGreaterThan(0);++ await wait(700);++ server = await server.killAndRestartOnSamePort({ downtimeMs: 300 });+ cleanups.unshift(() => server.shutdown());+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);+ await wait(1_000);++ const finalSource = pool.getActive()?.provider.document.getText('source').toString() ?? '';+ expect(finalSource.includes(MARKER)).toBe(true);+ expect(finalSource.split(MARKER).length - 1).toBe(1);+ }, 40_000);++ /**+ * Identity-stable offline window: the server never comes back during the+ * test. The fire-time guard must SKIP the recycle while the doc holds an+ * unsynced edit — the entry stays pooled and the edit stays live in the+ * original Y.Doc, ready to sync on a same-identity reconnect (the customer+ * case where their local server never restarted).+ *+ */+ test('a dirty entry is not recycled when the debounce window elapses offline', async () => {+ const server = await createRestartableServer();+ cleanups.push(() => server.shutdown());++ const docName = `recycle-window-dirty-${crypto.randomUUID()}`;+ const pool = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {+ recycleDebounceMs: 250,+ });+ cleanups.push(() => pool.dispose());+ await seedPoolServerInstanceId(server, pool);++ writeFileSync(join(server.contentDir, `${docName}.md`), SEED, 'utf-8');+ pool.open(docName);+ pool.setActive(docName);+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 10_000, 50);++ const firstProvider = pool.getActive()?.provider;+ if (!firstProvider) throw new Error('no active provider after seed');++ server.killNetwork();+ await pollUntil(() => pool.getActive()?.syncState === 'disconnected', 5_000, 20);++ const MARKER = 'RW-DIRTY-EDIT-MARKER-77e2';+ const doc = firstProvider.document;+ const paragraph = new Y.XmlElement('paragraph');+ const xtext = new Y.XmlText();+ xtext.applyDelta([{ insert: MARKER }]);+ paragraph.insert(0, [xtext]);+ doc.getXmlFragment('default').push([paragraph]);+ expect(firstProvider.unsyncedChanges).toBeGreaterThan(0);++ // Let the armed timer fire well past the 250ms debounce.+ await wait(700);++ // The fire-time guard skipped the recycle: same provider, edit live.+ expect(pool.getActive()?.provider).toBe(firstProvider);+ expect(firstProvider.document.getXmlFragment('default').toString().includes(MARKER)).toBe(true);+ }, 40_000);++ /**+ * Resource reclamation is unchanged for clean entries: with no unsynced+ * edits, the debounced recycle still tears down and re-opens the entry+ * after the window elapses.+ *+ */+ test('a clean entry still recycles after the debounce window elapses', async () => {+ const server = await createRestartableServer();+ cleanups.push(() => server.shutdown());++ const docName = `recycle-window-clean-${crypto.randomUUID()}`;+ const pool = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {+ recycleDebounceMs: 250,+ });+ cleanups.push(() => pool.dispose());+ await seedPoolServerInstanceId(server, pool);++ writeFileSync(join(server.contentDir, `${docName}.md`), SEED, 'utf-8');+ pool.open(docName);+ pool.setActive(docName);+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 10_000, 50);+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 10_000, 50);++ const firstProvider = pool.getActive()?.provider;+ if (!firstProvider) throw new Error('no active provider after seed');++ server.killNetwork();+ await pollUntil(() => pool.getActive()?.syncState === 'disconnected', 5_000, 20);++ // No local edit — the entry is clean, so the timer should recycle it.+ await pollUntil(() => pool.getActive()?.provider !== firstProvider, 5_000, 20);+ expect(pool.getActive()?.provider).not.toBe(firstProvider);+ }, 40_000);+});