rea-agents 6.3.0 → 6.4.0

package/dist/domain/javascript/javascriptSemanticMemberMutations.js

@@ -2,23 +2,23 @@ import * as t from "@babel/types";
 import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
 import { clearSemanticPrimitiveBindingValues, evaluateSemanticBinding, evaluateSemanticExpression, } from "./javascriptSemanticValues.js";
 import { semanticContainer, semanticSlotAtPath, } from "./javascriptSemanticSlots.js";
+import { semanticClassCandidates, semanticClassPropertyReferences, semanticObjectPropertyReferences, } from "./javascriptSemanticObjectReferences.js";
 import { semanticIterationSources } from "./javascriptSemanticIterationSources.js";
+import { semanticCallableResultExpressions } from "./javascriptSemanticCallableResults.js";
+import { createSemanticReturnedReferences } from "./javascriptSemanticReturnedReferences.js";
 import { semanticMutationInitializers } from "./javascriptSemanticMutationInitializers.js";
-import { semanticArrayIndex, semanticPropertyPathKeyMatches, } from "./javascriptSemanticPropertyPaths.js";
+import { semanticArrayIndex, SemanticPropertyPathCoverage, semanticPropertyPathKeyMatches, } from "./javascriptSemanticPropertyPaths.js";
 import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
-import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
-import { semanticStaticPropertyKey, unwrapJavaScriptExpression, } from "./javascriptAstValues.js";
-/** Preserve uncertainty from property writes and references exposed to calls. */
-export const collectSemanticMemberMutations = (program, state) => {
+import { traverseJavaScriptAstSteps } from "./javascriptSemanticTraversal.js";
+import { semanticStaticPropertyKey, semanticMemberWriteTargets, unwrapJavaScriptExpression, } from "./javascriptAstValues.js";
+/** Preserve uncertainty from property writes and references exposed to calls, yielding during traversal and fixpoint iteration. */
+export function* collectSemanticMemberMutationsSteps(program, state) {
     const parents = state.parentsByNode;
-    traverseJavaScriptAst(program, {
-        enter: (node, parent) => {
-            if (parent !== null)
-                parents.set(node, parent);
-        },
-    });
+    const normalizePath = observableMutationPaths(state);
+    const returnedReferences = createSemanticReturnedReferences(state);
     const recordedEffects = new Set();
     const selections = new Map();
+    const coveringPaths = new Map();
     let arrayIterationUnknown = false;
     const pendingReferences = [];
     const iterableReferences = [];
@@ -55,8 +55,10 @@ export const collectSemanticMemberMutations = (program, state) => {
     };
     const markValue = (node, path, bindings, effect = "write", mutation, originAt = mutation) => {
         const pending = [{ node, path, bindings, originAt }];
-        while (pending.length > 0) {
-            const current = pending.pop();
+        // Visit shallower alias traversals first so their exact prefixes suppress
+        // longer loop paths before those paths enumerate every assignment order.
+        for (let cursor = 0; cursor < pending.length; cursor++) {
+            const current = pending[cursor];
             if (current === undefined)
                 break;
             const expression = unwrapJavaScriptExpression(current.node).node;
@@ -72,18 +74,24 @@ export const collectSemanticMemberMutations = (program, state) => {
                     continue;
                 }
                 // An alias restored from a saved reference can revisit the same binding
-                // at an earlier capture. Only a repeated lifetime closes a cycle.
+                // at an earlier capture or a shorter getter-receiver path. Only a
+                // repeated capture and path closes a cycle.
                 const lifetime = JSON.stringify([
                     binding.bindingId,
                     current.originAt?.start,
                     current.originAt?.end,
+                    current.path,
                 ]);
                 if (current.bindings.has(lifetime))
                     continue;
                 // Union compatible copied-slot selections at each binding. Carrying every
                 // combination of exclusions through branch diamonds is exponential.
-                const selectorIndex = current.path.findIndex((key) => key !== null && typeof key === "object");
-                let path = current.path;
+                // Preserve paths that can change observed slots or Array prototype
+                // effects; canonicalize suffixes that cannot distinguish lattice facts.
+                let path = normalizePath(binding.bindingId, current.path, effect);
+                if (path === null)
+                    continue;
+                const selectorIndex = path.findIndex((key) => key !== null && typeof key === "object");
                 const selector = path[selectorIndex];
                 if (selector !== null && typeof selector === "object") {
                     const selectionIdentity = JSON.stringify([
@@ -106,6 +114,26 @@ export const collectSemanticMemberMutations = (program, state) => {
                     selections.set(selectionIdentity, excludedKeys);
                     path = path.map((key, index) => index === selectorIndex ? { ...selector, excludedKeys } : key);
                 }
+                // Keep an antichain of exact paths. Widening distinct member keys would
+                // also invalidate unrelated siblings that never reach this effect.
+                const pathState = JSON.stringify([
+                    binding.bindingId,
+                    effect,
+                    // Short writes stop at owned literal slots, whereas longer writes
+                    // reach shared children. Only equal-depth writes cover one another.
+                    effect === "write" ? path.length : null,
+                    mutation?.start,
+                    mutation?.end,
+                    current.originAt?.start,
+                    current.originAt?.end,
+                ]);
+                let covering = coveringPaths.get(pathState);
+                if (covering === undefined) {
+                    covering = new SemanticPropertyPathCoverage();
+                    coveringPaths.set(pathState, covering);
+                }
+                if (!covering.retain(path))
+                    continue;
                 const identity = JSON.stringify([
                     binding.bindingId,
                     effect,
@@ -117,7 +145,10 @@ export const collectSemanticMemberMutations = (program, state) => {
                 ]);
                 if (recordedEffects.has(identity))
                     continue;
-                const value = effect === "write"
+                // A recorded write invalidates the binding to a non-primitive value, so
+                // only its first write can target a primitive. Re-evaluating it would
+                // replay every earlier write and make repeated writes superlinear.
+                const value = effect === "write" && binding.mutatedPaths.length === 0
                     ? evaluateSemanticBinding(binding, state)
                     : undefined;
                 const primitiveWrite = value?.status === "literal" || value?.status === "union";
@@ -167,13 +198,9 @@ export const collectSemanticMemberMutations = (program, state) => {
                 });
             }
             else {
-                if (t.isArrayExpression(expression) &&
-                    ((current.path[0] === "__proto__" &&
-                        (effect === "escape" || current.path.length > 1)) ||
-                        (current.path[0] === "constructor" &&
-                            current.path[1] === "prototype")))
-                    arrayIterationUnknown = true;
-                for (const value of referencedValues(expression, current.path, effect)) {
+                for (const value of effect === "escape"
+                    ? escapedReferenceLeaves(expression, current.path)
+                    : expandedValues(expression, current.path, effect)) {
                     if (value.iterableFallbackPath !== undefined)
                         deferIterable({
                             node: value.node,
@@ -196,6 +223,71 @@ export const collectSemanticMemberMutations = (program, state) => {
         }
     };
     const markEscaped = (node, mutation, path = []) => markValue(node, path, new Set(), "escape", mutation);
+    function expandedValues(expression, path, effect) {
+        if (t.isArrayExpression(expression) &&
+            ((path[0] === "__proto__" && (effect === "escape" || path.length > 1)) ||
+                (path[0] === "constructor" && path[1] === "prototype")))
+            arrayIterationUnknown = true;
+        return referencedValues(expression, path, effect, state);
+    }
+    // Expanding a value below its references depends only on syntax, not on the
+    // escape site. Escaping an object reaches every method's results, so
+    // re-expanding it at each call through that object made N calls over N
+    // methods quadratic. Identifiers that resolve to the same binding and path
+    // are processed identically, so one stands for all of them.
+    const escapedLeaves = new WeakMap();
+    function escapedReferenceLeaves(root, rootPath) {
+        // Parser recovery can leave an argument hole, which expands to nothing.
+        if (!t.isNode(root))
+            return [];
+        const rootKey = JSON.stringify(rootPath);
+        const cached = escapedLeaves.get(root)?.get(rootKey);
+        if (cached !== undefined)
+            return cached;
+        const leaves = [];
+        const leafIdentities = new Set();
+        const expanded = new WeakMap();
+        const pending = [...expandedValues(root, rootPath, "escape")];
+        for (let cursor = 0; cursor < pending.length; cursor++) {
+            const value = pending[cursor];
+            if (value === undefined)
+                break;
+            const node = unwrapJavaScriptExpression(value.node).node;
+            if (!t.isNode(node))
+                continue;
+            const pathKey = JSON.stringify(value.path);
+            if (t.isIdentifier(node) && value.iterableFallbackPath === undefined) {
+                const binding = resolveSemanticBindingState(state, node, node.name);
+                const identity = JSON.stringify([
+                    binding === undefined ? null : binding.bindingId,
+                    binding === undefined ? node.name : null,
+                    pathKey,
+                ]);
+                if (leafIdentities.has(identity))
+                    continue;
+                leafIdentities.add(identity);
+                leaves.push(value);
+            }
+            else if (value.iterableFallbackPath !== undefined ||
+                t.isIdentifier(node) ||
+                t.isMemberExpression(node) ||
+                t.isOptionalMemberExpression(node))
+                leaves.push(value);
+            else {
+                const paths = expanded.get(node) ?? new Set();
+                if (paths.has(pathKey))
+                    continue;
+                paths.add(pathKey);
+                expanded.set(node, paths);
+                for (const reference of expandedValues(node, value.path, "escape"))
+                    pending.push(reference);
+            }
+        }
+        const byPath = escapedLeaves.get(root) ?? new Map();
+        byPath.set(rootKey, leaves);
+        escapedLeaves.set(root, byPath);
+        return leaves;
+    }
     const markReceiver = (callee, mutation) => {
         const expression = unwrapJavaScriptExpression(callee).node;
         if (t.isMemberExpression(expression) ||
@@ -203,23 +295,10 @@ export const collectSemanticMemberMutations = (program, state) => {
             markEscaped(expression.object, mutation);
     };
     const markTarget = (node, mutation) => {
-        if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
-            markValue(node.object, [semanticStaticPropertyKey(node.property, node.computed)], new Set(), "write", mutation);
-        else if (t.isRestElement(node))
-            markTarget(node.argument, mutation);
-        else if (t.isAssignmentPattern(node))
-            markTarget(node.left, mutation);
-        else if (t.isArrayPattern(node)) {
-            for (const element of node.elements)
-                if (element !== null)
-                    markTarget(element, mutation);
-        }
-        else if (t.isObjectPattern(node)) {
-            for (const property of node.properties)
-                markTarget(t.isRestElement(property) ? property.argument : property.value, mutation);
-        }
+        for (const target of semanticMemberWriteTargets(node))
+            markValue(target.object, [semanticStaticPropertyKey(target.property, target.computed)], new Set(), "write", mutation);
     };
-    traverseJavaScriptAst(program, {
+    yield* traverseJavaScriptAstSteps(program, {
         enter: (node, parent) => {
             for (const source of semanticIterationSources(node, parent))
                 deferIterable({
@@ -229,7 +308,7 @@ export const collectSemanticMemberMutations = (program, state) => {
                     bindings: new Set(),
                     effect: "escape",
                     originAt: source.mutation,
-                    iterationOnly: true,
+                    iterationOnly: source.kind === "iteration",
                 });
             if (t.isAssignmentExpression(node))
                 markTarget(node.left, node);
@@ -242,6 +321,8 @@ export const collectSemanticMemberMutations = (program, state) => {
             else if (t.isCallExpression(node) ||
                 t.isOptionalCallExpression(node) ||
                 t.isNewExpression(node)) {
+                for (const source of returnedReferences(node.callee))
+                    markEscaped(source.node, node, source.projection);
                 for (const argument of node.arguments)
                     if (t.isSpreadElement(argument))
                         deferIterable({
@@ -273,10 +354,25 @@ export const collectSemanticMemberMutations = (program, state) => {
         const effectsBefore = recordedEffects.size;
         const iterablesBefore = iterableReferences.length;
         const iterationBefore = arrayIterationUnknown;
-        for (const reference of pendingReferences.splice(0)) {
+        for (const [index, reference] of pendingReferences.splice(0).entries()) {
+            if (index % 64 === 0)
+                yield;
             const { initializer } = reference;
             if (referenceSourcesInactive(initializer, state))
                 pendingReferences.push(reference);
+            else if (t.isForOfStatement(initializer.node))
+                deferIterable({
+                    node: initializer.node.right,
+                    projection: [],
+                    path: [null, ...reference.path],
+                    fallbackPath: [],
+                    bindings: reference.bindings,
+                    effect: reference.effect,
+                    originAt: initializer.node,
+                    ...(reference.mutation === undefined
+                        ? {}
+                        : { mutation: reference.mutation }),
+                });
             else if (initializer.copyKind === "array-rest" &&
                 initializer.copyProjectionOffset !== undefined) {
                 const offset = initializer.copyProjectionOffset;
@@ -297,7 +393,9 @@ export const collectSemanticMemberMutations = (program, state) => {
             else
                 markValue(initializer.node, reference.path, reference.bindings, reference.effect, reference.mutation, reference.originAt);
         }
-        for (const reference of [...iterableReferences]) {
+        for (const [index, reference] of [...iterableReferences].entries()) {
+            if (index % 64 === 0)
+                yield;
             if (referenceSourcesInactive(reference, state))
                 continue;
             if (reference.iterationOnly) {
@@ -326,7 +424,7 @@ export const collectSemanticMemberMutations = (program, state) => {
     // Gathering effects can evaluate a primitive projection before its object
     // escapes. Final values must use the completed mutation state.
     clearSemanticPrimitiveBindingValues(state);
-};
+}
 const referenceSourcesInactive = (reference, state) => reference.requiredSources?.some((source) => selectedReferenceSlot(source, state, source.node)?.presence === "absent") === true ||
     reference.fallbackSources?.some((source) => {
         // Selection precedes effects through the chosen reference. A later escape
@@ -381,15 +479,35 @@ const expandedIterationReferences = (reference, state) => {
         };
     });
 };
-const referencedValues = (node, path, effect) => {
+const referencedValues = (node, path, effect, state) => {
+    if (effect === "escape" && t.isFunction(node))
+        return semanticCallableResultExpressions(node).flatMap(({ node, delegated }) => node === null ? [] : [{ node, path: delegated ? [null] : [] }]);
     // An initializer owns its slots; only deeper writes can affect shared children.
     if (t.isObjectExpression(node) || t.isArrayExpression(node)) {
         if (effect === "write" && path.length < 2)
             return [];
         return t.isObjectExpression(node)
-            ? objectReferencedValues(node, path)
+            ? semanticObjectPropertyReferences(node, path, state)
             : arrayReferencedValues(node, path);
     }
+    if (t.isClass(node)) {
+        const [key, ...remaining] = path;
+        if (key === undefined)
+            return [];
+        // Replacing or deleting the getter's property does not use the value it
+        // would return. Only a deeper path can mutate the returned object.
+        if (effect === "write" && remaining.length === 0)
+            return [];
+        return semanticClassPropertyReferences({ owner: node, kind: "static" }, [key, ...remaining], state);
+    }
+    if (t.isNewExpression(node)) {
+        const [key, ...remaining] = path;
+        if (key === undefined)
+            return [];
+        if (effect === "write" && remaining.length === 0)
+            return [];
+        return semanticClassCandidates(node.callee, state).flatMap((klass) => semanticClassPropertyReferences({ owner: klass, kind: "instance" }, [key, ...remaining], state));
+    }
     if (t.isAssignmentExpression(node))
         return node.operator === "||=" || node.operator === "??="
             ? [
@@ -415,50 +533,186 @@ const referencedValues = (node, path, effect) => {
         ];
     return [];
 };
-const objectReferencedValues = (node, path) => {
-    const [key, ...remaining] = path;
-    const references = [];
-    const overwritten = new Set();
-    for (const property of [...node.properties].reverse()) {
-        if (t.isSpreadElement(property)) {
-            const selected = key ?? null;
-            if (typeof selected !== "object" && overwritten.has(String(selected)))
-                continue;
-            references.push({
-                node: property.argument,
-                path: [
-                    typeof selected === "object"
-                        ? {
-                            ...selected,
-                            excludedKeys: [
-                                ...new Set([
-                                    ...(selected?.excludedKeys ?? []),
-                                    ...overwritten,
-                                ]),
-                            ].sort(compareUnicodeCodePoints),
-                        }
-                        : selected,
-                    ...remaining,
-                ],
-            });
-            continue;
+const observableMutationPaths = (state) => {
+    const bindingNodes = new Map();
+    const expressions = new WeakMap();
+    const pendingExpressions = [];
+    const pending = [];
+    const queued = new Set();
+    const schedule = (node) => {
+        if (queued.has(node))
+            return;
+        queued.add(node);
+        pending.push(node);
+    };
+    const create = (read) => 
+    // Most bindings have no object origin or property projection. Materialize
+    // each collection only when it contains a fact or relationship.
+    read === undefined ? {} : { read };
+    const link = (source, target) => {
+        if (target.sources?.has(source) === true)
+            return;
+        (target.sources ??= new Set()).add(source);
+        (source.dependents ??= new Set()).add(target);
+        schedule(target);
+    };
+    const expressionNode = (node) => {
+        const expression = unwrapJavaScriptExpression(node).node;
+        const existing = expressions.get(expression);
+        if (existing !== undefined)
+            return existing;
+        const observer = create();
+        expressions.set(expression, observer);
+        pendingExpressions.push({ expression, observer });
+        return observer;
+    };
+    const project = (source, path) => {
+        let observer = source;
+        for (const key of path) {
+            const identity = JSON.stringify(key === null || typeof key === "object" ? key : String(key));
+            let selected = observer.projections?.get(identity);
+            if (selected === undefined) {
+                selected = create({ source: observer, key });
+                (observer.projections ??= new Map()).set(identity, selected);
+                (observer.dependents ??= new Set()).add(selected);
+                schedule(selected);
+            }
+            observer = selected;
         }
-        const name = semanticStaticPropertyKey(property.key, property.computed);
-        if (name !== null && overwritten.has(name))
+        return observer;
+    };
+    for (const binding of state.bindingsById.values())
+        bindingNodes.set(binding.bindingId, create());
+    for (const binding of state.bindingsById.values()) {
+        const observer = bindingNodes.get(binding.bindingId);
+        if (observer === undefined)
             continue;
-        if (t.isObjectProperty(property) &&
-            (name === null || semanticPropertyPathKeyMatches(key ?? null, name)))
-            references.push({ node: property.value, path: remaining });
-        // A prototype setter does not replace an own property from a spread.
-        if (name !== null &&
-            !(t.isObjectMethod(property) && property.kind !== "method") &&
-            !(t.isObjectProperty(property) &&
-                !property.computed &&
-                !property.shorthand &&
-                name === "__proto__"))
-            overwritten.add(name);
+        for (const initializer of binding.initializers) {
+            const expression = unwrapJavaScriptExpression(initializer.node).node;
+            // Preserve member paths through class values and local instances so
+            // getter-result aliases can be resolved at the accessor boundary.
+            if (t.isClass(expression) || t.isNewExpression(expression))
+                (observer.origins ??= new Set()).add("opaque");
+            link(project(expressionNode(initializer.node), initializer.projection), observer);
+        }
+        // Preserve exact paths where copies, defaults or iteration need their
+        // reference-specific projections; an opaque origin prevents pruning.
+        if (binding.referenceInitializers.length > 0)
+            (observer.origins ??= new Set()).add("opaque");
+        for (const initializer of binding.referenceInitializers) {
+            for (const source of [
+                initializer,
+                ...(initializer.requiredSources ?? []),
+                ...(initializer.fallbackSources ?? []),
+            ])
+                link(expressionNode(source.node), observer);
+        }
     }
-    return references;
+    const settle = () => {
+        while (pendingExpressions.length > 0 || pending.length > 0) {
+            while (pendingExpressions.length > 0) {
+                const selected = pendingExpressions.pop();
+                if (selected === undefined)
+                    break;
+                const { expression, observer } = selected;
+                if (t.isObjectExpression(expression) || t.isArrayExpression(expression))
+                    (observer.origins ??= new Set()).add(expression);
+                else if (t.isIdentifier(expression)) {
+                    const binding = resolveSemanticBindingState(state, expression, expression.name);
+                    if (binding !== undefined) {
+                        const origin = bindingNodes.get(binding.bindingId);
+                        if (origin !== undefined)
+                            link(origin, observer);
+                    }
+                    else if (expression.name === "Array")
+                        (observer.origins ??= new Set()).add("array");
+                    else if (["globalThis", "global", "window", "self"].includes(expression.name))
+                        (observer.origins ??= new Set()).add("ambient");
+                }
+                else if (t.isMemberExpression(expression) ||
+                    t.isOptionalMemberExpression(expression))
+                    link(project(expressionNode(expression.object), [
+                        semanticStaticPropertyKey(expression.property, expression.computed),
+                    ]), observer);
+                else
+                    for (const reference of referencedValues(expression, [], "escape", state))
+                        link(project(expressionNode(reference.node), reference.path), observer);
+                schedule(observer);
+            }
+            const observer = pending.pop();
+            if (observer === undefined)
+                continue;
+            queued.delete(observer);
+            let changed = false;
+            const add = (origin) => {
+                if (observer.origins?.has(origin) === true)
+                    return;
+                (observer.origins ??= new Set()).add(origin);
+                changed = true;
+            };
+            for (const source of observer.sources ?? [])
+                for (const origin of source.origins ?? [])
+                    add(origin);
+            if (observer.read !== undefined) {
+                const { source, key } = observer.read;
+                if (key === null || typeof key === "object") {
+                    // Dynamic keys and copied-slot masks retain their original paths.
+                    // Enumerating their exclusion combinations would recreate the growth
+                    // that the mutation collector's selection union already prevents.
+                    if ((source.origins?.size ?? 0) > 0)
+                        add("opaque");
+                }
+                else
+                    for (const origin of source.origins ?? []) {
+                        if (typeof origin === "string") {
+                            if (origin === "array-prototype" || origin === "opaque")
+                                add(origin);
+                            else if (origin === "ambient" &&
+                                semanticPropertyPathKeyMatches(key, "Array"))
+                                add("array");
+                            else if (origin === "array" &&
+                                semanticPropertyPathKeyMatches(key, "prototype"))
+                                add("array-prototype");
+                        }
+                        else {
+                            for (const reference of referencedValues(origin, [key], "escape", state)) {
+                                link(project(expressionNode(reference.node), reference.path), observer);
+                                if (reference.iterableFallbackPath !== undefined)
+                                    link(project(expressionNode(reference.node), reference.iterableFallbackPath), observer);
+                            }
+                        }
+                    }
+            }
+            if (changed)
+                for (const dependent of observer.dependents ?? [])
+                    schedule(dependent);
+        }
+    };
+    settle();
+    return (bindingId, path, effect) => {
+        let observer = bindingNodes.get(bindingId);
+        if (observer === undefined)
+            return path;
+        if (path.some((key) => key !== null && typeof key === "object"))
+            return path;
+        if (effect === "escape") {
+            observer = project(observer, path);
+            settle();
+            return (observer.origins?.size ?? 0) === 0 ? null : path;
+        }
+        if ((observer.origins?.size ?? 0) === 0)
+            return path.length === 0 ? path : [null];
+        for (let offset = 0; offset < path.length; offset++) {
+            const key = path[offset];
+            if (key === undefined)
+                break;
+            observer = project(observer, [key]);
+            settle();
+            if ((observer.origins?.size ?? 0) === 0 && offset + 1 < path.length)
+                return [...path.slice(0, offset + 1), null];
+        }
+        return path;
+    };
 };
 const arrayReferencedValues = (node, path) => {
     const [key, ...remaining] = path;