rea-agents 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (343) hide show
  1. package/README.md +23 -17
  2. package/bridge/android/ReaJadxBridge.java +14 -5
  3. package/bridge/ghidra/ReaGhidraBridge.java +173 -47
  4. package/bridge/hopper_bridge.py +310 -128
  5. package/bridge/mitmproxy/capture.py +0 -2
  6. package/bridge/native/rea_lldb_tracer.py +630 -94
  7. package/bridge/process/ProcessRunTokenReader.swift +39 -5
  8. package/bridge/pwntools/recorded_crash_impl.py +4 -0
  9. package/dist/android/JadxConfiguration.js +196 -33
  10. package/dist/android/JadxMcpTransport.js +4 -0
  11. package/dist/android/JadxProtocol.js +6 -0
  12. package/dist/android/JadxProvider.js +19 -2
  13. package/dist/android/JadxSession.js +23 -4
  14. package/dist/application/AnalysisContextQueries.js +8 -35
  15. package/dist/application/AnalysisDocument.js +32 -0
  16. package/dist/application/AppBundleExecutable.js +67 -21
  17. package/dist/application/CallPathTracing.js +19 -3
  18. package/dist/application/CapabilityInventory.js +6 -3
  19. package/dist/application/ClientConfigurationDocument.js +871 -6
  20. package/dist/application/ClientRegistrationIdentity.js +26 -5
  21. package/dist/application/ClientRegistrationStatus.js +29 -14
  22. package/dist/application/DirectAnalysis.js +27 -37
  23. package/dist/application/Doctor.js +4 -2
  24. package/dist/application/DoctorScope.js +25 -13
  25. package/dist/application/EnhancedLiteralTracing.js +22 -25
  26. package/dist/application/EnhancedTools.js +13 -11
  27. package/dist/application/EvidenceBundleFiles.js +23 -11
  28. package/dist/application/FunctionAnalysisEvidence.js +2 -3
  29. package/dist/application/InventoryProjectionEvidence.js +4 -3
  30. package/dist/application/InvestigationProviders.js +3 -2
  31. package/dist/application/JsonFiles.js +50 -28
  32. package/dist/application/ProcedureAddressResolution.js +11 -0
  33. package/dist/application/ReconstructionCoverageService.js +7 -4
  34. package/dist/application/ReconstructionObligationLedgerService.js +4 -3
  35. package/dist/application/Setup.js +13 -1
  36. package/dist/application/SetupClientConfiguration.js +10 -15
  37. package/dist/application/SetupHost.js +5 -2
  38. package/dist/application/SetupPlan.js +5 -3
  39. package/dist/application/SupportedClients.js +34 -1
  40. package/dist/application/Uninstall.js +4 -3
  41. package/dist/application/Update.js +18 -3
  42. package/dist/application/UpdateRuntime.js +46 -25
  43. package/dist/application/WebModuleTraceService.js +4 -2
  44. package/dist/application/WebNetworkCaptureService.js +4 -2
  45. package/dist/application/WebRuntimeService.js +5 -3
  46. package/dist/application/WebScriptExportService.js +2 -2
  47. package/dist/application/WebSourceLocationService.js +4 -2
  48. package/dist/application/WorkflowEvidence.js +82 -0
  49. package/dist/application/binary/AnalysisProviderEvaluation.js +21 -5
  50. package/dist/application/binary/AnalysisProviderRegistry.js +2 -0
  51. package/dist/application/binary/AnalysisSnapshotCache.js +3 -6
  52. package/dist/application/binary/BinarySession.js +95 -68
  53. package/dist/application/binary/BinarySessionOpen.js +3 -3
  54. package/dist/application/binary/BinarySessionRecords.js +25 -3
  55. package/dist/application/binary/BinarySessionStatus.js +17 -1
  56. package/dist/application/binary/CompositeProvider.js +13 -0
  57. package/dist/application/binary/LazyAnalysisProvider.js +3 -0
  58. package/dist/application/binaryDiagnostics/BinaryLayoutService.js +4 -2
  59. package/dist/application/binaryDiagnostics/RecordedCrashService.js +4 -2
  60. package/dist/application/evm/EvmInterfaceService.js +4 -2
  61. package/dist/application/investigation/EvidenceLedger.js +21 -7
  62. package/dist/application/investigation/InvestigationRecords.js +8 -0
  63. package/dist/application/javascript/JavaScriptAnalysisControl.js +34 -0
  64. package/dist/application/javascript/JavaScriptApplicationEvidence.js +24 -3
  65. package/dist/application/javascript/JavaScriptApplicationEvidenceGraph.js +19 -2
  66. package/dist/application/javascript/JavaScriptApplicationService.js +22 -15
  67. package/dist/application/javascript/JavaScriptApplicationWorkflowService.js +5 -5
  68. package/dist/application/javascript/JavaScriptArtifactAnalysis.js +5 -4
  69. package/dist/application/javascript/JavaScriptArtifactGraphBuilder.js +39 -7
  70. package/dist/application/javascript/JavaScriptArtifactPathResolution.js +6 -3
  71. package/dist/application/javascript/JavaScriptArtifactReconstruction.js +11 -3
  72. package/dist/application/javascript/JavaScriptModuleRelationships.js +37 -8
  73. package/dist/application/javascript/JavaScriptRecoveryService.js +4 -2
  74. package/dist/application/javascript/JavaScriptRuntimeObservationService.js +3 -1
  75. package/dist/application/javascript/JavaScriptRuntimeReconciliationService.js +3 -3
  76. package/dist/application/javascript/JavaScriptSemanticGraphBuilder.js +63 -61
  77. package/dist/application/javascript/JavaScriptSemanticGraphValueProjection.js +23 -1
  78. package/dist/application/managed/ManagedApplicationGraphService.js +4 -3
  79. package/dist/application/managed/ManagedMemberComparisonService.js +7 -4
  80. package/dist/application/managed/ManagedNativeVerificationService.js +4 -3
  81. package/dist/application/managed/ManagedReconstructionService.js +4 -3
  82. package/dist/application/process/ProcessCli.js +14 -6
  83. package/dist/application/process/ProcessEvidence.js +4 -3
  84. package/dist/application/workflowInputError.js +18 -0
  85. package/dist/artifacts/ArtifactProvider.js +12 -2
  86. package/dist/artifacts/MachOSliceArtifactReader.js +98 -14
  87. package/dist/artifacts/NativeDmgArtifactReader.js +13 -6
  88. package/dist/artifacts/apple/AppleAssetCatalogAnalysis.js +22 -3
  89. package/dist/artifacts/apple/InterfaceBuilderAnalysis.js +176 -56
  90. package/dist/artifacts/apple/InterfaceBuilderDecodeBudget.js +195 -0
  91. package/dist/artifacts/apple/KeyedArchiveReader.js +36 -22
  92. package/dist/artifacts/apple/MachoLoadCommandReader.js +92 -31
  93. package/dist/artifacts/apple/NibArchive.js +81 -14
  94. package/dist/artifacts/apple/NibViewHierarchy.js +10 -3
  95. package/dist/artifacts/apple/PlistNumberLiterals.js +164 -0
  96. package/dist/artifacts/inventory/ArtifactGraphConstruction.js +13 -8
  97. package/dist/artifacts/inventory/scanCanonical.js +11 -14
  98. package/dist/artifacts/javascript/JavaScriptArtifactFiles.js +6 -2
  99. package/dist/browser/CdpCaptureCompleteness.js +2 -0
  100. package/dist/browser/CdpCaptureEventHandlers.js +76 -11
  101. package/dist/browser/CdpCaptureEventTypes.js +5 -1
  102. package/dist/browser/CdpCaptureEvents.js +25 -0
  103. package/dist/browser/CdpConnection.js +30 -11
  104. package/dist/browser/CdpOptionalCommand.js +2 -3
  105. package/dist/browser/CdpPageCapture.js +23 -1
  106. package/dist/browser/PlaywrightElectronActiveActions.js +32 -23
  107. package/dist/browser/PlaywrightElectronActiveProjection.js +141 -0
  108. package/dist/browser/PlaywrightElectronActiveProvider.js +123 -124
  109. package/dist/browser/WebSourceMapFetcher.js +426 -72
  110. package/dist/browser/assets/LocalWebScriptArtifacts.js +2 -2
  111. package/dist/browser/history/CaptureFailures.js +37 -1
  112. package/dist/browser/history/CaptureRelease.js +5 -0
  113. package/dist/browser/history/HarCaptureAdapter.js +3 -3
  114. package/dist/browser/history/HarJson.js +3 -2
  115. package/dist/browser/history/HistoricalCaptureDecoder.js +4 -2
  116. package/dist/cli/analysisSelector.js +23 -0
  117. package/dist/cli/applicationCommands.js +2 -3
  118. package/dist/cli/coreBinaryCommands.js +70 -12
  119. package/dist/cli/electronCommands.js +7 -6
  120. package/dist/cli/javascriptApplicationAnalysis.js +7 -3
  121. package/dist/cli/jsonOutput.js +4 -99
  122. package/dist/cli/nativeCallCommands.js +2 -3
  123. package/dist/cli/webRuntimeCommands.js +8 -8
  124. package/dist/cli.js +2 -1
  125. package/dist/cliCommandNames.js +0 -1
  126. package/dist/cliJsonInput.js +9 -4
  127. package/dist/config/environment.js +4 -0
  128. package/dist/config/ghidraStartupTimeout.js +17 -0
  129. package/dist/config/mcpResponseBudget.js +22 -0
  130. package/dist/config/parseConfig.js +2 -1
  131. package/dist/contracts/enhancedInputs.js +5 -3
  132. package/dist/contracts/enhancedToolContracts.js +3 -3
  133. package/dist/contracts/hopperMemoryContracts.js +2 -5
  134. package/dist/contracts/javascript/electronToolContracts.js +1 -1
  135. package/dist/contracts/managed/managedToolContracts.js +2 -4
  136. package/dist/contracts/native/nativeToolContracts.js +4 -2
  137. package/dist/contracts/officialToolContracts.js +14 -15
  138. package/dist/contracts/promptContracts.js +3 -3
  139. package/dist/contracts/sessionLifecycleInputs.js +3 -7
  140. package/dist/contracts/sessionStatusContract.js +2 -4
  141. package/dist/contracts/sessionToolContracts.js +4 -6
  142. package/dist/contracts/sessionToolSchemas.js +2 -5
  143. package/dist/contracts/toolContractExamples.js +0 -1
  144. package/dist/contracts/toolContractHelpers.js +4 -1
  145. package/dist/contracts/toolEffects.js +0 -1
  146. package/dist/contracts/toolOutputSchemaGroups.js +28 -27
  147. package/dist/contracts/toolOutputSchemaPrimitives.js +18 -0
  148. package/dist/contracts/toolSchemaMetadata.js +69 -10
  149. package/dist/contracts/webNetworkCaptureToolContracts.js +1 -1
  150. package/dist/domain/analysisErrorBase.js +8 -3
  151. package/dist/domain/analysisErrorCore.js +3 -1
  152. package/dist/domain/analysisErrorPresentation.js +72 -17
  153. package/dist/domain/analysisErrorProjection.js +106 -27
  154. package/dist/domain/android/androidAnalysis.js +2 -4
  155. package/dist/domain/android/androidApplication.js +17 -9
  156. package/dist/domain/apple/appleApplication.js +41 -14
  157. package/dist/domain/apple/dyldEnvironment.js +73 -0
  158. package/dist/domain/apple/dylibResolution.js +120 -9
  159. package/dist/domain/apple/dylibResolutionFindings.js +9 -7
  160. package/dist/domain/apple/interfaceBuilderGraph.js +25 -13
  161. package/dist/domain/apple/interfaceBuilderKeyedArchive.js +13 -3
  162. package/dist/domain/apple/keyedArchive.js +9 -1
  163. package/dist/domain/apple/machoContainer.js +54 -0
  164. package/dist/domain/apple/plistNumbers.js +76 -0
  165. package/dist/domain/artifactIdentity.js +29 -0
  166. package/dist/domain/artifactInventoryEvidence.js +19 -24
  167. package/dist/domain/bridgeCandidateProjection.js +71 -0
  168. package/dist/domain/browserCompleteness.js +1 -0
  169. package/dist/domain/browserObservationError.js +24 -5
  170. package/dist/domain/browserScenarioValues.js +2 -6
  171. package/dist/domain/bundleComparison.js +3 -2
  172. package/dist/domain/canonicalJsonDigestSteps.js +133 -0
  173. package/dist/domain/canonicalOrdering.js +9 -5
  174. package/dist/domain/changedBehavior.js +6 -6
  175. package/dist/domain/comparisonSourceEvidence.js +40 -0
  176. package/dist/domain/configurationErrors.js +1 -1
  177. package/dist/domain/evidence.js +64 -9
  178. package/dist/domain/evidenceBundle.js +42 -1
  179. package/dist/domain/evidenceErrors.js +12 -1
  180. package/dist/domain/explicitSensitiveFailure.js +17 -1
  181. package/dist/domain/firmware/firmwareAnalysis.js +6 -7
  182. package/dist/domain/hopperErrors.js +23 -2
  183. package/dist/domain/hopperValues.js +51 -8
  184. package/dist/domain/immutableJson.js +114 -0
  185. package/dist/domain/inputIssueProjection.js +3 -0
  186. package/dist/domain/javascript/electronActiveObservation.js +30 -4
  187. package/dist/domain/javascript/electronStaticAnalysisValues.js +6 -12
  188. package/dist/domain/javascript/javascriptApplicationAnalysis.js +71 -23
  189. package/dist/domain/javascript/javascriptApplicationGraph.js +13 -0
  190. package/dist/domain/javascript/javascriptAstValues.js +20 -0
  191. package/dist/domain/javascript/javascriptRecovery.js +3 -8
  192. package/dist/domain/javascript/javascriptSemanticAnalysis.js +97 -2
  193. package/dist/domain/javascript/javascriptSemanticCoverage.js +6 -5
  194. package/dist/domain/javascript/javascriptSemanticDataEffectHelpers.js +9 -17
  195. package/dist/domain/javascript/javascriptSemanticDataEffects.js +22 -5
  196. package/dist/domain/javascript/javascriptSemanticGraph.js +13 -0
  197. package/dist/domain/javascript/javascriptSemanticGraphSchemas.js +1 -0
  198. package/dist/domain/javascript/javascriptSemanticPrimitives.js +25 -17
  199. package/dist/domain/javascript/javascriptSemanticQuerySchemas.js +8 -4
  200. package/dist/domain/javascript/javascriptSemanticResourceLimits.js +77 -0
  201. package/dist/domain/javascript/javascriptSemanticValues.js +83 -11
  202. package/dist/domain/javascript/javascriptSourceParser.js +6 -2
  203. package/dist/domain/javascript/javascriptStaticAnalysis.js +22 -17
  204. package/dist/domain/javascript/javascriptStaticAnalysisBundler.js +5 -3
  205. package/dist/domain/javascript/javascriptStaticAnalysisCalls.js +14 -4
  206. package/dist/domain/javascript/javascriptStaticAnalysisFindings.js +66 -7
  207. package/dist/domain/javascript/javascriptStaticAnalysisHelpers.js +28 -16
  208. package/dist/domain/javascript/javascriptStaticAnalysisState.js +3 -2
  209. package/dist/domain/jsonSerialization.js +109 -0
  210. package/dist/domain/jsonValue.js +90 -6
  211. package/dist/domain/localPath.js +6 -0
  212. package/dist/domain/managed/managedApplicationGraph.js +10 -10
  213. package/dist/domain/managed/managedInspectionEvidence.js +16 -0
  214. package/dist/domain/managed/managedMemberComparisonMatch.js +5 -9
  215. package/dist/domain/managed/managedNativeVerification.js +3 -9
  216. package/dist/domain/native/fileOffsetPartialObservation.js +1 -0
  217. package/dist/domain/native/nativeCallObservation.js +33 -11
  218. package/dist/domain/native/nativeCallPartialObservation.js +33 -0
  219. package/dist/domain/process/processCapture.js +8 -4
  220. package/dist/domain/process/processComparison.js +38 -4
  221. package/dist/domain/process/processScenario.js +11 -10
  222. package/dist/domain/propertyListKeys.js +1 -1
  223. package/dist/domain/propertyListXmlText.js +19 -0
  224. package/dist/domain/providerAdapterError.js +1 -1
  225. package/dist/domain/providerOperationHealth.js +54 -0
  226. package/dist/domain/reconstructionVerification.js +6 -43
  227. package/dist/domain/reconstructionVerificationSchemas.js +2 -2
  228. package/dist/domain/staticRuntimeCorrelation.js +6 -43
  229. package/dist/domain/webBundleAnalysis.js +20 -8
  230. package/dist/domain/webBundleAnalyzerInspection.js +13 -8
  231. package/dist/domain/webBundleAnalyzerResult.js +41 -2
  232. package/dist/domain/webRuntime.js +19 -5
  233. package/dist/domain/webSourceLocation.js +1 -0
  234. package/dist/firmware/FirmwareFiles.js +1 -1
  235. package/dist/generatedPackageMetadata.js +1 -1
  236. package/dist/ghidra/GhidraAnalysisProfile.js +5 -0
  237. package/dist/ghidra/GhidraClient.js +47 -14
  238. package/dist/ghidra/GhidraDiagnostics.js +7 -7
  239. package/dist/ghidra/GhidraFunctionValues.js +10 -7
  240. package/dist/ghidra/GhidraInstallation.js +18 -21
  241. package/dist/ghidra/GhidraInventoryValues.js +14 -4
  242. package/dist/ghidra/GhidraJavaLaunch.js +62 -0
  243. package/dist/ghidra/GhidraLauncher.js +33 -16
  244. package/dist/ghidra/GhidraProviderCapabilities.js +14 -2
  245. package/dist/ghidra/GhidraProviderClient.js +23 -12
  246. package/dist/ghidra/GhidraSessionError.js +11 -7
  247. package/dist/ghidra/GhidraTargetSnapshot.js +47 -12
  248. package/dist/ghidra/GhidraTransport.js +20 -0
  249. package/dist/hopper/BridgeLauncher.js +31 -11
  250. package/dist/hopper/HopperAnalysisProfile.js +62 -4
  251. package/dist/hopper/HopperCleanup.js +15 -3
  252. package/dist/hopper/HopperClient.js +222 -14
  253. package/dist/hopper/HopperFileOffset.js +237 -0
  254. package/dist/hopper/HopperMachOImage.js +196 -0
  255. package/dist/hopper/HopperOperationStage.js +6 -0
  256. package/dist/hopper/HopperProvider.js +63 -9
  257. package/dist/hopper/HopperProviderCapabilities.js +19 -1
  258. package/dist/hopper/HopperRegexSearch.js +137 -0
  259. package/dist/hopper/HopperRegexWorker.js +27 -0
  260. package/dist/hopper/HopperRequestQueue.js +68 -19
  261. package/dist/hopper/HopperTargetLease.js +3 -2
  262. package/dist/inspector/JavaScriptRuntimeScope.js +9 -1
  263. package/dist/inspector/V8InspectorCaptureProjection.js +8 -3
  264. package/dist/inspector/V8InspectorProvider.js +47 -11
  265. package/dist/javascript/sourceMaps/DecodedSourceMap.js +47 -0
  266. package/dist/javascript/sourceMaps/SourceMapCommand.js +16 -0
  267. package/dist/javascript/sourceMaps/SourceMapFormat.js +79 -31
  268. package/dist/javascript/sourceMaps/TraceSourceMap.js +14 -28
  269. package/dist/mcpDoctor.js +62 -2
  270. package/dist/native/AppleDispatchCoverage.js +47 -6
  271. package/dist/native/AppleDispatchDecodeFacts.js +6 -0
  272. package/dist/native/AppleDispatchMetadata.js +6 -3
  273. package/dist/native/AppleMachoFixups.js +48 -24
  274. package/dist/native/AppleMachoSelection.js +32 -16
  275. package/dist/native/AppleObjcCategories.js +6 -2
  276. package/dist/native/AppleObjcDispatchFacets.js +5 -2
  277. package/dist/native/AppleObjcProperties.js +2 -1
  278. package/dist/native/AppleSwiftDispatchFacets.js +27 -21
  279. package/dist/native/AppleSwiftVtables.js +21 -15
  280. package/dist/native/CommandRunner.js +81 -84
  281. package/dist/native/LldbCallTracer.js +365 -102
  282. package/dist/native/LldbRetainedObservations.js +178 -0
  283. package/dist/native/NativeCallObservation.js +62 -3
  284. package/dist/native/NativeMacOSProvider.js +98 -17
  285. package/dist/native/SignatureTargetBinding.js +155 -0
  286. package/dist/native/parsers/lipo.js +71 -1
  287. package/dist/native/pwndbg/PwndbgCoreContext.js +25 -5
  288. package/dist/native/pwntools/RecordedCrashStructureBindings.js +2 -0
  289. package/dist/process/DarwinProcessRunTokenReader.js +8 -9
  290. package/dist/process/ExecFileOutput.js +20 -0
  291. package/dist/process/OwnedCommand.js +7 -2
  292. package/dist/process/ProcessOwnership.js +203 -53
  293. package/dist/process/ProcessOwnershipObservation.js +49 -4
  294. package/dist/process/ProviderProcess.js +38 -7
  295. package/dist/process/capture/ProcessCaptureError.js +2 -2
  296. package/dist/process/capture/ProcessCaptureLifecycle.js +100 -34
  297. package/dist/server/EvidenceMcpServer.js +146 -0
  298. package/dist/server/createServer.js +15 -8
  299. package/dist/server/registerAndroidTools.js +2 -4
  300. package/dist/server/registerApplicationTools/helpers.js +2 -4
  301. package/dist/server/registerArtifactComparisonTool.js +11 -7
  302. package/dist/server/registerBinaryDiagnosticsTools.js +2 -4
  303. package/dist/server/registerBrowserScenarioTool.js +2 -4
  304. package/dist/server/registerBrowserTools.js +2 -4
  305. package/dist/server/registerBundleComparisonTool.js +2 -3
  306. package/dist/server/registerCloseLifecycleTool.js +8 -18
  307. package/dist/server/registerElectronTools.js +2 -4
  308. package/dist/server/registerEnhancedTools.js +18 -59
  309. package/dist/server/registerEvidenceTools.js +2 -4
  310. package/dist/server/registerEvmTools.js +2 -4
  311. package/dist/server/registerFirmwareTools.js +2 -4
  312. package/dist/server/registerFunctionComparisonTool.js +10 -6
  313. package/dist/server/registerInvestigationTools.js +7 -7
  314. package/dist/server/registerJavaScriptRecoveryTool.js +2 -4
  315. package/dist/server/registerJavaScriptRuntimeObservationTools.js +2 -4
  316. package/dist/server/registerManagedWorkflowTools/compareManagedMembers.js +2 -4
  317. package/dist/server/registerManagedWorkflowTools/importManagedReconstruction.js +2 -4
  318. package/dist/server/registerManagedWorkflowTools/projectManagedApplicationGraph.js +2 -4
  319. package/dist/server/registerManagedWorkflowTools/verifyManagedNativeBoundaries.js +2 -4
  320. package/dist/server/registerOfficialTools.js +2 -4
  321. package/dist/server/registerProcessComparisonTool.js +71 -45
  322. package/dist/server/registerRecordedCrashTools.js +2 -4
  323. package/dist/server/registerSessionRecordTools.js +5 -6
  324. package/dist/server/registerSessionStatusTool.js +17 -3
  325. package/dist/server/registerSessionTools.js +11 -3
  326. package/dist/server/registerWebModuleTool.js +2 -4
  327. package/dist/server/registerWebNetworkCaptureTool.js +2 -4
  328. package/dist/server/registerWebRuntimeTools.js +3 -7
  329. package/dist/server/registerWebScriptTool.js +2 -4
  330. package/dist/server/registerWebSourceLocationTool.js +2 -4
  331. package/dist/server/runDerivedOperation.js +15 -3
  332. package/dist/server/sessionAvailabilityPolicy.js +0 -1
  333. package/dist/server/toolRegistrationOptions.js +2 -2
  334. package/dist/server/toolResult.js +62 -10
  335. package/dist/server/toolResultEncoding.js +33 -0
  336. package/install.sh +1 -1
  337. package/native/windows/build/manifest.json +1 -1
  338. package/package.json +8 -3
  339. package/scripts/electron-active-hook-boundaries.cjs +18 -20
  340. package/scripts/electron-active-hook.cjs +241 -37
  341. package/skills/reverse-engineer-anything/SKILL.md +11 -3
  342. package/skills/reverse-engineer-anything/references/javascript-applications.md +8 -1
  343. package/dist/ghidra/GhidraDefaults.js +0 -2
@@ -1,7 +1,9 @@
1
1
  import { z } from "zod";
2
2
  import { digestCanonicalValue } from "./canonicalDigest.js";
3
+ import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
3
4
  import { analysisProfileSchema, } from "./analysisProfile.js";
4
- import { jsonValueSchema } from "./jsonValue.js";
5
+ import { jsonObjectSchema, jsonValueSchema, jsonValueValidationIssue, jsonValueValidationSteps, } from "./jsonValue.js";
6
+ import { freezeJsonSnapshot, isImmutableJsonSnapshot, } from "./immutableJson.js";
5
7
  import { digestSchema } from "./../domain/digests.js";
6
8
  import { prefixedDigestSchema } from "./../domain/digests.js";
7
9
  /** Provider identity schema shared by evidence-bearing persistence formats. */
@@ -79,7 +81,7 @@ const evidenceBaseSchema = z
79
81
  provider: providerSchema,
80
82
  predicate_type: z.string().min(1),
81
83
  operation: z.string().min(1),
82
- parameters: z.record(z.string(), jsonValueSchema),
84
+ parameters: jsonObjectSchema,
83
85
  raw_result: jsonValueSchema.nullable(),
84
86
  normalized_result: jsonValueSchema,
85
87
  confidence: z.enum(["observed", "derived", "inferred"]),
@@ -116,6 +118,14 @@ export const evidenceRecordSchema = z.union([
116
118
  profiledEvidenceSchema,
117
119
  evidenceBaseSchema,
118
120
  ]);
121
+ const immutableEvidenceSnapshots = new WeakMap();
122
+ const immutableResultSchema = z
123
+ .custom(isImmutableJsonSnapshot)
124
+ .superRefine((value, context) => {
125
+ const issue = jsonValueValidationIssue(value);
126
+ if (issue !== undefined)
127
+ context.addIssue({ code: "custom", message: issue });
128
+ });
119
129
  const semanticProjection = (evidence) => ({
120
130
  subject: evidence.subject === null
121
131
  ? null
@@ -140,18 +150,60 @@ const semanticProjection = (evidence) => ({
140
150
  locations: evidence.locations,
141
151
  evidence_links: evidence.evidence_links,
142
152
  });
143
- /** Recompute the semantic identifier, excluding paths and raw payload bytes. */
153
+ /** Hash semantic content, including raw results and excluding display-subject fields. */
144
154
  const computeEvidenceId = (evidence) => `ev_${digestCanonicalValue(semanticProjection(evidence), "Evidence")}`;
145
155
  /** Parse evidence and reject a syntactically valid but tampered semantic ID. */
146
156
  export const parseEvidence = (input) => {
147
- const evidence = evidenceRecordSchema.parse(input);
157
+ const immutable = typeof input === "object" && input !== null
158
+ ? immutableEvidenceSnapshots.get(input)
159
+ : undefined;
160
+ if (immutable !== undefined)
161
+ return immutable;
162
+ // Select the producer's envelope before traversing its payload. A legacy
163
+ // record cannot satisfy the required-profile branch, whose failed parse
164
+ // would otherwise clone the entire normalized result before trying legacy.
165
+ const schema = typeof input === "object" && input !== null && "analysis_profile" in input
166
+ ? profiledEvidenceSchema
167
+ : evidenceBaseSchema;
168
+ const evidence = schema.parse(input);
148
169
  const { evidence_id: evidenceId, ...withoutId } = evidence;
149
170
  if (computeEvidenceId(withoutId) !== evidenceId)
150
171
  throw new TypeError("Evidence semantic identifier does not match its record");
151
172
  return evidence;
152
173
  };
174
+ /** Authenticate and seal a ledger-owned snapshot; external mutable values are copied first. */
175
+ export const immutableEvidence = (input) => rememberImmutableEvidence(parseEvidence(input));
176
+ /** Recognize authenticated Evidence whose complete reachable JSON data is immutable. */
177
+ export const isImmutableEvidence = (evidence) => immutableEvidenceSnapshots.has(evidence);
178
+ const rememberImmutableEvidence = (evidence) => {
179
+ freezeJsonSnapshot(evidence);
180
+ immutableEvidenceSnapshots.set(evidence, evidence);
181
+ return evidence;
182
+ };
153
183
  /** Build deterministic Evidence from an immutable artifact subject. */
154
184
  export const createEvidence = (target, provider, observation) => {
185
+ const { normalized, sharedResult } = normalizeEvidenceObservation(target, provider, observation);
186
+ const evidence = {
187
+ ...normalized,
188
+ evidence_id: computeEvidenceId(normalized),
189
+ };
190
+ return sharedResult ? rememberImmutableEvidence(evidence) : evidence;
191
+ };
192
+ /** Create Evidence from owned immutable JSON while exposing cooperative computation steps. */
193
+ export function* createImmutableEvidenceSteps(target, provider, observation) {
194
+ if (!isImmutableJsonSnapshot(observation.result))
195
+ throw new TypeError("Cooperative Evidence requires an authenticated immutable result");
196
+ // The envelope parser below retains its usual diagnostics, using the completed
197
+ // immutable validation rather than traversing the payload synchronously again.
198
+ yield* jsonValueValidationSteps(observation.result);
199
+ const { normalized } = normalizeEvidenceObservation(target, provider, observation);
200
+ const digest = yield* canonicalJsonDigestSteps(semanticProjection(normalized));
201
+ return rememberImmutableEvidence({
202
+ ...normalized,
203
+ evidence_id: `ev_${digest}`,
204
+ });
205
+ }
206
+ const normalizeEvidenceObservation = (target, provider, observation) => {
155
207
  const subject = target === undefined
156
208
  ? null
157
209
  : {
@@ -203,7 +255,13 @@ export const createEvidence = (target, provider, observation) => {
203
255
  const schema = observation.analysisProfile === undefined
204
256
  ? evidenceBaseSchema
205
257
  : profiledEvidenceSchema;
206
- const normalized = schema.parse({
258
+ const sharedResult = typeof observation.result === "object" &&
259
+ observation.result !== null &&
260
+ isImmutableJsonSnapshot(observation.result);
261
+ const selectedSchema = sharedResult
262
+ ? schema.safeExtend({ normalized_result: immutableResultSchema })
263
+ : schema;
264
+ const normalized = selectedSchema.parse({
207
265
  ...semantic,
208
266
  evidence_id: `ev_${"0".repeat(64)}`,
209
267
  subject,
@@ -211,8 +269,5 @@ export const createEvidence = (target, provider, observation) => {
211
269
  // The envelope has already been parsed into an independent snapshot. Only
212
270
  // its derived identifier changes here; parsing again clones the full payload
213
271
  // and recomputes the same digest while the previous snapshot is still live.
214
- return {
215
- ...normalized,
216
- evidence_id: computeEvidenceId(normalized),
217
- };
272
+ return { normalized, sharedResult };
218
273
  };
@@ -1,7 +1,8 @@
1
1
  import { z } from "zod";
2
2
  import canonicalize from "canonicalize";
3
- import { evidenceEnvelopeSchema, evidenceRecordSchema, parseEvidence, providerSchema, } from "./evidence.js";
3
+ import { evidenceEnvelopeSchema, evidenceRecordSchema, immutableEvidence, parseEvidence, providerSchema, } from "./evidence.js";
4
4
  import { residualUnknownSchema, } from "./residualUnknown.js";
5
+ import { freezeJsonSnapshot } from "./immutableJson.js";
5
6
  const artifactManifestSchema = evidenceEnvelopeSchema.shape.subject
6
7
  .unwrap()
7
8
  .pick({
@@ -29,6 +30,19 @@ export const evidenceBundleSchema = z.object({
29
30
  unknowns: z.array(residualUnknownSchema),
30
31
  records: z.array(evidenceRecordSchema),
31
32
  });
33
+ const immutableBundles = new WeakMap();
34
+ /** Build and authenticate a sealed bundle while reusing immutable Evidence records. */
35
+ export const createImmutableEvidenceBundle = (records, unknowns = []) => {
36
+ const checkedRecords = records.map(immutableEvidence);
37
+ if (new Set(checkedRecords.map(({ evidence_id }) => evidence_id)).size !==
38
+ checkedRecords.length)
39
+ throw new TypeError("Evidence bundle contains duplicate record IDs");
40
+ const checkedUnknowns = unknowns.map((unknown) => residualUnknownSchema.parse(unknown));
41
+ validateUnknownGraph(checkedUnknowns, checkedRecords);
42
+ const bundle = freezeJsonSnapshot(createEvidenceBundle(checkedRecords, checkedUnknowns));
43
+ immutableBundles.set(bundle, bundle);
44
+ return bundle;
45
+ };
32
46
  /** Project records into a deterministic bundle whose order has no semantics. */
33
47
  export const createEvidenceBundle = (records, unknowns = []) => {
34
48
  const sortedRecords = [...records].sort((left, right) => left.evidence_id.localeCompare(right.evidence_id));
@@ -120,8 +134,35 @@ const referencedEvidenceIds = (unknown) => [
120
134
  ...unknown.mutation_evidence_ids,
121
135
  ...(unknown.resolution?.evidence_ids ?? []),
122
136
  ];
137
+ /**
138
+ * Name the bundle constraint that failed and how to recover. A single
139
+ * Evidence record, such as one command result, is not a bundle.
140
+ */
141
+ export const describeEvidenceBundleFailure = (input, cause) => {
142
+ const record = evidenceRecordSchema.safeParse(input);
143
+ if (record.success)
144
+ return `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.data.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`;
145
+ return cause instanceof z.ZodError
146
+ ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
147
+ : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`;
148
+ };
149
+ /** Locate the first schema issue, or keep a thrown constraint message. */
150
+ export const describeValidationFailure = (cause) => {
151
+ if (!(cause instanceof z.ZodError))
152
+ return cause instanceof Error ? cause.message : String(cause);
153
+ const [first, ...rest] = cause.issues;
154
+ const location = first === undefined || first.path.length === 0
155
+ ? "the document root"
156
+ : first.path.map(String).join(".");
157
+ return `at ${location}: ${first?.message ?? "invalid value"}${rest.length === 0 ? "" : ` (${String(rest.length)} more issues)`}`;
158
+ };
123
159
  /** Parse records, verify semantic IDs, and reject inconsistent manifests. */
124
160
  export const parseEvidenceBundle = (input) => {
161
+ if (typeof input === "object" && input !== null) {
162
+ const owned = immutableBundles.get(input);
163
+ if (owned !== undefined)
164
+ return owned;
165
+ }
125
166
  const parsed = evidenceBundleSchema.parse(input);
126
167
  const recordIds = parsed.records.map(({ evidence_id: id }) => id);
127
168
  if (new Set(recordIds).size !== recordIds.length)
@@ -1,7 +1,15 @@
1
- import { AnalysisError } from "./analysisErrorBase.js";
1
+ import { AnalysisError, } from "./analysisErrorBase.js";
2
2
  /** Evidence identity, schema, or bundle manifests failed integrity checks. */
3
3
  export class EvidenceIntegrityError extends AnalysisError {
4
4
  _tag = "EvidenceIntegrityError";
5
+ userMessage;
6
+ constructor(message, options) {
7
+ super(message, options);
8
+ this.userMessage = options?.userMessage;
9
+ }
10
+ }
11
+ /** A valid snapshot belongs to a different target, provider, or analysis profile. */
12
+ export class AnalysisSnapshotMismatchError extends EvidenceIntegrityError {
5
13
  }
6
14
  /** A session Evidence reference is missing or has the wrong semantic identity. */
7
15
  export class EvidenceReferenceError extends EvidenceIntegrityError {
@@ -22,9 +30,12 @@ export class EvidenceFileError extends AnalysisError {
22
30
  operation;
23
31
  reason;
24
32
  _tag = "EvidenceFileError";
33
+ /** Caller-selected path that failed, resolved against the working directory. */
34
+ path;
25
35
  constructor(operation, reason, options) {
26
36
  super(`Evidence bundle ${operation} failed: ${reason}`, options);
27
37
  this.operation = operation;
28
38
  this.reason = reason;
39
+ this.path = options?.path;
29
40
  }
30
41
  }
@@ -1,4 +1,4 @@
1
- import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisCapabilityUnavailableError, } from "./analysisErrorCore.js";
1
+ import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisCapabilityUnavailableError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
2
2
  import { redactExplicitText } from "./explicitSensitiveValues.js";
3
3
  import { ProviderAdapterError } from "./providerAdapterError.js";
4
4
  import { ProviderCleanupError } from "./providerCleanupError.js";
@@ -79,6 +79,22 @@ export const redactExplicitFailure = (error, values) => {
79
79
  ? {}
80
80
  : { userMessage: text(error.userMessage) }),
81
81
  });
82
+ if (error instanceof AnalysisResourceConstraintError)
83
+ return new AnalysisResourceConstraintError(error.operation, error.resource, text(error.reason), error.reportedLimits === null ? null : diagnostics(error.reportedLimits), {
84
+ cause: error,
85
+ ...(error.remediationAction === undefined
86
+ ? {}
87
+ : { remediationAction: text(error.remediationAction) }),
88
+ ...(error.capturedOutput === undefined
89
+ ? {}
90
+ : {
91
+ capturedOutput: {
92
+ stdout: text(error.capturedOutput.stdout),
93
+ stderr: text(error.capturedOutput.stderr),
94
+ truncated: error.capturedOutput.truncated,
95
+ },
96
+ }),
97
+ });
82
98
  if (error instanceof ProviderCleanupError)
83
99
  return new ProviderCleanupError(error.providerId, error.cleanupResources.map(text), diagnostics(error.diagnostics ?? {}), { operation: error.operation, cause: error });
84
100
  if (error instanceof ProviderAdapterError)
@@ -1,13 +1,11 @@
1
1
  import { z } from "zod";
2
2
  import { digestSchema } from "../digests.js";
3
3
  import { jsonValueSchema } from "../jsonValue.js";
4
- import { isAbsoluteLocalPath } from "../localPath.js";
4
+ import { isAbsoluteLocalPath, localPathStringSchema } from "../localPath.js";
5
5
  const bytes = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
6
6
  const range = z.strictObject({ offset: bytes, length: bytes.positive() });
7
7
  const target = {
8
- path: z
9
- .string()
10
- .min(1)
8
+ path: localPathStringSchema
11
9
  .refine(isAbsoluteLocalPath, {
12
10
  message: "path must be an absolute local filesystem path (for example /tmp/firmware.bin or C:\\firmware\\firmware.bin)",
13
11
  })
@@ -18,9 +16,10 @@ export const firmwareInputSchemas = {
18
16
  inspect_firmware_regions: z.strictObject(target),
19
17
  extract_firmware: z.strictObject({
20
18
  ...target,
21
- output_directory: z
22
- .string()
23
- .min(1)
19
+ output_directory: localPathStringSchema
20
+ .refine(isAbsoluteLocalPath, {
21
+ message: "output_directory must be an absolute local filesystem path",
22
+ })
24
23
  .describe("Absolute, absent output directory; parent must exist"),
25
24
  range: range
26
25
  .optional()
@@ -9,13 +9,19 @@ export class HopperTimeoutError extends HopperError {
9
9
  operation;
10
10
  requestId;
11
11
  providerState;
12
+ stage;
13
+ launcherOutcome;
12
14
  _tag = "HopperTimeoutError";
13
- constructor(timeoutMs, operation, requestId, providerState = "not_started") {
15
+ constructor(timeoutMs, operation, requestId, providerState = "not_started", stage = operation === undefined
16
+ ? "launch"
17
+ : "analysis", launcherOutcome) {
14
18
  super(`Hopper ${operation === undefined ? "startup" : operation} timed out after ${String(timeoutMs)}ms`);
15
19
  this.timeoutMs = timeoutMs;
16
20
  this.operation = operation;
17
21
  this.requestId = requestId;
18
22
  this.providerState = providerState;
23
+ this.stage = stage;
24
+ this.launcherOutcome = launcherOutcome;
19
25
  }
20
26
  }
21
27
  /** The caller cancelled a Hopper operation before it completed. */
@@ -51,18 +57,31 @@ export class HopperProcessError extends HopperError {
51
57
  diagnostic;
52
58
  operation;
53
59
  requestId;
60
+ launcherFailure;
54
61
  _tag = "HopperProcessError";
55
62
  failureCode;
56
63
  userMessage;
57
- constructor(exitCode, diagnostic, operation, requestId) {
64
+ providerState;
65
+ stage;
66
+ constructor(exitCode, diagnostic, operation, requestId, providerState, stage, launcherFailure) {
58
67
  super(`Hopper bridge stopped unexpectedly with code ${String(exitCode)}`);
59
68
  this.exitCode = exitCode;
60
69
  this.diagnostic = diagnostic;
61
70
  this.operation = operation;
62
71
  this.requestId = requestId;
72
+ this.launcherFailure = launcherFailure;
63
73
  const failure = hopperStartupFailure(exitCode);
74
+ this.stage =
75
+ stage ??
76
+ (failure === undefined
77
+ ? operation === undefined
78
+ ? "connection"
79
+ : "analysis"
80
+ : "launch");
64
81
  this.failureCode = failure?.code;
65
82
  this.userMessage = failure?.message;
83
+ this.providerState =
84
+ providerState ?? (exitCode === null ? "unknown" : "exited");
66
85
  }
67
86
  }
68
87
  /** Hopper or the repository bridge could not be started. */
@@ -70,9 +89,11 @@ export class HopperStartError extends HopperError {
70
89
  _tag = "HopperStartError";
71
90
  userMessage;
72
91
  ownerRunId;
92
+ launcherFailure;
73
93
  constructor(options) {
74
94
  super("Hopper application bridge could not be started", options);
75
95
  this.userMessage = options?.userMessage;
76
96
  this.ownerRunId = options?.ownerRunId;
97
+ this.launcherFailure = options?.launcherFailure;
77
98
  }
78
99
  }
@@ -39,6 +39,34 @@ const segmentSchema = z.object({
39
39
  const unavailableAnalysisFactSchema = z
40
40
  .object({ available: z.literal(false), reason: z.string() })
41
41
  .strict();
42
+ /** Typed string evidence shared by inventories and referenced function literals. */
43
+ export const analysisStringSchema = z.object({
44
+ address: z.string(),
45
+ value: z.string(),
46
+ provider_value: z
47
+ .string()
48
+ .exactOptional()
49
+ .describe("Original provider display text, which may shorten the typed object."),
50
+ decoding: unavailableAnalysisFactSchema
51
+ .exactOptional()
52
+ .describe("When present, value retains native display text because typed bytes could not be decoded."),
53
+ string: z
54
+ .object({
55
+ encoding: z.string().min(1),
56
+ encoding_status: z
57
+ .enum(["observed", "inferred"])
58
+ .exactOptional()
59
+ .describe("Whether the provider declares the encoding or REA infers it from the typed bytes and native display. This does not establish the original source's intended encoding."),
60
+ termination: z.enum(["missing", "present_or_not_required"]),
61
+ byte_length: z.number().int().min(0),
62
+ })
63
+ .exactOptional(),
64
+ });
65
+ /** An analyzed bookmark retains a missing provider label as null. */
66
+ export const analysisBookmarkSchema = z.strictObject({
67
+ address: z.string(),
68
+ name: z.string().nullable(),
69
+ });
42
70
  /** Complete observed function-body ranges; every range endpoint is inclusive. */
43
71
  export const functionBodySchema = z.discriminatedUnion("available", [
44
72
  unavailableAnalysisFactSchema,
@@ -163,6 +191,13 @@ export const localVariableSchema = z
163
191
  .object({
164
192
  description: z.string(),
165
193
  provenance: z.string().min(1),
194
+ name: z.string().nullable().exactOptional(),
195
+ stack_displacement: z
196
+ .string()
197
+ .regex(/^-?\d+$/u)
198
+ .nullable()
199
+ .exactOptional()
200
+ .describe("Observed signed stack byte displacement, encoded as decimal to preserve precision."),
166
201
  })
167
202
  .strict();
168
203
  /** Provider-neutral complete raw-instruction list for one analyzed function. */
@@ -197,13 +232,26 @@ export const referenceKindSchema = z.discriminatedUnion("available", [
197
232
  unavailableAnalysisFactSchema,
198
233
  availableReferenceKindSchema,
199
234
  ]);
200
- const referenceEdgeSchema = z
235
+ /** Reported call sites without resolved targets; unreported dispatch stays unknown. */
236
+ export const unresolvedCallSchema = z.strictObject({
237
+ address: z.string(),
238
+ reason: z.string(),
239
+ });
240
+ /** Observed endpoints with complete or partial reference classification evidence. */
241
+ export const referenceEdgeSchema = z
201
242
  .object({
202
243
  source_address: z.string(),
203
244
  target_address: z.string(),
204
245
  source_procedure: procedureIdentitySchema.nullable(),
205
246
  target_procedure: procedureIdentitySchema.nullable(),
206
247
  kind: referenceKindSchema,
248
+ call: z
249
+ .strictObject({
250
+ classification: z.enum(["none", "unknown", "direct", "objective_c"]),
251
+ provider_type: z.number().int(),
252
+ provenance: z.string().min(1),
253
+ })
254
+ .exactOptional(),
207
255
  })
208
256
  .strict();
209
257
  export const functionDossierSchema = z
@@ -225,13 +273,8 @@ export const functionDossierSchema = z
225
273
  callees: z.array(procedureIdentitySchema),
226
274
  incoming_references: z.array(referenceEdgeSchema),
227
275
  outgoing_references: z.array(referenceEdgeSchema),
228
- referenced_strings: z.array(z
229
- .object({
230
- address: z.string(),
231
- value: z.string(),
232
- source_address: z.string(),
233
- })
234
- .strict()),
276
+ unresolved_calls: z.array(unresolvedCallSchema).exactOptional(),
277
+ referenced_strings: z.array(analysisStringSchema.extend({ source_address: z.string() })),
235
278
  referenced_names: z.array(z
236
279
  .object({
237
280
  address: z.string(),
@@ -0,0 +1,114 @@
1
+ const immutableSnapshots = new WeakSet();
2
+ /** Recognize an owned JSON snapshot sealed by this module, or an immutable scalar. */
3
+ export const isImmutableJsonSnapshot = (value) => value === null ||
4
+ typeof value === "string" ||
5
+ typeof value === "boolean" ||
6
+ (typeof value === "number" && Number.isFinite(value)) ||
7
+ (typeof value === "object" && immutableSnapshots.has(value));
8
+ /** Seal an already parsed, owned JSON snapshot for immutable zero-copy reuse. */
9
+ export const freezeJsonSnapshot = (value) => {
10
+ const pending = [{ value, exiting: false }];
11
+ // These sets exist only during traversal, while the owned root already
12
+ // retains every child. Strong sets avoid per-node ephemeron GC work.
13
+ const visited = new Set();
14
+ const ancestors = new Set();
15
+ const objects = [];
16
+ while (pending.length > 0) {
17
+ const entry = pending.pop();
18
+ if (entry === undefined)
19
+ break;
20
+ const item = entry.value;
21
+ if (entry.exiting && typeof item === "object" && item !== null) {
22
+ ancestors.delete(item);
23
+ visited.add(item);
24
+ objects.push(item);
25
+ continue;
26
+ }
27
+ if (isImmutableJsonSnapshot(item))
28
+ continue;
29
+ if (typeof item !== "object" || item === null)
30
+ throw new TypeError("Immutable JSON snapshots require JSON values");
31
+ if (ancestors.has(item))
32
+ throw new TypeError("Immutable JSON snapshots cannot contain circular references");
33
+ if (visited.has(item))
34
+ continue;
35
+ ancestors.add(item);
36
+ pending.push({ value: item, exiting: true });
37
+ pushSnapshotChildren(item, pending);
38
+ }
39
+ // Register only after every value is checked and every object is frozen.
40
+ // An arbitrary Object.freeze call cannot forge this snapshot identity.
41
+ for (const item of objects)
42
+ Object.freeze(item);
43
+ // Register the requested root, rather than retaining weak entries for every
44
+ // nested object. Sealing an Evidence or bundle skips previously sealed roots.
45
+ if (typeof value === "object" && value !== null)
46
+ immutableSnapshots.add(value);
47
+ return value;
48
+ };
49
+ /**
50
+ * Seal exclusively owned JSON in bounded steps, authenticating only completion.
51
+ * Abandonment or failure can leave the provisional input partly frozen.
52
+ */
53
+ export function* freezeOwnedJsonSnapshotSteps(value) {
54
+ const pending = [{ value, exiting: false }];
55
+ const visited = new Set();
56
+ const ancestors = new Set();
57
+ let examined = 0;
58
+ try {
59
+ while (pending.length > 0) {
60
+ if (examined++ === 4096) {
61
+ examined = 0;
62
+ yield;
63
+ }
64
+ const entry = pending.pop();
65
+ if (entry === undefined)
66
+ break;
67
+ const item = entry.value;
68
+ if (entry.exiting && typeof item === "object" && item !== null) {
69
+ ancestors.delete(item);
70
+ visited.add(item);
71
+ continue;
72
+ }
73
+ if (isImmutableJsonSnapshot(item))
74
+ continue;
75
+ if (typeof item !== "object" || item === null)
76
+ throw new TypeError("Immutable JSON snapshots require JSON values");
77
+ if (ancestors.has(item))
78
+ throw new TypeError("Immutable JSON snapshots cannot contain circular references");
79
+ if (visited.has(item))
80
+ continue;
81
+ ancestors.add(item);
82
+ pending.push({ value: item, exiting: true });
83
+ pushSnapshotChildren(item, pending);
84
+ // Lock every inspected edge before the scheduler can release control.
85
+ Object.freeze(item);
86
+ }
87
+ if (typeof value === "object" && value !== null)
88
+ immutableSnapshots.add(value);
89
+ return value;
90
+ }
91
+ finally {
92
+ pending.length = 0;
93
+ visited.clear();
94
+ ancestors.clear();
95
+ }
96
+ }
97
+ const pushSnapshotChildren = (item, pending) => {
98
+ const prototype = Object.getPrototypeOf(item);
99
+ if (!Array.isArray(item) &&
100
+ prototype !== Object.prototype &&
101
+ prototype !== null)
102
+ throw new TypeError("Immutable JSON snapshots require ordinary objects");
103
+ if (Array.isArray(item))
104
+ for (let index = 0; index < item.length; index += 1)
105
+ if (!Object.hasOwn(item, index))
106
+ throw new TypeError("Immutable JSON snapshots cannot contain sparse arrays");
107
+ for (const key of Object.getOwnPropertyNames(item)) {
108
+ const descriptor = Object.getOwnPropertyDescriptor(item, key);
109
+ if (descriptor === undefined || !Object.hasOwn(descriptor, "value"))
110
+ throw new TypeError("Immutable JSON snapshots cannot contain accessors");
111
+ const child = descriptor.value;
112
+ pending.push({ value: child, exiting: false });
113
+ }
114
+ };
@@ -1,3 +1,6 @@
1
+ import { AnalysisInputError, } from "./analysisErrorCore.js";
2
+ /** Build the standard application input error while retaining schema causes and extra semantic issues. */
3
+ export const analysisInputErrorFromIssues = (operation, issues, input, options = {}) => new AnalysisInputError(operation, options.cause === undefined ? undefined : { cause: options.cause }, [...projectInputIssues(issues, input), ...(options.additionalIssues ?? [])]);
1
4
  /** Project Zod failures to secret-safe caller correction metadata. */
2
5
  export const projectInputIssues = (issues, input) => issues.flatMap((issue) => projectIssue(issue, input));
3
6
  const projectIssue = (issue, input) => {
@@ -1,6 +1,6 @@
1
1
  import { z } from "zod";
2
- import { isAbsoluteLocalPath } from "../localPath.js";
3
- const pathInputSchema = z.string().trim().min(1).refine(isAbsoluteLocalPath, {
2
+ import { isAbsoluteLocalPath, localPathStringSchema } from "../localPath.js";
3
+ const pathInputSchema = localPathStringSchema.refine(isAbsoluteLocalPath, {
4
4
  message: "Electron executable, application, and root paths must be absolute local filesystem paths (for example /Applications/Electron.app/Contents/MacOS/Electron)",
5
5
  });
6
6
  const absolutePathSchema = z
@@ -60,7 +60,9 @@ export const electronActiveObservationInputSchema = z.strictObject({
60
60
  application_root: pathInputSchema
61
61
  .optional()
62
62
  .describe("Absolute local filesystem root for application-relative paths; omit to derive it from the application path. Relative paths are rejected."),
63
- args: z.array(z.string()).default([]),
63
+ args: z
64
+ .array(z.string().regex(/^[^\0]*$/u, "Electron arguments must not contain NUL"))
65
+ .default([]),
64
66
  actions: z.array(actionSchema).default([]),
65
67
  });
66
68
  const ipcEventSchema = z.strictObject({
@@ -235,13 +237,37 @@ export const electronActiveObservationResultSchema = z.strictObject({
235
237
  ipc: z.strictObject({
236
238
  events: z.array(ipcEventSchema),
237
239
  observed: z.number().int().min(0),
240
+ dropped: z.number().int().min(0).nullable().default(null),
238
241
  }),
239
242
  timeline: z
240
243
  .strictObject({
241
244
  events: z.array(timelineEventSchema),
242
245
  observed: z.number().int().min(0),
246
+ dropped: z.number().int().min(0).nullable().default(null),
243
247
  })
244
- .default({ events: [], observed: 0 }),
248
+ .default({ events: [], observed: 0, dropped: null }),
249
+ retention: z
250
+ .strictObject({
251
+ budget_bytes: z.number().int().min(0),
252
+ estimated_retained_bytes: z.number().int().min(0),
253
+ event_serialized_byte_upper_bound: z.number().int().min(0),
254
+ retained: z.number().int().min(0),
255
+ dropped: z.number().int().min(0),
256
+ dropped_event_families: z.array(z.strictObject({
257
+ family: z.string().min(1),
258
+ count: z.number().int().min(1),
259
+ })),
260
+ dropped_event_roles: z.array(z.strictObject({
261
+ role: z.string().min(1),
262
+ count: z.number().int().min(1),
263
+ })),
264
+ observed_ipc: z.number().int().min(0),
265
+ dropped_ipc: z.number().int().min(0),
266
+ observed_runtime: z.number().int().min(0),
267
+ dropped_runtime: z.number().int().min(0),
268
+ })
269
+ .nullable()
270
+ .default(null),
245
271
  coverage: coverageSchema.default({
246
272
  status: "partial_attach",
247
273
  observed_event_families: [],
@@ -1,6 +1,6 @@
1
1
  import * as t from "@babel/types";
2
2
  import { compareCodePoints } from "../canonicalOrdering.js";
3
- import { semanticStaticPropertyName } from "./javascriptAstValues.js";
3
+ import { readExactJavaScriptLiteral, semanticStaticPropertyName, } from "./javascriptAstValues.js";
4
4
  import { sourceSlice } from "./javascriptStaticAnalysisHelpers.js";
5
5
  /** Preserve one literal value or the exact inert expression. */
6
6
  export const electronStaticValue = (source, node) => {
@@ -101,17 +101,11 @@ const collectMembersAt = (object, prefix, depth, state) => {
101
101
  }
102
102
  };
103
103
  const literalValue = (node) => {
104
- if (t.isStringLiteral(node) || t.isNumericLiteral(node))
105
- return { found: true, value: node.value };
106
- if (t.isBooleanLiteral(node))
107
- return { found: true, value: node.value };
108
- if (t.isNullLiteral(node))
109
- return { found: true, value: null };
110
- if (t.isTemplateLiteral(node) && node.expressions.length === 0)
111
- return {
112
- found: true,
113
- value: node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw ?? "",
114
- };
104
+ if (node === null || node === undefined)
105
+ return { found: false };
106
+ const literal = readExactJavaScriptLiteral(node);
107
+ if (literal.found)
108
+ return literal;
115
109
  if (t.isUnaryExpression(node, { operator: "-" }) &&
116
110
  t.isNumericLiteral(node.argument))
117
111
  return { found: true, value: -node.argument.value };