Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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 versparseHocuspocusAuthToken(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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 = ztabSessionId: 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 = zexport 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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): PersisdocumentName,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.tsindex 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) {