rea-agents 6.3.0 → 6.4.0

package/dist/domain/javascript/javascriptSemanticValues.js

@@ -1,7 +1,7 @@
 import * as t from "@babel/types";
 import { semanticCapturePosition, semanticEscapeFollowsCapture, semanticBindingPrecedesCapture, } from "./javascriptSemanticMutationInitializers.js";
 import { semanticSlotAtPath } from "./javascriptSemanticSlots.js";
-import { invalidateSemanticEscapedPath, invalidateSemanticMutationPath, } from "./javascriptSemanticMutationValues.js";
+import { invalidateSemanticEscapedPath, invalidateSemanticMutationPaths, } from "./javascriptSemanticMutationValues.js";
 import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
 import { semanticRequireOrigin } from "./javascriptSemanticRequireOrigin.js";
 import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
@@ -91,21 +91,33 @@ const evaluateBinding = (binding, context) => {
     const initializer = binding.initializers[0];
     if (initializer === undefined)
         return { status: "unknown", reason: "Missing binding initializer." };
-    const nested = nestedContext(context, binding.bindingId);
-    let value = projectValue(evaluateExpression(initializer.node, nested), initializer.projection);
-    if (!isPrimitive(value)) {
-        const captureContext = primitiveCaptureContext(initializer.node, nested);
-        if (captureContext !== undefined) {
-            const captured = projectValue(evaluateExpression(initializer.node, captureContext), initializer.projection);
-            if (isPrimitive(captured))
-                value = captured;
+    context.bindings.add(binding.bindingId);
+    let value;
+    try {
+        const nested = nestedContext(context);
+        value = projectValue(evaluateExpression(initializer.node, nested), initializer.projection);
+        if (!isPrimitive(value)) {
+            const captureContext = primitiveCaptureContext(initializer.node, nested);
+            if (captureContext !== undefined) {
+                const captured = projectValue(evaluateExpression(initializer.node, captureContext), initializer.projection);
+                if (isPrimitive(captured))
+                    value = captured;
+            }
         }
     }
-    const mutated = binding.mutatedPaths.reduce(invalidateSemanticMutationPath, value);
-    const projected = binding.escapedPaths.reduce((value, escape) => context.capturePoint !== undefined &&
-        semanticEscapeFollowsCapture(binding, context.capturePoint, escape.node, context.state.parentsByNode)
-        ? value
-        : invalidateSemanticEscapedPath(value, escape.path), mutated);
+    finally {
+        context.bindings.delete(binding.bindingId);
+    }
+    let projected = invalidateSemanticMutationPaths(value, binding.mutatedPaths);
+    for (const escape of binding.escapedPaths) {
+        // Escapes only invalidate object references; other lattice values survive.
+        if (projected.status !== "object" && projected.status !== "array")
+            break;
+        if (context.capturePoint !== undefined &&
+            semanticEscapeFollowsCapture(binding, context.capturePoint, escape.node, context.state.parentsByNode))
+            continue;
+        projected = invalidateSemanticEscapedPath(projected, escape.path);
+    }
     // Point-local memoization also bounds failed speculative captures. Only a
     // primitive result is allowed back into ordinary value evaluation.
     if (context.capturePoint !== undefined ||
@@ -395,6 +407,17 @@ const projectValue = (value, projection) => {
         };
 };
 const provenanceForBinding = (binding, context) => {
+    const provenance = provenanceForBindingValue(binding, context);
+    const assigned = binding.definitions.some(({ kind }) => kind === "assignment");
+    const conditionallyInitialized = binding.initializers.some(({ node }) => context.state.conditionalInitializers.has(node));
+    if (provenance.status !== "module" ||
+        (!assigned && !conditionallyInitialized))
+        return provenance;
+    return semanticAmbiguousProvenance(provenance.origins, assigned
+        ? `Binding ${binding.name} may be reassigned.`
+        : `Binding ${binding.name} is conditionally initialized.`);
+};
+const provenanceForBindingValue = (binding, context) => {
     if (context.bindings.has(binding.bindingId))
         return semanticUnresolvedProvenance("cycle", `Alias cycle at ${binding.name}.`);
     if (binding.directOrigins.length > 0)
@@ -408,7 +431,14 @@ const provenanceForBinding = (binding, context) => {
         return semanticUnresolvedProvenance("unknown", "Missing binding initializer.");
     if (initializer.projection.includes(null))
         return semanticUnresolvedProvenance("unknown", "Dynamic provenance projection.");
-    const resolved = provenanceForExpression(initializer.node, nestedContext(context, binding.bindingId));
+    context.bindings.add(binding.bindingId);
+    let resolved;
+    try {
+        resolved = provenanceForExpression(initializer.node, nestedContext(context));
+    }
+    finally {
+        context.bindings.delete(binding.bindingId);
+    }
     if (resolved.status !== "module" || initializer.projection.length === 0)
         return resolved;
     return semanticOriginsProvenance(resolved.origins.map((origin) => ({
@@ -491,16 +521,14 @@ const mergeValues = (values) => {
         ? primitiveSet(primitives)
         : { status: "ambiguous", reason: "Branches have incompatible values." };
 };
-const nestedContext = (context, bindingId) => ({
+const nestedContext = (context) => ({
     state: context.state,
     primitiveBindingValues: context.primitiveBindingValues,
     ...(context.capturePoint === undefined
         ? {}
         : { capturePoint: context.capturePoint }),
     expressionDepth: context.expressionDepth + 1,
-    bindings: bindingId === undefined
-        ? context.bindings
-        : new Set([...context.bindings, bindingId]),
+    bindings: context.bindings,
 });
 const isPrimitive = (value) => value.status === "literal" || value.status === "union";
 const primitiveCaptureContext = (node, context) => {

package/dist/domain/javascript/javascriptSourceAnalysis.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/javascript/javascriptStaticAnalysis.js

@@ -1,13 +1,15 @@
 import * as t from "@babel/types";
-import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+import { ELECTRON_IDENTITY_LIMITATION, ELECTRON_MODULE, } from "./javascriptElectronMemberWrites.js";
+import { completeSemanticSteps, traverseJavaScriptAstSteps, } from "./javascriptSemanticTraversal.js";
 import { inspectElectronStaticNode } from "./electronStaticAnalysis.js";
 import { detectVendors, failedJavaScriptStaticAnalysis, registrationKey, sortedUnique, stringValue, } from "./javascriptStaticAnalysisHelpers.js";
-import { addReference, addSourceMapDirectives, inspectCall, inspectRouteProperty, inspectRoleProperty, } from "./javascriptStaticAnalysisCalls.js";
+import { addReference, addSourceMapDirectives, inspectCall, inspectRouteProperty, inspectRoleProperty, inspectRpcNode, } from "./javascriptStaticAnalysisCalls.js";
 import { inspectBundlerRegistration, inspectEsbuildWrapper, } from "./javascriptStaticAnalysisBundler.js";
 import { finalizeLocatedFindings } from "./javascriptStaticAnalysisFindings.js";
 import { createJavaScriptAnalysisAccumulator, } from "./javascriptStaticAnalysisState.js";
-import { classifyParsedJavaScriptOpenReceivers, } from "./javascriptSemanticAnalysis.js";
+import { classifyParsedJavaScriptElectronBindingsSteps, classifyParsedJavaScriptRpcClientRootsSteps, classifyParsedJavaScriptOpenReceivers, } from "./javascriptSemanticAnalysis.js";
 import { parseJavaScriptSource, } from "./javascriptSourceParser.js";
+import { createJavaScriptRpcScan } from "./javascriptRpcEndpoints.js";
 /** Parse one JavaScript artifact and recover static structure only. */
 export const analyzeJavaScriptStaticSource = (source) => {
     const file = parseJavaScriptSource(source);
@@ -16,21 +18,31 @@ export const analyzeJavaScriptStaticSource = (source) => {
         : analyzeParsedJavaScriptStaticSource(source, file, classifyParsedJavaScriptOpenReceivers(file));
 };
 /** Recover static structure from an already parsed JavaScript artifact. */
-export const analyzeParsedJavaScriptStaticSource = (source, file, openReceiverFacts) => {
+export const analyzeParsedJavaScriptStaticSource = (source, file, openReceiverFacts) => completeSemanticSteps(analyzeParsedJavaScriptStaticSourceSteps(source, file, openReceiverFacts));
+/** Static analysis that yields during its source traversal; results are unchanged. */
+export function* analyzeParsedJavaScriptStaticSourceSteps(source, file, openReceiverFacts) {
     const accumulator = createJavaScriptAnalysisAccumulator(source.length);
-    traverseStaticSource(source, file, accumulator, openReceiverFacts);
+    const electronBindings = yield* classifyParsedJavaScriptElectronBindingsSteps(file);
+    const clientRoots = yield* classifyParsedJavaScriptRpcClientRootsSteps(file);
+    yield* traverseStaticSourceSteps(file, {
+        source,
+        accumulator,
+        ...(openReceiverFacts === undefined ? {} : { openReceiverFacts }),
+        electronBindings,
+        rpcScan: createJavaScriptRpcScan(source, clientRoots),
+    });
     addSourceMapDirectives(source, file.comments ?? [], accumulator);
     return finalizeStaticAnalysis(source, file, accumulator);
-};
-const traverseStaticSource = (source, file, accumulator, openReceiverFacts) => {
-    traverseJavaScriptAst(file, {
+}
+function* traverseStaticSourceSteps(file, findings) {
+    yield* traverseJavaScriptAstSteps(file, {
         enter: (node) => {
-            accumulator.visitedNodes += 1;
-            inspectNode(source, node, accumulator, openReceiverFacts);
+            findings.accumulator.visitedNodes += 1;
+            inspectNode(node, findings);
             return undefined;
         },
     });
-};
+}
 const finalizeStaticAnalysis = (source, file, accumulator) => {
     const parserErrors = file.errors.length;
     const limitations = [
@@ -44,6 +56,9 @@ const finalizeStaticAnalysis = (source, file, accumulator) => {
             : [
                 "One or more static keys, expressions, or Electron boundary values were dynamic and remain unknown.",
             ]),
+        ...(accumulator.references.some(({ value }) => value.specifier !== null && ELECTRON_MODULE.test(value.specifier))
+            ? [ELECTRON_IDENTITY_LIMITATION]
+            : []),
         "JavaScript syntax was parsed as data and was never evaluated.",
     ];
     return {
@@ -70,12 +85,8 @@ const finalizeStaticAnalysis = (source, file, accumulator) => {
         limitations,
     };
 };
-const inspectNode = (source, node, accumulator, openReceiverFacts) => {
-    const findings = {
-        source,
-        accumulator,
-        ...(openReceiverFacts === undefined ? {} : { openReceiverFacts }),
-    };
+const inspectNode = (node, findings) => {
+    const { source, accumulator } = findings;
     inspectElectronStaticNode(node, findings);
     if (t.isCallExpression(node)) {
         inspectBundlerRegistration(source, node, accumulator);
@@ -110,4 +121,5 @@ const inspectNode = (source, node, accumulator, openReceiverFacts) => {
         inspectRouteProperty(node, findings);
         inspectRoleProperty(node, findings);
     }
+    inspectRpcNode(node, findings);
 };

package/dist/domain/javascript/javascriptStaticAnalysisBundler.js

@@ -15,7 +15,7 @@ export const inspectBundlerRegistration = (source, call, accumulator) => {
     const runtimeValue = runtimeMetadata(entry.elements[2]);
     if (!t.isArrayExpression(chunkIds) || !t.isObjectExpression(table))
         return;
-    const recovered = recoverBundlerModules(source, table, accumulator);
+    const recovered = recoverBundlerModules(source, table, runtime, accumulator);
     const chunkKeys = staticArrayValues(chunkIds);
     accumulator.unknownFindings += chunkKeys.unknown;
     accumulator.unknownFindings +=
@@ -55,13 +55,14 @@ export const inspectEsbuildWrapper = (source, call, accumulator) => {
     const table = call.arguments[0];
     if (wrapperKind === null || !t.isObjectExpression(table))
         return;
-    const recovered = recoverBundlerModules(source, table, accumulator);
+    const runtime = `esbuild-${wrapperKind}`;
+    const recovered = recoverBundlerModules(source, table, runtime, accumulator);
     if (recovered.modules.length === 0)
         return;
     accumulator.unknownFindings += recovered.unknownAsyncChunkKeys;
     const registration = {
         bundler: "esbuild",
-        runtime: `esbuild-${wrapperKind}`,
+        runtime,
         chunk_keys: [`${wrapperKind}@${String(call.start ?? 0)}`],
         unknown_chunk_keys: 0,
         runtime_require_name: null,
@@ -75,12 +76,12 @@ export const inspectEsbuildWrapper = (source, call, accumulator) => {
     };
     addFindingOnce(accumulator, `registration\0${registrationKey(registration)}`, () => accumulator.registrations.push(registration));
 };
-const recoverBundlerModules = (source, table, accumulator) => {
+const recoverBundlerModules = (source, table, runtime, accumulator) => {
     const modules = [];
     const asyncChunkKeys = [];
     let unknownAsyncChunkKeys = 0;
     for (const property of table.properties) {
-        const recovered = recoverBundlerModule(source, property, accumulator);
+        const recovered = recoverBundlerModule(source, property, runtime, accumulator);
         if (recovered === null)
             continue;
         modules.push(recovered.module);
@@ -93,7 +94,7 @@ const recoverBundlerModules = (source, table, accumulator) => {
         unknownAsyncChunkKeys,
     };
 };
-const recoverBundlerModule = (source, property, accumulator) => {
+const recoverBundlerModule = (source, property, runtime, accumulator) => {
     const factory = moduleFactory(property);
     if (factory === undefined)
         return null;
@@ -109,6 +110,7 @@ const recoverBundlerModule = (source, property, accumulator) => {
             start: factory.start,
             end: factory.end,
             key,
+            runtime,
             requireName,
         };
         accumulator.moduleRangeIndex.add(moduleRange);

package/dist/domain/javascript/javascriptStaticAnalysisCalls.js

@@ -32,6 +32,8 @@ export const inspectCall = (source, node, context) => {
         addReference(context, { node, kind: "service-worker", specifier: first });
     inspectEndpointCall(node, name, first, context);
     inspectStorageCall(node, name, first, context);
+    if (first === "audio" || first === "video")
+        noteMediaElementPreloads(node, accumulator);
     if (name.endsWith("loadFile") && first !== undefined)
         addLocatedFinding(context, {
             collection: accumulator.roles,
@@ -61,6 +63,18 @@ export const inspectCall = (source, node, context) => {
             },
         });
 };
+// Element factories such as jsx("audio", props) and createElement("video",
+// props) carry the HTML media `preload` hint ("none", "metadata", "auto"),
+// which never names an Electron preload script.
+const noteMediaElementPreloads = (node, accumulator) => {
+    const props = node.arguments[1];
+    if (!t.isObjectExpression(props))
+        return;
+    for (const property of props.properties)
+        if (t.isObjectProperty(property) &&
+            semanticStaticPropertyName(property.key, property.computed) === "preload")
+            accumulator.mediaElementPreloads.add(property);
+};
 const requireCallSpecifier = (node, name, moduleRequireName) => {
     if (name === "require" || name.endsWith(".require"))
         return { specifier: argumentValue(node.arguments[0]) };
@@ -114,6 +128,12 @@ const inspectEndpointCall = (node, name, first, context) => {
             mechanism: `call:${name}`,
         });
 };
+/** Record tRPC procedures, tRPC link URLs and named GraphQL operations. */
+export const inspectRpcNode = (node, context) => {
+    const rpc = context.rpcScan.inspect(node);
+    if (rpc !== undefined)
+        addEndpoint(context, { node, kind: "network", ...rpc });
+};
 export const inspectRouteProperty = (node, context) => {
     const key = semanticStaticPropertyName(node.key, node.computed);
     if ((key === "path" || key === "route") && t.isStringLiteral(node.value))
@@ -127,6 +147,8 @@ export const inspectRouteProperty = (node, context) => {
 export const inspectRoleProperty = (node, context) => {
     if (semanticStaticPropertyName(node.key, node.computed) !== "preload")
         return;
+    if (context.accumulator.mediaElementPreloads.has(node))
+        return;
     const path = staticPath(node.value);
     if (path === undefined)
         return;
@@ -213,13 +235,35 @@ export const addSourceMapDirectives = (source, comments, accumulator) => {
             end === undefined ||
             end === null)
             continue;
-        const match = /^(?:\/\/|\/\*)[#@]\s*sourceMappingURL\s*=\s*([^\s*]+)/u.exec(source.slice(start, end));
-        if (match === null)
+        const commentSource = source.slice(start, end);
+        if (!(commentSource.startsWith("//") || commentSource.startsWith("/*")) ||
+            !(commentSource[2] === "#" || commentSource[2] === "@"))
+            continue;
+        // Single-class searches avoid regex backtracking over unbounded whitespace
+        // or inline URLs, which can exhaust the engine stack on two-byte strings.
+        const nameOffset = commentSource.slice(3).search(/\S/u);
+        if (nameOffset === -1)
+            continue;
+        const nameStart = 3 + nameOffset;
+        if (!commentSource.startsWith("sourceMappingURL", nameStart))
+            continue;
+        const nameEnd = nameStart + "sourceMappingURL".length;
+        const equalsOffset = commentSource.slice(nameEnd).search(/\S/u);
+        if (equalsOffset === -1)
+            continue;
+        const equalsStart = nameEnd + equalsOffset;
+        if (!commentSource.startsWith("=", equalsStart))
+            continue;
+        const urlOffset = commentSource.slice(equalsStart + 1).search(/\S/u);
+        if (urlOffset === -1)
             continue;
-        const declared = match[1];
-        if (declared === undefined || declared.length === 0)
+        const declaredStart = equalsStart + 1 + urlOffset;
+        const terminator = commentSource.slice(declaredStart).search(/[\s*]/u);
+        const declaredEnd = terminator === -1 ? commentSource.length : declaredStart + terminator;
+        if (declaredEnd === declaredStart)
             continue;
-        const location = rangeForOffsets(source, start, start + match[0].length);
+        const declared = commentSource.slice(declaredStart, declaredEnd);
+        const location = rangeForOffsets(source, start, start + declaredEnd);
         addFindingOnce(accumulator, `source-map\0${declared}`, () => accumulator.sourceMaps.push({ declared_url: declared, location }));
     }
 };

package/dist/domain/javascript/javascriptStaticAnalysisFindings.js

@@ -76,7 +76,11 @@ export const addFindingOnce = (accumulator, key, add) => {
     add();
 };
 /** Attach recovered bundle-module ownership to findings after traversal. */
-export const finalizeLocatedFindings = (values, modules) => values.map(({ offset, value }) => ({
-    ...value,
-    module_key: modules.find(offset)?.key ?? null,
-}));
+export const finalizeLocatedFindings = (values, modules) => values.map(({ offset, value }) => {
+    const module = modules.find(offset);
+    return {
+        ...value,
+        module_key: module?.key ?? null,
+        ...(module === undefined ? {} : { module_runtime: module.runtime }),
+    };
+});

package/dist/domain/javascript/javascriptStaticAnalysisState.js

@@ -14,6 +14,7 @@ export const createJavaScriptAnalysisAccumulator = (sourceLength) => ({
     utilityProcesses: [],
     nativeAddonBindings: [],
     moduleRangeIndex: new JavaScriptModuleRangeIndex(sourceLength),
+    mediaElementPreloads: new WeakSet(),
     seen: new Set(),
     visitedNodes: 0,
     unknownFindings: 0,

package/dist/domain/jeb/jebAnalysis.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+/**
+ * Caller intent for JEB-backed inspection, independent of the engine build.
+ *
+ * JEB resolves paths on the host running the JEB client that serves MCP; REA
+ * never launches the engine or opens the target itself.
+ */
+export const jebInputSchemas = {
+    inspect_jeb_client: z.strictObject({}),
+    open_jeb_project: z.strictObject({
+        path: localPathStringSchema.describe("Artifact file or existing .jdb2 project database, resolved by the running JEB client"),
+    }),
+    list_jeb_units: z.strictObject({
+        filter: z
+            .string()
+            .optional()
+            .describe("Wildcard filter matched against unit paths; '*' allowed"),
+        parent_unit_path: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Restrict results to descendants of this unit path"),
+        index: z
+            .number()
+            .int()
+            .nonnegative()
+            .default(0)
+            .describe("Zero-based index of the first result to return"),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(100)
+            .describe("Maximum results to return; the engine protocol caps pages at 100"),
+    }),
+    decompile_jeb_item: z.strictObject({
+        unit_path: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Target code unit; the engine's first code unit in the project when omitted"),
+        item_address: z
+            .string()
+            .min(1)
+            .describe("Type or method address within the unit, as listed by the engine"),
+        item_kind: z.enum(["type", "method"]).describe("Kind of item to decompile"),
+    }),
+};
+/** Validate operation and input together so their types remain correlated. */
+export const jebRequestSchema = z.discriminatedUnion("operation", [
+    z.strictObject({
+        operation: z.literal("inspect_jeb_client"),
+        input: jebInputSchemas.inspect_jeb_client,
+    }),
+    z.strictObject({
+        operation: z.literal("open_jeb_project"),
+        input: jebInputSchemas.open_jeb_project,
+    }),
+    z.strictObject({
+        operation: z.literal("list_jeb_units"),
+        input: jebInputSchemas.list_jeb_units,
+    }),
+    z.strictObject({
+        operation: z.literal("decompile_jeb_item"),
+        input: jebInputSchemas.decompile_jeb_item,
+    }),
+]);
+const engine = z.strictObject({
+    name: z.string().min(1),
+    version: z.string().nullable(),
+    endpoint: z.string().min(1),
+    gui_client: z.boolean().nullable(),
+});
+const unit = z.strictObject({
+    unit_path: z.string(),
+    unit_type: z.string(),
+});
+/** Portable JEB observations with explicit identity and coverage limitations. */
+export const jebResultSchemas = {
+    inspect_jeb_client: z.strictObject({
+        engine,
+        startup_ts: z.number().int().nonnegative().nullable(),
+        message: z.string().nullable(),
+    }),
+    open_jeb_project: z.strictObject({
+        engine,
+        project_name: z.string().nullable(),
+        creation_datetime: z.string().nullable(),
+        input_files: z.array(z.strictObject({
+            file_name: z.string(),
+            file_size: z.number().int().nonnegative(),
+            contents_sha256_hash: z.string(),
+        })),
+        units: z.array(unit),
+    }),
+    list_jeb_units: z.strictObject({
+        engine,
+        filter: z.string().nullable(),
+        parent_unit_path: z.string().nullable(),
+        index: z.number().int().nonnegative(),
+        count: z.number().int().positive(),
+        units: z.array(unit),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    decompile_jeb_item: z.strictObject({
+        engine,
+        unit_path: z.string().nullable(),
+        item_address: z.string(),
+        item_kind: z.enum(["type", "method"]),
+        text: z.string(),
+    }),
+};

package/dist/domain/jsonShape.js

@@ -23,6 +23,7 @@ export const jsonShapeSchema = z.object({
         observations: z.number().int().min(1),
     })),
 });
+const arrayElementKey = Symbol("array-element");
 /** Parse approved JSON and immediately discard values after iterative shape inference. */
 export const inferJsonShape = (text) => {
     let root;
@@ -34,8 +35,31 @@ export const inferJsonShape = (text) => {
         void cause;
         return null;
     }
-    const properties = new Map();
-    const pending = [{ value: root, path: [], depth: 0 }];
+    const rootShape = {
+        path: [],
+        types: new Set(),
+        observations: 0,
+    };
+    // Each structural path owns one accumulator, shared by all matching array rows.
+    const childShape = (parent, key) => {
+        const children = (parent.children ??= new Map());
+        const existing = children.get(key);
+        if (existing !== undefined)
+            return existing;
+        const node = {
+            path: [
+                ...parent.path,
+                typeof key === "string"
+                    ? { kind: "property", name: key }
+                    : { kind: "array-element" },
+            ],
+            types: new Set(),
+            observations: 0,
+        };
+        children.set(key, node);
+        return node;
+    };
+    const pending = [{ value: root, shape: rootShape }];
     let nodeCount = 0;
     let maxDepthObserved = 0;
     while (pending.length > 0) {
@@ -43,29 +67,15 @@ export const inferJsonShape = (text) => {
         if (current === undefined)
             break;
         nodeCount += 1;
-        maxDepthObserved = Math.max(maxDepthObserved, current.depth);
-        if (current.path.length > 0) {
-            const key = JSON.stringify(current.path);
-            const type = jsonValueType(current.value);
-            const existing = properties.get(key);
-            if (existing === undefined)
-                properties.set(key, {
-                    path: current.path,
-                    types: new Set([type]),
-                    observations: 1,
-                });
-            else {
-                existing.types.add(type);
-                existing.observations += 1;
-            }
-        }
+        maxDepthObserved = Math.max(maxDepthObserved, current.shape.path.length);
+        current.shape.types.add(jsonValueType(current.value));
+        current.shape.observations += 1;
         if (Array.isArray(current.value)) {
+            if (current.value.length === 0)
+                continue;
+            const shape = childShape(current.shape, arrayElementKey);
             for (let index = current.value.length - 1; index >= 0; index -= 1)
-                pending.push({
-                    value: current.value[index],
-                    path: [...current.path, { kind: "array-element" }],
-                    depth: current.depth + 1,
-                });
+                pending.push({ value: current.value[index], shape });
             continue;
         }
         if (!isRecord(current.value))
@@ -76,25 +86,31 @@ export const inferJsonShape = (text) => {
             if (entry === undefined)
                 continue;
             const [name, value] = entry;
-            const path = [
-                ...current.path,
-                { kind: "property", name },
-            ];
-            pending.push({ value, path, depth: current.depth + 1 });
+            pending.push({ value, shape: childShape(current.shape, name) });
         }
     }
-    return jsonShapeSchema.parse({
+    // Preorder over sorted siblings gives canonical paths without repeatedly
+    // comparing their shared prefixes. Each returned path owns its segments.
+    const properties = [];
+    const shapes = orderedChildren(rootShape);
+    while (shapes.length > 0) {
+        const shape = shapes.pop();
+        if (shape === undefined)
+            break;
+        properties.push({
+            path: shape.path.map((segment) => ({ ...segment })),
+            types: [...shape.types].sort(),
+            observations: shape.observations,
+        });
+        for (const child of orderedChildren(shape))
+            shapes.push(child);
+    }
+    return {
         root_type: jsonValueType(root),
         node_count: nodeCount,
         max_depth_observed: maxDepthObserved,
-        properties: [...properties.values()]
-            .map((value) => ({
-            path: value.path,
-            types: [...value.types].sort(),
-            observations: value.observations,
-        }))
-            .sort((left, right) => compareShapePaths(left.path, right.path)),
-    });
+        properties,
+    };
 };
 const jsonValueType = (value) => {
     if (value === null)
@@ -113,18 +129,13 @@ const jsonValueType = (value) => {
     }
 };
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const compareShapePaths = (left, right) => {
-    for (let index = 0; index < Math.min(left.length, right.length); index += 1) {
-        const a = left[index];
-        const b = right[index];
-        if (a === undefined || b === undefined)
-            break;
-        const order = compareUnicodeCodePoints(a.kind, b.kind) ||
-            (a.kind === "property" && b.kind === "property"
-                ? compareUnicodeCodePoints(a.name, b.name)
-                : 0);
-        if (order !== 0)
-            return order;
-    }
-    return left.length - right.length;
-};
+/** Reverse sibling order for the traversal stack; array elements sort first. */
+const orderedChildren = (node) => [...(node.children ?? [])]
+    .sort(([left], [right]) => left === right
+    ? 0
+    : left === arrayElementKey
+        ? 1
+        : right === arrayElementKey
+            ? -1
+            : compareUnicodeCodePoints(right, left))
+    .map(([, child]) => child);

package/dist/domain/jsonValue.js

@@ -64,6 +64,9 @@ export function* jsonValueValidationSteps(root) {
     return finish(undefined);
 }
 const preserveJsonValue = (value) => {
+    const immutableCandidate = value;
+    if (isImmutableJsonSnapshot(immutableCandidate))
+        return value;
     if (Array.isArray(value))
         return value.map(preserveJsonValue);
     if (value !== null && typeof value === "object")