@geastack/compiler 1.0.15

package/dist/semantics/normalize/flow/component-solver.js

@@ -0,0 +1,587 @@
+/**
+ * Solve a lazily discovered dependency graph. `all-dependencies` admits a
+ * recursive component when every member has complete local facts and every
+ * dependency outside it is complete. `seeded-origin` preserves the legacy
+ * seed rule. `grounding-domains` enforces only domains required by members of
+ * a cycle and propagates witnesses over explicitly labelled dependency edges.
+ * An acyclic unseeded node remains a complete, vacuous answer.
+ */
+export const dependencyComponentSolver = (expand, mode) => {
+    const nodes = new Map();
+    // No `groundedDomains` here. It is a pure function of the expanded graph
+    // (`groundingDomainsFrom`, memoized by key), never of how components closed,
+    // so storing it per node only meant computing it for every node of every
+    // component -- the whole value-origin subgraph walked ~115,000 times on
+    // the three.js app -- when the only places it can change an answer are a cyclic
+    // component's requirement check and the published result of a node someone
+    // actually asks about.
+    const results = new Map();
+    const componentOf = new Map();
+    const nodeOf = (key) => {
+        let node = nodes.get(key);
+        if (node === undefined) {
+            node = expand(key);
+            nodes.set(key, node);
+            // Checked here, once per node, rather than inside the grounding walk.
+            // There it was `dependencies.includes(...)` per grounding edge, so a node
+            // carrying g grounding edges over d required ones paid g*d comparisons --
+            // and paid them again for every root whose walk reached it. One Set of
+            // the node's own dependencies answers all g in O(d + g), and moving the
+            // check to expansion makes it cover EVERY node the solver sees instead of
+            // only the ones some grounding walk happened to reach.
+            const grounding = node.groundingDependencies;
+            if (grounding !== undefined && grounding.length > 0) {
+                const declared = new Set(node.dependencies);
+                for (const edge of grounding)
+                    if (!declared.has(edge.dependency))
+                        throw new Error('grounding dependency must also be a closure dependency');
+            }
+        }
+        return node;
+    };
+    /**
+     * Grounding walks only the domain-labelled subgraph, never all closure edges.
+     *
+     * One walk, labelled by the domain of the edge it arrived on -- not a walk to
+     * collect the domain universe followed by a per-domain walk to search it. The
+     * collecting walk visited every node reachable over ANY grounding edge and
+     * could not stop early, because its purpose was to enumerate; the searching
+     * walk stops at the first witness. In this compiler there is exactly one
+     * domain (`source-value-session.ts`'s `VALUE_ORIGIN`), so the enumeration
+     * pass was a full traversal of the value-origin subgraph -- repeated for
+     * every node of every component -- to rediscover the single domain the
+     * search was about to walk anyway.
+     *
+     * Dropping it is answer-preserving, not an approximation. A domain can only
+     * enter the result by being witnessed on a path of its OWN edges from the
+     * root, so the domains the enumeration pass added from a node's
+     * `groundingRequirements`, or from an edge of some other domain, could never
+     * survive the search: the search would walk no edge of such a domain out of
+     * the root and would find nothing but the root's own seeds -- which are
+     * admitted here unconditionally, before any edge is walked.
+     */
+    const NO_DOMAINS = new Set();
+    const groundingCache = new Map();
+    const groundingDomainsFrom = (root) => {
+        const known = groundingCache.get(root);
+        if (known !== undefined)
+            return known;
+        const rootNode = nodeOf(root);
+        // A node that neither witnesses a domain nor labels an edge with one can
+        // only ever answer the empty set, and that is most of them: `seeded-origin`
+        // clients (`seeded-origins.ts`) never set a grounding field at all, and a
+        // solver is built per query there. Answering without allocating a walk is
+        // what keeps this off that path entirely.
+        if (!rootNode.groundingSeeds?.length && !rootNode.groundingDependencies?.length) {
+            groundingCache.set(root, NO_DOMAINS);
+            return NO_DOMAINS;
+        }
+        const found = new Set(rootNode.groundingSeeds ?? []);
+        const seen = new Map();
+        const frontier = [];
+        const follow = (node, domain) => {
+            for (const edge of node.groundingDependencies ?? [])
+                if (domain === null || edge.domain === domain)
+                    frontier.push({ key: edge.dependency, domain: edge.domain });
+        };
+        follow(rootNode, null);
+        for (let cursor = 0; cursor < frontier.length; cursor++) {
+            const { key, domain } = frontier[cursor];
+            if (found.has(domain))
+                continue;
+            let visited = seen.get(domain);
+            if (visited === undefined)
+                seen.set(domain, (visited = new Set()));
+            if (visited.has(key))
+                continue;
+            visited.add(key);
+            const node = nodeOf(key);
+            if (node.groundingSeeds?.includes(domain)) {
+                found.add(domain);
+                continue;
+            }
+            follow(node, domain);
+        }
+        groundingCache.set(root, found);
+        return found;
+    };
+    const explainFrom = (root) => {
+        const paths = new Map([[root, [root]]]);
+        const queue = [root];
+        const emittedOpaque = new Map();
+        const emittedIncomplete = new Set();
+        const emittedCycles = new Set();
+        const emittedDomainCycles = new Map();
+        const causes = [];
+        for (let cursor = 0; cursor < queue.length; cursor++) {
+            const key = queue[cursor];
+            const node = nodeOf(key);
+            const path = paths.get(key);
+            const reasons = node.causes ?? [];
+            if (!node.locallyComplete && reasons.length === 0 && !emittedIncomplete.has(key)) {
+                emittedIncomplete.add(key);
+                causes.push({ kind: 'incomplete-node', root: key, path });
+            }
+            if (!node.locallyComplete) {
+                let emitted = emittedOpaque.get(key);
+                if (!emitted)
+                    emittedOpaque.set(key, (emitted = new Set()));
+                for (const cause of reasons) {
+                    if (emitted.has(cause))
+                        continue;
+                    emitted.add(cause);
+                    causes.push({ kind: 'opaque', root: key, cause, path });
+                }
+            }
+            const component = componentOf.get(key);
+            if (component?.unseededCycle && !emittedCycles.has(component)) {
+                emittedCycles.add(component);
+                causes.push({ kind: 'unseeded-cycle', members: component.members, path });
+            }
+            if (component?.unseededDomains.size) {
+                let emitted = emittedDomainCycles.get(component);
+                if (!emitted)
+                    emittedDomainCycles.set(component, (emitted = new Set()));
+                for (const domain of component.unseededDomains) {
+                    if (emitted.has(domain))
+                        continue;
+                    emitted.add(domain);
+                    causes.push({ kind: 'unseeded-cycle', domain, members: component.members, unmet: component.unmet, path });
+                }
+            }
+            for (const dependency of node.dependencies) {
+                if (paths.has(dependency))
+                    continue;
+                paths.set(dependency, [...path, dependency]);
+                queue.push(dependency);
+            }
+        }
+        return causes;
+    };
+    /**
+     * A node's published grounding, computed when someone asks for it rather than
+     * when its component closed. Same function, same memo, same answer: the walk
+     * reads only `expand`ed nodes, which never change, so when it runs cannot
+     * change what it returns. In `grounding-domains` mode the legacy aggregate
+     * flag is the domain set's emptiness, exactly as the component loop used to
+     * record it; in the other modes it stays the seed witness that loop computes.
+     *
+     * A plain object, not one with accessors. Deferring these two fields behind
+     * getters was tried and cost 4.7% of a whole compile in this one function:
+     * a result is built for every top-level query, a solver is built per query,
+     * and an object literal carrying accessors is far more expensive to create
+     * than one carrying values. The walk itself is memoized and answers the
+     * no-grounding case without allocating, which is the cheap half anyway.
+     */
+    const publish = (root, known) => {
+        const groundedDomains = groundingDomainsFrom(root);
+        return {
+            status: known.status,
+            grounded: mode === 'grounding-domains' ? groundedDomains.size > 0 : known.grounded,
+            groundedDomains,
+            explain: () => explainFrom(root)
+        };
+    };
+    return (root) => {
+        const known = results.get(root);
+        if (known !== undefined)
+            return publish(root, known);
+        const indices = new Map();
+        const low = new Map();
+        const stack = [];
+        const active = new Set();
+        let next = 0;
+        // The low-link is kept in a local for the length of the loop and written to
+        // `low` once, on the way out. Nothing reads a node's low-link while its own
+        // visit is running -- a back edge reads `indices`, and a tree edge reads the
+        // child's low-link only after that child's visit has returned -- so the
+        // read-modify-write through the map on every edge was three map operations
+        // per edge to maintain a number only this frame could see.
+        const visit = (key) => {
+            const index = next++;
+            indices.set(key, index);
+            let lowest = index;
+            stack.push(key);
+            active.add(key);
+            for (const dependency of nodeOf(key).dependencies) {
+                if (results.has(dependency))
+                    continue;
+                const seen = indices.get(dependency);
+                if (seen === undefined) {
+                    visit(dependency);
+                    const reached = low.get(dependency);
+                    if (reached < lowest)
+                        lowest = reached;
+                }
+                else if (seen < lowest && active.has(dependency))
+                    lowest = seen;
+            }
+            low.set(key, lowest);
+            if (lowest !== index)
+                return;
+            const members = [];
+            let member;
+            do {
+                member = stack.pop();
+                active.delete(member);
+                members.push(member);
+            } while (member !== key);
+            // A singleton component's only member is `key` itself, so membership is
+            // an identity test. Most components are singletons, and building a Set to
+            // ask one question about one element is the allocation that shows up.
+            const memberSet = members.length === 1 ? null : new Set(members);
+            let complete = true;
+            let grounded = false;
+            let cyclic = members.length > 1;
+            const unseededDomains = new Set();
+            const unmet = [];
+            for (const current of members) {
+                const node = nodeOf(current);
+                complete &&= node.locallyComplete;
+                grounded ||= node.seed === true;
+                for (const dependency of node.dependencies) {
+                    if (memberSet === null ? dependency === key : memberSet.has(dependency)) {
+                        cyclic = true;
+                        continue;
+                    }
+                    const dependencyResult = results.get(dependency);
+                    complete &&= dependencyResult?.status === 'complete';
+                    grounded ||= dependencyResult?.grounded === true;
+                }
+            }
+            const unseededCycle = mode === 'seeded-origin' && complete && cyclic && !grounded;
+            if (unseededCycle)
+                complete = false;
+            // Only a cyclic component can fail a grounding requirement -- an acyclic
+            // node's requirement is discharged by the ordinary completeness rule --
+            // so this is the one place the walk has to run before an answer is
+            // published, and the members of one cycle are all it has to run for.
+            if (mode === 'grounding-domains' && complete && cyclic) {
+                for (const current of members) {
+                    const groundedForNode = groundingDomainsFrom(current);
+                    for (const domain of nodeOf(current).groundingRequirements ?? []) {
+                        if (groundedForNode.has(domain))
+                            continue;
+                        unseededDomains.add(domain);
+                        unmet.push(current);
+                    }
+                }
+                if (unseededDomains.size > 0)
+                    complete = false;
+            }
+            const component = { members, unseededCycle, unseededDomains, unmet };
+            for (const current of members) {
+                componentOf.set(current, component);
+                results.set(current, { status: complete ? 'complete' : 'refused', grounded });
+            }
+        };
+        visit(root);
+        return publish(root, results.get(root));
+    };
+};
+export const dependencyFactSolver = (expand, mode) => {
+    const states = new Map();
+    // States, not keys: `propagate` used to hold keys and call `stateOf(key)`
+    // on every drain, a Map lookup per edge fire across the three.js app's 14.7M
+    // observe edges. The State is already in hand wherever an edge fires or is
+    // created, so the queue (and `dependents`, on State above) carry it
+    // directly and dedupe on State identity, which is 1:1 with key identity
+    // because `states` is the only minter.
+    const queue = [];
+    const queued = new Set();
+    let dependencyRevision = 0;
+    // Every reason a node's TRANSFER must run again is a reason its SEAL must run
+    // again: the seal is the same transfer with `sealing` set, so it reads the
+    // same dependencies and answers differently only when they do. `queue` is
+    // drained by `propagate`; this set outlives it, because a seal pass happens
+    // after the drain and needs to know what the drain touched.
+    const sealDirty = new Set();
+    const enqueue = (state) => {
+        sealDirty.add(state.key);
+        if (queued.has(state))
+            return;
+        queued.add(state);
+        queue.push(state);
+    };
+    const stateOf = (key) => {
+        let state = states.get(key);
+        if (state === undefined) {
+            const built = {
+                key,
+                definition: expand(key),
+                observedDependencies: new Map(),
+                requiredDependencies: new Set(),
+                facts: new Set(),
+                dependents: new Set(),
+                read: (dependency) => readFrom(built, dependency),
+                observe: (dependency) => observeFrom(built, dependency),
+                holdersOf: (fact) => holdersOfFrom(built, fact)
+            };
+            state = built;
+            states.set(key, state);
+            enqueue(built);
+        }
+        return state;
+    };
+    /**
+     * `seed` is exactly this, exposed: create the state (a no-op if it already
+     * exists) and let `stateOf`'s own `enqueue` schedule its first transfer.
+     * No edge is recorded anywhere -- nothing subscribes and nothing is
+     * subscribed to -- because the only purpose is to make the node exist and
+     * run, not to make anyone depend on it.
+     */
+    const seed = (key) => {
+        stateOf(key);
+    };
+    // The reverse of `observedDependencies`/`dependents`: every state that has
+    // published a given fact VALUE, and every state that has ever asked
+    // `holdersOf` about it. Global across every query kind on purpose -- a fact
+    // is a fact regardless of which kind of node published it, and the size
+    // this costs is bounded by facts actually published (three.js app: ~205,000
+    // (state, fact) pairs total), not by how many candidates asked about them
+    // (the 456,000 edges this primitive exists to avoid storing).
+    const holders = new Map();
+    const valueSubscribers = new Map();
+    const NO_HOLDERS = [];
+    const holdersOfFrom = (ownerState, fact) => {
+        let subscribers = valueSubscribers.get(fact);
+        if (subscribers === undefined)
+            valueSubscribers.set(fact, (subscribers = new Set()));
+        // Idempotent by construction (a Set), so re-asking on every re-evaluation
+        // of the same node costs a lookup and nothing else -- no revision to bump,
+        // no queue entry to make, because registering the subscription changes
+        // nothing about what THIS transfer already computed with the holders it
+        // just read below. It only matters for facts published AFTER this call,
+        // which `propagate` below wakes through this same set.
+        subscribers.add(ownerState);
+        const holding = holders.get(fact);
+        if (holding === undefined)
+            return NO_HOLDERS;
+        const found = [];
+        for (const holder of holding)
+            found.push(holder.key);
+        return found;
+    };
+    // The owner's state is handed in rather than looked up: every transfer and
+    // every seal reads its dependencies through this, so a map lookup per edge
+    // for a state the caller is already holding was, on the three.js app, a quarter of
+    // the whole compile.
+    const factsFrom = (ownerState, dependency, required) => {
+        let dependencyState = ownerState.observedDependencies.get(dependency);
+        let changed = false;
+        if (dependencyState === undefined) {
+            dependencyState = stateOf(dependency);
+            ownerState.observedDependencies.set(dependency, dependencyState);
+            dependencyState.dependents.add(ownerState);
+            dependencyRevision++;
+            changed = true;
+        }
+        if (required && !ownerState.requiredDependencies.has(dependency)) {
+            ownerState.requiredDependencies.add(dependency);
+            dependencyRevision++;
+            changed = true;
+        }
+        // A new observation may expose facts on the next pass. An upgrade also
+        // invalidates the current seal even though the fact edge already existed.
+        if (changed)
+            enqueue(ownerState);
+        // The fact set is handed over as `ReadonlySet`, not as a copy. Copying per
+        // edge read was quadratic and made three's WebGLRenderer unfinishable;
+        // copying per (node, size) fixed the time and doubled the memory, which is
+        // what put the three.js app's third solve into a 4 GB OOM. Neither is necessary:
+        // `propagate` adds a node's facts only AFTER its transfer has returned --
+        // `evaluate` builds its result eagerly and hands back a set of its own --
+        // so no reader is ever iterating a set that is being written.
+        return dependencyState.facts;
+    };
+    const readFrom = (ownerState, dependency) => factsFrom(ownerState, dependency, true);
+    const observeFrom = (ownerState, dependency) => factsFrom(ownerState, dependency, false);
+    const propagate = () => {
+        for (let cursor = 0; cursor < queue.length; cursor++) {
+            const state = queue[cursor];
+            queued.delete(state);
+            counts.transfers++;
+            if (countsEnabled && counts.transfers % 200000 === 0)
+                report();
+            for (const fact of state.definition.transfer(state.read, state.observe, state.holdersOf)) {
+                if (state.facts.has(fact))
+                    continue;
+                state.facts.add(fact);
+                // This state is now a holder of `fact` -- recorded at the exact point
+                // a fact is genuinely NEW, same as `state.facts.add` beside it, so
+                // `holders` never grows for a re-observed fact.
+                let holding = holders.get(fact);
+                if (holding === undefined)
+                    holders.set(fact, (holding = new Set()));
+                holding.add(state);
+                for (const dependent of state.dependents)
+                    enqueue(dependent);
+                // A node that asked `holdersOf(fact)` before this state held it named
+                // no `K` to depend on -- there was nothing to name -- so an ordinary
+                // dependent edge cannot wake it. This is the other half of that
+                // subscription: without it, a container whose holder shows up only
+                // after `unknown-reads` first ran would publish an incomplete answer
+                // forever and never be asked again, which is the silently-wrong
+                // result SEMANTIC-AUTHORITY ranks below a slow one.
+                const subscribers = valueSubscribers.get(fact);
+                if (subscribers !== undefined)
+                    for (const subscriber of subscribers)
+                        enqueue(subscriber);
+            }
+        }
+        queue.length = 0;
+    };
+    // Seals survive between roots. A solved node whose facts and dependencies
+    // have not moved seals to the same answer, and re-deriving it is the cost
+    // that made this solver quadratic in (top-level queries x nodes discovered):
+    // every query re-sealed the whole graph it had explored so far, so the last
+    // query of a large program paid for all of it. Only what `enqueue` marked is
+    // re-sealed, which is exactly what could have changed.
+    const sealed = new Map();
+    // `sealRevision` invalidates the hoisted component-solve memo below, so
+    // bumping it on a re-seal that reproduces the same answer throws that memo
+    // away and forces a full component rebuild for nothing -- on the three.js app every
+    // seal was doing exactly that. The grounding fields compare soundly by
+    // value: `DependencyGroundingDomain` is `string | symbol`, and a grounding
+    // edge's `dependency` is a `K`, which this solver's own contract already
+    // requires to have stable identity. `causes` is `R`, a type this solver
+    // never gives an equality contract to -- source-value-session's `Cause` is
+    // a fresh `{reason, node}` object literal built on every seal call, so
+    // `===` per element is the only sound comparison available here. That
+    // reports "changed" for a content-identical-but-freshly-allocated cause
+    // list, which only over-invalidates (safe, never wrong); the common case --
+    // a node that resolves, whose `causes` is `[]` on every seal -- still
+    // compares equal by length alone, which is where the savings are.
+    const domainsEqual = (a, b) => a.length === b.length && a.every((domain, index) => domain === b[index]);
+    const groundingEdgesEqual = (a, b) => a.length === b.length && a.every((edge, index) => edge.domain === b[index].domain && edge.dependency === b[index].dependency);
+    const causesEqual = (a, b) => a.length === b.length && a.every((cause, index) => cause === b[index]);
+    const sealChanged = (previous, next) => previous === undefined ||
+        previous.locallyComplete !== next.locallyComplete ||
+        previous.seed !== next.seed ||
+        !causesEqual(previous.causes ?? [], next.causes ?? []) ||
+        !domainsEqual(previous.groundingRequirements ?? [], next.groundingRequirements ?? []) ||
+        !domainsEqual(previous.groundingSeeds ?? [], next.groundingSeeds ?? []) ||
+        !groundingEdgesEqual(previous.groundingDependencies ?? [], next.groundingDependencies ?? []);
+    const counts = { roots: 0, transfers: 0, seals: 0, componentNodes: 0 };
+    // What the heap is actually holding, for the runs where memory is the wall
+    // rather than time. Counted only when asked for: it walks every state.
+    const sizes = () => {
+        if (process.env['GEA_SOLVER_SIZES'] === undefined)
+            return '';
+        let observed = 0;
+        let required = 0;
+        let dependents = 0;
+        let facts = 0;
+        // This solver is generic over K by design -- SEMANTIC-AUTHORITY section 3
+        // requires one solved graph, not a solver bespoke to one key shape -- so
+        // nothing outside this debug path may assume a key has a `kind`. But
+        // attributing the three.js app's 14.7M observe edges to a fix means knowing which
+        // caller's loop owns them, and the one real caller's key (`Query` in
+        // source-value-session.ts) is a `{ kind: ... }` discriminated union. This
+        // reflects into that shape defensively, only inside the
+        // GEA_SOLVER_SIZES-gated path that prints nothing in production, and
+        // falls back to a single 'unknown' bucket for any key not shaped this way.
+        const perKind = new Map();
+        for (const state of states.values()) {
+            observed += state.observedDependencies.size;
+            required += state.requiredDependencies.size;
+            dependents += state.dependents.size;
+            facts += state.facts.size;
+            const kind = state.key.kind;
+            const bucketKey = typeof kind === 'string' ? kind : 'unknown';
+            let bucket = perKind.get(bucketKey);
+            if (bucket === undefined)
+                perKind.set(bucketKey, (bucket = { states: 0, observed: 0, required: 0, facts: 0 }));
+            bucket.states++;
+            bucket.observed += state.observedDependencies.size;
+            bucket.required += state.requiredDependencies.size;
+            bucket.facts += state.facts.size;
+        }
+        const byKind = [...perKind]
+            .sort(([, a], [, b]) => b.observed - a.observed)
+            .map(([kind, kindSizes]) => `\n[SOLVER-KIND] kind=${kind} states=${kindSizes.states} observed=${kindSizes.observed} required=${kindSizes.required} facts=${kindSizes.facts}`)
+            .join('');
+        return ` observed=${observed} required=${required} dependents=${dependents} facts=${facts}${byKind}`;
+    };
+    let sealRevision = 0;
+    let componentSolve = null;
+    let componentDependencyRevision = -1;
+    let componentSealRevision = -1;
+    const countsEnabled = process.env['GEA_SOLVER_COUNTS'] !== undefined;
+    const report = () => {
+        if (!countsEnabled)
+            return;
+        console.error(`[SOLVER] roots=${counts.roots} states=${states.size} transfers=${counts.transfers} seals=${counts.seals} component-expansions=${counts.componentNodes}${sizes()}`);
+    };
+    if (countsEnabled)
+        process.on('exit', report);
+    const NO_DEPENDENCIES = [];
+    const solve = (root) => {
+        counts.roots++;
+        // Reported as it goes, not only at exit: a run that has to be killed to be
+        // observed reports nothing, which is how a 20-minute compile stayed
+        // unattributed for two profiling attempts.
+        stateOf(root);
+        // Sealing may itself discover a dependency. In that case its transfer and
+        // every affected dependent must run again before any status is published.
+        while (true) {
+            propagate();
+            const revisionBeforeSeal = dependencyRevision;
+            const dirty = [...sealDirty];
+            sealDirty.clear();
+            for (const key of dirty) {
+                const state = states.get(key);
+                if (state === undefined)
+                    continue;
+                counts.seals++;
+                if (countsEnabled && counts.seals % 200000 === 0)
+                    report();
+                const next = state.definition.seal(state.read, state.observe, state.holdersOf);
+                if (sealChanged(sealed.get(key), next))
+                    sealRevision++;
+                sealed.set(key, next);
+            }
+            if (queue.length === 0 && sealDirty.size === 0 && dependencyRevision === revisionBeforeSeal)
+                break;
+        }
+        // The component solve reads the SEALED graph, so its answer stands for
+        // exactly as long as no node's seal and no node's dependency set has moved
+        // -- and both of those are counted. Built inside this per-root call it was
+        // thrown away and rebuilt for every root, taking its `results`, `nodes` and
+        // `componentOf` caches with it: on the three.js app the graph stopped growing at the
+        // eighth root and the next twenty-two thousand each re-expanded ~470 nodes
+        // of it, 10.4M expansions of an answer that had not changed. Rebuilding on
+        // a revision rather than on every call is the same walk, done once per
+        // change instead of once per question.
+        if (componentSolve === null || componentDependencyRevision !== dependencyRevision || componentSealRevision !== sealRevision) {
+            componentSolve = dependencyComponentSolver((key) => {
+                counts.componentNodes++;
+                if (countsEnabled && counts.componentNodes % 200000 === 0)
+                    report();
+                const state = states.get(key);
+                const local = sealed.get(key);
+                if (state === undefined || local === undefined)
+                    throw new Error('unsealed dependency fact node');
+                return { ...local, dependencies: [...state.requiredDependencies] };
+            }, mode);
+            componentDependencyRevision = dependencyRevision;
+            componentSealRevision = sealRevision;
+        }
+        const result = componentSolve(root);
+        if (result.status === 'complete')
+            return {
+                status: 'complete',
+                grounded: result.grounded,
+                groundedDomains: result.groundedDomains,
+                facts: new Set(stateOf(root).facts),
+                explain: result.explain
+            };
+        return {
+            status: 'refused',
+            grounded: result.grounded,
+            groundedDomains: result.groundedDomains,
+            explain: result.explain
+        };
+    };
+    return { solve, requiredDependenciesOf: (key) => states.get(key)?.requiredDependencies ?? NO_DEPENDENCIES, seed };
+};

package/dist/semantics/normalize/flow/computed-key-set.d.ts

@@ -0,0 +1,84 @@
+import ts from 'typescript';
+import { type ValueFlowIndex } from './model.js';
+import type { PrototypeKeyQuery } from '../host-mutation-keys.js';
+import type { OriginAuthority } from './origin-authority.js';
+/**
+ * Which property keys a computed key can take, proven from closed callers.
+ *
+ * Three's `Material.setValues( values )` and `Texture.setValues( values )`
+ * store `this[ key ] = newValue` for every `key` of `for ( const key in
+ * values )`. Read as "a store under any key", that one write tells every
+ * class-family, array-cell, host-mutation and reflection census that each
+ * material and texture may have grown an arbitrary property. But `values`
+ * only ever holds the options literals the program itself writes --
+ * `new MeshPhongMaterial( { color, flatShading: true } )` through the
+ * subclass's `this.setValues( parameters )`, and RenderTarget's local
+ * `values` literal plus its named writes -- so the key is one of a finite,
+ * enumerable set of names.
+ *
+ * The answer is an UPPER bound: every key the expression can evaluate to at
+ * run time is in the set. It is proven, never assumed:
+ *
+ * - A key spelled as a string (or numeric) literal, a conditional of such,
+ *   or a binding whose every write is one of those. When the checker types
+ *   the key as a literal union, the flow proof must fall inside it.
+ * - The binding of `for ( k in o )`: every own enumerable key of every value
+ *   `o` can hold, plus the intrinsic `Object.prototype`'s -- which is why that
+ *   arm carries an `Object` protocol requirement.
+ * - The binding of `for ( k of Object.keys( o ) )` or the first parameter of
+ *   `Object.keys( o ).forEach( ( k ) => ... )`: own keys only, requiring the
+ *   intact `Object.keys` and Array protocol.
+ *
+ * What `o` can hold comes from `sourceRecordDataWritePlanOf`, the shared
+ * record-origin authority (cells, complete parameter frames, factories,
+ * storage reads). Every origin must be an object literal with static keys, no
+ * spread, no accessor and no `__proto__`; `null`/`undefined` add nothing.
+ * Then each literal's key set is closed forward: every alias it reaches --
+ * cells, and parameters through resolved calls, including every override a
+ * method call can dispatch to -- is enumerated, a NAMED write through any of
+ * them adds its name, and any computed write, `delete`, bulk merge, method
+ * call through the record (which hands it out as `this`), `arguments`
+ * exposure, or escape into storage, a return, or an unresolved callee
+ * refuses. The order of writes does not matter: the set holds every name any
+ * write can add.
+ *
+ * `GEA_KEY_SET_DEBUG=1` prints every refusal with its reason and location.
+ */
+/** @semanticCategory generic-primitive */
+export interface ComputedKeySetAuthority extends OriginAuthority {
+    /**
+     * The intrinsic an enumeration depends on is intact: `('Object', undefined)`
+     * -- `Object.prototype` carries no enumerable string key a `for-in` would
+     * walk; `('Object', 'keys')` -- the static `Object.keys` is the original;
+     * `('Array', undefined)` -- the array iteration protocol. Absent, each
+     * requirement is registered on the flow's deferred intrinsic ledger (the
+     * production path, discharged by the sealed host-mutation census); with
+     * neither, the enumeration refuses.
+     */
+    readonly intrinsicIntact?: (intrinsic: 'Object' | 'Array', member: string | undefined, location: ts.Node) => boolean;
+}
+export type ComputedKeySetVerdict = {
+    readonly kind: 'keys';
+    readonly keys: ReadonlySet<string>;
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+    readonly at: ts.Node;
+};
+/**
+ * The complete set of property keys `keyExpression` can evaluate to, with the
+ * reason and location when that set cannot be proven. See the module comment.
+ */
+export declare const computedKeySetVerdictOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, keyExpression: ts.Expression, authority: ComputedKeySetAuthority) => ComputedKeySetVerdict;
+/** `for ( k of Object.keys( o ) )` and `Object.keys( o ).forEach( ... )` read these from Array.prototype and its iterator. */
+export declare const arrayIterationKeys: PrototypeKeyQuery;
+/**
+ * The complete set of property keys `keyExpression` can evaluate to, or null
+ * when the set is open or unknown. A for-in arm registers an `Object`
+ * prototype requirement (and an `Object.keys` arm an `Object.keys` member and
+ * `Array` requirement) through `authority.intrinsicIntact`, else on the flow's
+ * deferred intrinsic ledger -- so a consumer asks this inside its own ledger
+ * capture, exactly as it does for `sourceRecordDataWritePlanOf`'s prototype
+ * obligation.
+ */
+export declare const computedKeySetOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, keyExpression: ts.Expression, authority: ComputedKeySetAuthority) => ReadonlySet<string> | null;