rea-agents 2.2.0 → 2.4.0

package/dist/domain/javascriptSemanticReturns.js

@@ -0,0 +1,187 @@
+import * as t from "@babel/types";
+import { reachSemanticLimit, semanticCallableIdForNode, } from "./javascriptSemanticProjection.js";
+import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
+import { evaluateSemanticExpression } from "./javascriptSemanticValues.js";
+import { compareCodePoints, range } from "./javascriptStaticAnalysisHelpers.js";
+import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+/** Evaluate bounded direct returns while excluding every nested callable. */
+export const collectSemanticReturns = (program, state, parserPartial) => {
+    const nodes = callableNodes(program);
+    let retained = 0;
+    return state.callables.map((callable) => {
+        const node = nodes.get(callable.callableId);
+        if (node === undefined)
+            return {
+                ...callable,
+                returnCoverage: {
+                    status: "partial",
+                    retainedCount: 0,
+                    omittedCount: null,
+                    limitsReached: [],
+                },
+            };
+        const expressions = directReturnExpressions(node);
+        const sites = [];
+        let omitted = 0;
+        for (const expression of expressions) {
+            if (retained >= state.limits.maxReturnSites) {
+                omitted += 1;
+                reachSemanticLimit(state, "maxReturnSites");
+                continue;
+            }
+            retained += 1;
+            sites.push({
+                returnSiteId: semanticReturnSiteId(callable.callableId, expression.location),
+                location: expression.location,
+                identityReferenceLocation: expression.node !== null && t.isIdentifier(expression.node)
+                    ? range(expression.node)
+                    : null,
+                value: expression.node === null
+                    ? { status: "unknown", reason: "Return has no value." }
+                    : evaluateSemanticExpression(expression.node, state),
+            });
+        }
+        return {
+            ...callable,
+            returnSites: sites,
+            returnCoverage: {
+                status: omitted > 0 ? "truncated" : parserPartial ? "partial" : "complete",
+                retainedCount: sites.length,
+                omittedCount: omitted,
+                limitsReached: omitted > 0 ? ["maxReturnSites"] : [],
+            },
+        };
+    });
+};
+const semanticReturnSiteId = (callableId, location) => `${callableId}:return:${String(location.start.line)}:${String(location.start.column)}:${String(location.end.line)}:${String(location.end.column)}`;
+/** Link exports to callables only when lexical resolution is unique and exact. */
+export const resolveSemanticModuleCallables = (state, callables) => {
+    const callableIds = new Set(callables.map(({ callableId }) => callableId));
+    const root = state.scopes.find(({ kind }) => kind === "program");
+    return state.moduleLinks.map((link) => {
+        if (link.callableId !== null && callableIds.has(link.callableId))
+            return link;
+        if (link.localName === null || root === undefined)
+            return { ...link, callableId: null };
+        const named = callables.filter(({ name, containerScopeId }) => name === link.localName && containerScopeId === root.scopeId);
+        if (named.length === 1)
+            return { ...link, callableId: named[0]?.callableId ?? null };
+        const binding = root.bindings.get(link.localName);
+        const resolved = binding === undefined
+            ? []
+            : callableIdsForBinding(binding, state, callableIds, new Set());
+        return {
+            ...link,
+            callableId: resolved.length === 1 ? (resolved[0] ?? null) : null,
+        };
+    });
+};
+const callableNodes = (program) => {
+    const output = new Map();
+    traverseJavaScriptAst(program, {
+        enter: (node) => {
+            const id = semanticCallableIdForNode(node);
+            if (id !== null)
+                output.set(id, node);
+        },
+    });
+    return output;
+};
+const directReturnExpressions = (callable) => {
+    if (t.isArrowFunctionExpression(callable) &&
+        !t.isBlockStatement(callable.body))
+        return [{ node: callable.body, location: range(callable.body) }];
+    if (!t.isFunction(callable))
+        return [];
+    const output = [];
+    const visit = (node) => {
+        if (t.isFunction(node) || t.isClass(node))
+            return;
+        if (t.isReturnStatement(node)) {
+            output.push({ node: node.argument ?? null, location: range(node) });
+            return;
+        }
+        for (const child of childNodes(node))
+            visit(child);
+    };
+    for (const child of childNodes(callable.body))
+        visit(child);
+    return output;
+};
+const childNodes = (node) => (t.VISITOR_KEYS[node.type] ?? []).flatMap((key) => {
+    const value = Reflect.get(node, key);
+    if (t.isNode(value))
+        return [value];
+    return Array.isArray(value)
+        ? value.filter((item) => t.isNode(item))
+        : [];
+});
+const callableIdsForBinding = (binding, state, admitted, seen) => {
+    if (seen.has(binding.bindingId) || binding.initializers.length !== 1)
+        return [];
+    const initializer = binding.initializers[0];
+    if (initializer === undefined || initializer.projection.length > 0)
+        return [];
+    return callableIdsForNode(initializer.node, state, admitted, new Set([...seen, binding.bindingId]));
+};
+const callableIdsForNode = (node, state, admitted, seen) => {
+    const direct = semanticCallableIdForNode(node);
+    if (direct !== null && admitted.has(direct))
+        return [direct];
+    if (t.isIdentifier(node)) {
+        const binding = resolveSemanticBindingState(state, node, node.name);
+        return binding === undefined
+            ? []
+            : callableIdsForBinding(binding, state, admitted, seen);
+    }
+    if (t.isTSAsExpression(node) ||
+        t.isTSTypeAssertion(node) ||
+        t.isTSNonNullExpression(node))
+        return callableIdsForNode(node.expression, state, admitted, seen);
+    return [];
+};
+/** Flatten a semantic value to bounded JSON-pointer leaves for graph projection. */
+export const flattenSemanticReturnValue = (value) => {
+    const fields = [];
+    const propertyCoverage = [];
+    flattenValue(value, "", fields, propertyCoverage);
+    fields.sort((left, right) => compareCodePoints(left.path, right.path));
+    propertyCoverage.sort((left, right) => compareCodePoints(left.path, right.path));
+    return { fields, propertyCoverage };
+};
+const flattenValue = (value, path, fields, coverage) => {
+    if (value.status === "literal") {
+        fields.push({ path, state: "literal", value: value.value, reason: null });
+        return;
+    }
+    if (value.status === "union") {
+        fields.push({
+            path,
+            state: "union",
+            value: [...value.values],
+            reason: null,
+        });
+        return;
+    }
+    if (value.status === "object") {
+        coverage.push({
+            path,
+            status: value.unknownProperties ? "partial" : "complete",
+            omitted: value.omittedProperties,
+        });
+        for (const property of value.properties)
+            flattenValue(property.value, `${path}/${escapePointer(property.name)}`, fields, coverage);
+        return;
+    }
+    if (value.status === "array") {
+        coverage.push({
+            path,
+            status: value.unknownItems ? "partial" : "complete",
+            omitted: value.omittedItems,
+        });
+        value.items.forEach((item, index) => flattenValue(item, `${path}/${String(index)}`, fields, coverage));
+        return;
+    }
+    fields.push({ path, state: "unknown", value: null, reason: value.reason });
+};
+const escapePointer = (value) => value.replaceAll("~", "~0").replaceAll("/", "~1");

package/dist/domain/javascriptSemanticState.js

@@ -1,3 +1,4 @@
+import * as t from "@babel/types";
 /** Return the active scope from a non-empty construction stack. */
 export const currentSemanticScope = (stack) => {
     const scope = stack.at(-1);
@@ -38,3 +39,34 @@ export const semanticResolutionBlocked = (state, node, name) => {
     }
     return false;
 };
+/** Resolve one name starting from an explicitly selected lexical scope. */
+export const resolveSemanticBindingFromScope = (scope, name, state) => {
+    let candidate = scope;
+    while (candidate !== undefined) {
+        const binding = candidate.bindings.get(name);
+        if (binding !== undefined)
+            return binding;
+        if (!candidate.bindingsComplete)
+            return undefined;
+        candidate =
+            candidate.parentScopeId === null
+                ? undefined
+                : state.scopesById.get(candidate.parentScopeId);
+    }
+    return undefined;
+};
+/** Select the function/program owner for a var declaration. */
+export const semanticVariableScope = (scope, parent, state) => {
+    if (!(parent !== null && t.isVariableDeclaration(parent, { kind: "var" })))
+        return scope;
+    let candidate = scope;
+    while (candidate.kind === "block" || candidate.kind === "catch") {
+        const outer = candidate.parentScopeId === null
+            ? undefined
+            : state.scopesById.get(candidate.parentScopeId);
+        if (outer === undefined)
+            break;
+        candidate = outer;
+    }
+    return candidate;
+};

package/dist/domain/javascriptSemanticTraceSchemas.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { evidenceSchema } from "./evidence.js";
+import { javaScriptSemanticQueryInputSchema, javaScriptSemanticQueryResultSchema, } from "./javascriptSemanticQuerySchemas.js";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+/** Authenticated application Evidence plus one bounded semantic query. */
+export const traceJavaScriptSemanticsInputSchema = z.strictObject({
+    application: evidenceSchema,
+    query: javaScriptSemanticQueryInputSchema,
+});
+/** Evidence-linked semantic query result shared by CLI and MCP. */
+export const javaScriptSemanticTraceResultSchema = javaScriptSemanticQueryResultSchema.extend({
+    source_evidence_id: evidenceIdSchema,
+    evidence_links: z.array(evidenceIdSchema).length(1),
+});

package/dist/domain/javascriptSemanticValues.js

@@ -1,8 +1,12 @@
 import * as t from "@babel/types";
 import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
 import { compareCodePoints, propertyName, stringValue, } from "./javascriptStaticAnalysisHelpers.js";
+import { reachSemanticValueLimit, semanticLimitProvenance, semanticOriginsProvenance, semanticProvenance, uniqueSemanticOrigins, } from "./javascriptSemanticProvenance.js";
+import { semanticPrimitiveCandidates as primitiveCandidates, semanticPrimitiveSet as primitiveSet, semanticPrimitiveValue as primitiveValue, } from "./javascriptSemanticPrimitives.js";
 /** Evaluate one binding in the bounded constant-value lattice. */
 export const evaluateSemanticBinding = (binding, state) => evaluateBinding(binding, { state, bindings: new Set(), depth: 0 });
+/** Evaluate one arbitrary inert expression in the established lexical state. */
+export const evaluateSemanticExpression = (node, state) => evaluateExpression(node, { state, bindings: new Set(), depth: 0 });
 /** Follow module provenance through destructuring, members, and aliases. */
 export const evaluateSemanticProvenance = (binding, state) => provenanceForBinding(binding, { state, bindings: new Set(), depth: 0 });
 const evaluateBinding = (binding, context) => {
@@ -91,19 +95,31 @@ const evaluateTemplate = (node, context) => {
 const evaluateObject = (node, context) => {
     const properties = [];
     let unknownProperties = false;
+    let omittedProperties = 0;
     for (const property of node.properties) {
-        if (t.isSpreadElement(property) || property.computed) {
+        if (t.isSpreadElement(property)) {
             unknownProperties = true;
+            omittedProperties = null;
+            continue;
+        }
+        if (property.computed) {
+            unknownProperties = true;
+            if (omittedProperties !== null)
+                omittedProperties += 1;
             continue;
         }
         const name = propertyName(property.key);
         if (name === "" || !t.isObjectProperty(property)) {
             unknownProperties = true;
+            if (omittedProperties !== null)
+                omittedProperties += 1;
             continue;
         }
         if (properties.length >= context.state.limits.maxObjectProperties) {
-            markLimit(context.state, "maxObjectProperties");
+            reachSemanticValueLimit(context.state, "maxObjectProperties");
             unknownProperties = true;
+            if (omittedProperties !== null)
+                omittedProperties += 1;
             continue;
         }
         properties.push({
@@ -112,24 +128,39 @@ const evaluateObject = (node, context) => {
         });
     }
     properties.sort((left, right) => compareCodePoints(left.name, right.name));
-    return { status: "object", properties, unknownProperties };
+    return {
+        status: "object",
+        properties,
+        unknownProperties,
+        omittedProperties,
+    };
 };
 const evaluateArray = (node, context) => {
     const items = [];
     let unknownItems = false;
+    let omittedItems = 0;
     for (const element of node.elements) {
-        if (element === null || t.isSpreadElement(element)) {
+        if (t.isSpreadElement(element)) {
+            unknownItems = true;
+            omittedItems = null;
+            continue;
+        }
+        if (element === null) {
             unknownItems = true;
+            if (omittedItems !== null)
+                omittedItems += 1;
             continue;
         }
         if (items.length >= context.state.limits.maxObjectProperties) {
-            markLimit(context.state, "maxObjectProperties");
+            reachSemanticValueLimit(context.state, "maxObjectProperties");
             unknownItems = true;
+            if (omittedItems !== null)
+                omittedItems += 1;
             continue;
         }
         items.push(evaluateExpression(element, nestedContext(context)));
     }
-    return { status: "array", items, unknownItems };
+    return { status: "array", items, unknownItems, omittedItems };
 };
 const evaluateMember = (node, context) => {
     if (!t.isNode(node.object))
@@ -199,24 +230,24 @@ const projectValue = (value, projection) => {
 };
 const provenanceForBinding = (binding, context) => {
     if (context.bindings.has(binding.bindingId))
-        return provenance("cycle", [], `Alias cycle at ${binding.name}.`);
+        return semanticProvenance("cycle", [], `Alias cycle at ${binding.name}.`);
     if (context.depth >= context.state.limits.maxValueDepth)
-        return limitProvenance(context.state, "maxValueDepth");
+        return semanticLimitProvenance(context.state, "maxValueDepth");
     if (binding.directOrigins.length > 0)
-        return originsProvenance(binding.directOrigins, context.state);
+        return semanticOriginsProvenance(binding.directOrigins, context.state);
     if (binding.initializers.length === 0)
-        return provenance("local", [], null);
+        return semanticProvenance("local", [], null);
     if (binding.initializers.length > 1)
-        return provenance("ambiguous", [], `Binding ${binding.name} has multiple possible assignments.`);
+        return semanticProvenance("ambiguous", [], `Binding ${binding.name} has multiple possible assignments.`);
     const initializer = binding.initializers[0];
     if (initializer === undefined)
-        return provenance("unknown", [], "Missing binding initializer.");
+        return semanticProvenance("unknown", [], "Missing binding initializer.");
     if (initializer.projection.includes(null))
-        return provenance("unknown", [], "Dynamic provenance projection.");
+        return semanticProvenance("unknown", [], "Dynamic provenance projection.");
     const resolved = provenanceForExpression(initializer.node, nestedContext(context, binding.bindingId));
     if (resolved.status !== "module" || initializer.projection.length === 0)
         return resolved;
-    return originsProvenance(resolved.origins.map((origin) => ({
+    return semanticOriginsProvenance(resolved.origins.map((origin) => ({
         ...origin,
         importedPath: [
             ...origin.importedPath,
@@ -227,23 +258,23 @@ const provenanceForBinding = (binding, context) => {
 const provenanceForExpression = (node, context) => {
     const required = requireOrigin(node);
     if (required !== undefined)
-        return originsProvenance([required], context.state);
+        return semanticOriginsProvenance([required], context.state);
     if (t.isIdentifier(node)) {
         const binding = resolveSemanticBindingState(context.state, node, node.name);
         return binding === undefined
-            ? provenance("unknown", [], `Unbound identifier ${node.name}.`)
+            ? semanticProvenance("unknown", [], `Unbound identifier ${node.name}.`)
             : provenanceForBinding(binding, nestedContext(context));
     }
     if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
         if (!t.isNode(node.object))
-            return provenance("unknown", [], "Unsupported member base.");
+            return semanticProvenance("unknown", [], "Unsupported member base.");
         const member = memberKey(node);
         if (typeof member !== "string")
-            return provenance("unknown", [], "Dynamic provenance member.");
+            return semanticProvenance("unknown", [], "Dynamic provenance member.");
         const base = provenanceForExpression(node.object, nestedContext(context));
         return base.status !== "module"
             ? base
-            : originsProvenance(base.origins.map((origin) => ({
+            : semanticOriginsProvenance(base.origins.map((origin) => ({
                 ...origin,
                 importedPath: [...origin.importedPath, member],
             })), context.state);
@@ -257,10 +288,10 @@ const provenanceForExpression = (node, context) => {
         ];
         const origins = candidates.flatMap((candidate) => candidate.origins);
         return origins.length > 0
-            ? provenance("ambiguous", uniqueOrigins(origins), "Multiple module origins.")
-            : provenance("unknown", [], "Conditional provenance is unresolved.");
+            ? semanticProvenance("ambiguous", uniqueSemanticOrigins(origins), "Multiple module origins.")
+            : semanticProvenance("unknown", [], "Conditional provenance is unresolved.");
     }
-    return provenance("local", [], null);
+    return semanticProvenance("local", [], null);
 };
 const requireOrigin = (node) => {
     if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
@@ -285,31 +316,6 @@ const mergeValues = (values, state) => {
         ? primitiveSet(primitives, state)
         : { status: "ambiguous", reason: "Branches have incompatible values." };
 };
-const primitiveSet = (values, state) => {
-    const unique = [
-        ...new Map(values.map((value) => [primitiveKey(value), value])).values(),
-    ].sort((left, right) => compareCodePoints(primitiveKey(left), primitiveKey(right)));
-    if (unique.length > state.limits.maxUnionValues)
-        return limitValue(state, "maxUnionValues");
-    const only = unique[0];
-    return unique.length === 1 && only !== undefined
-        ? { status: "literal", value: only }
-        : { status: "union", values: unique };
-};
-const primitiveCandidates = (value) => value.status === "literal"
-    ? [value.value]
-    : value.status === "union"
-        ? value.values
-        : null;
-const primitiveValue = (node) => {
-    if (t.isStringLiteral(node) || t.isNumericLiteral(node))
-        return { found: true, value: node.value };
-    if (t.isBooleanLiteral(node))
-        return { found: true, value: node.value };
-    if (t.isNullLiteral(node))
-        return { found: true, value: null };
-    return { found: false };
-};
 const memberKey = (node) => {
     if (!node.computed)
         return propertyName(node.property) || undefined;
@@ -317,30 +323,10 @@ const memberKey = (node) => {
         return node.property.value;
     return undefined;
 };
-const originsProvenance = (origins, state) => {
-    const unique = uniqueOrigins(origins);
-    if (unique.length > state.limits.maxUnionValues)
-        return limitProvenance(state, "maxUnionValues");
-    return unique.length === 1
-        ? provenance("module", unique, null)
-        : provenance("ambiguous", unique, "Multiple module origins.");
-};
-const uniqueOrigins = (origins) => [
-    ...new Map(origins.map((origin) => [originKey(origin), origin])).values(),
-].sort((left, right) => compareCodePoints(originKey(left), originKey(right)));
-const provenance = (status, origins, reason) => ({ status, origins, reason });
 const limitValue = (state, limit) => {
-    markLimit(state, limit);
+    reachSemanticValueLimit(state, limit);
     return { status: "limit-reached", reason: `${limit} reached.` };
 };
-const limitProvenance = (state, limit) => {
-    markLimit(state, limit);
-    return provenance("limit-reached", [], `${limit} reached.`);
-};
-const markLimit = (state, limit) => {
-    state.limitsReached.add(limit);
-    state.omittedCount += 1;
-};
 const nestedContext = (context, bindingId) => ({
     state: context.state,
     depth: context.depth + 1,
@@ -348,5 +334,3 @@ const nestedContext = (context, bindingId) => ({
         ? context.bindings
         : new Set([...context.bindings, bindingId]),
 });
-const primitiveKey = (value) => `${value === null ? "null" : typeof value}:${JSON.stringify(value)}`;
-const originKey = (origin) => `${origin.specifier}\0${origin.importedPath.join("\0")}`;

package/dist/domain/processCapture.js

@@ -1,7 +1,20 @@
 import { z } from "zod";
 import { jsonValueSchema } from "./jsonValue.js";
 import { LEGACY_PROCESS_CAPTURE_MESSAGE, normalizationSchema, } from "./processScenario.js";
+import { PROCESS_REACTIVE_LIMITS } from "./processReactiveScenario.js";
 export * from "./processScenario.js";
+/** Capture collection whose members participate in global observation order. */
+export const PROCESS_CAPTURE_EVENT_COLLECTIONS = [
+    "frames",
+    "rendered_frames",
+    "interaction_events",
+    "lifecycle",
+    "process_samples",
+    "filesystem_checkpoints",
+    "shim_events",
+    "protocol_events",
+    "replay_transitions",
+];
 const fileStateSchema = z.object({
     path: z.string(),
     type: z.enum(["file", "directory", "symlink", "other"]),
@@ -115,8 +128,94 @@ export const processCaptureSchema = z.object({
             "unmatched",
             "script_exhausted",
             "disconnected",
+            "invalid_state",
+            "guard_failed",
+            "transition_exhausted",
+            "invalid_capture",
+            "unexpected_reconnect",
+            "limit_exhausted",
         ]),
     })),
+    replay_transitions: z
+        .array(z.object({
+        sequence: z.number().int().nonnegative(),
+        at_ms: z.number().int().nonnegative(),
+        transition_id: z.string().min(1).max(64),
+        state_before: z.string().min(1).max(64),
+        state_after: z.string().min(1).max(64),
+        sensitive_aliases: z.array(z.string().min(1).max(64)).max(32),
+    }))
+        .default([]),
+    reactive_run: z
+        .object({
+        status: z.enum(["running", "finished"]),
+        outcome: z
+            .enum([
+            "passed",
+            "predicate_timeout",
+            "scenario_deadline",
+            "ambiguous_match",
+            "action_rejected",
+            "target_lost",
+            "capture_incomplete",
+            "cancelled",
+            "cleanup_failed",
+        ])
+            .nullable(),
+        active_state: z.string().min(1).max(64),
+        controls: z
+            .array(z.object({
+            sequence: z.number().int().nonnegative(),
+            kind: z.enum([
+                "state_deadline",
+                "scenario_deadline",
+                "target_lost",
+                "cancelled",
+                "cleanup_failed",
+            ]),
+            after_capture_order: z.number().int().min(-1),
+        }))
+            .default([]),
+        transitions: z
+            .array(z.object({
+            sequence: z.number().int().nonnegative(),
+            transition_id: z.string().min(1).max(64),
+            state_before: z.string().min(1).max(64),
+            state_after: z.string().min(1).max(64).nullable(),
+            outcome: z
+                .enum([
+                "passed",
+                "predicate_timeout",
+                "scenario_deadline",
+                "ambiguous_match",
+                "action_rejected",
+                "target_lost",
+                "capture_incomplete",
+                "cancelled",
+                "cleanup_failed",
+            ])
+                .nullable(),
+            trigger_event_ids: z
+                .array(z.string().min(1))
+                .max(PROCESS_REACTIVE_LIMITS.predicates),
+            action_event_ids: z
+                .array(z.string().min(1))
+                .max(PROCESS_REACTIVE_LIMITS.actionsPerTransition),
+            action_types: z
+                .array(z.enum(["send_input", "resize", "send_signal", "checkpoint"]))
+                .max(PROCESS_REACTIVE_LIMITS.actionsPerTransition),
+        }))
+            .max(PROCESS_REACTIVE_LIMITS.transitions),
+    })
+        .nullable()
+        .default(null),
+    event_journal: z
+        .array(z.object({
+        capture_order: z.number().int().nonnegative(),
+        collection: z.enum(PROCESS_CAPTURE_EVENT_COLLECTIONS),
+        index: z.number().int().nonnegative(),
+    }))
+        .default([]),
     files_before: z.array(fileStateSchema),
     files_after: z.array(fileStateSchema),
     filesystem_effects: z.array(fileEffectSchema),
@@ -157,3 +256,4 @@ export const parseProcessCapture = (input) => {
     return capture;
 };
 export { compareProcessCaptures, comparisonStatusSchema, deriveProcessComparisonStatus, PROCESS_COMPARISON_DIMENSIONS, processCaptureComparisonSchema, } from "./processComparison.js";
+export { compareProcessTraces, processTraceComparisonResultSchema, processTraceSourceSchema, processTraceSpecificationSchema, } from "./processTraceComparison.js";