rea-agents 6.4.0 → 6.5.0

package/dist/domain/javascript/javascriptPackageImportAliases.js

@@ -0,0 +1,58 @@
+/**
+ * Exact package-private import-alias lookup. Node resolves `#` specifiers
+ * against the importer's enclosing package `imports` map; this module owns the
+ * specifier and exact-key rules. Condition, array, and null target selection
+ * stay with the shared package-target machinery. Wildcard keys, recursive
+ * `#` targets, and external-package targets remain explicit unknowns.
+ */
+/**
+ * Classify a `#` module specifier before any package-scope walk.
+ * `#` and names ending in `/` are invalid. Other literal keys, including
+ * `#/…`, participate in exact lookup; wildcard expansion remains unsupported.
+ */
+export const classifyPackageImportSpecifier = (specifier) => {
+    if (specifier === "#" || specifier.endsWith("/"))
+        return { kind: "invalid" };
+    if (specifier.includes("*"))
+        return { kind: "pattern" };
+    return { kind: "exact", key: specifier };
+};
+/** True when an `imports` key is a pattern rather than an exact alias. */
+export const isPackageImportPatternKey = (key) => key.includes("*") || key.endsWith("/");
+/**
+ * Look up one exact `#` key in a package `imports` value.
+ * A missing exact key is reported as missing when every declared key is also
+ * exact; if the map contains pattern keys, the miss stays pattern-unresolved
+ * rather than claiming the specifier is undefined.
+ */
+export const lookupExactPackageImport = (imports, key) => {
+    if (typeof imports !== "object" || imports === null || Array.isArray(imports))
+        return { kind: "undefined-map" };
+    const declared = Object.keys(imports);
+    if (Object.hasOwn(imports, key) && !isPackageImportPatternKey(key))
+        return {
+            kind: "found",
+            target: Reflect.get(imports, key),
+            declared,
+        };
+    return declared.some(isPackageImportPatternKey)
+        ? { kind: "pattern-unresolved", declared }
+        : { kind: "missing-key", declared };
+};
+/**
+ * Classify a selected string import target. Only package-local `./` paths are
+ * resolved as files; recursive `#` aliases and bare packages stay unknown.
+ * Parent-relative, absolute, and URL targets are invalid, allowing array
+ * selection to skip them before choosing a package-local fallback.
+ */
+export const classifyPackageImportTargetString = (target) => {
+    if (target.startsWith("./"))
+        return { kind: "relative", target };
+    if (target.startsWith("../") ||
+        target.startsWith("/") ||
+        URL.canParse(target))
+        return { kind: "invalid", target };
+    if (target.startsWith("#"))
+        return { kind: "recursive", target };
+    return { kind: "external-package", target };
+};

package/dist/domain/javascript/javascriptRecovery.js

@@ -2,9 +2,14 @@ import { z } from "zod";
 import { digestSchema } from "../digests.js";
 import { analyzeJavaScriptApplicationInputSchema } from "./javascriptApplicationAnalysis.js";
 import { localPathStringSchema } from "../localPath.js";
-/** Recover derived readable modules from one explicitly selected local script. */
+/** Recover derived readable modules from explicitly selected local scripts. */
 export const javascriptRecoveryInputSchema = z.strictObject({
     path: localPathStringSchema.describe("Absolute path to a UTF-8 JavaScript file; never executed"),
+    additional_paths: z
+        .array(localPathStringSchema)
+        .max(16)
+        .optional()
+        .describe("Additional absolute UTF-8 JavaScript files recovered together with path; each is snapshotted separately so imports can resolve across related chunks. All inputs share a 64 MiB total budget"),
     output_directory: localPathStringSchema.describe("Absolute absent output directory; parent must exist"),
     extraction_mode: z
         .enum(["structural", "heuristic", "inspection"])
@@ -24,12 +29,14 @@ const rangeSchema = z.strictObject({
     start: z.number().int().nonnegative(),
     end: z.number().int().nonnegative(),
 });
+const sourceSchema = fileSchema.extend({
+    snapshot_path: z.string().min(1),
+    published_copy: fileSchema,
+});
 /** Complete published artifacts and exact producer provenance for source recovery. */
 export const javascriptRecoveryResultSchema = z.strictObject({
-    source: fileSchema.extend({
-        snapshot_path: z.string().min(1),
-        published_copy: fileSchema,
-    }),
+    source: sourceSchema,
+    additional_sources: z.array(sourceSchema).optional(),
     engine: z.strictObject({
         id: z.string().min(1),
         version: z.string().min(1),

package/dist/domain/javascript/javascriptRpcEndpoints.js

@@ -88,36 +88,86 @@ const objectKeys = (node) => t.isObjectExpression(node)
         return key === null ? [] : [key];
     })
     : [];
-const objectStringProperty = (node, key) => {
-    for (const property of node.properties)
-        if (t.isObjectProperty(property) &&
-            semanticStaticPropertyKey(property.key, property.computed) === key &&
-            t.isStringLiteral(property.value))
-            return property.value.value;
-    return undefined;
-};
+/** Later properties own a key; an intervening dynamic write leaves it unknown. */
 const objectProperty = (node, key) => {
-    for (const property of node.properties)
-        if (t.isObjectProperty(property) &&
-            semanticStaticPropertyKey(property.key, property.computed) === key)
-            return property.value;
+    for (let index = node.properties.length - 1; index >= 0; index -= 1) {
+        const property = node.properties[index];
+        if (property === undefined || t.isSpreadElement(property))
+            return undefined;
+        const name = semanticStaticPropertyKey(property.key, property.computed);
+        if (name === null)
+            return undefined;
+        if (name === key)
+            return t.isObjectProperty(property) ? property.value : undefined;
+    }
     return undefined;
 };
+const objectStringProperty = (node, key) => {
+    const value = objectProperty(node, key);
+    return t.isStringLiteral(value) ? value.value : undefined;
+};
+/**
+ * Find source-body string values owned by a GraphQL Source-shaped literal.
+ * A later duplicate or spread can make the effective `body` unknown, but the
+ * earlier strings still belong to this object and must not become standalone
+ * operation findings during the string scan.
+ */
+const graphqlSourceBodyLiterals = (node) => {
+    const bodyStrings = (object) => object.properties.flatMap((property) => t.isObjectProperty(property) &&
+        semanticStaticPropertyKey(property.key, property.computed) === "body" &&
+        t.isStringLiteral(property.value)
+        ? [property.value]
+        : []);
+    const bodies = bodyStrings(node);
+    const hasLocationOffset = node.properties.some((property) => t.isObjectProperty(property) &&
+        semanticStaticPropertyKey(property.key, property.computed) ===
+            "locationOffset");
+    if (!hasLocationOffset)
+        return undefined;
+    // Inline object spreads can own additional body values which the surrounding
+    // Source object may select. Include only body-key string literals from those
+    // spread values; ordinary strings elsewhere in the object remain scannable.
+    const visited = new WeakSet();
+    visited.add(node);
+    const pending = node.properties.flatMap((property) => {
+        if (!t.isSpreadElement(property))
+            return [];
+        const spread = unwrapJavaScriptExpression(property.argument).node;
+        return t.isObjectExpression(spread) ? [spread] : [];
+    });
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined || visited.has(current))
+            continue;
+        visited.add(current);
+        bodies.push(...bodyStrings(current));
+        for (const property of current.properties) {
+            if (t.isSpreadElement(property)) {
+                const spread = unwrapJavaScriptExpression(property.argument).node;
+                if (t.isObjectExpression(spread))
+                    pending.push(spread);
+            }
+        }
+    }
+    return bodies.length === 0 ? undefined : bodies;
+};
 const GRAPHQL_OPERATION_TYPES = new Set([
     "query",
     "mutation",
     "subscription",
 ]);
-// A named GraphQL operation header (GraphQL October 2021, OperationDefinition):
-// type, name, then variable definitions starting with `$`, a directive, or a
-// selection set starting with a field name.
-const GRAPHQL_OPERATION_HEADER = /^(query|mutation|subscription)[\s,]+([_A-Za-z][_0-9A-Za-z]*)[\s,]*(?:\([\s,]*\$|@[_A-Za-z]|\{[\s,]*[_A-Za-z])/u;
-const isGraphqlIgnoredCharacter = (character) => character === "," || character === "" || /\s/u.test(character);
-/** Recover a named operation from GraphQL document text. */
-export const graphqlOperationFromText = (text) => {
-    // Skip GraphQL ignored tokens: whitespace, commas, BOM and # comments.
+// GraphQL October 2021 §2.1.7: ignored BOM, tab/space, line endings, commas;
+// comments are consumed separately below.
+const isGraphqlIgnoredCharacter = (character) => character === "," ||
+    character === "\uFEFF" ||
+    character === "\t" ||
+    character === " " ||
+    character === "\n" ||
+    character === "\r";
+/** Return the first offset after GraphQL ignored tokens. */
+const skipGraphqlIgnored = (text, start) => {
     const limit = text.length;
-    let index = 0;
+    let index = start;
     while (index < limit) {
         const character = text.charAt(index);
         if (isGraphqlIgnoredCharacter(character))
@@ -129,14 +179,33 @@ export const graphqlOperationFromText = (text) => {
         else
             break;
     }
-    if (index >= limit)
-        return undefined;
-    const header = GRAPHQL_OPERATION_HEADER.exec(text.slice(index));
-    const type = header?.[1];
-    const name = header?.[2];
-    return type === undefined || name === undefined
+    return index;
+};
+const graphqlNameAt = (text, index) => {
+    const name = /^[_A-Za-z][_0-9A-Za-z]*/u.exec(text.slice(index))?.[0];
+    return name === undefined
         ? undefined
-        : { value: name, mechanism: `graphql:${type}` };
+        : { value: name, end: index + name.length };
+};
+/** Recover a named operation from GraphQL document text. */
+export const graphqlOperationFromText = (text) => {
+    const type = graphqlNameAt(text, skipGraphqlIgnored(text, 0));
+    if (type === undefined || !GRAPHQL_OPERATION_TYPES.has(type.value))
+        return undefined;
+    const name = graphqlNameAt(text, skipGraphqlIgnored(text, type.end));
+    if (name === undefined)
+        return undefined;
+    const index = skipGraphqlIgnored(text, name.end);
+    const next = text.charAt(index);
+    // Keep the existing bounded recognition scope: a named operation followed
+    // by variable definitions, a directive, or a selection set with a field.
+    const hasHeader = next === "("
+        ? text.charAt(skipGraphqlIgnored(text, index + 1)) === "$"
+        : (next === "@" || next === "{") &&
+            graphqlNameAt(text, skipGraphqlIgnored(text, index + 1)) !== undefined;
+    return hasHeader
+        ? { value: name.value, mechanism: `graphql:${type.value}` }
+        : undefined;
 };
 /** Recover a named operation from a precompiled GraphQL document object. */
 export const graphqlOperationFromDocumentNode = (node) => {
@@ -195,9 +264,10 @@ const trpcLinkUrl = (node) => {
 export const createJavaScriptRpcScan = (source, clientRoots) => {
     let marker;
     const hasMarker = () => (marker ??= TRPC_SOURCE_MARKERS.some((value) => source.includes(value)));
-    // graphql-tag documents retain their source text in loc.source.body; that
-    // text repeats the OperationDefinition already recovered from the object.
-    const documentSourceBodies = new WeakSet();
+    // graphql-tag documents retain source text in loc.source.body. Keep each
+    // direct body literal owned by a Source-shaped object out of the independent
+    // string scan, including duplicates that a later property or spread hides.
+    const graphqlDocumentSourceBodies = new WeakSet();
     const procedure = (node) => {
         const path = memberPath(node.callee);
         if (path === undefined || t.isThisExpression(path.root))
@@ -228,24 +298,32 @@ export const createJavaScriptRpcScan = (source, clientRoots) => {
             if (t.isCallExpression(node) || t.isOptionalCallExpression(node))
                 return trpcLinkUrl(node) ?? procedure(node);
             if (t.isObjectExpression(node)) {
-                const body = objectProperty(node, "body");
-                if (t.isStringLiteral(body) &&
-                    objectProperty(node, "locationOffset") !== undefined) {
-                    documentSourceBodies.add(body);
+                const bodies = graphqlSourceBodyLiterals(node);
+                if (bodies !== undefined) {
+                    for (const body of bodies)
+                        graphqlDocumentSourceBodies.add(body);
                     return undefined;
                 }
                 return graphqlOperationFromDocumentNode(node);
             }
             if (t.isStringLiteral(node))
-                return documentSourceBodies.has(node)
+                return graphqlDocumentSourceBodies.has(node)
                     ? undefined
                     : graphqlOperationFromText(node.value);
             if (t.isTemplateLiteral(node)) {
-                // A template recovered without a cooked value stays dynamic.
-                const cooked = node.quasis[0]?.value.cooked;
-                return cooked === undefined || cooked === null
-                    ? undefined
-                    : graphqlOperationFromText(cooked);
+                // Interpolations may contain fragment definitions. Continue only
+                // across quasis that contain ignored tokens; prose or dynamic text
+                // before an operation prevents claiming a later operation belongs to
+                // this document prefix.
+                for (const quasi of node.quasis) {
+                    const cooked = quasi.value.cooked;
+                    if (cooked === undefined || cooked === null)
+                        return undefined;
+                    if (skipGraphqlIgnored(cooked, 0) === cooked.length)
+                        continue;
+                    return graphqlOperationFromText(cooked);
+                }
+                return undefined;
             }
             return undefined;
         },

package/dist/domain/javascript/javascriptRuntimeLoadState.js

@@ -14,11 +14,16 @@ export const classifyStaticLoadStates = (layers, runtimeEntities, matches, optio
 const classifyLayer = (layer, runtimeEntities, matches, options) => {
     const nodes = layer.graph.nodes.filter(isLoadStateNode);
     const direct = new Map();
+    const ambiguous = new Set();
     for (const match of matches)
         if (match.status === "matched" &&
             match.static_layer_id === layer.layerId &&
             match.static_node_id !== null)
             append(direct, match.static_node_id, match.runtime_node_id);
+        else if (match.status === "ambiguous")
+            for (const candidate of match.candidate_static_nodes)
+                if (candidate.static_layer_id === layer.layerId)
+                    ambiguous.add(candidate.static_node_id);
     const resident = residentNodes(layer, new Set(direct.keys()));
     const runtimeScope = createStaticRuntimeScope(layer, runtimeEntities);
     const scopedEntities = runtimeEntities.filter((entity) => mappedRuntimePaths(layer, entity).length > 0);
@@ -40,6 +45,12 @@ const classifyLayer = (layer, runtimeEntities, matches, options) => {
                 runtimeNodeIds: [],
                 reason: "containing-asset-was-loaded",
             });
+        if (ambiguous.has(node.node_id))
+            return state(layer, node, {
+                status: "unknown",
+                runtimeNodeIds: [],
+                reason: "ambiguous-runtime-candidate",
+            });
         const nodeWithinScope = staticNodeWithinRuntimeScope(node, runtimeScope);
         if (layerComplete && nodeWithinScope)
             return state(layer, node, {

package/dist/domain/javascript/javascriptRuntimeObservation.js

@@ -62,7 +62,10 @@ export const javascriptRuntimeTargetLocationSchema = z.union([
 const javascriptRuntimeTargetSchema = z.strictObject({
     target_id: z.string().min(1),
     protocol_type: z.string().min(1),
-    attached: z.boolean(),
+    attached: z
+        .boolean()
+        .nullable()
+        .describe("Discovery-reported debugger attachment state; null means unknown"),
     location: javascriptRuntimeTargetLocationSchema,
 });
 /** Complete V8 Inspector target inventory exposed by the selected endpoint. */

package/dist/domain/javascript/javascriptRuntimeReconciliationCaptureParsing.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { browserAllowedOriginsSchema, browserEndpointSchema, } from "../browserObservation.js";
+import { browserAllowedOriginsSchema, browserEndpointSchema, recordedBrowserObservationEndpointSchema, } from "../browserObservation.js";
 import { webPageInspectionSchema, } from "../browserObservationSchemas.js";
 import { classifyBrowserCompleteness, } from "../browserCompleteness.js";
 import { electronPageInspectionSchema, } from "./electronObservation.js";
@@ -185,12 +185,15 @@ const excludedV8Scripts = (result) => Object.values(result.scripts.excluded).red
 const assertRuntimeParameters = (evidence, expected, path) => {
     const common = {
         target_id: z.string().trim().min(1),
-        cdp_endpoint: browserEndpointSchema,
         include_script_sources: z.boolean(),
     };
     if (expected.kind === "browser") {
         const parameters = parseAtPath((value) => z
-            .object({ ...common, allowed_origins: browserAllowedOriginsSchema })
+            .object({
+            ...common,
+            cdp_endpoint: recordedBrowserObservationEndpointSchema,
+            allowed_origins: browserAllowedOriginsSchema,
+        })
             .passthrough()
             .parse(value), evidence.parameters, [...path, "parameters"]);
         if (parameters.target_id !== expected.targetId)
@@ -201,7 +204,10 @@ const assertRuntimeParameters = (evidence, expected, path) => {
             throw invalidInput([...path, "parameters", "include_script_sources"], "Runtime Evidence contains source without source-capture selection");
         return;
     }
-    const parameters = parseAtPath((value) => z.object(common).passthrough().parse(value), evidence.parameters, [...path, "parameters"]);
+    const parameters = parseAtPath((value) => z
+        .object({ ...common, cdp_endpoint: browserEndpointSchema })
+        .passthrough()
+        .parse(value), evidence.parameters, [...path, "parameters"]);
     if (parameters.target_id !== expected.targetId)
         throw invalidInput([...path, "parameters", "target_id"], "Runtime Evidence target disagrees with its captured result");
     if (expected.sourceIncluded && !parameters.include_script_sources)

package/dist/domain/javascript/javascriptRuntimeReconciliationMatching.js

@@ -100,7 +100,16 @@ const candidatesWithLocation = (entity, index, layers) => {
     const located = new Map();
     for (const layer of layers)
         for (const mapping of mappedRuntimePaths(layer, entity))
-            for (const candidate of index.byLayerCategoryPath.get(layerCategoryPathKey(layer.layerId, entity.staticKind, mapping.path)) ?? []) {
+            for (const candidate of [
+                ...(index.byLayerCategoryPath.get(layerCategoryPathKey(layer.layerId, entity.staticKind, mapping.path)) ?? []),
+                ...(mapping.fileStyle === null || mapping.nativeRelativePath === null
+                    ? []
+                    : (index.byNativeDeclarationPath.get(`${mapping.fileStyle}\0${layerCategoryPathKey(layer.layerId, entity.staticKind, mapping.nativeRelativePath)}`) ?? [])
+                        .filter(({ sourcePath }) => mapping.artifactPrefix === "" ||
+                        (sourcePath !== null &&
+                            sourcePath.startsWith(`${mapping.artifactPrefix}/`)))
+                        .map(({ candidate }) => candidate)),
+            ]) {
                 const key = candidateKey(candidate);
                 if (!located.has(key))
                     located.set(key, { candidate, mapping });
@@ -110,13 +119,17 @@ const candidatesWithLocation = (entity, index, layers) => {
 const indexCandidates = (candidates) => {
     const byCategoryDigest = new Map();
     const byLayerCategoryPath = new Map();
+    const byNativeDeclarationPath = new Map();
     for (const candidate of candidates) {
         for (const { sha256 } of candidate.digests)
             appendIndex(byCategoryDigest, categoryDigestKey(candidate.category, sha256), candidate);
         for (const path of candidate.paths)
             appendIndex(byLayerCategoryPath, layerCategoryPathKey(candidate.layer.layerId, candidate.category, path), candidate);
+        for (const style of ["posix", "windows"])
+            for (const { path, sourcePath } of candidate.nativeDeclarationPaths[style])
+                appendIndex(byNativeDeclarationPath, `${style}\0${layerCategoryPathKey(candidate.layer.layerId, candidate.category, path)}`, { candidate, sourcePath });
     }
-    return { byCategoryDigest, byLayerCategoryPath };
+    return { byCategoryDigest, byLayerCategoryPath, byNativeDeclarationPath };
 };
 const appendIndex = (index, key, candidate) => {
     const values = index.get(key);

package/dist/domain/javascript/javascriptRuntimeReconciliationResult.js

@@ -1,4 +1,3 @@
-import {} from "./javascriptApplicationGraph.js";
 import { digestCanonicalValue } from "../canonicalDigest.js";
 import { uniqueSorted } from "../canonicalOrdering.js";
 import { javascriptRuntimeReconciliationResultSchema, } from "./javascriptRuntimeReconciliationSchemas.js";

package/dist/domain/javascript/javascriptRuntimeReconciliationSchemas.js

@@ -1,18 +1,19 @@
 import { z } from "zod";
 import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+import { logicalPathEscapesRoot } from "../artifactIdentity.js";
 import { evidenceSchema } from "../evidence.js";
 import { javascriptRuntimeUnresolvedLocationSchema } from "./javascriptRuntimeObservation.js";
 import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
 import { digestSchema } from "../digests.js";
 import { prefixedDigestSchema } from "../digests.js";
+import { urlDeclaresQueryOrFragment } from "../urlComponents.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const nodeIdSchema = prefixedDigestSchema("jag_node");
 const boundedTextSchema = z.string().min(1);
 const safePrefixSchema = z
     .string()
     .refine((value) => value === "" ||
-    (!value.startsWith("/") &&
-        !value.includes("\\") &&
+    (!logicalPathEscapesRoot(value) &&
         value.split("/").every((part) => !["", ".", ".."].includes(part))), "Artifact prefix must be empty or a safe relative POSIX path");
 const runtimeFileMappingSchema = z.strictObject({
     kind: z.literal("file-root"),
@@ -41,8 +42,7 @@ const normalizeRuntimeUrlPrefix = (value) => {
     if (!["http:", "https:"].includes(url.protocol) ||
         url.username !== "" ||
         url.password !== "" ||
-        url.search !== "" ||
-        url.hash !== "")
+        urlDeclaresQueryOrFragment(url))
         return null;
     if (!url.pathname.endsWith("/"))
         url.pathname += "/";
@@ -191,6 +191,7 @@ const staticLoadStateSchema = z.strictObject({
         "not-observed-in-bounded-capture",
         "layer-outside-runtime-scope",
         "static-or-runtime-coverage-incomplete",
+        "ambiguous-runtime-candidate",
     ]),
 });
 /** Deterministic static/passive-runtime reconciliation with a combined JAG. */