@selvajs/compute 3.1.0-beta.1 → 3.1.0-beta.10

package/dist/grasshopper.d.cts

@@ -1,12 +1,56 @@
-import { R as RhinoComputeError, C as ComputeServerStats, F as FileBaseInfo } from './handle-files-9pkEgDIp.cjs';
-export { b as FileData, P as ProcessedFile, d as downloadFileData, e as extractFilesFromComputeResponse } from './handle-files-9pkEgDIp.cjs';
-import { R as RetryPolicy, C as ComputeConfig } from './types-ChF690kY.cjs';
-export { a as RhinoModelUnit } from './types-ChF690kY.cjs';
-import { f as GrasshopperComputeResponse, a as DataTree, e as GrasshopperComputeConfig, g as GrasshopperParsedIO, h as GrasshopperParsedIORaw, M as MeshExtractionOptions, k as InputParamSchema, j as InputParam, b as DataTreeDefault, c as DataTreePath } from './types-DK2-skCK.cjs';
-export { B as BooleanInputType, D as DataItem, d as DefaultValue, F as FileInputType, G as GeometryInputType, i as GrasshopperRequestSchema, I as InnerTreeData, N as NumericInputType, O as OutputParamSchema, l as OutputType, T as TextInputType, V as ValueListInputType } from './types-DK2-skCK.cjs';
+import { R as RhinoComputeError, C as ComputeServerStats, F as FileBaseInfo } from './handle-files-BISo_wob.cjs';
+export { b as FileData, P as ProcessedFile, d as downloadFileData, e as extractFilesFromComputeResponse } from './handle-files-BISo_wob.cjs';
+import { R as RetryPolicy, C as ComputeConfig } from './types-BGhtYxZ-.cjs';
+export { a as RhinoModelUnit } from './types-BGhtYxZ-.cjs';
+import { f as GrasshopperComputeResponse, a as DataTree, e as GrasshopperComputeConfig, g as GrasshopperParsedIO, h as GrasshopperParsedIORaw, m as MeshExtractionOptions, k as InputParamSchema, j as InputParam, b as DataTreeDefault, c as DataTreePath } from './types-C8XWc4Ab.cjs';
+export { B as BooleanInputType, D as DataItem, d as DefaultValue, F as FileInputType, G as GeometryInputType, i as GrasshopperRequestSchema, I as InnerTreeData, N as NumericInputType, O as OutputParamSchema, l as OutputType, T as TextInputType, V as ValueListInputType } from './types-C8XWc4Ab.cjs';
 import * as THREE from 'three';
 import 'rhino3dm';
 
+/**
+ * By-reference definition form for solves.
+ *
+ * Lets a caller that already knows a definition's identity (e.g. a stored
+ * version's UUID) schedule solves without materializing the multi-MB bytes:
+ * cache keys and the server-pointer map are derived from `key` alone, and
+ * `load()` is only called when an upload is genuinely unavoidable (first solve
+ * of a definition, or a server-side pointer miss).
+ */
+/**
+ * A definition identified by a stable key, with bytes materialized on demand.
+ *
+ * **Immutability contract — read this before constructing one.** `key` must
+ * identify IMMUTABLE bytes: every `load()` for a given `key` must return the
+ * same content, forever. All caching (the scheduler's result cache, the
+ * server-pointer map, and any durable cache built on these keys) trusts the
+ * key as the definition's identity WITHOUT looking at the bytes. If two
+ * different byte contents ever share a key, cached solves from one are served
+ * for the other — silent cache poisoning with no diagnostic. Use an identity
+ * that can never be reused for different content (e.g. a version UUID), never
+ * a mutable name or path.
+ */
+interface DefinitionRef {
+    /**
+     * Identity of immutable bytes (e.g. a version UUID). Two different byte
+     * contents must never share a key — cache poisoning otherwise.
+     */
+    key: string;
+    /**
+     * Materialize the bytes. Called ONLY when an upload is unavoidable — inside
+     * the solve execution, so it counts toward the solve's abort semantics.
+     */
+    load: () => Promise<Uint8Array>;
+}
+/**
+ * Every definition form accepted by the solve entry points:
+ * - a URL, base64 string, or plain string (content-hashed for caching)
+ * - raw `.gh` bytes (content-hashed)
+ * - a {@link DefinitionRef} (identity-keyed; bytes loaded lazily)
+ */
+type SolveDefinition = string | Uint8Array | DefinitionRef;
+/** Narrow a {@link SolveDefinition} to the by-reference form. */
+declare function isDefinitionRef(definition: SolveDefinition): definition is DefinitionRef;
+
 /**
  * Scheduling mode — controls how concurrent `solve()` calls interact.
  *
@@ -23,10 +67,36 @@ interface CacheOptions {
     maxEntries?: number;
     /** Time-to-live in ms. Set to `0` for no expiry (default). */
     ttlMs?: number;
+    /**
+     * Cache responses that carry Grasshopper `errors`. Default `true`: an
+     * errored solve is a valid, deterministic result — definitions raise GH
+     * errors by design (guarded components, validation branches), so replaying
+     * one from cache is correct. Set `false` for parity with Rhino's opt-in
+     * `cacheerroredsolves` server flag, e.g. when a definition's errors are
+     * transient (external data sources) rather than functions of the inputs.
+     */
+    cacheErroredSolves?: boolean;
 }
 interface SolveSchedulerOptions {
     mode?: SchedulerMode;
     maxConcurrent?: number;
+    /**
+     * Backpressure — cap on how many calls may wait in the FIFO queue (i.e.
+     * excluding the ones already in flight). When the queue is full, a new
+     * `solve()` is shed immediately with `code: QUEUE_FULL` (retryable, meant to
+     * map to HTTP 503 + Retry-After) instead of piling up unbounded. Bounds the
+     * miss path under load. Only applies to `queue` / `parallel` modes —
+     * `latest-wins` has an intrinsic depth of 1. Default: unbounded.
+     */
+    maxQueueDepth?: number;
+    /**
+     * Backpressure — max time (ms) a call may sit queued before it starts
+     * executing. If it's still waiting after this long it's shed with
+     * `code: QUEUE_TIMEOUT` rather than burning compute on a stale request.
+     * Bounds tail latency. Only applies to `queue` / `parallel` modes. Default:
+     * no deadline.
+     */
+    queueWaitMs?: number;
     timeoutMs?: number;
     retry?: RetryPolicy;
     /** Enable response caching keyed by hash of (definition, dataTree). */
@@ -81,7 +151,7 @@ type SolveResult = {
  * Adapter for the underlying solve function. Lets the scheduler be tested
  * without a real Compute server, and decouples it from the client class.
  */
-type SolveExecutor = (definition: string | Uint8Array, dataTree: DataTree[], config: GrasshopperComputeConfig) => Promise<GrasshopperComputeResponse>;
+type SolveExecutor = (definition: SolveDefinition, dataTree: DataTree[], config: GrasshopperComputeConfig) => Promise<GrasshopperComputeResponse>;
 /**
  * Cache-key-aware executor. When `cacheKey` is provided, the executor solves by
  * reference (`pointer: cacheKey`) and falls back to a full upload on a server
@@ -93,7 +163,7 @@ type SolveExecutor = (definition: string | Uint8Array, dataTree: DataTree[], con
  * Supplied by the client (which owns the solve primitives); the scheduler stays
  * decoupled from the transport.
  */
-type CacheKeyExecutor = (definition: string | Uint8Array, dataTree: DataTree[], cacheKey: string | null, config: GrasshopperComputeConfig) => Promise<{
+type CacheKeyExecutor = (definition: SolveDefinition, dataTree: DataTree[], cacheKey: string | null, config: GrasshopperComputeConfig) => Promise<{
     response: GrasshopperComputeResponse;
     cacheKey: string | null;
     missed: boolean;
@@ -104,6 +174,7 @@ type CacheKeyExecutor = (definition: string | Uint8Array, dataTree: DataTree[],
  * Sits between your application code and the underlying compute call,
  * adding:
  * - Configurable scheduling (latest-wins for sliders, queue for jobs)
+ * - Backpressure (bounded queue depth + queue-wait deadline) for the miss path
  * - In-flight cancellation (per-call signal + cancelAll)
  * - Optional response caching for repeated inputs
  * - Lifecycle hooks for UI indicators (start / settle / superseded)
@@ -134,11 +205,14 @@ declare class SolveScheduler {
     private readonly baseConfig;
     private readonly mode;
     private readonly maxConcurrent;
+    private readonly maxQueueDepth;
+    private readonly queueWaitMs;
     private readonly timeoutMs;
     private readonly retry;
     private readonly cacheEnabled;
     private readonly cacheMax;
     private readonly cacheTtl;
+    private readonly cacheErroredSolves;
     private readonly cache;
     /** Optional cache-key-aware executor and whether server-def-cache reuse is on. */
     private readonly cacheKeyExecutor?;
@@ -155,6 +229,10 @@ declare class SolveScheduler {
     private _lastResult;
     private _lastError;
     private _lastDurationMs;
+    /** Ordinal handed to each solve() call. */
+    private solveSeq;
+    /** seq of the solve that last wrote _lastResult/_lastError — see writeLastState. */
+    private lastStateSeq;
     private disposed;
     constructor(executor: SolveExecutor, baseConfig: GrasshopperComputeConfig, options?: SolveSchedulerOptions, cacheKeyExecutor?: CacheKeyExecutor);
     get isSolving(): boolean;
@@ -164,6 +242,7 @@ declare class SolveScheduler {
     get lastResult(): GrasshopperComputeResponse | null;
     get lastError(): RhinoComputeError | null;
     get lastDurationMs(): number | null;
+    /** Subscribe to state changes. */
     subscribe(listener: () => void): () => void;
     private notify;
     /**
@@ -174,18 +253,59 @@ declare class SolveScheduler {
      *   newer values arrived (latest-wins mode).
      * - Rejects with `code: ErrorCodes.ABORTED` when the call was canceled via
      *   caller-supplied signal or `cancelAll()`.
+     * - Rejects with `code: ErrorCodes.QUEUE_FULL` when `maxQueueDepth` is set and
+     *   the queue was already full (backpressure; `statusCode: 503`).
+     * - Rejects with `code: ErrorCodes.QUEUE_TIMEOUT` when `queueWaitMs` is set and
+     *   the call sat queued longer than that before starting (`statusCode: 503`).
      *
-     * Caller-supplied `signal` cancels just this call (rejects with `ABORTED`).
+     * Caller-supplied `signal` cancels just this call (rejects with `ABORTED`) —
+     * including while the call is still queued, before execution starts.
+     *
+     * A {@link DefinitionRef} definition is keyed by its `key` (result cache and
+     * server-pointer map alike) without materializing bytes — `load()` runs only
+     * when an upload is unavoidable. Its immutability contract is trusted here:
+     * a reused key serves the other content's cached solve.
+     *
+     * Responses served from the cache (and via `lastResult`) are shared objects,
+     * not copies — treat them as immutable. Mutating one poisons every later
+     * cache hit for that key.
      */
-    solve(definition: string | Uint8Array, dataTree: DataTree[], options?: {
+    solve(definition: SolveDefinition, dataTree: DataTree[], options?: {
         signal?: AbortSignal;
     }): Promise<GrasshopperComputeResponse>;
+    /**
+     * Record last-result state, but only if no newer solve has written since —
+     * a slow solve settling late must not overwrite the state a newer solve
+     * (or cache hit) already published.
+     */
+    private writeLastState;
+    /** latest-wins: supersede the pending item and abort everything in flight. */
+    private supersedeCurrent;
+    /** Settle a still-queued item as ABORTED and remove it from its queue. */
+    private abortQueuedItem;
+    /**
+     * Backpressure: settle an incoming item as QUEUE_FULL without ever enqueuing
+     * it. The structured context lets an HTTP layer map it to 503 + Retry-After.
+     */
+    private shedAsQueueFull;
+    /**
+     * Arm the queue-wait deadline for an item about to be queued. If the item is
+     * still waiting when it fires, it's shed as QUEUE_TIMEOUT and removed from the
+     * queue. Cleared on execute/settle via {@link clearQueueWaitTimer}.
+     */
+    private armQueueWaitTimer;
+    /** Clear a queued item's wait-deadline timer, if one is pending. */
+    private clearQueueWaitTimer;
     private enqueue;
     private execute;
     /**
      * Run the solve, using the server-definition-cache fast path when it's
      * enabled and the definition is reusable. Learns/updates the definition's
      * server cache key from the result so later solves can reference it.
+     *
+     * `definitionHash` is the {@link hashDefinition} result already computed at
+     * `solve()` entry — threaded through rather than recomputed, so each solve
+     * pays exactly one linear pass over the definition (issue 57).
      */
     private runExecutor;
     private drainNext;
@@ -212,6 +332,8 @@ declare class SolveScheduler {
      * @returns `true` if this call settled the item; `false` if it was already settled.
      */
     private settleSuccess;
+    /** Detach the queued-phase abort listener, if one is still attached. */
+    private removeQueuedAbortHandler;
     private isAbortLikeError;
     private normalizeExecutionError;
     /** Cancel everything — in-flight and pending. */
@@ -295,9 +417,14 @@ declare class GrasshopperClient {
      *
      * @throws {RhinoComputeError} with code INVALID_INPUT if definition is empty
      * @throws {RhinoComputeError} with code NETWORK_ERROR if server is offline
-     * @throws {RhinoComputeError} with code COMPUTATION_ERROR if computation fails
+     * @throws {RhinoComputeError} with code COMPUTATION_ERROR if computation fails.
+     *   On a partial-success response (some outputs computed, some errored) the
+     *   error's `context.values` carries the outputs that did compute — pass
+     *   `{ values } as GrasshopperComputeResponse` to the response processors to
+     *   render them. `context.inputSummary` describes the inputs (param names,
+     *   item counts, byte sizes) without pinning the full data tree.
      */
-    solve(definition: string | Uint8Array, dataTree: DataTree[], options?: SolveOptions): Promise<GrasshopperComputeResponse>;
+    solve(definition: SolveDefinition, dataTree: DataTree[], options?: SolveOptions): Promise<GrasshopperComputeResponse>;
     /**
      * Create a scheduler bound to this client. Use a scheduler for any UI surface
      * that fires solves frequently (sliders, live editors) or that needs cancel
@@ -344,6 +471,14 @@ interface GetValuesOptions {
 }
 interface GetValuesResult<T = ParsedContext> {
     values: T;
+    /**
+     * Free every rhino3dm WASM object decoded into `values`. When a `rhino`
+     * instance was passed, decoded geometry lives on the WASM heap and is never
+     * garbage-collected — call this once the values are consumed, or the heap
+     * grows monotonically across solves. Idempotent; a no-op when nothing was
+     * decoded. `values` must not be used after disposal.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -371,10 +506,6 @@ declare class GrasshopperResponseProcessor {
      * const { values } = processor.getValues();
      * ```
      *
-     * @example
-     * ```ts
-     * const { values } = processor.getValues(true); // keyed by param ID
-     * ```
      */
     getValues<T = ParsedContext>(byId?: boolean, options?: GetValuesOptions): GetValuesResult<T>;
     /**
@@ -414,11 +545,6 @@ declare class GrasshopperResponseProcessor {
      * ```
      */
     extractMeshesFromResponse(options?: MeshExtractionOptions): Promise<THREE.Object3D<THREE.Object3DEventMap>[]>;
-    /**
-     * Raw file entries packaged in the response (textures, JSON, CAD exports, …).
-     * Produced by the Selva **Block to File** / **Geometry To File** components on
-     * the VektorNode rhino.compute branch.
-     */
     private getFileData;
     /**
      * Download all files generated by Grasshopper, optionally including
@@ -443,6 +569,57 @@ declare class GrasshopperResponseProcessor {
     getAndDownloadFiles(folderName: string, additionalFiles?: FileBaseInfo[] | FileBaseInfo | null): Promise<void>;
 }
 
+/**
+ * Stable hashing for solve deduplication and caching.
+ *
+ * The public keying surface here — {@link stableStringify}, {@link hashDefinition},
+ * {@link hashSolveInput} — is exported from the package barrel so a durable
+ * (app-layer) cache or a pre-solved bundle viewer can reproduce the *exact*
+ * canonicalize-and-hash path the scheduler's in-process cache uses. Key parity
+ * across the two layers is a correctness requirement: a durable-cache key that
+ * canonicalizes even slightly differently would miss every entry the scheduler
+ * wrote (harmless) or, worse, collide differently (not). The FNV plumbing
+ * (`fnv1a`/`fnv1aBytes`) and the pre-hashed-definition fast path
+ * (`hashSolveInputForDefinition`) stay internal.
+ */
+
+/**
+ * Deterministic stringify with sorted keys. {a:1,b:2} and {b:2,a:1} produce
+ * the same string. Safely handles circular references and non-finite numbers.
+ *
+ * The output is a cache key, so the invariant that matters is: two payloads
+ * that serialize differently on the wire must stringify differently here
+ * (false misses are harmless; false hits serve the wrong cached solve).
+ */
+declare function stableStringify(value: unknown): string;
+/**
+ * Hash definition and data tree into a stable cache key.
+ *
+ * The definition is the *identity* of what we solve, so a binary definition is
+ * hashed over its full content (`fnv1aBytes`) — a length-only or sampled key
+ * would let two different `.gh` files collide and serve one's cached solve for
+ * the other. `.gh` files are small enough that a single linear pass is
+ * negligible. A {@link DefinitionRef} is keyed by its `key` alone — the
+ * caller-declared identity of immutable bytes — so no bytes are materialized
+ * or hashed at all.
+ *
+ * The key keeps the definition and tree hashes as separate parts rather than
+ * collapsing them into one 32-bit hash: a single FNV pass over the pair would
+ * birthday-collide quadratically in cache size, while requiring both 32-bit
+ * parts (plus lengths) to collide at once makes that negligible.
+ */
+declare function hashSolveInput(definition: SolveDefinition, dataTree: unknown): string;
+/**
+ * Stable identity of a definition alone (no inputs) — used to key the
+ * server-cache-key map so the same definition reuses its `pointer` across solves
+ * with different inputs. Same full-content hashing as {@link hashSolveInput}: a
+ * binary definition is hashed over all its bytes so two distinct `.gh` files of
+ * equal length can't share a cache key. A {@link DefinitionRef} is keyed by its
+ * `key` verbatim (refs are short identities like UUIDs, safe as Map keys) —
+ * its immutability contract makes the key equivalent to a content hash.
+ */
+declare function hashDefinition(definition: SolveDefinition): string;
+
 /**
  * Runs a Rhino Compute job using the provided tree prototypes and Grasshopper definition.
  *
@@ -454,6 +631,7 @@ declare class GrasshopperResponseProcessor {
  *   - A base64-encoded string of the .gh file
  *   - A plain string (will be base64-encoded)
  *   - A Uint8Array of the .gh file (will be base64-encoded)
+ *   - A `DefinitionRef` (bytes are loaded via `ref.load()` for the upload)
  * @param config - Compute configuration (server URL, API key, etc. along with optional timeout, units, etc.)
  * @returns An object containing the compute result and extracted file data.
  *
@@ -468,15 +646,23 @@ declare class GrasshopperResponseProcessor {
  * const fileData = new Uint8Array([...]);
  * await solveGrasshopperDefinition(trees, fileData, config);
  */
-declare function solveGrasshopperDefinition(dataTree: DataTree[], definition: string | Uint8Array, config: GrasshopperComputeConfig): Promise<GrasshopperComputeResponse>;
+declare function solveGrasshopperDefinition(dataTree: DataTree[], definition: SolveDefinition, config: GrasshopperComputeConfig): Promise<GrasshopperComputeResponse>;
 
 /**
  * Fetches raw input/output schemas from a Grasshopper definition.
- * Returns unprocessed data exactly as received from the Rhino Compute API (camelCased).
+ *
+ * "Raw" means no per-type parsing (no default coercion, no discriminated-union
+ * typing) — but NOT byte-for-byte wire data. The response IS normalized:
+ * per-param field KEYS are canonicalized to camelCase across server branches
+ * ({@link normalizeInputSchema} / {@link normalizeOutputSchema}, with honest
+ * fallbacks for missing required fields), missing/non-array `inputs`/`outputs`
+ * coerce to `[]`, and server load diagnostics surface as
+ * `loadWarnings`/`loadErrors` (coerced to strings). Field VALUES — notably
+ * `default` and the `values` dropdown-label map — pass through verbatim.
  *
  * @param definition - The Grasshopper definition (URL, base64 string, or Uint8Array)
  * @param config - Compute configuration (server URL, API key, etc.)
- * @returns Raw inputs and outputs with no type processing
+ * @returns Key-normalized inputs and outputs with no per-type processing
  * @throws {RhinoComputeError} If fetch fails or response is invalid
  *
  * @public Use `fetchParsedDefinitionIO()` for processed, type-safe inputs
@@ -655,17 +841,19 @@ declare class TreeBuilder {
      * - Use with `InnerTree[]` when modifying compute API results
      * - `DataTree` is the high-level builder; `InnerTree` is the Rhino Compute format
      *
+     * Copy-on-write: returns a new array; the caller's array is never mutated.
+     *
      * @overload For TreeBuilder instances (high-level builder)
-     * @param trees - Array of TreeBuilder instances to modify
+     * @param trees - Array of TreeBuilder instances to read from (not mutated)
      * @param paramName - The parameter name to set or replace
      * @param newValue - The new value (scalar, array, or TreeBuilder structure)
-     * @returns A new/modified TreeBuilder array with the updated parameter
+     * @returns A new TreeBuilder array with the updated parameter
      *
      * @overload For compiled InnerTree (low-level API format)
-     * @param trees - The compiled InnerTree array (typically from `client.solve()`)
+     * @param trees - The compiled InnerTree array (typically from `client.solve()`; not mutated)
      * @param paramName - The parameter name to set or replace
      * @param newValue - The new value (scalar, array, or TreeBuilder structure)
-     * @returns A new/modified InnerTree array with the updated parameter
+     * @returns A new InnerTree array with the updated parameter
      *
      * @example
      * ```ts
@@ -749,9 +937,13 @@ declare class TreeBuilder {
     private static readFromDataTrees;
     /**
      * Parse a TreeBuilder path string like "{0;1;2}" into [0, 1, 2].
+     * Negative indices ("{-1;2}") and the root path "{}" are valid.
      *
      * @param pathStr - Path string
      * @returns Array of path indices
+     * @throws Error when the path string is not a valid Grasshopper branch path.
+     *   Malformed keys must never silently collapse to a default branch —
+     *   two distinct unparseable keys would merge their items into one branch.
      */
     static parsePathString(pathStr: string): number[];
     /**
@@ -761,9 +953,7 @@ declare class TreeBuilder {
      * @returns Formatted path string like "{0;1;2}"
      */
     static formatPathString(path: number[]): DataTreePath;
-    /**
-     * Apply numeric constraints to all tree values.
-     */
+    /** Apply numeric constraints to all tree values. */
     private applyNumericConstraints;
     /**
      * Serialize a value for compute requests.
@@ -793,4 +983,4 @@ declare class TreeBuilder {
     private static clampValue;
 }
 
-export { type CacheOptions, ComputeConfig, DataTree, DataTreeDefault, DataTreePath, type DataTreeValue, FileBaseInfo, type GetValuesOptions, type GetValuesResult, GrasshopperClient, GrasshopperComputeConfig, GrasshopperComputeResponse, GrasshopperParsedIO, GrasshopperParsedIORaw, GrasshopperResponseProcessor, InputParam, InputParamSchema, type ParsedContext, RetryPolicy, RhinoComputeError, type SchedulerMode, type SolveContext, type SolveOptions, type SolveResult, SolveScheduler, type SolveSchedulerOptions, TreeBuilder, fetchDefinitionIO, fetchParsedDefinitionIO, processInput, processInputs, solveGrasshopperDefinition };
+export { type CacheOptions, ComputeConfig, DataTree, DataTreeDefault, DataTreePath, type DataTreeValue, type DefinitionRef, FileBaseInfo, type GetValuesOptions, type GetValuesResult, GrasshopperClient, GrasshopperComputeConfig, GrasshopperComputeResponse, GrasshopperParsedIO, GrasshopperParsedIORaw, GrasshopperResponseProcessor, InputParam, InputParamSchema, type ParsedContext, RetryPolicy, RhinoComputeError, type SchedulerMode, type SolveContext, type SolveDefinition, type SolveOptions, type SolveResult, SolveScheduler, type SolveSchedulerOptions, TreeBuilder, fetchDefinitionIO, fetchParsedDefinitionIO, hashDefinition, hashSolveInput, isDefinitionRef, processInput, processInputs, solveGrasshopperDefinition, stableStringify };