JavaScript and desktop reconstruction
REA builds a bounded model of a JavaScript or Electron application from shipped files and selected runtime observations. It joins static structure with Electron boundary facts and runtime links. The retained result supports tracing and reconstruction without treating a possible relation as proof of execution.
System scope
This area answers two linked questions: what the application contains and how observed runtime entities may relate to that content. Static analysis reads an ASAR file or directory without running its code. Runtime services add bounded Electron observations. Later workflows use the retained results for queries and comparison.
| Concern | System aim | Main result |
|---|---|---|
| Static reconstruction | Model files, modules, packages, routes, workers, and desktop boundaries | JavaScript Application Graph and semantic graph |
| Worker execution | Keep source parsing isolated and bounded | Static facts, semantic facts, or explicit partial coverage |
| Electron protocol analysis | Relate renderer, preload, main, utility, and native boundaries | IPC, bridge, protocol, dynamic-code, and call-path findings |
| Electron observation | List targets or inspect one selected page through a provider | Validated Electron Evidence or partial observation |
| Runtime reconciliation | Compare captured targets, frames, scripts, and workers with static layers | Matched, ambiguous, unmatched, or unknown relations |
| Semantic queries | Follow selected graph relations from an authenticated seed | A bounded trace with coverage and unknowns |
| Retained application facts | Preserve source identity and support for later work | Immutable Evidence with links to its sources |
The wider artifact route is described in artifact and application analysis. Application reconstruction covers the broader reconstruction and coverage model. Desktop application environments describes the wider desktop runtime context. Binary diagnostics and comparison covers native binary questions.
This diagram shows how shipped files and bounded runtime observations meet in the same evidence model.
flowchart LR
A[ASAR or application directory] --> B[Static reconstruction]
B --> C[Application graph]
B --> D[Semantic graph]
E[Electron target or page observation] --> F[Electron Evidence]
C --> G[Runtime reconciliation]
F --> G
G --> H[Reconciled application graph]
D --> I[Semantic query]
I --> J[Linked result]
C --> K[Retained application Evidence]
D --> K
H --> K
References: src/…/JavaScriptArtifactGraphBuilder.ts• L64-85 src/…/JavaScriptSemanticGraphBuilder.ts• L190-197
Static reconstruction
Static reconstruction resolves one local directory or .asar file and builds two related views. The application graph describes packaged entities and broad relationships. The semantic graph describes source-level values, calls, ownership, influence, and unresolved frontiers. The analysis reads shipped text as inert input.
Artifact graph
The artifact graph starts from stable inventory facts and keeps path ownership separate from equal file content. It can describe modules, chunks, workers, package roles, routes, source-map links, and Electron boundary findings. A selected source can be unavailable, skipped, or partly parsed. Those states remain visible so missing facts do not become claims of absence.
Graph assembly merges observations for the same retained node and removes repeated observation identities. It keeps distinct node identities distinct even when their content is equal. Loader conditions can qualify matching static evidence when the condition belongs to the same source artifact.
Reconstruction admits raw file observations before it expands them into package, module, relationship, and boundary nodes. A projection failure can leave the source fact visible while preventing unsupported relationships. Coverage also records unread files, invalid data, partial parsing, resource limits, and omitted inline scripts.
Analysis offers application JavaScript before dependency JavaScript when no explicit source paths are selected. Declared JavaScript preload paths receive a separate discovery pass. The pass resolves declared preload identities and uses the preload's CommonJS loader scope when required. It does not infer a preload from renderer API text. Discovery gaps remain in the final limitations.
Module and runtime path resolution follows the declared loader context. It keeps import, CommonJS, package entry points, HTML, URL, and runtime-path meanings separate. Incomplete inventory can change a missing result from not-found to unavailable. Unsafe path syntax remains distinct from an unresolved path.
The reconstruction result carries:
- The root artifact digest and inventory identity.
- The application graph and its coverage limits.
- The semantic graph and its unresolved facts.
- Route inventory and an Electron boundary summary when available.
- Parse, source-selection, resource, and projection limitations.
References: src/…/JavaScriptArtifactAnalysis.ts• L72-133 src/…/JavaScriptArtifactAnalysis.ts• L316-385 src/…/JavaScriptArtifactGraphAccumulator.ts• L20-133 src/…/JavaScriptArtifactGraphBuilder.ts• L205-277 src/…/JavaScriptArtifactGraphStructure.ts• L141-363
Worker execution
JavaScript source analysis runs in an owned worker so parsing, Electron call-path work, and semantic projection stay isolated from the main service. The parent sends source identity and bounded source text to the worker. The same boundary serves preload discovery and normal analysis.
The worker can report static facts before it offers semantic results. The parent can retain the static checkpoint when semantic work exceeds capacity or the worker stops. Separate total and per-file limits cover memory, time, checkpoints, results, semantic nodes, unknowns, and transferred records. A limit therefore produces partial facts and a stated reason instead of a silently shortened graph.
Semantic projection gives Electron boundary paths priority when capacity is tight. Each source file receives the smaller of its per-file capacity and the remaining application capacity. Relations are emitted only when their endpoint nodes remain in the graph. Unknown omissions retain counts by relation family and reason. Cancellation stops active call-path work at safe checkpoints, and a retry starts with fresh analysis state so a partial attempt does not duplicate unknown counts. Later queries can therefore distinguish an examined graph from a complete graph.
References: src/…/JavaScriptArtifactAnalysis.ts• L101-263 src/…/JavaScriptSemanticGraphBuilder.ts• L239-283 src/…/JavaScriptSemanticGraphBuilder.ts• L401-560 src/…/JavaScriptWrappedCallPathCancellation.test.ts• L13-164
Electron boundary model
Electron protocol analysis models the boundary between renderer code, preload exposure, the main process, utility processes, and native add-ons. It records windows, web preferences, context-bridge members, IPC operations, sender checks, protocol registrations, utility entry points, native binding requests, wrapped call paths, and cached-data compilation sites. These findings let a query relate a renderer-facing API to a host-side boundary.
The boundary summary distinguishes recovered, empty, and partial states. Recovered means boundary facts were found. Empty means the analyzed source referenced Electron but no boundary fact was recovered. Partial means some Electron-loading source was not fully examined. Candidate loader identities do not count as proven Electron coverage. A rejected projection can still leave the summary partial or empty because coverage comes from the retained analysis, not only from expanded graph nodes.
IPC pairing is conservative. A renderer transmission pairs with a main handler only when the channel, owner, and mode support one exact candidate. A static pair describes a candidate relationship. It does not prove registration, dispatch, reachability, sender acceptance, or native loading. Dynamic channels, competing owners, cached-data references, and native binding requests remain unknown or requested boundaries rather than proof of execution or export support.
References: src/…/JavaScriptArtifactGraphBuilder.ts• L114-169 src/…/JavaScriptArtifactGraphBuilder.ts• L231-245 src/…/JavaScriptArtifactGraphBuilder.ts• L380-471 src/…/JavaScriptArtifactGraphElectronCoverage.test.ts• L133-224 src/…/JavaScriptArtifactGraphElectronCoverage.test.ts• L339-425
Runtime reconciliation
Runtime reconciliation joins one application static layer with optional cache or asset layers and passive runtime captures. It projects captures into target, frame, script, and worker entities. It then tests whether each runtime entity has an authorized static counterpart.
The flow below shows the main evidence path.
flowchart LR
A[Authenticated static layers] --> C[Static candidates]
B[Passive runtime captures] --> D[Runtime entities]
C --> E[Location and content matching]
D --> E
E --> F[Load-state classification]
E --> G[Observed-as edges]
F --> H[Reconciled application graph]
G --> H
H --> I[Reconciliation Evidence]
Evidence inputs and mappings
Every input is authenticated before reconciliation. Exactly one layer must have the application role. A layer can also describe cache or asset content. A runtime mapping translates an authorized file root or URL prefix into an artifact prefix. It helps locate a static candidate but does not grant new filesystem or runtime access.
Runtime captures retain target location, frame scope, script source when captured, worker identity, and capture completeness. Unresolved locations and incomplete script inventories remain part of the input. Equal runtime payloads from distinct selected endpoints remain distinct capture instances. The graph does not merge observations only because their content is equal.
The reconciliation service normalizes relative file-root mappings against the current working directory while preserving portable absolute paths. It then validates the selected static layers and runtime observations before producing linked Evidence.
References: src/…/JavaScriptRuntimeReconciliationService.ts• L24-67 src/…/JavaScriptRuntimeReconciliationService.ts• L70-96 src/…/javascriptRuntimeReconciliationSchemas.ts• L25-77
Matching and load states
Matching prefers a content-and-location match when both are known. A unique content digest can match without a location. A unique location can match when source bytes are not present. Several candidates produce ambiguous. No authorized mapping produces unknown. A mapped location with no content match can produce unmatched.
The result classifies static modules and assets as loaded, resident in a loaded asset, not observed in the capture, or unknown. Not observed means outside the bounded capture window. It does not mean globally unloaded or unreachable. The combined graph adds observed_as edges only for matched entities and retains coverage beside each inference.
References: src/…/javascriptRuntimeReconciliationMatching.ts• L21-42 src/…/javascriptRuntimeReconciliationMatching.ts• L68-162 src/…/javascriptRuntimeReconciliationGraph.ts• L38-75
Electron observation
Electron observation uses an explicitly selected provider endpoint. Target listing returns the local file pages exposed by that endpoint. Page inspection observes one selected target for the caller's observation window. The service validates the provider output before it creates Evidence.
The retained record keeps normalized facts and the provider's source data when extra fields are present. A changed target or capture window is an output error rather than a valid observation of the caller's request. If cleanup fails after useful facts arrive, the service retains partial observation data and states the cleanup limit.
References: src/…/ElectronObservationService.ts• L27-65 src/…/ElectronObservationService.ts• L68-156 src/…/ElectronObservationService.ts• L158-183
Semantic queries
Semantic queries answer a focused question over one authenticated semantic graph. A seed identifies a semantic node, application node, literal, function fingerprint, property, endpoint, event, or Electron boundary field. The query walks only the requested direction and relation set. This makes the semantic graph a bounded route through retained source facts rather than a general execution model.
Query seeds and traversal
The query supports four directions:
backward-provenancefollows facts toward their sources.forward-influencefollows possible effects toward their consumers.callersfollows call relations toward calling functions.ownershipfollows ownership relations in either direction.
Callers can restrict relation kinds and can choose whether to include candidate dynamic edges. The result keeps reached nodes and relations with the evidence contexts that explain them. Static object reads, writes, spreads, and destructuring use exact property paths when the retained receiver and slot support that link. Otherwise the graph keeps a candidate relation and an unknown frontier instead of selecting a static leaf.
References: src/…/javascriptSemanticQuerySchemas.ts• L21-82 src/…/javascriptSemanticQuery.ts• L36-99 src/…/javascriptSemanticQuery.ts• L115-181 src/…/JavaScriptSemanticGraphObjectProjection.ts• L24-57 src/…/JavaScriptSemanticGraphObjectProjection.ts• L75-195
Query coverage
The query reports found, no-match, ambiguous, partial, or unsupported. It includes relevant unknown frontiers and candidate relation counts. A no-match result on a partial graph means only that no retained match was found. It does not prove that the application has no such relation.
Semantic graph facts retain compact evidence contexts. A node is anchored to its exact artifact digest, module path, source range, and role. After projection, matching application-graph locations add application node links. This lets a result point back to the exact static observation without copying all provenance into every row. Unknown omissions preserve the fact that a bounded budget prevented complete retention.
References: src/…/JavaScriptSemanticGraphBuilder.ts• L284-390 src/…/JavaScriptSemanticGraphBuilder.ts• L622-740 src/…/JavaScriptSemanticGraphBuilder.test.ts• L232-273 src/…/JavaScriptSemanticGraphBuilder.test.ts• L943-997
Retained application facts
The analysis services publish immutable Evidence only after they validate the graph, its cross-graph bindings, its source identity, and its limitations. A retained record supports later queries and derived workflows without rerunning source analysis. Derived records link the exact source records that produced them.
Application Evidence
Static application Evidence is tied to the input path, format, root artifact digest, and shipped-artifact authority. Runtime reconciliation Evidence has inferred authority and links its static layers and runtime captures. Electron observation Evidence has observed confidence from the named provider endpoint.
Semantic Evidence separates exact syntax from relationships inferred from syntax. Built-in operations remain low-confidence candidates when loader or mutation facts are not known. Dynamic syntax receives explicit unknown Evidence. These labels keep a possible static link distinct from an observed source fact or proof of runtime behavior.
Application analysis seals the complete result, validates its JSON form, hashes it, and remembers the graph Evidence for later use. If cancellation or cleanup interrupts a completed portion, the service can retain a validated partial application Evidence record rather than discard facts already owned by the analysis.
This separation keeps shipped facts distinct from analyst inference and runtime observation. A summary view does not replace the complete retained source.
References: src/…/JavaScriptArtifactGraphAccumulator.ts• L31-53 src/…/JavaScriptArtifactGraphStructure.ts• L59-97 src/…/JavaScriptArtifactGraphStructure.ts• L367-509 src/…/JavaScriptSemanticGraphBuilder.ts• L284-390
Derived workflows
Later workflows reuse retained application facts to trace a feature, compare application versions, compare export shapes, compare a source tree with a bundle, reconcile static and runtime views, or run a semantic query. Each workflow authenticates its inputs first and returns a new result with links to the sources it used.
The same rule applies to partial results. An unresolved match, incomplete graph, or missing runtime link stays in the result and can guide a later probe. The workflow does not upgrade static structure into proof of execution.
References: src/…/JavaScriptApplicationWorkflowService.ts• L81-152 src/…/JavaScriptSemanticTraceService.ts• L22-77 src/…/StaticObservedEndpointComparisonService.ts• L203-243
Analysis boundaries
The central boundary is between a fact observed from supplied bytes or a capture and a relation inferred from those facts. Static analysis does not run the application. Electron observation inspects only the selected provider target and window. Digest equality proves equal bytes. It does not prove execution, reachability, initialization, or feature use.
Runtime mappings help compare authorized inputs but do not enlarge their authority. Candidate loader identity, IPC pairing, native member requests, and cached-data references add useful paths without becoming runtime proof.
Use binary diagnostics and comparison for native layout and binary comparison. Use firmware and embedded analysis for embedded targets. Use application reconstruction when the question concerns reconstruction obligations across several application layers.
References: src/…/JavaScriptArtifactGraphBuilder.ts• L374-471 src/…/JavaScriptArtifactGraphFindings.ts• L207-353 src/…/JavaScriptSemanticGraphObjectProjection.ts• L49-57
Change checklist
When these files or sections are changed, remember to consider these:
- Keep static layer roles, runtime mapping normalization, capture identity, and reconciliation Evidence links aligned.
- Keep content matching, location matching, ambiguity rules, capture-instance identity, and load-state labels aligned so a missing mapping does not become an absence claim.
- Keep Electron observation target identity, observation-window identity, provider identity, raw source retention, and cleanup limitations aligned.
- Keep Electron applicability, semantics state, IPC mode compatibility, application ownership, source coverage, candidate status, and dynamic-code unknowns aligned across the summary and graphs.
- Keep worker source identity, static checkpoint admission, semantic result admission, semantic unknown budgets, cancellation checkpoints, and partial-fact recovery aligned.
- Keep semantic node artifact identity, source locations, application-node bindings, relation evidence, candidate built-in labels, object-path resolution, and unknown omissions aligned.
- Keep analysis admission order, explicit source selection, preload discovery, preload resolution, and loader choice aligned.
- Keep graph and semantic graph root artifact identity bound to the same application Evidence.
- Keep derived workflow source links and authority states aligned when a workflow consumes reconciled, observed, or partial facts.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A runtime entity has no authorized file or URL mapping | The system cannot claim a static absence | Report unknown and retain the unresolved location or mapping gap |
| Several static candidates match one runtime entity | A runtime script or worker may be assigned to the wrong file | Return ambiguous with all candidate identities |
| Captured source bytes disagree with a mapped static candidate | The result could join different artifact versions | Report disagreement instead of creating an observed_as edge |
| A passive capture is truncated or has incomplete script coverage | Unseen runtime entities may be mistaken for absent entities | Mark reconciliation coverage partial or truncated |
| A nearer package manifest is unavailable or unobserved | A source may use the wrong module scope | Keep the package type unknown and do not use a farther manifest |
| Preload discovery cannot read all relevant sources | A declared preload may keep the wrong loader scope or remain undiscovered | Retain the discovery limitation and avoid treating the preload set as complete |
| The Electron provider changes the selected target or observation window | Evidence could describe a different desktop page | Return an output error and retain the mismatched report as partial data |
| Electron cleanup fails after useful facts arrive | Valid observations could be lost or transport state could be overstated | Retain partial Evidence and state cleanup limits explicitly |
| An Electron IPC channel is dynamic, owned by an unknown application, or has competing handlers | A renderer call may be paired with the wrong handler | Keep the operation ambiguous or unpaired |
| Candidate Electron loading or a rejected source projection is treated as proven coverage | Empty or partial boundaries can be misread as complete | Keep candidate states out of proven counts and derive coverage from retained source analysis |
| The JavaScript worker reaches a resource or result limit | Some semantic facts are unavailable while static facts may remain | Retain the completed checkpoint and publish explicit partial limits |
| Semantic unknown capacity is exhausted | Unresolved frontiers are omitted from the graph | Retain omission counts and mark semantic coverage partial |
| A semantic query starts from a missing seed or partial graph | A no-match result can be overread as proof of absence | Return query status, coverage, and relevant unknown frontiers together |
| A property receiver or destructuring source is not a retained container | A query may point to the wrong static slot | Keep the relation as a candidate and retain an object-flow unknown |
| Wrapped Electron call-path work is cancelled during indexing | A partial handler path could be mistaken for a complete path | Stop at the checkpoint and retry with fresh state |
| A derived workflow receives altered or mismatched Evidence | The result could cite a graph that was not analyzed | Authenticate source identity and reject mismatched graph bindings |
Key files
| File | Why to read it |
|---|---|
| src/…/JavaScriptArtifactAnalysis.ts | Source admission, package scope, worker checkpoints, and partial-fact retention. |
| src/…/JavaScriptArtifactGraphBuilder.ts | Application graph coverage, Electron summary states, ownership gaps, and limitations. |
| src/…/JavaScriptArtifactGraphAccumulator.ts | Canonical node and edge assembly, observation deduplication, and loader-qualified evidence. |
| src/…/JavaScriptArtifactGraphFindings.ts | Static imports, workers, roles, endpoints, storage, source maps, and application ownership. |
| src/…/JavaScriptArtifactGraphStructure.ts | Artifact, package, file, ASAR, and unavailable-content structure. |
| src/…/JavaScriptSemanticGraphBuilder.ts | Semantic graph projection, resource ceilings, unknown retention, and graph coverage. |
| src/…/JavaScriptSemanticGraphObjectProjection.ts | Conservative property reads, writes, spreads, and destructuring links. |
| src/…/JavaScriptWrappedCallPathCancellation.test.ts | Cancellation checkpoints and stable retry behavior for Electron call paths. |
| src/…/JavaScriptArtifactGraphElectronCoverage.test.ts | Electron coverage states and limits on static boundary claims. |
| src/…/JavaScriptSemanticGraphBuilder.test.ts | Semantic flow, query coverage, and resource-bound behavior. |
| src/…/JavaScriptSemanticGraphDestructuring.test.ts | Soundness rules for object and array destructuring under mutation and iterator uncertainty. |
| src/…/JavaScriptApplicationWorkflowService.ts | Authenticated workflows over retained application facts. |