@metamesh/modeling 0.17.0 → 0.19.0

package/dist/engine/session/graph.js

@@ -0,0 +1,428 @@
+import { GeometryError } from "../../geometry/errors.js";
+import { captureDiagnosticPath } from "../../model/diagnostic-path.js";
+import { GenerationError, } from "../../model/generation.js";
+import { captureGenerationArguments, captureGenerationValue, compareGenerationValues, generationDataEntries, generationValueBytes, isImmutableGenerationValue, } from "../../model/immutable-generation-data.js";
+import { assertSynchronousScopeResult } from "../native/ownership.js";
+import { createMemoProvenance } from "./dependencies.js";
+const maxEntries = 100_000;
+const maxVersions = 8;
+const source = Symbol("params-source"), contextSource = Symbol("model-context-source"), keys = Symbol("parameter-keys"), negativeZero = Symbol("negative-zero");
+const canonicalId = (id) => typeof id === "string" && id.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id);
+function invalid(message) {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "memo" });
+}
+function locate(index, fn, inputs, create = false) {
+    let node = index.get(fn);
+    if (node === undefined && create)
+        index.set(fn, (node = { children: new Map() }));
+    for (const input of inputs) {
+        if (node === undefined)
+            return undefined;
+        const key = Object.is(input, -0) ? negativeZero : input;
+        let child = node.children.get(key);
+        if (child === undefined && create)
+            node.children.set(key, (child = { children: new Map() }));
+        node = child;
+    }
+    return node;
+}
+/** Conservative map/trie bookkeeping, including read keys; calculated once per successful entry. */
+function entryOverhead(inputs, parameters) {
+    let bytes = 192 + inputs.length * 128;
+    for (const key of parameters.keys())
+        bytes += 48 + (typeof key === "string" ? key.length * 2 : 8);
+    return bytes;
+}
+function captureParameters(input, previous, snapshot) {
+    return Object.freeze(Object.fromEntries(Array.from(generationDataEntries(input), ([key, value]) => [
+        key,
+        Object.is(value, previous[key]) &&
+            Object.hasOwn(snapshot, key) &&
+            isImmutableGenerationValue(value)
+            ? snapshot[key]
+            : captureGenerationValue(value),
+    ])));
+}
+/** Owns bounded successful memo histories and provisional per-revision evaluation. */
+export function createGenerationGraph(options, maxParts) {
+    let committed = new WeakMap();
+    let retained = [];
+    let clock = 0;
+    let previousInput = {}, previousSnapshot = {};
+    const validated = new WeakSet();
+    const provenance = createMemoProvenance();
+    return {
+        begin(input, checkReactiveRead) {
+            let active = true, declaring = true, assertionFailure;
+            let checkAccess = checkReactiveRead, previousEntries = committed, pending = new WeakMap();
+            let previousRetained = retained, revisionClock = clock, selected;
+            const inputValues = input;
+            const snapshot = captureParameters(inputValues, previousInput, previousSnapshot);
+            const keySignature = JSON.stringify(Object.keys(snapshot));
+            const stack = [], calls = [], diagnostics = [];
+            let boundContext;
+            const completed = [];
+            const reported = new WeakSet();
+            const declaredParts = new WeakSet(), partIds = new Set(), outerReads = new Set();
+            const assertActive = () => {
+                if (!active)
+                    invalid("The generation context has expired.");
+                checkAccess();
+            };
+            const assertNoFailedAssertion = () => {
+                if (assertionFailure !== undefined)
+                    throw assertionFailure;
+            };
+            const record = (key, value) => {
+                if (stack.length !== 0)
+                    for (const current of stack)
+                        current.parameters.set(key, value);
+                else if (typeof key === "string")
+                    outerReads.add(key);
+            };
+            const publish = (entry, node) => {
+                if (!reported.has(node)) {
+                    reported.add(node);
+                    completed.push({
+                        id: `memo-${completed.length + 1}`,
+                        inputs: entry.inputs,
+                        parameters: entry.parameters,
+                        value: entry.value,
+                    });
+                }
+                for (const parent of stack) {
+                    for (const [key, value] of entry.parameters)
+                        parent.parameters.set(key, value);
+                    if (!entry.cacheable)
+                        parent.cacheable = false;
+                }
+                return entry.value;
+            };
+            const roots = (entries) => [
+                snapshot,
+                inputValues,
+                ...entries.flatMap((entry) => [entry, ...entry.entry.parameters.values()]),
+            ];
+            // Current tuples take priority. Unused successful tuples stay ordered by last use;
+            // weak callable keys allow collected functions to be pruned on later revisions.
+            const prepareRetention = (extra, ceiling) => {
+                const current = [];
+                for (const { fn, inputs, node } of calls)
+                    if (node.state?.kind === "ready" && node.state.entry.cacheable)
+                        current.push({
+                            fn: new WeakRef(fn),
+                            inputs,
+                            entry: node.state.entry,
+                            usedAt: node.usedAt,
+                        });
+                current.sort((left, right) => right.usedAt - left.usedAt);
+                const dormant = [];
+                if (options.cache !== false)
+                    for (const entry of previousRetained) {
+                        const fn = entry.fn.deref();
+                        if (fn === undefined)
+                            continue;
+                        const touched = locate(pending, fn, entry.inputs)?.state;
+                        if (touched?.kind === "failed" ||
+                            (touched?.kind === "ready" &&
+                                (!touched.entry.cacheable || sameReads(touched.entry, entry.entry))))
+                            continue;
+                        dormant.push(entry);
+                    }
+                const candidates = [];
+                const overhead = [0];
+                // The trie interns validated argument tuples, so their immutable array identity is a
+                // stable bucket key across parameter versions. Keep only the newest bounded history.
+                const versions = new Map();
+                if (options.cache !== false)
+                    for (const entry of [...current, ...dormant]) {
+                        const count = versions.get(entry.inputs) ?? 0;
+                        if (count >= maxVersions)
+                            continue;
+                        versions.set(entry.inputs, count + 1);
+                        candidates.push(entry);
+                        overhead.push(overhead.at(-1) + entry.entry.overheadBytes);
+                        if (candidates.length >= maxEntries)
+                            break;
+                    }
+                const cost = (count) => overhead[count] +
+                    generationValueBytes([...roots(candidates.slice(0, count)), ...extra], ceiling - overhead[count]);
+                const fullCost = cost(candidates.length);
+                if (fullCost <= ceiling) {
+                    selected = candidates;
+                    return fullCost;
+                }
+                else {
+                    // Prefix search preserves priority while using logarithmic budget probes rather
+                    // than repeatedly walking a progressively shortened large cache one entry at a time.
+                    let low = 0, high = candidates.length;
+                    let selectedCost = cost(0);
+                    if (selectedCost > ceiling) {
+                        selected = [];
+                        return selectedCost;
+                    }
+                    while (low < high) {
+                        const middle = Math.ceil((low + high) / 2);
+                        const bytes = cost(middle);
+                        if (bytes <= ceiling) {
+                            low = middle;
+                            selectedCost = bytes;
+                        }
+                        else
+                            high = middle - 1;
+                    }
+                    selected = candidates.slice(0, low);
+                    return selectedCost;
+                }
+            };
+            const retainedEntries = () => {
+                if (selected === undefined)
+                    prepareRetention([], Infinity);
+                return selected;
+            };
+            const sameReads = (left, right) => left === right ||
+                (left.parameters.size === right.parameters.size &&
+                    [...left.parameters].every(([key, value]) => right.parameters.has(key) && Object.is(value, right.parameters.get(key))));
+            // One snapshot-backed proxy is shared by outer generation and every call. It is NEVER
+            // redirected to another revision, so identity/aliasing within a call remain ordinary JS.
+            const params = new Proxy(snapshot, {
+                get(target, key) {
+                    assertActive();
+                    const value = Reflect.get(target, key);
+                    if (typeof key === "string")
+                        record(key, value);
+                    return value;
+                },
+                set: () => invalid("Parameters are immutable."),
+                deleteProperty: () => invalid("Parameters are immutable."),
+                ownKeys(target) {
+                    assertActive();
+                    record(keys, keySignature);
+                    return Reflect.ownKeys(target);
+                },
+                has(target, key) {
+                    assertActive();
+                    record(keys, keySignature);
+                    return Reflect.has(target, key);
+                },
+                getOwnPropertyDescriptor(target, key) {
+                    assertActive();
+                    record(keys, keySignature);
+                    const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
+                    if (typeof key === "string")
+                        record(key, descriptor?.value);
+                    return descriptor;
+                },
+            });
+            const memo = ((fn, ...args) => {
+                assertActive();
+                const parent = stack.at(-1);
+                try {
+                    if (!declaring || typeof fn !== "function")
+                        invalid("Use memo(fn, ...args) during generation.");
+                    // Normal immutable args compare by identity. Only the explicitly passed current params
+                    // object is keyed by source + observed field values instead of revision proxy identity.
+                    const normalized = args.map((arg) => arg === params
+                        ? source
+                        : arg === boundContext && boundContext !== undefined
+                            ? contextSource
+                            : arg);
+                    const known = locate(pending, fn, normalized);
+                    const history = options.cache === false ? undefined : locate(previousEntries, fn, normalized)?.history;
+                    // A hit names the same already-validated immutable argument identities. Only a
+                    // genuinely new tuple needs another deep validation/capture traversal.
+                    const inputs = known?.state?.kind === "ready"
+                        ? known.state.entry.inputs
+                        : history !== undefined && history.length !== 0
+                            ? history[0].inputs
+                            : captureGenerationArguments(normalized, validated);
+                    if (known === undefined && calls.length >= maxEntries)
+                        throw new GeometryError("COMPLEXITY_LIMIT", "Too many memo calls.");
+                    const node = known ?? locate(pending, fn, inputs, true);
+                    node.usedAt = ++revisionClock;
+                    selected = undefined;
+                    if (node.state?.kind === "evaluating")
+                        invalid("Memo dependency cycle.");
+                    if (node.state?.kind === "failed")
+                        throw node.state.error;
+                    if (node.state?.kind === "ready") {
+                        return publish(node.state.entry, node);
+                    }
+                    calls.push({ fn, inputs, node });
+                    const previous = history?.find((entry) => [...entry.parameters].every(([key, value]) => Object.is(value, key === keys ? keySignature : Reflect.get(snapshot, key))));
+                    if (previous !== undefined && options.verifyCache !== true) {
+                        node.state = { kind: "ready", entry: previous };
+                        return publish(previous, node);
+                    }
+                    const evaluation = {
+                        kind: "evaluating",
+                        parameters: new Map(),
+                        cacheable: true,
+                    };
+                    node.state = evaluation;
+                    stack.push(evaluation);
+                    try {
+                        const result = Reflect.apply(fn, undefined, args);
+                        assertSynchronousScopeResult(result, () => new GeometryError("INVALID_ARGUMENT", "Memo functions must be synchronous."));
+                        assertNoFailedAssertion();
+                        // Capture is inside the tracked scope: returning/spreading params records all fields.
+                        let value = captureGenerationValue(result);
+                        if (previous !== undefined) {
+                            const comparison = compareGenerationValues(previous.value, value);
+                            if (comparison !== "equal")
+                                invalid(comparison === "different"
+                                    ? "Memo verification found changed output for unchanged inputs."
+                                    : "Memo verification cannot compare this output within its bounded probe.");
+                            value = previous.value;
+                        }
+                        const entry = Object.freeze({
+                            inputs,
+                            parameters: evaluation.parameters,
+                            value,
+                            cacheable: evaluation.cacheable,
+                            overheadBytes: entryOverhead(inputs, evaluation.parameters),
+                        });
+                        node.state = { kind: "ready", entry };
+                        return publish(entry, node);
+                    }
+                    catch (error) {
+                        node.state = { kind: "failed", error };
+                        throw error;
+                    }
+                    finally {
+                        stack.pop();
+                    }
+                }
+                catch (error) {
+                    if (parent !== undefined)
+                        parent.cacheable = false;
+                    throw error;
+                }
+            });
+            const issue = (severity, message, metadata) => {
+                assertActive();
+                if (typeof message !== "string" || message.length === 0)
+                    invalid("Diagnostics require a nonempty message.");
+                if (metadata?.parameterId !== undefined && !Object.hasOwn(snapshot, metadata.parameterId))
+                    invalid("Diagnostic parameterId must name an existing parameter.");
+                diagnostics.push(Object.freeze({
+                    severity,
+                    message,
+                    ...(metadata?.parameterId === undefined ? {} : { parameterId: metadata.parameterId }),
+                    ...(metadata?.path === undefined ? {} : { path: captureDiagnosticPath(metadata.path) }),
+                }));
+                if (severity === "error") {
+                    assertionFailure ??= new GenerationError(diagnostics);
+                    throw assertionFailure;
+                }
+            };
+            const part = ((id, value) => {
+                assertActive();
+                if (!declaring || stack.length !== 0)
+                    invalid("Declare parts only in outer generation.");
+                if (!canonicalId(id) || partIds.has(id))
+                    invalid("Part IDs must be unique canonical identifiers.");
+                partIds.add(id);
+                const configuration = typeof value === "object" && value !== null && "geometry" in value
+                    ? value
+                    : { geometry: value };
+                if ("position" in configuration || "rotation" in configuration)
+                    invalid("Part placement uses transform.");
+                if ([configuration.geometry, configuration.transform].some((item) => typeof item === "function"))
+                    invalid("Parts require ordinary geometry and transform values.");
+                const descriptor = Object.freeze({ ...configuration, id });
+                declaredParts.add(descriptor);
+                return descriptor;
+            });
+            function assert(condition, message, metadata) {
+                assertActive();
+                if (typeof condition !== "boolean")
+                    invalid("assert requires a boolean condition.");
+                if (!condition)
+                    issue("error", message, metadata);
+            }
+            const context = {
+                params,
+                memo,
+                part,
+                assert,
+                warn: (message, metadata) => {
+                    if (!declaring || stack.length !== 0)
+                        invalid("Warnings must be emitted in outer generation.");
+                    issue("warning", message, metadata);
+                },
+            };
+            return {
+                context,
+                withServices(services) {
+                    const supplied = Object.freeze({ ...context, services });
+                    boundContext = supplied;
+                    return supplied;
+                },
+                assertActive,
+                diagnostics,
+                finish(output) {
+                    assertSynchronousScopeResult(output, () => new GeometryError("INVALID_ARGUMENT", "Generation callbacks must be synchronous."));
+                    assertNoFailedAssertion();
+                    declaring = false;
+                    const parts = Array.isArray(output)
+                        ? output
+                        : [output];
+                    if (parts.length === 0)
+                        invalid("Generation must return at least one declared part.");
+                    if (parts.length > maxParts)
+                        throw new GeometryError("COMPLEXITY_LIMIT", `Output exceeds ${maxParts} parts.`);
+                    const ids = new Set();
+                    for (const descriptor of parts) {
+                        if (!declaredParts.has(descriptor) || ids.has(descriptor.id))
+                            invalid("Return each declared output part at most once.");
+                        ids.add(descriptor.id);
+                    }
+                    return parts;
+                },
+                dependencies(output) {
+                    return provenance(output, outerReads, completed);
+                },
+                prepareRetention,
+                memoValues() {
+                    return retainedEntries().map((entry) => entry.entry.value);
+                },
+                commit() {
+                    const next = new WeakMap();
+                    const accepted = [];
+                    for (const entry of retainedEntries()) {
+                        const fn = entry.fn.deref();
+                        if (fn === undefined)
+                            continue;
+                        const bucket = locate(next, fn, entry.inputs, true);
+                        (bucket.history ??= []).push(entry.entry);
+                        accepted.push(entry);
+                    }
+                    committed = next;
+                    retained = accepted;
+                    clock = revisionClock;
+                    previousInput = { ...inputValues };
+                    previousSnapshot = snapshot;
+                },
+                close() {
+                    active = false;
+                    calls.length = 0;
+                    pending = new WeakMap();
+                    previousEntries = new WeakMap();
+                    previousRetained = [];
+                    selected = [];
+                    completed.length = 0;
+                    checkAccess = () => { };
+                    boundContext = undefined;
+                },
+            };
+        },
+        clear() {
+            committed = new WeakMap();
+            retained = [];
+            clock = 0;
+            previousInput = {};
+            previousSnapshot = {};
+        },
+    };
+}

package/dist/engine/{session-native.js → session/native-cache.js}

@@ -1,4 +1,4 @@
-import { generationValueBytes } from "../model/immutable-generation-data.js";
+import { generationValueBytes } from "../../model/immutable-generation-data.js";
 function disposeValues(values) {
     const errors = [];
     for (const value of new Set(values)) {
@@ -22,7 +22,7 @@ function rollback(error, values, message) {
     }
     throw error;
 }
-/** Bounded evaluated computed roots. Candidates remain provisional until ordinary run cleanup succeeds. */
+/** Bounded evaluated memo roots. Candidates remain provisional until ordinary run cleanup succeeds. */
 export function createNativeGeometryCache() {
     let committed = new Map();
     const values = (entries) => new Set([...entries.values()].map((entry) => entry.native.value));

package/dist/engine/{session.js → session/session.js}

@@ -1,15 +1,16 @@
-import { GeometryError } from "../geometry/errors.js";
-import { resolveModelingLimits } from "../geometry/model-limits.js";
-import { bindModelContext } from "../model/execution-binding.js";
-import { captureGenerationValue, generationValueBytes, } from "../model/immutable-generation-data.js";
+import { GeometryError } from "../../geometry/errors.js";
+import { resolveModelingLimits } from "../../geometry/model-limits.js";
+import { bindModelContext } from "../../model/execution-binding.js";
+import { GenerationError } from "../../model/generation.js";
+import { captureGenerationValue } from "../../model/immutable-generation-data.js";
 import { createDeferredContext } from "./deferred-context.js";
-import { createGenerationGraph } from "./session-graph.js";
-import { createNativeGeometryCache } from "./session-native.js";
-import { createSnapshotCache } from "./session-snapshot.js";
+import { createGenerationGraph } from "./graph.js";
+import { createNativeGeometryCache } from "./native-cache.js";
+import { createSnapshotCache } from "./snapshot-cache.js";
 function invalid(message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "generate" });
 }
-/** Coordinates native transactions and bounded atomic cache commits; snapshots own their lifetime. */
+/** Coordinates native transactions and bounded atomic cache commits; results remain durable after cache cleanup. */
 export function createSession(program, suppliedOptions, engineLimits, transaction) {
     const options = Object.freeze({
         ...suppliedOptions,
@@ -58,6 +59,11 @@ export function createSession(program, suppliedOptions, engineLimits, transactio
             // Nothing becomes reusable until geometry validation AND native cleanup have succeeded.
             revision.commit();
         }
+        catch (error) {
+            if (mode === "validate" && error instanceof GenerationError)
+                return error.diagnostics;
+            throw error;
+        }
         finally {
             try {
                 revision.dispose();
@@ -69,8 +75,8 @@ export function createSession(program, suppliedOptions, engineLimits, transactio
         return completed.capture.snapshot;
     }
     return Object.freeze({
-        run: (params) => execute(params, "run"),
-        validate: (params) => execute(params, "validate"),
+        run: (params) => execute(params === undefined ? {} : params, "run"),
+        check: (params) => execute(params === undefined ? {} : params, "validate"),
         clearCache() {
             if (running)
                 invalid("Cannot clear a running session.");
@@ -87,7 +93,7 @@ export function createSession(program, suppliedOptions, engineLimits, transactio
 /**
  * Owns one attempted revision, including provisional retained native allocations. Declaration and capture
  * happen inside the native transaction; commit is allowed only after that transaction cleans up.
- * Disposal invalidates readers and releases any native allocations that were not committed.
+ * Disposal invalidates contexts and releases any native allocations that were not committed.
  */
 class SessionRevision {
     session;
@@ -114,7 +120,7 @@ class SessionRevision {
     generate(revision, deferred, native, mode) {
         const { program, services, caches } = this.session;
         const startedAt = performance.now();
-        const output = revision.finish(program.generate({ ...revision.context, services }));
+        const output = revision.finish(program.generate(revision.withServices(services)));
         if (mode === "validate")
             return { kind: "validation", diagnostics: Object.freeze([...revision.diagnostics]) };
         const captured = caches.snapshots.capture({
@@ -135,10 +141,10 @@ class SessionRevision {
         const { options, limits, caches } = this.session;
         if (options.cache === false)
             return;
-        const retainedBytes = generationValueBytes([...revision.retainedValues(), ...captured.retainedValues], limits.maxBytes);
+        const retainedBytes = revision.prepareRetention(captured.retainedValues, limits.maxBytes);
         if (retainedBytes > limits.maxBytes)
             return;
-        const nativeCandidate = caches.geometry.prepare(deferred.retentionCandidates(revision.computedValues()), (shape) => {
+        const nativeCandidate = caches.geometry.prepare(deferred.retentionCandidates(revision.memoValues()), (shape) => {
             const realized = deferred.realizedShape(shape);
             if (realized !== undefined)
                 return native().captureNative(realized);