From b4a2a79c55ad485b81bdef0fd87fc90436bd0ca4 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 04:49:19 +0800 Subject: [PATCH] test(lifecycle): move local gate copies, tests/process-global and tests/boundary phase gates onto the shared harness (#11412) * test(lifecycle): replace eight local gate helper copies with the shared harness * test(lifecycle): count an arrival announced in the turn its operation settles * test(lifecycle): move tests/process-global phase gates onto the shared harness (#11414) * test(lifecycle): move tests/process-global phase gates onto the shared harness * test(lifecycle): move tests/boundary filesystem and process phase gates onto the shared harness (#11418) * test(lifecycle): move tests/boundary provider phase gates onto the shared harness * test(lifecycle): move tests/boundary/mcp phase gates onto the shared harness (#11433) * test(lifecycle): give each phaseGate hold its own promise so unhandled held rejections stay visible * test(lifecycle): move tests/boundary browser, pcap and CLI worker phase gates onto the shared harness (#11437) * test(lifecycle): move tests/boundary browser, pcap and CLI worker phase gates onto the shared harness * test(lifecycle): move fixture-owned and arrival-only provider gates onto the shared harness (#11441) * test(lifecycle): move src/server and provider phase gates onto the shared harness (#11447) * test(lifecycle): move the remaining src server, Kuna copy, Frida and Ghidra phase gates onto the shared harness (#11471) --- docs/development/testing.md | 3 +- .../analysisView/evidenceFileSource.test.ts | 4 +- .../binary/DeferredAnalysisClient.test.ts | 126 ++++------ .../frida/FridaInstrumentationService.test.ts | 40 +--- src/browser/IsolatedWebBundleAnalyzer.test.ts | 34 +-- src/browser/PlaywrightScenarioBrowser.test.ts | 207 +++++----------- src/desktop/DesktopBuildDoctorFacts.test.ts | 2 +- src/frida/FridaInstrumentationManager.test.ts | 106 +++------ src/ghidra/GhidraProvider.behavior.test.ts | 107 ++++----- src/ghidra/GhidraRequestQueue.test.ts | 60 ++--- src/ida/IdaSessionClient.test.ts | 33 +-- src/inspector/V8InspectorAdmission.test.ts | 2 +- src/jeb/JebProvider.test.ts | 11 +- src/kuna/KunaCopy.test.ts | 50 ++-- src/resources/ArtifactResourceScope.test.ts | 58 ++--- src/server/DeferredEvidenceMcpServer.test.ts | 107 ++++----- src/server/EvidenceMcpServer.test.ts | 44 +--- .../environment/serveEnvironmentState.test.ts | 24 +- src/server/http/serveStreamableHttp.test.ts | 225 ++++++------------ .../cdpBrowserProvider.browserSocket.test.ts | 111 +++------ ...BrowserProvider.lifecycle_failures.test.ts | 10 +- .../browser/cdpEndpointResponseBounds.test.ts | 20 +- .../browser/cdpTargetSessionOwner.test.ts | 40 ++-- .../browser/historicalCaptureDecoder.test.ts | 14 +- .../browser/runtimeFixtureReadiness.test.ts | 42 +--- .../browser/webSourceMapFetcher.test.ts | 28 +-- .../boundary/cli/cliWorkerCompletion.test.ts | 9 +- .../evm/evmLimiterAvailability.test.ts | 41 +--- .../filesystem/analysisSnapshot.test.ts | 2 +- .../filesystem/asarReaderCleanup.test.ts | 20 +- .../composedWorkflowEvidenceLinks.test.ts | 15 +- .../filesystem/desktopApplication.test.ts | 20 +- .../filesystem/evidenceBundleFiles.test.ts | 2 +- .../ghidraLanguageCatalogRecovery.test.ts | 15 +- .../ghidraProfileArtifactOwnership.test.ts | 19 +- .../ownedArtifactReaderCleanup.test.ts | 21 +- .../filesystem/processCliFileInput.test.ts | 2 +- .../setupClientConfigCleanupOwnership.test.ts | 20 +- .../setupSkillCleanupOwnership.test.ts | 20 +- .../filesystem/stableArtifact.test.ts | 24 +- .../filesystem/windowsShortcut.test.ts | 32 +-- .../il2cpp/il2cppMetadataProvider.test.ts | 36 +-- .../javascriptSourceAnalysisWorker.test.ts | 20 +- .../applicationMcpHarnessLifecycle.test.ts | 15 +- tests/boundary/mcp/buildSecretsMcp.test.ts | 23 +- .../mcp/bundleComparisonCancellation.test.ts | 12 +- .../mcp/capabilityRemediationMcp.test.ts | 10 +- .../mcp/cutterCancellationMcp.test.ts | 42 ++-- .../mcp/errorEvidenceLifecycleMcp.test.ts | 117 +++------ .../mcp/evidenceImportCancellation.test.ts | 10 +- .../mcp/evidenceImportLifecycle.test.ts | 43 ++-- tests/boundary/mcp/evmInterfaceMcp.test.ts | 8 +- tests/boundary/mcp/fridaLifecycleMcp.test.ts | 133 +++-------- tests/boundary/mcp/fridaMcp.test.ts | 19 +- .../mcp/gdbRetirementCancellation.test.ts | 48 ++-- .../mcp/ghidraStartupCancellationMcp.test.ts | 29 +-- tests/boundary/mcp/goBinaryMcp.test.ts | 25 +- .../mcp/investigationAnalysisMcp.test.ts | 29 +-- .../mcp/investigationLifecycleMcp.test.ts | 44 ++-- .../lateAbortApplicationEvidenceMcp.test.ts | 43 ++-- .../boundary/mcp/mcpFixtureLifecycle.test.ts | 61 ++--- .../mcp/optionalProviderShutdown.test.ts | 18 +- tests/boundary/mcp/progressMcp.test.ts | 20 +- tests/boundary/mcp/promptMcp.test.ts | 101 +++----- .../boundary/mcp/providerSelectionMcp.test.ts | 103 +++----- .../mcp/resetArtifactCleanupMcp.test.ts | 20 +- tests/boundary/mcp/serverLifecycleMcp.test.ts | 30 +-- .../mcp/sessionAvailabilityRecovery.test.ts | 33 +-- tests/boundary/mcp/sessionMcp.test.ts | 35 +-- .../mcp/successEvidenceLifecycleMcp.test.ts | 45 ++-- tests/boundary/mcp/wasmArtifactMcp.test.ts | 20 +- .../mcp/workflowSnapshotReplayMcp.test.ts | 52 ++-- tests/boundary/pcap/pcapCommand.test.ts | 19 +- tests/boundary/pcap/pcapProvider.test.ts | 18 +- .../darwinProcessRunTokenReader.test.ts | 2 +- .../packageVerifierCommandSemantics.test.ts | 18 +- .../processCleanupRetryOwnership.test.ts | 13 +- .../process/selectedExecutableCleanup.test.ts | 20 +- .../process/verifierArtifactScope.test.ts | 19 +- .../process/verifierTerminalOwner.test.ts | 55 ++--- .../RizinDebugSessionCoverage.part3.test.ts | 20 +- ...RizinDebugSessionReviewRegressions.test.ts | 15 +- .../ghidra/ghidraCheckpointLifecycle.test.ts | 19 +- .../providers/ghidra/ghidraClient.fixture.ts | 9 +- .../providers/ghidra/ghidraClient.test.ts | 129 +++------- .../hopper/hopperClient.health.test.ts | 20 +- .../kuna/kunaHashOwnerPropagation.test.ts | 29 +-- .../kuna/kunaIndependentDecompileMcp.test.ts | 15 +- .../providers/kuna/kunaProjectCache.test.ts | 74 ++---- .../providers/kuna/kunaProvider.test.ts | 34 +-- .../providers/kuna/kunaQueryWork.test.ts | 11 +- .../providers/kuna/kunaRunOwnership.test.ts | 25 +- .../kuna/kunaSingleFunctionRuns.test.ts | 46 +--- .../kuna/kunaWorkspaceRollback.test.ts | 20 +- .../native/nativeCallTargetCleanup.test.ts | 19 +- .../native/nativeCommandResolver.test.ts | 33 +-- .../native/nativePlistFileCleanup.test.ts | 42 +--- .../providers/native/nativeProvider.test.ts | 57 ++--- .../providers/startupCloseWaiters.test.ts | 15 +- .../linuxHopperPublisherVerification.test.ts | 24 +- .../analysis-sessions/providerBinding.test.ts | 52 +--- .../reverseEngineeringEdgeCases.test.ts | 2 +- tests/evaluation/lifecycleHarness.test.ts | 36 ++- tests/fixtures/lifecycleAcknowledgement.ts | 2 +- .../apkSignatureLifecycle.test.ts | 33 +-- .../artifactFileSourceLifecycle.test.ts | 47 ++-- .../cutterDescriptorLifetime.test.ts | 52 ++-- .../environmentFinalizationCli.test.ts | 11 +- .../firmwareFileLifetime.test.ts | 38 +-- .../firmwarePublicationDeadline.test.ts | 20 +- .../ghidraEndpointLifetime.test.ts | 19 +- tests/process-global/gpuFileLifetime.test.ts | 19 +- .../idaWorkspaceCleanup.test.ts | 15 +- .../mainStartupCancellation.test.ts | 33 +-- .../managedBundleReadGuards.test.ts | 2 +- tests/process-global/pwntoolsCleanup.test.ts | 20 +- .../referenceSourceCancellation.test.ts | 2 +- .../selectedArtifactSourceLifecycle.test.ts | 31 +-- .../setupConfigurationConflicts.test.ts | 42 +--- .../setupConfigurationRollback.test.ts | 33 +-- .../sourceToBundleReferenceGuards.test.ts | 2 +- tests/support/holdFirstFileRead.ts | 21 +- tests/support/lifecycleHarness.ts | 55 +++-- 123 files changed, 1507 insertions(+), 2914 deletions(-) diff --git a/docs/development/testing.md b/docs/development/testing.md index 2c0695b7d1..372f9c99b0 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -873,7 +873,8 @@ delay after dispatch does not establish that phase. Use markers, barriers, or owned cleanup seams while preserving real cleanup where feasible. `tests/support/lifecycleHarness.ts` provides the shared controls: `phaseGate` holds a late handshake or in-flight work at a boundary and releases it with a -value or a rejection, `cancelDuringCleanup` +value or a rejection, `phaseArrival` marks a boundary whose work waits on +something else (an abort, another owner), `cancelDuringCleanup` cancels from inside final cleanup, and `controlledCleanup` gives children refused or confirmed outcomes with counted retries. Check server settlement and retained resources even if the MCP SDK rejects the client promise diff --git a/src/application/analysisView/evidenceFileSource.test.ts b/src/application/analysisView/evidenceFileSource.test.ts index 01f8980c24..fbf889194c 100644 --- a/src/application/analysisView/evidenceFileSource.test.ts +++ b/src/application/analysisView/evidenceFileSource.test.ts @@ -228,7 +228,7 @@ describe("evidence-file read failure provenance", () => { const pending = readEvidenceFileSource(path, { signal: controller.signal, }); - await reader.firstRead; + await reader.reached(pending, "first file read"); controller.abort(reason); reader.release(); const result = await pending; @@ -262,7 +262,7 @@ describe("evidence-file read failure provenance", () => { const pending = readEvidenceFileSource(path, { signal: controller.signal, }); - await reader.firstRead; + await reader.reached(pending, "first file read"); controller.abort(reason); reader.release(); const result = await pending; diff --git a/src/application/binary/DeferredAnalysisClient.test.ts b/src/application/binary/DeferredAnalysisClient.test.ts index 401ab78ccb..dbad09f781 100644 --- a/src/application/binary/DeferredAnalysisClient.test.ts +++ b/src/application/binary/DeferredAnalysisClient.test.ts @@ -1,6 +1,9 @@ import { expect, it } from "vitest"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../../tests/fixtures/lifecycleAcknowledgement.js"; +import { + phaseArrival, + phaseGate, +} from "../../../tests/support/lifecycleHarness.js"; import { DeferredAnalysisClient } from "../../providers/DeferredAnalysisClient.js"; import { createAnalysisExecution, @@ -65,13 +68,6 @@ it.each([ } }, ); -const gate = () => { - let resolve!: (value: T) => void; - const promise = new Promise((finish) => { - resolve = finish; - }); - return { promise, resolve }; -}; const child = ( close: AnalysisClient["close"] = async () => ok(null), ): AnalysisClient => ({ @@ -152,33 +148,27 @@ it.each([ ); it("keeps a shared creation alive for an interested peer", async () => { - const entered = gate(), - loading = gate(); + const creation = phaseGate(); let observed: AbortSignal | undefined, creates = 0, closes = 0; const client = new DeferredAnalysisClient(async (signal) => { creates++; observed = signal; - entered.resolve(); - return loading.promise; + return creation.hold(); }, identity.id); const controller = new AbortController(), reason = { request: "one peer leaves" }; const first = client.execute("health", {}, { signal: controller.signal }); const second = client.execute("health", {}); await withVerifierCleanup(async () => { - await awaitAcknowledgement( - entered.promise, - first, - "shared client creation", - ); + await creation.reached(first, "shared client creation"); controller.abort(reason); const cancelled = await first; if (cancelled.ok) throw new Error("Expected peer cancellation"); expect(cancelled.error.cause).toBe(reason); expect(observed?.aborted).toBe(false); - loading.resolve( + creation.release( child(async () => { closes++; return ok(null); @@ -190,7 +180,7 @@ it("keeps a shared creation alive for an interested peer", async () => { expect(closes).toBe(1); }, [ () => controller.abort(), - () => loading.resolve(child()), + () => creation.release(child()), async () => { await Promise.allSettled([first, second]); }, @@ -202,15 +192,12 @@ it("keeps a shared creation alive for an interested peer", async () => { }); it("joins a late acquired client's final cleanup before cancellation settles", async () => { - const entered = gate(), - loading = gate(), - closeEntered = gate(), - closing = gate(); + const creation = phaseGate(), + childClose = phaseGate(); let closes = 0, settled = false; const client = new DeferredAnalysisClient(async () => { - entered.resolve(); - return loading.promise; + return creation.hold(); }, identity.id); const controller = new AbortController(), reason = { request: "late acquisition" }; @@ -221,21 +208,20 @@ it("joins a late acquired client's final cleanup before cancellation settles", a return result; }); await withVerifierCleanup(async () => { - await awaitAcknowledgement(entered.promise, pending, "client creation"); + await creation.reached(pending, "client creation"); controller.abort(reason); - loading.resolve( + creation.release( child(async () => { closes++; - closeEntered.resolve(); - await closing.promise; + await childClose.hold(); return ok(null); }), ); - await awaitAcknowledgement(closeEntered.promise, pending, "client cleanup"); + await childClose.reached(pending, "client cleanup"); expect(settled).toBe(false); expect(client.operationHealthSnapshot()?.state).toBe("idle"); expect(client.reuseReadiness()).toBe("blocked"); - closing.resolve(); + childClose.release(); const result = await pending; if (result.ok) throw new Error("Expected cancellation"); expect(result.error.cause).toBe(reason); @@ -244,8 +230,8 @@ it("joins a late acquired client's final cleanup before cancellation settles", a expect(closes).toBe(1); }, [ () => controller.abort(), - () => loading.resolve(child()), - () => closing.resolve(), + () => creation.release(child()), + () => childClose.release(), async () => { await pending; }, @@ -257,16 +243,13 @@ it("joins a late acquired client's final cleanup before cancellation settles", a }); it("waits for abandoned creation cleanup before sharing a fresh client", async () => { - const entered = gate(), - loading = gate(), - closeEntered = gate(), - closing = gate(); + const creation = phaseGate(), + childClose = phaseGate(); let creates = 0; const client = new DeferredAnalysisClient(async () => { creates++; if (creates > 1) return child(); - entered.resolve(); - return loading.promise; + return creation.hold(); }, identity.id); const controller = new AbortController(); const reason = { request: "first caller" }; @@ -274,20 +257,19 @@ it("waits for abandoned creation cleanup before sharing a fresh client", async ( let second: ReturnType | undefined; let third: ReturnType | undefined; await withVerifierCleanup(async () => { - await awaitAcknowledgement(entered.promise, first, "client creation"); + await creation.reached(first, "client creation"); controller.abort(reason); - loading.resolve( + creation.release( child(async () => { - closeEntered.resolve(); - await closing.promise; + await childClose.hold(); return ok(null); }), ); - await awaitAcknowledgement(closeEntered.promise, first, "client cleanup"); + await childClose.reached(first, "client cleanup"); second = client.execute("health", {}); third = client.execute("health", {}); expect(creates).toBe(1); - closing.resolve(); + childClose.release(); const cancelled = await first; if (cancelled.ok) throw new Error("Expected first caller cancellation"); expect(cancelled.error.cause).toBe(reason); @@ -296,8 +278,8 @@ it("waits for abandoned creation cleanup before sharing a fresh client", async ( expect(creates).toBe(2); }, [ () => controller.abort(), - () => loading.resolve(child()), - () => closing.resolve(), + () => creation.release(child()), + () => childClose.release(), async () => { await Promise.allSettled([first, second, third]); }, @@ -311,11 +293,10 @@ it("waits for abandoned creation cleanup before sharing a fresh client", async ( it.each(["caller", "close", "cleanup", "physical"] as const)( "preserves %s while a new caller waits for abandoned creation", async (outcome) => { - const entered = gate(), - aborted = gate(), - acquisition = gate(), - release = gate(), - cleanupEntered = gate(); + const entered = phaseArrival(), + aborted = phaseArrival(), + acquisition = phaseGate(), + release = phaseGate(); const firstController = new AbortController(); const secondController = new AbortController(); const physical = new ProviderAdapterError( @@ -327,16 +308,15 @@ it.each(["caller", "close", "cleanup", "physical"] as const)( let denied = outcome === "cleanup"; const client = new DeferredAnalysisClient(async (signal) => { creates++; - signal.addEventListener("abort", () => aborted.resolve(), { once: true }); - entered.resolve(); + signal.addEventListener("abort", () => aborted.arrive(), { once: true }); + entered.arrive(); if (outcome === "physical") { - await release.promise; + await release.hold(); throw physical; } - await acquisition.promise; + await acquisition.hold(); return child(async () => { - cleanupEntered.resolve(); - await release.promise; + await release.hold(); return denied ? err( new ProviderCleanupError(identity.id, ["controlled child"], { @@ -354,16 +334,12 @@ it.each(["caller", "close", "cleanup", "physical"] as const)( let second: ReturnType | undefined; let closing: ReturnType | undefined; await withVerifierCleanup(async () => { - await awaitAcknowledgement(entered.promise, first, "client creation"); + await entered.reached(first, "client creation"); firstController.abort("first caller"); - await awaitAcknowledgement(aborted.promise, first, "creation abort"); + await aborted.reached(first, "creation abort"); if (outcome !== "physical") { - acquisition.resolve(); - await awaitAcknowledgement( - cleanupEntered.promise, - first, - "client cleanup", - ); + acquisition.release(); + await release.reached(first, "client cleanup"); } second = client.execute( "analyze_function", @@ -374,7 +350,7 @@ it.each(["caller", "close", "cleanup", "physical"] as const)( ); if (outcome === "caller") secondController.abort("second caller"); if (outcome === "close") closing = client.close(); - release.resolve(); + release.release(); const result = await second; if (result.ok) throw new Error("Expected interrupted creation"); if (outcome === "caller") { @@ -399,8 +375,8 @@ it.each(["caller", "close", "cleanup", "physical"] as const)( }, [ () => firstController.abort(), () => secondController.abort(), - () => acquisition.resolve(), - () => release.resolve(), + () => acquisition.release(), + () => release.release(), async () => { await Promise.allSettled([first, second, closing]); }, @@ -414,16 +390,14 @@ it.each(["caller", "close", "cleanup", "physical"] as const)( ); it("keeps a producer-authored physical failure primary even when it is the caller's abort reason", async () => { - const entered = gate(), - finishing = gate(); + const creation = phaseGate(); const physical = new ProviderAdapterError( identity.id, "create_analysis_client", { diagnostics: { reason: "physical fixture fault" } }, ); const client = new DeferredAnalysisClient(async () => { - entered.resolve(); - await finishing.promise; + await creation.hold(); throw physical; }, identity.id); const controller = new AbortController(); @@ -433,9 +407,9 @@ it("keeps a producer-authored physical failure primary even when it is the calle { signal: controller.signal }, ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(entered.promise, pending, "client creation"); + await creation.reached(pending, "client creation"); controller.abort(physical); - finishing.resolve(); + creation.release(); const result = await pending; if (result.ok) throw new Error("Expected physical failure"); expect(result.error).toMatchObject({ @@ -450,7 +424,7 @@ it("keeps a producer-authored physical failure primary even when it is the calle expect(projectAnalysisError(result.error).code).toBe("execution_failure"); }, [ () => controller.abort(), - () => finishing.resolve(), + () => creation.release(), async () => { await pending; }, diff --git a/src/application/frida/FridaInstrumentationService.test.ts b/src/application/frida/FridaInstrumentationService.test.ts index 9ac269e3d2..b75583c015 100644 --- a/src/application/frida/FridaInstrumentationService.test.ts +++ b/src/application/frida/FridaInstrumentationService.test.ts @@ -16,6 +16,7 @@ import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; import type { Evidence } from "../../domain/evidence.js"; import { ok } from "../../domain/result.js"; import { releaseOwnedCleanup } from "../../../tests/support/cleanupRelease.js"; +import { phaseGate } from "../../../tests/support/lifecycleHarness.js"; const createSession = () => ({ sessionId: "00000000-0000-4000-8000-000000000001", @@ -482,24 +483,15 @@ it.each([false, true])( "native resume failed", { diagnostics: { native_status: "resume_rejected" } }, ); - let markResumeEntered: (() => void) | undefined; - let finishResume: - | ((result: { - readonly ok: false; - readonly error: AnalysisCapabilityUnavailableError; - }) => void) - | undefined; - const resumeEntered = new Promise((resolve) => { - markResumeEntered = resolve; - }); + const resume = phaseGate< + void, + { readonly ok: false; readonly error: AnalysisCapabilityUnavailableError } + >(); let closes = 0; const service = new FridaInstrumentationService( createProvider({ resumeSession() { - markResumeEntered?.(); - return new Promise((resolve) => { - finishResume = resolve; - }); + return resume.hold(); }, async closeSession() { closes += 1; @@ -533,9 +525,9 @@ it.each([false, true])( }, controller.signal, ); - await resumeEntered; + await resume.reached(pending, "native resume"); controller.abort(abortReason); - finishResume?.({ ok: false, error: primary }); + resume.release({ ok: false, error: primary }); const result = await pending; expect(result.ok).toBe(false); @@ -1021,14 +1013,7 @@ it.each([false, true])( ); it("cleans up a session and returns typed cancellation after a pending start", async () => { - let finishStart: (() => void) | undefined; - let markStartCalled: (() => void) | undefined; - const startGate = new Promise((resolve) => { - finishStart = resolve; - }); - const startCalled = new Promise((resolve) => { - markStartCalled = resolve; - }); + const start = phaseGate(); const closed: string[] = []; const provider: FridaInstrumentationPort = { async listDevices() { @@ -1041,8 +1026,7 @@ it("cleans up a session and returns typed cancellation after a pending start", a }; }, async startSession() { - markStartCalled?.(); - await startGate; + await start.hold(); return { ok: true, value: { @@ -1082,9 +1066,9 @@ it("cleans up a session and returns typed cancellation after a pending start", a { mode: "attach", deviceId: "local", pid: 10 }, controller.signal, ); - await startCalled; + await start.reached(pending, "provider session start"); controller.abort(new Error("caller cancelled")); - finishStart?.(); + start.release(); const result = await pending; expect(result.ok).toBe(false); diff --git a/src/browser/IsolatedWebBundleAnalyzer.test.ts b/src/browser/IsolatedWebBundleAnalyzer.test.ts index 05595f4ada..7b4057b985 100644 --- a/src/browser/IsolatedWebBundleAnalyzer.test.ts +++ b/src/browser/IsolatedWebBundleAnalyzer.test.ts @@ -1,4 +1,7 @@ -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; +import { + phaseArrival, + phaseGate, +} from "../../tests/support/lifecycleHarness.js"; import { expect, it } from "vitest"; import { createWebPageInspection } from "../../tests/support/browser/webPageInspection.js"; @@ -319,13 +322,13 @@ it("carries the exact caller cancellation reason and completed prefix facts", as "fetch('/cancelled');", "fetch('/cancelled-suffix');", ]); - const started = deferred(); + const started = phaseArrival(); const controller = new AbortController(); const analyzer = new IsolatedWebBundleAnalyzer(() => ({ analyze: async (script, _timeout, signal) => { if (script.script_key === captured.scripts.items[0]?.script_key) return ok(analyzeCapturedWebScript(script)); - started.resolve(); + started.arrive(); await waitForAbort(signal); return err({ error: new AnalysisCancelledError("analyze_web_bundle", { @@ -346,7 +349,7 @@ it("carries the exact caller cancellation reason and completed prefix facts", as ); let result: Awaited; try { - await awaitAcknowledgement(started.promise, pending, "script analysis"); + await started.reached(pending, "script analysis"); controller.abort(exactReason); result = await pending; } finally { @@ -399,22 +402,18 @@ it("refuses work after close with REA's own cancellation reason, not an absent o it("retains all completed facts when cancellation arrives during worker close", async () => { const captured = inspection(["fetch('/one');", "fetch('/two');"]); - const closeStarted = deferred(); - let closeWorker: (() => void) | undefined; + const workerClose = phaseGate(); const analyzer = new IsolatedWebBundleAnalyzer(() => ({ analyze: async (script) => ok(analyzeCapturedWebScript(script)), close: async () => { - closeStarted.resolve(); - await new Promise((resolve) => { - closeWorker = resolve; - }); + await workerClose.hold(); }, })); expect((await analyzer.reserve()).ok).toBe(true); const pending = analyzer.analyze(captured, noSourceMaps, input); - await closeStarted.promise; + await workerClose.reached(pending, "worker close"); const closing = analyzer.close(); - closeWorker?.(); + workerClose.release(); await closing; const result = await pending; analyzer.releaseReservation(); @@ -565,17 +564,6 @@ const waitForAbort = (signal: AbortSignal | undefined): Promise => { }); }; -const deferred = (): { - promise: Promise; - resolve: (value: T) => void; -} => { - let resolve!: (value: T) => void; - const promise = new Promise((done) => { - resolve = done; - }); - return { promise, resolve }; -}; - const inspection = (sources: readonly string[]) => createWebPageInspection( sources.map((source, index) => ({ diff --git a/src/browser/PlaywrightScenarioBrowser.test.ts b/src/browser/PlaywrightScenarioBrowser.test.ts index 9c373a4a12..30bbd71c69 100644 --- a/src/browser/PlaywrightScenarioBrowser.test.ts +++ b/src/browser/PlaywrightScenarioBrowser.test.ts @@ -6,7 +6,7 @@ import { afterEach, expect, it, vi } from "vitest"; import { mkdir, writeFile, rm, access, symlink } from "node:fs/promises"; import { join } from "node:path"; import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../tests/support/lifecycleHarness.js"; import type { Browser, BrowserContext, @@ -50,14 +50,6 @@ it("locks one attached browser across loopback spellings of one endpoint", () => ); }); -const deferred = () => { - let resolve: (value: Value | PromiseLike) => void = () => undefined; - const promise = new Promise((resolvePromise) => { - resolve = resolvePromise; - }); - return { promise, resolve }; -}; - it("passes the selected environment to the actual browser launch boundary", async () => { vi.stubEnv("LANG", "ambient-language"); const selected = { @@ -215,8 +207,7 @@ it.each([false, true])( async (cancelled) => { const controller = new AbortController(); const reason = { caller: "cancelled during browser launch" }; - const started = deferred(); - const launched = deferred(); + const launch = phaseGate(); let profile = ""; const close = vi.fn(async () => undefined); const newPage = vi.fn(async () => ({}) as Page); @@ -228,8 +219,7 @@ it.each([false, true])( launcher: { launchPersistentContext: (directory) => { profile = directory; - started.resolve(undefined); - return launched.promise; + return launch.hold(); }, connectOverCDP: async () => { throw new Error("Unexpected connection"); @@ -247,9 +237,9 @@ it.each([false, true])( newPage, } as unknown as BrowserContext; try { - await awaitAcknowledgement(started.promise, opening, "browser launch"); + await launch.reached(opening, "browser launch"); if (cancelled) controller.abort(reason); - launched.resolve(context); + launch.release(context); const result = await opening; if (result.ok) { try { @@ -272,7 +262,7 @@ it.each([false, true])( await expect(access(profile)).rejects.toMatchObject({ code: "ENOENT" }); } finally { controller.abort(reason); - launched.resolve(context); + launch.release(context); const outcome = await opening; if (outcome.ok) await outcome.value.cleanup.close(); } @@ -350,13 +340,12 @@ it("waits for bounded event finalization and owned browser teardown", async () = it("keeps attached-target ownership after the cleanup response timeout", async () => { vi.useFakeTimers(); try { - const closeStarted = deferred(); - const closeResult = deferred(); + const browserClose = phaseGate(); const settled: boolean[] = []; const cleanup = new PlaywrightScenarioBrowserCleanupOwner({ closeBrowser: async (disconnectAtBoundary) => { - closeStarted.resolve(undefined); - await disconnectAtBoundary(() => closeResult.promise); + const closed = browserClose.hold(); + await disconnectAtBoundary(() => closed); }, removeProfile: undefined, onSettled: (browserClosed) => settled.push(browserClosed), @@ -370,7 +359,7 @@ it("keeps attached-target ownership after the cleanup response timeout", async ( reason: "cleanup_failed", cleanup: { reason: expect.stringContaining("timed out") }, }); - await closeStarted.promise; + await browserClose.reached(timedOutClose, "browser close"); let responseSettled = false; void timedOutClose .finally(() => { @@ -385,7 +374,7 @@ it("keeps attached-target ownership after the cleanup response timeout", async ( await timeoutExpectation; expect(settled).toEqual([]); - closeResult.resolve(undefined); + browserClose.release(); await cleanup.close(); expect(settled).toEqual([true]); expect(timedOutFailure).toMatchObject({ @@ -398,9 +387,10 @@ it("keeps attached-target ownership after the cleanup response timeout", async ( }); it("does not configure a late attached connection after cancellation", async () => { - const connection = - deferred>(); - const connectionStarted = deferred(); + const connection = phaseGate< + void, + Pick + >(); const connectedBrowser = { close: vi.fn(async () => undefined), contexts: vi.fn(() => []), @@ -409,10 +399,7 @@ it("does not configure a late attached connection after cancellation", async () }; const controller = new AbortController(); const launcher = { - connectOverCDP: () => { - connectionStarted.resolve(undefined); - return connection.promise; - }, + connectOverCDP: () => connection.hold(), launchPersistentContext: async () => { throw new Error("Unexpected launch"); }, @@ -435,13 +422,9 @@ it("does not configure a late attached connection after cancellation", async () }, ); try { - await awaitAcknowledgement( - connectionStarted.promise, - opening, - "CDP connection", - ); + await connection.reached(opening, "CDP connection"); controller.abort(); - connection.resolve(connectedBrowser); + connection.release(connectedBrowser); await expect(opening).rejects.toMatchObject({ _tag: "BrowserObservationError", @@ -451,7 +434,7 @@ it("does not configure a late attached connection after cancellation", async () expect(connectedBrowser.close).toHaveBeenCalledOnce(); } finally { controller.abort(); - connection.resolve(connectedBrowser); + connection.release(connectedBrowser); const opened = await opening.catch(() => undefined); await opened?.cleanup.close(); } @@ -643,8 +626,7 @@ it("restores its environment overrides before releasing an attached browser", as }); it("checks a late stop after attached restoration and before transport disconnect", async () => { - const restorationStarted = deferred(); - const finishRestoration = deferred(); + const restoration = phaseGate(); const order: string[] = []; const fixture = attachedBrowserFixture({ send: async (method, parameters) => { @@ -653,8 +635,7 @@ it("checks a late stop after attached restoration and before transport disconnec (parameters as { timezoneId?: string }).timezoneId === "" ) { order.push("restore-started"); - restorationStarted.resolve(undefined); - await finishRestoration.promise; + await restoration.hold(); order.push("restore-finished"); } }, @@ -674,16 +655,12 @@ it("checks a late stop after attached restoration and before transport disconnec }); try { - await awaitAcknowledgement( - restorationStarted.promise, - release, - "browser restoration", - ); + await restoration.reached(release, "browser restoration"); revision += 1; - finishRestoration.resolve(undefined); + restoration.release(); await release; } finally { - finishRestoration.resolve(undefined); + restoration.release(); await release.catch(() => undefined); } @@ -777,27 +754,21 @@ it("restores an attached environment override whose success reply is malformed", }); it("waits for a cancelled environment mutation before restoring it", async () => { - const localeStarted = deferred(); - const localeResult = deferred(); + const localeMutation = phaseGate(); const fixture = attachedBrowserFixture({ send: async (method, parameters) => { if ( method === "Emulation.setLocaleOverride" && (parameters as { locale?: string }).locale === "en-US" ) { - localeStarted.resolve(undefined); - await localeResult.promise; + await localeMutation.hold(); } }, }); const controller = new AbortController(); const opening = fixture.open(controller.signal); try { - await awaitAcknowledgement( - localeStarted.promise, - opening, - "locale mutation", - ); + await localeMutation.reached(opening, "locale mutation"); const cancelled = expect(opening).rejects.toMatchObject({ _tag: "AnalysisCancelledError", }); @@ -808,7 +779,7 @@ it("waits for a cancelled environment mutation before restoring it", async () => { locale: "" }, ); - localeResult.resolve(undefined); + localeMutation.release(); await cancelled; expect(fixture.environmentSession.send).toHaveBeenCalledWith( "Emulation.setLocaleOverride", @@ -818,7 +789,7 @@ it("waits for a cancelled environment mutation before restoring it", async () => expect(fixture.browser.close).toHaveBeenCalledOnce(); } finally { controller.abort(); - localeResult.resolve(undefined); + localeMutation.release(); const opened = await opening.catch(() => undefined); await opened?.cleanup.close(); } @@ -881,21 +852,11 @@ it("cancels same-target queued connection before acquiring a browser", async () }, ], }); - let rejectFirst: ((cause: Error) => void) | undefined; - const firstConnection = new Promise((_resolve, reject) => { - rejectFirst = reject; - }); - let resolveFirstStarted: (() => void) | undefined; - const firstStarted = new Promise((resolve) => { - resolveFirstStarted = resolve; - }); + const firstConnection = phaseGate(); const endpoints: string[] = []; const connectOverCDP = vi.fn((endpoint: string) => { endpoints.push(endpoint); - if (endpoints.length === 1) { - resolveFirstStarted?.(); - return firstConnection; - } + if (endpoints.length === 1) return firstConnection.hold(); return Promise.reject(new Error("connection failed")); }); const launchPersistentContext = vi.fn(async () => { @@ -908,7 +869,7 @@ it("cancels same-target queued connection before acquiring a browser", async () environment, { launcher }, ); - await firstStarted; + await firstConnection.reached(first, "first CDP connection"); expect(connectOverCDP).toHaveBeenCalledTimes(1); const controller = new AbortController(); @@ -945,9 +906,7 @@ it("cancels same-target queued connection before acquiring a browser", async () }); expect(launchPersistentContext).toHaveBeenCalledTimes(1); - if (rejectFirst === undefined) - throw new Error("first connection did not begin"); - rejectFirst(new Error("first connection failed")); + firstConnection.reject(new Error("first connection failed")); await expect(first).rejects.toThrow("first connection failed"); await expect( openPlaywrightScenarioBrowser(makeScenario("page-1"), environment, { @@ -970,20 +929,18 @@ it("serializes concurrent attach across loopback spellings of one browser", asyn }, ], }); - const firstConnection = - deferred>(); + const firstConnection = phaseGate< + void, + Pick + >(); let rejectFirstConnection: ((cause: Error) => void) | undefined; const failingConnection = new Promise((_resolve, reject) => { rejectFirstConnection = reject; }); - const firstStarted = deferred(); const endpoints: string[] = []; const connectOverCDP = vi.fn((endpoint: string) => { endpoints.push(endpoint); - if (endpoints.length === 1) { - firstStarted.resolve(undefined); - return firstConnection.promise; - } + if (endpoints.length === 1) return firstConnection.hold(); return failingConnection; }); const launcher = { @@ -998,7 +955,7 @@ it("serializes concurrent attach across loopback spellings of one browser", asyn {}, { launcher }, ); - await firstStarted.promise; + await firstConnection.reached(first, "first CDP connection"); const second = openPlaywrightScenarioBrowser( makeScenario("http://[::1]:9222"), @@ -1017,7 +974,7 @@ it("serializes concurrent attach across loopback spellings of one browser", asyn expect(race).toBe("queued"); expect(connectOverCDP).toHaveBeenCalledTimes(1); - firstConnection.resolve({ + firstConnection.release({ close: vi.fn(async () => undefined), contexts: vi.fn(() => []), isConnected: vi.fn(() => true), @@ -1086,10 +1043,8 @@ it("tracks only pending browser cleanup resources and resolves prior errors afte }); it("rechecks the browser release gate after finalization changes its revision", async () => { - const eventsStarted = deferred(); - const finishEvents = deferred(); - const gateStarted = deferred(); - const finishGate = deferred(); + const eventFinalization = phaseGate(); + const releaseGate = phaseGate(); const closeBrowser = vi.fn( async ( disconnectAtBoundary: (disconnect: () => Promise) => Promise, @@ -1103,8 +1058,7 @@ it("rechecks the browser release gate after finalization changes its revision", const gateRuns: number[] = []; const release = owner.release( async () => { - eventsStarted.resolve(undefined); - await finishEvents.promise; + await eventFinalization.hold(); }, { get revision() { @@ -1112,32 +1066,21 @@ it("rechecks the browser release gate after finalization changes its revision", }, async run() { gateRuns.push(revision); - if (gateRuns.length === 1) { - gateStarted.resolve(undefined); - await finishGate.promise; - } + if (gateRuns.length === 1) await releaseGate.hold(); }, }, ); try { - await awaitAcknowledgement( - eventsStarted.promise, - release, - "browser event finalization", - ); - finishEvents.resolve(undefined); - await awaitAcknowledgement( - gateStarted.promise, - release, - "browser release gate", - ); + await eventFinalization.reached(release, "browser event finalization"); + eventFinalization.release(); + await releaseGate.reached(release, "browser release gate"); revision += 1; - finishGate.resolve(undefined); + releaseGate.release(); await release; } finally { - finishEvents.resolve(undefined); - finishGate.resolve(undefined); + eventFinalization.release(); + releaseGate.release(); await release.catch(() => undefined); } @@ -1147,15 +1090,13 @@ it("rechecks the browser release gate after finalization changes its revision", }); it("runs the latest stop gate after attached restoration and before disconnect", async () => { - const restorationStarted = deferred(); - const finishRestoration = deferred(); + const restoration = phaseGate(); const gateRevisions: number[] = []; let revision = 0; let disconnected = false; const owner = new PlaywrightScenarioBrowserCleanupOwner({ closeBrowser: async (disconnectAtBoundary) => { - restorationStarted.resolve(undefined); - await finishRestoration.promise; + await restoration.hold(); await disconnectAtBoundary(async () => { disconnected = true; }); @@ -1172,16 +1113,12 @@ it("runs the latest stop gate after attached restoration and before disconnect", }); try { - await awaitAcknowledgement( - restorationStarted.promise, - release, - "browser restoration", - ); + await restoration.reached(release, "browser restoration"); revision += 1; - finishRestoration.resolve(undefined); + restoration.release(); await release; } finally { - finishRestoration.resolve(undefined); + restoration.release(); await release.catch(() => undefined); } @@ -1209,8 +1146,7 @@ it.each([false, true])( removeProfile: undefined, }); const failure = new Error("navigation stop was not confirmed"); - const gateStarted = deferred(); - const finishGate = deferred(); + const gateRun = phaseGate(); let revision = 0; let failGate = true; const gate = { @@ -1220,8 +1156,7 @@ it.each([false, true])( async run() { if (failGate) { failGate = false; - gateStarted.resolve(undefined); - await finishGate.promise; + await gateRun.hold(); throw failure; } }, @@ -1232,13 +1167,9 @@ it.each([false, true])( (cause: unknown) => ({ ok: false as const, cause }), ); try { - await awaitAcknowledgement( - gateStarted.promise, - release, - "browser release gate", - ); + await gateRun.reached(release, "browser release gate"); if (changeRevision) revision += 1; - finishGate.resolve(undefined); + gateRun.release(); await expect(release).resolves.toEqual({ ok: false, cause: failure }); expect(closeBrowser).toHaveBeenCalledTimes(1); expect(transportClosed).toBe(false); @@ -1250,7 +1181,7 @@ it.each([false, true])( expect(transportClosed).toBe(true); expect(owner.browserClosed).toBe(true); } finally { - finishGate.resolve(undefined); + gateRun.release(); try { await release; } finally { @@ -1515,14 +1446,7 @@ it("closes a context that launches after its deadline before removing the profil it("closes a browser that connects after its deadline without waiting to report the timeout", async () => { vi.useFakeTimers(); - let releaseHandshake!: () => void; - const held = new Promise((resolve) => { - releaseHandshake = resolve; - }); - let handshakeEntered!: () => void; - const entered = new Promise((resolve) => { - handshakeEntered = resolve; - }); + const handshake = phaseGate(); const closed = vi.fn(async () => undefined); const leases: AnalysisCleanupLease[] = []; const scenario = browserScenarioSchema.parse({ @@ -1544,8 +1468,7 @@ it("closes a browser that connects after its deadline without waiting to report retainCleanup: (lease) => leases.push(lease), launcher: { connectOverCDP: async () => { - handshakeEntered(); - await held; + await handshake.hold(); return { close: closed, contexts: () => [], @@ -1564,19 +1487,19 @@ it("closes a browser that connects after its deadline without waiting to report settled = true; }); try { - await entered; + await handshake.reached(opening, "late CDP handshake"); await vi.advanceTimersByTimeAsync(40); expect(settled).toBe(true); expect(closed).not.toHaveBeenCalled(); expect(await opening).toMatchObject({ reason: "timeout" }); expect(leases).toHaveLength(1); expect(leases[0]?.released).toBe(false); - releaseHandshake(); + handshake.release(); await leases[0]!.release(); expect(closed).toHaveBeenCalledTimes(1); expect(leases[0]?.released).toBe(true); } finally { - releaseHandshake(); + handshake.release(); try { await opening; await Promise.all(leases.map((lease) => lease.release())); diff --git a/src/desktop/DesktopBuildDoctorFacts.test.ts b/src/desktop/DesktopBuildDoctorFacts.test.ts index ffb73a2fe7..8caebc5248 100644 --- a/src/desktop/DesktopBuildDoctorFacts.test.ts +++ b/src/desktop/DesktopBuildDoctorFacts.test.ts @@ -884,7 +884,7 @@ it.skipIf(process.platform === "win32")( }, ); await awaitAcknowledgement( - Promise.all([slowReached, closeFailed]).then(() => undefined), + Promise.all([slowReached, closeFailed]), outcome, "slow client probe and failed runner close", ); diff --git a/src/frida/FridaInstrumentationManager.test.ts b/src/frida/FridaInstrumentationManager.test.ts index 832bdd0fae..e28db3ee65 100644 --- a/src/frida/FridaInstrumentationManager.test.ts +++ b/src/frida/FridaInstrumentationManager.test.ts @@ -1,6 +1,8 @@ import { describe, expect, it, onTestFinished, vi } from "vitest"; -import { createDeferred } from "../../tests/fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; +import { + phaseGate, + type PhaseGate, +} from "../../tests/support/lifecycleHarness.js"; import type { Device, @@ -91,8 +93,8 @@ class FakeSession implements Session { nextLoadFailure: Error | undefined; nextUnloadFailureCount = 0; detachFailureCount = 0; - scriptLoadGate: Promise | undefined; - onScriptLoadStarted: (() => void) | undefined; + /** Holds every later script load at the provider boundary. */ + scriptLoad: PhaseGate | undefined; private detachedState = false; readonly pid = 512; @@ -104,8 +106,7 @@ class FakeSession implements Session { const script = new FakeScript( this.nextPayload, async () => { - this.onScriptLoadStarted?.(); - await this.scriptLoadGate; + await this.scriptLoad?.hold(); }, this.nextDescription, this.nextStack, @@ -344,17 +345,9 @@ describe("FridaInstrumentationManager", () => { it("records a session already detached during process metadata lookup", async () => { const bindings = new FakeDeviceManager(); - let lookupStarted!: () => void; - const lookupEntered = new Promise((resolve) => { - lookupStarted = resolve; - }); - let finishLookup!: () => void; - const lookupGate = new Promise((resolve) => { - finishLookup = resolve; - }); + const lookup = phaseGate(); bindings.device.getProcessByPid = async () => { - lookupStarted(); - await lookupGate; + await lookup.hold(); return bindings.device.process; }; const manager = new FridaInstrumentationManager({ @@ -365,9 +358,9 @@ describe("FridaInstrumentationManager", () => { deviceId: "local", pid: 512, }); - await lookupEntered; + await lookup.reached(starting, "process metadata lookup"); bindings.device.session.markDetached(); - finishLookup(); + lookup.release(); const started = await starting; expect(started.ok).toBe(true); @@ -1118,22 +1111,14 @@ it("reports truncation when that script loses its own message", async () => { expect(first.ok).toBe(true); if (!first.ok) return; - let finishSecondLoad: (() => void) | undefined; - let markSecondLoadStarted: (() => void) | undefined; - const secondLoadGate = new Promise((resolve) => { - finishSecondLoad = resolve; - }); - const secondLoadStarted = new Promise((resolve) => { - markSecondLoadStarted = resolve; - }); + const secondLoad = phaseGate(); session.nextPayload = { tag: "B2" }; - session.scriptLoadGate = secondLoadGate; - session.onScriptLoadStarted = () => markSecondLoadStarted?.(); + session.scriptLoad = secondLoad; const secondLoading = manager.loadScript(started.value.sessionId, { sourceKind: "inline", source: "send({tag: 'B2'});", }); - await secondLoadStarted; + await secondLoad.reached(secondLoading, "second script load"); const secondScript = session.scripts[1]; expect(secondScript).toBeDefined(); if (secondScript === undefined) return; @@ -1148,7 +1133,7 @@ it("reports truncation when that script loses its own message", async () => { null, ); - finishSecondLoad?.(); + secondLoad.release(); const second = await secondLoading; expect(second.ok).toBe(true); if (second.ok) { @@ -1208,17 +1193,9 @@ it("retains the newest contiguous messages across repeated budget evictions", as it("serializes a final remote release against a new same-endpoint session", async () => { const bindings = new FakeDeviceManager(); - let enteredRemoval: (() => void) | undefined; - const removalEntered = new Promise((resolve) => { - enteredRemoval = resolve; - }); - let finishRemoval: (() => void) | undefined; - const removalGate = new Promise((resolve) => { - finishRemoval = resolve; - }); + const removal = phaseGate(); bindings.removeRemoteDevice = async (address) => { - enteredRemoval?.(); - await removalGate; + await removal.hold(); bindings.removedRemote.push(address); }; const manager = new FridaInstrumentationManager({ @@ -1234,7 +1211,7 @@ it("serializes a final remote release against a new same-endpoint session", asyn if (!first.ok) return; const closing = manager.closeSession(first.value.sessionId); - await removalEntered; + await removal.reached(closing, "final remote release"); let secondStarted = false; const secondPromise = manager .startSession({ mode: "attach", remote, pid: 512 }) @@ -1244,7 +1221,7 @@ it("serializes a final remote release against a new same-endpoint session", asyn }); await Promise.resolve(); expect(secondStarted).toBe(false); - finishRemoval?.(); + removal.release(); expect((await closing).ok).toBe(true); const second = await secondPromise; expect(second.ok).toBe(true); @@ -1746,16 +1723,8 @@ it.each([ it("serializes script loading against concurrent close and unloads the loaded script", async () => { const bindings = new FakeDeviceManager(); - let finishScriptLoad: (() => void) | undefined; - const scriptLoadGate = new Promise((resolve) => { - finishScriptLoad = resolve; - }); - let markScriptLoadStarted: (() => void) | undefined; - const scriptLoadStarted = new Promise((resolve) => { - markScriptLoadStarted = resolve; - }); - bindings.device.session.scriptLoadGate = scriptLoadGate; - bindings.device.session.onScriptLoadStarted = () => markScriptLoadStarted?.(); + const scriptLoad = phaseGate(); + bindings.device.session.scriptLoad = scriptLoad; const manager = new FridaInstrumentationManager({ deviceManager: bindings }); const started = await manager.startSession({ mode: "attach", @@ -1769,7 +1738,7 @@ it("serializes script loading against concurrent close and unloads the loaded sc sourceKind: "inline", source: "send('loaded');", }); - await scriptLoadStarted; + await scriptLoad.reached(loading, "script load"); let closed = false; const closing = manager.closeSession(started.value.sessionId); void closing.then(() => { @@ -1783,7 +1752,7 @@ it("serializes script loading against concurrent close and unloads the loaded sc await Promise.resolve(); expect(closed).toBe(false); expect(secondClosed).toBe(false); - finishScriptLoad?.(); + scriptLoad.release(); expect((await loading).ok).toBe(true); expect((await closing).ok).toBe(true); expect((await secondClose).ok).toBe(true); @@ -1856,11 +1825,9 @@ it.each([false, true])( onTestFinished(() => manager.closeAll()); if (!started.ok) throw started.error; const session = bindings.device.session; - const entered = createDeferred(); - const held = createDeferred(); - onTestFinished(() => held.resolve()); - session.onScriptLoadStarted = entered.resolve; - session.scriptLoadGate = held.promise; + const held = phaseGate(); + onTestFinished(() => held.release()); + session.scriptLoad = held; const nativeFailure = new Error("native load failed"); if (rejectNative) session.nextLoadFailure = nativeFailure; const controller = new AbortController(); @@ -1870,11 +1837,7 @@ it.each([false, true])( { sourceKind: "inline", source: "send('marker')" }, controller.signal, ); - await awaitAcknowledgement( - entered.promise, - loading, - "provider lifecycle boundary", - ); + await held.reached(loading, "provider lifecycle boundary"); const script = session.scripts[0]; if (script === undefined) throw new Error("Missing admitted script"); const unload = script.unload.bind(script); @@ -1887,7 +1850,7 @@ it.each([false, true])( await unload(); }; controller.abort(reason); - held.resolve(); + held.release(); const loaded = await loading; if (loaded.ok) throw new Error("Cancelled load succeeded"); expect(loaded.error).toBeInstanceOf(FridaScriptLoadCancelledError); @@ -1916,15 +1879,13 @@ it("preserves a native rejection observed before cancellation during script clea onTestFinished(() => manager.closeAll()); if (!started.ok) throw started.error; const session = bindings.device.session; - const entered = createDeferred(); - const held = createDeferred(); - onTestFinished(() => held.resolve()); + const providerLifecycleBoundary = phaseGate(); + onTestFinished(() => providerLifecycleBoundary.release()); const create = session.createScript.bind(session); session.createScript = async () => { const script = await create(); script.unload = async () => { - entered.resolve(); - await held.promise; + await providerLifecycleBoundary.hold(); const owned = session.scripts[0]; if (owned !== undefined) owned.isDestroyed = true; }; @@ -1938,13 +1899,12 @@ it("preserves a native rejection observed before cancellation during script clea { sourceKind: "inline", source: "void 0" }, controller.signal, ); - await awaitAcknowledgement( - entered.promise, + await providerLifecycleBoundary.reached( loading, "provider lifecycle boundary", ); controller.abort(new Error("late abort during cleanup")); - held.resolve(); + providerLifecycleBoundary.release(); const result = await loading; if (result.ok) throw new Error("Failed load succeeded"); expect(result.error).toBeInstanceOf(AnalysisCapabilityUnavailableError); diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.ts index 907d0fee5c..28f9becde6 100644 --- a/src/ghidra/GhidraProvider.behavior.test.ts +++ b/src/ghidra/GhidraProvider.behavior.test.ts @@ -37,7 +37,6 @@ import { type AnalysisCallerLifetime, } from "../domain/analysisErrorBase.js"; import { createDeferred } from "../../tests/fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; import { ProviderInspectionScope } from "../ports/ProviderInspectionScope.js"; import { ok as javaProbeOk, err, ok } from "../domain/result.js"; import type { GhidraJavaObservation } from "./GhidraJavaProbe.js"; @@ -53,6 +52,10 @@ import { join } from "node:path"; import { fileURLToPath } from "node:url"; import { promisify } from "node:util"; import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest"; +import { + phaseArrival, + phaseGate, +} from "../../tests/support/lifecycleHarness.js"; import * as nativeLoader from "../windows/WindowsNativeLoader.js"; import { fixtureDosLoadImage, @@ -3021,18 +3024,10 @@ it("shares one session snapshot across callers while isolating cancellation and let calls = 0; let snapshotReads = 0; let snapshotSignal: AbortSignal | undefined; - let releaseSnapshot: - | ((value: Result) => void) - | undefined; - let markSnapshotStarted: (() => void) | undefined; - const snapshotStarted = new Promise((resolve) => { - markSnapshotStarted = resolve; - }); - const snapshotResult = new Promise< + const snapshotRead = phaseGate< + void, Result - >((resolve) => { - releaseSnapshot = resolve; - }); + >(); const factory: GhidraProviderClientFactory = () => ({ start: () => Promise.resolve(ok(sessionInfo())), callTool: (operation) => { @@ -3056,8 +3051,7 @@ it("shares one session snapshot across callers while isolating cancellation and readTargetSnapshot: (_maximumBytes, signal) => { snapshotReads += 1; snapshotSignal = signal; - markSnapshotStarted?.(); - return snapshotResult; + return snapshotRead.hold(); }, close: () => Promise.resolve(ok(null)), }); @@ -3083,7 +3077,7 @@ it("shares one session snapshot across callers while isolating cancellation and signal: secondCaller.signal, }, ); - await snapshotStarted; + await snapshotRead.reached(first, "shared NativeAOT snapshot read"); expect(snapshotReads).toBe(1); expect(snapshotSignal).toBeDefined(); expect(snapshotSignal).not.toBe(firstCaller.signal); @@ -3093,7 +3087,7 @@ it("shares one session snapshot across callers while isolating cancellation and ok: false, error: { _tag: "AnalysisCancelledError" }, }); - releaseSnapshot?.(ok({ kind: "captured", bytes })); + snapshotRead.release(ok({ kind: "captured", bytes })); const secondResult = await second; expect(secondResult).toMatchObject({ ok: true, @@ -3183,18 +3177,10 @@ it.each(["captured", "cancelled-with-facts"] as const)( const bytes = nativeAotPeFixture(); const observation = fixtureDosLoadImage().observation; let calls = 0; - let resolveSnapshot: - | ((value: Result) => void) - | undefined; - let markSnapshotStarted: (() => void) | undefined; - const snapshotStarted = new Promise((resolve) => { - markSnapshotStarted = resolve; - }); - const snapshot = new Promise< + const snapshotRead = phaseGate< + void, Result - >((resolve) => { - resolveSnapshot = resolve; - }); + >(); const factory: GhidraProviderClientFactory = () => ({ start: () => Promise.resolve(ok(sessionInfo())), callTool: () => { @@ -3208,10 +3194,7 @@ it.each(["captured", "cancelled-with-facts"] as const)( ), ); }, - readTargetSnapshot: () => { - markSnapshotStarted?.(); - return snapshot; - }, + readTargetSnapshot: () => snapshotRead.hold(), close: () => Promise.resolve(ok(null)), }); const ghidra = provider(installationHost(), factory); @@ -3221,7 +3204,10 @@ it.each(["captured", "cancelled-with-facts"] as const)( throw new Error("Expected admitted PE profile"); const client = ghidra.createClient(target, profile.value.profile); const originalBase = client.execute("inspect_native_load_image", {}); - await snapshotStarted; + await snapshotRead.reached( + originalBase, + "original NativeAOT snapshot read", + ); const changedBase = await client.execute("inspect_native_load_image", {}); expect(changedBase).toMatchObject({ ok: false, @@ -3233,7 +3219,7 @@ it.each(["captured", "cancelled-with-facts"] as const)( }, }, }); - resolveSnapshot?.( + snapshotRead.release( outcome === "captured" ? ok({ kind: "captured", bytes }) : err( @@ -3364,14 +3350,14 @@ const nativeAotWaiterClient = async () => { const bytes = nativeAotPeFixture(); const observations = fixtureDosLoadImage().observation; observations.image_base = "0x140000000"; - const started = createDeferred(); + const started = phaseArrival(); const snapshot = createDeferred>(); const close = vi.fn(async () => ok(null)); const readSnapshot = vi.fn( (_maximum: number | undefined, signal: AbortSignal | undefined) => { if (signal === undefined) throw new Error("Missing owned read signal"); - started.resolve(signal); + started.arrive(signal); return snapshot.promise; }, ); @@ -3404,7 +3390,10 @@ const nativeAotWaiterClient = async () => { it("joins the in-flight NativeAOT producer before closing its owning client", async () => { const fixture = await nativeAotWaiterClient(); const pending = fixture.client.execute("inspect_native_load_image", {}); - const signal = await fixture.started.promise; + const signal = await fixture.started.reached( + pending, + "NativeAOT snapshot read", + ); let closed = false; const closing = fixture.client.close().then((result) => { closed = true; @@ -3433,7 +3422,10 @@ it("joins final NativeAOT waiter cancellation and retains exact producer cleanup settled = true; return result; }); - const signal = await fixture.started.promise; + const signal = await fixture.started.reached( + pending, + "NativeAOT snapshot read", + ); const cleanup = new ProviderCleanupError( "ghidra", ["controlled snapshot descriptor"], @@ -3481,7 +3473,10 @@ it.each([null, "caller stopped", new Error("caller stopped")])( {}, { signal: caller.signal }, ); - const signal = await fixture.started.promise; + const signal = await fixture.started.reached( + pending, + "NativeAOT snapshot read", + ); caller.abort(reason); await new Promise((resolve) => setImmediate(resolve)); expect(signal.aborted).toBe(true); @@ -3515,7 +3510,7 @@ it.each(["caller", "owner"] as const)( {}, { signal: caller.signal }, ); - await fixture.started.promise; + await fixture.started.reached(pending, "NativeAOT snapshot read"); const cleanup = new ProviderCleanupError( "ghidra", ["controlled snapshot descriptor"], @@ -3581,7 +3576,7 @@ it("lets a new NativeAOT caller join a draining attempt before retrying", async {}, { signal: caller.signal }, ); - await fixture.started.promise; + await fixture.started.reached(first, "NativeAOT snapshot read"); caller.abort("first caller"); await new Promise((resolve) => setImmediate(resolve)); const second = fixture.client.execute("inspect_native_load_image", {}); @@ -3601,7 +3596,7 @@ it("preserves a draining NativeAOT physical failure before later caller cancella {}, { signal: firstCaller.signal }, ); - await fixture.started.promise; + await fixture.started.reached(first, "NativeAOT snapshot read"); firstCaller.abort("first caller"); await new Promise((resolve) => setImmediate(resolve)); const secondCaller = new AbortController(); @@ -3654,7 +3649,7 @@ it("retains drained NativeAOT capture facts with the later caller's exact abort {}, { signal: firstCaller.signal }, ); - await fixture.started.promise; + await fixture.started.reached(first, "NativeAOT snapshot read"); firstCaller.abort("first caller"); await new Promise((resolve) => setImmediate(resolve)); const secondCaller = new AbortController(); @@ -3683,7 +3678,7 @@ it("retains drained NativeAOT capture facts with the later caller's exact abort it("attributes shared NativeAOT producer failure to each requesting operation", async () => { const fixture = await nativeAotWaiterClient(); const image = fixture.client.execute("inspect_native_load_image", {}); - await fixture.started.promise; + await fixture.started.reached(image, "NativeAOT snapshot read"); const detail = fixture.client.execute("inspect_native_data_type", { address: "0x140002280", }); @@ -6566,9 +6561,8 @@ it("reuses readiness only inside its active task and provider lifetime", async ( it.each(["retry", "physical", "cleanup", "close"] as const)( "handles %s during an abandoned installation inspection", async (outcome) => { - const entered = createDeferred(); - const aborted = createDeferred(); - const release = createDeferred(); + const javaInspection = phaseGate(); + const inspectionAbort = phaseArrival(); const base = installationHost(); let probes = 0; let denyCleanup = outcome === "cleanup"; @@ -6582,11 +6576,14 @@ it.each(["retry", "physical", "cleanup", "close"] as const)( probeJava: async (command, environment, options) => { probes++; if (probes === 1) { - options.signal?.addEventListener("abort", () => aborted.resolve(), { - once: true, - }); - entered.resolve(); - await release.promise; + options.signal?.addEventListener( + "abort", + () => inspectionAbort.arrive(), + { + once: true, + }, + ); + await javaInspection.hold(); if (outcome === "physical") return err(physical); if (outcome === "cleanup") { options.resourceOwner?.retain( @@ -6617,15 +6614,15 @@ it.each(["retry", "physical", "cleanup", "close"] as const)( let second: ReturnType | undefined; let closing: ReturnType | undefined; try { - await awaitAcknowledgement(entered.promise, first, "Java inspection"); + await javaInspection.reached(first, "Java inspection"); controller.abort("first inspection"); - await awaitAcknowledgement(aborted.promise, first, "inspection abort"); + await inspectionAbort.reached(first, "inspection abort"); second = ghidra.inspectAvailability(); void second.catch(() => undefined); await Promise.resolve(); expect(probes).toBe(1); if (outcome === "close") closing = ghidra.closeOwnedResources(); - release.resolve(); + javaInspection.release(); if (outcome === "retry") { await expect(first).rejects.toMatchObject({ _tag: "AnalysisCancelledError", @@ -6654,7 +6651,7 @@ it.each(["retry", "physical", "cleanup", "close"] as const)( } } finally { controller.abort(); - release.resolve(); + javaInspection.release(); await Promise.allSettled([first, second, closing]); denyCleanup = false; expect((await ghidra.closeOwnedResources()).ok).toBe(true); diff --git a/src/ghidra/GhidraRequestQueue.test.ts b/src/ghidra/GhidraRequestQueue.test.ts index 9248c63609..1b70d80a46 100644 --- a/src/ghidra/GhidraRequestQueue.test.ts +++ b/src/ghidra/GhidraRequestQueue.test.ts @@ -4,6 +4,7 @@ import { err, ok, type Result } from "../domain/result.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { GhidraRequestQueue } from "./GhidraRequestQueue.js"; import { releaseOwnedCleanup } from "../../tests/support/cleanupRelease.js"; +import { phaseGate } from "../../tests/support/lifecycleHarness.js"; import { bindGhidraSessionFailure, GhidraSessionError, @@ -216,25 +217,16 @@ describe("Ghidra request queue cancellation", () => { }); }); -const deferred = () => { - let resolve!: (value: Value) => void; - let reject!: (cause: unknown) => void; - const promise = new Promise((accept, fail) => { - resolve = accept; - reject = fail; - }); - return { promise, resolve, reject }; -}; type ExecutionResult = Result; type CleanupResult = Result; const nextTurn = () => new Promise((resolve) => setImmediate(resolve)); it("joins a completed response with cancellation cleanup before reporting cancellation", async () => { - const execution = deferred(); - const cleanup = deferred(); - const stop = vi.fn(() => cleanup.promise); + const execution = phaseGate(); + const cleanup = phaseGate(); + const stop = vi.fn(() => cleanup.hold()); const controller = new AbortController(); - const queue = new GhidraRequestQueue(() => execution.promise, failure, stop); + const queue = new GhidraRequestQueue(() => execution.hold(), failure, stop); let settled = false; const pending = queue .run("active", {}, { signal: controller.signal }) @@ -242,11 +234,11 @@ it("joins a completed response with cancellation cleanup before reporting cancel settled = true; return result; }); - execution.resolve(ok(null)); + execution.release(ok(null)); controller.abort(null); await nextTurn(); expect(settled).toBe(false); - cleanup.resolve(ok(null)); + cleanup.release(ok(null)); const result = await pending; expect(result).toMatchObject({ ok: false, @@ -258,7 +250,7 @@ it("joins a completed response with cancellation cleanup before reporting cancel it.each([false, true])( "records the session close on a late remote failure (cleanup failed: %s)", async (cleanupFailed) => { - const execution = deferred(); + const execution = phaseGate(); const original = new GhidraSessionError( "remote", "decompile limit reached", @@ -275,13 +267,13 @@ it.each([false, true])( }, ); const queue = new GhidraRequestQueue( - () => execution.promise, + () => execution.hold(), failure, () => Promise.resolve(cleanupFailed ? err(cleanupFailure) : ok(null)), ); const pending = queue.run("active", {}, { signal: controller.signal }); controller.abort(reason); - execution.resolve(err(original)); + execution.release(err(original)); const result = await pending; if (result.ok) throw new Error("Expected the remote failure"); // The observed failure stays primary; only the session close is added. @@ -304,8 +296,8 @@ it.each([false, true])( ); it("awaits active cancellation cleanup when execution rejects", async () => { - const execution = deferred(); - const cleanup = deferred(); + const execution = phaseGate(); + const cleanup = phaseGate(); const cause = new Error("executor rejected"); const cleanupFailure = new ProviderCleanupError( "ghidra", @@ -314,9 +306,9 @@ it("awaits active cancellation cleanup when execution rejects", async () => { ); const controller = new AbortController(); const queue = new GhidraRequestQueue( - () => execution.promise, + () => execution.hold(), failure, - () => cleanup.promise, + () => cleanup.hold(), ); let settled = false; const pending = queue @@ -329,7 +321,7 @@ it("awaits active cancellation cleanup when execution rejects", async () => { execution.reject(cause); await nextTurn(); expect(settled).toBe(false); - cleanup.resolve(err(cleanupFailure)); + cleanup.release(err(cleanupFailure)); const result = await pending; if (result.ok) throw new Error("Expected execution failure"); expect(result.error).toMatchObject({ kind: "protocol", cause }); @@ -360,9 +352,9 @@ it.each([null, "caller stopped", new Error("caller stopped")])( "retains the exact queued cancellation reason %j", async (reason) => { const controller = new AbortController(); - const execution = deferred(); + const execution = phaseGate(); const queue = new GhidraRequestQueue( - () => execution.promise, + () => execution.hold(), failure, () => Promise.resolve(ok(null)), ); @@ -370,7 +362,7 @@ it.each([null, "caller stopped", new Error("caller stopped")])( const queued = queue.run("queued", {}, { signal: controller.signal }); controller.abort(reason); const result = await queued; - execution.resolve(ok(null)); + execution.release(ok(null)); await active; if (result.ok) throw new Error("Expected queued cancellation"); expect(result.error.cancellation?.reason).toBe(reason); @@ -396,15 +388,15 @@ it.each([null, "caller stopped", new Error("caller stopped")])( it.each(["return", "throw"] as const)( "captures cleanup rejection before execution can %s", async (stage) => { - const execution = deferred(); - const cleanup = deferred(); + const execution = phaseGate(); + const cleanup = phaseGate(); const cause = new Error("early cleanup rejection"); const original = failure("remote", "Observed operation failure"); const controller = new AbortController(); const queue = new GhidraRequestQueue( - () => execution.promise, + () => execution.hold(), failure, - () => cleanup.promise, + () => cleanup.hold(), ); let settled = false; const pending = queue @@ -417,7 +409,7 @@ it.each(["return", "throw"] as const)( cleanup.reject(cause); await nextTurn(); expect(settled).toBe(false); - if (stage === "return") execution.resolve(err(original)); + if (stage === "return") execution.release(err(original)); else execution.reject(original); const result = await pending; if (result.ok) throw new Error("Expected operation and cleanup failure"); @@ -430,11 +422,11 @@ it.each(["return", "throw"] as const)( ); it("retains cleanup uncertainty when the cancellation cleanup callback throws synchronously", async () => { - const execution = deferred(); + const execution = phaseGate(); const cause = new Error("synchronous cleanup rejection"); const controller = new AbortController(); const queue = new GhidraRequestQueue( - () => execution.promise, + () => execution.hold(), failure, () => { throw cause; @@ -442,7 +434,7 @@ it("retains cleanup uncertainty when the cancellation cleanup callback throws sy ); const pending = queue.run("active", {}, { signal: controller.signal }); controller.abort(null); - execution.resolve(ok(null)); + execution.release(ok(null)); const result = await pending; if (result.ok) throw new Error("Expected unconfirmed cancellation cleanup"); expect(result.error).toMatchObject({ diff --git a/src/ida/IdaSessionClient.test.ts b/src/ida/IdaSessionClient.test.ts index 5a5bfeb77a..9152f0eb5f 100644 --- a/src/ida/IdaSessionClient.test.ts +++ b/src/ida/IdaSessionClient.test.ts @@ -10,8 +10,11 @@ import { } from "node:fs/promises"; import { basename, dirname, join, sep } from "node:path"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { + phaseArrival, + phaseGate, +} from "../../tests/support/lifecycleHarness.js"; import { z } from "zod"; -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; import { createIdaTarget, RecordingIdaMcp, @@ -899,18 +902,9 @@ describe("attached IDA function failure handling", () => { it("drains in-flight read-only work on cancellation before closing its proxy", async () => { const { producer, client } = await fixture(); await client.execute("health", {}); - let release: (() => void) | undefined; - let notify: (() => void) | undefined; - const started = new Promise((resolve) => { - notify = resolve; - }); + const readOnlyCall = phaseGate(); producer.beforeCall = async (name) => { - if (name === "decompile_function") { - notify?.(); - await new Promise((resolve) => { - release = resolve; - }); - } + if (name === "decompile_function") await readOnlyCall.hold(); }; const controller = new AbortController(); const call = client.execute( @@ -919,11 +913,11 @@ describe("attached IDA function failure handling", () => { { signal: controller.signal }, ); try { - await awaitAcknowledgement(started, call, "IDA read-only call"); + await readOnlyCall.reached(call, "IDA read-only call"); controller.abort(); const close = client.close(); expect(producer.closes).toBe(0); - release?.(); + readOnlyCall.release(); const result = await call; expect(result.ok).toBe(false); if (!result.ok) expect(result.error._tag).toBe("AnalysisCancelledError"); @@ -931,7 +925,7 @@ describe("attached IDA function failure handling", () => { expect(producer.closes).toBe(1); } finally { controller.abort(); - release?.(); + readOnlyCall.release(); try { await call; } finally { @@ -2303,10 +2297,7 @@ it("keeps the session cleanup owner until an ignored-abort HTTP acquisition and const { root, target } = await createIdaTarget(); roots.push(root); let deliver!: (response: Response) => void; - let entered!: () => void; - const started = new Promise((resolve) => { - entered = resolve; - }); + const httpAcquisition = phaseArrival(); const response = new Promise((resolve) => { deliver = resolve; }); @@ -2318,7 +2309,7 @@ it("keeps the session cleanup owner until an ignored-abort HTTP acquisition and vi.stubGlobal( "fetch", vi.fn(() => { - entered(); + httpAcquisition.arrive(); return response; }), ); @@ -2336,7 +2327,7 @@ it("keeps the session cleanup owner until an ignored-abort HTTP acquisition and ); const executing = client.execute("health", {}); try { - await awaitAcknowledgement(started, executing, "IDA HTTP acquisition"); + await httpAcquisition.reached(executing, "IDA HTTP acquisition"); const result = await executing; expect(result).toMatchObject({ ok: false, diff --git a/src/inspector/V8InspectorAdmission.test.ts b/src/inspector/V8InspectorAdmission.test.ts index ab23dcb960..76e4db8ca1 100644 --- a/src/inspector/V8InspectorAdmission.test.ts +++ b/src/inspector/V8InspectorAdmission.test.ts @@ -64,7 +64,7 @@ it("closes one inspector file scope without waiting for another", async () => { try { await held.reached(closingFirst, "first file cleanup"); await awaitAcknowledgement( - closingSecond.then(() => undefined), + closingSecond, closingFirst, "second file cleanup", ); diff --git a/src/jeb/JebProvider.test.ts b/src/jeb/JebProvider.test.ts index d5e6e9498a..bfa1160a88 100644 --- a/src/jeb/JebProvider.test.ts +++ b/src/jeb/JebProvider.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it, vi } from "vitest"; -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival } from "../../tests/support/lifecycleHarness.js"; import { createJebAnalysisProvider } from "../composition/jeb.js"; import { runWithAnalysisOperationSnapshot } from "../domain/analysisOperationSnapshot.js"; @@ -537,10 +537,7 @@ it.each(["list_jeb_units", "decompile_jeb_item"] as const)( it("forwards in-flight cancellation to the MCP call", async () => { const controller = new AbortController(); - let entered!: () => void; - const started = new Promise((resolve) => { - entered = resolve; - }); + const jebCall = phaseArrival(); const provider = providerWith({ sessionGeneration: 1, async connect() { @@ -551,7 +548,7 @@ it("forwards in-flight cancellation to the MCP call", async () => { }, async close() {}, async call(_name, _args, signal) { - entered(); + jebCall.arrive(); if (signal!.aborted) throw new AnalysisCancelledError(_name, { cause: signal!.reason }); await new Promise((_resolve, reject) => @@ -572,7 +569,7 @@ it("forwards in-flight cancellation to the MCP call", async () => { { signal: controller.signal }, ); try { - await awaitAcknowledgement(started, pending, "JEB MCP call"); + await jebCall.reached(pending, "JEB MCP call"); controller.abort(); const result = await pending; expect(result.ok).toBe(false); diff --git a/src/kuna/KunaCopy.test.ts b/src/kuna/KunaCopy.test.ts index 0681024b38..4cde06d3bc 100644 --- a/src/kuna/KunaCopy.test.ts +++ b/src/kuna/KunaCopy.test.ts @@ -16,19 +16,14 @@ import { ArtifactResourceScope } from "../resources/ArtifactResourceScope.js"; import { ArtifactReaderFailure } from "../resources/ArtifactReader.js"; import { copyAndHash, kunaCopyFailureFacts } from "./KunaCommand.js"; import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; +import { + phaseArrival, + phaseGate, +} from "../../tests/support/lifecycleHarness.js"; import { withKunaProjectDeadline } from "../../tests/boundary/providers/kuna/kunaProjectRequest.js"; vi.mock("node:fs/promises", { spy: true }); -const copyGate = () => { - let resolve!: () => void; - const promise = new Promise((acknowledge) => { - resolve = acknowledge; - }); - return { promise, resolve }; -}; - it.each([null, { caller: "active input copy" }])( "attributes cancellation after an actual copied chunk to its file owner (%j)", async (reason) => { @@ -38,23 +33,20 @@ it.each([null, { caller: "active input copy" }])( const resources = new ArtifactResourceScope(); onTestFinished(() => resources.close()); const controller = new AbortController(); - let acknowledge!: () => void; - const entered = new Promise((resolve) => { - acknowledge = resolve; - }); + const prefix = phaseArrival(); const copying = copyAndHash(source, join(root, "destination"), { signal: controller.signal, resources, keep: { probeBytes: 32, length: () => { - acknowledge(); + prefix.arrive(); return 32; }, }, }); const result = copying.catch((cause: unknown) => cause); - await awaitAcknowledgement(entered, result, "actual input prefix"); + await prefix.reached(result, "actual input prefix"); controller.abort(reason); const failure = await result; expect(failure).toBeInstanceOf(ArtifactReaderFailure); @@ -101,8 +93,7 @@ it.each(["read", "write"] as const)( await writeFile(source, Buffer.alloc(100, 0x61)); const resources = new ArtifactResourceScope(); const controller = new AbortController(); - const entered = copyGate(); - const release = copyGate(); + const held = phaseGate(); const handles: FileHandle[] = []; const native = await vi.importActual( @@ -117,8 +108,7 @@ it.each(["read", "write"] as const)( const original = file[stage]; vi.spyOn(file, stage).mockImplementationOnce( async (...ioArgs: unknown[]) => { - entered.resolve(); - await release.promise; + await held.hold(); return Reflect.apply(original, file, ioArgs); }, ); @@ -126,7 +116,7 @@ it.each(["read", "write"] as const)( return file; }); onTestFinished(async () => { - release.resolve(); + held.release(); vi.restoreAllMocks(); await resources.close(); for (const handle of handles) await handle.close(); @@ -140,13 +130,13 @@ it.each(["read", "write"] as const)( .finally(() => { settled = true; }); - await awaitAcknowledgement(entered.promise, result, `native ${stage}`); + await held.reached(result, `native ${stage}`); const reason = { stage }; controller.abort(reason); await new Promise((resolve) => setImmediate(resolve)); expect(settled).toBe(false); expect(handles.every(({ fd }) => fd >= 0)).toBe(true); - release.resolve(); + held.release(); const failure = await result; expect(failure).toBeInstanceOf(ArtifactReaderFailure); if (!(failure instanceof ArtifactReaderFailure)) @@ -350,8 +340,7 @@ it.each([false, true])( await writeFile(source, input); const resources = new ArtifactResourceScope(); const controller = new AbortController(); - const entered = copyGate(); - const release = copyGate(); + const held = phaseGate(); const original = OwnedFileHandle.prototype.close; let first = true; let rejectClose = refuse; @@ -359,15 +348,14 @@ it.each([false, true])( async function (this: OwnedFileHandle) { if (first) { first = false; - entered.resolve(); - await release.promise; + await held.hold(); } if (rejectClose) throw new Error("final descriptor close refused"); await original.call(this); }, ); onTestFinished(async () => { - release.resolve(); + held.release(); rejectClose = false; await resources.close(); vi.restoreAllMocks(); @@ -377,15 +365,11 @@ it.each([false, true])( resources, keep: { probeBytes: 1, length: () => 8 }, }).catch((cause: unknown) => cause); - await awaitAcknowledgement( - entered.promise, - result, - "final copy descriptor close", - ); + await held.reached(result, "final copy descriptor close"); expect((await readFile(destination)).equals(input)).toBe(true); const reason = { phase: "final copy close" }; controller.abort(reason); - release.resolve(); + held.release(); const failure = await result; expect(failure).toBeInstanceOf(ArtifactReaderFailure); const { completion } = kunaCopyFailureFacts(failure); diff --git a/src/resources/ArtifactResourceScope.test.ts b/src/resources/ArtifactResourceScope.test.ts index 906cf2e2ce..67b1d65191 100644 --- a/src/resources/ArtifactResourceScope.test.ts +++ b/src/resources/ArtifactResourceScope.test.ts @@ -1,7 +1,7 @@ import { open, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../tests/support/lifecycleHarness.js"; import { withArtifactFileHandle, bindArtifactFileCleanup, @@ -21,24 +21,14 @@ import { } from "./ArtifactReader.js"; import { translateArtifactFailure } from "../artifacts/ArtifactOperationFailure.js"; -const deferred = () => { - let resolve: (value: T) => void = () => {}; - const promise = new Promise((resolvePromise) => { - resolve = resolvePromise; - }); - return { promise, resolve }; -}; - it("waits for admitted operations and shares concurrent close", async () => { const scope = new ArtifactResourceScope(); - const started = deferred(); - const finish = deferred(); + const admitted = phaseGate(); const operation = scope.run(async () => { - started.resolve(); - await finish.promise; + await admitted.hold(); }); try { - await awaitAcknowledgement(started.promise, operation, "scope admission"); + await admitted.reached(operation, "scope admission"); const close = scope.close(); expect(scope.close()).toBe(close); await expect(scope.run(async () => undefined)).rejects.toMatchObject({ @@ -52,12 +42,12 @@ it("waits for admitted operations and shares concurrent close", async () => { await Promise.resolve(); expect(closed).toBe(false); - finish.resolve(); + admitted.release(); await operation; await close; expect(closed).toBe(true); } finally { - finish.resolve(); + admitted.release(); try { await operation; } finally { @@ -728,13 +718,11 @@ it("tracks diagnostic work outside admission and joins it before a cleanup retry }, }, }); - const started = deferred(); - const finish = deferred(); + const tracked = phaseGate(); let lateReleases = 0; // A pending owner neither delays nor fails tracked work. const sample = scope.track(async () => { - started.resolve(); - await finish.promise; + await tracked.hold(); scope.retain({ kind: "lease", resource: "sampled", @@ -747,7 +735,7 @@ it("tracks diagnostic work outside admission and joins it before a cleanup retry return "sample"; }); try { - await awaitAcknowledgement(started.promise, sample, "tracked work"); + await tracked.reached(sample, "tracked work"); earlierReleased = true; let retried = false; const retry = scope.retryCleanup().then(() => { @@ -755,7 +743,7 @@ it("tracks diagnostic work outside admission and joins it before a cleanup retry }); await Promise.resolve(); expect(retried).toBe(false); - finish.resolve(); + tracked.release(); await expect(sample).resolves.toBe("sample"); await retry; // The drain joined the tracked work, so the owner it retained was retried. @@ -763,39 +751,35 @@ it("tracks diagnostic work outside admission and joins it before a cleanup retry expect(scope.cleanupResources).toEqual([]); } finally { earlierReleased = true; - finish.resolve(); + tracked.release(); await scope.close(); } }); it("joins diagnostic work admitted while a cleanup retry releases an earlier owner", async () => { const scope = new ArtifactResourceScope(); - const releasing = deferred(); - const allowRelease = deferred(); + const earlierRelease = phaseGate(); scope.retain({ kind: "lease", resource: "earlier", lease: { release: async () => { - releasing.resolve(); - await allowRelease.promise; + await earlierRelease.hold(); }, }, }); let lateReleases = 0; - const started = deferred(); - const finish = deferred(); + const tracked = phaseGate(); let retried = false; const retry = scope.retryCleanup().then(() => { retried = true; }); let sample: Promise | undefined; try { - await awaitAcknowledgement(releasing.promise, retry, "earlier release"); + await earlierRelease.reached(retry, "earlier release"); // Admitted after the drain already found no active work. sample = scope.track(async () => { - started.resolve(); - await finish.promise; + await tracked.hold(); scope.retain({ kind: "lease", resource: "sampled", @@ -807,18 +791,18 @@ it("joins diagnostic work admitted while a cleanup retry releases an earlier own }); return "sample"; }); - await awaitAcknowledgement(started.promise, sample, "tracked work"); - allowRelease.resolve(); + await tracked.reached(sample, "tracked work"); + earlierRelease.release(); await new Promise((resolve) => setImmediate(resolve)); expect(retried).toBe(false); - finish.resolve(); + tracked.release(); await expect(sample).resolves.toBe("sample"); await retry; expect(lateReleases).toBe(1); expect(scope.hasPending).toBe(false); } finally { - allowRelease.resolve(); - finish.resolve(); + earlierRelease.release(); + tracked.release(); await Promise.allSettled(sample === undefined ? [retry] : [retry, sample]); await scope.close(); } diff --git a/src/server/DeferredEvidenceMcpServer.test.ts b/src/server/DeferredEvidenceMcpServer.test.ts index eb0869c30e..268b36c7a5 100644 --- a/src/server/DeferredEvidenceMcpServer.test.ts +++ b/src/server/DeferredEvidenceMcpServer.test.ts @@ -1,4 +1,3 @@ -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; import { AnalysisSettings } from "../application/AnalysisSettings.js"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import type { Tool, ServerContext } from "@modelcontextprotocol/server"; @@ -8,14 +7,12 @@ import type { RecordedMcpCatalog } from "../recordedMcpCatalog.js"; import { DeferredEvidenceMcpServer } from "./DeferredEvidenceMcpServer.js"; import { ToolResultDelivery } from "./ToolResultDelivery.js"; import { promptArgumentsSchema } from "./promptArguments.js"; +import { + phaseArrival, + phaseGate, + type PhaseGate, +} from "../../tests/support/lifecycleHarness.js"; -const barrier = () => { - let release!: () => void; - const promise = new Promise((resolve) => { - release = resolve; - }); - return { promise, release }; -}; const input = z.strictObject({ n: z.number().int().nonnegative().default(3) }); const output = z.strictObject({ n: z.number().int() }); const parameters = { @@ -71,7 +68,8 @@ afterEach(async () => { const fixture = async ( options: { - readonly hold?: ReturnType; + /** Holds deferred runtime loading after its cleanup is owned. */ + readonly startup?: PhaseGate; readonly analysisSettings?: AnalysisSettings; readonly execute?: () => Promise; readonly failClose?: () => boolean; @@ -85,7 +83,6 @@ const fixture = async ( readonly mode?: "legacy" | "auto"; } = {}, ) => { - const started = barrier(); const calls = vi.fn<(n: number, context: ServerContext) => void>(); const closed = vi.fn(); let loads = 0; @@ -111,8 +108,7 @@ const fixture = async ( if (options.failClose?.()) throw new Error("cleanup denied"); await target.closePartialRuntime(); }); - started.release(); - await options.hold?.promise; + await options.startup?.hold(); if (options.failLoad) throw new Error("PRIVATE startup cause"); target.analysisSettings = options.analysisSettings; target.materialize(() => { @@ -177,7 +173,6 @@ const fixture = async ( server, client, serverTransport, - started, calls, closed, loads: () => loads, @@ -272,8 +267,8 @@ it("uses recorded Evidence-reference guidance without loading the deferred runti }); it("discovers without initialization, then shares one canonical runtime and preserves request metadata", async () => { - const hold = barrier(); - const f = await fixture({ hold }); + const startup = phaseGate(); + const f = await fixture({ startup }); const before = await f.client.listTools(); // Listings omit the recorded output schemas (the default `off` profile). expect(before.tools).toEqual( @@ -292,10 +287,10 @@ it("discovers without initialization, then shares one canonical runtime and pres }); const pending: Promise[] = [a]; try { - await awaitAcknowledgement(f.started.promise, a, "deferred initialization"); + await startup.reached(a, "deferred initialization"); const b = f.client.callTool({ name: "fixture", arguments: { n: 7 } }); pending.push(b); - hold.release(); + startup.release(); expect((await a).structuredContent).toEqual({ n: 3 }); expect((await b).structuredContent).toEqual({ n: 7 }); expect(f.loads()).toBe(1); @@ -309,7 +304,7 @@ it("discovers without initialization, then shares one canonical runtime and pres expect(invalid.isError).toBe(true); expect(f.calls).toHaveBeenCalledTimes(2); } finally { - hold.release(); + startup.release(); await Promise.allSettled(pending); } }); @@ -389,14 +384,14 @@ it("retrieves a prompt as the first operation", async () => { }); it("does not execute a tool cancelled while canonical loading is pending", async () => { - const hold = barrier(); - const f = await fixture({ hold }); - const cancelled = barrier(); + const startup = phaseGate(); + const f = await fixture({ startup }); + const cancelled = phaseArrival(); const previous = f.serverTransport.onmessage; f.serverTransport.onmessage = (message, extra) => { previous?.(message, extra); if ("method" in message && message.method === "notifications/cancelled") - cancelled.release(); + cancelled.arrive(); }; const controller = new AbortController(); const pending = f.client.callTool( @@ -405,18 +400,13 @@ it("does not execute a tool cancelled while canonical loading is pending", async ); const rejected = expect(pending).rejects.toBeDefined(); try { - await awaitAcknowledgement( - f.started.promise, - pending, - "cancelled caller initialization", - ); + await startup.reached(pending, "cancelled caller initialization"); controller.abort(); - await awaitAcknowledgement( - cancelled.promise, + await cancelled.reached( f.server.ensureRuntime(), "cancellation notification", ); - hold.release(); + startup.release(); await rejected; await f.server.ensureRuntime(); expect(f.calls).not.toHaveBeenCalled(); @@ -425,7 +415,7 @@ it("does not execute a tool cancelled while canonical loading is pending", async ).not.toBe(true); } finally { controller.abort(); - hold.release(); + startup.release(); await Promise.allSettled([pending, rejected, f.server.ensureRuntime()]); if (previous === undefined) delete f.serverTransport.onmessage; else f.serverTransport.onmessage = previous; @@ -433,10 +423,10 @@ it("does not execute a tool cancelled while canonical loading is pending", async }); it("keeps an independent caller alive when its peer cancels during shared loading", async () => { - const hold = barrier(); - const f = await fixture({ hold }); - const secondRequest = barrier(); - const cancelled = barrier(); + const startup = phaseGate(); + const f = await fixture({ startup }); + const secondRequest = phaseArrival(); + const cancelled = phaseArrival(); let toolCalls = 0; const previous = f.serverTransport.onmessage; f.serverTransport.onmessage = (message, extra) => { @@ -446,9 +436,9 @@ it("keeps an independent caller alive when its peer cancels during shared loadin message.method === "tools/call" && ++toolCalls === 2 ) - secondRequest.release(); + secondRequest.arrive(); if ("method" in message && message.method === "notifications/cancelled") - cancelled.release(); + cancelled.arrive(); }; const controller = new AbortController(); const a = f.client @@ -456,28 +446,23 @@ it("keeps an independent caller alive when its peer cancels during shared loadin .catch(() => undefined); const pending: Promise[] = [a]; try { - await awaitAcknowledgement(f.started.promise, a, "shared initialization"); + await startup.reached(a, "shared initialization"); const b = f.client.callTool({ name: "fixture", arguments: { n: 8 } }); pending.push(b); - await awaitAcknowledgement( - secondRequest.promise, - b, - "independent caller admission", - ); + await secondRequest.reached(b, "independent caller admission"); controller.abort(); - await awaitAcknowledgement( - cancelled.promise, + await cancelled.reached( f.server.ensureRuntime(), "peer cancellation notification", ); - hold.release(); + startup.release(); await a; expect((await b).structuredContent).toEqual({ n: 8 }); expect(f.calls).toHaveBeenCalledTimes(1); expect(f.loads()).toBe(1); } finally { controller.abort(); - hold.release(); + startup.release(); await Promise.allSettled([...pending, f.server.ensureRuntime()]); if (previous === undefined) delete f.serverTransport.onmessage; else f.serverTransport.onmessage = previous; @@ -485,27 +470,23 @@ it("keeps an independent caller alive when its peer cancels during shared loadin }); it("joins late initialization during close and prevents target execution", async () => { - const hold = barrier(); - const f = await fixture({ hold }); + const startup = phaseGate(); + const f = await fixture({ startup }); const pending = f.client .callTool({ name: "fixture", arguments: {} }) .catch(() => undefined); let closing: Promise | undefined; try { - await awaitAcknowledgement( - f.started.promise, - pending, - "initialization before close", - ); + await startup.reached(pending, "initialization before close"); closing = f.server.close(); - hold.release(); + startup.release(); await closing; await pending; expect(f.calls).not.toHaveBeenCalled(); expect(f.closed).toHaveBeenCalledTimes(1); await expect(f.server.ensureRuntime()).rejects.toThrow("closed"); } finally { - hold.release(); + startup.release(); await Promise.allSettled([pending, closing]); } }); @@ -553,24 +534,18 @@ it("never executes a partially registered handler after initialization fails", a it("keeps one accepted settings snapshot through a deferred handler while the next call sees updates", async () => { const settings = new AnalysisSettings({}); - const entered = barrier(); - const held = barrier(); + const handler = phaseGate(); const seen: Array = []; const f = await fixture({ analysisSettings: settings, execute: async () => { - entered.release(); - await held.promise; + await handler.hold(); seen.push(settings.read().overrides["asar.max_header_bytes"]); }, }); const pending = f.client.callTool({ name: "fixture", arguments: {} }); try { - await awaitAcknowledgement( - entered.promise, - pending, - "settings snapshot handler entry", - ); + await handler.reached(pending, "settings snapshot handler entry"); expect( settings.update({ changes: [ @@ -579,7 +554,7 @@ it("keeps one accepted settings snapshot through a deferred handler while the ne }).ok, ).toBe(true); } finally { - held.release(); + handler.release(); await Promise.allSettled([pending]); } expect((await pending).isError).not.toBe(true); diff --git a/src/server/EvidenceMcpServer.test.ts b/src/server/EvidenceMcpServer.test.ts index 89f64d68e8..b7462c4789 100644 --- a/src/server/EvidenceMcpServer.test.ts +++ b/src/server/EvidenceMcpServer.test.ts @@ -18,7 +18,7 @@ import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/officialToolContracts.js"; import { EvidenceMcpServer } from "./EvidenceMcpServer.js"; import { forgetPendingMcpRequest } from "./EvidenceMcpServerCore.js"; import { createDeferred } from "../../tests/fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../tests/support/lifecycleHarness.js"; import { createToolResultDelivery } from "./toolResult.js"; const firstText = (result: { @@ -130,9 +130,8 @@ it("passes the owned cancellation signal to a tool without an input schema", asy (evidence) => records.recordEvidence(evidence), createToolResultDelivery(4096), ); - const entered = createDeferred(); + const handler = phaseGate(); const observed = createDeferred(); - const release = createDeferred(); const finished = createDeferred(); let started = false; server.registerTool("held", {}, async (context) => { @@ -141,9 +140,8 @@ it("passes the owned cancellation signal to a tool without an input schema", asy once: true, }); started = true; - entered.resolve(); try { - await release.promise; + await handler.hold(); return { content: [{ type: "text", text: "finished" }] }; } finally { finished.resolve(); @@ -162,11 +160,7 @@ it("passes the owned cancellation signal to a tool without an input schema", asy const pending = client .callTool({ name: "held" }, { signal: controller.signal }) .catch(() => undefined); - await awaitAcknowledgement( - entered.promise, - pending, - "held tool handler entry", - ); + await handler.reached(pending, "held tool handler entry"); controller.abort("stop no-input tool"); await pending; expect(await observed.promise).toMatchObject({ @@ -174,7 +168,7 @@ it("passes the owned cancellation signal to a tool without an input schema", asy clientReason: "stop no-input tool", }); } finally { - release.resolve(); + handler.release(); if (started) await finished.promise; await Promise.all([client.close(), serving.close()]); } @@ -188,9 +182,8 @@ it("aborts a running tool with a caller abort that keeps the client's reason", a (evidence) => records.recordEvidence(evidence), createToolResultDelivery(4096), ); - const entered = createDeferred(); + const handler = phaseGate(); const observed = createDeferred(); - const release = createDeferred(); const finished = createDeferred(); let started = false; server.registerTool( @@ -202,9 +195,8 @@ it("aborts a running tool with a caller abort that keeps the client's reason", a once: true, }); started = true; - entered.resolve(undefined); try { - await release.promise; + await handler.hold(); return { content: [{ type: "text", text: "finished" }] }; } finally { finished.resolve(); @@ -226,11 +218,7 @@ it("aborts a running tool with a caller abort that keeps the client's reason", a { signal: controller.signal }, ); const rejected = expect(pending).rejects.toBeDefined(); - await awaitAcknowledgement( - entered.promise, - pending, - "held tool handler entry", - ); + await handler.reached(pending, "held tool handler entry"); controller.abort("user stopped"); await rejected; @@ -242,7 +230,7 @@ it("aborts a running tool with a caller abort that keeps the client's reason", a name: "AbortError", }); } finally { - release.resolve(); + handler.release(); if (started) await finished.promise; await Promise.all([client.close(), serving.close()]); } @@ -256,9 +244,8 @@ it("reports owner shutdown to the handler when transport close invokes onclose", (evidence) => records.recordEvidence(evidence), createToolResultDelivery(4096), ); - const entered = createDeferred(); + const handler = phaseGate(); const observed = createDeferred(); - const release = createDeferred(); const finished = createDeferred(); let started = false; server.registerTool( @@ -271,9 +258,8 @@ it("reports owner shutdown to the handler when transport close invokes onclose", { once: true }, ); started = true; - entered.resolve(); try { - await release.promise; + await handler.hold(); return { content: [{ type: "text", text: "finished" }] }; } finally { finished.resolve(); @@ -292,16 +278,12 @@ it("reports owner shutdown to the handler when transport close invokes onclose", const pending = client .callTool({ name: "held", arguments: {} }) .catch(() => undefined); - await awaitAcknowledgement( - entered.promise, - pending, - "held tool handler entry", - ); + await handler.reached(pending, "held tool handler entry"); await server.close(); expect(await observed.promise).toBe(OwnerCancellation.ownerClosed); await pending; } finally { - release.resolve(); + handler.release(); if (started) await finished.promise; await Promise.all([client.close(), serving.close()]); } diff --git a/src/server/environment/serveEnvironmentState.test.ts b/src/server/environment/serveEnvironmentState.test.ts index bd40764fbf..927ea89037 100644 --- a/src/server/environment/serveEnvironmentState.test.ts +++ b/src/server/environment/serveEnvironmentState.test.ts @@ -8,6 +8,7 @@ import { join } from "node:path"; import { pathToFileURL } from "node:url"; import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest"; import { awaitAcknowledgement } from "../../../tests/fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival } from "../../../tests/support/lifecycleHarness.js"; const closeFailureControl = vi.hoisted(() => ({ failure: null as Error | null, @@ -155,16 +156,13 @@ const addByUri = ( /** A fetcher that reports each call and the signal it was given, then answers only when `answer` settles. */ const heldFetcher = (answer: () => Promise) => { const signals: AbortSignal[] = []; - let started: () => void = () => undefined; - const fetching = new Promise((resolve) => { - started = resolve; - }); + const fetching = phaseArrival(); const fetchState = (_: URL, signal: AbortSignal) => { signals.push(signal); - started(); + fetching.arrive(); return answer(); }; - return { signals, fetching, fetchState }; + return { signals, fetching: fetching.reached, fetchState }; }; describe("state data plane", () => { @@ -551,7 +549,7 @@ describe("state data plane timing and order", () => { addByUri(1), { jsonrpc: "2.0", id: 2, method: "data/get" }, ]); - await held.fetching; + await held.fetching(batch, "state fetch admission"); const reset = plane.call("data/reset"); release(); const replies = (await batch).json; @@ -602,7 +600,7 @@ describe("state data plane cancellation", () => { addByUri(1), { jsonrpc: "2.0", id: 2, method: "data/reset" }, ]); - await held.fetching; + await held.fetching(batch, "state fetch admission"); stopping.abort(); expect((await batch).json).toEqual([ { @@ -643,7 +641,7 @@ describe("state data plane cancellation", () => { }); const leaving = new AbortController(); const add = plane.post(addByUri(1), leaving.signal); - await held.fetching; + await held.fetching(add, "state fetch admission"); leaving.abort(); expect((await add).json).toMatchObject({ error: { code: -32000, data: { reason: "cancelled" } }, @@ -1141,11 +1139,7 @@ describe("state response cleanup", () => { signal: AbortSignal.timeout(10_000), }).catch(() => undefined); try { - await awaitAcknowledgement( - held.fetching, - answered, - "state fetch admission", - ); + await held.fetching(answered, "state fetch admission"); await environment.close(); giveResponse( new Response( @@ -1189,7 +1183,7 @@ describe("serveEnvironment state file cleanup", () => { (response) => response.status, () => "closed", ); - await held.fetching; + await held.fetching(answered, "state fetch admission"); // The download's own limit is 30 s; stopping must not wait for it. const started = performance.now(); await environment.close(); diff --git a/src/server/http/serveStreamableHttp.test.ts b/src/server/http/serveStreamableHttp.test.ts index ea7a308855..d7f7b9e42d 100644 --- a/src/server/http/serveStreamableHttp.test.ts +++ b/src/server/http/serveStreamableHttp.test.ts @@ -13,7 +13,10 @@ import { expectForeignHostRefused, rawHttpRequest, } from "../../../tests/support/http/rawRequest.js"; -import { awaitAcknowledgement } from "../../../tests/fixtures/lifecycleAcknowledgement.js"; +import { + phaseArrival, + phaseGate, +} from "../../../tests/support/lifecycleHarness.js"; import { closeVerifierResources } from "../../../scripts/lib/verifier-cleanup.mjs"; import { hostHeaderAllowlist, @@ -37,14 +40,6 @@ import { ok } from "../../domain/result.js"; const servers: StreamableHttpServer[] = []; -const createGate = () => { - let release!: () => void; - const promise = new Promise((resolve) => { - release = resolve; - }); - return { promise, release }; -}; - afterEach(async () => { await Promise.all(servers.splice(0).map((server) => server.close())); }); @@ -1075,18 +1070,8 @@ it("does not let a zero-quality, quoted or SDK-refused Accept qualify a session it.each(["replacement", "DELETE"])( "waits for a cancelled tool's finally block before reusing the instance after %s", async (ending) => { - let release!: () => void; - let entered!: () => void; - let cancelled!: () => void; - const gate = new Promise((resolve) => { - release = resolve; - }); - const started = new Promise((resolve) => { - entered = resolve; - }); - const aborted = new Promise((resolve) => { - cancelled = resolve; - }); + const toolRun = phaseGate(); + const toolAbort = phaseArrival(); let state = "initial"; let connections = 0; const { served } = await start({ @@ -1101,12 +1086,13 @@ it.each(["replacement", "DELETE"])( "slow", { inputSchema: z.object({}) }, async (_args, context) => { - context.mcpReq.signal.addEventListener("abort", cancelled, { - once: true, - }); - entered(); + context.mcpReq.signal.addEventListener( + "abort", + () => toolAbort.arrive(), + { once: true }, + ); try { - await gate; + await toolRun.hold(); return { content: [] }; } finally { state = "old-finally"; @@ -1126,23 +1112,23 @@ it.each(["replacement", "DELETE"])( .callTool({ name: "slow", arguments: {} }) .catch(() => undefined); try { - await awaitAcknowledgement(started, request, "tool start"); + await toolRun.reached(request, "tool start"); deletion = ending === "DELETE" ? first.transport.terminateSession() : undefined; if (deletion !== undefined) - await awaitAcknowledgement(aborted, deletion, "tool cancellation"); + await toolAbort.reached(deletion, "tool cancellation"); let connected = false; replacement = connect(served.url).then((value) => { connected = true; next = value; return value; }); - await awaitAcknowledgement(aborted, replacement, "tool cancellation"); + await toolAbort.reached(replacement, "tool cancellation"); await new Promise((resolve) => setImmediate(resolve)); expect(connections).toBe(1); expect(connected).toBe(false); expect(state).toBe("initial"); - release(); + toolRun.release(); await deletion; const connectedNext = await replacement; expect(state).toBe("old-finally"); @@ -1150,7 +1136,7 @@ it.each(["replacement", "DELETE"])( { type: "text", text: "new session" }, ]); } finally { - release(); + toolRun.release(); await closeVerifierResources([ () => first.client.close(), async () => { @@ -1170,16 +1156,14 @@ it.each(["ready", "failure"] as const)( const reserved = await start(); const url = new URL(reserved.served.url); await reserved.served.close(); - const factoryStarted = createGate(); - const factoryGate = createGate(); + const factoryStart = phaseGate(); const failure = new Error("provider unavailable"); const handled = vi.fn(() => new Response("ready")); const starting = serveStreamableHttp({ host: "127.0.0.1", port: Number(url.port), createMcpServer: async () => { - factoryStarted.release(); - await factoryGate.promise; + await factoryStart.hold(); if (outcome === "failure") throw failure; return createEchoServer(() => undefined); }, @@ -1187,14 +1171,10 @@ it.each(["ready", "failure"] as const)( }); const settled = starting.catch(() => undefined); try { - await awaitAcknowledgement( - factoryStarted.promise, - starting, - "factory start", - ); + await factoryStart.reached(starting, "factory start"); expect((await fetch(new URL("/pending", url))).status).toBe(503); expect(handled).not.toHaveBeenCalled(); - factoryGate.release(); + factoryStart.release(); if (outcome === "failure") { await expect(starting).rejects.toBe(failure); await expect(rawHttpRequest(url)).rejects.toMatchObject({ @@ -1206,7 +1186,7 @@ it.each(["ready", "failure"] as const)( expect(handled).toHaveBeenCalledTimes(1); } } finally { - factoryGate.release(); + factoryStart.release(); await (await settled)?.close(); } }, @@ -1215,16 +1195,15 @@ it.each(["ready", "failure"] as const)( it.each(["open stream", "late response"])( "joins response-body cancellation before provider hooks for %s", async (timing) => { - const entered = createGate(); - const cancelling = createGate(); - const cleanup = createGate(); + const routeStart = phaseArrival(); + const bodyCancel = phaseGate(); const { served, shutdownHooks } = await start({ routes: [ { method: "GET", path: "/stream", handle: async (request) => { - entered.release(); + routeStart.arrive(); if (timing === "late response") await new Promise((resolve) => { request.signal.addEventListener("abort", () => resolve(), { @@ -1239,8 +1218,7 @@ it.each(["open stream", "late response"])( ); }, async cancel() { - cancelling.release(); - await cleanup.promise; + await bodyCancel.hold(); }, }), ); @@ -1253,25 +1231,21 @@ it.each(["open stream", "late response"])( ); let closing: Promise | undefined; try { - await awaitAcknowledgement(entered.promise, response, "route start"); + await routeStart.reached(response, "route start"); if (timing === "open stream") await response; let closed = false; closing = served.prepareShutdown().then(() => { closed = true; }); - await awaitAcknowledgement( - cancelling.promise, - closing, - "body cancellation", - ); + await bodyCancel.reached(closing, "body cancellation"); await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); expect(shutdownHooks()).toBe(0); - cleanup.release(); + bodyCancel.release(); await closing; expect(shutdownHooks()).toBe(1); } finally { - cleanup.release(); + bodyCancel.release(); await closeVerifierResources([ async () => { await (closing ?? served.close()); @@ -1287,7 +1261,7 @@ it.each(["open stream", "late response"])( it.each(["chunk", "headers"])( "joins response cleanup after an output failure in %s", async (failure) => { - const cleanup = createGate(); + const responseCleanup = phaseGate(); let cancelled = 0; const source = new ReadableStream({ start(controller) { @@ -1300,7 +1274,7 @@ it.each(["chunk", "headers"])( }, async cancel() { cancelled += 1; - await cleanup.promise; + await responseCleanup.hold(); }, }); const { served, shutdownHooks } = await start({ @@ -1338,12 +1312,12 @@ it.each(["chunk", "headers"])( await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); expect(shutdownHooks()).toBe(0); - cleanup.release(); + responseCleanup.release(); await closing; expect(shutdownHooks()).toBe(1); expect(cancelled).toBe(1); } finally { - cleanup.release(); + responseCleanup.release(); await source.cancel().catch(() => undefined); await closing; await received; @@ -1435,8 +1409,7 @@ it("retains failed response cleanup and blocks provider teardown and further adm }); it("retains plain-response admission until asynchronous cancellation settles", async () => { - const cancelling = createGate(); - const cleanup = createGate(); + const streamCancel = phaseGate(); const health = vi.fn(() => new Response("ok")); const { served } = await start({ maxConcurrentDispatches: 1, @@ -1452,8 +1425,7 @@ it("retains plain-response admission until asynchronous cancellation settles", a controller.enqueue(new TextEncoder().encode("ready")); }, async cancel() { - cancelling.release(); - await cleanup.promise; + await streamCancel.hold(); }, }), ), @@ -1464,15 +1436,19 @@ it("retains plain-response admission until asynchronous cancellation settles", a try { expect((await fetch(new URL("/health", served.url))).status).toBe(503); await response.body?.cancel(); - await cancelling.promise; + // The client-side cancel has already settled; only the deadline bounds this wait. + await streamCancel.reached( + new Promise(() => {}), + "server stream cancellation", + ); expect((await fetch(new URL("/health", served.url))).status).toBe(503); expect(health).not.toHaveBeenCalled(); - cleanup.release(); + streamCancel.release(); await waitFor(async () => { expect((await fetch(new URL("/health", served.url))).status).toBe(200); }); } finally { - cleanup.release(); + streamCancel.release(); await response.body?.cancel(); } }); @@ -1505,14 +1481,14 @@ it("supports sequential keep-alive requests on the same connection", async () => it.each(["pending handler", "open response"])( "closes a peer pipelining behind a %s without queuing refusals", async (mode) => { - const first = createGate(); - const fallback = createGate(); + const firstRoute = phaseArrival(); + const fallback = phaseGate(); let finalized = 0; let secondCalled = 0; const held = async (request: Request) => { try { await Promise.race([ - fallback.promise, + fallback.hold(), new Promise((resolve) => { request.signal.addEventListener("abort", () => resolve(), { once: true, @@ -1532,7 +1508,7 @@ it.each(["pending handler", "open response"])( method: "GET", path: "/first", handle: (request) => { - first.release(); + firstRoute.arrive(); return mode === "pending handler" ? held(request) : new Response( @@ -1567,8 +1543,11 @@ it.each(["pending handler", "open response"])( await new Promise((resolve) => { socket.once("connect", resolve); }); + const socketClosed = new Promise((resolve) => { + socket.once("close", () => resolve()); + }); socket.write(request("/first")); - await first.promise; + await firstRoute.reached(socketClosed, "first pipelined route"); socket.write(request("/second")); socket.write(request("/health").repeat(32)); await waitFor(() => { @@ -1589,25 +1568,15 @@ it.each(["pending handler", "open response"])( it.each(["prepareShutdown", "close"] as const)( "waits for plain-route finalizers before provider hooks during %s", async (method) => { - let entered!: () => void; - let finalizing!: () => void; - let release!: () => void; - const started = new Promise((resolve) => { - entered = resolve; - }); - const cleanupStarted = new Promise((resolve) => { - finalizing = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const routeStart = phaseArrival(); + const routeFinalizer = phaseGate(); const { served, shutdownHooks } = await start({ routes: [ { method: "GET", path: "/pending", handle: async (request) => { - entered(); + routeStart.arrive(); try { await new Promise((resolve) => { request.signal.addEventListener("abort", () => resolve(), { @@ -1615,8 +1584,7 @@ it.each(["prepareShutdown", "close"] as const)( }); }); } finally { - finalizing(); - await gate; + await routeFinalizer.hold(); } return new Response("done"); }, @@ -1628,20 +1596,20 @@ it.each(["prepareShutdown", "close"] as const)( ); let closing: Promise | undefined; try { - await awaitAcknowledgement(started, response, "route start"); + await routeStart.reached(response, "route start"); let closed = false; closing = served[method]().then(() => { closed = true; }); - await awaitAcknowledgement(cleanupStarted, closing, "route finalizer"); + await routeFinalizer.reached(closing, "route finalizer"); await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); expect(shutdownHooks()).toBe(0); - release(); + routeFinalizer.release(); await closing; expect(shutdownHooks()).toBe(1); } finally { - release(); + routeFinalizer.release(); await closeVerifierResources([ async () => { await (closing ?? served.close()); @@ -1913,19 +1881,11 @@ it.each(["replacement", "DELETE", "shutdown"])( const opened = await slot.handle(initializeRequest()); const sessionId = opened.headers.get("mcp-session-id"); expect(sessionId).toEqual(expect.any(String)); - let release!: () => void; - const gate = new Promise((resolve) => { - release = resolve; - }); - let reading!: () => void; - const readStarted = new Promise((resolve) => { - reading = resolve; - }); + const requestBodyRead = phaseGate(); const body = new ReadableStream( { async pull(controller) { - reading(); - await gate; + await requestBodyRead.hold(); controller.enqueue( new TextEncoder().encode( JSON.stringify({ @@ -1956,7 +1916,7 @@ it.each(["replacement", "DELETE", "shutdown"])( ); try { // With no stream prefetch, this proves the SDK is waiting on the old body. - await awaitAcknowledgement(readStarted, pending, "request body read"); + await requestBodyRead.reached(pending, "request body read"); if (ending === "shutdown") await slot.close(); else { if (ending === "DELETE") { @@ -1972,7 +1932,7 @@ it.each(["replacement", "DELETE", "shutdown"])( expect(next.status).toBe(200); expect(next.headers.get("mcp-session-id")).not.toBe(sessionId); } - release(); + requestBodyRead.release(); const refused = await pending; expect(refused.status).toBe(404); await expect(refused.json()).resolves.toMatchObject({ @@ -1980,7 +1940,7 @@ it.each(["replacement", "DELETE", "shutdown"])( }); expect(called).not.toHaveBeenCalled(); } finally { - release(); + requestBodyRead.release(); await pending; await slot.close(); } @@ -2047,18 +2007,8 @@ it.each(["replacement", "shutdown"])( it.each(["after timeout", "during drain"])( "automatically completes shutdown %s when the retained handler settles", async (shutdownTiming) => { - let release!: () => void; - let entered!: () => void; - let draining!: () => void; - const gate = new Promise((resolve) => { - release = resolve; - }); - const started = new Promise((resolve) => { - entered = resolve; - }); - const drainStarted = new Promise((resolve) => { - draining = resolve; - }); + const toolStart = phaseGate(); + const sessionDrain = phaseArrival(); let shutdowns = 0; const { served } = await start({ sessionDrainTimeoutMs: 0, @@ -2069,12 +2019,11 @@ it.each(["after timeout", "during drain"])( const drain = server.drainRequests.bind(server); vi.spyOn(server, "drainRequests").mockImplementation((timeoutMs) => { const result = drain(timeoutMs); - draining(); + sessionDrain.arrive(); return result; }); server.registerTool("slow", { inputSchema: z.object({}) }, async () => { - entered(); - await gate; + await toolStart.hold(); return { content: [] }; }); return server; @@ -2087,7 +2036,7 @@ it.each(["after timeout", "during drain"])( let replacement: Promise | undefined; let pendingClose: Promise | undefined; try { - await awaitAcknowledgement(started, request, "tool start"); + await toolStart.reached(request, "tool start"); replacement = fetch(served.url, { method: "POST", headers: { @@ -2100,7 +2049,7 @@ it.each(["after timeout", "during drain"])( if (shutdownTiming === "during drain") return undefined; throw cause; }); - await awaitAcknowledgement(drainStarted, replacement, "session drain"); + await sessionDrain.reached(replacement, "session drain"); pendingClose = shutdownTiming === "during drain" ? served.close() : undefined; const refused = await replacement; @@ -2112,11 +2061,11 @@ it.each(["after timeout", "during drain"])( await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); expect(shutdowns).toBe(0); - release(); + toolStart.release(); await closing; expect(shutdowns).toBe(1); } finally { - release(); + toolStart.release(); await closeVerifierResources([ () => first.client.close(), async () => { @@ -2133,18 +2082,8 @@ it.each(["after timeout", "during drain"])( it.each(["replacement", "shutdown", "DELETE"] as const)( "tells a pending Evidence tool who ended its session after %s", async (ending) => { - let release!: () => void; - let entered!: () => void; - let observed!: (reason: unknown) => void; - const gate = new Promise((resolve) => { - release = resolve; - }); - const started = new Promise((resolve) => { - entered = resolve; - }); - const aborted = new Promise((resolve) => { - observed = resolve; - }); + const toolStart = phaseGate(); + const toolAbort = phaseArrival(); const { served } = await start({ createMcpServer: () => { const server = new EvidenceMcpServer( @@ -2159,11 +2098,10 @@ it.each(["replacement", "shutdown", "DELETE"] as const)( async (_args, context) => { context.mcpReq.signal.addEventListener( "abort", - () => observed(context.mcpReq.signal.reason), + () => toolAbort.arrive(context.mcpReq.signal.reason), { once: true }, ); - entered(); - await gate; + await toolStart.hold(); return { content: [] }; }, ); @@ -2176,23 +2114,18 @@ it.each(["replacement", "shutdown", "DELETE"] as const)( .catch(() => undefined); let ended: Promise | undefined; try { - await awaitAcknowledgement(started, request, "tool start"); + await toolStart.reached(request, "tool start"); ended = ending === "DELETE" ? first.transport.terminateSession() : ending === "shutdown" ? served.prepareShutdown() : connect(served.url).then((next) => next.client.close()); - await awaitAcknowledgement( - aborted.then(() => undefined), - ended, - "tool abort", - ); - const reason = await aborted; + const reason = await toolAbort.reached(ended, "tool abort"); if (ending === "DELETE") expect(reason).toBeInstanceOf(CallerAbort); else expect(reason).toBe(OwnerCancellation.ownerClosed); } finally { - release(); + toolStart.release(); await closeVerifierResources([ () => first.client.close(), async () => { diff --git a/tests/boundary/browser/cdpBrowserProvider.browserSocket.test.ts b/tests/boundary/browser/cdpBrowserProvider.browserSocket.test.ts index 182565b9fd..ac59a331bd 100644 --- a/tests/boundary/browser/cdpBrowserProvider.browserSocket.test.ts +++ b/tests/boundary/browser/cdpBrowserProvider.browserSocket.test.ts @@ -1,6 +1,11 @@ import { createServer, type Socket } from "node:net"; import { describe, expect, it, vi } from "vitest"; +import { + phaseArrival, + phaseGate, + type PhaseGate, +} from "../../support/lifecycleHarness.js"; import { CdpBrowserProvider } from "../../../src/browser/CdpBrowserProvider.js"; import { CdpConnection } from "../../../src/browser/CdpConnection.js"; @@ -17,7 +22,6 @@ import { import { observeWebSessionInputSchema } from "../../../src/domain/browserSession.js"; import { captureWebScreenshotInputSchema } from "../../../src/domain/webScreenshot.js"; import { startFakeCdpBrowser } from "../../fixtures/fakeCdpBrowser.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { trackBrowser } from "./cdpBrowserProvider.support.js"; import { waitFor } from "../../support/testWait.js"; @@ -471,10 +475,7 @@ describe("CdpBrowserProvider: shared browser socket lifecycle regressions", () = trackBrowser(browser); const provider = new CdpBrowserProvider(); const closeSpy = vi.spyOn(CdpConnection.prototype, "close"); - let armed!: () => void; - const observationArmed = new Promise((resolve) => { - armed = resolve; - }); + const observationStart = phaseArrival(); const controller = new AbortController(); let observing: ReturnType | undefined; try { @@ -488,13 +489,12 @@ describe("CdpBrowserProvider: shared browser socket lifecycle regressions", () = signal: controller.signal, progress: { report: async (update) => { - if (update.completed === 1) armed(); + if (update.completed === 1) observationStart.arrive(); }, }, }, ); - await awaitAcknowledgement( - observationArmed, + await observationStart.reached( observing, "peer session observation start", ); @@ -542,10 +542,7 @@ describe("CdpBrowserProvider: shared browser socket lifecycle regressions", () = ? Promise.reject(new Error("controlled shared socket close failure")) : originalClose.call(this); }); - let armed!: () => void; - const observationArmed = new Promise((resolve) => { - armed = resolve; - }); + const observationStart = phaseArrival(); const controller = new AbortController(); let observing: ReturnType | undefined; try { @@ -559,13 +556,12 @@ describe("CdpBrowserProvider: shared browser socket lifecycle regressions", () = signal: controller.signal, progress: { report: async (update) => { - if (update.completed === 1) armed(); + if (update.completed === 1) observationStart.arrive(); }, }, }, ); - await awaitAcknowledgement( - observationArmed, + await observationStart.reached( observing, "peer session observation start", ); @@ -703,10 +699,7 @@ it("blocks new admissions while forced shared-socket cleanup fails with an activ ? Promise.reject(new Error("controlled shared socket close failure")) : originalClose.call(this); }); - let armed!: () => void; - const observationArmed = new Promise((resolve) => { - armed = resolve; - }); + const observationStart = phaseArrival(); const controller = new AbortController(); let observing: ReturnType | undefined; try { @@ -720,16 +713,12 @@ it("blocks new admissions while forced shared-socket cleanup fails with an activ signal: controller.signal, progress: { report: async (update) => { - if (update.completed === 1) armed(); + if (update.completed === 1) observationStart.arrive(); }, }, }, ); - await awaitAcknowledgement( - observationArmed, - observing, - "peer session observation start", - ); + await observationStart.reached(observing, "peer session observation start"); expect(browser.openedConnectionCount()).toBe(1); denyClose = true; @@ -794,10 +783,7 @@ it("keeps an admitted shared browser socket alive for concurrent peers when a ca }); trackBrowser(browser); const provider = new CdpBrowserProvider(); - let armed!: () => void; - const observationArmed = new Promise((resolve) => { - armed = resolve; - }); + const observationStart = phaseArrival(); const peerController = new AbortController(); const cancelController = new AbortController(); let observing: ReturnType | undefined; @@ -813,16 +799,12 @@ it("keeps an admitted shared browser socket alive for concurrent peers when a ca signal: peerController.signal, progress: { report: async (update) => { - if (update.completed === 1) armed(); + if (update.completed === 1) observationStart.arrive(); }, }, }, ); - await awaitAcknowledgement( - observationArmed, - observing, - "peer session observation start", - ); + await observationStart.reached(observing, "peer session observation start"); expect(browser.openedConnectionCount()).toBe(1); slowTargetDiscovery = true; @@ -847,22 +829,15 @@ it("keeps an admitted shared browser socket alive for concurrent peers when a ca expect(browser.openedConnectionCount()).toBe(1); expect(browser.activeConnectionCount()).toBe(1); - let enterCancelDiscovery!: () => void; - const cancelDiscoveryEntered = new Promise((resolve) => { - enterCancelDiscovery = resolve; - }); - notifySlowDiscoveryStarted = enterCancelDiscovery; + const sharedDiscovery = phaseArrival(); + notifySlowDiscoveryStarted = () => sharedDiscovery.arrive(); cancelling = provider.listTargets( listBrowserTargetsInputSchema.parse({ cdp_endpoint: browser.browserWebSocketUrl, }), { signal: cancelController.signal }, ); - await awaitAcknowledgement( - cancelDiscoveryEntered, - cancelling, - "shared socket discovery start", - ); + await sharedDiscovery.reached(cancelling, "shared socket discovery start"); cancelController.abort(new Error("caller cancelled discovery")); expect(await cancelling).toMatchObject({ ok: false, @@ -1008,27 +983,9 @@ describe("CdpBrowserProvider: coalesced cold-start browser sockets", () => { }); }); -const createDeferredGate = (): { - readonly promise: Promise; - readonly open: () => void; -} => { - let open = (): void => undefined; - const promise = new Promise((resolve) => { - open = resolve; - }); - return { promise, open }; -}; - -const holdProgressStep = ( - step: number, - entered: () => void, - release: Promise, -) => ({ +const holdProgressStep = (step: number, gate: PhaseGate) => ({ async report(update: { readonly completed: number }) { - if (update.completed === step) { - entered(); - await release; - } + if (update.completed === step) await gate.hold(); }, }); @@ -1037,9 +994,13 @@ it("isolates concurrent target sessions on one shared browser socket when a shor trackBrowser(browser); const provider = new CdpBrowserProvider(); const controller = new AbortController(); - const observationArmed = createDeferredGate(); - const inspectionHeld = createDeferredGate(); - const peersGate = createDeferredGate(); + // Both peers stay held until the shorter screenshot call has detached. + const observationHeld = phaseGate(); + const inspectionHeld = phaseGate(); + const releasePeers = () => { + observationHeld.release(); + inspectionHeld.release(); + }; let observing: ReturnType | undefined; let inspecting: ReturnType | undefined; let capturing: @@ -1054,11 +1015,10 @@ it("isolates concurrent target sessions on one shared browser socket when a shor }), { signal: controller.signal, - progress: holdProgressStep(1, observationArmed.open, peersGate.promise), + progress: holdProgressStep(1, observationHeld), }, ); - await awaitAcknowledgement( - observationArmed.promise, + await observationHeld.reached( observing, "shared browser-socket observation start", ); @@ -1071,11 +1031,10 @@ it("isolates concurrent target sessions on one shared browser socket when a shor }), { signal: controller.signal, - progress: holdProgressStep(2, inspectionHeld.open, peersGate.promise), + progress: holdProgressStep(2, inspectionHeld), }, ); - await awaitAcknowledgement( - inspectionHeld.promise, + await inspectionHeld.reached( inspecting, "shared browser-socket inspection hold", ); @@ -1125,7 +1084,7 @@ it("isolates concurrent target sessions on one shared browser socket when a shor ); if (!barrier.ok) throw barrier.error; - peersGate.open(); + releasePeers(); const [inspected, observed] = await Promise.all([inspecting, observing]); if (!inspected.ok) throw inspected.error; if (!observed.ok) throw observed.error; @@ -1163,7 +1122,7 @@ it("isolates concurrent target sessions on one shared browser socket when a shor "session-3", ]); } finally { - peersGate.open(); + releasePeers(); controller.abort(new Error("test teardown")); await Promise.allSettled([observing, inspecting, capturing]); await provider.close(); diff --git a/tests/boundary/browser/cdpBrowserProvider.lifecycle_failures.test.ts b/tests/boundary/browser/cdpBrowserProvider.lifecycle_failures.test.ts index b16d91f1a9..df80eb44ca 100644 --- a/tests/boundary/browser/cdpBrowserProvider.lifecycle_failures.test.ts +++ b/tests/boundary/browser/cdpBrowserProvider.lifecycle_failures.test.ts @@ -1,4 +1,5 @@ import { describe, expect, it, vi } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { CdpBrowserProvider } from "../../../src/browser/CdpBrowserProvider.js"; import { @@ -751,16 +752,13 @@ describe("CdpBrowserProvider: source-map cancellation", () => { trackBrowser(browser); const controller = new AbortController(); const reason = new AnalysisInputError("caller_operation"); - let markSourceMapRequested!: () => void; - const sourceMapRequested = new Promise((resolve) => { - markSourceMapRequested = resolve; - }); + const sourceMapRequest = phaseArrival(); const originalFetch = globalThis.fetch; const fetchMock = vi .spyOn(globalThis, "fetch") .mockImplementation((resource, init) => { if (String(resource).includes("/app.js.map")) { - markSourceMapRequested(); + sourceMapRequest.arrive(); return new Promise((_resolve, reject) => { const signal = init?.signal; if (signal?.aborted === true) { @@ -785,7 +783,7 @@ describe("CdpBrowserProvider: source-map cancellation", () => { }), { signal: controller.signal }, ); - await sourceMapRequested; + await sourceMapRequest.reached(pending, "source-map request"); controller.abort(reason); const result = await pending; expect(result).toMatchObject({ diff --git a/tests/boundary/browser/cdpEndpointResponseBounds.test.ts b/tests/boundary/browser/cdpEndpointResponseBounds.test.ts index 255e22f567..ad840b6e8f 100644 --- a/tests/boundary/browser/cdpEndpointResponseBounds.test.ts +++ b/tests/boundary/browser/cdpEndpointResponseBounds.test.ts @@ -2,8 +2,8 @@ import { createServer } from "node:http"; import type { RequestListener, Server } from "node:http"; import { afterEach, describe, expect, it } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { discoverCdpEndpoint, @@ -151,15 +151,12 @@ describe("CDP discovery response bounds", () => { it("ends a response that exceeds the total elapsed deadline", async () => { let responseClosed = false; - let requestStarted: (() => void) | undefined; - const started = new Promise((resolve) => { - requestStarted = resolve; - }); + const cdpRequest = phaseArrival(); const server = await startServer((_request, response) => { response.once("close", () => { responseClosed = true; }); - requestStarted?.(); + cdpRequest.arrive(); }); const controller = new AbortController(); const pending = readCdpJson( @@ -172,7 +169,7 @@ describe("CDP discovery response bounds", () => { }, ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(started, pending, "CDP request"); + await cdpRequest.reached(pending, "CDP request"); await expect(pending).rejects.toMatchObject({ _tag: "BrowserObservationError", reason: "timeout", @@ -188,15 +185,12 @@ describe("CDP discovery response bounds", () => { it("preserves caller cancellation and closes the response", async () => { let responseClosed = false; - let requestStarted: (() => void) | undefined; - const started = new Promise((resolve) => { - requestStarted = resolve; - }); + const cdpRequest = phaseArrival(); const server = await startServer((_request, response) => { response.once("close", () => { responseClosed = true; }); - requestStarted?.(); + cdpRequest.arrive(); }); const controller = new AbortController(); const pending = readCdpJson( @@ -209,7 +203,7 @@ describe("CDP discovery response bounds", () => { }, ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(started, pending, "CDP request"); + await cdpRequest.reached(pending, "CDP request"); controller.abort(); await expect(pending).rejects.toMatchObject({ _tag: "AnalysisCancelledError", diff --git a/tests/boundary/browser/cdpTargetSessionOwner.test.ts b/tests/boundary/browser/cdpTargetSessionOwner.test.ts index 893ef435ee..7516ded11c 100644 --- a/tests/boundary/browser/cdpTargetSessionOwner.test.ts +++ b/tests/boundary/browser/cdpTargetSessionOwner.test.ts @@ -3,6 +3,7 @@ import type { Duplex } from "node:stream"; import { WebSocket, WebSocketServer } from "ws"; import { expect, it, onTestFinished, vi } from "vitest"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { CdpTargetSessionOwner } from "../../../src/browser/CdpTargetSessionOwner.js"; import { CdpConnection } from "../../../src/browser/CdpConnection.js"; @@ -15,7 +16,6 @@ import { } from "../../../src/domain/analysisErrorCore.js"; import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js"; import { startFakeCdpBrowser } from "../../fixtures/fakeCdpBrowser.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { waitFor } from "../../support/testWait.js"; it.each(["connect", "acquireBrowserSocket"] as const)( @@ -52,21 +52,15 @@ it("joins a late owned handshake and waits for its active operation", async () = const http = createServer(); const webSockets = new WebSocketServer({ noServer: true }); let port = 0; - let releaseUpgrade: (() => void) | undefined; - let upgradeReceived: (() => void) | undefined; - const received = new Promise((resolve) => { - upgradeReceived = resolve; - }); - const allow = new Promise((resolve) => { - releaseUpgrade = resolve; - }); + const lateUpgrade = phaseGate(); http.on("upgrade", (request, socket, head) => { - upgradeReceived?.(); - void allow.then(() => - webSockets.handleUpgrade(request, socket, head, (webSocket) => - webSockets.emit("connection", webSocket, request), - ), - ); + void lateUpgrade + .hold() + .then(() => + webSockets.handleUpgrade(request, socket, head, (webSocket) => + webSockets.emit("connection", webSocket, request), + ), + ); }); await new Promise((resolve) => http.listen(0, "127.0.0.1", resolve)); const address = http.address(); @@ -76,7 +70,7 @@ it("joins a late owned handshake and waits for its active operation", async () = const owner = new CdpTargetSessionOwner(); let connecting: Promise | undefined; onTestFinished(async () => { - releaseUpgrade?.(); + lateUpgrade.release(); if (connecting !== undefined) { const pendingConnection = await connecting; await owner.finish(pendingConnection); @@ -96,7 +90,7 @@ it("joins a late owned handshake and waits for its active operation", async () = {}, "late-handshake", ); - await received; + await lateUpgrade.reached(connecting, "late WebSocket upgrade"); const closing = owner.close(); let closed = false; void closing.then(() => { @@ -104,7 +98,7 @@ it("joins a late owned handshake and waits for its active operation", async () = }); await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); - releaseUpgrade?.(); + lateUpgrade.release(); const connection = await connecting; await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); @@ -409,15 +403,12 @@ it("surfaces cold-start acquireBrowserSocket cleanup failure to live waiters wit it("surfaces cold-start acquireBrowserSocket cleanup failure when the last waiter aborts without unhandled rejections", async () => { const http = createServer(); const upgradeSockets = new Set(); - let upgradeReceived: (() => void) | undefined; - const received = new Promise((resolve) => { - upgradeReceived = resolve; - }); + const upgradeReceipt = phaseArrival(); http.on("upgrade", (_request, socket) => { upgradeSockets.add(socket); socket.on("close", () => upgradeSockets.delete(socket)); socket.on("error", () => undefined); - upgradeReceived?.(); + upgradeReceipt.arrive(); }); await new Promise((resolve) => http.listen(0, "127.0.0.1", resolve)); const address = http.address(); @@ -461,8 +452,7 @@ it("surfaces cold-start acquireBrowserSocket cleanup failure when the last waite { signal: secondController.signal }, limits, ); - await awaitAcknowledgement( - received, + await upgradeReceipt.reached( Promise.all([first, second]), "cold browser-socket upgrade", ); diff --git a/tests/boundary/browser/historicalCaptureDecoder.test.ts b/tests/boundary/browser/historicalCaptureDecoder.test.ts index 72a18bca29..b8d87e1b44 100644 --- a/tests/boundary/browser/historicalCaptureDecoder.test.ts +++ b/tests/boundary/browser/historicalCaptureDecoder.test.ts @@ -1,7 +1,6 @@ import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import type { AnalysisError } from "../../../src/domain/analysisErrorBase.js"; import { ProviderProcessSupervisor } from "../../../src/process/ProviderProcess.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js"; import { access, @@ -18,6 +17,7 @@ import { import { tmpdir } from "node:os"; import { join } from "node:path"; import { expect, it, onTestFinished, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { HistoricalCaptureDecoder } from "../../../src/browser/history/HistoricalCaptureDecoder.js"; import { MitmproxyCaptureAdapter } from "../../../src/browser/history/MitmproxyCaptureAdapter.js"; import { @@ -247,8 +247,7 @@ it.each(["cancelled", "process"] as const)( const finishPath = join(root, "finish"); const text = JSON.stringify(historicalHar()); await writeFile(capturePath, text); - const peerEntered = createDeferred(); - const peerContinue = createDeferred(); + const peerCommand = phaseGate(); const controller = new AbortController(); const reason = { request: "cancel owned inert decoder" }; let targetPid: number | undefined; @@ -291,8 +290,7 @@ it.each(["cancelled", "process"] as const)( finishPath, ], }; - peerEntered.resolve(undefined); - await peerContinue.promise; + await peerCommand.hold(); await writeFile( join(runtimePath, "reply.json"), JSON.stringify({ ok: true, value: decodeHarCapture(text, []) }), @@ -321,7 +319,7 @@ it.each(["cancelled", "process"] as const)( onTestFinished(async () => { denied = false; denyRoot = false; - peerContinue.resolve(undefined); + peerCommand.release(); await targetOwner?.stop(); await decoder.close(); vi.restoreAllMocks(); @@ -336,7 +334,7 @@ it.each(["cancelled", "process"] as const)( targetPid = JSON.parse(await readFile(markerPath, "utf8")); }); const peer = decoder.inspect(input); - await peerEntered.promise; + await peerCommand.reached(peer, "peer decoder command"); if (outcome === "cancelled") controller.abort(reason); else await writeFile(finishPath, "finish workload"); const failed = await target; @@ -362,7 +360,7 @@ it.each(["cancelled", "process"] as const)( () => undefined, (cause) => cause, ); - peerContinue.resolve(undefined); + peerCommand.release(); expect((await peer).ok).toBe(true); expect(await closing).toBeInstanceOf(Error); expect(targetRootCloses).toBe(0); diff --git a/tests/boundary/browser/runtimeFixtureReadiness.test.ts b/tests/boundary/browser/runtimeFixtureReadiness.test.ts index e2c48194b2..495858b1a8 100644 --- a/tests/boundary/browser/runtimeFixtureReadiness.test.ts +++ b/tests/boundary/browser/runtimeFixtureReadiness.test.ts @@ -3,7 +3,7 @@ import { createServer } from "node:http"; import { setImmediate } from "node:timers/promises"; import { afterEach, expect, it, vi } from "vitest"; import { z } from "zod"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; const mock = vi.hoisted(() => ({ spawn: vi.fn(), port: vi.fn() })); vi.mock("../../../dist/process/ProviderProcess.js", () => ({ @@ -60,25 +60,17 @@ const startFixture = async (): Promise => ), ).startRuntimeFixtureBrowser; -const deferred = () => { - let resolve!: () => void; - const promise = new Promise((complete) => { - resolve = complete; - }); - return { promise, resolve }; -}; - const fixture = async ( mode: "empty targets" | "discovery timeout" | "malformed" | "exited", ) => { let ready = false; let requests = 0; - const listed = deferred(); - const published = deferred(); + const listed = phaseArrival(); + const published = phaseArrival(); const server = createServer((request, response) => { requests += 1; if (mode === "exited") { - listed.resolve(); + listed.arrive(); return; } if (mode === "malformed") { @@ -107,7 +99,7 @@ const fixture = async ( : [], ), ); - if (request.url === "/json/list") listed.resolve(); + if (request.url === "/json/list") listed.arrive(); }); await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); const address = server.address(); @@ -130,13 +122,13 @@ const fixture = async ( cleanup, }); mock.port.mockImplementation(async () => { - published.resolve(); + published.arrive(); return port; }); return { origin, - listed: listed.promise, - published: published.promise, + listed, + published, cleanup, exit: () => child.kill("SIGTERM"), makeReady: () => { @@ -166,19 +158,11 @@ it.each(["empty targets", "discovery timeout"] as const)( }, ); try { - await awaitAcknowledgement( - server.published, - pending, - "fixture port publication", - ); + await server.published.reached(pending, "fixture port publication"); await setImmediate(); expect(settled).toBe(false); if (mode === "empty targets") { - await awaitAcknowledgement( - server.listed, - pending, - "fixture target listing", - ); + await server.listed.reached(pending, "fixture target listing"); expect(settled).toBe(false); server.makeReady(); } @@ -216,11 +200,7 @@ it("interrupts pending discovery when the owned fixture exits", async () => { "exited before CDP discovery", ); try { - await awaitAcknowledgement( - server.listed, - pending, - "fixture target listing", - ); + await server.listed.reached(pending, "fixture target listing"); server.exit(); await rejected; expect(server.cleanup).toHaveBeenCalledTimes(1); diff --git a/tests/boundary/browser/webSourceMapFetcher.test.ts b/tests/boundary/browser/webSourceMapFetcher.test.ts index 9de0c68aa4..135056de57 100644 --- a/tests/boundary/browser/webSourceMapFetcher.test.ts +++ b/tests/boundary/browser/webSourceMapFetcher.test.ts @@ -2,9 +2,9 @@ import { createHash } from "node:crypto"; import { createServer } from "node:http"; import { describe, expect, it } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { fetchWebSourceMaps } from "../../../src/browser/WebSourceMapFetcher.js"; import { fetchWebSourceMapsOk } from "../../fixtures/fetchWebSourceMapsOk.js"; import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; @@ -808,17 +808,14 @@ describe("web source-map fetching and validation: enforcing fetch limits and val describe("source-map response cancellation", () => { it("cancels a pending response reader on caller abort", async () => { - let markPullStarted: (() => void) | undefined; - const pullStarted = new Promise((resolve) => { - markPullStarted = resolve; - }); + const pullStart = phaseArrival(); let cancelled = false; const body = new ReadableStream({ start(controller) { controller.enqueue(new TextEncoder().encode("{")); }, pull() { - markPullStarted?.(); + pullStart.arrive(); }, cancel() { cancelled = true; @@ -831,11 +828,7 @@ describe("source-map response cancellation", () => { }); await withVerifierCleanup(async () => { - await awaitAcknowledgement( - pullStarted, - pending, - "source-map response pull", - ); + await pullStart.reached(pending, "source-map response pull"); controller.abort(abortReason); const result = await pending; expect(result.ok).toBe(false); @@ -854,17 +847,14 @@ describe("completed source-map cancellation", () => { it.each([null, { stopped: "caller" }, new AnalysisCancelledError("test")])( "retains a completed map when a later response is cancelled with reason %s", async (reason) => { - let markPullStarted: (() => void) | undefined; - const pullStarted = new Promise((resolve) => { - markPullStarted = resolve; - }); + const pullStart = phaseArrival(); let cancelled = false; const secondBody = new ReadableStream({ start(controller) { controller.enqueue(new TextEncoder().encode("{")); }, pull() { - markPullStarted?.(); + pullStart.arrive(); }, cancel() { cancelled = true; @@ -903,11 +893,7 @@ describe("completed source-map cancellation", () => { ); await withVerifierCleanup(async () => { - await awaitAcknowledgement( - pullStarted, - pending, - "second source-map response pull", - ); + await pullStart.reached(pending, "second source-map response pull"); controller.abort(reason); const result = await pending; expect(result.ok).toBe(false); diff --git a/tests/boundary/cli/cliWorkerCompletion.test.ts b/tests/boundary/cli/cliWorkerCompletion.test.ts index e33fc5e1f9..4756a6ad8e 100644 --- a/tests/boundary/cli/cliWorkerCompletion.test.ts +++ b/tests/boundary/cli/cliWorkerCompletion.test.ts @@ -2,10 +2,9 @@ import { readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; import { expect } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { z } from "zod"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { createCliSessionFrameReader, @@ -55,15 +54,15 @@ process.stdout.write = (chunk, ...arguments_) => { child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString("utf8"); }); - const ready = createDeferred(); + const workerReady = phaseArrival(); child.stdout.on( "data", createCliSessionFrameReader((value: unknown) => { const frame = z.object({ ready: z.boolean() }).parse(value); - if (frame.ready) ready.resolve(); + if (frame.ready) workerReady.arrive(); }), ); - await awaitAcknowledgement(ready.promise, closed, "CLI worker startup"); + await workerReady.reached(closed, "CLI worker startup"); child.stdin.end( encodeCliSessionFrame({ id: 1, diff --git a/tests/boundary/evm/evmLimiterAvailability.test.ts b/tests/boundary/evm/evmLimiterAvailability.test.ts index 9f83640783..844a7d0c82 100644 --- a/tests/boundary/evm/evmLimiterAvailability.test.ts +++ b/tests/boundary/evm/evmLimiterAvailability.test.ts @@ -7,7 +7,7 @@ import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; import { buildCapabilityInventory } from "../../../src/application/CapabilityInventory.js"; import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; import { evmLimiterAvailability } from "../../../src/evm/EvmoleInterfaceProvider.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; const linux = { platform: "linux" as const, arch: "x64" }; const status = { open: false, capabilities: [] }; @@ -182,39 +182,31 @@ it("rechecks on each observation so inventory follows the selected executable's }); it("yields the event loop while the filesystem owner probe is pending", async () => { - let release!: () => void; - const pendingAccess = new Promise((resolve) => { - release = resolve; - }); - let accessStarted!: () => void; - const started = new Promise((resolve) => { - accessStarted = resolve; - }); + const filesystemAccess = phaseGate(); const probe = evmLimiterAvailability( {}, { ...linux, fs: { access: async () => { - accessStarted(); - await pendingAccess; + await filesystemAccess.hold(); }, stat: async () => ({ isFile: () => true }), }, }, ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(started, probe, "filesystem access"); + await filesystemAccess.reached(probe, "filesystem access"); let timerRan = false; setImmediate(() => { timerRan = true; }); await new Promise((resolve) => setImmediate(resolve)); expect(timerRan).toBe(true); - release(); + filesystemAccess.release(); expect(await probe).toMatchObject({ status: "available" }); }, [ - release, + filesystemAccess.release, async () => { await probe; }, @@ -224,14 +216,7 @@ it("yields the event loop while the filesystem owner probe is pending", async () it.each(["access", "stat"] as const)( "preserves cancellation while the %s filesystem probe is pending", async (stage) => { - let release!: () => void; - const pendingProbe = new Promise((resolve) => { - release = resolve; - }); - let probeStarted!: () => void; - const started = new Promise((resolve) => { - probeStarted = resolve; - }); + const filesystemProbe = phaseGate(); const controller = new AbortController(); const abortReason = { source: "caller-stop" }; const probe = evmLimiterAvailability( @@ -242,14 +227,12 @@ it.each(["access", "stat"] as const)( fs: { access: async () => { if (stage !== "access") return; - probeStarted(); - await pendingProbe; + await filesystemProbe.hold(); }, stat: async () => { if (stage === "access") throw new Error("stat must not run after access cancellation"); - probeStarted(); - await pendingProbe; + await filesystemProbe.hold(); return { isFile: () => true }; }, }, @@ -257,15 +240,15 @@ it.each(["access", "stat"] as const)( ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(started, probe, `${stage} filesystem probe`); + await filesystemProbe.reached(probe, `${stage} filesystem probe`); controller.abort(abortReason); - release(); + filesystemProbe.release(); const error = await probe.catch((cause: unknown) => cause); expect(error).toBeInstanceOf(AnalysisCancelledError); expect(error).toMatchObject({ operation: "binary_session" }); expect((error as AnalysisCancelledError).cause).toBe(abortReason); }, [ - release, + filesystemProbe.release, async () => { await probe.catch(() => undefined); }, diff --git a/tests/boundary/filesystem/analysisSnapshot.test.ts b/tests/boundary/filesystem/analysisSnapshot.test.ts index 9e1839131a..69fa7fe6ba 100644 --- a/tests/boundary/filesystem/analysisSnapshot.test.ts +++ b/tests/boundary/filesystem/analysisSnapshot.test.ts @@ -286,7 +286,7 @@ describe("analysis snapshot member decoding", () => { reads.release(); }); const pending = readAnalysisSnapshot(path, controller.signal); - await reads.firstRead; + await reads.reached(pending, "first file read"); controller.abort(reason); reads.release(); try { diff --git a/tests/boundary/filesystem/asarReaderCleanup.test.ts b/tests/boundary/filesystem/asarReaderCleanup.test.ts index 47acbf5b2d..016db621ed 100644 --- a/tests/boundary/filesystem/asarReaderCleanup.test.ts +++ b/tests/boundary/filesystem/asarReaderCleanup.test.ts @@ -13,7 +13,7 @@ import { describe, expect, it } from "vitest"; import { AsarArtifactReader } from "../../../src/artifacts/AsarArtifactReader.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; const CONTENT = "module.exports = 'owned';\n"; @@ -158,20 +158,12 @@ describe("ASAR reader cleanup", () => { it("closes a member handle adopted while reader shutdown is queued", async () => { const { archive } = await createArchive(); let pauseMemberOpen = false; - let memberOpenReached!: () => void; - let releaseMemberOpen!: () => void; - const memberOpenStarted = new Promise((resolve) => { - memberOpenReached = resolve; - }); - const memberOpenGate = new Promise((resolve) => { - releaseMemberOpen = resolve; - }); + const memberOpen = phaseGate(); const { reader, opened } = createTrackedReader(archive, { beforeAdoption: async (path) => { if (pauseMemberOpen && path.includes("rea-asar-snapshot-")) { pauseMemberOpen = false; - memberOpenReached(); - await memberOpenGate; + await memberOpen.hold(); } }, }); @@ -182,9 +174,9 @@ describe("ASAR reader cleanup", () => { const entry = await packedMember(reader); pauseMemberOpen = true; opening = reader.open(entry); - await awaitAcknowledgement(memberOpenStarted, opening, "member open"); + await memberOpen.reached(opening, "member open"); closing = reader.close(); - releaseMemberOpen(); + memberOpen.release(); const output = await opening; const memberHandle = latestHandle(opened); const root = dirname(memberHandle.path); @@ -194,7 +186,7 @@ describe("ASAR reader cleanup", () => { expect(output.destroyed).toBe(true); await expectSnapshotRemoved(memberHandle.fd, root); }, [ - releaseMemberOpen, + memberOpen.release, async () => { await opening; }, diff --git a/tests/boundary/filesystem/composedWorkflowEvidenceLinks.test.ts b/tests/boundary/filesystem/composedWorkflowEvidenceLinks.test.ts index 437086ab55..52e4d5c9cd 100644 --- a/tests/boundary/filesystem/composedWorkflowEvidenceLinks.test.ts +++ b/tests/boundary/filesystem/composedWorkflowEvidenceLinks.test.ts @@ -2,9 +2,8 @@ import { projectCliAnalysisResult } from "../../../src/cli/projectCliAnalysisRes import { executeComposedWorkflow } from "../../../src/application/WorkflowEvidence.js"; import { parseAnalysisSnapshot } from "../../../src/domain/analysisSnapshot.js"; import { ok } from "../../../src/domain/result.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { expect, it } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { runDirectAnalysis } from "../../../src/application/DirectAnalysis.js"; import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js"; import { composedWorkflowFixture } from "../../fixtures/composedWorkflowEvidence.js"; @@ -177,12 +176,10 @@ it.each([false, true])( ); it("deduplicates repeated and nested consumed records without linking unrelated concurrent work", async () => { - const entered = createDeferred(); - const release = createDeferred(); + const summaryExecution = phaseGate(); const fixture = await composedWorkflowFixture({ beforeSummary: async () => { - entered.resolve(); - await release.promise; + await summaryExecution.hold(); }, }); await fixture.open(); @@ -202,7 +199,7 @@ it("deduplicates repeated and nested consumed records without linking unrelated }, ); try { - await awaitAcknowledgement(entered.promise, overview, "summary execution"); + await summaryExecution.reached(overview, "summary execution"); const other = await executeComposedWorkflow( fixture.session, async (observed) => { @@ -214,7 +211,7 @@ it("deduplicates repeated and nested consumed records without linking unrelated }, ); if (!other.ok) throw other.error; - release.resolve(); + summaryExecution.release(); const result = await overview; if (!result.ok) throw result.error; const atomic = fixture.session @@ -235,7 +232,7 @@ it("deduplicates repeated and nested consumed records without linking unrelated ), ).toHaveLength(1); } finally { - release.resolve(); + summaryExecution.release(); await overview; } }); diff --git a/tests/boundary/filesystem/desktopApplication.test.ts b/tests/boundary/filesystem/desktopApplication.test.ts index a42913f4e0..35f07be76c 100644 --- a/tests/boundary/filesystem/desktopApplication.test.ts +++ b/tests/boundary/filesystem/desktopApplication.test.ts @@ -12,7 +12,7 @@ import { execFileSync } from "node:child_process"; import { createServer as createNetServer } from "node:net"; import { expect, it, onTestFinished, vi } from "vitest"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { createDesktopApplicationService } from "../../../src/composition/desktop.js"; import { desktopApplicationSchema, @@ -757,21 +757,13 @@ it("keeps a completed directory report and exact cleanup authority until retry c it("bounds simultaneous directory scans without cancelling the admitted caller", async () => { const root = await createTestTempDirectory("rea-desktop-capacity-"); await put(root, "notes.txt", "observed"); - let release!: () => void; - let entered!: () => void; - const barrier = new Promise((resolve) => { - release = resolve; - }); - const started = new Promise((resolve) => { - entered = resolve; - }); + const desktopDirectoryScan = phaseGate(); const service = new DesktopApplicationService( new DesktopApplicationReader((path) => { const reader = new DirectoryArtifactReader(path); const entries = reader.entries.bind(reader); reader.entries = async function* (...args: Parameters) { - entered(); - await barrier; + await desktopDirectoryScan.hold(); yield* entries(...args); }; return reader; @@ -779,7 +771,7 @@ it("bounds simultaneous directory scans without cancelling the admitted caller", ); const first = service.inspect({ path: root }); try { - await awaitAcknowledgement(started, first, "desktop directory scan"); + await desktopDirectoryScan.reached(first, "desktop directory scan"); const second = await service.inspect({ path: root }); expect(second.ok).toBe(false); if (!second.ok) @@ -788,14 +780,14 @@ it("bounds simultaneous directory scans without cancelling the admitted caller", resource: "capacity", retryable: true, }); - release(); + desktopDirectoryScan.release(); const result = await first; if (!result.ok) throw result.error; expect( desktopApplicationSchema.parse(result.value.normalized_result).files, ).toHaveLength(1); } finally { - release(); + desktopDirectoryScan.release(); try { await first; } finally { diff --git a/tests/boundary/filesystem/evidenceBundleFiles.test.ts b/tests/boundary/filesystem/evidenceBundleFiles.test.ts index 4e727a37b2..89d3df231d 100644 --- a/tests/boundary/filesystem/evidenceBundleFiles.test.ts +++ b/tests/boundary/filesystem/evidenceBundleFiles.test.ts @@ -425,7 +425,7 @@ it.each([ const reason = new Error("stop bundle import"); try { const pending = read(path, controller.signal); - await reader.firstRead; + await reader.reached(pending, "first file read"); controller.abort(reason); reader.release(); const result = await pending; diff --git a/tests/boundary/filesystem/ghidraLanguageCatalogRecovery.test.ts b/tests/boundary/filesystem/ghidraLanguageCatalogRecovery.test.ts index 457d5f9115..df95be4893 100644 --- a/tests/boundary/filesystem/ghidraLanguageCatalogRecovery.test.ts +++ b/tests/boundary/filesystem/ghidraLanguageCatalogRecovery.test.ts @@ -2,6 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { afterEach, expect, it, onTestFinished, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { AnalysisProviderRegistry } from "../../../src/application/binary/AnalysisProviderRegistry.js"; import { composeBinarySession } from "../../../src/application/binary/BinarySessionComposition.js"; import { parseConfig } from "../../../src/config/parseConfig.js"; @@ -10,8 +11,6 @@ import { ghidraProfileInstallationHost } from "../../../src/ghidra/GhidraInstall import { GhidraProvider } from "../../../src/ghidra/GhidraProvider.js"; import { silentLogger } from "../../../src/logger.js"; import { createServer } from "../../../src/server/createServer.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { nativeAotPeFixture } from "../../fixtures/nativeaotPe.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; @@ -186,11 +185,9 @@ it.each(["released", "still failing"] as const)( expect(first.error.cleanupIncomplete).toBe(true); expect(first.error.cleanupResources).toEqual([definition]); - const entered = createDeferred(); - const release = createDeferred(); + const catalogCleanup = phaseGate(); fault.onClose = async () => { - entered.resolve(undefined); - await release.promise; + await catalogCleanup.hold(); }; const controller = new AbortController(); const reason = { caller: "cancel during catalog cleanup retry" }; @@ -201,14 +198,14 @@ it.each(["released", "still failing"] as const)( settled = true; }); try { - await awaitAcknowledgement(entered.promise, admission, "catalog cleanup"); + await catalogCleanup.reached(admission, "catalog cleanup"); controller.abort(reason); await Promise.resolve(); // Cancellation never abandons the in-flight close of the retained owner. expect(settled).toBe(false); if (outcome === "released") fault.deny = false; fault.onClose = undefined; - release.resolve(undefined); + catalogCleanup.release(); const cancelled = await admission; if (cancelled.ok) throw new Error("Expected cancelled admission"); expect(fault.closes).toBe(2); @@ -236,7 +233,7 @@ it.each(["released", "still failing"] as const)( expect(registry.hasPendingOwnedResources()).toBe(false); } finally { fault.onClose = undefined; - release.resolve(undefined); + catalogCleanup.release(); await admission.catch(() => undefined); } }, diff --git a/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts b/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts index d2417bb106..11b8c973a1 100644 --- a/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts +++ b/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts @@ -7,8 +7,6 @@ import { GhidraProvider } from "../../../src/ghidra/GhidraProvider.js"; import { ghidraProfileInstallationHost } from "../../../src/ghidra/GhidraInstallation.fixture.js"; import { silentLogger } from "../../../src/logger.js"; import { OwnerCancellation } from "../../../src/domain/analysisErrorCore.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { readFile, rename, @@ -17,6 +15,7 @@ import { type FileHandle, } from "node:fs/promises"; import { afterEach, expect, it, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { ArtifactResourceScope } from "../../../src/resources/ArtifactResourceScope.js"; import { parseConfig } from "../../../src/config/parseConfig.js"; import { @@ -379,13 +378,11 @@ it("joins whole provider resolution before shutdown and gates the next admission {}, ghidraProfileInstallationHost, ); - const entered = createDeferred(); - const release = createDeferred(); + const profileResolution = phaseGate(); controls.realpath = async (path) => { if (path !== seed) return; controls.realpath = undefined; - entered.resolve(); - await release.promise; + await profileResolution.hold(); }; let opens = 0; controls.file = () => { @@ -395,11 +392,7 @@ it("joins whole provider resolution before shutdown and gates the next admission let closing: ReturnType | undefined; let next: ReturnType | undefined; try { - await awaitAcknowledgement( - entered.promise, - resolving, - "profile resolution", - ); + await profileResolution.reached(resolving, "profile resolution"); const count = opens; let closed = false; closing = provider.closeOwnedResources().then((result) => { @@ -411,7 +404,7 @@ it("joins whole provider resolution before shutdown and gates the next admission expect(closed).toBe(false); expect(opens).toBe(count); expect(provider.hasPendingOwnedResources()).toBe(true); - release.resolve(); + profileResolution.release(); const stopped = await resolving; if (stopped.ok) throw new Error("Expected owned resolution cancellation"); expect(stopped.error.cause).toBe(OwnerCancellation.startupOwnerClosed); @@ -427,7 +420,7 @@ it("joins whole provider resolution before shutdown and gates the next admission expect((await next).ok).toBe(true); expect(provider.hasPendingOwnedResources()).toBe(false); } finally { - release.resolve(); + profileResolution.release(); await Promise.allSettled([ resolving, ...(closing ? [closing] : []), diff --git a/tests/boundary/filesystem/ownedArtifactReaderCleanup.test.ts b/tests/boundary/filesystem/ownedArtifactReaderCleanup.test.ts index ba8b85d14b..d44e4c7140 100644 --- a/tests/boundary/filesystem/ownedArtifactReaderCleanup.test.ts +++ b/tests/boundary/filesystem/ownedArtifactReaderCleanup.test.ts @@ -4,7 +4,7 @@ import { join } from "node:path"; import { expect, it, onTestFinished, vi } from "vitest"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { ArtifactResourceScope } from "../../../src/resources/ArtifactResourceScope.js"; import { BunStandaloneArtifactReader } from "../../../src/artifacts/BunStandaloneArtifactReader.js"; import { DenoStandaloneArtifactReader } from "../../../src/artifacts/DenoStandaloneArtifactReader.js"; @@ -227,14 +227,7 @@ it("joins late .NET descriptor admission before reporting reader shutdown", asyn const root = await createTestTempDirectory("rea-dotnet-late-admission-"); const path = join(root, "source"); await writeFile(path, "unread source"); - let reach = () => {}; - let resume = () => {}; - const reached = new Promise((resolve) => { - reach = resolve; - }); - const gate = new Promise((resolve) => { - resume = resolve; - }); + const netDescriptorAdmission = phaseGate(); let descriptor: FileHandle | undefined; injected.opened = (openedPath, handle) => { if (openedPath !== path || descriptor !== undefined) return; @@ -244,8 +237,7 @@ it("joins late .NET descriptor admission before reporting reader shutdown", asyn vi.spyOn(handle, "stat").mockImplementation(async (...args) => { if (!held) { held = true; - reach(); - await gate; + await netDescriptorAdmission.hold(); } return stat(...args); }); @@ -255,8 +247,7 @@ it("joins late .NET descriptor admission before reporting reader shutdown", asyn try { const inspection = reader.entries()[Symbol.asyncIterator]().next(); launched.push(inspection); - await awaitAcknowledgement( - reached, + await netDescriptorAdmission.reached( inspection, ".NET descriptor admission", ); @@ -267,12 +258,12 @@ it("joins late .NET descriptor admission before reporting reader shutdown", asyn launched.push(closing); await Promise.resolve(); expect(closed).toBe(false); - resume(); + netDescriptorAdmission.release(); await Promise.allSettled(launched); expect(closed).toBe(true); expect(descriptor?.fd).toBe(-1); } finally { - resume(); + netDescriptorAdmission.release(); await Promise.allSettled(launched); try { await reader.close(); diff --git a/tests/boundary/filesystem/processCliFileInput.test.ts b/tests/boundary/filesystem/processCliFileInput.test.ts index 85528b352d..77a81c27e0 100644 --- a/tests/boundary/filesystem/processCliFileInput.test.ts +++ b/tests/boundary/filesystem/processCliFileInput.test.ts @@ -135,7 +135,7 @@ describe("process CLI file cancellation", () => { process.env, controller.signal, ); - await reader.firstRead; + await reader.reached(pending, "first file read"); controller.abort(); reader.release(); expect(await pending).toMatchObject({ diff --git a/tests/boundary/filesystem/setupClientConfigCleanupOwnership.test.ts b/tests/boundary/filesystem/setupClientConfigCleanupOwnership.test.ts index c5743eb418..c1617c8354 100644 --- a/tests/boundary/filesystem/setupClientConfigCleanupOwnership.test.ts +++ b/tests/boundary/filesystem/setupClientConfigCleanupOwnership.test.ts @@ -38,7 +38,7 @@ import { runUninstall, } from "../../../src/application/Uninstall.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; import { supportedClientRegistrationProfile } from "../../../src/application/SupportedClients.js"; @@ -836,14 +836,7 @@ describe("setup client configuration cleanup ownership", () => { ); await writeFile(client.configPath, '{"servers": {}}\n'); - let beginRead!: () => void; - const readStarted = new Promise((resolve) => { - beginRead = resolve; - }); - let unblockRead!: () => void; - const readGate = new Promise((resolve) => { - unblockRead = resolve; - }); + const configurationRead = phaseGate(); let heldRead = false; openMock.mockImplementation(async (...args) => { const handle = await actualFs.open(...args); @@ -851,8 +844,7 @@ describe("setup client configuration cleanup ownership", () => { heldRead = true; const nativeRead = handle.read.bind(handle); vi.spyOn(handle, "read").mockImplementation(async (...readArgs) => { - beginRead(); - await readGate; + await configurationRead.hold(); return nativeRead(...readArgs); }); return handle; @@ -862,7 +854,7 @@ describe("setup client configuration cleanup ownership", () => { const alignment = host.clientNeedsConfigure(client, {}, ["rea", "mcp"]); let closeResult: ReturnType> | undefined; await withVerifierCleanup(async () => { - await awaitAcknowledgement(readStarted, alignment, "configuration read"); + await configurationRead.reached(alignment, "configuration read"); const close = host.close; if (close === undefined) throw new Error("Setup host close is missing"); @@ -883,12 +875,12 @@ describe("setup client configuration cleanup ownership", () => { }); expect(hostCloseFinished).toBe(false); - unblockRead(); + configurationRead.release(); await expect(alignment).resolves.toBe(true); expect(await closeResult).toBeUndefined(); expect(hostCloseFinished).toBe(true); }, [ - unblockRead, + configurationRead.release, async () => { await alignment; }, diff --git a/tests/boundary/filesystem/setupSkillCleanupOwnership.test.ts b/tests/boundary/filesystem/setupSkillCleanupOwnership.test.ts index fd937aa292..2c3bbff26a 100644 --- a/tests/boundary/filesystem/setupSkillCleanupOwnership.test.ts +++ b/tests/boundary/filesystem/setupSkillCleanupOwnership.test.ts @@ -28,7 +28,7 @@ import { systemUninstallHost, } from "../../../src/application/Uninstall.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; vi.mock("node:fs/promises", async (importOriginal) => { @@ -227,14 +227,7 @@ describe("skill regular-file cleanup ownership", () => { await mkdir(dirname(manifest), { recursive: true }); await writeFile(manifest, "stale managed skill\n"); const resources = new ArtifactResourceScope(); - let beginRead!: () => void; - const readStarted = new Promise((resolve) => { - beginRead = resolve; - }); - let unblockRead!: () => void; - const readGate = new Promise((resolve) => { - unblockRead = resolve; - }); + const skillRead = phaseGate(); let heldRead = false; openMock.mockImplementation(async (...args) => { const handle = await actualFs.open(...args); @@ -242,8 +235,7 @@ describe("skill regular-file cleanup ownership", () => { heldRead = true; const nativeRead = handle.read.bind(handle); vi.spyOn(handle, "read").mockImplementation(async (...readArgs) => { - beginRead(); - await readGate; + await skillRead.hold(); return nativeRead(...readArgs); }); return handle; @@ -252,19 +244,19 @@ describe("skill regular-file cleanup ownership", () => { const reading = readSkillFile(manifest, resources); let closing: Promise | undefined; await withVerifierCleanup(async () => { - await awaitAcknowledgement(readStarted, reading, "skill read"); + await skillRead.reached(reading, "skill read"); let closed = false; closing = resources.close().then(() => { closed = true; }); await Promise.resolve(); expect(closed).toBe(false); - unblockRead(); + skillRead.release(); expect(await reading).toBe("stale managed skill\n"); await closing; expect(closed).toBe(true); }, [ - unblockRead, + skillRead.release, async () => { await reading; }, diff --git a/tests/boundary/filesystem/stableArtifact.test.ts b/tests/boundary/filesystem/stableArtifact.test.ts index 8c1cf0f3c3..cf4ecd4ae6 100644 --- a/tests/boundary/filesystem/stableArtifact.test.ts +++ b/tests/boundary/filesystem/stableArtifact.test.ts @@ -10,7 +10,7 @@ import { import { join } from "node:path"; import { createHash } from "node:crypto"; import { expect, it, onTestFinished } from "vitest"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { readStableArtifact } from "../../../src/resources/readStableArtifact.js"; import { artifactFileCompletion, @@ -129,16 +129,7 @@ it.each(["complete", "fail"] as const)( const physical = Object.assign(new Error("pending physical read failed"), { code: "EIO", }); - let enter!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - let release!: () => void; - let reject!: (cause: unknown) => void; - const blocked = new Promise((resolve, fail) => { - release = resolve; - reject = fail; - }); + const stableRead = phaseGate(); let descriptor: Awaited> | undefined; const reading = readStableArtifact(path, 64, controller.signal, { lstat: (selected) => lstat(selected, { bigint: true }), @@ -147,8 +138,7 @@ it.each(["complete", "fail"] as const)( descriptor = handle; Object.defineProperty(handle, "read", { value: async (buffer: Buffer, offset: number) => { - enter(); - await blocked; + await stableRead.hold(); buffer.set(bytes, offset); return { bytesRead: bytes.length, buffer }; }, @@ -163,13 +153,13 @@ it.each(["complete", "fail"] as const)( settled = true; }); try { - await awaitAcknowledgement(entered, result, "stable artifact read"); + await stableRead.reached(result, "stable artifact read"); controller.abort(reason); await new Promise((resolve) => setImmediate(resolve)); expect(settled).toBe(false); expect(descriptor?.fd).toBeGreaterThanOrEqual(0); - if (outcome === "fail") reject(physical); - else release(); + if (outcome === "fail") stableRead.reject(physical); + else stableRead.release(); const failure = await result; if (outcome === "fail") expect(failure).toBe(physical); else @@ -178,7 +168,7 @@ it.each(["complete", "fail"] as const)( expect(descriptor?.fd).toBe(-1); } finally { controller.abort(reason); - release(); + stableRead.release(); await result; } }, diff --git a/tests/boundary/filesystem/windowsShortcut.test.ts b/tests/boundary/filesystem/windowsShortcut.test.ts index 30d26ec776..f264e04d17 100644 --- a/tests/boundary/filesystem/windowsShortcut.test.ts +++ b/tests/boundary/filesystem/windowsShortcut.test.ts @@ -7,7 +7,7 @@ import { powershellHiddenIconSpoofShortcut, windowsShortcutBytes, } from "../../fixtures/binaryDiagnostics/windowsShortcut.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; const { realpathCalls, lstatCalls, lstatGate } = vi.hoisted(() => ({ @@ -15,9 +15,7 @@ const { realpathCalls, lstatCalls, lstatGate } = vi.hoisted(() => ({ lstatCalls: vi.fn(), // When set, the next lstat reports its path and waits for the gate. lstatGate: {} as { - hold?: - | { entered: (path: string) => void; release: Promise } - | undefined; + hold?: ((path: string) => Promise) | undefined; }, })); @@ -34,8 +32,7 @@ vi.mock("node:fs/promises", async (importOriginal) => { const hold = lstatGate.hold; if (hold !== undefined) { lstatGate.hold = undefined; - hold.entered(String(args[0])); - await hold.release; + await hold(String(args[0])); } return actual.lstat(...args); }) as typeof actual.lstat, @@ -252,24 +249,13 @@ describe("Windows shortcut parent directory links", () => { const path = join(root, "shortcut.lnk"); await writeFile(path, powershellHiddenIconSpoofShortcut()); const provider = new WindowsShortcutProvider("win32"); - let release!: () => void; - const entered = new Promise((resolve) => { - lstatGate.hold = { - entered: resolve, - release: new Promise((done) => { - release = done; - }), - }; - }); + const parentWalk = phaseGate(); + lstatGate.hold = (selected) => parentWalk.hold(selected); const inspecting = provider.inspect(providerInput(path)); let closing: Promise | undefined; try { - await awaitAcknowledgement( - entered.then(() => undefined), - inspecting, - "parent walk lstat", - ); + await parentWalk.reached(inspecting, "parent walk lstat"); let closed = false; closing = provider.close().then(() => { closed = true; @@ -278,7 +264,7 @@ describe("Windows shortcut parent directory links", () => { expect(closed).toBe(false); } finally { lstatGate.hold = undefined; - release(); + parentWalk.release(); await inspecting; await closing; } @@ -296,7 +282,7 @@ describe("Windows shortcut parent directory links", () => { const path = join(root, "shortcut.lnk"); await writeFile(path, powershellHiddenIconSpoofShortcut()); const entered = vi.fn(); - lstatGate.hold = { entered, release: Promise.resolve() }; + lstatGate.hold = async (selected) => entered(selected); const result = await new WindowsShortcutProvider("win32").inspect( providerInput(path), @@ -353,7 +339,7 @@ describe("Windows shortcut parent directory links", () => { ["..\\real\\a.lnk", ".."], ] as const) { const entered = vi.fn(); - lstatGate.hold = { entered, release: Promise.resolve() }; + lstatGate.hold = async (selected) => entered(selected); await provider.inspect(providerInput(path)); lstatGate.hold = undefined; expect(entered).toHaveBeenCalledWith(first); diff --git a/tests/boundary/il2cpp/il2cppMetadataProvider.test.ts b/tests/boundary/il2cpp/il2cppMetadataProvider.test.ts index 6fa220f78e..a5b1d14092 100644 --- a/tests/boundary/il2cpp/il2cppMetadataProvider.test.ts +++ b/tests/boundary/il2cpp/il2cppMetadataProvider.test.ts @@ -27,7 +27,7 @@ import { createLinkedIl2cppMetadataFixture, } from "../../fixtures/il2cpp/metadata.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; afterEach(() => { vi.restoreAllMocks(); @@ -485,23 +485,15 @@ it("bounds concurrent snapshots and retains active decoding until close complete const root = await createTestTempDirectory("rea-il2cpp-provider-close-"); const path = join(root, "global-metadata.dat"); await writeFile(path, createIl2cppMetadataFixture().bytes); - let markEntered!: () => void; - const entered = new Promise((resolve) => { - markEntered = resolve; - }); - let resume!: () => void; - const release = new Promise((resolve) => { - resume = resolve; - }); + const decoding = phaseGate(); const provider = new Il2cppMetadataProvider(undefined, () => { - markEntered(); - return release; + return decoding.hold(); }); const active = provider.inspect({ path }); let closed = false; let closing: Promise | undefined; await withVerifierCleanup(async () => { - await awaitAcknowledgement(entered, active, "metadata decoding"); + await decoding.reached(active, "metadata decoding"); closing = provider.close().then(() => { closed = true; }); @@ -520,7 +512,7 @@ it("bounds concurrent snapshots and retains active decoding until close complete } await setImmediate(); expect(closed).toBe(false); - resume(); + decoding.release(); await closing; expect((await active).ok).toBe(true); expect(closed).toBe(true); @@ -533,7 +525,7 @@ it("bounds concurrent snapshots and retains active decoding until close complete expect(projectAnalysisError(afterClose.error).retryable).toBe(false); } }, [ - resume, + decoding.release, async () => { await closing; }, @@ -550,21 +542,13 @@ it("keeps occupied capacity retryable while the reader remains open", async () = const root = await createTestTempDirectory("rea-il2cpp-provider-occupied-"); const path = join(root, "global-metadata.dat"); await writeFile(path, createIl2cppMetadataFixture().bytes); - let markEntered!: () => void; - const entered = new Promise((resolve) => { - markEntered = resolve; - }); - let resume!: () => void; - const release = new Promise((resolve) => { - resume = resolve; - }); + const decoding = phaseGate(); const provider = new Il2cppMetadataProvider(undefined, () => { - markEntered(); - return release; + return decoding.hold(); }); const active = provider.inspect({ path }); await withVerifierCleanup(async () => { - await awaitAcknowledgement(entered, active, "metadata decoding"); + await decoding.reached(active, "metadata decoding"); const refused = await provider.inspect({ path }); expect(refused.ok).toBe(false); if (!refused.ok) { @@ -581,7 +565,7 @@ it("keeps occupied capacity retryable while the reader remains open", async () = }); } }, [ - resume, + decoding.release, async () => { await active; }, diff --git a/tests/boundary/javascript/javascriptSourceAnalysisWorker.test.ts b/tests/boundary/javascript/javascriptSourceAnalysisWorker.test.ts index eaa26b2355..1d8f9378f4 100644 --- a/tests/boundary/javascript/javascriptSourceAnalysisWorker.test.ts +++ b/tests/boundary/javascript/javascriptSourceAnalysisWorker.test.ts @@ -5,7 +5,7 @@ import { join } from "node:path"; import { promisify } from "node:util"; import { expect, it } from "vitest"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { JavaScriptAnalysisWorker } from "../../../src/javascript/analysis/JavaScriptAnalysisWorker.js"; import { createJavaScriptSourceAnalysis } from "../../../src/artifacts/javascript/JavaScriptSourceAnalysis.js"; import { ArtifactResourceScope } from "../../../src/resources/ArtifactResourceScope.js"; @@ -332,15 +332,8 @@ it("keeps a worker parked while a limit change closes the previous process", asy const limits = { heapMb: 128, timeoutMs: 30_000 }; const file = source("parked.mjs", "export const observed = 1;"); const originalClose = JavaScriptAnalysisWorker.prototype.close; - let releaseClose = (): void => {}; - const gate = new Promise((resolve) => { - releaseClose = resolve; - }); let closeCalls = 0; - let markCloseStarted = (): void => {}; - const closeStarted = new Promise((resolve) => { - markCloseStarted = resolve; - }); + const workerClose = phaseGate(); let replacement: | ReturnType | undefined; @@ -361,8 +354,7 @@ it("keeps a worker parked while a limit change closes the previous process", asy ) { closeCalls += 1; if (closeCalls === 1) { - markCloseStarted(); - await gate; + await workerClose.hold(); } return originalClose.call(this); }; @@ -371,7 +363,7 @@ it("keeps a worker parked while a limit change closes the previous process", asy 1, { scope, launcher }, ); - await awaitAcknowledgement(closeStarted, replacement, "worker close"); + await workerClose.reached(replacement, "worker close"); const concurrent = await createJavaScriptSourceAnalysis(limits, 1, { scope, @@ -387,7 +379,7 @@ it("keeps a worker parked while a limit change closes the previous process", asy if (parkedPid === undefined) throw new Error("Parked analyzer has no observed PID"); - releaseClose(); + workerClose.release(); const extra = await replacement; const extraResult = await extra.analyze(file, { nodes: 100, @@ -408,7 +400,7 @@ it("keeps a worker parked while a limit change closes the previous process", asy await exits.get(parkedPid); expect(exited.has(parkedPid)).toBe(true); }, [ - releaseClose, + workerClose.release, async () => { const port = await replacement?.catch(() => undefined); await port?.close(); diff --git a/tests/boundary/mcp/applicationMcpHarnessLifecycle.test.ts b/tests/boundary/mcp/applicationMcpHarnessLifecycle.test.ts index cc5b1d6630..31080620aa 100644 --- a/tests/boundary/mcp/applicationMcpHarnessLifecycle.test.ts +++ b/tests/boundary/mcp/applicationMcpHarnessLifecycle.test.ts @@ -2,6 +2,7 @@ import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect, it, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import type { AnalysisClient } from "../../../src/ports/AnalysisProvider.js"; import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js"; @@ -12,11 +13,9 @@ import { } from "../../fixtures/applicationMcpHarness.js"; import { createCacheProvider, - createDeferred, createTestBinarySession, } from "../../fixtures/binarySession.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { releaseOwnedCleanup } from "../../support/cleanupRelease.js"; const failureLeaves = (reason: unknown): unknown[] => @@ -66,12 +65,10 @@ it("reports a failed session close, joins concurrent attempts and retries the re const failure = new ProviderCleanupError("fixture", ["binary-owner"], { reason: "controlled binary close denial", }); - const entered = createDeferred(); - const release = createDeferred(); + const providerClose = phaseGate(); let allowClose = false; const closeProvider = vi.fn(async () => { - entered.resolve(); - await release.promise; + await providerClose.hold(); if (!allowClose) return err(failure); releaseOwnedCleanup(failure); return ok(null); @@ -82,11 +79,11 @@ it("reports a failed session close, joins concurrent attempts and retries the re harness = acquired.harness; const closing = harness.close(); const outcome = closing.catch((reason: unknown) => reason); - await awaitAcknowledgement(entered.promise, outcome, "provider close"); + await providerClose.reached(outcome, "provider close"); const concurrent = harness.close(); const concurrentOutcome = concurrent.catch((reason: unknown) => reason); expect(closeProvider).toHaveBeenCalledTimes(1); - release.resolve(); + providerClose.release(); const reason: unknown = await outcome; expect(reason).toBeInstanceOf(AggregateError); if (!(reason instanceof AggregateError)) @@ -110,7 +107,7 @@ it("reports a failed session close, joins concurrent attempts and retries the re expect(closeProvider).toHaveBeenCalledTimes(2); } finally { allowClose = true; - release.resolve(); + providerClose.release(); await harness?.close(); } }); diff --git a/tests/boundary/mcp/buildSecretsMcp.test.ts b/tests/boundary/mcp/buildSecretsMcp.test.ts index cc4e93b8b8..4e683bf42e 100644 --- a/tests/boundary/mcp/buildSecretsMcp.test.ts +++ b/tests/boundary/mcp/buildSecretsMcp.test.ts @@ -34,7 +34,7 @@ import { import type { FakeApp } from "../../fixtures/fakeAgentEnvComputer.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { AgentEnvComputer } from "../../../src/desktop/AgentEnvComputer.js"; import { DesktopBuildSecrets } from "../../../src/application/desktop/DesktopBuildSecrets.js"; @@ -524,14 +524,7 @@ it.each([ computer_id: first, name: "end", }); - let entered = () => {}; - const acknowledged = new Promise((resolve) => { - entered = resolve; - }); - let release = () => {}; - const gate = new Promise((resolve) => { - release = resolve; - }); + const captureOutputRead = phaseGate(); const original = AgentEnvComputer.prototype.homeFiles; const spy = vi .spyOn(AgentEnvComputer.prototype, "homeFiles") @@ -552,8 +545,7 @@ it.each([ ), ) ) { - entered(); - await gate; + await captureOutputRead.hold(); } return original.call(this, paths, bytes, signal); }); @@ -570,8 +562,7 @@ it.each([ (phase === "draft-command" || phase === "draft-failure") && argv.some((arg) => arg.includes("describe-desktop-application-task")) ) { - entered(); - await gate; + await captureOutputRead.hold(); if (phase === "draft-failure") throw new Error(VALUE.slice(0, 10)); } return originalExec.call(this, argv, timeout, signal); @@ -580,12 +571,12 @@ it.each([ computer_id: first, }); try { - await awaitAcknowledgement(acknowledged, stopping, "capture output read"); + await captureOutputRead.reached(stopping, "capture output read"); expect(await secrets.resolve("master")).toEqual({ ok: true, value: VALUE, }); - release(); + captureOutputRead.release(); const stopped = await stopping; expect(stopped.structuredContent).toMatchObject({ draft: null, @@ -601,7 +592,7 @@ it.each([ expect(JSON.stringify(stopped)).not.toContain(VALUE.slice(0, 10)); } } finally { - release(); + captureOutputRead.release(); await Promise.allSettled([stopping]); spy.mockRestore(); execSpy.mockRestore(); diff --git a/tests/boundary/mcp/bundleComparisonCancellation.test.ts b/tests/boundary/mcp/bundleComparisonCancellation.test.ts index 22fd1e3abe..285575ace4 100644 --- a/tests/boundary/mcp/bundleComparisonCancellation.test.ts +++ b/tests/boundary/mcp/bundleComparisonCancellation.test.ts @@ -2,6 +2,7 @@ import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect, it, onTestFinished, vi } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; import { createEvidence } from "../../../src/domain/evidence.js"; @@ -76,16 +77,13 @@ it("leaves the session unchanged after bundle comparison cancellation and permit const reader = await holdFirstFileRead(leftPath); releaseRead = reader.release; - let resolveDispatched: (() => void) | undefined; - const dispatched = new Promise((resolve) => { - resolveDispatched = resolve; - }); + const dispatch = phaseArrival(); const send = clientTransport.send.bind(clientTransport); vi.spyOn(clientTransport, "send").mockImplementation( async (message, ...args) => { await send(message, ...args); if ("method" in message && message.method === "tools/call") - resolveDispatched?.(); + dispatch.arrive(); }, ); let resolveCompleted: (() => void) | undefined; @@ -124,8 +122,8 @@ it("leaves the session unchanged after bundle comparison cancellation and permit () => "completed", (error: unknown) => error, ); - await dispatched; - await reader.firstRead; + await dispatch.reached(cancellation, "compare_bundles dispatch"); + await reader.reached(cancellation, "first file read"); await client.ping(); controller.abort(new Error("SDK bundle comparison cancellation")); reader.release(); diff --git a/tests/boundary/mcp/capabilityRemediationMcp.test.ts b/tests/boundary/mcp/capabilityRemediationMcp.test.ts index eeba046845..1eafe3c01a 100644 --- a/tests/boundary/mcp/capabilityRemediationMcp.test.ts +++ b/tests/boundary/mcp/capabilityRemediationMcp.test.ts @@ -3,6 +3,7 @@ import { join } from "node:path"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import type { CallToolResult } from "@modelcontextprotocol/server"; import { afterAll, expect, it, onTestFinished } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { AnalysisProviderRegistry } from "../../../src/application/binary/AnalysisProviderRegistry.js"; import { composeBinarySession } from "../../../src/application/binary/BinarySessionComposition.js"; @@ -52,14 +53,11 @@ const discoverTools = async (environment: NodeJS.ProcessEnv) => { }; it("names the JEB discovery deadline setting instead of repeating the expired deadline", async () => { - let release!: () => void; - const gate = new Promise((resolve) => { - release = resolve; - }); + const toolListing = phaseGate(); const fixture = await startJebMcpFixture( () => null, async () => { - await gate; + await toolListing.hold(); return { tools: [] }; }, ); @@ -84,7 +82,7 @@ it("names the JEB discovery deadline setting instead of repeating the expired de ); expect(entry?.remediation).not.toContain("deadlineExpired"); } finally { - release(); + toolListing.release(); await fixture.close(); } }); diff --git a/tests/boundary/mcp/cutterCancellationMcp.test.ts b/tests/boundary/mcp/cutterCancellationMcp.test.ts index ee904541cf..2bee64e5e6 100644 --- a/tests/boundary/mcp/cutterCancellationMcp.test.ts +++ b/tests/boundary/mcp/cutterCancellationMcp.test.ts @@ -1,7 +1,7 @@ import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { McpServer } from "@modelcontextprotocol/server"; import { expect, it } from "vitest"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { chmod, rm, writeFile } from "node:fs/promises"; import { createServer, type Socket } from "node:net"; import { join } from "node:path"; @@ -23,11 +23,8 @@ import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; const CUTTER_REQUEST_DEADLINE_MS = 25_000; it("propagates MCP cancellation into an active Cutter command", async () => { - let markDispatched: (() => void) | undefined; let observedAbort = false; - const dispatched = new Promise((resolve) => { - markDispatched = resolve; - }); + const dispatch = phaseArrival(); const service = new CutterBridgeService({ listSessions: async () => ({ sessions: [], @@ -36,7 +33,7 @@ it("propagates MCP cancellation into an active Cutter command", async () => { bridge_directory_security: "private_verified", }), execute: async ({ signal }) => { - markDispatched?.(); + dispatch.arrive(); await new Promise((resolve) => { signal?.addEventListener( "abort", @@ -87,7 +84,7 @@ it("propagates MCP cancellation into an active Cutter command", async () => { }, { signal: controller.signal }, ); - await dispatched; + await dispatch.reached(request, "Cutter command dispatch"); controller.abort(); await expect(request).rejects.toThrow(/abort/iu); await expect.poll(() => observedAbort).toBe(true); @@ -97,14 +94,8 @@ it("propagates MCP cancellation into an active Cutter command", async () => { }); it("shares one cleanup proof across concurrent Cutter MCP commands without BinarySession", async () => { - let releaseProof!: () => void; - let enterProof!: () => void; - const proof = new Promise((resolve) => { - releaseProof = resolve; - }); - const entered = new Promise((resolve) => { - enterProof = resolve; - }); + // Later confirmations wait on the same held proof without arriving first. + const cleanupProof = phaseGate(); let confirmations = 0; let dispatches = 0; const service = new CutterBridgeService({ @@ -117,12 +108,11 @@ it("shares one cleanup proof across concurrent Cutter MCP commands without Binar confirmCommandCompletion: async () => { confirmations += 1; if (confirmations > 1) { - await proof; + await cleanupProof.hold(); await new Promise((resolve) => setImmediate(resolve)); return { ok: true, value: false }; } - enterProof(); - await proof; + await cleanupProof.hold(); return { ok: true, value: true }; }, execute: async ({ command }) => { @@ -168,19 +158,18 @@ it("shares one cleanup proof across concurrent Cutter MCP commands without Binar const first = call("first queued command"); const second = call("second queued command"); pending = [first, second]; - await awaitAcknowledgement( - entered, + await cleanupProof.reached( Promise.race([first, second]), "Cutter cleanup verification", ); await new Promise((resolve) => setImmediate(resolve)); - releaseProof(); + cleanupProof.release(); const results = await Promise.all([first, second]); for (const result of results) expect(result.isError).not.toBe(true); expect(confirmations).toBe(1); expect(dispatches).toBe(3); } finally { - releaseProof(); + cleanupProof.release(); await Promise.allSettled(pending); await Promise.allSettled([client.close(), server.close()]); } @@ -191,16 +180,13 @@ it("cancels active discovery sockets, stops queued probes and recovers on the sa if (process.platform !== "win32") await chmod(root, 0o700); const sockets = new Set(); let connections = 0; - let ready!: () => void; - const connected = new Promise((resolve) => { - ready = resolve; - }); + const probesConnected = phaseArrival(); const peer = createServer((socket) => { sockets.add(socket); connections++; socket.on("close", () => sockets.delete(socket)); socket.resume(); - if (connections === 8) ready(); + if (connections === 8) probesConnected.arrive(); }); await new Promise((resolve) => peer.listen(0, "127.0.0.1", resolve)); const address = peer.address(); @@ -261,7 +247,7 @@ it("cancels active discovery sockets, stops queued probes and recovers on the sa { name: "list_cutter_sessions", arguments: {} }, { signal: controller.signal }, ); - await awaitAcknowledgement(connected, request, "Cutter discovery"); + await probesConnected.reached(request, "Cutter discovery"); controller.abort(new Error("selected discovery cancellation")); await expect(request).rejects.toThrow("selected discovery cancellation"); await expect.poll(() => settled).toBe(true); diff --git a/tests/boundary/mcp/errorEvidenceLifecycleMcp.test.ts b/tests/boundary/mcp/errorEvidenceLifecycleMcp.test.ts index 85c84c1fad..a9d4d52e17 100644 --- a/tests/boundary/mcp/errorEvidenceLifecycleMcp.test.ts +++ b/tests/boundary/mcp/errorEvidenceLifecycleMcp.test.ts @@ -7,6 +7,7 @@ import { import { readFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { expect, it, vi } from "vitest"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { z } from "zod"; import { createEvidence } from "../../../src/domain/evidence.js"; @@ -19,10 +20,8 @@ import { createToolResultDelivery } from "../../../src/server/toolResult.js"; import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js"; import { createCacheProvider, - createDeferred, createTestBinarySession, } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; @@ -109,9 +108,8 @@ it("publishes an oversized validation-error reference only after an earlier rese { operation: "fixture_observation", parameters: {}, result: true }, ); expect(test.session.recordEvidence(previous).ok).toBe(true); - const entered = createDeferred(); - const release = createDeferred(); - const queued = createDeferred(); + const checkpointCleanup = phaseGate(); + const recoveryQueue = phaseArrival(); const originalClose = OwnedStagedOutput.prototype.close; const originalAdmission = test.session.withAdmittedAnalysis.bind( test.session, @@ -121,15 +119,14 @@ it("publishes an oversized validation-error reference only after an earlier rese .mockImplementation(async function (this: OwnedStagedOutput) { await originalClose.call(this); if (dirname(this.directory) === root) { - entered.resolve(); - await release.promise; + await checkpointCleanup.hold(); } }); const admission = vi .spyOn(test.session, "withAdmittedAnalysis") .mockImplementation((operationName, signal, operation) => { const admitted = originalAdmission(operationName, signal, operation); - if (operationName === invalidRequest.name) queued.resolve(); + if (operationName === invalidRequest.name) recoveryQueue.arrive(); return admitted; }); const resetting = test.client.callTool({ @@ -138,19 +135,11 @@ it("publishes an oversized validation-error reference only after an earlier rese }); let invalid: Promise | undefined; try { - await awaitAcknowledgement( - entered.promise, - resetting, - "checkpoint cleanup", - ); + await checkpointCleanup.reached(resetting, "checkpoint cleanup"); invalid = test.client.callTool(invalidRequest); - await awaitAcknowledgement( - queued.promise, - invalid, - "queued error recovery", - ); + await recoveryQueue.reached(invalid, "queued error recovery"); expect(test.session.exportEvidenceBundle().records).toEqual([previous]); - release.resolve(); + checkpointCleanup.release(); const [reset, reply] = await Promise.all([resetting, invalid]); expect(reset.isError, JSON.stringify(reset)).not.toBe(true); const id = retainedReference(reply); @@ -170,7 +159,7 @@ it("publishes an oversized validation-error reference only after an earlier rese raw_result: { content: [{ text: expect.stringContaining(invalidKey) }] }, }); } finally { - release.resolve(); + checkpointCleanup.release(); await Promise.allSettled([ resetting, ...(invalid === undefined ? [] : [invalid]), @@ -185,9 +174,8 @@ it("drains retained error publication before checkpointing a later reset", async const test = await fixture(); const root = await createTestTempDirectory("rea-error-before-reset-"); const checkpoint = join(root, "saved.json"); - const entered = createDeferred(); - const release = createDeferred(); - const resettingEntered = createDeferred(); + const errorPublication = phaseGate(); + const resetAdmission = phaseArrival(); const originalSend = InMemoryTransport.prototype.send; const originalReset = test.session.resetInvestigation.bind(test.session); let held = false; @@ -205,8 +193,7 @@ it("drains retained error publication before checkpointing a later reset", async message.result.isError === true ) { held = true; - entered.resolve(); - await release.promise; + await errorPublication.hold(); } await originalSend.call(this, message, options); }); @@ -214,24 +201,20 @@ it("drains retained error publication before checkpointing a later reset", async .spyOn(test.session, "resetInvestigation") .mockImplementation((options) => { const resetting = originalReset(options); - resettingEntered.resolve(); + resetAdmission.arrive(); return resetting; }); const invalid = test.client.callTool(invalidRequest); let resetting: Promise | undefined; try { - await awaitAcknowledgement(entered.promise, invalid, "error publication"); + await errorPublication.reached(invalid, "error publication"); expect(test.session.exportEvidenceBundle().records).toHaveLength(1); resetting = test.client.callTool({ name: "reset_investigation", arguments: { save_path: checkpoint }, }); - await awaitAcknowledgement( - resettingEntered.promise, - resetting, - "later reset admission", - ); - release.resolve(); + await resetAdmission.reached(resetting, "later reset admission"); + errorPublication.release(); const [reply, cleared] = await Promise.all([invalid, resetting]); const id = retainedReference(reply); expect(cleared.isError, JSON.stringify(cleared)).not.toBe(true); @@ -240,7 +223,7 @@ it("drains retained error publication before checkpointing a later reset", async expect(saved.records[0]).toMatchObject({ evidence_id: id }); expect(test.session.exportEvidenceBundle().records).toEqual([]); } finally { - release.resolve(); + errorPublication.release(); await Promise.allSettled([ invalid, ...(resetting === undefined ? [] : [resetting]), @@ -271,10 +254,9 @@ it("cancels queued SDK error recovery before it can write into the next investig const test = await fixture(); const root = await createTestTempDirectory("rea-error-reset-cancellation-"); const checkpoint = join(root, "saved.json"); - const entered = createDeferred(); - const release = createDeferred(); - const queued = createDeferred(); - const cancelled = createDeferred(); + const checkpointCleanup = phaseGate(); + const recoveryQueue = phaseArrival(); + const recoveryCancellation = phaseArrival(); const originalClose = OwnedStagedOutput.prototype.close; const originalAdmission = test.session.withAdmittedAnalysis.bind( test.session, @@ -284,8 +266,7 @@ it("cancels queued SDK error recovery before it can write into the next investig .mockImplementation(async function (this: OwnedStagedOutput) { await originalClose.call(this); if (dirname(this.directory) === root) { - entered.resolve(); - await release.promise; + await checkpointCleanup.hold(); } }); const admission = vi @@ -293,10 +274,10 @@ it("cancels queued SDK error recovery before it can write into the next investig .mockImplementation((operationName, signal, operation) => { const admitted = originalAdmission(operationName, signal, operation); if (operationName === invalidRequest.name) { - signal?.addEventListener("abort", () => cancelled.resolve(), { + signal?.addEventListener("abort", () => recoveryCancellation.arrive(), { once: true, }); - queued.resolve(); + recoveryQueue.arrive(); } return admitted; }); @@ -307,25 +288,16 @@ it("cancels queued SDK error recovery before it can write into the next investig }); let invalid: Promise | undefined; try { - await awaitAcknowledgement( - entered.promise, - resetting, - "checkpoint cleanup", - ); + await checkpointCleanup.reached(resetting, "checkpoint cleanup"); invalid = test.client .callTool(invalidRequest, { signal: controller.signal }) .then( (reply) => reply, (cause: unknown) => cause, ); - await awaitAcknowledgement( - queued.promise, - invalid, - "queued cancellable recovery", - ); + await recoveryQueue.reached(invalid, "queued cancellable recovery"); controller.abort(new Error("Caller cancelled queued validation recovery")); - await awaitAcknowledgement( - cancelled.promise, + await recoveryCancellation.reached( test.client.ping(), "transport cancellation notification", ); @@ -334,7 +306,7 @@ it("cancels queued SDK error recovery before it can write into the next investig "Caller cancelled queued validation recovery", ), }); - release.resolve(); + checkpointCleanup.release(); expect((await resetting).isError).not.toBe(true); // A public read after reset confirms the new investigation has no late write. const current = await test.client.callTool({ @@ -346,7 +318,7 @@ it("cancels queued SDK error recovery before it can write into the next investig expect((await readBundle(checkpoint)).records).toEqual([]); } finally { controller.abort(); - release.resolve(); + checkpointCleanup.release(); await Promise.allSettled([ resetting, ...(invalid === undefined ? [] : [invalid]), @@ -414,9 +386,8 @@ it.each(["handler throws", "output fails validation"] as const)( it("waits for handler cleanup when cancellation suppresses its unsent SDK reply", async () => { const fixture = customFixture(); const record = authoredRecord(); - const entered = createDeferred(); - const cleanupEntered = createDeferred(); - const release = createDeferred(); + const handlerEntry = phaseArrival(); + const handlerCleanup = phaseGate(); fixture.server.registerTool( "fixture_publication", { inputSchema: z.strictObject({}) }, @@ -437,15 +408,14 @@ it("waits for handler cleanup when cancellation suppresses its unsent SDK reply" ); for (let index = 0; index <= requestId; index += 1) await context.mcpReq.send({ method: "ping" }); - entered.resolve(); + handlerEntry.arrive(); await new Promise((resolve) => context.mcpReq.signal.addEventListener("abort", () => resolve(), { once: true, }), ); } finally { - cleanupEntered.resolve(); - await release.promise; + await handlerCleanup.hold(); } return null; }, @@ -458,13 +428,13 @@ it("waits for handler cleanup when cancellation suppresses its unsent SDK reply" const test = await fixture.connect(); const root = await createTestTempDirectory("rea-cancelled-handler-cleanup-"); const path = join(root, "saved.json"); - const resetEntered = createDeferred(); + const resetAdmission = phaseArrival(); const originalReset = test.session.resetInvestigation.bind(test.session); const reset = vi .spyOn(test.session, "resetInvestigation") .mockImplementation((options) => { const resetting = originalReset(options); - resetEntered.resolve(); + resetAdmission.arrive(); return resetting; }); const controller = new AbortController(); @@ -479,14 +449,9 @@ it("waits for handler cleanup when cancellation suppresses its unsent SDK reply" ); let resetting: Promise | undefined; try { - await awaitAcknowledgement( - entered.promise, - operation, - "fixture handler admission", - ); + await handlerEntry.reached(operation, "fixture handler admission"); controller.abort(new Error("Cancel before handler cleanup")); - await awaitAcknowledgement( - cleanupEntered.promise, + await handlerCleanup.reached( test.client.ping(), "cancelled handler cleanup", ); @@ -494,19 +459,15 @@ it("waits for handler cleanup when cancellation suppresses its unsent SDK reply" name: "reset_investigation", arguments: { save_path: path }, }); - await awaitAcknowledgement( - resetEntered.promise, - resetting, - "reset after suppressed reply", - ); + await resetAdmission.reached(resetting, "reset after suppressed reply"); expect(test.session.exportEvidenceBundle().records).toEqual([record]); - release.resolve(); + handlerCleanup.release(); expect((await resetting).isError).not.toBe(true); expect((await readBundle(path)).records).toEqual([record]); expect(test.session.exportEvidenceBundle().records).toEqual([]); } finally { controller.abort(); - release.resolve(); + handlerCleanup.release(); await Promise.allSettled([ operation, ...(resetting === undefined ? [] : [resetting]), diff --git a/tests/boundary/mcp/evidenceImportCancellation.test.ts b/tests/boundary/mcp/evidenceImportCancellation.test.ts index 0ba700cc6b..10492ff00f 100644 --- a/tests/boundary/mcp/evidenceImportCancellation.test.ts +++ b/tests/boundary/mcp/evidenceImportCancellation.test.ts @@ -3,6 +3,7 @@ import type { ServerContext, ToolCallback } from "@modelcontextprotocol/server"; import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect, it, onTestFinished, vi } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; import { createEvidence } from "../../../src/domain/evidence.js"; import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js"; @@ -134,16 +135,13 @@ it("keeps the complete session unchanged after SDK import cancellation and permi expect(unknown.isError, JSON.stringify(unknown)).not.toBe(true); const before = session.exportEvidenceBundle(); - let resolveDispatched: (() => void) | undefined; - const dispatched = new Promise((resolve) => { - resolveDispatched = resolve; - }); + const dispatch = phaseArrival(); const send = clientTransport.send.bind(clientTransport); vi.spyOn(clientTransport, "send").mockImplementation( async (message, ...args) => { await send(message, ...args); if ("method" in message && message.method === "tools/call") - resolveDispatched?.(); + dispatch.arrive(); }, ); let resolveCompleted: (() => void) | undefined; @@ -171,7 +169,7 @@ it("keeps the complete session unchanged after SDK import cancellation and permi () => "completed", (error: unknown) => error, ); - await dispatched; + await dispatch.reached(cancellation, "import_evidence_bundle dispatch"); // The real SDK ping completes while the dispatched file reader awaits I/O. await client.ping(); controller.abort(new Error("SDK import cancellation verification")); diff --git a/tests/boundary/mcp/evidenceImportLifecycle.test.ts b/tests/boundary/mcp/evidenceImportLifecycle.test.ts index 68f967603b..bc70f3d73d 100644 --- a/tests/boundary/mcp/evidenceImportLifecycle.test.ts +++ b/tests/boundary/mcp/evidenceImportLifecycle.test.ts @@ -2,15 +2,13 @@ import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect, it, onTestFinished, vi } from "vitest"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { createEvidence } from "../../../src/domain/evidence.js"; import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js"; import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js"; import { createServer } from "../../../src/server/createServer.js"; -import { - createDeferred, - createTestBinarySession, -} from "../../fixtures/binarySession.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; const connectImportSession = async () => { @@ -23,22 +21,20 @@ const connectImportSession = async () => { name: "evidence-import-lifecycle", version: "1", }); - const readCompleted = createDeferred(); - const releaseRead = createDeferred(); + const importRead = phaseGate(); const originalFileClose = OwnedFileHandle.prototype.close; vi.spyOn(OwnedFileHandle.prototype, "close").mockImplementationOnce( async function (this: OwnedFileHandle) { await originalFileClose.call(this); - readCompleted.resolve(); - await releaseRead.promise; + await importRead.hold(); }, ); - const closeStarted = createDeferred(); + const closeStart = phaseArrival(); const originalSessionClose = session.close.bind(session); const events: string[] = []; vi.spyOn(session, "close").mockImplementation((...args) => { const closing = originalSessionClose(...args); - closeStarted.resolve(); + closeStart.arrive(); return closing.then((result) => { events.push("close"); return result; @@ -51,7 +47,7 @@ const connectImportSession = async () => { return imported; }); onTestFinished(async () => { - releaseRead.resolve(); + importRead.release(); vi.restoreAllMocks(); await client.close(); await server.close(); @@ -59,7 +55,7 @@ const connectImportSession = async () => { }); const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); - const laterImportDispatched = createDeferred(); + const laterImportDispatch = phaseArrival(); let importsDispatched = 0; const send = clientTransport.send.bind(clientTransport); vi.spyOn(clientTransport, "send").mockImplementation( @@ -71,7 +67,7 @@ const connectImportSession = async () => { message.params?.name === "import_evidence_bundle" ) { importsDispatched += 1; - if (importsDispatched === 2) laterImportDispatched.resolve(); + if (importsDispatched === 2) laterImportDispatch.arrive(); } }, ); @@ -95,24 +91,23 @@ const connectImportSession = async () => { session, events, importBundle, - readCompleted: readCompleted.promise, - closeStarted: closeStarted.promise, - laterImportDispatched: laterImportDispatched.promise, - releaseRead: () => releaseRead.resolve(), + importRead, + closeStart, + laterImportDispatch, }; }; it("drains a file import before close_binary releases the engine and retains its records", async () => { const fixture = await connectImportSession(); const importing = fixture.importBundle("before_close"); - await fixture.readCompleted; + await fixture.importRead.reached(importing, "import file read"); const closing = fixture.client.callTool({ name: "close_binary", arguments: {}, }); - await fixture.closeStarted; + await fixture.closeStart.reached(closing, "close_binary start"); await fixture.client.ping(); - fixture.releaseRead(); + fixture.importRead.release(); const [imported, closed] = await Promise.all([importing, closing]); expect(imported.isError, JSON.stringify(imported)).not.toBe(true); @@ -133,16 +128,16 @@ it("drains a file import before close_binary releases the engine and retains its it("admits a later import after close_binary while retaining the earlier bundle", async () => { const fixture = await connectImportSession(); const earlier = fixture.importBundle("before_close"); - await fixture.readCompleted; + await fixture.importRead.reached(earlier, "import file read"); const closing = fixture.client.callTool({ name: "close_binary", arguments: {}, }); - await fixture.closeStarted; + await fixture.closeStart.reached(closing, "close_binary start"); const later = fixture.importBundle("after_close"); - await fixture.laterImportDispatched; + await fixture.laterImportDispatch.reached(later, "later import dispatch"); await fixture.client.ping(); - fixture.releaseRead(); + fixture.importRead.release(); const results = await Promise.all([earlier, closing, later]); for (const result of results) diff --git a/tests/boundary/mcp/evmInterfaceMcp.test.ts b/tests/boundary/mcp/evmInterfaceMcp.test.ts index e815c43c63..9505a7ba28 100644 --- a/tests/boundary/mcp/evmInterfaceMcp.test.ts +++ b/tests/boundary/mcp/evmInterfaceMcp.test.ts @@ -2,7 +2,6 @@ import { canonicalOutputSchema, withCanonicalOutputSchema, } from "../../fixtures/canonicalOutputSchema.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { advertisedMcpToolSchemas, assertRecordedMcpEvidence, @@ -10,6 +9,7 @@ import { import { createHash } from "node:crypto"; import { Ajv2020 } from "ajv/dist/2020.js"; import { expect, it, onTestFinished, vi } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { EvmInterfaceService } from "../../../src/application/evm/EvmInterfaceService.js"; import { WasmArtifactService } from "../../../src/application/wasm/WasmArtifactService.js"; import { toolContract } from "../../../src/contracts/toolContracts.js"; @@ -286,7 +286,7 @@ mcpTest( ); it("settles the admitted EVM operation after SDK cancellation and accepts a subsequent request", async () => { - const entered = createDeferred(); + const evmInspection = phaseArrival(); const stopped = createDeferred(); let invocations = 0; const harness = await createApplicationMcpHarness({ @@ -302,7 +302,7 @@ it("settles the admitted EVM operation after SDK cancellation and accepts a subs else signal.addEventListener("abort", () => resolve(), { once: true }); }); - entered.resolve(); + evmInspection.arrive(); await aborted; stopped.resolve(); return err(new AnalysisCancelledError("inspect_evm_interface")); @@ -323,7 +323,7 @@ it("settles the admitted EVM operation after SDK cancellation and accepts a subs (error: unknown) => error, ); onTestFinished(() => controller.abort()); - await awaitAcknowledgement(entered.promise, cancellation, "EVM inspection"); + await evmInspection.reached(cancellation, "EVM inspection"); controller.abort(new Error("SDK EVM cancellation verification")); expect(await cancellation).toMatchObject({ message: expect.stringContaining("SDK EVM cancellation verification"), diff --git a/tests/boundary/mcp/fridaLifecycleMcp.test.ts b/tests/boundary/mcp/fridaLifecycleMcp.test.ts index a1eb188c40..bd52116a90 100644 --- a/tests/boundary/mcp/fridaLifecycleMcp.test.ts +++ b/tests/boundary/mcp/fridaLifecycleMcp.test.ts @@ -13,7 +13,6 @@ import type { Session, } from "frida"; import { expect, it, onTestFinished, vi } from "vitest"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { FridaScriptLoadCancelledError } from "../../../src/ports/frida/FridaInstrumentationPort.js"; import type { @@ -44,27 +43,9 @@ import { ToolResultDelivery } from "../../../src/server/ToolResultDelivery.js"; import { createToolResultDelivery } from "../../../src/server/toolResult.js"; import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { waitFor } from "../../support/testWait.js"; -const gate = () => { - let markEntered = () => {}; - let release = () => {}; - const entered = new Promise((resolve) => { - markEntered = resolve; - }); - const released = new Promise((resolve) => { - release = resolve; - }); - return { - entered, - release, - async wait() { - markEntered(); - await released; - }, - }; -}; - const nativeFixture = () => { const created: string[] = []; const loaded: string[] = []; @@ -316,9 +297,9 @@ it.each(["attached", "during-resume", "after-resume"] as const)( "preserves observed detachment through resume settlement: %s", async (timing) => { const fixture = await connectedFixture(); - const held = gate(); - onTestFinished(held.release); - fixture.controls.resume = held.wait; + const held = phaseGate(); + onTestFinished(() => held.release()); + fixture.controls.resume = () => held.hold(); const id = await fixture.start(); const state = async () => { const result = await fixture.client.callTool({ @@ -335,11 +316,7 @@ it.each(["attached", "during-resume", "after-resume"] as const)( name: "resume_frida_session", arguments: { session_id: id }, }); - await awaitAcknowledgement( - held.entered, - resuming, - "Frida operation admission", - ); + await held.reached(resuming, "Frida operation admission"); if (timing === "during-resume") fixture.markDetached(); expect(await state()).toBe( timing === "during-resume" ? "detached" : "paused", @@ -428,9 +405,9 @@ it.each([ "classifies server completion after final detach (cancel=$cancel, detachFails=$detachFails)", async ({ cancel, detachFails }) => { const fixture = await connectedFixture(); - const held = gate(); - onTestFinished(held.release); - fixture.controls.detach = held.wait; + const held = phaseGate(); + onTestFinished(() => held.release()); + fixture.controls.detach = () => held.hold(); fixture.controls.detachFailures = detachFails ? 1 : 0; let serverSignal: AbortSignal | undefined; const load = fixture.manager.loadScript.bind(fixture.manager); @@ -473,11 +450,7 @@ it.each([ (value) => ({ kind: "result" as const, value }), (cause: unknown) => ({ kind: "rejected" as const, cause }), ); - await awaitAcknowledgement( - held.entered, - pending, - "Frida operation admission", - ); + await held.reached(pending, "Frida operation admission"); expect(fixture.unloaded).toEqual(["completed-before-detach"]); if (cancel) { controller.abort(new Error("cancel during final detach")); @@ -585,10 +558,10 @@ it.each([ it("preserves the native resume failure after MCP cancellation reaches the server", async () => { const fixture = await connectedFixture(); - const held = gate(); - onTestFinished(held.release); + const held = phaseGate(); + onTestFinished(() => held.release()); fixture.controls.resume = async () => { - await held.wait(); + await held.hold(); fixture.controls.resume = async () => {}; throw new Error("native resume rejected"); }; @@ -620,11 +593,7 @@ it("preserves the native resume failure after MCP cancellation reaches the serve { signal: controller.signal }, ) .catch((cause: unknown) => cause); - await awaitAcknowledgement( - held.entered, - pending, - "Frida operation admission", - ); + await held.reached(pending, "Frida operation admission"); controller.abort(new Error("cancel pending resume")); await fixture.client.ping(); expect(serverSignal?.aborted).toBe(true); @@ -917,9 +886,9 @@ const scriptLoadFixture = async (stage: "create" | "load" = "load") => { const fixture = await connectedFixture(); const id = await fixture.start(); const original = await fixture.load(id, "original"); - const held = gate(); - onTestFinished(held.release); - fixture.controls[stage] = held.wait; + const held = phaseGate(); + onTestFinished(() => held.release()); + fixture.controls[stage] = () => held.hold(); return { fixture, id, original, held }; }; @@ -1048,11 +1017,7 @@ it.each(["load", "resume", "unload"] as const)( original.structuredContent, ).normalized_result.script_id; const first = fixture.load(id, "blocking"); - await awaitAcknowledgement( - held.entered, - first, - "Frida operation admission", - ); + await held.reached(first, "Frida operation admission"); const controller = new AbortController(); const cancelled = operation === "load" @@ -1096,11 +1061,7 @@ it.each(["create", "load"] as const)( const rejected = expect(cancelled).rejects.toThrow( "cancel native operation", ); - await awaitAcknowledgement( - held.entered, - cancelled, - "Frida operation admission", - ); + await held.reached(cancelled, "Frida operation admission"); controller.abort(new Error("cancel native operation")); await fixture.client.ping(); await rejected; @@ -1135,18 +1096,14 @@ it.each(["create", "load"] as const)( it("retains cancellation source facts without claiming native creation when no script handle returns", async () => { const { fixture, id, held } = await scriptLoadFixture("create"); fixture.controls.create = async () => { - await held.wait(); + await held.hold(); throw new Error("native create rejected"); }; const controller = new AbortController(); const loading = fixture .load(id, "no-returned-handle", controller.signal) .catch((cause: unknown) => cause); - await awaitAcknowledgement( - held.entered, - loading, - "Frida operation admission", - ); + await held.reached(loading, "Frida operation admission"); controller.abort(new Error("cancel while creating")); await fixture.client.ping(); held.release(); @@ -1192,11 +1149,7 @@ it("retains original malformed file identity and decoded representation through { signal: controller.signal }, ) .catch((cause: unknown) => cause); - await awaitAcknowledgement( - held.entered, - loading, - "Frida operation admission", - ); + await held.reached(loading, "Frida operation admission"); controller.abort(new Error("cancel file load")); await fixture.client.ping(); held.release(); @@ -1265,11 +1218,7 @@ it.each([ (value) => ({ kind: "result" as const, value }), (cause: unknown) => ({ kind: "rejected" as const, cause }), ); - await awaitAcknowledgement( - held.entered, - loading, - "Frida operation admission", - ); + await held.reached(loading, "Frida operation admission"); if (cancel) { controller.abort(new Error("cancel before native rejection")); await fixture.client.ping(); @@ -1328,9 +1277,9 @@ it.each([ it("awaits an admitted attach on server shutdown and retries failed native cleanup", async () => { const fixture = await connectedFixture(); - const held = gate(); - onTestFinished(held.release); - fixture.controls.attach = held.wait; + const held = phaseGate(); + onTestFinished(() => held.release()); + fixture.controls.attach = () => held.hold(); fixture.controls.detachFailures = 1; const starting = fixture.client .callTool({ @@ -1342,11 +1291,7 @@ it("awaits an admitted attach on server shutdown and retries failed native clean }, }) .catch(() => undefined); - await awaitAcknowledgement( - held.entered, - starting, - "Frida operation admission", - ); + await held.reached(starting, "Frida operation admission"); const { closing } = await pendingShutdown(fixture.server); expect(fixture.controls.detachCalls).toBe(0); held.release(); @@ -1369,9 +1314,9 @@ it("awaits an admitted attach on server shutdown and retries failed native clean it("drains remote discovery before shutdown and retains failed connection cleanup", async () => { const fixture = await connectedFixture(); - const held = gate(); - onTestFinished(held.release); - fixture.controls.discover = held.wait; + const held = phaseGate(); + onTestFinished(() => held.release()); + fixture.controls.discover = () => held.hold(); fixture.controls.removalFailures = 2; const discovering = fixture.client .callTool({ @@ -1381,11 +1326,7 @@ it("drains remote discovery before shutdown and retains failed connection cleanu }, }) .catch(() => undefined); - await awaitAcknowledgement( - held.entered, - discovering, - "Frida operation admission", - ); + await held.reached(discovering, "Frida operation admission"); const { closing } = await pendingShutdown(fixture.server); held.release(); expect(await closing).toBeInstanceOf(AggregateError); @@ -1405,11 +1346,7 @@ it.each(["create", "load"] as const)( const rejected = expect(cancelled).rejects.toThrow( "cancel retained script", ); - await awaitAcknowledgement( - held.entered, - cancelled, - "Frida operation admission", - ); + await held.reached(cancelled, "Frida operation admission"); controller.abort(new Error("cancel retained script")); await fixture.client.ping(); await rejected; @@ -1462,11 +1399,7 @@ it.each([0, 1])( const rejected = expect(loading).rejects.toThrow( "cancel before queued resume", ); - await awaitAcknowledgement( - held.entered, - loading, - "Frida operation admission", - ); + await held.reached(loading, "Frida operation admission"); const resume = () => fixture.client.callTool({ name: "resume_frida_session", @@ -1524,7 +1457,7 @@ it.each([0, 1, 2, 3, 4, 8])( }; const loading = fixture.load(id, "settling-native", controller.signal); const observed = loading.catch(() => undefined); - await awaitAcknowledgement(held.entered, loading, "Frida script load"); + await held.reached(loading, "Frida script load"); const resuming = fixture.client.callTool({ name: "resume_frida_session", arguments: { session_id: id }, diff --git a/tests/boundary/mcp/fridaMcp.test.ts b/tests/boundary/mcp/fridaMcp.test.ts index 083b6aeb21..3345e75835 100644 --- a/tests/boundary/mcp/fridaMcp.test.ts +++ b/tests/boundary/mcp/fridaMcp.test.ts @@ -7,6 +7,7 @@ import { Ajv2020 } from "ajv/dist/2020.js"; import type { AnySchema } from "ajv"; import type { DeviceManager } from "frida"; import { afterAll, expect, it, onTestFinished } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import type { FridaInstrumentationPort } from "../../../src/ports/frida/FridaInstrumentationPort.js"; import { toolContract } from "../../../src/contracts/toolContracts.js"; @@ -616,22 +617,14 @@ it("retains cancellation Evidence after the MCP client stops waiting", async () const session = createTestBinarySession(() => { throw new Error("Binary provider must not start"); }); - let finishLoad: (() => void) | undefined; - const loadGate = new Promise((resolve) => { - finishLoad = resolve; - }); - let markLoadStarted: (() => void) | undefined; - const loadStarted = new Promise((resolve) => { - markLoadStarted = resolve; - }); + const scriptLoad = phaseGate(); let markSessionClosed: (() => void) | undefined; const sessionClosed = new Promise((resolve) => { markSessionClosed = resolve; }); const provider = createFridaTestProvider({ async loadScript() { - markLoadStarted?.(); - await loadGate; + await scriptLoad.hold(); return { ok: true, value: { @@ -673,7 +666,7 @@ it("retains cancellation Evidence after the MCP client stops waiting", async () ); const controller = new AbortController(); onTestFinished(async () => { - finishLoad?.(); + scriptLoad.release(); controller.abort(); await client.close(); await server.close(); @@ -697,9 +690,9 @@ it("retains cancellation Evidence after the MCP client stops waiting", async () }, { signal: controller.signal }, ); - await loadStarted; + await scriptLoad.reached(call, "Frida script load"); controller.abort(new Error("cancel Frida observation")); - finishLoad?.(); + scriptLoad.release(); await expect(call).rejects.toThrow("cancel Frida observation"); await sessionClosed; await client.ping(); diff --git a/tests/boundary/mcp/gdbRetirementCancellation.test.ts b/tests/boundary/mcp/gdbRetirementCancellation.test.ts index 3f79bff61b..3162e60d03 100644 --- a/tests/boundary/mcp/gdbRetirementCancellation.test.ts +++ b/tests/boundary/mcp/gdbRetirementCancellation.test.ts @@ -1,5 +1,6 @@ import type { CallToolResult, McpServer } from "@modelcontextprotocol/server"; import { expect, it, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { registerGdbTools, type GdbToolManager, @@ -18,10 +19,8 @@ import { } from "../../../src/ports/AnalysisProvider.js"; import { CompositeProvider } from "../../../src/application/binary/CompositeProvider.js"; import { runWithExternalMutationAdmission } from "../../../src/server/externalMutationAdmission.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { createBinarySessionTargets, - createDeferred, createTestBinarySession, } from "../../fixtures/binarySession.js"; import { releaseOwnedCleanup } from "../../support/cleanupRelease.js"; @@ -29,8 +28,7 @@ import { releaseOwnedCleanup } from "../../support/cleanupRelease.js"; it("compares cancellation before dispatch, during retirement, and an uncancelled control", async () => { for (const mode of ["pre-aborted", "during-retirement", "control"] as const) { const [target] = await createBinarySessionTargets(); - const entered = createDeferred(); - const released = createDeferred(); + const sessionRetirement = phaseGate(); let closes = 0; const session = createTestBinarySession( () => @@ -38,8 +36,7 @@ it("compares cancellation before dispatch, during retirement, and an uncancelled execute: async () => ok({ operation: "health", value: null }), close: async () => { closes++; - entered.resolve(); - await released.promise; + await sessionRetirement.hold(); return ok(null); }, }) as never, @@ -88,16 +85,12 @@ it("compares cancellation before dispatch, during retirement, and an uncancelled { mcpReq: { signal: controller.signal } }, ); if (mode !== "pre-aborted") { - await awaitAcknowledgement( - entered.promise, - pending, - "session retirement", - ); + await sessionRetirement.reached(pending, "session retirement"); expect(execute).toHaveBeenCalledTimes(1); expect(record).not.toHaveBeenCalled(); if (mode === "during-retirement") controller.abort(reason); } - released.resolve(); + sessionRetirement.release(); const result = await pending; const body = result.structuredContent as any; const observation = { @@ -126,7 +119,7 @@ it("compares cancellation before dispatch, during retirement, and an uncancelled if (mode === "during-retirement") expect(record.mock.calls[0]?.[0]).toEqual(evidence); } finally { - released.resolve(); + sessionRetirement.release(); await session.close(); } } @@ -136,8 +129,7 @@ it.each(["completed", "failed"] as const)( "preserves a %s command and cleanup ownership when cancellation overlaps failed retirement", async (mode) => { const [target] = await createBinarySessionTargets(); - const entered = createDeferred(); - const released = createDeferred(); + const failedSessionRetirement = phaseGate(); const cleanup = new ProviderCleanupError("fixture", ["document"], {}); let closes = 0; const session = createTestBinarySession( @@ -146,8 +138,7 @@ it.each(["completed", "failed"] as const)( execute: async () => ok({ operation: "health", value: null }), close: async () => { if (++closes === 1) { - entered.resolve(); - await released.promise; + await failedSessionRetirement.hold(); return err(cleanup); } return ok(null); @@ -175,13 +166,12 @@ it.each(["completed", "failed"] as const)( async () => (mode === "completed" ? ok(evidence) : err(commandFailure)), (value) => value, ); - await awaitAcknowledgement( - entered.promise, + await failedSessionRetirement.reached( pending, "failed session retirement", ); controller.abort(reason); - released.resolve(); + failedSessionRetirement.release(); const result = await pending; if (result.ok) throw new Error("Expected a failure"); expect(result.error.cleanupIncomplete).toBe(true); @@ -196,7 +186,7 @@ it.each(["completed", "failed"] as const)( expect((await session.close()).ok).toBe(true); expect(result.error.cleanupIncomplete).toBe(false); } finally { - released.resolve(); + failedSessionRetirement.release(); await session.close(); } }, @@ -206,15 +196,13 @@ it.each(["started", "failed"] as const)( "keeps a %s mutation outcome when successful retirement is cancelled", async (mode) => { const [target] = await createBinarySessionTargets(); - const entered = createDeferred(); - const released = createDeferred(); + const sessionRetirement = phaseGate(); const session = createTestBinarySession( () => ({ execute: async () => ok({ operation: "health", value: null }), close: async () => { - entered.resolve(); - await released.promise; + await sessionRetirement.hold(); return ok(null); }, }) as never, @@ -234,13 +222,9 @@ it.each(["started", "failed"] as const)( undefined, (value) => ({ session_id: value.session_id }), ); - await awaitAcknowledgement( - entered.promise, - pending, - "session retirement", - ); + await sessionRetirement.reached(pending, "session retirement"); controller.abort(reason); - released.resolve(); + sessionRetirement.release(); const result = await pending; if (result.ok) throw new Error("Expected a failure"); if (mode === "started") { @@ -254,7 +238,7 @@ it.each(["started", "failed"] as const)( ).toBe(true); } } finally { - released.resolve(); + sessionRetirement.release(); await session.close(); } }, diff --git a/tests/boundary/mcp/ghidraStartupCancellationMcp.test.ts b/tests/boundary/mcp/ghidraStartupCancellationMcp.test.ts index 55e10d1b90..b8560a2454 100644 --- a/tests/boundary/mcp/ghidraStartupCancellationMcp.test.ts +++ b/tests/boundary/mcp/ghidraStartupCancellationMcp.test.ts @@ -2,6 +2,7 @@ import { access } from "node:fs/promises"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { expect, it } from "vitest"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { AnalysisProviderRegistry } from "../../../src/application/binary/AnalysisProviderRegistry.js"; import { composeBinarySession } from "../../../src/application/binary/BinarySessionComposition.js"; @@ -12,8 +13,6 @@ import { GhidraProvider } from "../../../src/ghidra/GhidraProvider.js"; import type { GhidraProviderClientFactory } from "../../../src/ghidra/GhidraProviderClient.js"; import { silentLogger } from "../../../src/logger.js"; import { createServer } from "../../../src/server/createServer.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { GhidraFixtureLauncher } from "../providers/ghidra/ghidraClient.fixture.js"; import { waitFor } from "../../support/testWait.js"; @@ -21,9 +20,8 @@ import { waitFor } from "../../support/testWait.js"; it.each([0, 1])( "releases cancelled MCP startup caller %s while its peer completes and stays warm", async (cancelledIndex) => { - const entered = createDeferred(); - const admitted = [createDeferred(), createDeferred()]; - const gate = createDeferred(); + const ghidraStartup = phaseGate(); + const admitted = [phaseArrival(), phaseArrival()]; const fixture = new GhidraFixtureLauncher(); const roots = fixture.runtimeRoots; const children = fixture.processes; @@ -40,8 +38,7 @@ it.each([0, 1])( launcher: { async launch(launch, launchOptions) { producerSignal = launchOptions?.signal; - entered.resolve(); - await gate.promise; + await ghidraStartup.hold(); return fixture.launch(launch); }, }, @@ -51,7 +48,7 @@ it.each([0, 1])( start: (signal, progress) => { const index = startCount++; const pending = raw.start(signal, progress); - admitted[index]?.resolve(); + admitted[index]?.arrive(); return pending.then((result) => { startResults[index] = result; return result; @@ -111,17 +108,9 @@ it.each([0, 1])( (cause: unknown) => ({ ok: false as const, cause }), ), ); - await awaitAcknowledgement( - admitted[index]!.promise, - calls[index]!, - "MCP caller admission", - ); + await admitted[index]!.reached(calls[index]!, "MCP caller admission"); } - await awaitAcknowledgement( - entered.promise, - Promise.race(calls), - "Ghidra startup", - ); + await ghidraStartup.reached(Promise.race(calls), "Ghidra startup"); controllers[cancelledIndex]?.abort(); await waitFor(() => expect(startResults[cancelledIndex]).toMatchObject({ @@ -133,7 +122,7 @@ it.each([0, 1])( expect(producerSignal?.aborted).toBe(false); expect(children).toHaveLength(0); expect(queryCount).toBe(0); - gate.resolve(); + ghidraStartup.release(); const staying = await calls[1 - cancelledIndex]; if (staying === undefined || !staying.ok) throw new Error("Live MCP peer did not complete", { cause: staying }); @@ -147,7 +136,7 @@ it.each([0, 1])( expect(children).toHaveLength(1); } finally { for (const controller of controllers) controller.abort(); - gate.resolve(); + ghidraStartup.release(); await Promise.allSettled(calls); await mcp.close(); await server.close(); diff --git a/tests/boundary/mcp/goBinaryMcp.test.ts b/tests/boundary/mcp/goBinaryMcp.test.ts index 66c057fd89..8132eb51ae 100644 --- a/tests/boundary/mcp/goBinaryMcp.test.ts +++ b/tests/boundary/mcp/goBinaryMcp.test.ts @@ -8,6 +8,7 @@ import { Ajv2020 } from "ajv/dist/2020.js"; import { mkdir, symlink, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect } from "vitest"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; import { readAnalysisSnapshot } from "../../../src/application/binary/AnalysisSnapshotFiles.js"; import { GoBinaryService } from "../../../src/application/go/GoBinaryService.js"; @@ -21,7 +22,6 @@ import { GoBinaryProvider } from "../../../src/go/GoBinaryProvider.js"; import { createServer } from "../../../src/server/createServer.js"; import { createCacheProvider, - createDeferred, createTestBinarySession, } from "../../fixtures/binarySession.js"; import { @@ -31,7 +31,6 @@ import { createGoBinaryPathFailureFixture, } from "../../fixtures/go/image.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { mcpTest } from "../../support/mcp/mcpFixture.js"; @@ -68,9 +67,8 @@ mcpTest( const fixture = createGoBinaryFixture({ bits: 32, byteOrder: "big" }); fixture.bytes.writeUInt16BE(8, 18); // ELF EM_MIPS. await writeFile(path, fixture.bytes); - const entered = createDeferred(); - const release = createDeferred(); - const closeStarted = createDeferred(); + const goInspection = phaseGate(); + const inspectionClose = phaseArrival(); const provider = new GoBinaryProvider(); const session = createTestBinarySession(createCacheProvider([])); const service = new GoBinaryService({ @@ -78,8 +76,7 @@ mcpTest( identity: provider.identity, inspect: async (input, options) => { const result = await provider.inspect(input, options); - entered.resolve(); - await release.promise; + await goInspection.hold(); return result; }, }); @@ -95,24 +92,20 @@ mcpTest( }); expect(opened.isError, JSON.stringify(opened.content)).not.toBe(true); client.setNotificationHandler("notifications/progress", () => { - closeStarted.resolve(); + inspectionClose.arrive(); }); inspection = client.callTool({ name: "inspect_go_binary", arguments: { path }, }); - await awaitAcknowledgement(entered.promise, inspection, "Go inspection"); + await goInspection.reached(inspection, "Go inspection"); closing = client.callTool({ name: "close_binary", arguments: { snapshot_path: snapshotPath }, _meta: { progressToken: "go-close-race" }, }); - await awaitAcknowledgement( - closeStarted.promise, - closing, - "Go snapshot close", - ); - release.resolve(); + await inspectionClose.reached(closing, "Go snapshot close"); + goInspection.release(); const inspected = await inspection; expect(inspected.isError, JSON.stringify(inspected.content)).not.toBe( true, @@ -139,7 +132,7 @@ mcpTest( expect(reset.isError, JSON.stringify(reset.content)).not.toBe(true); expect(session.evidenceById(evidence.evidence_id)).toBeUndefined(); }, [ - () => release.resolve(), + () => goInspection.release(), async () => { await Promise.allSettled([ ...(inspection === undefined ? [] : [inspection]), diff --git a/tests/boundary/mcp/investigationAnalysisMcp.test.ts b/tests/boundary/mcp/investigationAnalysisMcp.test.ts index 99cc4d74fc..f1da542dee 100644 --- a/tests/boundary/mcp/investigationAnalysisMcp.test.ts +++ b/tests/boundary/mcp/investigationAnalysisMcp.test.ts @@ -1,11 +1,10 @@ -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { parseEvidence, createEvidence } from "../../../src/domain/evidence.js"; import { ok as resultOk } from "../../../src/domain/result.js"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { expect, it } from "vitest"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { - createDeferred, createBinarySessionTargets, createTestBinarySession, } from "../../fixtures/binarySession.js"; @@ -137,9 +136,8 @@ it("keeps call-path publication ahead of close_binary record draining", async () const client = new Client({ name: "investigation-close-race", version: "1" }); const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); - const preparationReached = createDeferred(); - const closeReached = createDeferred(); - const releasePreparation = createDeferred(); + const callPathPreparation = phaseGate(); + const analysisClose = phaseArrival(); const send = serverTransport.send.bind(serverTransport); let preparationToken: string | number | undefined; serverTransport.send = async (message, options) => { @@ -157,10 +155,9 @@ it("keeps call-path publication ahead of close_binary record draining", async () if (preparationToken === undefined) { // The first request cannot advance until this notification is released. preparationToken = message.params.progressToken; - preparationReached.resolve(); - await releasePreparation.promise; + await callPathPreparation.hold(); } else if (message.params.progressToken !== preparationToken) { - closeReached.resolve(); + analysisClose.arrive(); } } }; @@ -183,11 +180,7 @@ it("keeps call-path publication ahead of close_binary record draining", async () return response; }); pending.push(request); - await awaitAcknowledgement( - preparationReached.promise, - request, - "call-path preparation", - ); + await callPathPreparation.reached(request, "call-path preparation"); let closeSettled = false; const closing = client @@ -201,14 +194,10 @@ it("keeps call-path publication ahead of close_binary record draining", async () return response; }); pending.push(closing); - await awaitAcknowledgement( - closeReached.promise, - closing, - "call-path queued close", - ); + await analysisClose.reached(closing, "call-path queued close"); expect(closeSettled).toBe(false); - releasePreparation.resolve(); + callPathPreparation.release(); const [response, closed] = await Promise.all([request, closing]); expect(response.isError, JSON.stringify(response)).not.toBe(true); expect(closed.isError, JSON.stringify(closed)).not.toBe(true); @@ -222,7 +211,7 @@ it("keeps call-path publication ahead of close_binary record draining", async () for (const source of input.functions) expect(session.hasEvidence(source.evidence_id)).toBe(true); } finally { - releasePreparation.resolve(); + callPathPreparation.release(); await Promise.allSettled(pending); await close(session, server, client); } diff --git a/tests/boundary/mcp/investigationLifecycleMcp.test.ts b/tests/boundary/mcp/investigationLifecycleMcp.test.ts index 05034db27a..e139404725 100644 --- a/tests/boundary/mcp/investigationLifecycleMcp.test.ts +++ b/tests/boundary/mcp/investigationLifecycleMcp.test.ts @@ -3,6 +3,7 @@ import type { CallToolResult } from "@modelcontextprotocol/server"; import { access, readFile, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { expect, it, onTestFinished, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { z } from "zod"; import type { AnalysisClient } from "../../../src/ports/AnalysisProvider.js"; @@ -23,13 +24,11 @@ import { observed } from "../../fixtures/analysisExecution.js"; import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js"; import { createCacheProvider, - createDeferred, createTestBinarySession, } from "../../fixtures/binarySession.js"; import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js"; import { parseMcpEvidenceBundle } from "../../fixtures/mcpEvidenceBundle.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; // Native behavior is simulated here. The real SDK, session, ledger, source @@ -392,16 +391,14 @@ it("saves the complete history before clearing and restores it in a fresh public }); it("drains a late valid observation before saving and prevents it from entering the reset investigation", async () => { - const entered = createDeferred(); - const release = createDeferred(); + const analysisBeforeResetEntry = phaseGate(); let addressCalls = 0; const test = await fixture({ execute: async (operation) => { if (operation === "health") return observed(null); addressCalls += 1; if (addressCalls === 1) { - entered.resolve(); - await release.promise; + await analysisBeforeResetEntry.hold(); return observed("late-before-reset"); } return observed("fresh-after-reset"); @@ -414,8 +411,7 @@ it("drains a late valid observation before saving and prevents it from entering }); const pending: Promise[] = [earlier]; try { - await awaitAcknowledgement( - entered.promise, + await analysisBeforeResetEntry.reached( earlier, "analysis before reset entry", ); @@ -433,7 +429,7 @@ it("drains a late valid observation before saving and prevents it from entering pending.push(later); await test.client.ping(); expect(addressCalls).toBe(1); - release.resolve(); + analysisBeforeResetEntry.release(); const [, reset, next] = await Promise.all([earlier, resetting, later]); expect(reset.isError, JSON.stringify(reset)).not.toBe(true); expect(next.isError, JSON.stringify(next)).not.toBe(true); @@ -452,7 +448,7 @@ it("drains a late valid observation before saving and prevents it from entering expect(test.createClient).toHaveBeenCalledTimes(1); expect(test.providerClose).not.toHaveBeenCalled(); } finally { - release.resolve(); + analysisBeforeResetEntry.release(); await Promise.allSettled(pending); } }); @@ -506,8 +502,7 @@ it("preserves the investigation when SDK cancellation arrives during final save const test = await fixture(); const seeded = await seedHistory(test.client); const path = join(test.root, "cancelled-reset.json"); - const entered = createDeferred(); - const release = createDeferred(); + const resetFinalCleanupEntry = phaseGate(); const original = OwnedStagedOutput.prototype.close; let held = false; const seam = vi @@ -516,12 +511,11 @@ it("preserves the investigation when SDK cancellation arrives during final save await original.call(this); if (dirname(this.directory) === test.root && !held) { held = true; - entered.resolve(); - await release.promise; + await resetFinalCleanupEntry.hold(); } }); onTestFinished(() => { - release.resolve(); + resetFinalCleanupEntry.release(); seam.mockRestore(); }); const controller = new AbortController(); @@ -535,8 +529,7 @@ it("preserves the investigation when SDK cancellation arrives during final save (error: unknown) => error, ); try { - await awaitAcknowledgement( - entered.promise, + await resetFinalCleanupEntry.reached( resetting, "reset final cleanup entry", ); @@ -547,7 +540,7 @@ it("preserves the investigation when SDK cancellation arrives during final save message: expect.stringContaining("Caller cancelled reset"), }); await test.client.ping(); - release.resolve(); + resetFinalCleanupEntry.release(); // A later admitted read joins server settlement even when SDK cancellation // suppresses the reset reply. The published file and all records must survive. expect(await bundle(test.client)).toEqual(seeded.before); @@ -558,7 +551,7 @@ it("preserves the investigation when SDK cancellation arrives during final save (await call(test.client, "reset_investigation")).structuredContent, ).toEqual({ result: cleared(seeded.before, false) }); } finally { - release.resolve(); + resetFinalCleanupEntry.release(); await Promise.allSettled([resetting]); await test.session.withAdmittedAnalysis( "fixture_reset_settlement", @@ -574,8 +567,7 @@ it("drains admitted work before retrying process cleanup and refuses reset while const path = join(test.root, "process-cleanup-checkpoint.json"); const originalBytes = Buffer.from("caller-owned checkpoint"); await writeFile(path, originalBytes); - const entered = createDeferred(); - const release = createDeferred(); + const metadataBeforeCleanupEntry = phaseGate(); const events: string[] = []; let cleanupAllowed = false; const retainedProcessRoot = join( @@ -606,15 +598,13 @@ it("drains admitted work before retrying process cleanup and refuses reset while "fixture_metadata_before_reset", undefined, async () => { - entered.resolve(); - await release.promise; + await metadataBeforeCleanupEntry.hold(); events.push("metadata_drained"); }, ); const pending: Promise[] = [admitted]; try { - await awaitAcknowledgement( - entered.promise, + await metadataBeforeCleanupEntry.reached( admitted, "metadata before cleanup entry", ); @@ -625,7 +615,7 @@ it("drains admitted work before retrying process cleanup and refuses reset while pending.push(resetting); await test.client.ping(); expect(retry).not.toHaveBeenCalled(); - release.resolve(); + metadataBeforeCleanupEntry.release(); await admitted; expect(parseMcpToolError(await resetting)).toMatchObject({ error: { @@ -658,7 +648,7 @@ it("drains admitted work before retrying process cleanup and refuses reset while expect(test.createClient).not.toHaveBeenCalled(); } finally { cleanupAllowed = true; - release.resolve(); + metadataBeforeCleanupEntry.release(); await Promise.allSettled(pending); retry.mockRestore(); } diff --git a/tests/boundary/mcp/lateAbortApplicationEvidenceMcp.test.ts b/tests/boundary/mcp/lateAbortApplicationEvidenceMcp.test.ts index f003d6259b..8cf954be2d 100644 --- a/tests/boundary/mcp/lateAbortApplicationEvidenceMcp.test.ts +++ b/tests/boundary/mcp/lateAbortApplicationEvidenceMcp.test.ts @@ -1,10 +1,7 @@ import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { expect, it, onTestFinished } from "vitest"; -import { - createTestBinarySession, - createDeferred, -} from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { GoBinaryService } from "../../../src/application/go/GoBinaryService.js"; import type { GoBinary } from "../../../src/domain/go/goBinary.js"; import { silentLogger } from "../../../src/logger.js"; @@ -17,8 +14,7 @@ import type { JavaScriptRuntimeTargetList } from "../../../src/domain/javascript import { waitFor } from "../../support/testWait.js"; it("retains late-cancelled Go artifact Evidence through MCP and keeps the server usable", async () => { - const gate = createDeferred(); - const started = createDeferred(); + const goInspection = phaseGate(); const controller = new AbortController(); const report: GoBinary = { artifact: { path: "/artifacts/example", sha256: "a".repeat(64), bytes: 10 }, @@ -36,8 +32,7 @@ it("retains late-cancelled Go artifact Evidence through MCP and keeps the server close: async () => {}, identity: { id: "fixture", name: "fixture", version: "1" }, inspect: async (_input, options) => { - started.resolve(); - await gate.promise; + await goInspection.hold(); if (!options?.signal) throw new Error("MCP did not forward its signal"); return ok(report); }, @@ -50,7 +45,7 @@ it("retains late-cancelled Go artifact Evidence through MCP and keeps the server const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); onTestFinished(async () => { - gate.resolve(); + goInspection.release(); controller.abort(); await client.close(); await server.close(); @@ -62,9 +57,9 @@ it("retains late-cancelled Go artifact Evidence through MCP and keeps the server { name: "inspect_go_binary", arguments: { path: report.artifact.path } }, { signal: controller.signal }, ); - await awaitAcknowledgement(started.promise, call, "MCP observation"); + await goInspection.reached(call, "MCP observation"); controller.abort(); - gate.resolve(); + goInspection.release(); await expect(call).rejects.toThrow(); await waitFor(() => { expect(session.exportEvidenceBundle().records).toContainEqual( @@ -78,8 +73,7 @@ it("retains late-cancelled Go artifact Evidence through MCP and keeps the server }); it("retains late-cancelled Inspector target Evidence through MCP and keeps the server usable", async () => { - const gate = createDeferred(); - const started = createDeferred(); + const inspectorObservation = phaseGate(); const controller = new AbortController(); const targetList: JavaScriptRuntimeTargetList = { runtime: { product: "Node.js", protocol_version: "1.0", v8_version: null }, @@ -94,8 +88,7 @@ it("retains late-cancelled Inspector target Evidence through MCP and keeps the s version: "1", }), listTargets: async (_input, options) => { - started.resolve(); - await gate.promise; + await inspectorObservation.hold(); if (!options?.signal) throw new Error("MCP did not forward its signal"); return ok(targetList); }, @@ -114,7 +107,7 @@ it("retains late-cancelled Inspector target Evidence through MCP and keeps the s const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); onTestFinished(async () => { - gate.resolve(); + inspectorObservation.release(); controller.abort(); await client.close(); await server.close(); @@ -129,9 +122,9 @@ it("retains late-cancelled Inspector target Evidence through MCP and keeps the s }, { signal: controller.signal }, ); - await awaitAcknowledgement(started.promise, call, "MCP observation"); + await inspectorObservation.reached(call, "MCP observation"); controller.abort(); - gate.resolve(); + inspectorObservation.release(); await expect(call).rejects.toThrow(); await waitFor(() => { expect(session.exportEvidenceBundle().records).toContainEqual( @@ -145,8 +138,7 @@ it("retains late-cancelled Inspector target Evidence through MCP and keeps the s }); it("records late-cancelled Browser target Evidence and keeps the server usable", async () => { - const gate = createDeferred(); - const started = createDeferred(); + const browserObservation = phaseGate(); const controller = new AbortController(); const targetList: BrowserTargetList = { browser: { @@ -163,8 +155,7 @@ it("records late-cancelled Browser target Evidence and keeps the server usable", const browser: BrowserObservationPort = { identity: () => ({ id: "fixture-browser", name: "fixture", version: "1" }), listTargets: async (_input, options) => { - started.resolve(); - await gate.promise; + await browserObservation.hold(); if (!options?.signal) throw new Error("MCP did not forward its signal"); return ok(targetList); }, @@ -201,7 +192,7 @@ it("records late-cancelled Browser target Evidence and keeps the server usable", const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); onTestFinished(async () => { - gate.resolve(); + browserObservation.release(); controller.abort(); await client.close(); await server.close(); @@ -216,9 +207,9 @@ it("records late-cancelled Browser target Evidence and keeps the server usable", }, { signal: controller.signal }, ); - await awaitAcknowledgement(started.promise, call, "MCP observation"); + await browserObservation.reached(call, "MCP observation"); controller.abort(); - gate.resolve(); + browserObservation.release(); await expect(call).rejects.toThrow(); await waitFor(() => { expect(session.exportEvidenceBundle().records).toContainEqual( diff --git a/tests/boundary/mcp/mcpFixtureLifecycle.test.ts b/tests/boundary/mcp/mcpFixtureLifecycle.test.ts index 8b9a804262..9771ceaf64 100644 --- a/tests/boundary/mcp/mcpFixtureLifecycle.test.ts +++ b/tests/boundary/mcp/mcpFixtureLifecycle.test.ts @@ -1,9 +1,8 @@ import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { McpServer } from "@modelcontextprotocol/server"; import { expect, it, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { createTestMcp } from "../../support/mcp/mcpFixture.js"; /** Keep real SDK objects recoverable even when a red ownership assertion fails. */ @@ -45,13 +44,11 @@ const createSdkFixture = () => { it("joins an accepted late handshake and refuses to publish it after shutdown", async () => { const fixture = createSdkFixture(); const server = fixture.server("late-handshake"); - const connected = createDeferred(); - const release = createDeferred(); + const lateHandshake = phaseGate(); const connect = server.connect.bind(server); server.connect = async (transport) => { await connect(transport); - connected.resolve(); - await release.promise; + await lateHandshake.hold(); }; const serverClose = vi.spyOn(server, "close"); const opening = fixture.mcp.connect(server).then( @@ -61,7 +58,7 @@ it("joins an accepted late handshake and refuses to publish it after shutdown", let closeSettled = false; let closing: Promise | undefined; try { - await connected.promise; + await lateHandshake.reached(opening, "late handshake"); closing = fixture.mcp.close().then(() => { closeSettled = true; }); @@ -70,13 +67,13 @@ it("joins an accepted late handshake and refuses to publish it after shutdown", await Promise.resolve(); await Promise.resolve(); expect(closeSettled).toBe(false); - release.resolve(); + lateHandshake.release(); expect(await opening).toMatchObject({ ok: false }); await closing; expect(serverClose).toHaveBeenCalledTimes(1); expect(fixture.clientCloses).toHaveBeenCalledTimes(1); } finally { - release.resolve(); + lateHandshake.release(); await opening; await closing?.catch(() => undefined); await fixture.dispose(); @@ -86,8 +83,7 @@ it("joins an accepted late handshake and refuses to publish it after shutdown", it("registers acquisition before a producer can reenter shutdown and attach its transport late", async () => { const fixture = createSdkFixture(); const server = fixture.server("reentrant-shutdown"); - const entered = createDeferred(); - const release = createDeferred(); + const reentrantShutdown = phaseGate(); const connect = server.connect.bind(server); const close = server.close.bind(server); const lifecycle: string[] = []; @@ -97,8 +93,7 @@ it("registers acquisition before a producer can reenter shutdown and attach its closing = fixture.mcp.close().then(() => { closeSettled = true; }); - entered.resolve(); - await release.promise; + await reentrantShutdown.hold(); await connect(transport); lifecycle.push("attached"); }; @@ -111,17 +106,13 @@ it("registers acquisition before a producer can reenter shutdown and attach its (reason: unknown) => ({ ok: false as const, reason }), ); try { - await awaitAcknowledgement( - entered.promise, - opening, - "MCP lifecycle boundary", - ); + await reentrantShutdown.reached(opening, "MCP lifecycle boundary"); await Promise.resolve(); await Promise.resolve(); expect(closeSettled).toBe(false); expect(serverClose).not.toHaveBeenCalled(); expect(fixture.clientCloses).not.toHaveBeenCalled(); - release.resolve(); + reentrantShutdown.release(); const outcome = await opening; if (outcome.ok) throw new Error("Shutdown published a late MCP client"); expect(outcome.reason).toMatchObject({ @@ -133,7 +124,7 @@ it("registers acquisition before a producer can reenter shutdown and attach its expect(serverClose).toHaveBeenCalledTimes(1); expect(fixture.clientCloses).toHaveBeenCalledTimes(1); } finally { - release.resolve(); + reentrantShutdown.release(); await opening; await closing?.catch(() => undefined); await fixture.dispose(); @@ -143,8 +134,7 @@ it("registers acquisition before a producer can reenter shutdown and attach its it("shares one concurrent close attempt and does not reclose released SDK objects", async () => { const fixture = createSdkFixture(); const server = fixture.server("concurrent-close"); - const entered = createDeferred(); - const release = createDeferred(); + const serverCloseHold = phaseGate(); let first: Promise | undefined; let second: Promise | undefined; try { @@ -154,28 +144,23 @@ it("shares one concurrent close attempt and does not reclose released SDK object const serverClose = vi .spyOn(server, "close") .mockImplementation(async () => { - entered.resolve(); - await release.promise; + await serverCloseHold.hold(); await close(); }); first = fixture.mcp.close(); - await awaitAcknowledgement( - entered.promise, - first, - "MCP lifecycle boundary", - ); + await serverCloseHold.reached(first, "MCP lifecycle boundary"); second = fixture.mcp.close(); await Promise.resolve(); await Promise.resolve(); expect(serverClose).toHaveBeenCalledTimes(1); expect(fixture.clientCloses).toHaveBeenCalledTimes(1); - release.resolve(); + serverCloseHold.release(); await Promise.all([first, second]); await fixture.mcp.close(); expect(serverClose).toHaveBeenCalledTimes(1); expect(fixture.clientCloses).toHaveBeenCalledTimes(1); } finally { - release.resolve(); + serverCloseHold.release(); await Promise.allSettled([first, second]); await fixture.dispose(); } @@ -184,11 +169,9 @@ it("shares one concurrent close attempt and does not reclose released SDK object it("cancels a real initialize handshake before awaiting its held server handler", async () => { const fixture = createSdkFixture(); const server = fixture.server("stalled-initialize"); - const entered = createDeferred(); - const release = createDeferred(); + const initializeHandler = phaseGate(); server.server.setRequestHandler("initialize", async () => { - entered.resolve(); - await release.promise; + await initializeHandler.hold(); throw new Error("Held initialize handler released during test cleanup"); }); let openingSettled = false; @@ -204,17 +187,13 @@ it("cancels a real initialize handshake before awaiting its held server handler" ); const serverClose = vi.spyOn(server, "close"); try { - await awaitAcknowledgement( - entered.promise, - opening, - "MCP lifecycle boundary", - ); + await initializeHandler.reached(opening, "MCP lifecycle boundary"); await fixture.mcp.close(); expect(openingSettled).toBe(true); expect(await opening).toMatchObject({ ok: false }); expect(serverClose).toHaveBeenCalledTimes(1); } finally { - release.resolve(); + initializeHandler.release(); await opening; await fixture.dispose(); } diff --git a/tests/boundary/mcp/optionalProviderShutdown.test.ts b/tests/boundary/mcp/optionalProviderShutdown.test.ts index f4e7758087..8b93db8498 100644 --- a/tests/boundary/mcp/optionalProviderShutdown.test.ts +++ b/tests/boundary/mcp/optionalProviderShutdown.test.ts @@ -1,11 +1,9 @@ import { afterAll, expect, it, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { mkdirSync, mkdtempSync, rmSync } from "node:fs"; import { resolve } from "node:path"; -import { - createDeferred, - createTestBinarySession, -} from "../../fixtures/binarySession.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { createBrowserObservationProvider } from "../../../src/composition/browserObservation.js"; import { createJavaScriptRuntimeObservationProvider } from "../../../src/composition/javascriptRuntimeObservation.js"; import { run } from "../../../src/main.js"; @@ -30,8 +28,7 @@ for (const path of [ afterAll(() => rmSync(root, { recursive: true, force: true })); it("refuses eager server publication after the shutdown snapshot and completed close", async () => { - const closingHandle = createDeferred(); - const releaseHandle = createDeferred(); + const transportClose = phaseGate(); const acquired: ReturnType[] = []; let publish: (() => unknown) | undefined; let shutdown: (() => Promise) | undefined; @@ -53,8 +50,7 @@ it("refuses eager server publication after the shutdown snapshot and completed c return { close: async () => { transportCloses++; - closingHandle.resolve(); - await releaseHandle.promise; + await transportClose.hold(); }, }; }, @@ -69,16 +65,16 @@ it("refuses eager server publication after the shutdown snapshot and completed c if (shutdown === undefined || publish === undefined) throw new Error("Runtime ownership hooks were not installed"); closing = shutdown(); - await closingHandle.promise; + await transportClose.reached(closing, "transport close"); expect(publish).toThrow("MCP connection is closed"); - releaseHandle.resolve(); + transportClose.release(); await closing; expect(publish).toThrow("MCP connection is closed"); await shutdown(); expect(transportCloses).toBe(1); expect(acquired).toHaveLength(1); } finally { - releaseHandle.resolve(); + transportClose.release(); await closing; await shutdown?.(); for (const server of acquired) await server.close(); diff --git a/tests/boundary/mcp/progressMcp.test.ts b/tests/boundary/mcp/progressMcp.test.ts index 388e3436d3..8aa5516514 100644 --- a/tests/boundary/mcp/progressMcp.test.ts +++ b/tests/boundary/mcp/progressMcp.test.ts @@ -13,7 +13,7 @@ import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js import { err, ok } from "../../../src/domain/result.js"; import { createServer } from "../../../src/server/createServer.js"; import { observed } from "../../fixtures/analysisExecution.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; describe("ordinary MCP progress and cancellation", () => { it("advances MCP progress when provider waiting does not advance completed work", async () => { @@ -107,29 +107,21 @@ describe("ordinary MCP progress and cancellation", () => { it("propagates client cancellation to the active provider request", async () => { let providerObservedCancellation = false; let providerWasStarted = false; - let markProviderStarted!: () => void; let markProviderFinished!: () => void; - let releaseProvider!: () => void; - const providerStarted = new Promise((resolve) => { - markProviderStarted = resolve; - }); const providerFinished = new Promise((resolve) => { markProviderFinished = resolve; }); - const providerGate = new Promise((resolve) => { - releaseProvider = resolve; - }); + const providerRequest = phaseGate(); const analysis: AnalysisOperationPort = { execute: async (operation, _parameters, options) => { const onAbort = () => { providerObservedCancellation = true; - releaseProvider(); + providerRequest.release(); }; options?.signal?.addEventListener("abort", onAbort, { once: true }); providerWasStarted = true; - markProviderStarted(); try { - await providerGate; + await providerRequest.hold(); return err(new AnalysisCancelledError(operation)); } finally { options?.signal?.removeEventListener("abort", onAbort); @@ -149,13 +141,13 @@ describe("ordinary MCP progress and cancellation", () => { { name: "current_address", arguments: {} }, { signal: controller.signal }, ); - await awaitAcknowledgement(providerStarted, request, "provider request"); + await providerRequest.reached(request, "provider request"); controller.abort(); await expect(request).rejects.toThrow(/abort/iu); await expect.poll(() => providerObservedCancellation).toBe(true); }, [ async () => { - releaseProvider(); + providerRequest.release(); if (providerWasStarted) await providerFinished; }, () => client.close(), diff --git a/tests/boundary/mcp/promptMcp.test.ts b/tests/boundary/mcp/promptMcp.test.ts index a627a1d1fe..fda86a3cd4 100644 --- a/tests/boundary/mcp/promptMcp.test.ts +++ b/tests/boundary/mcp/promptMcp.test.ts @@ -5,7 +5,12 @@ import { import { ok as resultOk, err, ok } from "../../../src/domain/result.js"; import { readFile, writeFile } from "node:fs/promises"; import { basename, join } from "node:path"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { + phaseArrival, + phaseGate, + type PhaseArrival, + type PhaseGate, +} from "../../support/lifecycleHarness.js"; import { Client, @@ -633,11 +638,11 @@ it("guided prompt completion avoids cold startup and cancels warm lookup on clos const startup = fixture.holdStartup(); const warming = client.callTool({ name: "list_documents", arguments: {} }); await withVerifierCleanup(async () => { - await startup.started; + await startup.reached(warming, "deep provider startup"); expect(await complete(client, "document", "")).toEqual([]); expect(await complete(client, "procedure", "")).toEqual([]); expect(fixture.childrenCreated()).toBe(1); - startup.finish(); + startup.release(); const warmed = await warming; expect(warmed.isError, JSON.stringify(warmed)).not.toBe(true); expect(fixture.childrenCreated()).toBe(1); @@ -646,7 +651,7 @@ it("guided prompt completion avoids cold startup and cancels warm lookup on clos ]); }, [ async () => { - startup.finish(); + startup.release(); }, async () => { await warming; @@ -662,7 +667,7 @@ it("guided prompt completion avoids cold startup and cancels warm lookup on clos }, { signal: controller.signal }, ); - await cancellation.started; + await cancellation.start.reached(cancelled, "prompt completion start"); controller.abort(); await expect(cancelled).rejects.toThrow(); await cancellation.aborted; @@ -672,7 +677,7 @@ it("guided prompt completion avoids cold startup and cancels warm lookup on clos ref: { type: "ref/prompt", name: "investigate_feature" }, argument: { name: "document", value: "" }, }); - await lifecycle.started; + await lifecycle.start.reached(pending, "prompt completion start"); const closed = await client.callTool({ name: "close_binary", arguments: {}, @@ -685,18 +690,9 @@ it("guided prompt completion avoids cold startup and cancels warm lookup on clos it.each(["replacement", "shutdown"])( "waits for cancelled completion cleanup before HTTP %s", async (ending) => { - let release!: () => void; - let entered!: () => void; - let cancelled!: () => void; - const gate = new Promise((resolve) => { - release = resolve; - }); - const started = new Promise((resolve) => { - entered = resolve; - }); - const aborted = new Promise((resolve) => { - cancelled = resolve; - }); + const completionStart = phaseArrival(); + const completionAbort = phaseArrival(); + const completionCleanup = phaseGate(); const server = new EvidenceMcpServer( { name: "http-completion-drain", version: "1" }, {}, @@ -708,20 +704,20 @@ it.each(["replacement", "shutdown"])( registerGuidedPrompts(server, { async execute(_operation, _parameters, options) { if (++calls > 1) return observed(["fresh-document"]); - entered(); + completionStart.arrive(); try { await new Promise((resolve) => { options?.signal?.addEventListener( "abort", () => { - cancelled(); + completionAbort.arrive(); resolve(); }, { once: true }, ); }); } finally { - await gate; + await completionCleanup.hold(); } return observed(["old-document"]); }, @@ -747,7 +743,7 @@ it.each(["replacement", "shutdown"])( try { initial = complete(first, "document", ""); void initial.catch(() => undefined); - await awaitAcknowledgement(started, initial, "prompt completion start"); + await completionStart.reached(initial, "prompt completion start"); let finished = false; finishing = ( ending === "shutdown" @@ -758,22 +754,21 @@ it.each(["replacement", "shutdown"])( ).then(() => { finished = true; }); - await awaitAcknowledgement( - aborted, + await completionAbort.reached( finishing, "prompt completion cancellation", ); await new Promise((resolve) => setImmediate(resolve)); expect(connections).toHaveBeenCalledTimes(1); expect(finished).toBe(false); - release(); + completionCleanup.release(); await finishing; if (next !== undefined) expect(await complete(next, "document", "fresh")).toEqual([ "fresh-document", ]); } finally { - release(); + completionCleanup.release(); await finishing?.catch(() => undefined); } }, @@ -782,14 +777,7 @@ it.each(["replacement", "shutdown"])( describe("guided prompt completion lifecycle", () => { it("survives a cancelled completion and ignores its late result", async () => { let calls = 0; - let markStarted = (): void => undefined; - let release = (): void => undefined; - const started = new Promise((resolve) => { - markStarted = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const completionStart = phaseGate(); let producerDone!: () => void; const producerFinished = new Promise((resolve) => { producerDone = resolve; @@ -805,9 +793,8 @@ describe("guided prompt completion lifecycle", () => { async execute() { calls += 1; if (calls === 1) { - markStarted(); try { - await gate; + await completionStart.hold(); return observed(["late-document"]); } finally { producerDone(); @@ -827,10 +814,10 @@ describe("guided prompt completion lifecycle", () => { { signal: controller.signal }, ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(started, pending, "prompt completion start"); + await completionStart.reached(pending, "prompt completion start"); controller.abort(); await expect(pending).rejects.toThrow(); - release(); + completionStart.release(); await new Promise((resolve) => setTimeout(resolve, 0)); expect(await complete(client, "document", "fresh")).toEqual([ @@ -840,7 +827,7 @@ describe("guided prompt completion lifecycle", () => { }, [ async () => { controller.abort(); - release(); + completionStart.release(); }, async () => { await pending.catch(() => undefined); @@ -916,15 +903,10 @@ const createWarmCompletionFixture = async () => { resultOk(createAnalysisExecution(result, identity, { analysisProfile })); let childrenCreated = 0; let ready = false; - let startupGate: - | { - readonly started: () => void; - readonly release: Promise; - } - | undefined; + let startupGate: PhaseGate | undefined; let completionGate: | { - readonly started: () => void; + readonly start: PhaseArrival; readonly aborted: () => void; } | undefined; @@ -937,8 +919,7 @@ const createWarmCompletionFixture = async () => { const gate = startupGate; if (gate !== undefined) { startupGate = undefined; - gate.started(); - await gate.release; + await gate.hold(); } ready = true; } @@ -966,7 +947,7 @@ const createWarmCompletionFixture = async () => { ), ); completionGate = undefined; - gate.started(); + gate.start.arrive(); return new Promise((resolve) => { const signal = options?.signal; const cancel = (): void => { @@ -1005,28 +986,18 @@ const createWarmCompletionFixture = async () => { client, childrenCreated: () => childrenCreated, holdStartup: () => { - let started = (): void => undefined; - let finish = (): void => undefined; - const observedStart = new Promise((resolve) => { - started = resolve; - }); - const release = new Promise((resolve) => { - finish = resolve; - }); - startupGate = { started, release }; - return { started: observedStart, finish }; + const gate = phaseGate(); + startupGate = gate; + return gate; }, holdCompletion: () => { - let started = (): void => undefined; + const start = phaseArrival(); let aborted = (): void => undefined; - const observedStart = new Promise((resolve) => { - started = resolve; - }); const observedAbort = new Promise((resolve) => { aborted = resolve; }); - completionGate = { started, aborted }; - return { started: observedStart, aborted: observedAbort }; + completionGate = { start, aborted }; + return { start, aborted: observedAbort }; }, }; }; diff --git a/tests/boundary/mcp/providerSelectionMcp.test.ts b/tests/boundary/mcp/providerSelectionMcp.test.ts index 3f807d68df..ec2ee1a9d0 100644 --- a/tests/boundary/mcp/providerSelectionMcp.test.ts +++ b/tests/boundary/mcp/providerSelectionMcp.test.ts @@ -15,8 +15,7 @@ import { z } from "zod"; import { jsonObjectSchema } from "../../../src/domain/jsonValue.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import type { BinarySession } from "../../../src/application/binary/BinarySession.js"; import { @@ -669,15 +668,13 @@ const expectQueuedOpenReceipt = async ( const call = (name: string, args: Record) => mcp.callTool({ name, arguments: args }); const originalOpen = session.open.bind(session); - const failedSettled = createDeferred(); - const deliverFailure = createDeferred(); + const failedSnapshotOpen = phaseGate(); const intercept = vi .spyOn(session, "open") .mockImplementation(async (path, options) => { const result = await originalOpen(path, options); if (path === second && options?.loadSnapshot !== undefined) { - failedSettled.resolve(); - await deliverFailure.promise; + await failedSnapshotOpen.hold(); } return result; }); @@ -688,11 +685,7 @@ const expectQueuedOpenReceipt = async ( snapshot_path: snapshotPath, }); try { - await awaitAcknowledgement( - failedSettled.promise, - failedSwitch, - "failed snapshot open", - ); + await failedSnapshotOpen.reached(failedSwitch, "failed snapshot open"); const nextReply = await call("open_binary", { path: second, provider_id: "beta", @@ -703,13 +696,13 @@ const expectQueuedOpenReceipt = async ( expect((await call("binary_session", {})).structuredContent).toMatchObject({ result: { path: second, sha256: sha("second fixture") }, }); - deliverFailure.resolve(); + failedSnapshotOpen.release(); const failedReply = await failedSwitch; expect( parseMcpToolError(failedReply).error.details?.selection_at_failure, ).toEqual(expectedOpenSelection(first, sha("first fixture"))); } finally { - deliverFailure.resolve(); + failedSnapshotOpen.release(); await failedSwitch.catch(() => undefined); intercept.mockRestore(); } @@ -1227,16 +1220,14 @@ const checkQueuedSwitchReceipt = async ( ): Promise => { const other = join(directory, "other.hop"); await writeFile(other, "other fixture"); - const settled = createDeferred(); - const release = createDeferred(); + const failedOpenReceipt = phaseGate(); const open = session.open.bind(session); const spy = vi .spyOn(session, "open") .mockImplementation(async (path, options) => { const result = await open(path, options); if (options?.providerId === "missing") { - settled.resolve(); - await release.promise; + await failedOpenReceipt.hold(); } return result; }); @@ -1245,7 +1236,7 @@ const checkQueuedSwitchReceipt = async ( arguments: { path: target, provider_id: "missing" }, }); try { - await awaitAcknowledgement(settled.promise, pending, "failed-open receipt"); + await failedOpenReceipt.reached(pending, "failed-open receipt"); const switched = await mcp.callTool({ name: "open_binary", arguments: { path: other, provider_id: "alpha" }, @@ -1254,7 +1245,7 @@ const checkQueuedSwitchReceipt = async ( expect(session.activeTarget()?.sha256).toBe( createHash("sha256").update("other fixture").digest("hex"), ); - release.resolve(); + failedOpenReceipt.release(); const queuedRefusal = await pending; for (const result of [structured(queuedRefusal), refusal]) expect(result).toMatchObject({ @@ -1266,7 +1257,7 @@ const checkQueuedSwitchReceipt = async ( }, }); } finally { - release.resolve(); + failedOpenReceipt.release(); await Promise.allSettled([pending]); spy.mockRestore(); } @@ -1436,15 +1427,8 @@ it("preserves the bound client when a candidate refresh is cancelled during fina const starts: string[] = []; const base = candidate("alpha", starts); let hold = false; - let enter!: () => void; - let finish!: () => void; let finalized!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - finish = resolve; - }); + const candidateRefresh = phaseGate(); const done = new Promise((resolve) => { finalized = resolve; }); @@ -1457,8 +1441,7 @@ it("preserves the bound client when a candidate refresh is cancelled during fina }: AnalysisProviderInspectionOptions = {}) => { const result = await base.inspectAvailability(); if (!hold) return result; - enter(); - await gate; + await candidateRefresh.hold(); finalized(); if (signal?.aborted) throw new AnalysisCancelledError("binary_session", { @@ -1499,10 +1482,10 @@ it("preserves the bound client when a candidate refresh is cancelled during fina { name: "binary_session", arguments: { refresh_candidates: true } }, { signal: controller.signal }, ); - await awaitAcknowledgement(entered, refreshing, "candidate refresh"); + await candidateRefresh.reached(refreshing, "candidate refresh"); controller.abort(); await expect(refreshing).rejects.toThrow(); - finish(); + candidateRefresh.release(); await done; hold = false; expect( @@ -1518,7 +1501,7 @@ it("preserves the bound client when a candidate refresh is cancelled during fina expect(starts).toEqual(["alpha"]); } finally { hold = false; - finish(); + candidateRefresh.release(); await Promise.allSettled(refreshing === undefined ? [] : [refreshing]); } }); @@ -1532,14 +1515,7 @@ it("orders a provider switch after an in-flight candidate refresh", async () => const starts: string[] = []; const alpha = candidate("alpha", starts); let hold = false; - let enter!: () => void; - let finish!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - finish = resolve; - }); + const candidateRefresh = phaseGate(); const session = composeBinarySession( new AnalysisProviderRegistry([ { @@ -1547,8 +1523,7 @@ it("orders a provider switch after an in-flight candidate refresh", async () => inspectAvailability: async () => { if (hold) { hold = false; - enter(); - await gate; + await candidateRefresh.hold(); } return alpha.inspectAvailability(); }, @@ -1582,7 +1557,7 @@ it("orders a provider switch after an in-flight candidate refresh", async () => name: "binary_session", arguments: { refresh_candidates: true }, }); - await awaitAcknowledgement(entered, refreshing, "candidate refresh"); + await candidateRefresh.reached(refreshing, "candidate refresh"); let switched = false; switching = mcp .callTool({ @@ -1595,7 +1570,7 @@ it("orders a provider switch after an in-flight candidate refresh", async () => }); await new Promise((resolve) => setImmediate(resolve)); expect(switched).toBe(false); - finish(); + candidateRefresh.release(); const result = await refreshing; expect(result.isError).toBeFalsy(); expect(structured(result).result).toMatchObject({ @@ -1609,7 +1584,7 @@ it("orders a provider switch after an in-flight candidate refresh", async () => analysis_provider_binding: { provider: { id: "beta" } }, }); } finally { - finish(); + candidateRefresh.release(); await Promise.allSettled( [refreshing, switching].filter((operation) => operation !== undefined), ); @@ -1621,14 +1596,7 @@ it("does not cancel an already admitted prompt lookup for a candidate refresh", const target = join(directory, "fixture.hop"); await writeFile(target, "fixture"); const base = candidate("alpha", []); - let enter!: () => void; - let finish!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - finish = resolve; - }); + const promptLookup = phaseGate(); const session = composeBinarySession( new AnalysisProviderRegistry([ { @@ -1638,8 +1606,7 @@ it("does not cancel an already admitted prompt lookup for a candidate refresh", return { ...client, executeIfReady: async (operation, args, options) => { - enter(); - await gate; + await promptLookup.hold(); if (options?.signal?.aborted) throw new Error("Prompt lookup was cancelled"); return client.execute(operation, args, options); @@ -1673,7 +1640,7 @@ it("does not cancel an already admitted prompt lookup for a candidate refresh", (await mcp.callTool({ name: "address_name", arguments: {} })).isError, ).toBeFalsy(); lookup = session.executeIfProviderReady("address_name", {}); - await awaitAcknowledgement(entered, lookup, "prompt lookup"); + await promptLookup.reached(lookup, "prompt lookup"); expect( ( await mcp.callTool({ @@ -1682,10 +1649,10 @@ it("does not cancel an already admitted prompt lookup for a candidate refresh", }) ).isError, ).toBeFalsy(); - finish(); + promptLookup.release(); expect((await lookup)?.ok).toBe(true); } finally { - finish(); + promptLookup.release(); await Promise.allSettled(lookup === undefined ? [] : [lookup]); } }); @@ -1856,14 +1823,7 @@ it.each(["ready", "cancelled", "physical"] as const)( async (mode) => { const starts: string[] = []; const base = candidate("alpha", starts); - let enter!: () => void; - let finish!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - finish = resolve; - }); + const providerReadiness = phaseGate(); const session = composeBinarySession( new AnalysisProviderRegistry([ { @@ -1871,8 +1831,7 @@ it.each(["ready", "cancelled", "physical"] as const)( inspectAvailability: async ({ signal, }: AnalysisProviderInspectionOptions = {}) => { - enter(); - await gate; + await providerReadiness.hold(); if (mode === "physical") throw new ProviderAdapterError("alpha", "binary_session", { diagnostics: { @@ -1907,7 +1866,7 @@ it.each(["ready", "cancelled", "physical"] as const)( }); let closing: ReturnType | undefined; try { - await awaitAcknowledgement(entered, observing, "provider readiness"); + await providerReadiness.reached(observing, "provider readiness"); if (mode !== "ready") { closing = session.close(); const during = structured( @@ -1948,7 +1907,7 @@ it.each(["ready", "cancelled", "physical"] as const)( } await new Promise((resolve) => setImmediate(resolve)); expect(settled).toBe(false); - finish(); + providerReadiness.release(); const result = await observing; if (mode === "ready") { expect(result.isError).not.toBe(true); @@ -1978,7 +1937,7 @@ it.each(["ready", "cancelled", "physical"] as const)( } expect(starts).toEqual([]); } finally { - finish(); + providerReadiness.release(); try { await Promise.all([observing, closing]); } finally { diff --git a/tests/boundary/mcp/resetArtifactCleanupMcp.test.ts b/tests/boundary/mcp/resetArtifactCleanupMcp.test.ts index 843e9eda71..50cbfde754 100644 --- a/tests/boundary/mcp/resetArtifactCleanupMcp.test.ts +++ b/tests/boundary/mcp/resetArtifactCleanupMcp.test.ts @@ -3,6 +3,7 @@ import type { CallToolResult } from "@modelcontextprotocol/server"; import { access, readFile, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { expect, it, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { z } from "zod"; import { FUNCTION_COMPARISON_EXAMPLE } from "../../../src/contracts/functionComparisonExample.js"; @@ -15,11 +16,7 @@ import { silentLogger } from "../../../src/logger.js"; import { ProcessCaptureError } from "../../../src/process/capture/ProcessCaptureError.js"; import { ProcessCaptureResourceScope } from "../../../src/process/capture/ProcessCaptureLifecycle.js"; import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js"; -import { - createDeferred, - createTestBinarySession, -} from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { parseMcpEvidenceBundle } from "../../fixtures/mcpEvidenceBundle.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; @@ -91,8 +88,7 @@ it("drains ordinary exports and refuses reset until their retained artifact owne const checkpointPath = join(root, "caller-checkpoint.json"); const checkpointBytes = Buffer.from("caller-owned checkpoint"); await writeFile(checkpointPath, checkpointBytes); - const entered = createDeferred(); - const release = createDeferred(); + const ordinaryExportFinalCleanup = phaseGate(); const originalClose = OwnedStagedOutput.prototype.close; const originalProcessRetry = ProcessCaptureResourceScope.prototype.retryCleanup; @@ -130,8 +126,7 @@ it("drains ordinary exports and refuses reset until their retained artifact owne } if (this === retainedOutput) { cleanupAttempts += 1; - entered.resolve(); - await release.promise; + await ordinaryExportFinalCleanup.hold(); if (!cleanupAllowed) throw new Error("Controlled ordinary-export staging cleanup refusal"); } @@ -144,8 +139,7 @@ it("drains ordinary exports and refuses reset until their retained artifact owne arguments: { path: exportPath }, }); pending.push(exporting); - await awaitAcknowledgement( - entered.promise, + await ordinaryExportFinalCleanup.reached( exporting, "ordinary export final cleanup", ); @@ -157,7 +151,7 @@ it("drains ordinary exports and refuses reset until their retained artifact owne await client.ping(); expect(cleanupAttempts).toBe(1); expect(session.immutableEvidenceBundle()).toEqual(before); - release.resolve(); + ordinaryExportFinalCleanup.release(); expect(parseMcpToolError(await exporting)).toMatchObject({ error: { code: "cleanup_incomplete" }, }); @@ -237,7 +231,7 @@ it("drains ordinary exports and refuses reset until their retained artifact owne } finally { cleanupAllowed = true; processCleanupAllowed = true; - release.resolve(); + ordinaryExportFinalCleanup.release(); await Promise.allSettled(pending); close.mockRestore(); retryProcess.mockRestore(); diff --git a/tests/boundary/mcp/serverLifecycleMcp.test.ts b/tests/boundary/mcp/serverLifecycleMcp.test.ts index 6ac1734db1..df11130a19 100644 --- a/tests/boundary/mcp/serverLifecycleMcp.test.ts +++ b/tests/boundary/mcp/serverLifecycleMcp.test.ts @@ -3,7 +3,7 @@ import { parseMcpEvidenceBundle } from "../../fixtures/mcpEvidenceBundle.js"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import type { CallToolResult } from "@modelcontextprotocol/server"; import { afterEach, expect, it } from "vitest"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import type { AnalysisOperationPort } from "../../../src/ports/AnalysisProvider.js"; import { HopperRemoteError } from "../../../src/domain/hopperErrors.js"; @@ -35,7 +35,6 @@ import { removeTestWorkspace, } from "../../support/workspace/workspaceFixture.js"; import { z } from "zod"; -import { createDeferred } from "../../fixtures/binarySession.js"; import { GoBinaryService } from "../../../src/application/go/GoBinaryService.js"; import { Il2cppMetadataService } from "../../../src/application/il2cpp/Il2cppMetadataService.js"; import { WebNetworkCaptureService } from "../../../src/application/WebNetworkCaptureService.js"; @@ -51,8 +50,7 @@ it.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)( const workspace = await createTestWorkspace("rea-sqlite-mcp-admission-"); const database = createSqliteDatabaseFixture(workspace.root); database.close(); - const acquired = createDeferred(); - const release = createDeferred(); + const runtimeRoot = phaseGate(); const provider = new SqliteDatabaseProvider( process.env, (spawn) => @@ -73,8 +71,7 @@ it.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)( const root = await PrivateRuntimeRoot.create({ parent: workspace.root, }); - acquired.resolve(); - await release.promise; + await runtimeRoot.hold(); return root; }, ); @@ -93,7 +90,7 @@ it.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)( name: "inspect_sqlite_database", arguments: { path: database.path, table: "records", columns: ["id"] }, }); - await acquired.promise; + await runtimeRoot.reached(inspection, "SQLite runtime root"); let closed = false; const closing = session.close().then((result) => { closed = true; @@ -101,7 +98,7 @@ it.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)( }); await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); - release.resolve(); + runtimeRoot.release(); const result = await inspection; expect(result.isError).not.toBe(true); const evidenceId = z @@ -115,7 +112,7 @@ it.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)( expect(session.evidenceById(evidenceId)?.evidence_id).toBe(evidenceId); expect(closed).toBe(true); } finally { - release.resolve(); + runtimeRoot.release(); await client.close(); await server.close(); await session.close(); @@ -617,12 +614,7 @@ it("preserves distinct results across concurrent tool calls", async () => { ]); const pending = new Map void>(); let releaseRemaining = false; - let allStarted: () => void = () => { - throw new Error("start gate missing"); - }; - const started = new Promise((resolve) => { - allStarted = resolve; - }); + const allStarted = phaseArrival(); const client = await connect({ execute: async (name) => { const payload = payloads.get(name); @@ -630,7 +622,7 @@ it("preserves distinct results across concurrent tool calls", async () => { throw new Error(`Unexpected operation: ${name}`); await new Promise((resolve) => { pending.set(name, resolve); - if (pending.size === payloads.size) allStarted(); + if (pending.size === payloads.size) allStarted.arrive(); if (releaseRemaining) resolve(); }); return ok(payload); @@ -641,11 +633,7 @@ it("preserves distinct results across concurrent tool calls", async () => { client.callTool({ name, arguments: {} }), ); try { - await awaitAcknowledgement( - started, - Promise.all(requests), - "MCP tool calls", - ); + await allStarted.reached(Promise.all(requests), "MCP tool calls"); for (const name of [...names].reverse()) { const release = pending.get(name); if (release === undefined) diff --git a/tests/boundary/mcp/sessionAvailabilityRecovery.test.ts b/tests/boundary/mcp/sessionAvailabilityRecovery.test.ts index 1557744311..51b707d93b 100644 --- a/tests/boundary/mcp/sessionAvailabilityRecovery.test.ts +++ b/tests/boundary/mcp/sessionAvailabilityRecovery.test.ts @@ -1,4 +1,5 @@ import { expect, it, onTestFinished } from "vitest"; +import { phaseGate, type PhaseGate } from "../../support/lifecycleHarness.js"; import { createAnalysisExecution, @@ -23,7 +24,6 @@ import { err, ok, type Result } from "../../../src/domain/result.js"; import { silentLogger } from "../../../src/logger.js"; import { observed } from "../../fixtures/analysisExecution.js"; import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { createBinarySessionTargets, @@ -34,8 +34,7 @@ import { it("restores MCP tool availability after cancelling a target switch", async () => { const [first, second] = await createBinarySessionTargets(); - const closing = createDeferred(); - const release = createDeferred(); + const providerClose = phaseGate(); const cancellationObserved = createDeferred(); const provider = createCacheProvider([]); const resolveProfile = provider.resolveAnalysisProfile; @@ -58,8 +57,7 @@ it("restores MCP tool availability after cancelling a target switch", async () = close: async () => { state.closed += 1; if (firstClient) { - closing.resolve(); - await release.promise; + await providerClose.hold(); } return ok(null); }, @@ -118,10 +116,10 @@ it("restores MCP tool availability after cancelling a target switch", async () = { signal: controller.signal }, ); const cancelled = expect(switching).rejects.toThrow(); - await awaitAcknowledgement(closing.promise, switching, "provider close"); + await providerClose.reached(switching, "provider close"); controller.abort(); await cancellationObserved.promise; - release.resolve(); + providerClose.release(); await cancelled; // Cancellation ends the client's wait before the server restores its session. @@ -161,7 +159,7 @@ it("restores MCP tool availability after cancelling a target switch", async () = ]); } finally { controller.abort(); - release.resolve(); + providerClose.release(); await close(); } }); @@ -381,10 +379,7 @@ const refusal = (operation: string, reason: string) => const heldCalls = ( client: Awaited>["client"], ) => { - const held = new Map< - string, - { readonly reply: Promise; readonly received: () => void } - >(); + const held = new Map>(); const launched: { readonly release: (reply: Reply) => void; readonly response: Promise; @@ -395,18 +390,16 @@ const heldCalls = ( const entry = held.get(operation); if (entry === undefined) return undefined; held.delete(operation); - entry.received(); - return entry.reply; + return entry.hold(); }, dispatch: async (name: string, arguments_: Record) => { - const reply = createDeferred(); - const received = createDeferred(); - held.set(name, { reply: reply.promise, received: received.resolve }); + const reply = phaseGate(); + held.set(name, reply); const response = client.callTool({ name, arguments: arguments_ }); - launched.push({ release: reply.resolve, response }); - await awaitAcknowledgement(received.promise, response, name); + launched.push({ release: reply.release, response }); + await reply.reached(response, name); return { - release: reply.resolve, + release: reply.release, isError: async () => (await response).isError === true, }; }, diff --git a/tests/boundary/mcp/sessionMcp.test.ts b/tests/boundary/mcp/sessionMcp.test.ts index 7140b932e8..b6f1176582 100644 --- a/tests/boundary/mcp/sessionMcp.test.ts +++ b/tests/boundary/mcp/sessionMcp.test.ts @@ -7,15 +7,12 @@ import { join } from "node:path"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import type { CallToolResult } from "@modelcontextprotocol/server"; import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { z } from "zod"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; -import { - createDeferred, - createTestBinarySession, -} from "../../fixtures/binarySession.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; import type { AnalysisClient, AnalysisProvider, @@ -67,8 +64,7 @@ afterEach(async () => { describe("MCP snapshot lifecycle ordering", () => { it("saves earlier in-flight observations, blocks later calls, and preserves the session on write failure", async () => { directory = await createTestTempDirectory("rea-mcp-snapshot-order-"); - const started = createDeferred(); - const release = createDeferred>(); + const sessionObservation = phaseGate>(); const { mcp, first, closed } = await createSessionMcpHarness( directory, (closed) => { @@ -84,8 +80,7 @@ describe("MCP snapshot lifecycle ordering", () => { ...client(target.path, closed), execute: (name) => { if (name === "health") return Promise.resolve(ok(null)); - started.resolve(); - return release.promise; + return sessionObservation.hold(); }, }), }; @@ -100,12 +95,8 @@ describe("MCP snapshot lifecycle ordering", () => { name: "address_name", arguments: { address: "0x1000", document: "fixture" }, }); - onTestFinished(() => release.resolve(ok(first))); - await awaitAcknowledgement( - started.promise, - observation, - "session observation", - ); + onTestFinished(() => sessionObservation.release(ok(first))); + await sessionObservation.reached(observation, "session observation"); const snapshotPath = join(directory, "analysis.json"); const closing = mcp.callTool({ name: "close_binary", @@ -120,7 +111,7 @@ describe("MCP snapshot lifecycle ordering", () => { .result, ).toMatchObject({ open: true }); expect(closed).toEqual([]); - release.resolve(ok(first)); + sessionObservation.release(ok(first)); expect((await observation).isError).not.toBe(true); expect((await closing).isError).not.toBe(true); expect((await later).isError).toBe(true); @@ -339,14 +330,12 @@ describe("target-free MCP lifecycle", () => { directory = await createTestTempDirectory("rea-mcp-status-readiness-"); const targetPath = join(directory, "target.hop"); await writeFile(targetPath, "fixture target"); - const entered = createDeferred(); - const availability = createDeferred(); + const readiness = phaseGate(); const closed: string[] = []; const session = createTestBinarySession(provider(closed)); const androidAnalysis: AndroidAnalysisPort = { inspectAvailability: () => { - entered.resolve(); - return availability.promise; + return readiness.hold(); }, close: () => Promise.resolve(), execute: () => Promise.resolve(ok(null)), @@ -366,7 +355,7 @@ describe("target-free MCP lifecycle", () => { await mcp.connect(clientTransport); onTestFinished(() => - availability.resolve({ + readiness.release({ status: "available", code: null, reason: null, @@ -374,9 +363,9 @@ describe("target-free MCP lifecycle", () => { }), ); const status = mcp.callTool({ name: "binary_session", arguments: {} }); - await awaitAcknowledgement(entered.promise, status, "provider readiness"); + await readiness.reached(status, "provider readiness"); expect((await session.open(targetPath)).ok).toBe(true); - availability.resolve({ + readiness.release({ status: "available", code: null, reason: null, diff --git a/tests/boundary/mcp/successEvidenceLifecycleMcp.test.ts b/tests/boundary/mcp/successEvidenceLifecycleMcp.test.ts index 793042e316..6beda5708d 100644 --- a/tests/boundary/mcp/successEvidenceLifecycleMcp.test.ts +++ b/tests/boundary/mcp/successEvidenceLifecycleMcp.test.ts @@ -22,7 +22,7 @@ import { createDeferred, createTestBinarySession, } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { parseMcpEvidenceBundle } from "../../fixtures/mcpEvidenceBundle.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; @@ -51,7 +51,7 @@ const fixture = async () => ({ /** Observe the public session admission port without depending on its private bookkeeping. */ const observeLifecycle = (session: BinarySession, events: string[]) => { - const resetEntered = createDeferred(); + const resetEntry = phaseArrival(); let activeCalls = 0; let resetCompleted = false; const originalAdmission = session.withAdmittedAnalysis.bind(session); @@ -70,14 +70,14 @@ const observeLifecycle = (session: BinarySession, events: string[]) => { .spyOn(session, "resetInvestigation") .mockImplementation((options) => { const resetting = originalReset(options); - resetEntered.resolve(); + resetEntry.arrive(); return resetting.finally(() => { resetCompleted = true; events.push("reset-completed"); }); }); return { - resetEntered: resetEntered.promise, + resetEntry, get activeCalls() { return activeCalls; }, @@ -93,10 +93,9 @@ const observeLifecycle = (session: BinarySession, events: string[]) => { /** Hold a genuine successful reply below REA's transport wrapper, before physical send. */ const holdPublication = (events: string[]) => { - const entered = createDeferred(); - const release = createDeferred(); + const sending = phaseGate(); const settled = createDeferred(); - const cancelled = createDeferred(); + const cancellation = phaseArrival(); const originalSend = InMemoryTransport.prototype.send; let heldId: string | number | undefined; let offered: Evidence | undefined; @@ -119,9 +118,8 @@ const holdPublication = (events: string[]) => { ) { heldId = message.id; offered = parseEvidence(message.result.structuredContent); - entered.resolve(); try { - await release.promise; + await sending.hold(); await originalSend.call(this, message, options); events.push("success-published"); } finally { @@ -135,18 +133,18 @@ const holdPublication = (events: string[]) => { message.method === "notifications/cancelled" && message.params?.["requestId"] === heldId ) - cancelled.resolve(); + cancellation.arrive(); }); return { - entered: entered.promise, + reached: sending.reached, settled: settled.promise, - cancelled: cancelled.promise, + cancellation, evidence: () => { if (offered === undefined) throw new Error("No call-path reply reached transport"); return offered; }, - release: () => release.resolve(), + release: () => sending.release(), join: async () => { if (offered !== undefined) await settled.promise; }, @@ -163,19 +161,14 @@ it("keeps successful Evidence admitted through physical publication before a lat const running = test.client.callTool(request); let resetting: Promise | undefined; try { - await awaitAcknowledgement( - publication.entered, - running, - "successful call-path publication", - ); + await publication.reached(running, "successful call-path publication"); const expected = createEvidenceBundle([source, publication.evidence()]); expect(test.session.exportEvidenceBundle()).toEqual(expected); resetting = test.client.callTool({ name: "reset_investigation", arguments: { save_path: checkpoint }, }); - await awaitAcknowledgement( - lifecycle.resetEntered, + await lifecycle.resetEntry.reached( resetting, "reset after successful handler", ); @@ -226,26 +219,20 @@ it("does not release an already-started successful send when SDK cancellation pr ); let resetting: Promise | undefined; try { - await awaitAcknowledgement( - publication.entered, - running, - "cancellable successful publication", - ); + await publication.reached(running, "cancellable successful publication"); const expected = createEvidenceBundle([source, publication.evidence()]); resetting = test.client.callTool({ name: "reset_investigation", arguments: { save_path: checkpoint }, }); - await awaitAcknowledgement( - lifecycle.resetEntered, + await lifecycle.resetEntry.reached( resetting, "reset behind cancellable publication", ); controller.abort( new Error("Caller cancelled an already-started successful send"), ); - await awaitAcknowledgement( - publication.cancelled, + await publication.cancellation.reached( publication.settled, "successful-send cancellation delivery", ); diff --git a/tests/boundary/mcp/wasmArtifactMcp.test.ts b/tests/boundary/mcp/wasmArtifactMcp.test.ts index e498e6b28e..852b0959a6 100644 --- a/tests/boundary/mcp/wasmArtifactMcp.test.ts +++ b/tests/boundary/mcp/wasmArtifactMcp.test.ts @@ -5,7 +5,7 @@ import { } from "../../fixtures/advertisedMcpTool.js"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { afterAll, expect, it, onTestFinished, vi } from "vitest"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { createMcpSchemaValidation } from "../../fixtures/mcpSchemaValidation.js"; import { readFile, realpath, writeFile } from "node:fs/promises"; import { join } from "node:path"; @@ -270,21 +270,13 @@ it.each([undefined, "summary"] as const)( "records complete WASM Evidence when an MCP request is cancelled during provider work (detail=%s)", async (detail) => { const value = wasmArtifactFixture(); - let releaseProvider: (() => void) | undefined; - let providerStarted: (() => void) | undefined; - const started = new Promise((resolve) => { - providerStarted = resolve; - }); - const providerGate = new Promise((resolve) => { - releaseProvider = resolve; - }); + const wasmProviderStart = phaseGate(); let serverSignal: AbortSignal | undefined; const service = new WasmArtifactService({ close: () => Promise.resolve(), inspect: async (_input, options) => { serverSignal = options?.signal; - providerStarted?.(); - await providerGate; + await wasmProviderStart.hold(); expect(options?.signal?.aborted).toBe(true); return ok(wasmArtifactExecution(value)); }, @@ -312,14 +304,14 @@ it.each([undefined, "summary"] as const)( ); const rejected = expect(cancellation).rejects.toThrow(); try { - await awaitAcknowledgement(started, cancellation, "WASM provider start"); + await wasmProviderStart.reached(cancellation, "WASM provider start"); controller.abort(new Error("cancel after provider work starts")); let serverReason: unknown; try { await harness.client.ping(); serverReason = serverSignal?.reason; } finally { - releaseProvider?.(); + wasmProviderStart.release(); } await rejected; expect(inspect).toHaveBeenCalledOnce(); @@ -353,7 +345,7 @@ it.each([undefined, "summary"] as const)( expect(session.evidenceById(partial.evidence_id)).toEqual(partial); } finally { controller.abort(); - releaseProvider?.(); + wasmProviderStart.release(); await cancellation.catch(() => undefined); await rejected.catch(() => undefined); } diff --git a/tests/boundary/mcp/workflowSnapshotReplayMcp.test.ts b/tests/boundary/mcp/workflowSnapshotReplayMcp.test.ts index a6d7487478..f0a069d556 100644 --- a/tests/boundary/mcp/workflowSnapshotReplayMcp.test.ts +++ b/tests/boundary/mcp/workflowSnapshotReplayMcp.test.ts @@ -5,6 +5,11 @@ import { dirname, join } from "node:path"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; import { afterEach, describe, expect, it } from "vitest"; +import { + phaseArrival, + phaseGate, + type PhaseGate, +} from "../../support/lifecycleHarness.js"; import { z } from "zod"; import { @@ -14,12 +19,8 @@ import { } from "../../../src/ports/AnalysisProvider.js"; import type { DirectAnalysisDependencies } from "../../../src/application/DirectAnalysisDependencies.js"; import { runDirectAnalysis } from "../../../src/application/DirectAnalysis.js"; -import { - createDeferred, - createTestBinarySession, -} from "../../fixtures/binarySession.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { createAnalysisProfile } from "../../../src/domain/analysisProfile.js"; import { createEvidence } from "../../../src/domain/evidence.js"; @@ -82,7 +83,7 @@ describe("MCP external command snapshot retirement", () => { arguments: { path: targetPath, command: "iI" }, }); let closeSettled = false; - const closeStarted = createDeferred(); + const snapshotClose = phaseArrival(); let closeRequest: ReturnType | undefined; try { const readyDeadline = Date.now() + 5_000; @@ -101,17 +102,13 @@ describe("MCP external command snapshot retirement", () => { name: "close_binary", arguments: { snapshot_path: snapshotPath }, }, - { onprogress: () => closeStarted.resolve() }, + { onprogress: () => snapshotClose.arrive() }, ) .finally(() => { closeSettled = true; }); // Close queues its transition before sending its first progress event. - await awaitAcknowledgement( - closeStarted.promise, - closeRequest, - "snapshot close progress", - ); + await snapshotClose.reached(closeRequest, "snapshot close progress"); expect(closeSettled).toBe(false); await expect(access(snapshotPath)).rejects.toMatchObject({ code: "ENOENT", @@ -186,15 +183,14 @@ describe("MCP composed workflow target admission", () => { throw new Error("Expected two workflow targets"); const starts: string[] = []; const calls: string[] = []; - const entered = createDeferred(); - const release = createDeferred(); + const providerEntry = phaseGate(); const session = createWorkflowSession( - makeProvider(starts, calls, undefined, { entered, release }), + makeProvider(starts, calls, undefined, providerEntry), ); const { mcp } = await connectWorkflowMcp(session, "admitted-workflow"); - const closeStarted = createDeferred(); + const workflowClose = phaseArrival(); mcp.setNotificationHandler("notifications/progress", () => { - closeStarted.resolve(); + workflowClose.arrive(); }); await openWorkflowTarget(mcp, firstPath); @@ -205,27 +201,19 @@ describe("MCP composed workflow target admission", () => { let closeRequest: ReturnType | undefined; let openRequest: ReturnType | undefined; try { - await awaitAcknowledgement( - entered.promise, - analysisRequest, - "workflow provider entry", - ); + await providerEntry.reached(analysisRequest, "workflow provider entry"); closeRequest = mcp.callTool({ name: "close_binary", arguments: { snapshot_path: snapshotPath }, _meta: { progressToken: "close-race" }, }); - await awaitAcknowledgement( - closeStarted.promise, - closeRequest, - "workflow close progress", - ); + await workflowClose.reached(closeRequest, "workflow close progress"); openRequest = mcp.callTool({ name: "open_binary", arguments: { path: secondPath }, }); } finally { - release.resolve(); + providerEntry.release(); await Promise.allSettled([ analysisRequest, ...(closeRequest === undefined ? [] : [closeRequest]), @@ -925,10 +913,7 @@ const makeProvider = ( starts: string[], calls: string[], liveOperation?: (typeof operations)[number], - pause?: { - readonly entered: ReturnType>; - readonly release: ReturnType>; - }, + pause?: PhaseGate, ): AnalysisProvider => { const capabilities: CapabilityDescriptor[] = operations.map((operation) => ({ operation, @@ -957,8 +942,7 @@ const makeProvider = ( execute: async (operation) => { calls.push(operation); if (operation === "list_documents" && pause !== undefined) { - pause.entered.resolve(); - await pause.release.promise; + await pause.hold(); } const result = operation === "health" diff --git a/tests/boundary/pcap/pcapCommand.test.ts b/tests/boundary/pcap/pcapCommand.test.ts index 635942f48b..fa50991c2a 100644 --- a/tests/boundary/pcap/pcapCommand.test.ts +++ b/tests/boundary/pcap/pcapCommand.test.ts @@ -5,6 +5,7 @@ import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; import type { AnalysisError } from "../../../src/domain/analysisErrorBase.js"; import { expect, it, onTestFinished, test, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { runPcapCommand } from "../../../src/pcap/PcapCommand.js"; import { Deadline } from "../../../src/domain/deadline.js"; import * as ownership from "../../../src/process/ProcessOwnershipObservation.js"; @@ -149,14 +150,7 @@ it.skipIf(process.platform !== "darwin")( "does not spend the tool execution deadline preparing native ownership", async () => { const original = ownership.prepareProcessOwnershipInspection; - let entered!: () => void; - let release!: () => void; - const preparing = new Promise((resolve) => { - entered = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const ownershipPreparation = phaseGate(); let first = true; const prepare = vi .spyOn(ownership, "prepareProcessOwnershipInspection") @@ -164,8 +158,7 @@ it.skipIf(process.platform !== "darwin")( await original(signal); if (first) { first = false; - entered(); - await gate; + await ownershipPreparation.hold(); } }); const timeoutMs = 4321; @@ -177,7 +170,7 @@ it.skipIf(process.platform !== "darwin")( onTestFinished(() => { deadlines.mockRestore(); prepare.mockRestore(); - release(); + ownershipPreparation.release(); }); const pending = runPcapCommand({ platform: HOST_PLATFORM.platform, @@ -196,11 +189,11 @@ it.skipIf(process.platform !== "darwin")( (value) => ({ ok: true as const, value }), (error: unknown) => ({ ok: false as const, error }), ); - await preparing; + await ownershipPreparation.reached(pending, "native ownership preparation"); // Observe before release; assert after the command is joined so a failed // check never leaves it running past the test. const armedWhilePreparing = commandDeadlines(); - release(); + ownershipPreparation.release(); const result = await pending; // The command deadline is armed only once preparation has finished. expect(armedWhilePreparing).toEqual([]); diff --git a/tests/boundary/pcap/pcapProvider.test.ts b/tests/boundary/pcap/pcapProvider.test.ts index b50c6a5d85..945371add0 100644 --- a/tests/boundary/pcap/pcapProvider.test.ts +++ b/tests/boundary/pcap/pcapProvider.test.ts @@ -3,8 +3,8 @@ import { watch } from "node:fs"; import { readFile, symlink, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { expect, onTestFinished, test, vi } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { PcapProvider } from "../../../src/pcap/PcapProvider.js"; import { @@ -804,18 +804,16 @@ fs.writeFileSync(${JSON.stringify(marker)}, 'ready'); setInterval(() => {}, 1000 }); onTestFinished(() => provider.close()); const controller = new AbortController(); - let watcher: ReturnType | undefined; - const ready = new Promise((resolve) => { - watcher = watch(root, (_event, name) => { - if (name === "ready") resolve(); - }); + const toolStart = phaseArrival(); + const watcher = watch(root, (_event, name) => { + if (name === "ready") toolStart.arrive(); }); const pending = provider.execute( { operation: "inspect_pcap_capture", input: { path } }, { signal: controller.signal }, ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(ready, pending, `${phase} tool startup`); + await toolStart.reached(pending, `${phase} tool startup`); controller.abort(new Error("caller cancellation")); const result = await pending; if (result.ok) throw new Error("expected cancellation"); @@ -826,7 +824,7 @@ fs.writeFileSync(${JSON.stringify(marker)}, 'ready'); setInterval(() => {}, 1000 async () => { await pending; }, - () => watcher?.close(), + () => watcher.close(), ]); }, ); @@ -846,7 +844,7 @@ it.each(["change", "cancel"] as const)( { signal: controller.signal }, ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(held.firstRead, pending, "snapshot read"); + await held.reached(pending, "snapshot read"); if (action === "cancel") controller.abort(); else await writeFile(path, "changed source bytes"); held.release(); @@ -879,7 +877,7 @@ it("admits one capture and drains it before close releases resources", async () }); let closing: Promise | undefined; await withVerifierCleanup(async () => { - await awaitAcknowledgement(held.firstRead, pending, "snapshot read"); + await held.reached(pending, "snapshot read"); const concurrent = await provider.execute({ operation: "inspect_pcap_capture", input: { path }, diff --git a/tests/boundary/process/darwinProcessRunTokenReader.test.ts b/tests/boundary/process/darwinProcessRunTokenReader.test.ts index 7727e0b74a..13890ed1ee 100644 --- a/tests/boundary/process/darwinProcessRunTokenReader.test.ts +++ b/tests/boundary/process/darwinProcessRunTokenReader.test.ts @@ -1674,7 +1674,7 @@ const waitForChildReadiness = async ( const exit = once(child, "exit", { signal: listeners.signal }); try { await awaitAcknowledgement( - message.then(() => undefined), + message, exit, "title-mutating child readiness", timeoutMs, diff --git a/tests/boundary/process/packageVerifierCommandSemantics.test.ts b/tests/boundary/process/packageVerifierCommandSemantics.test.ts index 226ac2c56a..9d2b7085de 100644 --- a/tests/boundary/process/packageVerifierCommandSemantics.test.ts +++ b/tests/boundary/process/packageVerifierCommandSemantics.test.ts @@ -11,7 +11,7 @@ import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; import { systemProcessOwnershipHost } from "../../../src/process/ProcessOwnershipObservation.js"; import { liveProcesses } from "../../../src/process/ProcessOwnershipProcessTree.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; const observed = (promise: Promise) => promise.then( @@ -392,19 +392,11 @@ it("retains the same adopted capability and workspace after failed close, then r }); it("rejects a new cleanup owner once workspace release has started", async () => { - let markReleaseStarted!: () => void; - const releaseStarted = new Promise((resolve) => { - markReleaseStarted = resolve; - }); - let unblockWorkspaceClose!: () => void; - const allowRelease = new Promise((resolve) => { - unblockWorkspaceClose = resolve; - }); + const workspaceRelease = phaseGate(); const events: string[] = []; const fixture = await commandFixture(async () => { events.push("workspace-release-started"); - markReleaseStarted(); - await allowRelease; + await workspaceRelease.hold(); events.push("workspace-close-unblocked"); }); // This resource belongs to the caller until adoption succeeds. Keep it @@ -423,7 +415,7 @@ it("rejects a new cleanup owner once workspace release has started", async () => let rejection: unknown; let retained; await withVerifierCleanup(async () => { - await awaitAcknowledgement(releaseStarted, closing, "workspace release"); + await workspaceRelease.reached(closing, "workspace release"); try { fixture.commands.adopt(capability, path); } catch (cause: unknown) { @@ -436,7 +428,7 @@ it("rejects a new cleanup owner once workspace release has started", async () => }; }, [ () => capability.close(), - () => unblockWorkspaceClose(), + () => workspaceRelease.release(), async () => { const result = await closing; if (!result.ok) throw result.cause; diff --git a/tests/boundary/process/processCleanupRetryOwnership.test.ts b/tests/boundary/process/processCleanupRetryOwnership.test.ts index 2a4644eb56..af10da763d 100644 --- a/tests/boundary/process/processCleanupRetryOwnership.test.ts +++ b/tests/boundary/process/processCleanupRetryOwnership.test.ts @@ -3,8 +3,7 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import { setImmediate } from "node:timers/promises"; import { expect, it } from "vitest"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; import { ProcessCaptureError } from "../../../src/process/capture/ProcessCaptureError.js"; @@ -193,21 +192,19 @@ it("keeps mixed root errors and retry aggregates bound to only unresolved roots" it("joins an already-started release when shutdown begins", async () => { const scope = new ProcessCaptureResourceScope(); const root = await createRoot(); - const entered = createDeferred(); - const unblock = createDeferred(); + const resourceRelease = phaseGate(); let attempts = 0; const releasing = scope.release( cleanupOptions(root, async (path) => { attempts += 1; - entered.resolve(); - await unblock.promise; + await resourceRelease.hold(); await rm(path, { recursive: true }); }), ); let closed = false; let closing: Promise | undefined; try { - await awaitAcknowledgement(entered.promise, releasing, "resource release"); + await resourceRelease.reached(releasing, "resource release"); closing = scope.close().then(() => { closed = true; }); @@ -215,7 +212,7 @@ it("joins an already-started release when shutdown begins", async () => { expect(closed).toBe(false); await expect(stat(root)).resolves.toBeDefined(); } finally { - unblock.resolve(); + resourceRelease.release(); await Promise.allSettled([releasing, ...(closing ? [closing] : [])]); await scope.close(); await rm(root, { recursive: true, force: true }); diff --git a/tests/boundary/process/selectedExecutableCleanup.test.ts b/tests/boundary/process/selectedExecutableCleanup.test.ts index 5e2ab21ae0..ec4f253a6b 100644 --- a/tests/boundary/process/selectedExecutableCleanup.test.ts +++ b/tests/boundary/process/selectedExecutableCleanup.test.ts @@ -5,7 +5,7 @@ import { join } from "node:path"; import { afterEach, expect, it, vi } from "vitest"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; const injected = vi.hoisted(() => ({ path: "", @@ -255,14 +255,7 @@ it.each([ if (systemError) Object.assign(primary, { code: "EIO", syscall: "read" }); const reason = { request: "cancel while the descriptor read is pending" }; const controller = new AbortController(); - let enter!: () => void; - let release!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const pending = new Promise((resolve) => { - release = resolve; - }); + const selectedExecutableRead = phaseGate(); injected.path = path; injected.closeFailure = closeDenied ? new Error("descriptor close denied after failed read") @@ -272,8 +265,7 @@ it.each([ open: async (selected: string, flags: number) => { const handle = await open(selected, flags); handle.read = async () => { - enter(); - await pending; + await selectedExecutableRead.hold(); throw primary; }; return handle; @@ -287,9 +279,9 @@ it.each([ ), ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(entered, reading, "selected executable read"); + await selectedExecutableRead.reached(reading, "selected executable read"); controller.abort(reason); - release(); + selectedExecutableRead.release(); const failure = await reading; expect(failure.cause).toBe(primary); expect(failure.outcome).toMatchObject({ kind: "failed", cause: primary }); @@ -316,7 +308,7 @@ it.each([ await scope.close(); }, [ () => controller.abort(), - release, + selectedExecutableRead.release, async () => { await reading; }, diff --git a/tests/boundary/process/verifierArtifactScope.test.ts b/tests/boundary/process/verifierArtifactScope.test.ts index fe33f99920..c82a47cbb4 100644 --- a/tests/boundary/process/verifierArtifactScope.test.ts +++ b/tests/boundary/process/verifierArtifactScope.test.ts @@ -4,7 +4,7 @@ import { withVerifierArtifactScope, } from "../../../scripts/lib/verifier-artifact-scope.mjs"; import type { ArtifactResourceScope } from "../../../src/resources/ArtifactResourceScope.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; it("retains the exact scope for retry and preserves the operation failure", async () => { const primary = new Error("analysis failed"); @@ -55,22 +55,14 @@ it("retains cleanup authority when the operation succeeds", async () => { it("finishes every close hook when cancellation arrives during final cleanup", async () => { const controller = new AbortController(); const cleanup = new Error("first close failed"); - let release: (() => void) | undefined; - let entered: (() => void) | undefined; - const started = new Promise((resolve) => { - entered = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const verifierArtifactCloseHook = phaseGate(); const calls: string[] = []; let attempts = 0; const operation = withVerifierArtifactScope(async (scope) => { scope.addCloseHook(async () => { calls.push("first"); if (++attempts === 1) { - entered?.(); - await gate; + await verifierArtifactCloseHook.hold(); if (controller.signal.aborted) throw cleanup; } }); @@ -80,15 +72,14 @@ it("finishes every close hook when cancellation arrives during final cleanup", a return "finished"; }); try { - await awaitAcknowledgement( - started, + await verifierArtifactCloseHook.reached( operation, "verifier artifact close hook", ); controller.abort(); } finally { // Release and join the parked cleanup even when the boundary is missed. - release?.(); + verifierArtifactCloseHook.release(); await operation.catch(() => undefined); } let failure: unknown; diff --git a/tests/boundary/process/verifierTerminalOwner.test.ts b/tests/boundary/process/verifierTerminalOwner.test.ts index 9c51fe89e9..6bae128e2f 100644 --- a/tests/boundary/process/verifierTerminalOwner.test.ts +++ b/tests/boundary/process/verifierTerminalOwner.test.ts @@ -21,7 +21,7 @@ import { import { systemProcessOwnershipHost } from "../../../src/process/ProcessOwnershipObservation.js"; import { liveProcesses } from "../../../src/process/ProcessOwnershipProcessTree.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; type Outcome = | { readonly ok: true; readonly value: Value } @@ -33,19 +33,6 @@ const observed = (promise: Promise): Promise> => (cause: unknown) => ({ ok: false, cause }), ); -const deferred = () => { - let resolve!: () => void; - const promise = new Promise((finish) => { - resolve = finish; - }); - return { promise, resolve }; -}; - -const waitForBoundary = ( - boundary: Promise, - running: Promise>, -) => awaitAcknowledgement(boundary, running, "terminal lifecycle"); - const terminalFixture = async () => { const parent = await createTestTempDirectory("rea-verifier-terminal-"); const path = join(parent, "workspace"); @@ -113,16 +100,16 @@ const expectReleased = ( }; const observeClose = (owner: VerifierCleanupOwner) => { - const entered = deferred(); + const entered = phaseArrival(); const original = owner.close; const spy = vi.spyOn(owner, "close").mockImplementation(function ( this: VerifierCleanupOwner, ) { const closing = original.call(this); - entered.resolve(); + entered.arrive(); return closing; }); - return { entered: entered.promise, restore: () => spy.mockRestore() }; + return { entered, restore: () => spy.mockRestore() }; }; const posix = it.skipIf(process.platform === "win32"); @@ -186,7 +173,7 @@ posix( "cancels an acknowledged active terminal and joins it before workspace removal", async () => { const fixture = await terminalFixture(); - const ready = deferred(); + const ready = phaseArrival(); const source = 'process.stdout.write("__PID__" + process.pid + "\\n"); setInterval(() => {}, 1000); setTimeout(() => process.exit(0), 10000);'; const running = observed( @@ -198,7 +185,7 @@ posix( const match = /__PID__(\d+)\r?\n/u.exec(output); if (match !== null) { fixture.pids.add(Number(match[1])); - ready.resolve(); + ready.arrive(); } }, }, @@ -207,7 +194,7 @@ posix( ); let outcome: Outcome | undefined; try { - await waitForBoundary(ready.promise, running); + await ready.reached(running, "terminal readiness"); await fixture.commands.close(); outcome = await running; } finally { @@ -333,8 +320,7 @@ posix( "selects cancellation while completed-child cleanup is pending and joins that same attempt", async () => { const fixture = await terminalFixture(); - const cleanupEntered = deferred(); - const allowCleanup = deferred(); + const childCleanup = phaseGate(); let attempts = 0; const running = observed( runOwnedVerifierTerminal( @@ -345,8 +331,7 @@ posix( { cleanupProcessGroup: async (ownership) => { attempts += 1; - cleanupEntered.resolve(); - await allowCleanup.promise; + await childCleanup.hold(); return fixture.cleanup(ownership); }, }, @@ -356,17 +341,17 @@ posix( let closing: Promise> | undefined; let outcome: Outcome | undefined; await withVerifierCleanup(async () => { - await waitForBoundary(cleanupEntered.promise, running); + await childCleanup.reached(running, "completed-child cleanup"); const owner = fixture.adopted[0]; if (owner === undefined) throw new Error("Terminal was not adopted"); closeObservation = observeClose(owner); closing = observed(fixture.commands.close()); - await waitForBoundary(closeObservation.entered, closing); - allowCleanup.resolve(); + await closeObservation.entered.reached(closing, "owner close"); + childCleanup.release(); expect(await closing).toEqual({ ok: true, value: undefined }); outcome = await running; }, [ - () => allowCleanup.resolve(), + () => childCleanup.release(), () => fixture.commands.close(), async () => { await running; @@ -388,8 +373,7 @@ posix( "joins a delayed native-module load without spawning after cancellation", async () => { const fixture = await terminalFixture(); - const loadEntered = deferred(); - const allowLoad = deferred(); + const ptyLoad = phaseGate(); let spawns = 0; let cleanups = 0; const running = observed( @@ -401,8 +385,7 @@ posix( { loadPty: async () => { const pty = await import("@lydell/node-pty"); - loadEntered.resolve(); - await allowLoad.promise; + await ptyLoad.hold(); return { ...pty, spawn(...args: Parameters) { @@ -422,17 +405,17 @@ posix( let closing: Promise> | undefined; let outcome: Outcome | undefined; await withVerifierCleanup(async () => { - await waitForBoundary(loadEntered.promise, running); + await ptyLoad.reached(running, "native-module load"); const owner = fixture.adopted[0]; if (owner === undefined) throw new Error("Terminal was not adopted"); closeObservation = observeClose(owner); closing = observed(fixture.commands.close()); - await waitForBoundary(closeObservation.entered, closing); - allowLoad.resolve(); + await closeObservation.entered.reached(closing, "owner close"); + ptyLoad.release(); expect(await closing).toEqual({ ok: true, value: undefined }); outcome = await running; }, [ - () => allowLoad.resolve(), + () => ptyLoad.release(), () => fixture.commands.close(), async () => { await running; diff --git a/tests/boundary/providers/RizinDebugSessionCoverage.part3.test.ts b/tests/boundary/providers/RizinDebugSessionCoverage.part3.test.ts index 55ed424ebe..196ea9a96a 100644 --- a/tests/boundary/providers/RizinDebugSessionCoverage.part3.test.ts +++ b/tests/boundary/providers/RizinDebugSessionCoverage.part3.test.ts @@ -1,6 +1,6 @@ import { afterEach, expect, it, vi } from "vitest"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; import { stopOwnedDebuggerProcess } from "../../../src/process/ownedDebuggerSession.js"; import { rizinTestInferiorTty } from "./RizinTestInferiorTty.js"; @@ -510,14 +510,7 @@ it.skipIf(process.platform === "win32").each([ async ({ stage, incomplete }) => { const controller = new AbortController(); const reason = { boundary: "final cleanup" }; - let enterStop!: () => void; - const entered = new Promise((resolve) => { - enterStop = resolve; - }); - let releaseStop!: () => void; - const released = new Promise((resolve) => { - releaseStop = resolve; - }); + const debuggerFinalCleanup = phaseGate(); let stopping = true; const injected = createInjectedProcess({ onWrite: (_text, control) => { @@ -534,8 +527,7 @@ it.skipIf(process.platform === "win32").each([ { stopProcess: async () => { if (stopping) { - enterStop(); - await released; + await debuggerFinalCleanup.hold(); } return incomplete && stopping ? { status: "incomplete", reason: "stop settlement pending" } @@ -554,9 +546,9 @@ it.skipIf(process.platform === "win32").each([ controller.signal, ); await withVerifierCleanup(async () => { - await awaitAcknowledgement(entered, pending, "debugger final cleanup"); + await debuggerFinalCleanup.reached(pending, "debugger final cleanup"); controller.abort(reason); - releaseStop(); + debuggerFinalCleanup.release(); const result = await pending; expect(result.ok).toBe(false); if (result.ok) return; @@ -575,7 +567,7 @@ it.skipIf(process.platform === "win32").each([ expect(result.error.cleanupIncomplete).toBe(false); } }, [ - releaseStop, + debuggerFinalCleanup.release, async () => { await pending; }, diff --git a/tests/boundary/providers/RizinDebugSessionReviewRegressions.test.ts b/tests/boundary/providers/RizinDebugSessionReviewRegressions.test.ts index cc663d6dca..134016568c 100644 --- a/tests/boundary/providers/RizinDebugSessionReviewRegressions.test.ts +++ b/tests/boundary/providers/RizinDebugSessionReviewRegressions.test.ts @@ -4,6 +4,7 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, expect, it } from "vitest"; +import { phaseArrival } from "../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; import { RizinDebugSessionManager } from "../../../src/rizin/RizinDebugSessionManager.js"; @@ -14,8 +15,6 @@ import { import { evidenceSchema } from "../../../src/domain/evidence.js"; import { OwnerCancellation } from "../../../src/domain/analysisErrorCore.js"; import { absoluteCallerPath } from "../../../src/filesystem/callerPath.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { createRizinTestManager, rizinTestInferiorTty, @@ -151,7 +150,7 @@ process.stdin.on("data", (chunk) => { it.skipIf(process.platform === "win32")( "aborts an in-flight Rizin start as owner-closed when the manager closes", async () => { - const spawnEntered = createDeferred(); + const rizinSpawn = phaseArrival(); const manager = new RizinDebugSessionManager(process.env, { platform: "linux", // Ownership preparation that only an abort of the start ends. @@ -162,7 +161,7 @@ it.skipIf(process.platform === "win32")( () => reject(options.signal?.reason), { once: true }, ); - spawnEntered.resolve(); + rizinSpawn.arrive(); }), }); managers.push(manager); @@ -170,7 +169,7 @@ it.skipIf(process.platform === "win32")( path: "/tmp/fixture.bin", inferior_tty: await rizinTestInferiorTty(), }); - await awaitAcknowledgement(spawnEntered.promise, starting, "Rizin spawn"); + await rizinSpawn.reached(starting, "Rizin spawn"); await manager.closeAll(); const started = await starting; @@ -819,13 +818,13 @@ it.skipIf(process.platform === "win32")( `#!/usr/bin/env node\nprocess.stdin.resume();\nsetInterval(() => {}, 1000);\n`, ); await chmod(provider, 0o700); - const spawned = createDeferred(); + const rizinSpawn = phaseArrival(); const manager = createRizinTestManager( { REA_RIZIN_COMMAND: provider }, { spawnProcess: async (options) => { const launched = await spawnOwnedProviderProcess(options); - spawned.resolve(); + rizinSpawn.arrive(); return launched; }, }, @@ -837,7 +836,7 @@ it.skipIf(process.platform === "win32")( controller.signal, ); const started = await withVerifierCleanup(async () => { - await awaitAcknowledgement(spawned.promise, starting, "Rizin spawn"); + await rizinSpawn.reached(starting, "Rizin spawn"); controller.abort(); return await starting; }, [ diff --git a/tests/boundary/providers/ghidra/ghidraCheckpointLifecycle.test.ts b/tests/boundary/providers/ghidra/ghidraCheckpointLifecycle.test.ts index ea9bba9ac2..0edffa6b6a 100644 --- a/tests/boundary/providers/ghidra/ghidraCheckpointLifecycle.test.ts +++ b/tests/boundary/providers/ghidra/ghidraCheckpointLifecycle.test.ts @@ -17,7 +17,6 @@ import type { BridgeMaxReplyBytes } from "../../../../src/config/bridgeMaxReplyB import { ConfigurationError } from "../../../../src/domain/configurationErrors.js"; import { resolveGhidraCheckpoint } from "../../../../src/ghidra/GhidraCheckpoint.js"; import { GhidraFixtureLauncher } from "./ghidraClient.fixture.js"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; vi.mock("node:fs/promises", async (importOriginal) => { const actual = await importOriginal(); @@ -207,11 +206,7 @@ it.skipIf(process.platform === "win32")( name: "changed", }); const closing = f.client.close(); - await awaitAcknowledgement( - f.launcher.checkpointHeld, - closing, - "final checkpoint", - ); + await f.launcher.checkpointHold.reached(closing, "final checkpoint"); expect(f.launcher.processes[0]!.exitCode).toBeNull(); const selection = await resolveGhidraCheckpoint( f.root, @@ -280,11 +275,7 @@ it.skipIf(process.platform === "win32")( const first = f.client.start(abort.signal), peer = f.client.start(); const child = await f.launcher.started; - await awaitAcknowledgement( - f.launcher.checkpointHeld, - peer, - "initial checkpoint", - ); + await f.launcher.checkpointHold.reached(peer, "initial checkpoint"); abort.abort("only this waiter"); expect((await first).ok).toBe(false); child.send("release_checkpoint"); @@ -300,11 +291,7 @@ it.skipIf(process.platform === "win32")( abort = new AbortController(); const starting = f.client.start(abort.signal), child = await f.launcher.started; - await awaitAcknowledgement( - f.launcher.checkpointHeld, - starting, - "initial checkpoint", - ); + await f.launcher.checkpointHold.reached(starting, "initial checkpoint"); abort.abort("last waiter"); expect((await starting).ok).toBe(false); expect((await f.client.close()).ok).toBe(true); diff --git a/tests/boundary/providers/ghidra/ghidraClient.fixture.ts b/tests/boundary/providers/ghidra/ghidraClient.fixture.ts index 3c185424db..736936ac01 100644 --- a/tests/boundary/providers/ghidra/ghidraClient.fixture.ts +++ b/tests/boundary/providers/ghidra/ghidraClient.fixture.ts @@ -8,6 +8,7 @@ import type { GhidraLaunchSession, GhidraLauncher, } from "../../../../src/ghidra/GhidraLauncher.js"; +import { phaseArrival } from "../../../support/lifecycleHarness.js"; /** Shared real-socket producer for Ghidra client and public MCP regressions. */ export const ghidraFixturePath = fileURLToPath( @@ -71,10 +72,8 @@ export class GhidraFixtureLauncher implements GhidraLauncher { readonly processes: ChildProcess[] = []; readonly requests: string[] = []; readonly packedPrograms: GhidraLaunchSession["packedProgram"][] = []; - #notifyCheckpointHeld: (() => void) | undefined; - readonly checkpointHeld = new Promise((resolve) => { - this.#notifyCheckpointHeld = resolve; - }); + /** The fixture child holds its checkpoint request open (an IPC event). */ + readonly checkpointHold = phaseArrival(); constructor(readonly mode: FixtureMode = "success") {} @@ -108,7 +107,7 @@ export class GhidraFixtureLauncher implements GhidraLauncher { "event" in value && value.event === "checkpoint-held" ) - this.#notifyCheckpointHeld?.(); + this.checkpointHold.arrive(); if ( typeof value === "object" && value !== null && diff --git a/tests/boundary/providers/ghidra/ghidraClient.test.ts b/tests/boundary/providers/ghidra/ghidraClient.test.ts index 7bbbf02f6a..e7e081b4bc 100644 --- a/tests/boundary/providers/ghidra/ghidraClient.test.ts +++ b/tests/boundary/providers/ghidra/ghidraClient.test.ts @@ -27,7 +27,7 @@ import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest"; import pino from "pino"; import { ConfigurationError } from "../../../../src/domain/configurationErrors.js"; import { withVerifierCleanup } from "../../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../../support/lifecycleHarness.js"; import type { Logger } from "pino"; import type { ProgressUpdate } from "../../../../src/ports/ProgressReporter.js"; @@ -217,19 +217,11 @@ it("reports unknown startup work and stops notifications when cancellation relea it("keeps one shared startup despite a failed progress sink and stops reports after readiness", async () => { vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] }); const launcher = new FixtureLauncher(); - let releaseLaunch: (() => void) | undefined; - let markLaunchPending: (() => void) | undefined; - const launchPending = new Promise((resolve) => { - markLaunchPending = resolve; - }); - const launchGate = new Promise((resolve) => { - releaseLaunch = resolve; - }); + const sharedStartup = phaseGate(); const client = clientFor( { async launch(session) { - markLaunchPending?.(); - await launchGate; + await sharedStartup.hold(); return launcher.launch(session); }, }, @@ -243,10 +235,10 @@ it("keeps one shared startup despite a failed progress sink and stops reports af }, }); const concurrent = client.start(); - await launchPending; + await sharedStartup.reached(started, "shared Ghidra launch"); await vi.advanceTimersByTimeAsync(10_000); expect(reports).toBe(1); - releaseLaunch?.(); + sharedStartup.release(); await expect(started).resolves.toMatchObject({ ok: true }); await expect(concurrent).resolves.toMatchObject({ ok: true }); expect(launcher.processes).toHaveLength(1); @@ -601,13 +593,7 @@ it("joins a snapshot read before closing its descriptor and runtime", async () = const probe = await open(fixturePath, "r"); const prototype = Object.getPrototypeOf(probe) as FileHandle; await probe.close(); - let markRead!: () => void, resume!: () => void; - const reading = new Promise((resolve) => { - markRead = resolve; - }); - const gate = new Promise((resolve) => { - resume = resolve; - }); + const snapshotRead = phaseGate(); let captured: FileHandle | undefined; const original = prototype.read; const read = vi @@ -617,19 +603,18 @@ it("joins a snapshot read before closing its descriptor and runtime", async () = ...args: Parameters ) { captured = this; - markRead(); - await gate; + await snapshotRead.hold(); return Reflect.apply(original, this, args); }); let pending: ReturnType | undefined; onTestFinished(async () => { - resume(); + snapshotRead.release(); await pending; read.mockRestore(); await client.close(); }); pending = client.hashTargetSnapshot(); - await reading; + await snapshotRead.reached(pending, "target snapshot read"); const closing = client.close(); await childClosed; // Cross the event-loop phase after the owned child closed, rather than @@ -639,7 +624,7 @@ it("joins a snapshot read before closing its descriptor and runtime", async () = const root = launcher.runtimeRoots[0]; if (root === undefined) throw new Error("Missing runtime root"); await expect(access(root)).resolves.toBeUndefined(); - resume(); + snapshotRead.release(); expect((await pending).ok).toBe(true); expect((await closing).ok).toBe(true); expect(captured?.fd).toBe(-1); @@ -1221,20 +1206,12 @@ describe("GhidraClient", () => { }); it("reports owner closure to live startup callers without cancelling their signals", async () => { - let entered: (() => void) | undefined; - let release: (() => void) | undefined; - const pending = new Promise((resolve) => { - entered = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const startupLineage = phaseGate(); const original = ProviderRunLineage.prototype.observe; const observe = vi .spyOn(ProviderRunLineage.prototype, "observe") .mockImplementationOnce(async function (this: ProviderRunLineage, launch) { - entered?.(); - await gate; + await startupLineage.hold(); await original.call(this, launch); }); const client = clientFor(new FixtureLauncher(), { @@ -1243,13 +1220,9 @@ it("reports owner closure to live startup callers without cancelling their signa const controllers = [new AbortController(), new AbortController()]; const waits = controllers.map(({ signal }) => client.start(signal)); await withVerifierCleanup(async () => { - await awaitAcknowledgement( - pending, - Promise.race(waits), - "startup observation", - ); + await startupLineage.reached(Promise.race(waits), "startup observation"); const closing = client.close(); - release?.(); + startupLineage.release(); for (const wait of waits) await expect(wait).resolves.toMatchObject({ ok: false, @@ -1262,7 +1235,7 @@ it("reports owner closure to live startup callers without cancelling their signa expect(controllers.every(({ signal }) => !signal.aborted)).toBe(true); expect(client.isReady()).toBe(false); }, [ - () => release?.(), + () => startupLineage.release(), async () => { const result = await client.close(); if (!result.ok) throw result.error; @@ -1365,20 +1338,12 @@ it.skipIf(process.platform === "win32")( it.each([0, 1])( "cancels startup waiter %s without interrupting its peer", async (cancelledIndex) => { - let entered: (() => void) | undefined; - let release: (() => void) | undefined; - const launchPending = new Promise((resolve) => { - entered = resolve; - }); - const launchGate = new Promise((resolve) => { - release = resolve; - }); + const sharedLaunch = phaseGate(); const launcher = new FixtureLauncher(); const client = clientFor( { async launch(session) { - entered?.(); - await launchGate; + await sharedLaunch.hold(); return launcher.launch(session); }, }, @@ -1387,7 +1352,7 @@ it.each([0, 1])( const controllers = [new AbortController(), new AbortController()]; const waits = controllers.map(({ signal }) => client.start(signal)); try { - await launchPending; + await sharedLaunch.reached(Promise.race(waits), "shared Ghidra launch"); let cancelled: Awaited> | undefined; void waits[cancelledIndex]?.then((result) => { cancelled = result; @@ -1400,14 +1365,14 @@ it.each([0, 1])( }), ); expect(launcher.processes).toHaveLength(0); - release?.(); + sharedLaunch.release(); await expect(waits[1 - cancelledIndex]).resolves.toMatchObject({ ok: true, }); expect(launcher.processes).toHaveLength(1); expect(client.isReady()).toBe(true); } finally { - release?.(); + sharedLaunch.release(); await Promise.all(waits); } }, @@ -1443,14 +1408,7 @@ it("retains startup failure and cleans up when lineage observation rejects", asy }); it("cleans up when the final waiter cancels during lineage observation", async () => { - let markObservationPending: (() => void) | undefined; - const observationPending = new Promise((resolve) => { - markObservationPending = resolve; - }); - let releaseObservation: (() => void) | undefined; - const observationGate = new Promise((resolve) => { - releaseObservation = resolve; - }); + const lineageObservation = phaseGate(); const originalObserve = ProviderRunLineage.prototype.observe; const observe = vi.spyOn(ProviderRunLineage.prototype, "observe"); onTestFinished(() => observe.mockRestore()); @@ -1458,8 +1416,7 @@ it("cleans up when the final waiter cancels during lineage observation", async ( this: ProviderRunLineage, launch, ) { - markObservationPending?.(); - await observationGate; + await lineageObservation.hold(); return await originalObserve.call(this, launch); }); @@ -1467,12 +1424,12 @@ it("cleans up when the final waiter cancels during lineage observation", async ( const client = clientFor(launcher); const controller = new AbortController(); const starting = client.start(controller.signal); - await observationPending; + await lineageObservation.reached(starting, "lineage observation"); const child = launcher.processes[0]; if (child === undefined) throw new Error("fixture child was not launched"); controller.abort(); - releaseObservation?.(); + lineageObservation.release(); await expect(starting).resolves.toMatchObject({ ok: false, @@ -1491,14 +1448,7 @@ it("cleans up when the final waiter cancels during lineage observation", async ( }); it("cancels a retry waiter without taking ownership of startup cleanup", async () => { - let markLaunchPending: (() => void) | undefined; - const launchPending = new Promise((resolve) => { - markLaunchPending = resolve; - }); - let releaseLaunch: (() => void) | undefined; - const launchGate = new Promise((resolve) => { - releaseLaunch = resolve; - }); + const retryLaunch = phaseGate(); let markStartupAborted: (() => void) | undefined; const startupAborted = new Promise((resolve) => { markStartupAborted = resolve; @@ -1509,8 +1459,7 @@ it("cancels a retry waiter without taking ownership of startup cleanup", async ( options?.signal?.addEventListener("abort", () => markStartupAborted?.(), { once: true, }); - markLaunchPending?.(); - await launchGate; + await retryLaunch.hold(); return launcher.launch(session); }, }); @@ -1518,7 +1467,7 @@ it("cancels a retry waiter without taking ownership of startup cleanup", async ( const first = client.start(firstController.signal); let retry: ReturnType | undefined; try { - await launchPending; + await retryLaunch.reached(first, "retried Ghidra launch"); firstController.abort(); // The retry starts after the shared owner has observed the final departure. await startupAborted; @@ -1531,7 +1480,7 @@ it("cancels a retry waiter without taking ownership of startup cleanup", async ( error: { kind: "cancelled" }, }); } finally { - releaseLaunch?.(); + retryLaunch.release(); await Promise.allSettled([first, retry]); } await expect(first).resolves.toMatchObject({ @@ -2244,14 +2193,7 @@ it.each([ it("retains the identity refusal when cancellation arrives during final startup cleanup", async () => { const fixture = new FixtureLauncher("import_identity_mismatch"); - let entered: (() => void) | undefined; - let release: (() => void) | undefined; - const cleanupStarted = new Promise((resolve) => { - entered = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const identityRefusalCleanup = phaseGate(); const launcher: GhidraLauncher = { launch: async (session) => { const launched = await fixture.launch(session); @@ -2259,8 +2201,7 @@ it("retains the identity refusal when cancellation arrives during final startup return ok({ ...launched.value, cleanup: async () => { - entered?.(); - await gate; + await identityRefusalCleanup.hold(); return { cleaned: true as const, signaled: false }; }, }); @@ -2270,13 +2211,9 @@ it("retains the identity refusal when cancellation arrives during final startup const controller = new AbortController(); const started = client.start(controller.signal); await withVerifierCleanup(async () => { - await awaitAcknowledgement( - cleanupStarted, - started, - "identity refusal cleanup", - ); + await identityRefusalCleanup.reached(started, "identity refusal cleanup"); controller.abort("cancel during final cleanup"); - release?.(); + identityRefusalCleanup.release(); const result = await started; if (result.ok) throw new Error("Expected the earlier identity refusal"); expect(result.error.kind).toBe("admission"); @@ -2288,7 +2225,7 @@ it("retains the identity refusal when cancellation arrives during final startup code: "ENOENT", }); }, [ - () => release?.(), + () => identityRefusalCleanup.release(), async () => { await client.close(); }, diff --git a/tests/boundary/providers/hopper/hopperClient.health.test.ts b/tests/boundary/providers/hopper/hopperClient.health.test.ts index 274bf7a7da..d5e0eab15f 100644 --- a/tests/boundary/providers/hopper/hopperClient.health.test.ts +++ b/tests/boundary/providers/hopper/hopperClient.health.test.ts @@ -6,7 +6,7 @@ import { EventEmitter } from "node:events"; import { PassThrough } from "node:stream"; import { describe, expect, it, onTestFinished } from "vitest"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../../support/lifecycleHarness.js"; import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js"; import { ok } from "../../../../src/domain/result.js"; @@ -75,38 +75,30 @@ const start = async (owned: boolean) => { it("reports launch work until the first authenticated handshake completes", async () => { const fixture = new HopperFixtureLauncher(undefined, "quiet", "gated"); - let enterLaunch: (() => void) | undefined; - let releaseLaunch: (() => void) | undefined; - const entered = new Promise((resolve) => { - enterLaunch = resolve; - }); - const release = new Promise((resolve) => { - releaseLaunch = resolve; - }); + const hopperLaunch = phaseGate(); const client = new HopperClient({ replyContracts: transportReplyContracts, startupTimeoutMs: 10_000, launcher: { async launch(session) { - enterLaunch?.(); - await release; + await hopperLaunch.hold(); return fixture.launch(session); }, }, }); onTestFinished(async () => { - releaseLaunch?.(); + hopperLaunch.release(); await client.close(); }); const starting = client.callTool("current_document"); - await awaitAcknowledgement(entered, starting, "Hopper launch"); + await hopperLaunch.reached(starting, "Hopper launch"); expect(client.requestActivity()).toBeNull(); expect(client.operationHealth()).toMatchObject({ state: "busy", stage: "launch", retryAction: "wait", }); - releaseLaunch?.(); + hopperLaunch.release(); const handshake = await fixture.waitForRequest("health"); expect(client.operationHealth()).toMatchObject({ state: "busy", diff --git a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts index 6270d2277a..929b5ba7ed 100644 --- a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts +++ b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts @@ -10,9 +10,12 @@ import { createHash } from "node:crypto"; import { join } from "node:path"; import { afterEach, expect, it, vi } from "vitest"; +import { + phaseGate, + type PhaseGate, +} from "../../../support/lifecycleHarness.js"; import { AnalysisError } from "../../../../src/domain/analysisErrorBase.js"; import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; import { ArtifactResourceScope } from "../../../../src/resources/ArtifactResourceScope.js"; import type { RetainedResourceScope } from "../../../../src/ports/AnalysisProvider.js"; @@ -42,9 +45,7 @@ const injected = vi.hoisted(() => ({ abort: () => void; } | undefined, - commandHashClose: undefined as - | { entered: () => void; release: Promise } - | undefined, + commandHashClose: undefined as PhaseGate | undefined, handles: [] as import("node:fs/promises").FileHandle[], nativeCloses: new Map< import("node:fs/promises").FileHandle, @@ -176,8 +177,7 @@ vi.mock("../../../../src/filesystem/RegularFile.js", async (importOriginal) => { injected.closeCalls += 1; if (commandHashMatched && commandHashClose !== undefined) { commandHashMatched = false; - commandHashClose.entered(); - await commandHashClose.release; + await commandHashClose.hold(); } if (abortCloseMatched) abortOnClose?.abort(); if ( @@ -221,31 +221,24 @@ it.skipIf(process.platform === "win32").each([ const fixture = await session("rea-kuna-draining-hash-close-"); const client = fixture.open(); await run(client, "health"); - let entered!: () => void; - let release!: () => void; - const closeEntered = new Promise((resolve) => { - entered = resolve; - }); - const closeRelease = new Promise((resolve) => { - release = resolve; - }); + const hashClose = phaseGate(); const controller = new AbortController(); const reason = { caller: "abandoned string scan" }; injected.installationPath = fixture.kuna; injected.closeCalls = 0; - injected.commandHashClose = { entered, release: closeRelease }; + injected.commandHashClose = hashClose; const first = client.execute(operation, input, { signal: controller.signal, }); let second: ReturnType | undefined; try { - await awaitAcknowledgement(closeEntered, first, "Kuna hash close"); + await hashClose.reached(first, "Kuna hash close"); injected.holdCloseFailures = true; controller.abort(reason); await new Promise((resolve) => setImmediate(resolve)); second = client.execute(operation, input); await new Promise((resolve) => setImmediate(resolve)); - release(); + hashClose.release(); const firstResult = await first; const secondResult = await second; if (firstResult.ok || secondResult.ok) @@ -278,7 +271,7 @@ it.skipIf(process.platform === "win32").each([ ), ).toHaveLength(1); } finally { - release(); + hashClose.release(); controller.abort(); injected.releaseCloseFailures = true; await Promise.allSettled([first, second]); diff --git a/tests/boundary/providers/kuna/kunaIndependentDecompileMcp.test.ts b/tests/boundary/providers/kuna/kunaIndependentDecompileMcp.test.ts index 3369bea2b8..cc89962b2d 100644 --- a/tests/boundary/providers/kuna/kunaIndependentDecompileMcp.test.ts +++ b/tests/boundary/providers/kuna/kunaIndependentDecompileMcp.test.ts @@ -1,6 +1,7 @@ import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { afterAll, expect, it as test, vi } from "vitest"; +import { phaseArrival } from "../../../support/lifecycleHarness.js"; import { AnalysisProviderRegistry } from "../../../../src/application/binary/AnalysisProviderRegistry.js"; import { composeBinarySession } from "../../../../src/application/binary/BinarySessionComposition.js"; import { parseEvidence } from "../../../../src/domain/evidence.js"; @@ -10,7 +11,6 @@ import { elfNoteFixture } from "../../../../src/native/elf/ElfNotes.fixture.js"; import { createApplicationMcpHarness } from "../../../fixtures/applicationMcpHarness.js"; import { callAdvertisedMcpTool } from "../../../fixtures/advertisedMcpTool.js"; import { createMcpSchemaValidation } from "../../../fixtures/mcpSchemaValidation.js"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; import { fakeKunaCalls, @@ -279,10 +279,7 @@ it("retains the independent run slot until an unproven stop is resolved", async }; expect(failure.error.code).toBe("cleanup_incomplete"); const acquire = KunaRunSlots.prototype.acquire; - let arrived!: () => void; - const admission = new Promise((resolve) => { - arrived = resolve; - }); + const slotAdmission = phaseArrival(); let slotSettled = false; const spy = vi .spyOn(KunaRunSlots.prototype, "acquire") @@ -291,7 +288,7 @@ it("retains the independent run slot until an unproven stop is resolved", async void result.then(() => { slotSettled = true; }); - arrived(); + slotAdmission.arrive(); return result; }); restoreAcquire = () => spy.mockRestore(); @@ -300,11 +297,7 @@ it("retains the independent run slot until an unproven stop is resolved", async { procedure: "main", analysis: "independent_fresh" }, caller.signal, ).catch(() => undefined); - await awaitAcknowledgement( - admission, - queued, - "independent run slot admission", - ); + await slotAdmission.reached(queued, "independent run slot admission"); await new Promise((resolve) => setImmediate(resolve)); expect(slotSettled).toBe(false); expect( diff --git a/tests/boundary/providers/kuna/kunaProjectCache.test.ts b/tests/boundary/providers/kuna/kunaProjectCache.test.ts index 426e262927..bc66195b7d 100644 --- a/tests/boundary/providers/kuna/kunaProjectCache.test.ts +++ b/tests/boundary/providers/kuna/kunaProjectCache.test.ts @@ -28,7 +28,7 @@ import { } from "../../../../src/kuna/KunaProjectCache.js"; import type { KunaExportStatus } from "../../../../src/kuna/KunaProjectExport.js"; import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../../support/lifecycleHarness.js"; import { OwnedFileHandle } from "../../../../src/filesystem/OwnedFileHandle.js"; import { RegularFileCleanupFailure } from "../../../../src/filesystem/OwnedRegularFile.js"; import * as stableFileHash from "../../../../src/filesystem/StableFileHash.js"; @@ -112,16 +112,6 @@ const processGone = (pid: number): boolean => { } }; -const deferred = () => { - let resolve!: (value: T) => void; - let reject!: (cause: unknown) => void; - const promise = new Promise((resolvePromise, rejectPromise) => { - resolve = resolvePromise; - reject = rejectPromise; - }); - return { promise, resolve, reject }; -}; - it.each([1, 2])( "regenerates layout %i once and retires it without touching unrelated cache resources", async (layout) => { @@ -381,10 +371,8 @@ it.each(["success", "failure"] as const)( const warmCache = newCache(installation); const initialCloseFailure = new Error("initial descriptor close failure"); const retryCloseFailure = new Error("concurrent retry close failure"); - const initialClose = deferred(); - const retryGate = deferred(); - const initialCloseEntered = deferred(); - const retryEntered = deferred(); + const initialClose = phaseGate(); + const retryClose = phaseGate(); const closeCounts = new Map(); let retainedOwner: OwnedFileHandle | undefined; let concurrentLookup: Promise | undefined; @@ -396,12 +384,10 @@ it.each(["success", "failure"] as const)( closeCounts.set(this, count); if (count === 1 && retainedOwner === undefined) { retainedOwner = this; - initialCloseEntered.resolve(); - return initialClose.promise; + return initialClose.hold(); } if (this === retainedOwner && count === 2) { - retryEntered.resolve(); - return retryGate.promise.then(async () => { + return retryClose.hold().then(async () => { if (retryOutcome === "failure") throw retryCloseFailure; await closeOwner.call(this); }); @@ -413,28 +399,20 @@ it.each(["success", "failure"] as const)( .lookup(built.value.key) .catch((cause: unknown) => cause); try { - await awaitAcknowledgement( - initialCloseEntered.promise, - firstLookup, - "initial descriptor close", - ); + await initialClose.reached(firstLookup, "initial descriptor close"); initialClose.reject(initialCloseFailure); // The failed descriptor is retained before the first lookup binds its // originating error, so this lookup begins the retry in that window. concurrentLookup = Promise.resolve().then(() => warmCache.lookup(built.value.key).catch((cause: unknown) => cause), ); - await awaitAcknowledgement( - retryEntered.promise, - concurrentLookup, - "descriptor close retry", - ); + await retryClose.reached(concurrentLookup, "descriptor close retry"); const firstFailure = await firstLookup; expect(firstFailure).toBeInstanceOf(ProviderCleanupError); if (!(firstFailure instanceof ProviderCleanupError)) throw firstFailure; expect(firstFailure.cleanupIncomplete).toBe(true); - retryGate.resolve(); + retryClose.release(); if (concurrentLookup === undefined) throw new Error("Concurrent lookup did not start"); const retryResult = await concurrentLookup; @@ -463,8 +441,8 @@ it.each(["success", "failure"] as const)( expect(retryResult.cleanupIncomplete).toBe(false); } } finally { - initialClose.resolve(); - retryGate.resolve(); + initialClose.release(); + retryClose.release(); await Promise.allSettled([ firstLookup, ...(concurrentLookup === undefined ? [] : [concurrentLookup]), @@ -488,8 +466,7 @@ it("resolves a hash failure delivered after its retained owner was released", as ); if (!built.ok) throw built.error; const warmCache = newCache(installation); - const failureRetained = deferred(); - const deliverFailure = deferred(); + const hashFailure = phaseGate(); const hashFile = stableFileHash.observeStableFile; const hash = vi .spyOn(stableFileHash, "observeStableFile") @@ -498,8 +475,7 @@ it("resolves a hash failure delivered after its retained owner was released", as return await hashFile(...args); } catch (cause: unknown) { if (!(cause instanceof RegularFileCleanupFailure)) throw cause; - failureRetained.resolve(); - await deliverFailure.promise; + await hashFailure.hold(); throw cause; } }); @@ -511,17 +487,13 @@ it("resolves a hash failure delivered after its retained owner was released", as .lookup(built.value.key) .catch((cause: unknown) => cause); try { - await awaitAcknowledgement( - failureRetained.promise, - firstLookup, - "retained hash failure", - ); + await hashFailure.reached(firstLookup, "retained hash failure"); expect(warmCache.hasPendingCleanup).toBe(true); expect(await warmCache.lookup(built.value.key)).toMatchObject({ key: built.value.key, }); expect(warmCache.hasPendingCleanup).toBe(false); - deliverFailure.resolve(); + hashFailure.release(); const error = await firstLookup; expect(error).toBeInstanceOf(ProviderCleanupError); if (!(error instanceof ProviderCleanupError)) throw error; @@ -531,7 +503,7 @@ it("resolves a hash failure delivered after its retained owner was released", as expect(error.cause.cleanupCause).toBe(closeCause); expect(error.cause.owner.handle.fd).toBe(-1); } finally { - deliverFailure.resolve(); + hashFailure.release(); await firstLookup; hash.mockRestore(); close.mockRestore(); @@ -1238,8 +1210,7 @@ it("reports an abandoned build's unproven cleanup even after a retry replaced it { project: "hang" }, ); let exports = 0; - const cleanupStarted = deferred(); - const releaseCleanup = deferred(); + const exportCleanup = phaseGate(); const cache = new KunaProjectCache(cacheRoot, { maxBytes: 64 * 1024 ** 2, launcher: async (options) => { @@ -1250,8 +1221,7 @@ it("reports an abandoned build's unproven cleanup even after a retry replaced it return { ...spawned, cleanup: async () => { - cleanupStarted.resolve(); - await releaseCleanup.promise; + await exportCleanup.hold(); await cleanupOwnedProcessGroup(spawned.ownership); return { cleaned: false, reason: "first export unverified" }; }, @@ -1275,11 +1245,7 @@ it("reports an abandoned build's unproven cleanup even after a retry replaced it first.abort(); await firstBuild; stopping = cache.settled(keyOf(installation, input)); - await awaitAcknowledgement( - cleanupStarted.promise, - stopping, - "abandoned export cleanup", - ); + await exportCleanup.reached(stopping, "abandoned export cleanup"); // A retry for the same key starts while the first is still stopping. secondBuild = cache.build( @@ -1292,7 +1258,7 @@ it("reports an abandoned build's unproven cleanup even after a retry replaced it await expect.poll(() => callsOf(kuna, "decompile-project")).toHaveLength(2); second.abort(); await secondBuild; - releaseCleanup.resolve(); + exportCleanup.release(); expect(await cache.close()).toMatchObject({ ok: false, @@ -1301,7 +1267,7 @@ it("reports an abandoned build's unproven cleanup even after a retry replaced it } finally { first.abort(); second.abort(); - releaseCleanup.resolve(); + exportCleanup.release(); await Promise.allSettled([ firstBuild, ...(secondBuild === undefined ? [] : [secondBuild]), diff --git a/tests/boundary/providers/kuna/kunaProvider.test.ts b/tests/boundary/providers/kuna/kunaProvider.test.ts index 40a22ea153..219534ee49 100644 --- a/tests/boundary/providers/kuna/kunaProvider.test.ts +++ b/tests/boundary/providers/kuna/kunaProvider.test.ts @@ -11,7 +11,7 @@ import { import { join } from "node:path"; import { expect, it as test, vi } from "vitest"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../../support/lifecycleHarness.js"; import type { BinaryTarget } from "../../../../src/domain/binaryTargetTypes.js"; import type { JsonValue } from "../../../../src/domain/jsonValue.js"; @@ -112,21 +112,13 @@ it("waits for an aborted pre-session hash before retrying its late close owner", ); const nativeClose = OwnedFileHandle.prototype.close; let closeCalls = 0; - let enteredClose!: () => void; - let releaseClose!: () => void; - const closeEntered = new Promise((resolve) => { - enteredClose = resolve; - }); - const closeGate = new Promise((resolve) => { - releaseClose = resolve; - }); + const hashClose = phaseGate(); const close = vi .spyOn(OwnedFileHandle.prototype, "close") .mockImplementation(async function (this: OwnedFileHandle) { closeCalls += 1; if (closeCalls === 1) { - enteredClose(); - await closeGate; + await hashClose.hold(); } if (closeCalls <= 2) throw new Error("injected Kuna profile close failure"); @@ -143,7 +135,7 @@ it("waits for an aborted pre-session hash before retrying its late close owner", previewSettled = true; return result; }); - await closeEntered; + await hashClose.reached(previewWork, "Kuna profile hash close"); controller.abort(); let closeSettled = false; const closing = binary.close().then((result) => { @@ -154,7 +146,7 @@ it("waits for an aborted pre-session hash before retrying its late close owner", expect(previewSettled).toBe(false); expect(closeSettled).toBe(false); expect(await binary.status()).toMatchObject({ cleanup_pending: true }); - releaseClose(); + hashClose.release(); const preview = await previewWork; expect(preview).toMatchObject({ ok: false, @@ -179,7 +171,7 @@ it("waits for an aborted pre-session hash before retrying its late close owner", expect(preview.error.cleanupIncomplete).toBe(false); expect(firstClose.error.cleanupIncomplete).toBe(false); } finally { - releaseClose(); + hashClose.release(); close.mockRestore(); await binary.close(); } @@ -735,10 +727,7 @@ it("keeps answering pseudocode one function at a time when the export fails", as }); it("keeps an overflow as the primary failure when cancellation arrives during final cleanup", async () => { - let enteredCleanup!: () => void; - let releaseCleanup!: () => void; - const entered = new Promise((resolve) => (enteredCleanup = resolve)); - const released = new Promise((resolve) => (releaseCleanup = resolve)); + const finalCleanup = phaseGate(); const launcher: KunaProcessLauncher = async (options) => { const spawned = await spawnOwnedProviderProcess(options); if (options.arguments[0] !== "decompile") return spawned; @@ -746,8 +735,7 @@ it("keeps an overflow as the primary failure when cancellation arrives during fi ...spawned, cleanup: async () => { const result = await cleanupOwnedProcessGroup(spawned.ownership); - enteredCleanup(); - await released; + await finalCleanup.hold(); return result; }, }; @@ -766,9 +754,9 @@ it("keeps an overflow as the primary failure when cancellation arrives during fi { signal: caller.signal }, ); try { - await awaitAcknowledgement(entered, pending, "Kuna overflow cleanup"); + await finalCleanup.reached(pending, "Kuna overflow cleanup"); caller.abort("cancel during overflow cleanup"); - releaseCleanup(); + finalCleanup.release(); const result = await pending; expect(result.ok).toBe(false); if (!result.ok) @@ -779,7 +767,7 @@ it("keeps an overflow as the primary failure when cancellation arrives during fi }, }); } finally { - releaseCleanup(); + finalCleanup.release(); caller.abort(); await pending; expect(await client.close()).toEqual({ ok: true, value: null }); diff --git a/tests/boundary/providers/kuna/kunaQueryWork.test.ts b/tests/boundary/providers/kuna/kunaQueryWork.test.ts index 218490d081..723d836163 100644 --- a/tests/boundary/providers/kuna/kunaQueryWork.test.ts +++ b/tests/boundary/providers/kuna/kunaQueryWork.test.ts @@ -1,6 +1,6 @@ import { expect, it } from "vitest"; +import { phaseArrival } from "../../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; import { KunaQueryWork } from "../../../../src/kuna/KunaQueryWork.js"; import { KunaRunSlots } from "../../../../src/kuna/KunaRunSlots.js"; @@ -25,23 +25,20 @@ it("does not materialize values for a cancelled queued regex query", async () => own: (promise) => promise, runSlots: new KunaRunSlots(1), }); - let admitted!: () => void; - const ready = new Promise((resolve) => { - admitted = resolve; - }); + const workerAdmission = phaseArrival(); const slow = work.match({ operation: "search_strings", pattern: "^(a+)+$", caseSensitive: true, values: () => { - admitted(); + workerAdmission.arrive(); return [`${"a".repeat(40)}!`]; }, }); const cancelled = new AbortController(); let queued: ReturnType | undefined; await withVerifierCleanup(async () => { - await awaitAcknowledgement(ready, slow, "regex worker admission"); + await workerAdmission.reached(slow, "regex worker admission"); let materialized = false; queued = work.match({ operation: "search_procedures", diff --git a/tests/boundary/providers/kuna/kunaRunOwnership.test.ts b/tests/boundary/providers/kuna/kunaRunOwnership.test.ts index ad97d7e2a3..61fc3c25b2 100644 --- a/tests/boundary/providers/kuna/kunaRunOwnership.test.ts +++ b/tests/boundary/providers/kuna/kunaRunOwnership.test.ts @@ -1,7 +1,7 @@ import { setImmediate } from "node:timers/promises"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; import { expect, it as test, vi } from "vitest"; +import { phaseGate } from "../../../support/lifecycleHarness.js"; import { inspectKunaInstallationOwned as inspectKunaInstallation } from "./kunaResourceScope.js"; import { KunaRunSlots } from "../../../../src/kuna/KunaRunSlots.js"; @@ -11,19 +11,11 @@ import { fakeKunaCalls } from "./fakeKuna.js"; import { run, session, unprovenCleanupLauncher } from "./kunaSessionFixture.js"; const it = test.skipIf(process.platform === "win32"); -const barrier = () => { - let release = () => {}; - const promise = new Promise((resolve) => { - release = resolve; - }); - return { promise, release }; -}; it.each(["procedure_callees", "xrefs"] as const)( "shares foreground admission between a decompile and %s", async (operation) => { - const started = barrier(); - const proceed = barrier(); + const decompileLaunch = phaseGate(); const grants: { owner: KunaRunSlots }[] = []; const acquire = KunaRunSlots.prototype.acquire; const spy = vi @@ -38,8 +30,7 @@ it.each(["procedure_callees", "xrefs"] as const)( {}, async (options) => { if (options.arguments[0] === "decompile") { - started.release(); - await proceed.promise; + await decompileLaunch.hold(); } return spawnOwnedProviderProcess(options); }, @@ -49,11 +40,7 @@ it.each(["procedure_callees", "xrefs"] as const)( const text = run(client, "procedure_pseudo_code", { procedure: "main" }); let reference: ReturnType | undefined; try { - await awaitAcknowledgement( - started.promise, - text, - "Kuna decompile admission", - ); + await decompileLaunch.reached(text, "Kuna decompile admission"); const budget = grants[0]?.owner; expect(budget).toBeDefined(); reference = run( @@ -71,13 +58,13 @@ it.each(["procedure_callees", "xrefs"] as const)( ({ argv }) => argv[0] === "decompile-graph" || argv[0] === "xrefs", ), ).toBe(false); - proceed.release(); + decompileLaunch.release(); expect((await text).result).toContain("single-function"); expect((await reference).result).toEqual([ operation === "xrefs" ? "0x1004" : "0x1040", ]); } finally { - proceed.release(); + decompileLaunch.release(); await Promise.allSettled([text, reference]); await client.close(); spy.mockRestore(); diff --git a/tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts b/tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts index 7c3e777939..12c035a15f 100644 --- a/tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts +++ b/tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts @@ -1,6 +1,6 @@ import { expect, it as test, vi } from "vitest"; import { runWithAnalysisOperationSnapshot } from "../../../../src/domain/analysisOperationSnapshot.js"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival, phaseGate } from "../../../support/lifecycleHarness.js"; import { KunaRunSlots } from "../../../../src/kuna/KunaRunSlots.js"; import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js"; @@ -131,14 +131,14 @@ it("answers a queued request from the export once it finishes first", async () = ); const client = open(); const holder = new AbortController(); - const admission = deferred(); + const admission = phaseArrival(); const acquire = KunaRunSlots.prototype.acquire; let arrivals = 0; const requests = vi .spyOn(KunaRunSlots.prototype, "acquire") .mockImplementation(function (this: KunaRunSlots, signal) { const pending = acquire.call(this, signal); - if (++arrivals === 2) admission.resolve(); + if (++arrivals === 2) admission.arrive(); return pending; }); let queued: ReturnType | undefined; @@ -151,11 +151,7 @@ it("answers a queued request from the export once it finishes first", async () = try { await awaitKunaCommand(kuna, "decompile", holding); queued = client.execute("procedure_pseudo_code", { procedure: "parse" }); - await awaitAcknowledgement( - admission.promise, - queued, - "queued single-function admission", - ); + await admission.reached(queued, "queued single-function admission"); await releaseFakeKunaCommand(kuna, "decompile-project"); const completed = await queued; if (!completed.ok) throw completed.error; @@ -201,7 +197,7 @@ it("keeps the slot of a run whose stop is unproven until close proves it", async ), ).toMatchObject({ ok: false, error: { cleanupIncomplete: true } }); // The timed-out tree may still run, so the next run must not start. - const admission = deferred(); + const admission = phaseArrival(); const acquire = KunaRunSlots.prototype.acquire; let granted = false; const requests = vi @@ -211,7 +207,7 @@ it("keeps the slot of a run whose stop is unproven until close proves it", async void pending.then(() => { granted = true; }); - admission.resolve(); + admission.arrive(); return pending; }); restoreAcquire = () => requests.mockRestore(); @@ -220,11 +216,7 @@ it("keeps the slot of a run whose stop is unproven until close proves it", async { procedure: "parse" }, { signal: waiter.signal }, ); - await awaitAcknowledgement( - admission.promise, - queued, - "retained single-function slot", - ); + await admission.reached(queued, "retained single-function slot"); await new Promise((resolve) => setImmediate(resolve)); expect(granted).toBe(false); expect(await decompilesOf(kuna)).toHaveLength(1); @@ -312,30 +304,18 @@ it("keeps answering repeats from the completed run after the export fails", asyn } }); -const deferred = () => { - let resolve!: (value: T) => void; - let reject!: (reason?: unknown) => void; - const promise = new Promise((res, rej) => { - resolve = res; - reject = rej; - }); - return { promise, resolve, reject }; -}; - it("reports sibling unavailability when fallback observes settled export failure without prior assembly call", async () => { - const exportSettled = deferred(); - exportSettled.promise.catch(() => undefined); + // Held decompile launches continue once the export build settles. + const exportSettled = phaseGate(); const originalBuild = KunaProjectCache.prototype.build; const exportBuild = vi .spyOn(KunaProjectCache.prototype, "build") .mockImplementation(function (this: KunaProjectCache, ...args) { const promise = originalBuild.apply(this, args); - return promise.finally(() => exportSettled.resolve()); + return promise.finally(() => exportSettled.release()); }); const launcher: KunaProcessLauncher = async (options) => { - if (options.arguments[0] === "decompile") { - await exportSettled.promise; - } + if (options.arguments[0] === "decompile") await exportSettled.hold(); return spawnOwnedProviderProcess(options); }; const { kuna, open } = await session( @@ -359,9 +339,9 @@ it("reports sibling unavailability when fallback observes settled export failure ]); expect(answer.siblingUnavailability?.providerId).toBe("kuna"); expect(await decompilesOf(kuna)).toHaveLength(1); - await exportSettled.promise; + await exportSettled.hold(); } finally { - exportSettled.resolve(); + exportSettled.release(); try { expect(await client.close()).toEqual({ ok: true, value: null }); } finally { diff --git a/tests/boundary/providers/kuna/kunaWorkspaceRollback.test.ts b/tests/boundary/providers/kuna/kunaWorkspaceRollback.test.ts index 56287394a9..5d09b69bfe 100644 --- a/tests/boundary/providers/kuna/kunaWorkspaceRollback.test.ts +++ b/tests/boundary/providers/kuna/kunaWorkspaceRollback.test.ts @@ -18,7 +18,7 @@ import { ExecFileOutputCancelledError } from "../../../../src/process/ExecFileOu import { PrivateRuntimeRoot } from "../../../../src/process/PrivateRuntimeRoot.js"; import { ProviderCleanupError } from "../../../../src/domain/providerCleanupError.js"; import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../../support/lifecycleHarness.js"; import { session } from "./kunaSessionFixture.js"; import { releaseOwnedCleanup } from "../../../support/cleanupRelease.js"; @@ -93,14 +93,7 @@ it.each(["clean", "refuse"] as const)( const commands = new KunaTargetCommands(fixture.target, { signal: lifetime.signal, }); - let entered!: () => void; - let release!: () => void; - const started = new Promise((resolve) => { - entered = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const workspaceRollback = phaseGate(); const create = PrivateRuntimeRoot.create; let holdFailures = mode === "refuse"; let rootClose: ReturnType | undefined; @@ -110,8 +103,7 @@ it.each(["clean", "refuse"] as const)( const root = await create(options); const close = root.close.bind(root); rootClose = vi.spyOn(root, "close").mockImplementation(async () => { - entered(); - await gate; + await workspaceRollback.hold(); if (holdFailures) throw new Error("controlled finalization refusal"); await close(); }); @@ -129,7 +121,7 @@ it.each(["clean", "refuse"] as const)( ); let closing: ReturnType | undefined; await withVerifierCleanup(async () => { - await awaitAcknowledgement(started, pending, "workspace rollback"); + await workspaceRollback.reached(pending, "workspace rollback"); lifetime.abort({ caller: "shutdown during rollback" }); closing = commands.close(); let closed = false; @@ -144,7 +136,7 @@ it.each(["clean", "refuse"] as const)( await new Promise((resolve) => setImmediate(resolve)); expect(settled).toBe(false); expect(closed).toBe(false); - release(); + workspaceRollback.release(); const result = await pending; if (result.ok) throw new Error("Expected changed-target failure"); expect(result.error.cleanupIncomplete).toBe(mode === "refuse"); @@ -160,7 +152,7 @@ it.each(["clean", "refuse"] as const)( }, [ () => { holdFailures = false; - release(); + workspaceRollback.release(); }, async () => { await pending; diff --git a/tests/boundary/providers/native/nativeCallTargetCleanup.test.ts b/tests/boundary/providers/native/nativeCallTargetCleanup.test.ts index c692304a4e..5aab446653 100644 --- a/tests/boundary/providers/native/nativeCallTargetCleanup.test.ts +++ b/tests/boundary/providers/native/nativeCallTargetCleanup.test.ts @@ -1,13 +1,13 @@ import { open, writeFile, type FileHandle } from "node:fs/promises"; import { join } from "node:path"; import { expect, it, vi, onTestFinished } from "vitest"; +import { phaseGate } from "../../../support/lifecycleHarness.js"; import { NativeMacOSProvider } from "../../../../src/native/NativeMacOSProvider.js"; import { NativeFixtureRunner, nativeMachoTargetForFile, } from "../../../fixtures/nativeCommands.js"; import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; import { AnalysisOutputError } from "../../../../src/domain/analysisErrorCore.js"; import { resolvedAnalysisError } from "../../../../src/domain/analysisErrorBase.js"; import { err, ok } from "../../../../src/domain/result.js"; @@ -91,13 +91,7 @@ it("retains preflight read failure and exact descriptor across failed client cle it("joins admitted preflight before closing the tracer", async () => { const { target, prototype } = await fixture(); - let enter!: () => void, resume!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - resume = resolve; - }); + const targetRead = phaseGate(); const original = prototype.read; const read = vi .spyOn(prototype, "read") @@ -105,8 +99,7 @@ it("joins admitted preflight before closing the tracer", async () => { this: FileHandle, ...args: Parameters ) { - enter(); - await gate; + await targetRead.hold(); return Reflect.apply(original, this, args); }); const calls: string[] = []; @@ -131,7 +124,7 @@ it("joins admitted preflight before closing the tracer", async () => { }), ).createClient(target); onTestFinished(async () => { - resume(); + targetRead.release(); try { await observing; } finally { @@ -140,7 +133,7 @@ it("joins admitted preflight before closing the tracer", async () => { } }); const observing = client.execute("observe_native_calls", parameters); - await awaitAcknowledgement(entered, observing, "native target read"); + await targetRead.reached(observing, "native target read"); let closed = false; const closing = client.close().then((result) => { closed = true; @@ -148,7 +141,7 @@ it("joins admitted preflight before closing the tracer", async () => { }); await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); - resume(); + targetRead.release(); expect((await observing).ok).toBe(false); expect((await closing).ok).toBe(true); expect(calls).toEqual(["trace", "close"]); diff --git a/tests/boundary/providers/native/nativeCommandResolver.test.ts b/tests/boundary/providers/native/nativeCommandResolver.test.ts index 0d14b80a41..9f8914764a 100644 --- a/tests/boundary/providers/native/nativeCommandResolver.test.ts +++ b/tests/boundary/providers/native/nativeCommandResolver.test.ts @@ -2,7 +2,7 @@ import { EventEmitter } from "node:events"; import { PassThrough } from "node:stream"; import { afterEach, expect, it, vi } from "vitest"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival } from "../../../support/lifecycleHarness.js"; import { resolveXcrunTool, @@ -57,10 +57,7 @@ afterEach(() => { }); it("keeps a realpath I/O failure primary when cancellation is observed before rejection", async () => { - let realpathStarted!: () => void; - const started = new Promise((resolve) => { - realpathStarted = resolve; - }); + const realpathStart = phaseArrival(); let rejectRealpath: ((cause: unknown) => void) | undefined; realpathState.resolve = () => new Promise((_resolve, reject) => { @@ -69,13 +66,13 @@ it("keeps a realpath I/O failure primary when cancellation is observed before re return; } rejectRealpath = reject; - realpathStarted(); + realpathStart.arrive(); }); const controller = new AbortController(); const cancellationReason = { source: "caller", phase: "tool resolution" }; const pending = resolveXcrunTool("file", {}, controller.signal, launcher); try { - await awaitAcknowledgement(started, pending, "native tool realpath"); + await realpathStart.reached(pending, "native tool realpath"); controller.abort(cancellationReason); const ioFailure = Object.assign(new Error("fixture realpath failure"), { code: "EACCES", @@ -99,10 +96,7 @@ it("keeps a realpath I/O failure primary when cancellation is observed before re it("retains exact cancellation observed after successful tool path resolution", async () => { let finishRealpath: (() => void) | undefined; - let realpathStarted!: () => void; - const started = new Promise((resolve) => { - realpathStarted = resolve; - }); + const realpathStart = phaseArrival(); realpathState.resolve = () => new Promise((resolve, reject) => { if (controller.signal.aborted) { @@ -110,13 +104,13 @@ it("retains exact cancellation observed after successful tool path resolution", return; } finishRealpath = () => resolve("/controlled/physical-tool"); - realpathStarted(); + realpathStart.arrive(); }); const controller = new AbortController(); const cancellationReason = { source: "caller", phase: "tool selection" }; const pending = resolveXcrunTool("file", {}, controller.signal, launcher); try { - await awaitAcknowledgement(started, pending, "native tool realpath"); + await realpathStart.reached(pending, "native tool realpath"); controller.abort(cancellationReason); finishRealpath?.(); @@ -142,10 +136,7 @@ it.skipIf(process.platform === "win32")( "uses the AbortError cause as the exact tool-hash cancellation fact", async () => { let finishRealpath: (() => void) | undefined; - let realpathStarted!: () => void; - const started = new Promise((resolve) => { - realpathStarted = resolve; - }); + const realpathStart = phaseArrival(); realpathState.resolve = () => new Promise((resolve, reject) => { if (controller.signal.aborted) { @@ -153,17 +144,13 @@ it.skipIf(process.platform === "win32")( return; } finishRealpath = () => resolve("/dev/zero"); - realpathStarted(); + realpathStart.arrive(); }); const controller = new AbortController(); const cancellationReason = { source: "caller", phase: "tool hash" }; const pending = resolveXcrunTool("file", {}, controller.signal, launcher); try { - await awaitAcknowledgement( - started, - pending, - "native tool hash selection", - ); + await realpathStart.reached(pending, "native tool hash selection"); finishRealpath?.(); setImmediate(() => controller.abort(cancellationReason)); diff --git a/tests/boundary/providers/native/nativePlistFileCleanup.test.ts b/tests/boundary/providers/native/nativePlistFileCleanup.test.ts index e5376c0612..13b353f07b 100644 --- a/tests/boundary/providers/native/nativePlistFileCleanup.test.ts +++ b/tests/boundary/providers/native/nativePlistFileCleanup.test.ts @@ -9,7 +9,7 @@ import { nativeMachoTargetForFile, } from "../../../fixtures/nativeCommands.js"; import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../../support/lifecycleHarness.js"; import { OwnedFileHandle } from "../../../../src/filesystem/OwnedFileHandle.js"; import { ProviderCleanupError } from "../../../../src/domain/providerCleanupError.js"; import { resolvedAnalysisError } from "../../../../src/domain/analysisErrorBase.js"; @@ -339,22 +339,8 @@ it.for([ async ([phase, route]) => { const { client, path, prototype, runner } = await fixture(); if (route !== "source") await writeFile(path, "{ name = value; }"); - let enter!: () => void; - let resume!: () => void; - let enterValidation!: () => void; - let resumeValidation!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - resume = resolve; - }); - const validationEntered = new Promise((resolve) => { - enterValidation = resolve; - }); - const validationGate = new Promise((resolve) => { - resumeValidation = resolve; - }); + const plistFileRead = phaseGate(); + const plistValidation = phaseGate(); const original = prototype.read; let reads = 0; const read = vi.spyOn(prototype, "read").mockImplementation(async function ( @@ -363,8 +349,7 @@ it.for([ ) { reads += 1; if (reads === (phase === "prefix" ? 1 : 2)) { - enter(); - await gate; + await plistFileRead.hold(); } return Reflect.apply(original, this, args); }); @@ -375,8 +360,7 @@ it.for([ .mockImplementation(async (tool, args, options) => { if (tool === "plutil" && (route !== "xml" || args[1] === "xml1")) { validationStarted = true; - enterValidation(); - await validationGate; + await plistValidation.hold(); } const result = await run(tool, args, options); if (route !== "xml" || tool !== "plutil" || !result.ok) return result; @@ -390,8 +374,8 @@ it.for([ }); }); onTestFinished(async () => { - resume(); - resumeValidation(); + plistFileRead.release(); + plistValidation.release(); try { await inspecting; } finally { @@ -404,7 +388,7 @@ it.for([ path, native_command_timeout_ms: 1500, }); - await awaitAcknowledgement(entered, inspecting, "plist file read"); + await plistFileRead.reached(inspecting, "plist file read"); let finished = false; const closing = client.close().then((result) => { finished = true; @@ -416,16 +400,12 @@ it.for([ ok: false, error: { _tag: "AnalysisCapabilityUnavailableError" }, }); - resume(); - await awaitAcknowledgement( - validationEntered, - inspecting, - "plist validation", - ); + plistFileRead.release(); + await plistValidation.reached(inspecting, "plist validation"); expect(validationStarted).toBe(true); await new Promise((resolve) => setImmediate(resolve)); expect(finished).toBe(false); - resumeValidation(); + plistValidation.release(); const inspected = await inspecting; if (!inspected.ok) throw inspected.error; expect((await closing).ok).toBe(true); diff --git a/tests/boundary/providers/native/nativeProvider.test.ts b/tests/boundary/providers/native/nativeProvider.test.ts index 3e81ba6102..f82b82a1a4 100644 --- a/tests/boundary/providers/native/nativeProvider.test.ts +++ b/tests/boundary/providers/native/nativeProvider.test.ts @@ -12,6 +12,7 @@ import { build } from "plist"; import { withVerifierCleanup } from "../../../../scripts/lib/verifier-cleanup.mjs"; import { awaitAcknowledgement } from "../../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival, phaseGate } from "../../../support/lifecycleHarness.js"; import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; import { NativeMacOSProvider } from "../../../../src/native/NativeMacOSProvider.js"; @@ -880,18 +881,8 @@ describe("native late cancellation with cleanup", () => { it("keeps a late cancellation fact with the physical command failure and retries its retained owner", async () => { const cancellationReason = { caller: "stop after process failure" }; const controller = new AbortController(); - let commandStarted!: () => void; - const started = new Promise((resolve) => { - commandStarted = resolve; - }); - let cleanupStarted!: () => void; - const cleanupAttempt = new Promise((resolve) => { - cleanupStarted = resolve; - }); - let releaseFirstCleanup!: () => void; - const firstCleanup = new Promise((resolve) => { - releaseFirstCleanup = resolve; - }); + const commandStart = phaseArrival(); + const nativeCleanupStart = phaseGate(); let cleanupCalls = 0; let launches = 0; const launcher: NativeCommandLauncher = async (options) => { @@ -911,7 +902,7 @@ describe("native late cancellation with cleanup", () => { child.exitCode = 7; child.emit("exit", 7, null); child.emit("close", 7, null); - commandStarted(); + commandStart.arrive(); }); return { process: child, @@ -924,8 +915,7 @@ describe("native late cancellation with cleanup", () => { cleanup: async () => { cleanupCalls += 1; if (cleanupCalls === 1) { - cleanupStarted(); - await firstCleanup; + await nativeCleanupStart.hold(); return { cleaned: false, reason: "controlled cleanup remains incomplete", @@ -952,14 +942,10 @@ describe("native late cancellation with cleanup", () => { {}, { signal: controller.signal }, ); - await awaitAcknowledgement(started, pending, "native command start"); - await awaitAcknowledgement( - cleanupAttempt, - pending, - "native cleanup start", - ); + await commandStart.reached(pending, "native command start"); + await nativeCleanupStart.reached(pending, "native cleanup start"); controller.abort(cancellationReason); - releaseFirstCleanup(); + nativeCleanupStart.release(); const result = await pending; if (result.ok) @@ -988,7 +974,7 @@ describe("native late cancellation with cleanup", () => { expect(cleanupCalls).toBe(2); expect(launches).toBe(1); } finally { - releaseFirstCleanup(); + nativeCleanupStart.release(); await client.close(); } }); @@ -1107,24 +1093,13 @@ describe("native command cleanup lifecycle", () => { }); it("waits for an active command before retrying its failed owner at close", async () => { - let finishCommand!: ( - result: Awaited>, - ) => void; - let commandStarted!: () => void; - const started = new Promise((resolve) => { - commandStarted = resolve; - }); - const command = new Promise< + const commandRun = phaseGate< + void, Awaited> - >((resolve) => { - finishCommand = resolve; - }); + >(); let cleanupRetries = 0; const runner: NativeCommandRunner = { - run: () => { - commandStarted(); - return command; - }, + run: () => commandRun.hold(), retryCleanup: async () => { cleanupRetries += 1; return cleanupRetries === 1 @@ -1160,11 +1135,11 @@ describe("native command cleanup lifecycle", () => { }), ); try { - await awaitAcknowledgement(started, execution, "native command start"); + await commandRun.reached(execution, "native command start"); const closing = client.close(); await Promise.resolve(); expect(cleanupRetries).toBe(0); - finishCommand(commandResult); + commandRun.release(commandResult); const [observed, closed] = await Promise.all([execution, closing]); expect(observed.ok).toBe(false); @@ -1194,7 +1169,7 @@ describe("native command cleanup lifecycle", () => { await expect(client.close()).resolves.toMatchObject({ ok: true }); expect(cleanupRetries).toBe(2); } finally { - finishCommand(commandResult); + commandRun.release(commandResult); try { await execution; } finally { diff --git a/tests/boundary/providers/startupCloseWaiters.test.ts b/tests/boundary/providers/startupCloseWaiters.test.ts index c08a00a7d2..b4a0fb99ee 100644 --- a/tests/boundary/providers/startupCloseWaiters.test.ts +++ b/tests/boundary/providers/startupCloseWaiters.test.ts @@ -3,13 +3,12 @@ import { readFileSync } from "node:fs"; import { access } from "node:fs/promises"; import { expect, it, vi } from "vitest"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; import { GhidraClient } from "../../../src/ghidra/GhidraClient.js"; import { HopperClient } from "../../../src/hopper/HopperClient.js"; import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js"; -import { createDeferred } from "../../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; import { GhidraFixtureLauncher, ghidraFixturePath, @@ -62,15 +61,13 @@ it.each(providers)( "cancels a $name restart wait without taking ownership of pending close", async ({ create, cancelled }) => { const { client, roots, children } = create(); - const entered = createDeferred(); - const gate = createDeferred(); + const providerClose = phaseGate(); const originalClose = PrivateRuntimeRoot.prototype.close; const close = vi .spyOn(PrivateRuntimeRoot.prototype, "close") .mockImplementation(async function (this: PrivateRuntimeRoot) { if (this.path === roots[0]) { - entered.resolve(); - await gate.promise; + await providerClose.hold(); } await originalClose.call(this); }); @@ -80,7 +77,7 @@ it.each(providers)( await withVerifierCleanup(async () => { await expect(client.start()).resolves.toMatchObject({ ok: true }); closing = client.close(); - await awaitAcknowledgement(entered.promise, closing, "provider close"); + await providerClose.reached(closing, "provider close"); retry = client.start(controller.signal); let settled: Awaited | undefined; void retry.then( @@ -95,7 +92,7 @@ it.each(providers)( ); await expect(access(roots[0] ?? "")).resolves.toBeUndefined(); expect(children).toHaveLength(1); - gate.resolve(); + providerClose.release(); await expect(closing).resolves.toMatchObject({ ok: true }); await retry; await expect(access(roots[0] ?? "")).rejects.toMatchObject({ @@ -104,7 +101,7 @@ it.each(providers)( await expect(client.start()).resolves.toMatchObject({ ok: true }); expect(children).toHaveLength(2); }, [ - () => gate.resolve(), + () => providerClose.release(), () => controller.abort(), async () => { await retry; diff --git a/tests/boundary/setup/linuxHopperPublisherVerification.test.ts b/tests/boundary/setup/linuxHopperPublisherVerification.test.ts index f583e16c57..3696a3a06a 100644 --- a/tests/boundary/setup/linuxHopperPublisherVerification.test.ts +++ b/tests/boundary/setup/linuxHopperPublisherVerification.test.ts @@ -23,7 +23,7 @@ import { fileURLToPath } from "node:url"; import { createMessage, generateKey, readPrivateKey, sign } from "openpgp"; import { afterEach, describe, expect, it, vi } from "vitest"; import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../../support/lifecycleHarness.js"; import { LinuxHopperPublisher, @@ -1073,14 +1073,7 @@ portableTar( await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive), ).toMatchObject({ ok: true }); - let reachedMetadataClose!: () => void; - const metadataCloseStarted = new Promise((resolve) => { - reachedMetadataClose = resolve; - }); - let releaseMetadataClose!: () => void; - const metadataCloseGate = new Promise((resolve) => { - releaseMetadataClose = resolve; - }); + const metadataClose = phaseGate(); const metadataIdentity = await stat(join(f.cache, "release.json")); const launcherIdentity = await stat(f.launcher); let metadataOwner: OwnedFileHandle | undefined; @@ -1099,8 +1092,7 @@ portableTar( observed.ino === metadataIdentity.ino ) { metadataOwner = this; - reachedMetadataClose(); - await metadataCloseGate; + await metadataClose.hold(); } if ( hashActive && @@ -1118,11 +1110,7 @@ portableTar( }); const inspection = f.publisher.inspectLauncher(f.launcher); await withVerifierCleanup(async () => { - await awaitAcknowledgement( - metadataCloseStarted, - inspection, - "metadata close", - ); + await metadataClose.reached(inspection, "metadata close"); hashActive = true; const hashFailure = await f.publisher.hashLauncher(f.launcher).then( () => undefined, @@ -1140,7 +1128,7 @@ portableTar( expect(hashOwner?.handle.fd).toBeGreaterThanOrEqual(0); expect(hashCloseAttempts).toBeGreaterThanOrEqual(2); allowHashClose = true; - releaseMetadataClose(); + metadataClose.release(); await expect(inspection).resolves.toMatchObject({ ok: true, value: { source: "signed_package_cache" }, @@ -1151,7 +1139,7 @@ portableTar( }, [ () => { allowHashClose = true; - releaseMetadataClose(); + metadataClose.release(); }, async () => { await inspection; diff --git a/tests/composition/analysis-sessions/providerBinding.test.ts b/tests/composition/analysis-sessions/providerBinding.test.ts index 0177df779c..0fc2b26c3b 100644 --- a/tests/composition/analysis-sessions/providerBinding.test.ts +++ b/tests/composition/analysis-sessions/providerBinding.test.ts @@ -5,7 +5,7 @@ import { describe, expect, it, onTestFinished } from "vitest"; import { z } from "zod"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival, phaseGate } from "../../support/lifecycleHarness.js"; import { createAnalysisExecution, @@ -133,12 +133,10 @@ describe("target-bound provider routing", () => { const target = await databaseTarget(); const alpha = deepProvider("alpha"); const beta = deepProvider("beta"); - const pending = deferred>(); - const callStarted = deferred(); - const profileStarted = deferred(); - alpha.pending = pending.promise; - alpha.onPending = () => callStarted.resolve(); - beta.onProfile = () => profileStarted.resolve(); + const call = phaseGate>(); + const profileResolution = phaseArrival(); + alpha.pending = () => call.hold(); + beta.onProfile = () => profileResolution.arrive(); const session = selectableSession([alpha.provider, beta.provider]); const controller = new AbortController(); const reason = new Error("cancel provider switch"); @@ -146,7 +144,7 @@ describe("target-bound provider routing", () => { let switching: ReturnType | undefined; onTestFinished(async () => { controller.abort(reason); - pending.resolve(successfulExecution("alpha")); + call.release(successfulExecution("alpha")); await Promise.allSettled([ ...(running === undefined ? [] : [running]), ...(switching === undefined ? [] : [switching]), @@ -155,20 +153,16 @@ describe("target-bound provider routing", () => { }); expect((await session.open(target, { providerId: "alpha" })).ok).toBe(true); running = session.execute("address_name", { address: "0x1" }); - await awaitAcknowledgement(callStarted.promise, running, "provider call"); + await call.reached(running, "provider call"); switching = session.open(target, { providerId: "beta", signal: controller.signal, }); - await awaitAcknowledgement( - profileStarted.promise, - switching, - "provider profile resolution", - ); + await profileResolution.reached(switching, "provider profile resolution"); expect(alpha.clients[0]?.closed).toBe(false); controller.abort(reason); - pending.resolve(successfulExecution("alpha")); + call.release(successfulExecution("alpha")); expect(await running).toMatchObject({ ok: true }); const cancelled = await switching; @@ -276,8 +270,8 @@ interface DeepProviderFixture { available: boolean; fail: boolean; onProfile: (() => void) | undefined; - onPending: (() => void) | undefined; - pending: Promise> | undefined; + /** Holds each call while set. */ + pending: (() => Promise>) | undefined; } const deepProvider = (id: string): DeepProviderFixture => { @@ -291,7 +285,6 @@ const deepProvider = (id: string): DeepProviderFixture => { available: true, fail: false, onProfile: undefined, - onPending: undefined, pending: undefined, }; const provider: AnalysisProviderCandidate = { @@ -341,10 +334,7 @@ const deepProvider = (id: string): DeepProviderFixture => { return Promise.resolve( err(new ProviderAdapterError(id, operation)), ); - if (fixture.pending !== undefined) { - fixture.onPending?.(); - return fixture.pending; - } + if (fixture.pending !== undefined) return fixture.pending(); return Promise.resolve(successfulExecution(id, profile?.provider)); }, close: () => { @@ -447,21 +437,3 @@ const bindingStatus = async (session: BinarySession) => }) .passthrough() .parse(await session.status()); - -interface Deferred { - readonly promise: Promise; - resolve(value: Value): void; -} - -const deferred = (): Deferred => { - let resolvePromise: ((value: Value) => void) | undefined; - const promise = new Promise((resolve) => { - resolvePromise = resolve; - }); - return { - promise, - resolve(value) { - resolvePromise?.(value); - }, - }; -}; diff --git a/tests/composition/reverseEngineeringEdgeCases.test.ts b/tests/composition/reverseEngineeringEdgeCases.test.ts index a92a22123d..71317b0310 100644 --- a/tests/composition/reverseEngineeringEdgeCases.test.ts +++ b/tests/composition/reverseEngineeringEdgeCases.test.ts @@ -430,7 +430,7 @@ it("rejects work after reaching the concurrent provider-operation limit", async await withVerifierCleanup(async () => { const rejection = service.executeRizinCommand({ path, command: "iI" }); await awaitAcknowledgement( - rejection.then(() => {}), + rejection, Promise.all(admitted), "capacity response", ); diff --git a/tests/evaluation/lifecycleHarness.test.ts b/tests/evaluation/lifecycleHarness.test.ts index 602e220aa3..1cff0e1db9 100644 --- a/tests/evaluation/lifecycleHarness.test.ts +++ b/tests/evaluation/lifecycleHarness.test.ts @@ -1,6 +1,6 @@ import { setImmediate as nextTurn } from "node:timers/promises"; import { expect, it } from "vitest"; -import { phaseGate } from "../support/lifecycleHarness.js"; +import { phaseArrival, phaseGate } from "../support/lifecycleHarness.js"; it("hands an early rejection to the later hold without an unhandled rejection", async () => { const unhandled: unknown[] = []; @@ -20,6 +20,17 @@ it("hands an early rejection to the later hold without an unhandled rejection", } }); +it("gives each hold its own promise, so an unhandled held rejection is still reported", async () => { + const gate = phaseGate(); + const first = gate.hold(); + const second = gate.hold(); + // The gate's internal guard against an early rejection must not mark the + // promise the code under test receives as handled. + expect(first).not.toBe(second); + gate.release(1); + expect(await Promise.all([first, second])).toEqual([1, 1]); +}); + it("releases every hold with the first value", async () => { const gate = phaseGate(); const operation = gate.hold("arrived"); @@ -30,3 +41,26 @@ it("releases every hold with the first value", async () => { expect(await operation).toBe(7); expect(await gate.hold("again")).toBe(7); }); + +it("reports an arrival only when it happens before the operation settles", async () => { + const arrival = phaseArrival(); + const settled = Promise.resolve("done"); + await expect(arrival.reached(settled, "late boundary")).rejects.toThrow( + "late boundary was not acknowledged before the triggering operation settled", + ); + const running = new Promise(() => {}); + arrival.arrive("first"); + arrival.arrive("second"); + expect(await arrival.reached(running, "announced boundary")).toBe("first"); +}); + +it("counts an arrival announced in the same turn the operation settles", async () => { + const arrival = phaseArrival(); + const operation = Promise.resolve().then(() => arrival.arrive()); + await arrival.reached(operation, "immediate boundary"); + const gate = phaseGate(); + const held = Promise.resolve().then(() => { + void gate.hold(); + }); + await gate.reached(held, "immediate hold"); +}); diff --git a/tests/fixtures/lifecycleAcknowledgement.ts b/tests/fixtures/lifecycleAcknowledgement.ts index 23a8699bad..a108d145bf 100644 --- a/tests/fixtures/lifecycleAcknowledgement.ts +++ b/tests/fixtures/lifecycleAcknowledgement.ts @@ -5,7 +5,7 @@ import { testWaitDeadline } from "../support/testWait.js"; * reaches its controlled lifecycle boundary. */ export const awaitAcknowledgement = async ( - acknowledgement: Promise, + acknowledgement: Promise, operation: Promise, boundary: string, timeoutMs = testWaitDeadline(), diff --git a/tests/process-global/apkSignatureLifecycle.test.ts b/tests/process-global/apkSignatureLifecycle.test.ts index 16a6e848e2..44787252b5 100644 --- a/tests/process-global/apkSignatureLifecycle.test.ts +++ b/tests/process-global/apkSignatureLifecycle.test.ts @@ -3,7 +3,7 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import { TextReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js"; import { afterAll, afterEach, beforeAll, expect, it, vi } from "vitest"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../support/lifecycleHarness.js"; const fault = vi.hoisted(() => ({ path: "", @@ -14,9 +14,8 @@ const fault = vi.hoisted(() => ({ abortAtStat: undefined as | { controller: AbortController; reason: unknown } | undefined, - pauseAtStat: undefined as - | { started: () => void; resume: Promise } - | undefined, + /** Holds the next stat of the faulted file. */ + pauseAtStat: undefined as (() => Promise) | undefined, })); vi.mock("node:fs/promises", async (importOriginal) => { @@ -34,10 +33,7 @@ vi.mock("node:fs/promises", async (importOriginal) => { abort?.controller.abort(abort.reason); const pause = fault.pauseAtStat; fault.pauseAtStat = undefined; - if (pause !== undefined) { - pause.started(); - await pause.resume; - } + await pause?.(); return stat(...statArgs); }) as typeof handle.stat; handle.close = async () => { @@ -64,13 +60,6 @@ import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.j let root = ""; let path = ""; const exitCode = process.exitCode; -const deferred = () => { - let complete = () => {}; - const promise = new Promise((resolve) => { - complete = resolve; - }); - return { promise, resolve: () => complete() }; -}; beforeAll(async () => { root = await mkdtemp(join(tmpdir(), "rea-apk-lifecycle-")); path = join(root, "unsigned.apk"); @@ -93,13 +82,9 @@ afterAll(async () => { it("serializes reads across providers, preserves queued aborts and drains admitted work on close", async () => { const first = new ApkSignatureProvider(); const second = new ApkSignatureProvider(); - const started = deferred(); - const resume = deferred(); + const statRead = phaseGate(); fault.path = path; - fault.pauseAtStat = { - started: () => started.resolve(), - resume: resume.promise, - }; + fault.pauseAtStat = () => statRead.hold(); const reading = first.inspect({ path }); const controller = new AbortController(); const reason = new Error("cancel while queued"); @@ -108,7 +93,7 @@ it("serializes reads across providers, preserves queued aborts and drains admitt let closing: Promise | undefined; let closed = false; try { - await awaitAcknowledgement(started.promise, reading, "APK signature read"); + await statRead.reached(reading, "APK signature read"); queued = second.inspect({ path }); cancelled = second.inspect({ path }, { signal: controller.signal }); closing = second.close().then(() => { @@ -120,13 +105,13 @@ it("serializes reads across providers, preserves queued aborts and drains admitt error: { _tag: "AnalysisCancelledError", cause: reason }, }); expect(closed).toBe(false); - resume.resolve(); + statRead.release(); expect((await reading).ok).toBe(true); expect((await queued).ok).toBe(true); await closing; expect(closed).toBe(true); } finally { - resume.resolve(); + statRead.release(); await Promise.allSettled([ reading, ...(queued ? [queued] : []), diff --git a/tests/process-global/artifactFileSourceLifecycle.test.ts b/tests/process-global/artifactFileSourceLifecycle.test.ts index 4f80dfdecd..3e22896472 100644 --- a/tests/process-global/artifactFileSourceLifecycle.test.ts +++ b/tests/process-global/artifactFileSourceLifecycle.test.ts @@ -10,6 +10,7 @@ import { dirname, join } from "node:path"; import { text } from "node:stream/consumers"; import { setImmediate } from "node:timers/promises"; import { afterEach, expect, it, vi } from "vitest"; +import { phaseGate } from "../support/lifecycleHarness.js"; import { ArtifactReaderFailure, @@ -21,9 +22,7 @@ import { GodotPckArtifactReader } from "../../src/artifacts/GodotPckArtifactRead import { NodeSeaArtifactReader } from "../../src/artifacts/NodeSeaArtifactReader.js"; import { nodeSeaElf } from "../../src/artifacts/nodeSea/NodeSea.fixture.js"; import type { StableRegularFileDescriptor } from "../../src/filesystem/RegularFile.js"; -import { createDeferred } from "../fixtures/binarySession.js"; import { buildGodotPck } from "../fixtures/godotPck.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; interface OpenControl { @@ -135,12 +134,10 @@ it.each(carriers)( "$name joins late admission before close and refuses replacement work", async (carrier) => { const { path, sha256 } = await carrierFile(carrier); - const admitted = createDeferred(); - const release = createDeferred(); + const admission = phaseGate(); control.onOpen = async (handle) => { vi.spyOn(handle, "close"); - admitted.resolve(); - await release.promise; + await admission.hold(); }; const reader = carrier.reader(path); const operations: Promise[] = []; @@ -148,11 +145,7 @@ it.each(carriers)( try { const preparing = reader.prepareContainer(sha256); operations.push(preparing); - await awaitAcknowledgement( - admitted.promise, - preparing, - "carrier admission", - ); + await admission.reached(preparing, "carrier admission"); const handle = openedHandle(); const closeAttempts = [reader.close(), reader.close()]; operations.push(...closeAttempts); @@ -164,7 +157,7 @@ it.each(carriers)( expect(closed).toBe(false); expect(handle.fd).toBeGreaterThanOrEqual(0); expect(handle.close).not.toHaveBeenCalled(); - release.resolve(); + admission.release(); await preparing; await closing; expect(handle.fd).toBe(-1); @@ -181,7 +174,7 @@ it.each(carriers)( await reader.close(); expect(handle.close).toHaveBeenCalledOnce(); } finally { - release.resolve(); + admission.release(); await Promise.allSettled(operations); await reader.close(); } @@ -192,15 +185,13 @@ it.each(carriers)( "$name retains a failed physical close and retries only that exact descriptor", async (carrier) => { const { path, sha256 } = await carrierFile(carrier); - const entered = createDeferred(); - const release = createDeferred(); + const carrierClose = phaseGate(); const failure = new Error("controlled carrier close failure"); let blocked = true; control.onOpen = async (handle) => { const close = handle.close.bind(handle); vi.spyOn(handle, "close").mockImplementation(async () => { - entered.resolve(); - await release.promise; + await carrierClose.hold(); if (blocked) throw failure; await close(); }); @@ -214,10 +205,10 @@ it.each(carriers)( expect(await text(await reader.open(entry))).toBe(BODY); const handle = openedHandle(); closing = Promise.allSettled([reader.close(), reader.close()]); - await awaitAcknowledgement(entered.promise, closing, "carrier close"); + await carrierClose.reached(closing, "carrier close"); expect(handle.fd).toBeGreaterThanOrEqual(0); expect(handle.close).toHaveBeenCalledOnce(); - release.resolve(); + carrierClose.release(); expect(await closing).toEqual([ { status: "rejected", reason: failure }, { status: "rejected", reason: failure }, @@ -232,7 +223,7 @@ it.each(carriers)( expect(control.handles.size).toBe(1); } finally { blocked = false; - release.resolve(); + carrierClose.release(); await closing; await reader.close(); } @@ -296,8 +287,7 @@ it.each(admissionCases)( "$name awaits physical admission cleanup and preserves $primary (closeFails=$closeFails)", async ({ carrier, primary, closeFails }) => { const { path } = await carrierFile(carrier); - const entered = createDeferred(); - const release = createDeferred(); + const admissionClose = phaseGate(); const controller = new AbortController(); const admissionFailure = new Error("controlled descriptor stat failure"); const cleanupFailure = new Error("controlled admission close failure"); @@ -309,8 +299,7 @@ it.each(admissionCases)( else controller.abort(cancellation); const close = handle.close.bind(handle); vi.spyOn(handle, "close").mockImplementation(async () => { - entered.resolve(); - await release.promise; + await admissionClose.hold(); if (blocked) throw cleanupFailure; await close(); }); @@ -328,18 +317,14 @@ it.each(admissionCases)( .finally(() => { settled = true; }); - await awaitAcknowledgement( - entered.promise, - operation, - "admission cleanup", - ); + await admissionClose.reached(operation, "admission cleanup"); const handle = openedHandle(); // An earlier metadata failure stays primary when cancellation arrives in close. controller.abort(cancellation); await setImmediate(); expect(settled).toBe(false); expect(handle.fd).toBeGreaterThanOrEqual(0); - release.resolve(); + admissionClose.release(); const failure = await reading; if (!(failure instanceof ArtifactReaderFailure)) throw new Error("Expected a typed carrier admission failure"); @@ -375,7 +360,7 @@ it.each(admissionCases)( } finally { controller.abort(cancellation); blocked = false; - release.resolve(); + admissionClose.release(); await reading; await reader.close(); } diff --git a/tests/process-global/cutterDescriptorLifetime.test.ts b/tests/process-global/cutterDescriptorLifetime.test.ts index f2838321b2..68ad7b42eb 100644 --- a/tests/process-global/cutterDescriptorLifetime.test.ts +++ b/tests/process-global/cutterDescriptorLifetime.test.ts @@ -38,7 +38,7 @@ import { AnalysisCancelledError } from "../../src/domain/analysisErrorCore.js"; import { AnalysisError } from "../../src/domain/analysisErrorBase.js"; import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival, phaseGate } from "../support/lifecycleHarness.js"; import { cliTest } from "../support/cli/cliFixture.js"; import { authenticatedServer } from "../fixtures/cutterBridgeProtocol.js"; @@ -162,23 +162,15 @@ it("shutdown waits for descriptor finalization before retrying retained cleanup" throw new Error("Expected a local Cutter test port"); await descriptor(root, 1, address.port); fault.root = root; - let entered!: () => void; - let release!: () => void; - const closing = new Promise((resolve) => { - entered = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const descriptorClose = phaseGate(); fault.onClose = async () => { - entered(); - await gate; + await descriptorClose.hold(); }; const client = new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: root }); const reading = client.listSessions(); let shutdown: Promise | undefined; try { - await awaitAcknowledgement(closing, reading, "descriptor finalization"); + await descriptorClose.reached(reading, "descriptor finalization"); let settled = false; shutdown = client.close().then(() => { settled = true; @@ -186,7 +178,7 @@ it("shutdown waits for descriptor finalization before retrying retained cleanup" await new Promise((resolve) => setImmediate(resolve)); expect(settled).toBe(false); fault.blocked.clear(); - release(); + descriptorClose.release(); expect(await reading).toMatchObject({ discovery_status: "sessions_found", sessions: [{ session_id: sessionId }], @@ -194,7 +186,7 @@ it("shutdown waits for descriptor finalization before retrying retained cleanup" await shutdown; expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true); } finally { - release(); + descriptorClose.release(); fault.onClose = undefined; fault.blocked.clear(); await Promise.allSettled([reading, ...(shutdown ? [shutdown] : [])]); @@ -242,40 +234,28 @@ it("does not assign a peer's later cancellation to a descriptor that already fai fault.root = root; const controller = new AbortController(); const reason = new Error("cancel after the first descriptor failure"); - let entered!: () => void; - let release!: () => void; - const waiting = new Promise((resolve) => { - entered = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); - let firstClosing!: () => void; - const firstCloseStarted = new Promise((resolve) => { - firstClosing = resolve; - }); + const peerClose = phaseGate(); + const firstClose = phaseArrival(); fault.onClose = async (handle) => { if (handle === fault.handles[0]) { - firstClosing(); + firstClose.arrive(); return; } - entered(); - await gate; + await peerClose.hold(); }; const client = new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: root }); const reading = client .listSessions({ signal: controller.signal }) .catch((cause: unknown) => cause); try { - await awaitAcknowledgement( - Promise.all([waiting, firstCloseStarted]).then(() => undefined), - reading, - "peer descriptor finalization", - ); + await Promise.all([ + peerClose.reached(reading, "peer descriptor finalization"), + firstClose.reached(reading, "first descriptor close"), + ]); // Let the first close rejection propagate while its peer remains gated. await new Promise((resolve) => setImmediate(resolve)); controller.abort(reason); - release(); + peerClose.release(); const failure = await reading; if ( !(failure instanceof AnalysisError) || @@ -300,7 +280,7 @@ it("does not assign a peer's later cancellation to a descriptor that already fai await client.close(); expect(failure.cleanupIncomplete).toBe(false); } finally { - release(); + peerClose.release(); fault.onClose = undefined; fault.blocked.clear(); await reading; diff --git a/tests/process-global/environmentFinalizationCli.test.ts b/tests/process-global/environmentFinalizationCli.test.ts index e75fca2536..86c5cd8cd6 100644 --- a/tests/process-global/environmentFinalizationCli.test.ts +++ b/tests/process-global/environmentFinalizationCli.test.ts @@ -5,7 +5,7 @@ import type { ServedEnvironment } from "../../src/server/environment/serveEnviro import type { ServeStreamableHttpOptions } from "../../src/server/http/serveStreamableHttp.js"; import { StreamableHttpListenError } from "../../src/server/http/streamableHttpListenError.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseArrival } from "../support/lifecycleHarness.js"; import { writeEnvironmentServeFiles } from "../fixtures/environmentServe.js"; const control = vi.hoisted(() => ({ @@ -102,11 +102,8 @@ it.each([ ); const originalExitCode = process.exitCode; const originalListeners = new Set(process.listeners("SIGINT")); - let ready!: () => void; - const started = new Promise((resolve) => { - ready = resolve; - }); - control.ready = ready; + const startup = phaseArrival(); + control.ready = () => startup.arrive(); control.served = undefined; control.failClose = fails; control.closeCalls = 0; @@ -131,7 +128,7 @@ it.each([ }, ); try { - await awaitAcknowledgement(started, pending, "environment CLI startup"); + await startup.reached(pending, "environment CLI startup"); const served = observedEnvironment(); if (served === undefined) throw new Error("Environment was not admitted"); if (ending === "signal") { diff --git a/tests/process-global/firmwareFileLifetime.test.ts b/tests/process-global/firmwareFileLifetime.test.ts index dc98151bd1..f876123826 100644 --- a/tests/process-global/firmwareFileLifetime.test.ts +++ b/tests/process-global/firmwareFileLifetime.test.ts @@ -13,7 +13,7 @@ import { join } from "node:path"; import { pathToFileURL } from "node:url"; import { promisify } from "node:util"; import { afterEach, beforeEach, expect, it, vi } from "vitest"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../support/lifecycleHarness.js"; const fault = vi.hoisted(() => ({ selected: "", @@ -884,18 +884,10 @@ it("waits through selected-range snapshot finalization when shutdown starts duri await mkdir(work); await writeFile(path, "firmware bytes"); fault.selected = path; - let enter!: () => void; - let release!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const sourceClose = phaseGate(); fault.onClose = async () => { fault.blocked.clear(); - enter(); - await gate; + await sourceClose.hold(); }; const files = new FirmwareFileAccess(); const pending = files.snapshot( @@ -914,14 +906,14 @@ it("waits through selected-range snapshot finalization when shutdown starts duri new AbortController().signal, ); try { - await awaitAcknowledgement(entered, pending, "firmware source close"); + await sourceClose.reached(pending, "firmware source close"); let closed = false; const closing = files.close().then(() => { closed = true; }); await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); - release(); + sourceClose.release(); const snapshot = await pending; await closing; expect(snapshot.selection).toMatchObject({ @@ -931,7 +923,7 @@ it("waits through selected-range snapshot finalization when shutdown starts duri }); expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true); } finally { - release(); + sourceClose.release(); await pending.catch(() => {}); await files.close(); } @@ -1021,21 +1013,13 @@ it("shares one workspace cleanup attempt across concurrent shutdown callers", as await writeFile(path, "firmware bytes"); let blocked = true; let attempts = 0; - let enter!: () => void; - let release!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const workspaceCleanup = phaseGate(); const close = PrivateRuntimeRoot.prototype.close; vi.spyOn(PrivateRuntimeRoot.prototype, "close").mockImplementation( async function (this: PrivateRuntimeRoot) { attempts++; if (blocked) throw new Error("controlled first workspace close failure"); - enter(); - await gate; + await workspaceCleanup.hold(); await close.call(this); }, ); @@ -1049,7 +1033,7 @@ it("shares one workspace cleanup attempt across concurrent shutdown callers", as blocked = false; const first = provider.close(); try { - await awaitAcknowledgement(entered, first, "firmware workspace cleanup"); + await workspaceCleanup.reached(first, "firmware workspace cleanup"); const second = provider.close(); let secondSettled = false; void second.then(() => { @@ -1058,11 +1042,11 @@ it("shares one workspace cleanup attempt across concurrent shutdown callers", as await Promise.resolve(); expect(secondSettled).toBe(false); expect(attempts).toBe(2); - release(); + workspaceCleanup.release(); await Promise.all([first, second]); expect(result.error.cleanupIncomplete).toBe(false); } finally { - release(); + workspaceCleanup.release(); await first; } }); diff --git a/tests/process-global/firmwarePublicationDeadline.test.ts b/tests/process-global/firmwarePublicationDeadline.test.ts index 9cf81b2cf8..c4140c857d 100644 --- a/tests/process-global/firmwarePublicationDeadline.test.ts +++ b/tests/process-global/firmwarePublicationDeadline.test.ts @@ -2,7 +2,7 @@ import { projectCliAnalysisResult } from "../../src/cli/projectCliAnalysisResult import { access, readFile } from "node:fs/promises"; import { join } from "node:path"; import { afterEach, expect, it, vi } from "vitest"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../support/lifecycleHarness.js"; import * as firmwareFiles from "../../src/firmware/FirmwareFiles.js"; import { SafeOutputTree } from "../../src/resources/SafeOutputTree.js"; import { PrivateRuntimeRoot } from "../../src/process/PrivateRuntimeRoot.js"; @@ -190,14 +190,7 @@ test("keeps each queued request's independent analysis and publication budgets", budgets.push(ms); return timeout(ms); }); - let enter!: () => void; - let release!: () => void; - const entered = new Promise((resolve) => { - enter = resolve; - }); - const gate = new Promise((resolve) => { - release = resolve; - }); + const publication = phaseGate(); const publish = firmwareFiles.FirmwareFileAccess.prototype.publish; let first = true; vi.spyOn( @@ -209,8 +202,7 @@ test("keeps each queued request's independent analysis and publication budgets", ) { if (first) { first = false; - enter(); - await gate; + await publication.hold(); } return publish.apply(this, args); }); @@ -222,7 +214,7 @@ test("keeps each queued request's independent analysis and publication budgets", }); let queued: typeof pending | undefined; try { - await awaitAcknowledgement(entered, pending, "firmware publication"); + await publication.reached(pending, "firmware publication"); queued = fixture.service.execute("extract_firmware", { path: fixture.path, output_directory: join(fixture.root, "second-output"), @@ -230,7 +222,7 @@ test("keeps each queued request's independent analysis and publication budgets", analysis_timeout_ms: 765_432, }); expect(budgets).toEqual([234_567, 123_456]); - release(); + publication.release(); const results = await Promise.all([pending, queued]); expect( results.map((result) => @@ -247,7 +239,7 @@ test("keeps each queued request's independent analysis and publication budgets", ]); expect(budgets).toEqual([234_567, 123_456, 765_432, 654_321]); } finally { - release(); + publication.release(); try { await Promise.allSettled([pending, queued]); } finally { diff --git a/tests/process-global/ghidraEndpointLifetime.test.ts b/tests/process-global/ghidraEndpointLifetime.test.ts index 1ca0cb0dc5..8ac1c0a7df 100644 --- a/tests/process-global/ghidraEndpointLifetime.test.ts +++ b/tests/process-global/ghidraEndpointLifetime.test.ts @@ -11,7 +11,7 @@ import { } from "node:fs/promises"; import { basename, join } from "node:path"; import { afterEach, beforeEach, expect, it, vi } from "vitest"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../support/lifecycleHarness.js"; const fault = vi.hoisted(() => ({ path: "", @@ -229,22 +229,17 @@ it.skipIf(process.platform === "win32")( "keeps endpoint observation admitted until its read and close finish", async () => { const { endpoint, resources } = await fixture(); - let entered: (() => void) | undefined; - const observed = new Promise((resolve) => { - entered = resolve; - }); - const gate = new Promise((resolve) => { - releaseRead = resolve; - }); + const endpointRead = phaseGate(); + // afterEach releases a read a failed test left held. + releaseRead = () => endpointRead.release(); fault.readGate = async () => { - entered?.(); - await gate; + await endpointRead.hold(); }; const pending = observeGhidraEndpoint(endpoint, { resourceScope: resources, }); operations.push(pending); - await awaitAcknowledgement(observed, pending, "Ghidra endpoint read"); + await endpointRead.reached(pending, "Ghidra endpoint read"); let closed = false; const closing = resources.close().then(() => { closed = true; @@ -252,7 +247,7 @@ it.skipIf(process.platform === "win32")( operations.push(closing); await new Promise((resolve) => setImmediate(resolve)); expect(closed).toBe(false); - releaseRead?.(); + endpointRead.release(); await expect(pending).resolves.toMatchObject({ ok: true }); await closing; expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true); diff --git a/tests/process-global/gpuFileLifetime.test.ts b/tests/process-global/gpuFileLifetime.test.ts index 98ba4ede28..907e21f7ee 100644 --- a/tests/process-global/gpuFileLifetime.test.ts +++ b/tests/process-global/gpuFileLifetime.test.ts @@ -9,7 +9,7 @@ import { gpuCodeObjectsSchema, } from "../../src/domain/gpu/gpuCodeObjects.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../support/lifecycleHarness.js"; import { amdFixture, cudaFixture } from "../fixtures/gpu/codeObjects.js"; type ReadFile = ( buffer: Buffer, @@ -208,13 +208,7 @@ it("preserves completed observations when caller cancellation arrives during fin it("joins an admitted file read during shutdown and rejects overlapping work", async () => { const { path, prototype, provider } = await fixture(); - let entered!: () => void, release!: () => void; - const admitted = new Promise((resolve) => { - entered = resolve; - }), - barrier = new Promise((resolve) => { - release = resolve; - }); + const fileRead = phaseGate(); const read = prototype.read; let blocked = false; const spy = vi.spyOn(prototype, "read").mockImplementation(async function ( @@ -223,8 +217,7 @@ it("joins an admitted file read during shutdown and rejects overlapping work", a ) { if (!blocked) { blocked = true; - entered(); - await barrier; + await fileRead.hold(); } return read.apply(this, args); }); @@ -232,7 +225,7 @@ it("joins an admitted file read during shutdown and rejects overlapping work", a let closing: Promise | undefined; try { active = provider.inspect({ path, analysis: "kernels" }); - await awaitAcknowledgement(admitted, active, "GPU file read admission"); + await fileRead.reached(active, "GPU file read admission"); let closed = false; closing = provider.close().then(() => { closed = true; @@ -243,13 +236,13 @@ it("joins an admitted file read during shutdown and rejects overlapping work", a error: { _tag: "AnalysisResourceConstraintError" }, }); expect(closed).toBe(false); - release(); + fileRead.release(); const result = await active; expect(result.ok).toBe(true); await closing; expect(closed).toBe(true); } finally { - release(); + fileRead.release(); try { try { await active; diff --git a/tests/process-global/idaWorkspaceCleanup.test.ts b/tests/process-global/idaWorkspaceCleanup.test.ts index dbdc40b1a4..108e409983 100644 --- a/tests/process-global/idaWorkspaceCleanup.test.ts +++ b/tests/process-global/idaWorkspaceCleanup.test.ts @@ -2,6 +2,7 @@ import { createHash } from "node:crypto"; import { access, readFile, writeFile, type FileHandle } from "node:fs/promises"; import { join } from "node:path"; import { afterEach, expect, it, vi } from "vitest"; +import { phaseGate } from "../support/lifecycleHarness.js"; import { ArtifactFileCleanupFailure } from "../../src/resources/ArtifactFileOperation.js"; import { ArtifactReaderFailure } from "../../src/resources/ArtifactReader.js"; @@ -12,8 +13,6 @@ import { IdaWorkspace } from "../../src/ida/IdaWorkspace.js"; import { IdaSessionClient } from "../../src/ida/IdaSessionClient.js"; import { PrivateRuntimeRoot } from "../../src/process/PrivateRuntimeRoot.js"; import { RecordingIdaMcp } from "../fixtures/idaMcp.js"; -import { createDeferred } from "../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; interface ObservedHandle { @@ -411,22 +410,20 @@ it("keeps shared IDA startup owned when the caller leaves during source finaliza it("joins an admitted copy before removing its root and refuses new copy admission", async () => { const { workspace, target } = await fixture(); - const entered = createDeferred(); - const release = createDeferred(); + const copyRead = phaseGate(); control.install = ({ handle, path }) => { if (path !== target.path) return; const reading: CopyReadPort = handle; const read = reading.read.bind(handle); vi.spyOn(reading, "read").mockImplementation(async (...args) => { - entered.resolve(); - await release.promise; + await copyRead.hold(); return read(...args); }); }; const copying = workspace.copyInput(); let removing: Promise | undefined; try { - await awaitAcknowledgement(entered.promise, copying, "selected copy read"); + await copyRead.reached(copying, "selected copy read"); let removed = false; removing = workspace.remove().then(() => { removed = true; @@ -436,12 +433,12 @@ it("joins an admitted copy before removing its root and refuses new copy admissi }); expect(removed).toBe(false); await access(workspace.directory); - release.resolve(); + copyRead.release(); await copying; await removing; expect(workspace.inputSha256).toBe(target.sha256); } finally { - release.resolve(); + copyRead.release(); await Promise.allSettled([copying, removing]); } }); diff --git a/tests/process-global/mainStartupCancellation.test.ts b/tests/process-global/mainStartupCancellation.test.ts index ac6c11a5b0..28312e5136 100644 --- a/tests/process-global/mainStartupCancellation.test.ts +++ b/tests/process-global/mainStartupCancellation.test.ts @@ -1,6 +1,7 @@ import { EventEmitter } from "node:events"; import { PassThrough } from "node:stream"; import { afterEach, expect, it, vi } from "vitest"; +import { phaseArrival, phaseGate } from "../support/lifecycleHarness.js"; import { StdioServerTransport } from "@modelcontextprotocol/server/stdio"; import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server"; import type { BinarySession } from "../../src/application/binary/BinarySession.js"; @@ -12,11 +13,7 @@ import { run } from "../../src/main.js"; import { registerProcessShutdown } from "../../src/main/processShutdown.js"; import { ownStdioStartupInput } from "../../src/main/StdioStartupInput.js"; import { MCP_SHUTDOWN_FAILED } from "../../src/main/messages.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; -import { - createDeferred, - createTestBinarySession, -} from "../fixtures/binarySession.js"; +import { createTestBinarySession } from "../fixtures/binarySession.js"; const control = vi.hoisted(() => ({ session: undefined as BinarySession | undefined, @@ -67,12 +64,12 @@ it.each([ const session = sessionOwner(); const input = new PassThrough(); const signals = new EventEmitter(); - const entered = createDeferred(); + const initialOpen = phaseArrival(); vi.spyOn(session, "open").mockImplementation(async (_path, options) => { const signal = options?.signal; if (signal === undefined) throw new Error("Initial open has no cancellation owner"); - entered.resolve(signal); + initialOpen.arrive(signal); await new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }), ); @@ -109,12 +106,7 @@ it.each([ registerProcessShutdown(handler, { signals, stdin: input }), }); try { - await awaitAcknowledgement( - entered.promise.then(() => undefined), - pending, - "initial target open", - ); - const signal = await entered.promise; + const signal = await initialOpen.reached(pending, "initial target open"); expect(signals.listenerCount("SIGINT")).toBe(1); expect(signals.listenerCount("SIGTERM")).toBe(1); if (trigger === "EOF") input.end(); @@ -161,12 +153,10 @@ it.each(["optional", "late-handle"] as const)( const closeSession = vi.spyOn(session, "close").mockResolvedValue(ok(null)); const input = new PassThrough(); const signals = new EventEmitter(); - const entered = createDeferred(); - const release = createDeferred(); + const startupStage = phaseGate(); const closeHandle = vi.fn(async () => {}); const serve = vi.fn(async () => { - entered.resolve(); - await release.promise; + await startupStage.hold(); return { close: closeHandle }; }); const pending = run({ @@ -175,8 +165,7 @@ it.each(["optional", "late-handle"] as const)( serve, loadOptionalProviders: async () => { if (stage === "optional") { - entered.resolve(); - await release.promise; + await startupStage.hold(); } return {}; }, @@ -186,7 +175,7 @@ it.each(["optional", "late-handle"] as const)( registerProcessShutdown(handler, { signals, stdin: input }), }); try { - await awaitAcknowledgement(entered.promise, pending, "startup stage"); + await startupStage.reached(pending, "startup stage"); if (stage === "optional") { await new Promise((resolve) => { input.once("end", resolve); @@ -195,7 +184,7 @@ it.each(["optional", "late-handle"] as const)( } else signals.emit("SIGTERM"); expect(closeHandle).not.toHaveBeenCalled(); expect(closeSession).not.toHaveBeenCalled(); - release.resolve(); + startupStage.release(); expect(await pending).toBe(0); expect(serve).toHaveBeenCalledTimes(stage === "optional" ? 0 : 1); expect(closeHandle).toHaveBeenCalledTimes(stage === "optional" ? 0 : 1); @@ -206,7 +195,7 @@ it.each(["optional", "late-handle"] as const)( expect(signals.listenerCount("SIGINT")).toBe(0); } finally { signals.emit("SIGTERM"); - release.resolve(); + startupStage.release(); input.destroy(); await pending.catch(() => undefined); } diff --git a/tests/process-global/managedBundleReadGuards.test.ts b/tests/process-global/managedBundleReadGuards.test.ts index eeb98da482..4150254ab3 100644 --- a/tests/process-global/managedBundleReadGuards.test.ts +++ b/tests/process-global/managedBundleReadGuards.test.ts @@ -211,7 +211,7 @@ it("preserves the view operation and caller reason when bundle I/O is cancelled" undefined, { evidenceBundlePath: path, resources, signal: controller.signal }, ); - await held.firstRead; + await held.reached(pending, "first file read"); controller.abort(reason); held.release(); const result = await pending; diff --git a/tests/process-global/pwntoolsCleanup.test.ts b/tests/process-global/pwntoolsCleanup.test.ts index 4105a67e2d..8e1090880e 100644 --- a/tests/process-global/pwntoolsCleanup.test.ts +++ b/tests/process-global/pwntoolsCleanup.test.ts @@ -9,7 +9,7 @@ import { spawnOwnedProviderProcess } from "../../src/process/ProviderProcess.js" import { cleanupOwnedProcessGroup } from "../../src/process/ProcessOwnership.js"; import { prepareProcessOwnershipInspection } from "../../src/process/ProcessOwnershipObservation.js"; import { stopProviderProcessFixture } from "../fixtures/providerProcess.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../support/lifecycleHarness.js"; import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.js"; import { createTestWorkspace, @@ -215,21 +215,13 @@ it.runIf(supportedHost)( "cancels queued inspections promptly and drains the running inspection when closing", async () => { const { workspace, path } = await fixture(); - let release: (() => void) | undefined; - let entered: (() => void) | undefined; - const gate = new Promise((resolve) => { - release = resolve; - }); - const started = new Promise((resolve) => { - entered = resolve; - }); + const launch = phaseGate(); let launches = 0; const provider = new PwntoolsLayoutProvider( { REA_PWNTOOLS_PYTHON: process.execPath }, async (input) => { launches++; - entered?.(); - await gate; + await launch.hold(); return spawnOwnedProviderProcess({ ...input, arguments: ["-e", "process.exit(2)"], @@ -240,11 +232,11 @@ it.runIf(supportedHost)( SIMULATED_LINUX_X64, ); onTestFinished(async () => { - release?.(); + launch.release(); await provider.close(); }); const first = provider.inspect({ path }); - await awaitAcknowledgement(started, first, "pwntools launch"); + await launch.reached(first, "pwntools launch"); const controller = new AbortController(); const cancelled = provider.inspect({ path }, { signal: controller.signal }); const reason = { stage: "queued" }; @@ -259,7 +251,7 @@ it.runIf(supportedHost)( const queued = provider.inspect({ path }); const closing = provider.close(); const late = provider.inspect({ path }); - release?.(); + launch.release(); const [firstResult, queuedResult, lateResult] = await Promise.all([ first, queued, diff --git a/tests/process-global/referenceSourceCancellation.test.ts b/tests/process-global/referenceSourceCancellation.test.ts index 7113df50b0..2f92f8e1b6 100644 --- a/tests/process-global/referenceSourceCancellation.test.ts +++ b/tests/process-global/referenceSourceCancellation.test.ts @@ -65,7 +65,7 @@ it.each([ }); try { if (held !== undefined) { - await held.firstRead; + await held.reached(running, "first file read"); process.emit(signal); held.release(); } diff --git a/tests/process-global/selectedArtifactSourceLifecycle.test.ts b/tests/process-global/selectedArtifactSourceLifecycle.test.ts index 142bb8c48d..49ea935361 100644 --- a/tests/process-global/selectedArtifactSourceLifecycle.test.ts +++ b/tests/process-global/selectedArtifactSourceLifecycle.test.ts @@ -11,6 +11,7 @@ import { join } from "node:path"; import { buffer } from "node:stream/consumers"; import { setImmediate } from "node:timers/promises"; import { afterEach, expect, it, vi } from "vitest"; +import { phaseGate } from "../support/lifecycleHarness.js"; import { ArtifactFileSource } from "../../src/artifacts/ArtifactFileSource.js"; import * as artifactHash from "../../src/artifacts/ArtifactHash.js"; @@ -25,8 +26,6 @@ import { machoImage, } from "../../src/artifacts/apple/MachoImage.fixture.js"; import * as regularFile from "../../src/filesystem/RegularFile.js"; -import { createDeferred } from "../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; import { NativeFixtureRunner } from "../fixtures/nativeCommands.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; @@ -134,12 +133,10 @@ const expectDescriptorUnchanged = async ( it("joins late Mach-O admission before releasing its descriptor and dispatches no lipo after closure", async () => { const fixture = await machoCarrier(); - const entered = createDeferred(); - const release = createDeferred(); + const admission = phaseGate(); control.onOpen = async (handle) => { vi.spyOn(handle, "close"); - entered.resolve(); - await release.promise; + await admission.hold(); }; const run = vi.spyOn(fixture.runner, "run"); const reader = new MachOSliceArtifactReader(fixture.path, {}, fixture.runner); @@ -148,7 +145,7 @@ it("joins late Mach-O admission before releasing its descriptor and dispatches n const operation = entries(reader); const reading = operation.catch((cause: unknown) => cause); operations.push(reading); - await awaitAcknowledgement(entered.promise, operation, "Mach-O admission"); + await admission.reached(operation, "Mach-O admission"); const handle = openedHandle(); let closed = false; const closings = [reader.close(), reader.close()]; @@ -161,7 +158,7 @@ it("joins late Mach-O admission before releasing its descriptor and dispatches n expect(closed).toBe(false); expect(handle.fd).toBeGreaterThanOrEqual(0); expect(handle.close).not.toHaveBeenCalled(); - release.resolve(); + admission.release(); expect(await reading).toMatchObject({ reason: "unavailable" }); await closing; expect(handle.fd).toBe(-1); @@ -174,7 +171,7 @@ it("joins late Mach-O admission before releasing its descriptor and dispatches n await reader.close(); expect(handle.close).toHaveBeenCalledOnce(); } finally { - release.resolve(); + admission.release(); await Promise.allSettled(operations); await reader.close(); } @@ -296,16 +293,14 @@ it.each([false, true])( "rejects selected pathname replacement after real hashing even with a late abort (%s)", async (abort) => { const fixture = await machoCarrier(); - const completed = createDeferred(); - const release = createDeferred(); + const hashCompletion = phaseGate(); const controller = new AbortController(); const originalHash = artifactHash.hashReadable; vi.spyOn(artifactHash, "hashReadable").mockImplementation( async (...args) => { const hashed = await originalHash(...args); expect(hashed.sha256).toBe(fixture.sha256); - completed.resolve(); - await release.promise; + await hashCompletion.hold(); return hashed; }, ); @@ -317,18 +312,14 @@ it.each([false, true])( controller.signal, ); binding = operation.catch((cause: unknown) => cause); - await awaitAcknowledgement( - completed.promise, - operation, - "selected carrier hash", - ); + await hashCompletion.reached(operation, "selected carrier hash"); const handle = openedHandle(); const initial = await handle.stat(); await replaceSelectedDirectory(fixture); await expectDescriptorUnchanged(handle, initial); if (abort) controller.abort({ request: "cancel after completed carrier hash" }); - release.resolve(); + hashCompletion.release(); const failure = await binding; if (!(failure instanceof ArtifactReaderFailure)) throw new Error("Expected a selected-path identity failure"); @@ -340,7 +331,7 @@ it.each([false, true])( await source.close(); expect(handle.fd).toBe(-1); } finally { - release.resolve(); + hashCompletion.release(); await binding; await source.close(); } diff --git a/tests/process-global/setupConfigurationConflicts.test.ts b/tests/process-global/setupConfigurationConflicts.test.ts index 1600b43e0a..3e9f384314 100644 --- a/tests/process-global/setupConfigurationConflicts.test.ts +++ b/tests/process-global/setupConfigurationConflicts.test.ts @@ -11,7 +11,7 @@ import { } from "node:fs/promises"; import { join, relative } from "node:path"; import { afterEach, expect, it, vi } from "vitest"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; +import { phaseGate } from "../support/lifecycleHarness.js"; const writers = vi.hoisted(() => ({ before: undefined as undefined | ((path: string) => Promise), @@ -347,19 +347,11 @@ it.skipIf(process.platform === "win32")( if (presence === "existing") await writeFile(realPath, "{}\n"); const entered: string[] = []; - let releaseFirst!: () => void; - const release = new Promise((resolve) => { - releaseFirst = resolve; - }); - let markStarted!: () => void; - const started = new Promise((resolve) => { - markStarted = resolve; - }); + const writer = phaseGate(); writers.before = async (target) => { entered.push(target); if (entered.length === 1) { - markStarted(); - await release; + await writer.hold(); } }; @@ -374,11 +366,7 @@ it.skipIf(process.platform === "win32")( ); let second: ReturnType | undefined; try { - await awaitAcknowledgement( - started, - first, - "setup configuration writer", - ); + await writer.reached(first, "setup configuration writer"); second = configureClientConfiguration( { name: "cursor", @@ -404,7 +392,7 @@ it.skipIf(process.platform === "win32")( }); expect(secondReachedWriter).toBe(false); expect(entered).toEqual([realPath]); - releaseFirst(); + writer.release(); const [firstResult, secondResult] = await Promise.all([first, second]); expect([firstResult.status, secondResult.status]).toEqual([ "configured", @@ -417,7 +405,7 @@ it.skipIf(process.platform === "win32")( await readFile(realPath, "utf8"), ); } finally { - releaseFirst(); + writer.release(); writers.before = undefined; await Promise.allSettled([first, second]); } @@ -457,27 +445,19 @@ it("releases a failed setup transaction so a queued request can configure the fi configPath: path, format: "json", } as const; - let markStarted!: () => void; - const started = new Promise((resolve) => { - markStarted = resolve; - }); - let releaseWriter!: () => void; - const release = new Promise((resolve) => { - releaseWriter = resolve; - }); + const writer = phaseGate(); writers.before = async () => { writers.before = undefined; - markStarted(); - await release; + await writer.hold(); throw new Error("The first writer could not stage its configuration"); }; const first = configureClientConfiguration(client, { FIRST: "1" }); let second: ReturnType | undefined; try { - await awaitAcknowledgement(started, first, "setup configuration writer"); + await writer.reached(first, "setup configuration writer"); second = configureClientConfiguration(client, { SECOND: "2" }); - releaseWriter(); + writer.release(); const [failed, queued] = await Promise.all([first, second]); expect(failed).toMatchObject({ @@ -500,7 +480,7 @@ it("releases a failed setup transaction so a queued request can configure the fi status: "unchanged", }); } finally { - releaseWriter(); + writer.release(); writers.before = undefined; await Promise.allSettled([first, second]); } diff --git a/tests/process-global/setupConfigurationRollback.test.ts b/tests/process-global/setupConfigurationRollback.test.ts index 1cdec09bf0..e27e746d87 100644 --- a/tests/process-global/setupConfigurationRollback.test.ts +++ b/tests/process-global/setupConfigurationRollback.test.ts @@ -3,6 +3,7 @@ import { createHash } from "node:crypto"; import { join } from "node:path"; import { afterEach, expect, it, onTestFinished, vi } from "vitest"; +import { phaseGate } from "../support/lifecycleHarness.js"; const state = vi.hoisted(() => ({ readbackFailed: false, @@ -155,8 +156,6 @@ import { AnalysisError } from "../../src/domain/analysisErrorBase.js"; import { systemUninstallHost } from "../../src/application/Uninstall.js"; import { ConfigurationError } from "../../src/domain/configurationErrors.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; -import { createDeferred } from "../fixtures/binarySession.js"; -import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; import { supportedClientRegistrationProfile } from "../../src/application/SupportedClients.js"; const ownReadHandle = async (path: string) => { @@ -842,11 +841,9 @@ it("uninstall close joins a publication already admitted by its host", async () path, '{"mcpServers":{"rea":{"command":"rea","args":["mcp"]}}}\n', ); - const arrived = createDeferred(); - const release = createDeferred(); + const publication = phaseGate(); state.afterPublication = async () => { - arrived.resolve(); - await release.promise; + await publication.hold(); }; const host = systemUninstallHost(root); const removal = host.removeClient({ @@ -858,11 +855,7 @@ it("uninstall close joins a publication already admitted by its host", async () let closed = false; let closing: ReturnType> | undefined; try { - await awaitAcknowledgement( - arrived.promise, - removal, - "configuration publication", - ); + await publication.reached(removal, "configuration publication"); closing = host.close?.().then((result) => { closed = true; return result; @@ -871,7 +864,7 @@ it("uninstall close joins a publication already admitted by its host", async () expect(closed).toBe(false); expect(state.publicationHandles[0]!.fd).toBeGreaterThanOrEqual(0); } finally { - release.resolve(); + publication.release(); await Promise.allSettled([removal, ...(closing ? [closing] : [])]); await host.close?.(); } @@ -1027,12 +1020,10 @@ it("uninstall progresses when a peer leaves a denied-close descriptor pending", if (rejectClose) throw new Error("peer close denied"); await close(); }; - const arrived = createDeferred(); - const release = createDeferred(); + const publication = phaseGate(); state.failReadback = false; state.afterPublication = async () => { - arrived.resolve(); - await release.promise; + await publication.hold(); }; const host = systemUninstallHost(root); const removal = host.removeClient({ @@ -1043,11 +1034,7 @@ it("uninstall progresses when a peer leaves a denied-close descriptor pending", }); let timeout: ReturnType | undefined; try { - await awaitAcknowledgement( - arrived.promise, - removal, - "configuration publication", - ); + await publication.reached(removal, "configuration publication"); state.initialCleanupFailure = new RegularFileCleanupFailure({ path: other, owner, @@ -1064,7 +1051,7 @@ it("uninstall progresses when a peer leaves a denied-close descriptor pending", }), ).toMatchObject({ status: "failed" }); state.initialCleanupFailure = undefined; - release.resolve(); + publication.release(); const result = await Promise.race([ removal, new Promise((_resolve, reject) => { @@ -1087,7 +1074,7 @@ it("uninstall progresses when a peer leaves a denied-close descriptor pending", if (timeout !== undefined) clearTimeout(timeout); state.initialCleanupFailure = undefined; rejectClose = false; - release.resolve(); + publication.release(); await owner.close(); for (const handle of state.publicationHandles) if (handle.fd >= 0) await handle.close(); diff --git a/tests/process-global/sourceToBundleReferenceGuards.test.ts b/tests/process-global/sourceToBundleReferenceGuards.test.ts index bfc0ebc59d..fe8aec4e3b 100644 --- a/tests/process-global/sourceToBundleReferenceGuards.test.ts +++ b/tests/process-global/sourceToBundleReferenceGuards.test.ts @@ -81,7 +81,7 @@ it("attributes file-I/O cancellation to the comparison and preserves its exact c controller.signal, resources, ); - await held.firstRead; + await held.reached(pending, "first file read"); controller.abort(cause); held.release(); const result = await pending; diff --git a/tests/support/holdFirstFileRead.ts b/tests/support/holdFirstFileRead.ts index 3d50828917..81dc820cd8 100644 --- a/tests/support/holdFirstFileRead.ts +++ b/tests/support/holdFirstFileRead.ts @@ -1,6 +1,8 @@ import { open, type FileHandle } from "node:fs/promises"; import { vi } from "vitest"; +import { phaseGate } from "./lifecycleHarness.js"; + /** Pause after one selected file chunk reaches the operating system. */ export const holdFirstFileRead = async (path: string) => { const probe = await open(path, "r"); @@ -16,14 +18,7 @@ export const holdFirstFileRead = async (path: string) => { await probe.close(); let totalReadBytes = 0; let readCount = 0; - let resolveFirstRead: (() => void) | undefined; - const firstRead = new Promise((resolve) => { - resolveFirstRead = resolve; - }); - let releaseRead: (() => void) | undefined; - const readGate = new Promise((resolve) => { - releaseRead = resolve; - }); + const firstRead = phaseGate(); const read = fileHandlePrototype.read; vi.spyOn(fileHandlePrototype, "read").mockImplementation(async function ( this: FileHandle, @@ -36,15 +31,13 @@ export const holdFirstFileRead = async (path: string) => { if (!isTarget) return result; totalReadBytes += result.bytesRead; readCount += 1; - if (readCount === 1) { - resolveFirstRead?.(); - await readGate; - } + if (readCount === 1) await firstRead.hold(); return result; }); return { - firstRead, - release: () => releaseRead?.(), + /** Wait until the first read is held; fails if `operation` settles first. */ + reached: firstRead.reached, + release: () => firstRead.release(), get readCount() { return readCount; }, diff --git a/tests/support/lifecycleHarness.ts b/tests/support/lifecycleHarness.ts index c78327f3ad..cfadf3e8b6 100644 --- a/tests/support/lifecycleHarness.ts +++ b/tests/support/lifecycleHarness.ts @@ -3,11 +3,43 @@ import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; /** * Controls for the scenarios in * docs/development/testing.md#lifecycle-regressions that a fixed delay cannot - * establish: a late handshake or work still in flight at close (`phaseGate`), + * establish: a late handshake or work still in flight at close (`phaseGate`, + * or `phaseArrival` when the work waits on something other than a release), * cancellation during final cleanup (`cancelDuringCleanup`), and mixed child * cleanup outcomes with retry (`controlledCleanup`). */ +/** + * A phase boundary the code under test only announces: it calls `arrive` and + * keeps going (or waits on something the test triggers, such as an abort), + * and the test waits until the boundary is `reached`. + */ +export interface PhaseArrival { + /** Called by the code under test: records arrival with `value`. */ + arrive(value: T): void; + /** + * Resolve with the arrival value once the boundary is reached. Fails if + * `operation` settles first or the test wait deadline passes. + */ + reached(operation: Promise, boundary: string): Promise; +} + +export const phaseArrival = (): PhaseArrival => { + let arrive!: (value: T) => void; + const arrived = new Promise((resolve) => { + arrive = resolve; + }); + return { + arrive, + reached: async (operation, boundary) => { + // Pass `arrived` itself: a derived promise would settle a turn later + // and lose the race to an operation that settles right after arriving. + await awaitAcknowledgement(arrived, operation, boundary); + return arrived; + }, + }; +}; + /** * A phase boundary the test holds open. The code under test calls `hold` at * the boundary and waits there; the test waits until the boundary is @@ -33,10 +65,7 @@ export interface PhaseGate { } export const phaseGate = (): PhaseGate => { - let arrive!: (value: T) => void; - const arrived = new Promise((resolve) => { - arrive = resolve; - }); + const arrival = phaseArrival(); let release!: (value: R) => void; let reject!: (error: unknown) => void; const released = new Promise((resolve, refuse) => { @@ -46,18 +75,14 @@ export const phaseGate = (): PhaseGate => { // A rejection before any `hold` is observed by that later `hold`, not here. released.catch(() => {}); return { + // Each hold gets its own promise, so code under test that leaves a held + // rejection unhandled is still reported; the guard above covers only the + // gate's shared outcome. hold: (value) => { - arrive(value); - return released; - }, - reached: async (operation, boundary) => { - await awaitAcknowledgement( - arrived.then(() => {}), - operation, - boundary, - ); - return arrived; + arrival.arrive(value); + return released.then((outcome) => outcome); }, + reached: arrival.reached, release, reject, };