@selvajs/solve 0.2.0-beta.2 → 0.2.0-beta.4

package/dist/server.d.cts

@@ -15,21 +15,20 @@ type ServerIdentity = string & {
 interface ResolvedServer {
     id: string;
     serverUrl: string;
-    /** Sent as `RhinoComputeKey`. */
+    /** Sent as the `RhinoComputeKey` header. */
     apiKey?: string;
 }
-/** Derive the opaque cache identity from a resolved server. Identity is the `id`. */
 declare function serverIdentity(server: Pick<ResolvedServer, 'id'>): ServerIdentity;
 interface CachedClient {
     client: GrasshopperClient;
     scheduler: SolveScheduler;
     /**
-     * Last Server-Timing decode/solve/encode, written by onServerTiming.
-     * The scheduler runs up to `maxConcurrent` solves at once, so `last` alone
-     * can't be trusted per-request: callers snapshot `seq` before their solve
-     * and only attribute `last` to themselves if exactly one write happened
-     * since (see the guard in `runSolvePipeline`), dropping it otherwise
-     * rather than risk misattributing another request's timing.
+     * Last Server-Timing decode/solve/encode, written by `onServerTiming`. The
+     * scheduler runs up to `maxConcurrent` solves at once, so `last` alone can't
+     * be trusted per-request: callers snapshot `seq` before their solve and only
+     * attribute `last` to themselves if exactly one write happened since (see
+     * the guard in `runSolvePipeline`), dropping it otherwise rather than risk
+     * misattributing another request's timing.
      */
     rhinoTiming: {
         last: {
@@ -41,7 +40,7 @@ interface CachedClient {
     };
     /**
      * Same snapshot-and-attribute pattern as `rhinoTiming`, for the scheduler's
-     * onSettle cache verdict. `seq` increments on every settle (success or
+     * `onSettle` cache verdict. `seq` increments on every settle (success or
      * error); `last` is written only on success.
      */
     solveMeta: {
@@ -62,37 +61,34 @@ type ClientCacheDebug = boolean | 'verbose';
 interface ClientCacheConfig {
     /** Per-solve timeout forwarded to the scheduler (`ComputeLimits.maxSolveDurationMs`). */
     maxSolveDurationMs: number;
-    /** Ask Rhino.Compute to cache solve results and return them on identical repeats. */
     cachesolve: boolean;
-    /** Also cache solves that reported GH errors (only meaningful with `cachesolve`). */
+    /** Only meaningful with `cachesolve`. */
     cacheerroredsolves: boolean;
-    /** Reference large definitions by server cache key (pointer) instead of re-uploading. */
+    /** Reference large definitions by server cache key instead of re-uploading. */
     reuseServerDefinitionCache: boolean;
     /**
-     * Backpressure — max solves that may WAIT in the FIFO queue (excludes the
-     * in-flight solves, capped at the scheduler's `maxConcurrent`, itself driven
-     * by the compute server's probed child count). `0` = unbounded (`ComputeLimits.
-     * computeMaxQueueDepth`); a full queue sheds new solves with `QUEUE_FULL`.
+     * Max solves that may wait in the FIFO queue, excluding in-flight solves
+     * (capped at `maxConcurrent`, itself driven by the server's probed child
+     * count). `0` = unbounded (`ComputeLimits.computeMaxQueueDepth`); a full
+     * queue rejects new solves with `QUEUE_FULL`.
      */
     maxQueueDepth: number;
     /**
-     * Backpressure — max ms a solve may sit queued before executing; `0` = no
-     * deadline (`ComputeLimits.computeQueueWaitMs`). A too-long wait sheds with
+     * Max ms a solve may sit queued before executing; `0` = no deadline
+     * (`ComputeLimits.computeQueueWaitMs`). Too long a wait rejects with
      * `QUEUE_TIMEOUT`.
      */
     queueWaitMs: number;
     /**
-     * Byte budget for this client's in-process solve cache, evicted LRU alongside
-     * its entry-count cap. Applies per warm client — total worst-case heap is this
-     * × `maxWarmComputeServers`. `0` disables the cache entirely
-     * (`ComputeLimits.computeSolveCacheBytes`, env `COMPUTE_SOLVE_CACHE_MB`).
+     * Byte budget for this client's in-process solve cache. Applies per warm
+     * client — worst-case heap is this × `maxWarmComputeServers`. `0` disables
+     * the cache (`ComputeLimits.computeSolveCacheBytes`, env `COMPUTE_SOLVE_CACHE_MB`).
      */
     responseCacheMaxBytes: number;
-    /** Debug verbosity. `onDebugLog` is only ever invoked when this is not `false`. */
     debug: ClientCacheDebug;
     /** Max distinct warm compute servers before the LRU evicts the oldest. Default 16. */
     maxWarmComputeServers?: number;
-    /** Sink for the concise debug lines (the app wires `console.log`). */
+    /** Sink for the debug lines. `onDebugLog` only fires when `debug` is not `false`. */
     onDebugLog?: (message: string) => void;
 }
 interface ClientCache {
@@ -107,11 +103,7 @@ interface ClientCache {
     }): Promise<CachedClient>;
     /** Dispose and drop the warm client for `id`, so the next request rebuilds against fresh connection details. */
     evict(id: string | ServerIdentity): void;
-    /**
-     * Solve-cache counters summed across every warm client. `warmClients` is
-     * reported alongside since each client owns its own cache. Counters die
-     * with the client that owns them, so totals can fall over time.
-     */
+    /** Solve-cache counters summed across every warm client. Counters die with the client that owns them, so totals can fall over time. */
     solveCacheStats(): SolveCacheStats;
     /**
      * Drop every retained solve result, keeping the warm clients (and their
@@ -124,7 +116,6 @@ interface ClientCache {
     /** Dispose every warm client. Test seam / shutdown hook. */
     disposeAll(): void;
 }
-/** Aggregate solve-cache counters across the warm clients (see `solveCacheStats`). */
 interface SolveCacheStats {
     warmClients: number;
     entries: number;
@@ -163,7 +154,6 @@ declare function createClientCache(config: ClientCacheConfig): ClientCache;
  */
 interface ByteRefOutcome {
     loaded: boolean;
-    /** When `loaded`, whether the bytes came from a warm cache entry. */
     fromCache: boolean;
 }
 /** A definition reference shaped for `@selvajs/compute`'s `DefinitionRef`. */
@@ -172,24 +162,16 @@ interface ByteCacheRef {
     load: () => Promise<Uint8Array>;
     outcome: ByteRefOutcome;
 }
-/** Hit/miss/eviction counters for observability (Server-Timing, admin debug). */
 interface ByteCacheStats {
     hits: number;
     misses: number;
-    /** Entries dropped by the byte-budget LRU. */
     evictions: number;
     entries: number;
     bytes: number;
 }
 interface DefinitionByteCache {
-    /**
-     * `DefinitionRef` whose `load()` serves `versionId`'s bytes from the cache
-     * when warm, otherwise calls `load` and caches the result. Cheap to build
-     * and moves no bytes until `load()` runs.
-     */
     getOrLoad(versionId: string, load: () => Promise<Uint8Array>): ByteCacheRef;
     stats(): ByteCacheStats;
-    /** Test seam / eviction on definition delete if ever needed. */
     clear(): void;
 }
 /**
@@ -201,10 +183,9 @@ declare function createDefinitionByteCache(maxBytes: number): DefinitionByteCach
 /**
  * Transport-agnostic solve pipeline: given an already-resolved solve context
  * (`.gh` bytes, input params + user values, a warm `SolveScheduler`), runs the
- * framework-free half of a solve and returns a discriminated {@link SolveOutcome}
- * instead of throwing for expected failures. Nothing here touches auth, the
- * database, share tokens, rate limits, or metric sinks — those stay app policy
- * in the route that calls this.
+ * solve and returns a discriminated {@link SolveOutcome} instead of throwing
+ * for expected failures. Auth, the database, share tokens, rate limits, and
+ * metric sinks are the calling route's job, not this file's.
  */
 
 /** Compute-response contract version. Bump (and document the change) whenever the envelope's shape changes in a way a consumer could observe. */
@@ -217,25 +198,20 @@ type PipelineInput = SchemaInput & {
 };
 interface SolvePipelineArgs {
     /**
-     * The definition to solve. Either raw `.gh` bytes, or a `DefinitionRef` (from
-     * the definition-byte cache) whose bytes the scheduler materializes ONLY when
-     * an upload is unavoidable — a pointer-known solve of a `DefinitionRef` moves
-     * zero bytes.
+     * Raw `.gh` bytes, or a byte-cache `DefinitionRef` whose bytes the scheduler
+     * materializes only when an upload is unavoidable — a pointer-known solve
+     * moves zero bytes.
      */
     definitionSource: SolveDefinition;
-    /**
-     * When `definitionSource` is a byte-cache `DefinitionRef`, its mutable outcome
-     * so the pipeline can emit the `def_bytes` Server-Timing verdict. Omit for
-     * raw-bytes solves.
-     */
+    /** Mutable load outcome for a `DefinitionRef` source, so the `def_bytes` Server-Timing verdict can be emitted. Omit for raw-bytes solves. */
     byteRefOutcome?: ByteRefOutcome;
     /** Persisted input params; only those with a `paramType` are sent to the solve. */
     inputs: PipelineInput[];
     /**
-     * A tree the caller already built with {@link buildSolveInputTree}. When present
-     * the pipeline skips its own build and solves this exact object.
+     * A tree the caller already built with {@link buildSolveInputTree}; skips the
+     * pipeline's own build and solves this object directly.
      *
-     * Needed whenever the caller coalesces concurrent solves: a single-flight key
+     * A caller coalescing concurrent solves needs this: a single-flight key
      * derived from raw `{inputs, values}` would split two requests that transform
      * to the same tree, which is the identity the scheduler actually caches on.
      */
@@ -244,28 +220,21 @@ interface SolvePipelineArgs {
     values: Record<string, unknown>;
     client: CachedClient;
     responseMaxBytes: number;
-    /** Used only to phrase the timeout message — the scheduler enforces the deadline itself. */
+    /** Only phrases the timeout message — the scheduler enforces the deadline itself. */
     maxSolveDurationMs: number;
     /** Client's `Accept-Encoding`; gzip is applied only when it advertises `gzip`. */
     acceptEncoding: string;
     /**
-     * Request abort signal, forwarded to the scheduler so a client disconnect
-     * cancels the upstream compute call. Its `aborted` flag also disambiguates a
-     * client disconnect from the scheduler's own deadline firing.
+     * Forwarded to the scheduler so a client disconnect cancels the upstream
+     * compute call. Its `aborted` flag also distinguishes a client disconnect
+     * from the scheduler's own deadline firing.
      */
     signal: AbortSignal;
-    /**
-     * Wall-clock origin (`performance.now()` captured at the top of the request)
-     * so the pipeline's `load`/`total` phase timings line up with the caller's
-     * pre-solve prep.
-     */
+    /** Wall-clock origin (`performance.now()` at the top of the request) so `load`/`total` phase timings line up with the caller's pre-solve prep. */
     loadStartMs: number;
     /** Pre-solve "load" phase duration the caller already measured (auth + DB + fetch). */
     defLoadMs: number;
-    /**
-     * Pre-solve prep sub-phase marks (`[label, ms]`), surfaced verbatim as `p_*`
-     * Server-Timing entries.
-     */
+    /** Pre-solve prep sub-phase marks (`[label, ms]`), surfaced verbatim as `p_*` Server-Timing entries. */
     prepMarks?: [string, number][];
 }
 /** Phase timings the pipeline measured; the caller uses them for debug logging. */
@@ -289,12 +258,11 @@ interface SolveEnvelope {
     metrics: SolvePhaseMetrics;
 }
 /**
- * Discriminated result. `ok` carries the envelope; every other variant names an
- * expected failure the transport maps to a status code (the app route maps
- * timeout→504, client_abort→499, too_large→413, shed→503+Retry-After;
- * `compute_error` re-surfaces the original error for the generic 500/503 path).
- * `durationMs` on the error variants is the solve wall time up to the failure,
- * for the metric record.
+ * `ok` carries the envelope; every other variant names an expected failure the
+ * calling route maps to a status code (timeout→504, client_abort→499,
+ * too_large→413, shed→503+Retry-After, compute_error→generic 500/503).
+ * `durationMs` on error variants is the solve wall time up to the failure, for
+ * the metric record.
  */
 type SolveOutcome = {
     kind: 'ok';
@@ -312,12 +280,7 @@ type SolveOutcome = {
 } | {
     kind: 'too_large';
 }
-/**
- * Scheduler backpressure shed the solve before it executed — the per-server
- * queue was full (`QUEUE_FULL`) or it sat queued past the wait deadline
- * (`QUEUE_TIMEOUT`). Retryable: the route maps this to 503 + `Retry-After`.
- * `retryAfterSeconds` is a suggested backoff hint for the client.
- */
+/** Scheduler backpressure rejected the solve before it ran: queue was full (`queue_full`) or the wait exceeded the deadline (`queue_timeout`). Retryable — `retryAfterSeconds` is a backoff hint. */
  | {
     kind: 'shed';
     durationMs: number;
@@ -329,24 +292,19 @@ type SolveOutcome = {
     durationMs: number;
     error: unknown;
 };
-/**
- * Build the transformed input tree — the exact object handed to the scheduler.
- * `runSolvePipeline` calls this itself; a caller only needs it directly to see
- * the tree before the pipeline runs (see {@link SolvePipelineArgs.inputTree}).
- */
+/** The transformed input tree exactly as handed to the scheduler; `runSolvePipeline` calls this itself unless the caller supplies {@link SolvePipelineArgs.inputTree}. */
 declare function buildSolveInputTree(inputs: PipelineInput[], values: Record<string, unknown>): DataTree[];
 declare function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOutcome>;
 /**
  * Re-key a coalesced envelope to a single waiter's `Accept-Encoding`.
  *
  * The single-flight coalescer runs ONE pipeline execution for N identical
- * concurrent solves and hands every waiter the same {@link SolveEnvelope}. That
- * envelope's wire form is baked from the FIRST caller's `Accept-Encoding`, so a
- * later waiter with a different `Accept-Encoding` would otherwise get a body
- * labelled with the wrong encoding (`Vary` can't help — this is one object
- * shared across waiters, not a cache lookup). Encoding is deliberately not part
- * of the coalesce key, so mixed clients still coalesce; this adapts the shared
- * result to each waiter instead.
+ * concurrent solves and hands every waiter the same {@link SolveEnvelope},
+ * baked from the FIRST caller's `Accept-Encoding`. A later waiter with a
+ * different `Accept-Encoding` would otherwise get a body labelled with the
+ * wrong encoding — `Vary` can't help here, since it's one shared object, not a
+ * cache lookup. Encoding is deliberately left out of the coalesce key so mixed
+ * clients still coalesce; this adapts the shared result to each waiter instead.
  *
  * Only the correctness-critical direction is adapted: a gzip envelope served to
  * a non-gzip waiter is gunzipped back to JSON. The reverse (plain JSON to a
@@ -358,11 +316,8 @@ declare function adaptEnvelopeToEncoding(envelope: SolveEnvelope, acceptEncoding
 };
 
 /**
- * Adapt a persisted `SchemaInput` into `@selvajs/compute`'s raw `InputParamSchema`
- * and let its `processInput` produce the typed `InputParam`. `values`/`acceptedFormats`
- * are absent on `SchemaInput` (they live on the layout item's config), so
- * valueList/file inputs fall back to carrying the selected value with no option
- * list — the same value that reaches Grasshopper.
+ * `SchemaInput` has no `values`/`acceptedFormats` (those live on the layout item's config), so
+ * valueList/file inputs here carry just the selected value with no option list.
  */
 declare function transformInputParameter(input: SchemaInput & {
     minimum?: number;
@@ -373,70 +328,56 @@ declare function transformInputParameter(input: SchemaInput & {
 /**
  * In-process single-flight — dogpile protection for every solve.
  *
- * Deliberately NOT conditional on a result cache being configured: the dogpile is
- * worst precisely when nothing else is caching (N concurrent identical solves each
- * paying a full Rhino round trip — the scheduler has no in-flight coalescing of its
- * own, and Rhino's `cachesolve` still costs a round trip per repeat). Gating this on
- * cache configuration, as an earlier version did, turned it off in exactly the
- * deployments most exposed to a cold-key stampede (hot public definition + a deploy).
+ * Always on, not gated behind a result cache being configured: the dogpile is worst
+ * when nothing else is caching, since N concurrent identical solves each pay a full
+ * Rhino round trip (the scheduler doesn't coalesce in-flight requests itself, and
+ * Rhino's `cachesolve` still costs a round trip per repeat). An earlier version
+ * gated this on cache config and so disabled it in exactly the deployments most
+ * exposed to a cold-key stampede — hot public definition plus a deploy.
  *
- * In-process only, sitting above `ISolveResultCache` (per app instance). A
- * cross-instance lease (Redis `SET NX`) is a later backend capability.
+ * Per app instance, above `ISolveResultCache`. No cross-instance lease (Redis
+ * `SET NX`) yet.
  *
- * Correctness note: the shared promise resolves to ONE value for all waiters, so
- * the wrapped work must return an immutable / independently-serializable result
- * (the solve pipeline's envelope is safe to share by reference here because the
- * app serializes it per response).
+ * The shared promise resolves to one value for every waiter, so `work` must return
+ * something safe to share by reference — the solve pipeline's envelope qualifies
+ * because the app serializes it per response.
  */
 interface SolveCacheSingleFlight {
     /**
-     * Run `work` under `key`, coalescing concurrent identical calls: the first
-     * caller executes, overlapping callers for the same key await the same promise
-     * and result, and the key is freed as soon as it settles.
+     * Coalesces concurrent calls under the same key: the first caller runs `work`,
+     * later callers for that key await the same promise, and the key frees as soon
+     * as it settles.
      *
-     * `onWaiterJoined` fires on the OWNER's call each time another caller joins its
-     * flight — ownership changes what the owner's abort signal means (a solo run
-     * may cancel on its own client's disconnect, a shared one may not, or it would
-     * 499 every waiter). Never fires for a joining caller, and never after `work`
-     * settles.
+     * `onWaiterJoined` fires only on the owner's call, only while `work` is still
+     * running, each time another caller joins. Ownership changes what the owner's
+     * abort signal should mean: a solo run can cancel on its own client's
+     * disconnect, but a shared run can't without 499-ing every waiter.
      */
     run<T>(key: string, work: () => Promise<T>, onWaiterJoined?: () => void): Promise<T>;
-    /** Number of keys currently in flight (observability / tests). */
     inFlight(): number;
 }
 interface SolveCacheSingleFlightOptions {
-    /**
-     * Fired when a caller joins an already-in-flight key instead of running its
-     * own work — the coalescing win this module exists for, otherwise invisible.
-     */
     onJoin?: (key: string) => void;
 }
 declare function createSolveCacheSingleFlight(options?: SolveCacheSingleFlightOptions): SolveCacheSingleFlight;
 
 /**
- * `SolveEngine` — the facade that owns everything a consumer needs to run
- * interactive Grasshopper solves: the per-server warm-client cache, the
- * definition-byte cache, single-flight coalescing, the pipeline call, and the
- * outcome→HTTP mapping. Composes `createClientCache` + `createDefinitionByteCache`
- * + `createSolveCacheSingleFlight` + `runSolvePipeline` — the same primitives a
- * hand-assembled app route already wires, minus the wiring.
+ * Facade over the warm-client cache, definition-byte cache, single-flight
+ * coalescing, and the solve pipeline — the primitives an app route would
+ * otherwise wire up by hand.
  *
- * Deliberately does NOT read env itself (no `resolveComputeLimits` call here):
- * `@selvajs/server`, which owns that function, depends on `@selvajs/solve`, so
- * the reverse import would be circular. A consumer resolves its own limits
- * (`resolveComputeLimits` from `@selvajs/server/compute`, or any equivalent) and
- * passes the handful of fields this engine actually needs.
+ * Doesn't read env itself: `@selvajs/server` owns `resolveComputeLimits` and
+ * depends on `@selvajs/solve`, so calling it from here would be a circular
+ * import. Callers resolve their own limits and pass in the fields below.
  *
- * What stays OUT, on purpose (matches `server/index.ts`'s existing boundary):
- * auth, DB reads, share tokens, rate limiting, metric sinks, and which compute
- * server to use (`resolveServerForOrg`-equivalent) — all app policy, supplied
- * per-call via `SolveEngineSolveArgs.server`.
+ * Stays out of auth, DB reads, share tokens, rate limiting, metrics, and
+ * compute-server selection — all app policy, supplied per-call via
+ * `SolveEngineSolveArgs.server`.
  */
 
 /**
- * The subset of `ComputeLimits` (`@selvajs/server/compute`) the engine needs,
- * passed straight through to `createClientCache` — pass the resolved object
- * through, its extra fields are ignored.
+ * Subset of `ComputeLimits` (`@selvajs/server/compute`) the engine needs.
+ * Pass the resolved object through as-is — extra fields are ignored.
  */
 interface SolveEngineLimits {
     maxSolveDurationMs: number;
@@ -450,24 +391,22 @@ interface SolveEngineLimits {
     computeSolveCacheBytes: number;
 }
 interface SolveEngineOptions {
-    /** Required — the engine does not read env itself (see module doc). */
     limits: SolveEngineLimits;
     logger?: ILogger;
-    /** Max distinct warm compute servers before the LRU evicts the oldest. Default 16 (see `createClientCache`). */
+    /** Max distinct warm compute servers before the LRU evicts the oldest. Default 16. */
     maxWarmComputeServers?: number;
-    /** Concise cache/timing logs when truthy; `'verbose'` also enables full lib-level request/response dumps. Default off. */
+    /** Concise cache/timing logs when truthy; `'verbose'` also dumps full lib-level requests/responses. Default off. */
     debug?: ClientCacheDebug;
     onDebugLog?: (message: string) => void;
-    /** Fired when a caller joins an already-in-flight solve instead of running its own (`createSolveCacheSingleFlight`'s `onJoin`). */
+    /** Fired when a caller joins an already-in-flight solve instead of running its own. */
     onSolveCoalesced?: (key: string) => void;
 }
 /**
- * `definitionSource` accepts every form `runSolvePipeline` does, plus the
- * `{versionId, load}` sugar that builds (and caches) a `ByteCacheRef` internally.
- * A `ByteCacheRef` obtained from `engine.definitionRef()` ahead of time (e.g. to
- * read its bytes for schema extraction before solving) is accepted directly and
- * NOT re-wrapped — recognized by its `outcome` field, which a plain external
- * `DefinitionRef` never has.
+ * Accepts every form `runSolvePipeline` does, plus `{versionId, load}` sugar
+ * that builds (and caches) a `ByteCacheRef` internally. A `ByteCacheRef`
+ * obtained ahead of time from `engine.definitionRef()` (e.g. to read bytes for
+ * schema extraction before solving) is passed through as-is — detected by its
+ * `outcome` field, which a plain `DefinitionRef` never has.
  */
 type SolveEngineDefinitionSource = Uint8Array | string | DefinitionRef | ByteCacheRef | {
     versionId: string;
@@ -477,18 +416,17 @@ interface SolveEngineSolveArgs {
     server: ResolvedServer;
     definitionSource: SolveEngineDefinitionSource;
     /**
-     * Coalesce-key identity for a raw `Uint8Array`/`string` `definitionSource`,
-     * which has no natural identity the way a `DefinitionRef`'s `.key` does.
-     * Required in that case — `solve()` throws without it, rather than silently
-     * hashing bytes (a different identity convention than the rest of the
-     * package, which keys on immutable ids). Ignored for the other source forms.
+     * Coalesce-key identity for a raw `Uint8Array`/`string` source, which has
+     * no natural identity the way a `DefinitionRef`'s `.key` does. Required in
+     * that case — `solve()` throws rather than silently hashing the bytes.
+     * Ignored for the other source forms.
      */
     definitionKey?: string;
     inputs: PipelineInput[];
     values: Record<string, unknown>;
     signal: AbortSignal;
     acceptEncoding?: string;
-    /** Stamped as `X-Selva-Definition` on this solve's client — see `ClientCache.getClient`. */
+    /** Stamped as `X-Selva-Definition` on this solve's client. */
     definitionGuid?: string;
     loadStartMs?: number;
     defLoadMs?: number;