reverseport 0.0.0-stage → 1.2.0

package/dist/contracts/investigationExamples.js

@@ -0,0 +1,116 @@
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { compareProcessCaptures } from "../domain/process/processComparison.js";
+import { parseProcessCapture } from "../domain/process/processCaptureParsing.js";
+import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js";
+import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../domain/process/processCaptureExample.js";
+import { compareFunctions } from "../domain/functionComparison.js";
+const comparison = compareFunctions(FUNCTION_COMPARISON_EXAMPLE.left, FUNCTION_COMPARISON_EXAMPLE.right);
+export const FUNCTION_COMPARISON_EVIDENCE = createEvidence(undefined, {
+    id: "rea-function-comparison",
+    name: "REA function comparison",
+    version: "1",
+}, {
+    predicateType: "rea.function-comparison",
+    operation: "compare_functions",
+    parameters: {
+        left_evidence_id: FUNCTION_COMPARISON_EXAMPLE.left.evidence_id,
+        right_evidence_id: FUNCTION_COMPARISON_EXAMPLE.right.evidence_id,
+    },
+    result: jsonValueSchema.parse(comparison),
+    confidence: "derived",
+    authority: "analyst-inference",
+    evidenceLinks: [
+        FUNCTION_COMPARISON_EXAMPLE.left.evidence_id,
+        FUNCTION_COMPARISON_EXAMPLE.right.evidence_id,
+    ],
+});
+const PROCESS_PROVIDER = {
+    id: "rea-process",
+    name: "REA deterministic process harness",
+    version: "3",
+};
+const capture = parseProcessCapture(EMPTY_PROCESS_CAPTURE_EXAMPLE);
+const captureEvidence = (scenario) => createEvidence(undefined, PROCESS_PROVIDER, {
+    predicateType: "rea.process-capture",
+    operation: "capture_process_scenario",
+    parameters: { scenario },
+    result: jsonValueSchema.parse(capture),
+    confidence: "observed",
+    authority: "controlled-replay",
+    environment: {
+        id: "fixture-linux",
+        platform: "linux",
+        architecture: "x86_64",
+        isolation: "container",
+    },
+});
+export const PROCESS_CAPTURE_REFERENCE = captureEvidence("reference");
+export const PROCESS_CAPTURE_RECONSTRUCTION = captureEvidence("reconstruction");
+export const PROCESS_COMPARISON_EVIDENCE = createEvidence(undefined, PROCESS_PROVIDER, {
+    predicateType: "rea.process-comparison",
+    operation: "compare_process_captures",
+    parameters: {
+        left_evidence_id: PROCESS_CAPTURE_REFERENCE.evidence_id,
+        right_evidence_id: PROCESS_CAPTURE_RECONSTRUCTION.evidence_id,
+        left_normalization: capture.normalization,
+        right_normalization: capture.normalization,
+    },
+    result: jsonValueSchema.parse(compareProcessCaptures(capture, capture)),
+    confidence: "derived",
+    authority: "analyst-inference",
+    evidenceLinks: [
+        PROCESS_CAPTURE_REFERENCE.evidence_id,
+        PROCESS_CAPTURE_RECONSTRUCTION.evidence_id,
+    ],
+});
+/** Canonical inputs for comparison-composed investigation contracts. */
+export const INVESTIGATION_EXAMPLES = {
+    compare_process_captures: {
+        input: {
+            left: PROCESS_CAPTURE_REFERENCE,
+            right: PROCESS_CAPTURE_RECONSTRUCTION,
+        },
+    },
+    find_changed_behavior: { comparisons: [FUNCTION_COMPARISON_EVIDENCE] },
+    build_call_path: {
+        functions: [FUNCTION_COMPARISON_EXAMPLE.left],
+        start: { address: "0x1000" },
+        goal: { address: "0x1000" },
+    },
+    correlate_static_and_runtime: {
+        static_comparisons: [FUNCTION_COMPARISON_EVIDENCE],
+        runtime_comparisons: [PROCESS_COMPARISON_EVIDENCE],
+        mappings: [
+            {
+                static: {
+                    comparison_evidence_id: FUNCTION_COMPARISON_EVIDENCE.evidence_id,
+                    selector: { kind: "function", dimension: "pseudocode" },
+                },
+                runtime: {
+                    comparison_evidence_id: PROCESS_COMPARISON_EVIDENCE.evidence_id,
+                    dimension: "terminal",
+                },
+                side_alignment: "left_to_left",
+                hypothesis: {
+                    statement: "Static implementation changed without terminal change.",
+                    expected_pattern: "static_only",
+                },
+            },
+        ],
+    },
+    verify_reconstruction: {
+        specification: {
+            name: "Terminal compatibility",
+            claims: [
+                {
+                    kind: "behavioral",
+                    claim_id: "terminal-output",
+                    title: "Terminal output remains equivalent",
+                    comparison_evidence_id: PROCESS_COMPARISON_EVIDENCE.evidence_id,
+                    dimension: "terminal",
+                },
+            ],
+        },
+    },
+};

package/dist/contracts/javascript/applicationWorkflowInputContracts.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { evidenceInputSchema } from "../evidenceInputContracts.js";
+import { compareApplicationVersionsInputSchema } from "../../domain/javascript/javascriptApplicationVersionComparisonSchemas.js";
+import { compareJavaScriptExportShapesInputSchema } from "../../domain/javascript/javascriptExportShapeComparisonSchemas.js";
+import { traceApplicationFeatureInputSchema } from "../../domain/javascript/javascriptFeatureTraceSchemas.js";
+import { javaScriptSemanticQueryInputSchema } from "../../domain/javascript/javascriptSemanticQuerySchemas.js";
+import { compareSourceToBundleInputSchema } from "../../domain/javascript/sourceToBundleComparisonSchemas.js";
+const traceApplicationFeatureFacts = {
+    native_observations: traceApplicationFeatureInputSchema.shape.native_observations,
+    seed: traceApplicationFeatureInputSchema.shape.seed,
+    direction: traceApplicationFeatureInputSchema.shape.direction,
+};
+/** Application trace request accepting inline or same-session application Evidence. */
+export const traceApplicationFeatureRequestSchema = z.strictObject({
+    ...traceApplicationFeatureFacts,
+    application: evidenceInputSchema,
+});
+/** Semantic trace request accepting inline or same-session application Evidence. */
+export const traceJavaScriptSemanticsRequestSchema = z.strictObject({
+    application: evidenceInputSchema,
+    query: javaScriptSemanticQueryInputSchema,
+});
+const compareApplicationVersionsFacts = {
+    left_native_observations: compareApplicationVersionsInputSchema.shape.left_native_observations,
+    right_native_observations: compareApplicationVersionsInputSchema.shape.right_native_observations,
+};
+/** Application comparison request accepting inline or same-session application Evidence. */
+export const compareApplicationVersionsRequestSchema = z.strictObject({
+    ...compareApplicationVersionsFacts,
+    left: evidenceInputSchema,
+    right: evidenceInputSchema,
+});
+const compareSourceToBundleFacts = {
+    reference: compareSourceToBundleInputSchema.shape.reference,
+};
+/** Historical-source comparison accepting inline or same-session application Evidence. */
+export const compareSourceToBundleRequestSchema = z.strictObject({
+    ...compareSourceToBundleFacts,
+    application: evidenceInputSchema,
+});
+const compareJavaScriptExportShapesFacts = {
+    left_module_path: compareJavaScriptExportShapesInputSchema.shape.left_module_path,
+    left_export_name: compareJavaScriptExportShapesInputSchema.shape.left_export_name,
+    right_module_path: compareJavaScriptExportShapesInputSchema.shape.right_module_path,
+    right_export_name: compareJavaScriptExportShapesInputSchema.shape.right_export_name,
+};
+/** Export-shape request accepting inline or same-session application Evidence. */
+export const compareJavaScriptExportShapesRequestSchema = z.strictObject({
+    ...compareJavaScriptExportShapesFacts,
+    left: evidenceInputSchema,
+    right: evidenceInputSchema,
+});

package/dist/contracts/javascript/electronToolContracts.js

@@ -0,0 +1,118 @@
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { electronPageInspectionSchema, electronTargetListSchema, inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../../domain/javascript/electronObservation.js";
+import { electronActiveObservationInputSchema, electronActiveObservationResultSchema, } from "../../domain/javascript/electronActiveObservation.js";
+import { javascriptApplicationSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
+import { analysisDetailOutputSchemaOf, analysisDetailSchema, } from "../analysisDetail.js";
+import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../../domain/javascript/javascriptApplicationAnalysis.js";
+import { javascriptRuntimeReconciliationResultSchema, reconcileJavaScriptRuntimeInputSchema, } from "../../domain/javascript/javascriptRuntimeReconciliationSchemas.js";
+import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "./javascriptRuntimeReconciliationExample.js";
+const listOutputSchema = evidenceResultOf(electronTargetListSchema);
+const inspectionOutputSchema = evidenceResultOf(electronPageInspectionSchema);
+/** Caller-selected delivery of a completed JavaScript application analysis. */
+export const analyzeJavaScriptApplicationRequestSchema = analyzeJavaScriptApplicationInputSchema.extend({
+    detail: analysisDetailSchema,
+});
+const applicationOutputSchema = analysisDetailOutputSchemaOf(javascriptApplicationAnalysisResultSchema, javascriptApplicationSummaryViewResultSchema);
+const reconciliationOutputSchema = evidenceResultOf(javascriptRuntimeReconciliationResultSchema);
+const endpoint = "http://127.0.0.1:9223";
+const activeExample = {
+    executable_path: "/Applications/Electron.app/Contents/MacOS/Electron",
+    application_path: "/Applications/Example.app/Contents/Resources/main.js",
+    args: [],
+    actions: [{ step_id: "exercise-ipc", kind: "click", selector: "#run" }],
+};
+/** Endpoint-scoped Electron file-page discovery and inspection contracts. */
+export const ELECTRON_TOOL_CONTRACTS = [
+    {
+        name: "list_electron_targets",
+        ...toolContractMetadata("list_electron_targets"),
+        description: "List every Electron file:// page target from a selected loopback CDP endpoint. Local file paths are canonicalized after symlink resolution. Selecting an endpoint exposes every eligible target and its local path metadata.",
+        kind: "electron-provider",
+        inputSchema: listElectronTargetsInputSchema,
+        outputSchema: listOutputSchema,
+        examples: [
+            {
+                title: "List Electron file pages",
+                input: {
+                    cdp_endpoint: endpoint,
+                },
+            },
+        ],
+    },
+    {
+        name: "inspect_electron_page",
+        ...toolContractMetadata("inspect_electron_page"),
+        description: "Passively inspect one Electron file page by supplying its loopback CDP endpoint and target ID. The provider rechecks that the target currently exists at that endpoint and is a local file page. Returns frames, DOM structure, resource paths, and scripts without evaluating renderer JavaScript or invoking Electron APIs. The selected endpoint exposes every local file page and its metadata to this tool.",
+        kind: "electron-provider",
+        inputSchema: inspectElectronPageInputSchema,
+        outputSchema: inspectionOutputSchema,
+        examples: [
+            {
+                title: "Inspect an Electron page",
+                input: {
+                    cdp_endpoint: endpoint,
+                    target_id: "TARGET_ID_FROM_LIST_ELECTRON_TARGETS",
+                },
+            },
+        ],
+    },
+    {
+        name: "analyze_javascript_application",
+        ...toolContractMetadata("analyze_javascript_application"),
+        description: "Reconstruct one local ASAR or extracted JavaScript application as an inline application graph without executing it. Returns recovered graph nodes, edges, semantic relations, integrity contradictions, limitations, and coverage. Select source_paths to acquire and analyze only exact inventoried file paths; the complete artifact inventory and identity remain intact, and unselected sources remain explicit unknowns. Dependencies are not implicitly analyzed. Select detail summary to retain the complete analysis Evidence in this session and receive only its summary view, then inspect selected modules or pages with inspect_analysis_view. Summary detail reduces delivery, whereas source_paths bounds source analysis. Integrity mismatches fail by default; record-and-continue retains observed bytes as untrusted and marks graph coverage partial.",
+        kind: "electron-provider",
+        inputSchema: analyzeJavaScriptApplicationRequestSchema,
+        outputSchema: applicationOutputSchema,
+        examples: [
+            {
+                title: "Analyze one local JavaScript application",
+                input: {
+                    input_path: "/Applications/Example.app/Contents/Resources/app.asar",
+                    format: "auto",
+                    integrity_policy: "fail",
+                },
+            },
+            {
+                title: "Analyze selected entry sources before unrelated vendor files",
+                input: {
+                    input_path: "/Applications/Example.app/Contents/Resources/app.asar",
+                    source_paths: ["package.json", "main.js", "preload.js"],
+                    detail: "summary",
+                },
+            },
+            {
+                title: "Retain the complete analysis and return its summary view",
+                input: {
+                    input_path: "/Applications/Example.app/Contents/Resources/app.asar",
+                    detail: "summary",
+                },
+            },
+        ],
+    },
+    {
+        name: "reconcile_javascript_runtime",
+        ...toolContractMetadata("reconcile_javascript_runtime"),
+        description: "Reconcile verified static JavaScript application graphs with existing passive web/Electron CDP, passive V8 Inspector, or provider-owned active Electron Evidence. Active Electron captures contribute an explicitly partial target-only runtime record; they never invent renderer scripts, frames, workers, or execution claims. Exact captured-source digests take priority over caller-declared file/URL mappings; target, frame, script, and worker ambiguity remains explicit, and source-map authority stays separate.",
+        kind: "electron-provider",
+        inputSchema: reconcileJavaScriptRuntimeInputSchema,
+        outputSchema: reconciliationOutputSchema,
+        examples: [
+            {
+                title: "Reconcile one passive Electron capture",
+                input: JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
+            },
+        ],
+    },
+    {
+        name: "capture_electron_scenario",
+        ...toolContractMetadata("capture_electron_scenario"),
+        description: "Use this for a provider-owned Electron run when passive CDP or Inspector observation cannot exercise application behavior. REA owns startup and teardown, accepts caller-defined click/wait actions plus window-targeted renderer reload/crash and synthetic open-url/second-instance delivery, and returns correlated window/WebContents/process/preload/session/navigation/shell/IPC evidence without retaining payload values. Actions wait for completion or request cancellation; a missing click target can keep the request pending. Results identify observed and unavailable event families, coverage status, action targets, and truncation. Cleanup failures retain collected observations with explicit cleanup uncertainty. External shell, navigation, permission, download, popup, updater, and OS-integration effects are blocked and recorded. Use passive Electron tools for observation-only work.",
+        kind: "electron-provider",
+        inputSchema: electronActiveObservationInputSchema,
+        outputSchema: evidenceResultOf(electronActiveObservationResultSchema),
+        examples: [
+            { title: "Exercise an owned Electron application", input: activeExample },
+        ],
+    },
+];

package/dist/contracts/javascript/javascriptApplicationWorkflowExamples.js

@@ -0,0 +1,85 @@
+import { createEvidence } from "../../domain/evidence.js";
+import { parseRuntimeReconciliationInput, reconcileJavaScriptRuntime, } from "../../domain/javascript/javascriptRuntimeReconciliation.js";
+import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE, JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE, } from "./javascriptRuntimeReconciliationExample.js";
+import { createHistoricalSourceGraph } from "../../domain/referenceSourceGraph.js";
+import { reconcileJavaScriptRuntimeInputSchema } from "../../domain/javascript/javascriptRuntimeReconciliationSchemas.js";
+const reconciliation = reconcileJavaScriptRuntime(parseRuntimeReconciliationInput(reconcileJavaScriptRuntimeInputSchema.parse(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",
+    operation: "reconcile_javascript_runtime",
+    parameters: {
+        static_layers: JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.static_layers.map(({ analysis }) => ({
+            role: "application",
+            evidence_id: analysis.evidence_id,
+            runtime_mappings: [],
+        })),
+        runtime_evidence_ids: JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.runtime_observations.map(({ evidence_id: id }) => id),
+    },
+    result: reconciliation,
+    confidence: "inferred",
+    authority: "analyst-inference",
+    limitations: reconciliation.limitations,
+    evidenceLinks: reconciliation.evidence_links,
+});
+const TRACE_SEED = {
+    kind: "module",
+    value: "renderer.js",
+    match: "exact",
+    case_sensitive: false,
+};
+/** Natural trace request with the producer's complete Evidence inline. */
+export const JAVASCRIPT_FEATURE_TRACE_EXAMPLE = {
+    application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+    seed: TRACE_SEED,
+    direction: "both",
+};
+/** Natural version comparison with both Evidence records inline. */
+export const JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE = {
+    left: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+    right: reconciliationEvidence,
+};
+/** Historical source inventory compared with inline application Evidence. */
+export const SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE = {
+    reference: createHistoricalSourceGraph({
+        schema: "HistoricalSourceGraph",
+        authority: "historical-reference",
+        root_alias: "$REFERENCE_ROOT",
+        inventory_state: "complete",
+        entries: [
+            {
+                path: "src",
+                kind: "directory",
+                classifications: ["source"],
+                tree_state: "enumerated",
+                limitations: [],
+            },
+            {
+                path: "src/main.ts",
+                kind: "file",
+                sha256: "2".repeat(64),
+                size: 128,
+                language: "TypeScript",
+                classifications: ["source"],
+                content_state: "hashed",
+                limitations: [],
+            },
+        ],
+        relationships: [],
+        parse_failures: [],
+        exclusions: [],
+        languages: ["TypeScript"],
+        manifests: [],
+        vcs: { kind: "none", head: null, dirty: null },
+        provenance: {
+            importer: "rea",
+            importer_version: "1",
+            caller: "contract-example",
+        },
+        limitations: [],
+    }),
+    application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+};

package/dist/contracts/javascript/javascriptExportShapeComparisonExample.js

@@ -0,0 +1,248 @@
+import { createEvidence } from "../../domain/evidence.js";
+import { createWebTextArtifact } from "../../domain/webContentArtifact.js";
+import { analyzeJavaScriptSemantics } from "../../domain/javascript/javascriptSemanticAnalysis.js";
+import { projectJavaScriptExportReturnShapes } from "../../domain/javascript/javascriptExportReturnShapeProjection.js";
+import { completeApplicationCoverage, partialApplicationCoverage, } from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
+import { createJavaScriptApplicationGraph, createJavaScriptApplicationNode, } from "../../domain/javascript/javascriptApplicationGraph.js";
+import { createJavaScriptSemanticGraph, createJavaScriptSemanticGraphNode, JavaScriptSemanticEvidenceContextRegistry, } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../../domain/javascript/javascriptSemanticGraphSchemas.js";
+import { javascriptApplicationAnalysisResultSchema } from "../../domain/javascript/javascriptApplicationAnalysis.js";
+// Inventory identities/counters captured from real analysis of these two sources.
+// The inline example retains only source-derived export facts, with explicit gaps.
+const captures = {
+    count: {
+        input_path: "/examples/javascript-export-presence/left",
+        root_artifact_sha256: "5005ebc2f35719a2fc014f19a81c669f3a1ab471b7245ef6985a111b6845a747",
+        inventory_manifest_id: "agm_f30ded9a83d43a3980417bbe63dfad569e83386f243c4d6a01af0166372cb9e6",
+        inventory_graph_sha256: "4b8aceaf67e43fd8317ec1f5fd1df5235f8fa402335accf011683e008c6bc62c",
+        integrity_contradictions: [],
+    },
+    total: {
+        input_path: "/examples/javascript-export-presence/right",
+        root_artifact_sha256: "269ae72a601ad5ac02f1c2dda6ff9accffa2d2e4f4a9e406facee0d5a78a5377",
+        inventory_manifest_id: "agm_d3ceaa1af38fb3474070ca25c0d4644282e5fb7d5824cee3e3a81391481e9fc1",
+        inventory_graph_sha256: "3e9bc926951480c35385efe5650d9d781631bd74c37a523d543b5fbe06b01ce6",
+        integrity_contradictions: [],
+    },
+};
+const summary = {
+    browser_windows: 0,
+    explicit_web_preferences: 0,
+    preload_entrypoints: 0,
+    context_bridge_apis: 0,
+    exposed_api_members: 0,
+    ipc: {
+        operations: 0,
+        literal_channels: 0,
+        dynamic_channel_operations: 0,
+        renderer_transmissions: 0,
+        renderer_listeners: 0,
+        main_handlers: 0,
+        paired_renderer_transmissions: 0,
+        ambiguous_renderer_transmissions: 0,
+        unpaired_literal_renderer_transmissions: 0,
+    },
+    sender_validation_observations: 0,
+    utility_processes: 0,
+    resolved_utility_entrypoints: 0,
+    native_addon_bindings: 0,
+    resolved_native_addon_bindings: 0,
+};
+const statistics = {
+    relevant_files: 1,
+    nested_asar_containers: 0,
+    text_bytes_read: 60,
+    invalid_utf8_files: 0,
+    parsed_javascript_files: 1,
+    visited_ast_nodes: 12,
+    findings: 1,
+    modules: 0,
+    parse_failures: 0,
+};
+const modulePath = "parser.mjs";
+const limitations = [
+    "This example retains export and return-shape facts only; other application and semantic relationships are omitted.",
+];
+const exampleEvidence = (property) => {
+    const metadata = captures[property];
+    const source = `export default () => ({ kind: "results", ${property}: query() });\n`;
+    const artifact = createWebTextArtifact(source, "text/javascript");
+    const ir = analyzeJavaScriptSemantics(source);
+    const link = ir.moduleLinks.find(({ exportedName }) => exportedName === "default");
+    if (link === undefined)
+        throw new Error("Example source must define a default export");
+    const coverage = ir.coverage.status === "complete"
+        ? completeApplicationCoverage()
+        : partialApplicationCoverage([], ir.coverage.omittedCount);
+    const projection = projectJavaScriptExportReturnShapes({
+        ir,
+        link,
+        modulePath,
+        baseCoverage: coverage,
+    });
+    if (projection === null)
+        throw new Error("Example export must retain return shapes");
+    const evidence = {
+        artifact: {
+            available: true,
+            artifact_id: `art_${artifact.sha256}`,
+            sha256: artifact.sha256,
+        },
+        location: {
+            available: true,
+            value: { kind: "source-range", source: modulePath, ...link.location },
+        },
+        extractor: {
+            name: "rea-javascript-artifact-reconstruction",
+            version: "1",
+            operation: "recover-module-export",
+            executable_sha256: null,
+        },
+        coverage,
+        limitations: ir.limitations,
+        evidence_ids: [],
+    };
+    const exported = createJavaScriptApplicationNode({
+        kind: "javascript-module",
+        identity: {
+            strategy: "artifact-local-key",
+            stability: "artifact-version",
+            artifact_sha256: artifact.sha256,
+            namespace: "module-export",
+            key: `${metadata.root_artifact_sha256}:${modulePath}:default`,
+        },
+        observations: [
+            {
+                label: `${modulePath}:default`,
+                properties: {
+                    semantic_role: "export-binding",
+                    module_path: modulePath,
+                    relationship_kind: link.kind,
+                    exported_name: link.exportedName,
+                    local_name: link.localName,
+                    imported_name: link.importedName,
+                    declared_specifier: link.specifier,
+                },
+                evidence: {
+                    ...evidence,
+                    authority: "ast-static-analysis",
+                    state: "observed",
+                    confidence: "exact",
+                },
+            },
+            {
+                label: `${modulePath}:default:return-shapes`,
+                properties: projection.properties,
+                evidence: {
+                    ...evidence,
+                    authority: "static-relationship-inference",
+                    state: "inferred",
+                    confidence: "high",
+                    location: {
+                        available: true,
+                        value: {
+                            kind: "source-range",
+                            source: modulePath,
+                            ...projection.range,
+                        },
+                    },
+                    extractor: {
+                        ...evidence.extractor,
+                        operation: "recover-export-return-shapes",
+                    },
+                    coverage: projection.coverage,
+                    limitations: projection.limitations,
+                },
+            },
+        ],
+    });
+    const graph = createJavaScriptApplicationGraph({
+        schema: "JavaScriptApplicationGraph",
+        root_node_ids: [exported.node_id],
+        nodes: [exported],
+        edges: [],
+        coverage: partialApplicationCoverage([], null),
+        limitations,
+    });
+    const evidenceContexts = new JavaScriptSemanticEvidenceContextRegistry();
+    const module = createJavaScriptSemanticGraphNode({
+        kind: "module",
+        identity: {
+            artifact_sha256: artifact.sha256,
+            module_path: modulePath,
+            source_range: null,
+            role_key: "example-module",
+        },
+        function_node_id: null,
+        application_node_ids: [exported.node_id],
+        label: modulePath,
+        properties: {},
+        evidence: {
+            ...evidence,
+            authority: "ast-static-analysis",
+            state: "observed",
+            confidence: "exact",
+        },
+    }, evidenceContexts);
+    const semanticGraph = createJavaScriptSemanticGraph({
+        schema: "JavaScriptSemanticRelationGraph",
+        root_artifact_sha256: metadata.root_artifact_sha256,
+        application_graph_id: graph.graph_id,
+        root_node_ids: [module.node_id],
+        evidence_contexts: evidenceContexts.contexts,
+        nodes: [module],
+        relations: [],
+        fingerprints: [],
+        unknowns: [],
+        coverage: {
+            status: "unknown",
+            truncated: false,
+            omitted_nodes: null,
+            omitted_relations: null,
+            limits: [],
+            families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({
+                family,
+                status: "unknown",
+                retained_relations: 0,
+                omitted_relations: null,
+                unknown_ids: [],
+            })),
+        },
+        limitations,
+    });
+    const result = javascriptApplicationAnalysisResultSchema.parse({
+        ...metadata,
+        format: "directory",
+        graph,
+        semantic_graph: semanticGraph,
+        summary,
+        statistics,
+        limitations,
+    });
+    return createEvidence({
+        path: result.input_path,
+        sha256: result.root_artifact_sha256,
+        format: "directory",
+    }, {
+        id: "rea-javascript-application",
+        name: "REA JavaScript application analyzer",
+        version: "1",
+    }, {
+        predicateType: "rea.javascript-application-analysis",
+        operation: "analyze_javascript_application",
+        parameters: {},
+        result,
+        confidence: "derived",
+        authority: "shipped-artifact",
+        limitations,
+    });
+};
+/** Source-derived tagged exports with known presence and unresolved values. */
+export const JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE = {
+    left: exampleEvidence("count"),
+    right: exampleEvidence("total"),
+    left_module_path: modulePath,
+    left_export_name: "default",
+    right_module_path: modulePath,
+    right_export_name: "default",
+};

package/dist/contracts/javascript/javascriptRecoveryToolContracts.js

@@ -0,0 +1,35 @@
+import { javascriptRecoveryInputSchema, javascriptRecoveryResultSchema, } from "../../domain/javascript/javascriptRecovery.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+/** Derived script artifacts from optional upstream recovery adapters. */
+export const JAVASCRIPT_RECOVERY_TOOL_CONTRACTS = [
+    {
+        name: "recover_javascript_sources",
+        ...toolContractMetadata("recover_javascript_sources"),
+        kind: "application",
+        description: "Recover readable modules from local UTF-8 JavaScript scripts/bundles into an absent directory, using caller-supplied Wakaru ^1.13.0 (verified with 1.14.0) on Linux x64. Use additional_paths for related chunks; each input retains its own snapshot and provenance. Returns original/derived digests, extraction byte ranges, emitted source maps, warnings and analysis_input inline. Structural splitting may fall back to one module; original names and runtime equivalence remain unknown. No application code execution. Requires util-linux prlimit; one worker, 1 GiB address-space ceiling, 120-second deadline, 64 MiB total input, 128 MiB output, 10000 entries and 8 MiB per diagnostic/report stream.",
+        inputSchema: javascriptRecoveryInputSchema,
+        outputSchema: evidenceResultOf(javascriptRecoveryResultSchema),
+        examples: [
+            {
+                title: "Recover a captured production bundle",
+                input: {
+                    path: "/tmp/web-scripts/app.js",
+                    output_directory: "/tmp/recovered-app",
+                },
+            },
+            {
+                title: "Recover a code-split bundle together",
+                input: {
+                    path: "/tmp/web-scripts/main.js",
+                    additional_paths: [
+                        "/tmp/web-scripts/runtime.js",
+                        "/tmp/web-scripts/shared.js",
+                        "/tmp/web-scripts/checkout.chunk.js",
+                    ],
+                    output_directory: "/tmp/recovered-chunks",
+                },
+            },
+        ],
+    },
+];