Files
reverse-engineering-anything/src/application/EvidenceBundleFiles.ts
T
morluto 2826592759 refactor(application): build application cancellations with a required reason (#10574)
* refactor(application): build application cancellations with a required reason

Migrate every AnalysisCancelledError construction under src/application
to cancelledBy and lower the guard baseline from 671 to 442.

Shutdown refusals in BinarySession report OwnerCancellation.ownerClosed
when the caller did not abort, instead of an undefined reason.
ReverseEngineeringService and DesktopBuildOwnedWork close their work
with the typed owner reason. SharedStartupAttempt returns the departing
caller's reason with a cancelled wait. One shared isAborted predicate
replaces eleven local copies and narrows a checked signal for
cancelledBy.

* refactor(desktop): drop an unused cancellation import from desktop capture state
2026-11-15 18:38:24 +08:00

254 lines
9.0 KiB
TypeScript

import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { EvidenceBundleExportReceipt } from "../domain/investigationLifecycle.js";
import { jsonValueValidationIssue } from "../domain/jsonValue.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { requireAuthenticationHeadroom } from "./JsonAuthenticationHeadroom.js";
import { absoluteCallerPath } from "../filesystem/callerPath.js";
import { resemblesAnalysisSnapshot } from "../domain/analysisSnapshot.js";
import { describeValidationFailure } from "../domain/validationFailure.js";
import {
safeParseImmutableEvidenceBundle,
safeParseEvidenceBundle,
isImmutableEvidenceBundle,
type EvidenceBundle,
} from "../domain/evidenceBundle.js";
import {
EvidenceFileError,
EvidenceIntegrityError,
type PublishedEvidenceFile,
} from "../domain/evidenceErrors.js";
import { err, ok, type Result } from "../domain/result.js";
import {
AnalysisCancelledError,
type AnalysisResourceConstraintError,
cancelledBy,
} from "../domain/analysisErrorCore.js";
import { safeParseProcessCapture } from "../domain/process/processCaptureParsing.js";
import {
bufferedJsonParts,
canonicalJsonParts,
} from "../domain/jsonSerialization.js";
import { readJsonFile, writeTextParts } from "./JsonFiles.js";
import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
type EvidenceBundleFileFailure =
| EvidenceFileError
| EvidenceIntegrityError
| AnalysisResourceConstraintError
| AnalysisCancelledError;
/** Project a published bundle with record and residual-unknown revision counts. */
export const evidenceBundleExportReceipt = (
bundle: EvidenceBundle,
published: PublishedEvidenceFile,
): EvidenceBundleExportReceipt => ({
path: published.path,
bytes: published.bytes,
records: bundle.records.length,
unknowns: bundle.unknowns.length,
});
/** Read and validate an evidence bundle at the caller-supplied path. */
export const readEvidenceBundle = (
path: string,
signal?: AbortSignal,
resources?: ArtifactResourceScope,
operation = "import_evidence_bundle",
): Promise<Result<EvidenceBundle, EvidenceBundleFileFailure>> =>
readBundle(path, false, signal, resources, operation);
/** Read an authenticated immutable snapshot for a subsequent session import. */
export const readImmutableEvidenceBundle = (
path: string,
signal?: AbortSignal,
resources?: ArtifactResourceScope,
operation = "import_evidence_bundle",
): Promise<Result<EvidenceBundle, EvidenceBundleFileFailure>> =>
readBundle(path, true, signal, resources, operation);
/** Join both comparison reads and preserve cleanup owned by either failed input. */
export const readComparisonEvidenceBundles = async (
leftPath: string,
rightPath: string,
signal?: AbortSignal,
resources?: ArtifactResourceScope,
operation = "compare_bundles",
): Promise<
Result<
{ readonly left: EvidenceBundle; readonly right: EvidenceBundle },
AnalysisError
>
> => {
const [left, right] = await Promise.all([
readImmutableEvidenceBundle(leftPath, signal, resources, operation),
readImmutableEvidenceBundle(rightPath, signal, resources, operation),
]);
if (!left.ok) {
if (!right.ok && right.error.cleanupIncomplete)
return err(
analysisErrorWithCleanupFailure(
left.error,
right.error,
operation,
).bindCleanupDependencies([left.error, right.error]),
);
return left;
}
if (!right.ok) return right;
return ok({ left: left.value, right: right.value });
};
const readBundle = async (
path: string,
immutable: boolean,
signal?: AbortSignal,
resources?: ArtifactResourceScope,
operation = "import_evidence_bundle",
): Promise<Result<EvidenceBundle, EvidenceBundleFileFailure>> => {
if (signal?.aborted) return err(cancelledBy(operation, signal));
const loaded = await readJsonFile(path, signal, resources, operation);
if (!loaded.ok) return loaded;
if (signal?.aborted) return err(cancelledBy(operation, signal));
return authenticateEvidenceBundleValue(loaded.value, path, {
operation,
immutable,
});
};
/** Authenticate a loaded bundle once, preserving file-reader failure and process-capture semantics. */
export const authenticateEvidenceBundleValue = (
value: unknown,
path: string,
options: { readonly operation: string; readonly immutable?: boolean },
): Result<EvidenceBundle, EvidenceBundleFileFailure> => {
const { operation } = options;
const headroom = requireAuthenticationHeadroom(value, {
operation,
path: absoluteCallerPath(path),
description:
"Insufficient heap headroom to authenticate the Evidence bundle",
});
if (!headroom.ok) return headroom;
const parsed =
options.immutable === true
? safeParseImmutableEvidenceBundle(value)
: safeParseEvidenceBundle(value);
if (!parsed.ok) {
const failure = parsed.error;
if (failure.kind === "single-record")
return err(
new EvidenceFileError("read", "wrong-kind", {
path: absoluteCallerPath(path),
cause: failure.cause,
userMessage: failure.message,
}),
);
if (
operation === "import_evidence_bundle" &&
typeof value === "object" &&
value !== null &&
!Object.hasOwn(value, "records") &&
resemblesAnalysisSnapshot(value)
)
return err(
new EvidenceFileError("read", "wrong-kind", {
path: absoluteCallerPath(path),
cause: failure.cause,
detectedKind: "analysis-snapshot",
userMessage:
"This JSON appears to be an analysis snapshot rather than an Evidence bundle. Its snapshot content has not been validated. To restore it, use a matching target, provider and analysis profile: call open_binary with snapshot_path set to this file, or pass --snapshot to a compatible CLI analysis command (which loads and updates the snapshot). Alternatively, supply a bundle from export_evidence_bundle.",
}),
);
return err(
new EvidenceIntegrityError("Evidence bundle validation failed", {
cause: failure.cause,
userMessage: failure.message,
}),
);
}
return validateBundlePayloads(parsed.value, path, operation);
};
/** Validate typed payloads without restricting historical workflow or provider identities. */
const validateBundlePayloads = (
bundle: EvidenceBundle,
path: string,
operation: string,
): Result<
EvidenceBundle,
EvidenceIntegrityError | AnalysisResourceConstraintError
> => {
for (const record of bundle.records) {
if (record.predicate_type !== "rea.process-capture") continue;
// A sealed bundle borrows records, but this typed parser still allocates a
// capture copy. Admit its actual working set against current headroom.
const headroom = requireAuthenticationHeadroom(record.normalized_result, {
operation,
path: absoluteCallerPath(path),
description: `Insufficient heap headroom to validate process capture ${record.evidence_id} in the Evidence bundle`,
});
if (!headroom.ok) return headroom;
const parsedCapture = safeParseProcessCapture(record.normalized_result);
if (!parsedCapture.success) {
return err(
new EvidenceIntegrityError("Evidence bundle validation failed", {
cause: parsedCapture.error,
userMessage: `Process capture record ${record.evidence_id} has an invalid normalized_result (${describeValidationFailure(parsedCapture.error)}). Recreate or re-export the bundle, then try again.`,
}),
);
}
}
return ok(bundle);
};
/** Atomically write deterministic evidence JSON at the caller-supplied path. */
export const writeEvidenceBundle = async (
bundle: EvidenceBundle,
path: string,
overwrite: boolean,
resources: ArtifactResourceScope,
signal?: AbortSignal,
operation = "export_evidence_bundle",
): Promise<
Result<
{ readonly path: string; readonly bytes: number },
EvidenceBundleFileFailure
>
> => {
if (signal?.aborted === true) return err(cancelledBy(operation, signal));
if (!isImmutableEvidenceBundle(bundle)) {
const issue = jsonValueValidationIssue(bundle);
if (issue !== undefined)
return err(
new EvidenceIntegrityError("Evidence checkpoint is not ordinary JSON", {
userMessage: issue,
}),
);
const headroom = requireAuthenticationHeadroom(bundle, {
operation,
path: absoluteCallerPath(path),
description:
"Insufficient heap headroom to authenticate the Evidence checkpoint",
});
if (!headroom.ok) return headroom;
}
const checked = safeParseEvidenceBundle(bundle);
if (!checked.ok) {
return err(
new EvidenceIntegrityError("Evidence bundle validation failed", {
cause: checked.error.cause,
}),
);
}
const validated = validateBundlePayloads(checked.value, path, operation);
if (!validated.ok) return validated;
return writeTextParts(
bufferedJsonParts(canonicalJsonParts(validated.value)),
path,
overwrite,
resources,
signal === undefined ? undefined : { signal, operation },
);
};