refactor(native): read retained inventory views through the operation fact contracts (#10883)

* refactor(native): read retained inventory views through the operation fact contracts

* refactor(native): read matching inventories through the operation fact contracts (#10887)

* refactor(native): read dispatch symbol fallbacks as lenient name facts at the port (#10889)

* refactor(native): read dispatch symbol fallbacks as lenient name facts at the port

* test(native): accept undeclared name-row fields in both dispatch consumers

* refactor(native): read literal searches and overview counts as operation facts (#10894)

* refactor(native): read literal searches and overview counts as operation facts

* refactor(native): read addressed inventory rows as operation facts in every reader (#10899)

* refactor(native): read addressed inventory rows as operation facts in every reader

* test(native): cover xrefs name resolution through the name fact contract

* test(server): pin procedure completion to the procedure inventory contract
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 17:24:24 +08:00
1 parent f8e8dc3e7a
commit 85df21992f
15 files changed
+370 -218

No files matched your search

+15
View File
@@ -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)",
@@ -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 },
},
});
});
+51 -54
View File
@@ -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<Result<AnalysisExecution, AnalysisError>>;
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<Result<{ matches: LiteralFeatureMatch[] }, AnalysisError>> => {
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 (
+53 -57
View File
@@ -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;
@@ -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",
},
});
});
+9 -15
View File
@@ -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<Result<string | null, AnalysisError>> => {
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<string>();
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);
@@ -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,
});
};
@@ -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", () => {
@@ -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");
});
@@ -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,
}),
),
+19 -8
View File
@@ -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<NativeInventoryOperation, unknown>;
/** 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 = {
+24 -9
View File
@@ -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 = <Output>(
type Body = z.infer<typeof functionBodySchema>;
type AddressedValue = z.infer<typeof addressedValueSchema>;
/** 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<string, AddressedValue[]>,
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<void> => {
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(),
-14
View File
@@ -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<number, AnalysisOutputError> => {
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);
};
+2 -5
View File
@@ -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);
@@ -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) {