@selvajs/solve 2.0.0-beta.8 → 2.0.0

package/dist/server.d.ts

@@ -1,14 +1,25 @@
 import { t as SolveInput } from "./solve-input-CUjVGYPC.js";
-import { DataTree, GrasshopperClient, GrasshopperComputeResponse, SelvaEventTarget, SolveScheduler } from "@selvajs/compute/grasshopper";
-import { DefinitionRef, DefinitionRef as DefinitionRef$1, SolveDefinition, SolveDefinition as SolveDefinition$1, isDefinitionRef } from "@selvajs/compute/core";
-import { ILogger } from "@selvajs/platform";
+import { UISchema } from "@selvajs/schemas";
+import { GrasshopperClient, GrasshopperComputeResponse, SelvaEventTarget, SolveScheduler } from "@selvajs/compute/grasshopper";
+import { DefinitionRef, DefinitionRef as DefinitionRef$1, ServerTiming, SolveDefinition } from "@selvajs/compute/core";
+/** Rhino.Compute's own default `--timeout`, for a server that can't report its own. */
+export declare const DEFAULT_SOLVE_DEADLINE_MS = 100000;
 /**
- * Opaque identity of a compute server — construct only via `serverIdentity()`.
- * Kept opaque so "a server is now a pool of URLs behind one id" stays additive.
+ * Ceiling on any solve deadline, whatever the server reports. Bounds how long a request, its
+ * live-event token and a delegated session stay open; past an hour a solve belongs in a job.
  */
-type ServerIdentity = string & {
-  readonly __brand: 'ServerIdentity';
-};
+export declare const MAX_SOLVE_DEADLINE_MS: number;
+/** What Selva holds a solve to on one compute server. */
+interface SolveLimits {
+  solveDeadlineMs: number;
+  /** `null` when the server didn't say: its own 413 is then the only check. */
+  maxRequestBytes: number | null;
+  /**
+   * Send a pointer to the server's cached definition instead of the `.gh`. Only on a server that
+   * answers a stale pointer with `definition_not_cached`: one that doesn't returns empty geometry.
+   */
+  reuseDefinitionCache: boolean;
+}
 /** Minimal resolved-server shape the cache needs (a subset of the app's `ComputeServerConfig`). */
 interface ResolvedServer {
   id: string;
@@ -16,10 +27,11 @@ interface ResolvedServer {
   /** Sent as the `RhinoComputeKey` header. */
   apiKey?: string;
 }
-export declare function serverIdentity(server: Pick<ResolvedServer, 'id'>): ServerIdentity;
 interface CachedClient {
   client: GrasshopperClient;
   scheduler: SolveScheduler;
+  /** Read from the server when the client was built; a changed server rebuilds the client. */
+  limits: SolveLimits;
 }
 /**
  * Debug verbosity: `false` is silent, `true` gives concise cache/timing logs
@@ -27,70 +39,6 @@ interface CachedClient {
  * dumps (incl. geometry) — a superset of `true`, not an independent setting.
  */
 type ClientCacheDebug = boolean | 'verbose';
-/** Config injected by the consuming app, so this module stays env-agnostic and testable. */
-interface ClientCacheConfig {
-  /** Per-solve timeout forwarded to the scheduler (`ComputeLimits.solveDeadlineMs`). */
-  solveDeadlineMs: number;
-  cachesolve: boolean;
-  /** Only meaningful with `cachesolve`. */
-  cacheerroredsolves: boolean;
-  /** Reference large definitions by server cache key instead of re-uploading. */
-  reuseServerDefinitionCache: boolean;
-  /**
-   * 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;
-  /**
-   * 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. Applies per warm
-   * client — worst-case heap is this × `maxWarmComputeServers`. `0` disables
-   * the cache (`ComputeLimits.computeSolveCacheBytes`, env `COMPUTE_SOLVE_CACHE_MB`).
-   */
-  responseCacheMaxBytes: number;
-  /**
-   * Largest compute response body read; past it the download is cancelled (`too_large`).
-   * Default: no limit.
-   */
-  maxResponseBytes?: number;
-  debug: ClientCacheDebug;
-  /** Max distinct warm compute servers before the LRU evicts the oldest. Default 16. */
-  maxWarmComputeServers?: number;
-  /** Sink for the debug lines. `onDebugLog` only fires when `debug` is not `false`. */
-  onDebugLog?: (message: string) => void;
-}
-interface ClientCache {
-  /**
-   * Get (or create) the warm client + scheduler for a resolved compute server,
-   * keyed by its `id`. `definitionGuid`, when present, is stamped as the
-   * `X-Selva-Definition` header on this client's outbound solve/IO requests —
-   * inert routing/telemetry metadata until a pool router exists.
-   */
-  getClient(server: ResolvedServer, opts?: {
-    definitionGuid?: string;
-  }): 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. 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
-   * connections and server-side definition pointers) intact. Nothing expires
-   * these on its own — the byte budget is the only other pressure — so this is
-   * the operator's release valve when a definition's inputs no longer describe
-   * its output, e.g. it reads an external source that has since changed.
-   */
-  clearSolveCaches(): void;
-  /** Dispose every warm client. Test seam / shutdown hook. */
-  disposeAll(): void;
-}
 interface SolveCacheStats {
   warmClients: number;
   entries: number;
@@ -100,7 +48,6 @@ interface SolveCacheStats {
   /** Entries dropped under size/byte pressure (not replacement or manual clears). */
   evictions: number;
 }
-export declare function createClientCache(config: ClientCacheConfig): ClientCache;
 /**
  * In-process cache of `.gh` definition bytes, keyed by immutable **version id**.
  *
@@ -133,7 +80,7 @@ interface ByteRefOutcome {
 /** A definition reference shaped for `@selvajs/compute`'s `DefinitionRef`. */
 interface ByteCacheRef {
   key: string;
-  load: () => Promise<Uint8Array>;
+  load: (signal?: AbortSignal) => Promise<Uint8Array>;
   outcome: ByteRefOutcome;
 }
 interface ByteCacheStats {
@@ -143,65 +90,23 @@ interface ByteCacheStats {
   entries: number;
   bytes: number;
 }
-interface DefinitionByteCache {
-  getOrLoad(versionId: string, load: () => Promise<Uint8Array>): ByteCacheRef;
-  stats(): ByteCacheStats;
-  clear(): void;
+/** A pre-solve prep sub-phase: `[label, ms]`, surfaced as a `p_*` Server-Timing entry. */
+type PrepMark = [string, number];
+interface CacheVerdict {
+  fromCache: boolean;
+  definitionReuploaded?: boolean;
 }
 /**
- * @param maxBytes total retained-byte budget; `0` (or negative) disables caching
- *   entirely — every `load()` calls the loader and nothing is retained.
+ * skipped = scheduler never materialized bytes (pointer-known solve, the whole point of this
+ * path); hit = warm byte cache; miss = fell through to storage.
  */
-export declare function createDefinitionByteCache(maxBytes: number): DefinitionByteCache;
+type DefBytesVerdict = 'skipped' | 'hit' | 'miss';
 /** Compute-response contract version. Bump (and document the change) whenever the envelope's shape changes in a way a consumer could observe. */
 export declare const COMPUTE_CONTRACT_VERSION: 1;
 export declare const COMPUTE_VERSION_HEADER = "X-Selva-Compute-Version";
-type PipelineInput = SolveInput;
-interface SolvePipelineArgs {
-  /**
-   * 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$1;
-  /** 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}; skips the
-   * pipeline's own build and solves this object directly.
-   *
-   * 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.
-   */
-  inputTree?: DataTree[];
-  /** User-chosen values keyed by input id; missing keys fall back to the schema default. */
-  values: Record<string, unknown>;
-  client: CachedClient;
-  responseMaxBytes: number;
-  /** Only phrases the timeout message — the scheduler enforces the deadline itself. */
-  solveDeadlineMs: number;
-  /** Client's `Accept-Encoding`; gzip is applied only when it advertises `gzip`. */
-  acceptEncoding: string;
-  /** Per-solve live-event callback the compute server hands to the definition; absent when the caller opened no stream. */
-  selvaEvents?: SelvaEventTarget;
-  /**
-   * 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()` 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. */
-  prepMarks?: [string, number][];
-}
-/** Phase timings the pipeline measured; the caller uses them for debug logging. */
+/** What the `Server-Timing` header carries for one caller, as data: read this, don't parse that. */
 interface SolvePhaseMetrics {
+  defLoadMs: number;
   treeBuildMs: number;
   solveMs: number;
   serializeMs: number;
@@ -210,6 +115,11 @@ interface SolvePhaseMetrics {
   serializedBytes: number;
   /** Null when compression was skipped. */
   compressedBytes: number | null;
+  /** The compute server's own timing; null when it reports none. */
+  rhino: ServerTiming | null;
+  settle: CacheVerdict;
+  /** Absent for raw-bytes solves. */
+  defBytes?: DefBytesVerdict;
 }
 /** A ready-to-send response: body + headers + the solve result + phase metrics. */
 interface SolveEnvelope {
@@ -220,20 +130,21 @@ interface SolveEnvelope {
   result: GrasshopperComputeResponse;
   metrics: SolvePhaseMetrics;
 }
+/** Whether an `Accept-Encoding` header takes gzip. `gzip;q=0` is a client refusing it. */
+export declare function acceptsGzip(acceptEncoding: string): boolean;
 /**
- * `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.
+ * `ok` carries the envelope; every other variant names an expected failure:
+ * `SolveEngine.toWebResponse` maps each to a status. `durationMs` on error variants is the solve
+ * wall time up to the failure, for the metric record.
  */
-type SolveOutcome = {
+type SolveEngineOutcome = {
   kind: 'ok';
   envelope: SolveEnvelope;
   solveMs: number;
   errorCount: number;
   warningCount: number;
-} | {
+} | SolveFailure;
+type SolveFailure = {
   kind: 'timeout';
   durationMs: number;
   message: string;
@@ -243,11 +154,21 @@ type SolveOutcome = {
 } | {
   kind: 'too_large';
 } |
-/** 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. */
+/** The compute server refused the request body (its `RHINO_COMPUTE_MAX_REQUEST_SIZE`). */
+{
+  kind: 'request_too_large';
+  durationMs: number;
+  message: string;
+} |
+/**
+ * Retryable: no result, through no fault of the request, and `retryAfterSeconds` is a backoff
+ * hint. Scheduler backpressure rejected the solve before it ran (`queue_full`,
+ * `queue_timeout`), or its client was shut down under it (`interrupted`).
+ */
 {
   kind: 'shed';
   durationMs: number;
-  reason: 'queue_full' | 'queue_timeout';
+  reason: 'queue_full' | 'queue_timeout' | 'interrupted';
   retryAfterSeconds: number;
   message: string;
 } | {
@@ -255,73 +176,13 @@ type SolveOutcome = {
   durationMs: number;
   error: unknown;
 };
-export 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},
- * 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
- * gzip-capable waiter) is left uncompressed — correct, just not maximally small.
- */
-export declare function adaptEnvelopeToEncoding(envelope: SolveEnvelope, acceptEncoding: string): {
-  body: string | Uint8Array;
-  headers: Record<string, string>;
-};
-/** The input tree a solve sends: each input's value, or its schema default when it has none. */
-export declare function buildSolveInputTree(inputs: SolveInput[], values: Record<string, unknown>): DataTree[];
-/**
- * In-process single-flight — dogpile protection for every solve.
- *
- * 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.
- *
- * Per app instance, above `ISolveResultCache`. No cross-instance lease (Redis
- * `SET NX`) yet.
- *
- * 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 {
-  /**
-   * 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 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>;
-  inFlight(): number;
-}
-interface SolveCacheSingleFlightOptions {
-  onJoin?: (key: string) => void;
-}
-export declare function createSolveCacheSingleFlight(options?: SolveCacheSingleFlightOptions): SolveCacheSingleFlight;
 /**
  * Subset of `ComputeLimits` (`@selvajs/server/compute`) the engine needs.
  * Pass the resolved object through as-is — extra fields are ignored.
  */
 interface SolveEngineLimits {
-  solveDeadlineMs: number;
   computeResponseMaxBytes: number;
-  computeReuseDefinitionCache: boolean;
   computeServerCachesolve: boolean;
-  computeCacheErroredSolves: boolean;
   computeMaxQueueDepth: number;
   computeQueueWaitMs: number;
   computeDefinitionCacheBytes: number;
@@ -329,26 +190,20 @@ interface SolveEngineLimits {
 }
 interface SolveEngineOptions {
   limits: SolveEngineLimits;
-  logger?: ILogger;
-  /** Max distinct warm compute servers before the LRU evicts the oldest. Default 16. */
+  /** Max distinct warm compute servers before the LRU evicts the oldest. */
   maxWarmComputeServers?: number;
   /** Concise cache/timing logs when truthy; `'verbose'` also dumps full lib-level requests/responses. Default off. */
   debug?: ClientCacheDebug;
+  /** Sink for the debug lines. Without it they go nowhere. */
   onDebugLog?: (message: string) => void;
   /** Fired when a caller joins an already-in-flight solve instead of running its own. */
   onSolveCoalesced?: (key: string) => void;
 }
 /**
- * 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.
+ * A `ByteCacheRef` obtained ahead of time from `engine.definitionRef()` (e.g. to
+ * read bytes for schema extraction before solving) is passed through as-is.
  */
-type SolveEngineDefinitionSource = Uint8Array | string | DefinitionRef$1 | ByteCacheRef | {
-  versionId: string;
-  load: () => Promise<Uint8Array>;
-};
+type SolveEngineDefinitionSource = Uint8Array | string | DefinitionRef$1 | ByteCacheRef;
 interface SolveEngineSolveArgs {
   server: ResolvedServer;
   definitionSource: SolveEngineDefinitionSource;
@@ -359,27 +214,26 @@ interface SolveEngineSolveArgs {
    * Ignored for the other source forms.
    */
   definitionKey?: string;
-  inputs: PipelineInput[];
+  /**
+   * The definition's inputs, from the schema you stored, never from the request: `id`, `nickname`,
+   * `paramType` and the bounds decide what reaches the definition, so a body that supplies them
+   * can drop a limit or fill a slot your host reserved.
+   */
+  inputs: SolveInput[];
   values: Record<string, unknown>;
   signal: AbortSignal;
   acceptEncoding?: string;
-  /** Stamped as `X-Selva-Definition` on this solve's client. */
+  /**
+   * Stamped as `X-Selva-Definition` when this solve builds the server's warm client. The header
+   * is fixed per client, so later solves on that server carry the first definition's guid.
+   */
   definitionGuid?: string;
   loadStartMs?: number;
   defLoadMs?: number;
-  prepMarks?: [string, number][];
-  /**
-   * Per-solve live-event callback. A coalesced waiter shares the first caller's
-   * compute call, so only that caller's target reaches the definition; the
-   * others still get the server-emitted start/end events on their own stream.
-   */
+  prepMarks?: PrepMark[];
+  /** Per-solve live-event callback. A solve carrying one runs its own compute call, never a shared one. */
   selvaEvents?: SelvaEventTarget;
 }
-interface FrameworkAgnosticResponse {
-  status: number;
-  headers: Record<string, string>;
-  body: string | Uint8Array;
-}
 interface SolveEngineStats {
   client: SolveCacheStats;
   definitionBytes: ByteCacheStats;
@@ -392,11 +246,17 @@ export declare class SolveEngine {
   private readonly clientCache;
   private readonly byteCache;
   private readonly singleFlight;
+  private readonly clientGenerations;
+  private lastClientGeneration;
   constructor(options: SolveEngineOptions);
   getClient(server: ResolvedServer, opts?: {
     definitionGuid?: string;
   }): Promise<CachedClient>;
-  definitionRef(versionId: string, load: () => Promise<Uint8Array>): ByteCacheRef;
+  definitionRef(versionId: string, load: (signal: AbortSignal) => Promise<Uint8Array>): ByteCacheRef;
+  /**
+   * Drops the warm client for `id`; call it when the server's URL or key changes. Solves already
+   * running finish on the old connection details first, so a revoked key stays in use until then.
+   */
   evictServer(id: string): void;
   clearSolveCaches(): void;
   /**
@@ -405,15 +265,23 @@ export declare class SolveEngine {
    */
   clearDefinitionCache(): void;
   stats(): SolveEngineStats;
-  solve(args: SolveEngineSolveArgs): Promise<SolveOutcome>;
-  toResponse(outcome: SolveOutcome, opts?: {
-    onError?: (status: number, body: {
-      message: string;
-      retryAfter?: number;
-    }) => never;
-  }): FrameworkAgnosticResponse;
-  toWebResponse(outcome: SolveOutcome): Response;
+  solve(args: SolveEngineSolveArgs): Promise<SolveEngineOutcome>;
+  /**
+   * The response for an outcome; the mapping from outcome to status lives here. Throws
+   * `compute_error`'s error: what it means for the caller is the host's to decide.
+   */
+  toWebResponse(outcome: SolveEngineOutcome): Response;
+  /**
+   * Part of the coalesce key: after an eviction the id stays and the client changes, and a new
+   * caller joining a draining flight would get an answer from the old URL or key.
+   */
+  private clientGeneration;
   private resolveDefinitionSource;
 }
-export { type ByteCacheRef, type ByteCacheStats, type ByteRefOutcome, type CachedClient, type ClientCache, type ClientCacheConfig, type DefinitionByteCache, type DefinitionRef, type FrameworkAgnosticResponse, type PipelineInput, type ResolvedServer, type ServerIdentity, type SolveCacheSingleFlight, type SolveCacheSingleFlightOptions, type SolveCacheStats, type SolveDefinition, type SolveEngineDefinitionSource, type SolveEngineLimits, type SolveEngineOptions, type SolveEngineSolveArgs, type SolveEngineStats, type SolveEnvelope, type SolveInput, type SolveOutcome, type SolvePhaseMetrics, type SolvePipelineArgs, isDefinitionRef };
+/**
+ * What `SolveEngine.solve` takes as `inputs`, from a schema the host stored. The bounds live on
+ * the number widgets in the layout, not on `schema.inputs`, so without them nothing clamps.
+ */
+export declare function solveInputsFromSchema(schema: UISchema): SolveInput[];
+export type { ByteCacheRef, ByteCacheStats, ByteRefOutcome, CachedClient, DefinitionRef, ResolvedServer, SolveCacheStats, SolveDefinition, SolveEngineDefinitionSource, SolveEngineLimits, SolveEngineOptions, SolveEngineOutcome, SolveEngineSolveArgs, SolveEngineStats, SolveEnvelope, SolveInput, SolveLimits, SolvePhaseMetrics };
 //# sourceMappingURL=server.d.ts.map