diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index 8b49ffd3c6..c7adfff99e 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -231,6 +231,21 @@ check( ], ); +// Native inventory results parse once against their named fact contract +// (docs/adr/native/typed-operation-facts.md). Hopper's reply table and the +// advertised output schemas own their own protocol and catalog contracts. +check( + "native inventory rows parsed outside their fact contract (use executeFact or a contract from src/domain/native/nativeOperationFacts)", + files, + /\bnativeInventoryRowsSchemas\b|z\.array\(\s*addressedValueSchema\b|\baddressedValueSchema\s*\.\s*(?:safeParse|parse|pick)\b/, + [ + "src/domain/native/nativeInventory.ts", + "src/domain/native/nativeOperationFacts.ts", + "src/hopper/HopperReplyContracts.ts", + "src/contracts/toolOutputSchemaGroups.ts", + ], +); + // Mach-O load-command codes have one table; a local copy drifts from it. check( "local Mach-O load-command code (import LC from src/domain/apple/machoLoadCommandCodes)", diff --git a/src/application/EnhancedLiteralTracing.test.ts b/src/application/EnhancedLiteralTracing.test.ts new file mode 100644 index 0000000000..77f7eee5da --- /dev/null +++ b/src/application/EnhancedLiteralTracing.test.ts @@ -0,0 +1,43 @@ +import { expect, it } from "vitest"; + +import { ok } from "../domain/result.js"; +import { + createAnalysisExecution, + type AnalysisOperationPort, +} from "./AnalysisProvider.js"; +import { traceLiteralFeature } from "./EnhancedLiteralTracing.js"; + +const provider = { id: "fixture", name: "Fixture", version: "1" }; + +it("refuses a malformed literal search result at the port with the observed execution", async () => { + const calls: string[] = []; + const analysis: AnalysisOperationPort = { + execute: async (operation) => { + calls.push(operation); + return ok( + createAnalysisExecution( + operation === "search_strings" ? [{ address: "0x10" }] : [], + provider, + ), + ); + }, + }; + const traced = await traceLiteralFeature(analysis, { + query: "token", + case_sensitive: true, + }); + expect(calls).toEqual(["search_strings"]); + expect(traced.ok).toBe(false); + if (traced.ok) return; + expect(traced.error).toMatchObject({ + _tag: "AnalysisOutputError", + operation: "search_strings", + diagnostics: { + contract_issues: [{ path: [0, "value"], code: "invalid_type" }], + }, + partialObservation: { + operation: "search_strings", + parameters: { pattern: "token", mode: "literal", case_sensitive: true }, + }, + }); +}); diff --git a/src/application/EnhancedLiteralTracing.ts b/src/application/EnhancedLiteralTracing.ts index db03757a40..5fd6806691 100644 --- a/src/application/EnhancedLiteralTracing.ts +++ b/src/application/EnhancedLiteralTracing.ts @@ -1,8 +1,13 @@ import type { LiteralFeatureMatch } from "../domain/native/literalFeatureMatch.js"; -import { nativeInventoryRowsSchemas } from "../domain/native/nativeInventory.js"; +import { + searchProceduresFact, + searchStringsFact, +} from "../domain/native/nativeOperationFacts.js"; +import { executeFact } from "./AnalysisOperationFacts.js"; import type { AnalysisExecution, AnalysisOperation, + AnalysisOperationPort, } from "./AnalysisProvider.js"; import { AnalysisCancelledError, @@ -30,21 +35,11 @@ type ObserveCall = ( signal?: AbortSignal, ) => Promise>; -type LiteralSearchSource = readonly [ - "search_strings" | "search_procedures", - "string" | "procedure", -]; - interface ReferenceTraceRequest { readonly matches: readonly LiteralFeatureMatch[]; readonly signal?: AbortSignal; } -const LITERAL_SEARCH_SOURCES: readonly LiteralSearchSource[] = [ - ["search_strings", "string"], - ["search_procedures", "procedure"], -]; - export interface LiteralTraceInput { readonly query: string; readonly case_sensitive: boolean; @@ -52,17 +47,21 @@ export interface LiteralTraceInput { /** Trace matching strings and procedures through provider xrefs. */ export const traceLiteralFeature = async ( - call: AnalysisCall, - observe: ObserveCall, + analysis: AnalysisOperationPort, input: LiteralTraceInput, signal?: AbortSignal, ): EnhancedResult => { - const searched = await literalMatches( - call, - input, - LITERAL_SEARCH_SOURCES, - signal, - ); + const observe: ObserveCall = (name, arguments_, operationSignal) => + analysis.execute( + name, + arguments_, + operationSignal === undefined ? {} : { signal: operationSignal }, + ); + const call: AnalysisCall = async (name, arguments_, operationSignal) => { + const observed = await observe(name, arguments_, operationSignal); + return observed.ok ? ok(observed.value.result) : observed; + }; + const searched = await literalMatches(analysis, input, signal); if (!searched.ok) return searched; const traced = await traceReferences(call, observe, { matches: searched.value.matches, @@ -80,44 +79,42 @@ export const traceLiteralFeature = async ( }; const literalMatches = async ( - call: AnalysisCall, + analysis: AnalysisOperationPort, input: LiteralTraceInput, - sources: readonly LiteralSearchSource[], signal?: AbortSignal, ): Promise> => { - const matches: LiteralFeatureMatch[] = []; - for (const [tool, type] of sources) { - const result = await call( - tool, - { - pattern: input.query, - mode: "literal", - case_sensitive: input.case_sensitive, - }, - signal, - ); - if (!result.ok) return result; - const items = ( - type === "string" - ? nativeInventoryRowsSchemas.strings - : nativeInventoryRowsSchemas.names - ).safeParse(result.value); - if (!items.success) - return err( - new AnalysisOutputError( - tool, - "provider returned an invalid search result", - ), - ); - for (const item of items.data) { - matches.push( - type === "string" - ? { ...item, type: "string" } - : { ...item, type: "procedure" }, - ); - } - } - return ok({ matches }); + const parameters = { + pattern: input.query, + mode: "literal", + case_sensitive: input.case_sensitive, + }; + const options = signal === undefined ? {} : { signal }; + const strings = await executeFact( + analysis, + searchStringsFact, + parameters, + options, + ); + if (!strings.ok) return strings; + const procedures = await executeFact( + analysis, + searchProceduresFact, + parameters, + options, + ); + if (!procedures.ok) return procedures; + return ok({ + matches: [ + ...strings.value.fact.map((item) => ({ + ...item, + type: "string" as const, + })), + ...procedures.value.fact.map((item) => ({ + ...item, + type: "procedure" as const, + })), + ], + }); }; const traceReferences = async ( diff --git a/src/application/EnhancedTools.ts b/src/application/EnhancedTools.ts index f6b4000708..91fdf12fe9 100644 --- a/src/application/EnhancedTools.ts +++ b/src/application/EnhancedTools.ts @@ -31,10 +31,13 @@ import { import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { parseFunctionDossier } from "../domain/native/functionDossier.js"; +import type { AddressedName } from "../domain/native/nativeInventory.js"; import { - parseNativeInventoryCount, - addressedValueSchema, -} from "../domain/native/nativeInventory.js"; + listNamesFact, + listProceduresFact, + listStringsFact, +} from "../domain/native/nativeOperationFacts.js"; +import { executeFact } from "./AnalysisOperationFacts.js"; import { parseSegments, projectBinaryOverview, @@ -239,14 +242,7 @@ export class EnhancedTools { case "inspect_native_api": return this.#inspectNativeApi(call.input, signal); case "trace_feature": - return traceLiteralFeature( - (name, arguments_, operationSignal) => - this.#call(name, arguments_, operationSignal), - (name, arguments_, operationSignal) => - this.#observe(name, arguments_, operationSignal), - call.input, - signal, - ); + return traceLiteralFeature(this.#observed, call.input, signal); case "trace_call_path": return traceCallPath( (name, arguments_, operationSignal, selectorOrigin) => @@ -310,14 +306,18 @@ export class EnhancedTools { } async #objcClasses(pattern: string, signal?: AbortSignal): EnhancedResult { - const namesExecution = await this.#observe("list_names", {}, signal); - if (!namesExecution.ok) return namesExecution; - const names = this.#parseAddressed( - "list_names", - namesExecution.value.result, + const inventory = await executeFact( + this.#observed, + listNamesFact, + {}, + signal === undefined ? {} : { signal }, + ); + if (!inventory.ok) return inventory; + const namesExecution = inventory.value.execution; + const candidates = selectObjcClassCandidates( + addressedNames(inventory.value.fact), + pattern, ); - if (!names.ok) return names; - const candidates = selectObjcClassCandidates(names.value, pattern); if (candidates.length === 0) return ok( projectObjcClassCandidates(candidates, { @@ -355,10 +355,10 @@ export class EnhancedTools { const native = nativeDispatchMetadataResultSchema.safeParse( bindingsExecution.value.result, ); - const nameSubject = namesExecution.value.subject; + const nameSubject = namesExecution.subject; const bindingSubject = bindingsExecution.value.subject; const namesSelection = profileMachoTargetSelection( - namesExecution.value.analysisProfile, + namesExecution.analysisProfile, ); const nativeSelection = native.success ? native.data.result.target_selection @@ -378,8 +378,8 @@ export class EnhancedTools { native.data.target_sha256 !== nameSubject.sha256 || native.data.target_architecture !== nameSubject.architecture || native.data.provider.id !== bindingsExecution.value.provider.id || - namesExecution.value.analysisProfile?.provider.id !== - namesExecution.value.provider.id || + namesExecution.analysisProfile?.provider.id !== + namesExecution.provider.id || nativeSelection === undefined || !machoTargetSelectionMatchesArchitecture( nativeSelection, @@ -402,7 +402,7 @@ export class EnhancedTools { ); const coverage = native.data.result.objc_class_import_binding_coverage; - const inventoryLimitations = namesExecution.value.limitations; + const inventoryLimitations = namesExecution.limitations; const inventoryIncomplete = inventoryLimitations.length > 0; const coverageReason = [ coverage.reason, @@ -754,11 +754,12 @@ export class EnhancedTools { signal, ); if (!document.ok) return document; + const options = signal === undefined ? {} : { signal }; const [segmentsResult, proceduresResult, stringsResult] = await Promise.all( [ this.#call("list_segments", {}, signal), - this.#call("list_procedures", {}, signal), - this.#call("list_strings", {}, signal), + executeFact(this.#observed, listProceduresFact, {}, options), + executeFact(this.#observed, listStringsFact, {}, options), ], ); if (!segmentsResult.ok && !permitsCapabilityFallback(segmentsResult.error)) @@ -770,24 +771,14 @@ export class EnhancedTools { ? parseSegments(segmentsResult.value) : undefined; if (segments !== undefined && !segments.ok) return segments; - const procedureCount = parseNativeInventoryCount( - proceduresResult.value, - "list_procedures", - ); - if (!procedureCount.ok) return procedureCount; - const stringCount = parseNativeInventoryCount( - stringsResult.value, - "list_strings", - ); - if (!stringCount.ok) return stringCount; return ok( withOverviewInventoryCoverage( projectBinaryOverview({ document: document.value, ...(segments?.ok ? { segments: segments.value } : {}), - procedure_count: procedureCount.value, - string_count: stringCount.value, + procedure_count: proceduresResult.value.fact.length, + string_count: stringsResult.value.fact.length, }), ), ); @@ -797,28 +788,20 @@ export class EnhancedTools { tool: "list_names" | "list_procedures", signal?: AbortSignal, ) { - const result = await this.#call(tool, {}, signal); - if (!result.ok) return result; - return this.#parseAddressed(tool, result.value); + const inventory = await executeFact( + this.#observed, + tool === "list_names" ? listNamesFact : listProceduresFact, + {}, + signal === undefined ? {} : { signal }, + ); + return inventory.ok ? ok(addressedNames(inventory.value.fact)) : inventory; } - #parseAddressed(tool: "list_names" | "list_procedures", value: JsonValue) { - const parsed = z.array(addressedValueSchema).safeParse(value); - return parsed.success - ? ok( - parsed.data.map(({ address, value: name, objc_class_label }) => ({ - address, - name, - ...(objc_class_label === undefined ? {} : { objc_class_label }), - })), - ) - : err( - new AnalysisOutputError( - tool, - "provider returned an invalid inventory", - ), - ); - } + /** This tool's port: every call goes through `#observe`'s cancellation checks. */ + readonly #observed: AnalysisOperationPort = { + execute: (name, arguments_, options) => + this.#observe(name, arguments_, options?.signal, options?.selectorOrigin), + }; async #call( name: AnalysisOperation, @@ -854,5 +837,18 @@ export class EnhancedTools { } } +const addressedNames = ( + rows: readonly { + readonly address: string; + readonly value: string; + readonly objc_class_label?: "hopper_legacy_class_object"; + }[], +): AddressedName[] => + rows.map(({ address, value: name, objc_class_label }) => ({ + address, + name, + ...(objc_class_label === undefined ? {} : { objc_class_label }), + })); + const isAborted = (signal: AbortSignal | undefined): boolean => signal?.aborted === true; diff --git a/src/application/XrefsAddressResolution.test.ts b/src/application/XrefsAddressResolution.test.ts new file mode 100644 index 0000000000..89ae072da1 --- /dev/null +++ b/src/application/XrefsAddressResolution.test.ts @@ -0,0 +1,54 @@ +import { expect, it } from "vitest"; + +import type { JsonValue } from "../domain/jsonValue.js"; +import { ok } from "../domain/result.js"; +import { + createAnalysisExecution, + type AnalysisOperationPort, +} from "./AnalysisProvider.js"; +import { resolveXrefsName } from "./XrefsAddressResolution.js"; + +const names = (rows: JsonValue): AnalysisOperationPort => ({ + execute: async () => + ok( + createAnalysisExecution(rows, { + id: "fixture", + name: "Fixture", + version: "1", + }), + ), +}); + +it("resolves an exact name from rows carrying undeclared provider fields", async () => { + expect( + await resolveXrefsName( + names([{ address: "0x10", value: "main", provider_rank: 1 }]), + "main", + ), + ).toEqual({ ok: true, value: "0x10" }); +}); + +it("refuses a malformed name row with field diagnostics", async () => { + expect( + await resolveXrefsName(names([{ address: 16, value: "main" }]), "main"), + ).toMatchObject({ + ok: false, + error: { + _tag: "AnalysisOutputError", + operation: "list_names", + diagnostics: { contract_issues: [{ path: [0, "address"] }] }, + }, + }); +}); + +it("refuses a name row without an address it could pass back to xrefs", async () => { + expect( + await resolveXrefsName(names([{ address: "", value: "main" }]), "main"), + ).toMatchObject({ + ok: false, + error: { + _tag: "AnalysisOutputError", + reason: "Invalid symbol inventory entry at index 0", + }, + }); +}); diff --git a/src/application/XrefsAddressResolution.ts b/src/application/XrefsAddressResolution.ts index 8348c12f66..ffc3b1aab2 100644 --- a/src/application/XrefsAddressResolution.ts +++ b/src/application/XrefsAddressResolution.ts @@ -1,5 +1,6 @@ import { permitsCapabilityFallback } from "./CapabilityFallback.js"; -import { addressedValueSchema } from "../domain/native/nativeInventory.js"; +import { listNamesFact } from "../domain/native/nativeOperationFacts.js"; +import { executeFact } from "./AnalysisOperationFacts.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { AnalysisCancelledError, @@ -48,8 +49,9 @@ export const resolveXrefsName = async ( ): Promise> => { if (signal?.aborted) return err(new AnalysisCancelledError(operation, { cause: signal.reason })); - const inventory = await analysis.execute( - "list_names", + const inventory = await executeFact( + analysis, + listNamesFact, {}, signal === undefined ? {} : { signal }, ); @@ -75,25 +77,17 @@ export const resolveXrefsName = async ( } if (signal?.aborted) return err(new AnalysisCancelledError(operation, { cause: signal.reason })); - if (!Array.isArray(inventory.value.result)) - return err( - new AnalysisOutputError( - "list_names", - "Expected a symbol inventory array", - ), - ); - const addresses = new Set(); - for (const [index, item] of inventory.value.result.entries()) { - const parsed = addressedValueSchema.safeParse(item); - if (!parsed.success || parsed.data.address.length === 0) + for (const [index, row] of inventory.value.fact.entries()) { + // An empty address cannot be passed back to xrefs. + if (row.address.length === 0) return err( new AnalysisOutputError( "list_names", `Invalid symbol inventory entry at index ${index}`, ), ); - if (parsed.data.value === selector) addresses.add(parsed.data.address); + if (row.value === selector) addresses.add(row.address); } const [address] = addresses; if (addresses.size <= 1) return ok(address ?? null); diff --git a/src/application/decompileDirectory/decompileAll.ts b/src/application/decompileDirectory/decompileAll.ts index fa72ebad92..1d789f3f55 100644 --- a/src/application/decompileDirectory/decompileAll.ts +++ b/src/application/decompileDirectory/decompileAll.ts @@ -30,7 +30,8 @@ import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; import { procedureInfoSchema } from "../../domain/native/procedureInfo.js"; -import { addressedValueSchema } from "../../domain/native/nativeInventory.js"; +import { listProceduresFact } from "../../domain/native/nativeOperationFacts.js"; +import { executeFact } from "../AnalysisOperationFacts.js"; import { addressCoordinate } from "../../domain/native/addressCoordinate.js"; import type { JsonValue } from "../../domain/jsonValue.js"; import { err, ok, type Result } from "../../domain/result.js"; @@ -305,32 +306,27 @@ const loadProcedures = async ( AnalysisError > > => { - const observed = await analysis.execute( - "list_procedures", + const inventory = await executeFact( + analysis, + listProceduresFact, {}, executionOptions(signal), ); - if (!observed.ok) return observed; - const parsed = z.array(addressedValueSchema).safeParse(observed.value.result); - if (!parsed.success) - return err( - new AnalysisOutputError( - "list_procedures", - "provider returned an invalid procedure inventory", - ), - ); - const identity = identityFrom(observed.value, layout); + if (!inventory.ok) return inventory; + const identity = identityFrom(inventory.value.execution, layout); if (!identity.ok) return identity; // An empty address cannot name a file or a journal record. - const addressed = parsed.data.filter((row) => row.address.length > 0); + const addressed = inventory.value.fact.filter( + (row) => row.address.length > 0, + ); return ok({ procedures: addressed.map((row) => ({ address: row.address, name: row.value.length === 0 ? null : row.value, })), identity: identity.value, - unaddressed: parsed.data.length - addressed.length, - limitations: observed.value.limitations, + unaddressed: inventory.value.fact.length - addressed.length, + limitations: inventory.value.execution.limitations, }); }; diff --git a/src/application/native/EnhancedNativeInvestigation.test.ts b/src/application/native/EnhancedNativeInvestigation.test.ts index 8aa12446fe..7be7aeedc5 100644 --- a/src/application/native/EnhancedNativeInvestigation.test.ts +++ b/src/application/native/EnhancedNativeInvestigation.test.ts @@ -642,10 +642,6 @@ describe("native dispatch inventory", () => { label: "malformed value with a legacy name", entry: { ...methodInventoryEntry, value: 42, name: methodName }, }, - { - label: "undeclared field", - entry: { address: "0x1000", value: methodName, unexpected: true }, - }, ])( "rejects $label inventory in both dispatch consumers", async ({ entry }) => { @@ -663,12 +659,32 @@ describe("native dispatch inventory", () => { error: { _tag: "AnalysisOutputError", operation: "list_names", - reason: "provider returned an invalid inventory", + reason: "Provider returned an invalid name inventory", }, }); } }, ); + + it("accepts an inventory row with an undeclared provider field in both dispatch consumers", async () => { + const tools = new EnhancedTools( + testAnalysis({ + list_names: () => + execution("list_names", [ + { ...methodInventoryEntry, provider_rank: 1 }, + ]), + }), + ); + for (const [operation, parameters] of [ + ["inspect_native_dispatch_metadata", { max_records: 10 }], + ["trace_native_ui_action", { action: "buildTapped:" }], + ] as const) { + const result = await tools.execute(operation, parameters); + expect(result.ok ? null : result.error._tag).not.toBe( + "AnalysisOutputError", + ); + } + }); }); describe("native UI query outcomes", () => { diff --git a/src/application/native/NativeDispatchMetadataInspection.fallback.test.ts b/src/application/native/NativeDispatchMetadataInspection.fallback.test.ts index c1efa9acd8..5b3b726d07 100644 --- a/src/application/native/NativeDispatchMetadataInspection.fallback.test.ts +++ b/src/application/native/NativeDispatchMetadataInspection.fallback.test.ts @@ -74,3 +74,29 @@ it("retains both the reader refusal and malformed symbol observation", async () }, }); }); + +it("accepts symbol rows with provider fields the name contract does not name", async () => { + const direct = new AnalysisCapabilityUnavailableError( + "native-macos", + "inspect_native_dispatch_metadata", + "Unsupported 32-bit Mach-O metadata", + ); + const rows = [ + { address: "0x1000", value: "_OBJC_CLASS_$_Widget", provider_rank: 1 }, + ]; + const analysis: AnalysisOperationPort = { + execute: async (operation) => + operation === "list_names" + ? ok( + createAnalysisExecution(rows, { + id: "fixture", + name: "Fixture", + version: "1", + }), + ) + : err(direct), + }; + const result = await inspectNativeDispatch(analysis, 10); + if (!result.ok) throw result.error; + expect(JSON.stringify(result.value)).toContain("Widget"); +}); diff --git a/src/application/native/NativeDispatchMetadataInspection.ts b/src/application/native/NativeDispatchMetadataInspection.ts index c901a17ff1..0c4319d2b5 100644 --- a/src/application/native/NativeDispatchMetadataInspection.ts +++ b/src/application/native/NativeDispatchMetadataInspection.ts @@ -1,6 +1,6 @@ import { createAnalysisExecutionEvidence } from "../../domain/analysisObservation.js"; import { permitsCapabilityFallback } from "../CapabilityFallback.js"; -import { nativeInventoryRowsSchemas } from "../../domain/native/nativeInventory.js"; +import { listNamesFact } from "../../domain/native/nativeOperationFacts.js"; import { nativeDispatchMetadataResultSchema, inspectNativeDispatchMetadata, @@ -9,13 +9,10 @@ import { AnalysisOutputError } from "../../domain/analysisErrorCore.js"; import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; import { jsonValueSchema } from "../../domain/jsonValue.js"; import { err, ok } from "../../domain/result.js"; +import { executeFact } from "../AnalysisOperationFacts.js"; import type { AnalysisOperationPort } from "../AnalysisProvider.js"; import type { EnhancedResult } from "../EnhancedToolTypes.js"; -const dispatchNameInventorySchema = nativeInventoryRowsSchemas.names.element - .strict() - .array(); - /** Source operations for this workflow, shared with capability discovery. */ export const NATIVE_DISPATCH_METADATA_SOURCES = { binary: "inspect_native_dispatch_metadata", @@ -79,39 +76,21 @@ export const inspectNativeDispatch = async ( } if (!permitsCapabilityFallback(binaryMetadata.error)) return err(binaryMetadata.error); - const execution = await analysis.execute( - NATIVE_DISPATCH_METADATA_SOURCES.symbols, + const names = await executeFact( + analysis, + listNamesFact, {}, signal === undefined ? {} : { signal }, ); - if (!execution.ok) + if (!names.ok) return err( - execution.error.retainSecondaryFailure(binaryMetadata.error, { + names.error.retainSecondaryFailure(binaryMetadata.error, { binary_metadata_failure: projectAnalysisError(binaryMetadata.error), }), ); - const names = dispatchNameInventorySchema.safeParse(execution.value.result); - if (!names.success) - return err( - new AnalysisOutputError( - NATIVE_DISPATCH_METADATA_SOURCES.symbols, - "provider returned an invalid inventory", - { cause: names.error }, - ) - .retainPartialObservation( - createAnalysisExecutionEvidence( - NATIVE_DISPATCH_METADATA_SOURCES.symbols, - {}, - execution.value, - "observed", - ), - ) - .retainSecondaryFailure(binaryMetadata.error, { - binary_metadata_failure: projectAnalysisError(binaryMetadata.error), - }), - ); + const { execution, fact } = names.value; const result = inspectNativeDispatchMetadata( - names.data.map((entry) => ({ + fact.map((entry) => ({ address: entry.address, name: entry.value, })), @@ -130,11 +109,10 @@ export const inspectNativeDispatch = async ( return ok( jsonValueSchema.parse( nativeDispatchMetadataResultSchema.parse({ - target_sha256: execution.value.subject?.sha256 ?? null, - target_architecture: execution.value.subject?.architecture ?? null, - provider: execution.value.provider, - analysis_profile_digest: - execution.value.analysisProfile?.digest ?? null, + target_sha256: execution.subject?.sha256 ?? null, + target_architecture: execution.subject?.architecture ?? null, + provider: execution.provider, + analysis_profile_digest: execution.analysisProfile?.digest ?? null, result, }), ), diff --git a/src/domain/analysisView/nativeInventoryView.ts b/src/domain/analysisView/nativeInventoryView.ts index 04a329e7ae..058946ea23 100644 --- a/src/domain/analysisView/nativeInventoryView.ts +++ b/src/domain/analysisView/nativeInventoryView.ts @@ -5,8 +5,15 @@ import { jsonValueSchema } from "../jsonValue.js"; import { addressedValueSchema, isNativeInventoryOperation, - nativeInventoryRowsSchemas, + type NativeInventoryOperation, } from "../native/nativeInventory.js"; +import { + listNamesFact, + listProceduresFact, + listStringsFact, + searchProceduresFact, + searchStringsFact, +} from "../native/nativeOperationFacts.js"; import { err, ok } from "../result.js"; import type { AnalysisViewParent } from "./analysisViewParent.js"; import { @@ -59,12 +66,16 @@ export const nativeInventorySummarySchema = z.strictObject({ selectable_fields: z.array(fieldSchema), }); -const readNames = createAnalysisViewResultReader( - nativeInventoryRowsSchemas.names, -); -const readStrings = createAnalysisViewResultReader( - nativeInventoryRowsSchemas.strings, -); +/** Retained inventory Evidence reads through its parent operation's contract. */ +const readInventory = { + list_names: createAnalysisViewResultReader(listNamesFact.schema), + list_procedures: createAnalysisViewResultReader(listProceduresFact.schema), + search_procedures: createAnalysisViewResultReader( + searchProceduresFact.schema, + ), + list_strings: createAnalysisViewResultReader(listStringsFact.schema), + search_strings: createAnalysisViewResultReader(searchStringsFact.schema), +} satisfies Record; /** Project already completed provider observations without another provider read or sort. */ export const projectNativeInventoryView = ( @@ -91,7 +102,7 @@ export const projectNativeInventoryView = ( const strings = parent.operation === "list_strings" || parent.operation === "search_strings"; - const parsed = strings ? readStrings(parent) : readNames(parent); + const parsed = readInventory[parent.operation](parent); if (!parsed.ok) return parsed; const rows: readonly InventoryRecord[] = parsed.value; const shared = { diff --git a/src/domain/native/functionInventory.ts b/src/domain/native/functionInventory.ts index c121e88a80..856ce86a77 100644 --- a/src/domain/native/functionInventory.ts +++ b/src/domain/native/functionInventory.ts @@ -12,10 +12,12 @@ import { } from "../native/functionBody.js"; import { unavailableNativeFactSchema } from "./nativeFactAvailability.js"; import { nativeSymbolOrigin } from "./nativeSymbol.js"; +import type { addressedValueSchema } from "./nativeInventory.js"; import { - addressedValueSchema, - nativeInventoryRowsSchemas, -} from "./nativeInventory.js"; + listNamesFact, + listProceduresFact, + type NativeOperationFactContract, +} from "./nativeOperationFacts.js"; import { nativeAddressInputSchema } from "./nativeAddress.js"; import { nativeByteReadSchema } from "./nativeByteRead.js"; import { procedureInfoSchema } from "./procedureInfo.js"; @@ -25,9 +27,6 @@ import { type NativeMatchingCheckpoint, } from "./functionByteCoverage.js"; -const matchingRowsSchema = nativeInventoryRowsSchemas.names.element - .extend({ address: nativeAddressInputSchema }) - .array(); const matchingBodySchema = z.discriminatedUnion("available", [ unavailableNativeFactSchema, availableFunctionBodySchema.safeExtend({ @@ -68,6 +67,22 @@ const sourcePayload = ( type Body = z.infer; type AddressedValue = z.infer; +/** Matching keys rows by normalized address: a step over the contract's typed rows. */ +const rowAddressesSchema = z.array( + z.object({ address: nativeAddressInputSchema }), +); +const matchingRows = ( + contract: NativeOperationFactContract, + input: unknown, +): AddressedValue[] => { + const rows = sourcePayload(contract.schema, input); + const addresses = sourcePayload(rowAddressesSchema, rows); + return rows.map((row, index) => ({ + ...row, + address: addresses[index]!.address, + })); +}; + export interface MatchingFunction { readonly member: NativeFunctionMatchMember; readonly symbol: string | null; @@ -158,8 +173,8 @@ const addNames = async ( symbols: Facts["symbols"], checkpoint: NativeMatchingCheckpoint, ): Promise => { - for (const symbol of sourcePayload( - matchingRowsSchema, + for (const symbol of matchingRows( + listNamesFact, observation.normalized_result, )) { await checkpoint(128 + symbol.value.length * 2); @@ -319,7 +334,7 @@ export const readFunctionInventory = async ( if (Array.isArray(source)) for (const row of source as unknown[]) await checkpoint(rowBytes(row)); await checkpoint(256 + 8 * inventory.evidence_id.length); - const rows = sourcePayload(matchingRowsSchema, source); + const rows = matchingRows(listProceduresFact, source); const facts: Facts = { details: new Map(), symbols: new Map(), diff --git a/src/domain/native/nativeInventory.ts b/src/domain/native/nativeInventory.ts index 814d1787f6..0778c5170e 100644 --- a/src/domain/native/nativeInventory.ts +++ b/src/domain/native/nativeInventory.ts @@ -72,17 +72,3 @@ export const analysisBookmarkSchema = z.strictObject({ address: z.string(), name: z.string().nullable(), }); -/** Count only complete canonical inventories, using the advertised row contracts. */ -export const parseNativeInventoryCount = ( - value: JsonValue, - operation: "list_procedures" | "list_strings", -): Result => { - const schema = - operation === "list_procedures" - ? nativeInventoryRowsSchemas.names - : nativeInventoryRowsSchemas.strings; - const parsed = schema.safeParse(value); - return parsed.success - ? ok(parsed.data.length) - : invalidNativeOutput(operation, "inventory rows", parsed.error); -}; diff --git a/src/server/promptCompletion.ts b/src/server/promptCompletion.ts index 8127b73f04..aab542e7d1 100644 --- a/src/server/promptCompletion.ts +++ b/src/server/promptCompletion.ts @@ -6,16 +6,13 @@ import type { AnalysisOperationPort } from "../application/AnalysisProvider.js"; import { parseProcessCaptureEvidence } from "../application/process/ProcessEvidence.js"; import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js"; import type { PromptCompletionKind } from "../contracts/promptContracts.js"; -import { addressedValueSchema } from "../domain/native/nativeInventory.js"; +import { listProceduresFact } from "../domain/native/nativeOperationFacts.js"; import { currentMcpRequestSignal } from "./EvidenceMcpServerCore.js"; import { parseArtifactInventoryEvidence } from "../domain/artifactInventoryEvidence.js"; import { EvidenceIntegrityError } from "../domain/evidenceErrors.js"; import type { Evidence } from "../domain/evidence.js"; const documentListSchema = z.array(z.string().min(1)); -const procedureInventorySchema = z.array( - addressedValueSchema.pick({ address: true, value: true }), -); const providerStatusSchema = z.object({ analysis_provider_candidates: z.array( z.object({ provider: z.object({ id: z.string().min(1) }) }), @@ -116,7 +113,7 @@ const procedureCandidates = async ( ); if (result === undefined) return []; if (result.ok) { - const parsed = procedureInventorySchema.safeParse(result.value.result); + const parsed = listProceduresFact.schema.safeParse(result.value.result); if (parsed.success) for (const { address, value: name } of parsed.data) { addresses.add(address); diff --git a/tests/boundary/mcp/promptCompletion.test.ts b/tests/boundary/mcp/promptCompletion.test.ts index 7c23e71d69..bca944bef4 100644 --- a/tests/boundary/mcp/promptCompletion.test.ts +++ b/tests/boundary/mcp/promptCompletion.test.ts @@ -379,6 +379,34 @@ describe("guided prompt completion from complete inventories", () => { expect(values).toContain("0x00000000"); }); + it.each([ + [ + "valid symbol metadata and an undeclared provider field", + { + primary: true, + dynamic: false, + external: false, + type: "function", + source: "analysis", + }, + ["0x1000", "main"], + ], + ["malformed symbol metadata", { primary: "yes" }, []], + ] as const)( + "reads procedure rows with %s through the procedure inventory contract", + async (_case, symbol, expected) => { + const completion = createPromptCompletionSource({ + execute: () => + Promise.resolve( + observed([ + { address: "0x1000", value: "main", symbol, provider_rank: 1 }, + ]), + ), + }); + expect(await completion.complete("procedure", "")).toEqual(expected); + }, + ); + it("normalizes Unicode prefixes while preserving distinct exact identifiers", async () => { const completion = createPromptCompletionSource({ execute(operation) {