rea-agents 2.1.0 → 2.3.0

package/dist/domain/javascriptExportShapeComparisonSchemas.js

@@ -0,0 +1,277 @@
+import { z } from "zod";
+import { evidenceSchema } from "./evidence.js";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const graphIdSchema = z.string().regex(/^jag_[a-f0-9]{64}$/u);
+const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
+const boundedTextSchema = z.string().min(1).max(4_096);
+const selectorTextSchema = z.string().min(1).max(4_096);
+const semanticPrimitiveSchema = z.union([
+    z.string().max(4_096),
+    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()
+    .max(4_096)
+    .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",
+        });
+});
+const comparisonLimitsSchema = z.strictObject({
+    max_candidate_exports: z.number().int().min(1).max(1_000).default(100),
+    max_return_variants: z.number().int().min(1).max(1_000).default(128),
+    max_changes: z.number().int().min(1).max(10_000).default(1_000),
+});
+/** Two authenticated application graphs, exact export selectors, and bounds. */
+export const compareJavaScriptExportShapesInputSchema = z
+    .strictObject({
+    left: evidenceSchema,
+    right: evidenceSchema,
+    left_module_path: selectorTextSchema,
+    left_export_name: selectorTextSchema,
+    right_module_path: selectorTextSchema,
+    right_export_name: selectorTextSchema,
+    limits: comparisonLimitsSchema.default({
+        max_candidate_exports: 100,
+        max_return_variants: 128,
+        max_changes: 1_000,
+    }),
+    unknown_registry_approved: z.literal(true).optional(),
+})
+    .superRefine((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 projectedReturnFieldSchema = z
+    .strictObject({
+    path: jsonPointerSchema,
+    state: z.enum(["literal", "union", "unknown"]),
+    value: z.union([
+        semanticPrimitiveSchema,
+        z.array(semanticPrimitiveSchema).min(1).max(32),
+    ]),
+    reason: boundedTextSchema.nullable(),
+})
+    .superRefine((field, context) => {
+    if (field.state === "union" && !Array.isArray(field.value))
+        context.addIssue({
+            code: "custom",
+            path: ["value"],
+            message: "Union return fields require a primitive value array",
+        });
+    if (field.state !== "union" && Array.isArray(field.value))
+        context.addIssue({
+            code: "custom",
+            path: ["value"],
+            message: "Only union return fields may contain a value array",
+        });
+    if (field.state === "unknown" && field.reason === null)
+        context.addIssue({
+            code: "custom",
+            path: ["reason"],
+            message: "Unknown return fields require a reason",
+        });
+    if (field.state !== "unknown" && field.reason !== null)
+        context.addIssue({
+            code: "custom",
+            path: ["reason"],
+            message: "Known return fields cannot carry an unknown reason",
+        });
+});
+const projectedPropertyCoverageSchema = z.strictObject({
+    path: jsonPointerSchema,
+    status: z.enum(["complete", "partial"]),
+    omitted: z.number().int().min(0).nullable(),
+});
+const projectedReturnShapeSchema = z
+    .strictObject({
+    source_range: sourceRangeSchema,
+    value_status: z.enum([
+        "literal",
+        "union",
+        "object",
+        "array",
+        "unknown",
+        "ambiguous",
+        "cycle",
+        "limit-reached",
+    ]),
+    fields: z.array(projectedReturnFieldSchema).max(64),
+    property_coverage: z.array(projectedPropertyCoverageSchema).max(64),
+})
+    .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: selectorTextSchema,
+    exported_name: selectorTextSchema,
+    callable_id: boundedTextSchema,
+    callable_kind: z.enum(["function", "class", "method"]),
+    static_return_shapes: z.array(projectedReturnShapeSchema).max(32),
+    return_shape_coverage: z.strictObject({
+        status: z.enum(["complete", "partial", "truncated"]),
+        retained_return_sites: z.number().int().min(0).max(32),
+        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: selectorTextSchema,
+    export_name: selectorTextSchema,
+    matches_requested_module: z.boolean(),
+    matches_requested_export: z.boolean(),
+});
+const selectorResultSchema = z.strictObject({
+    evidence_id: evidenceIdSchema,
+    graph_id: graphIdSchema,
+    requested_module_path: selectorTextSchema,
+    requested_export_name: selectorTextSchema,
+    status: z.enum(["selected", "missing", "ambiguous", "unavailable"]),
+    selected_node_id: nodeIdSchema.nullable(),
+    candidates: z.array(exportCandidateSchema).max(1_000),
+    omitted_candidates: z.number().int().min(0),
+});
+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).max(32),
+    }),
+    z.strictObject({
+        availability: z.literal("unknown"),
+        reason: boundedTextSchema,
+    }),
+]);
+const discriminantSchema = z.strictObject({
+    path: jsonPointerSchema,
+    value: semanticPrimitiveSchema,
+});
+const comparisonChangeSchema = z.strictObject({
+    change_id: z.string().regex(/^jesc_change_[a-f0-9]{64}$/u),
+    status: z.enum(["added", "removed", "changed", "unknown"]),
+    path: jsonPointerSchema,
+    discriminant: discriminantSchema.nullable(),
+    left: valueAvailabilitySchema,
+    right: valueAvailabilitySchema,
+    left_source_range: sourceRangeSchema.nullable(),
+    right_source_range: sourceRangeSchema.nullable(),
+    evidence_links: z.tuple([evidenceIdSchema, evidenceIdSchema]),
+    limitations: z.array(boundedTextSchema).max(20),
+});
+/** Bounded static export-return comparison with explicit unknown semantics. */
+export const javaScriptExportShapeComparisonResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    comparison_id: z.string().regex(/^jesc_[a-f0-9]{64}$/u),
+    left: selectorResultSchema,
+    right: selectorResultSchema,
+    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(comparisonChangeSchema).max(10_000),
+    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.tuple([evidenceIdSchema, evidenceIdSchema]),
+    limitations: z.array(boundedTextSchema).max(1_000),
+    runtime_validation: z.strictObject({
+        recommended_tool: z.literal("run_controlled_replay"),
+        automatically_started: z.literal(false),
+        required_for: z.literal("runtime-semantics"),
+    }),
+});

package/dist/domain/javascriptExportShapeSelection.js

@@ -0,0 +1,132 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { projectedExportReturnShapesSchema, } from "./javascriptExportShapeComparisonSchemas.js";
+/** Select one exact trusted export and its exact static return-shape observation. */
+export const selectJavaScriptExport = (side, maxCandidates) => {
+    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 retainedCandidates = diagnosticPool.slice(0, maxCandidates);
+    const base = selectorBase(side, diagnosticPool, retainedCandidates);
+    if (exact.length === 0)
+        return unresolvedSelection(base, "missing", null, [
+            `No exact export binding matched ${side.modulePath}:${side.exportName}.`,
+        ]);
+    if (exact.length > 1)
+        return unresolvedSelection(base, "ambiguous", 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, "unavailable", 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, "unavailable", 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: [],
+    };
+};
+/** Apply the caller's explicit return-variant limit. */
+export const retainJavaScriptExportShapes = (selection, maximum) => {
+    const shapes = selection.projection?.static_return_shapes ?? [];
+    const retained = shapes.slice(0, maximum);
+    return { shapes: retained, omitted: shapes.length - retained.length };
+};
+const selectorBase = (side, candidates, retained) => ({
+    evidence_id: side.evidenceId,
+    graph_id: side.graph.graph_id,
+    requested_module_path: side.modulePath,
+    requested_export_name: side.exportName,
+    candidates: retained.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: candidates.length - retained.length,
+});
+const unresolvedSelection = (base, status, nodeId, limitations) => ({
+    selection: { ...base, status, selected_node_id: nodeId },
+    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) => compareCodePoints(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,
+        reason: "",
+    };
+};
+const unavailableReturnShape = (reason) => ({
+    projection: null,
+    observationComplete: false,
+    reason,
+});

package/dist/domain/javascriptExportShapeVariants.js

@@ -0,0 +1,272 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { canonicalExportShapeValue, digestExportShapeValue, } from "./javascriptExportShapeComparisonIdentity.js";
+/** Pair variants only through reciprocal unique exact literal discriminants. */
+export const pairJavaScriptExportShapeVariants = (left, right) => {
+    const leftKeys = discriminantOccurrences(left);
+    const rightKeys = discriminantOccurrences(right);
+    const edges = new Map();
+    const leftTargets = new Map();
+    const rightTargets = new Map();
+    for (const [key, leftOccurrence] of leftKeys) {
+        const rightOccurrence = rightKeys.get(key);
+        if (leftOccurrence.indexes.length !== 1 ||
+            rightOccurrence?.indexes.length !== 1)
+            continue;
+        const leftIndex = leftOccurrence.indexes[0];
+        const rightIndex = rightOccurrence.indexes[0];
+        if (leftIndex === undefined || rightIndex === undefined)
+            continue;
+        const edgeKey = `${String(leftIndex)}:${String(rightIndex)}`;
+        edges.set(edgeKey, [
+            ...(edges.get(edgeKey) ?? []),
+            leftOccurrence.discriminant,
+        ]);
+        addTarget(leftTargets, leftIndex, rightIndex);
+        addTarget(rightTargets, rightIndex, leftIndex);
+    }
+    const pairs = reciprocalPairs(leftTargets, rightTargets, edges);
+    const pairedLeft = new Set(pairs.map(({ leftIndex }) => leftIndex));
+    const pairedRight = new Set(pairs.map(({ rightIndex }) => rightIndex));
+    return {
+        pairs,
+        unpairedLeft: indexesNotIn(left, pairedLeft),
+        unpairedRight: indexesNotIn(right, pairedRight),
+    };
+};
+/** Build bounded-ready field and unpaired-variant changes before caller slicing. */
+export const buildJavaScriptExportShapeChanges = (input) => {
+    if (input.leftSelection.selection.status !== "selected" ||
+        input.rightSelection.selection.status !== "selected")
+        return [selectionUnknownChange(input)];
+    if (input.leftShapes.length === 0 || input.rightShapes.length === 0)
+        return [emptyShapeUnknownChange(input)];
+    const paired = input.pairing.pairs.flatMap((pair) => {
+        const left = input.leftShapes[pair.leftIndex];
+        const right = input.rightShapes[pair.rightIndex];
+        return left === undefined || right === undefined
+            ? []
+            : diffPair(left, right, pair.discriminant, input.evidenceLinks);
+    });
+    const unpairedLeft = input.pairing.unpairedLeft.flatMap((index) => {
+        const shape = input.leftShapes[index];
+        return shape === undefined
+            ? []
+            : [unpairedChange("left", shape, input.evidenceLinks)];
+    });
+    const unpairedRight = input.pairing.unpairedRight.flatMap((index) => {
+        const shape = input.rightShapes[index];
+        return shape === undefined
+            ? []
+            : [unpairedChange("right", shape, input.evidenceLinks)];
+    });
+    return [...paired, ...unpairedLeft, ...unpairedRight];
+};
+/** Sort changes by semantic content rather than traversal order. */
+export const compareJavaScriptExportShapeChanges = (left, right) => compareCodePoints(canonicalExportShapeValue(changeSortKey(left)), canonicalExportShapeValue(changeSortKey(right)));
+/** Report whether any retained shape lacks complete property coverage. */
+export const hasPartialJavaScriptExportPropertyCoverage = (shapes) => shapes.some((shape) => shape.property_coverage.some(({ status }) => status === "partial"));
+const discriminantOccurrences = (shapes) => {
+    const output = new Map();
+    shapes.forEach((shape, index) => {
+        for (const field of shape.fields) {
+            const value = literalValue(field);
+            if (!value.found)
+                continue;
+            const discriminant = { path: field.path, value: value.value };
+            const key = canonicalExportShapeValue(discriminant);
+            const current = output.get(key);
+            output.set(key, {
+                discriminant,
+                indexes: [...(current?.indexes ?? []), index],
+            });
+        }
+    });
+    return output;
+};
+const reciprocalPairs = (leftTargets, rightTargets, edges) => {
+    const pairs = [];
+    for (const [leftIndex, targets] of leftTargets) {
+        if (targets.size !== 1)
+            continue;
+        const rightIndex = [...targets][0];
+        if (rightIndex === undefined ||
+            rightTargets.get(rightIndex)?.size !== 1 ||
+            !rightTargets.get(rightIndex)?.has(leftIndex))
+            continue;
+        const discriminants = edges
+            .get(`${String(leftIndex)}:${String(rightIndex)}`)
+            ?.toSorted(compareDiscriminants);
+        const discriminant = discriminants?.[0];
+        if (discriminant !== undefined)
+            pairs.push({ leftIndex, rightIndex, discriminant });
+    }
+    return pairs.sort((first, second) => compareDiscriminants(first.discriminant, second.discriminant));
+};
+const addTarget = (map, source, target) => {
+    const values = map.get(source) ?? new Set();
+    values.add(target);
+    map.set(source, values);
+};
+const indexesNotIn = (shapes, paired) => shapes.map((_, index) => index).filter((index) => !paired.has(index));
+const compareDiscriminants = (left, right) => compareCodePoints(canonicalExportShapeValue(left), canonicalExportShapeValue(right));
+const selectionUnknownChange = (input) => changeWithId({
+    status: "unknown",
+    path: "",
+    discriminant: null,
+    left: selectionAvailability(input.leftSelection.selection, "left"),
+    right: selectionAvailability(input.rightSelection.selection, "right"),
+    left_source_range: null,
+    right_source_range: null,
+    evidence_links: input.evidenceLinks,
+    limitations: [
+        "Both selectors must resolve one exact export with trusted static return shapes before comparison.",
+    ],
+});
+const emptyShapeUnknownChange = (input) => changeWithId({
+    status: "unknown",
+    path: "",
+    discriminant: null,
+    left: emptyShapeAvailability(input.leftShapes, "left"),
+    right: emptyShapeAvailability(input.rightShapes, "right"),
+    left_source_range: null,
+    right_source_range: null,
+    evidence_links: input.evidenceLinks,
+    limitations: [
+        "At least one selected export has no retained direct return shape.",
+    ],
+});
+const diffPair = (left, right, discriminant, evidenceLinks) => {
+    const leftFields = new Map(left.fields.map((field) => [field.path, field]));
+    const rightFields = new Map(right.fields.map((field) => [field.path, field]));
+    const paths = uniqueSorted([...leftFields.keys(), ...rightFields.keys()]);
+    return paths.flatMap((path) => {
+        const leftField = leftFields.get(path);
+        const rightField = rightFields.get(path);
+        const status = fieldChangeStatus({
+            leftShape: left,
+            rightShape: right,
+            path,
+            leftField,
+            rightField,
+        });
+        if (status === null)
+            return [];
+        return [
+            changeWithId({
+                status,
+                path,
+                discriminant,
+                left: fieldAvailability(leftField),
+                right: fieldAvailability(rightField),
+                left_source_range: left.source_range,
+                right_source_range: right.source_range,
+                evidence_links: evidenceLinks,
+                limitations: status === "unknown"
+                    ? [
+                        "The static value or relevant parent-property coverage is incomplete.",
+                    ]
+                    : [],
+            }),
+        ];
+    });
+};
+const fieldChangeStatus = ({ leftShape, rightShape, path, leftField, rightField, }) => {
+    if (leftField !== undefined && rightField !== undefined) {
+        if (canonicalExportShapeValue(leftField) ===
+            canonicalExportShapeValue(rightField))
+            return null;
+        return leftField.state === "unknown" || rightField.state === "unknown"
+            ? "unknown"
+            : "changed";
+    }
+    const present = leftField ?? rightField;
+    if (present === undefined)
+        return null;
+    const parent = parentPointer(path);
+    const parentsComplete = propertyCoverageComplete(leftShape, parent) &&
+        propertyCoverageComplete(rightShape, parent);
+    if (present.state === "unknown" || !parentsComplete)
+        return "unknown";
+    return leftField === undefined ? "added" : "removed";
+};
+const propertyCoverageComplete = (shape, path) => path !== null &&
+    shape.property_coverage.some((coverage) => coverage.path === path && coverage.status === "complete");
+const parentPointer = (path) => {
+    if (path === "")
+        return null;
+    const separator = path.lastIndexOf("/");
+    return separator < 0 ? null : path.slice(0, separator);
+};
+const fieldAvailability = (field) => {
+    if (field === undefined)
+        return { availability: "absent" };
+    if (field.state === "unknown")
+        return {
+            availability: "unknown",
+            reason: field.reason ?? "Static field value is unknown.",
+        };
+    if (field.state === "union")
+        return { availability: "union", values: primitiveArray(field.value) };
+    const literal = literalValue(field);
+    return literal.found
+        ? { availability: "literal", value: literal.value }
+        : {
+            availability: "unknown",
+            reason: "Static literal field failed its projection boundary.",
+        };
+};
+const selectionAvailability = (selection, side) => ({
+    availability: "unknown",
+    reason: `${capitalize(side)} export selection is ${selection.status}.`,
+});
+const emptyShapeAvailability = (shapes, side) => ({
+    availability: "unknown",
+    reason: shapes.length === 0
+        ? `${capitalize(side)} export has no retained direct return shape.`
+        : `${capitalize(side)} export return shape cannot be paired without an opposite variant.`,
+});
+const unpairedChange = (side, shape, evidenceLinks) => changeWithId({
+    status: "unknown",
+    path: "",
+    discriminant: null,
+    left: {
+        availability: "unknown",
+        reason: side === "left"
+            ? "Left return variant has no unique exact cross-version pairing."
+            : "No left return variant was uniquely paired with this right variant.",
+    },
+    right: {
+        availability: "unknown",
+        reason: side === "right"
+            ? "Right return variant has no unique exact cross-version pairing."
+            : "No right return variant was uniquely paired with this left variant.",
+    },
+    left_source_range: side === "left" ? shape.source_range : null,
+    right_source_range: side === "right" ? shape.source_range : null,
+    evidence_links: evidenceLinks,
+    limitations: [
+        "The return variant was not paired because no reciprocal unique literal discriminant exists.",
+    ],
+});
+const changeWithId = (semantic) => ({
+    ...semantic,
+    change_id: `jesc_change_${digestExportShapeValue(semantic)}`,
+});
+const changeSortKey = (change) => ({
+    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,
+});
+const literalValue = (field) => field.state === "literal" && isPrimitive(field.value)
+    ? { found: true, value: field.value }
+    : { found: false };
+const primitiveArray = (value) => Array.isArray(value) ? value.filter(isPrimitive) : [];
+const isPrimitive = (value) => value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean";
+const capitalize = (value) => `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);