Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Join background work in server test fixtures (#5589)

Nick Gomez662b7656f127
diff --git a/packages/server/src/derive-defer-floor.test.ts b/packages/server/src/derive-defer-floor.test.ts
index ba8298df6..54820dafb 100644
--- a/packages/server/src/derive-defer-floor.test.ts
+++ b/packages/server/src/derive-defer-floor.test.ts
@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
+import { setImmediate as nextTurn } from 'node:timers/promises';
import type { Hocuspocus } from '@hocuspocus/server';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import {
@@ -24,9 +25,33 @@ import {
WIRED_PENDING_LINE,
type WiredPreDrainRig,
} from './pre-drain-wired.test-helper.ts';
+import { shadowOpGateFor } from './shadow-op-gate.ts';
import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
import { getDocumentHistory } from './timeline-query.ts';
+const lossAppendHold = vi.hoisted(() => ({
+ path: null as string | null,
+ release: null as Promise<void> | null,
+ onEntered: null as (() => void) | null,
+ onWritten: null as (() => void) | null,
+}));
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('node:fs/promises')>();
+ return {
+ ...actual,
+ writeFile: (async (...args: Parameters<typeof actual.writeFile>) => {
+ if (String(args[0]) !== lossAppendHold.path) return actual.writeFile(...args);
+ const release = lossAppendHold.release;
+ if (!release) throw new Error('loss append hold is not configured');
+ lossAppendHold.onEntered?.();
+ await release;
+ await actual.writeFile(...args);
+ lossAppendHold.onWritten?.();
+ }) as typeof actual.writeFile,
+ };
+});
+
interface FloorHarness {
readonly wired: WiredPreDrainRig;
readonly shadow: ShadowHandle;
@@ -38,7 +63,15 @@ interface FloorHarness {
cleanup(): Promise<void>;
}
-async function createFloorHarness(docName: string): Promise<FloorHarness> {
+interface FloorCleanupSignals {
+ afterWiredCleanup?(): void;
+ beforeRemove?(): Promise<void> | void;
+}
+
+async function createFloorHarness(
+ docName: string,
+ cleanupSignals: FloorCleanupSignals = {},
+): Promise<FloorHarness> {
const tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-defer-floor-'));
const projectRoot = resolve(tmpDir, 'project');
const shadow = await initShadowRepo(projectRoot);
@@ -60,6 +93,13 @@ async function createFloorHarness(docName: string): Promise<FloorHarness> {
},
});
+ async function drainCheckpoint(): Promise<void> {
+ await nextTurn();
+ await shadowOpGateFor(shadow).drain();
+ await nextTurn();
+ await ring.drain();
+ }
+
return {
wired,
shadow,
@@ -79,21 +119,17 @@ async function createFloorHarness(docName: string): Promise<FloorHarness> {
expect(wired.ytextString()).not.toContain(WIRED_PENDING_LINE);
},
awaitDetectorTrip: async () => {
- let trip: LossCaptureEvent | undefined;
- for (let i = 0; i < 100 && !trip; i++) {
- await ring.drain();
- try {
- const events = parseLossCaptureLines(
- readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'),
- );
- trip = events.find((e) => e.event === 'detector-trip' && Boolean(e.checkpointSha));
- } catch {}
- if (!trip) await new Promise((r) => setTimeout(r, 10));
- }
- return trip;
+ await drainCheckpoint();
+ const events = parseLossCaptureLines(
+ readFileSync(lossCaptureCurrentPath(projectRoot), 'utf-8'),
+ );
+ return events.find((e) => e.event === 'detector-trip' && Boolean(e.checkpointSha));
},
cleanup: async () => {
await wired.cleanup();
+ cleanupSignals.afterWiredCleanup?.();
+ await drainCheckpoint();
+ await cleanupSignals.beforeRemove?.();
await rm(tmpDir, { recursive: true, force: true });
},
};
@@ -177,6 +213,121 @@ describe('checkpoint floor after a derive-timing defer', () => {
}
});
+ test('agent undo checkpoint finishes before its shadow fixture is removed', async () => {
+ const wiredCleaned = Promise.withResolvers<void>();
+ const releaseWriter = Promise.withResolvers<void>();
+ let writerFinished = false;
+ let removedBeforeWriterFinished = false;
+ let gate: ReturnType<typeof shadowOpGateFor>;
+ const h = await createFloorHarness('floor-agent-undo-cleanup', {
+ afterWiredCleanup: wiredCleaned.resolve,
+ beforeRemove: async () => {
+ removedBeforeWriterFinished = !writerFinished;
+ await releaseWriter.promise;
+ await gate.drain();
+ },
+ });
+ gate = shadowOpGateFor(h.shadow);
+ const writerEntered = Promise.withResolvers<void>();
+ const realWithMutator = gate.withMutator.bind(gate);
+ const mutatorSpy = vi.spyOn(gate, 'withMutator').mockImplementation((fn) =>
+ realWithMutator(async () => {
+ writerEntered.resolve();
+ await releaseWriter.promise;
+ const result = await fn();
+ writerFinished = true;
+ return result;
+ }),
+ );
+ let cleanup: Promise<void> | undefined;
+ try {
+ h.wired.agentWrite('Agent appended line.', 'append');
+ h.stageDeferredKeystroke();
+ expect(h.wired.agentUndo('last')).toBe(true);
+ await writerEntered.promise;
+
+ cleanup = h.cleanup();
+ await wiredCleaned.promise;
+ releaseWriter.resolve();
+ await cleanup;
+
+ expect(writerFinished).toBe(true);
+ expect(removedBeforeWriterFinished).toBe(false);
+ } finally {
+ releaseWriter.resolve();
+ try {
+ await gate.drain();
+ if (cleanup) await cleanup;
+ else await h.cleanup();
+ } finally {
+ mutatorSpy.mockRestore();
+ }
+ }
+ });
+
+ test('agent undo loss event finishes appending before its shadow fixture is removed', async () => {
+ const wiredCleaned = Promise.withResolvers<void>();
+ const appendEntered = Promise.withResolvers<void>();
+ const releaseAppend = Promise.withResolvers<void>();
+ const appendWritten = Promise.withResolvers<void>();
+ let appendFinished = false;
+ let removedBeforeLossWriteFinished = false;
+ let eventBeforeRemove: LossCaptureEvent | undefined;
+ let h: FloorHarness;
+ h = await createFloorHarness('floor-agent-undo-loss-append', {
+ afterWiredCleanup: wiredCleaned.resolve,
+ beforeRemove: async () => {
+ removedBeforeLossWriteFinished = !appendFinished;
+ await releaseAppend.promise;
+ await h.ring.drain();
+ const events = parseLossCaptureLines(
+ readFileSync(lossCaptureCurrentPath(h.shadow.workTree), 'utf-8'),
+ );
+ eventBeforeRemove = events.find(
+ (event) => event.event === 'detector-trip' && event.docName === h.docName,
+ );
+ },
+ });
+ const gate = shadowOpGateFor(h.shadow);
+ lossAppendHold.path = lossCaptureCurrentPath(h.shadow.workTree);
+ lossAppendHold.release = releaseAppend.promise;
+ lossAppendHold.onEntered = appendEntered.resolve;
+ lossAppendHold.onWritten = () => {
+ appendFinished = true;
+ appendWritten.resolve();
+ };
+ let cleanup: Promise<void> | undefined;
+ try {
+ h.wired.agentWrite('Agent appended line.', 'append');
+ h.stageDeferredKeystroke();
+ expect(h.wired.agentUndo('last')).toBe(true);
+ cleanup = h.cleanup();
+
+ await wiredCleaned.promise;
+ await appendEntered.promise;
+ releaseAppend.resolve();
+ await appendWritten.promise;
+ await cleanup;
+
+ expect(eventBeforeRemove?.checkpointSha).toBeDefined();
+ expect(eventBeforeRemove?.site).toBe(DERIVE_LOSS_SITE_AGENT_UNDO);
+ expect(removedBeforeLossWriteFinished).toBe(false);
+ } finally {
+ releaseAppend.resolve();
+ try {
+ await gate.drain();
+ await h.ring.drain();
+ if (cleanup) await cleanup;
+ else await h.cleanup();
+ } finally {
+ lossAppendHold.path = null;
+ lossAppendHold.release = null;
+ lossAppendHold.onEntered = null;
+ lossAppendHold.onWritten = null;
+ }
+ }
+ });
+
test('file-watcher change: the deferred keystroke lands on the floor, restorable', async () => {
const h = await createFloorHarness('floor-file-watcher');
try {
diff --git a/packages/server/src/shadow-drain-on-destroy.test.ts b/packages/server/src/shadow-drain-on-destroy.test.ts
index ab4277ec9..55123efe0 100644
--- a/packages/server/src/shadow-drain-on-destroy.test.ts
+++ b/packages/server/src/shadow-drain-on-destroy.test.ts
@@ -1,24 +1,48 @@
import { existsSync, rmSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, normalize } from 'node:path';
+import { setImmediate as nextTurn } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { getCallSites } from 'node:util';
import simpleGit from 'simple-git';
-import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { createServer, type ServerInstance, SHADOW_FANOUT_WARMUP_MS } from './server-factory.ts';
import { type ShadowOpGate, shadowOpGateFor } from './shadow-op-gate.ts';
import { FANOUT_INDEX_NAME, initShadowRepo, type ShadowHandle } from './shadow-repo.ts';
+const serverFactoryPath = fileURLToPath(new URL('./server-factory.ts', import.meta.url));
+
+const warmupObservers = vi.hoisted(
+ () => new Map<string, (operation: { promise: Promise<string> }) => void>(),
+);
+
+vi.mock('./shadow-repo.ts', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('./shadow-repo.ts')>();
+ return {
+ ...actual,
+ buildWipTree: (...args: Parameters<typeof actual.buildWipTree>) => {
+ const promise = actual.buildWipTree(...args);
+ warmupObservers.get(args[0].gitDir)?.({ promise });
+ return promise;
+ },
+ };
+});
+
describe('createServer() — shadow mutator drain on destroy', () => {
+ const heldReleases: Array<() => void> = [];
let projectDir: string;
let shadow: ShadowHandle;
let gate: ShadowOpGate;
let server: ServerInstance | null;
+ let warmupStarted: Promise<{ promise: Promise<string> }>;
function deferred(): { promise: Promise<void>; resolve: () => void } {
let resolve!: () => void;
const promise = new Promise<void>((r) => {
resolve = r;
});
+ heldReleases.push(resolve);
return { promise, resolve };
}
@@ -35,15 +59,27 @@ describe('createServer() — shadow mutator drain on destroy', () => {
shadow = await initShadowRepo(projectDir);
gate = shadowOpGateFor(shadow);
+ warmupStarted = new Promise((resolve) => {
+ warmupObservers.set(shadow.gitDir, resolve);
+ });
server = null;
});
afterEach(async () => {
- await server?.destroy().catch(() => {});
- await rm(projectDir, { recursive: true, force: true });
+ try {
+ for (const release of heldReleases.splice(0)) release();
+ await server?.destroy().catch(() => {});
+ await gate.drain();
+ await rm(projectDir, { recursive: true, force: true });
+ } finally {
+ warmupObservers.delete(shadow.gitDir);
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ vi.useRealTimers();
+ }
});
- async function boot(destroyTimeoutMs: number): Promise<ServerInstance> {
+ async function bootReady(destroyTimeoutMs: number): Promise<ServerInstance> {
const srv = createServer({
contentDir: projectDir,
projectDir,
@@ -56,6 +92,148 @@ describe('createServer() — shadow mutator drain on destroy', () => {
return srv;
}
+ async function boot(
+ destroyTimeoutMs: number,
+ signals: { afterReady?(): void; beforeReturn?(): void } = {},
+ ): Promise<ServerInstance> {
+ const srv = await bootReady(destroyTimeoutMs);
+ signals.afterReady?.();
+ await (await warmupStarted).promise;
+ await gate.drain();
+ signals.beforeReturn?.();
+ return srv;
+ }
+
+ test('boot precondition joins a started fan-out write before mutator counts are asserted', async () => {
+ const warmupEntered = deferred();
+ const readyReached = deferred();
+ const releaseWarmup = deferred();
+ const schedule = globalThis.setTimeout;
+ let triggerWarmup: (() => void) | undefined;
+ vi.stubGlobal('setTimeout', ((callback: () => void, ms?: number, ...args: unknown[]) => {
+ const caller = getCallSites(2)[1]?.scriptName;
+ if (ms !== SHADOW_FANOUT_WARMUP_MS || !caller || normalize(caller) !== serverFactoryPath) {
+ return schedule(callback, ms, ...args);
+ }
+ const timer = schedule(() => {}, ms);
+ triggerWarmup = () => {
+ clearTimeout(timer);
+ callback();
+ };
+ return timer;
+ }) as typeof setTimeout);
+
+ const realWithMutator = gate.withMutator.bind(gate);
+ let triggeringWarmup = false;
+ let warmupFinished = false;
+ vi.spyOn(gate, 'withMutator').mockImplementation((fn) => {
+ if (!triggeringWarmup) return realWithMutator(fn);
+ return realWithMutator(async () => {
+ warmupEntered.resolve();
+ await releaseWarmup.promise;
+ const result = await fn();
+ warmupFinished = true;
+ return result;
+ });
+ });
+
+ let bootReturnedBeforeWarmupFinished = false;
+ try {
+ const booted = boot(10_000, {
+ afterReady: () => {
+ triggeringWarmup = true;
+ triggerWarmup?.();
+ triggeringWarmup = false;
+ readyReached.resolve();
+ },
+ beforeReturn: () => {
+ bootReturnedBeforeWarmupFinished = !warmupFinished;
+ },
+ });
+ await readyReached.promise;
+ expect(triggerWarmup).toBeDefined();
+ await warmupEntered.promise;
+ releaseWarmup.resolve();
+ const srv = await booted;
+ await gate.drain();
+
+ expect(warmupFinished).toBe(true);
+ expect(gate.activeMutators).toBe(0);
+ expect(bootReturnedBeforeWarmupFinished).toBe(false);
+ await srv.destroy();
+ } finally {
+ releaseWarmup.resolve();
+ }
+ });
+
+ test('boot precondition waits for a fan-out timer that has not fired at ready', async () => {
+ const readyReached = deferred();
+ const warmupEntered = deferred();
+ const releaseWarmup = deferred();
+ const schedule = globalThis.setTimeout;
+ let triggerWarmup: (() => void) | undefined;
+ let warmupTimerFired = false;
+ vi.stubGlobal('setTimeout', ((callback: () => void, ms?: number, ...args: unknown[]) => {
+ const caller = getCallSites(2)[1]?.scriptName;
+ if (ms !== SHADOW_FANOUT_WARMUP_MS || !caller || normalize(caller) !== serverFactoryPath) {
+ return schedule(callback, ms, ...args);
+ }
+ const timer = schedule(() => {}, ms);
+ triggerWarmup = () => {
+ clearTimeout(timer);
+ warmupTimerFired = true;
+ callback();
+ };
+ return timer;
+ }) as typeof setTimeout);
+
+ const realWithMutator = gate.withMutator.bind(gate);
+ let triggeringWarmup = false;
+ let warmupFinished = false;
+ vi.spyOn(gate, 'withMutator').mockImplementation((fn) => {
+ if (!triggeringWarmup) return realWithMutator(fn);
+ return realWithMutator(async () => {
+ warmupEntered.resolve();
+ await releaseWarmup.promise;
+ const result = await fn();
+ warmupFinished = true;
+ return result;
+ });
+ });
+
+ let bootReturned = false;
+ try {
+ const booted = boot(10_000, {
+ afterReady: readyReached.resolve,
+ beforeReturn: () => {
+ bootReturned = true;
+ },
+ });
+ await readyReached.promise;
+ expect(triggerWarmup).toBeDefined();
+ expect(warmupTimerFired).toBe(false);
+ expect(gate.activeMutators).toBe(0);
+ await nextTurn();
+ const returnedWhileTimerPending = bootReturned;
+
+ triggeringWarmup = true;
+ triggerWarmup?.();
+ triggeringWarmup = false;
+ await warmupEntered.promise;
+ releaseWarmup.resolve();
+ const srv = await booted;
+ await gate.drain();
+
+ expect(warmupTimerFired).toBe(true);
+ expect(warmupFinished).toBe(true);
+ expect(gate.activeMutators).toBe(0);
+ expect(returnedWhileTimerPending).toBe(false);
+ await srv.destroy();
+ } finally {
+ releaseWarmup.resolve();
+ }
+ });
+
test('destroy() stays pending while a shadow mutator is in flight', async () => {
const PROBE_MS = 1_000;
const srv = await boot(10_000);
@@ -81,14 +259,46 @@ describe('createServer() — shadow mutator drain on destroy', () => {
});
test('destroy() cancels the pending fan-out warm-up so no shadow write lands after teardown', async () => {
- const srv = await boot(10_000);
+ const nativeSchedule = globalThis.setTimeout;
+ const nativeCancel = globalThis.clearTimeout;
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ const schedule = globalThis.setTimeout;
+ const cancel = globalThis.clearTimeout;
+ const controlledTimers = new Set<Parameters<typeof clearTimeout>[0]>();
+ let warmupScheduled = false;
+ let warmupFired = false;
+ vi.stubGlobal('setTimeout', ((callback: () => void, ms?: number, ...args: unknown[]) => {
+ const caller = getCallSites(2)[1]?.scriptName;
+ if (ms !== SHADOW_FANOUT_WARMUP_MS || !caller || normalize(caller) !== serverFactoryPath) {
+ return nativeSchedule(callback, ms, ...args);
+ }
+ warmupScheduled = true;
+ const timer = schedule(() => {
+ warmupFired = true;
+ callback();
+ }, ms);
+ controlledTimers.add(timer);
+ return timer;
+ }) as typeof setTimeout);
+ vi.spyOn(globalThis, 'clearTimeout').mockImplementation((timer) => {
+ if (controlledTimers.has(timer)) {
+ cancel(timer);
+ } else {
+ nativeCancel(timer);
+ }
+ });
+ const srv = await bootReady(10_000);
const fanoutIndex = join(shadow.gitDir, FANOUT_INDEX_NAME);
+ expect(warmupScheduled).toBe(true);
+ expect(warmupFired).toBe(false);
+
await srv.destroy();
rmSync(fanoutIndex, { force: true });
- await delay(SHADOW_FANOUT_WARMUP_MS + 500);
+ await vi.advanceTimersByTimeAsync(SHADOW_FANOUT_WARMUP_MS);
await shadowOpGateFor(shadow).drain();
+ expect(warmupFired).toBe(false);
expect(existsSync(fanoutIndex)).toBe(false);
});