rea-agents 2.2.0 → 2.3.0

package/dist/application/Doctor.js

@@ -12,25 +12,42 @@ import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js";
 import { readClientRegistrationStatuses, } from "./ClientRegistrationStatus.js";
 import { inspectRuntimeExecutables, } from "./RuntimeExecutableDiagnostics.js";
 import { collectDoctorDiagnostics, doctorHealthy, } from "./DoctorDiagnostics.js";
+import { normalizeDoctorScope, scopeDoctorChecks, } from "./DoctorScope.js";
 const execFileAsync = promisify(execFile);
+/** Deep provider IDs whose readiness can be selected explicitly by doctor. */
+export const DOCTOR_PROVIDER_IDS = ["hopper", "ghidra"];
 /**
  * Check requirements and an optional target without mutating the host.
  * Every failed check includes remediation suitable for either the one-shot CLI
  * or an agent consuming the structured result.
  */
-export const runDoctor = async (target, host = systemDoctorHost()) => {
+export const runDoctor = async (target, host = systemDoctorHost(), requestedScope) => {
     const { checks: diagnosticChecks, hopperPath, providerInspections, runtimeExecutables, } = await collectDoctorDiagnostics(target, host);
     const identity = await collectDoctorIdentity(host, runtimeExecutables);
     const checks = [...diagnosticChecks, ...identity.checks];
+    const providers = {
+        hopperAvailable: hopperPath !== undefined &&
+            checks
+                .filter(({ name }) => name.startsWith("hopper"))
+                .every(({ ok }) => ok),
+        hopperConfigured: host.configuredHopperPath !== undefined,
+        providerInspections,
+    };
+    const environmentHealthy = doctorHealthy(checks, providers);
+    const scope = normalizeDoctorScope(requestedScope, target);
+    const scoped = scopeDoctorChecks({
+        checks,
+        registrations: identity.value.registrations,
+        skillState: identity.value.skill.state,
+        providers,
+        scope,
+    });
     return {
-        healthy: doctorHealthy(checks, {
-            hopperAvailable: hopperPath !== undefined &&
-                checks
-                    .filter(({ name }) => name.startsWith("hopper"))
-                    .every(({ ok }) => ok),
-            hopperConfigured: host.configuredHopperPath !== undefined,
-            providerInspections,
-        }),
+        healthy: scope.mode === "audit-wide" ? environmentHealthy : scoped.healthy,
+        environment_healthy: environmentHealthy,
+        scope,
+        scope_checks: scope.mode === "audit-wide" ? checks : scoped.scopeChecks,
+        informational_checks: scope.mode === "audit-wide" ? [] : scoped.informationalChecks,
         ...(hopperPath === undefined ? {} : { hopperPath }),
         ...(providerInspections === undefined ? {} : { providerInspections }),
         checks,
@@ -127,7 +144,7 @@ export const systemDoctorHost = (options = {}) => ({
         return (await parseBinaryTarget(path)).ok;
     },
     executable: executableAvailable,
-    linuxDemoRuntimeReady,
+    linuxDemoRuntimeCheck: options.linuxDemoRuntimeCheck ?? uncomposedLinuxDemoRuntimeCheck,
     supportedLinuxHopper: linuxHopperBinarySupported,
     async brewHopperPath() {
         return probeHomebrew(async (command) => {
@@ -202,21 +219,13 @@ const executableAvailable = async (path) => {
         return false;
     }
 };
-const linuxDemoRuntimeReady = async () => {
-    try {
-        await access("/usr/bin/Xvfb", constants.X_OK);
-        await access("/usr/bin/xauth", constants.X_OK);
-        await access("/usr/bin/python3", constants.X_OK);
-        await execFileAsync("/usr/bin/python3", [
-            "-c",
-            "import ctypes; ctypes.CDLL('libX11.so.6'); ctypes.CDLL('libXtst.so.6')",
-        ]);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
+const uncomposedLinuxDemoRuntimeCheck = () => Promise.resolve({
+    name: "hopper-demo-runtime",
+    ok: false,
+    classification: "config_drift",
+    detail: "Linux Hopper private-display diagnostics were not composed",
+    remediation: "Run rea doctor through the production CLI adapter.",
+});
 const manualHopperPaths = async () => {
     const paths = [];
     for (const root of ["/Applications", join(homedir(), "Applications")]) {

package/dist/application/DoctorDiagnostics.js

@@ -134,10 +134,7 @@ const optionalHopperVersionCheck = async (host, hopperPath) => {
 };
 const optionalHopperDemoCheck = async (host, hopperPath) => host.platform !== "linux" || hopperPath === undefined
     ? undefined
-    : check("hopper-demo-runtime", await host.linuxDemoRuntimeReady(), undefined, {
-        remediation: "Rerun rea setup to install the Xvfb, xauth, Python, X11, and XTEST packages required for Linux demo sessions.",
-        classification: "missing_dependency",
-    });
+    : host.linuxDemoRuntimeCheck();
 const optionalIlspyCheck = async (host) => {
     if (host.configuredIlspyCmdPath === undefined)
         return undefined;

package/dist/application/DoctorProjection.js

@@ -0,0 +1,43 @@
+/** Project doctor diagnostics for concise CLI output or explicit full detail. */
+export const projectDoctorReport = (report, detail) => detail === "full" ? report : doctorSummary(report);
+const doctorSummary = (report) => ({
+    healthy: report.healthy,
+    environment_healthy: report.environment_healthy,
+    scope: report.scope,
+    ...(report.hopperPath === undefined
+        ? {}
+        : { hopper_path: report.hopperPath }),
+    providers: (report.providerInspections ?? []).map((provider) => ({
+        id: provider.id,
+        configured: provider.configured,
+        available: provider.available,
+        provider_version: provider.providerVersion,
+        failed_checks: provider.checks.filter(({ ok }) => !ok).map(checkSummary),
+    })),
+    failed_scope_checks: report.scope_checks
+        .filter(({ ok }) => !ok)
+        .map(checkSummary),
+    informational_drift_count: report.informational_checks.filter(({ ok }) => !ok)
+        .length,
+    identity: report.identity === undefined
+        ? null
+        : {
+            cli_package_version: report.identity.cli_package_version,
+            expected_skill_version: report.identity.expected_skill_version,
+            catalog: {
+                counts: report.identity.catalog.counts,
+                digests: report.identity.catalog.digests,
+            },
+            installations: report.identity.installations,
+            skill: report.identity.skill,
+            registrations: report.identity.registrations,
+        },
+});
+const checkSummary = (check) => ({
+    name: check.name,
+    classification: check.classification,
+    ...(check.detail === undefined ? {} : { detail: check.detail }),
+    ...(check.remediation === undefined || check.remediation === null
+        ? {}
+        : { remediation: check.remediation }),
+});

package/dist/application/DoctorScope.js

@@ -0,0 +1,102 @@
+import { doctorHealthy } from "./DoctorDiagnostics.js";
+/** Normalize a caller-selected doctor readiness boundary. */
+export const normalizeDoctorScope = (requested, target) => ({
+    mode: requested === undefined ? "audit-wide" : "explicit",
+    clients: uniqueSorted(requested?.clients ?? []),
+    providers: uniqueSorted(requested?.providers ?? []),
+    skill: requested?.skill === true,
+    target: target ?? null,
+});
+/** Partition diagnostics into required and informational scope checks. */
+export const scopeDoctorChecks = (input) => {
+    const providerChecks = input.checks.filter((candidate) => isProviderCheck(candidate.name, input.providers.providerInspections));
+    const coreChecks = input.checks.filter(({ name }) => !isProviderCheck(name, input.providers.providerInspections) &&
+        name !== "skill:identity" &&
+        !name.startsWith("registration:"));
+    const clientChecks = input.scope.clients.map((client) => selectedRegistrationCheck(client, input.registrations.find((candidate) => candidate.client === client)));
+    const skillChecks = input.scope.skill
+        ? [selectedSkillCheck(input.skillState, input.checks)]
+        : [];
+    const selectedProviderChecks = input.scope.providers.length === 0
+        ? configuredProviderChecks(providerChecks, input.providers)
+        : input.scope.providers.flatMap((providerId) => selectedProviderChecksFor(providerId, providerChecks, input.providers));
+    const scopeChecks = [
+        ...coreChecks,
+        ...selectedProviderChecks,
+        ...clientChecks,
+        ...skillChecks,
+    ];
+    const providerHealthy = input.scope.providers.length === 0
+        ? doctorHealthy([...coreChecks, ...providerChecks, ...clientChecks, ...skillChecks], input.providers)
+        : selectedProviderChecks.every(({ ok }) => ok);
+    const selectedNames = new Set(scopeChecks.map(({ name }) => name));
+    return {
+        healthy: coreChecks.every(({ ok }) => ok) &&
+            clientChecks.every(({ ok }) => ok) &&
+            skillChecks.every(({ ok }) => ok) &&
+            providerHealthy,
+        scopeChecks,
+        informationalChecks: input.checks.filter(({ name }) => !selectedNames.has(name)),
+    };
+};
+const isProviderCheck = (name, inspections) => name.startsWith("hopper") ||
+    inspections?.some(({ id }) => doctorProviderCheckName(id, name)) === true;
+const configuredProviderChecks = (checks, providers) => checks.filter(({ name }) => name.startsWith("hopper")
+    ? providers.hopperConfigured
+    : providers.providerInspections?.some(({ id, configured }) => configured && doctorProviderCheckName(id, name)) === true);
+const selectedProviderChecksFor = (providerId, checks, providers) => {
+    const selected = checks.filter(({ name }) => providerId === "hopper"
+        ? name.startsWith("hopper")
+        : doctorProviderCheckName(providerId, name));
+    const available = providerId === "hopper"
+        ? providers.hopperAvailable
+        : providers.providerInspections?.find(({ id }) => id === providerId)
+            ?.available === true;
+    if (available && selected.every(({ ok }) => ok))
+        return selected;
+    if (selected.some(({ ok }) => !ok))
+        return selected;
+    return [
+        ...selected,
+        {
+            name: `provider:${providerId}`,
+            ok: false,
+            classification: "missing_analysis_engine",
+            detail: `Requested provider ${providerId} is unavailable.`,
+            remediation: `Configure the ${providerId} provider, then rerun rea doctor.`,
+        },
+    ];
+};
+const selectedRegistrationCheck = (client, status) => status === undefined
+    ? {
+        name: `registration:${client}`,
+        ok: false,
+        classification: "config_drift",
+        detail: `Requested client ${client} was not detected.`,
+        remediation: `Install or select ${client}, then run rea setup --client ${client}.`,
+    }
+    : status.state === "aligned"
+        ? {
+            name: `registration:${client}`,
+            ok: true,
+            classification: "healthy",
+            detail: status.config_path,
+        }
+        : registrationCheck(status);
+const registrationCheck = (status) => ({
+    name: `registration:${status.client}`,
+    ok: false,
+    classification: "config_drift",
+    detail: status.config_path,
+    remediation: status.remediation ?? "Run rea setup, then restart the affected client.",
+});
+const selectedSkillCheck = (state, checks) => checks.find(({ name }) => name === "skill:identity") ?? {
+    name: "skill:identity",
+    ok: state === "aligned",
+    classification: state === "aligned" ? "healthy" : "config_drift",
+    ...(state === "aligned"
+        ? { detail: "Installed REA skill identity is aligned." }
+        : { remediation: "Run rea setup to update the installed REA skill." }),
+};
+const uniqueSorted = (values) => [...new Set(values)].sort((left, right) => left.localeCompare(right));
+const doctorProviderCheckName = (providerId, name) => name === providerId || name.startsWith(`${providerId}-`);

package/dist/application/EvidenceReferenceResolver.js

@@ -0,0 +1,26 @@
+import { EvidenceReferenceError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Resolve IDs without accepting the digest-shaped identifier as proof itself. */
+export const resolveEvidenceReferences = (lookup, evidenceIds, expected) => {
+    const records = [];
+    for (const evidenceId of evidenceIds) {
+        const record = lookup?.(evidenceId);
+        if (record === undefined)
+            return err(new EvidenceReferenceError(evidenceId, "missing", expectationDescription(expected), null));
+        if (expected !== undefined) {
+            const operations = expected.filter(({ operation }) => operation === record.operation);
+            if (operations.length === 0)
+                return err(new EvidenceReferenceError(evidenceId, "wrong_operation", unique(expected.map(({ operation }) => operation)).join(" | "), record.operation));
+            if (!operations.some(({ predicate }) => predicate === record.predicate_type))
+                return err(new EvidenceReferenceError(evidenceId, "wrong_predicate", unique(operations.map(({ predicate }) => predicate)).join(" | "), record.predicate_type));
+        }
+        records.push(record);
+    }
+    return ok(records);
+};
+const expectationDescription = (expected) => expected === undefined
+    ? "Evidence in the current authority"
+    : expected
+        .map(({ operation, predicate }) => `${operation}:${predicate}`)
+        .join(" | ");
+const unique = (values) => [...new Set(values)];

package/dist/application/JavaScriptApplicationEvidence.js

@@ -7,7 +7,7 @@ export const createJavaScriptApplicationEvidence = (input, result) => createEvid
     sha256: result.root_artifact_sha256,
     format: result.format,
 }, JAVASCRIPT_APPLICATION_PROVIDER, {
-    predicateType: "rea.javascript-application-analysis/v1",
+    predicateType: `rea.javascript-application-analysis/v${String(result.schema_version)}`,
     operation: "analyze_javascript_application",
     parameters: parameters(input),
     result: jsonValueSchema.parse(result),

package/dist/application/JavaScriptApplicationEvidenceGraph.js

@@ -7,7 +7,10 @@ import { managedApplicationGraphResultSchema } from "../domain/managedApplicatio
 export const parseApplicationGraphEvidence = (input) => {
     const evidence = parseEvidence(input);
     if (evidence.operation === "analyze_javascript_application" &&
-        evidence.predicate_type === "rea.javascript-application-analysis/v1" &&
+        [
+            "rea.javascript-application-analysis/v1",
+            "rea.javascript-application-analysis/v2",
+        ].includes(evidence.predicate_type) &&
         providerMatches(evidence, JAVASCRIPT_APPLICATION_PROVIDER))
         return staticApplicationSource(evidence);
     if (evidence.operation === "reconcile_javascript_runtime" &&
@@ -25,6 +28,9 @@ const staticApplicationSource = (evidence) => {
         evidence.confidence !== "derived")
         throw new TypeError("JavaScript application Evidence authority or confidence is invalid");
     const result = javascriptApplicationAnalysisResultSchema.parse(evidence.normalized_result);
+    if (evidence.predicate_type !==
+        `rea.javascript-application-analysis/v${String(result.schema_version)}`)
+        throw new TypeError("JavaScript application Evidence predicate does not match its result schema version");
     analyzeJavaScriptApplicationInputSchema.parse({
         input_path: result.input_path,
         ...evidence.parameters,
@@ -35,6 +41,7 @@ const staticApplicationSource = (evidence) => {
         graph: result.graph,
         kind: "static-application",
         rootArtifactSha256: result.root_artifact_sha256,
+        semanticGraph: result.schema_version === 2 ? result.semantic_graph : null,
     };
 };
 const staticRuntimeSource = (evidence) => {
@@ -52,6 +59,7 @@ const staticRuntimeSource = (evidence) => {
         graph: result.graph,
         kind: "static-runtime-reconciliation",
         rootArtifactSha256: applicationLayer.root_artifact_sha256,
+        semanticGraph: null,
     };
 };
 const managedApplicationSource = (evidence) => {
@@ -66,6 +74,7 @@ const managedApplicationSource = (evidence) => {
         graph: result.graph,
         kind: "managed-application",
         rootArtifactSha256: result.root_artifact_sha256,
+        semanticGraph: null,
     };
 };
 const assertApplicationSubject = (evidence, result) => {

package/dist/application/JavaScriptApplicationService.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
 import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisProtocolError, ArtifactOperationError, PermissionRequiredError, } from "../domain/errors.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { err, ok } from "../domain/result.js";
 import { createJavaScriptApplicationEvidence } from "./JavaScriptApplicationEvidence.js";
 import { reconstructJavaScriptArtifact } from "./JavaScriptArtifactReconstruction.js";
@@ -10,7 +11,7 @@ const OPERATION = "analyze_javascript_application";
 export const analyzeJavaScriptApplication = async (authority, rawInput, options = {}) => {
     const parsed = analyzeJavaScriptApplicationInputSchema.safeParse(rawInput);
     if (!parsed.success)
-        return err(new AnalysisInputError(OPERATION));
+        return err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(parsed.error.issues, rawInput)));
     return analyzeJavaScriptApplicationValidated(authority, parsed.data, options);
 };
 /** Analyze input already parsed by a trusted adapter boundary. */
@@ -50,7 +51,7 @@ export const analyzeJavaScriptApplicationValidated = async (authority, input, op
         }, options.signal);
         const { electron_summary: summary, ...application } = reconstructed;
         const result = javascriptApplicationAnalysisResultSchema.parse({
-            schema_version: 1,
+            schema_version: 2,
             ...application,
             summary,
             limitations: reconstructed.graph.limitations,

package/dist/application/JavaScriptApplicationWorkflowEvidence.js

@@ -14,6 +14,19 @@ export const createApplicationFeatureTraceEvidence = (parameters, result) => cre
     limitations: result.limitations,
     evidenceLinks: result.evidence_links,
 });
+/** Create derived Evidence for one bounded JavaScript semantic trace. */
+export const createJavaScriptSemanticTraceEvidence = (parameters, result) => createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
+    predicateType: "rea.javascript-semantic-trace/v1",
+    operation: "trace_javascript_semantics",
+    parameters,
+    result: jsonValueSchema.parse(result),
+    rawResult: null,
+    confidence: "inferred",
+    authority: "analyst-inference",
+    environment: null,
+    limitations: result.limitations,
+    evidenceLinks: result.evidence_links,
+});
 /** Create derived Evidence for one tiered application version comparison. */
 export const createApplicationVersionComparisonEvidence = (parameters, result) => createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
     predicateType: "rea.application-version-comparison/v1",
@@ -27,3 +40,16 @@ export const createApplicationVersionComparisonEvidence = (parameters, result) =
     limitations: result.limitations,
     evidenceLinks: result.evidence_links,
 });
+/** Create derived Evidence for one bounded static export-shape comparison. */
+export const createJavaScriptExportShapeComparisonEvidence = (parameters, result) => createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
+    predicateType: "rea.javascript-export-shape-comparison/v1",
+    operation: "compare_javascript_export_shapes",
+    parameters,
+    result: jsonValueSchema.parse(result),
+    rawResult: null,
+    confidence: "inferred",
+    authority: "analyst-inference",
+    environment: null,
+    limitations: result.limitations,
+    evidenceLinks: result.evidence_links,
+});

package/dist/application/JavaScriptApplicationWorkflowService.js

@@ -3,11 +3,13 @@ import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js"
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { compareJavaScriptApplicationVersions } from "../domain/javascriptApplicationVersionComparison.js";
 import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { compareJavaScriptExportShapes } from "../domain/javascriptExportShapeComparison.js";
+import { compareJavaScriptExportShapesInputSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
 import { traceApplicationFeature } from "../domain/javascriptFeatureTrace.js";
 import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
 import { err, ok } from "../domain/result.js";
 import { parseApplicationGraphEvidence, parseNativeApplicationEvidence, } from "./JavaScriptApplicationEvidenceGraph.js";
-import { createApplicationFeatureTraceEvidence, createApplicationVersionComparisonEvidence, } from "./JavaScriptApplicationWorkflowEvidence.js";
+import { createApplicationFeatureTraceEvidence, createApplicationVersionComparisonEvidence, createJavaScriptExportShapeComparisonEvidence, } from "./JavaScriptApplicationWorkflowEvidence.js";
 /** Authenticate Evidence and derive one bounded cross-layer feature trace. */
 export const traceApplicationFeatureEvidence = (rawInput) => {
     const operation = "trace_application_feature";
@@ -85,6 +87,52 @@ export const compareApplicationVersionsEvidenceValidated = (input) => {
         return workflowFailure(operation, cause);
     }
 };
+/**
+ * Authenticate both graphs and compare one exact export return shape.
+ * @public
+ */
+export const compareJavaScriptExportShapesEvidence = (rawInput) => {
+    const operation = "compare_javascript_export_shapes";
+    const parsed = compareJavaScriptExportShapesInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(operation, undefined, projectInputIssues(parsed.error.issues, rawInput)));
+    return compareJavaScriptExportShapesEvidenceValidated(parsed.data);
+};
+/** Compare exact export shapes from input parsed by a trusted adapter. */
+export const compareJavaScriptExportShapesEvidenceValidated = (input) => {
+    const operation = "compare_javascript_export_shapes";
+    try {
+        const left = parseApplicationGraphEvidence(input.left);
+        const right = parseApplicationGraphEvidence(input.right);
+        const result = compareJavaScriptExportShapes({
+            left: {
+                evidenceId: left.evidence.evidence_id,
+                graph: left.graph,
+                modulePath: input.left_module_path,
+                exportName: input.left_export_name,
+            },
+            right: {
+                evidenceId: right.evidence.evidence_id,
+                graph: right.graph,
+                modulePath: input.right_module_path,
+                exportName: input.right_export_name,
+            },
+            limits: input.limits,
+        });
+        return ok(createJavaScriptExportShapeComparisonEvidence({
+            left_evidence_id: left.evidence.evidence_id,
+            right_evidence_id: right.evidence.evidence_id,
+            left_module_path: input.left_module_path,
+            left_export_name: input.left_export_name,
+            right_module_path: input.right_module_path,
+            right_export_name: input.right_export_name,
+            limits: input.limits,
+        }, result));
+    }
+    catch (cause) {
+        return workflowFailure(operation, cause);
+    }
+};
 const workflowFailure = (operation, cause) => err(cause instanceof z.ZodError || cause instanceof TypeError
     ? new AnalysisInputError(operation)
     : new AnalysisProtocolError("JavaScript application workflow produced an invalid result", { cause }));

package/dist/application/JavaScriptArtifactReconstruction.js

@@ -9,6 +9,7 @@ import { buildJavaScriptArtifactGraph } from "./JavaScriptArtifactGraphBuilder.j
 import { artifactLimitsForReconstruction, javascriptArtifactReconstructionInputSchema, } from "./JavaScriptArtifactReconstructionInput.js";
 import { scanCanonicalArtifactInventory } from "./ArtifactInventory.js";
 import { summarizeElectronBoundaries } from "./ElectronBoundaryAnalysis.js";
+import { buildJavaScriptSemanticGraph } from "./JavaScriptSemanticGraphBuilder.js";
 /** Reconstruct one local ASAR or extracted directory without executing code. */
 export const reconstructJavaScriptArtifact = async (rawInput, signal) => {
     const input = javascriptArtifactReconstructionInputSchema.parse(rawInput);
@@ -24,6 +25,11 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal) => {
         const analysis = analyzeJavaScriptArtifactFiles(files, input, () => performance.now());
         abortIfNeeded(signal);
         const graph = buildJavaScriptArtifactGraph(snapshot, files, analysis, input);
+        const semanticGraph = buildJavaScriptSemanticGraph({
+            rootArtifactSha256: snapshot.manifest.root_sha256,
+            applicationGraph: graph,
+            analysis,
+        });
         return {
             input_path: path,
             format,
@@ -31,6 +37,7 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal) => {
             inventory_manifest_id: snapshot.manifest.manifest_id,
             inventory_graph_sha256: snapshot.manifest.graph_sha256,
             graph,
+            semantic_graph: semanticGraph,
             electron_summary: summarizeElectronBoundaries(analysis),
             statistics: {
                 relevant_files: files.files.length,

package/dist/application/JavaScriptModuleRelationships.js

@@ -2,6 +2,7 @@ import { posix } from "node:path";
 import { addAstContainsEdge, artifactLocalIdentity, } from "./JavaScriptArtifactGraphContext.js";
 import { astObservationEvidence, completeReconstructionCoverage, partialReconstructionCoverage, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
 import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
+import { projectJavaScriptExportReturnShapes } from "./JavaScriptReturnShapeProjection.js";
 /** Create one path-scoped source-module identity for every analyzed source file. */
 export const addJavaScriptSourceModules = (context) => {
     for (const analyzed of context.analysis.files) {
@@ -76,6 +77,13 @@ const addExportRelationship = (input) => {
     const { context, file, semantic, source, link } = input;
     if (link.exportedName === null)
         return;
+    const baseCoverage = semanticCoverage(semantic);
+    const returnShapes = projectJavaScriptExportReturnShapes({
+        ir: semantic.ir,
+        link,
+        modulePath: file.path,
+        baseCoverage,
+    });
     const exported = context.accumulator.addNode({
         kind: "javascript-module",
         identity: artifactLocalIdentity(file.sha256, "module-export", `${file.container_sha256}:${file.path}:${link.exportedName}`),
@@ -96,10 +104,26 @@ const addExportRelationship = (input) => {
                     path: file.path,
                     range: link.location,
                     operation: "recover-module-export",
-                    coverage: semanticCoverage(semantic),
+                    coverage: baseCoverage,
                     limitations: semantic.ir.limitations,
                 }),
             },
+            ...(returnShapes === null
+                ? []
+                : [
+                    {
+                        label: `${file.path}:${link.exportedName}:return-shapes`,
+                        properties: returnShapes.properties,
+                        evidence: staticInferenceEvidence({
+                            sha256: file.sha256,
+                            path: file.path,
+                            range: returnShapes.range,
+                            operation: "recover-export-return-shapes",
+                            coverage: returnShapes.coverage,
+                            limitations: returnShapes.limitations,
+                        }),
+                    },
+                ]),
         ],
     });
     context.accumulator.addEdge({

package/dist/application/JavaScriptReturnShapeProjection.js

@@ -0,0 +1,111 @@
+import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
+import { flattenSemanticReturnValue } from "../domain/javascriptSemanticReturns.js";
+import { partialReconstructionCoverage } from "./JavaScriptArtifactGraphEvidence.js";
+const MAX_PROJECTED_RETURN_SHAPES = 32;
+const MAX_PROJECTED_RETURN_FIELDS = 64;
+const MAX_PROJECTED_PROPERTY_COVERAGE = 64;
+/** Project one exact export/callable link into shallow bounded graph values. */
+export const projectJavaScriptExportReturnShapes = (input) => {
+    if (input.link.callableId === null || input.link.exportedName === null)
+        return null;
+    const callable = input.ir.callables.find(({ callableId }) => callableId === input.link.callableId);
+    if (callable === undefined)
+        return null;
+    const projection = projectReturnSites(callable);
+    const projectionOmitted = projection.omittedSites +
+        projection.omittedFields +
+        projection.omittedCoverage;
+    const semanticOmitted = callable.returnCoverage.omittedCount;
+    const complete = input.baseCoverage.status === "complete" &&
+        callable.returnCoverage.status === "complete" &&
+        projectionOmitted === 0;
+    const coverage = complete
+        ? input.baseCoverage
+        : partialReconstructionCoverage([
+            ...input.baseCoverage.limits,
+            {
+                name: "return-shape-sites",
+                value: MAX_PROJECTED_RETURN_SHAPES,
+                unit: "items",
+            },
+            {
+                name: "return-shape-fields",
+                value: MAX_PROJECTED_RETURN_FIELDS,
+                unit: "items",
+            },
+            {
+                name: "return-shape-property-coverage",
+                value: MAX_PROJECTED_PROPERTY_COVERAGE,
+                unit: "items",
+            },
+        ], semanticOmitted === null ? null : semanticOmitted + projectionOmitted, callable.returnCoverage.status === "truncated" || projectionOmitted > 0);
+    const limitations = [
+        ...input.ir.limitations,
+        "Return shapes are inferred from inert syntax and do not prove runtime behavior.",
+        ...(callable.returnSites.length === 0
+            ? [
+                "No direct return value was retained; runtime return behavior remains unknown.",
+            ]
+            : []),
+        ...(projectionOmitted > 0
+            ? ["Return-shape graph projection reached explicit retention limits."]
+            : []),
+    ];
+    return {
+        properties: jsonObjectSchema.parse({
+            semantic_role: "export-return-shapes",
+            module_path: input.modulePath,
+            exported_name: input.link.exportedName,
+            callable_id: callable.callableId,
+            callable_kind: callable.kind,
+            static_return_shapes: projection.shapes,
+            return_shape_coverage: {
+                status: callable.returnCoverage.status,
+                retained_return_sites: projection.shapes.length,
+                omitted_return_sites: semanticOmitted === null
+                    ? null
+                    : semanticOmitted + projection.omittedSites,
+                omitted_fields: projection.omittedFields,
+                omitted_property_coverage: projection.omittedCoverage,
+                projection_complete: projectionOmitted === 0,
+            },
+        }),
+        range: callable.location,
+        coverage,
+        limitations,
+    };
+};
+const projectReturnSites = (callable) => {
+    let retainedFields = 0;
+    let retainedCoverage = 0;
+    let omittedFields = 0;
+    let omittedCoverage = 0;
+    const retainedSites = callable.returnSites.slice(0, MAX_PROJECTED_RETURN_SHAPES);
+    const shapes = retainedSites.map((site) => {
+        const flattened = flattenSemanticReturnValue(site.value);
+        const remainingFields = Math.max(0, MAX_PROJECTED_RETURN_FIELDS - retainedFields);
+        const fields = flattened.fields.slice(0, remainingFields).map((field) => ({
+            ...field,
+            value: jsonValueSchema.parse(field.value),
+        }));
+        retainedFields += fields.length;
+        omittedFields += flattened.fields.length - fields.length;
+        const remainingCoverage = Math.max(0, MAX_PROJECTED_PROPERTY_COVERAGE - retainedCoverage);
+        const propertyCoverage = flattened.propertyCoverage.slice(0, remainingCoverage);
+        retainedCoverage += propertyCoverage.length;
+        omittedCoverage +=
+            flattened.propertyCoverage.length - propertyCoverage.length;
+        return {
+            source_range: site.location,
+            value_status: site.value.status,
+            fields,
+            property_coverage: propertyCoverage,
+        };
+    });
+    return {
+        shapes,
+        omittedSites: callable.returnSites.length - retainedSites.length,
+        omittedFields,
+        omittedCoverage,
+    };
+};