Files
reverse-engineering-anything/src/domain/analysisErrorBase.ts
T
morluto dd7597a108 refactor(errors): read cleanup completion from dependencies instead of pushing it to dependents (#10744)
* 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
2026-11-15 15:22:21 +08:00

598 lines
22 KiB
TypeScript

import type { InterfaceBuilderAnalysis } from "./apple/interfaceBuilderGraph.js";
import type { PartialTaskMeasurement } from "./desktop/taskDifficulty.js";
import type { AppleIpsPartialObservation } from "./native/appleIps.js";
import type { PlaywrightTrace } from "./playwrightTrace/playwrightTrace.js";
import type { ApiContract } from "./apiContract/apiContract.js";
import type { GraphqlContract } from "./apiContract/graphqlContract.js";
import type { SavedAnalysisSnapshotPartialObservation } from "./savedAnalysisSnapshot.js";
import type { AnalysisSettingLimit } from "./analysisSettings.js";
import type { JsonValue } from "./jsonValue.js";
import type { AnalysisCleanupRetry } from "./analysisErrorRecovery.js";
import type { EnvironmentBundlePublication } from "./environmentBundleExport.js";
import type { HistoricalSourceGraph } from "./referenceSourceGraph.js";
/** Stable tags exposed by safe analysis-error projections. */
const ANALYSIS_ERROR_TAGS = [
"AnalysisProtocolError",
"AnalysisInputError",
"AnalysisAccessDeniedError",
"AnalysisArtifactChangedError",
"AnalysisOutputError",
"AnalysisCapabilityUnavailableError",
"AnalysisUnsupportedTargetError",
"AnalysisCancelledError",
"AnalysisTimeoutError",
"AnalysisResourceConstraintError",
"ProviderSelectionError",
"ProviderAdapterError",
"BrowserObservationError",
"ArtifactOperationError",
"ProcessCaptureError",
"EvidenceIntegrityError",
"EvidenceFileError",
"UnknownRegistryError",
"HopperTimeoutError",
"HopperCancelledError",
"HopperProtocolError",
"HopperRemoteError",
"HopperProcessError",
"HopperStartError",
"ConfigurationError",
"NoBinaryOpenError",
"BinaryTargetError",
] as const;
/** Stable tag for an expected analysis failure. */
export type AnalysisErrorTag = (typeof ANALYSIS_ERROR_TAGS)[number];
/** Retained command output associated with a typed failure; truncation stays explicit. */
export interface AnalysisCapturedOutput {
readonly stdout: string;
readonly stderr: string;
readonly truncated: boolean;
readonly stdout_bytes?: number;
readonly stderr_bytes?: number;
readonly exit_code?: number | null;
readonly signal?: string | null;
}
/** Cleanup uncertainty attached to the original typed analysis failure. */
export interface AnalysisCleanupObservation {
readonly reason: string;
readonly resources: readonly string[];
}
/** Publication stopped after a workflow produced its Evidence. Counts describe
* question occurrences, not distinct Unknown identities. */
export interface WorkflowUnknownPublication {
readonly evidence_id: string;
readonly evidence_retention: "retained" | "unverified";
readonly total_questions: number;
readonly created_questions: number;
readonly existing_questions: number;
readonly next_question_index: number;
}
/**
* How long the adapter delivering a failure keeps REA's runtime and provider
* session for its caller. An MCP connection continues: later calls reuse the
* session and can update runtime settings. A one-shot invocation, such as a
* CLI command, releases its provider session and exits before its caller can
* act; only a new invocation's launch settings or arguments apply.
*/
export type AnalysisCallerLifetime = "continuing" | "invocation";
/**
* Producer guidance that holds only for a continuing caller, kept apart from
* the request's outcome. The error's own message and remediation must remain
* true after an invocation has released the provider session.
*/
export interface AnalysisContinuingCallerGuidance {
/** Appended to the outcome, such as that the provider session remains usable. */
readonly userMessage?: string;
/** Replaces the remediation, such as a same-session runtime setting update. */
readonly remediationAction?: string;
}
/** Optional provider-neutral context that must survive typed error projection. */
export interface AnalysisErrorOptions extends ErrorOptions {
/** Typed primary retained when a later lifecycle failure composes this error. */
readonly cleanupPrimary?: AnalysisError | undefined;
/** Producer-owned, caller-safe facts retained through every typed projection. */
readonly diagnostics?: Readonly<Record<string, JsonValue>> | undefined;
readonly limit?: AnalysisSettingLimit | undefined;
readonly continuingCallerGuidance?:
| AnalysisContinuingCallerGuidance
| undefined;
/**
* The same diagnostics recorded for an invocation caller, present only when
* an embedded child failure projects differently for that lifetime.
*/
readonly invocationDiagnostics?:
| Readonly<Record<string, JsonValue>>
| undefined;
readonly capturedOutput?: AnalysisCapturedOutput | undefined;
readonly cleanup?: AnalysisCleanupObservation | undefined;
readonly partialObservation?: AnalysisPartialObservation | undefined;
}
/** Exact cleanup owner that can attribute its currently unresolved resources. */
export interface AnalysisCleanupResourceOwner {
readonly cleanupResources: readonly string[] | undefined;
}
/** A lease-backed claim whose owner records the confirmed release. */
export interface AnalysisCleanupReleaseClaim {
readonly cleanupReleased: boolean;
}
/** Result completed before its source Evidence could be published. */
export type SourcePublicationCompletion =
| {
readonly kind: "unretained-evidence";
readonly source_closure: "not-established";
readonly evidence: Evidence;
}
| {
readonly kind: "retained-evidence";
readonly source_closure: "not-established";
readonly evidence_id: string;
}
| {
readonly kind: "unretained-observation";
readonly source_closure: "not-established";
readonly observation: Readonly<Record<string, JsonValue>>;
}
| {
readonly kind: "inline-evidence";
readonly retention: "one-shot-session" | "unknown";
readonly source_closure: "not-established";
readonly evidence: Evidence;
}
| {
readonly kind: "omitted";
readonly source_closure: "not-established";
readonly reason:
| "primary-authentication-failed"
| "insufficient-authentication-headroom"
| "recovery-input-invalid";
};
export interface SourcePublicationRecovery {
readonly source: AnalysisPartialObservation | undefined;
readonly completed: SourcePublicationCompletion;
}
/** Base class for expected analysis, provider, and session failures. */
export abstract class AnalysisError extends Error {
limit: Readonly<AnalysisSettingLimit> | undefined;
/** Bind the accepted setting at its producing boundary. */
bindLimit(limit: AnalysisSettingLimit): this {
this.limit = Object.freeze({ ...limit });
return this;
}
readonly #cleanupPrimary: AnalysisError | undefined;
// Undefined means unbound; a bound empty set records confirmed completion.
#cleanupDependencies: Set<AnalysisError> | undefined;
#cleanupResourceProjection:
| { readonly cleanupResources: readonly string[] }
| undefined;
readonly diagnostics: Readonly<Record<string, JsonValue>> | undefined;
readonly continuingCallerGuidance:
| Readonly<AnalysisContinuingCallerGuidance>
| undefined;
readonly invocationDiagnostics:
| Readonly<Record<string, JsonValue>>
| undefined;
#capturedOutput: AnalysisCapturedOutput | undefined;
get capturedOutput(): AnalysisCapturedOutput | undefined {
return this.#capturedOutput;
}
readonly cleanup: AnalysisCleanupObservation | undefined;
/**
* This error's own unresolved cleanup. With bound dependencies, completion
* is read from them when asked instead of being pushed to each dependent.
*/
#cleanupIncomplete: boolean;
#ownedCleanupResources: readonly string[];
#cleanupResourceOwner: AnalysisCleanupResourceOwner | undefined;
#cleanupCompletionOwner: AnalysisCleanupResourceOwner | undefined;
readonly #cleanupReleaseClaims: AnalysisCleanupReleaseClaim[] = [];
#cleanupRetry: AnalysisCleanupRetry | undefined;
#secondaryFailures: AnalysisError[] = [];
constructor(message: string, options?: AnalysisErrorOptions) {
super(message, options);
this.#cleanupPrimary = options?.cleanupPrimary;
if (options?.limit !== undefined) this.bindLimit(options.limit);
this.diagnostics =
options?.diagnostics === undefined
? undefined
: structuredClone(options.diagnostics);
this.continuingCallerGuidance =
options?.continuingCallerGuidance === undefined
? undefined
: Object.freeze({ ...options.continuingCallerGuidance });
this.invocationDiagnostics =
options?.invocationDiagnostics === undefined
? undefined
: structuredClone(options.invocationDiagnostics);
this.#capturedOutput =
options?.capturedOutput === undefined
? undefined
: { ...options.capturedOutput };
this.cleanup = options?.cleanup;
this.#cleanupIncomplete = options?.cleanup !== undefined;
this.#ownedCleanupResources = [...(options?.cleanup?.resources ?? [])];
this.partialObservation = options?.partialObservation;
}
abstract readonly _tag: AnalysisErrorTag;
readonly userMessage: string | undefined = undefined;
readonly userCategory: "cancelled" | undefined = undefined;
readonly executionFailure: string | undefined = undefined;
partialObservation: AnalysisPartialObservation | undefined;
sourcePublicationRecovery: SourcePublicationRecovery | undefined;
workflowUnknownPublication: WorkflowUnknownPublication | undefined;
/** Keep the failed source and completed result with their error owner. */
retainSourcePublication(completed: SourcePublicationCompletion): this {
this.sourcePublicationRecovery = {
source: this.partialObservation,
completed,
};
this.partialObservation = undefined;
return this;
}
get cleanupPrimary(): AnalysisError | undefined {
return this.#cleanupPrimary;
}
/**
* Whether owned resources remain unreleased, read from the owners when
* asked. Bound dependencies decide it once bound; otherwise a released
* lease claim completes it. Completion is monotonic, so a later binding
* cannot reopen it.
*/
get cleanupIncomplete(): boolean {
if (!this.#cleanupIncomplete) return false;
const dependencies = this.#cleanupDependencies;
if (dependencies === undefined) {
if (!this.#cleanupReleaseClaims.some((claim) => claim.cleanupReleased))
return true;
} else
for (const dependency of dependencies)
if (dependency.cleanupIncomplete) return true;
this.#cleanupIncomplete = false;
dependencies?.clear();
this.#cleanupReleaseClaims.length = 0;
return false;
}
/** Read completion from a lease owner instead of having it pushed here. */
bindCleanupReleaseClaim(claim: AnalysisCleanupReleaseClaim): this {
this.#cleanupReleaseClaims.push(claim);
return this;
}
/** A subclass whose own resources are unreleased when it is constructed. */
protected markCleanupIncomplete(incomplete: boolean): void {
this.#cleanupIncomplete = incomplete;
}
/** Later typed failures retained without changing the primary error cause. */
get secondaryFailures(): readonly AnalysisError[] {
return [...this.#secondaryFailures];
}
readonly cleanupReport: ProcessCaptureCleanupReport | undefined = undefined;
/** Live dependencies own current resource attribution; cleanup keeps history. */
get cleanupResources(): readonly string[] {
if (this.#cleanupDependencies === undefined)
return (
this.#cleanupResourceOwner?.cleanupResources ??
this.#ownedCleanupResources
);
const pending = [...this.#cleanupDependencies].filter(
(dependency) => dependency.cleanupIncomplete,
);
if (pending.length === 0) return [];
if (this.#cleanupResourceProjection !== undefined)
return this.#cleanupResourceProjection.cleanupResources;
return [
...new Set(pending.flatMap((dependency) => dependency.cleanupResources)),
];
}
/** Whether cleanup follows an explicit owner or dependent errors. */
get hasCleanupOwner(): boolean {
return (
this.#cleanupResourceOwner !== undefined ||
this.#cleanupCompletionOwner !== undefined ||
this.#cleanupDependencies !== undefined
);
}
/** Bind attribution only to the producer that owns the complete cleanup set. */
bindCleanupResourceOwner(owner: AnalysisCleanupResourceOwner): this {
this.#cleanupResourceOwner = owner;
return this;
}
/** Observe exact completion without replacing the producer's resource facts. */
bindCleanupCompletionOwner(owner: AnalysisCleanupResourceOwner): this {
this.#cleanupCompletionOwner = owner;
return this;
}
/** Caller retry for the live cleanup; undefined once cleanup completes. */
get cleanupRetry(): AnalysisCleanupRetry | undefined {
return this.cleanupIncomplete ? this.#cleanupRetry : undefined;
}
/** Bind only from the owner retaining every reported resource for this retry. */
bindCleanupRetry(retry: AnalysisCleanupRetry): this {
this.#cleanupRetry = Object.freeze({ ...retry });
return this;
}
/** Initialize resource facts supplied by a more specific error producer. */
protected setCleanupResources(resources: readonly string[]): void {
this.#ownedCleanupResources = [...resources];
}
/** Retain diagnostic facts without replacing the original typed error. */
retainDiagnostics(diagnostics: Readonly<Record<string, JsonValue>>): this {
Object.assign(this, {
diagnostics: structuredClone({ ...this.diagnostics, ...diagnostics }),
...(this.invocationDiagnostics === undefined
? {}
: {
invocationDiagnostics: structuredClone({
...this.invocationDiagnostics,
...diagnostics,
}),
}),
});
return this;
}
/** Retain facts on every primary that cleanup settlement can reveal. */
retainPrimaryDiagnostics(
diagnostics: Readonly<Record<string, JsonValue>>,
): this {
for (
let error: AnalysisError | undefined = this;
error !== undefined;
error = error.cleanupPrimary
)
error.retainDiagnostics(diagnostics);
return this;
}
/** Diagnostics recorded for a caller with this lifetime. */
diagnosticsFor(
callerLifetime: AnalysisCallerLifetime,
): Readonly<Record<string, JsonValue>> | undefined {
return callerLifetime === "invocation"
? (this.invocationDiagnostics ?? this.diagnostics)
: this.diagnostics;
}
retainSecondaryFailure(
failure: AnalysisError,
diagnostics?: Readonly<Record<string, JsonValue>>,
): this {
// Secondary resources remain owned by their cleanup lifecycle; preserve
// the primary error's live cleanup status and original output.
if (diagnostics !== undefined) this.retainDiagnostics(diagnostics);
this.#secondaryFailures.push(failure);
return this;
}
/** Keep a composed error incomplete until all explicitly owned source errors resolve. */
bindCleanupDependencies(
dependencies: readonly AnalysisError[],
resourceProjection?: { readonly cleanupResources: readonly string[] },
): this {
// Settle the dependencies already bound before adding more: completion is
// monotonic, so a dependency bound after they released cannot reopen it.
if (!this.cleanupIncomplete) this.#cleanupDependencies?.clear();
const pending = (this.#cleanupDependencies ??= new Set<AnalysisError>());
if (resourceProjection !== undefined)
this.#cleanupResourceProjection = resourceProjection;
for (const dependency of dependencies)
if (dependency.cleanupIncomplete) pending.add(dependency);
if (pending.size === 0) this.resolveCleanup();
return this;
}
/**
* Clear live cleanup status only after its owning resource confirms retry
* success. Errors composed from this one read the change on their next check.
*/
resolveCleanup(): this {
if (
[...(this.#cleanupDependencies ?? [])].some(
(dependency) => dependency.cleanupIncomplete,
)
)
return this;
this.#cleanupDependencies?.clear();
this.#cleanupIncomplete = false;
return this;
}
/** Retain a completed observation when a later step fails. */
retainPartialObservation(observation: AnalysisPartialObservation): this {
this.partialObservation ??= observation;
return this;
}
/** Keep command output observed before this error without replacing the owner. */
retainCapturedOutput(output: AnalysisCapturedOutput): this {
this.#capturedOutput ??= { ...output };
return this;
}
/** Preserve the exact committed prefix when automatic question publication stops. */
retainWorkflowUnknownPublication(
publication: WorkflowUnknownPublication,
): this {
this.workflowUnknownPublication ??= Object.freeze({ ...publication });
return this;
}
}
/** Confirmed cleanup reveals the typed primary; unresolved ownership stays visible. */
export const resolvedAnalysisError = (error: AnalysisError): AnalysisError => {
while (!error.cleanupIncomplete && error.cleanupPrimary !== undefined)
error = error.cleanupPrimary;
return error;
};
/** Original operation semantics remain distinct from the live cleanup envelope. */
export const primaryAnalysisError = (error: AnalysisError): AnalysisError => {
while (error.cleanupPrimary !== undefined) error = error.cleanupPrimary;
return error;
};
/** Find the completed publication outcome owned anywhere in a cleanup chain. */
export const sourcePublicationRecoveryOf = (
error: AnalysisError,
): SourcePublicationRecovery | undefined => {
for (
let owner: AnalysisError | undefined = error;
owner !== undefined;
owner = owner.cleanupPrimary
)
if (owner.sourcePublicationRecovery !== undefined)
return owner.sourcePublicationRecovery;
return undefined;
};
import type {
PartialProcessCaptureObservation,
ProcessCaptureCleanupReport,
} from "./process/processCapture.js";
import type { FileOffsetPartialObservation } from "./native/fileOffsetPartialObservation.js";
import type { NativeCallPartialObservation } from "./native/nativeCallPartialObservation.js";
import type { HopperCallerReconciliationPartial } from "./native/hopperCallerReconciliation.js";
import type {
ElectronActiveObservationResult,
ElectronActivePartialObservation,
} from "./javascript/electronActiveObservation.js";
import type { JavaScriptRuntimeObservation } from "./javascript/javascriptRuntimeObservation.js";
import type {
ArtifactInventoryPartialObservation,
ArtifactExtractionPartialObservation,
} from "./artifactPartialObservation.js";
import type { WebScriptExportPartialObservation } from "./webScriptExport.js";
import type { JavaScriptRecoveryPartialObservation } from "./javascript/javascriptRecovery.js";
import type { BrowserScenarioPartialObservation } from "./browserScenarioCapture.js";
import type { Evidence } from "./evidence.js";
import type {
ElectronPageInspection,
ElectronPagePartialObservation,
} from "./javascript/electronObservation.js";
import type { AndroidPartialObservation } from "./android/androidPartialObservation.js";
import type { FirmwarePartialObservation } from "./firmware/firmwareAnalysis.js";
import type {
AdbActivityStartPartialObservation,
AdbAcquiredFilePartialObservation,
AdbPackagePullPartialObservation,
AdbDisplayPartialObservation,
} from "./adb/adbDeviceAnalysis.js";
import type {
InspectMacho,
InspectSignature,
} from "./native/nativeInspection.js";
import type { NativeUiObservationResult } from "./native/nativeUiObservation.js";
import type { BinaryLayout } from "./native/binaryLayout.js";
import type {
RecordedCrash,
RecordedCrashPartialObservation,
} from "./native/recordedCrash.js";
import type { WebPageInspection } from "./browserObservationSchemas.js";
import type {
WebBundleAcquisitionPartialObservation,
WebBundleAnalysis,
WebSourceMapFetchPartialObservation,
} from "./webBundleAnalysis.js";
import type { WebExecutionObservation } from "./webExecution.js";
import type { WebSourceMapReport } from "./webSourceLocation.js";
import type { WebEventListenersObservation } from "./webEventListeners.js";
import type { NativeLoadImagePartialObservation } from "./native/nativeLoadImage.js";
import type { NativeAotSnapshotObservation } from "./native/nativeAotSnapshotObservation.js";
import type { FileSnapshotPartialObservation } from "./fileSnapshotObservation.js";
import type { WebModuleResolutionObservation } from "./webModuleTrace.js";
import type { WebNetworkCapture } from "./webNetworkCapture.js";
import type { FridaDeviceList, FridaProcessList } from "./fridaDiscovery.js";
import type { CutterBridgeDiscovery } from "./cutterDiscovery.js";
import type { WebTraceObservation } from "./webTraceObservation.js";
import type { WebArtifactAcquisition } from "./webArtifactAcquisition.js";
/** Provider-neutral evidence collected before a typed analysis failure. */
export type AnalysisPartialObservation =
| InterfaceBuilderAnalysis
| PartialTaskMeasurement
| {
readonly kind: "omitted-observation";
readonly reason:
| "insufficient-authentication-headroom"
| "recovery-input-invalid";
}
| { readonly kind: "unretained-evidence"; readonly evidence: Evidence }
| { readonly kind: "retained-evidence"; readonly evidence_id: string }
| ApiContract
| GraphqlContract
| PlaywrightTrace
| SavedAnalysisSnapshotPartialObservation
| WebArtifactAcquisition
| WebTraceObservation
| CutterBridgeDiscovery
| FridaDeviceList
| FridaProcessList
| WebModuleResolutionObservation
| HistoricalSourceGraph
| WebNetworkCapture
| NativeLoadImagePartialObservation
| NativeAotSnapshotObservation
| FileSnapshotPartialObservation
| PartialProcessCaptureObservation
| NativeCallPartialObservation
| HopperCallerReconciliationPartial
| FileOffsetPartialObservation
| ElectronActivePartialObservation
| ElectronActiveObservationResult
| BrowserScenarioPartialObservation
| WebPageInspection
| WebBundleAnalysis
| WebBundleAcquisitionPartialObservation
| WebSourceMapFetchPartialObservation
| WebSourceMapReport
| WebExecutionObservation
| WebEventListenersObservation
| JavaScriptRuntimeObservation
| ArtifactInventoryPartialObservation
| ArtifactExtractionPartialObservation
| WebScriptExportPartialObservation
| EnvironmentBundlePublication
| JavaScriptRecoveryPartialObservation
| Evidence
| BinaryLayout
| RecordedCrash
| AppleIpsPartialObservation
| RecordedCrashPartialObservation
| AndroidPartialObservation
| FirmwarePartialObservation
| NativeUiObservationResult
| InspectSignature
| InspectMacho
| ElectronPagePartialObservation
| ElectronPageInspection
| AdbActivityStartPartialObservation
| AdbAcquiredFilePartialObservation
| AdbPackagePullPartialObservation
| AdbDisplayPartialObservation;