@selvajs/compute 4.0.0-beta.0 → 4.0.0-beta.3

package/dist/grasshopper.d.ts

@@ -1,5 +1,309 @@
-import { C as ComputeConfig, e as RhinoModelUnit, R as RetryPolicy, d as RhinoComputeError, a as ComputeServerStats, F as FileBaseInfo } from './handle-files-DcA24IkS.js';
-export { c as FileData, P as ProcessedFile, f as downloadFileData, g as extractFilesFromComputeResponse } from './handle-files-DcA24IkS.js';
+import { C as ComputeConfig, R as RetryPolicy, a as ComputeError, e as SolveDefinition, F as FileBaseInfo } from './handle-files-DMK9bCOW.js';
+export { D as DefinitionRef, c as FileData, P as ProcessedFile, f as downloadFileData, g as extractFilesFromComputeResponse, i as isDefinitionRef } from './handle-files-DMK9bCOW.js';
+
+/**
+ * ComputeServerStats provides methods to query Rhino Compute server statistics.
+ *
+ * @public Use this for server health monitoring and statistics.
+ *
+ * @example
+ * ```typescript
+ * const stats = new ComputeServerStats('http://localhost:6500', 'your-api-key');
+ *
+ * try {
+ *   const isOnline = await stats.isServerOnline();
+ *   const children = await stats.getActiveChildren();
+ *   const version = await stats.getVersion();
+ *
+ *   // Or get everything at once
+ *   const allStats = await stats.getServerStats();
+ * } finally {
+ *   await stats.dispose(); // Clean up resources
+ * }
+ * ```
+ */
+declare class ComputeServerStats {
+    private readonly serverUrl;
+    private readonly apiKey?;
+    private disposed;
+    private activeMonitors;
+    private activeTimeouts;
+    /** Timeout (ms) for the fast read/monitoring endpoints. */
+    private static readonly DEFAULT_TIMEOUT_MS;
+    /** Timeout (ms) for child-lifecycle POSTs — a cold Windows child can take ~30s to spawn. */
+    private static readonly LIFECYCLE_TIMEOUT_MS;
+    /** Floor for `monitor()`'s `intervalMs` — anything lower hot-loops the server. */
+    private static readonly MIN_MONITOR_INTERVAL_MS;
+    /**
+     * @param serverUrl - Base URL of the Rhino Compute server with http:// or https:// scheme (e.g., 'http://localhost:6500')
+     * @param apiKey - Optional API key for authentication
+     */
+    constructor(serverUrl: string, apiKey?: string);
+    /**
+     * Build request headers with optional API key.
+     */
+    private buildHeaders;
+    /**
+     * `fetch` wrapper that aborts after `timeoutMs` so a hung connection can't stall
+     * a probe (or the `monitor()` loop) forever. Pass `0` to disable the timeout.
+     */
+    private fetchWithTimeout;
+    /**
+     * Check if the server is online.
+     *
+     * This is a single-sample probe: it returns `true` only on a 2xx from the
+     * proxy liveness root `/`, and `false` for every other outcome (non-2xx,
+     * network error, or timeout). A cold or briefly-busy-but-up server can therefore
+     * read as offline — callers that gate on this (e.g. client construction)
+     * should retry rather than treat a single `false` as authoritative.
+     *
+     * @param timeoutMs - Abort the probe after this many ms (default: 5000).
+     *   Pass `0` to disable the timeout. Prevents a hung connection from
+     *   stalling the caller indefinitely.
+     */
+    isServerOnline(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Get the number of active child processes on the server.
+     *
+     * By default the proxy's `/activechildren` endpoint will *spawn* children up
+     * to the configured count if none are running, then report the count — which
+     * wakes (and bills) an idle server. Pass `{ initialize: false }` for a passive
+     * read that reports the current count without spawning; use this for
+     * monitoring or before a purge/probe where you must not wake the server.
+     *
+     * @param options.initialize - When `false`, append `?initialize=false` so the
+     *   server reports without spawning. Defaults to `true` (the server's default).
+     * @returns Number of active children, or null if unavailable
+     */
+    getActiveChildren(options?: {
+        initialize?: boolean;
+    }): Promise<number | null>;
+    /**
+     * Get the server version information.
+     *
+     * @returns Version object with rhino, compute, and git_sha, or null if unavailable
+     */
+    getVersion(): Promise<{
+        rhino: string;
+        compute: string;
+        git_sha: string | null;
+    } | null>;
+    /**
+     * Get the plugins installed on the server.
+     *
+     * Returns a `name → version` map of non-core plugins the server has loaded,
+     * or `null` if the request failed. Pass `kind` to choose which inventory:
+     * `'gh'` (default) lists Grasshopper add-on assemblies via
+     * `/plugins/gh/installed`; `'rhino'` lists Rhino plugins via
+     * `/plugins/rhino/installed`. Plugins that ship with Rhino / are core
+     * libraries are excluded by the server.
+     *
+     * @param kind - `'gh'` for Grasshopper add-ons (default) or `'rhino'` for Rhino plugins.
+     * @returns Map of plugin name to version, or `null` on failure.
+     *
+     * @example
+     * ```ts
+     * const gh = await stats.getInstalledPlugins();        // Grasshopper add-ons
+     * const selvaVersion = gh?.['Selva'] ?? null;
+     * ```
+     */
+    getInstalledPlugins(kind?: 'gh' | 'rhino'): Promise<Record<string, string> | null>;
+    /**
+     * Get comprehensive server statistics.
+     * Fetches all available server information in parallel.
+     *
+     * @returns Object containing server status and available stats
+     */
+    getServerStats(): Promise<{
+        isOnline: boolean;
+        version?: {
+            rhino: string;
+            compute: string;
+            git_sha: string | null;
+        };
+        activeChildren?: number;
+    }>;
+    /**
+     * Purge the server's solve-results / URL-data cache.
+     *
+     * POSTs to `cache/purge` and returns the number of entries removed, or `null`
+     * if the request failed. This clears cached solve responses and fetched
+     * definition-URL data; it does NOT evict the definition cache (active
+     * `pointer` references stay valid).
+     *
+     * **Caveat:** `cache/purge` is forwarded by the rhino.compute proxy to a
+     * single round-robin-selected child, so in a multi-child deployment one call
+     * purges one child's cache. Call repeatedly (or size the pool to 1) if you
+     * need a fleet-wide purge.
+     *
+     * @returns Number of entries removed, or `null` on failure.
+     *
+     * @example
+     * ```ts
+     * const removed = await stats.purgeCache();
+     * if (removed !== null) console.log(`Purged ${removed} cached solves`);
+     * ```
+     */
+    purgeCache(): Promise<number | null>;
+    /**
+     * Best-effort fleet-wide cache purge across a multi-child deployment.
+     *
+     * A single {@link purgeCache} POST is forwarded by the rhino.compute proxy to
+     * just ONE round-robin-selected child, so the other children keep serving
+     * stale cached solves. There is no proxy endpoint that addresses children
+     * individually, so this method reads the active child count (passively, never
+     * spawning) and fires `2 × count` sequential purges, relying on the proxy's
+     * round-robin to spread the hits across the pool.
+     *
+     * **This is best-effort, not a guarantee.** Round-robin can revisit one child
+     * and skip another; under concurrent traffic the rotation drifts. The result's
+     * `confident` flag is `true` only when the server reports a single child (where
+     * one purge is exact) — surface it so callers don't over-promise. For a hard
+     * fleet-wide guarantee, run the deployment at `--childcount 1` or add a
+     * server-side fan-out endpoint.
+     *
+     * @returns `{ totalPurged, calls, children, confident }`, or `null` if the
+     *   child count couldn't be read (server unreachable). `totalPurged` sums the
+     *   per-call counts; `calls` is how many purges were issued; `children` is the
+     *   reported pool size; `confident` is `true` only at a single-child pool.
+     *
+     * @example
+     * ```ts
+     * const r = await stats.purgeAllChildren();
+     * if (r && !r.confident) {
+     *   console.warn(`Purged ~${r.totalPurged} across ${r.children} children (best-effort)`);
+     * }
+     * ```
+     */
+    purgeAllChildren(): Promise<{
+        totalPurged: number;
+        calls: number;
+        children: number;
+        confident: boolean;
+    } | null>;
+    /**
+     * Get the server's current UTC clock.
+     *
+     * GETs `/servertime`, which the server emits as a JSON-encoded ISO-8601
+     * timestamp (e.g. `"2026-06-18T08:30:00Z"`). Useful for detecting clock skew
+     * between caller and server. Returns `null` if the request failed or the body
+     * isn't a parseable date.
+     *
+     * @returns A `Date` for the server's UTC time, or `null` on failure.
+     */
+    getServerTime(): Promise<Date | null>;
+    /**
+     * Get how long the rhino.compute proxy has been idle.
+     *
+     * GETs `/idlespan` on the proxy, which returns the seconds elapsed since the
+     * last request was forwarded to a compute child. This is a proxy-level metric
+     * (not proxied to a child) used by autoscalers to decide when a node can be
+     * drained. Returns `null` if unavailable.
+     *
+     * @returns Idle time in seconds, or `null` on failure.
+     */
+    getIdleSpan(): Promise<number | null>;
+    /**
+     * Fill the compute child pool up to the server's configured baseline.
+     *
+     * POSTs `/launch-children`. No-op when the pool is already at or above the
+     * configured `--childcount`. Returns `{ spawned, active }` — how many children
+     * were started and the resulting child count — or `null` on failure.
+     *
+     * To raise capacity above the baseline use {@link launchChild}; the baseline
+     * itself can only be changed by restarting rhino.compute.
+     *
+     * @returns `{ spawned, active }`, or `null` on failure.
+     */
+    launchChildren(): Promise<{
+        spawned: number[];
+        active: number;
+    } | null>;
+    /**
+     * Add a single compute child to the pool, optionally on a specific port.
+     *
+     * POSTs `/launch-child` (with `?port=N` when `port` is given). Unlike
+     * {@link launchChildren}, this can push the pool above the baseline, up to the
+     * server's `MaxChildren` cap. Returns `{ spawned: [port] }` on success, or
+     * `null` on failure (server replies 400 for a bad port, 409 if the port is in
+     * use, 503 at the max-children cap).
+     *
+     * @param port - Optional specific port to launch on; otherwise the next free one.
+     * @returns `{ spawned }` listing the launched port, or `null` on failure.
+     */
+    launchChild(port?: number): Promise<{
+        spawned: number[];
+    } | null>;
+    /**
+     * Gracefully shut down compute children without respawning them.
+     *
+     * POSTs `/shutdown-children`. With no `port` it shuts down every child; with
+     * `port` it targets just that one. Children do not respawn, but the next
+     * `/grasshopper` request auto-spawns the pool back to the baseline. Returns
+     * `{ shutdown, active }` — how many were stopped and the remaining count — or
+     * `null` on failure.
+     *
+     * @param port - Optional port to target; omit to shut down all children.
+     * @returns `{ shutdown, active }`, or `null` on failure.
+     */
+    shutdownChildren(port?: number): Promise<{
+        shutdown: number;
+        active: number;
+    } | null>;
+    /**
+     * Shut down compute children and respawn replacements (rolling restart).
+     *
+     * POSTs `/recycle-children`. With no `port` it recycles every child; with
+     * `port` it recycles just that one. The server recycles sequentially (each
+     * replacement is serving before the next child is stopped) so the pool never
+     * drops to zero mid-recycle. Returns `{ shutdown, spawned, active }`, or
+     * `null` on failure.
+     *
+     * @param port - Optional port to target; omit to recycle all children.
+     * @returns `{ shutdown, spawned, active }`, or `null` on failure.
+     */
+    recycleChildren(port?: number): Promise<{
+        shutdown: number;
+        spawned: number[];
+        active: number;
+    } | null>;
+    /**
+     * POST a control endpoint that replies with a JSON object and return it,
+     * degrading to `null` on any non-2xx, non-JSON, or network failure. Shared by
+     * the child-lifecycle methods so their failure semantics stay identical. Uses
+     * the longer lifecycle timeout since a spawn/recycle can take ~30s.
+     */
+    private postJson;
+    /**
+     * Continuously monitor server stats at specified interval.
+     *
+     * @param callback - Function called with stats on each interval
+     * @param intervalMs - Milliseconds between checks (default: 5000). Must be a
+     *   finite number of at least 100 ms — lower values would hot-loop the server.
+     * @returns Function to stop monitoring
+     * @throws {RangeError} If `intervalMs` is not a finite number >= 100.
+     *
+     * @example
+     * ```typescript
+     * const stopMonitoring = stats.monitor((data) => {
+     *   console.log('Server stats:', data);
+     * }, 3000);
+     *
+     * // Later...
+     * stopMonitoring();
+     * ```
+     */
+    monitor(callback: (stats: Awaited<ReturnType<typeof this.getServerStats>>) => void, intervalMs?: number): () => void;
+    /**
+     * Disposes of all resources and stops all active monitors.
+     * Call this when you're done using the stats instance.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Ensures the instance hasn't been disposed.
+     */
+    private ensureNotDisposed;
+}
 
 type DataTreePath = `{${string}}`;
 interface DataItem {
@@ -124,6 +428,7 @@ interface ColorInputType extends BaseInputType {
  */
 type InputParam = NumericInputType | BooleanInputType | TextInputType | ValueListInputType | GeometryInputType | FileInputType | ColorInputType;
 
+type RhinoModelUnit = 'None' | 'Microns' | 'Millimeters' | 'Centimeters' | 'Decimeters' | 'Meters' | 'Kilometers' | 'Mils' | 'Inches' | 'Feet' | 'Yards' | 'Miles' | 'CustomUnits' | 'Unset';
 /**
  * Base Grasshopper schema properties shared by config, args, and response
  */
@@ -301,9 +606,9 @@ interface InputParseError {
     inputName: string;
     /** The declared paramType from the raw schema. */
     paramType: string;
-    /** Human-readable reason from the underlying RhinoComputeError. */
+    /** Human-readable reason from the underlying ComputeError. */
     message: string;
-    /** Error code from the underlying RhinoComputeError, if available. */
+    /** Error code from the underlying ComputeError, if available. */
     code?: string;
 }
 /**
@@ -331,50 +636,6 @@ interface GrasshopperParsedIO {
     loadErrors?: string[];
 }
 
-/**
- * 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.
  *
@@ -387,19 +648,29 @@ declare function isDefinitionRef(definition: SolveDefinition): definition is Def
  */
 type SchedulerMode = 'latest-wins' | 'queue' | 'parallel';
 interface CacheOptions {
-    /** Maximum entries kept in the LRU. Default: 50. */
-    maxEntries?: number;
-    /**
-     * Total byte budget for retained responses, evicted LRU alongside
-     * `maxEntries` (both bounds apply). Responses range KB→100s of MB, so an
-     * entry count alone can't bound heap. Sizing uses the response's wire size
-     * (JSON text length, recorded at the fetch boundary — no re-serialization);
-     * a response without that hint (custom executor) is sized by a one-off
-     * `JSON.stringify`. A single response larger than the whole budget is
-     * served but never retained. `0` = no byte bound (count-only, default).
-     */
-    maxBytes?: number;
-    /** Time-to-live in ms. Set to `0` for no expiry (default). */
+    /**
+     * Total byte budget for retained responses, evicted LRU. The only size bound
+     * there is: responses range KB→100s of MB, so memory is the constraint that
+     * matters and an entry count would only obscure it.
+     *
+     * Sizing uses the response's wire size (JSON text length, recorded at the
+     * fetch boundary — no re-serialization); a response without that hint
+     * (custom executor) is sized by a one-off `JSON.stringify`. A single
+     * response larger than the whole budget is served but never retained.
+     *
+     * Required and must be > 0 — to disable caching, pass `cache: false`.
+     */
+    maxBytes: number;
+    /**
+     * Time-to-live in ms. Set to `0` for no expiry (default, and the right
+     * choice for a solve keyed by immutable definition+inputs — expiry there
+     * only buys a paid re-solve of an identical answer). Meaningful only when a
+     * definition reaches outside its inputs (external data source, clock), where
+     * a stale result is genuinely wrong rather than merely old.
+     *
+     * Expiry is evaluated lazily on read: an expired entry keeps its bytes
+     * counted against `maxBytes` until that exact key is next consulted.
+     */
     ttlMs?: number;
     /**
      * Cache responses that carry Grasshopper `errors`. Default `true`: an
@@ -417,7 +688,7 @@ interface SolveSchedulerOptions {
     /**
      * 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
+     * `solve()` is rejected 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.
@@ -425,7 +696,7 @@ interface SolveSchedulerOptions {
     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
+     * executing. If it's still waiting after this long it's rejected with
      * `code: QUEUE_TIMEOUT` rather than burning compute on a stale request.
      * Bounds tail latency. Only applies to `queue` / `parallel` modes. Default:
      * no deadline.
@@ -433,8 +704,12 @@ interface SolveSchedulerOptions {
     queueWaitMs?: number;
     timeoutMs?: number;
     retry?: RetryPolicy;
-    /** Enable response caching keyed by hash of (definition, dataTree). */
-    cache?: boolean | CacheOptions;
+    /**
+     * Response caching keyed by hash of (definition, dataTree). Omit or pass
+     * `false` to disable; otherwise a byte budget is required, so an unbounded
+     * cache can't be enabled by accident.
+     */
+    cache?: false | CacheOptions;
     /**
      * Reuse the server's definition cache key so a large (base64/binary)
      * definition is uploaded once and subsequent solves reference it by
@@ -476,7 +751,7 @@ type SolveResult = {
     definitionReuploaded?: boolean;
 } | {
     status: 'error';
-    error: RhinoComputeError;
+    error: ComputeError;
     durationMs: number;
 } | {
     status: 'superseded';
@@ -535,13 +810,17 @@ declare class SolveScheduler {
     private readonly executor;
     private readonly baseConfig;
     private readonly mode;
-    private readonly maxConcurrent;
+    /**
+     * Mutable via {@link setMaxConcurrent}: the compute server's worker pool can grow
+     * or shrink while this scheduler is alive, and the dispatch loops re-read this on
+     * every pass rather than capturing it.
+     */
+    private maxConcurrent;
     private readonly maxQueueDepth;
     private readonly queueWaitMs;
     private readonly timeoutMs;
     private readonly retry;
     private readonly cacheEnabled;
-    private readonly cacheMax;
     private readonly cacheMaxBytes;
     private readonly cacheTtl;
     private readonly cacheErroredSolves;
@@ -583,15 +862,26 @@ declare class SolveScheduler {
     get inFlightCount(): number;
     get queueDepth(): number;
     get lastResult(): GrasshopperComputeResponse | null;
-    get lastError(): RhinoComputeError | null;
+    get lastError(): ComputeError | null;
     get lastDurationMs(): number | null;
+    /**
+     * Adjust how many solves may run at once, for when the compute server's worker
+     * pool changes size after this scheduler was built.
+     *
+     * Raising it drains queued work immediately. Lowering it never interrupts work
+     * already in flight — those finish above the new limit, and the cap applies from
+     * the next dispatch. Values below 1 are clamped, since 0 would wedge the queue.
+     */
+    setMaxConcurrent(value: number): void;
+    /** Current concurrency cap — reflects any {@link setMaxConcurrent} adjustment. */
+    getMaxConcurrent(): number;
     /** Subscribe to state changes. */
     subscribe(listener: () => void): () => void;
     private notify;
     /**
      * Schedule a solve. Returns a promise that:
      * - Resolves with the compute response on success.
-     * - Rejects with `RhinoComputeError` on failure.
+     * - Rejects with `ComputeError` on failure.
      * - Rejects with `code: ErrorCodes.SUPERSEDED` when the call was canceled because
      *   newer values arrived (latest-wins mode).
      * - Rejects with `code: ErrorCodes.ABORTED` when the call was canceled via
@@ -633,8 +923,8 @@ declare class SolveScheduler {
     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}.
+     * still waiting when it fires, it's rejected 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. */
@@ -759,9 +1049,9 @@ declare class GrasshopperClient {
      * exponential backoff before giving up. Each probe is also bounded by a
      * timeout so a hung connection can't stall construction.
      *
-     * @throws {RhinoComputeError} with code NETWORK_ERROR if the server stays
+     * @throws {ComputeError} with code NETWORK_ERROR if the server stays
      *   unreachable across all attempts
-     * @throws {RhinoComputeError} with code INVALID_CONFIG if configuration is invalid
+     * @throws {ComputeError} with code INVALID_CONFIG if configuration is invalid
      */
     static create(config: GrasshopperComputeConfig): Promise<GrasshopperClient>;
     /**
@@ -777,9 +1067,9 @@ declare class GrasshopperClient {
     /**
      * Run a compute job with a Grasshopper definition.
      *
-     * @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 {ComputeError} with code INVALID_INPUT if definition is empty
+     * @throws {ComputeError} with code NETWORK_ERROR if server is offline
+     * @throws {ComputeError} 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
@@ -814,7 +1104,7 @@ declare class GrasshopperClient {
     /**
      * Validates and normalizes a compute configuration.
      *
-     * @throws {RhinoComputeError} with code INVALID_CONFIG if configuration is invalid
+     * @throws {ComputeError} with code INVALID_CONFIG if configuration is invalid
      */
     private normalizeComputeConfig;
 }
@@ -1042,7 +1332,7 @@ declare function solveGrasshopperDefinition(dataTree: DataTree[], definition: So
  * @param definition - The Grasshopper definition (URL, base64 string, or Uint8Array)
  * @param config - Compute configuration (server URL, API key, etc.)
  * @returns Key-normalized inputs and outputs with no per-type processing
- * @throws {RhinoComputeError} If fetch fails or response is invalid
+ * @throws {ComputeError} If fetch fails or response is invalid
  *
  * @public Use `fetchParsedDefinitionIO()` for processed, type-safe inputs
  */
@@ -1056,7 +1346,7 @@ declare function fetchDefinitionIO(definition: string | Uint8Array, config: Comp
  * @param definition - The Grasshopper definition (URL, base64 string, or Uint8Array)
  * @param config - Compute configuration (server URL, API key, etc.)
  * @returns Processed inputs with discriminated union types and outputs
- * @throws {RhinoComputeError} If fetch fails or response is invalid
+ * @throws {ComputeError} If fetch fails or response is invalid
  *
  * @example
  * ```typescript
@@ -1075,6 +1365,35 @@ declare function fetchDefinitionIO(definition: string | Uint8Array, config: Comp
  */
 declare function fetchParsedDefinitionIO(definition: string | Uint8Array, config: ComputeConfig): Promise<GrasshopperParsedIO>;
 
+/** One entry of the schema endpoint's response, after wrapper-key normalization. */
+interface SchemaEndpointResult<TSchema = unknown> {
+    /** Schemas embedded in that file. Absent when the file yielded none. */
+    schemas?: TSchema[];
+    /** Per-file diagnosis. Compute reports this and still answers 200. */
+    error?: string;
+}
+/**
+ * Read compute's `/grasshopper/schema` body: `[{ FileName, Schemas }]` per
+ * uploaded file, or a bare object for a single file.
+ *
+ * Use this rather than unwrapping the body by hand. The wrapper's casing varies
+ * by server branch — mcneel serializes `FileName`/`Schemas`, the VektorNode fork
+ * `fileName`/`schemas` — so a fixed-key read silently yields `undefined` against
+ * half the servers, and the endpoint answers 200 either way. The failure looks
+ * like "this definition has no schemas", which sends you debugging the wrong
+ * thing entirely.
+ *
+ * A blanket key-rewrite (the old `camelcaseKeys` approach) is NOT the fix: it
+ * reaches inside the schemas and mangles user-authored names — `"Display3d"` →
+ * `"display3d"`, value-list labels like `"Option A"` → `"optionA"`. Only the two
+ * wrapper keys are read here; schema CONTENTS pass through untouched, which is
+ * why `TSchema` is a pass-through type parameter this module never inspects.
+ *
+ * @typeParam TSchema - Your schema type (e.g. `UISchema`). Not inspected.
+ * @param raw - The parsed JSON body.
+ */
+declare function readSchemaResults<TSchema = unknown>(raw: unknown): SchemaEndpointResult<TSchema>[];
+
 /**
  * Parse one raw Grasshopper input schema into a typed {@link InputParam}.
  * Validation failures are swallowed and replaced with a safe default; use
@@ -1356,4 +1675,4 @@ declare class TreeBuilder {
     private static clampValue;
 }
 
-export { type BooleanInputType, type CacheOptions, type DataItem, type DataTree, type DataTreeDefault, type DataTreePath, type DataTreeValue, type DefaultValue, type DefinitionRef, FileBaseInfo, type FileInputType, type GeometryInputType, type GetValuesOptions, type GetValuesResult, GrasshopperClient, type GrasshopperComputeConfig, type GrasshopperComputeResponse, type GrasshopperParsedIO, type GrasshopperParsedIORaw, type GrasshopperRequestSchema, GrasshopperResponseProcessor, type InnerTreeData, type InputParam, type InputParamSchema, type NumericInputType, type OutputParamSchema, type OutputType, type ParsedContext, type SchedulerMode, type SolveContext, type SolveDefinition, type SolveOptions, type SolveResult, SolveScheduler, type SolveSchedulerOptions, type TextInputType, TreeBuilder, type ValueListInputType, fetchDefinitionIO, fetchParsedDefinitionIO, hashDefinition, hashSolveInput, isDefinitionRef, processInput, solveGrasshopperDefinition, stableStringify };
+export { type BooleanInputType, type CacheOptions, ComputeServerStats, type DataItem, type DataTree, type DataTreeDefault, type DataTreePath, type DataTreeValue, type DefaultValue, FileBaseInfo, type FileInputType, type GeometryInputType, type GetValuesOptions, type GetValuesResult, GrasshopperClient, type GrasshopperComputeConfig, type GrasshopperComputeResponse, type GrasshopperParsedIO, type GrasshopperParsedIORaw, type GrasshopperRequestSchema, GrasshopperResponseProcessor, type InnerTreeData, type InputParam, type InputParamSchema, type NumericInputType, type OutputParamSchema, type OutputType, type ParsedContext, type RhinoModelUnit, type SchedulerMode, type SchemaEndpointResult, type SolveContext, SolveDefinition, type SolveOptions, type SolveResult, SolveScheduler, type SolveSchedulerOptions, type TextInputType, TreeBuilder, type ValueListInputType, fetchDefinitionIO, fetchParsedDefinitionIO, hashDefinition, hashSolveInput, processInput, readSchemaResults, solveGrasshopperDefinition, stableStringify };