+
PermissionScope
diff --git a/docs/api/interfaces/domain_permissionPolicy.PermissionRequest.html b/docs/api/interfaces/domain_permissionPolicy.PermissionRequest.html
index db82c40b4..3181f55b4 100644
--- a/docs/api/interfaces/domain_permissionPolicy.PermissionRequest.html
+++ b/docs/api/interfaces/domain_permissionPolicy.PermissionRequest.html
@@ -15,7 +15,7 @@
-
+
PermissionScope
diff --git a/docs/api/interfaces/domain_permissionPolicy.PermissionScope.html b/docs/api/interfaces/domain_permissionPolicy.PermissionScope.html
index f22f665be..6aa86a674 100644
--- a/docs/api/interfaces/domain_permissionPolicy.PermissionScope.html
+++ b/docs/api/interfaces/domain_permissionPolicy.PermissionScope.html
@@ -15,7 +15,7 @@
-
+
PermissionScope
diff --git a/docs/api/interfaces/domain_webInventory.StableWebResource.html b/docs/api/interfaces/domain_webInventory.StableWebResource.html
index 1dbde87f4..aef0a68fd 100644
--- a/docs/api/interfaces/domain_webInventory.StableWebResource.html
+++ b/docs/api/interfaces/domain_webInventory.StableWebResource.html
@@ -12,7 +12,7 @@
StableWebResource
Interface StableWebResource
-
+
WebInventoryResourceInput
diff --git a/docs/api/interfaces/domain_webInventory.WebInventoryResourceInput.html b/docs/api/interfaces/domain_webInventory.WebInventoryResourceInput.html
index 936a27743..f2b607520 100644
--- a/docs/api/interfaces/domain_webInventory.WebInventoryResourceInput.html
+++ b/docs/api/interfaces/domain_webInventory.WebInventoryResourceInput.html
@@ -12,7 +12,7 @@
WebInventoryResourceInput
Interface WebInventoryResourceInput
-
+
WebInventoryResourceInput
diff --git a/docs/api/interfaces/ghidra_GhidraLauncher.GhidraLaunch.html b/docs/api/interfaces/ghidra_GhidraLauncher.GhidraLaunch.html
index 2a26bb452..f8cddfa56 100644
--- a/docs/api/interfaces/ghidra_GhidraLauncher.GhidraLaunch.html
+++ b/docs/api/interfaces/ghidra_GhidraLauncher.GhidraLaunch.html
@@ -15,7 +15,7 @@
-
+
ProviderProcessLaunch
diff --git a/docs/api/interfaces/ghidra_GhidraSessionError.GhidraSessionErrorOptions.html b/docs/api/interfaces/ghidra_GhidraSessionError.GhidraSessionErrorOptions.html
index 6984ad5bc..31d732015 100644
--- a/docs/api/interfaces/ghidra_GhidraSessionError.GhidraSessionErrorOptions.html
+++ b/docs/api/interfaces/ghidra_GhidraSessionError.GhidraSessionErrorOptions.html
@@ -15,7 +15,7 @@
-
+
Hierarchy
ErrorOptions
diff --git a/docs/api/interfaces/hopper_BridgeLauncher.BridgeLaunch.html b/docs/api/interfaces/hopper_BridgeLauncher.BridgeLaunch.html
index 1979fe5ca..c917d5c88 100644
--- a/docs/api/interfaces/hopper_BridgeLauncher.BridgeLaunch.html
+++ b/docs/api/interfaces/hopper_BridgeLauncher.BridgeLaunch.html
@@ -15,7 +15,7 @@
-
+
ProviderProcessLaunch
diff --git a/docs/api/interfaces/process_ProviderProcess.ProviderProcessLaunch.html b/docs/api/interfaces/process_ProviderProcess.ProviderProcessLaunch.html
index 3df9d777d..3cf60c195 100644
--- a/docs/api/interfaces/process_ProviderProcess.ProviderProcessLaunch.html
+++ b/docs/api/interfaces/process_ProviderProcess.ProviderProcessLaunch.html
@@ -15,7 +15,7 @@
-
+
ProviderProcessLaunch
diff --git a/docs/api/interfaces/server_createServer.CreateServerOptions.html b/docs/api/interfaces/server_createServer.CreateServerOptions.html
index b0fe0c4ee..25afd4adb 100644
--- a/docs/api/interfaces/server_createServer.CreateServerOptions.html
+++ b/docs/api/interfaces/server_createServer.CreateServerOptions.html
@@ -13,7 +13,7 @@
Interface CreateServerOptions
+Defined in src/server/createServer.ts:24
Optional Readonlyartifact artifactIntegrityContinueEnabled ?: () => boolean
+Defined in src/server/createServer.ts:33
Optional Readonlyavailability availabilityPolicy ?: () => { browserObservationEnabled ?: boolean ; electronObservationEnabled ?: boolean ; evidenceFileRoots : number ; processCaptureEnabled : boolean ; }
+Defined in src/server/createServer.ts:34
Optional Readonlybrowser
+Defined in src/server/createServer.ts:31
Optional Readonlyelectron
+Defined in src/server/createServer.ts:32
Optional Readonlyevidence
+Defined in src/server/createServer.ts:27
investigationInputRoots ?: readonly string []
+Defined in src/server/createServer.ts:28
Optional Readonlylogger logger ?: Logger
+Defined in src/server/createServer.ts:25
Optional Readonlypermission
+Defined in src/server/createServer.ts:30
Optional Readonlyprocess
+Defined in src/server/createServer.ts:26
+Variables JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE ToolKind : | "official-proxy" | "enhanced" | "native-provider" | "artifact-provider" | "browser-provider" | "electron-provider" | "session"
+ToolKind : | "official-proxy" | "enhanced" | "native-provider" | "artifact-provider" | "browser-provider" | "electron-provider" | "application" | "session"
diff --git a/docs/api/types/contracts_toolContracts.OfficialToolName.html b/docs/api/types/contracts_toolContracts.OfficialToolName.html
index 60d770f56..2aa728431 100644
--- a/docs/api/types/contracts_toolContracts.OfficialToolName.html
+++ b/docs/api/types/contracts_toolContracts.OfficialToolName.html
@@ -15,7 +15,7 @@
+Defined in src/contracts/toolContracts.ts:343
-javascriptRuntimeReconciliationResultSchema : ZodObject < { coverage : ZodObject < { omitted_graph_items : ZodNumber ; omitted_reconciliation_items : ZodNumber ; omitted_runtime_entities : ZodNumber ; omitted_static_load_states : ZodNumber ; status : ZodEnum < { "complete-within-inputs" : "complete-within-inputs" ; partial : "partial" ; truncated : "truncated" ; } , > ; truncated : ZodBoolean ; } , $strict , > ; evidence_links : ZodArray < ZodString > ; graph : ZodObject < { coverage : ZodObject < { limits : ZodArray < ZodObject < { name : ZodString ; unit : ZodEnum < { bytes : ...; characters : ...; depth : ...; instructions : ...; items : ...; milliseconds : ...; other : ...; } , > ; value : ZodNumber ; } , $strict , > , > ; omitted_count : ZodNullable < ZodNumber > ; status : ZodEnum < { complete : "complete" ; partial : "partial" ; unavailable : "unavailable" ; unknown : "unknown" ; } , > ; truncated : ZodBoolean ; } , $strict , > ; edges : ZodArray < ZodObject < { edge_id : ZodString ; evidence : ZodObject < { artifact : ZodDiscriminatedUnion < [ (...), (...)] , "available" > ; authority : ZodEnum < { "artifact-bytes" : ...; "ast-static-analysis" : ...; "controlled-replay" : ...; "cross-layer-reconciliation" : ...; "historical-reference" : ...; "native-analysis-provider" : ...; "passive-cdp-runtime" : ...; "static-relationship-inference" : ...; unknown : ...; "user-assertion" : ...; } , > ; confidence : ZodEnum < { exact : ...; high : ...; low : ...; medium : ...; unknown : ... } , > ; coverage : ZodObject < { limits : ...; omitted_count : ...; status : ...; truncated : ...; } , $strict , > ; evidence_ids : ZodArray < ZodString > ; extractor : ZodObject < { executable_sha256 : ...; name : ...; operation : ...; version : ...; } , $strict , > ; limitations : ZodArray < ZodString > ; location : ZodDiscriminatedUnion < [ (...), (...)] , "available" > ; state : ZodEnum < { inferred : ...; observed : ...; unavailable : ...; unknown : ...; } , > ; } , $strict , > ; identifier_strategy : ZodObject < { stability : ZodLiteral < "relationship-exact" > ; strategy : ZodLiteral < "semantic-content-sha256" > ; } , $strict , > ; properties : ZodRecord < ZodString , ZodJSONSchema > ; relation : ZodEnum < { calls : "calls" ; changed_from : "changed_from" ; contains : "contains" ; exposes : "exposes" ; handles : "handles" ; imports : "imports" ; invokes : "invokes" ; loads : "loads" ; maps_to : "maps_to" ; observed_as : "observed_as" ; persists_to : "persists_to" ; sends : "sends" ; } , > ; source_node_id : ZodString ; target_node_id : ZodString ; } , $strict , > , > ; graph_id : ZodString ; limitations : ZodArray < ZodString > ; nodes : ZodArray < ZodObject < { identity : ZodDiscriminatedUnion < [ ZodObject < { sha256 : ...; stability : ...; strategy : ... } , $strict , > , ZodObject < { original_source : ...; source_map_sha256 : ...; source_sha256 : ...; stability : ...; strategy : ...; } , $strict , > , ZodObject < { artifact_sha256 : ...; path : ...; stability : ...; strategy : ...; } , $strict , > , ] , "strategy" , > ; kind : ZodEnum < { artifact : "artifact" ; "asar-entry" : "asar-entry" ; "browser-window" : "browser-window" ; "context-bridge-api" : "context-bridge-api" ; "electron-main" : "electron-main" ; "electron-preload" : "electron-preload" ; "electron-renderer" : "electron-renderer" ; "electron-utility" : "electron-utility" ; endpoint : "endpoint" ; frame : "frame" ; installer : "installer" ; "ipc-channel" : "ipc-channel" ; "ipc-handler" : "ipc-handler" ; "javascript-asset" : "javascript-asset" ; "javascript-chunk" : "javascript-chunk" ; "javascript-module" : "javascript-module" ; "native-addon" : "native-addon" ; "native-export" : "native-export" ; package : "package" ; "runtime-script-instance" : "runtime-script-instance" ; "service-worker" : "service-worker" ; "source-map" : "source-map" ; "source-module" : "source-module" ; storage : "storage" ; target : "target" ; unknown : "unknown" ; worker : "worker" ; } , > ; node_id : ZodString ; observations : ZodArray < ZodObject < { evidence : ZodObject < (...), (...)> ; identifier_strategy : ZodObject < (...), (...)> ; label : ZodNullable < (...)> ; observation_id : ZodString ; properties : ZodRecord < (...), (...)> ; } , $strict , > , > ; } , $strict , > , > ; root_node_ids : ZodArray < ZodString > ; schema : ZodLiteral < "JavaScriptApplicationGraph" > ; schema_version : ZodLiteral < 1 > ; } , $strict , > ; limitations : ZodArray < ZodString > ; reconciliation_id : ZodString ; reconciliations : ZodArray < ZodObject < { basis : ZodEnum < { "artifact-path" : "artifact-path" ; "content-and-location" : "content-and-location" ; "content-sha256" : "content-sha256" ; "module-source-sha256" : "module-source-sha256" ; none : "none" ; "operator-file-mapping" : "operator-file-mapping" ; "operator-url-mapping" : "operator-url-mapping" ; } , > ; candidate_static_count : ZodNumber ; candidate_static_nodes : ZodArray < ZodObject < { static_layer_id : ZodString ; static_node_id : ZodString } , $strict , > , > ; confidence : ZodEnum < { exact : "exact" ; high : "high" ; low : "low" ; medium : "medium" ; unknown : "unknown" ; } , > ; entity_kind : ZodEnum < { frame : "frame" ; script : "script" ; target : "target" ; worker : "worker" ; } , > ; reason : ZodEnum < { "ambiguous-static-candidates" : "ambiguous-static-candidates" ; "captured-content-disagrees-with-static-location" : "captured-content-disagrees-with-static-location" ; "content-and-location-match" : "content-and-location-match" ; "no-authorized-location-mapping" : "no-authorized-location-mapping" ; "no-static-content-match" : "no-static-content-match" ; "reconciliation-limit-reached" : "reconciliation-limit-reached" ; "runtime-frame-unattributed" : "runtime-frame-unattributed" ; "static-or-runtime-coverage-incomplete" : "static-or-runtime-coverage-incomplete" ; "unique-content-match" : "unique-content-match" ; "unique-location-match" : "unique-location-match" ; } , > ; reconciliation_id : ZodString ; runtime_evidence_id : ZodString ; runtime_node_id : ZodString ; static_layer_id : ZodNullable < ZodString > ; static_node_id : ZodNullable < ZodString > ; status : ZodEnum < { ambiguous : "ambiguous" ; matched : "matched" ; unknown : "unknown" ; unmatched : "unmatched" ; } , > ; } , $strict , > , > ; runtime_captures : ZodArray < ZodObject < { capture_sha256 : ZodString ; evidence_id : ZodString ; frames : ZodNumber ; kind : ZodEnum < { browser : "browser" ; electron : "electron" } > ; scripts : ZodNumber ; scripts_complete_within_scope : ZodBoolean ; target_key : ZodString ; target_location : ZodString ; target_node_id : ZodString ; workers : ZodNumber ; } , $strict , > , > ; schema_version : ZodLiteral < 1 > ; source_map_authority : ZodObject < { limitation : ZodString ; runtime_script_declarations : ZodNumber ; static_layers_with_read_approval : ZodNumber ; used_for_primary_matching : ZodLiteral < false > ; } , $strict , > ; static_layers : ZodArray < ZodObject < { evidence_id : ZodString ; format : ZodEnum < { asar : "asar" ; directory : "directory" } > ; graph_id : ZodString ; input_path : ZodString ; layer_id : ZodString ; role : ZodEnum < { application : "application" ; assets : "assets" ; cache : "cache" } , > ; root_artifact_sha256 : ZodString ; runtime_mappings : ZodArray < ZodDiscriminatedUnion < [ ZodObject < { artifact_prefix : ZodDefault < (...)> ; kind : ZodLiteral < (...)> ; root : ZodString ; } , $strict , > , ZodObject < { artifact_prefix : ZodDefault < (...)> ; kind : ZodLiteral < (...)> ; prefix : ZodString ; } , $strict , > , ] , "kind" , > , > ; } , $strict , > , > ; static_load_states : ZodArray < ZodObject < { kind : ZodEnum < { "javascript-asset" : "javascript-asset" ; "javascript-chunk" : "javascript-chunk" ; "javascript-module" : "javascript-module" ; } , > ; reason : ZodEnum < { "containing-asset-was-loaded" : "containing-asset-was-loaded" ; "layer-outside-runtime-scope" : "layer-outside-runtime-scope" ; "not-observed-in-bounded-capture" : "not-observed-in-bounded-capture" ; "runtime-script-correspondence" : "runtime-script-correspondence" ; "static-or-runtime-coverage-incomplete" : "static-or-runtime-coverage-incomplete" ; } , > ; runtime_node_ids : ZodArray < ZodString > ; static_layer_id : ZodString ; static_node_id : ZodString ; status : ZodEnum < { loaded : "loaded" ; "not-observed-in-capture" : "not-observed-in-capture" ; "resident-in-loaded-asset" : "resident-in-loaded-asset" ; unknown : "unknown" ; } , > ; } , $strict , > , > ; summary : ZodObject < { ambiguous : ZodNumber ; matched : ZodNumber ; runtime_frames : ZodNumber ; runtime_scripts : ZodNumber ; runtime_targets : ZodNumber ; runtime_workers : ZodNumber ; static_loaded : ZodNumber ; static_not_observed : ZodNumber ; static_resident : ZodNumber ; static_unknown : ZodNumber ; unknown : ZodNumber ; unmatched : ZodNumber ; } , $strict , > ; } , $strict , > = ...
+javascriptRuntimeReconciliationResultSchema : ZodObject < { coverage : ZodObject < { omitted_graph_items : ZodNumber ; omitted_reconciliation_items : ZodNumber ; omitted_runtime_entities : ZodNumber ; omitted_static_load_states : ZodNumber ; status : ZodEnum < { "complete-within-inputs" : "complete-within-inputs" ; partial : "partial" ; truncated : "truncated" ; } , > ; truncated : ZodBoolean ; } , $strict , > ; evidence_links : ZodArray < ZodString > ; graph : ZodObject < { coverage : ZodObject < { limits : ZodArray < ZodObject < { name : ZodString ; unit : ZodEnum < { bytes : ...; characters : ...; depth : ...; instructions : ...; items : ...; milliseconds : ...; other : ...; } , > ; value : ZodNumber ; } , $strict , > , > ; omitted_count : ZodNullable < ZodNumber > ; status : ZodEnum < { complete : "complete" ; partial : "partial" ; unavailable : "unavailable" ; unknown : "unknown" ; } , > ; truncated : ZodBoolean ; } , $strict , > ; edges : ZodArray < ZodObject < { edge_id : ZodString ; evidence : ZodObject < { artifact : ZodDiscriminatedUnion < [ (...), (...)] , "available" > ; authority : ZodEnum < { "artifact-bytes" : ...; "ast-static-analysis" : ...; "controlled-replay" : ...; "cross-layer-reconciliation" : ...; "cross-version-comparison" : ...; "historical-reference" : ...; "native-analysis-provider" : ...; "passive-cdp-runtime" : ...; "static-relationship-inference" : ...; unknown : ...; "user-assertion" : ...; } , > ; confidence : ZodEnum < { exact : ...; high : ...; low : ...; medium : ...; unknown : ... } , > ; coverage : ZodObject < { limits : ...; omitted_count : ...; status : ...; truncated : ...; } , $strict , > ; evidence_ids : ZodArray < ZodString > ; extractor : ZodObject < { executable_sha256 : ...; name : ...; operation : ...; version : ...; } , $strict , > ; limitations : ZodArray < ZodString > ; location : ZodDiscriminatedUnion < [ (...), (...)] , "available" > ; state : ZodEnum < { inferred : ...; observed : ...; unavailable : ...; unknown : ...; } , > ; } , $strict , > ; identifier_strategy : ZodObject < { stability : ZodLiteral < "relationship-exact" > ; strategy : ZodLiteral < "semantic-content-sha256" > ; } , $strict , > ; properties : ZodRecord < ZodString , ZodJSONSchema > ; relation : ZodEnum < { calls : "calls" ; changed_from : "changed_from" ; contains : "contains" ; exposes : "exposes" ; handles : "handles" ; imports : "imports" ; invokes : "invokes" ; loads : "loads" ; maps_to : "maps_to" ; observed_as : "observed_as" ; persists_to : "persists_to" ; sends : "sends" ; } , > ; source_node_id : ZodString ; target_node_id : ZodString ; } , $strict , > , > ; graph_id : ZodString ; limitations : ZodArray < ZodString > ; nodes : ZodArray < ZodObject < { identity : ZodDiscriminatedUnion < [ ZodObject < { sha256 : ...; stability : ...; strategy : ... } , $strict , > , ZodObject < { original_source : ...; source_map_sha256 : ...; source_sha256 : ...; stability : ...; strategy : ...; } , $strict , > , ZodObject < { artifact_sha256 : ...; path : ...; stability : ...; strategy : ...; } , $strict , > , ] , "strategy" , > ; kind : ZodEnum < { artifact : "artifact" ; "asar-entry" : "asar-entry" ; "browser-window" : "browser-window" ; "context-bridge-api" : "context-bridge-api" ; "electron-main" : "electron-main" ; "electron-preload" : "electron-preload" ; "electron-renderer" : "electron-renderer" ; "electron-utility" : "electron-utility" ; endpoint : "endpoint" ; frame : "frame" ; installer : "installer" ; "ipc-channel" : "ipc-channel" ; "ipc-handler" : "ipc-handler" ; "javascript-asset" : "javascript-asset" ; "javascript-chunk" : "javascript-chunk" ; "javascript-module" : "javascript-module" ; "native-addon" : "native-addon" ; "native-export" : "native-export" ; package : "package" ; "runtime-script-instance" : "runtime-script-instance" ; "service-worker" : "service-worker" ; "source-map" : "source-map" ; "source-module" : "source-module" ; storage : "storage" ; target : "target" ; unknown : "unknown" ; worker : "worker" ; } , > ; node_id : ZodString ; observations : ZodArray < ZodObject < { evidence : ZodObject < (...), (...)> ; identifier_strategy : ZodObject < (...), (...)> ; label : ZodNullable < (...)> ; observation_id : ZodString ; properties : ZodRecord < (...), (...)> ; } , $strict , > , > ; } , $strict , > , > ; root_node_ids : ZodArray < ZodString > ; schema : ZodLiteral < "JavaScriptApplicationGraph" > ; schema_version : ZodLiteral < 1 > ; } , $strict , > ; limitations : ZodArray < ZodString > ; reconciliation_id : ZodString ; reconciliations : ZodArray < ZodObject < { basis : ZodEnum < { "artifact-path" : "artifact-path" ; "content-and-location" : "content-and-location" ; "content-sha256" : "content-sha256" ; "module-source-sha256" : "module-source-sha256" ; none : "none" ; "operator-file-mapping" : "operator-file-mapping" ; "operator-url-mapping" : "operator-url-mapping" ; } , > ; candidate_static_count : ZodNumber ; candidate_static_nodes : ZodArray < ZodObject < { static_layer_id : ZodString ; static_node_id : ZodString } , $strict , > , > ; confidence : ZodEnum < { exact : "exact" ; high : "high" ; low : "low" ; medium : "medium" ; unknown : "unknown" ; } , > ; entity_kind : ZodEnum < { frame : "frame" ; script : "script" ; target : "target" ; worker : "worker" ; } , > ; reason : ZodEnum < { "ambiguous-static-candidates" : "ambiguous-static-candidates" ; "captured-content-disagrees-with-static-location" : "captured-content-disagrees-with-static-location" ; "content-and-location-match" : "content-and-location-match" ; "no-authorized-location-mapping" : "no-authorized-location-mapping" ; "no-static-content-match" : "no-static-content-match" ; "reconciliation-limit-reached" : "reconciliation-limit-reached" ; "runtime-frame-unattributed" : "runtime-frame-unattributed" ; "static-or-runtime-coverage-incomplete" : "static-or-runtime-coverage-incomplete" ; "unique-content-match" : "unique-content-match" ; "unique-location-match" : "unique-location-match" ; } , > ; reconciliation_id : ZodString ; runtime_evidence_id : ZodString ; runtime_node_id : ZodString ; static_layer_id : ZodNullable < ZodString > ; static_node_id : ZodNullable < ZodString > ; status : ZodEnum < { ambiguous : "ambiguous" ; matched : "matched" ; unknown : "unknown" ; unmatched : "unmatched" ; } , > ; } , $strict , > , > ; runtime_captures : ZodArray < ZodObject < { capture_sha256 : ZodString ; evidence_id : ZodString ; frames : ZodNumber ; kind : ZodEnum < { browser : "browser" ; electron : "electron" } > ; scripts : ZodNumber ; scripts_complete_within_scope : ZodBoolean ; target_key : ZodString ; target_location : ZodString ; target_node_id : ZodString ; workers : ZodNumber ; } , $strict , > , > ; schema_version : ZodLiteral < 1 > ; source_map_authority : ZodObject < { limitation : ZodString ; runtime_script_declarations : ZodNumber ; static_layers_with_read_approval : ZodNumber ; used_for_primary_matching : ZodLiteral < false > ; } , $strict , > ; static_layers : ZodArray < ZodObject < { evidence_id : ZodString ; format : ZodEnum < { asar : "asar" ; directory : "directory" } > ; graph_id : ZodString ; input_path : ZodString ; layer_id : ZodString ; role : ZodEnum < { application : "application" ; assets : "assets" ; cache : "cache" } , > ; root_artifact_sha256 : ZodString ; runtime_mappings : ZodArray < ZodDiscriminatedUnion < [ ZodObject < { artifact_prefix : ZodDefault < (...)> ; kind : ZodLiteral < (...)> ; root : ZodString ; } , $strict , > , ZodObject < { artifact_prefix : ZodDefault < (...)> ; kind : ZodLiteral < (...)> ; prefix : ZodString ; } , $strict , > , ] , "kind" , > , > ; } , $strict , > , > ; static_load_states : ZodArray < ZodObject < { kind : ZodEnum < { "javascript-asset" : "javascript-asset" ; "javascript-chunk" : "javascript-chunk" ; "javascript-module" : "javascript-module" ; } , > ; reason : ZodEnum < { "containing-asset-was-loaded" : "containing-asset-was-loaded" ; "layer-outside-runtime-scope" : "layer-outside-runtime-scope" ; "not-observed-in-bounded-capture" : "not-observed-in-bounded-capture" ; "runtime-script-correspondence" : "runtime-script-correspondence" ; "static-or-runtime-coverage-incomplete" : "static-or-runtime-coverage-incomplete" ; } , > ; runtime_node_ids : ZodArray < ZodString > ; static_layer_id : ZodString ; static_node_id : ZodString ; status : ZodEnum < { loaded : "loaded" ; "not-observed-in-capture" : "not-observed-in-capture" ; "resident-in-loaded-asset" : "resident-in-loaded-asset" ; unknown : "unknown" ; } , > ; } , $strict , > , > ; summary : ZodObject < { ambiguous : ZodNumber ; matched : ZodNumber ; runtime_frames : ZodNumber ; runtime_scripts : ZodNumber ; runtime_targets : ZodNumber ; runtime_workers : ZodNumber ; static_loaded : ZodNumber ; static_not_observed : ZodNumber ; static_resident : ZodNumber ; static_unknown : ZodNumber ; unknown : ZodNumber ; unmatched : ZodNumber ; } , $strict , > ; } , $strict , > = ...
diff --git a/docs/architecture.mermaid b/docs/architecture.mermaid
index f8920dc08..97c2698e8 100644
--- a/docs/architecture.mermaid
+++ b/docs/architecture.mermaid
@@ -32,7 +32,7 @@ graph TD
end
subgraph "Contracts Layer"
- CONTRACTS["src/contracts/ => {
+ const operation = "trace_application_feature";
+ const parsed = traceApplicationFeatureInputSchema.safeParse(rawInput);
+ if (!parsed.success) return err(new AnalysisInputError(operation));
+ try {
+ const source = parseApplicationGraphEvidence(parsed.data.application);
+ const nativeEvidence = parseNativeApplicationEvidence(
+ parsed.data.native_observations,
+ );
+ const result = traceApplicationFeature({
+ sourceEvidenceId: source.evidence.evidence_id,
+ graph: source.graph,
+ nativeEvidence,
+ seed: parsed.data.seed,
+ direction: parsed.data.direction,
+ limits: parsed.data.limits,
+ });
+ return ok(
+ createApplicationFeatureTraceEvidence(
+ {
+ application_evidence_id: source.evidence.evidence_id,
+ native_evidence_ids: nativeEvidence.map(({ evidence_id: id }) => id),
+ seed: parsed.data.seed,
+ direction: parsed.data.direction,
+ limits: parsed.data.limits,
+ },
+ result,
+ ),
+ );
+ } catch (cause: unknown) {
+ return workflowFailure(operation, cause);
+ }
+};
+
+/** Authenticate both graphs and derive a tiered cross-version change graph. */
+export const compareApplicationVersionsEvidence = (
+ rawInput: unknown,
+): Result => {
+ const operation = "compare_application_versions";
+ const parsed = compareApplicationVersionsInputSchema.safeParse(rawInput);
+ if (!parsed.success) return err(new AnalysisInputError(operation));
+ try {
+ const left = parseApplicationGraphEvidence(parsed.data.left);
+ const right = parseApplicationGraphEvidence(parsed.data.right);
+ const leftNative = parseNativeApplicationEvidence(
+ parsed.data.left_native_observations,
+ );
+ const rightNative = parseNativeApplicationEvidence(
+ parsed.data.right_native_observations,
+ );
+ const result = compareJavaScriptApplicationVersions({
+ left: {
+ evidenceId: left.evidence.evidence_id,
+ rootArtifactSha256: left.rootArtifactSha256,
+ graph: left.graph,
+ },
+ right: {
+ evidenceId: right.evidence.evidence_id,
+ rootArtifactSha256: right.rootArtifactSha256,
+ graph: right.graph,
+ },
+ leftNativeEvidence: leftNative,
+ rightNativeEvidence: rightNative,
+ limits: parsed.data.limits,
+ });
+ return ok(
+ createApplicationVersionComparisonEvidence(
+ {
+ left_evidence_id: left.evidence.evidence_id,
+ right_evidence_id: right.evidence.evidence_id,
+ left_native_evidence_ids: leftNative.map(({ evidence_id: id }) => id),
+ right_native_evidence_ids: rightNative.map(
+ ({ evidence_id: id }) => id,
+ ),
+ limits: parsed.data.limits,
+ },
+ result,
+ ),
+ );
+ } catch (cause: unknown) {
+ return workflowFailure(operation, cause);
+ }
+};
+
+const workflowFailure = (
+ operation: string,
+ cause: unknown,
+): Result =>
+ err(
+ cause instanceof z.ZodError || cause instanceof TypeError
+ ? new AnalysisInputError(operation)
+ : new AnalysisProtocolError(
+ "JavaScript application workflow produced an invalid result",
+ { cause },
+ ),
+ );
diff --git a/src/cli.ts b/src/cli.ts
index 307ef3ae9..89c2dfc91 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -34,6 +34,7 @@ import { registerPolicyCommands } from "./cliPolicyCommands.js";
import { registerBrowserCommands } from "./cliBrowserCommands.js";
import { registerAdvancedBrowserCommands } from "./cliBrowserAdvancedCommands.js";
import { registerElectronCommands } from "./cliElectronCommands.js";
+import { registerApplicationCommands } from "./cliApplicationCommands.js";
import { CLI_COMMANDS } from "./cliCommandNames.js";
import {
analysisProviderSelectorSchema,
@@ -89,6 +90,7 @@ export const createCli = (): ReturnType => {
registerBrowserCommands(cli, logger);
registerAdvancedBrowserCommands(cli, logger);
registerElectronCommands(cli, logger);
+ registerApplicationCommands(cli, logger);
return cli;
};
diff --git a/src/cliApplicationCommands.ts b/src/cliApplicationCommands.ts
new file mode 100644
index 000000000..013b21d2e
--- /dev/null
+++ b/src/cliApplicationCommands.ts
@@ -0,0 +1,68 @@
+import { Cli, z } from "incur";
+
+import {
+ compareApplicationVersionsEvidence,
+ traceApplicationFeatureEvidence,
+} from "./application/JavaScriptApplicationWorkflowService.js";
+import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { parseCliJsonInput } from "./cliJsonInput.js";
+import { logCliCommand } from "./cliLogging.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import type { JsonValue } from "./domain/jsonValue.js";
+import type { Logger } from "./logger.js";
+
+/** Register CLI equivalents of provider-neutral application graph workflows. */
+export const registerApplicationCommands = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ registerJsonCommand(
+ cli,
+ logger,
+ CLI_COMMANDS.traceApplicationFeature,
+ "Trace a typed seed through authenticated application Evidence JSON",
+ traceApplicationFeatureEvidence,
+ );
+ registerJsonCommand(
+ cli,
+ logger,
+ CLI_COMMANDS.compareApplicationVersions,
+ "Compare two authenticated JavaScript Application Graph versions",
+ compareApplicationVersionsEvidence,
+ );
+};
+
+const registerJsonCommand = (
+ cli: ReturnType,
+ logger: Logger,
+ name: string,
+ description: string,
+ workflow: (
+ input: unknown,
+ ) =>
+ | { readonly ok: true; readonly value: JsonValue }
+ | { readonly ok: false; readonly error: Error },
+): void => {
+ cli.command(name, {
+ description,
+ args: z.object({
+ inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
+ }),
+ run: ({ args }) =>
+ logCliCommand(logger, name, async () => {
+ const input = await parseCliJsonInput(args.inputJson, name);
+ if (!input.ok) return input.error;
+ const result = workflow(input.value);
+ return result.ok
+ ? result.value
+ : {
+ error: "Application workflow failed",
+ ...projectAnalysisError(
+ result.error instanceof AnalysisInputError
+ ? result.error
+ : new AnalysisInputError(name),
+ ),
+ };
+ }),
+ });
+};
diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.ts
index a99d59af2..a24d57973 100644
--- a/src/cliCommandNames.ts
+++ b/src/cliCommandNames.ts
@@ -40,6 +40,8 @@ export const CLI_COMMANDS = Object.freeze({
inspectElectronPage: "inspect-electron-page",
analyzeJavaScriptApplication: "analyze-javascript-application",
reconcileJavaScriptRuntime: "reconcile-javascript-runtime",
+ traceApplicationFeature: "trace-application-feature",
+ compareApplicationVersions: "compare-application-versions",
});
/** Ordered primary CLI inventory; aliases are intentionally excluded. */
diff --git a/src/cliElectronCommands.ts b/src/cliElectronCommands.ts
index 296327c01..03f7aac6e 100644
--- a/src/cliElectronCommands.ts
+++ b/src/cliElectronCommands.ts
@@ -1,5 +1,3 @@
-import { readFile, stat } from "node:fs/promises";
-
import { Cli, z } from "incur";
import {
@@ -21,8 +19,7 @@ import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
import type { JsonValue } from "./domain/jsonValue.js";
import type { Logger } from "./logger.js";
import { CLI_COMMANDS } from "./cliCommandNames.js";
-
-const MAX_RECONCILIATION_INPUT_BYTES = 64 * 1_024 * 1_024;
+import { parseCliJsonInput } from "./cliJsonInput.js";
const scopeOptions = {
allowedFileRoots: z
@@ -61,7 +58,10 @@ const registerJavaScriptRuntimeReconciliationCommand = (
logger,
CLI_COMMANDS.reconcileJavaScriptRuntime,
async () => {
- const input = await parseJsonInput(args.inputJson);
+ const input = await parseCliJsonInput(
+ args.inputJson,
+ "reconcile_javascript_runtime",
+ );
if (!input.ok) return input.error;
const result = reconcileJavaScriptRuntimeEvidence(input.value);
return result.ok ? result.value : cliError(result.error);
@@ -266,60 +266,6 @@ const electronContext = async () => {
const inputError = (operation: string): JsonValue =>
cliError(new AnalysisInputError(operation));
-const parseJson = (value: string): unknown => {
- try {
- return JSON.parse(value);
- } catch {
- return undefined;
- }
-};
-
-const parseJsonInput = async (
- value: string,
-): Promise<
- | { readonly ok: true; readonly value: unknown }
- | { readonly ok: false; readonly error: JsonValue }
-> => {
- const inline = parseJson(value);
- if (inline !== undefined) return { ok: true, value: inline };
- if (["{", "["].includes(value.trimStart()[0] ?? ""))
- return {
- ok: false,
- error: inputError("reconcile_javascript_runtime"),
- };
- try {
- const metadata = await stat(value);
- if (!metadata.isFile()) return jsonFileError(value, "not-file");
- if (metadata.size > MAX_RECONCILIATION_INPUT_BYTES)
- return jsonFileError(value, "too-large");
- const bytes = await readFile(value);
- if (bytes.byteLength > MAX_RECONCILIATION_INPUT_BYTES)
- return jsonFileError(value, "too-large");
- const parsed = parseJson(bytes.toString("utf8"));
- return parsed === undefined
- ? jsonFileError(value, "invalid-json")
- : { ok: true, value: parsed };
- } catch {
- return jsonFileError(value, "read-failed");
- }
-};
-
-const jsonFileError = (
- path: string,
- reason: "not-file" | "too-large" | "invalid-json" | "read-failed",
-) => ({
- ok: false as const,
- error: {
- error: "Electron analysis failed",
- ...projectAnalysisError(
- new AnalysisInputError("reconcile_javascript_runtime"),
- ),
- input_path: path,
- input_reason: reason,
- maximum_input_bytes: MAX_RECONCILIATION_INPUT_BYTES,
- },
-});
-
const cliError = (
error: Parameters[0],
): JsonValue => ({
diff --git a/src/cliJsonInput.ts b/src/cliJsonInput.ts
new file mode 100644
index 000000000..deca5b7bc
--- /dev/null
+++ b/src/cliJsonInput.ts
@@ -0,0 +1,63 @@
+import { readFile, stat } from "node:fs/promises";
+
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import type { JsonValue } from "./domain/jsonValue.js";
+
+const MAX_JSON_INPUT_BYTES = 64 * 1_024 * 1_024;
+
+/** Parse bounded inline JSON or one bounded local JSON file for a CLI workflow. */
+export const parseCliJsonInput = async (
+ value: string,
+ operation: string,
+): Promise<
+ | { readonly ok: true; readonly value: unknown }
+ | { readonly ok: false; readonly error: JsonValue }
+> => {
+ const inline = parseJson(value);
+ if (inline !== undefined) return { ok: true, value: inline };
+ if (["{", "["].includes(value.trimStart()[0] ?? ""))
+ return { ok: false, error: inputError(operation) };
+ try {
+ const metadata = await stat(value);
+ if (!metadata.isFile()) return jsonFileError(value, operation, "not-file");
+ if (metadata.size > MAX_JSON_INPUT_BYTES)
+ return jsonFileError(value, operation, "too-large");
+ const bytes = await readFile(value);
+ if (bytes.byteLength > MAX_JSON_INPUT_BYTES)
+ return jsonFileError(value, operation, "too-large");
+ const parsed = parseJson(bytes.toString("utf8"));
+ return parsed === undefined
+ ? jsonFileError(value, operation, "invalid-json")
+ : { ok: true, value: parsed };
+ } catch {
+ return jsonFileError(value, operation, "read-failed");
+ }
+};
+
+const parseJson = (value: string): unknown => {
+ try {
+ return JSON.parse(value);
+ } catch {
+ return undefined;
+ }
+};
+
+const inputError = (operation: string): JsonValue => ({
+ error: "Application workflow failed",
+ ...projectAnalysisError(new AnalysisInputError(operation)),
+});
+
+const jsonFileError = (
+ path: string,
+ operation: string,
+ reason: "not-file" | "too-large" | "invalid-json" | "read-failed",
+) => ({
+ ok: false as const,
+ error: {
+ error: "Application workflow failed",
+ ...projectAnalysisError(new AnalysisInputError(operation)),
+ input_path: path,
+ input_reason: reason,
+ maximum_input_bytes: MAX_JSON_INPUT_BYTES,
+ },
+});
diff --git a/src/contracts/applicationToolContracts.ts b/src/contracts/applicationToolContracts.ts
new file mode 100644
index 000000000..68fdadc5f
--- /dev/null
+++ b/src/contracts/applicationToolContracts.ts
@@ -0,0 +1,65 @@
+import {
+ applicationVersionComparisonResultSchema,
+ compareApplicationVersionsInputSchema,
+} from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import {
+ applicationFeatureTraceResultSchema,
+ traceApplicationFeatureInputSchema,
+} from "../domain/javascriptFeatureTraceSchemas.js";
+import { evidenceEnvelopeSchema } from "../domain/evidence.js";
+import type { ToolContract } from "./toolContracts.js";
+import {
+ JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+ JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+} from "./javascriptApplicationWorkflowExamples.js";
+
+const traceOutputSchema = evidenceEnvelopeSchema
+ .omit({ normalized_result: true })
+ .extend({ normalized_result: applicationFeatureTraceResultSchema });
+const comparisonOutputSchema = evidenceEnvelopeSchema
+ .omit({ normalized_result: true })
+ .extend({ normalized_result: applicationVersionComparisonResultSchema });
+
+/** Provider-neutral graph workflow contracts shared by MCP and CLI adapters. */
+export const APPLICATION_TOOL_CONTRACTS = [
+ {
+ name: "trace_application_feature",
+ description:
+ "Trace a typed literal seed through an authenticated JavaScript Application Graph with explicit direction, depth, node, edge, and path bounds. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
+ kind: "application",
+ inputSchema: traceApplicationFeatureInputSchema,
+ outputSchema: traceOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false,
+ },
+ examples: [
+ {
+ title: "Trace one module seed through a retained application graph",
+ input: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+ },
+ ],
+ },
+ {
+ name: "compare_application_versions",
+ description:
+ "Compare two authenticated JavaScript Application Graph versions using unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus a bounded changed_from graph without fuzzy or module-ordinal pairing.",
+ kind: "application",
+ inputSchema: compareApplicationVersionsInputSchema,
+ outputSchema: comparisonOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false,
+ },
+ examples: [
+ {
+ title: "Compare authenticated static and reconciled application graphs",
+ input: JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+ },
+ ],
+ },
+] as const satisfies readonly ToolContract[];
diff --git a/src/contracts/javascriptApplicationWorkflowExamples.ts b/src/contracts/javascriptApplicationWorkflowExamples.ts
new file mode 100644
index 000000000..f15083b92
--- /dev/null
+++ b/src/contracts/javascriptApplicationWorkflowExamples.ts
@@ -0,0 +1,64 @@
+import { createEvidence } from "../domain/evidence.js";
+import { reconcileJavaScriptRuntime } from "../domain/javascriptRuntimeReconciliation.js";
+import {
+ JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+ JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
+} from "./javascriptRuntimeReconciliationExample.js";
+
+const reconciliation = reconcileJavaScriptRuntime(
+ JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
+);
+const reconciliationEvidence = createEvidence(
+ undefined,
+ {
+ id: "rea-javascript-runtime-reconciliation",
+ name: "REA JavaScript runtime reconciliation",
+ version: "1",
+ },
+ {
+ predicateType: "rea.javascript-runtime-reconciliation/v1",
+ operation: "reconcile_javascript_runtime",
+ parameters: {
+ static_layers:
+ JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.static_layers.map(
+ ({ role, analysis }) => ({
+ role,
+ evidence_id: analysis.evidence_id,
+ runtime_mappings: [],
+ }),
+ ),
+ runtime_evidence_ids:
+ JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.runtime_observations.map(
+ ({ evidence_id: id }) => id,
+ ),
+ limits: {
+ max_runtime_entities: 10_000,
+ max_reconciliation_items: 20_000,
+ max_static_load_states: 20_000,
+ },
+ },
+ result: reconciliation,
+ confidence: "inferred",
+ authority: "analyst-inference",
+ limitations: reconciliation.limitations,
+ evidenceLinks: reconciliation.evidence_links,
+ },
+);
+
+/** Valid public trace request without proprietary artifacts. */
+export const JAVASCRIPT_FEATURE_TRACE_EXAMPLE = {
+ application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+ seed: {
+ kind: "module" as const,
+ value: "renderer.js",
+ match: "exact" as const,
+ case_sensitive: false,
+ },
+ direction: "both" as const,
+};
+
+/** Valid static/runtime graph pair demonstrating comparison authority. */
+export const JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE = {
+ left: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+ right: reconciliationEvidence,
+};
diff --git a/src/contracts/javascriptRuntimeReconciliationExample.ts b/src/contracts/javascriptRuntimeReconciliationExample.ts
index f3529b7e1..6f9320256 100644
--- a/src/contracts/javascriptRuntimeReconciliationExample.ts
+++ b/src/contracts/javascriptRuntimeReconciliationExample.ts
@@ -132,6 +132,9 @@ const staticEvidence = createEvidence(
},
);
+/** Minimal valid static application Evidence for graph workflow examples. */
+export const JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE = staticEvidence;
+
const runtimeEvidence = createEvidence(
undefined,
{
diff --git a/src/contracts/promptContracts.ts b/src/contracts/promptContracts.ts
index 1a7bb237b..b74fd2c6e 100644
--- a/src/contracts/promptContracts.ts
+++ b/src/contracts/promptContracts.ts
@@ -114,9 +114,13 @@ export const PROMPT_CONTRACTS = [
},
steps: [
{
- tools: ["binary_session", "open_binary"],
+ tools: [
+ "binary_session",
+ "open_binary",
+ "analyze_javascript_application",
+ ],
instruction:
- "Inspect provider availability and effects first. Open target_path only when no matching target is active.",
+ "Inspect provider availability and effects first. For an approved JavaScript/Electron artifact, reconstruct its application graph without execution; otherwise open target_path only when no matching target is active.",
},
{
tools: ["list_documents", "set_current_document", "binary_overview"],
@@ -128,6 +132,11 @@ export const PROMPT_CONTRACTS = [
instruction:
"Search in literal mode first, follow every continuation needed for the stated scope, and resolve selected procedures to canonical addresses.",
},
+ {
+ tools: ["trace_application_feature"],
+ instruction:
+ "When authenticated application-graph Evidence exists, trace a typed literal route, API, channel, module, string, or native export through a bounded cross-layer subgraph before native localization.",
+ },
{
tools: [
"analyze_function",
@@ -179,6 +188,15 @@ export const PROMPT_CONTRACTS = [
instruction:
"Inventory each target independently before extraction. Follow nodes, occurrences, and edges to completion and retain every Evidence page for each manifest.",
},
+ {
+ tools: [
+ "analyze_javascript_application",
+ "reconcile_javascript_runtime",
+ "compare_application_versions",
+ ],
+ instruction:
+ "For JavaScript/Electron versions, reconstruct each approved artifact independently, optionally reconcile separately retained passive runtime Evidence, then compare authenticated graphs with unique-only identity tiers. Keep ambiguous and incomplete matches unknown.",
+ },
{
tools: ["export_evidence_bundle", "compare_artifacts"],
instruction:
diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.ts
index e71312e80..3481eaf6d 100644
--- a/src/contracts/toolContractTypes.ts
+++ b/src/contracts/toolContractTypes.ts
@@ -24,6 +24,7 @@ export type ToolKind =
| "artifact-provider"
| "browser-provider"
| "electron-provider"
+ | "application"
| "session";
/** Single source of truth for a public MCP tool. */
diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts
index cedf50b7a..30832c5d5 100644
--- a/src/contracts/toolContracts.ts
+++ b/src/contracts/toolContracts.ts
@@ -28,6 +28,7 @@ import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "./browserToolContracts.js";
import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
+import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
import {
closeBinaryInputSchema,
openBinaryInputSchema,
@@ -526,5 +527,6 @@ export const TOOL_CONTRACTS = [
...ARTIFACT_TOOL_CONTRACTS,
...BROWSER_TOOL_CONTRACTS,
...ELECTRON_TOOL_CONTRACTS,
+ ...APPLICATION_TOOL_CONTRACTS,
...SESSION_TOOL_CONTRACTS,
] as const;
diff --git a/src/domain/javascriptApplicationChangeGraph.ts b/src/domain/javascriptApplicationChangeGraph.ts
new file mode 100644
index 000000000..72c550fe0
--- /dev/null
+++ b/src/domain/javascriptApplicationChangeGraph.ts
@@ -0,0 +1,324 @@
+import {
+ compareCodePoints,
+ createJavaScriptApplicationEdge,
+ createJavaScriptApplicationGraph,
+ createJavaScriptApplicationNode,
+ type ApplicationEdge,
+ type ApplicationGraphEvidence,
+ type ApplicationNode,
+ type JavaScriptApplicationGraph,
+} from "./javascriptApplicationGraph.js";
+import type {
+ ApplicationVersionComparisonItem,
+ CompareApplicationVersionsInput,
+} from "./javascriptApplicationVersionComparisonSchemas.js";
+
+interface ChangeGraphInput {
+ readonly left: JavaScriptApplicationGraph;
+ readonly right: JavaScriptApplicationGraph;
+ readonly leftEvidenceId: string;
+ readonly rightEvidenceId: string;
+ readonly items: readonly ApplicationVersionComparisonItem[];
+ readonly omittedComparisonItems: number;
+ readonly limits: CompareApplicationVersionsInput["limits"];
+}
+
+/** Bounded cross-version graph and exact projection omission counts. */
+export interface ApplicationChangeGraphProjection {
+ readonly graph: JavaScriptApplicationGraph;
+ readonly omittedNodes: number;
+ readonly omittedEdges: number;
+ readonly omittedObservations: number;
+}
+
+/** Merge compared nodes and add inferred right-to-left changed_from edges. */
+export const buildJavaScriptApplicationChangeGraph = (
+ input: ChangeGraphInput,
+): ApplicationChangeGraphProjection => {
+ const allNodes = nodeCandidates(input);
+ const preferredRoots = uniqueSorted([
+ ...input.right.root_node_ids,
+ ...input.left.root_node_ids,
+ ]).filter((nodeId) => allNodes.has(nodeId));
+ const orderedNodeIds = uniqueSorted([
+ ...preferredRoots,
+ ...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
+ ...(right === null ? [] : [right]),
+ ...(left === null ? [] : [left]),
+ ]),
+ ]);
+ const retainedIds = orderedNodeIds.slice(0, input.limits.max_graph_nodes);
+ const retained = new Set(retainedIds);
+ const merged = mergeNodes(
+ retainedIds.flatMap((nodeId) => allNodes.get(nodeId) ?? []),
+ );
+ const sourceEdges = uniqueEdges([
+ ...input.left.edges,
+ ...input.right.edges,
+ ]).filter(
+ ({ source_node_id: source, target_node_id: target }) =>
+ retained.has(source) && retained.has(target),
+ );
+ const comparisonEdges = input.items.flatMap((item) =>
+ changedFromEdge(item, input, retained),
+ );
+ const candidateEdges = uniqueEdges([...sourceEdges, ...comparisonEdges]);
+ const edges = candidateEdges.slice(0, input.limits.max_graph_edges);
+ const omittedNodes = Math.max(0, orderedNodeIds.length - retainedIds.length);
+ const omittedEdges = Math.max(0, candidateEdges.length - edges.length);
+ const graphOmissions =
+ omittedNodes + omittedEdges + merged.omittedObservations;
+ const rootNodeIds = preferredRoots
+ .filter((nodeId) => retained.has(nodeId))
+ .slice(0, 1_000);
+ const fallbackRoot = merged.nodes[0]?.node_id;
+ const graph = createJavaScriptApplicationGraph({
+ schema: "JavaScriptApplicationGraph",
+ schema_version: 1,
+ root_node_ids:
+ rootNodeIds.length > 0
+ ? rootNodeIds
+ : fallbackRoot === undefined
+ ? []
+ : [fallbackRoot],
+ nodes: merged.nodes,
+ edges,
+ coverage: changeGraphCoverage(input, graphOmissions),
+ limitations: uniqueSorted([
+ ...input.left.limitations.map((value) => `Left: ${value}`),
+ ...input.right.limitations.map((value) => `Right: ${value}`),
+ "changed_from edges are cross-version inferences and never promote structural or semantic matches to exact identity.",
+ "The change graph contains compared entities and their retained relationships; it is not an executable application.",
+ ...(graphOmissions === 0
+ ? []
+ : ["The change graph omitted content at explicit caller bounds."]),
+ ]),
+ });
+ return {
+ graph,
+ omittedNodes,
+ omittedEdges,
+ omittedObservations: merged.omittedObservations,
+ };
+};
+
+const nodeCandidates = (
+ input: ChangeGraphInput,
+): Map => {
+ const required = new Set([
+ ...input.left.root_node_ids,
+ ...input.right.root_node_ids,
+ ...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
+ ...(left === null ? [] : [left]),
+ ...(right === null ? [] : [right]),
+ ]),
+ ]);
+ const output = new Map();
+ for (const node of [...input.left.nodes, ...input.right.nodes])
+ if (required.has(node.node_id))
+ output.set(node.node_id, [...(output.get(node.node_id) ?? []), node]);
+ return output;
+};
+
+const changedFromEdge = (
+ item: ApplicationVersionComparisonItem,
+ input: ChangeGraphInput,
+ retained: ReadonlySet,
+): ApplicationEdge[] => {
+ const left = item.left_node_id;
+ const right = item.right_node_id;
+ if (
+ item.match.status !== "matched" ||
+ item.status === "unchanged" ||
+ left === null ||
+ right === null ||
+ left === right ||
+ !retained.has(left) ||
+ !retained.has(right)
+ )
+ return [];
+ const evidence = comparisonEvidence(item, input);
+ return [
+ createJavaScriptApplicationEdge({
+ source_node_id: right,
+ target_node_id: left,
+ relation: "changed_from",
+ properties: {
+ comparison_item_id: item.item_id,
+ status: item.status,
+ match_basis: item.match.basis,
+ match_confidence: item.match.confidence,
+ dimensions: item.dimensions,
+ },
+ evidence,
+ }),
+ ];
+};
+
+const comparisonEvidence = (
+ item: ApplicationVersionComparisonItem,
+ input: ChangeGraphInput,
+): ApplicationGraphEvidence => {
+ const right = input.right.nodes.find(
+ ({ node_id: id }) => id === item.right_node_id,
+ );
+ const left = input.left.nodes.find(
+ ({ node_id: id }) => id === item.left_node_id,
+ );
+ const source =
+ right?.observations[0]?.evidence ?? left?.observations[0]?.evidence;
+ const complete =
+ input.left.coverage.status === "complete" &&
+ input.right.coverage.status === "complete" &&
+ input.omittedComparisonItems === 0;
+ return {
+ authority: "cross-version-comparison",
+ state: "inferred",
+ confidence: item.match.confidence === "medium" ? "medium" : "high",
+ artifact: source?.artifact ?? {
+ available: false,
+ reason: "unresolved",
+ detail: "Compared node has no artifact-backed observation.",
+ },
+ location: source?.location ?? {
+ available: false,
+ reason: "unresolved",
+ detail: "Compared node has no actionable source location.",
+ },
+ extractor: {
+ name: "rea-application-version-comparison",
+ version: "1",
+ operation: "compare_application_versions",
+ executable_sha256: null,
+ },
+ coverage: complete
+ ? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
+ : {
+ status: "partial",
+ truncated: input.omittedComparisonItems > 0,
+ omitted_count:
+ input.omittedComparisonItems > 0
+ ? input.omittedComparisonItems
+ : (source?.coverage.omitted_count ?? null),
+ limits:
+ input.omittedComparisonItems > 0
+ ? [
+ {
+ name: "max-comparison-items",
+ value: input.limits.max_comparison_items,
+ unit: "items",
+ },
+ ]
+ : [],
+ },
+ limitations: [
+ "Cross-version pairing is inferred from the stated match basis; changed_from does not prove runtime reachability.",
+ ...item.limitations,
+ ],
+ evidence_ids: [input.leftEvidenceId, input.rightEvidenceId],
+ };
+};
+
+const changeGraphCoverage = (
+ input: ChangeGraphInput,
+ graphOmissions: number,
+): JavaScriptApplicationGraph["coverage"] => {
+ const outputOmissions = graphOmissions + input.omittedComparisonItems;
+ if (outputOmissions > 0)
+ return {
+ status: "partial",
+ truncated: true,
+ omitted_count: outputOmissions,
+ limits: [
+ {
+ name: "max-comparison-items",
+ value: input.limits.max_comparison_items,
+ unit: "items",
+ },
+ {
+ name: "max-graph-nodes",
+ value: input.limits.max_graph_nodes,
+ unit: "items",
+ },
+ {
+ name: "max-graph-edges",
+ value: input.limits.max_graph_edges,
+ unit: "items",
+ },
+ ],
+ };
+ if (
+ input.left.coverage.status === "complete" &&
+ input.right.coverage.status === "complete"
+ )
+ return {
+ status: "complete",
+ truncated: false,
+ omitted_count: 0,
+ limits: [],
+ };
+ const counts = [
+ input.left.coverage.omitted_count,
+ input.right.coverage.omitted_count,
+ ];
+ return {
+ status: "partial",
+ truncated: false,
+ omitted_count: counts.every((value) => value !== null)
+ ? counts.reduce((total, value) => total + (value ?? 0), 0)
+ : null,
+ limits: [],
+ };
+};
+
+const mergeNodes = (
+ nodes: readonly ApplicationNode[],
+): {
+ readonly nodes: ApplicationNode[];
+ readonly omittedObservations: number;
+} => {
+ const groups = new Map();
+ for (const node of nodes)
+ groups.set(node.node_id, [...(groups.get(node.node_id) ?? []), node]);
+ let omittedObservations = 0;
+ const merged = [...groups.values()].map((group) => {
+ const first = group[0];
+ if (first === undefined)
+ throw new TypeError("Empty change-graph node group");
+ const observations = [
+ ...new Map(
+ group
+ .flatMap(({ observations: values }) => values)
+ .map((observation) => [observation.observation_id, observation]),
+ ).values(),
+ ].sort((left, right) =>
+ compareCodePoints(left.observation_id, right.observation_id),
+ );
+ omittedObservations += Math.max(0, observations.length - 64);
+ return createJavaScriptApplicationNode({
+ kind: first.kind,
+ identity: first.identity,
+ observations: observations
+ .slice(0, 64)
+ .map(
+ ({ observation_id: _id, identifier_strategy: _strategy, ...value }) =>
+ value,
+ ),
+ });
+ });
+ return {
+ nodes: merged.sort((left, right) =>
+ compareCodePoints(left.node_id, right.node_id),
+ ),
+ omittedObservations,
+ };
+};
+
+const uniqueEdges = (edges: readonly ApplicationEdge[]): ApplicationEdge[] =>
+ [...new Map(edges.map((edge) => [edge.edge_id, edge])).values()].sort(
+ (left, right) => compareCodePoints(left.edge_id, right.edge_id),
+ );
+
+const uniqueSorted = (
+ values: readonly Value[],
+): Value[] => [...new Set(values)].sort(compareCodePoints);
diff --git a/src/domain/javascriptApplicationEvidenceSchemas.ts b/src/domain/javascriptApplicationEvidenceSchemas.ts
index 1cfd0db5a..cda8d6fea 100644
--- a/src/domain/javascriptApplicationEvidenceSchemas.ts
+++ b/src/domain/javascriptApplicationEvidenceSchemas.ts
@@ -24,6 +24,7 @@ const applicationEvidenceAuthoritySchema = z.enum([
"static-relationship-inference",
"passive-cdp-runtime",
"cross-layer-reconciliation",
+ "cross-version-comparison",
"controlled-replay",
"native-analysis-provider",
"historical-reference",
@@ -269,6 +270,15 @@ const checkAuthorityState = (
path: ["state"],
message: "Cross-layer reconciliation authority must remain inferred",
});
+ if (
+ evidence.authority === "cross-version-comparison" &&
+ evidence.state !== "inferred"
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["state"],
+ message: "Cross-version comparison authority must remain inferred",
+ });
if (
evidence.authority === "unknown" &&
!["unknown", "unavailable"].includes(evidence.state)
diff --git a/src/domain/javascriptApplicationVersionComparison.ts b/src/domain/javascriptApplicationVersionComparison.ts
new file mode 100644
index 000000000..1576d4234
--- /dev/null
+++ b/src/domain/javascriptApplicationVersionComparison.ts
@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+
+import canonicalize from "canonicalize";
+
+import type { Evidence } from "./evidence.js";
+import { buildJavaScriptApplicationChangeGraph } from "./javascriptApplicationChangeGraph.js";
+import {
+ applicationVersionComparisonResultSchema,
+ type ApplicationVersionComparisonResult,
+ type CompareApplicationVersionsInput,
+} from "./javascriptApplicationVersionComparisonSchemas.js";
+import type { JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js";
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { classifyJavaScriptApplicationVersions } from "./javascriptApplicationVersionItems.js";
+import { matchJavaScriptApplicationVersions } from "./javascriptApplicationVersionKeys.js";
+
+/** Pure inputs after application-layer Evidence authentication. */
+export interface ApplicationVersionComparisonProjectionInput {
+ readonly left: {
+ readonly evidenceId: string;
+ readonly rootArtifactSha256: string;
+ readonly graph: JavaScriptApplicationGraph;
+ };
+ readonly right: {
+ readonly evidenceId: string;
+ readonly rootArtifactSha256: string;
+ readonly graph: JavaScriptApplicationGraph;
+ };
+ readonly leftNativeEvidence: readonly Evidence[];
+ readonly rightNativeEvidence: readonly Evidence[];
+ readonly limits: CompareApplicationVersionsInput["limits"];
+}
+
+/** Compare application entities with ordered unique-only identity tiers. */
+export const compareJavaScriptApplicationVersions = (
+ input: ApplicationVersionComparisonProjectionInput,
+): ApplicationVersionComparisonResult => {
+ const matching = matchJavaScriptApplicationVersions(
+ input.left.graph.nodes,
+ input.right.graph.nodes,
+ );
+ const projection = classifyJavaScriptApplicationVersions(matching, {
+ leftGraph: input.left.graph,
+ rightGraph: input.right.graph,
+ leftEvidenceId: input.left.evidenceId,
+ rightEvidenceId: input.right.evidenceId,
+ leftNativeEvidence: input.leftNativeEvidence,
+ rightNativeEvidence: input.rightNativeEvidence,
+ maxCandidates: input.limits.max_candidate_nodes,
+ });
+ const items = projection.items.slice(0, input.limits.max_comparison_items);
+ const omittedComparisonItems = projection.items.length - items.length;
+ const changeGraph = buildJavaScriptApplicationChangeGraph({
+ left: input.left.graph,
+ right: input.right.graph,
+ leftEvidenceId: input.left.evidenceId,
+ rightEvidenceId: input.right.evidenceId,
+ items,
+ omittedComparisonItems,
+ limits: input.limits,
+ });
+ const evidenceLinks = uniqueSorted(
+ projection.items.flatMap(({ evidence_links: links }) => links),
+ );
+ const omissions = {
+ omitted_comparison_items: omittedComparisonItems,
+ omitted_candidate_references: projection.omittedCandidateReferences,
+ omitted_graph_nodes: changeGraph.omittedNodes,
+ omitted_graph_edges: changeGraph.omittedEdges,
+ omitted_graph_observations: changeGraph.omittedObservations,
+ };
+ const semantic = {
+ schema_version: 1 as const,
+ left: {
+ evidence_id: input.left.evidenceId,
+ graph_id: input.left.graph.graph_id,
+ root_artifact_sha256: input.left.rootArtifactSha256,
+ },
+ right: {
+ evidence_id: input.right.evidenceId,
+ graph_id: input.right.graph.graph_id,
+ root_artifact_sha256: input.right.rootArtifactSha256,
+ },
+ summary: summary(projection.items),
+ matching: matchingSummary(projection.items),
+ items,
+ graph: changeGraph.graph,
+ coverage: {
+ status: comparisonCoverageStatus(input, omissions),
+ left_graph_status: input.left.graph.coverage.status,
+ right_graph_status: input.right.graph.coverage.status,
+ ...omissions,
+ },
+ evidence_links: evidenceLinks,
+ limitations: comparisonLimitations(input, omissions),
+ };
+ return applicationVersionComparisonResultSchema.parse({
+ ...semantic,
+ comparison_id: `javc_${digestCanonical(semantic)}`,
+ });
+};
+
+const summary = (
+ items: readonly ApplicationVersionComparisonResult["items"][number][],
+): ApplicationVersionComparisonResult["summary"] => ({
+ unchanged: countStatus(items, "unchanged"),
+ added: countStatus(items, "added"),
+ removed: countStatus(items, "removed"),
+ changed: countStatus(items, "changed"),
+ unknown: countStatus(items, "unknown"),
+});
+
+const countStatus = (
+ items: readonly ApplicationVersionComparisonResult["items"][number][],
+ status: ApplicationVersionComparisonResult["items"][number]["status"],
+): number => items.filter((item) => item.status === status).length;
+
+const matchingSummary = (
+ items: readonly ApplicationVersionComparisonResult["items"][number][],
+): ApplicationVersionComparisonResult["matching"] => ({
+ exact_node_identity: countBasis(items, "exact-node-identity"),
+ exact_content_digest: countBasis(items, "exact-content-digest"),
+ exact_module_source_digest: countBasis(items, "exact-module-source-digest"),
+ source_map_identity: countBasis(items, "source-map-identity"),
+ structural_fingerprint: countBasis(items, "structural-fingerprint"),
+ semantic_key: countBasis(items, "semantic-key"),
+ ambiguous: items.filter(({ match }) => match.status === "ambiguous").length,
+ unmatched: items.filter(({ match }) => match.status === "unmatched").length,
+});
+
+const countBasis = (
+ items: readonly ApplicationVersionComparisonResult["items"][number][],
+ basis: ApplicationVersionComparisonResult["items"][number]["match"]["basis"],
+): number => items.filter(({ match }) => match.basis === basis).length;
+
+type ComparisonOmissions = ApplicationVersionComparisonResult["coverage"];
+
+const comparisonCoverageStatus = (
+ input: ApplicationVersionComparisonProjectionInput,
+ omissions: Omit<
+ ComparisonOmissions,
+ "status" | "left_graph_status" | "right_graph_status"
+ >,
+): ApplicationVersionComparisonResult["coverage"]["status"] =>
+ Object.values(omissions).some((value) => value > 0)
+ ? "truncated"
+ : input.left.graph.coverage.status === "complete" &&
+ input.right.graph.coverage.status === "complete"
+ ? "complete-within-inputs"
+ : "partial";
+
+const comparisonLimitations = (
+ input: ApplicationVersionComparisonProjectionInput,
+ omissions: Omit<
+ ComparisonOmissions,
+ "status" | "left_graph_status" | "right_graph_status"
+ >,
+): string[] =>
+ uniqueSorted([
+ "Application comparison never uses bundler module ordinals as persistent identity and performs no fuzzy pairing.",
+ "Exact digest equality proves byte identity only; source-map, structural-fingerprint, and semantic-key matches retain inferred confidence.",
+ "Minified names and chunk locations are not assumed stable across versions.",
+ "The comparison reads retained graphs and Evidence only; it does not execute either application.",
+ "Native Evidence is linked only by exact subject digest; provider snapshot reuse remains target/provider/profile exact.",
+ ...(input.left.graph.coverage.status === "complete" &&
+ input.right.graph.coverage.status === "complete"
+ ? []
+ : [
+ "At least one source graph is incomplete; unmatched entities on the opposite side remain unknown rather than added or removed.",
+ ]),
+ ...(Object.values(omissions).some((value) => value > 0)
+ ? ["Comparison output was truncated at explicit caller limits."]
+ : []),
+ ]);
+
+const digestCanonical = (value: unknown): string => {
+ const encoded = canonicalize(value);
+ if (encoded === undefined)
+ throw new TypeError(
+ "Application version comparison could not canonicalize data",
+ );
+ return createHash("sha256").update(encoded).digest("hex");
+};
+
+const uniqueSorted = (
+ values: readonly Value[],
+): Value[] => [...new Set(values)].sort(compareCodePoints);
diff --git a/src/domain/javascriptApplicationVersionComparisonSchemas.ts b/src/domain/javascriptApplicationVersionComparisonSchemas.ts
new file mode 100644
index 000000000..96ab87ea0
--- /dev/null
+++ b/src/domain/javascriptApplicationVersionComparisonSchemas.ts
@@ -0,0 +1,161 @@
+import { z } from "zod";
+
+import { evidenceSchema } from "./evidence.js";
+import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
+import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "./javascriptApplicationGraphSchemas.js";
+
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
+const boundedTextSchema = z.string().min(1).max(4_096);
+
+const comparisonLimitsSchema = z.strictObject({
+ max_comparison_items: z.number().int().min(1).max(50_000).default(20_000),
+ max_candidate_nodes: z.number().int().min(1).max(1_000).default(100),
+ max_graph_nodes: z.number().int().min(1).max(100_000).default(20_000),
+ max_graph_edges: z.number().int().min(1).max(200_000).default(40_000),
+});
+
+/** Two authenticated application versions and deterministic output bounds. */
+export const compareApplicationVersionsInputSchema = z
+ .strictObject({
+ left: evidenceSchema,
+ right: evidenceSchema,
+ left_native_observations: z.array(evidenceSchema).max(64).default([]),
+ right_native_observations: z.array(evidenceSchema).max(64).default([]),
+ limits: comparisonLimitsSchema.default({
+ max_comparison_items: 20_000,
+ max_candidate_nodes: 100,
+ max_graph_nodes: 20_000,
+ max_graph_edges: 40_000,
+ }),
+ unknown_registry_approved: z.literal(true).optional(),
+ })
+ .superRefine((input, context) => {
+ if (input.left.evidence_id === input.right.evidence_id)
+ context.addIssue({
+ code: "custom",
+ path: ["right"],
+ message: "Application version Evidence must be distinct",
+ });
+ for (const side of [
+ "left_native_observations",
+ "right_native_observations",
+ ] as const) {
+ const ids = input[side].map(({ evidence_id: id }) => id);
+ if (new Set(ids).size !== ids.length)
+ context.addIssue({
+ code: "custom",
+ path: [side],
+ message: "Native observations must be unique on each side",
+ });
+ }
+ });
+
+const applicationVersionMatchBasisSchema = z.enum([
+ "exact-node-identity",
+ "exact-content-digest",
+ "exact-module-source-digest",
+ "source-map-identity",
+ "structural-fingerprint",
+ "semantic-key",
+ "none",
+]);
+
+const comparisonItemSchema = z.strictObject({
+ item_id: z.string().regex(/^javc_item_[a-f0-9]{64}$/u),
+ status: z.enum(["unchanged", "added", "removed", "changed", "unknown"]),
+ node_kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
+ left_node_id: nodeIdSchema.nullable(),
+ right_node_id: nodeIdSchema.nullable(),
+ match: z.strictObject({
+ status: z.enum(["matched", "unmatched", "ambiguous"]),
+ basis: applicationVersionMatchBasisSchema,
+ confidence: z.enum(["exact", "high", "medium", "unknown"]),
+ candidate_left_node_ids: z.array(nodeIdSchema).max(1_000),
+ candidate_right_node_ids: z.array(nodeIdSchema).max(1_000),
+ }),
+ dimensions: z
+ .array(
+ z.enum([
+ "content",
+ "location",
+ "properties",
+ "relationships",
+ "availability",
+ "coverage",
+ ]),
+ )
+ .max(6),
+ evidence_links: z.array(evidenceIdSchema).min(2).max(130),
+ limitations: z.array(boundedTextSchema).max(100),
+});
+
+/** Tiered module/entity matching plus a bounded cross-version change graph. */
+export const applicationVersionComparisonResultSchema = z.strictObject({
+ schema_version: z.literal(1),
+ comparison_id: z.string().regex(/^javc_[a-f0-9]{64}$/u),
+ left: z.strictObject({
+ evidence_id: evidenceIdSchema,
+ graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+ root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+ }),
+ right: z.strictObject({
+ evidence_id: evidenceIdSchema,
+ graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+ root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+ }),
+ summary: z.strictObject({
+ unchanged: z.number().int().min(0),
+ added: z.number().int().min(0),
+ removed: z.number().int().min(0),
+ changed: z.number().int().min(0),
+ unknown: z.number().int().min(0),
+ }),
+ matching: z.strictObject({
+ exact_node_identity: z.number().int().min(0),
+ exact_content_digest: z.number().int().min(0),
+ exact_module_source_digest: z.number().int().min(0),
+ source_map_identity: z.number().int().min(0),
+ structural_fingerprint: z.number().int().min(0),
+ semantic_key: z.number().int().min(0),
+ ambiguous: z.number().int().min(0),
+ unmatched: z.number().int().min(0),
+ }),
+ items: z.array(comparisonItemSchema).max(50_000),
+ graph: javascriptApplicationGraphSchema,
+ coverage: z.strictObject({
+ status: z.enum(["complete-within-inputs", "partial", "truncated"]),
+ left_graph_status: z.enum([
+ "complete",
+ "partial",
+ "unknown",
+ "unavailable",
+ ]),
+ right_graph_status: z.enum([
+ "complete",
+ "partial",
+ "unknown",
+ "unavailable",
+ ]),
+ omitted_comparison_items: z.number().int().min(0),
+ omitted_candidate_references: z.number().int().min(0),
+ omitted_graph_nodes: z.number().int().min(0),
+ omitted_graph_edges: z.number().int().min(0),
+ omitted_graph_observations: z.number().int().min(0),
+ }),
+ evidence_links: z.array(evidenceIdSchema).min(2).max(130),
+ limitations: z.array(boundedTextSchema).max(1_000),
+});
+
+export type CompareApplicationVersionsInput = z.infer<
+ typeof compareApplicationVersionsInputSchema
+>;
+export type ApplicationVersionComparisonItem = z.infer<
+ typeof comparisonItemSchema
+>;
+export type ApplicationVersionComparisonResult = z.infer<
+ typeof applicationVersionComparisonResultSchema
+>;
+export type ApplicationVersionMatchBasis = z.infer<
+ typeof applicationVersionMatchBasisSchema
+>;
diff --git a/src/domain/javascriptApplicationVersionItems.ts b/src/domain/javascriptApplicationVersionItems.ts
new file mode 100644
index 000000000..07db36faa
--- /dev/null
+++ b/src/domain/javascriptApplicationVersionItems.ts
@@ -0,0 +1,371 @@
+import { createHash } from "node:crypto";
+
+import canonicalize from "canonicalize";
+
+import type { Evidence } from "./evidence.js";
+import {
+ compareCodePoints,
+ type ApplicationEdge,
+ type ApplicationNode,
+ type JavaScriptApplicationGraph,
+} from "./javascriptApplicationGraph.js";
+import type {
+ ApplicationVersionComparisonItem,
+ CompareApplicationVersionsInput,
+} from "./javascriptApplicationVersionComparisonSchemas.js";
+import type {
+ ApplicationVersionMatchingProjection,
+ ApplicationVersionNodePair,
+} from "./javascriptApplicationVersionKeys.js";
+
+/** All classified entities before the caller's item bound is applied. */
+export interface ApplicationVersionItemProjection {
+ readonly items: ApplicationVersionComparisonItem[];
+ readonly omittedCandidateReferences: number;
+}
+
+interface ItemContext {
+ readonly leftGraph: JavaScriptApplicationGraph;
+ readonly rightGraph: JavaScriptApplicationGraph;
+ readonly leftEvidenceId: string;
+ readonly rightEvidenceId: string;
+ readonly leftNativeEvidence: readonly Evidence[];
+ readonly rightNativeEvidence: readonly Evidence[];
+ readonly pairByLeft: ReadonlyMap;
+ readonly pairByRight: ReadonlyMap;
+ readonly maxCandidates: number;
+}
+
+/** Classify matched, unmatched, and ambiguous nodes without inventing absence. */
+export const classifyJavaScriptApplicationVersions = (
+ matching: ApplicationVersionMatchingProjection,
+ context: Omit & {
+ readonly maxCandidates: CompareApplicationVersionsInput["limits"]["max_candidate_nodes"];
+ },
+): ApplicationVersionItemProjection => {
+ const pairByLeft = new Map(
+ matching.pairs.map(({ left, right }) => [
+ left.node_id,
+ `pair:${left.node_id}:${right.node_id}`,
+ ]),
+ );
+ const pairByRight = new Map(
+ matching.pairs.map(({ left, right }) => [
+ right.node_id,
+ `pair:${left.node_id}:${right.node_id}`,
+ ]),
+ );
+ const fullContext: ItemContext = { ...context, pairByLeft, pairByRight };
+ let omittedCandidateReferences = 0;
+ const leftItems = matching.unmatchedLeft.map((node) => {
+ const candidates = matching.candidatesForLeft.get(node.node_id) ?? [];
+ omittedCandidateReferences += Math.max(
+ 0,
+ candidates.length - context.maxCandidates,
+ );
+ return unmatchedItem(
+ node,
+ "left",
+ candidates.slice(0, context.maxCandidates),
+ fullContext,
+ );
+ });
+ const rightItems = matching.unmatchedRight.map((node) => {
+ const candidates = matching.candidatesForRight.get(node.node_id) ?? [];
+ omittedCandidateReferences += Math.max(
+ 0,
+ candidates.length - context.maxCandidates,
+ );
+ return unmatchedItem(
+ node,
+ "right",
+ candidates.slice(0, context.maxCandidates),
+ fullContext,
+ );
+ });
+ return {
+ items: [
+ ...matching.pairs.map((pair) => matchedItem(pair, fullContext)),
+ ...leftItems,
+ ...rightItems,
+ ].sort((left, right) => compareCodePoints(left.item_id, right.item_id)),
+ omittedCandidateReferences,
+ };
+};
+
+const matchedItem = (
+ pair: ApplicationVersionNodePair,
+ context: ItemContext,
+): ApplicationVersionComparisonItem => {
+ const dimensions = changedDimensions(pair, context);
+ const complete = graphsComplete(context);
+ const observedChange = dimensions.some((dimension) =>
+ ["content", "location", "properties"].includes(dimension),
+ );
+ const status: ApplicationVersionComparisonItem["status"] =
+ observedChange || (complete && dimensions.length > 0)
+ ? "changed"
+ : complete
+ ? "unchanged"
+ : "unknown";
+ const finalDimensions =
+ status === "unknown" && !dimensions.includes("coverage")
+ ? [...dimensions, "coverage" as const]
+ : dimensions;
+ const semantic = {
+ status,
+ node_kind: pair.left.kind,
+ left_node_id: pair.left.node_id,
+ right_node_id: pair.right.node_id,
+ match: {
+ status: "matched" as const,
+ basis: pair.basis,
+ confidence: pair.confidence,
+ candidate_left_node_ids: [],
+ candidate_right_node_ids: [],
+ },
+ dimensions: finalDimensions,
+ evidence_links: itemEvidenceLinks(pair.left, pair.right, context),
+ limitations: pairLimitations(pair, status),
+ };
+ return itemWithId(semantic);
+};
+
+const unmatchedItem = (
+ node: ApplicationNode,
+ side: "left" | "right",
+ candidates: readonly string[],
+ context: ItemContext,
+): ApplicationVersionComparisonItem => {
+ const ambiguous = candidates.length > 0;
+ const oppositeComplete =
+ (side === "left" ? context.rightGraph : context.leftGraph).coverage
+ .status === "complete";
+ const status: ApplicationVersionComparisonItem["status"] = ambiguous
+ ? "unknown"
+ : oppositeComplete
+ ? side === "left"
+ ? "removed"
+ : "added"
+ : "unknown";
+ const semantic = {
+ status,
+ node_kind: node.kind,
+ left_node_id: side === "left" ? node.node_id : null,
+ right_node_id: side === "right" ? node.node_id : null,
+ match: {
+ status: ambiguous ? ("ambiguous" as const) : ("unmatched" as const),
+ basis: "none" as const,
+ confidence: "unknown" as const,
+ candidate_left_node_ids: side === "right" ? [...candidates] : [],
+ candidate_right_node_ids: side === "left" ? [...candidates] : [],
+ },
+ dimensions: [
+ "availability" as const,
+ ...(status === "unknown" && !ambiguous ? (["coverage"] as const) : []),
+ ],
+ evidence_links: itemEvidenceLinks(
+ side === "left" ? node : undefined,
+ side === "right" ? node : undefined,
+ context,
+ ),
+ limitations: [
+ ...(ambiguous
+ ? [
+ "Multiple nodes share the same permitted match key; no cross-version pair was selected.",
+ ]
+ : []),
+ ...(status === "unknown" && !ambiguous
+ ? [
+ "The opposite graph is incomplete, so an unmatched node cannot be classified as added or removed.",
+ ]
+ : []),
+ ],
+ };
+ return itemWithId(semantic);
+};
+
+const changedDimensions = (
+ pair: ApplicationVersionNodePair,
+ context: ItemContext,
+): ApplicationVersionComparisonItem["dimensions"] => {
+ const dimensions: ApplicationVersionComparisonItem["dimensions"] = [];
+ const leftContent = contentIdentity(pair.left);
+ const rightContent = contentIdentity(pair.right);
+ if (
+ leftContent !== null &&
+ rightContent !== null &&
+ leftContent !== rightContent
+ )
+ dimensions.push("content");
+ if (canonical(locations(pair.left)) !== canonical(locations(pair.right)))
+ dimensions.push("location");
+ if (canonical(properties(pair.left)) !== canonical(properties(pair.right)))
+ dimensions.push("properties");
+ if (
+ relationshipSignature(pair.left, "left", context) !==
+ relationshipSignature(pair.right, "right", context)
+ )
+ dimensions.push("relationships");
+ return dimensions;
+};
+
+const contentIdentity = (node: ApplicationNode): string | null => {
+ if (node.identity.strategy === "content-digest")
+ return `content:${node.identity.sha256}`;
+ if (node.kind === "javascript-module")
+ return stringProperty(node, "source_sha256");
+ if (
+ node.kind === "source-module" &&
+ node.identity.strategy === "source-map-original"
+ )
+ return node.identity.source_sha256;
+ return null;
+};
+
+const locations = (node: ApplicationNode) =>
+ node.observations
+ .map(({ evidence }) =>
+ evidence.location.available ? evidence.location.value : evidence.location,
+ )
+ .sort((left, right) =>
+ compareCodePoints(canonical(left), canonical(right)),
+ );
+
+const properties = (node: ApplicationNode) =>
+ node.observations
+ .map(({ label, properties: values }) => ({ label, properties: values }))
+ .sort((left, right) =>
+ compareCodePoints(canonical(left), canonical(right)),
+ );
+
+const relationshipSignature = (
+ node: ApplicationNode,
+ side: "left" | "right",
+ context: ItemContext,
+): string => {
+ const graph = side === "left" ? context.leftGraph : context.rightGraph;
+ const paired = side === "left" ? context.pairByLeft : context.pairByRight;
+ const nodeById = new Map(graph.nodes.map((value) => [value.node_id, value]));
+ const signatures = graph.edges.flatMap((edge) => {
+ if (edge.source_node_id === node.node_id)
+ return [
+ edgeSignature(
+ "out",
+ edge.relation,
+ edge.target_node_id,
+ paired,
+ nodeById,
+ ),
+ ];
+ if (edge.target_node_id === node.node_id)
+ return [
+ edgeSignature(
+ "in",
+ edge.relation,
+ edge.source_node_id,
+ paired,
+ nodeById,
+ ),
+ ];
+ return [];
+ });
+ return canonical(signatures.sort(compareCodePoints));
+};
+
+const edgeSignature = (
+ direction: "in" | "out",
+ relation: ApplicationEdge["relation"],
+ neighborId: string,
+ paired: ReadonlyMap,
+ nodeById: ReadonlyMap,
+): string => {
+ const mapped = paired.get(neighborId);
+ const neighbor = nodeById.get(neighborId);
+ return `${direction}\0${relation}\0${mapped ?? `unmatched:${neighbor?.kind ?? "unknown"}`}`;
+};
+
+const itemEvidenceLinks = (
+ left: ApplicationNode | undefined,
+ right: ApplicationNode | undefined,
+ context: ItemContext,
+): string[] =>
+ [
+ ...new Set([
+ context.leftEvidenceId,
+ context.rightEvidenceId,
+ ...nativeLinks(left, context.leftNativeEvidence),
+ ...nativeLinks(right, context.rightNativeEvidence),
+ ]),
+ ].sort(compareCodePoints);
+
+const nativeLinks = (
+ node: ApplicationNode | undefined,
+ evidence: readonly Evidence[],
+): string[] => {
+ const digest =
+ node === undefined
+ ? null
+ : contentIdentity(node)?.replace(/^content:/u, "");
+ return digest === null
+ ? []
+ : evidence
+ .filter(({ subject }) => subject?.digest.sha256 === digest)
+ .map(({ evidence_id: id }) => id);
+};
+
+const pairLimitations = (
+ pair: ApplicationVersionNodePair,
+ status: ApplicationVersionComparisonItem["status"],
+): string[] => [
+ ...(pair.basis === "structural-fingerprint"
+ ? [
+ "Structural fingerprint equality is rename-resistant inference; it is not byte identity or proof of semantic equivalence.",
+ ]
+ : []),
+ ...(pair.basis === "source-map-identity"
+ ? [
+ "Source-map original names identify a candidate source lineage; changed or unavailable source content remains explicit.",
+ ]
+ : []),
+ ...(pair.basis === "semantic-key"
+ ? [
+ "Semantic-key pairing is a deterministic inference and is never promoted to exact identity.",
+ ]
+ : []),
+ ...(status === "unknown"
+ ? ["Incomplete graph coverage prevents a complete node-level conclusion."]
+ : []),
+];
+
+const itemWithId = (
+ semantic: Omit,
+): ApplicationVersionComparisonItem => ({
+ ...semantic,
+ item_id: `javc_item_${digestCanonical(semantic)}`,
+});
+
+const stringProperty = (node: ApplicationNode, key: string): string | null => {
+ const values = [
+ ...new Set(
+ node.observations
+ .map(({ properties: values }) => values[key])
+ .filter((value): value is string => typeof value === "string"),
+ ),
+ ];
+ return values.length === 1 ? (values[0] ?? null) : null;
+};
+
+const graphsComplete = (context: ItemContext): boolean =>
+ context.leftGraph.coverage.status === "complete" &&
+ context.rightGraph.coverage.status === "complete";
+
+const canonical = (value: unknown): string => {
+ const encoded = canonicalize(value);
+ if (encoded === undefined)
+ throw new TypeError("Application version item could not canonicalize data");
+ return encoded;
+};
+
+const digestCanonical = (value: unknown): string =>
+ createHash("sha256").update(canonical(value)).digest("hex");
diff --git a/src/domain/javascriptApplicationVersionKeys.ts b/src/domain/javascriptApplicationVersionKeys.ts
new file mode 100644
index 000000000..6ad5475ac
--- /dev/null
+++ b/src/domain/javascriptApplicationVersionKeys.ts
@@ -0,0 +1,273 @@
+import type { ApplicationNode } from "./javascriptApplicationGraph.js";
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import type { ApplicationVersionMatchBasis } from "./javascriptApplicationVersionComparisonSchemas.js";
+import type { JsonValue } from "./jsonValue.js";
+
+/** One deterministic one-to-one match between two graph versions. */
+export interface ApplicationVersionNodePair {
+ readonly left: ApplicationNode;
+ readonly right: ApplicationNode;
+ readonly basis: Exclude;
+ readonly confidence: "exact" | "high" | "medium";
+}
+
+/** Matched nodes plus ambiguity candidates that were never forced into pairs. */
+export interface ApplicationVersionMatchingProjection {
+ readonly pairs: ApplicationVersionNodePair[];
+ readonly unmatchedLeft: ApplicationNode[];
+ readonly unmatchedRight: ApplicationNode[];
+ readonly candidatesForLeft: ReadonlyMap;
+ readonly candidatesForRight: ReadonlyMap;
+}
+
+interface MatchTier {
+ readonly basis: ApplicationVersionNodePair["basis"];
+ readonly confidence: ApplicationVersionNodePair["confidence"];
+ readonly key: (node: ApplicationNode) => string | null;
+}
+
+const matchTiers = (): readonly MatchTier[] => [
+ { basis: "exact-content-digest", confidence: "exact", key: contentDigestKey },
+ {
+ basis: "exact-module-source-digest",
+ confidence: "exact",
+ key: moduleSourceDigestKey,
+ },
+ { basis: "exact-node-identity", confidence: "exact", key: nodeIdentityKey },
+ { basis: "source-map-identity", confidence: "high", key: sourceMapKey },
+ {
+ basis: "structural-fingerprint",
+ confidence: "medium",
+ key: structuralFingerprintKey,
+ },
+ { basis: "semantic-key", confidence: "medium", key: semanticKey },
+];
+
+/** Apply ordered, unique-only matching tiers without fuzzy pairing. */
+export const matchJavaScriptApplicationVersions = (
+ leftNodes: readonly ApplicationNode[],
+ rightNodes: readonly ApplicationNode[],
+): ApplicationVersionMatchingProjection => {
+ const left = new Map(leftNodes.map((node) => [node.node_id, node]));
+ const right = new Map(rightNodes.map((node) => [node.node_id, node]));
+ const leftCandidates = new Map>();
+ const rightCandidates = new Map>();
+ const pairs: ApplicationVersionNodePair[] = [];
+ for (const tier of matchTiers())
+ applyTier(left, right, pairs, leftCandidates, rightCandidates, tier);
+ const remainingLeft = sortedNodes(left.values());
+ const remainingRight = sortedNodes(right.values());
+ const leftIds = new Set(remainingLeft.map(({ node_id: id }) => id));
+ const rightIds = new Set(remainingRight.map(({ node_id: id }) => id));
+ return {
+ pairs: pairs.sort((a, b) =>
+ compareCodePoints(
+ `${a.left.node_id}\0${a.right.node_id}`,
+ `${b.left.node_id}\0${b.right.node_id}`,
+ ),
+ ),
+ unmatchedLeft: remainingLeft,
+ unmatchedRight: remainingRight,
+ candidatesForLeft: filteredCandidates(leftCandidates, rightIds),
+ candidatesForRight: filteredCandidates(rightCandidates, leftIds),
+ };
+};
+
+const applyTier = (
+ left: Map,
+ right: Map,
+ pairs: ApplicationVersionNodePair[],
+ leftCandidates: Map>,
+ rightCandidates: Map>,
+ tier: MatchTier,
+): void => {
+ const leftByKey = nodesByKey(left.values(), tier.key);
+ const rightByKey = nodesByKey(right.values(), tier.key);
+ for (const key of [...leftByKey.keys()].sort(compareCodePoints)) {
+ const leftGroup = leftByKey.get(key) ?? [];
+ const rightGroup = rightByKey.get(key) ?? [];
+ if (rightGroup.length === 0) continue;
+ recordCandidates(leftGroup, rightGroup, leftCandidates, rightCandidates);
+ if (leftGroup.length !== 1 || rightGroup.length !== 1) continue;
+ const leftNode = leftGroup[0];
+ const rightNode = rightGroup[0];
+ if (leftNode === undefined || rightNode === undefined) continue;
+ pairs.push({ left: leftNode, right: rightNode, ...tier });
+ left.delete(leftNode.node_id);
+ right.delete(rightNode.node_id);
+ }
+};
+
+const nodesByKey = (
+ nodes: Iterable,
+ keyFor: (node: ApplicationNode) => string | null,
+): Map => {
+ const output = new Map();
+ for (const node of nodes) {
+ const key = keyFor(node);
+ if (key === null) continue;
+ output.set(key, [...(output.get(key) ?? []), node]);
+ }
+ return output;
+};
+
+const recordCandidates = (
+ left: readonly ApplicationNode[],
+ right: readonly ApplicationNode[],
+ leftCandidates: Map>,
+ rightCandidates: Map>,
+): void => {
+ for (const leftNode of left) {
+ const candidates =
+ leftCandidates.get(leftNode.node_id) ?? new Set();
+ for (const rightNode of right) candidates.add(rightNode.node_id);
+ leftCandidates.set(leftNode.node_id, candidates);
+ }
+ for (const rightNode of right) {
+ const candidates =
+ rightCandidates.get(rightNode.node_id) ?? new Set();
+ for (const leftNode of left) candidates.add(leftNode.node_id);
+ rightCandidates.set(rightNode.node_id, candidates);
+ }
+};
+
+const filteredCandidates = (
+ candidates: ReadonlyMap>,
+ retained: ReadonlySet,
+): ReadonlyMap =>
+ new Map(
+ [...candidates.entries()].flatMap(([nodeId, values]) => {
+ const filtered = [...values]
+ .filter((value) => retained.has(value))
+ .sort(compareCodePoints);
+ return filtered.length === 0 ? [] : [[nodeId, filtered] as const];
+ }),
+ );
+
+const nodeIdentityKey = (node: ApplicationNode): string =>
+ `node\0${node.kind}\0${node.node_id}`;
+
+const contentDigestKey = (node: ApplicationNode): string | null =>
+ node.identity.strategy === "content-digest"
+ ? `content\0${node.kind}\0${node.identity.sha256}`
+ : null;
+
+const moduleSourceDigestKey = (node: ApplicationNode): string | null => {
+ if (node.kind !== "javascript-module") return null;
+ const value = uniqueStringProperty(node, "source_sha256");
+ return value === null ? null : `module-source\0${node.kind}\0${value}`;
+};
+
+const sourceMapKey = (node: ApplicationNode): string | null =>
+ node.kind === "source-module" &&
+ node.identity.strategy === "source-map-original"
+ ? `source-map\0${node.identity.original_source}`
+ : null;
+
+const structuralFingerprintKey = (node: ApplicationNode): string | null => {
+ if (node.kind !== "javascript-module") return null;
+ const digest = uniqueStringProperty(node, "structural_fingerprint_sha256");
+ const algorithm = uniqueStringProperty(
+ node,
+ "structural_fingerprint_algorithm",
+ );
+ const status = uniqueStringProperty(node, "structural_fingerprint_status");
+ return digest === null || algorithm === null || status !== "complete"
+ ? null
+ : `structural\0${node.kind}\0${algorithm}\0${digest}`;
+};
+
+const semanticKey = (node: ApplicationNode): string | null => {
+ if (
+ [
+ "javascript-module",
+ "javascript-chunk",
+ "runtime-script-instance",
+ "unknown",
+ ].includes(node.kind)
+ )
+ return null;
+ const properties = firstProperties(node);
+ const value = semanticValue(node, properties);
+ return value === null ? null : `semantic\0${node.kind}\0${value}`;
+};
+
+const semanticValue = (
+ node: ApplicationNode,
+ properties: Readonly>,
+): string | null => {
+ if (node.kind === "endpoint")
+ return joined(properties.endpoint_kind, properties.value);
+ if (node.kind === "storage")
+ return joined(
+ properties.storage_kind,
+ properties.name ?? properties.mechanism,
+ );
+ if (node.kind === "ipc-channel")
+ return properties.resolution === "dynamic"
+ ? null
+ : (stringValue(properties.channel) ?? firstLabel(node));
+ if (node.kind === "context-bridge-api")
+ return firstLabel(node) ?? stringValue(properties.api_name);
+ if (node.kind === "native-export")
+ return (
+ joined(
+ properties.specifier,
+ stringList(properties.requested_members).join(","),
+ ) ?? firstLabel(node)
+ );
+ if (
+ [
+ "electron-main",
+ "electron-preload",
+ "electron-renderer",
+ "electron-utility",
+ ].includes(node.kind)
+ )
+ return joined(properties.declared_path, properties.resolved_path);
+ if (node.kind === "package") return stringValue(properties.name);
+ return canonicalPath(node) ?? stringValue(properties.path);
+};
+
+const canonicalPath = (node: ApplicationNode): string | null =>
+ node.identity.strategy === "canonical-path" ? node.identity.path : null;
+
+const firstProperties = (node: ApplicationNode) =>
+ node.observations[0]?.properties ?? {};
+
+const firstLabel = (node: ApplicationNode): string | null =>
+ node.observations.find(({ label }) => label !== null)?.label ?? null;
+
+const uniqueStringProperty = (
+ node: ApplicationNode,
+ name: string,
+): string | null => {
+ const values = [
+ ...new Set(
+ node.observations
+ .map(({ properties }) => properties[name])
+ .filter((value): value is string => typeof value === "string"),
+ ),
+ ];
+ return values.length === 1 ? (values[0] ?? null) : null;
+};
+
+const joined = (...values: readonly unknown[]): string | null => {
+ const strings = values.map(stringValue);
+ return strings.some((value) => value === null) ? null : strings.join("\0");
+};
+
+const stringValue = (value: unknown): string | null =>
+ typeof value === "string" && value !== "" ? value : null;
+
+const stringList = (value: unknown): string[] =>
+ Array.isArray(value)
+ ? value
+ .filter((item): item is string => typeof item === "string")
+ .sort(compareCodePoints)
+ : [];
+
+const sortedNodes = (nodes: Iterable): ApplicationNode[] =>
+ [...nodes].sort((left, right) =>
+ compareCodePoints(left.node_id, right.node_id),
+ );
diff --git a/src/domain/javascriptFeatureSeed.ts b/src/domain/javascriptFeatureSeed.ts
new file mode 100644
index 000000000..2899fb515
--- /dev/null
+++ b/src/domain/javascriptFeatureSeed.ts
@@ -0,0 +1,191 @@
+import type { ApplicationNode } from "./javascriptApplicationGraph.js";
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import type { ApplicationFeatureSeed } from "./javascriptFeatureTraceSchemas.js";
+import type { JsonValue } from "./jsonValue.js";
+
+/** One explicit field that matched a feature seed. */
+export interface ApplicationFeatureSeedMatch {
+ readonly node_id: string;
+ readonly kind: ApplicationNode["kind"];
+ readonly basis: "node-id" | "label" | "identity" | "property";
+ readonly field: string;
+}
+
+interface CandidateField {
+ readonly basis: ApplicationFeatureSeedMatch["basis"];
+ readonly field: string;
+ readonly value: string;
+}
+
+/** Locate every graph node matching a typed literal seed without regex execution. */
+export const findApplicationFeatureSeeds = (
+ nodes: readonly ApplicationNode[],
+ seed: ApplicationFeatureSeed,
+): ApplicationFeatureSeedMatch[] =>
+ nodes
+ .flatMap((node) => seedMatch(node, seed))
+ .sort((left, right) =>
+ compareCodePoints(
+ `${left.node_id}\0${left.basis}\0${left.field}`,
+ `${right.node_id}\0${right.basis}\0${right.field}`,
+ ),
+ );
+
+const seedMatch = (
+ node: ApplicationNode,
+ seed: ApplicationFeatureSeed,
+): ApplicationFeatureSeedMatch[] => {
+ if (seed.kind === "node-id")
+ return node.node_id === seed.value
+ ? [
+ {
+ node_id: node.node_id,
+ kind: node.kind,
+ basis: "node-id",
+ field: "node_id",
+ },
+ ]
+ : [];
+ if (!kindMatches(node, seed.kind)) return [];
+ const mode = seed.match ?? (seed.kind === "string" ? "contains" : "exact");
+ const query = normalized(seed.value, seed.case_sensitive);
+ const match = candidateFields(node, seed.kind).find((candidate) => {
+ const value = normalized(candidate.value, seed.case_sensitive);
+ return mode === "exact" ? value === query : value.includes(query);
+ });
+ return match === undefined
+ ? []
+ : [
+ {
+ node_id: node.node_id,
+ kind: node.kind,
+ basis: match.basis,
+ field: match.field,
+ },
+ ];
+};
+
+const kindMatches = (
+ node: ApplicationNode,
+ kind: Exclude,
+): boolean => {
+ if (kind === "string") return true;
+ if (kind === "route")
+ return (
+ node.kind === "endpoint" &&
+ node.observations.some(
+ ({ properties }) => properties.endpoint_kind === "route",
+ )
+ );
+ if (kind === "api") return node.kind === "context-bridge-api";
+ if (kind === "channel") return node.kind === "ipc-channel";
+ if (kind === "module")
+ return ["javascript-asset", "javascript-module", "source-module"].includes(
+ node.kind,
+ );
+ return node.kind === "native-export";
+};
+
+const candidateFields = (
+ node: ApplicationNode,
+ seedKind: Exclude,
+): CandidateField[] => {
+ const fields: CandidateField[] = [
+ ...identityFields(node),
+ ...node.observations.flatMap((observation, index) => [
+ ...(observation.label === null
+ ? []
+ : [
+ {
+ basis: "label" as const,
+ field: `observations[${String(index)}].label`,
+ value: observation.label,
+ },
+ ]),
+ ...propertyFields(
+ observation.properties,
+ `observations[${String(index)}].properties`,
+ ),
+ ]),
+ ];
+ if (seedKind === "string") return fields;
+ const names = relevantFields[seedKind];
+ return fields.filter(({ field }) =>
+ names.some((name) => field === "identity" || field.endsWith(name)),
+ );
+};
+
+const relevantFields = {
+ route: [".label", ".value", ".path"],
+ api: [".label", ".api_name", ".key", ".methods", ".members"],
+ channel: [".label", ".channel", ".key"],
+ module: [
+ ".label",
+ ".module_key",
+ ".path",
+ ".source",
+ ".original_source",
+ ".exports",
+ ],
+ "native-export": [".label", ".key", ".requested_members", ".members"],
+} as const;
+
+const identityFields = (node: ApplicationNode): CandidateField[] => {
+ const identity = node.identity;
+ if (identity.strategy === "content-digest")
+ return [{ basis: "identity", field: "identity", value: identity.sha256 }];
+ if (identity.strategy === "source-map-original")
+ return [
+ {
+ basis: "identity",
+ field: "identity.original_source",
+ value: identity.original_source,
+ },
+ ];
+ if (identity.strategy === "canonical-path")
+ return [
+ { basis: "identity", field: "identity.path", value: identity.path },
+ ];
+ if (identity.strategy === "artifact-local-key")
+ return [{ basis: "identity", field: "identity.key", value: identity.key }];
+ if (identity.strategy === "runtime-instance")
+ return [
+ {
+ basis: "identity",
+ field: "identity.runtime_key",
+ value: identity.runtime_key,
+ },
+ ];
+ return [];
+};
+
+const propertyFields = (
+ value: Readonly>,
+ prefix: string,
+): CandidateField[] => {
+ const output: CandidateField[] = [];
+ const visit = (current: JsonValue, path: string, depth: number): void => {
+ if (output.length >= 512 || depth > 6) return;
+ if (typeof current === "string") {
+ output.push({ basis: "property", field: path, value: current });
+ return;
+ }
+ if (Array.isArray(current)) {
+ for (const [index, item] of current.entries())
+ visit(item, `${path}[${String(index)}]`, depth + 1);
+ return;
+ }
+ if (current !== null && typeof current === "object")
+ for (const key of Object.keys(current).sort(compareCodePoints))
+ visit(current[key] ?? null, `${path}.${key}`, depth + 1);
+ };
+ visit(value, prefix, 0);
+ return output;
+};
+
+const normalized = (value: string, caseSensitive: boolean): string => {
+ const normalizedValue = value.normalize("NFKC");
+ return caseSensitive
+ ? normalizedValue
+ : normalizedValue.toLocaleLowerCase("en-US");
+};
diff --git a/src/domain/javascriptFeatureTrace.ts b/src/domain/javascriptFeatureTrace.ts
new file mode 100644
index 000000000..33907ba4c
--- /dev/null
+++ b/src/domain/javascriptFeatureTrace.ts
@@ -0,0 +1,349 @@
+import { createHash } from "node:crypto";
+
+import canonicalize from "canonicalize";
+
+import type { Evidence } from "./evidence.js";
+import {
+ compareCodePoints,
+ createJavaScriptApplicationGraph,
+ type ApplicationEdge,
+ type ApplicationNode,
+ type JavaScriptApplicationGraph,
+} from "./javascriptApplicationGraph.js";
+import {
+ applicationFeatureTraceResultSchema,
+ type ApplicationFeatureTraceResult,
+ type TraceApplicationFeatureInput,
+} from "./javascriptFeatureTraceSchemas.js";
+import {
+ findApplicationFeatureSeeds,
+ type ApplicationFeatureSeedMatch,
+} from "./javascriptFeatureSeed.js";
+import {
+ traverseApplicationFeature,
+ type ApplicationFeatureTraversal,
+} from "./javascriptFeatureTraversal.js";
+import { buildJavaScriptNativeHandoffs } from "./javascriptNativeHandoff.js";
+
+/** Pure, authenticated inputs projected by the application service. */
+export interface ApplicationFeatureTraceProjectionInput {
+ readonly sourceEvidenceId: string;
+ readonly graph: JavaScriptApplicationGraph;
+ readonly nativeEvidence: readonly Evidence[];
+ readonly seed: TraceApplicationFeatureInput["seed"];
+ readonly direction: TraceApplicationFeatureInput["direction"];
+ readonly limits: TraceApplicationFeatureInput["limits"];
+}
+
+/** Trace a literal feature through a bounded, authority-preserving JAG. */
+export const traceApplicationFeature = (
+ input: ApplicationFeatureTraceProjectionInput,
+): ApplicationFeatureTraceResult => {
+ const allSeedMatches = findApplicationFeatureSeeds(
+ input.graph.nodes,
+ input.seed,
+ );
+ const seedMatches = allSeedMatches.slice(0, input.limits.max_seed_matches);
+ if (seedMatches.length === 0) return noMatchResult(input);
+ const traversal = traverseApplicationFeature(
+ input.graph,
+ seedMatches.map(({ node_id: id }) => id),
+ input.direction,
+ input.limits,
+ );
+ const graph = traceGraph(
+ input,
+ seedMatches,
+ traversal,
+ allSeedMatches.length,
+ );
+ const allPaths = terminalPaths(traversal, seedMatches);
+ const paths = allPaths.slice(0, input.limits.max_paths);
+ const nativeHandoffs = buildJavaScriptNativeHandoffs(
+ traversal.nodes,
+ traversal.edges,
+ input.nativeEvidence,
+ );
+ const evidenceLinks = uniqueSorted([
+ input.sourceEvidenceId,
+ ...nativeHandoffs.flatMap(({ evidence_ids: ids }) => ids),
+ ]);
+ const omissions = traceOmissions(
+ input,
+ traversal,
+ allSeedMatches.length,
+ allPaths.length,
+ );
+ const semantic = {
+ schema_version: 1 as const,
+ source_evidence_id: input.sourceEvidenceId,
+ source_graph_id: input.graph.graph_id,
+ seed: input.seed,
+ direction: input.direction,
+ seed_matches: seedMatches,
+ graph,
+ paths,
+ native_handoffs: nativeHandoffs,
+ summary: {
+ matched_seeds: seedMatches.length,
+ traced_nodes: traversal.nodes.length,
+ traced_edges: traversal.edges.length,
+ terminal_paths: paths.length,
+ native_handoffs: nativeHandoffs.length,
+ ...factSummary(traversal.nodes, traversal.edges),
+ },
+ coverage: {
+ status: traceCoverageStatus(input.graph, omissions),
+ source_graph_status: input.graph.coverage.status,
+ scanned_nodes: input.graph.nodes.length,
+ total_seed_matches: allSeedMatches.length,
+ ...omissions,
+ frontier_node_ids: traversal.frontierNodeIds,
+ },
+ evidence_links: evidenceLinks,
+ limitations: traceLimitations(input.graph, omissions),
+ };
+ return applicationFeatureTraceResultSchema.parse({
+ ...semantic,
+ trace_id: `jatr_${digestCanonical(semantic)}`,
+ });
+};
+
+const noMatchResult = (
+ input: ApplicationFeatureTraceProjectionInput,
+): ApplicationFeatureTraceResult => {
+ const semantic = {
+ schema_version: 1 as const,
+ source_evidence_id: input.sourceEvidenceId,
+ source_graph_id: input.graph.graph_id,
+ seed: input.seed,
+ direction: input.direction,
+ seed_matches: [],
+ graph: null,
+ paths: [],
+ native_handoffs: [],
+ summary: {
+ matched_seeds: 0,
+ traced_nodes: 0,
+ traced_edges: 0,
+ terminal_paths: 0,
+ native_handoffs: 0,
+ observed_facts: 0,
+ inferred_facts: 0,
+ unknown_facts: 0,
+ unavailable_facts: 0,
+ },
+ coverage: {
+ status: "no-match" as const,
+ source_graph_status: input.graph.coverage.status,
+ scanned_nodes: input.graph.nodes.length,
+ total_seed_matches: 0,
+ omitted_seed_matches: 0,
+ omitted_nodes: 0,
+ omitted_edges: 0,
+ omitted_paths: 0,
+ frontier_node_ids: [],
+ },
+ evidence_links: [input.sourceEvidenceId],
+ limitations: uniqueSorted([
+ "No graph entity matched the literal seed; this is not evidence that the feature is absent.",
+ ...sourceCoverageLimitations(input.graph),
+ ]),
+ };
+ return applicationFeatureTraceResultSchema.parse({
+ ...semantic,
+ trace_id: `jatr_${digestCanonical(semantic)}`,
+ });
+};
+
+const traceGraph = (
+ input: ApplicationFeatureTraceProjectionInput,
+ seedMatches: readonly ApplicationFeatureSeedMatch[],
+ traversal: ApplicationFeatureTraversal,
+ totalSeedMatches: number,
+): JavaScriptApplicationGraph => {
+ const omitted =
+ traversal.omittedNodeCount +
+ traversal.omittedEdgeCount +
+ (totalSeedMatches - seedMatches.length);
+ return createJavaScriptApplicationGraph({
+ schema: "JavaScriptApplicationGraph",
+ schema_version: 1,
+ root_node_ids: uniqueSorted(seedMatches.map(({ node_id: id }) => id)),
+ nodes: traversal.nodes,
+ edges: traversal.edges,
+ coverage: traceGraphCoverage(input.graph, input.limits, omitted),
+ limitations: uniqueSorted([
+ ...input.graph.limitations,
+ "Trace edges retain their source authority; graph connectivity does not prove runtime execution or reachability.",
+ ...(omitted === 0
+ ? []
+ : ["Trace output stopped at explicit caller bounds."]),
+ ]),
+ });
+};
+
+const traceGraphCoverage = (
+ source: JavaScriptApplicationGraph,
+ limits: TraceApplicationFeatureInput["limits"],
+ omitted: number,
+): JavaScriptApplicationGraph["coverage"] => {
+ if (omitted > 0)
+ return {
+ status: "partial",
+ truncated: true,
+ omitted_count: omitted,
+ limits: [
+ {
+ name: "max-seed-matches",
+ value: limits.max_seed_matches,
+ unit: "items",
+ },
+ { name: "max-depth", value: limits.max_depth, unit: "depth" },
+ { name: "max-nodes", value: limits.max_nodes, unit: "items" },
+ { name: "max-edges", value: limits.max_edges, unit: "items" },
+ ],
+ };
+ return source.coverage.status === "complete"
+ ? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
+ : {
+ status: source.coverage.status,
+ truncated: source.coverage.truncated,
+ omitted_count: source.coverage.omitted_count,
+ limits: source.coverage.limits,
+ };
+};
+
+const terminalPaths = (
+ traversal: ApplicationFeatureTraversal,
+ seeds: readonly ApplicationFeatureSeedMatch[],
+): ApplicationFeatureTraceResult["paths"] => {
+ const seedIds = new Set(seeds.map(({ node_id: id }) => id));
+ const edgeById = new Map(traversal.edges.map((edge) => [edge.edge_id, edge]));
+ return traversal.nodes
+ .filter(
+ (node) =>
+ isTerminal(node) &&
+ (!seedIds.has(node.node_id) || traversal.nodes.length === 1),
+ )
+ .map((node) => pathTo(node, traversal.predecessors, edgeById))
+ .filter((path): path is NonNullable => path !== null)
+ .sort((left, right) => compareCodePoints(left.path_id, right.path_id));
+};
+
+const pathTo = (
+ node: ApplicationNode,
+ predecessors: ApplicationFeatureTraversal["predecessors"],
+ edgeById: ReadonlyMap,
+): ApplicationFeatureTraceResult["paths"][number] | null => {
+ const nodeIds = [node.node_id];
+ const edgeIds: string[] = [];
+ let current = node.node_id;
+ while (predecessors.has(current)) {
+ const predecessor = predecessors.get(current);
+ if (predecessor === undefined) break;
+ nodeIds.push(predecessor.previousNodeId);
+ edgeIds.push(predecessor.edgeId);
+ current = predecessor.previousNodeId;
+ }
+ nodeIds.reverse();
+ edgeIds.reverse();
+ const edges = edgeIds
+ .map((edgeId) => edgeById.get(edgeId))
+ .filter((edge): edge is ApplicationEdge => edge !== undefined);
+ if (edges.length !== edgeIds.length) return null;
+ const semantic = {
+ start_node_id: nodeIds[0] ?? node.node_id,
+ end_node_id: node.node_id,
+ end_kind: node.kind,
+ node_ids: nodeIds,
+ edge_ids: edgeIds,
+ authorities: uniqueSorted(edges.map(({ evidence }) => evidence.authority)),
+ contains_inference: edges.some(
+ ({ evidence }) => evidence.state === "inferred",
+ ),
+ };
+ return { ...semantic, path_id: `jatp_${digestCanonical(semantic)}` };
+};
+
+const isTerminal = (node: ApplicationNode): boolean =>
+ ["endpoint", "storage", "native-addon", "native-export", "unknown"].includes(
+ node.kind,
+ );
+
+const factSummary = (
+ nodes: readonly ApplicationNode[],
+ edges: readonly ApplicationEdge[],
+) => {
+ const states = [
+ ...nodes.flatMap(({ observations }) =>
+ observations.map(({ evidence }) => evidence.state),
+ ),
+ ...edges.map(({ evidence }) => evidence.state),
+ ];
+ return {
+ observed_facts: states.filter((state) => state === "observed").length,
+ inferred_facts: states.filter((state) => state === "inferred").length,
+ unknown_facts: states.filter((state) => state === "unknown").length,
+ unavailable_facts: states.filter((state) => state === "unavailable").length,
+ };
+};
+
+const traceOmissions = (
+ input: ApplicationFeatureTraceProjectionInput,
+ traversal: ApplicationFeatureTraversal,
+ seedMatches: number,
+ paths: number,
+) => ({
+ omitted_seed_matches: Math.max(
+ 0,
+ seedMatches - input.limits.max_seed_matches,
+ ),
+ omitted_nodes: traversal.omittedNodeCount,
+ omitted_edges: traversal.omittedEdgeCount,
+ omitted_paths: Math.max(0, paths - input.limits.max_paths),
+});
+
+const traceCoverageStatus = (
+ graph: JavaScriptApplicationGraph,
+ omissions: ReturnType,
+): ApplicationFeatureTraceResult["coverage"]["status"] =>
+ Object.values(omissions).some((value) => value > 0)
+ ? "truncated"
+ : graph.coverage.status === "complete"
+ ? "complete-within-source"
+ : "partial";
+
+const traceLimitations = (
+ graph: JavaScriptApplicationGraph,
+ omissions: ReturnType,
+): string[] =>
+ uniqueSorted([
+ "A trace reports graph relationships, not proof that code executed or that a feature is reachable in every state.",
+ "Static, native, passive-runtime, inferred, and unknown facts retain their original authority in the returned graph.",
+ "Native handoffs never open a binary or invoke a provider automatically; snapshot reuse remains provider/profile/target exact.",
+ ...sourceCoverageLimitations(graph),
+ ...(Object.values(omissions).some((value) => value > 0)
+ ? ["Trace results were truncated at explicit caller limits."]
+ : []),
+ ]);
+
+const sourceCoverageLimitations = (
+ graph: JavaScriptApplicationGraph,
+): string[] =>
+ graph.coverage.status === "complete"
+ ? []
+ : [
+ "The source application graph is incomplete; unmatched seeds and frontiers remain unknown.",
+ ];
+
+const digestCanonical = (value: unknown): string => {
+ const encoded = canonicalize(value);
+ if (encoded === undefined)
+ throw new TypeError("Feature trace could not canonicalize data");
+ return createHash("sha256").update(encoded).digest("hex");
+};
+
+const uniqueSorted = (
+ values: readonly Value[],
+): Value[] => [...new Set(values)].sort(compareCodePoints);
diff --git a/src/domain/javascriptFeatureTraceSchemas.ts b/src/domain/javascriptFeatureTraceSchemas.ts
new file mode 100644
index 000000000..00119218e
--- /dev/null
+++ b/src/domain/javascriptFeatureTraceSchemas.ts
@@ -0,0 +1,157 @@
+import { z } from "zod";
+
+import { evidenceSchema, providerSchema } from "./evidence.js";
+import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
+
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
+const edgeIdSchema = z.string().regex(/^jag_edge_[a-f0-9]{64}$/u);
+const boundedTextSchema = z.string().min(1).max(4_096);
+
+/** Literal starting point for one bounded application trace. */
+const applicationFeatureSeedSchema = z.strictObject({
+ kind: z.enum([
+ "node-id",
+ "route",
+ "string",
+ "api",
+ "channel",
+ "module",
+ "native-export",
+ ]),
+ value: boundedTextSchema,
+ match: z.enum(["exact", "contains"]).nullable().default(null),
+ case_sensitive: z.boolean().default(false),
+});
+
+const featureTraceLimitsSchema = z.strictObject({
+ max_seed_matches: z.number().int().min(1).max(1_000).default(25),
+ max_depth: z.number().int().min(0).max(64).default(12),
+ max_nodes: z.number().int().min(1).max(50_000).default(2_000),
+ max_edges: z.number().int().min(1).max(100_000).default(4_000),
+ max_paths: z.number().int().min(1).max(1_000).default(100),
+});
+
+/** Evidence-backed application graph and explicit trace bounds. */
+export const traceApplicationFeatureInputSchema = z
+ .strictObject({
+ application: evidenceSchema,
+ native_observations: z.array(evidenceSchema).max(64).default([]),
+ seed: applicationFeatureSeedSchema,
+ direction: z.enum(["outgoing", "incoming", "both"]).default("both"),
+ limits: featureTraceLimitsSchema.default({
+ max_seed_matches: 25,
+ max_depth: 12,
+ max_nodes: 2_000,
+ max_edges: 4_000,
+ max_paths: 100,
+ }),
+ })
+ .superRefine((input, context) => {
+ const ids = input.native_observations.map(({ evidence_id: id }) => id);
+ if (new Set(ids).size !== ids.length)
+ context.addIssue({
+ code: "custom",
+ path: ["native_observations"],
+ message: "Native observations must be unique",
+ });
+ });
+
+const seedMatchSchema = z.strictObject({
+ node_id: nodeIdSchema,
+ kind: z.string().min(1).max(128),
+ basis: z.enum(["node-id", "label", "identity", "property"]),
+ field: z.string().min(1).max(256),
+});
+
+const tracePathSchema = z.strictObject({
+ path_id: z.string().regex(/^jatp_[a-f0-9]{64}$/u),
+ start_node_id: nodeIdSchema,
+ end_node_id: nodeIdSchema,
+ end_kind: z.string().min(1).max(128),
+ node_ids: z.array(nodeIdSchema).min(1).max(65),
+ edge_ids: z.array(edgeIdSchema).max(64),
+ authorities: z.array(z.string().min(1).max(128)).max(16),
+ contains_inference: z.boolean(),
+});
+
+const nativeHandoffSchema = z.strictObject({
+ native_node_id: nodeIdSchema,
+ artifact_sha256: digestSchema,
+ artifact_path: z.string().min(1).max(4_096).nullable(),
+ export_node_ids: z.array(nodeIdSchema).max(1_000),
+ requested_exports: z.array(boundedTextSchema).max(1_000),
+ status: z.enum(["evidence-linked", "requires-provider-analysis"]),
+ providers: z.array(providerSchema).max(64),
+ evidence_ids: z.array(evidenceIdSchema).max(64),
+ recommended_tools: z
+ .array(
+ z.enum([
+ "open_binary",
+ "binary_overview",
+ "search_procedures",
+ "analyze_function",
+ "xrefs",
+ ]),
+ )
+ .max(5),
+});
+
+/** Evidence-preserving bounded subgraph and native-analysis frontiers. */
+export const applicationFeatureTraceResultSchema = z.strictObject({
+ schema_version: z.literal(1),
+ trace_id: z.string().regex(/^jatr_[a-f0-9]{64}$/u),
+ source_evidence_id: evidenceIdSchema,
+ source_graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+ seed: applicationFeatureSeedSchema,
+ direction: z.enum(["outgoing", "incoming", "both"]),
+ seed_matches: z.array(seedMatchSchema).max(1_000),
+ graph: javascriptApplicationGraphSchema.nullable(),
+ paths: z.array(tracePathSchema).max(1_000),
+ native_handoffs: z.array(nativeHandoffSchema).max(10_000),
+ summary: z.strictObject({
+ matched_seeds: z.number().int().min(0),
+ traced_nodes: z.number().int().min(0),
+ traced_edges: z.number().int().min(0),
+ terminal_paths: z.number().int().min(0),
+ native_handoffs: z.number().int().min(0),
+ observed_facts: z.number().int().min(0),
+ inferred_facts: z.number().int().min(0),
+ unknown_facts: z.number().int().min(0),
+ unavailable_facts: z.number().int().min(0),
+ }),
+ coverage: z.strictObject({
+ status: z.enum([
+ "complete-within-source",
+ "partial",
+ "truncated",
+ "no-match",
+ ]),
+ source_graph_status: z.enum([
+ "complete",
+ "partial",
+ "unknown",
+ "unavailable",
+ ]),
+ scanned_nodes: z.number().int().min(0),
+ total_seed_matches: z.number().int().min(0),
+ omitted_seed_matches: z.number().int().min(0),
+ omitted_nodes: z.number().int().min(0),
+ omitted_edges: z.number().int().min(0),
+ omitted_paths: z.number().int().min(0),
+ frontier_node_ids: z.array(nodeIdSchema).max(50_000),
+ }),
+ evidence_links: z.array(evidenceIdSchema).min(1).max(65),
+ limitations: z.array(boundedTextSchema).max(1_000),
+});
+
+export type TraceApplicationFeatureInput = z.infer<
+ typeof traceApplicationFeatureInputSchema
+>;
+export type ApplicationFeatureSeed = z.infer<
+ typeof applicationFeatureSeedSchema
+>;
+export type ApplicationFeatureTraceResult = z.infer<
+ typeof applicationFeatureTraceResultSchema
+>;
diff --git a/src/domain/javascriptFeatureTraversal.ts b/src/domain/javascriptFeatureTraversal.ts
new file mode 100644
index 000000000..52304e5fb
--- /dev/null
+++ b/src/domain/javascriptFeatureTraversal.ts
@@ -0,0 +1,143 @@
+import {
+ compareCodePoints,
+ type ApplicationEdge,
+ type ApplicationNode,
+ type JavaScriptApplicationGraph,
+} from "./javascriptApplicationGraph.js";
+import type { TraceApplicationFeatureInput } from "./javascriptFeatureTraceSchemas.js";
+
+interface AdjacencyEntry {
+ readonly edge: ApplicationEdge;
+ readonly nextNodeId: string;
+}
+
+interface Predecessor {
+ readonly previousNodeId: string;
+ readonly edgeId: string;
+}
+
+/** Bounded graph projection plus the first deterministic path to each node. */
+export interface ApplicationFeatureTraversal {
+ readonly nodes: ApplicationNode[];
+ readonly edges: ApplicationEdge[];
+ readonly depths: ReadonlyMap;
+ readonly predecessors: ReadonlyMap;
+ readonly frontierNodeIds: string[];
+ readonly omittedNodeCount: number;
+ readonly omittedEdgeCount: number;
+}
+
+/** Traverse a JAG without treating edge inference as observed reachability. */
+export const traverseApplicationFeature = (
+ graph: JavaScriptApplicationGraph,
+ seedNodeIds: readonly string[],
+ direction: TraceApplicationFeatureInput["direction"],
+ limits: TraceApplicationFeatureInput["limits"],
+): ApplicationFeatureTraversal => {
+ const nodeById = new Map(graph.nodes.map((node) => [node.node_id, node]));
+ const adjacency = buildAdjacency(graph.edges, direction);
+ const visited = new Set(seedNodeIds);
+ const retainedEdges = new Map();
+ const omittedNodes = new Set();
+ const omittedEdges = new Set();
+ const frontier = new Set();
+ const depths = new Map(seedNodeIds.map((nodeId) => [nodeId, 0]));
+ const predecessors = new Map();
+ const queue = [...seedNodeIds];
+ for (let offset = 0; offset < queue.length; offset += 1) {
+ const current = queue[offset];
+ if (current === undefined) continue;
+ const depth = depths.get(current) ?? 0;
+ for (const entry of adjacency.get(current) ?? []) {
+ if (depth >= limits.max_depth) {
+ recordOmission(entry, current, omittedNodes, omittedEdges, frontier);
+ continue;
+ }
+ if (!visited.has(entry.nextNodeId) && visited.size >= limits.max_nodes) {
+ recordOmission(entry, current, omittedNodes, omittedEdges, frontier);
+ continue;
+ }
+ if (
+ !retainedEdges.has(entry.edge.edge_id) &&
+ retainedEdges.size >= limits.max_edges
+ ) {
+ omittedEdges.add(entry.edge.edge_id);
+ frontier.add(current);
+ frontier.add(entry.nextNodeId);
+ continue;
+ }
+ retainedEdges.set(entry.edge.edge_id, entry.edge);
+ if (visited.has(entry.nextNodeId)) continue;
+ if (!nodeById.has(entry.nextNodeId)) continue;
+ visited.add(entry.nextNodeId);
+ depths.set(entry.nextNodeId, depth + 1);
+ predecessors.set(entry.nextNodeId, {
+ previousNodeId: current,
+ edgeId: entry.edge.edge_id,
+ });
+ queue.push(entry.nextNodeId);
+ }
+ }
+ return {
+ nodes: [...visited]
+ .map((nodeId) => nodeById.get(nodeId))
+ .filter((node): node is ApplicationNode => node !== undefined)
+ .sort((left, right) => compareCodePoints(left.node_id, right.node_id)),
+ edges: [...retainedEdges.values()].sort((left, right) =>
+ compareCodePoints(left.edge_id, right.edge_id),
+ ),
+ depths,
+ predecessors,
+ frontierNodeIds: [...frontier].sort(compareCodePoints),
+ omittedNodeCount: omittedNodes.size,
+ omittedEdgeCount: omittedEdges.size,
+ };
+};
+
+const buildAdjacency = (
+ edges: readonly ApplicationEdge[],
+ direction: TraceApplicationFeatureInput["direction"],
+): ReadonlyMap => {
+ const adjacency = new Map();
+ for (const edge of edges) {
+ if (direction !== "incoming")
+ addAdjacency(adjacency, edge.source_node_id, {
+ edge,
+ nextNodeId: edge.target_node_id,
+ });
+ if (direction !== "outgoing")
+ addAdjacency(adjacency, edge.target_node_id, {
+ edge,
+ nextNodeId: edge.source_node_id,
+ });
+ }
+ for (const entries of adjacency.values())
+ entries.sort((left, right) =>
+ compareCodePoints(
+ `${left.edge.edge_id}\0${left.nextNodeId}`,
+ `${right.edge.edge_id}\0${right.nextNodeId}`,
+ ),
+ );
+ return adjacency;
+};
+
+const addAdjacency = (
+ adjacency: Map,
+ nodeId: string,
+ entry: AdjacencyEntry,
+): void => {
+ adjacency.set(nodeId, [...(adjacency.get(nodeId) ?? []), entry]);
+};
+
+const recordOmission = (
+ entry: AdjacencyEntry,
+ current: string,
+ omittedNodes: Set,
+ omittedEdges: Set,
+ frontier: Set,
+): void => {
+ omittedNodes.add(entry.nextNodeId);
+ omittedEdges.add(entry.edge.edge_id);
+ frontier.add(current);
+ frontier.add(entry.nextNodeId);
+};
diff --git a/src/domain/javascriptNativeHandoff.ts b/src/domain/javascriptNativeHandoff.ts
new file mode 100644
index 000000000..d72bb9dd8
--- /dev/null
+++ b/src/domain/javascriptNativeHandoff.ts
@@ -0,0 +1,132 @@
+import type { Evidence } from "./evidence.js";
+import {
+ compareCodePoints,
+ type ApplicationEdge,
+ type ApplicationNode,
+} from "./javascriptApplicationGraph.js";
+import type { ApplicationFeatureTraceResult } from "./javascriptFeatureTraceSchemas.js";
+
+type NativeHandoff = ApplicationFeatureTraceResult["native_handoffs"][number];
+
+/** Build provider-neutral addon targets and link exact-subject native Evidence. */
+export const buildJavaScriptNativeHandoffs = (
+ nodes: readonly ApplicationNode[],
+ edges: readonly ApplicationEdge[],
+ nativeEvidence: readonly Evidence[],
+): NativeHandoff[] => {
+ const nodeById = new Map(nodes.map((node) => [node.node_id, node]));
+ return nodes
+ .filter(({ kind }) => kind === "native-addon")
+ .flatMap((node) => {
+ const digest = artifactDigest(node);
+ if (digest === null) return [];
+ const linked = nativeEvidence.filter(
+ ({ subject }) => subject?.digest.sha256 === digest,
+ );
+ const exportNodes = nativeExportNodes(node, edges, nodeById);
+ return [
+ {
+ native_node_id: node.node_id,
+ artifact_sha256: digest,
+ artifact_path: artifactPath(node),
+ export_node_ids: exportNodes.map(({ node_id: id }) => id),
+ requested_exports: requestedExports(exportNodes),
+ status:
+ linked.length === 0
+ ? ("requires-provider-analysis" as const)
+ : ("evidence-linked" as const),
+ providers: uniqueProviders(linked),
+ evidence_ids: linked
+ .map(({ evidence_id: id }) => id)
+ .sort(compareCodePoints),
+ recommended_tools: [
+ "open_binary" as const,
+ "binary_overview" as const,
+ "search_procedures" as const,
+ "analyze_function" as const,
+ "xrefs" as const,
+ ],
+ },
+ ];
+ })
+ .sort((left, right) =>
+ compareCodePoints(left.native_node_id, right.native_node_id),
+ );
+};
+
+const artifactDigest = (node: ApplicationNode): string | null => {
+ if (node.identity.strategy === "content-digest") return node.identity.sha256;
+ const observation = node.observations.find(
+ ({ evidence }) => evidence.artifact.available,
+ );
+ return observation?.evidence.artifact.available === true
+ ? observation.evidence.artifact.sha256
+ : null;
+};
+
+const artifactPath = (node: ApplicationNode): string | null => {
+ for (const { evidence } of node.observations)
+ if (
+ evidence.location.available &&
+ evidence.location.value.kind === "artifact-path"
+ )
+ return evidence.location.value.path;
+ return null;
+};
+
+const nativeExportNodes = (
+ addon: ApplicationNode,
+ edges: readonly ApplicationEdge[],
+ nodeById: ReadonlyMap,
+): ApplicationNode[] => {
+ const ids = edges.flatMap((edge) => {
+ if (
+ edge.source_node_id === addon.node_id &&
+ ["contains", "exposes"].includes(edge.relation)
+ )
+ return [edge.target_node_id];
+ if (
+ edge.target_node_id === addon.node_id &&
+ ["imports", "loads"].includes(edge.relation)
+ )
+ return [edge.source_node_id];
+ return [];
+ });
+ return [...new Set(ids)]
+ .map((id) => nodeById.get(id))
+ .filter((node): node is ApplicationNode => node?.kind === "native-export")
+ .sort((left, right) => compareCodePoints(left.node_id, right.node_id));
+};
+
+const requestedExports = (nodes: readonly ApplicationNode[]): string[] => {
+ const values = nodes.flatMap((node) =>
+ node.observations.flatMap((observation) => [
+ ...(observation.label === null ? [] : [observation.label]),
+ ...stringArray(observation.properties.requested_members),
+ ...stringArray(observation.properties.members),
+ ]),
+ );
+ return [...new Set(values)].sort(compareCodePoints).slice(0, 1_000);
+};
+
+const stringArray = (value: unknown): string[] =>
+ Array.isArray(value)
+ ? value.filter((item): item is string => typeof item === "string")
+ : [];
+
+const uniqueProviders = (
+ evidence: readonly Evidence[],
+): NativeHandoff["providers"] =>
+ [
+ ...new Map(
+ evidence.map(({ provider }) => [
+ `${provider.id}\0${provider.name}\0${provider.version ?? ""}`,
+ provider,
+ ]),
+ ).values(),
+ ].sort((left, right) =>
+ compareCodePoints(
+ `${left.id}\0${left.name}\0${left.version ?? ""}`,
+ `${right.id}\0${right.name}\0${right.version ?? ""}`,
+ ),
+ );
diff --git a/src/generatedPackageMetadata.ts b/src/generatedPackageMetadata.ts
index a663d819a..90a7815f9 100644
--- a/src/generatedPackageMetadata.ts
+++ b/src/generatedPackageMetadata.ts
@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
serverSdkVersion: "2.0.0-beta.4",
clientSdkVersion: "2.0.0-beta.4",
coreSdkVersion: "2.0.0-beta.4",
- skillVersion: "16",
+ skillVersion: "17",
} as const;
diff --git a/src/server/createServer.ts b/src/server/createServer.ts
index 438953125..2bf9b2289 100644
--- a/src/server/createServer.ts
+++ b/src/server/createServer.ts
@@ -19,6 +19,7 @@ import type { BrowserObservationPort } from "../application/BrowserObservationPo
import { registerBrowserTools } from "./registerBrowserTools.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
import { registerElectronTools } from "./registerElectronTools.js";
+import { registerApplicationTools } from "./registerApplicationTools.js";
export interface CreateServerOptions {
readonly logger?: Logger;
@@ -113,6 +114,17 @@ export const createServer = (
server.sendResourceListChanged();
return recorded;
};
+ const recordEvidenceWithUnknown =
+ session === undefined
+ ? undefined
+ : (
+ evidence: Parameters[0],
+ input: Parameters[1],
+ ) => {
+ const recorded = session.recordEvidenceWithUnknown(evidence, input);
+ if (recorded.ok) server.sendResourceListChanged();
+ return recorded;
+ };
registerOfficialTools(server, analysis, {
logger: toolLogger,
activeTarget,
@@ -158,6 +170,11 @@ export const createServer = (
permissionAuthority: options.permissionAuthority,
recordEvidence,
});
+ registerApplicationTools(server, {
+ logger: toolLogger,
+ recordEvidence,
+ recordEvidenceWithUnknown,
+ });
registerGuidedPrompts(server, analysis, session);
if (session !== undefined) {
registerEvidenceResources(server, session);
diff --git a/src/server/registerApplicationTools.ts b/src/server/registerApplicationTools.ts
new file mode 100644
index 000000000..e089e3e45
--- /dev/null
+++ b/src/server/registerApplicationTools.ts
@@ -0,0 +1,131 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+
+import type { BinarySessionPort } from "../application/BinarySession.js";
+import {
+ compareApplicationVersionsEvidence,
+ traceApplicationFeatureEvidence,
+} from "../application/JavaScriptApplicationWorkflowService.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../contracts/applicationToolContracts.js";
+import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { applicationVersionComparisonResultSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
+import type { Evidence } from "../domain/evidence.js";
+import type { Logger } from "../logger.js";
+import { logToolExecution } from "./toolLogging.js";
+import { toCallToolResult } from "./toolResult.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+
+interface ApplicationToolRegistration {
+ readonly logger: Logger;
+ readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
+ readonly recordEvidenceWithUnknown:
+ | BinarySessionPort["recordEvidenceWithUnknown"]
+ | undefined;
+}
+
+/** Register provider-neutral JavaScript application graph workflows. */
+export const registerApplicationTools = (
+ server: McpServer,
+ options: ApplicationToolRegistration,
+): void => {
+ const [traceContract, compareContract] = APPLICATION_TOOL_CONTRACTS;
+ server.registerTool(
+ traceContract.name,
+ toolRegistrationOptions(traceContract),
+ async (input) => {
+ const parsed = traceApplicationFeatureInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ traceContract.name,
+ () => Promise.resolve(traceApplicationFeatureEvidence(parsed)),
+ );
+ if (!result.ok) return toCallToolResult(result, traceContract);
+ const sources = [parsed.application, ...parsed.native_observations];
+ const recorded = recordSources(options.recordEvidence, sources);
+ if (!recorded.ok) return toCallToolResult(recorded, traceContract);
+ return recordResult(options, traceContract, result.value);
+ },
+ );
+ server.registerTool(
+ compareContract.name,
+ toolRegistrationOptions(compareContract),
+ async (input) => {
+ const parsed = compareApplicationVersionsInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ compareContract.name,
+ () => Promise.resolve(compareApplicationVersionsEvidence(parsed)),
+ );
+ if (!result.ok) return toCallToolResult(result, compareContract);
+ const sources = [
+ parsed.left,
+ parsed.right,
+ ...parsed.left_native_observations,
+ ...parsed.right_native_observations,
+ ];
+ const recorded = recordSources(options.recordEvidence, sources);
+ if (!recorded.ok) return toCallToolResult(recorded, compareContract);
+ const comparison = applicationVersionComparisonResultSchema.parse(
+ result.value.normalized_result,
+ );
+ const unknown = comparison.summary.unknown > 0;
+ return recordResult(
+ options,
+ compareContract,
+ result.value,
+ parsed.unknown_registry_approved === true && unknown,
+ );
+ },
+ );
+};
+
+const recordSources = (
+ recordEvidence: ApplicationToolRegistration["recordEvidence"],
+ sources: readonly Evidence[],
+) => {
+ for (const source of sources) {
+ const recorded = recordEvidence?.(source);
+ if (recorded !== undefined && !recorded.ok) return recorded;
+ }
+ return { ok: true as const, value: null };
+};
+
+const recordResult = (
+ options: ApplicationToolRegistration,
+ contract: (typeof APPLICATION_TOOL_CONTRACTS)[number],
+ evidence: Evidence,
+ recordUnknown = false,
+) => {
+ const recorded = recordUnknown
+ ? options.recordEvidenceWithUnknown?.(evidence, {
+ approved: true,
+ question:
+ "Which application entities remain unmatched or ambiguous across these versions?",
+ severity: "medium",
+ domain: "application-version-comparison",
+ supporting_evidence_ids: [evidence.evidence_id],
+ contradicting_evidence_ids: [],
+ required_authority: "shipped-artifact",
+ required_confidence: "observed",
+ required_environment: null,
+ recommended_probes: [
+ {
+ operation: "analyze_javascript_application",
+ rationale:
+ "Repeat static reconstruction with complete artifacts and source maps when available.",
+ },
+ {
+ operation: "reconcile_javascript_runtime",
+ rationale:
+ "Add approved passive runtime Evidence without promoting it to static fact.",
+ },
+ ],
+ relationships: [],
+ })
+ : options.recordEvidence?.(evidence);
+ if (recorded !== undefined && !recorded.ok)
+ return toCallToolResult(recorded, contract);
+ return toCallToolResult({ ok: true, value: evidence }, contract, {
+ evidenceResourcesAvailable: recorded !== undefined,
+ });
+};
diff --git a/tests/applicationWorkflowCli.test.ts b/tests/applicationWorkflowCli.test.ts
new file mode 100644
index 000000000..2c51385f8
--- /dev/null
+++ b/tests/applicationWorkflowCli.test.ts
@@ -0,0 +1,67 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+ JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+ JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+} from "../src/contracts/javascriptApplicationWorkflowExamples.js";
+
+const execute = promisify(execFile);
+
+describe("application workflow CLI parity", () => {
+ const temporary: string[] = [];
+
+ afterEach(async () => {
+ await Promise.all(
+ temporary
+ .splice(0)
+ .map(async (path) => rm(path, { recursive: true, force: true })),
+ );
+ });
+
+ it("accepts inline trace JSON and file-backed comparison JSON", async () => {
+ const traced = await runCli([
+ "trace-application-feature",
+ JSON.stringify(JAVASCRIPT_FEATURE_TRACE_EXAMPLE),
+ "--json",
+ ]);
+ expect(traced).toMatchObject({
+ operation: "trace_application_feature",
+ normalized_result: { schema_version: 1 },
+ });
+
+ const root = await mkdtemp(join(tmpdir(), "rea-application-cli-"));
+ temporary.push(root);
+ const comparisonPath = join(root, "comparison.json");
+ await writeFile(
+ comparisonPath,
+ JSON.stringify(JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE),
+ );
+ const compared = await runCli([
+ "compare-application-versions",
+ comparisonPath,
+ "--json",
+ ]);
+ expect(compared).toMatchObject({
+ operation: "compare_application_versions",
+ normalized_result: {
+ schema_version: 1,
+ summary: { unknown: expect.any(Number) },
+ },
+ });
+ }, 20_000);
+});
+
+const runCli = async (arguments_: readonly string[]): Promise => {
+ const { stdout } = await execute(
+ process.execPath,
+ ["scripts/rea.mjs", ...arguments_],
+ { cwd: process.cwd(), env: process.env, maxBuffer: 16 * 1_024 * 1_024 },
+ );
+ return JSON.parse(stdout);
+};
diff --git a/tests/applicationWorkflowMcp.test.ts b/tests/applicationWorkflowMcp.test.ts
new file mode 100644
index 000000000..6c05d0d9f
--- /dev/null
+++ b/tests/applicationWorkflowMcp.test.ts
@@ -0,0 +1,78 @@
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { describe, expect, it } from "vitest";
+
+import { BinarySession } from "../src/application/BinarySession.js";
+import {
+ JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+ JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+} from "../src/contracts/javascriptApplicationWorkflowExamples.js";
+import { createServer } from "../src/server/createServer.js";
+import { observed } from "./fixtures/analysisExecution.js";
+
+describe("application workflow MCP parity", () => {
+ it("traces and compares authenticated graph Evidence in the session", async () => {
+ const session = new BinarySession(() => ({
+ execute: () => Promise.resolve(observed(null)),
+ close: () => Promise.resolve(),
+ }));
+ const server = createServer(session, session);
+ const client = new Client({
+ name: "application-workflow-test",
+ version: "1",
+ });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ try {
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+
+ const traced = await client.callTool({
+ name: "trace_application_feature",
+ arguments: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+ });
+ expect(traced.isError).not.toBe(true);
+ expect(traced.structuredContent).toMatchObject({
+ operation: "trace_application_feature",
+ provider: { id: "rea-javascript-application-workflows" },
+ normalized_result: {
+ schema_version: 1,
+ coverage: { status: expect.any(String) },
+ },
+ });
+
+ const compared = await client.callTool({
+ name: "compare_application_versions",
+ arguments: {
+ ...JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+ unknown_registry_approved: true,
+ },
+ });
+ expect(compared.isError).not.toBe(true);
+ expect(compared.structuredContent).toMatchObject({
+ operation: "compare_application_versions",
+ normalized_result: {
+ schema_version: 1,
+ summary: { unknown: expect.any(Number) },
+ coverage: { status: expect.any(String) },
+ },
+ });
+ expect(session.exportEvidenceBundle().records.length).toBeGreaterThan(2);
+
+ const spoofed = await client.callTool({
+ name: "trace_application_feature",
+ arguments: {
+ ...JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+ application: {
+ ...JAVASCRIPT_FEATURE_TRACE_EXAMPLE.application,
+ provider: { id: "spoofed", name: "spoofed", version: "1" },
+ },
+ },
+ });
+ expect(spoofed.isError).toBe(true);
+ } finally {
+ await client.close();
+ await server.close();
+ await session.close();
+ }
+ });
+});
diff --git a/tests/applicationWorkflowVerifier.test.ts b/tests/applicationWorkflowVerifier.test.ts
new file mode 100644
index 000000000..ea568a596
--- /dev/null
+++ b/tests/applicationWorkflowVerifier.test.ts
@@ -0,0 +1,61 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { writeVersionedJavaScriptApplicationFixtures } from "./fixtures/javascriptArtifactApplication.js";
+
+const execute = promisify(execFile);
+
+describe("local application workflow verifier", () => {
+ const temporary: string[] = [];
+
+ afterEach(async () => {
+ await Promise.all(
+ temporary
+ .splice(0)
+ .map(async (path) => rm(path, { recursive: true, force: true })),
+ );
+ });
+
+ it("reports bounded two-version and trace claims without source text", async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-application-verifier-"));
+ temporary.push(root);
+ const fixtures = await writeVersionedJavaScriptApplicationFixtures(root);
+ const { stdout } = await execute(
+ process.execPath,
+ [
+ "scripts/verify-local-application-workflows.mjs",
+ "--left",
+ fixtures.left,
+ "--right",
+ fixtures.right,
+ "--seed-kind",
+ "module",
+ "--seed-value",
+ "stable",
+ ],
+ { cwd: process.cwd(), maxBuffer: 16 * 1_024 * 1_024 },
+ );
+ const result = JSON.parse(stdout);
+ expect(result).toMatchObject({
+ verified: true,
+ summary: {
+ added: expect.any(Number),
+ removed: expect.any(Number),
+ changed: expect.any(Number),
+ unknown: expect.any(Number),
+ },
+ matching: {
+ exact_module_source_digest: expect.any(Number),
+ structural_fingerprint: expect.any(Number),
+ },
+ coverage: { status: expect.any(String) },
+ trace: { summary: { matched_seeds: expect.any(Number) } },
+ });
+ expect(stdout).not.toContain("stableValue");
+ }, 20_000);
+});
diff --git a/tests/browserMcp.test.ts b/tests/browserMcp.test.ts
index b7574254c..d5904a3f6 100644
--- a/tests/browserMcp.test.ts
+++ b/tests/browserMcp.test.ts
@@ -37,7 +37,7 @@ describe("browser MCP tools", () => {
const connected = await connectBrowser(browser);
const tools = await connected.client.listTools();
- expect(tools.tools).toHaveLength(80);
+ expect(tools.tools).toHaveLength(82);
expect(tools.tools.map(({ name }) => name)).toEqual(
expect.arrayContaining([
"list_browser_targets",
diff --git a/tests/contractSnapshot.test.ts b/tests/contractSnapshot.test.ts
index dd0111646..4877ad5e4 100644
--- a/tests/contractSnapshot.test.ts
+++ b/tests/contractSnapshot.test.ts
@@ -10,6 +10,7 @@ import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js";
import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js";
import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../src/contracts/applicationToolContracts.js";
import {
enhancedOutputSchemas,
officialOutputSchemas,
@@ -57,8 +58,9 @@ describe("tool contract surface", () => {
...ARTIFACT_TOOL_CONTRACTS,
...BROWSER_TOOL_CONTRACTS,
...ELECTRON_TOOL_CONTRACTS,
+ ...APPLICATION_TOOL_CONTRACTS,
];
- expect(contracts).toHaveLength(62);
+ expect(contracts).toHaveLength(64);
for (const contract of contracts) {
const inputSchema = contractJsonSchema(contract.inputSchema);
const outputSchema = contractJsonSchema(contract.outputSchema);
@@ -148,7 +150,7 @@ describe("tool contract surface", () => {
}
});
- it("publishes no unconstrained output-schema holes across all 80 tools", () => {
+ it("publishes no unconstrained output-schema holes across all 82 tools", () => {
const contracts = [
...OFFICIAL_TOOL_CONTRACTS,
...ENHANCED_TOOL_CONTRACTS,
@@ -156,9 +158,10 @@ describe("tool contract surface", () => {
...ARTIFACT_TOOL_CONTRACTS,
...BROWSER_TOOL_CONTRACTS,
...ELECTRON_TOOL_CONTRACTS,
+ ...APPLICATION_TOOL_CONTRACTS,
...SESSION_TOOL_CONTRACTS,
];
- expect(contracts).toHaveLength(80);
+ expect(contracts).toHaveLength(82);
for (const contract of contracts) {
const schema = contractJsonSchema(contract.outputSchema);
expect(emptySchemaPaths(schema), contract.name).toEqual([]);
diff --git a/tests/fixtures/javascriptArtifactApplication.ts b/tests/fixtures/javascriptArtifactApplication.ts
index 00a6ed5ae..0936b3577 100644
--- a/tests/fixtures/javascriptArtifactApplication.ts
+++ b/tests/fixtures/javascriptArtifactApplication.ts
@@ -123,3 +123,98 @@ export const writeJavaScriptArtifactFixture = async (
),
]);
};
+
+/** Materialize two source-owned rechunked/minified comparison fixtures. */
+export const writeVersionedJavaScriptApplicationFixtures = async (
+ root: string,
+): Promise<{ readonly left: string; readonly right: string }> => {
+ const left = join(root, "version-1");
+ const right = join(root, "version-2");
+ await Promise.all([
+ writeVersionFixture(left, "1.0.0", "left-bundle.js", versionOneBundle()),
+ writeVersionFixture(right, "2.0.0", "right-bundle.js", versionTwoBundle()),
+ ]);
+ return { left, right };
+};
+
+const writeVersionFixture = async (
+ root: string,
+ version: string,
+ bundleName: string,
+ bundle: string,
+): Promise => {
+ await mkdir(join(root, "renderer", "chunks"), { recursive: true });
+ await Promise.all([
+ writeFile(
+ join(root, "package.json"),
+ JSON.stringify({
+ name: "rea-version-comparison-fixture",
+ version,
+ main: "./main.js",
+ renderer: "./renderer/index.html",
+ }),
+ ),
+ writeFile(
+ join(root, "main.js"),
+ 'const { ipcMain } = require("electron"); ipcMain.handle("feature:open", () => require("./native.node"));\n',
+ ),
+ writeFile(
+ join(root, "renderer", "index.html"),
+ ``,
+ ),
+ writeFile(join(root, "renderer", "chunks", bundleName), bundle),
+ writeFile(
+ join(root, "renderer", `${bundleName}.map`),
+ JSON.stringify({
+ version: 3,
+ file: bundleName,
+ sources: ["src/feature.ts"],
+ sourcesContent: [
+ version === "1.0.0"
+ ? 'export const feature = "before";'
+ : 'export const feature = "after";',
+ ],
+ names: [],
+ mappings: "AAAA",
+ }),
+ ),
+ writeFile(
+ join(root, "native.node"),
+ Buffer.from([0x7f, 0x45, 0x4c, 0x46, 0x02, 0x01, 0x01, 0x00]),
+ ),
+ ]);
+};
+
+const versionOneBundle = (): string => `
+ (globalThis.webpackChunkfixture = globalThis.webpackChunkfixture || []).push([
+ [101],
+ {
+ "stable-old": (module, exports) => { exports.stable = () => 42; },
+ "descriptive-name": (module, exports) => {
+ const descriptiveValue = 1;
+ exports.changedName = () => descriptiveValue + 2;
+ },
+ "duplicate-a": (module, exports) => { exports.duplicate = () => 7; },
+ "duplicate-b": (module, exports) => { exports.duplicate = () => 7; },
+ "removed": (module, exports) => { exports.removed = true; }
+ }
+ ]);
+ ${String.fromCharCode(47, 47)}# sourceMap${"ping"}URL=left-bundle.js.map
+`;
+
+const versionTwoBundle = (): string => `
+ (globalThis.webpackChunkfixture = globalThis.webpackChunkfixture || []).push([
+ [909],
+ {
+ "stable-new": (module, exports) => { exports.stable = () => 42; },
+ "a": (module, exports) => {
+ const b = 1;
+ exports.changedName = () => b + 2;
+ },
+ "collision-x": (module, exports) => { exports.duplicate = () => 7; },
+ "collision-y": (module, exports) => { exports.duplicate = () => 7; },
+ "added": (module, exports) => { exports.added = true; }
+ }
+ ]);
+ ${String.fromCharCode(47, 47)}# sourceMap${"ping"}URL=right-bundle.js.map
+`;
diff --git a/tests/integration/serverIntegration.test.ts b/tests/integration/serverIntegration.test.ts
index 453dd7245..74b86d304 100644
--- a/tests/integration/serverIntegration.test.ts
+++ b/tests/integration/serverIntegration.test.ts
@@ -131,7 +131,7 @@ describe("full MCP integration with multi-tool sequences", () => {
});
});
- it("preserves the complete 80-tool inventory with a session", async () => {
+ it("preserves the complete 82-tool inventory with a session", async () => {
const session = new BinarySession(
(_path) =>
({
@@ -154,7 +154,7 @@ describe("full MCP integration with multi-tool sequences", () => {
await client.connect(clientTransport);
const listed = await client.listTools();
- expect(listed.tools).toHaveLength(80);
+ expect(listed.tools).toHaveLength(82);
const names = listed.tools.map((t) => t.name);
expect(names).toContain("open_binary");
expect(names).toContain("close_binary");
diff --git a/tests/javascriptApplicationWorkflows.test.ts b/tests/javascriptApplicationWorkflows.test.ts
new file mode 100644
index 000000000..ed8a3f700
--- /dev/null
+++ b/tests/javascriptApplicationWorkflows.test.ts
@@ -0,0 +1,291 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { analyzeJavaScriptApplication } from "../src/application/JavaScriptApplicationService.js";
+import { compareApplicationVersionsEvidence } from "../src/application/JavaScriptApplicationWorkflowService.js";
+import { createEvidence } from "../src/domain/evidence.js";
+import { applicationVersionComparisonResultSchema } from "../src/domain/javascriptApplicationVersionComparisonSchemas.js";
+import { compareJavaScriptApplicationVersions } from "../src/domain/javascriptApplicationVersionComparison.js";
+import { createJavaScriptApplicationGraph } from "../src/domain/javascriptApplicationGraph.js";
+import { traceApplicationFeature } from "../src/domain/javascriptFeatureTrace.js";
+import { applicationFeatureTraceResultSchema } from "../src/domain/javascriptFeatureTraceSchemas.js";
+import {
+ APPLICATION_GRAPH_DIGESTS,
+ buildSyntheticJavaScriptApplicationGraph,
+} from "./fixtures/javascriptApplicationGraph.js";
+import { writeVersionedJavaScriptApplicationFixtures } from "./fixtures/javascriptArtifactApplication.js";
+import { permissionAuthorityForRoot } from "./fixtures/permissionAuthority.js";
+
+describe("JavaScript application workflows", () => {
+ const temporary: string[] = [];
+
+ afterEach(async () => {
+ await Promise.all(
+ temporary
+ .splice(0)
+ .map(async (path) => rm(path, { recursive: true, force: true })),
+ );
+ });
+
+ it("traces a contextBridge API through IPC into linked native evidence", () => {
+ const graph = buildSyntheticJavaScriptApplicationGraph();
+ const nativeEvidence = createEvidence(
+ {
+ path: "/tmp/synthetic.node",
+ sha256: APPLICATION_GRAPH_DIGESTS.nativeAddon,
+ format: "elf",
+ architecture: "x86_64",
+ },
+ { id: "ghidra", name: "Ghidra", version: "fixture" },
+ {
+ operation: "analyze_function",
+ parameters: { address: "openProject" },
+ result: { name: "openProject", address: "0x1000" },
+ limitations: ["Synthetic native provider observation."],
+ },
+ );
+
+ const result = traceApplicationFeature({
+ sourceEvidenceId: `ev_${"a".repeat(64)}`,
+ graph,
+ nativeEvidence: [nativeEvidence],
+ seed: {
+ kind: "api",
+ value: "desktopApi",
+ match: "exact",
+ case_sensitive: false,
+ },
+ direction: "outgoing",
+ limits: traceLimits(),
+ });
+
+ expect(() =>
+ applicationFeatureTraceResultSchema.parse(result),
+ ).not.toThrow();
+ expect(result.summary).toMatchObject({
+ matched_seeds: 1,
+ native_handoffs: 1,
+ });
+ expect(result.native_handoffs).toContainEqual(
+ expect.objectContaining({
+ artifact_sha256: APPLICATION_GRAPH_DIGESTS.nativeAddon,
+ status: "evidence-linked",
+ evidence_ids: [nativeEvidence.evidence_id],
+ requested_exports: expect.arrayContaining(["openProject"]),
+ }),
+ );
+ expect(result.paths).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ end_kind: "native-export" }),
+ ]),
+ );
+ expect(
+ result.graph?.edges.some(
+ ({ evidence }) =>
+ evidence.authority === "static-relationship-inference" &&
+ evidence.state === "inferred",
+ ),
+ ).toBe(true);
+ });
+
+ it("keeps no-match and bounded frontiers explicit", () => {
+ const graph = buildSyntheticJavaScriptApplicationGraph();
+ const noMatch = traceApplicationFeature({
+ sourceEvidenceId: `ev_${"a".repeat(64)}`,
+ graph,
+ nativeEvidence: [],
+ seed: {
+ kind: "route",
+ value: "/missing",
+ match: "exact",
+ case_sensitive: false,
+ },
+ direction: "both",
+ limits: traceLimits(),
+ });
+ expect(noMatch).toMatchObject({
+ graph: null,
+ coverage: { status: "no-match" },
+ summary: { matched_seeds: 0 },
+ });
+
+ const bounded = traceApplicationFeature({
+ sourceEvidenceId: `ev_${"a".repeat(64)}`,
+ graph,
+ nativeEvidence: [],
+ seed: {
+ kind: "api",
+ value: "desktopApi",
+ match: "exact",
+ case_sensitive: false,
+ },
+ direction: "outgoing",
+ limits: { ...traceLimits(), max_depth: 1 },
+ });
+ expect(bounded.coverage).toMatchObject({ status: "truncated" });
+ expect(bounded.coverage.omitted_nodes).toBeGreaterThan(0);
+ expect(bounded.summary.native_handoffs).toBe(0);
+ });
+
+ it("matches rechunked modules by exact source and minified modules by structural fingerprint", async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-application-versions-"));
+ temporary.push(root);
+ const fixtures = await writeVersionedJavaScriptApplicationFixtures(root);
+ const [left, right] = await Promise.all([
+ analyzeFixture(fixtures.left, true),
+ analyzeFixture(fixtures.right, true),
+ ]);
+ const compared = compareApplicationVersionsEvidence({ left, right });
+ if (!compared.ok) throw compared.error;
+ const result = applicationVersionComparisonResultSchema.parse(
+ compared.value.normalized_result,
+ );
+ const modules = result.items.filter(
+ ({ node_kind: kind }) => kind === "javascript-module",
+ );
+
+ expect(modules).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ match: expect.objectContaining({
+ status: "matched",
+ basis: "exact-module-source-digest",
+ confidence: "exact",
+ }),
+ }),
+ expect.objectContaining({
+ status: "changed",
+ match: expect.objectContaining({
+ status: "matched",
+ basis: "structural-fingerprint",
+ confidence: "medium",
+ }),
+ }),
+ ]),
+ );
+ expect(result.matching.ambiguous).toBeGreaterThanOrEqual(4);
+ expect(modules.filter(({ match }) => match.status === "ambiguous")).toEqual(
+ expect.arrayContaining([expect.objectContaining({ status: "unknown" })]),
+ );
+ expect(result.summary.added).toBeGreaterThan(0);
+ expect(result.summary.removed).toBeGreaterThan(0);
+ expect(result.graph.edges).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ relation: "changed_from",
+ evidence: expect.objectContaining({
+ authority: "cross-version-comparison",
+ state: "inferred",
+ }),
+ }),
+ ]),
+ );
+ expect(result.limitations.join(" ")).toMatch(
+ /module ordinals|fuzzy pairing/u,
+ );
+ });
+
+ it("pairs source-map originals without promoting the match to exact", async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-source-map-versions-"));
+ temporary.push(root);
+ const fixtures = await writeVersionedJavaScriptApplicationFixtures(root);
+ const [left, right] = await Promise.all([
+ analyzeFixture(fixtures.left, true),
+ analyzeFixture(fixtures.right, true),
+ ]);
+ const compared = compareApplicationVersionsEvidence({ left, right });
+ if (!compared.ok) throw compared.error;
+ const result = applicationVersionComparisonResultSchema.parse(
+ compared.value.normalized_result,
+ );
+ expect(result.items).toContainEqual(
+ expect.objectContaining({
+ node_kind: "source-module",
+ status: "changed",
+ match: expect.objectContaining({
+ basis: "source-map-identity",
+ confidence: "high",
+ }),
+ }),
+ );
+ });
+
+ it("keeps incomplete one-sided absence unknown and reports output truncation", () => {
+ const complete = buildSyntheticJavaScriptApplicationGraph();
+ const rootNode = complete.nodes.find(({ node_id: id }) =>
+ complete.root_node_ids.includes(id),
+ );
+ if (rootNode === undefined) throw new Error("Synthetic graph root missing");
+ const partial = createJavaScriptApplicationGraph({
+ schema: "JavaScriptApplicationGraph",
+ schema_version: 1,
+ root_node_ids: [rootNode.node_id],
+ nodes: [rootNode],
+ edges: [],
+ coverage: {
+ status: "partial",
+ truncated: true,
+ omitted_count: complete.nodes.length - 1,
+ limits: [{ name: "fixture_nodes", value: 1, unit: "items" }],
+ },
+ limitations: ["Synthetic partial graph."],
+ });
+ const input = {
+ left: {
+ evidenceId: `ev_${"a".repeat(64)}`,
+ rootArtifactSha256: APPLICATION_GRAPH_DIGESTS.package,
+ graph: complete,
+ },
+ right: {
+ evidenceId: `ev_${"b".repeat(64)}`,
+ rootArtifactSha256: APPLICATION_GRAPH_DIGESTS.package,
+ graph: partial,
+ },
+ leftNativeEvidence: [],
+ rightNativeEvidence: [],
+ limits: {
+ max_comparison_items: 1,
+ max_candidate_nodes: 1,
+ max_graph_nodes: 20,
+ max_graph_edges: 20,
+ },
+ };
+
+ const first = compareJavaScriptApplicationVersions(input);
+ const second = compareJavaScriptApplicationVersions(input);
+ expect(first.comparison_id).toBe(second.comparison_id);
+ expect(first.coverage).toMatchObject({
+ status: "truncated",
+ right_graph_status: "partial",
+ });
+ expect(first.coverage.omitted_comparison_items).toBeGreaterThan(0);
+ expect(first.summary.removed).toBe(0);
+ expect(first.summary.unknown).toBeGreaterThan(0);
+ });
+});
+
+const traceLimits = () => ({
+ max_seed_matches: 25,
+ max_depth: 12,
+ max_nodes: 2_000,
+ max_edges: 4_000,
+ max_paths: 100,
+});
+
+const analyzeFixture = async (root: string, sourceMaps = false) => {
+ const authority = await permissionAuthorityForRoot(
+ root,
+ ["investigation_input"],
+ ["investigation_input"],
+ );
+ const result = await analyzeJavaScriptApplication(authority, {
+ input_path: root,
+ approved: true,
+ source_map_read_approved: sourceMaps,
+ });
+ if (!result.ok) throw result.error;
+ return result.value;
+};
diff --git a/tests/productCatalog.test.ts b/tests/productCatalog.test.ts
index 5eccb4030..70ba2c230 100644
--- a/tests/productCatalog.test.ts
+++ b/tests/productCatalog.test.ts
@@ -10,6 +10,7 @@ import { SUPPORTED_CLIENT_DEFINITIONS } from "../src/application/SupportedClient
import {
ARTIFACT_GRAPH_PROVIDER,
JAVASCRIPT_APPLICATION_PROVIDER,
+ JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER,
JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER,
} from "../src/application/InvestigationProviders.js";
import { CDP_BROWSER_PROVIDER_IDENTITY } from "../src/browser/CdpBrowserProvider.js";
@@ -72,6 +73,7 @@ describe("canonical product catalog", () => {
CDP_ELECTRON_PROVIDER_IDENTITY,
JAVASCRIPT_APPLICATION_PROVIDER,
JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER,
+ JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER,
]
.map(({ id }) => id)
.sort(),
@@ -99,6 +101,11 @@ describe("canonical product catalog", () => {
({ id }) => id === JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER.id,
)?.capabilities,
).toEqual(["reconcile_javascript_runtime"]);
+ expect(
+ catalog.providers.find(
+ ({ id }) => id === JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER.id,
+ )?.capabilities,
+ ).toEqual(["compare_application_versions", "trace_application_feature"]);
expect(
z.toJSONSchema(analysisSnapshotSchema).properties?.snapshot_version,
).toMatchObject({
diff --git a/tests/promptMcp.test.ts b/tests/promptMcp.test.ts
index e086387da..beedf718b 100644
--- a/tests/promptMcp.test.ts
+++ b/tests/promptMcp.test.ts
@@ -54,7 +54,7 @@ describe("guided prompts over MCP", () => {
),
);
}
- expect((await client.listTools()).tools).toHaveLength(80);
+ expect((await client.listTools()).tools).toHaveLength(82);
const result = await client.getPrompt({
name: "investigate_feature",
arguments: {
diff --git a/tests/readmeConsistency.test.ts b/tests/readmeConsistency.test.ts
index 83ee4eb56..e3d6b4d35 100644
--- a/tests/readmeConsistency.test.ts
+++ b/tests/readmeConsistency.test.ts
@@ -12,6 +12,7 @@ import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js";
import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js";
import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../src/contracts/applicationToolContracts.js";
import { SUPPORTED_CLIENT_DEFINITIONS } from "../src/application/SupportedClients.js";
const readmes = [
@@ -29,6 +30,7 @@ const expectedToolCounts = [
ARTIFACT_TOOL_CONTRACTS.length,
BROWSER_TOOL_CONTRACTS.length,
ELECTRON_TOOL_CONTRACTS.length,
+ APPLICATION_TOOL_CONTRACTS.length,
SESSION_TOOL_CONTRACTS.length,
] as const;
diff --git a/tests/runtime.test.ts b/tests/runtime.test.ts
index 1b51d1d53..6b0701c4e 100644
--- a/tests/runtime.test.ts
+++ b/tests/runtime.test.ts
@@ -10,7 +10,7 @@ const fixturePath = fileURLToPath(
);
describe("production stdio runtime", () => {
- it("starts the built entrypoint, lists 80 tools, calls one, and shuts down", async () => {
+ it("starts the built entrypoint, lists 82 tools, calls one, and shuts down", async () => {
const transport = new StdioClientTransport({
command: process.execPath,
args: [mainPath],
@@ -32,7 +32,7 @@ describe("production stdio runtime", () => {
try {
await client.connect(transport);
const tools = await client.listTools();
- expect(tools.tools).toHaveLength(80);
+ expect(tools.tools).toHaveLength(82);
const result = await client.callTool({
name: "current_document",
arguments: {},
@@ -78,7 +78,7 @@ describe("production stdio runtime", () => {
try {
await client.connect(transport);
- expect((await client.listTools()).tools).toHaveLength(80);
+ expect((await client.listTools()).tools).toHaveLength(82);
} finally {
await client.close();
await transport.close();
diff --git a/tests/serverIdentity.test.ts b/tests/serverIdentity.test.ts
index caa1c11c9..3908df070 100644
--- a/tests/serverIdentity.test.ts
+++ b/tests/serverIdentity.test.ts
@@ -24,11 +24,11 @@ describe("server and catalog identity", () => {
});
expect(PRODUCT_IDENTITY.packageVersion).toBe(packageJson.version);
expect(SDK_IDENTITY.server).toBe("2.0.0-beta.4");
- expect(CLI_COMMAND_NAMES).toHaveLength(40);
- expect(new Set(CLI_COMMAND_NAMES).size).toBe(40);
+ expect(CLI_COMMAND_NAMES).toHaveLength(42);
+ expect(new Set(CLI_COMMAND_NAMES).size).toBe(42);
expect(CATALOG_IDENTITY.counts).toEqual({
- cli_commands: 40,
- mcp_tools: 80,
+ cli_commands: 42,
+ mcp_tools: 82,
mcp_prompts: 6,
mcp_resources: 2,
mcp_resource_templates: 7,
@@ -162,7 +162,7 @@ describe("server and catalog identity", () => {
expect(status.structuredContent).toMatchObject({
result: {
server_identity: {
- catalog: { counts: { mcp_tools: 80, cli_commands: 40 } },
+ catalog: { counts: { mcp_tools: 82, cli_commands: 42 } },
alignment: { state: "mcp_server_restart_required" },
},
tool_availability: expect.arrayContaining([
diff --git a/tests/sessionMcp.test.ts b/tests/sessionMcp.test.ts
index 2e2decbf8..3505bdaa0 100644
--- a/tests/sessionMcp.test.ts
+++ b/tests/sessionMcp.test.ts
@@ -142,7 +142,7 @@ describe("target-free MCP lifecycle", () => {
expect(text(before)).toBe(
"No app is open. Ask the user which app to investigate, then call open_binary with its local path.",
);
- expect((await mcp.listTools()).tools).toHaveLength(80);
+ expect((await mcp.listTools()).tools).toHaveLength(82);
const deniedCapture = await mcp.callTool({
name: "capture_process_scenario",
arguments: {
diff --git a/tests/setupSkill.test.ts b/tests/setupSkill.test.ts
index 2477b7231..b3f873c4e 100644
--- a/tests/setupSkill.test.ts
+++ b/tests/setupSkill.test.ts
@@ -31,7 +31,7 @@ describe("canonical skill transaction", () => {
expect(await readFile(`${destination}.rea.backup`, "utf8")).toBe(
"stale managed skill\n",
);
- expect(await readFile(destination, "utf8")).toContain('version: "16"');
+ expect(await readFile(destination, "utf8")).toContain('version: "17"');
expect(await readFile(destination, "utf8")).toContain(
`tool_count: ${String(TOOL_CONTRACTS.length)}`,
);
diff --git a/tests/toolContracts.test.ts b/tests/toolContracts.test.ts
index af1dbd537..df741b227 100644
--- a/tests/toolContracts.test.ts
+++ b/tests/toolContracts.test.ts
@@ -10,9 +10,10 @@ import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.
import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js";
import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../src/contracts/applicationToolContracts.js";
describe("tool contract inventory", () => {
- it("publishes 62 analysis contracts and eighteen session tools", () => {
+ it("publishes 64 analysis contracts and eighteen session tools", () => {
expect(OFFICIAL_TOOL_CONTRACTS).toHaveLength(33);
expect(ENHANCED_TOOL_CONTRACTS).toHaveLength(10);
expect(NATIVE_TOOL_CONTRACTS).toHaveLength(5);
@@ -33,6 +34,10 @@ describe("tool contract inventory", () => {
"analyze_javascript_application",
"reconcile_javascript_runtime",
]);
+ expect(APPLICATION_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([
+ "trace_application_feature",
+ "compare_application_versions",
+ ]);
expect(SESSION_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([
"open_binary",
"close_binary",
@@ -53,8 +58,8 @@ describe("tool contract inventory", () => {
"update_unknown",
"verify_unknown_resolution",
]);
- expect(TOOL_CONTRACTS).toHaveLength(80);
- expect(new Set(TOOL_CONTRACTS.map(({ name }) => name)).size).toBe(80);
+ expect(TOOL_CONTRACTS).toHaveLength(82);
+ expect(new Set(TOOL_CONTRACTS.map(({ name }) => name)).size).toBe(82);
});
it("retains documented enhanced-tool limits at the input boundary", () => {
Create or replace one canonical edge by semantic identifier.