Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.tsindex 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.tsindex 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);});