Files
reverse-engineering-anything/src/domain/analysisRefusal.ts
T
morluto d4a7c17b38 feat(errors): project fixed native and producer input allowances as typed refusals (#11623)
* feat(errors): project fixed native and producer input allowances as typed refusals

fixedNativeAllowance wrote its allowance and value only into the remediation
sentence, and fixedProducerInputAllowance put the byte count into the
allowance name. Both now build fixedAllowanceOptions with limit and unit, so
the native command output capture, PE resource metadata, Ghidra
installation-properties and artifact analysis input refusals project
details.refusal {kind: fixed_ceiling, allowance_kind, limit, unit}. The
fixed-ceiling remediation renders the value from those facts for every
ceiling that carries them.

Refs #10508

* test(errors): check the rendered allowance value, not its sentence
2026-11-16 08:39:18 +08:00

177 lines
6.8 KiB
TypeScript

import type { AnalysisCallerLifetime } from "./analysisErrorBase.js";
import type { AnalysisSettingLimit } from "./analysisSettings.js";
import { analysisSettingDefinition } from "./analysisSettingDefinitions.js";
import {
fixedAllowanceRemediation,
type FixedAllowance,
} from "./fixedAllowanceRemediation.js";
import type { JsonValue } from "./jsonValue.js";
/** A caller-addressable request field, as a path into the operation's input. */
export type RefusalField = readonly (string | number)[];
/** A selector that matched several candidates where the operation needs one. */
export interface AmbiguousSelector {
/** Request field whose value would choose one candidate. */
readonly field: RefusalField;
/** Every matching candidate, in the producer's order. */
readonly candidates: readonly JsonValue[];
}
/**
* A deliberate refusal the producer typed, attributed to the request's
* operation. Each variant owns its recovery, so presentation needs no generic
* fallback for it:
*
* - `fixed_ceiling`: a release-fixed allowance (`FixedAllowance`) with its
* optional limit, unit and narrowing step.
* - `adjustable_budget`: an agent-adjustable setting or per-call parameter
* (`AnalysisSettingLimit`) with its control, unit, range and, when the
* producer measured it, the minimum value (`required_value`) that admits
* the request.
* - `ambiguous_selector`: a selector that matched several candidates.
*/
export type AnalysisRefusal =
| {
readonly kind: "fixed_ceiling";
readonly operation: string;
readonly ceiling: FixedAllowance;
}
| {
readonly kind: "adjustable_budget";
readonly operation: string;
readonly budget: AnalysisSettingLimit;
}
| {
readonly kind: "ambiguous_selector";
readonly operation: string;
readonly selector: AmbiguousSelector;
};
const fieldName = (field: RefusalField): string => field.map(String).join(".");
const UNCHANGED = "Repeating the unchanged request is not expected to succeed.";
const adjustableBudgetRemediation = (
operation: string,
budget: AnalysisSettingLimit,
callerLifetime: AnalysisCallerLifetime,
): string => {
const {
unit,
minimum,
maximum,
effective_value: value,
required_value: required,
} = budget;
const control = budget.parameter ?? budget.setting;
const range = `${String(minimum)}..${String(maximum)} ${unit}`;
const effective =
value === null
? `The effective ${control} value is unknown`
: `${operation} reached its ${control} budget of ${String(value)} ${unit}${budget.source === undefined ? "" : ` (source ${budget.source})`}`;
if (value !== null && value >= maximum)
return `${effective}. ${control} is already at its maximum (${range}); narrow the request or select a smaller input. ${UNCHANGED}`;
if (required !== undefined && required > maximum)
return `${effective}. The request requires ${String(required)} ${unit}, above the ${control} maximum (${range}); narrow the request or select a smaller input. ${UNCHANGED}`;
const environment = analysisSettingDefinition(budget.setting).environment;
const change =
budget.parameter !== undefined &&
(budget.update_mode === "parameter" ||
(callerLifetime === "invocation" && environment === undefined))
? `Pass a larger ${budget.parameter} on the next ${operation} call`
: callerLifetime === "invocation"
? `Set ${environment ?? budget.setting} for the next invocation`
: budget.update_mode === "runtime"
? `Raise ${budget.setting} with update_analysis_settings`
: `Set ${environment ?? budget.setting} in the environment that starts REA, then restart REA`;
const atLeast =
required === undefined ? "" : `at least ${String(required)} ${unit}; `;
return `${effective}. ${change} (${atLeast}range ${range}), then retry.`;
};
/**
* The one recovery for a typed refusal. Total over every variant: adding a
* variant fails compilation here until it has its own recovery.
*/
export const analysisRefusalRemediation = (
refusal: AnalysisRefusal,
callerLifetime: AnalysisCallerLifetime = "continuing",
): string => {
switch (refusal.kind) {
case "fixed_ceiling": {
const { ceiling } = refusal;
const base = fixedAllowanceRemediation(ceiling.name, ceiling.kind);
const value =
ceiling.limit === undefined || ceiling.unit === undefined
? ""
: ` The allowance is ${String(ceiling.limit)} ${ceiling.unit}; this release has no runtime override.`;
return ceiling.narrowing === undefined
? `${base}${value}`
: `${base}${value} ${ceiling.narrowing}`;
}
case "adjustable_budget":
return adjustableBudgetRemediation(
refusal.operation,
refusal.budget,
callerLifetime,
);
case "ambiguous_selector": {
const { field, candidates } = refusal.selector;
return `Set ${fieldName(field)} to exactly one of the ${String(candidates.length)} candidates in details.refusal.candidates, then retry ${refusal.operation}. ${UNCHANGED}`;
}
}
};
/** Outcome sentence for a refusal whose producer authored none. */
export const analysisRefusalMessage = (
refusal: AnalysisRefusal,
): string | undefined =>
refusal.kind === "ambiguous_selector"
? `${fieldName(refusal.selector.field)} matches ${String(refusal.selector.candidates.length)} candidates; ${refusal.operation} needs exactly one.`
: undefined;
/** Machine-readable refusal facts projected under `details.refusal`. */
export const analysisRefusalDetails = (
refusal: AnalysisRefusal,
): Readonly<Record<string, JsonValue>> => {
switch (refusal.kind) {
case "fixed_ceiling": {
const { ceiling } = refusal;
return {
kind: refusal.kind,
operation: refusal.operation,
allowance: ceiling.name,
allowance_kind: ceiling.kind,
...(ceiling.limit === undefined ? {} : { limit: ceiling.limit }),
...(ceiling.unit === undefined ? {} : { unit: ceiling.unit }),
...(ceiling.narrowing === undefined
? {}
: { narrowing: ceiling.narrowing }),
};
}
case "adjustable_budget": {
const { budget } = refusal;
return {
kind: refusal.kind,
operation: refusal.operation,
control: budget.parameter ?? budget.setting,
setting: budget.setting,
effective_value: budget.effective_value,
unit: budget.unit,
range: { minimum: budget.minimum, maximum: budget.maximum },
...(budget.required_value === undefined
? {}
: { required_value: budget.required_value }),
};
}
case "ambiguous_selector":
return {
kind: refusal.kind,
operation: refusal.operation,
field: [...refusal.selector.field],
candidates: [...refusal.selector.candidates],
};
}
};