Files
rea/src/contracts/toolContracts.test.ts
T
b5afa5f91e feat(browser): attribute native execution and listener sources (#917)
* feat(browser): attribute native execution and listener sources

Integrate finite native precise-coverage windows and direct DOM listener inspection through shared CLI/MCP workflows, exact session script identities, inline source evidence and owned instrumentation cleanup.

Refs #881, #774

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): preserve runtime identity and settle fixture cleanup

Retain complete reported initiator objects, reject changing loader availability, propagate the selected operation through main-frame authorization and complete effect/help inventories. Close only the synthetic owned Chrome via its native endpoint, await process-group settlement and preserve primary verification errors during cleanup.

Refs #881

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): settle invalid events and preserve document evidence

Accept same-document URL changes with proven stable loader identity, retain metadata without inventing ownership, terminate malformed event collection immediately, and sanitize known transport URLs without erasing sourceURL declarations.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): end detached target windows and sanitize coverage identities

Reuse the existing flat-session event matcher, retain prearming termination, and apply the source identity policy to coverage URLs. Add real MCP target-close verification and producer regressions for detachment orderings.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): retain final sample metadata and settle fatal protocol failures

Keep source inventory open through the resetting sample, propagate fatal wire failures without outstanding commands, and check listener collection failures after final document validation.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)

Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): require default execution worlds for website attribution

Preserve native context and world metadata without treating same-frame isolated or unknown contexts as website sources. Verify actual Chrome isolated function execution before excluding its coverage, and cover ambiguous world metadata with producer regressions.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)

Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): revalidate runtime source joins and selector failures

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-10-07 21:45:07 +08:00

232 lines
7.7 KiB
TypeScript

import { describe, expect, it } from "vitest";
import { ENHANCED_TOOL_CONTRACTS } from "./enhancedToolContracts.js";
import { OFFICIAL_TOOL_CONTRACTS } from "./officialToolContracts.js";
import { SESSION_TOOL_CONTRACTS } from "./sessionToolContracts.js";
import { TOOL_CONTRACTS } from "./toolContracts.js";
import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
import { MANAGED_TOOL_CONTRACTS } from "./managed/managedToolContracts.js";
import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";
import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";
import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managed/managedWorkflowToolContracts.js";
import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.js";
import { ELECTRON_TOOL_CONTRACTS } from "./javascript/electronToolContracts.js";
import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "./javascript/javascriptRuntimeObservationToolContracts.js";
import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
import { JAVASCRIPT_RECOVERY_TOOL_CONTRACTS } from "./javascript/javascriptRecoveryToolContracts.js";
import { WEB_SCRIPT_TOOL_CONTRACTS } from "./webScriptToolContracts.js";
import { WEB_RUNTIME_TOOL_CONTRACTS } from "./webRuntimeToolContracts.js";
const GROUPS = {
official: OFFICIAL_TOOL_CONTRACTS,
enhanced: ENHANCED_TOOL_CONTRACTS,
native: NATIVE_TOOL_CONTRACTS,
artifact: ARTIFACT_TOOL_CONTRACTS,
managed: MANAGED_TOOL_CONTRACTS,
android: ANDROID_TOOL_CONTRACTS,
firmware: FIRMWARE_TOOL_CONTRACTS,
managed_workflow: MANAGED_WORKFLOW_TOOL_CONTRACTS,
browser_provider: BROWSER_PROVIDER_TOOL_CONTRACTS,
electron: ELECTRON_TOOL_CONTRACTS,
javascript_runtime_observation: JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS,
application: APPLICATION_TOOL_CONTRACTS,
javascript_recovery: JAVASCRIPT_RECOVERY_TOOL_CONTRACTS,
web_script_export: WEB_SCRIPT_TOOL_CONTRACTS,
web_runtime: WEB_RUNTIME_TOOL_CONTRACTS,
session: SESSION_TOOL_CONTRACTS,
} as const;
/**
* Published tool names that must remain in the inventory.
*
* This is a floor, not an equality. Structural invariants already prove every
* group member is published, so on their own a contract removed from both its
* group and the aggregate would regenerate the catalog with no failing test.
* These names catch that removal. Adding a tool needs no edit here; removing
* one is a deliberate API change that must delete its name deliberately.
*/
const PUBLISHED_TOOL_NAME_FLOOR = [
"address_name",
"address_to_file_offset",
"analyze_function",
"analyze_javascript_application",
"analyze_swift_types",
"analyze_web_bundle",
"batch_decompile",
"binary_overview",
"binary_session",
"build_call_path",
"build_reconstruction_obligation_ledger",
"capture_browser_scenario",
"capture_electron_scenario",
"capture_process_scenario",
"capture_web_screenshot",
"close_binary",
"comment",
"compare_application_versions",
"compare_artifacts",
"compare_bundles",
"compare_functions",
"compare_javascript_export_shapes",
"compare_managed_members",
"compare_process_captures",
"compare_source_to_bundle",
"compare_web_captures",
"compare_web_screenshots",
"correlate_static_and_runtime",
"current_address",
"current_document",
"current_procedure",
"decode_interface_builder",
"demangle_swift",
"discover_webmcp_tools",
"evaluate_reconstruction_coverage",
"export_evidence_bundle",
"extract_artifact",
"export_web_scripts",
"trace_web_module_imports",
"trace_web_source_location",
"observe_web_execution",
"inspect_web_event_listeners",
"find_changed_behavior",
"find_xrefs_to_name",
"get_call_graph",
"get_evidence_bundle",
"get_navigation_context",
"get_objc_classes",
"get_objc_protocols",
"goto_address",
"import_evidence_bundle",
"import_managed_reconstruction",
"inline_comment",
"inspect_address_context",
"inspect_artifact",
"inspect_asset_catalog",
"inspect_electron_page",
"inspect_macho",
"inspect_managed_artifact",
"inspect_firmware_regions",
"extract_firmware",
"inspect_android_package",
"search_android_classes",
"inspect_android_class",
"inspect_android_method",
"trace_android_references",
"inspect_managed_members",
"inspect_managed_native_boundaries",
"inspect_native_api",
"inspect_native_dispatch_metadata",
"inspect_plist",
"inspect_signature",
"inspect_web_page",
"list_architectures",
"list_bookmarks",
"list_browser_targets",
"list_documents",
"list_electron_targets",
"list_javascript_runtime_targets",
"list_names",
"list_procedures",
"list_segments",
"list_strings",
"list_unknowns",
"next_address",
"observe_javascript_runtime",
"observe_web_session",
"open_binary",
"prev_address",
"procedure_address",
"procedure_assembly",
"procedure_callees",
"procedure_callers",
"procedure_info",
"procedure_pseudo_code",
"procedure_references",
"project_android_application_graph",
"project_apple_application_graph",
"project_managed_application_graph",
"read_bytes",
"read_function_instructions",
"reconcile_javascript_runtime",
"record_unknown",
"resolve_containing_procedure",
"search_procedures",
"search_strings",
"set_address_name",
"set_addresses_names",
"set_bookmark",
"set_comment",
"set_current_document",
"set_inline_comment",
"trace_application_feature",
"trace_call_path",
"trace_feature",
"trace_javascript_semantics",
"trace_native_ui_action",
"unset_bookmark",
"update_unknown",
"verify_managed_native_boundaries",
"verify_reconstruction",
"verify_unknown_resolution",
"xrefs",
] as const;
// These assertions are deliberately structural rather than numeric. Pinning
// group sizes made every additive catalog change require a test edit, which
// blocked additive change without catching defects. Removal is still covered:
// the floor above catches a contract dropped from both its group and the
// aggregate.
describe("tool contract inventory", () => {
it("assigns every published tool a unique name", () => {
const names = TOOL_CONTRACTS.map(({ name }) => name);
expect(new Set(names).size).toBe(names.length);
});
it("contains every group member in the published inventory", () => {
const published = new Set(TOOL_CONTRACTS.map(({ name }) => name));
for (const [group, contracts] of Object.entries(GROUPS)) {
for (const { name } of contracts) {
expect(
published.has(name),
`${group} tool ${name} is not in TOOL_CONTRACTS`,
).toBe(true);
}
}
});
it("keeps every published tool name in the declared floor", () => {
const published = new Set(TOOL_CONTRACTS.map(({ name }) => name));
const removed = PUBLISHED_TOOL_NAME_FLOOR.filter(
(name) => !published.has(name),
);
expect(
removed,
"published tool names were removed; deleting one is a deliberate API change",
).toEqual([]);
});
it("keeps groups mutually disjoint", () => {
const entries = Object.entries(GROUPS);
for (const [leftName, left] of entries) {
for (const [rightName, right] of entries) {
if (leftName >= rightName) continue;
const rightNames = new Set(right.map(({ name }) => name));
const overlap = left
.map(({ name }) => name)
.filter((name) => rightNames.has(name));
expect(
overlap,
`${leftName} and ${rightName} both publish ${overlap.join(", ")}`,
).toEqual([]);
}
}
});
it("publishes a non-empty inventory from every group", () => {
for (const [group, contracts] of Object.entries(GROUPS)) {
expect(contracts.length, `${group} is empty`).toBeGreaterThan(0);
}
});
});