Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): prevent CRDT lineage duplication on doc reload (#1723)

Nick Gomez49ec23cc74c5
diff --git a/.changeset/doc-lineage-fence.md b/.changeset/doc-lineage-fence.md
new file mode 100644
index 000000000..5f0fa916f
--- /dev/null
+++ b/.changeset/doc-lineage-fence.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fixed a document-corruption bug where reopening a doc the server had unloaded and re-read from disk (an external delete + recreate — e.g. a `git pull` or checkout rewriting files — a rename, or any other server-side unload) could merge the browser's cached copy into the fresh document as a second materialization: every block appeared twice, and content deleted on disk resurrected. The server now stamps each loaded document with a lineage epoch; browsers record the epoch they synced and present it when rejoining, and a stale rejoin is rejected up front — the client clears its cached copy and reloads the document cleanly instead of corrupting it. The same fence covers the deferred cache-attach window during boot, so a cache learned to be stale after sync is discarded rather than merged. Also fixes a separate, pre-existing cleanup gap the fence depends on: clearing the browser cache of a renamed or deleted doc was silently skipped in tabs that had not yet observed a branch, leaving stale rows that could re-merge on a later open.
diff --git a/packages/app/src/editor/provider-pool.test.ts b/packages/app/src/editor/provider-pool.test.ts
index 9257e56ce..3d58f60bf 100644
--- a/packages/app/src/editor/provider-pool.test.ts
+++ b/packages/app/src/editor/provider-pool.test.ts
@@ -698,6 +698,21 @@ describe('buildAuthToken (MECHANISM-ONLY — CRDT restart recovery + client vers
parseHocuspocusAuthToken(buildAuthToken(tabId, 'sid-x', ''))?.expectedBranch,
).toBeUndefined();
});
+
+ test('includes expectedDocLineageEpoch when supplied', () => {
+ const parsed = parseHocuspocusAuthToken(buildAuthToken(null, 'sid-x', null, 'epoch-1'));
+ if (!parsed) throw new Error('expected valid token');
+ expect(parsed.expectedDocLineageEpoch).toBe('epoch-1');
+ });
+
+ test('omits expectedDocLineageEpoch when null or empty', () => {
+ expect(
+ parseHocuspocusAuthToken(buildAuthToken(null, 'sid-x', null, null))?.expectedDocLineageEpoch,
+ ).toBeUndefined();
+ expect(
+ parseHocuspocusAuthToken(buildAuthToken(null, 'sid-x', null, ''))?.expectedDocLineageEpoch,
+ ).toBeUndefined();
+ });
});
describe('ProviderPool server-instance-ID claim (US-001)', () => {
@@ -977,6 +992,257 @@ describe('ProviderPool server-instance-ID claim (US-001)', () => {
});
});
+describe('ProviderPool doc-lineage epoch records', () => {
+ const ENVELOPE_KEY = 'ok-doc-lineage-epochs';
+
+ function makeStubStorage(): {
+ stub: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+ store: Map<string, string>;
+ } {
+ const store = new Map<string, string>();
+ const stub = {
+ getItem: (k: string) => store.get(k) ?? null,
+ setItem: (k: string, v: string) => {
+ store.set(k, v);
+ },
+ removeItem: (k: string) => {
+ store.delete(k);
+ },
+ };
+ return { stub, store };
+ }
+
+ function makePersistenceStub(): ClientPersistenceProvider {
+ return {
+ whenSynced: Promise.resolve(undefined as never),
+ synced: true,
+ destroy: async () => {},
+ clearData: async () => {},
+ } as unknown as ClientPersistenceProvider;
+ }
+
+ function makeEnvelope(
+ serverInstanceId: string,
+ epochs: Record<string, string>,
+ branch = '_unknown_',
+ ): string {
+ return JSON.stringify({ branch, serverInstanceId, epochs });
+ }
+
+ function tokenOf(entry: { provider: { configuration: { token: unknown } } }) {
+ const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
+ if (!parsed) throw new Error('expected valid token');
+ return parsed;
+ }
+
+ test('open() claims the epoch recorded in a valid storage envelope', () => {
+ const { stub, store } = makeStubStorage();
+ store.set(ENVELOPE_KEY, makeEnvelope(TEST_SERVER_INSTANCE_ID, { doc1: 'epoch-1' }));
+ pool = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const entry = pool.open('doc1');
+ if (!entry) throw new Error('expected entry');
+ expect(tokenOf(entry).expectedDocLineageEpoch).toBe('epoch-1');
+ });
+
+ test('claim is omitted while the server instance id is unknown', () => {
+ const { stub, store } = makeStubStorage();
+ store.set(ENVELOPE_KEY, makeEnvelope(TEST_SERVER_INSTANCE_ID, { doc1: 'epoch-1' }));
+ pool = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ const entry = pool.open('doc1');
+ if (!entry) throw new Error('expected entry');
+ expect(tokenOf(entry).expectedDocLineageEpoch).toBeUndefined();
+ });
+
+ test('envelope from a different server instance is ignored', () => {
+ const { stub, store } = makeStubStorage();
+ store.set(ENVELOPE_KEY, makeEnvelope('dead-instance', { doc1: 'epoch-1' }));
+ pool = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const entry = pool.open('doc1');
+ if (!entry) throw new Error('expected entry');
+ expect(tokenOf(entry).expectedDocLineageEpoch).toBeUndefined();
+ });
+
+ test('envelope from a different branch scope is ignored', () => {
+ const { stub, store } = makeStubStorage();
+ store.set(ENVELOPE_KEY, makeEnvelope(TEST_SERVER_INSTANCE_ID, { doc1: 'epoch-1' }, 'feature'));
+ pool = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const entry = pool.open('doc1');
+ if (!entry) throw new Error('expected entry');
+ expect(tokenOf(entry).expectedDocLineageEpoch).toBeUndefined();
+ });
+
+ test('synced lifecycle epoch is recorded and round-trips into a fresh pool', () => {
+ const { stub, store } = makeStubStorage();
+ pool = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const docName = uniqueDocName('pp-lineage-record');
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+
+ entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-live');
+ entry.provider.emit('synced', { state: true });
+
+ const raw = store.get(ENVELOPE_KEY);
+ if (raw === undefined) throw new Error('expected envelope written to storage');
+ const envelope = JSON.parse(raw) as {
+ branch: string;
+ serverInstanceId: string;
+ epochs: Record<string, string>;
+ };
+ expect(envelope.serverInstanceId).toBe(TEST_SERVER_INSTANCE_ID);
+ expect(envelope.epochs[docName]).toBe('epoch-live');
+
+ const pool2 = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ try {
+ pool2.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const entry2 = pool2.open(docName);
+ if (!entry2) throw new Error('expected entry2');
+ expect(tokenOf(entry2).expectedDocLineageEpoch).toBe('epoch-live');
+ } finally {
+ pool2.dispose();
+ }
+ });
+
+ test('doc-lineage-mismatch rejection drops the record and reopens claim-less', async () => {
+ const { stub, store } = makeStubStorage();
+ const docName = uniqueDocName('pp-lineage-reject');
+ store.set(ENVELOPE_KEY, makeEnvelope(TEST_SERVER_INSTANCE_ID, { [docName]: 'epoch-dead' }));
+ pool = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ pool.setActive(docName);
+ expect(tokenOf(entry).expectedDocLineageEpoch).toBe('epoch-dead');
+
+ const warnSpy = mock(() => {});
+ const origWarn = console.warn;
+ console.warn = warnSpy;
+ entry.provider.emit('authenticationFailed', { reason: 'doc-lineage-mismatch' });
+ console.warn = origWarn;
+
+ const reopened = pool.peek(docName);
+ if (!reopened) throw new Error('expected reopened entry');
+ expect(reopened).not.toBe(entry);
+ expect(pool.getActiveDocName()).toBe(docName);
+ expect(tokenOf(reopened).expectedDocLineageEpoch).toBeUndefined();
+
+ const raw = store.get(ENVELOPE_KEY);
+ if (raw === undefined) throw new Error('expected envelope still present');
+ const envelope = JSON.parse(raw) as { epochs: Record<string, string> };
+ expect(envelope.epochs[docName]).toBeUndefined();
+
+ const emitted = warnSpy.mock.calls
+ .map((call) => call[0] as string)
+ .filter((line) => typeof line === 'string' && line.includes('ok-doc-lineage-mismatch'));
+ expect(emitted.length).toBe(1);
+ const event = JSON.parse(emitted[0] ?? '{}') as Record<string, string>;
+ expect(event.via).toBe('auth-rejection');
+ expect(event.staleEpoch).toBe('epoch-dead');
+
+ await wait(10);
+ });
+
+ test('deferred-attach guard replaces a stale-lineage entry instead of hydrating it', async () => {
+ const { stub } = makeStubStorage();
+ pool = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ const docName = uniqueDocName('pp-lineage-deferred');
+
+ const first = pool.open(docName);
+ if (!first) throw new Error('expected first entry');
+ first.provider.document.getMap('lifecycle').set('epoch', 'epoch-dead');
+ first.provider.emit('synced', { state: true });
+ pool.close(docName);
+
+ const entry = pool.open(docName);
+ if (!entry) throw new Error('expected entry');
+ expect(entry.persistence).toBeNull();
+ entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-live');
+ entry.provider.emit('synced', { state: true });
+
+ const warnSpy = mock(() => {});
+ const origWarn = console.warn;
+ console.warn = warnSpy;
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ console.warn = origWarn;
+
+ const reopened = pool.peek(docName);
+ if (!reopened) throw new Error('expected reopened entry');
+ expect(reopened).not.toBe(entry);
+ expect(tokenOf(reopened).expectedDocLineageEpoch).toBe('epoch-live');
+ expect(reopened.lineageEpochRecordAtOpen).toBe('epoch-live');
+
+ const emitted = warnSpy.mock.calls
+ .map((call) => call[0] as string)
+ .filter((line) => typeof line === 'string' && line.includes('ok-doc-lineage-mismatch'));
+ expect(emitted.length).toBe(1);
+ const event = JSON.parse(emitted[0] ?? '{}') as Record<string, string>;
+ expect(event.via).toBe('deferred-attach');
+ expect(event.staleEpoch).toBe('epoch-dead');
+ expect(event.liveEpoch).toBe('epoch-live');
+
+ await wait(10);
+ });
+
+ test('rename-redirect and doc-deleted rejections prune the lineage record', () => {
+ const { stub, store } = makeStubStorage();
+ const renamedDoc = uniqueDocName('pp-lineage-renamed');
+ const deletedDoc = uniqueDocName('pp-lineage-deleted');
+ store.set(
+ ENVELOPE_KEY,
+ makeEnvelope(TEST_SERVER_INSTANCE_ID, {
+ [renamedDoc]: 'epoch-a',
+ [deletedDoc]: 'epoch-b',
+ }),
+ );
+ pool = new ProviderPool(3, DUMMY_WS, {
+ storage: stub,
+ persistenceFactory: mock(makePersistenceStub),
+ });
+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
+ const renamedEntry = pool.open(renamedDoc);
+ const deletedEntry = pool.open(deletedDoc);
+ if (!renamedEntry || !deletedEntry) throw new Error('expected entries');
+
+ renamedEntry.provider.emit('authenticationFailed', {
+ reason: `rename-redirect:${renamedDoc}-new`,
+ });
+ deletedEntry.provider.emit('authenticationFailed', { reason: 'doc-deleted' });
+
+ const raw = store.get(ENVELOPE_KEY);
+ if (raw === undefined) throw new Error('expected envelope still present');
+ const envelope = JSON.parse(raw) as { epochs: Record<string, string> };
+ expect(envelope.epochs[renamedDoc]).toBeUndefined();
+ expect(envelope.epochs[deletedDoc]).toBeUndefined();
+ });
+});
+
describe("ProviderPool authenticationFailed handling (US-002 / 'server-instance-mismatch')", () => {
test("reason 'server-instance-mismatch' recycles every pool entry", async () => {
pool = new ProviderPool(3, DUMMY_WS, { storage: null });
diff --git a/packages/app/src/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.ts
index a13eed3c2..ff32d91c7 100644
--- a/packages/app/src/editor/provider-pool.ts
+++ b/packages/app/src/editor/provider-pool.ts
@@ -1,5 +1,5 @@
import { HocuspocusProvider } from '@hocuspocus/provider';
-import { MarkdownManager } from '@inkeep/open-knowledge-core';
+import { LINEAGE_EPOCH_KEY, MarkdownManager } from '@inkeep/open-knowledge-core';
import type {
HocuspocusAuthRejectionReason,
HocuspocusAuthToken,
@@ -58,6 +58,7 @@ interface PoolEntryBase {
bridgeSetupFailed: boolean;
lastServerSyncedSV: Uint8Array | null;
lastDiskAckedSV: Uint8Array | null;
+ lineageEpochRecordAtOpen: string | null;
}
interface ActivePoolEntry extends PoolEntryBase {
@@ -140,6 +141,8 @@ class ClientPersistenceClearTimeoutError extends Error {
const LAST_OBSERVED_BRANCH_KEY = 'ok-last-observed-branch';
+const DOC_LINEAGE_EPOCHS_KEY = 'ok-doc-lineage-epochs';
+
const FORCE_SYNC_INTERVAL_MS = 5_000;
const MAX_BUFFER_BYTES = readNumericOverride('MAX_BUFFER_BYTES', 1 * 1024 * 1024);
@@ -166,6 +169,7 @@ export function buildAuthToken(
tabIdentity: { principalId: string; tabSessionId: string } | null,
expectedServerInstanceId: string | null,
expectedBranch: string | null = null,
+ expectedDocLineageEpoch: string | null = null,
): string {
const claim: HocuspocusAuthToken = { ...browserClientVersionTokenFields() };
if (tabIdentity !== null) {
@@ -178,6 +182,9 @@ export function buildAuthToken(
if (expectedBranch !== null && expectedBranch.length > 0) {
claim.expectedBranch = expectedBranch;
}
+ if (expectedDocLineageEpoch !== null && expectedDocLineageEpoch.length > 0) {
+ claim.expectedDocLineageEpoch = expectedDocLineageEpoch;
+ }
return JSON.stringify(claim);
}
@@ -292,7 +299,7 @@ export class ProviderPool {
doc: Y.Doc,
): ClientPersistenceProvider {
return this.persistenceFactory({
- branch: this.getOrInitObservedBranch() ?? UNKNOWN_BRANCH_SENTINEL,
+ branch: this.normalizedObservedBranch(),
serverInstanceId,
docName,
doc,
@@ -301,9 +308,32 @@ export class ProviderPool {
private attachDeferredPersistence(serverInstanceId: string): void {
let anyAttached = false;
- for (const entry of this._entries.values()) {
+ for (const entry of Array.from(this._entries.values())) {
if (entry.kind !== 'active') continue;
if (entry.persistence !== null) continue;
+ if (this._entries.get(entry.docName) !== entry) continue;
+ if (entry.hasSynced && entry.lineageEpochRecordAtOpen !== null) {
+ const liveEpoch = entry.provider.document.getMap('lifecycle').get(LINEAGE_EPOCH_KEY);
+ if (
+ typeof liveEpoch === 'string' &&
+ liveEpoch.length > 0 &&
+ liveEpoch !== entry.lineageEpochRecordAtOpen
+ ) {
+ const docName = entry.docName;
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-doc-lineage-mismatch',
+ ...this.recoveryTelemetryBase(docName),
+ via: 'deferred-attach',
+ staleEpoch: entry.lineageEpochRecordAtOpen,
+ liveEpoch,
+ });
+ const wasActive = this.activeDocName === docName;
+ void this.runCloseAndClearPersistence(docName);
+ const reopened = this.open(docName);
+ if (reopened !== null && wasActive) this.setActive(docName);
+ continue;
+ }
+ }
try {
entry.persistence = this.buildPersistence(
serverInstanceId,
@@ -369,6 +399,79 @@ export class ProviderPool {
} catch {}
}
+ private readonly docLineageEpochs = new Map<string, string>();
+ private docLineageEpochsEnvelopeConsumed = false;
+
+ private normalizedObservedBranch(): string {
+ return this.getOrInitObservedBranch() ?? UNKNOWN_BRANCH_SENTINEL;
+ }
+
+ private consumeLineageEpochEnvelopeIfValid(): void {
+ if (this.docLineageEpochsEnvelopeConsumed) return;
+ const instanceId = this.cachedServerInstanceId;
+ if (instanceId === null || instanceId.length === 0) return;
+ this.docLineageEpochsEnvelopeConsumed = true;
+ try {
+ const raw = this.storage?.getItem(DOC_LINEAGE_EPOCHS_KEY) ?? null;
+ if (raw === null) return;
+ const parsed: unknown = JSON.parse(raw);
+ if (typeof parsed !== 'object' || parsed === null) return;
+ const envelope = parsed as { branch?: unknown; serverInstanceId?: unknown; epochs?: unknown };
+ if (envelope.branch !== this.normalizedObservedBranch()) return;
+ if (envelope.serverInstanceId !== instanceId) return;
+ if (typeof envelope.epochs !== 'object' || envelope.epochs === null) return;
+ for (const [docName, epoch] of Object.entries(envelope.epochs as Record<string, unknown>)) {
+ if (typeof epoch === 'string' && epoch.length > 0 && !this.docLineageEpochs.has(docName)) {
+ this.docLineageEpochs.set(docName, epoch);
+ }
+ }
+ } catch (err: unknown) {
+ if (!(err instanceof DOMException)) {
+ console.warn(
+ JSON.stringify({
+ event: 'ok-lineage-epoch-envelope-read-error',
+ errorName: err instanceof Error ? err.name : typeof err,
+ message: err instanceof Error ? err.message : String(err),
+ }),
+ );
+ }
+ }
+ }
+
+ private getRecordedLineageEpoch(docName: string): string | null {
+ const inMemory = this.docLineageEpochs.get(docName);
+ if (inMemory !== undefined) return inMemory;
+ this.consumeLineageEpochEnvelopeIfValid();
+ return this.docLineageEpochs.get(docName) ?? null;
+ }
+
+ private persistLineageEpochEnvelope(): void {
+ const instanceId = this.cachedServerInstanceId;
+ if (instanceId === null || instanceId.length === 0) return;
+ try {
+ this.storage?.setItem(
+ DOC_LINEAGE_EPOCHS_KEY,
+ JSON.stringify({
+ branch: this.normalizedObservedBranch(),
+ serverInstanceId: instanceId,
+ epochs: Object.fromEntries(this.docLineageEpochs),
+ }),
+ );
+ } catch {}
+ }
+
+ private recordLineageEpoch(docName: string, epoch: string): void {
+ if (this.docLineageEpochs.get(docName) === epoch) return;
+ this.docLineageEpochs.set(docName, epoch);
+ this.persistLineageEpochEnvelope();
+ }
+
+ private deleteLineageEpochRecord(docName: string): void {
+ if (this.docLineageEpochs.delete(docName)) {
+ this.persistLineageEpochEnvelope();
+ }
+ }
+
private withClearDataTimeout(docName: string, promise: Promise<void>): Promise<void> {
return new Promise((resolve, reject) => {
const timeout = setTimeout(() => {
@@ -391,7 +494,7 @@ export class ProviderPool {
docName: string,
staleClaimOverride?: string | undefined,
): { docName: string; branch: string; serverInstanceId?: string } {
- const branch = this.getOrInitObservedBranch() ?? UNKNOWN_BRANCH_SENTINEL;
+ const branch = this.normalizedObservedBranch();
const base: { docName: string; branch: string; serverInstanceId?: string } = {
docName,
branch,
@@ -597,10 +700,14 @@ export class ProviderPool {
}
const expectedServerInstanceId = this.cachedServerInstanceId;
+ const lineageEpochRecordAtOpen = this.getRecordedLineageEpoch(docName);
const token = buildAuthToken(
this.tabIdentity,
expectedServerInstanceId,
this.getOrInitObservedBranch(),
+ expectedServerInstanceId !== null && expectedServerInstanceId.length > 0
+ ? lineageEpochRecordAtOpen
+ : null,
);
const provider = new HocuspocusProvider({
url: appendTraceContextToCollabUrl(this.wsUrl),
@@ -662,6 +769,7 @@ export class ProviderPool {
pendingRecycleTimer: null,
bridgeSetupFailed: false,
serverDrivenCloseReauthInFlight: false,
+ lineageEpochRecordAtOpen,
};
mark('ok/pool/open', { docName, hit: false, poolEventId });
mark.count('ok/pool/open', { hit: false });
@@ -678,6 +786,10 @@ export class ProviderPool {
entry.syncState = 'synced';
entry.hasSynced = true;
entry.lastServerSyncedSV = captureStateVector(provider.document);
+ const syncedLineageEpoch = provider.document.getMap('lifecycle').get(LINEAGE_EPOCH_KEY);
+ if (typeof syncedLineageEpoch === 'string' && syncedLineageEpoch.length > 0) {
+ this.recordLineageEpoch(docName, syncedLineageEpoch);
+ }
if (entry.pendingRecycleTimer) {
clearTimeout(entry.pendingRecycleTimer);
entry.pendingRecycleTimer = null;
@@ -727,6 +839,7 @@ export class ProviderPool {
'branch-mismatch',
'rename-redirect',
'doc-deleted',
+ 'doc-lineage-mismatch',
] as const satisfies readonly HocuspocusAuthRejectionReason[];
type _AssertCovers = HocuspocusAuthRejectionReason extends (typeof KNOWN)[number]
? true
@@ -770,17 +883,34 @@ export class ProviderPool {
}
const fromDocName = docName;
const toDocName = payload;
+ this.deleteLineageEpochRecord(fromDocName);
const existing = this.entries.get(fromDocName);
const hadOpenProvider = existing !== undefined && existing.kind === 'active';
this.onRenameRedirect?.({ fromDocName, toDocName, hadOpenProvider });
return;
}
if (typed === 'doc-deleted') {
+ this.deleteLineageEpochRecord(docName);
const existing = this.entries.get(docName);
const hadOpenProvider = existing !== undefined && existing.kind === 'active';
this.onDocDeleted?.({ docName, hadOpenProvider });
return;
}
+ if (typed === 'doc-lineage-mismatch') {
+ if (entry.kind !== 'active' || this.entries.get(docName) !== entry) return;
+ this.deleteLineageEpochRecord(docName);
+ this.emitStructuredClientRecoveryEvent({
+ event: 'ok-doc-lineage-mismatch',
+ ...this.recoveryTelemetryBase(docName),
+ via: 'auth-rejection',
+ staleEpoch: entry.lineageEpochRecordAtOpen ?? '',
+ });
+ const wasActive = this.activeDocName === docName;
+ void this.runCloseAndClearPersistence(docName);
+ const reopened = this.open(docName);
+ if (reopened !== null && wasActive) this.setActive(docName);
+ return;
+ }
const _never: never = typed;
void _never;
};
@@ -1139,9 +1269,9 @@ export class ProviderPool {
}
}
- const branch = this.getOrInitObservedBranch();
+ const branch = this.normalizedObservedBranch();
const serverInstanceId = this.cachedServerInstanceId;
- if (branch === null || serverInstanceId === null) return;
+ if (serverInstanceId === null) return;
const dbName = `ok-ydoc:${branch}:${serverInstanceId}:${docName}`;
try {
@@ -1229,6 +1359,8 @@ export class ProviderPool {
this.bufferedUpdates.clear();
this.pendingClears.clear();
this.clearFailures.clear();
+ this.docLineageEpochs.clear();
+ this.docLineageEpochsEnvelopeConsumed = false;
this.onBranchMismatch = null;
this.branchMismatchInFlight = null;
this.onRenameRedirect = null;
diff --git a/packages/app/tests/integration/stale-idb-doc-reload.test.ts b/packages/app/tests/integration/stale-idb-doc-reload.test.ts
new file mode 100644
index 000000000..dbeb48120
--- /dev/null
+++ b/packages/app/tests/integration/stale-idb-doc-reload.test.ts
@@ -0,0 +1,129 @@
+import './idb-preload';
+import { afterEach, describe, expect, test } from 'bun:test';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as Y from 'yjs';
+import {
+ createClientPersistence,
+ UNKNOWN_BRANCH_SENTINEL,
+} from '../../src/editor/client-persistence';
+import { ProviderPool } from '../../src/editor/provider-pool';
+import {
+ awaitFileWatcherIndexed,
+ createTestServer,
+ getServerState,
+ pollUntil,
+ seedPoolServerInstanceId,
+ wait,
+} from './test-harness';
+
+const FIXTURE_V1 = `# Lineage Fixture
+
+Stable paragraph: shared marker LINEAGE-ALPHA.
+
+## Session One Section
+
+Paragraph with marker LINEAGE-V1-ONLY that the rewrite removes.
+`;
+
+const FIXTURE_V2 = `# Lineage Fixture
+
+Stable paragraph: shared marker LINEAGE-ALPHA.
+
+## Session Two Section
+
+Paragraph with marker LINEAGE-V2-ONLY introduced by the rewrite.
+`;
+
+function countOccurrences(haystack: string, needle: string): number {
+ return haystack.split(needle).length - 1;
+}
+
+async function readPersistedYtext(docName: string, serverInstanceId: string): Promise<string> {
+ const doc = new Y.Doc();
+ const persistence = createClientPersistence({
+ branch: UNKNOWN_BRANCH_SENTINEL,
+ serverInstanceId,
+ docName,
+ doc,
+ });
+ try {
+ await persistence.whenSynced;
+ return doc.getText('source').toString();
+ } finally {
+ await persistence.destroy();
+ doc.destroy();
+ }
+}
+
+const cleanups: Array<() => Promise<void> | void> = [];
+
+afterEach(async () => {
+ while (cleanups.length > 0) {
+ await cleanups.pop()?.();
+ }
+});
+
+describe('client-persisted state meets a re-seeded doc lineage (same server instance)', () => {
+ test('reopening a doc the server unloaded and re-seeded from disk shows the disk content exactly once', async () => {
+ const server = await createTestServer();
+ cleanups.push(() => server.cleanup());
+
+ const docName = `lineage-${crypto.randomUUID()}`;
+ const filePath = join(server.contentDir, `${docName}.md`);
+ writeFileSync(filePath, FIXTURE_V1, 'utf-8');
+ await awaitFileWatcherIndexed(server, docName);
+
+ const pool = new ProviderPool(3, `ws://localhost:${server.port}/collab`);
+ cleanups.push(() => pool.dispose());
+ const serverInstanceId = await seedPoolServerInstanceId(server, pool);
+
+ pool.open(docName);
+ pool.setActive(docName);
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);
+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 15_000, 50);
+ const session1Text = pool.getActive()?.provider.document.getText('source').toString() ?? '';
+ expect(countOccurrences(session1Text, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(session1Text, 'LINEAGE-V1-ONLY')).toBe(1);
+
+ await pollUntil(
+ async () =>
+ countOccurrences(await readPersistedYtext(docName, serverInstanceId), 'LINEAGE-V1-ONLY') >
+ 0,
+ 10_000,
+ 100,
+ );
+
+ pool.close(docName);
+
+ rmSync(filePath);
+ await pollUntil(() => getServerState(server, docName) === null, 20_000, 100);
+ writeFileSync(filePath, FIXTURE_V2, 'utf-8');
+ await awaitFileWatcherIndexed(server, docName);
+
+ pool.open(docName);
+ pool.setActive(docName);
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);
+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 15_000, 50);
+ await wait(500);
+
+ const clientYtext = (): string =>
+ pool.getActive()?.provider.document.getText('source').toString() ?? '';
+ const serverYtext = (): string => getServerState(server, docName)?.ytext.toString() ?? '';
+
+ const clientText = clientYtext();
+ expect(countOccurrences(clientText, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(clientText, 'LINEAGE-V1-ONLY')).toBe(0);
+ expect(countOccurrences(clientText, 'LINEAGE-V2-ONLY')).toBe(1);
+
+ await pollUntil(() => clientYtext().length > 0 && clientYtext() === serverYtext(), 10_000, 100);
+ expect(clientYtext()).toBe(FIXTURE_V2);
+ expect(countOccurrences(serverYtext(), 'LINEAGE-ALPHA')).toBe(1);
+
+ await wait(1500);
+ const diskContent = readFileSync(filePath, 'utf-8');
+ expect(countOccurrences(diskContent, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(diskContent, 'LINEAGE-V1-ONLY')).toBe(0);
+ expect(countOccurrences(diskContent, 'LINEAGE-V2-ONLY')).toBe(1);
+ }, 120_000);
+});
diff --git a/packages/app/tests/integration/stale-idb-lineage-doors.test.ts b/packages/app/tests/integration/stale-idb-lineage-doors.test.ts
new file mode 100644
index 000000000..69721f025
--- /dev/null
+++ b/packages/app/tests/integration/stale-idb-lineage-doors.test.ts
@@ -0,0 +1,231 @@
+import './idb-preload';
+import { afterEach, describe, expect, test } from 'bun:test';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as Y from 'yjs';
+import {
+ createClientPersistence,
+ UNKNOWN_BRANCH_SENTINEL,
+} from '../../src/editor/client-persistence';
+import { ProviderPool } from '../../src/editor/provider-pool';
+import {
+ awaitFileWatcherIndexed,
+ createTestServer,
+ getServerState,
+ pollUntil,
+ seedPoolServerInstanceId,
+ wait,
+} from './test-harness';
+
+const FIXTURE_V1 = `# Lineage Fixture
+
+Stable paragraph: shared marker LINEAGE-ALPHA.
+
+## Session One Section
+
+Paragraph with marker LINEAGE-V1-ONLY that the rewrite removes.
+`;
+
+const FIXTURE_V2 = `# Lineage Fixture
+
+Stable paragraph: shared marker LINEAGE-ALPHA.
+
+## Session Two Section
+
+Paragraph with marker LINEAGE-V2-ONLY introduced by the rewrite.
+`;
+
+function countOccurrences(haystack: string, needle: string): number {
+ return haystack.split(needle).length - 1;
+}
+
+async function readPersistedYtext(docName: string, serverInstanceId: string): Promise<string> {
+ const doc = new Y.Doc();
+ const persistence = createClientPersistence({
+ branch: UNKNOWN_BRANCH_SENTINEL,
+ serverInstanceId,
+ docName,
+ doc,
+ });
+ try {
+ await persistence.whenSynced;
+ return doc.getText('source').toString();
+ } finally {
+ await persistence.destroy();
+ doc.destroy();
+ }
+}
+
+function makeStubStorage(): {
+ stub: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+ store: Map<string, string>;
+} {
+ const store = new Map<string, string>();
+ const stub = {
+ getItem: (k: string) => store.get(k) ?? null,
+ setItem: (k: string, v: string) => {
+ store.set(k, v);
+ },
+ removeItem: (k: string) => {
+ store.delete(k);
+ },
+ };
+ return { stub, store };
+}
+
+const cleanups: Array<() => Promise<void> | void> = [];
+
+afterEach(async () => {
+ while (cleanups.length > 0) {
+ await cleanups.pop()?.();
+ }
+});
+
+describe('client-persisted state meets a re-seeded doc lineage (deferred-attach door)', () => {
+ test('an instance id learned after sync must not hydrate a stale lineage into the live doc', async () => {
+ const server = await createTestServer();
+ cleanups.push(() => server.cleanup());
+
+ const docName = `lineage-deferred-${crypto.randomUUID()}`;
+ const filePath = join(server.contentDir, `${docName}.md`);
+ writeFileSync(filePath, FIXTURE_V1, 'utf-8');
+ await awaitFileWatcherIndexed(server, docName);
+
+ const pool = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {
+ storage: makeStubStorage().stub,
+ });
+ cleanups.push(() => pool.dispose());
+ const serverInstanceId = await seedPoolServerInstanceId(server, pool);
+
+ pool.open(docName);
+ pool.setActive(docName);
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);
+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 15_000, 50);
+ const session1Text = pool.getActive()?.provider.document.getText('source').toString() ?? '';
+ expect(countOccurrences(session1Text, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(session1Text, 'LINEAGE-V1-ONLY')).toBe(1);
+
+ await pollUntil(
+ async () =>
+ countOccurrences(await readPersistedYtext(docName, serverInstanceId), 'LINEAGE-V1-ONLY') >
+ 0,
+ 10_000,
+ 100,
+ );
+
+ pool.close(docName);
+
+ rmSync(filePath);
+ await pollUntil(() => getServerState(server, docName) === null, 20_000, 100);
+ writeFileSync(filePath, FIXTURE_V2, 'utf-8');
+ await awaitFileWatcherIndexed(server, docName);
+
+ pool.setExpectedServerInstanceId(null);
+
+ pool.open(docName);
+ pool.setActive(docName);
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);
+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 15_000, 50);
+
+ const clientYtext = (): string =>
+ pool.getActive()?.provider.document.getText('source').toString() ?? '';
+ const serverYtext = (): string => getServerState(server, docName)?.ytext.toString() ?? '';
+
+ const preAttachText = clientYtext();
+ expect(countOccurrences(preAttachText, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(preAttachText, 'LINEAGE-V1-ONLY')).toBe(0);
+ expect(countOccurrences(preAttachText, 'LINEAGE-V2-ONLY')).toBe(1);
+
+ await seedPoolServerInstanceId(server, pool);
+
+ await pollUntil(() => (pool.getActive()?.persistence ?? null) !== null, 15_000, 50);
+ await pool.getActive()?.persistence?.whenSynced;
+ await pollUntil(() => pool.getActive()?.provider.isSynced === true, 15_000, 50);
+ await pollUntil(() => pool.getActive()?.provider.unsyncedChanges === 0, 15_000, 50);
+ await wait(500);
+
+ const clientText = clientYtext();
+ expect(countOccurrences(clientText, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(clientText, 'LINEAGE-V1-ONLY')).toBe(0);
+ expect(countOccurrences(clientText, 'LINEAGE-V2-ONLY')).toBe(1);
+
+ await pollUntil(() => clientYtext().length > 0 && clientYtext() === serverYtext(), 10_000, 100);
+ expect(clientYtext()).toBe(FIXTURE_V2);
+ expect(countOccurrences(serverYtext(), 'LINEAGE-ALPHA')).toBe(1);
+
+ await wait(1500);
+ const diskContent = readFileSync(filePath, 'utf-8');
+ expect(countOccurrences(diskContent, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(diskContent, 'LINEAGE-V1-ONLY')).toBe(0);
+ expect(countOccurrences(diskContent, 'LINEAGE-V2-ONLY')).toBe(1);
+ }, 120_000);
+});
+
+describe('client-persisted state meets a re-seeded doc lineage (fresh-pool rejoin door)', () => {
+ test('a brand-new pool reopening a doc the server unloaded and re-seeded shows the disk content exactly once', async () => {
+ const server = await createTestServer();
+ cleanups.push(() => server.cleanup());
+
+ const docName = `lineage-freshpool-${crypto.randomUUID()}`;
+ const filePath = join(server.contentDir, `${docName}.md`);
+ writeFileSync(filePath, FIXTURE_V1, 'utf-8');
+ await awaitFileWatcherIndexed(server, docName);
+
+ const wsUrl = `ws://localhost:${server.port}/collab`;
+ const { stub: sharedStorage } = makeStubStorage();
+
+ const poolA = new ProviderPool(3, wsUrl, { storage: sharedStorage });
+ cleanups.push(() => poolA.dispose());
+ const serverInstanceId = await seedPoolServerInstanceId(server, poolA);
+ poolA.open(docName);
+ poolA.setActive(docName);
+ await pollUntil(() => poolA.getActive()?.provider.isSynced === true, 15_000, 50);
+ await pollUntil(() => poolA.getActive()?.provider.unsyncedChanges === 0, 15_000, 50);
+ const session1Text = poolA.getActive()?.provider.document.getText('source').toString() ?? '';
+ expect(countOccurrences(session1Text, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(session1Text, 'LINEAGE-V1-ONLY')).toBe(1);
+
+ await pollUntil(
+ async () =>
+ countOccurrences(await readPersistedYtext(docName, serverInstanceId), 'LINEAGE-V1-ONLY') >
+ 0,
+ 10_000,
+ 100,
+ );
+
+ poolA.dispose();
+
+ rmSync(filePath);
+ await pollUntil(() => getServerState(server, docName) === null, 20_000, 100);
+ writeFileSync(filePath, FIXTURE_V2, 'utf-8');
+ await awaitFileWatcherIndexed(server, docName);
+
+ const poolB = new ProviderPool(3, wsUrl, { storage: sharedStorage });
+ cleanups.push(() => poolB.dispose());
+ await seedPoolServerInstanceId(server, poolB);
+ poolB.open(docName);
+ poolB.setActive(docName);
+ await pollUntil(() => poolB.getActive()?.provider.isSynced === true, 15_000, 50);
+ await pollUntil(() => poolB.getActive()?.provider.unsyncedChanges === 0, 15_000, 50);
+ await wait(500);
+
+ const clientYtext = (): string =>
+ poolB.getActive()?.provider.document.getText('source').toString() ?? '';
+ const serverYtext = (): string => getServerState(server, docName)?.ytext.toString() ?? '';
+
+ const clientText = clientYtext();
+ expect(countOccurrences(clientText, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(clientText, 'LINEAGE-V1-ONLY')).toBe(0);
+ expect(countOccurrences(clientText, 'LINEAGE-V2-ONLY')).toBe(1);
+
+ await pollUntil(() => clientYtext().length > 0 && clientYtext() === serverYtext(), 10_000, 100);
+ expect(clientYtext()).toBe(FIXTURE_V2);
+ expect(countOccurrences(serverYtext(), 'LINEAGE-ALPHA')).toBe(1);
+
+ await wait(1500);
+ const diskContent = readFileSync(filePath, 'utf-8');
+ expect(countOccurrences(diskContent, 'LINEAGE-ALPHA')).toBe(1);
+ expect(countOccurrences(diskContent, 'LINEAGE-V1-ONLY')).toBe(0);
+ expect(countOccurrences(diskContent, 'LINEAGE-V2-ONLY')).toBe(1);
+ }, 120_000);
+});
diff --git a/packages/core/src/constants/doc-lifecycle.ts b/packages/core/src/constants/doc-lifecycle.ts
new file mode 100644
index 000000000..0e13ed631
--- /dev/null
+++ b/packages/core/src/constants/doc-lifecycle.ts
@@ -0,0 +1 @@
+export const LINEAGE_EPOCH_KEY = 'epoch';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index b04c604f4..4696a7392 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -161,6 +161,7 @@ export {
CREATE_NEW_PROJECT_FAILURE_REASONS,
type CreateNewProjectFailureReason,
} from './constants/create-new-project-reason.ts';
+export { LINEAGE_EPOCH_KEY } from './constants/doc-lifecycle.ts';
export {
DOCUMENT_OPEN_BYTE_LIMIT,
isDocumentOverOpenByteLimit,
diff --git a/packages/server/src/auth-token-schema.test.ts b/packages/server/src/auth-token-schema.test.ts
index 6bafd184f..591bb585c 100644
--- a/packages/server/src/auth-token-schema.test.ts
+++ b/packages/server/src/auth-token-schema.test.ts
@@ -9,10 +9,11 @@ import {
} from './auth-token-schema.ts';
describe('HOCUSPOCUS_AUTH_REJECTION_REASONS', () => {
- it('contains the four wire reasons used by server-side throws', () => {
+ it('contains the five wire reasons used by server-side throws', () => {
expect([...HOCUSPOCUS_AUTH_REJECTION_REASONS].sort()).toEqual([
'branch-mismatch',
'doc-deleted',
+ 'doc-lineage-mismatch',
'rename-redirect',
'server-instance-mismatch',
]);
diff --git a/packages/server/src/auth-token-schema.ts b/packages/server/src/auth-token-schema.ts
index e48438ce3..e6a12cb37 100644
--- a/packages/server/src/auth-token-schema.ts
+++ b/packages/server/src/auth-token-schema.ts
@@ -1,3 +1,4 @@
+import { LINEAGE_EPOCH_KEY } from '@inkeep/open-knowledge-core';
import { z } from 'zod';
export const HocuspocusAuthTokenSchema = z
@@ -6,6 +7,7 @@ export const HocuspocusAuthTokenSchema = z
tabSessionId: z.string().optional(),
expectedServerInstanceId: z.string().optional(),
expectedBranch: z.string().optional(),
+ expectedDocLineageEpoch: z.string().optional(),
clientProtocolVersion: z.number().optional(),
clientRuntimeVersion: z.string().optional(),
clientKind: z.string().optional(),
@@ -14,11 +16,14 @@ export const HocuspocusAuthTokenSchema = z
export type HocuspocusAuthToken = z.infer<typeof HocuspocusAuthTokenSchema>;
+export { LINEAGE_EPOCH_KEY };
+
export const HOCUSPOCUS_AUTH_REJECTION_REASONS = [
'server-instance-mismatch',
'branch-mismatch',
'rename-redirect',
'doc-deleted',
+ 'doc-lineage-mismatch',
] as const;
export type HocuspocusAuthRejectionReason = (typeof HOCUSPOCUS_AUTH_REJECTION_REASONS)[number];
diff --git a/packages/server/src/doc-lineage-guard.test.ts b/packages/server/src/doc-lineage-guard.test.ts
new file mode 100644
index 000000000..35920c0aa
--- /dev/null
+++ b/packages/server/src/doc-lineage-guard.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+import { HocuspocusAuthRejection, LINEAGE_EPOCH_KEY } from './auth-token-schema.ts';
+import { type DocLineageGuardDeps, runDocLineageGuard } from './doc-lineage-guard.ts';
+import { getMetrics, resetMetrics } from './metrics.ts';
+
+const docs: Y.Doc[] = [];
+
+function liveDoc(epoch?: unknown): Y.Doc {
+ const doc = new Y.Doc();
+ docs.push(doc);
+ if (epoch !== undefined) {
+ doc.getMap('lifecycle').set(LINEAGE_EPOCH_KEY, epoch);
+ }
+ return doc;
+}
+
+function depsFor(doc: Y.Doc | undefined): DocLineageGuardDeps {
+ return { getLoadedDoc: () => doc };
+}
+
+function expectRejection(fn: () => void): HocuspocusAuthRejection {
+ let caught: unknown;
+ try {
+ fn();
+ } catch (e) {
+ caught = e;
+ }
+ expect(caught).toBeInstanceOf(HocuspocusAuthRejection);
+ return caught as HocuspocusAuthRejection;
+}
+
+beforeEach(() => {
+ resetMetrics();
+});
+
+afterEach(() => {
+ while (docs.length > 0) {
+ docs.pop()?.destroy();
+ }
+ resetMetrics();
+});
+
+describe('runDocLineageGuard', () => {
+ test('admits absent and empty claims unconditionally, even for unloaded docs', () => {
+ expect(() => runDocLineageGuard('notes/a', undefined, depsFor(undefined))).not.toThrow();
+ expect(() => runDocLineageGuard('notes/a', '', depsFor(undefined))).not.toThrow();
+ });
+
+ test('short-circuits system and config docs before any doc lookup', () => {
+ const deps: DocLineageGuardDeps = {
+ getLoadedDoc: () => {
+ throw new Error('must not be consulted for synthetic docs');
+ },
+ };
+ expect(() => runDocLineageGuard('__system__', 'epoch-1', deps)).not.toThrow();
+ expect(() => runDocLineageGuard('__config__/project', 'epoch-1', deps)).not.toThrow();
+ expect(() => runDocLineageGuard('__user__/config.yml', 'epoch-1', deps)).not.toThrow();
+ });
+
+ test('rejects a claim against an unloaded doc (stale by construction)', () => {
+ const err = expectRejection(() => runDocLineageGuard('notes/a', 'epoch-1', depsFor(undefined)));
+ expect(err.kind).toBe('doc-lineage-mismatch');
+ expect(err.payload).toBeUndefined();
+ expect(err.reason).toBe('doc-lineage-mismatch');
+ });
+
+ test('rejects when the live doc carries no epoch', () => {
+ const err = expectRejection(() => runDocLineageGuard('notes/a', 'epoch-1', depsFor(liveDoc())));
+ expect(err.kind).toBe('doc-lineage-mismatch');
+ });
+
+ test('rejects when the live epoch is the empty string and a claim is present', () => {
+ const err = expectRejection(() =>
+ runDocLineageGuard('notes/a', 'epoch-1', depsFor(liveDoc(''))),
+ );
+ expect(err.kind).toBe('doc-lineage-mismatch');
+ });
+
+ test('rejects when the live epoch differs from the claim', () => {
+ const err = expectRejection(() =>
+ runDocLineageGuard('notes/a', 'epoch-old', depsFor(liveDoc('epoch-new'))),
+ );
+ expect(err.kind).toBe('doc-lineage-mismatch');
+ });
+
+ test('rejects when the live epoch is present but not a string', () => {
+ const err = expectRejection(() => runDocLineageGuard('notes/a', '42', depsFor(liveDoc(42))));
+ expect(err.kind).toBe('doc-lineage-mismatch');
+ });
+
+ test('admits when the claim matches the live epoch exactly', () => {
+ expect(() =>
+ runDocLineageGuard('notes/a', 'epoch-1', depsFor(liveDoc('epoch-1'))),
+ ).not.toThrow();
+ });
+
+ test('admits (fail-open) when the dependency throws unexpectedly', () => {
+ const deps: DocLineageGuardDeps = {
+ getLoadedDoc: () => {
+ throw new Error('synthetic registry failure');
+ },
+ };
+ expect(() => runDocLineageGuard('notes/a', 'epoch-1', deps)).not.toThrow();
+ });
+
+ test('increments the mismatch counter on each rejection arm', () => {
+ expectRejection(() => runDocLineageGuard('notes/a', 'epoch-1', depsFor(undefined)));
+ expect(getMetrics().authDocLineageMismatchCount).toBe(1);
+ expectRejection(() =>
+ runDocLineageGuard('notes/a', 'epoch-old', depsFor(liveDoc('epoch-new'))),
+ );
+ expect(getMetrics().authDocLineageMismatchCount).toBe(2);
+ expect(getMetrics().authDocLineageGuardErrors).toBe(0);
+ });
+
+ test('does not increment any counter on admits (absent claim, synthetic doc, exact match)', () => {
+ runDocLineageGuard('notes/a', undefined, depsFor(undefined));
+ runDocLineageGuard('__system__', 'epoch-1', depsFor(undefined));
+ runDocLineageGuard('notes/a', 'epoch-1', depsFor(liveDoc('epoch-1')));
+ expect(getMetrics().authDocLineageMismatchCount).toBe(0);
+ expect(getMetrics().authDocLineageGuardErrors).toBe(0);
+ });
+
+ test('increments the guard-error counter on fail-open, not the mismatch counter', () => {
+ const deps: DocLineageGuardDeps = {
+ getLoadedDoc: () => {
+ throw new Error('synthetic registry failure');
+ },
+ };
+ runDocLineageGuard('notes/a', 'epoch-1', deps);
+ expect(getMetrics().authDocLineageGuardErrors).toBe(1);
+ expect(getMetrics().authDocLineageMismatchCount).toBe(0);
+ });
+
+ test('HocuspocusAuthRejection rethrow path does NOT increment the guard-error counter', () => {
+ expectRejection(() => runDocLineageGuard('notes/a', 'epoch-1', depsFor(undefined)));
+ expect(getMetrics().authDocLineageGuardErrors).toBe(0);
+ });
+});
+
+test('LINEAGE_EPOCH_KEY wire value is stable', () => {
+ expect(LINEAGE_EPOCH_KEY).toBe('epoch');
+});
diff --git a/packages/server/src/doc-lineage-guard.ts b/packages/server/src/doc-lineage-guard.ts
new file mode 100644
index 000000000..042346f39
--- /dev/null
+++ b/packages/server/src/doc-lineage-guard.ts
@@ -0,0 +1,51 @@
+import type * as Y from 'yjs';
+import { HocuspocusAuthRejection, LINEAGE_EPOCH_KEY } from './auth-token-schema.ts';
+import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';
+import { incrementAuthDocLineageGuardError, incrementAuthDocLineageMismatch } from './metrics.ts';
+import { setActiveSpanAttributes } from './telemetry.ts';
+
+export interface DocLineageGuardDeps {
+ getLoadedDoc: (documentName: string) => Y.Doc | undefined;
+}
+
+export function runDocLineageGuard(
+ documentName: string,
+ claimedEpoch: string | undefined,
+ deps: DocLineageGuardDeps,
+): void {
+ try {
+ if (typeof claimedEpoch !== 'string' || claimedEpoch.length === 0) return;
+ if (isSystemDoc(documentName) || isConfigDoc(documentName)) return;
+
+ const doc = deps.getLoadedDoc(documentName);
+ if (doc === undefined) {
+ incrementAuthDocLineageMismatch();
+ setActiveSpanAttributes({ 'auth.reason': 'doc-lineage-mismatch' });
+ throw new HocuspocusAuthRejection(
+ 'doc-lineage-mismatch',
+ `doc lineage mismatch: claim against unloaded ${documentName} is stale by construction`,
+ );
+ }
+
+ const liveEpoch = doc.getMap('lifecycle').get(LINEAGE_EPOCH_KEY);
+ if (typeof liveEpoch !== 'string' || liveEpoch.length === 0 || liveEpoch !== claimedEpoch) {
+ incrementAuthDocLineageMismatch();
+ setActiveSpanAttributes({ 'auth.reason': 'doc-lineage-mismatch' });
+ throw new HocuspocusAuthRejection(
+ 'doc-lineage-mismatch',
+ `doc lineage mismatch for ${documentName}: claimed epoch does not match the live lineage`,
+ );
+ }
+ } catch (err) {
+ if (err instanceof HocuspocusAuthRejection) throw err;
+ incrementAuthDocLineageGuardError();
+ console.warn(
+ JSON.stringify({
+ event: 'doc-lineage-guard-error',
+ documentName,
+ errorName: err instanceof Error ? err.name : typeof err,
+ message: err instanceof Error ? err.message : String(err),
+ }),
+ );
+ }
+}
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index cf975a79f..0b6099699 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -41,6 +41,7 @@ export {
type HocuspocusAuthToken,
HocuspocusAuthTokenSchema,
isHocuspocusAuthRejectionReason,
+ LINEAGE_EPOCH_KEY,
parseAuthRejectionWire,
parseHocuspocusAuthToken,
} from './auth-token-schema.ts';
diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.ts
index e4dc8a873..8a2faedb2 100644
--- a/packages/server/src/metrics.ts
+++ b/packages/server/src/metrics.ts
@@ -252,6 +252,28 @@ export interface ReconciliationMetrics {
* non-zero indicates a cache populator is producing inconsistent
* rename pairs and the defense is silently degrading. */
removalRedirectChainCycles: number;
+ /** Count of WebSocket connections rejected by `docLineageGuard` with the
+ * `'doc-lineage-mismatch'` reason — a client claimed a lineage epoch that
+ * doesn't match the live doc (or claimed against an unloaded doc, stale
+ * by construction). Each rejection is one prevented union-merge of a dead
+ * materialization, at the cost of a client close → clearIDB → reopen
+ * round-trip. Steady-state near-zero with bursts after external
+ * delete/recreate or rename; a high steady rate means the epoch minting
+ * or the client's record bookkeeping has drifted and every connection is
+ * paying the recovery round-trip. Lifetime total: the operator signal is
+ * the growth rate computed at the metrics consumer (burst = expected;
+ * sustained = drifted bookkeeping), not the absolute value. */
+ authDocLineageMismatchCount: number;
+ /** Count of `docLineageGuard` invocations that fell through to admit via
+ * the defensive try/catch — same fail-open philosophy and observability
+ * rationale as `authRemovalGuardErrors`: each fall-through silently
+ * disables the stale-lineage fence for that connection, so non-zero
+ * growth (correlated with `doc-lineage-guard-error` warns) means the
+ * corruption class the fence exists to prevent can reach docs unnoticed.
+ * Lifetime total with no built-in threshold: alert on sustained growth
+ * rate at the metrics consumer — a one-time blip is a transient, a
+ * climbing rate means the fence is silently disabled under live traffic. */
+ authDocLineageGuardErrors: number;
}
const counters: ReconciliationMetrics = {
@@ -302,6 +324,8 @@ const counters: ReconciliationMetrics = {
recentlyRemovedDocsSize: 0,
authRemovalGuardErrors: 0,
removalRedirectChainCycles: 0,
+ authDocLineageMismatchCount: 0,
+ authDocLineageGuardErrors: 0,
};
export function incrementReconcile(): void {
@@ -459,6 +483,14 @@ export function incrementRemovalRedirectChainCycle(): void {
counters.removalRedirectChainCycles++;
}
+export function incrementAuthDocLineageMismatch(): void {
+ counters.authDocLineageMismatchCount++;
+}
+
+export function incrementAuthDocLineageGuardError(): void {
+ counters.authDocLineageGuardErrors++;
+}
+
export function incrementCollabSocketFilteredError(code: 'EPIPE' | 'ECONNRESET'): void {
if (code === 'EPIPE') counters.collabSocketEpipeCount++;
else counters.collabSocketEconnresetCount++;
@@ -548,4 +580,6 @@ export function resetMetrics(): void {
counters.recentlyRemovedDocsSize = 0;
counters.authRemovalGuardErrors = 0;
counters.removalRedirectChainCycles = 0;
+ counters.authDocLineageMismatchCount = 0;
+ counters.authDocLineageGuardErrors = 0;
}
diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.ts
index 2f7605185..eca156d76 100644
--- a/packages/server/src/persistence.ts
+++ b/packages/server/src/persistence.ts
@@ -23,6 +23,7 @@ import {
import type { JSONContent } from '@tiptap/core';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import * as Y from 'yjs';
+import { LINEAGE_EPOCH_KEY } from './auth-token-schema.ts';
import type { BacklinkIndex } from './backlink-index.ts';
import { getMsSinceLastUserTx, isDocQuiescent } from './bridge-quiescence.ts';
import { assertBridgeInvariant } from './bridge-watchdog.ts';
@@ -1215,6 +1216,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
documentName,
options?.resolveSize,
);
+ document.getMap('lifecycle').set(LINEAGE_EPOCH_KEY, crypto.randomUUID());
}, FILE_WATCHER_ORIGIN);
log.info(
{ filePath, children: xmlFragment.length },
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 6a8391825..09f761286 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -46,6 +46,7 @@ import { isDocInConflict } from './conflict-errors.ts';
import { createConflictLifecycleSeedExtension } from './conflict-lifecycle-seed.ts';
import { type ContentFilter, createContentFilter } from './content-filter.ts';
import { getDocExtension, stripDocExtension } from './doc-extensions.ts';
+import { runDocLineageGuard } from './doc-lineage-guard.ts';
import {
DEFAULT_EMBEDDINGS_DIMENSIONS,
type Embedder,
@@ -615,6 +616,17 @@ export function createServer(options: ServerOptions): ServerInstance {
};
hocuspocus.configuration.extensions.push(removalRedirectGuard);
+ const docLineageGuard: Extension & { __kind: 'doc-lineage-guard' } = {
+ __kind: 'doc-lineage-guard',
+ async onAuthenticate(payload) {
+ const parsed = parseHocuspocusAuthToken(payload.token);
+ runDocLineageGuard(payload.documentName, parsed?.expectedDocLineageEpoch, {
+ getLoadedDoc: (name) => hocuspocus.documents.get(name),
+ });
+ },
+ };
+ hocuspocus.configuration.extensions.push(docLineageGuard);
+
const systemDocBroadcastGuard: Extension & { __kind: 'system-doc-broadcast-guard' } = {
__kind: 'system-doc-broadcast-guard',
async beforeHandleMessage(payload) {