rea-agents 2.2.0 → 2.3.0

package/dist/domain/javascriptExportShapeComparison.js

@@ -0,0 +1,145 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { digestExportShapeValue } from "./javascriptExportShapeComparisonIdentity.js";
+import { javaScriptExportShapeComparisonResultSchema, } from "./javascriptExportShapeComparisonSchemas.js";
+import { retainJavaScriptExportShapes, selectJavaScriptExport, } from "./javascriptExportShapeSelection.js";
+import { buildJavaScriptExportShapeChanges, compareJavaScriptExportShapeChanges, hasPartialJavaScriptExportPropertyCoverage, pairJavaScriptExportShapeVariants, } from "./javascriptExportShapeVariants.js";
+/** Compare exact selected export return shapes without executing JavaScript. */
+export const compareJavaScriptExportShapes = (input) => {
+    const left = selectJavaScriptExport(input.left, input.limits.max_candidate_exports);
+    const right = selectJavaScriptExport(input.right, input.limits.max_candidate_exports);
+    const leftRetained = retainJavaScriptExportShapes(left, input.limits.max_return_variants);
+    const rightRetained = retainJavaScriptExportShapes(right, input.limits.max_return_variants);
+    const pairing = pairJavaScriptExportShapeVariants(leftRetained.shapes, rightRetained.shapes);
+    const evidenceLinks = evidencePair(input.left.evidenceId, input.right.evidenceId);
+    const allChanges = buildJavaScriptExportShapeChanges({
+        leftSelection: left,
+        rightSelection: right,
+        pairing,
+        leftShapes: leftRetained.shapes,
+        rightShapes: rightRetained.shapes,
+        evidenceLinks,
+    }).sort(compareJavaScriptExportShapeChanges);
+    const changes = allChanges.slice(0, input.limits.max_changes);
+    const omittedChanges = allChanges.length - changes.length;
+    const coverage = comparisonCoverage({
+        input,
+        left,
+        right,
+        leftRetained,
+        rightRetained,
+        pairing,
+        allChanges,
+        omittedChanges,
+    });
+    const limitations = comparisonLimitations(left, right, coverage.status);
+    const semantic = {
+        schema_version: 1,
+        left: left.selection,
+        right: right.selection,
+        summary: summarize(allChanges),
+        changes,
+        coverage,
+        evidence_links: evidenceLinks,
+        limitations,
+        runtime_validation: {
+            recommended_tool: "run_controlled_replay",
+            automatically_started: false,
+            required_for: "runtime-semantics",
+        },
+    };
+    return javaScriptExportShapeComparisonResultSchema.parse({
+        ...semantic,
+        comparison_id: `jesc_${digestExportShapeValue(semantic)}`,
+    });
+};
+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.",
+    "Controlled replay is recommended separately for runtime semantics and was not started.",
+    ...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,
+];
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptExportShapeComparisonIdentity.js

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+/** Canonically encode one export-shape comparison value. */
+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/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,
+});