rea-agents 2.2.0 → 2.4.0

package/dist/application/JavaScriptSemanticGraphFlowProjection.js

@@ -0,0 +1,72 @@
+import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
+import { addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
+import { inferredSemanticEvidenceAt, unknownSemanticEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
+import { semanticNodesWithinRange } from "./JavaScriptSemanticGraphProjection.js";
+/** Link direct return expressions to their retained semantic references. */
+export const projectSemanticReturnValues = (context) => {
+    for (const callable of context.ir.callables)
+        for (const site of callable.returnSites) {
+            const returnNode = context.returnSiteNodes.get(site.returnSiteId);
+            const references = semanticNodesWithinRange(context.referenceNodes, site.location);
+            for (const reference of references)
+                addSemanticGraphRelation(context.state, {
+                    source: reference,
+                    target: returnNode,
+                    relation: "aliases",
+                    resolution: site.identityReferenceLocation !== null &&
+                        rangesEqual(reference.identity.source_range, site.identityReferenceLocation)
+                        ? "resolved"
+                        : "candidate",
+                });
+        }
+};
+const rangesEqual = (left, right) => left !== null &&
+    right !== null &&
+    left.start.line === right.start.line &&
+    left.start.column === right.start.column &&
+    left.end.line === right.end.line &&
+    left.end.column === right.end.column;
+/** Link each captured binding to the callable at the exact reference site. */
+export const projectSemanticClosureCaptures = (context) => {
+    for (const capture of context.ir.closureCaptures)
+        addSemanticGraphRelation(context.state, {
+            source: context.bindingNodes.get(capture.bindingId),
+            target: context.callableNodes.get(capture.callableId),
+            relation: "captures",
+            resolution: "resolved",
+            evidence: inferredSemanticEvidenceAt(context.file, capture.referenceLocation),
+        });
+};
+/** Retain bounded unresolved dynamic-call and dynamic-property frontiers. */
+export const projectSemanticFrontiers = (context) => {
+    for (const frontier of context.ir.frontiers) {
+        const unknown = createJavaScriptSemanticGraphUnknown({
+            node_id: frontier.callableId === null
+                ? context.moduleNode.node_id
+                : (context.callableNodes.get(frontier.callableId)?.node_id ??
+                    context.moduleNode.node_id),
+            family: frontier.kind === "dynamic-call" ? "call-flow" : "object-flow",
+            relation_kinds: frontier.kind === "dynamic-call"
+                ? ["calls"]
+                : ["reads-property", "writes-property"],
+            reason: frontier.kind,
+            detail: frontier.reason,
+            candidate_node_ids: [],
+            evidence: unknownSemanticEvidence(context.file, frontier.location),
+        });
+        addSemanticGraphUnknown(context.state, unknown);
+    }
+};
+/** Publish exact semantic analyzer limits reached by any admitted source file. */
+export const semanticRecoveryLimits = (analysis) => {
+    const limits = new Map();
+    for (const { semantic } of analysis.files) {
+        if (semantic === null)
+            continue;
+        for (const name of semantic.ir.coverage.limitsReached)
+            limits.set(`semantic.${name}`, semantic.limits[name]);
+    }
+    return [...limits]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, value]) => ({ name, value, unit: "items" }));
+};

package/dist/application/JavaScriptSemanticGraphProjection.js

@@ -0,0 +1,33 @@
+import { compareCodePoints } from "../domain/javascriptApplicationGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../domain/javascriptSemanticGraphSchemas.js";
+/** Find the innermost callable that contains one exact source range. */
+export const owningSemanticCallableNode = (location, ir, nodes) => {
+    if (location === null)
+        return undefined;
+    return ir.callables
+        .filter((callable) => contains(callable.location, location))
+        .sort((left, right) => compareCodePoints(positionKey(right.location), positionKey(left.location)))
+        .map(({ callableId }) => nodes.get(callableId))
+        .find((node) => node !== undefined);
+};
+/** Find retained semantic nodes whose exact ranges are within one expression. */
+export const semanticNodesWithinRange = (nodes, range) => nodes.filter((node) => node.identity.source_range !== null &&
+    contains(range, node.identity.source_range));
+/** Report extractor support without treating missing families as absence. */
+export const semanticFamilyStatus = (family, analysis, truncated) => {
+    if (!["call-flow", "closure", "data-flow", "object-flow"].includes(family))
+        return "unsupported";
+    if (truncated)
+        return "unknown";
+    return analysis.truncated_scopes === 0 ? "partial" : "unknown";
+};
+/** Compare two exact semantic source ranges. */
+export const semanticRangesEqual = (left, right) => left !== null &&
+    left.start.line === right.start.line &&
+    left.start.column === right.start.column &&
+    left.end.line === right.end.line &&
+    left.end.column === right.end.column;
+const contains = (outer, inner) => pointCompare(outer.start, inner.start) <= 0 &&
+    pointCompare(outer.end, inner.end) >= 0;
+const pointCompare = (left, right) => left.line - right.line || left.column - right.column;
+const positionKey = (range) => `${String(range.start.line).padStart(12, "0")}:${String(range.start.column).padStart(12, "0")}`;

package/dist/application/JavaScriptSemanticTraceService.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { queryJavaScriptSemanticGraph } from "../domain/javascriptSemanticQuery.js";
+import { JavaScriptSemanticQueryCursorError } from "../domain/javascriptSemanticQueryIdentity.js";
+import { javaScriptSemanticTraceResultSchema, traceJavaScriptSemanticsInputSchema, } from "../domain/javascriptSemanticTraceSchemas.js";
+import { err, ok } from "../domain/result.js";
+import { parseApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
+import { createJavaScriptSemanticTraceEvidence } from "./JavaScriptApplicationWorkflowEvidence.js";
+const OPERATION = "trace_javascript_semantics";
+/** Trace semantic relations from input already parsed by a trusted adapter. */
+export const traceJavaScriptSemanticsEvidenceValidated = (input) => {
+    try {
+        const source = parseApplicationGraphEvidence(input.application);
+        if (source.semanticGraph === null)
+            return err(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["application"],
+                    reason: "invalid_value",
+                    expected: "analyze_javascript_application v2 Evidence; reanalyze the artifact with the current REA version",
+                },
+            ]));
+        const query = queryJavaScriptSemanticGraph(source.semanticGraph, input.query);
+        const result = javaScriptSemanticTraceResultSchema.parse({
+            ...query,
+            source_evidence_id: source.evidence.evidence_id,
+            evidence_links: [source.evidence.evidence_id],
+        });
+        return ok(createJavaScriptSemanticTraceEvidence({
+            application_evidence_id: source.evidence.evidence_id,
+            query: jsonValueSchema.parse(input.query),
+        }, result));
+    }
+    catch (cause) {
+        if (cause instanceof JavaScriptSemanticQueryCursorError)
+            return err(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["query", "cursor"],
+                    reason: "invalid_value",
+                    expected: "a cursor returned by the same graph, query, and limits",
+                },
+            ]));
+        return err(new AnalysisProtocolError("JavaScript semantic trace failed", { cause }));
+    }
+};

package/dist/application/LoopbackReplay.js

@@ -1,113 +1,144 @@
 import { createServer, } from "node:http";
 import { WebSocketServer } from "ws";
-class ReplayRecorder {
-    scenario;
-    events = [];
-    started = Date.now();
-    truncated = false;
-    constructor(scenario) {
-        this.scenario = scenario;
+import {} from "../domain/replayMachineRuntime.js";
+import { closeReplayServer, listenOnLoopback, recordMachineEvent, readReplayRequestBody, ReplayRecorder, requestHeaders, waitForReplayDelay, } from "./LoopbackReplayRecorder.js";
+const recordHttpResponse = (recorder, request, data, outcome) => recorder.record({
+    at_ms: recorder.atMs(),
+    protocol: "http",
+    direction: "response",
+    method: request.method,
+    path: request.path,
+    data,
+    outcome,
+});
+const handleMachineHttp = async (recorder, request) => {
+    const machine = recorder.machine;
+    if (machine === undefined)
+        return;
+    const decision = recorder.dispatchMachine({
+        protocol: "http",
+        connection: "not_applicable",
+        at_ms: request.rawAtMs,
+        recorded_at_ms: request.recordedAtMs,
+        method: request.method,
+        path: request.path,
+        headers: requestHeaders(request.request),
+        body: request.body,
+    });
+    recordMachineEvent(recorder, {
+        at_ms: request.recordedAtMs,
+        protocol: "http",
+        direction: "request",
+        method: request.method,
+        path: request.path,
+        data: request.body,
+    }, decision);
+    if (decision.outcome !== "matched") {
+        request.response.statusCode = decision.outcome === "unmatched" ? 404 : 409;
+        request.response.end();
+        return;
     }
-    atMs() {
-        return (Math.floor((Date.now() - this.started) /
-            this.scenario.normalization.time_bucket_ms) * this.scenario.normalization.time_bucket_ms);
+    for (const action of decision.actions) {
+        if (action.type === "delay")
+            await waitForReplayDelay(action.duration_ms);
+        else if (action.type === "disconnect") {
+            request.response.destroy();
+            recordHttpResponse(recorder, request, "", "disconnected");
+            return;
+        }
+        else if (action.type === "http_response") {
+            request.response.statusCode = action.status;
+            for (const [name, value] of Object.entries(action.headers))
+                request.response.setHeader(name, value);
+            request.response.end(action.body);
+            recordHttpResponse(recorder, request, machine.redact(action.body), "matched");
+        }
     }
-    record(event) {
-        if (this.events.length < this.scenario.limits.protocol_events)
-            this.events.push({ sequence: this.events.length, ...event });
-        else
-            this.truncated = true;
+};
+const handleStaticHttp = async (recorder, request, calls) => {
+    const index = recorder.scenario.replay.http.findIndex((route) => route.method !== request.method || route.path !== request.path
+        ? false
+        : (route.request_body === undefined ||
+            route.request_body === request.body) &&
+            Object.entries(route.request_headers).every(([name, value]) => request.request.headers[name.toLowerCase()] === value));
+    const route = recorder.scenario.replay.http[index];
+    const used = index < 0 ? 0 : (calls.get(index) ?? 0);
+    const outcome = route === undefined
+        ? "unmatched"
+        : used >= route.max_calls
+            ? "script_exhausted"
+            : "matched";
+    recorder.record({
+        at_ms: recorder.atMs(),
+        protocol: "http",
+        direction: "request",
+        method: request.method,
+        path: request.path,
+        data: request.body.length === 0 ? "" : "<redacted-request-body>",
+        outcome,
+    });
+    if (route === undefined || outcome === "script_exhausted") {
+        request.response.statusCode = route === undefined ? 404 : 409;
+        request.response.end();
+        return;
     }
-}
-const readRequestBody = async (request, limit) => {
-    const chunks = [];
-    let bytes = 0;
-    for await (const chunk of request) {
-        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        bytes += value.byteLength;
-        if (bytes > limit)
-            return undefined;
-        chunks.push(value);
+    calls.set(index, used + 1);
+    if (route.delay_ms > 0)
+        await waitForReplayDelay(route.delay_ms);
+    if (route.disconnect) {
+        request.response.destroy();
+        recordHttpResponse(recorder, request, "", "disconnected");
+        return;
     }
-    return Buffer.concat(chunks).toString("utf8");
+    request.response.statusCode = route.status;
+    for (const [name, value] of Object.entries(route.response_headers))
+        request.response.setHeader(name, value);
+    request.response.end(route.body);
+    recordHttpResponse(recorder, request, route.body, "matched");
 };
-const createHttpHandler = (recorder) => {
-    const calls = new Map();
-    return async (request, response) => {
-        const method = request.method ?? "GET";
-        const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
-        const body = await readRequestBody(request, recorder.scenario.limits.protocol_body_bytes);
-        if (body === undefined) {
-            recorder.truncated = true;
-            response.statusCode = 413;
-            response.end();
-            recorder.record({
-                at_ms: recorder.atMs(),
-                protocol: "http",
-                direction: "request",
-                method,
-                path,
-                data: "<body-over-limit>",
-                outcome: "unmatched",
-            });
-            return;
-        }
-        const index = recorder.scenario.replay.http.findIndex((route) => {
-            if (route.method !== method || route.path !== path)
-                return false;
-            if (route.request_body !== undefined && route.request_body !== body)
-                return false;
-            return Object.entries(route.request_headers).every(([name, value]) => request.headers[name.toLowerCase()] === value);
-        });
-        const route = recorder.scenario.replay.http[index];
-        const used = index < 0 ? 0 : (calls.get(index) ?? 0);
-        const outcome = route === undefined
-            ? "unmatched"
-            : used >= route.max_calls
-                ? "script_exhausted"
-                : "matched";
+const handleHttpRequest = async (recorder, request, response, calls) => {
+    const body = await readReplayRequestBody(request, recorder.scenario.limits.protocol_body_bytes);
+    const method = request.method ?? "GET";
+    const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+    if (body === undefined) {
+        recorder.truncated = true;
+        response.statusCode = 413;
+        response.end();
         recorder.record({
             at_ms: recorder.atMs(),
             protocol: "http",
             direction: "request",
             method,
             path,
-            data: body.length === 0 ? "" : "<redacted-request-body>",
-            outcome,
+            data: "<body-over-limit>",
+            outcome: "unmatched",
         });
-        if (route === undefined || outcome === "script_exhausted") {
-            response.statusCode = route === undefined ? 404 : 409;
-            response.end();
-            return;
-        }
-        calls.set(index, used + 1);
-        if (route.delay_ms > 0)
-            await new Promise((resolveDelay) => setTimeout(resolveDelay, route.delay_ms));
-        if (route.disconnect) {
-            response.destroy();
-            recorder.record({
-                at_ms: recorder.atMs(),
-                protocol: "http",
-                direction: "response",
-                method,
-                path,
-                data: "",
-                outcome: "disconnected",
-            });
-            return;
-        }
-        response.statusCode = route.status;
-        for (const [name, value] of Object.entries(route.response_headers))
-            response.setHeader(name, value);
-        response.end(route.body);
-        recorder.record({
-            at_ms: recorder.atMs(),
-            protocol: "http",
-            direction: "response",
-            method,
-            path,
-            data: route.body,
-            outcome: "matched",
+        return;
+    }
+    const replayRequest = {
+        request,
+        response,
+        method,
+        path,
+        body,
+        rawAtMs: recorder.rawAtMs(),
+        recordedAtMs: recorder.atMs(),
+    };
+    await (recorder.machine === undefined
+        ? handleStaticHttp(recorder, replayRequest, calls)
+        : recorder.enqueueMachine(() => handleMachineHttp(recorder, replayRequest)));
+};
+const createHttpHandler = (recorder) => {
+    const calls = new Map();
+    return (request, response) => {
+        void handleHttpRequest(recorder, request, response, calls).catch(() => {
+            recorder.truncated = true;
+            if (response.headersSent)
+                response.destroy();
+            else {
+                response.statusCode = 500;
+                response.end();
+            }
         });
     };
 };
@@ -161,6 +192,119 @@ const sendWebSocketScript = async (client, connection, recorder) => {
         });
     }
 };
+const runWebSocketActions = async (client, recorder, decision, path) => {
+    for (const action of decision.actions) {
+        if (action.type === "delay") {
+            await waitForReplayDelay(action.duration_ms);
+            continue;
+        }
+        if (action.type === "disconnect") {
+            client.close();
+            recorder.record({
+                at_ms: recorder.atMs(),
+                protocol: "websocket",
+                direction: "sent",
+                method: null,
+                path,
+                data: "",
+                outcome: "disconnected",
+            });
+            return;
+        }
+        if (action.type === "websocket_send" && client.readyState === 1) {
+            client.send(action.data);
+            recorder.record({
+                at_ms: recorder.atMs(),
+                protocol: "websocket",
+                direction: "sent",
+                method: null,
+                path,
+                data: recorder.machine?.redact(action.data) ?? action.data,
+                outcome: "matched",
+            });
+        }
+    }
+};
+const handleStaticWebSocket = (client, recorder, connection, path) => {
+    client.on("message", (value) => recorder.record({
+        at_ms: recorder.atMs(),
+        protocol: "websocket",
+        direction: "received",
+        method: null,
+        path,
+        data: value.toString(),
+        outcome: "matched",
+    }));
+    void sendWebSocketScript(client, connection, recorder);
+};
+const handleMachineWebSocket = (options) => {
+    const { client, request, recorder, connection, path } = options;
+    const machine = recorder.machine;
+    if (machine === undefined)
+        return;
+    void recorder
+        .enqueueMachine(async () => {
+        const connectedAt = recorder.atMs();
+        const connectionDecision = recorder.dispatchMachine({
+            protocol: "websocket_connect",
+            connection: connection === 1 ? "initial" : "reconnect",
+            at_ms: recorder.rawAtMs(),
+            recorded_at_ms: connectedAt,
+            method: null,
+            path,
+            headers: requestHeaders(request),
+            body: "",
+        });
+        recordMachineEvent(recorder, {
+            at_ms: connectedAt,
+            protocol: "websocket",
+            direction: "received",
+            method: null,
+            path,
+            data: "",
+        }, connectionDecision);
+        if (connectionDecision.outcome === "matched")
+            await runWebSocketActions(client, recorder, connectionDecision, path);
+        else
+            client.close();
+    })
+        .catch(() => {
+        recorder.truncated = true;
+        client.terminate();
+    });
+    client.on("message", (value) => {
+        const body = value.toString();
+        const rawAtMs = recorder.rawAtMs();
+        const recordedAtMs = recorder.atMs();
+        void recorder
+            .enqueueMachine(async () => {
+            const decision = recorder.dispatchMachine({
+                protocol: "websocket_message",
+                connection: connection === 1 ? "initial" : "reconnect",
+                at_ms: rawAtMs,
+                recorded_at_ms: recordedAtMs,
+                method: null,
+                path,
+                headers: {},
+                body,
+            });
+            recordMachineEvent(recorder, {
+                at_ms: recordedAtMs,
+                protocol: "websocket",
+                direction: "received",
+                method: null,
+                path,
+                data: body,
+            }, decision);
+            if (decision.outcome === "matched")
+                await runWebSocketActions(client, recorder, decision, path);
+        })
+            .catch(() => {
+            recorder.truncated = true;
+            client.terminate();
+        });
+    });
+};
 const createWebSocketReplay = (server, recorder) => {
     let connections = 0;
     const websocket = new WebSocketServer({
@@ -169,13 +313,14 @@ const createWebSocketReplay = (server, recorder) => {
         clientTracking: true,
     });
     server.on("upgrade", (request, socket, head) => {
-        if (new URL(request.url ?? "/", "http://127.0.0.1").pathname !== "/ws") {
+        if (recorder.machine === undefined &&
+            new URL(request.url ?? "/", "http://127.0.0.1").pathname !== "/ws") {
             socket.destroy();
             return;
         }
         websocket.handleUpgrade(request, socket, head, (client) => websocket.emit("connection", client, request));
     });
-    websocket.on("connection", (client) => {
+    websocket.on("connection", (client, request) => {
         connections += 1;
         if (connections > recorder.scenario.limits.connections) {
             recorder.truncated = true;
@@ -183,60 +328,59 @@ const createWebSocketReplay = (server, recorder) => {
             return;
         }
         client.on("error", () => undefined);
-        client.on("message", (value) => recorder.record({
-            at_ms: recorder.atMs(),
-            protocol: "websocket",
-            direction: "received",
-            method: null,
-            path: "/ws",
-            data: value.toString(),
-            outcome: "matched",
-        }));
-        void sendWebSocketScript(client, connections, recorder);
+        const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+        if (recorder.machine === undefined)
+            handleStaticWebSocket(client, recorder, connections, path);
+        else
+            handleMachineWebSocket({
+                client,
+                request,
+                recorder,
+                connection: connections,
+                path,
+            });
     });
     return websocket;
 };
-const listen = async (server) => {
-    await new Promise((resolveListen, rejectListen) => {
-        server.once("error", rejectListen);
-        server.listen(0, "127.0.0.1", () => {
-            server.off("error", rejectListen);
-            resolveListen();
-        });
-    });
-    const address = server.address();
-    if (address === null || typeof address === "string")
-        throw new Error("loopback replay did not acquire a TCP port");
-    return address.port;
-};
-const closeServer = (server) => new Promise((resolveClose, rejectClose) => {
-    server.close((error) => error === undefined ? resolveClose() : rejectClose(error));
-});
 /** Start bounded HTTP and WebSocket replay endpoints on IPv4 loopback only. */
-export const startLoopbackReplay = async (scenario) => {
-    const recorder = new ReplayRecorder(scenario);
+export const startLoopbackReplay = async (scenario, recordEvent = () => undefined) => {
+    const recorder = new ReplayRecorder(scenario, recordEvent);
     const server = createServer(createHttpHandler(recorder));
     const websocket = createWebSocketReplay(server, recorder);
+    let closePromise;
     let port;
     try {
-        port = await listen(server);
+        port = await listenOnLoopback(server);
     }
     catch (cause) {
-        await closeServer(server).catch(() => undefined);
+        await closeReplayServer(server).catch(() => undefined);
         throw cause;
     }
     return {
         httpUrl: `http://127.0.0.1:${String(port)}`,
         websocketUrl: `ws://127.0.0.1:${String(port)}/ws`,
-        events: recorder.events,
+        get events() {
+            return recorder.events.map((event) => ({ ...event }));
+        },
+        get transitions() {
+            return recorder.transitions.map((transition) => ({
+                ...transition,
+                sensitive_aliases: [...transition.sensitive_aliases],
+            }));
+        },
         get truncated() {
             return recorder.truncated;
         },
         async close() {
-            for (const client of websocket.clients)
-                client.terminate();
-            await new Promise((resolveClose) => websocket.close(() => resolveClose()));
-            await closeServer(server);
+            closePromise ??= (async () => {
+                recorder.stopMachineAdmission();
+                for (const client of websocket.clients)
+                    client.terminate();
+                await new Promise((resolveClose) => websocket.close(() => resolveClose()));
+                await closeReplayServer(server);
+                await recorder.drainMachine();
+            })();
+            await closePromise;
         },
     };
 };