@geastack/compiler 1.0.15

package/dist/semantics/normalize/flow/collection-value-continuation.d.ts

@@ -0,0 +1,21 @@
+import ts from 'typescript';
+import type { ValueFlowIndex } from './model.js';
+import { type NativeCollectionProtocolPlan } from './native-collection-protocol.js';
+/** Every read from the same authenticated native map storage. */
+export declare const collectionValueContinuationsOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, publication: ts.CallExpression, value: ts.Expression, protocolClosed?: (plan: NativeCollectionProtocolPlan) => boolean) => readonly ts.Expression[] | null;
+/** Every stored value that can reach a get, independent of its runtime key.
+ * Iterable constructor payloads need their own value-flow proof. */
+export declare const collectionStoredValuesOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, read: ts.CallExpression, protocolClosed?: (plan: NativeCollectionProtocolPlan) => boolean) => readonly ts.Expression[] | null;
+/**
+ * Whether handing `reference` to this call as its KEY exposes nothing.
+ *
+ * Three's `WebGLObjects.update` keys its per-frame `updateMap` WeakMap by the
+ * drawable itself: `updateMap.get( object ) !== frame`, then
+ * `updateMap.set( object, frame )`. A native map only compares a key by
+ * identity, and the closed map family (`collectionValueFlowOf`) already
+ * refuses every way to get a key back out -- `keys`/`entries`/`forEach`,
+ * iteration, spreading, or the map escaping to unknown code -- so the key
+ * argument is inert. Only the KEY position: in `m.set( k, k )` the value
+ * argument is a separate reference whose reads the caller still follows.
+ */
+export declare const collectionKeyArgumentIsInert: (checker: ts.TypeChecker, flow: ValueFlowIndex, call: ts.CallExpression, reference: ts.Expression, protocolClosed: (plan: NativeCollectionProtocolPlan) => boolean) => boolean;

package/dist/semantics/normalize/flow/collection-value-continuation.js

@@ -0,0 +1,192 @@
+import ts from 'typescript';
+import { isStandardInterfaceType } from '../derived-expression-type.js';
+import { outermostErasureOf, unwrapErasedExpression } from '../producers/erasure.js';
+import { nativeCollectionProtocolPlanOf } from './native-collection-protocol.js';
+import { isModuleExportedDeclaration, resolveFlowSymbolAlias } from './targets.js';
+const inventories = new WeakMap();
+const collectionWritesAt = (flow, site) => {
+    let inventory = inventories.get(flow);
+    if (!inventory) {
+        inventory = new Map();
+        for (const write of flow.allWrites) {
+            if (write.edge !== 'collection-key' && write.edge !== 'collection-value')
+                continue;
+            const writes = inventory.get(write.site) ?? [];
+            writes.push(write);
+            inventory.set(write.site, writes);
+        }
+        inventories.set(flow, inventory);
+    }
+    return inventory.get(site) ?? [];
+};
+const isCell = (node) => ts.isVariableDeclaration(node) || ts.isPropertyDeclaration(node);
+/** Every value read from a local native map holding this publication. Unknown
+ * consumers or iterator protocols are deliberately not a closed continuation. */
+const collectionValueFlowOf = (checker, flow, publication, write, protocolClosed) => {
+    if (!write.naming || !write.target.declaration || !isCell(write.target.declaration))
+        return null;
+    const cells = new Set();
+    const active = new Set();
+    const constructions = new Set();
+    let family = null;
+    const original = unwrapErasedExpression;
+    const exported = (declaration) => {
+        return isModuleExportedDeclaration(checker, declaration, checker.getSymbolAtLocation(declaration.name) ?? null);
+    };
+    const origins = (declaration) => {
+        if (exported(declaration))
+            return false;
+        if (cells.has(declaration))
+            return true;
+        if (active.has(declaration))
+            return false;
+        active.add(declaration);
+        const writes = flow.writesToDeclaration(declaration).filter((entry) => entry.slot === 'whole');
+        const closed = writes.length > 0 &&
+            writes.every((entry) => {
+                if (!entry.value ||
+                    (entry.edge !== 'declaration-initializer' &&
+                        entry.edge !== 'identifier-assignment' &&
+                        entry.edge !== 'class-field-initializer' &&
+                        entry.edge !== 'property-assignment'))
+                    return false;
+                const source = original(entry.value);
+                if (ts.isIdentifier(source) || ts.isPropertyAccessExpression(source) || ts.isElementAccessExpression(source)) {
+                    const owner = flow.targetOf(source)?.declaration;
+                    return owner !== null && owner !== undefined && isCell(owner) && origins(owner);
+                }
+                if (!ts.isNewExpression(source))
+                    return false;
+                const callee = original(source.expression);
+                if (!ts.isIdentifier(callee))
+                    return false;
+                const type = checker.getTypeAtLocation(source);
+                const native = isStandardInterfaceType(checker, source, 'Map', type)
+                    ? 'Map'
+                    : isStandardInterfaceType(checker, source, 'WeakMap', type)
+                        ? 'WeakMap'
+                        : null;
+                if (native === null || (family !== null && family !== native))
+                    return false;
+                const constructor = resolveFlowSymbolAlias(checker, checker.getSymbolAtLocation(callee));
+                if (!constructor?.valueDeclaration?.getSourceFile().isDeclarationFile)
+                    return false;
+                family = native;
+                constructions.add(source);
+                return true;
+            });
+        active.delete(declaration);
+        if (closed)
+            cells.add(declaration);
+        return closed;
+    };
+    if (!origins(write.target.declaration))
+        return null;
+    const protocol = nativeCollectionProtocolPlanOf(checker, flow, publication, family, constructions);
+    if (!protocol || !protocolClosed?.(protocol))
+        return null;
+    const results = new Set();
+    const values = new Set();
+    const seen = new Set();
+    const cell = (declaration) => {
+        if (!origins(declaration))
+            return false;
+        return flow.referencesToDeclaration(declaration).every(use);
+    };
+    const use = (reference) => {
+        if (seen.has(reference))
+            return true;
+        seen.add(reference);
+        const parent = reference.parent;
+        if (ts.isPropertyAccessExpression(parent) && parent.name === reference)
+            return use(parent);
+        if (ts.isPropertyDeclaration(parent) && parent.name === reference)
+            return true;
+        if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+            if (parent.name === reference)
+                return true;
+            return parent.initializer === reference && cell(parent);
+        }
+        if (ts.isParenthesizedExpression(parent) || ts.isAsExpression(parent) || ts.isTypeAssertionExpression(parent))
+            return use(parent);
+        if (ts.isPropertyAccessExpression(parent) && parent.expression === reference) {
+            const member = checker.getSymbolAtLocation(parent.name);
+            if (!member?.declarations?.length || !member.declarations.every((declaration) => declaration.getSourceFile().isDeclarationFile))
+                return false;
+            if (parent.name.text === 'size')
+                return family === 'Map' && !ts.isBinaryExpression(parent.parent);
+            const call = parent.parent;
+            if (!ts.isCallExpression(call) || call.expression !== parent || call.arguments.some(ts.isSpreadElement))
+                return false;
+            const key = collectionWritesAt(flow, call).some((entry) => entry.edge === 'collection-key');
+            if (parent.name.text === 'get' && key) {
+                results.add(call);
+                return true;
+            }
+            if ((parent.name.text === 'has' || parent.name.text === 'delete') && key)
+                return true;
+            if (parent.name.text === 'clear' && family === 'Map')
+                return true;
+            if (parent.name.text === 'set' && key) {
+                for (const entry of collectionWritesAt(flow, call)) {
+                    if (entry.edge === 'collection-value' && entry.value)
+                        values.add(entry.value);
+                }
+                return ts.isExpressionStatement(call.parent);
+            }
+            return false;
+        }
+        if (ts.isBinaryExpression(parent) && parent.right === reference && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+            const owner = flow.targetOf(parent.left)?.declaration;
+            return owner !== null && owner !== undefined && isCell(owner) && cell(owner);
+        }
+        // Whole-cell assignment origins were checked above. Its expression result
+        // aliases the new map, so only a discarded assignment is closed here.
+        if (ts.isBinaryExpression(parent) && parent.left === reference && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken)
+            return ts.isExpressionStatement(parent.parent);
+        return ts.isTypeOfExpression(parent);
+    };
+    return [...cells].every(cell) ? { reads: [...results], values: [...values], constructions } : null;
+};
+/** Every read from the same authenticated native map storage. */
+export const collectionValueContinuationsOf = (checker, flow, publication, value, protocolClosed) => {
+    const write = collectionWritesAt(flow, publication).find((entry) => entry.edge === 'collection-value' && entry.value === value);
+    return write ? (collectionValueFlowOf(checker, flow, publication, write, protocolClosed)?.reads ?? null) : null;
+};
+/** Every stored value that can reach a get, independent of its runtime key.
+ * Iterable constructor payloads need their own value-flow proof. */
+export const collectionStoredValuesOf = (checker, flow, read, protocolClosed) => {
+    const callee = unwrapErasedExpression(read.expression);
+    if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== 'get')
+        return null;
+    const write = collectionWritesAt(flow, read).find((entry) => entry.edge === 'collection-key');
+    if (!write)
+        return null;
+    const graph = collectionValueFlowOf(checker, flow, read, write, protocolClosed);
+    if (!graph || !graph.reads.includes(read) || [...graph.constructions].some((node) => (node.arguments?.length ?? 0) > 0))
+        return null;
+    return graph.values;
+};
+const KEYED_METHODS = new Set(['get', 'has', 'delete', 'set']);
+/**
+ * Whether handing `reference` to this call as its KEY exposes nothing.
+ *
+ * Three's `WebGLObjects.update` keys its per-frame `updateMap` WeakMap by the
+ * drawable itself: `updateMap.get( object ) !== frame`, then
+ * `updateMap.set( object, frame )`. A native map only compares a key by
+ * identity, and the closed map family (`collectionValueFlowOf`) already
+ * refuses every way to get a key back out -- `keys`/`entries`/`forEach`,
+ * iteration, spreading, or the map escaping to unknown code -- so the key
+ * argument is inert. Only the KEY position: in `m.set( k, k )` the value
+ * argument is a separate reference whose reads the caller still follows.
+ */
+export const collectionKeyArgumentIsInert = (checker, flow, call, reference, protocolClosed) => {
+    const callee = unwrapErasedExpression(call.expression);
+    if (!ts.isPropertyAccessExpression(callee) || !KEYED_METHODS.has(callee.name.text) || call.arguments.some(ts.isSpreadElement))
+        return false;
+    const key = call.arguments[0];
+    if (!key || (reference !== key && outermostErasureOf(reference) !== key))
+        return false;
+    const write = collectionWritesAt(flow, call).find((entry) => entry.edge === 'collection-key' && entry.value === key);
+    return write !== undefined && collectionValueFlowOf(checker, flow, call, write, protocolClosed) !== null;
+};

package/dist/semantics/normalize/flow/component-solver.d.ts

@@ -0,0 +1,199 @@
+/** A lazily expanded graph solved as strongly connected components. */
+export interface DependencyComponentNode<K, R> {
+    /** Facts local to this node are complete, without assuming dependencies. */
+    readonly locallyComplete: boolean;
+    /** Every node whose answer this node requires. */
+    readonly dependencies: readonly K[];
+    /** Terminal reasons that made this node locally incomplete. */
+    readonly causes?: readonly R[];
+    /** Domain-specific grounding witness, used by the seeded-origin policy. */
+    readonly seed?: boolean;
+    /** Grounding domains that must have a witness if this node is in a cycle. */
+    readonly groundingRequirements?: readonly DependencyGroundingDomain[];
+    /** Domain-specific witnesses local to this node. */
+    readonly groundingSeeds?: readonly DependencyGroundingDomain[];
+    /**
+     * Edges that may carry the named grounding domain. Each edge must also be a
+     * regular dependency. Untagged dependencies never propagate grounding.
+     */
+    readonly groundingDependencies?: readonly {
+        readonly domain: DependencyGroundingDomain;
+        readonly dependency: K;
+    }[];
+}
+export type DependencyGroundingDomain = string | symbol;
+export type DependencyComponentMode = 'all-dependencies' | 'seeded-origin' | 'grounding-domains';
+export type DependencyRootCause<K, R> = {
+    readonly kind: 'opaque';
+    readonly root: K;
+    readonly cause: R;
+    readonly path: readonly K[];
+} | {
+    readonly kind: 'incomplete-node';
+    readonly root: K;
+    readonly path: readonly K[];
+} | {
+    readonly kind: 'unseeded-cycle';
+    readonly members: readonly K[];
+    readonly path: readonly K[];
+} | {
+    readonly kind: 'unseeded-cycle';
+    readonly domain: DependencyGroundingDomain;
+    readonly members: readonly K[];
+    /** The members whose own grounding requirement no walk witnessed: where to look. */
+    readonly unmet: readonly K[];
+    readonly path: readonly K[];
+};
+export interface DependencyComponentResult<K, R> {
+    readonly status: 'complete' | 'refused';
+    /** Legacy aggregate witness flag retained for seeded-origin clients. */
+    readonly grounded: boolean;
+    /** Witness domains reached over explicitly labelled edges. */
+    readonly groundedDomains: ReadonlySet<DependencyGroundingDomain>;
+    /** Materialize root causes and one shortest dependency path to each only when needed. */
+    readonly explain: () => readonly DependencyRootCause<K, R>[];
+}
+/**
+ * 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 declare const dependencyComponentSolver: <K, R>(expand: (key: K) => DependencyComponentNode<K, R>, mode: DependencyComponentMode) => ((key: K) => DependencyComponentResult<K, R>);
+/** A node whose fact set is transferred monotonically from discovered dependencies. */
+export type DependencyFactRead<K, V> = (dependency: K) => ReadonlySet<V>;
+/** A discovery edge whose facts are visible but whose completeness is not required. */
+export type DependencyFactObserve<K, V> = (dependency: K) => ReadonlySet<V>;
+/**
+ * The reverse of `read`/`observe`: given a fact VALUE, the keys of every node
+ * that holds it so far. `read`/`observe` name the dependency up front; this is
+ * for the shape where the dependency is not knowable up front -- "which of an
+ * unbounded candidate set holds this" -- which a per-key whole-program scan
+ * inside a transfer is the usual symptom of. `unknownReadsOf` in
+ * `source-value-session.ts` used to `observe` all 968 of the three.js app's
+ * computed-key reads from every one of 570 containers, to ask a question that
+ * does not depend on the key: whether the read's RECEIVER can be this
+ * container. Asked in reverse, each container asks once, "who holds me",
+ * instead of 570 containers each asking the same 968 receivers.
+ *
+ * Calling this still makes the caller a dependent, exactly as `observe`
+ * would -- a node that comes to hold this fact LATER still wakes every past
+ * caller, via a value-keyed subscription rather than a per-dependency edge.
+ * Skipping that would mean a container that gains a holder only after this
+ * ran publishes an incomplete answer forever: a silently wrong result, not a
+ * slow one.
+ *
+ * Never becomes a required edge, and cannot: there is no dependency `K` here
+ * to require -- the very thing being asked is which nodes hold this fact, not
+ * whether one named node is complete. A consumer that needs this fact's
+ * completeness must `read` a query that owns it directly.
+ *
+ * Only finds nodes that already EXIST and have already transferred at least
+ * once. A candidate nothing else in the program ever depends on is never
+ * created and never runs, so its facts never reach here -- the caller must
+ * materialise every candidate explicitly (`DependencyFactSolver.seed`) rather
+ * than relying on this call to do it, the way the 968 `observe` calls it
+ * replaces used to as a side effect of `read`/`observe`'s own `stateOf`.
+ */
+export type DependencyFactHoldersOf<K, V> = (fact: V) => Iterable<K>;
+export interface DependencyFactDefinition<K, V, R> {
+    /**
+     * Add facts derivable now. `read` registers a required dependency, even when
+     * its current fact set is empty. `observe` registers a discovery-only edge:
+     * its facts are visible and it is revisited when they grow, but its local
+     * completeness does not become a requirement of this node. Transfers must
+     * be monotone: later reads may add facts, never retract them. If a transfer
+     * relies on an observed node being complete, it must also call `read` for it.
+     *
+     * Declared `ReadonlySet<V>`, not `Iterable<V>`, on purpose. `propagate`
+     * iterates this return value while it is still mutating the node's own
+     * `facts` -- adding each yielded value before pulling the next one -- and
+     * `read`/`observe` hand a dependency's `facts` out LIVE, with no defensive
+     * copy (a copy per edge read was quadratic and unfinishable on three's
+     * WebGLRenderer; a copy per node doubled the three.js app's peak memory into a 4 GB
+     * OOM -- see `factsFrom`). An `Iterable` return invites a generator, and a
+     * generator's continuation runs interleaved with that iteration: for a
+     * self- or mutually-cyclic node, a `read`/`observe` call made partway
+     * through would see a partially-filled `facts` Set from the transfer pass
+     * CURRENTLY IN PROGRESS instead of the stable snapshot taken when transfer
+     * started, silently breaking the "transfers must be monotone" contract
+     * above and making the answer depend on iteration order. Every
+     * implementation already returns a materialised Set built before it
+     * returns; this type makes that the only legal shape.
+     */
+    readonly transfer: (read: DependencyFactRead<K, V>, observe: DependencyFactObserve<K, V>, holdersOf: DependencyFactHoldersOf<K, V>) => ReadonlySet<V>;
+    /**
+     * Called only after transfer propagation reaches a fixed point. Calling
+     * `read` or `observe` here registers that edge and causes propagation/sealing
+     * to repeat. `read` makes the dependency closure-required; `observe` only
+     * discovers it. This is where a domain decides whether all local alternatives
+     * were accounted for and supplies terminal causes or a grounding witness.
+     * A grounding dependency must be closure-required via `read`; observation
+     * alone can never carry a grounding witness. `holdersOf` behaves like
+     * `observe` here too: it can only ever grow what is locally complete, never
+     * shrink it, and it cannot supply a grounding witness either.
+     */
+    readonly seal: (read: DependencyFactRead<K, V>, observe: DependencyFactObserve<K, V>, holdersOf: DependencyFactHoldersOf<K, V>) => {
+        readonly locallyComplete: boolean;
+        readonly causes?: readonly R[];
+        readonly seed?: boolean;
+        readonly groundingRequirements?: readonly DependencyGroundingDomain[];
+        readonly groundingSeeds?: readonly DependencyGroundingDomain[];
+        readonly groundingDependencies?: readonly {
+            readonly domain: DependencyGroundingDomain;
+            readonly dependency: K;
+        }[];
+    };
+}
+export type DependencyFactResult<K, V, R> = {
+    readonly status: 'complete';
+    readonly grounded: boolean;
+    readonly groundedDomains: ReadonlySet<DependencyGroundingDomain>;
+    readonly facts: ReadonlySet<V>;
+    readonly explain: () => readonly DependencyRootCause<K, R>[];
+} | {
+    readonly status: 'refused';
+    readonly grounded: boolean;
+    readonly groundedDomains: ReadonlySet<DependencyGroundingDomain>;
+    readonly explain: () => readonly DependencyRootCause<K, R>[];
+};
+/**
+ * Demand-discover and monotonically propagate generic fact sets, then seal the
+ * discovered graph with `dependencyComponentSolver`. Empty reads during
+ * propagation are pending values, not refusals; only `seal` can mark a node
+ * locally incomplete. Public facts are exposed only for a complete result.
+ *
+ * Keys and fact values must have stable identity/equality for the lifetime of
+ * the solver. A consumer must ensure its transfer reaches a finite fixed point.
+ */
+/**
+ * A solve, plus the proof graph it already holds.
+ *
+ * A consumer that walks "what did this node read" must not keep its own copy
+ * of the answer: the solver records every required edge anyway, and the second
+ * copy is a whole duplicate dependency graph. The three.js app's was ~115,000 nodes per
+ * solve and three solves deep when the heap ran out.
+ */
+export interface DependencyFactSolver<K, V, R> {
+    readonly solve: (key: K) => DependencyFactResult<K, V, R>;
+    readonly requiredDependenciesOf: (key: K) => Iterable<K>;
+    /**
+     * Materialise a node and schedule its transfer, without creating any edge
+     * to it from anywhere.
+     *
+     * `holdersOf` only ever finds nodes that already exist, because it has
+     * nothing to expand from -- it is handed a fact value, not a key. A caller
+     * that builds a fixed candidate list up front (the three.js app's 968 computed-key
+     * receivers) used to force each candidate into existence as a SIDE EFFECT
+     * of subscribing to it with `observe`; inverting the question removes the
+     * subscription but does not remove the need for the candidate to exist and
+     * have run at least once. This is that need, named: create-and-schedule
+     * with no subscriber, so `seed`ing a whole candidate list costs one
+     * scheduling operation per candidate and stores zero edges, instead of one
+     * stored edge per (candidate, asker) pair.
+     */
+    readonly seed: (key: K) => void;
+}
+export declare const dependencyFactSolver: <K, V, R>(expand: (key: K) => DependencyFactDefinition<K, V, R>, mode: DependencyComponentMode) => DependencyFactSolver<K, V, R>;