import { unknownTarget } from "../../domain/targetIdentity.js"; import { NativeMatchingAdmission } from "./NativeMatchingAdmission.js"; import { loadNativeMatchingBundleSources } from "./NativeMatchingBundleSources.js"; import { RegularFileCleanupFailure } from "../../filesystem/OwnedRegularFile.js"; import { matchFunctionInventories } from "../../domain/native/matchFunctionInventories.js"; import type { ArtifactResourceScope } from "../../resources/index.js"; import { setImmediate } from "node:timers/promises"; import { matchNativeFunctionsInputSchema, type MatchNativeFunctionsInput, } from "../../contracts/native/functionMatchingContracts.js"; import { createEvidence, evidenceFileTarget, type Evidence, } from "../../domain/evidence.js"; import { readFunctionInventory } from "../../domain/native/functionInventory.js"; import { nativeFunctionMatchingSchema, nativeFunctionByteSourceGuidance, NATIVE_FUNCTION_MATCHING_PREDICATE, } from "../../domain/native/functionMatching.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { cancelledBy } from "../../domain/analysisErrorCore.js"; import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js"; import { err, ok, type Result } from "../../domain/result.js"; import type { EvidenceLookup } from "../EvidenceInputResolver.js"; import { resolveNativeMatchingSources } from "./NativeMatchingSources.js"; import type { ExecutionOptions } from "../../ports/AnalysisProvider.js"; import type { NativeMatchingAllowance } from "../../config/nativeMatchingAllowance.js"; import { FUNCTION_COMPARISON_PROVIDER } from "../../domain/comparisonEvidenceIdentity.js"; const OPERATION = "match_native_functions"; /** Effective admission budget, separate from caller-authored Evidence parameters. */ export interface NativeFunctionMatchingOptions extends ExecutionOptions { readonly representationAllowance?: NativeMatchingAllowance; } export interface NativeFunctionMatchingResult { readonly evidence: Evidence; readonly sources: readonly Evidence[]; readonly detail: MatchNativeFunctionsInput["detail"]; } /** Pair existing observations through one source/analysis admission. */ export const matchNativeFunctions = async ( rawInput: unknown, options?: NativeFunctionMatchingOptions, lookup?: EvidenceLookup, ): Promise> => { const admission = new NativeMatchingAdmission( OPERATION, options?.signal, options?.representationAllowance, ); try { await setImmediate(); await admission.checkpoint(); await admission.admit(rawInput); const parsed = matchNativeFunctionsInputSchema.safeParse(rawInput); if (!parsed.success) return err( analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput), ); return ok(await matchWithAdmission(parsed.data, admission, lookup)); } catch (cause: unknown) { return matchingFailure(cause, options); } }; const matchWithAdmission = async ( input: MatchNativeFunctionsInput, admission: NativeMatchingAdmission, lookup: EvidenceLookup | undefined, ): Promise => { const checkpoint = admission.checkpoint; const { left, right, leftObservations, rightObservations, directLinks, sources, } = await resolveNativeMatchingSources(input, admission, lookup); const leftFunctions = await readFunctionInventory( left, leftObservations, checkpoint, ); const rightFunctions = await readFunctionInventory( right, rightObservations, checkpoint, ); const leftTarget = evidenceFileTarget(left); const rightTarget = evidenceFileTarget(right); const compatible = leftTarget?.architecture != null && leftTarget.architecture === rightTarget?.architecture; const { matches, summary } = await matchFunctionInventories( leftFunctions, rightFunctions, { identicalBytesComparable: compatible, checkpoint }, ); const byteSources: { side: "left" | "right"; evidence_id: string; limitations: string[]; }[] = []; for (const [side, functions, observations] of [ ["left", leftFunctions, leftObservations], ["right", rightFunctions, rightObservations], ] as const) { const used = new Set(); for (const item of functions) for (const id of item.member.evidence_links) { if (!used.has(id)) await checkpoint(128 + id.length * 4); used.add(id); } for (const observation of observations) { if ( observation.operation !== "read_bytes" || !used.has(observation.evidence_id) ) continue; used.delete(observation.evidence_id); await checkpoint(512 + observation.evidence_id.length * 8); for (const limitation of observation.limitations) await checkpoint(128 + limitation.length * 8); byteSources.push({ side, evidence_id: observation.evidence_id, limitations: [...observation.limitations], }); } } const limitations = [ ...new Set([ ...left.limitations.map((x) => `Left: ${x}`), ...right.limitations.map((x) => `Right: ${x}`), "Coverage is restricted to the supplied provider-observed inventories; missing/truncated inventory facts never prove absence from either binary.", "Only unique exact symbols and bytes are paired. Compatible observed CFG/call/string fingerprints propose unresolved candidates, never identity or equivalence. Missing structural coverage stays unknown.", "Name or byte correspondence is not behavioral equivalence; use analyze_function for selected pairs, then compare_functions. Existing dossier pairs include directly usable retained-reference inputs.", ...(byteSources.length === 0 ? [] : [nativeFunctionByteSourceGuidance]), ...(!compatible ? [ "Identical-byte matching unavailable: input architectures are missing or differ.", ] : []), ]), ]; const report = nativeFunctionMatchingSchema.parse({ left: { evidence_id: left.evidence_id, sha256: leftTarget!.sha256, functions: leftFunctions.length, }, right: { evidence_id: right.evidence_id, sha256: rightTarget!.sha256, functions: rightFunctions.length, }, scope: "provider-observed-inputs", source_coverage: { status: summary.only_left + summary.only_right + summary.unresolved > 0 ? "partial" : "complete-within-inputs", left_inventory_completeness: "unknown", right_inventory_completeness: "unknown", left_byte_fingerprints: leftFunctions.filter( (x) => x.fingerprint !== null, ).length, left_structural_candidates: leftFunctions.filter( (x) => x.member.structural_candidate_sha256 !== null, ).length, right_structural_candidates: rightFunctions.filter( (x) => x.member.structural_candidate_sha256 !== null, ).length, right_byte_fingerprints: rightFunctions.filter( (x) => x.fingerprint !== null, ).length, }, summary, byte_sources_count: byteSources.length, byte_sources: byteSources, matches, limitations, }); await checkpoint(); const evidence = createEvidence( unknownTarget("derived-from-linked-evidence"), FUNCTION_COMPARISON_PROVIDER, { operation: OPERATION, predicateType: NATIVE_FUNCTION_MATCHING_PREDICATE, confidence: "derived", authority: "analyst-inference", parameters: { left_evidence_id: left.evidence_id, right_evidence_id: right.evidence_id, left_observation_ids: leftObservations.map((x) => x.evidence_id), right_observation_ids: rightObservations.map((x) => x.evidence_id), algorithm: "exact-symbol-body-bytes-and-structural-candidates-v1", }, result: report, limitations, evidenceLinks: directLinks, }, ); await checkpoint(); return { evidence, sources, detail: input.detail }; }; /** Preserve cleanup owners and expected failures; unexpected implementation failures escape. */ const matchingFailure = ( cause: unknown, options: ExecutionOptions | undefined, ): Result => { if (cause instanceof RegularFileCleanupFailure) throw cause; if (options?.signal?.aborted) return err(cancelledBy(OPERATION, options.signal)); if (cause instanceof AnalysisError) return err(cause); throw cause; }; /** Load selected portable records; do not retain unrelated records across bundles. */ export const matchNativeFunctionsFromBundles = async ( input: MatchNativeFunctionsInput, paths: readonly string[], resources: ArtifactResourceScope, options?: NativeFunctionMatchingOptions, ): Promise> => { try { const admission = new NativeMatchingAdmission( OPERATION, options?.signal, options?.representationAllowance, ); await admission.admit(input); const loaded = await loadNativeMatchingBundleSources({ input, paths, resources, admission, }); await setImmediate(); await admission.checkpoint(); return ok(await matchWithAdmission(loaded.input, admission, loaded.lookup)); } catch (cause: unknown) { return matchingFailure(cause, options); } };