@metamesh/modeling 0.10.0 → 0.12.0

package/dist/engine/session-graph.js

@@ -0,0 +1,447 @@
+import { GeometryError } from "../geometry/errors.js";
+import { GenerationError, } from "../model/generation.js";
+import { captureGenerationDependencies, captureGenerationValue, compareGenerationValues, generationDataEntries, } from "./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;
+                    if (!isArray(output) || output.length === 0)
+                        invalid("Generation must return at least one declared part.");
+                    if (output.length > maxParts)
+                        throw new GeometryError("COMPLEXITY_LIMIT", `Output exceeds ${maxParts} parts.`, {
+                            operation: "generate",
+                        });
+                    const returnedIds = new Set();
+                    for (const descriptor of output) {
+                        if (!declaredParts.has(descriptor) || returnedIds.has(descriptor.id))
+                            invalid("Return each declared output part at most once.");
+                        returnedIds.add(descriptor.id);
+                    }
+                },
+                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/engine/session-native.js

@@ -0,0 +1,90 @@
+import { generationValueBytes } from "./immutable-generation-data.js";
+function disposeValues(values) {
+    const errors = [];
+    for (const value of new Set(values)) {
+        try {
+            value.delete();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length > 0)
+        throw new AggregateError(errors, "Failed to release cached native geometry.");
+}
+/** Releases provisional ownership without hiding the failure that caused rollback. */
+function rollback(error, values, message) {
+    try {
+        disposeValues(values);
+    }
+    catch (cleanup) {
+        throw new AggregateError([error, cleanup], message, { cause: cleanup });
+    }
+    throw error;
+}
+/** Bounded evaluated computed 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));
+    return {
+        get(shape) {
+            return committed.get(shape);
+        },
+        prepare(roots, capture, detach, budget) {
+            const previousValues = values(committed);
+            const next = new Map();
+            const admitted = new Set();
+            const staged = new Set();
+            let remaining = budget;
+            try {
+                for (const root of roots) {
+                    if (remaining <= 0 || next.size >= 256)
+                        break;
+                    const entry = committed.get(root) ?? capture(root);
+                    if (entry === undefined)
+                        continue;
+                    const native = entry.native.value;
+                    const cost = (admitted.has(native) ? 0 : entry.bytes) +
+                        generationValueBytes([entry.anchors, entry.profile], remaining);
+                    if (!Number.isFinite(cost) || cost > remaining)
+                        continue;
+                    if (!previousValues.has(native) && !staged.has(native)) {
+                        detach(entry);
+                        staged.add(native);
+                    }
+                    admitted.add(native);
+                    next.set(root, entry);
+                    remaining -= cost;
+                }
+            }
+            catch (error) {
+                rollback(error, staged, "Native cache preparation failed.");
+            }
+            return {
+                commit() {
+                    committed = next;
+                    staged.clear();
+                    // Drop references before cleanup: a deletion failure must never leave deleted objects
+                    // available for a later cache hit. The session clears its other caches on this failure.
+                    try {
+                        disposeValues([...previousValues].filter((value) => !admitted.has(value)));
+                    }
+                    catch (error) {
+                        committed = new Map();
+                        rollback(error, admitted, "Native cache replacement failed.");
+                    }
+                },
+                dispose() {
+                    const abandoned = [...staged];
+                    staged.clear();
+                    disposeValues(abandoned);
+                },
+            };
+        },
+        clear() {
+            const previous = values(committed);
+            committed = new Map();
+            disposeValues(previous);
+        },
+    };
+}

package/dist/engine/session-snapshot.js

@@ -0,0 +1,153 @@
+import { GeometryError } from "../geometry/errors.js";
+import { isImmutableBuffer } from "../model/immutable-buffer.js";
+import { createGeometryFinalizer, rememberSnapshotPart, } from "./finalization.js";
+import { createModelSummary } from "./model-summary.js";
+import { placeFinalizedGeometry } from "./placement.js";
+let nextSession = 0;
+function invalid(message) {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "generate" });
+}
+const vector = (value) => {
+    const result = value ?? [0, 0, 0];
+    if (!Array.isArray(result) || result.length !== 3 || !result.every(Number.isFinite))
+        invalid("Part placement requires three finite coordinates.");
+    return Object.freeze([...result]);
+};
+/** Only fixed buffer fields can establish immutable mesh identity across revisions. */
+function isImmutableMesh(value) {
+    return (Object.isFrozen(value) &&
+        isImmutableBuffer(Object.getOwnPropertyDescriptor(value, "positions")?.value) &&
+        isImmutableBuffer(Object.getOwnPropertyDescriptor(value, "indices")?.value));
+}
+/** Publishes copied views while retaining the authoritative local buffers privately. */
+function createResource(id, geometry, reusable) {
+    return {
+        geometry,
+        reusable,
+        public: Object.freeze({
+            id,
+            revision: 1,
+            measurements: geometry.measurements,
+            get positions() {
+                return new Float32Array(geometry.positions);
+            },
+            get indices() {
+                return new Uint32Array(geometry.indices);
+            },
+        }),
+    };
+}
+/** Captures authoritative placement and appearance before consulting world-geometry reuse. */
+function capturePlacement(descriptor) {
+    const position = vector(typeof descriptor.position === "function" ? descriptor.position() : descriptor.position);
+    const rotation = vector(typeof descriptor.rotation === "function" ? descriptor.rotation() : descriptor.rotation);
+    const color = descriptor.color;
+    if (color !== undefined && (typeof color !== "string" || !/^#[\da-f]{6}$/i.test(color)))
+        invalid("Part colors must be six-digit hex strings.");
+    return { position, rotation, ...(color === undefined ? {} : { color: color.toLowerCase() }) };
+}
+/** Snapshot accessors own their copies; export can still use the trusted private world buffers. */
+function capturePart(id, geometry, placement, worldGeometry) {
+    const part = Object.freeze({
+        id,
+        geometry,
+        ...placement,
+        measurements: worldGeometry.measurements,
+        get positions() {
+            return new Float32Array(worldGeometry.positions);
+        },
+        get indices() {
+            return new Uint32Array(worldGeometry.indices);
+        },
+    });
+    rememberSnapshotPart(part, worldGeometry);
+    return part;
+}
+/** Isolates a snapshot's lifetime from the cache transaction that produced it. */
+function createSnapshot(parts, { bounds, stats }, diagnostics, dependencies) {
+    let ownedParts = Object.freeze(parts);
+    const requireParts = () => ownedParts ?? invalid("This model snapshot has been disposed.");
+    return Object.freeze({
+        get parts() {
+            return requireParts();
+        },
+        get bounds() {
+            requireParts();
+            return bounds;
+        },
+        get stats() {
+            requireParts();
+            return stats;
+        },
+        diagnostics: Object.freeze([...diagnostics]),
+        dependencies,
+        dispose() {
+            ownedParts = undefined;
+        },
+    });
+}
+/**
+ * Owns committed local resources and placed geometry, independently of computation tracking.
+ * A capture stages replacements without mutating either cache. Only its caller may commit after
+ * all finalization and native cleanup succeed; snapshots keep their own references either way.
+ */
+export function createSnapshotCache(options, limits) {
+    const sessionId = ++nextSession;
+    let resourceVersion = 0;
+    let resourceCache = new Map();
+    let placedCache = new Map();
+    return {
+        capture({ output, native, deferred, startedAt, builtAt, diagnostics, readDependencies, }) {
+            const nextResources = new Map();
+            const nextPlaced = new Map();
+            const worldParts = [];
+            const summary = createModelSummary(limits);
+            let finalizeGeometry;
+            for (const descriptor of output) {
+                const geometry = typeof descriptor.geometry === "function" ? descriptor.geometry() : descriptor.geometry;
+                if (typeof geometry !== "object" || geometry === null)
+                    invalid("Parts require Solid recipes or indexed manufacturing meshes.");
+                let resource = options.cache === false ? undefined : resourceCache.get(geometry);
+                resource ??= nextResources.get(geometry);
+                if (resource === undefined) {
+                    const isSolid = deferred.isSolid(geometry);
+                    finalizeGeometry ??= createGeometryFinalizer(native(), limits, options);
+                    const finalized = finalizeGeometry(isSolid ? deferred.resolve(geometry) : geometry);
+                    resource = createResource(`s${sessionId}-g${++resourceVersion}`, finalized, isSolid || isImmutableMesh(geometry));
+                }
+                nextResources.set(geometry, resource);
+                const placement = capturePlacement(descriptor);
+                // World buffers belong to geometry and placement, independently of semantic part identity.
+                const placementKey = JSON.stringify([
+                    resource.public.id,
+                    placement.position,
+                    placement.rotation,
+                ]);
+                const placed = nextPlaced.get(placementKey) ??
+                    placedCache.get(placementKey) ??
+                    placeFinalizedGeometry(resource.geometry, placement.position, placement.rotation, options.meshValidation);
+                nextPlaced.set(placementKey, placed);
+                summary.add(placed);
+                worldParts.push(capturePart(descriptor.id, resource.public, placement, placed));
+            }
+            return {
+                snapshot: createSnapshot(worldParts, summary.finish(startedAt, builtAt), diagnostics, readDependencies()),
+                retainedValues: [
+                    ...nextResources.keys(),
+                    ...[...nextResources.values()].map((resource) => resource.geometry),
+                    ...nextPlaced.values(),
+                ],
+                commit() {
+                    // Raw mesh buffers can change even behind a frozen wrapper. Deduplicate them within
+                    // this capture, but only reuse proven immutable geometry in later revisions.
+                    resourceCache = new Map([...nextResources].filter(([, resource]) => resource.reusable));
+                    placedCache = nextPlaced;
+                },
+            };
+        },
+        clear() {
+            resourceCache.clear();
+            placedCache.clear();
+        },
+    };
+}