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

package/src/library/kernel-artifact-codec.ts

@@ -8,12 +8,31 @@ const decoder = new TextDecoder('utf-8', {fatal: true});
 // references. Native handles never escape their runtime; only BinTools bytes do.
 type Node = null | boolean | string | number | readonly [string, unknown];
 
+const binaryTypes: Record<
+  string,
+  new (buffer: ArrayBuffer, offset?: number, length?: number) => ArrayBufferView
+> = {
+  Int8Array,
+  Uint8Array,
+  Uint8ClampedArray,
+  Int16Array,
+  Uint16Array,
+  Int32Array,
+  Uint32Array,
+  Float32Array,
+  Float64Array,
+  BigInt64Array,
+  BigUint64Array,
+  DataView,
+};
+
 export function encodeKernelArtifact(
   signature: string,
   value: unknown,
 ): Uint8Array {
   const chunks: Uint8Array[] = [];
   let offset = 0;
+  const references = new Map<object, number>();
   function binary(kind: string, bytes: Uint8Array): Node {
     const node: Node = [kind, [offset, bytes.byteLength]];
     chunks.push(bytes);
@@ -32,21 +51,56 @@ export function encodeKernelArtifact(
       typeof value === 'boolean'
     )
       return value;
+    if (typeof value === 'bigint') return ['bigint', String(value)];
+    if (typeof value !== 'object')
+      throw new Error('Unsupported kernel artifact value');
+    const existing = references.get(value);
+    if (existing !== undefined) return ['reference', existing];
+    const id = references.size;
+    references.set(value, id);
+    return ['value', [id, encodeObject(value)]];
+  }
+  function encodeObject(value: object): Node {
     if (value instanceof Shape)
       return binary('shape', encodeShape(value as AnyShape));
-    if (value instanceof Float32Array || value instanceof Uint32Array) {
-      return binary(
-        value instanceof Float32Array ? 'float32' : 'uint32',
-        new Uint8Array(value.buffer, value.byteOffset, value.byteLength),
-      );
+    if (ArrayBuffer.isView(value)) {
+      if (!Object.hasOwn(binaryTypes, value.constructor.name))
+        throw new Error('Unsupported kernel artifact view');
+      return [
+        'view',
+        [
+          value.constructor.name,
+          encode(value.buffer),
+          value.byteOffset,
+          value instanceof DataView
+            ? value.byteLength
+            : (value as unknown as {length: number}).length,
+        ],
+      ];
     }
-    if (Array.isArray(value)) return ['array', value.map(encode)];
+    if (value instanceof ArrayBuffer)
+      return binary('ArrayBuffer', new Uint8Array(value));
+    if (value instanceof Date) return ['date', encode(value.getTime())];
+    if (value instanceof Map)
+      return [
+        'map',
+        [...value].map(([key, item]) => [encode(key), encode(item)]),
+      ];
+    if (value instanceof Set) return ['set', [...value].map(encode)];
+    if (Array.isArray(value))
+      return [
+        'array',
+        [
+          value.length,
+          Object.entries(value).map(([key, item]) => [key, encode(item)]),
+        ],
+      ];
     if (
-      typeof value === 'object' &&
-      Object.getPrototypeOf(value) === Object.prototype
+      Object.getPrototypeOf(value) === Object.prototype ||
+      Object.getPrototypeOf(value) === null
     ) {
       return [
-        'object',
+        Object.getPrototypeOf(value) === null ? 'record' : 'object',
         Object.entries(value).map(([key, item]) => [key, encode(item)]),
       ];
     }
@@ -81,23 +135,79 @@ export function decodeKernelArtifact<Value>(
   if (storedSignature !== signature)
     throw new Error('Kernel artifact signature mismatch');
   const shapes: AnyShape[] = [];
-  function decode(node: Node): unknown {
+  const references = new Map<number, unknown>();
+  function decode(node: Node, referenceId?: number): unknown {
+    const register = <T>(value: T): T => {
+      if (referenceId !== undefined) references.set(referenceId, value);
+      return value;
+    };
     if (!Array.isArray(node)) return node;
     const [kind, data] = node;
     switch (kind) {
+      case 'reference':
+        if (!references.has(data as number))
+          throw new Error('Invalid kernel artifact reference');
+        return references.get(data as number);
+      case 'value': {
+        const [id, value] = data as [number, Node];
+        return decode(value, id);
+      }
       case 'undefined':
         return undefined;
       case 'number':
         return Number(data);
+      case 'bigint':
+        return BigInt(data as string);
+      case 'date':
+        return register(new Date(decode(data as Node) as number));
+      case 'map': {
+        const map = register(new Map());
+        for (const [key, item] of data as [Node, Node][])
+          map.set(decode(key), decode(item));
+        return map;
+      }
+      case 'set': {
+        const set = register(new Set());
+        for (const item of data as Node[]) set.add(decode(item));
+        return set;
+      }
       case 'array':
-        return (data as Node[]).map(decode);
-      case 'object':
-        return Object.fromEntries(
-          (data as [string, Node][]).map(([key, item]) => [key, decode(item)]),
+      case 'record':
+      case 'object': {
+        const object = register(
+          kind === 'array'
+            ? new Array((data as [number, unknown])[0])
+            : kind === 'record'
+              ? Object.create(null)
+              : {},
         );
+        const entries = (
+          kind === 'array' ? (data as [number, unknown])[1] : data
+        ) as [string, Node][];
+        for (const [key, item] of entries)
+          Object.defineProperty(object, key, {
+            value: decode(item),
+            writable: true,
+            configurable: true,
+            enumerable: true,
+          });
+        return object;
+      }
+      case 'view': {
+        const [name, buffer, offset, length] = data as [
+          string,
+          Node,
+          number,
+          number,
+        ];
+        if (!Object.hasOwn(binaryTypes, name))
+          throw new Error('Invalid kernel artifact view');
+        return register(
+          new binaryTypes[name](decode(buffer) as ArrayBuffer, offset, length),
+        );
+      }
       case 'shape':
-      case 'float32':
-      case 'uint32': {
+      case 'ArrayBuffer': {
         const [offset, length] = data as number[];
         if (
           !Number.isSafeInteger(offset) ||
@@ -108,13 +218,12 @@ export function decodeKernelArtifact<Value>(
         ) {
           throw new Error('Invalid kernel artifact binary range');
         }
-        // Each retained array owns exactly its bytes, not the whole disk record.
+        // Each restored backing buffer owns its source bytes, not the disk record.
         const chunk = bytes.slice(start + offset, start + offset + length);
-        if (kind === 'float32') return new Float32Array(chunk.buffer);
-        if (kind === 'uint32') return new Uint32Array(chunk.buffer);
+        if (kind === 'ArrayBuffer') return register(chunk.buffer);
         const shape = decodeShape(chunk);
         shapes.push(shape);
-        return shape;
+        return register(shape);
       }
       default:
         throw new Error('Invalid kernel artifact node');

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;
@@ -31,6 +40,7 @@ export type KernelValueLifecycle<Value> = Readonly<{
 }>;
 
 type CacheEntry<Value> = Readonly<{
+  persistenceEligible: boolean;
   estimatedBytes: number;
   signature: string;
   value: Value;
@@ -38,11 +48,13 @@ type CacheEntry<Value> = Readonly<{
   release(value: Value): void;
 }>;
 
-export function createKernelOperationCache({
+export function createComputationCache({
   maximumBytes = 2 * 1024 ** 3,
+  minimumPersistenceMilliseconds = 1,
   nativeAllocatedBytes,
 }: {
   maximumBytes?: number;
+  minimumPersistenceMilliseconds?: number;
   nativeAllocatedBytes: () => number;
 }) {
   const entries = new Map<string, CacheEntry<unknown>>();
@@ -56,10 +68,23 @@ 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;
 
+  /** Adjust historical retention without invalidating the current model. */
+  function setKernelCacheBudget(bytes: number): void {
+    maximumBytes = bytes;
+    evictHistoricalEntries();
+  }
+
+  /** Apply to future computations without changing existing entries' admission. */
+  function setKernelCachePersistenceThreshold(milliseconds: number): void {
+    minimumPersistenceMilliseconds = milliseconds;
+  }
+
   /** The host accounts for in-flight inputs and all auxiliary native heaps. */
   function setKernelExternalBytes(bytes: number): void {
     externalBytes = bytes;
@@ -69,6 +94,7 @@ export function createKernelOperationCache({
   function setKernelArtifactStore(next: KernelArtifactStore | undefined): void {
     store = next;
     persisted.clear();
+    pendingPersistence.clear();
   }
 
   function accessStore<Result>(
@@ -93,60 +119,101 @@ export function createKernelOperationCache({
    */
   function beginKernelOperationEvaluation(
     checkCancelled?: () => void,
+    kind: 'model' | 'inspect' = 'model',
   ): () => void {
     const used = new Set<string>();
     currentEvaluation = {used, checkCancelled};
     return () => {
-      for (const id of retainedEvaluation) {
-        if (!used.has(id)) historicalEntries.set(id, entries.get(id)!);
+      flushPendingPersistence();
+      if (kind === 'model') {
+        for (const id of retainedEvaluation) {
+          if (!used.has(id)) historicalEntries.set(id, entries.get(id)!);
+        }
+        retainedEvaluation = used;
+      } else {
+        // Inspection owns temporary geometry, without replacing the model's
+        // retained working set or accumulating every previously inspected scene.
+        for (const id of used) {
+          if (!retainedEvaluation.has(id))
+            historicalEntries.set(id, entries.get(id)!);
+        }
       }
-      retainedEvaluation = used;
       currentEvaluation = undefined;
       evictHistoricalEntries();
       accessStore(store => store.flush());
     };
   }
 
-  /**
-   * 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 started = performance.now();
     const value = compute();
-    acceptKernelOperation(key, lifecycle, value);
+    const milliseconds = performance.now() - started;
+    acceptKernelOperation(key, lifecycle, value, milliseconds, 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));
           misses += 1;
           return undefined;
         }
-        cached = retainEntry(key, lifecycle, restored);
+        // Existing disk records have already been admitted; reading one must
+        // not reinterpret decode time as its original computation cost.
+        cached = retainEntry(key, lifecycle, restored, true);
         persistentHits += 1;
         persisted.add(id);
       }
@@ -159,7 +226,8 @@ 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 (cached.persistenceEligible && codec !== false)
+      persist(key, cached.value, codec, true);
     touchEntry(id, cached as CacheEntry<unknown>);
     return {id, value};
   }
@@ -169,6 +237,8 @@ export function createKernelOperationCache({
     key: KernelOperationKey,
     lifecycle: KernelValueLifecycle<Value>,
     value: Value,
+    milliseconds: number,
+    codec?: CacheCodec<Value> | false,
   ): void {
     const existing = entries.get(key.id);
     if (existing) {
@@ -184,28 +254,74 @@ export function createKernelOperationCache({
       lifecycle.release(value);
       throw error;
     }
-    const entry = retainEntry(key, lifecycle, retained);
-    persist(key, retained);
+    const entry = retainEntry(
+      key,
+      lifecycle,
+      retained,
+      milliseconds >= minimumPersistenceMilliseconds,
+    );
+    if (entry.persistenceEligible && 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>,
     retained: Value,
+    persistenceEligible: boolean,
   ): CacheEntry<Value> {
     const entry: CacheEntry<Value> = {
+      persistenceEligible,
       estimatedBytes:
         256 +
         estimateRetainedBytes(key.signature) +
@@ -244,8 +360,10 @@ export function createKernelOperationCache({
     estimatedJavaScriptBytes = 0;
     persistentHits = 0;
     persistentWrites = 0;
+    persistenceEncodeMilliseconds = 0;
     persistenceErrors = 0;
     persisted.clear();
+    pendingPersistence.clear();
   }
 
   function kernelOperationCacheStats() {
@@ -258,8 +376,10 @@ export function createKernelOperationCache({
       nativeAllocatedBytes: nativeAllocatedBytes(),
       maximumBytes,
       externalBytes,
+      pendingPersistenceBytes: store?.pendingWriteBytes ?? 0,
       persistentHits,
       persistentWrites,
+      persistenceEncodeMilliseconds,
       persistenceErrors,
     };
   }
@@ -267,7 +387,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 +402,41 @@ export function createKernelOperationCache({
   }
 
   return {
+    evaluateCachedArtifact,
     beginKernelOperationEvaluation,
-    evaluateKernelOperation,
     clearKernelOperationCache,
     kernelOperationCacheStats,
+    setKernelCacheBudget,
+    setKernelCachePersistenceThreshold,
     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,
+  setKernelCacheBudget,
+  setKernelCachePersistenceThreshold,
   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 +451,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

@@ -62,7 +62,11 @@ export function loftWithTopology(
       ruled,
       holes.map(wires => wires[0]),
     );
-    return booleanWithTopology(outer, inner, 'cut');
+    return booleanWithTopology(
+      {...outer, namespace: 'intermediate'},
+      {...inner, namespace: 'intermediate'},
+      'cut',
+    );
   } finally {
     inner?.shape.delete();
     outer?.shape.delete();
@@ -104,6 +108,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());
+}