Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): fence record-absent lineage ingress (PRD-6967 on-HEAD doors) (#1806)
Nick Gomez75eeca43f6f0
diff --git a/packages/app/src/editor/branch-invalidation.test.ts b/packages/app/src/editor/branch-invalidation.test.tsindex ecd8b263c..9709fc5e6 100644--- a/packages/app/src/editor/branch-invalidation.test.ts+++ b/packages/app/src/editor/branch-invalidation.test.ts@@ -17,6 +17,18 @@ function docName(prefix = 'branch-inv'): string {return `${prefix}-${randomUUID()}`;}+async function awaitAttachedPersistence(entry: {+ persistence: { clearData(): Promise<void> } | null;+}): Promise<{ clearData(): Promise<void> }> {+ const deadline = Date.now() + 2_000;+ while (entry.persistence === null && Date.now() < deadline) {+ await new Promise<void>((resolve) => setTimeout(resolve, 10));+ }+ const persistence = entry.persistence;+ if (persistence === null) throw new Error('expected persistence to attach');+ return persistence;+}+describe('handleBranchSwitched', () => {test("calls clearData on every entry's persistence", async () => {pool = new ProviderPool(3, DUMMY_WS);@@ -26,12 +38,13 @@ describe('handleBranchSwitched', () => {const e1 = pool.open(d1);const e2 = pool.open(d2);if (!e1 || !e2) throw new Error('pool.open returned null');- if (!e1.persistence || !e2.persistence) throw new Error('entry missing persistence');+ const p1 = await awaitAttachedPersistence(e1);+ const p2 = await awaitAttachedPersistence(e2);const clear1 = mock(() => Promise.resolve());const clear2 = mock(() => Promise.resolve());- e1.persistence.clearData = clear1;- e2.persistence.clearData = clear2;+ p1.clearData = clear1;+ p2.clearData = clear2;await handleBranchSwitched(pool, 'feature');@@ -47,7 +60,8 @@ describe('handleBranchSwitched', () => {const e1 = pool.open(d1);const e2 = pool.open(d2);if (!e1 || !e2) throw new Error('pool.open returned null');- if (!e1.persistence || !e2.persistence) throw new Error('entry missing persistence');+ const p1 = await awaitAttachedPersistence(e1);+ const p2 = await awaitAttachedPersistence(e2);let clearResolved = false;const clearPromise = new Promise<void>((resolve) => {@@ -56,8 +70,8 @@ describe('handleBranchSwitched', () => {resolve();}, 20);});- e1.persistence.clearData = mock(() => clearPromise);- e2.persistence.clearData = mock(() => Promise.resolve());+ p1.clearData = mock(() => clearPromise);+ p2.clearData = mock(() => Promise.resolve());let recycleObservedClearResolved = false;const originalRecycle = pool.recycleAllEntries.bind(pool);@@ -81,12 +95,13 @@ describe('handleBranchSwitched', () => {const e2 = pool.open(d2);if (!e1 || !e2) throw new Error('pool.open returned null');if (e1.kind !== 'active' || e2.kind !== 'active') throw new Error('expected active');- if (!e1.persistence || !e2.persistence) throw new Error('entry missing persistence');+ const p1 = await awaitAttachedPersistence(e1);+ const p2 = await awaitAttachedPersistence(e2);const clear1 = mock(() => Promise.resolve());const clear2 = mock(() => Promise.resolve());- e1.persistence.clearData = clear1;- e2.persistence.clearData = clear2;+ p1.clearData = clear1;+ p2.clearData = clear2;const torn = e1 as unknown as {kind: 'tearing-down';@@ -108,11 +123,10 @@ describe('handleBranchSwitched', () => {pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const d1 = docName('d1');const e1 = pool.open(d1);- if (!e1?.persistence) throw new Error('pool.open returned null');+ if (!e1) throw new Error('pool.open returned null');+ const p1 = await awaitAttachedPersistence(e1);- e1.persistence.clearData = mock(() =>- Promise.reject(new Error('simulated-idb-quota-exhausted')),- );+ p1.clearData = mock(() => Promise.reject(new Error('simulated-idb-quota-exhausted')));const originalRecycle = pool.recycleAllEntries.bind(pool);const recycleSpy = mock(() => {diff --git a/packages/app/src/editor/client-persistence.test.ts b/packages/app/src/editor/client-persistence.test.tsindex 11c2fbcc7..d92c4da0a 100644--- a/packages/app/src/editor/client-persistence.test.ts+++ b/packages/app/src/editor/client-persistence.test.ts@@ -7,6 +7,7 @@ import {computeUnsyncedUpdate,createClientPersistence,mergeStateVectors,+ peekStoredLineageEpoch,} from './client-persistence';function uniqueDocName(prefix = 'cp-test'): string {@@ -60,6 +61,39 @@ async function countPersistedUpdates(});}+async function readPersistedUpdates(+ branch: string,+ serverInstanceId: string,+ docName: string,+): Promise<unknown[]> {+ const dbName = `ok-ydoc:${branch}:${serverInstanceId}:${docName}`;+ const dbs = await indexedDB.databases();+ if (!dbs.some((d) => d.name === dbName)) return [];++ return new Promise<unknown[]>((resolve, reject) => {+ const req = indexedDB.open(dbName);+ req.onerror = () => reject(req.error);+ req.onsuccess = () => {+ const db = req.result;+ if (!db.objectStoreNames.contains('updates')) {+ db.close();+ resolve([]);+ return;+ }+ const tx = db.transaction('updates', 'readonly');+ const getAll = tx.objectStore('updates').getAll();+ getAll.onsuccess = () => {+ db.close();+ resolve(getAll.result as unknown[]);+ };+ getAll.onerror = () => {+ db.close();+ reject(getAll.error);+ };+ };+ });+}+describe('createClientPersistence', () => {test('creates provider for empty IDB and emits synced event', async () => {const docName = uniqueDocName();@@ -383,6 +417,277 @@ describe('createClientPersistence', () => {});});+describe('peekStoredLineageEpoch', () => {+ test('returns null when no database exists, without breaking a later attach', async () => {+ const docName = uniqueDocName('cp-peek-absent');+ const peeked = await peekStoredLineageEpoch({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ });+ expect(peeked).toBeNull();++ const doc = new Y.Doc();+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc,+ });+ await provider.whenSynced;+ doc.getText('t').insert(0, 'post-peek attach works');+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ await provider.destroy();+ doc.destroy();++ const docB = new Y.Doc();+ const providerB = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc: docB,+ });+ await providerB.whenSynced;+ expect(docB.getText('t').toString()).toBe('post-peek attach works');+ await providerB.destroy();+ docB.destroy();+ });++ test('reads the epoch carried in-band by the stored rows', async () => {+ const docName = uniqueDocName('cp-peek-epoch');+ const doc = new Y.Doc();+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc,+ });+ await provider.whenSynced;+ doc.getMap('lifecycle').set('epoch', 'epoch-stored');+ doc.getText('source').insert(0, 'content under epoch-stored');+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ await provider.destroy();+ doc.destroy();++ const peeked = await peekStoredLineageEpoch({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ });+ expect(peeked).toBe('epoch-stored');+ });++ test('returns null for rows that carry no epoch (pre-epoch writer)', async () => {+ const docName = uniqueDocName('cp-peek-noepoch');+ const doc = new Y.Doc();+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc,+ });+ await provider.whenSynced;+ doc.getText('source').insert(0, 'offline-first content, no lifecycle epoch');+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ await provider.destroy();+ doc.destroy();++ const peeked = await peekStoredLineageEpoch({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ });+ expect(peeked).toBeNull();+ });++ test('does not mutate the stored rows (read-only contract)', async () => {+ const docName = uniqueDocName('cp-peek-readonly');+ const doc = new Y.Doc();+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc,+ });+ await provider.whenSynced;+ doc.getMap('lifecycle').set('epoch', 'epoch-ro');+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ await provider.destroy();+ doc.destroy();++ const before = await countPersistedUpdates(TEST_BRANCH, TEST_SERVER_INSTANCE_ID, docName);+ await peekStoredLineageEpoch({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ });+ const after = await countPersistedUpdates(TEST_BRANCH, TEST_SERVER_INSTANCE_ID, docName);+ expect(after).toBe(before);+ });+});++describe('flushFullState', () => {+ test('persists content the incremental listener never saw (post-sync attach gap-fill)', async () => {+ const docName = uniqueDocName('cp-flush');+ const doc = new Y.Doc();+ doc.getText('source').insert(0, 'delivered before attach');+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc,+ });+ await provider.whenSynced;+ await provider.flushFullState?.();+ await provider.destroy();+ doc.destroy();++ const docB = new Y.Doc();+ const providerB = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc: docB,+ });+ await providerB.whenSynced;+ expect(docB.getText('source').toString()).toBe('delivered before attach');+ await providerB.destroy();+ docB.destroy();+ });++ test('resolves only after the full-state row is committed and superseded rows are trimmed', async () => {+ const docName = uniqueDocName('cp-flush-durable');+ const doc = new Y.Doc();+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc,+ });+ await provider.whenSynced;+ doc.getText('source').insert(0, 'a');+ doc.getText('source').insert(1, 'b');++ await provider.flushFullState();++ const rows = await readPersistedUpdates(TEST_BRANCH, TEST_SERVER_INSTANCE_ID, docName);+ expect(rows.length).toBe(1);+ const fresh = new Y.Doc();+ Y.applyUpdate(fresh, rows[0] as Uint8Array);+ expect(fresh.getText('source').toString()).toBe('ab');+ fresh.destroy();++ await provider.destroy();+ doc.destroy();+ });++ test('rejects instead of hanging when a stored row is malformed', async () => {+ const docName = uniqueDocName('cp-flush-malformed');+ const doc = new Y.Doc();+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ doc,+ docName,+ });+ await provider.whenSynced;+ doc.getText('source').insert(0, 'healthy');+ const dbName = `ok-ydoc:${TEST_BRANCH}:${TEST_SERVER_INSTANCE_ID}:${docName}`;+ await new Promise<void>((resolve, reject) => {+ const req = indexedDB.open(dbName);+ req.onerror = () => reject(req.error);+ req.onsuccess = () => {+ const db = req.result;+ const tx = db.transaction('updates', 'readwrite');+ tx.objectStore('updates').add(new Uint8Array([255, 255, 255]));+ tx.oncomplete = () => {+ db.close();+ resolve();+ };+ tx.onabort = () => {+ db.close();+ reject(tx.error);+ };+ };+ });++ await expect(provider.flushFullState()).rejects.toThrow();++ await provider.destroy();+ doc.destroy();+ });+});++describe('peekStoredLineageEpoch without indexedDB.databases()', () => {+ async function withoutDatabasesEnumeration(run: () => Promise<void>): Promise<void> {+ const factory = indexedDB as unknown as Record<string, unknown>;+ const original = factory.databases;+ factory.databases = undefined;+ try {+ await run();+ } finally {+ factory.databases = original;+ }+ }++ test('peek of a never-persisted doc returns null', async () => {+ await withoutDatabasesEnumeration(async () => {+ const docName = uniqueDocName('cp-peek-nodbs-null');+ const epoch = await peekStoredLineageEpoch({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ });+ expect(epoch).toBeNull();+ });+ });++ test('a peek-created DB does not break the later real attach, and a second peek reads its rows', async () => {+ await withoutDatabasesEnumeration(async () => {+ const docName = uniqueDocName('cp-peek-nodbs-attach');+ const first = await peekStoredLineageEpoch({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ });+ expect(first).toBeNull();++ const doc = new Y.Doc();+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc,+ });+ await provider.whenSynced;+ doc.getText('source').insert(0, 'written after peek-created DB');+ doc.getMap('lifecycle').set('epoch', 'epoch-nodbs');+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ await provider.destroy();+ doc.destroy();++ const docB = new Y.Doc();+ const providerB = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc: docB,+ });+ await providerB.whenSynced;+ expect(docB.getText('source').toString()).toBe('written after peek-created DB');+ await providerB.destroy();+ docB.destroy();++ const second = await peekStoredLineageEpoch({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ });+ expect(second).toBe('epoch-nodbs');+ });+ });+});+describe('captureStateVector', () => {test('returns a non-empty Uint8Array for a non-empty doc', () => {const doc = new Y.Doc();@@ -517,3 +822,55 @@ describe('mergeStateVectors', () => {expect(mergeStateVectors(sv, sv)).toEqual(sv);});});++describe('flushFullState cross-tab fold', () => {+ test('folds cross-tab rows into the full state instead of trimming them away', async () => {+ const docName = uniqueDocName('cp-flush-crosstab');+ const doc = new Y.Doc();+ const provider = createClientPersistence({+ branch: TEST_BRANCH,+ serverInstanceId: TEST_SERVER_INSTANCE_ID,+ docName,+ doc,+ });+ await provider.whenSynced;+ doc.getText('source').insert(0, 'tab-a edit\n');++ const otherTab = new Y.Doc();+ otherTab.getText('other').insert(0, 'tab-b edit not yet synced');+ const otherTabRow = Y.encodeStateAsUpdate(otherTab);+ otherTab.destroy();+ const dbName = `ok-ydoc:${TEST_BRANCH}:${TEST_SERVER_INSTANCE_ID}:${docName}`;+ await new Promise<void>((resolve, reject) => {+ const req = indexedDB.open(dbName);+ req.onerror = () => reject(req.error);+ req.onsuccess = () => {+ const db = req.result;+ const tx = db.transaction('updates', 'readwrite');+ tx.objectStore('updates').add(otherTabRow);+ tx.oncomplete = () => {+ db.close();+ resolve();+ };+ tx.onabort = () => {+ db.close();+ reject(tx.error);+ };+ };+ });++ await provider.flushFullState();++ const rows = await readPersistedUpdates(TEST_BRANCH, TEST_SERVER_INSTANCE_ID, docName);+ expect(rows.length).toBe(1);+ const fresh = new Y.Doc();+ Y.applyUpdate(fresh, rows[0] as Uint8Array);+ expect(fresh.getText('source').toString()).toBe('tab-a edit\n');+ expect(fresh.getText('other').toString()).toBe('tab-b edit not yet synced');+ fresh.destroy();+ expect(doc.getText('other').toString()).toBe('tab-b edit not yet synced');++ await provider.destroy();+ doc.destroy();+ });+});diff --git a/packages/app/src/editor/client-persistence.ts b/packages/app/src/editor/client-persistence.tsindex 478c827a8..90b3e786f 100644--- a/packages/app/src/editor/client-persistence.ts+++ b/packages/app/src/editor/client-persistence.ts@@ -1,7 +1,11 @@+import { LINEAGE_EPOCH_KEY } from '@inkeep/open-knowledge-core';import { IndexeddbPersistence } from 'y-indexeddb';import * as Y from 'yjs';import { mark } from '@/lib/perf';+const UPDATES_STORE_NAME = 'updates';+const CUSTOM_STORE_NAME = 'custom';+function instrumentationDisabled(): boolean {return import.meta.env?.PROD === true;}@@ -13,6 +17,7 @@ export interface ClientPersistenceProvider {readonly synced: boolean;destroy(): Promise<void>;clearData(): Promise<void>;+ flushFullState(): Promise<void>;}interface CreateClientPersistenceArgs {@@ -69,6 +74,48 @@ class ClientPersistenceImpl implements ClientPersistenceProvider {}}+ async flushFullState(): Promise<void> {+ if (this._idb.db === null) {+ await this.whenSynced;+ }+ const db = this._idb.db;+ if (db === null) return;+ const idb = this._idb;+ await new Promise<void>((resolve, reject) => {+ const tx = db.transaction(UPDATES_STORE_NAME, 'readwrite');+ const store = tx.objectStore(UPDATES_STORE_NAME);+ const getAllReq = store.getAll();+ getAllReq.onerror = () =>+ reject(getAllReq.error ?? new Error('flushFullState getAll failed'));+ getAllReq.onsuccess = () => {+ try {+ Y.transact(+ idb.doc,+ () => {+ for (const row of getAllReq.result as unknown[]) {+ Y.applyUpdate(idb.doc, row as Uint8Array);+ }+ },+ idb,+ false,+ );+ const addReq = store.add(Y.encodeStateAsUpdate(idb.doc));+ addReq.onerror = () => reject(addReq.error ?? new Error('flushFullState add failed'));+ addReq.onsuccess = () => {+ store.delete(IDBKeyRange.upperBound(addReq.result, true));+ };+ } catch (err) {+ reject(err instanceof Error ? err : new Error(String(err)));+ try {+ tx.abort();+ } catch {}+ }+ };+ tx.oncomplete = () => resolve();+ tx.onabort = () => reject(tx.error ?? new Error('flushFullState transaction aborted'));+ });+ }+async clearData(): Promise<void> {const start = instrumentationDisabled() ? 0 : performance.now();try {@@ -101,6 +148,61 @@ export function createClientPersistence(return new ClientPersistenceImpl(args);}+export interface PeekStoredLineageEpochArgs {+ readonly branch: string;+ readonly serverInstanceId: string;+ readonly docName: string;+}++export async function peekStoredLineageEpoch(+ args: PeekStoredLineageEpochArgs,+): Promise<string | null> {+ if (typeof indexedDB === 'undefined') return null;+ const dbName = `ok-ydoc:${args.branch}:${args.serverInstanceId}:${args.docName}`;+ if (typeof indexedDB.databases === 'function') {+ const dbs = await indexedDB.databases();+ if (!dbs.some((d) => d.name === dbName)) return null;+ }+ const db = await new Promise<IDBDatabase>((resolve, reject) => {+ const req = indexedDB.open(dbName);+ req.onupgradeneeded = () => {+ const created = req.result;+ if (!created.objectStoreNames.contains(UPDATES_STORE_NAME)) {+ created.createObjectStore(UPDATES_STORE_NAME, { autoIncrement: true });+ }+ if (!created.objectStoreNames.contains(CUSTOM_STORE_NAME)) {+ created.createObjectStore(CUSTOM_STORE_NAME);+ }+ };+ req.onsuccess = () => resolve(req.result);+ req.onerror = () => reject(req.error);+ });+ try {+ if (!db.objectStoreNames.contains(UPDATES_STORE_NAME)) return null;+ const updates = await new Promise<unknown[]>((resolve, reject) => {+ const tx = db.transaction(UPDATES_STORE_NAME, 'readonly');+ const getAll = tx.objectStore(UPDATES_STORE_NAME).getAll();+ getAll.onsuccess = () => resolve(getAll.result as unknown[]);+ getAll.onerror = () => reject(getAll.error);+ });+ if (updates.length === 0) return null;+ const scratch = new Y.Doc();+ try {+ Y.transact(scratch, () => {+ for (const update of updates) {+ Y.applyUpdate(scratch, update as Uint8Array);+ }+ });+ const epoch = scratch.getMap('lifecycle').get(LINEAGE_EPOCH_KEY);+ return typeof epoch === 'string' && epoch.length > 0 ? epoch : null;+ } finally {+ scratch.destroy();+ }+ } finally {+ db.close();+ }+}+export function captureStateVector(doc: Y.Doc): Uint8Array {return Y.encodeStateVector(doc);}diff --git a/packages/app/src/editor/provider-pool.attach-boundary.test.ts b/packages/app/src/editor/provider-pool.attach-boundary.test.tsnew file mode 100644index 000000000..4e201241a--- /dev/null+++ b/packages/app/src/editor/provider-pool.attach-boundary.test.ts@@ -0,0 +1,31 @@+import { describe, expect, test } from 'bun:test';+import { join } from 'node:path';+import { Project, SyntaxKind } from 'ts-morph';++const SANCTIONED_CALLERS = ['attachValidatedPersistence', 'open'] as const;++describe('persistence-attach boundary (buildPersistence callers)', () => {+ test('buildPersistence has exactly the two sanctioned callers', () => {+ const project = new Project({ skipAddingFilesFromTsConfig: true });+ const sourceFile = project.addSourceFileAtPath(join(import.meta.dir, 'provider-pool.ts'));++ const callerMethods = sourceFile+ .getDescendantsOfKind(SyntaxKind.CallExpression)+ .filter((call) => {+ const expression = call.getExpression();+ return (+ expression.getKind() === SyntaxKind.PropertyAccessExpression &&+ expression.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName() ===+ 'buildPersistence'+ );+ })+ .map((call) => {+ const method = call.getFirstAncestorByKind(SyntaxKind.MethodDeclaration);+ const line = call.getStartLineNumber();+ return `${method?.getName() ?? '<outside-method>'} (provider-pool.ts:${line})`;+ })+ .sort();++ expect(callerMethods.map((entry) => entry.split(' ')[0])).toEqual([...SANCTIONED_CALLERS]);+ });+});diff --git a/packages/app/src/editor/provider-pool.test.ts b/packages/app/src/editor/provider-pool.test.tsindex 3d58f60bf..dcec03ca7 100644--- a/packages/app/src/editor/provider-pool.test.ts+++ b/packages/app/src/editor/provider-pool.test.ts@@ -28,6 +28,15 @@ async function waitFor(predicate: () => boolean, timeoutMs = 1_000): Promise<booreturn predicate();}+async function awaitAttachedPersistence(entry: {+ persistence: ClientPersistenceProvider | null;+}): Promise<ClientPersistenceProvider> {+ await waitFor(() => entry.persistence !== null, 2_000);+ const persistence = entry.persistence;+ if (persistence === null) throw new Error('expected persistence to attach');+ return persistence;+}+const DUMMY_WS = 'ws://localhost:1/collab';const TEST_SERVER_INSTANCE_ID = 'test-server-instance';@@ -1018,6 +1027,7 @@ describe('ProviderPool doc-lineage epoch records', () => {synced: true,destroy: async () => {},clearData: async () => {},+ flushFullState: async () => {},} as unknown as ClientPersistenceProvider;}@@ -1243,6 +1253,373 @@ describe('ProviderPool doc-lineage epoch records', () => {});});+describe('ProviderPool stored-state validation spine', () => {+ function makePersistenceStub(): ClientPersistenceProvider {+ return {+ whenSynced: Promise.resolve(undefined as never),+ synced: true,+ destroy: async () => {},+ clearData: async () => {},+ flushFullState: async () => {},+ } as unknown as ClientPersistenceProvider;+ }++ function captureWarns(): {+ lines: () => string[];+ restore: () => void;+ spy: ReturnType<typeof spyOn>;+ } {+ const spy = spyOn(console, 'warn').mockImplementation(() => undefined);+ return {+ lines: () =>+ spy.mock.calls+ .map((call) => call[0])+ .filter((first): first is string => typeof first === 'string'),+ restore: () => spy.mockRestore(),+ spy,+ };+ }++ test('refuses stored rows whose in-band epoch differs from the live lineage', async () => {+ const warns = captureWarns();+ try {+ const peek = mock(async () => 'epoch-dead');+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory: mock(makePersistenceStub),+ peekStoredLineageEpoch: peek,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-refuse');+ const entry = pool.open(docName);+ if (!entry) throw new Error('expected entry');+ pool.setActive(docName);+ expect(entry.persistence).toBeNull();++ entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-live');+ entry.provider.emit('synced', { state: true });++ const replaced = await waitFor(+ () => pool.peek(docName) !== null && pool.peek(docName) !== entry,+ 2_000,+ );+ expect(replaced).toBe(true);+ expect(pool.getActiveDocName()).toBe(docName);++ const emitted = warns.lines().filter((line) => 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('stored-state-validation');+ expect(event.staleEpoch).toBe('epoch-dead');+ expect(event.liveEpoch).toBe('epoch-live');+ expect(event.docName).toBe(docName);++ await wait(10);+ } finally {+ warns.restore();+ }+ });++ test('refuses stored epoch-bearing rows when the live doc carries no epoch post-sync', async () => {+ const warns = captureWarns();+ try {+ const peek = mock(async () => 'epoch-dead');+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory: mock(makePersistenceStub),+ peekStoredLineageEpoch: peek,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-live-absent');+ const entry = pool.open(docName);+ if (!entry) throw new Error('expected entry');++ entry.provider.emit('synced', { state: true });++ const replaced = await waitFor(+ () => pool.peek(docName) !== null && pool.peek(docName) !== entry,+ 2_000,+ );+ expect(replaced).toBe(true);++ const emitted = warns.lines().filter((line) => 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('stored-state-validation');+ expect(event.staleEpoch).toBe('epoch-dead');+ expect(event.liveEpoch).toBe('<absent>');++ await wait(10);+ } finally {+ warns.restore();+ }+ });++ test('attaches when the stored epoch matches the live lineage, then backfills the cache', async () => {+ const flushSpy = mock(async () => {});+ const persistenceFactory = mock(+ () =>+ ({+ whenSynced: Promise.resolve(undefined as never),+ synced: true,+ destroy: async () => {},+ clearData: async () => {},+ flushFullState: flushSpy,+ }) as unknown as ClientPersistenceProvider,+ );+ const peek = mock(async () => 'epoch-live');+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory,+ peekStoredLineageEpoch: peek,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-match');+ 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 });++ await awaitAttachedPersistence(entry);+ expect(persistenceFactory).toHaveBeenCalledTimes(1);+ const flushed = await waitFor(() => flushSpy.mock.calls.length === 1, 2_000);+ expect(flushed).toBe(true);+ });++ test('attaches immediately when the stored rows carry nothing to validate (null peek)', async () => {+ const persistenceFactory = mock(makePersistenceStub);+ const peek = mock(async () => null);+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory,+ peekStoredLineageEpoch: peek,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-null');+ const entry = pool.open(docName);+ if (!entry) throw new Error('expected entry');++ await awaitAttachedPersistence(entry);+ expect(entry.hasSynced).toBe(false);+ expect(persistenceFactory).toHaveBeenCalledTimes(1);+ });++ test('record-present entry that has not synced waits for sync before validating', async () => {+ const persistenceFactory = mock(makePersistenceStub);+ const peek = mock(async () => 'epoch-x');+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory,+ peekStoredLineageEpoch: peek,+ });+ const docName = uniqueDocName('pp-spine-wait');++ const first = pool.open(docName);+ if (!first) throw new Error('expected first entry');+ first.provider.document.getMap('lifecycle').set('epoch', 'epoch-x');+ first.provider.emit('synced', { state: true });+ pool.close(docName);++ const entry = pool.open(docName);+ if (!entry) throw new Error('expected entry');+ expect(entry.lineageEpochRecordAtOpen).toBe('epoch-x');+ expect(entry.hasSynced).toBe(false);++ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);++ await wait(50);+ expect(entry.persistence).toBeNull();++ entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-x');+ entry.provider.emit('synced', { state: true });+ await awaitAttachedPersistence(entry);+ expect(persistenceFactory).toHaveBeenCalledTimes(1);+ });++ test('a re-dispatch onto an entry with an in-flight spine run is a no-op (attach ownership)', async () => {+ let resolvePeek: (value: string | null) => void = () => {};+ const peek = mock(+ () =>+ new Promise<string | null>((resolve) => {+ resolvePeek = resolve;+ }),+ );+ const persistenceFactory = mock(makePersistenceStub);+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory,+ peekStoredLineageEpoch: peek,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-own');+ const entry = pool.open(docName);+ if (!entry) throw new Error('expected entry');+ expect(peek).toHaveBeenCalledTimes(1);++ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ expect(peek).toHaveBeenCalledTimes(1);++ resolvePeek(null);+ await awaitAttachedPersistence(entry);+ expect(persistenceFactory).toHaveBeenCalledTimes(1);+ });++ test('a rejecting peek leaves the entry cacheless and emits the attach-failed arm', async () => {+ const warns = captureWarns();+ try {+ const persistenceFactory = mock(makePersistenceStub);+ const peek = mock(async (): Promise<string | null> => {+ throw new Error('idb exploded');+ });+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory,+ peekStoredLineageEpoch: peek,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-peek-reject');+ const entry = pool.open(docName);+ if (!entry) throw new Error('expected entry');++ const emitted = await waitFor(+ () => warns.lines().some((line) => line.includes('ok-client-persistence-attach-failed')),+ 2_000,+ );+ expect(emitted).toBe(true);+ const lines = warns+ .lines()+ .filter((line) => line.includes('ok-client-persistence-attach-failed'));+ expect(lines.length).toBe(1);+ const event = JSON.parse(lines[0] ?? '{}') as Record<string, string>;+ expect(event.docName).toBe(docName);+ expect(event.phase).toBe('peek');+ expect(event.errorMessage).toBe('idb exploded');+ expect(entry.persistence).toBeNull();+ expect(persistenceFactory).not.toHaveBeenCalled();+ } finally {+ warns.restore();+ }+ });++ test('a wedged peek decays into the attach-failed arm after the timeout', async () => {+ const warns = captureWarns();+ try {+ const persistenceFactory = mock(makePersistenceStub);+ const peek = mock(() => new Promise<string | null>(() => {}));+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory,+ peekStoredLineageEpoch: peek,+ clearDataTimeoutMs: 20,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-peek-wedge');+ const entry = pool.open(docName);+ if (!entry) throw new Error('expected entry');++ const emitted = await waitFor(+ () => warns.lines().some((line) => line.includes('ok-client-persistence-attach-failed')),+ 2_000,+ );+ expect(emitted).toBe(true);+ const lines = warns+ .lines()+ .filter((line) => line.includes('ok-client-persistence-attach-failed'));+ const event = JSON.parse(lines[0] ?? '{}') as Record<string, string>;+ expect(event.docName).toBe(docName);+ expect(event.phase).toBe('peek');+ expect(event.errorName).toBe('StoredEpochPeekTimeoutError');+ expect(entry.persistence).toBeNull();+ expect(persistenceFactory).not.toHaveBeenCalled();+ } finally {+ warns.restore();+ }+ });++ test('a throwing factory on the matched-epoch arm emits attach-failed and leaves the entry cacheless', async () => {+ const warns = captureWarns();+ try {+ const peek = mock(async () => 'epoch-live');+ const persistenceFactory = mock((): ClientPersistenceProvider => {+ throw new Error('factory exploded');+ });+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory,+ peekStoredLineageEpoch: peek,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-factory-throw');+ 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 emitted = await waitFor(+ () => warns.lines().some((line) => line.includes('ok-client-persistence-attach-failed')),+ 2_000,+ );+ expect(emitted).toBe(true);+ const lines = warns+ .lines()+ .filter((line) => line.includes('ok-client-persistence-attach-failed'));+ const event = JSON.parse(lines[0] ?? '{}') as Record<string, string>;+ expect(event.docName).toBe(docName);+ expect(event.phase).toBe('attach');+ expect(event.errorMessage).toBe('factory exploded');+ expect(entry.persistence).toBeNull();+ } finally {+ warns.restore();+ }+ });++ test('a failing backfill emits the structured attach-failed event with phase backfill', async () => {+ const warns = captureWarns();+ try {+ const persistenceFactory = mock(+ () =>+ ({+ whenSynced: Promise.resolve(undefined as never),+ synced: true,+ destroy: async () => {},+ clearData: async () => {},+ flushFullState: async () => {+ throw new Error('backfill exploded');+ },+ }) as unknown as ClientPersistenceProvider,+ );+ const peek = mock(async () => null);+ pool = new ProviderPool(3, DUMMY_WS, {+ storage: null,+ persistenceFactory,+ peekStoredLineageEpoch: peek,+ });+ pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);+ const docName = uniqueDocName('pp-spine-backfill-fail');+ const entry = pool.open(docName);+ if (!entry) throw new Error('expected entry');+ await awaitAttachedPersistence(entry);+ entry.provider.emit('synced', { state: true });++ const emitted = await waitFor(+ () => warns.lines().some((line) => line.includes('ok-client-persistence-attach-failed')),+ 2_000,+ );+ expect(emitted).toBe(true);+ const lines = warns+ .lines()+ .filter((line) => line.includes('ok-client-persistence-attach-failed'));+ const event = JSON.parse(lines[0] ?? '{}') as Record<string, string>;+ expect(event.docName).toBe(docName);+ expect(event.phase).toBe('backfill');+ expect(event.errorMessage).toBe('backfill exploded');+ expect(entry.persistence).not.toBeNull();+ } finally {+ warns.restore();+ }+ });+});+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 });@@ -1362,11 +1739,12 @@ describe("ProviderPool authenticationFailed handling (US-002 / 'server-instance-pool = new ProviderPool(3, DUMMY_WS, { storage: null });pool.setExpectedServerInstanceId('server-old');const entry = pool.open('doc1');- if (!entry?.persistence) throw new Error('expected entry');+ if (!entry) throw new Error('expected entry');+ const persistence = await awaitAttachedPersistence(entry);pool.setActive('doc1');let resolveClear: () => void = () => {};- entry.persistence.clearData = mock(+ persistence.clearData = mock(() =>new Promise<void>((resolve) => {resolveClear = resolve;@@ -1410,10 +1788,11 @@ describe("ProviderPool authenticationFailed handling (US-002 / 'server-instance-pool.setExpectedServerInstanceId('server-old');pool.setObservedBranch('clear-fail-branch');const entry = pool.open('doc1');- if (!entry?.persistence) throw new Error('expected entry');+ if (!entry) throw new Error('expected entry');+ const persistence = await awaitAttachedPersistence(entry);pool.setActive('doc1');const originalProvider = entry.provider;- entry.persistence.clearData = mock(() => Promise.reject(new Error('idb blocked')));+ persistence.clearData = mock(() => Promise.reject(new Error('idb blocked')));entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });await wait(50);@@ -1467,9 +1846,10 @@ describe("ProviderPool authenticationFailed handling (US-002 / 'server-instance-pool.setExpectedServerInstanceId('server-old');pool.setObservedBranch('timeout-branch');const entry = pool.open('doc1');- if (!entry?.persistence) throw new Error('expected entry');+ if (!entry) throw new Error('expected entry');+ const persistence = await awaitAttachedPersistence(entry);pool.setActive('doc1');- entry.persistence.clearData = mock(() => new Promise<void>(() => {}));+ persistence.clearData = mock(() => new Promise<void>(() => {}));entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });await wait(30);@@ -1936,18 +2316,17 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {synced: true,destroy: mock(async () => {}),clearData: mock(async () => {}),+ flushFullState: async () => {},} as ClientPersistenceProvider;}- test('open() attaches a ClientPersistenceProvider to the pool entry', () => {+ test('open() attaches a ClientPersistenceProvider to the pool entry', async () => {pool = new ProviderPool(3, DUMMY_WS);pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName();const entry = pool.open(docName);if (!entry) throw new Error('expected entry');- expect(entry.persistence).not.toBeNull();- const persistence = entry.persistence;- if (!persistence) throw new Error('expected persistence');+ const persistence = await awaitAttachedPersistence(entry);expect(typeof persistence.destroy).toBe('function');expect(typeof persistence.clearData).toBe('function');});@@ -1960,7 +2339,7 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {expect(entry.persistence).toBeNull();});- test('deferred persistence attach continues after one entry throws', () => {+ test('deferred persistence attach continues after one entry throws', async () => {const warnSpy = spyOn(console, 'warn').mockImplementation(() => undefined);try {const badDoc = uniqueDocName('pp-deferred-throw');@@ -1982,9 +2361,11 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {expect(() => pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID)).not.toThrow();- expect(badEntry.persistence).toBeNull();+ await awaitAttachedPersistence(goodEntry);expect(goodEntry.persistence).toBe(goodPersistence);+ await waitFor(() => persistenceFactory.mock.calls.length === 2, 2_000);expect(persistenceFactory).toHaveBeenCalledTimes(2);+ expect(badEntry.persistence).toBeNull();const events = warnSpy.mock.calls.map((call) => String(call[0] ?? ''));expect(events.some((event) => event.includes('"event":"ok-client-persistence-attach-failed"')),@@ -1994,37 +2375,40 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {}});- test('re-opening the same docName reuses the existing persistence instance', () => {+ test('re-opening the same docName reuses the existing persistence instance', async () => {pool = new ProviderPool(3, DUMMY_WS);pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName();const entry1 = pool.open(docName);- const persistence1 = entry1?.persistence;+ if (!entry1) throw new Error('expected entry1');+ const persistence1 = await awaitAttachedPersistence(entry1);const entry2 = pool.open(docName);expect(entry2?.persistence).toBe(persistence1);});- test('prewarm() also attaches a persistence instance', () => {+ test('prewarm() also attaches a persistence instance', async () => {pool = new ProviderPool(3, DUMMY_WS);pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName('pp-prewarm');const entry = pool.prewarm(docName);if (!entry) throw new Error('expected prewarmed entry');+ await awaitAttachedPersistence(entry);expect(entry.persistence).not.toBeNull();});- test('close() destroys the persistence before the provider', () => {+ test('close() destroys the persistence before the provider', async () => {pool = new ProviderPool(3, DUMMY_WS);pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName('pp-close');const entry = pool.open(docName);- if (!entry?.persistence) throw new Error('expected persistence');+ if (!entry) throw new Error('expected entry');+ const attached = await awaitAttachedPersistence(entry);const order: string[] = [];const persistenceSpy = mock(async () => {order.push('persistence');});- entry.persistence.destroy = persistenceSpy;+ attached.destroy = persistenceSpy;const origProviderDestroy = entry.provider.destroy.bind(entry.provider);entry.provider.destroy = (() => {@@ -2044,7 +2428,8 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName('pp-recycle');const entry = pool.open(docName);- if (!entry?.persistence) throw new Error('expected persistence');+ if (!entry) throw new Error('expected entry');+ const attached = await awaitAttachedPersistence(entry);pool.setActive(docName);entry.observerCleanup = () => {};@@ -2052,7 +2437,7 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {const persistenceSpy = mock(async () => {order.push('persistence');});- entry.persistence.destroy = persistenceSpy;+ attached.destroy = persistenceSpy;const origProviderDestroy = entry.provider.destroy.bind(entry.provider);entry.provider.destroy = (() => {@@ -2073,7 +2458,7 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {expect(order[1]).toBe('provider');});- test('evictLru destroys the persistence on the evicted entry', () => {+ test('evictLru destroys the persistence on the evicted entry', async () => {pool = new ProviderPool(2, DUMMY_WS);pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const doc1 = uniqueDocName('pp-evict');@@ -2082,10 +2467,11 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {pool.open(doc1);pool.setActive(doc1);const entry2 = pool.open(doc2);- if (!entry2?.persistence) throw new Error('expected persistence on doc2');+ if (!entry2) throw new Error('expected entry on doc2');+ const attached2 = await awaitAttachedPersistence(entry2);const destroySpy = mock(async () => {});- entry2.persistence.destroy = destroySpy;+ attached2.destroy = destroySpy;pool.open(doc3);@@ -2093,19 +2479,21 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {expect(destroySpy).toHaveBeenCalledTimes(1);});- test('dispose() destroys every pool entry’s persistence', () => {+ test('dispose() destroys every pool entry’s persistence', async () => {pool = new ProviderPool(3, DUMMY_WS);pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const doc1 = uniqueDocName('pp-dispose');const doc2 = uniqueDocName('pp-dispose');const e1 = pool.open(doc1);const e2 = pool.open(doc2);- if (!e1?.persistence || !e2?.persistence) throw new Error('expected persistences');+ if (!e1 || !e2) throw new Error('expected entries');+ const p1 = await awaitAttachedPersistence(e1);+ const p2 = await awaitAttachedPersistence(e2);const spy1 = mock(async () => {});const spy2 = mock(async () => {});- e1.persistence.destroy = spy1;- e2.persistence.destroy = spy2;+ p1.destroy = spy1;+ p2.destroy = spy2;pool.dispose();@@ -2118,10 +2506,11 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName('pp-rename-clear');const entry = pool.open(docName);- if (!entry?.persistence) throw new Error('expected persistence');+ if (!entry) throw new Error('expected entry');+ const attached = await awaitAttachedPersistence(entry);const clearSpy = mock(async () => {});- entry.persistence.clearData = clearSpy;+ attached.clearData = clearSpy;await pool.closeAndClearPersistence(docName);@@ -2192,8 +2581,8 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {const dbB = `ok-ydoc:main:server-roundtrip:${nameB}`;const entryA1 = pool.open(nameA);- if (!entryA1?.persistence) throw new Error('expected persistence');- await entryA1.persistence.whenSynced;+ if (!entryA1) throw new Error('expected entry');+ await (await awaitAttachedPersistence(entryA1)).whenSynced;let dbs = await indexedDB.databases();expect(dbs.find((d) => d.name === dbA)).toBeDefined();@@ -2204,8 +2593,8 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {expect(dbs.find((d) => d.name === dbB)).toBeUndefined();const entryB = pool.open(nameB);- if (!entryB?.persistence) throw new Error('expected persistence');- await entryB.persistence.whenSynced;+ if (!entryB) throw new Error('expected entry');+ await (await awaitAttachedPersistence(entryB)).whenSynced;dbs = await indexedDB.databases();expect(dbs.find((d) => d.name === dbB)).toBeDefined();@@ -2216,8 +2605,8 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {expect(dbs.find((d) => d.name === dbB)).toBeUndefined();const entryA2 = pool.open(nameA);- if (!entryA2?.persistence) throw new Error('expected persistence');- await entryA2.persistence.whenSynced;+ if (!entryA2) throw new Error('expected entry');+ await (await awaitAttachedPersistence(entryA2)).whenSynced;dbs = await indexedDB.databases();expect(dbs.find((d) => d.name === dbA)).toBeDefined();});@@ -2229,14 +2618,16 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {const doc2 = uniqueDocName('pp-mismatch');const e1 = pool.open(doc1);const e2 = pool.open(doc2);- if (!e1?.persistence || !e2?.persistence) throw new Error('expected persistences');+ if (!e1 || !e2) throw new Error('expected entries');+ const p1 = await awaitAttachedPersistence(e1);+ const p2 = await awaitAttachedPersistence(e2);pool.setActive(doc1);e1.observerCleanup = () => {};const clearSpy1 = mock(async () => {});const clearSpy2 = mock(async () => {});- e1.persistence.clearData = clearSpy1;- e2.persistence.clearData = clearSpy2;+ p1.clearData = clearSpy1;+ p2.clearData = clearSpy2;e1.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });await wait(50);@@ -2256,9 +2647,12 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {const e1 = pool.open(doc1);const e2 = pool.open(doc2);const e3 = pool.open(doc3);- if (!e1?.persistence || !e2?.persistence || !e3?.persistence) {- throw new Error('expected persistences');+ if (!e1 || !e2 || !e3) {+ throw new Error('expected entries');}+ const p1 = await awaitAttachedPersistence(e1);+ const p2 = await awaitAttachedPersistence(e2);+ const p3 = await awaitAttachedPersistence(e3);pool.setActive(doc1);e1.observerCleanup = () => {};e2.observerCleanup = () => {};@@ -2271,9 +2665,9 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {const clearOk1 = mock(async () => {});const clearFail = mock(() => Promise.reject(new Error('idb-clear-blocked')));const clearOk2 = mock(async () => {});- e1.persistence.clearData = clearOk1;- e2.persistence.clearData = clearFail;- e3.persistence.clearData = clearOk2;+ p1.clearData = clearOk1;+ p2.clearData = clearFail;+ p3.clearData = clearOk2;e1.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });await wait(50);@@ -2301,15 +2695,17 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {const docHung = uniqueDocName('pp-partial-timeout-hung');const ea = pool.open(docActive);const eb = pool.open(docHung);- if (!ea?.persistence || !eb?.persistence) {- throw new Error('expected persistences');+ if (!ea || !eb) {+ throw new Error('expected entries');}+ const pa = await awaitAttachedPersistence(ea);+ const pb = await awaitAttachedPersistence(eb);pool.setActive(docActive);ea.observerCleanup = () => {};eb.observerCleanup = () => {};- ea.persistence.clearData = mock(async () => {});- eb.persistence.clearData = mock(() => new Promise<void>(() => {}));+ pa.clearData = mock(async () => {});+ pb.clearData = mock(() => new Promise<void>(() => {}));ea.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });await wait(60);@@ -2348,6 +2744,7 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {synced: true,destroy: mock(async () => {}),clearData: clearSpy,+ flushFullState: async () => {},} as unknown as ClientPersistenceProvider;return { stub, clearSpy };}@@ -2368,7 +2765,8 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName('pp-pending-clears-dedup');const entry = pool.open(docName);- if (!entry?.persistence) throw new Error('expected persistence');+ if (!entry) throw new Error('expected entry');+ await awaitAttachedPersistence(entry);const deleteDbCallsBefore = deleteDbSpy.mock.calls.length;const call1 = pool.closeAndClearPersistence(docName);@@ -2403,7 +2801,8 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {const docName = uniqueDocName('pp-pending-clears-defer-success');const entry1 = pool.open(docName);- if (!entry1?.persistence) throw new Error('expected initial persistence');+ if (!entry1) throw new Error('expected entry1');+ await awaitAttachedPersistence(entry1);const clearPromise = pool.closeAndClearPersistence(docName);@@ -2413,7 +2812,7 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {resolveClear();await clearPromise;- await wait(0);+ await waitFor(() => entry2.persistence !== null, 2_000);expect(entry2.persistence).toBe(fresh.stub);});@@ -2431,7 +2830,9 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName('pp-pending-clears-defer-fail');- pool.open(docName);+ const entry1 = pool.open(docName);+ if (!entry1) throw new Error('expected entry1');+ await awaitAttachedPersistence(entry1);const clearPromise = pool.closeAndClearPersistence(docName);const entry2 = pool.open(docName);@@ -2473,7 +2874,9 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {pool = new ProviderPool(3, DUMMY_WS, { persistenceFactory, clearDataTimeoutMs: 30_000 });pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);const docName = uniqueDocName('pp-pending-clears-dispose');- pool.open(docName);+ const entry1 = pool.open(docName);+ if (!entry1) throw new Error('expected entry1');+ await awaitAttachedPersistence(entry1);const clearPromise = pool.closeAndClearPersistence(docName);const entry2 = pool.open(docName);@@ -2508,7 +2911,11 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {uniqueDocName('pp-swallow-fail'),uniqueDocName('pp-swallow-ok2'),];- for (const d of docs) pool.open(d);+ for (const d of docs) {+ const entry = pool.open(d);+ if (!entry) throw new Error('expected entry');+ await awaitAttachedPersistence(entry);+ }const warnSpy = spyOn(console, 'warn').mockImplementation(() => undefined);try {@@ -2536,7 +2943,8 @@ describe('ProviderPool client-persistence attachment (US-003)', () => {const docName = uniqueDocName('pp-clearfail-retry');const entry1 = pool.open(docName);- if (!entry1?.persistence) throw new Error('expected initial persistence');+ if (!entry1) throw new Error('expected entry1');+ await awaitAttachedPersistence(entry1);const deleteDbSpy = spyOn(indexedDB, 'deleteDatabase');const warnSpy = spyOn(console, 'warn').mockImplementation(() => undefined);@@ -2901,6 +3309,7 @@ describe('ProviderPool structured mismatch telemetry', () => {const docName = uniqueDocName('replay-flush');const entry = pool.open(docName);if (!entry) throw new Error('expected entry');+ await awaitAttachedPersistence(entry);pool.setActive(docName);entry.observerCleanup = () => {};@@ -3087,6 +3496,8 @@ describe('ProviderPool provider-open gating', () => {if (entryA.kind !== 'active' || entryB.kind !== 'active') {throw new Error('expected entries to remain active');}+ await awaitAttachedPersistence(entryA);+ await awaitAttachedPersistence(entryB);expect(entryA.persistence).not.toBeNull();expect(entryB.persistence).not.toBeNull();expect(typeof entryA.persistence?.destroy).toBe('function');@@ -3104,30 +3515,30 @@ describe('ProviderPool provider-open gating', () => {}});- test('setExpectedServerInstanceId is a no-op for entries that already have persistence attached', () => {+ test('setExpectedServerInstanceId is a no-op for entries that already have persistence attached', async () => {pool = new ProviderPool(3, DUMMY_WS);pool.setExpectedServerInstanceId('server-warm');const docName = uniqueDocName('pp-warm');const entry = pool.open(docName);if (!entry) throw new Error('expected entry');- const persistenceBefore = entry.persistence;- expect(persistenceBefore).not.toBeNull();+ const persistenceBefore = await awaitAttachedPersistence(entry);pool.setExpectedServerInstanceId('server-warm-update');+ await wait(20);if (entry.kind !== 'active') throw new Error('expected entry to remain active');expect(entry.persistence).toBe(persistenceBefore);});- test('setExpectedServerInstanceId(null) does not detach already-attached persistence', () => {+ test('setExpectedServerInstanceId(null) does not detach already-attached persistence', async () => {pool = new ProviderPool(3, DUMMY_WS);pool.setExpectedServerInstanceId('server-warm');const docName = uniqueDocName('pp-no-detach');const entry = pool.open(docName);if (!entry) throw new Error('expected entry');- const persistenceBefore = entry.persistence;- expect(persistenceBefore).not.toBeNull();+ const persistenceBefore = await awaitAttachedPersistence(entry);pool.setExpectedServerInstanceId(null);+ await wait(20);if (entry.kind !== 'active') throw new Error('expected entry to remain active');expect(entry.persistence).toBe(persistenceBefore);});diff --git a/packages/app/src/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.tsindex ff32d91c7..ac67a7607 100644--- a/packages/app/src/editor/provider-pool.ts+++ b/packages/app/src/editor/provider-pool.ts@@ -16,6 +16,8 @@ import {computeUnsyncedUpdate,createClientPersistence,mergeStateVectors,+ type PeekStoredLineageEpochArgs,+ peekStoredLineageEpoch,UNKNOWN_BRANCH_SENTINEL,} from './client-persistence';import { appendTraceContextToCollabUrl } from './collab-otel';@@ -67,6 +69,7 @@ interface ActivePoolEntry extends PoolEntryBase {observerCleanup: (() => void) | null;observerFireCounterCleanup: (() => void) | null;pendingRecycleTimer: ReturnType<typeof setTimeout> | null;+ persistenceAttachOwned: boolean;serverDrivenCloseReauthInFlight: boolean;}@@ -129,6 +132,8 @@ type ClientPersistenceFactory = (args: {doc: Y.Doc;}) => ClientPersistenceProvider;+type PeekStoredLineageEpoch = (args: PeekStoredLineageEpochArgs) => Promise<string | null>;+class ClientPersistenceClearTimeoutError extends Error {constructor(readonly docName: string,@@ -139,6 +144,16 @@ class ClientPersistenceClearTimeoutError extends Error {}}+class StoredEpochPeekTimeoutError extends Error {+ constructor(+ readonly docName: string,+ readonly timeoutMs: number,+ ) {+ super(`stored-state epoch peek timed out for ${docName} after ${timeoutMs}ms`);+ this.name = 'StoredEpochPeekTimeoutError';+ }+}+const LAST_OBSERVED_BRANCH_KEY = 'ok-last-observed-branch';const DOC_LINEAGE_EPOCHS_KEY = 'ok-doc-lineage-epochs';@@ -237,6 +252,7 @@ export class ProviderPool {private readonly pendingClears = new Map<string, Promise<void>>();private readonly clearFailures = new Set<string>();private readonly persistenceFactory: ClientPersistenceFactory;+ private readonly peekStoredEpoch: PeekStoredLineageEpoch;private readonly storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;@@ -248,6 +264,7 @@ export class ProviderPool {clearDataTimeoutMs?: number;storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;persistenceFactory?: ClientPersistenceFactory;+ peekStoredLineageEpoch?: PeekStoredLineageEpoch;},) {this.maxSize = maxSize;@@ -255,6 +272,7 @@ export class ProviderPool {this.recycleDebounceMs = options?.recycleDebounceMs ?? RECYCLE_DEBOUNCE_MS;this.clearDataTimeoutMs = options?.clearDataTimeoutMs ?? CLEAR_DATA_TIMEOUT_MS;this.persistenceFactory = options?.persistenceFactory ?? createClientPersistence;+ this.peekStoredEpoch = options?.peekStoredLineageEpoch ?? peekStoredLineageEpoch;if (options?.storage !== undefined) {this.storage = options.storage;} else {@@ -306,8 +324,138 @@ export class ProviderPool {});}+ private async validateStoredStateThenAttach(+ entry: ActivePoolEntry,+ serverInstanceId: string,+ ): Promise<void> {+ if (entry.persistenceAttachOwned) return;+ entry.persistenceAttachOwned = true;+ const docName = entry.docName;+ const entryIsCurrent = (): boolean =>+ this._entries.get(docName) === entry &&+ entry.kind === 'active' &&+ entry.persistence === null &&+ !this.pendingClears.has(docName);+ if (!entryIsCurrent()) return;+ let storedEpoch: string | null;+ try {+ storedEpoch = await new Promise<string | null>((resolve, reject) => {+ const timer = setTimeout(() => {+ reject(new StoredEpochPeekTimeoutError(docName, this.clearDataTimeoutMs));+ }, this.clearDataTimeoutMs);+ this.peekStoredEpoch({+ branch: this.normalizedObservedBranch(),+ serverInstanceId,+ docName,+ }).then(+ (value) => {+ clearTimeout(timer);+ resolve(value);+ },+ (err: unknown) => {+ clearTimeout(timer);+ reject(err);+ },+ );+ });+ } catch (err: unknown) {+ this.emitStructuredClientRecoveryEvent({+ event: 'ok-client-persistence-attach-failed',+ ...this.recoveryTelemetryBase(docName),+ phase: 'peek',+ errorName: err instanceof Error ? err.name : 'non-error-throw',+ errorMessage: err instanceof Error ? err.message : String(err),+ });+ return;+ }+ if (!entryIsCurrent()) return;+ if (storedEpoch === null) {+ this.attachValidatedPersistence(entry, serverInstanceId);+ return;+ }+ if (!entry.hasSynced) {+ await this.awaitFirstSyncOrDestroy(entry);+ if (!entryIsCurrent() || !entry.hasSynced) return;+ }+ const liveEpochRaw = entry.provider.document.getMap('lifecycle').get(LINEAGE_EPOCH_KEY);+ const liveEpoch =+ typeof liveEpochRaw === 'string' && liveEpochRaw.length > 0 ? liveEpochRaw : null;+ if (liveEpoch === storedEpoch) {+ this.attachValidatedPersistence(entry, serverInstanceId);+ return;+ }+ this.emitStructuredClientRecoveryEvent({+ event: 'ok-doc-lineage-mismatch',+ ...this.recoveryTelemetryBase(docName),+ via: 'stored-state-validation',+ staleEpoch: storedEpoch,+ liveEpoch: liveEpoch ?? '<absent>',+ });+ const wasActive = this.activeDocName === docName;+ void this.runCloseAndClearPersistence(docName);+ const reopened = this.open(docName);+ if (reopened !== null && wasActive) this.setActive(docName);+ }++ private attachValidatedPersistence(entry: ActivePoolEntry, serverInstanceId: string): void {+ const docName = entry.docName;+ try {+ const persistence = this.buildPersistence(serverInstanceId, docName, entry.provider.document);+ entry.persistence = persistence;+ this.notify();+ void this.backfillCacheAfterFirstSync(entry, persistence).catch((err: unknown) => {+ this.emitStructuredClientRecoveryEvent({+ event: 'ok-client-persistence-attach-failed',+ ...this.recoveryTelemetryBase(docName),+ phase: 'backfill',+ errorName: err instanceof Error ? err.name : 'non-error-throw',+ errorMessage: err instanceof Error ? err.message : String(err),+ });+ });+ } catch (err: unknown) {+ this.emitStructuredClientRecoveryEvent({+ event: 'ok-client-persistence-attach-failed',+ ...this.recoveryTelemetryBase(docName),+ phase: 'attach',+ errorName: err instanceof Error ? err.name : 'non-error-throw',+ errorMessage: err instanceof Error ? err.message : String(err),+ });+ }+ }++ private async backfillCacheAfterFirstSync(+ entry: ActivePoolEntry,+ persistence: ClientPersistenceProvider,+ ): Promise<void> {+ await persistence.whenSynced;+ if (!entry.hasSynced) {+ await this.awaitFirstSyncOrDestroy(entry);+ }+ if (+ this._entries.get(entry.docName) !== entry ||+ entry.kind !== 'active' ||+ entry.persistence !== persistence ||+ !entry.hasSynced+ ) {+ return;+ }+ await persistence.flushFullState();+ }++ private async awaitFirstSyncOrDestroy(entry: ActivePoolEntry): Promise<void> {+ if (entry.hasSynced) return;+ await new Promise<void>((resolve) => {+ const settle = (): void => {+ entry.provider.off('synced', settle);+ entry.provider.off('destroy', settle);+ resolve();+ };+ entry.provider.on('synced', settle);+ entry.provider.on('destroy', settle);+ });+ }+private attachDeferredPersistence(serverInstanceId: string): void {- let anyAttached = false;for (const entry of Array.from(this._entries.values())) {if (entry.kind !== 'active') continue;if (entry.persistence !== null) continue;@@ -334,25 +482,7 @@ export class ProviderPool {continue;}}- try {- entry.persistence = this.buildPersistence(- serverInstanceId,- entry.docName,- entry.provider.document,- );- anyAttached = true;- } catch (err: unknown) {- const errorName = err instanceof Error ? err.name : 'non-error-throw';- this.emitStructuredClientRecoveryEvent({- event: 'ok-client-persistence-attach-failed',- ...this.recoveryTelemetryBase(entry.docName),- errorName,- errorMessage: err instanceof Error ? err.message : String(err),- });- }- }- if (anyAttached) {- this.notify();+ void this.validateStoredStateThenAttach(entry, serverInstanceId);}}@@ -725,7 +855,8 @@ export class ProviderPool {const persistence: ClientPersistenceProvider | null =persistenceServerInstanceId !== null &&persistenceServerInstanceId.length > 0 &&- pendingClearForDocName === undefined+ pendingClearForDocName === undefined &&+ lineageEpochRecordAtOpen !== null? this.buildPersistence(persistenceServerInstanceId, docName, provider.document): null;if (import.meta.env.PROD !== true) {@@ -746,7 +877,15 @@ export class ProviderPool {} else {mark('ok/pool/idb-bypass-no-epoch',- { docName },+ {+ docName,+ reason:+ persistenceServerInstanceId === null || persistenceServerInstanceId.length === 0+ ? 'no-epoch'+ : pendingClearForDocName !== undefined+ ? 'pending-clear'+ : 'stored-state-validation',+ },{ startTime: idbAttachStart, duration: 0 },);}@@ -769,6 +908,7 @@ export class ProviderPool {pendingRecycleTimer: null,bridgeSetupFailed: false,serverDrivenCloseReauthInFlight: false,+ persistenceAttachOwned: false,lineageEpochRecordAtOpen,};mark('ok/pool/open', { docName, hit: false, poolEventId });@@ -980,6 +1120,15 @@ export class ProviderPool {this.touch(docName);this.notify();+ if (+ persistence === null &&+ persistenceServerInstanceId !== null &&+ persistenceServerInstanceId.length > 0 &&+ pendingClearForDocName === undefined+ ) {+ void this.validateStoredStateThenAttach(entry, persistenceServerInstanceId);+ }+if (pendingClearForDocName !== undefined &&persistenceServerInstanceId !== null &&@@ -1025,22 +1174,7 @@ export class ProviderPool {if (current !== entry || current.kind !== 'active' || current.persistence !== null) {return;}- try {- current.persistence = this.buildPersistence(- serverInstanceId,- entry.docName,- current.provider.document,- );- this.notify();- } catch (err: unknown) {- const errorName = err instanceof Error ? err.name : 'non-error-throw';- this.emitStructuredClientRecoveryEvent({- event: 'ok-client-persistence-attach-failed',- ...this.recoveryTelemetryBase(entry.docName),- errorName,- errorMessage: err instanceof Error ? err.message : String(err),- });- }+ void this.validateStoredStateThenAttach(current, serverInstanceId);}private handleServerInstanceMismatch(staleClaimedServerInstanceId: string): void {diff --git a/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts b/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.tsnew file mode 100644index 000000000..2a9baaace--- /dev/null+++ b/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts@@ -0,0 +1,335 @@+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.+`;++const ENVELOPE_KEY = 'ok-doc-lineage-epochs';++const HYDRATION_WINDOW_MS = 5_000;++function countOccurrences(haystack: string, needle: string): number {+ return haystack.split(needle).length - 1;+}++function hasUnionMergeArtifacts(text: string): boolean {+ return (+ countOccurrences(text, 'LINEAGE-ALPHA') > 1 || countOccurrences(text, 'LINEAGE-V1-ONLY') > 0+ );+}++async function settleHydrationWindow(read: () => string, doneEarly?: () => boolean): Promise<void> {+ const deadline = Date.now() + HYDRATION_WINDOW_MS;+ while (Date.now() < deadline) {+ if (hasUnionMergeArtifacts(read())) return;+ if (doneEarly?.() === true) return;+ await wait(100);+ }+}++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 };+}++function captureLineageMismatchWarns(): {+ emitted: string[];+ restore: () => void;+} {+ const emitted: string[] = [];+ const original = console.warn;+ console.warn = (...args: unknown[]): void => {+ const first = args[0];+ if (typeof first === 'string' && first.includes('ok-doc-lineage-mismatch')) {+ emitted.push(first);+ }+ original.apply(console, args);+ };+ return {+ emitted,+ restore: () => {+ console.warn = original;+ },+ };+}++const cleanups: Array<() => Promise<void> | void> = [];++afterEach(async () => {+ while (cleanups.length > 0) {+ await cleanups.pop()?.();+ }+});++async function stageStaleRowsAndReseed(opts: {+ server: Awaited<ReturnType<typeof createTestServer>>;+ docName: string;+ filePath: string;+ storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;+}): Promise<void> {+ const { server, docName, filePath, storage } = opts;+ const poolA = new ProviderPool(3, `ws://localhost:${server.port}/collab`, { storage });+ 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);+}++async function assertSingleLineageEverywhere(opts: {+ clientYtext: () => string;+ serverYtext: () => string;+ filePath: string;+}): Promise<void> {+ const { clientYtext, serverYtext, filePath } = opts;++ 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);+}++describe('client-persisted state meets a re-seeded doc lineage (boot-window fresh-pool door)', () => {+ test('a fresh pool that opened during the instance-unknown window must not hydrate a stale lineage when the id lands', async () => {+ const server = await createTestServer();+ cleanups.push(() => server.cleanup());++ const docName = `lineage-bootwindow-${crypto.randomUUID()}`;+ const filePath = join(server.contentDir, `${docName}.md`);+ writeFileSync(filePath, FIXTURE_V1, 'utf-8');+ await awaitFileWatcherIndexed(server, docName);++ const { stub: sharedStorage, store } = makeStubStorage();+ await stageStaleRowsAndReseed({ server, docName, filePath, storage: sharedStorage });++ const envelopeRaw = store.get(ENVELOPE_KEY) ?? null;+ expect(envelopeRaw).not.toBeNull();+ expect(envelopeRaw as string).toContain(docName);++ const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {+ storage: sharedStorage,+ });+ cleanups.push(() => poolB.dispose());+ 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);++ const clientYtext = (): string =>+ poolB.getActive()?.provider.document.getText('source').toString() ?? '';+ const serverYtext = (): string => getServerState(server, docName)?.ytext.toString() ?? '';++ expect(poolB.getActive()?.persistence ?? null).toBeNull();+ 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, poolB);+ await settleHydrationWindow(clientYtext);++ await assertSingleLineageEverywhere({ clientYtext, serverYtext, filePath });+ }, 120_000);+});++describe('client-persisted state meets a re-seeded doc lineage (record-absent profile door)', () => {+ test('a claimless open over surviving IDB rows must not hydrate a stale lineage into the re-seeded doc', async () => {+ const server = await createTestServer();+ cleanups.push(() => server.cleanup());++ const docName = `lineage-noenvelope-${crypto.randomUUID()}`;+ const filePath = join(server.contentDir, `${docName}.md`);+ writeFileSync(filePath, FIXTURE_V1, 'utf-8');+ await awaitFileWatcherIndexed(server, docName);++ const { stub: storageA } = makeStubStorage();+ await stageStaleRowsAndReseed({ server, docName, filePath, storage: storageA });++ const { stub: emptyStorage } = makeStubStorage();+ const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {+ storage: emptyStorage,+ });+ 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);++ const clientYtext = (): string =>+ poolB.getActive()?.provider.document.getText('source').toString() ?? '';+ const serverYtext = (): string => getServerState(server, docName)?.ytext.toString() ?? '';++ await settleHydrationWindow(clientYtext);++ await assertSingleLineageEverywhere({ clientYtext, serverYtext, filePath });+ }, 120_000);+});++describe('refusing dead-lineage state is observable (boot-window fresh-pool door)', () => {+ test('fencing the late attach emits the structured ok-doc-lineage-mismatch recovery event', async () => {+ const server = await createTestServer();+ cleanups.push(() => server.cleanup());++ const docName = `lineage-bootwindow-telemetry-${crypto.randomUUID()}`;+ const filePath = join(server.contentDir, `${docName}.md`);+ writeFileSync(filePath, FIXTURE_V1, 'utf-8');+ await awaitFileWatcherIndexed(server, docName);++ const { stub: sharedStorage } = makeStubStorage();+ await stageStaleRowsAndReseed({ server, docName, filePath, storage: sharedStorage });++ const capture = captureLineageMismatchWarns();+ cleanups.push(capture.restore);++ const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {+ storage: sharedStorage,+ });+ cleanups.push(() => poolB.dispose());+ 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);++ const clientYtext = (): string =>+ poolB.getActive()?.provider.document.getText('source').toString() ?? '';++ await seedPoolServerInstanceId(server, poolB);+ await settleHydrationWindow(clientYtext, () => capture.emitted.length > 0);+ capture.restore();++ expect(capture.emitted.length).toBeGreaterThanOrEqual(1);+ const events = capture.emitted.map((line) => JSON.parse(line) as Record<string, unknown>);+ expect(events.some((e) => e.docName === docName && e.via === 'stored-state-validation')).toBe(+ true,+ );+ }, 120_000);+});++describe('refusing dead-lineage state is observable (record-absent profile door)', () => {+ test('fencing the claimless admission attach emits the structured ok-doc-lineage-mismatch recovery event', async () => {+ const server = await createTestServer();+ cleanups.push(() => server.cleanup());++ const docName = `lineage-noenvelope-telemetry-${crypto.randomUUID()}`;+ const filePath = join(server.contentDir, `${docName}.md`);+ writeFileSync(filePath, FIXTURE_V1, 'utf-8');+ await awaitFileWatcherIndexed(server, docName);++ const { stub: storageA } = makeStubStorage();+ await stageStaleRowsAndReseed({ server, docName, filePath, storage: storageA });++ const capture = captureLineageMismatchWarns();+ cleanups.push(capture.restore);++ const { stub: emptyStorage } = makeStubStorage();+ const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {+ storage: emptyStorage,+ });+ 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);++ const clientYtext = (): string =>+ poolB.getActive()?.provider.document.getText('source').toString() ?? '';++ await settleHydrationWindow(clientYtext, () => capture.emitted.length > 0);+ capture.restore();++ expect(capture.emitted.length).toBeGreaterThanOrEqual(1);+ const events = capture.emitted.map((line) => JSON.parse(line) as Record<string, unknown>);+ expect(events.some((e) => e.docName === docName && e.via === 'stored-state-validation')).toBe(+ true,+ );+ }, 120_000);+});