@code3d/core 0.0.1-alpha.0 → 0.0.1-alpha.3

package/src/library/kernel-cache.ts

@@ -1,17 +1,21 @@
-import type {OpenCascadeInstance} from '@code3d/opencascade';
-import {getOC} from 'replicad';
-import {estimateRetainedBytes} from './retained-memory.js';
 import {
   decodeKernelArtifact,
   encodeKernelArtifact,
 } from './kernel-artifact-codec.js';
+import {estimateRetainedBytes} from './retained-memory.js';
 
 /** The host opens storage before synchronous evaluation and owns its lifetime. */
 export interface KernelArtifactStore {
+  /** Encoded writes retained by the host for the current working version. */
+  readonly pendingWriteBytes?: number;
   get(id: string): Uint8Array | undefined;
+  getMany(ids: readonly string[]): readonly (Uint8Array | undefined)[];
   set(id: string, bytes: Uint8Array): void;
   touch(id: string): boolean;
+  /** Update access order together, returning existence in the same order. */
+  touchMany(ids: readonly string[]): readonly boolean[];
   delete(id: string): void;
+  /** Schedule persistence; hosts may complete disk I/O in the background. */
   flush(): void;
 }
 
@@ -23,6 +27,11 @@ export type KernelArtifact<Value> = Readonly<{
   value: Value;
 }>;
 
+export type CacheCodec<Value> = Readonly<{
+  encoder(value: Value): Uint8Array;
+  decoder(bytes: Uint8Array): Value;
+}>;
+
 export type KernelValueLifecycle<Value> = Readonly<{
   estimateBytes(value: Value): number;
   retain(value: Value): Value;
@@ -38,7 +47,7 @@ type CacheEntry<Value> = Readonly<{
   release(value: Value): void;
 }>;
 
-export function createKernelOperationCache({
+export function createComputationCache({
   maximumBytes = 2 * 1024 ** 3,
   nativeAllocatedBytes,
 }: {
@@ -56,8 +65,10 @@ export function createKernelOperationCache({
   let store: KernelArtifactStore | undefined;
   let persistentHits = 0;
   let persistentWrites = 0;
+  let persistenceEncodeMilliseconds = 0;
   let persistenceErrors = 0;
   const persisted = new Set<string>();
+  const pendingPersistence = new Map<string, () => Uint8Array>();
   let externalBytes = 0;
 
   /** The host accounts for in-flight inputs and all auxiliary native heaps. */
@@ -69,6 +80,7 @@ export function createKernelOperationCache({
   function setKernelArtifactStore(next: KernelArtifactStore | undefined): void {
     store = next;
     persisted.clear();
+    pendingPersistence.clear();
   }
 
   function accessStore<Result>(
@@ -97,6 +109,7 @@ export function createKernelOperationCache({
     const used = new Set<string>();
     currentEvaluation = {used, checkCancelled};
     return () => {
+      flushPendingPersistence();
       for (const id of retainedEvaluation) {
         if (!used.has(id)) historicalEntries.set(id, entries.get(id)!);
       }
@@ -107,39 +120,65 @@ export function createKernelOperationCache({
     };
   }
 
-  /**
-   * Reuses one complete, deterministic kernel operation. Arguments describe
-   * scalar semantics; inputs carry the content identities of prior operations.
-   * The lifecycle keeps the retained value independent from each disposable use.
-   */
-  function evaluateKernelOperation<Value>(
-    operation: string,
-    arguments_: readonly KernelKeyPart[],
-    inputs: readonly KernelArtifact<unknown>[],
+  function evaluateCachedArtifact<Value>(
+    key: KernelOperationKey,
     lifecycle: KernelValueLifecycle<Value>,
     compute: () => Value,
+    codec?: CacheCodec<Value> | false,
   ): KernelArtifact<Value> {
-    const key = kernelOperationKey(operation, arguments_, inputs);
-    const cached = findKernelOperation(key, lifecycle);
-    if (cached) return cached;
+    const hit = findKernelOperation(key, lifecycle, codec);
+    if (hit) return hit;
     const value = compute();
-    acceptKernelOperation(key, lifecycle, value);
+    acceptKernelOperation(key, lifecycle, value, codec);
     return {id: key.id, value};
   }
 
   function findKernelOperation<Value>(
     key: KernelOperationKey,
     lifecycle: KernelValueLifecycle<Value>,
+    codec?: CacheCodec<Value> | false,
+  ): KernelArtifact<Value> | undefined {
+    return lookup(key, lifecycle, codec, () =>
+      accessStore(store => store.get(key.id)),
+    );
+  }
+
+  function findKernelOperations<Value>(
+    keys: readonly KernelOperationKey[],
+    lifecycle: KernelValueLifecycle<Value>,
+    codec?: CacheCodec<Value> | false,
+  ): readonly (KernelArtifact<Value> | undefined)[] {
+    currentEvaluation?.checkCancelled?.();
+    const missing =
+      codec === false ? [] : keys.filter(key => !entries.has(key.id));
+    const bytes = missing.length
+      ? accessStore(store => store.getMany(missing.map(key => key.id)))
+      : undefined;
+    const restored = new Map(
+      missing.map((key, index) => [key.id, bytes?.[index]]),
+    );
+    return keys.map(key =>
+      lookup(key, lifecycle, codec, () => restored.get(key.id)),
+    );
+  }
+
+  function lookup<Value>(
+    key: KernelOperationKey,
+    lifecycle: KernelValueLifecycle<Value>,
+    codec: CacheCodec<Value> | false | undefined,
+    read: () => Uint8Array | undefined,
   ): KernelArtifact<Value> | undefined {
     currentEvaluation?.checkCancelled?.();
     const {id, signature} = key;
     let cached = entries.get(id) as CacheEntry<Value> | undefined;
-    if (!cached) {
-      const bytes = accessStore(store => store.get(id));
+    if (!cached && codec !== false) {
+      const bytes = read();
       if (bytes) {
         let restored: Value;
         try {
-          restored = decodeKernelArtifact<Value>(bytes, signature);
+          restored = codec
+            ? codec.decoder(decodeKernelArtifact<Uint8Array>(bytes, signature))
+            : decodeKernelArtifact<Value>(bytes, signature);
         } catch {
           persistenceErrors += 1;
           accessStore(store => store.delete(id));
@@ -159,7 +198,7 @@ export function createKernelOperationCache({
       throw new Error(`Kernel operation cache identity collision: ${id}`);
     hits += 1;
     const value = cached.instantiate(cached.value);
-    persist(key, cached.value);
+    if (codec !== false) persist(key, cached.value, codec, true);
     touchEntry(id, cached as CacheEntry<unknown>);
     return {id, value};
   }
@@ -169,6 +208,7 @@ export function createKernelOperationCache({
     key: KernelOperationKey,
     lifecycle: KernelValueLifecycle<Value>,
     value: Value,
+    codec?: CacheCodec<Value> | false,
   ): void {
     const existing = entries.get(key.id);
     if (existing) {
@@ -185,21 +225,59 @@ export function createKernelOperationCache({
       throw error;
     }
     const entry = retainEntry(key, lifecycle, retained);
-    persist(key, retained);
+    if (codec !== false) persist(key, retained, codec);
     touchEntry(key.id, entry as CacheEntry<unknown>);
   }
 
-  function persist(key: KernelOperationKey, value: unknown): void {
+  function persist<Value>(
+    key: KernelOperationKey,
+    value: Value,
+    codec?: CacheCodec<Value>,
+    defer = false,
+  ): void {
     if (!store || persisted.has(key.id)) return;
+    const encode = () => {
+      const started = performance.now();
+      try {
+        return encodeKernelArtifact(
+          key.signature,
+          codec ? Uint8Array.from(codec.encoder(value)) : value,
+        );
+      } finally {
+        persistenceEncodeMilliseconds += performance.now() - started;
+      }
+    };
+    if (defer && currentEvaluation) {
+      pendingPersistence.set(key.id, encode);
+      return;
+    }
     accessStore(store => {
-      if (!store.touch(key.id)) {
-        store.set(key.id, encodeKernelArtifact(key.signature, value));
+      // A completed computation follows a miss; write it without another lookup.
+      if (!defer || !store.touch(key.id)) {
+        store.set(key.id, encode());
         persistentWrites += 1;
       }
       persisted.add(key.id);
     });
   }
 
+  /** Memory hits need one transaction, while newly computed work is saved immediately. */
+  function flushPendingPersistence(): void {
+    if (!pendingPersistence.size) return;
+    accessStore(store => {
+      const ids = [...pendingPersistence.keys()];
+      const present = store.touchMany(ids);
+      ids.forEach((id, index) => {
+        if (!present[index]) {
+          store.set(id, pendingPersistence.get(id)!());
+          persistentWrites += 1;
+        }
+        persisted.add(id);
+      });
+    });
+    pendingPersistence.clear();
+  }
+
   function retainEntry<Value>(
     key: KernelOperationKey,
     lifecycle: KernelValueLifecycle<Value>,
@@ -244,8 +322,10 @@ export function createKernelOperationCache({
     estimatedJavaScriptBytes = 0;
     persistentHits = 0;
     persistentWrites = 0;
+    persistenceEncodeMilliseconds = 0;
     persistenceErrors = 0;
     persisted.clear();
+    pendingPersistence.clear();
   }
 
   function kernelOperationCacheStats() {
@@ -258,8 +338,10 @@ export function createKernelOperationCache({
       nativeAllocatedBytes: nativeAllocatedBytes(),
       maximumBytes,
       externalBytes,
+      pendingPersistenceBytes: store?.pendingWriteBytes ?? 0,
       persistentHits,
       persistentWrites,
+      persistenceEncodeMilliseconds,
       persistenceErrors,
     };
   }
@@ -267,7 +349,10 @@ export function createKernelOperationCache({
   function evictHistoricalEntries(): void {
     while (
       historicalEntries.size &&
-      nativeAllocatedBytes() + estimatedJavaScriptBytes + externalBytes >
+      nativeAllocatedBytes() +
+        estimatedJavaScriptBytes +
+        externalBytes +
+        (store?.pendingWriteBytes ?? 0) >
         maximumBytes
     ) {
       const [id, entry] = historicalEntries.entries().next().value!;
@@ -279,29 +364,37 @@ export function createKernelOperationCache({
   }
 
   return {
+    evaluateCachedArtifact,
     beginKernelOperationEvaluation,
-    evaluateKernelOperation,
     clearKernelOperationCache,
     kernelOperationCacheStats,
     setKernelArtifactStore,
     findKernelOperation,
+    findKernelOperations,
     acceptKernelOperation,
     setKernelExternalBytes,
   };
 }
 
+let nativeMemoryCounter = () => 0;
+
+/** The installed backend supplies native accounting; pure caches need no kernel. */
+export function setKernelNativeMemoryCounter(read: () => number): void {
+  nativeMemoryCounter = read;
+}
+
 export const {
+  evaluateCachedArtifact,
   beginKernelOperationEvaluation,
-  evaluateKernelOperation,
   clearKernelOperationCache,
   kernelOperationCacheStats,
   setKernelArtifactStore,
   findKernelOperation,
+  findKernelOperations,
   acceptKernelOperation,
   setKernelExternalBytes,
-} = createKernelOperationCache({
-  nativeAllocatedBytes: () =>
-    (getOC() as OpenCascadeInstance).Code3dMemory.AllocatedBytes(),
+} = createComputationCache({
+  nativeAllocatedBytes: () => nativeMemoryCounter(),
 });
 
 export type KernelOperationKey = Readonly<{id: string; signature: string}>;
@@ -316,16 +409,17 @@ export function kernelOperationKey(
     arguments_,
     inputs.map(input => input.id),
   ]);
-  return {id: contentId(signature), signature};
+  return {id: kernelContentId(signature), signature};
 }
 
-function contentId(value: string): string {
+export function kernelContentId(value: string | Uint8Array): string {
   let first = 0x811c9dc5;
   let second = 0x9e3779b9;
   let third = 0x85ebca6b;
   let fourth = 0xc2b2ae35;
   for (let index = 0; index < value.length; index += 1) {
-    const code = value.charCodeAt(index);
+    const code =
+      typeof value === 'string' ? value.charCodeAt(index) : value[index];
     first = Math.imul(first ^ code, 0x01000193);
     second = Math.imul(second ^ code, 0x27d4eb2d);
     third = Math.imul(third ^ code, 0x165667b1);

package/src/library/loft.ts

@@ -104,6 +104,10 @@ function loftContoursWithTopology(
       builder.SetMutableInput(false);
       for (const wire of wires) builder.AddWire(wire.wrapped);
       builder.Build();
+      if (!builder.IsDone())
+        throw new Error(
+          'Could not construct a solid loft through these sections. Adjust their positions, orientations, or profiles.',
+        );
     }
     result = castOwnedShape3D(builder.Shape());
     caps[0] = castOwnedShape(builder.FirstShape()) as Face;

package/src/library/material.ts

@@ -6,7 +6,7 @@ import {
   type SerializedImage,
   type Texture,
   type TypedArray,
-} from './three.js';
+} from 'three';
 import {parseModelColor} from './model-color.js';
 
 /** A color selects the default material for each geometry kind. */
@@ -52,14 +52,13 @@ export function captureModelMaterial(
     }
   }
   if ('isShaderMaterial' in input) {
-    const shader = input as import('./three.js').ShaderMaterial;
+    const shader = input as import('three').ShaderMaterial;
     if (
       shader.uniformsGroups.length ||
       shader.index0AttributeName !== undefined ||
       JSON.stringify(shader.defaultAttributeValues) !==
         JSON.stringify(
-          (restored as import('./three.js').ShaderMaterial)
-            .defaultAttributeValues,
+          (restored as import('three').ShaderMaterial).defaultAttributeValues,
         )
     ) {
       throw new Error(

package/src/library/open-cascade.ts

@@ -0,0 +1,13 @@
+import type {OpenCascadeInstance} from '@code3d/opencascade';
+import {setOC} from 'replicad';
+import {
+  clearKernelOperationCache,
+  setKernelNativeMemoryCounter,
+} from './kernel-cache.js';
+
+/** Install the backend and its memory accounting for Node and hosted runtimes. */
+export function installOpenCascade(openCascade: OpenCascadeInstance): void {
+  clearKernelOperationCache();
+  setOC(openCascade);
+  setKernelNativeMemoryCounter(() => openCascade.Code3dMemory.AllocatedBytes());
+}

package/src/library/replicad.ts

@@ -1,5 +1,5 @@
 import * as replicadModule from 'replicad';
-import {modelFromReplicadSolid} from './runtime.js';
+import {primitiveConstructor} from './runtime.js';
 import {castOwnedShape} from './kernel-shapes.js';
 import type {SolidModel} from './index.js';
 import type {Shape3D} from 'replicad';
@@ -29,12 +29,12 @@ export const replicad: Replicad = Object.freeze({
 
 /**
  * Defines a synchronous model constructor with the builder's parameters.
- * The builder runs on every call and transfers ownership of its returned solid
- * to code3d. Intermediate shapes remain the builder's responsibility.
+ * Reuses deterministic geometry by arguments; pass changing captured state as
+ * explicit parameters. Each invocation creates a fresh model. The builder
+ * transfers its returned solid to code3d and owns its intermediate shapes.
  */
 export function definePrimitive<
   Builder extends (...arguments_: never[]) => Shape3D,
 >(build: Builder): (...arguments_: Parameters<Builder>) => SolidModel {
-  return (...arguments_: Parameters<Builder>) =>
-    modelFromReplicadSolid(build(...arguments_));
+  return primitiveConstructor(build);
 }

package/src/library/retained-memory.ts

@@ -12,7 +12,12 @@ export function estimateRetainedBytes(value: unknown): number {
     seen.add(value);
     if (ArrayBuffer.isView(value)) return 64 + visit(value.buffer);
     if (value instanceof ArrayBuffer) return 32 + value.byteLength;
-    const values = Object.values(value);
+    const values =
+      value instanceof Map
+        ? [...value].flat()
+        : value instanceof Set
+          ? [...value]
+          : Object.values(value);
     return (
       32 +
       values.length * 8 +