fix(navigation): offer available instruction observations (#10307)

This commit is contained in:
Kaoru0822 authored and GitHub committed 2026-11-12 23:57:46 -08:00
1 parent c2ca3819e5
commit 15a2de737c
16 files changed
+809 -47

No files matched your search

+20 -1
View File
@@ -54,7 +54,10 @@ import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
import { recordEvidenceSources } from "../investigation/recordEvidenceSources.js";
import { recoverProviderSourceFailure } from "../investigation/sourcePublicationRecovery.js";
import { BinarySessionRecords } from "./BinarySessionRecords.js";
import { binarySessionStatus } from "./BinarySessionStatus.js";
import {
binarySessionStatus,
currentRouteCapability,
} from "./BinarySessionStatus.js";
import { SessionRuntimeAvailability } from "./SessionRuntimeAvailability.js";
import { isSourceEvidenceRetainable } from "./AnalysisSnapshotCache.js";
import type { BinarySessionDetail } from "../../contracts/sessionStatusContract.js";
@@ -1567,6 +1570,8 @@ export class BinarySession
parameters: arguments_,
snapshotContext: options?.snapshotContext,
nativeSourceAdmitted: this.#active?.nativeSourceAdmitted === true,
isOperationAvailable: (operation) => this.#currentlyAvailable(operation),
isOperationAdvertised: options?.isOperationAdvertised,
unboundOperationError: (operation, route) =>
this.#providerRouter.unboundOperationError(operation, route),
lookupSnapshot: (target, profile, operation, parameters) =>
@@ -1705,6 +1710,20 @@ export class BinarySession
return execution;
}
/** Whether the active route can run an operation now, as status reports it. */
#currentlyAvailable(operation: string): boolean {
const active = this.#active;
const descriptor = active?.route.capabilities.get(operation);
return (
descriptor !== undefined &&
currentRouteCapability(
descriptor,
active?.target,
this.#runtimeAvailability.entries,
).available
);
}
#clearRuntimeAvailability(): void {
if (this.#runtimeAvailability.clear()) this.#emitAvailabilityChanged();
}
@@ -17,6 +17,7 @@ import type {
CapabilityDescriptor,
ExecutionOptions,
} from "../AnalysisProvider.js";
import { offeredOperationAlternatives } from "../OperationAlternatives.js";
import {
isSnapshotCacheable,
requestsFreshIndependentDecompile,
@@ -45,6 +46,11 @@ interface PrepareSessionExecutionInput {
readonly parameters: Readonly<Record<string, JsonValue>>;
readonly snapshotContext?: ExecutionOptions["snapshotContext"];
readonly nativeSourceAdmitted: boolean;
/** Current availability as binary_session reports it, not the declaration. */
readonly isOperationAvailable: (operation: AnalysisOperation) => boolean;
readonly isOperationAdvertised:
| ((operation: AnalysisOperation) => boolean)
| undefined;
readonly unboundOperationError: (
operation: AnalysisOperation,
route: SessionProviderRoute,
@@ -79,6 +85,8 @@ export const prepareSessionExecution = (
operation,
parameters,
nativeSourceAdmitted,
isOperationAvailable,
isOperationAdvertised,
unboundOperationError,
lookupSnapshot,
} = input;
@@ -97,6 +105,15 @@ export const prepareSessionExecution = (
capability === undefined
? undeclaredOperationGuidance(operation, entryCommentAvailable)
: undefined;
const offered =
capability === undefined
? offeredOperationAlternatives(
operation,
(alternative) =>
isOperationAvailable(alternative) &&
(isOperationAdvertised?.(alternative) ?? true),
)
: undefined;
return err(
new AnalysisCapabilityUnavailableError(
active.route.binding?.identity.id ?? active.route.identity.id,
@@ -114,6 +131,12 @@ export const prepareSessionExecution = (
: {
userMessage: `The selected provider does not declare ${operation}.`,
fallbackRemediationAction: undeclaredGuidance,
...(offered === undefined
? {}
: {
alternatives: offered.operations,
remediationAction: offered.remediation,
}),
},
),
);
@@ -0,0 +1,200 @@
import { describe, expect, it, onTestFinished } from "vitest";
import { observed } from "../../../tests/fixtures/analysisExecution.js";
import {
createBinarySessionTargets,
createTestBinarySession,
} from "../../../tests/fixtures/binarySession.js";
import { createAnalysisProfile } from "../../domain/analysisProfile.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { ok } from "../../domain/result.js";
import type {
AnalysisOperation,
AnalysisProvider,
CapabilityDescriptor,
ExecutionOptions,
} from "../AnalysisProvider.js";
import { buildCapabilityInventory } from "../CapabilityInventory.js";
import { offeredOperationAlternatives } from "../OperationAlternatives.js";
const IDENTITY = {
id: "fixture",
name: "Fixture analysis provider",
version: "1",
} as const;
const GENERIC =
"This analysis is unavailable for the current target. Choose another analysis or target.";
/** The owning formatter's remediation for exactly these offered tools. */
const remediationFor = (operation: string, offered: readonly string[]) =>
offeredOperationAlternatives(operation, (alternative) =>
offered.includes(alternative),
)?.remediation;
const capability = (
operation: Exclude<AnalysisOperation, "health">,
available = true,
): CapabilityDescriptor => ({
provider: IDENTITY,
operation,
...(available
? ({ available: true, reason: null } as const)
: ({
available: false,
reason: `${operation} needs a loaded listing`,
} as const)),
cachePolicy: "live",
effects: {
mutatesArtifact: false,
launchesProcess: false,
mayShowUi: false,
mayAccessNetwork: false,
mayWriteFilesystem: false,
changesPermissions: false,
requiresRoot: false,
},
limitations: [],
});
/** A deep provider whose declared operations alone decide the offers. */
const openSession = async (capabilities: readonly CapabilityDescriptor[]) => {
const provider: AnalysisProvider = {
identity: () => IDENTITY,
resolveAnalysisProfile: () =>
Promise.resolve(
ok({ profile: createAnalysisProfile(IDENTITY, { fixture: true }) }),
),
capabilities: () => capabilities,
createClient: () => ({
execute: (operation) => Promise.resolve(observed(operation)),
close: () => Promise.resolve(ok(null)),
}),
};
const session = createTestBinarySession(provider);
onTestFinished(async () => {
expect(await session.close()).toEqual({ ok: true, value: null });
});
const [target] = await createBinarySessionTargets();
expect((await session.open(target)).ok).toBe(true);
return session;
};
const refusal = async (
session: Awaited<ReturnType<typeof openSession>>,
operation: "next_address" | "prev_address",
options?: ExecutionOptions,
) => {
const result = await session.execute(operation, {}, options);
if (result.ok) throw new Error(`${operation} unexpectedly succeeded`);
return projectAnalysisError(result.error);
};
const offeredInDiscovery = async (
session: Awaited<ReturnType<typeof openSession>>,
isToolAdvertised?: (name: string) => boolean,
) =>
buildCapabilityInventory(
await session.status(),
{ processCaptureEnabled: false },
isToolAdvertised,
)
.filter(({ name }) => name === "next_address" || name === "prev_address")
.map((tool) => (tool.available ? undefined : tool.alternatives));
describe("undeclared navigation refusals", () => {
it("describe only offered tools, what none establishes and the provider choice", () => {
const offered = offeredOperationAlternatives(
"prev_address",
(alternative) => alternative === "procedure_assembly",
);
expect(offered?.operations).toEqual(["procedure_assembly"]);
expect(offered?.remediation).toContain("procedure_assembly (");
expect(offered?.remediation).not.toMatch(
/inspect_native_instruction|read_function_instructions/u,
);
expect(offered?.remediation).toContain("executed control flow");
expect(offered?.remediation).toContain("prev_address itself");
expect(
offeredOperationAlternatives("list_procedures", () => true),
).toBeUndefined();
});
it("offer only alternatives the provider makes available", async () => {
const session = await openSession([
capability("inspect_native_instruction", false),
capability("read_function_instructions"),
capability("procedure_assembly"),
]);
for (const operation of ["next_address", "prev_address"] as const)
expect(await refusal(session, operation)).toMatchObject({
code: "capability_unavailable",
remediation: {
action: remediationFor(operation, [
"read_function_instructions",
"procedure_assembly",
]),
},
details: {
provider_id: "fixture",
operation,
alternatives: ["read_function_instructions", "procedure_assembly"],
},
});
expect(await offeredInDiscovery(session)).toEqual([
["read_function_instructions", "procedure_assembly"],
["read_function_instructions", "procedure_assembly"],
]);
});
it("offer only alternatives the caller advertises", async () => {
const session = await openSession([
capability("read_function_instructions"),
capability("procedure_assembly"),
]);
const withoutListing = (operation: string) =>
operation !== "read_function_instructions";
const narrowed = await refusal(session, "next_address", {
isOperationAdvertised: withoutListing,
});
expect(narrowed.details?.alternatives).toEqual(["procedure_assembly"]);
expect(narrowed.remediation.action).toBe(
remediationFor("next_address", ["procedure_assembly"]),
);
expect(await offeredInDiscovery(session, withoutListing)).toEqual([
["procedure_assembly"],
["procedure_assembly"],
]);
const hidden = (operation: string) =>
operation !== "read_function_instructions" &&
operation !== "procedure_assembly";
const generic = await refusal(session, "prev_address", {
isOperationAdvertised: hidden,
});
expect(generic.remediation.action).toEqual(
expect.stringContaining("binary_session"),
);
expect(generic.details).not.toHaveProperty("alternatives");
expect(await offeredInDiscovery(session, hidden)).toEqual([
undefined,
undefined,
]);
});
it("keep a declared operation's own unavailability reason", async () => {
const session = await openSession([
capability("next_address", false),
capability("read_function_instructions"),
]);
const declared = await refusal(session, "next_address");
expect(declared).toMatchObject({
code: "capability_unavailable",
remediation: { action: GENERIC },
details: { reason: "next_address needs a loaded listing" },
});
expect(declared.details).not.toHaveProperty("alternatives");
const [next, previous] = await offeredInDiscovery(session);
expect(next).toBeUndefined();
expect(previous).toEqual(["read_function_instructions"]);
});
});
+31 -22
View File
@@ -51,6 +51,34 @@ interface BinarySessionStatusInput {
readonly refreshCandidates?: boolean;
}
/**
* One route capability as the session currently reports it: target
* applicability and observed runtime unavailability override the declaration.
*/
export const currentRouteCapability = (
descriptor: CapabilityDescriptor,
target: BinaryTarget | undefined,
runtimeUnavailability: ReadonlyMap<string, { readonly reason: string }>,
) => {
const targetRefusal =
target === undefined
? undefined
: descriptor.targetApplicability === undefined
? artifactTargetRefusal(descriptor.operation, target)
: targetApplicabilityRefusal(descriptor.targetApplicability, target);
if (targetRefusal !== undefined && descriptor.available)
return {
...descriptor,
available: false as const,
availabilityCode: targetRefusal.code,
reason: targetRefusal.reason,
};
const unavailable = runtimeUnavailability.get(descriptor.operation);
return unavailable === undefined
? descriptor
: runtimeUnavailable(descriptor, unavailable.reason);
};
/** Project internal provider routing state into the caller-visible session status. */
export const binarySessionStatus = async ({
investigation,
@@ -79,28 +107,9 @@ export const binarySessionStatus = async ({
.sort((left, right) =>
compareUnicodeCodePoints(left.operation, right.operation),
)
.map((descriptor) => {
const targetRefusal =
target === undefined
? undefined
: descriptor.targetApplicability === undefined
? artifactTargetRefusal(descriptor.operation, target)
: targetApplicabilityRefusal(
descriptor.targetApplicability,
target,
);
if (targetRefusal !== undefined && descriptor.available)
return {
...descriptor,
available: false as const,
availabilityCode: targetRefusal.code,
reason: targetRefusal.reason,
};
const unavailable = runtimeUnavailability.get(descriptor.operation);
return unavailable === undefined
? descriptor
: runtimeUnavailable(descriptor, unavailable.reason);
});
.map((descriptor) =>
currentRouteCapability(descriptor, target, runtimeUnavailability),
);
const capabilities = providerCapabilitySets(routeCapabilities);
const analysisProviderBinding =
bundleResourceRoot !== undefined