reverseport 0.0.0-stage → 1.2.0

package/dist/domain/javascript/javascriptExportReturnShapeProjection.js

@@ -0,0 +1,81 @@
+import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js";
+import { partialApplicationCoverage, truncatedApplicationCoverage, } from "./javascriptApplicationEvidenceSchemas.js";
+import { flattenSemanticReturnValue } from "./javascriptSemanticReturns.js";
+/** Project one exact export/callable link into inert return-shape observations. */
+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 limits = input.baseCoverage.limits;
+    const omitted = semanticOmitted === null ? null : semanticOmitted + projectionOmitted;
+    const coverage = complete
+        ? input.baseCoverage
+        : projectionOmitted > 0
+            ? truncatedApplicationCoverage(limits, omitted)
+            : partialApplicationCoverage(limits, omitted);
+    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.",
+            ]
+            : []),
+    ];
+    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) => {
+    const retainedSites = callable.returnSites;
+    const shapes = retainedSites.map((site) => {
+        const flattened = flattenSemanticReturnValue(site.value);
+        const fields = flattened.fields.map((field) => ({
+            ...field,
+            value: jsonValueSchema.parse(field.value),
+        }));
+        const propertyCoverage = flattened.propertyCoverage;
+        return {
+            source_range: site.location,
+            value_status: site.value.status,
+            fields,
+            property_coverage: propertyCoverage,
+        };
+    });
+    return {
+        shapes,
+        omittedSites: 0,
+        omittedFields: 0,
+        omittedCoverage: 0,
+    };
+};

package/dist/domain/javascript/javascriptExportShapeComparison.js

@@ -0,0 +1,161 @@
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+import { canonicalExportShapeValue, digestExportShapeValue, } from "./javascriptExportShapeComparisonIdentity.js";
+import { javaScriptExportShapeComparisonResultSchema, } from "./javascriptExportShapeComparisonSchemas.js";
+import { retainJavaScriptExportShapes, selectJavaScriptExport, } from "./javascriptExportShapeSelection.js";
+import { buildJavaScriptExportShapeChanges, buildJavaScriptExportShapeInventories, hasPartialJavaScriptExportPropertyCoverage, pairJavaScriptExportShapeVariants, } from "./javascriptExportShapeVariants.js";
+/** Compare exact selected export return shapes without executing JavaScript. */
+export const compareJavaScriptExportShapes = (input) => {
+    const left = selectJavaScriptExport(input.left);
+    const right = selectJavaScriptExport(input.right);
+    const leftRetained = retainJavaScriptExportShapes(left);
+    const rightRetained = retainJavaScriptExportShapes(right);
+    const pairing = pairJavaScriptExportShapeVariants(leftRetained.shapes, rightRetained.shapes);
+    const evidenceLinks = evidencePair(input.left.evidenceId, input.right.evidenceId);
+    const allChanges = sortChanges(buildJavaScriptExportShapeChanges({
+        leftSelection: left,
+        rightSelection: right,
+        pairing,
+        leftShapes: leftRetained.shapes,
+        rightShapes: rightRetained.shapes,
+        evidenceLinks,
+    }));
+    const changes = allChanges;
+    const omittedChanges = 0;
+    const propertyInventories = buildJavaScriptExportShapeInventories({
+        pairing,
+        leftShapes: leftRetained.shapes,
+        rightShapes: rightRetained.shapes,
+    });
+    const coverage = comparisonCoverage({
+        input,
+        left,
+        right,
+        leftRetained,
+        rightRetained,
+        pairing,
+        allChanges,
+        omittedChanges,
+    });
+    const limitations = comparisonLimitations(left, right, coverage.status);
+    const semantic = {
+        left: left.selection,
+        right: right.selection,
+        property_inventories: propertyInventories,
+        summary: summarize(allChanges),
+        changes,
+        coverage,
+        evidence_links: evidenceLinks,
+        limitations,
+    };
+    return javaScriptExportShapeComparisonResultSchema.parse({
+        ...semantic,
+        comparison_id: `jesc_${digestExportShapeValue(semantic)}`,
+    });
+};
+const sortChanges = (changes) => changes
+    .map((change, index) => ({
+    change,
+    index,
+    sortKey: canonicalExportShapeValue({
+        discriminant: change.discriminant,
+        path: change.path,
+        status: change.status,
+        left_source_range: change.left_source_range,
+        right_source_range: change.right_source_range,
+        change_id: change.change_id,
+    }),
+}))
+    .sort((left, right) => compareUnicodeCodePoints(left.sortKey, right.sortKey) ||
+    left.index - right.index)
+    .map(({ change }) => change);
+const comparisonCoverage = (context) => {
+    const leftSource = context.left.projection?.return_shape_coverage;
+    const rightSource = context.right.projection?.return_shape_coverage;
+    const omittedCandidates = context.left.selection.omitted_candidates +
+        context.right.selection.omitted_candidates;
+    const truncated = comparisonTruncated(context, omittedCandidates);
+    const partial = comparisonPartial(context);
+    return {
+        status: truncated
+            ? "truncated"
+            : partial
+                ? "partial"
+                : "complete-within-inputs",
+        left_graph_status: context.input.left.graph.coverage.status,
+        right_graph_status: context.input.right.graph.coverage.status,
+        paired_variants: context.pairing.pairs.length,
+        unpaired_left_variants: context.pairing.unpairedLeft.length,
+        unpaired_right_variants: context.pairing.unpairedRight.length,
+        omitted_left_variants: context.leftRetained.omitted,
+        omitted_right_variants: context.rightRetained.omitted,
+        left_source_omitted_variants: leftSource?.omitted_return_sites ?? null,
+        right_source_omitted_variants: rightSource?.omitted_return_sites ?? null,
+        left_omitted_fields: leftSource?.omitted_fields ?? 0,
+        right_omitted_fields: rightSource?.omitted_fields ?? 0,
+        left_omitted_property_coverage: leftSource?.omitted_property_coverage ?? 0,
+        right_omitted_property_coverage: rightSource?.omitted_property_coverage ?? 0,
+        omitted_candidates: omittedCandidates,
+        omitted_changes: context.omittedChanges,
+    };
+};
+const comparisonTruncated = (context, omittedCandidates) => context.leftRetained.omitted > 0 ||
+    context.rightRetained.omitted > 0 ||
+    omittedCandidates > 0 ||
+    context.omittedChanges > 0 ||
+    sourceProjectionTruncated(context.left) ||
+    sourceProjectionTruncated(context.right);
+const sourceProjectionTruncated = (selection) => {
+    const coverage = selection.projection?.return_shape_coverage;
+    if (coverage === undefined)
+        return false;
+    return (coverage.status === "truncated" ||
+        coverage.omitted_fields > 0 ||
+        coverage.omitted_property_coverage > 0 ||
+        coverage.projection_complete === false);
+};
+const comparisonPartial = (context) => selectionPartial(context.left) ||
+    selectionPartial(context.right) ||
+    context.input.left.graph.coverage.status !== "complete" ||
+    context.input.right.graph.coverage.status !== "complete" ||
+    hasPartialJavaScriptExportPropertyCoverage(context.leftRetained.shapes) ||
+    hasPartialJavaScriptExportPropertyCoverage(context.rightRetained.shapes) ||
+    context.pairing.unpairedLeft.length > 0 ||
+    context.pairing.unpairedRight.length > 0 ||
+    context.allChanges.some(({ status }) => status === "unknown");
+const selectionPartial = (selection) => {
+    const coverage = selection.projection?.return_shape_coverage;
+    return (selection.selection.status !== "selected" ||
+        !selection.observationComplete ||
+        coverage?.status !== "complete" ||
+        coverage.projection_complete !== true);
+};
+const comparisonLimitations = (left, right, status) => uniqueSorted([
+    "Return shapes are inferred from inert syntax and do not prove runtime behavior.",
+    "Return variants are paired only by unique exact literal discriminants, never by source order.",
+    "Dynamic values, incomplete object coverage, and ambiguous variants remain unknown.",
+    "This static comparison cannot establish runtime semantics; run behavioral probes directly against the relevant application versions when that evidence is required.",
+    ...left.limitations,
+    ...right.limitations,
+    ...(status === "truncated"
+        ? [
+            "Comparison output or source return-shape recovery reached an explicit limit.",
+        ]
+        : []),
+    ...(status === "partial"
+        ? [
+            "At least one selector, graph, return shape, or property boundary is incomplete.",
+        ]
+        : []),
+]);
+const summarize = (changes) => ({
+    added: countStatus(changes, "added"),
+    removed: countStatus(changes, "removed"),
+    changed: countStatus(changes, "changed"),
+    unknown: countStatus(changes, "unknown"),
+});
+const countStatus = (changes, status) => changes.filter((change) => change.status === status).length;
+const evidencePair = (left, right) => [
+    left,
+    right,
+];

package/dist/domain/javascript/javascriptExportShapeComparisonIdentity.js

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+/**
+ * Canonically encode one export-shape comparison value.
+ *
+ * Comparison identifiers hash the full result semantics, including each
+ * change's presence object and the per-variant property inventories.
+ */
+export const canonicalExportShapeValue = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("JavaScript export shape comparison could not canonicalize data");
+    return encoded;
+};
+/** Derive one deterministic SHA-256 comparison identifier component. */
+export const digestExportShapeValue = (value) => createHash("sha256").update(canonicalExportShapeValue(value)).digest("hex");

package/dist/domain/javascript/javascriptExportShapeComparisonSchemas.js

@@ -0,0 +1,302 @@
+import { z } from "zod";
+import { evidenceSchema } from "../evidence.js";
+import { prefixedDigestSchema } from "../digests.js";
+const evidenceIdSchema = prefixedDigestSchema("ev");
+const graphIdSchema = prefixedDigestSchema("jag");
+const nodeIdSchema = prefixedDigestSchema("jag_node");
+const textSchema = z.string().min(1);
+const semanticPrimitiveSchema = z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+]);
+function isJsonPointer(value) {
+    if (value === "")
+        return true;
+    if (!value.startsWith("/"))
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        if (value[index] !== "~")
+            continue;
+        const escaped = value[index + 1];
+        if (escaped !== "0" && escaped !== "1")
+            return false;
+        index += 1;
+    }
+    return true;
+}
+const jsonPointerSchema = z
+    .string()
+    .refine(isJsonPointer, "Expected an RFC 6901 JSON Pointer");
+const sourcePointSchema = z.strictObject({
+    line: z.number().int().min(1),
+    column: z.number().int().min(0),
+});
+const sourceRangeSchema = z
+    .strictObject({
+    start: sourcePointSchema,
+    end: sourcePointSchema,
+})
+    .superRefine((range, context) => {
+    if (range.end.line < range.start.line ||
+        (range.end.line === range.start.line &&
+            range.end.column < range.start.column))
+        context.addIssue({
+            code: "custom",
+            path: ["end"],
+            message: "Source range end must not precede its start",
+        });
+});
+/** Check that export-shape comparisons bind distinct source Evidence. */
+const validateJavaScriptExportShapeIdentities = (input, context) => {
+    if (input.left.evidence_id === input.right.evidence_id)
+        context.addIssue({
+            code: "custom",
+            path: ["right"],
+            message: "JavaScript export shape Evidence must be distinct",
+        });
+};
+const evidenceIdentitySchema = z.object({ evidence_id: evidenceIdSchema });
+/** Validate export-shape identities without capturing complete source graphs. */
+export const javaScriptExportShapeIdentitiesSchema = z
+    .object({
+    left: evidenceIdentitySchema,
+    right: evidenceIdentitySchema,
+})
+    .superRefine(validateJavaScriptExportShapeIdentities);
+/** Two authenticated application graphs and exact export selectors. */
+export const compareJavaScriptExportShapesInputSchema = z
+    .strictObject({
+    left: evidenceSchema,
+    right: evidenceSchema,
+    left_module_path: textSchema,
+    left_export_name: textSchema,
+    right_module_path: textSchema,
+    right_export_name: textSchema,
+})
+    .superRefine(validateJavaScriptExportShapeIdentities);
+const projectedReturnFieldShape = {
+    path: jsonPointerSchema,
+    presence: z.enum(["present", "absent", "unknown-coverage"]),
+};
+const projectedReturnFieldSchema = z.discriminatedUnion("state", [
+    z.strictObject({
+        ...projectedReturnFieldShape,
+        state: z.literal("literal"),
+        value: semanticPrimitiveSchema,
+        reason: z.null(),
+    }),
+    z.strictObject({
+        ...projectedReturnFieldShape,
+        state: z.literal("union"),
+        value: z.array(semanticPrimitiveSchema).min(1),
+        reason: z.null(),
+    }),
+    z.strictObject({
+        ...projectedReturnFieldShape,
+        state: z.literal("unknown"),
+        value: z.null(),
+        reason: textSchema,
+    }),
+]);
+const projectedPropertyCoverageSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        path: jsonPointerSchema,
+        status: z.literal("complete"),
+        omitted: z.literal(0),
+    }),
+    z.strictObject({
+        path: jsonPointerSchema,
+        status: z.literal("partial"),
+        omitted: z.union([z.number().int().positive(), z.null()]),
+    }),
+]);
+const projectedReturnShapeSchema = z
+    .strictObject({
+    source_range: sourceRangeSchema,
+    value_status: z.enum([
+        "literal",
+        "union",
+        "object",
+        "array",
+        "unknown",
+        "ambiguous",
+        "cycle",
+    ]),
+    fields: z.array(projectedReturnFieldSchema),
+    property_coverage: z.array(projectedPropertyCoverageSchema),
+})
+    .superRefine((shape, context) => {
+    const fieldPaths = shape.fields.map(({ path }) => path);
+    if (new Set(fieldPaths).size !== fieldPaths.length)
+        context.addIssue({
+            code: "custom",
+            path: ["fields"],
+            message: "Projected return field paths must be unique",
+        });
+    const coveragePaths = shape.property_coverage.map(({ path }) => path);
+    if (new Set(coveragePaths).size !== coveragePaths.length)
+        context.addIssue({
+            code: "custom",
+            path: ["property_coverage"],
+            message: "Projected property coverage paths must be unique",
+        });
+});
+/** Strict graph-observation payload produced by static return-shape recovery. */
+export const projectedExportReturnShapesSchema = z
+    .strictObject({
+    semantic_role: z.literal("export-return-shapes"),
+    module_path: textSchema,
+    exported_name: textSchema,
+    callable_id: textSchema,
+    callable_kind: z.enum(["function", "class", "method"]),
+    static_return_shapes: z.array(projectedReturnShapeSchema),
+    return_shape_coverage: z.strictObject({
+        status: z.enum(["complete", "partial", "truncated"]),
+        retained_return_sites: z.number().int().min(0),
+        omitted_return_sites: z.number().int().min(0).nullable(),
+        omitted_fields: z.number().int().min(0),
+        omitted_property_coverage: z.number().int().min(0),
+        projection_complete: z.boolean(),
+    }),
+})
+    .superRefine((projection, context) => {
+    if (projection.return_shape_coverage.retained_return_sites !==
+        projection.static_return_shapes.length)
+        context.addIssue({
+            code: "custom",
+            path: ["return_shape_coverage", "retained_return_sites"],
+            message: "Retained return-site count must match projected shapes",
+        });
+});
+const exportCandidateSchema = z.strictObject({
+    node_id: nodeIdSchema,
+    module_path: textSchema,
+    export_name: textSchema,
+    matches_requested_module: z.boolean(),
+    matches_requested_export: z.boolean(),
+});
+const selectorResultShape = {
+    evidence_id: evidenceIdSchema,
+    graph_id: graphIdSchema,
+    requested_module_path: textSchema,
+    requested_export_name: textSchema,
+    candidates: z.array(exportCandidateSchema),
+    omitted_candidates: z.number().int().min(0),
+};
+const selectorResultSchema = z.union([
+    z.strictObject({
+        ...selectorResultShape,
+        status: z.literal("selected"),
+        selected_node_id: nodeIdSchema,
+    }),
+    z.strictObject({
+        ...selectorResultShape,
+        status: z.enum(["missing", "ambiguous"]),
+        selected_node_id: z.null(),
+    }),
+    z.strictObject({
+        ...selectorResultShape,
+        status: z.literal("unavailable"),
+        selected_node_id: nodeIdSchema.nullable(),
+    }),
+]);
+const valueAvailabilitySchema = z.discriminatedUnion("availability", [
+    z.strictObject({ availability: z.literal("absent") }),
+    z.strictObject({
+        availability: z.literal("literal"),
+        value: semanticPrimitiveSchema,
+    }),
+    z.strictObject({
+        availability: z.literal("union"),
+        values: z.array(semanticPrimitiveSchema).min(1),
+    }),
+    z.strictObject({
+        availability: z.literal("unknown"),
+        reason: textSchema,
+    }),
+]);
+const discriminantSchema = z.strictObject({
+    path: jsonPointerSchema,
+    value: semanticPrimitiveSchema,
+});
+const propertyPresenceSchema = z.enum([
+    "present",
+    "absent",
+    "unknown-coverage",
+]);
+/** One change row; presence is required even when values stay unknown. */
+export const javaScriptExportShapeComparisonChangeSchema = z.strictObject({
+    change_id: prefixedDigestSchema("jesc_change"),
+    status: z.enum(["added", "removed", "changed", "unknown"]),
+    path: jsonPointerSchema,
+    discriminant: discriminantSchema.nullable(),
+    presence: z.strictObject({
+        left: propertyPresenceSchema,
+        right: propertyPresenceSchema,
+    }),
+    left: valueAvailabilitySchema,
+    right: valueAvailabilitySchema,
+    left_source_range: sourceRangeSchema.nullable(),
+    right_source_range: sourceRangeSchema.nullable(),
+    evidence_links: z.array(evidenceIdSchema).length(2),
+    limitations: z.array(textSchema),
+});
+const inventoryPropertyCoverageSchema = z.strictObject({
+    path: jsonPointerSchema,
+    status: z.enum(["complete", "partial"]),
+});
+const propertyInventorySchema = z.strictObject({
+    side: z.enum(["left", "right"]),
+    variant_index: z.number().int().nonnegative(),
+    discriminant: discriminantSchema.nullable(),
+    paired: z.boolean(),
+    source_range: sourceRangeSchema,
+    properties: z.array(jsonPointerSchema),
+    property_coverage: z.array(inventoryPropertyCoverageSchema),
+});
+/** Static export-return comparison with explicit unknown semantics. */
+export const javaScriptExportShapeComparisonResultSchema = z.strictObject({
+    comparison_id: prefixedDigestSchema("jesc"),
+    left: selectorResultSchema,
+    right: selectorResultSchema,
+    property_inventories: z.array(propertyInventorySchema),
+    summary: z.strictObject({
+        added: z.number().int().min(0),
+        removed: z.number().int().min(0),
+        changed: z.number().int().min(0),
+        unknown: z.number().int().min(0),
+    }),
+    changes: z.array(javaScriptExportShapeComparisonChangeSchema),
+    coverage: z.strictObject({
+        status: z.enum(["complete-within-inputs", "partial", "truncated"]),
+        left_graph_status: z.enum([
+            "complete",
+            "partial",
+            "unknown",
+            "unavailable",
+        ]),
+        right_graph_status: z.enum([
+            "complete",
+            "partial",
+            "unknown",
+            "unavailable",
+        ]),
+        paired_variants: z.number().int().min(0),
+        unpaired_left_variants: z.number().int().min(0),
+        unpaired_right_variants: z.number().int().min(0),
+        omitted_left_variants: z.number().int().min(0),
+        omitted_right_variants: z.number().int().min(0),
+        left_source_omitted_variants: z.number().int().min(0).nullable(),
+        right_source_omitted_variants: z.number().int().min(0).nullable(),
+        left_omitted_fields: z.number().int().min(0),
+        right_omitted_fields: z.number().int().min(0),
+        left_omitted_property_coverage: z.number().int().min(0),
+        right_omitted_property_coverage: z.number().int().min(0),
+        omitted_candidates: z.number().int().min(0),
+        omitted_changes: z.number().int().min(0),
+    }),
+    evidence_links: z.array(evidenceIdSchema).length(2),
+    limitations: z.array(textSchema),
+});

package/dist/domain/javascript/javascriptExportShapeSelection.js

@@ -0,0 +1,130 @@
+import { projectedExportReturnShapesSchema, } from "./javascriptExportShapeComparisonSchemas.js";
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+/** Select one exact trusted export and its exact static return-shape observation. */
+export const selectJavaScriptExport = (side) => {
+    const candidates = exportCandidates(side.graph);
+    const exact = candidates.filter(({ modulePath, exportName }) => modulePath === side.modulePath && exportName === side.exportName);
+    const matchingOneSelector = candidates.filter(({ modulePath, exportName }) => modulePath === side.modulePath || exportName === side.exportName);
+    const diagnosticPool = exact.length > 0
+        ? exact
+        : matchingOneSelector.length > 0
+            ? matchingOneSelector
+            : candidates;
+    const base = selectorBase(side, diagnosticPool);
+    if (exact.length === 0)
+        return unresolvedSelection(base, { status: "missing", selected_node_id: null }, [
+            `No exact export binding matched ${side.modulePath}:${side.exportName}.`,
+        ]);
+    if (exact.length > 1)
+        return unresolvedSelection(base, { status: "ambiguous", selected_node_id: null }, [
+            `Multiple exact export bindings matched ${side.modulePath}:${side.exportName}; none was selected.`,
+        ]);
+    const selected = exact[0];
+    if (selected === undefined || !selected.trusted)
+        return unresolvedSelection(base, {
+            status: "unavailable",
+            selected_node_id: selected?.node.node_id ?? null,
+        }, [
+            "The exact export binding lacks the expected static-analysis authority.",
+        ]);
+    const returnShape = returnShapeFor(selected.node, side);
+    if (returnShape.projection === null)
+        return unresolvedSelection(base, { status: "unavailable", selected_node_id: selected.node.node_id }, [returnShape.reason]);
+    return {
+        selection: {
+            ...base,
+            status: "selected",
+            selected_node_id: selected.node.node_id,
+        },
+        projection: returnShape.projection,
+        observationComplete: returnShape.observationComplete,
+        limitations: [],
+    };
+};
+/** Retain every authenticated variant with its explicit slot presence. */
+export const retainJavaScriptExportShapes = (selection) => ({
+    shapes: selection.projection?.static_return_shapes ?? [],
+    omitted: 0,
+});
+const selectorBase = (side, candidates) => ({
+    evidence_id: side.evidenceId,
+    graph_id: side.graph.graph_id,
+    requested_module_path: side.modulePath,
+    requested_export_name: side.exportName,
+    candidates: candidates.map((candidate) => ({
+        node_id: candidate.node.node_id,
+        module_path: candidate.modulePath,
+        export_name: candidate.exportName,
+        matches_requested_module: candidate.modulePath === side.modulePath,
+        matches_requested_export: candidate.exportName === side.exportName,
+    })),
+    omitted_candidates: 0,
+});
+const unresolvedSelection = (base, resolution, limitations) => ({
+    selection: { ...base, ...resolution },
+    projection: null,
+    observationComplete: false,
+    limitations,
+});
+const exportCandidates = (graph) => {
+    const candidates = new Map();
+    for (const node of graph.nodes) {
+        for (const observation of node.observations) {
+            const properties = observation.properties;
+            if (properties.semantic_role !== "export-binding")
+                continue;
+            const modulePath = properties.module_path;
+            const exportName = properties.exported_name;
+            if (typeof modulePath !== "string" || typeof exportName !== "string")
+                continue;
+            const key = `${node.node_id}\0${modulePath}\0${exportName}`;
+            const trusted = observation.evidence.authority === "ast-static-analysis" &&
+                observation.evidence.state === "observed" &&
+                observation.evidence.extractor.operation === "recover-module-export";
+            const existing = candidates.get(key);
+            candidates.set(key, {
+                node,
+                modulePath,
+                exportName,
+                trusted: trusted || existing?.trusted === true,
+            });
+        }
+    }
+    return [...candidates.values()].sort((left, right) => compareUnicodeCodePoints(candidateKey(left), candidateKey(right)));
+};
+const candidateKey = (candidate) => `${candidate.modulePath}\0${candidate.exportName}\0${candidate.node.node_id}`;
+const returnShapeFor = (node, side) => {
+    const roleObservations = node.observations.filter(({ properties }) => properties.semantic_role === "export-return-shapes");
+    const parsed = roleObservations.map((observation) => ({
+        observation,
+        result: projectedExportReturnShapesSchema.safeParse(observation.properties),
+    }));
+    if (parsed.some(({ result }) => !result.success))
+        return unavailableReturnShape("The export return-shape observation is malformed.");
+    const matching = parsed.filter(({ result }) => result.success &&
+        result.data.module_path === side.modulePath &&
+        result.data.exported_name === side.exportName);
+    if (matching.length !== 1)
+        return unavailableReturnShape(matching.length === 0
+            ? "No exact static return-shape observation is available for the selected export."
+            : "Multiple static return-shape observations matched the selected export.");
+    const selected = matching[0];
+    if (selected === undefined || !selected.result.success)
+        return unavailableReturnShape("The selected return-shape observation could not be parsed.");
+    const { observation } = selected;
+    const trusted = observation.evidence.authority === "static-relationship-inference" &&
+        observation.evidence.state === "inferred" &&
+        observation.evidence.extractor.operation === "recover-export-return-shapes";
+    if (!trusted)
+        return unavailableReturnShape("The return-shape observation lacks the expected static-inference authority.");
+    return {
+        projection: selected.result.data,
+        observationComplete: observation.evidence.coverage.status === "complete" &&
+            !observation.evidence.coverage.truncated,
+    };
+};
+const unavailableReturnShape = (reason) => ({
+    projection: null,
+    observationComplete: false,
+    reason,
+});