Files
reverse-engineering-anything/src/application/binary/AnalysisProviderRegistry.test.ts
T
morluto df1e647266 refactor(desktop): let build-computer and agentenv cleanup errors read their owner's release (#10855)
* refactor(errors): read cleanup completion from dependencies instead of pushing it to dependents

AnalysisError.cleanupIncomplete becomes a getter over the error's own unresolved state and its bound dependencies. The WeakRef dependents graph and resolveCleanup's push propagation are removed, and subclasses mark their initial state through markCleanupIncomplete instead of overriding a public mutable field.

* fix(errors): settle bound dependencies before binding more

A composite whose dependencies had released but whose status was never read
stayed incomplete when a later dependency was bound.

* refactor(errors): let errors read a lease group's release instead of resolving them (#10759)

AnalysisCleanupLeaseGroup no longer calls resolveCleanup() on its error.
The error holds the group as a release claim and reads cleanupReleased when
asked, so completion follows the lease owner without a push.

* chore(verify): count resolveCleanup and bindCleanupDependencies calls so they only shrink (#10763)

* refactor(errors): let errors read a lease group's release instead of resolving them

AnalysisCleanupLeaseGroup no longer calls resolveCleanup() on its error.
The error holds the group as a release claim and reads cleanupReleased when
asked, so completion follows the lease owner without a push.

* chore(verify): count resolveCleanup and bindCleanupDependencies calls so they only shrink

* refactor(process): let worker cleanup errors read their root epoch's release

OwnedWorkerRuntime's root epoch is now an AnalysisCleanupReleaseClaim. Errors bound to it read its release when asked instead of the epoch pushing resolveCleanup() through weak references, and a runtime without a retained root binds an already-released owner. Removes the OwnedWorkerCleanupFailure structural type and four resolveCleanup() pushes; the counted baseline shrinks accordingly.

* refactor(pcap): let pcap cleanup errors read command and snapshot release (#10792)

Retained pcap commands, retained snapshot failures and snapshot completion descriptors now own their release and errors read it: commands and snapshot failures implement AnalysisCleanupReleaseClaim, and a failed completion-descriptor close is retried through an AnalysisCleanupLease bound to its error. Removes four resolveCleanup() pushes; the counted baseline shrinks accordingly.

* refactor(process): let Darwin helper cleanup errors read their owner's release

Darwin helper cache and run-token reader root cleanup now record an AnalysisCleanupRelease that every failure reports; a successful retry confirms it. Replaces the first-failure anchor that later failures depended on and the resolveCleanup() push. Removes two resolveCleanup() and two bindCleanupDependencies() calls; both counted baselines shrink.

* refactor(ghidra): let Ghidra cleanup errors read the client's and checkpoint's release

GhidraClient and GhidraCheckpoint bind each cleanup failure to an AnalysisCleanupRelease and confirm it when a later close or retry releases everything, instead of keeping a set of failures and pushing resolveCleanup() to each. Removes two resolveCleanup() calls; the counted baseline shrinks.

* refactor(process): let debugger session cleanup errors read a confirmed stop

OwnedDebuggerSessionRegistry binds each retained gdb or rizin cleanup failure to the session's AnalysisCleanupRelease and confirms it when a stop is confirmed, keeping the latest failure for retry reporting, instead of pushing resolveCleanup() to a set of failures. Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(process): drop the debugger registry's unused closeOperation option

Returning the latest retained failure removed the last reader of closeOperation; remove the option and the values gdb and rizin supplied.

* refactor(server): let environment shutdown errors read a successful close

serveEnvironment binds each shutdown failure to an AnalysisCleanupRelease that a later successful close confirms, instead of pushing resolveCleanup() to a set of failures. The state-file retry test now also requires the earlier report to read the release. Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(desktop): release retained screen-judge cleanup through its lease

Each retained judge or screenshot cleanup owner is wrapped in an AnalysisCleanupLease bound to its failure; close() releases the lease, which records the release the failure reads, instead of closing the owner and pushing resolveCleanup(). Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(ida): let IDA close failures read the session's later close

IdaSessionClient's close failure binds an owner that is both its resource owner and its release claim, read from the client's closed state, instead of keeping weak references and pushing resolveCleanup() after a successful retry. Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(javascript): let source-map codec cleanup errors read a later close (#10814)

* refactor(javascript): let source-map codec cleanup errors read a later close

OwnedCodec binds each close failure to an AnalysisCleanupRelease that a later successful close confirms, replacing the first-failure anchor that later failures depended on and the resolveCleanup() push. Removes one resolveCleanup() and one bindCleanupDependencies() call; both counted baselines shrink.

* refactor(cutter): let pending Cutter command errors read the completion receipt (#10815)

* refactor(cutter): let pending Cutter command errors read the completion receipt

Each pending Cutter command keeps an AnalysisCleanupRelease bound to its timeout failure; the producer's terminal completion receipt confirms it instead of pushing resolveCleanup(). Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(application): let provider candidate cleanup errors read the candidate's close (#10817)

* refactor(application): let provider candidate cleanup errors read the candidate's close

AnalysisProviderRegistry keeps one AnalysisCleanupRelease per candidate whose resource close is unconfirmed; failures bind to it and a later confirmed close confirms it, instead of pushing resolveCleanup() to a set of failures. Removes one resolveCleanup() call; the counted baseline shrinks.

* fix(errors): bind a cleanup release claim to an error at most once

AnalysisError kept release claims in an array, so a provider whose retried close returned the same error bound the same claim again on every retry and each cleanupIncomplete read scanned the duplicates. Keep the claims in a set.

* refactor(application): let reverse-tool cleanup errors read a verified stop (#10819)

* refactor(application): let reverse-tool cleanup errors read a verified stop

Each retained provider process group in ReverseEngineeringService keeps an AnalysisCleanupRelease; its command and retry failures bind to it and a later verified stop confirms it, instead of collecting failures and pushing resolveCleanup(). Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(sqlite): let SQLite worker and root cleanup errors read their release (#10821)

Each retained SQLite snapshot cleanup records an AnalysisCleanupRelease for its worker and for its runtime root; the resource failures bind to them and a verified stop or root removal confirms them, instead of pushing resolveCleanup(). Composite failures keep reading those resource failures. Removes two resolveCleanup() calls; the counted baseline shrinks.

* refactor(android): let JADX cleanup errors read their retained cleanup's release

Each retained JADX cleanup records an AnalysisCleanupRelease for the admission failure's descriptor owners and one for the whole retained cleanup. The admission failure and every error the cleanup reports bind to them, and a confirmed close confirms them, instead of pushing resolveCleanup() through WeakRefs to reported errors. Removes two resolveCleanup() calls; the counted baseline shrinks.

* refactor(application): let session close failures read the client's later close

A retained session cleanup records an AnalysisCleanupRelease; unowned cleanup failures the client's close reported bind to it and the successful close confirms it, instead of the session collecting them and pushing resolveCleanup(). Failures that already follow their own owner keep reading it. Adds a regression for an unowned close failure. Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(desktop): let build-computer and agentenv cleanup errors read their owner's release

Build-computer teardown, retained task readers, remote reader folders and agentenv solve sandboxes each record an AnalysisCleanupRelease that their bound failures read; a verified teardown or stop confirms it instead of pushing resolveCleanup() through WeakRef sets. Long-run job failures read whether every job they name has confirmed its stop, so a failure naming two jobs no longer reads complete when only one stops (regression added). WeakRef sets kept only where late facts (completion receipts, reader views) are still retained as diagnostics. Removes six resolveCleanup() calls; the counted baseline shrinks.

* refactor(kuna): let source-map and Kuna cache cleanup errors read their owner's release (#10856)

* refactor(browser): let late source-map fetch errors read their response's release

A pending source-map fetch and a response cancellation each record an AnalysisCleanupRelease that their cancellation or deadline failure reads; releasing the late response or the reader lock confirms it instead of pushing resolveCleanup(). Removes two resolveCleanup() calls; the counted baseline shrinks.

* refactor(kuna): let project-cache cleanup errors read each owner's release

Each retained Kuna resource owner (process, staging, hash descriptor, retired file) records a release that the errors reporting it read; an error completes once every owner it reports confirms, and retirement that moves staging to a retained file forwards the staging owner's release to the file's. Replaces the WeakRef report list, its pruning and the resolveCleanup() push. Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(process): forbid resolveCleanup() pushes; native markers read their supervisor's release (#10857)

* refactor(providers): let an attributed client failure read its source's completed cleanup

Re-attributing a failure whose source cleanup already completed now binds a claim reading that source's release instead of pushing resolveCleanup() onto the new error; a pending source is still bound as a dependency. Resources stay as history, as before. Removes one resolveCleanup() call; the counted baseline shrinks.

* refactor(process): let native command markers read their supervisor's release

ProviderProcessSupervisor records an AnalysisCleanupRelease that a stop proving the process ended confirms. Native command and LLDB resolver cleanup markers bind to their supervisor's release, so a verified stop by either owner completes them, instead of each owner pushing resolveCleanup() onto the markers it tracks. Removes the last two resolveCleanup() calls outside the error base; the counted baseline is empty.

* chore(verify): forbid resolveCleanup() pushes outside the error base

Every production owner now confirms a release its errors read, so the counted baseline is empty. The guard becomes an outright ban with no baseline entry.

* test(native): complete native command and LLDB markers through a direct supervisor stop

* refactor(errors): complete an error's cleanup from its owner's record and every dependency (#10892)

* refactor(errors): complete an error's cleanup from its owner's record and every dependency

* refactor(errors): complete test errors through an owner release and delete resolveCleanup() (#10898)

* refactor(android): compose JADX and Apktool cleanup failures through one shared owner (#10900)

* refactor(android): compose JADX and Apktool cleanup failures through one shared owner

* refactor(application): compose service cleanup failures through the shared owner (#10902)
2026-11-15 20:06:47 +08:00

1943 lines
63 KiB
TypeScript

import { describe, expect, it } from "vitest";
import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs";
import { awaitAcknowledgement } from "../../../tests/fixtures/lifecycleAcknowledgement.js";
import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
import {
createAnalysisExecution,
type AnalysisClient,
type AnalysisProviderCandidate,
type AnalysisProviderInspectionOptions,
type CapabilityDescriptor,
type ProviderAvailability,
type ProviderIdentity,
type ProviderTargetSupport,
} from "../AnalysisProvider.js";
import { createAnalysisProfile } from "../../domain/analysisProfile.js";
import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import {
AnalysisCapabilityUnavailableError,
AnalysisUnsupportedTargetError,
AnalysisCancelledError,
} from "../../domain/analysisErrorCore.js";
import { ProviderSelectionError } from "../../domain/providerSelectionError.js";
import { LinuxOwnedProcessPrerequisiteError } from "../../process/ProcessOwnershipObservation.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { err, ok } from "../../domain/result.js";
import { releaseOwnedCleanup } from "../../../tests/support/cleanupRelease.js";
const DATABASE_TARGET: BinaryTarget = {
path: "/tmp/fixture.hop",
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
};
const ARTIFACT_TARGET: BinaryTarget = {
path: "/tmp/app.asar",
sha256: "b".repeat(64),
kind: "archive",
format: "asar",
};
it("rejects malformed provider capability declarations", () => {
const alpha = candidate("alpha");
expect(
() => new AnalysisProviderRegistry([alpha.provider, alpha.provider]),
).toThrow(/Duplicate analysis provider ID: alpha/u);
expect(
() =>
new AnalysisProviderRegistry([
{
...alpha.provider,
capabilities: () => {
const descriptor = capability(alpha.provider.identity());
return [descriptor, descriptor];
},
},
]),
).toThrow(/declares operation address_name more than once/u);
expect(
() =>
new AnalysisProviderRegistry([
{
...alpha.provider,
capabilities: () => [
capability({ ...alpha.provider.identity(), name: "forged" }),
],
},
]),
).toThrow(/published mismatched capability provenance/u);
expect(
() => new AnalysisProviderRegistry([candidate("auto").provider]),
).toThrow(/Invalid analysis provider ID: auto/u);
});
it("uses one owner readiness snapshot for candidate availability and capabilities", async () => {
const base = candidate("alpha").provider;
let observed = 0;
let capabilityReads = 0;
const provider: AnalysisProviderCandidate = {
...base,
inspectAvailability: () => {
throw new Error("availability must come from the owner snapshot");
},
capabilities: () => {
capabilityReads += 1;
return [capability(base.identity())];
},
inspectReadinessSnapshot: () => {
observed += 1;
return {
availability: {
status: "unavailable",
code: "runtime_unavailable",
reason: "native inspection failed",
remediation: "Repair the fixture provider.",
diagnostics: { failure_stage: "self-test" },
},
capabilities: [capability(base.identity())],
};
},
};
const [status] = await new AnalysisProviderRegistry([provider]).candidates();
expect(observed).toBe(1);
expect(capabilityReads).toBe(1);
expect(status).toMatchObject({
availability: {
status: "unavailable",
code: "runtime_unavailable",
diagnostics: { failure_stage: "self-test" },
},
capabilities: [{ operation: "address_name" }],
});
});
it("reports a missing Linux ps as one candidate's unavailability and keeps the others", async () => {
const base = candidate("alpha").provider;
const gamma = candidate("gamma").provider;
const refused: AnalysisProviderCandidate = {
...base,
// Mirrors a provider adapter re-attributing the refusal to its own operation.
inspectReadinessSnapshot: () => {
throw new AnalysisCapabilityUnavailableError(
"process-ownership",
"ghidra:inspection",
"ps is unavailable",
{
cause: new LinuxOwnedProcessPrerequisiteError(
new Error("spawn ps ENOENT"),
),
},
);
},
};
const statuses = await new AnalysisProviderRegistry([
refused,
gamma,
]).candidates();
expect(statuses).toMatchObject([
{
provider: { id: "alpha" },
availability: {
status: "unavailable",
code: "runtime_unavailable",
reason: expect.stringContaining("spawn ps ENOENT") as unknown,
diagnostics: { stage: "ownership_preparation" },
},
capabilities: [{ operation: "address_name" }],
},
{ provider: { id: "gamma" }, availability: { status: "available" } },
]);
const selected = await new AnalysisProviderRegistry([refused]).select(
DATABASE_TARGET,
"alpha",
);
if (selected.ok) throw new Error("expected the prerequisite refusal");
expect(selected.error).toMatchObject({
_tag: "AnalysisCapabilityUnavailableError",
providerId: "process-ownership",
});
});
it("selects the sole available provider and honors explicit selection precedence", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta", { available: false });
const sole = await new AnalysisProviderRegistry([
beta.provider,
alpha.provider,
]).select(DATABASE_TARGET);
expect(sole).toMatchObject({
ok: true,
value: {
binding: {
identity: { id: "alpha" },
selectionSource: "auto-single-candidate",
},
},
});
const selected = new AnalysisProviderRegistry(
[alpha.provider, candidate("beta").provider],
"beta",
);
expect(await selected.select(DATABASE_TARGET)).toMatchObject({
ok: true,
value: {
binding: {
identity: { id: "beta" },
selectionSource: "environment",
},
},
});
expect(await selected.select(DATABASE_TARGET, "alpha")).toMatchObject({
ok: true,
value: {
binding: {
identity: { id: "alpha" },
selectionSource: "request",
},
},
});
});
describe("inspection without deep binding", () => {
it("retains discovery facts without resolving a deep profile for covered automatic inspection", async () => {
const alpha = candidate("alpha", { profile: "error" });
const beta = candidate("beta", { profile: "error" });
const registry = new AnalysisProviderRegistry(
[alpha.provider, beta.provider],
"auto",
(target) => target === DATABASE_TARGET,
);
expect(await registry.select(DATABASE_TARGET)).toMatchObject({
ok: true,
value: {
requestedProviderId: "auto",
binding: null,
candidates: [
{
provider: { id: "alpha" },
selected: false,
availability: { status: "available" },
},
{
provider: { id: "beta" },
selected: false,
availability: { status: "available" },
},
],
},
});
expect(alpha.created).toEqual([]);
expect(beta.created).toEqual([]);
});
it("keeps explicit request and environment choices even when auxiliary inspection covers the target", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta");
const registry = new AnalysisProviderRegistry(
[alpha.provider, beta.provider],
"beta",
() => true,
);
expect(await registry.select(DATABASE_TARGET)).toMatchObject({
ok: true,
value: {
binding: { identity: { id: "beta" }, selectionSource: "environment" },
},
});
expect(await registry.select(DATABASE_TARGET, "alpha")).toMatchObject({
ok: true,
value: {
binding: { identity: { id: "alpha" }, selectionSource: "request" },
},
});
expect(await registry.select(DATABASE_TARGET, "auto")).toMatchObject({
ok: true,
value: { binding: null },
});
expect(await registry.select(DATABASE_TARGET, "missing")).toMatchObject({
ok: false,
error: { reason: "unknown_provider" },
});
});
it("preserves ordinary ambiguity when auxiliary inspection does not cover the target", async () => {
const registry = new AnalysisProviderRegistry(
[candidate("alpha").provider, candidate("beta").provider],
"auto",
() => false,
);
expect(await registry.select(DATABASE_TARGET)).toMatchObject({
ok: false,
error: { reason: "ambiguous" },
});
const controller = new AbortController();
controller.abort();
expect(
await registry.select(DATABASE_TARGET, undefined, {
signal: controller.signal,
}),
).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" } });
});
});
describe("analysis provider registry: selection failures", () => {
it("offers only admitted providers for ambiguous automatic selection", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta");
const ghidra = candidate("ghidra", {
available: false,
unconfigured: true,
});
const kuna = candidate("kuna", {
available: false,
unconfigured: true,
});
const registry = new AnalysisProviderRegistry([
alpha.provider,
beta.provider,
ghidra.provider,
kuna.provider,
]);
const ambiguous = await registry.select(DATABASE_TARGET);
expect(ambiguous.ok).toBe(false);
if (!ambiguous.ok)
expect(projectAnalysisError(ambiguous.error)).toMatchObject({
details: {
selection_reason: "ambiguous",
candidate_ids: ["alpha", "beta"],
rejections: [
{ provider_id: "ghidra", code: "not_configured" },
{ provider_id: "kuna", code: "not_configured" },
],
},
});
for (const selected of [
await registry.select(DATABASE_TARGET, "alpha"),
await registry.select(DATABASE_TARGET, "beta"),
])
expect(selected).toMatchObject({ ok: true });
expect([
...alpha.created,
...beta.created,
...ghidra.created,
...kuna.created,
]).toEqual([]);
});
it("returns actionable unknown, unavailable, and unsupported failures", async () => {
const unavailable = candidate("alpha", { available: false });
const registry = new AnalysisProviderRegistry([unavailable.provider]);
const unknown = await registry.select(DATABASE_TARGET, "missing");
expect(unknown.ok).toBe(false);
if (!unknown.ok)
expect(projectAnalysisError(unknown.error)).toMatchObject({
details: {
selection_reason: "unknown_provider",
requested_provider_id: "missing",
candidate_ids: ["alpha"],
},
});
const rejected = await registry.select(DATABASE_TARGET, "alpha");
expect(rejected.ok).toBe(false);
if (!rejected.ok)
expect(projectAnalysisError(rejected.error)).toMatchObject({
code: "provider_unavailable",
details: {
rejections: [
{
provider_id: "alpha",
code: "runtime_missing",
diagnostics: { executable_path: "/opt/alpha/bin/analyze" },
},
],
},
});
const unsupported = await new AnalysisProviderRegistry([
candidate("alpha", { available: false }).provider,
]).select(ARTIFACT_TARGET, "alpha");
if (unsupported.ok)
throw new Error("expected unsupported target rejection");
expect(unsupported.error).toBeInstanceOf(ProviderSelectionError);
if (
!unsupported.ok &&
unsupported.error instanceof ProviderSelectionError
) {
expect(unsupported.error).toMatchObject({
reason: "target_unsupported",
});
expect(unsupported.error.rejections.map(({ code }) => code)).toEqual([
"runtime_missing",
"target_kind_unsupported",
]);
}
});
it("keeps artifact-only targets unbound under auto or environment preference", async () => {
const alpha = candidate("alpha");
const environment = new AnalysisProviderRegistry([alpha.provider], "alpha");
const automatic = new AnalysisProviderRegistry([alpha.provider]);
for (const registry of [environment, automatic]) {
const selected = await registry.select(ARTIFACT_TARGET);
expect(selected).toMatchObject({
ok: true,
value: {
binding: null,
candidates: [
{
selected: false,
targetSupport: {
status: "unsupported",
code: "target_kind_unsupported",
},
},
],
},
});
}
const explicit = await automatic.select(ARTIFACT_TARGET, "alpha");
if (explicit.ok) throw new Error("expected provider selection rejection");
expect(explicit.error).toBeInstanceOf(ProviderSelectionError);
if (explicit.error instanceof ProviderSelectionError)
expect(explicit.error.reason).toBe("target_unsupported");
});
it("rejects an unknown environment preference even when every candidate rejects the target", async () => {
const alpha = candidate("alpha");
const misconfigured = new AnalysisProviderRegistry(
[alpha.provider],
"missing",
);
for (const selected of [
await misconfigured.select(ARTIFACT_TARGET),
await misconfigured.select(ARTIFACT_TARGET, "missing"),
]) {
if (selected.ok) throw new Error("expected unknown provider rejection");
expect(projectAnalysisError(selected.error)).toMatchObject({
details: {
selection_reason: "unknown_provider",
requested_provider_id: "missing",
candidate_ids: ["alpha"],
},
});
}
});
});
describe("analysis provider registry: automatic selection diagnostics", () => {
it("retains the selected candidate and every rejected candidate for automatic selection", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta", { available: false });
const gamma = candidate("gamma", { available: false, unconfigured: true });
const registry = new AnalysisProviderRegistry([
gamma.provider,
beta.provider,
alpha.provider,
]);
const selected = await registry.select(DATABASE_TARGET);
if (!selected.ok) throw selected.error;
expect(
selected.value.candidates.map(({ provider }) => provider.id),
).toEqual(["alpha", "beta", "gamma"]);
expect(selected.value.binding).toMatchObject({
identity: { id: "alpha", version: "1" },
selectionSource: "auto-single-candidate",
});
expect(selected.value.candidates).toMatchObject([
{
provider: { id: "alpha", version: "1" },
selected: true,
selectionSource: "auto-single-candidate",
rejections: [],
availability: { status: "available" },
targetSupport: { status: "supported" },
capabilities: [{ operation: "address_name" }],
},
{
provider: { id: "beta", version: null },
selected: false,
selectionSource: null,
rejections: [
{
providerId: "beta",
origin: "availability",
code: "runtime_missing",
reason: "beta runtime is unavailable",
remediation: "Repair the fixture provider.",
diagnostics: { executable_path: "/opt/beta/bin/analyze" },
},
],
},
{
provider: { id: "gamma", version: null },
selected: false,
selectionSource: null,
rejections: [
{
providerId: "gamma",
origin: "availability",
code: "not_configured",
reason: "gamma runtime is unavailable",
remediation: "Repair the fixture provider.",
diagnostics: { executable_path: "/opt/gamma/bin/analyze" },
},
],
},
]);
const repeated = await registry.candidates(DATABASE_TARGET);
expect(repeated.map(({ provider }) => provider.id)).toEqual([
"alpha",
"beta",
"gamma",
]);
expect([...alpha.created, ...beta.created, ...gamma.created]).toEqual([]);
});
});
describe("analysis provider registry: explicit selection diagnostics", () => {
it("attributes request and environment choices without starting a provider", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta");
const registry = new AnalysisProviderRegistry(
[beta.provider, alpha.provider],
"beta",
);
expect(await registry.select(DATABASE_TARGET)).toMatchObject({
ok: true,
value: {
candidates: [
{
provider: { id: "alpha" },
selected: false,
selectionSource: null,
rejections: [],
},
{
provider: { id: "beta" },
selected: true,
selectionSource: "environment",
rejections: [],
},
],
},
});
expect(await registry.select(DATABASE_TARGET, "alpha")).toMatchObject({
ok: true,
value: {
candidates: [
{
provider: { id: "alpha" },
selected: true,
selectionSource: "request",
rejections: [],
},
{
provider: { id: "beta" },
selected: false,
selectionSource: null,
rejections: [],
},
],
},
});
expect([...alpha.created, ...beta.created]).toEqual([]);
});
it("keeps explicit selection fail-closed and explains unknown candidates", async () => {
const alpha = candidate("alpha", { available: false });
const beta = candidate("beta");
const registry = new AnalysisProviderRegistry([
alpha.provider,
beta.provider,
]);
const selected = await registry.select(DATABASE_TARGET, "alpha");
expect(selected.ok).toBe(false);
if (selected.ok) return;
expect(selected.error).toBeInstanceOf(ProviderSelectionError);
if (!(selected.error instanceof ProviderSelectionError)) return;
expect(selected.error).toMatchObject({
reason: "provider_unavailable",
requestedProviderId: "alpha",
candidateIds: ["alpha", "beta"],
rejections: [
{
providerId: "alpha",
origin: "availability",
code: "runtime_missing",
remediation: "Repair the fixture provider.",
},
],
});
expect(selected.error.remediationAction).toBe(
"Repair the fixture provider.",
);
const unknown = await registry.select(DATABASE_TARGET, "missing");
expect(unknown.ok).toBe(false);
if (unknown.ok) return;
expect(unknown.error).toBeInstanceOf(ProviderSelectionError);
if (!(unknown.error instanceof ProviderSelectionError)) return;
expect(unknown.error).toMatchObject({
reason: "unknown_provider",
requestedProviderId: "missing",
candidateIds: ["alpha", "beta"],
rejections: [
{
providerId: "alpha",
origin: "availability",
code: "runtime_missing",
},
],
});
expect([...alpha.created, ...beta.created]).toEqual([]);
});
});
describe("analysis provider registry: rejection diagnostics", () => {
it("keeps automatic ambiguity visible with usable and rejected candidates", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta");
const gamma = candidate("gamma", { available: false });
const registry = new AnalysisProviderRegistry([
beta.provider,
gamma.provider,
alpha.provider,
]);
const ambiguous = await registry.select(DATABASE_TARGET);
expect(ambiguous.ok).toBe(false);
if (ambiguous.ok) return;
expect(ambiguous.error).toBeInstanceOf(ProviderSelectionError);
if (!(ambiguous.error instanceof ProviderSelectionError)) return;
expect(ambiguous.error).toMatchObject({
reason: "ambiguous",
requestedProviderId: "auto",
candidateIds: ["alpha", "beta"],
rejections: [
{
providerId: "gamma",
origin: "availability",
code: "runtime_missing",
remediation: "Repair the fixture provider.",
},
],
});
expect([...alpha.created, ...beta.created, ...gamma.created]).toEqual([]);
});
it("keeps unresolved profiles and unavailable candidates in an unbound result", async () => {
const unresolved = candidate("alpha", { profile: "missing" });
const unavailable = candidate("beta", { available: false });
const registry = new AnalysisProviderRegistry([
unavailable.provider,
unresolved.provider,
]);
const selected = await registry.select(DATABASE_TARGET);
expect(selected).toMatchObject({
ok: true,
value: {
requestedProviderId: "auto",
binding: null,
candidates: [
{
provider: { id: "alpha" },
selected: false,
selectionSource: null,
availability: {
status: "unavailable",
code: "version_unresolved",
},
rejections: [
{
providerId: "alpha",
origin: "availability",
code: "version_unresolved",
// doctor cannot check this provider, so it is not offered.
remediation: expect.not.stringContaining(
"rea doctor",
) as unknown,
},
],
},
{
provider: { id: "beta" },
selected: false,
selectionSource: null,
rejections: [
{
providerId: "beta",
origin: "availability",
code: "runtime_missing",
},
],
},
],
},
});
expect([...unresolved.created, ...unavailable.created]).toEqual([]);
});
it("reports an unsupported target as a target rejection without fallback", async () => {
const alpha = candidate("alpha");
const registry = new AnalysisProviderRegistry([alpha.provider], "alpha");
const unbound = await registry.select(ARTIFACT_TARGET);
expect(unbound).toMatchObject({
ok: true,
value: {
binding: null,
candidates: [
{
provider: { id: "alpha" },
selected: false,
selectionSource: null,
targetSupport: {
status: "unsupported",
code: "target_kind_unsupported",
},
rejections: [
{
providerId: "alpha",
origin: "target",
code: "target_kind_unsupported",
reason: expect.stringContaining(
"only accepts analysis databases",
) as unknown,
diagnostics: { target_kind: "archive" },
},
],
},
],
},
});
const explicit = await registry.select(ARTIFACT_TARGET, "alpha");
expect(explicit.ok).toBe(false);
if (explicit.ok) return;
expect(explicit.error).toMatchObject({
reason: "target_unsupported",
requestedProviderId: "alpha",
rejections: [
{
providerId: "alpha",
origin: "target",
code: "target_kind_unsupported",
},
],
});
expect(alpha.created).toEqual([]);
});
});
describe("analysis provider registry: discovery diagnostics", () => {
it("keeps discovery side-effect free and preserves cancellation", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta");
const registry = new AnalysisProviderRegistry([
beta.provider,
alpha.provider,
]);
const statuses = await registry.candidates(DATABASE_TARGET);
expect(statuses).toMatchObject([
{
provider: { id: "alpha" },
selected: false,
selectionSource: null,
rejections: [],
},
{
provider: { id: "beta" },
selected: false,
selectionSource: null,
rejections: [],
},
]);
expect([...alpha.created, ...beta.created]).toEqual([]);
const controller = new AbortController();
const reason = { caller: "diagnostic cancellation" };
controller.abort(reason);
const cancelled = await registry.select(DATABASE_TARGET, undefined, {
signal: controller.signal,
});
expect(cancelled).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", cause: reason },
});
expect([...alpha.created, ...beta.created]).toEqual([]);
});
});
describe("analysis provider registry: rejection origins", () => {
it("distinguishes recorded readiness failures from an unobserved target refusal", async () => {
const registry = new AnalysisProviderRegistry([
candidate("alpha", { available: false, unconfigured: true }).provider,
candidate("gamma", { available: false, unconfigured: true }).provider,
]);
const selection = await registry.select(DATABASE_TARGET);
if (!selection.ok) throw selection.error;
const projected = projectAnalysisError(
registry.unboundOperationError("binary_overview", selection.value),
);
expect(projected.message).toContain(
"Provider selection failed local readiness checks. No target-support refusal was reported.",
);
});
it("reports a configured provider's readiness failure without hiding a ready alternative", async () => {
const invalid = candidate("alpha", { available: false });
const ready = candidate("beta");
const registry = new AnalysisProviderRegistry([
{
...invalid.provider,
inspectAvailability: () => ({
status: "unavailable",
code: "open_options_invalid",
reason: "Configured registration is invalid",
remediation: "Repair the fixture provider.",
diagnostics: { registration_path: "/configured/alpha.json" },
}),
},
ready.provider,
]);
const selected = await registry.select(DATABASE_TARGET, "alpha");
if (selected.ok)
throw new Error("Expected the selected provider to refuse");
const projected = projectAnalysisError(selected.error);
expect(projected.message).toContain("local readiness");
expect(projected.message).not.toContain(
"No analysis provider is configured",
);
expect(projected.details).toMatchObject({
requested_provider_id: "alpha",
candidate_ids: ["alpha", "beta"],
rejections: [
{
provider_id: "alpha",
origin: "availability",
code: "open_options_invalid",
reason: "Configured registration is invalid",
diagnostics: { registration_path: "/configured/alpha.json" },
},
],
});
expect((await registry.select(DATABASE_TARGET, "beta")).ok).toBe(true);
expect(invalid.created).toEqual([]);
});
it("names whether a rejection came from provider availability or target support", async () => {
const availabilityOnly = new AnalysisProviderRegistry([
candidate("alpha", { available: false, unconfigured: true }).provider,
candidate("gamma", { available: false, unconfigured: true }).provider,
]);
const availabilitySelection =
await availabilityOnly.select(DATABASE_TARGET);
expect(availabilitySelection.ok).toBe(true);
if (availabilitySelection.ok) {
const { details } = projectAnalysisError(
availabilityOnly.unboundOperationError(
"binary_overview",
availabilitySelection.value,
),
);
const rejections = details?.rejections as unknown as readonly {
origin: string;
}[];
expect(rejections.map(({ origin }) => origin)).toEqual([
"availability",
"availability",
]);
}
const unconfiguredButAdmitting: AnalysisProviderCandidate = {
...candidate("alpha", { available: false, unconfigured: true }).provider,
inspectTargetSupport: () => ({
status: "supported",
code: null,
reason: null,
diagnostics: { target_kind: "archive" },
}),
};
const refusingTarget: AnalysisProviderCandidate = {
...candidate("beta").provider,
inspectTargetSupport: () => ({
status: "unsupported",
code: "target_format_unsupported",
reason: "beta refuses archives",
diagnostics: { target_kind: "archive" },
}),
};
const mixed = new AnalysisProviderRegistry([
unconfiguredButAdmitting,
refusingTarget,
]);
const mixedSelection = await mixed.select(ARTIFACT_TARGET);
expect(mixedSelection.ok).toBe(true);
if (mixedSelection.ok) {
const projected = projectAnalysisError(
mixed.unboundOperationError("binary_overview", mixedSelection.value),
);
expect(projected.message).toContain(
"The selected analysis provider is unavailable",
);
const { details } = projected;
const rejections = details?.rejections as unknown as readonly {
origin: string;
code: string;
}[];
expect(rejections).toMatchObject([
{ origin: "availability", code: "not_configured" },
{ origin: "target", code: "target_format_unsupported" },
]);
}
});
});
describe("analysis provider registry: profile and cleanup failures", () => {
it("does not bind a profile with unresolved version or adapter failure", async () => {
const unresolved = candidate("unresolved", { profile: "missing" });
const failed = candidate("failed", { profile: "error" });
const automatic = await new AnalysisProviderRegistry([
unresolved.provider,
]).select(DATABASE_TARGET);
expect(automatic).toMatchObject({
ok: true,
value: {
binding: null,
candidates: [
{
availability: {
status: "unavailable",
code: "version_unresolved",
},
},
],
},
});
const explicit = await new AnalysisProviderRegistry([
failed.provider,
]).select(DATABASE_TARGET, "failed");
if (explicit.ok) throw new Error("expected provider selection rejection");
expect(explicit.error).toMatchObject({
_tag: "ProviderAdapterError",
providerId: "failed",
});
});
it("aborts automatic selection when a provider reports unconfirmed cleanup", async () => {
const ghidra = candidate("ghidra");
const alternate = candidate("hopper");
const cleanupFailure = new ProviderCleanupError(
"ghidra",
["/opt/ghidra/data/languages/x86.ldefs"],
{ reason: "descriptor close failed" },
{ operation: "resolve_analysis_profile" },
);
const provider: AnalysisProviderCandidate = {
...ghidra.provider,
resolveAnalysisProfile: () => Promise.resolve(err(cleanupFailure)),
};
const selected = await new AnalysisProviderRegistry([
alternate.provider,
provider,
]).select(DATABASE_TARGET);
expect(selected).toMatchObject({
ok: false,
error: {
_tag: "ProviderAdapterError",
providerId: "ghidra",
cleanupIncomplete: true,
},
});
expect(alternate.created).toEqual([]);
});
it("owns a signal-ignoring profile probe until final completion and joins shutdown", async () => {
const alpha = candidate("alpha");
let observedSignal: AbortSignal | undefined;
let finish: (() => void) | undefined;
let started: (() => void) | undefined;
const pending = new Promise<void>((resolve) => {
started = resolve;
});
const gate = new Promise<void>((resolve) => {
finish = resolve;
});
const ignoresCancellation: AnalysisProviderCandidate = {
...alpha.provider,
resolveAnalysisProfile: async (target, options) => {
observedSignal = options?.signal;
started?.();
await gate;
return alpha.provider.resolveAnalysisProfile(target);
},
};
const registry = new AnalysisProviderRegistry([ignoresCancellation]);
const controller = new AbortController();
const reason = { caller: "profile finalization" };
let selected = false;
const selecting = registry
.select(DATABASE_TARGET, "alpha", { signal: controller.signal })
.then((result) => {
selected = true;
return result;
});
let closed = false;
let closing: ReturnType<typeof registry.closeOwnedResources> | undefined;
await withVerifierCleanup(async () => {
await awaitAcknowledgement(pending, selecting, "profile probe");
controller.abort(reason);
closing = registry.closeOwnedResources().then((result) => {
closed = true;
return result;
});
await new Promise<void>((resolve) => setImmediate(resolve));
expect(selected).toBe(false);
expect(closed).toBe(false);
expect(registry.hasPendingOwnedResources()).toBe(true);
expect(observedSignal?.aborted).toBe(true);
expect(observedSignal?.reason).toBe(reason);
finish?.();
const result = await selecting;
expect(result).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", cause: reason },
});
expect(await closing).toEqual(ok(null));
expect(registry.hasPendingOwnedResources()).toBe(false);
expect(alpha.created).toEqual([]);
}, [
() => {
controller.abort(reason);
finish?.();
},
async () => {
await Promise.allSettled([selecting, closing]);
},
async () => {
expect(await registry.closeOwnedResources()).toEqual(ok(null));
},
]);
});
});
interface CandidateFixture {
readonly provider: AnalysisProviderCandidate;
readonly created: string[];
}
const candidate = (
id: string,
options: {
readonly available?: boolean;
readonly unconfigured?: boolean;
readonly profile?: "resolved" | "missing" | "error";
} = {},
): CandidateFixture => {
const identity: ProviderIdentity = {
id,
name: `${id} provider`,
version: null,
};
const created: string[] = [];
const available = options.available ?? true;
const provider: AnalysisProviderCandidate = {
identity: () => identity,
capabilities: () => [capability(identity)],
inspectAvailability: (): ProviderAvailability =>
available
? {
status: "available",
code: null,
reason: null,
diagnostics: { executable_path: `/opt/${id}/bin/analyze` },
}
: {
status: "unavailable",
code: options.unconfigured ? "not_configured" : "runtime_missing",
reason: `${id} runtime is unavailable`,
remediation: "Repair the fixture provider.",
diagnostics: { executable_path: `/opt/${id}/bin/analyze` },
},
inspectTargetSupport: (target): ProviderTargetSupport =>
target.kind === "database"
? {
status: "supported",
code: null,
reason: null,
diagnostics: { target_kind: target.kind },
}
: {
status: "unsupported",
code: "target_kind_unsupported",
reason: `${id} only accepts analysis databases in this fixture`,
diagnostics: { target_kind: target.kind },
},
resolveAnalysisProfile: () => {
if (options.profile === "error")
return Promise.resolve(
err(new ProviderAdapterError(id, "resolve_analysis_profile")),
);
return Promise.resolve(
ok({
profile:
options.profile === "missing"
? null
: createAnalysisProfile(
{ id, name: identity.name, version: "1" },
{ fixture: id },
),
}),
);
},
createClient: (_target, profile): AnalysisClient => {
created.push(id);
const executionIdentity = profile?.provider ?? identity;
return {
execute: (operation) =>
Promise.resolve(
ok(
createAnalysisExecution(
operation === "health" ? null : `${id}:${operation}`,
executionIdentity,
),
),
),
close: () => Promise.resolve(ok(null)),
};
},
};
return { provider, created };
};
const capability = (provider: ProviderIdentity): CapabilityDescriptor => ({
provider,
operation: "address_name",
available: true,
reason: null,
effects: {
mutatesArtifact: false,
launchesProcess: true,
mayShowUi: false,
mayAccessNetwork: false,
mayWriteFilesystem: false,
changesPermissions: false,
requiresRoot: false,
},
limitations: [],
});
describe("analysis provider registry: explicit profile refusals", () => {
const refusing = (refusal: AnalysisUnsupportedTargetError) => ({
...candidate("ghidra").provider,
resolveAnalysisProfile: () => Promise.resolve(err(refusal)),
});
it("keeps a refusing provider's reason, recovery and evidence in the selection failure", async () => {
const capturedOutput = {
stdout: "",
stderr: "x86-64 only",
truncated: false,
};
const refusal = new AnalysisUnsupportedTargetError(
"resolve_analysis_profile",
DATABASE_TARGET.path,
"The configured extension supports x86-64 only.",
{
remediationAction: "Omit the extension setting for this target.",
capturedOutput,
diagnostics: { extension: "fixture" },
},
);
const selected = await new AnalysisProviderRegistry([
refusing(refusal),
]).select(DATABASE_TARGET, "ghidra");
if (selected.ok) throw new Error("expected a profile refusal");
expect(selected.error).toBeInstanceOf(ProviderSelectionError);
expect(selected.error.cause).toBe(refusal);
expect(projectAnalysisError(selected.error)).toMatchObject({
code: "capability_unavailable",
message: refusal.message,
remediation: { action: "Omit the extension setting for this target." },
details: {
selection_reason: "target_unsupported",
requested_provider_id: "ghidra",
candidate_ids: ["ghidra"],
rejections: [
{
provider_id: "ghidra",
code: "target_format_unsupported",
reason: "The configured extension supports x86-64 only.",
},
],
captured_output: capturedOutput,
diagnostics: { extension: "fixture" },
},
});
});
it("returns a refusal with unconfirmed cleanup unchanged", async () => {
const refusal = new AnalysisUnsupportedTargetError(
"resolve_analysis_profile",
DATABASE_TARGET.path,
"The configured extension supports x86-64 only.",
{ cleanup: { reason: "probe close failed", resources: ["/tmp/probe"] } },
);
const selected = await new AnalysisProviderRegistry([
refusing(refusal),
]).select(DATABASE_TARGET, "ghidra");
if (selected.ok) throw new Error("expected a profile refusal");
expect(selected.error).toBe(refusal);
expect(projectAnalysisError(selected.error)).toMatchObject({
code: "cleanup_incomplete",
details: { cleanup: "incomplete", resources: ["/tmp/probe"] },
});
});
});
describe("profile resolution terminal facts", () => {
it.each([false, true])(
"preserves a physical profile failure across late caller abort (throws: %s)",
async (throws) => {
const alpha = candidate("alpha");
const controller = new AbortController();
const primary = new ProviderAdapterError(
"alpha",
"resolve_analysis_profile",
{ cause: new Error("physical profile failure") },
);
const registry = new AnalysisProviderRegistry([
{
...alpha.provider,
resolveAnalysisProfile: async () => {
controller.abort({ caller: "after physical failure" });
if (throws) throw primary;
return err(primary);
},
},
]);
const result = await registry.select(DATABASE_TARGET, "alpha", {
signal: controller.signal,
});
expect(result).toEqual(err(primary));
expect(registry.hasPendingOwnedResources()).toBe(false);
expect(await registry.closeOwnedResources()).toEqual(ok(null));
},
);
it("preserves exact cancellation with cleanup and blocks admission until its owner confirms release", async () => {
const alpha = candidate("alpha");
const controller = new AbortController();
const reason = { caller: "final cleanup" };
const primary = new AnalysisCancelledError("resolve_analysis_profile", {
cause: reason,
cleanup: { reason: "file close rejected", resources: ["profile-file"] },
});
let attempts = 0;
let allowClose = false;
const registry = new AnalysisProviderRegistry([
{
...alpha.provider,
resolveAnalysisProfile: async () => {
attempts++;
controller.abort(reason);
return err(primary);
},
closeOwnedResources: async () => {
if (!allowClose) return err(primary);
releaseOwnedCleanup(primary);
return ok(null);
},
},
]);
const result = await registry.select(DATABASE_TARGET, "alpha", {
signal: controller.signal,
});
expect(result).toEqual(err(primary));
expect(primary.cause).toBe(reason);
expect(registry.hasPendingOwnedResources()).toBe(true);
expect(await registry.select(DATABASE_TARGET, "alpha")).toEqual(
err(primary),
);
expect(attempts).toBe(1);
allowClose = true;
expect(await registry.closeOwnedResources()).toEqual(ok(null));
expect(primary.cleanupIncomplete).toBe(false);
expect(registry.hasPendingOwnedResources()).toBe(false);
});
});
describe("automatic profile cleanup ownership", () => {
it.each(["alpha", "beta"])(
"keeps automatic mixed-child cleanup conjunctive when %s releases first",
async (first) => {
const alpha = candidate("alpha");
const beta = candidate("beta");
const controller = new AbortController();
const reason = { caller: "mixed profile finalization" };
const failures = {
alpha: new AnalysisCancelledError("resolve_analysis_profile", {
cause: reason,
cleanup: { reason: "alpha descriptor", resources: ["alpha-file"] },
}),
beta: new ProviderCleanupError("beta", ["beta-file"], {
reason: "beta descriptor",
}),
};
let entered = 0;
let admitChildren: (() => void) | undefined;
const admitted = new Promise<void>((resolve) => {
admitChildren = resolve;
});
const released = new Set<string>();
const registry = new AnalysisProviderRegistry(
[alpha, beta].map((fixture) => {
const id = fixture.provider.identity().id as "alpha" | "beta";
return {
...fixture.provider,
resolveAnalysisProfile: async () => {
entered++;
if (entered === 2) {
controller.abort(reason);
admitChildren?.();
}
await admitted;
return err(failures[id]);
},
closeOwnedResources: async () => {
if (!released.has(id)) return err(failures[id]);
releaseOwnedCleanup(failures[id]);
return ok(null);
},
};
}),
);
const selecting = registry.select(DATABASE_TARGET, "auto", {
signal: controller.signal,
});
await withVerifierCleanup(async () => {
await awaitAcknowledgement(
admitted,
selecting,
"profile children admission",
);
const result = await selecting;
if (result.ok) throw new Error("Mixed failed profiles admitted");
expect(result.error.cleanupIncomplete).toBe(true);
expect(result.error.cleanupResources).toEqual([
"alpha-file",
"beta-file",
]);
expect(result.error.diagnostics?.profile_errors).toEqual(
expect.arrayContaining([
expect.objectContaining({ provider_id: "alpha" }),
expect.objectContaining({ provider_id: "beta" }),
]),
);
const close1 = await registry.closeOwnedResources();
expect(close1.ok).toBe(false);
released.add(first);
const close2 = await registry.closeOwnedResources();
expect(close2.ok).toBe(false);
expect(result.error.cleanupIncomplete).toBe(true);
expect(result.error.cleanupResources).toEqual([
first === "alpha" ? "beta-file" : "alpha-file",
]);
expect(close1.ok ? [] : close1.error.cleanupResources).toEqual([
first === "alpha" ? "beta-file" : "alpha-file",
]);
released.add(first === "alpha" ? "beta" : "alpha");
expect(await registry.closeOwnedResources()).toEqual(ok(null));
expect(result.error.cleanupIncomplete).toBe(false);
if (close1.ok || close2.ok)
throw new Error("Cleanup unexpectedly succeeded");
expect(close1.error.cleanupIncomplete).toBe(false);
expect(close2.error.cleanupIncomplete).toBe(false);
expect(registry.hasPendingOwnedResources()).toBe(false);
}, [
() => {
released.add("alpha");
released.add("beta");
controller.abort(reason);
admitChildren?.();
},
async () => {
await Promise.allSettled([selecting]);
},
async () => {
expect(await registry.closeOwnedResources()).toEqual(ok(null));
},
]);
},
);
});
it("registers before production and gates fresh selections until shutdown has joined finalization", async () => {
const alpha = candidate("alpha");
let calls = 0;
let enter: (() => void) | undefined;
let finish: (() => void) | undefined;
const entered = new Promise<void>((resolve) => {
enter = resolve;
});
const gate = new Promise<void>((resolve) => {
finish = resolve;
});
const registry = new AnalysisProviderRegistry([
{
...alpha.provider,
resolveAnalysisProfile: async (target) => {
calls++;
if (calls === 1) {
enter?.();
await gate;
}
return alpha.provider.resolveAnalysisProfile(target);
},
},
]);
const selecting = registry.select(DATABASE_TARGET, "alpha");
let closing: ReturnType<typeof registry.closeOwnedResources> | undefined;
let next: ReturnType<typeof registry.select> | undefined;
await withVerifierCleanup(async () => {
await awaitAcknowledgement(entered, selecting, "profile finalization");
closing = registry.closeOwnedResources();
next = registry.select(DATABASE_TARGET, "alpha");
await new Promise<void>((resolve) => setImmediate(resolve));
expect(calls).toBe(1);
expect(registry.hasPendingOwnedResources()).toBe(true);
finish?.();
expect(await selecting).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError" },
});
expect(await closing).toEqual(ok(null));
expect((await next).ok).toBe(true);
expect(calls).toBe(2);
expect(registry.hasPendingOwnedResources()).toBe(false);
}, [
() => finish?.(),
async () => {
await Promise.allSettled([selecting, closing, next]);
},
async () => {
expect(await registry.closeOwnedResources()).toEqual(ok(null));
},
]);
});
it("joins cancelled readiness finalization and shutdown before admitting another observation", async () => {
const base = candidate("alpha").provider;
let enter!: () => void;
let finish!: () => void;
const entered = new Promise<void>((resolve) => {
enter = resolve;
});
const gate = new Promise<void>((resolve) => {
finish = resolve;
});
let calls = 0;
let observed: AbortSignal | undefined;
const registry = new AnalysisProviderRegistry([
{
...base,
inspectAvailability: async ({
signal,
}: AnalysisProviderInspectionOptions = {}) => {
calls++;
if (calls === 1) {
observed = signal;
enter();
await gate;
}
return base.inspectAvailability();
},
},
]);
const controller = new AbortController();
const reason = { request: "opaque readiness cancellation" };
let settled = false;
const observing = registry
.candidates(undefined, { signal: controller.signal })
.catch((cause) => {
settled = true;
return cause;
});
let closed = false;
let closing: ReturnType<typeof registry.closeOwnedResources> | undefined;
let next: ReturnType<typeof registry.candidates> | undefined;
await withVerifierCleanup(async () => {
await awaitAcknowledgement(entered, observing, "readiness observation");
controller.abort(reason);
closing = registry.closeOwnedResources().then((value) => {
closed = true;
return value;
});
next = registry.candidates();
await new Promise<void>((resolve) => setImmediate(resolve));
expect(settled).toBe(false);
expect(closed).toBe(false);
expect(calls).toBe(1);
expect(observed?.reason).toBe(reason);
expect(registry.hasPendingOwnedResources()).toBe(true);
finish();
const failure = await observing;
expect(failure).toBeInstanceOf(AnalysisCancelledError);
expect(failure.cause).toBe(reason);
expect(await closing).toEqual(ok(null));
expect(await next).toMatchObject([
{
availability: {
status: "unknown",
diagnostics: { finalization: "in_progress" },
},
},
]);
expect(await registry.candidates()).toHaveLength(1);
expect(calls).toBe(2);
expect(registry.hasPendingOwnedResources()).toBe(false);
}, [
() => {
controller.abort(reason);
finish();
},
async () => {
await Promise.allSettled([observing, closing, next]);
},
async () => {
expect(await registry.closeOwnedResources()).toEqual(ok(null));
},
]);
});
it.each(["alpha", "beta"])(
"releases unflagged and flagged candidate receipts only after their owners confirm close (%s unflagged)",
async (unknownOwner) => {
const unknown = new ProviderAdapterError(unknownOwner, "close_binary", {
userMessage: "cleanup completion unknown",
});
const tracked = new ProviderCleanupError("rea", ["owned-reader"], {});
let released = false;
const registry = new AnalysisProviderRegistry(
["alpha", "beta"].map((id) => ({
...candidate(id).provider,
closeOwnedResources: async () => {
if (!released) return err(id === unknownOwner ? unknown : tracked);
if (id !== unknownOwner) releaseOwnedCleanup(tracked);
return ok(null);
},
})),
);
const closed = await registry.closeOwnedResources();
if (closed.ok) throw new Error("Expected incomplete registry close");
expect(closed.error.cleanupIncomplete).toBe(true);
released = true;
expect(await registry.closeOwnedResources()).toEqual(ok(null));
expect(tracked.cleanupIncomplete).toBe(false);
expect(closed.error.cleanupIncomplete).toBe(false);
},
);
it.each([
["returned", "physical"],
["returned", "cancelled"],
["thrown", "physical"],
["thrown", "cancelled"],
] as const)(
"retains an unflagged %s %s close failure until that candidate confirms completion",
async (delivery, kind) => {
const reason = { reason: "controlled caller cancellation" };
const physical = { reason: "controlled descriptor close failure" };
const original =
kind === "cancelled"
? new AnalysisCancelledError("close_binary", { cause: reason })
: new ProviderAdapterError("alpha", "close_binary", {
cause: physical,
diagnostics: { reason: "descriptor close failed" },
});
const alpha = candidate("alpha").provider;
let released = false;
let inspections = 0;
let peerCloses = 0;
const registry = new AnalysisProviderRegistry([
{
...alpha,
inspectAvailability: async (options) => {
inspections++;
return alpha.inspectAvailability(options);
},
closeOwnedResources: async () => {
if (released) return ok(null);
if (delivery === "thrown") throw original;
return err(original);
},
},
{
...candidate("beta").provider,
closeOwnedResources: async () => {
peerCloses++;
return ok(null);
},
},
]);
await withVerifierCleanup(async () => {
const closed = await registry.closeOwnedResources();
if (closed.ok) throw new Error("Expected incomplete candidate close");
expect(closed.error).toBeInstanceOf(ProviderCleanupError);
expect(closed.error.cause).toBe(original);
expect(closed.error.cleanupPrimary).toBe(original);
expect(original.cause).toBe(kind === "cancelled" ? reason : physical);
expect(registry.hasPendingOwnedResources()).toBe(true);
expect((await registry.select(DATABASE_TARGET, "alpha")).ok).toBe(false);
expect(inspections).toBe(0);
expect(peerCloses).toBe(2);
released = true;
expect(await registry.closeOwnedResources()).toEqual(ok(null));
expect(closed.error.cleanupIncomplete).toBe(false);
expect(registry.hasPendingOwnedResources()).toBe(false);
expect((await registry.select(DATABASE_TARGET, "alpha")).ok).toBe(true);
expect(inspections).toBe(1);
}, [
async () => {
released = true;
expect(await registry.closeOwnedResources()).toEqual(ok(null));
},
]);
},
);
it("joins every candidate and retains physical failure with exact mixed cleanup owners", async () => {
const alpha = candidate("alpha").provider;
const beta = candidate("beta").provider;
const gamma = candidate("gamma").provider;
let finish!: () => void;
let enter!: () => void;
const entered = new Promise<void>((resolve) => {
enter = resolve;
});
const gate = new Promise<void>((resolve) => {
finish = resolve;
});
const physical = new ProviderAdapterError("alpha", "binary_session", {
diagnostics: { reason: "physical observation failed" },
});
const cleanup = new ProviderCleanupError(
"beta",
["beta retained prerequisite"],
{ reason: "controlled cleanup refusal" },
);
let releases = 0;
const registry = new AnalysisProviderRegistry([
{
...alpha,
inspectAvailability: async () => {
throw physical;
},
},
{
...beta,
inspectAvailability: async () => {
enter();
await gate;
throw cleanup;
},
closeOwnedResources: async () => {
releases++;
releaseOwnedCleanup(cleanup);
return ok(null);
},
},
gamma,
]);
let settled = false;
const observing = registry.candidates().catch((cause) => {
settled = true;
return cause;
});
await withVerifierCleanup(async () => {
await awaitAcknowledgement(
entered,
observing,
"mixed readiness observation",
);
await new Promise<void>((resolve) => setImmediate(resolve));
expect(settled).toBe(false);
finish();
const failure = await observing;
expect(failure.cleanupIncomplete).toBe(true);
expect(failure.cleanupResources).toContain("beta retained prerequisite");
expect(failure.diagnostics).toMatchObject({
readiness_candidates: [
{ provider: { id: "gamma" }, availability: { status: "available" } },
],
});
expect(failure.cleanupPrimary).toBe(physical);
expect(projectAnalysisError(failure).details).toMatchObject({
diagnostics: {
readiness_errors: expect.arrayContaining([
{
provider_id: "alpha",
error: expect.objectContaining({ code: "execution_failure" }),
},
{
provider_id: "beta",
error: expect.objectContaining({ code: "cleanup_incomplete" }),
},
]),
},
});
expect(registry.hasPendingOwnedResources()).toBe(true);
expect(await registry.closeOwnedResources()).toEqual(ok(null));
expect(releases).toBe(1);
expect(failure.cleanupIncomplete).toBe(false);
expect(projectAnalysisError(failure)).toMatchObject({
code: "execution_failure",
details: { diagnostics: { reason: "physical observation failed" } },
});
expect(registry.hasPendingOwnedResources()).toBe(false);
}, [
finish,
async () => {
await observing;
},
async () => {
expect(await registry.closeOwnedResources()).toEqual(ok(null));
},
]);
});
it("registers selection before async readiness can race shutdown", async () => {
let calls = 0;
let observed: AbortSignal | undefined;
const base = candidate("alpha").provider;
const registry = new AnalysisProviderRegistry([
{
...base,
inspectAvailability: async ({
signal,
}: AnalysisProviderInspectionOptions = {}) => {
calls++;
observed = signal;
return base.inspectAvailability();
},
},
]);
const selecting = registry.select(DATABASE_TARGET, "alpha");
const closing = registry.closeOwnedResources();
const [selected, closed] = await Promise.all([selecting, closing]);
expect(selected).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError" },
});
expect(closed).toEqual(ok(null));
expect(calls).toBe(1);
expect(observed?.aborted).toBe(true);
expect((await registry.select(DATABASE_TARGET, "alpha")).ok).toBe(true);
expect(calls).toBe(2);
expect(registry.hasPendingOwnedResources()).toBe(false);
});
it.each(["typed", "untyped", "returned"] as const)(
"joins peer cleanup when a candidate close callback fails (%s)",
async (kind) => {
const failure = new ProviderCleanupError(
"alpha",
["alpha profile reader"],
{
reason: "controlled close rejection",
},
);
let denied = true;
const rejection =
kind === "untyped" ? { reason: "opaque rejection" } : failure;
const closed: string[] = [];
const registry = new AnalysisProviderRegistry([
{
...candidate("alpha").provider,
closeOwnedResources: async () => {
closed.push("alpha");
if (denied) {
if (kind === "returned") return err(failure);
throw rejection;
}
return ok(null);
},
},
{
...candidate("beta").provider,
closeOwnedResources: async () => {
closed.push("beta");
return ok(null);
},
},
]);
try {
const result = await registry.closeOwnedResources();
if (result.ok) throw new Error("Expected retained candidate cleanup");
if (kind !== "untyped") expect(result.error).toBe(failure);
else {
expect(result.error).toBeInstanceOf(ProviderCleanupError);
expect(result.error.cause).toBe(rejection);
}
expect(closed).toEqual(["alpha", "beta"]);
expect(registry.hasPendingOwnedResources()).toBe(true);
denied = false;
expect(await registry.closeOwnedResources()).toEqual(ok(null));
expect(result.error.cleanupIncomplete).toBe(false);
expect(registry.hasPendingOwnedResources()).toBe(false);
} finally {
denied = false;
await registry.closeOwnedResources();
}
},
);
it.each(["alpha", "beta"] as const)(
"retains each candidate receipt until its own close succeeds (%s first)",
async (first) => {
const failures = {
alpha: new ProviderCleanupError("alpha", ["alpha-reader"], {}),
beta: new ProviderCleanupError("beta", ["beta-reader"], {}),
};
const released = new Set<string>();
const calls: string[] = [];
const registry = new AnalysisProviderRegistry([
...(["alpha", "beta"] as const).map((id) => ({
...candidate(id).provider,
closeOwnedResources: async () => {
calls.push(id);
if (released.has(id)) return ok(null);
if (id === "alpha") throw failures.alpha;
return err(failures.beta);
},
})),
{
...candidate("gamma").provider,
closeOwnedResources: async () => {
calls.push("gamma");
return ok(null);
},
},
]);
try {
const initial = await registry.closeOwnedResources();
if (initial.ok) throw new Error("Expected both retained candidates");
expect(calls).toEqual(["alpha", "beta", "gamma"]);
expect(initial.error.cleanupResources).toEqual([
"alpha-reader",
"beta-reader",
]);
expect(initial.error.cause).toBeInstanceOf(AggregateError);
if (!(initial.error.cause instanceof AggregateError))
throw new Error("Expected attributed failures");
expect(initial.error.cause.errors).toEqual([
failures.alpha,
failures.beta,
]);
released.add(first);
const partial = await registry.closeOwnedResources();
expect(partial.ok).toBe(false);
const remaining = first === "alpha" ? "beta" : "alpha";
expect(failures[first].cleanupIncomplete).toBe(false);
expect(failures[remaining].cleanupIncomplete).toBe(true);
expect(initial.error.cleanupIncomplete).toBe(true);
expect(initial.error.cleanupResources).toEqual([`${remaining}-reader`]);
expect(registry.hasPendingOwnedResources()).toBe(true);
released.add(remaining);
expect(await registry.closeOwnedResources()).toEqual(ok(null));
expect(initial.error.cleanupIncomplete).toBe(false);
expect(registry.hasPendingOwnedResources()).toBe(false);
} finally {
released.add("alpha");
released.add("beta");
expect(await registry.closeOwnedResources()).toEqual(ok(null));
}
},
);
it("does not inspect a new selection after cancellation while its retained candidate cleanup settles", async () => {
const base = candidate("alpha").provider;
const failure = new ProviderCleanupError("alpha", ["profile-reader"], {});
let allowClose = false;
let inspections = 0;
let enter!: () => void;
let finish!: () => void;
const entered = new Promise<void>((resolve) => {
enter = resolve;
});
const gate = new Promise<void>((resolve) => {
finish = resolve;
});
const registry = new AnalysisProviderRegistry([
{
...base,
inspectAvailability: () => {
inspections++;
return base.inspectAvailability();
},
closeOwnedResources: async () => {
if (!allowClose) throw failure;
enter();
await gate;
return ok(null);
},
},
]);
const controller = new AbortController();
const reason = { request: "cancel while cleanup completes" };
let selecting: ReturnType<typeof registry.select> | undefined;
await withVerifierCleanup(async () => {
expect(await registry.closeOwnedResources()).toEqual(err(failure));
allowClose = true;
selecting = registry.select(DATABASE_TARGET, "alpha", {
signal: controller.signal,
});
await awaitAcknowledgement(entered, selecting, "candidate cleanup retry");
controller.abort(reason);
finish();
const result = await selecting;
expect(result).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", cause: reason },
});
expect(inspections).toBe(0);
expect(failure.cleanupIncomplete).toBe(false);
expect(registry.hasPendingOwnedResources()).toBe(false);
expect((await registry.select(DATABASE_TARGET, "alpha")).ok).toBe(true);
expect(inspections).toBe(1);
}, [
() => {
allowClose = true;
finish();
},
async () => {
await selecting;
},
async () => {
expect(await registry.closeOwnedResources()).toEqual(ok(null));
},
]);
});