@metamesh/modeling 0.17.0 → 0.19.0

package/dist/engine/session-graph.js

@@ -1,449 +0,0 @@
-import { GeometryError } from "../geometry/errors.js";
-import { GenerationError, } from "../model/generation.js";
-import { captureGenerationDependencies, captureGenerationValue, compareGenerationValues, generationDataEntries, } from "../model/immutable-generation-data.js";
-import { createModelDependencies } from "./model-dependencies.js";
-import { assertSynchronousScopeResult } from "./native/ownership.js";
-function reusableEntry(node) {
-    if (node.state.kind === "ready")
-        return node.state.entry;
-    if (node.state.kind === "pending")
-        return node.previous;
-    return undefined;
-}
-const parameterKeys = Symbol("parameter-keys");
-const emptyInputs = Object.freeze([]);
-const isArray = (value) => Array.isArray(value);
-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: "generate" });
-}
-const sameInputs = (left, right) => left.length === right.length && left.every((value, index) => Object.is(value, right[index]));
-function evaluateComputed(callback) {
-    const result = callback();
-    assertSynchronousScopeResult(result, () => new GeometryError("INVALID_ARGUMENT", "Computed callbacks must be synchronous.", {
-        operation: "computed",
-    }));
-    return captureGenerationValue(result);
-}
-/** Reuse immutable captures only when the host supplies the same input value. */
-function captureParameters(input, previousInput, previousSnapshot) {
-    return Object.freeze(Object.fromEntries(Array.from(generationDataEntries(input), ([key, value]) => {
-        if (Object.is(value, previousInput[key]) && Object.hasOwn(previousSnapshot, key))
-            return [key, previousSnapshot[key]];
-        return [key, captureGenerationValue(value)];
-    })));
-}
-/**
- * Owns one revision's lazy computations and dynamic read sets. A failed read stays failed for the
- * attempt; only the surrounding generation revision can promote successful entries to the cache.
- */
-class ComputationRevision {
-    options;
-    parameterSnapshot;
-    committed;
-    readerIds;
-    validatedInputs;
-    assertActive;
-    assertNoFailedAssertion;
-    nodes = new Map();
-    keySignature;
-    stack = [];
-    constructor(options, parameterSnapshot, committed, readerIds, validatedInputs, assertActive, assertNoFailedAssertion) {
-        this.options = options;
-        this.parameterSnapshot = parameterSnapshot;
-        this.committed = committed;
-        this.readerIds = readerIds;
-        this.validatedInputs = validatedInputs;
-        this.assertActive = assertActive;
-        this.assertNoFailedAssertion = assertNoFailedAssertion;
-        // Structural reads share one unambiguous signature, even when parameter names contain NUL.
-        this.keySignature = JSON.stringify(Object.keys(parameterSnapshot));
-    }
-    get evaluating() {
-        return this.stack.length > 0;
-    }
-    currentEvaluation() {
-        const current = this.stack.at(-1);
-        if (current === undefined)
-            return undefined;
-        const state = this.nodes.get(current)?.state;
-        return state?.kind === "evaluating" ? state : undefined;
-    }
-    dispose() {
-        // Retained numerical callbacks may keep an expired parameter guard alive. That guard must
-        // not retain unrelated callbacks or chain together every previous computation cache.
-        this.nodes.clear();
-        this.committed = new Map();
-    }
-    register(id, callback, dependencies = emptyInputs) {
-        if (!canonicalId(id) || this.nodes.has(id))
-            invalid("Computed IDs must be unique canonical lowercase identifiers of at most 64 characters.");
-        if (this.nodes.size >= 100_000)
-            throw new GeometryError("COMPLEXITY_LIMIT", "Too many declared computations.", {
-                operation: "computed",
-            });
-        if (typeof callback !== "function" || !Array.isArray(dependencies))
-            invalid("Use computed(id, callback, dependencies?) with an optional dependency array.");
-        const inputs = dependencies === emptyInputs
-            ? emptyInputs
-            : captureGenerationDependencies(dependencies, (value) => this.readerIds.has(value), this.validatedInputs);
-        const previous = this.committed.get(id);
-        this.nodes.set(id, {
-            callback,
-            inputs,
-            previous,
-            state: { kind: "pending" },
-        });
-    }
-    /** A handled dependency failure must still prevent the caller's fallback from becoming reusable. */
-    read = (id) => {
-        this.assertActive();
-        const parent = this.currentEvaluation();
-        try {
-            const node = this.nodes.get(id);
-            if (node === undefined)
-                invalid(`Computed '${id}' must be declared before it is read.`);
-            const cycle = this.stack.indexOf(id);
-            if (cycle >= 0)
-                invalid(`Computed dependency cycle: ${[...this.stack.slice(cycle), id].join(" -> ")}.`);
-            if (node.state.kind === "failed")
-                throw node.state.error;
-            const entry = node.state.kind === "ready" ? node.state.entry : this.evaluateNode(id, node);
-            if (parent !== undefined) {
-                parent.dependencies.set(id, entry.token);
-                if (!entry.cacheable)
-                    parent.cacheable = false;
-            }
-            return entry.value;
-        }
-        catch (error) {
-            if (parent !== undefined)
-                parent.cacheable = false;
-            throw error;
-        }
-    };
-    /** Validate old reads, evaluate or reuse the output, and publish exactly one local outcome. */
-    evaluateNode(id, node) {
-        const evaluation = {
-            kind: "evaluating",
-            parameters: new Map(),
-            dependencies: new Map(),
-            cacheable: true,
-        };
-        node.state = evaluation;
-        this.stack.push(id);
-        try {
-            const previous = node.previous;
-            const reusable = previous !== undefined && this.canReuse(node, previous);
-            let entry;
-            if (reusable && this.options.verifyCache !== true) {
-                entry = evaluation.cacheable ? previous : Object.freeze({ ...previous, cacheable: false });
-            }
-            else {
-                entry = this.evaluateCallback(id, node, evaluation, reusable);
-            }
-            node.state = { kind: "ready", entry };
-            return entry;
-        }
-        catch (error) {
-            // Neither partial dependencies nor an earlier value may escape a failed evaluation.
-            node.state = { kind: "failed", error };
-            throw error;
-        }
-        finally {
-            this.stack.pop();
-        }
-    }
-    canReuse(node, previous) {
-        if (this.options.cache === false || !sameInputs(node.inputs, previous.inputs))
-            return false;
-        for (const [key, value] of previous.parameters) {
-            const current = key === parameterKeys ? this.keySignature : Reflect.get(this.parameterSnapshot, key);
-            if (!Object.is(current, value))
-                return false;
-        }
-        for (const [dependency, token] of previous.dependencies) {
-            if (!this.nodes.has(dependency))
-                return false;
-            try {
-                this.read(dependency);
-            }
-            catch {
-                // Let the callback decide whether a failed dependency propagates or uses a fallback.
-                return false;
-            }
-            const state = this.nodes.get(dependency).state;
-            if (state.kind !== "ready" || state.entry.token !== token)
-                return false;
-        }
-        return true;
-    }
-    evaluateCallback(id, node, evaluation, reusable) {
-        // Validation may read old branches. Only callback reads describe the successful output,
-        // whether this is a cache miss or a development verification.
-        evaluation.parameters.clear();
-        evaluation.dependencies.clear();
-        evaluation.cacheable = true;
-        // Declared readers depend on their output, not just their stable callable identity.
-        for (const input of node.inputs) {
-            const dependency = typeof input === "function" ? this.readerIds.get(input) : undefined;
-            if (dependency !== undefined) {
-                try {
-                    this.read(dependency);
-                }
-                catch {
-                    // Failed reads already prevent reuse; the callback owns propagation or fallback.
-                }
-            }
-        }
-        const result = evaluateComputed(node.callback);
-        this.assertNoFailedAssertion();
-        const previous = node.previous;
-        let value = result;
-        if (reusable && previous !== undefined) {
-            const comparison = compareGenerationValues(previous.value, result);
-            if (comparison === "different")
-                invalid(`Cache verification for '${id}' found a changed result without a tracked dependency. Add changing outer values to the dependency array.`);
-            if (comparison === "unsupported")
-                invalid(`Cache verification for '${id}' cannot compare this result within its bounded data/recipe probe. Use cache: false for a full output equivalence check.`);
-            value = previous.value;
-        }
-        return Object.freeze({
-            inputs: node.inputs,
-            parameters: evaluation.parameters,
-            dependencies: evaluation.dependencies,
-            value,
-            cacheable: evaluation.cacheable,
-            // Tokens identify successful outputs, including new registrations of removed IDs. A per-node
-            // counter could repeat an old dependency's version and serve stale data.
-            token: previous !== undefined && Object.is(previous.value, value) ? previous.token : {},
-        });
-    }
-}
-/** Owns computed identities and per-revision reads; the session commits only successful revisions. */
-export function createGenerationGraph(options, maxParts) {
-    let committed = new Map();
-    const readers = new Map();
-    const readerIds = new WeakMap();
-    const validatedInputs = new WeakSet();
-    let activeRead;
-    let previousInput = {};
-    let previousParameterSnapshot = {};
-    // Build stable readers outside registration's lexical scope so they cannot retain a revision's
-    // callback, captured locals, or dependency inputs after that revision closes.
-    const createReader = (id) => (() => {
-        if (activeRead === undefined)
-            return invalid("Computed readers can only be used during their active model session revision.");
-        return activeRead(id);
-    });
-    return {
-        begin(input, checkReactiveRead) {
-            let active = true;
-            let declaring = true;
-            let assertionFailure;
-            const diagnostics = [];
-            const partIds = new Set();
-            const declaredParts = new WeakSet();
-            const modelParameters = new Set();
-            const inputValues = input;
-            const parameterSnapshot = captureParameters(inputValues, previousInput, previousParameterSnapshot);
-            const assertActive = () => {
-                if (!active)
-                    invalid("The generation context has expired.");
-                checkReactiveRead();
-            };
-            const assertNoFailedAssertion = () => {
-                if (assertionFailure !== undefined)
-                    throw assertionFailure;
-            };
-            const computations = new ComputationRevision(options, parameterSnapshot, committed, readerIds, validatedInputs, assertActive, assertNoFailedAssertion);
-            const params = new Proxy(parameterSnapshot, {
-                get: (target, key) => {
-                    assertActive();
-                    const value = Reflect.get(target, key);
-                    const current = computations.currentEvaluation();
-                    if (current !== undefined && typeof key === "string")
-                        current.parameters.set(key, value);
-                    else if (typeof key === "string" && Object.hasOwn(target, key))
-                        modelParameters.add(key);
-                    return value;
-                },
-                set: () => invalid("Parameters are immutable."),
-                deleteProperty: () => invalid("Parameters are immutable."),
-                ownKeys: (target) => {
-                    assertActive();
-                    const current = computations.currentEvaluation();
-                    if (current !== undefined)
-                        current.parameters.set(parameterKeys, computations.keySignature);
-                    else
-                        for (const key of Object.keys(target))
-                            modelParameters.add(key);
-                    return Reflect.ownKeys(target);
-                },
-                has: (target, key) => {
-                    assertActive();
-                    const current = computations.currentEvaluation();
-                    if (current !== undefined)
-                        current.parameters.set(parameterKeys, computations.keySignature);
-                    else if (typeof key === "string")
-                        modelParameters.add(key);
-                    return Reflect.has(target, key);
-                },
-                getOwnPropertyDescriptor: (target, key) => {
-                    assertActive();
-                    const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
-                    const current = computations.currentEvaluation();
-                    if (current !== undefined) {
-                        const dependencies = current.parameters;
-                        dependencies.set(parameterKeys, computations.keySignature);
-                        if (typeof key === "string")
-                            dependencies.set(key, descriptor?.value);
-                    }
-                    else if (typeof key === "string")
-                        modelParameters.add(key);
-                    return descriptor;
-                },
-            });
-            activeRead = computations.read;
-            const computed = ((id, callback, dependencies) => {
-                assertActive();
-                if (!declaring || computations.evaluating)
-                    invalid("Declare computations only in the outer generation callback.");
-                computations.register(id, callback, dependencies);
-                let reader = readers.get(id);
-                if (reader === undefined) {
-                    reader = createReader(id);
-                    readers.set(id, reader);
-                    readerIds.set(reader, id);
-                }
-                return reader;
-            });
-            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(parameterSnapshot, metadata.parameterId))
-                    invalid("Diagnostic parameterId must name an existing parameter.");
-                diagnostics.push(Object.freeze({
-                    severity,
-                    message,
-                    ...(metadata?.parameterId === undefined ? {} : { parameterId: metadata.parameterId }),
-                }));
-                if (severity === "error") {
-                    assertionFailure ??= new GenerationError(diagnostics);
-                    throw assertionFailure;
-                }
-            };
-            const part = ((id, value) => {
-                assertActive();
-                if (!declaring || computations.evaluating)
-                    invalid("Declare parts only in the outer generation callback.");
-                if (!canonicalId(id) || partIds.has(id))
-                    invalid("Part IDs must be unique canonical lowercase identifiers of at most 64 characters.");
-                partIds.add(id);
-                const configuration = typeof value === "object" && value !== null && "geometry" in value
-                    ? value
-                    : { geometry: value };
-                for (const value of [
-                    configuration.geometry,
-                    configuration.position,
-                    configuration.rotation,
-                ])
-                    if (typeof value === "function" && !readerIds.has(value))
-                        invalid("Part readers must belong to this model session.");
-                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);
-            }
-            return {
-                context: {
-                    params,
-                    computed,
-                    part,
-                    assert,
-                    warn: (message, metadata) => {
-                        if (!declaring || computations.evaluating)
-                            invalid("Warnings must be emitted in the outer generation callback.");
-                        issue("warning", message, metadata);
-                    },
-                },
-                assertActive,
-                diagnostics,
-                finish(output) {
-                    assertSynchronousScopeResult(output, () => new GeometryError("INVALID_ARGUMENT", "Generation callbacks must be synchronous.", {
-                        operation: "generate",
-                    }));
-                    // Catching an assertion does not turn its revision into a successful snapshot.
-                    assertNoFailedAssertion();
-                    declaring = false;
-                    const parts = 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.`, {
-                            operation: "generate",
-                        });
-                    const returnedIds = new Set();
-                    for (const descriptor of parts) {
-                        if (!declaredParts.has(descriptor) || returnedIds.has(descriptor.id))
-                            invalid("Return each declared output part at most once.");
-                        returnedIds.add(descriptor.id);
-                    }
-                    return parts;
-                },
-                dependencies(output) {
-                    return createModelDependencies(output, modelParameters, new Map([...computations.nodes].map(([id, node]) => [id, reusableEntry(node)])), readerIds);
-                },
-                computedValues() {
-                    return [...computations.nodes.values()].map((node) => reusableEntry(node)?.value);
-                },
-                retainedValues() {
-                    const retained = [];
-                    for (const node of computations.nodes.values()) {
-                        const entry = reusableEntry(node);
-                        if (entry !== undefined)
-                            retained.push(entry.value, entry.inputs, ...entry.parameters.values());
-                    }
-                    return [...retained, parameterSnapshot, inputValues];
-                },
-                commit() {
-                    const accepted = new Map();
-                    for (const [id, node] of computations.nodes) {
-                        const entry = reusableEntry(node);
-                        if (entry?.cacheable)
-                            accepted.set(id, entry);
-                    }
-                    committed = accepted;
-                    previousInput = { ...inputValues };
-                    previousParameterSnapshot = parameterSnapshot;
-                    for (const id of readers.keys())
-                        if (!computations.nodes.has(id))
-                            readers.delete(id);
-                },
-                close() {
-                    active = false;
-                    activeRead = undefined;
-                    computations.dispose();
-                    // Failed edits and validation probes cannot retain newly registered readers.
-                    for (const id of readers.keys())
-                        if (!committed.has(id))
-                            readers.delete(id);
-                },
-            };
-        },
-        clear() {
-            committed.clear();
-            readers.clear();
-            previousInput = {};
-            previousParameterSnapshot = {};
-        },
-    };
-}

package/dist/geometry/profiles/profiles.js

@@ -1,71 +0,0 @@
-import { resolveCircularSampling } from "../circular-sampling.js";
-import { GeometryError } from "../errors.js";
-import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
-export { rectangleContour } from "./rectangle.js";
-/**
- * Creates an immutable centered CCW circle with +X seam and vertex or face radial sizing.
- *
- * @example Explicit circular point data
- * ```ts
- * circleContour({ diameter: 20, segments: 32 });
- * ```
- */
-export const circleContour = (options) => {
-    const operation = "circleContour";
-    const { segments, vertexRadius } = resolveCircularSampling(options);
-    requireProfileVertexCount(segments, 3, operation, options.limits);
-    return Object.freeze(Array.from({ length: segments }, (_, index) => {
-        const angle = (Math.PI * 2 * index) / segments;
-        return Object.freeze([vertexRadius * Math.cos(angle), vertexRadius * Math.sin(angle)]);
-    }));
-};
-/**
- * Creates a centered CCW point loop with vertex or face radial sizing and an implicit seam.
- *
- * @example Hexagon sized to its faces
- * ```ts
- * regularPolygonContour({ radius: 10, sides: 6, sizing: "face" });
- * ```
- */
-export const regularPolygonContour = (options) => {
-    const operation = "regularPolygonContour";
-    const { radius, sides, rotation = 0, sizing = "vertex" } = options;
-    requireFiniteProfileValues([radius, rotation], operation);
-    if (!(radius > 0)) {
-        throw new GeometryError("INVALID_ARGUMENT", "Polygon radius must be positive.", { operation });
-    }
-    requireProfileVertexCount(sides, 3, operation, options.limits);
-    if (sizing !== "vertex" && sizing !== "face")
-        throw new GeometryError("INVALID_ARGUMENT", "Polygon sizing must be vertex or face.", {
-            operation,
-        });
-    const sampledRadius = sizing === "face" ? radius / Math.cos(Math.PI / sides) : radius;
-    requireFiniteProfileValues([sampledRadius], operation);
-    const rotationRadians = ((rotation % 360) * Math.PI) / 180;
-    return Array.from({ length: sides }, (_, index) => {
-        const angle = rotationRadians + (Math.PI * 2 * index) / sides;
-        return [sampledRadius * Math.cos(angle), sampledRadius * Math.sin(angle)];
-    });
-};
-/**
- * Creates a centered CCW alternating-radius star within the selected profile sampling ceiling.
- *
- * @example Five-point outline
- * ```ts
- * starContour(12, 5, 6);
- * ```
- */
-export const starContour = (outerRadius, points, innerRadius = outerRadius / 2, limits = {}) => {
-    const operation = "starContour";
-    requireFiniteProfileValues([outerRadius, innerRadius], operation);
-    if (!(outerRadius > 0) || !(innerRadius > 0) || innerRadius >= outerRadius) {
-        throw new GeometryError("INVALID_ARGUMENT", "Star radii must be positive, with the inner radius smaller than the outer.", { operation });
-    }
-    requireProfileVertexCount(points, 3, operation, limits);
-    requireProfileVertexCount(points * 2, 6, operation, limits);
-    return Array.from({ length: points * 2 }, (_, index) => {
-        const radius = index % 2 === 0 ? outerRadius : innerRadius;
-        const angle = (Math.PI * index) / points;
-        return [radius * Math.cos(angle), radius * Math.sin(angle)];
-    });
-};