Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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<boo
return 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.ts
index 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.ts
new file mode 100644
index 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);
+});