@selvajs/solve 2.0.0-beta.8 → 2.0.0

package/dist/server.d.cts

@@ -1,419 +0,0 @@
-import { t as SolveInput } from "./solve-input-CUjVGYPC.cjs";
-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";
-/**
- * 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.
- */
-type ServerIdentity = string & {
-  readonly __brand: 'ServerIdentity';
-};
-/** Minimal resolved-server shape the cache needs (a subset of the app's `ComputeServerConfig`). */
-interface ResolvedServer {
-  id: string;
-  serverUrl: string;
-  /** Sent as the `RhinoComputeKey` header. */
-  apiKey?: string;
-}
-export declare function serverIdentity(server: Pick<ResolvedServer, 'id'>): ServerIdentity;
-interface CachedClient {
-  client: GrasshopperClient;
-  scheduler: SolveScheduler;
-}
-/**
- * Debug verbosity: `false` is silent, `true` gives concise cache/timing logs
- * (`onDebugLog`), `'verbose'` also enables full lib-level request/response
- * 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;
-  bytes: number;
-  hits: number;
-  misses: number;
-  /** 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**.
- *
- * Turns an eager `storage.get(fileKey)` on every solve request into a lazy
- * `DefinitionRef.load()`: the scheduler calls `load()` only when an upload is
- * unavoidable (a pointer-known re-solve never touches storage or this cache).
- *
- * The key MUST be the version id, never a `fileKey` — a delete-latest-then-
- * reupload can reuse a `fileKey` for different content, which would silently
- * serve one version's bytes for another with no diagnostic. Callers pass
- * `version.id`, and the returned `DefinitionRef.key` is that same id, so the
- * scheduler's own result/pointer cache keys on the same immutable identity.
- *
- * Eviction is LRU by total byte budget, not entry count — definitions range
- * from tens of KB to hundreds of MB, so a count cap would either pin
- * gigabytes or evict uselessly. `COMPUTE_DEFINITION_CACHE_MB` sets the
- * budget (see `createDefinitionByteCache`). No TTL: version ids are
- * immutable, so a cached entry can never go stale. An entry larger than the
- * whole budget is served but never retained.
- */
-/**
- * Per-`getOrLoad` outcome, observable after the scheduler has (or hasn't)
- * called `load()` — lets the solve pipeline emit a `def_bytes` Server-Timing
- * verdict (`skipped` / `hit` / `miss`).
- */
-interface ByteRefOutcome {
-  loaded: boolean;
-  fromCache: boolean;
-}
-/** A definition reference shaped for `@selvajs/compute`'s `DefinitionRef`. */
-interface ByteCacheRef {
-  key: string;
-  load: () => Promise<Uint8Array>;
-  outcome: ByteRefOutcome;
-}
-interface ByteCacheStats {
-  hits: number;
-  misses: number;
-  evictions: number;
-  entries: number;
-  bytes: number;
-}
-interface DefinitionByteCache {
-  getOrLoad(versionId: string, load: () => Promise<Uint8Array>): ByteCacheRef;
-  stats(): ByteCacheStats;
-  clear(): void;
-}
-/**
- * @param maxBytes total retained-byte budget; `0` (or negative) disables caching
- *   entirely — every `load()` calls the loader and nothing is retained.
- */
-export declare function createDefinitionByteCache(maxBytes: number): DefinitionByteCache;
-/** 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. */
-interface SolvePhaseMetrics {
-  treeBuildMs: number;
-  solveMs: number;
-  serializeMs: number;
-  gzipMs: number;
-  serverTotalMs: number;
-  serializedBytes: number;
-  /** Null when compression was skipped. */
-  compressedBytes: number | null;
-}
-/** A ready-to-send response: body + headers + the solve result + phase metrics. */
-interface SolveEnvelope {
-  /** A gzip `Uint8Array` when `encoding === 'gzip'`, else the JSON string. */
-  body: string | Uint8Array;
-  encoding?: 'gzip';
-  headers: Record<string, string>;
-  result: GrasshopperComputeResponse;
-  metrics: SolvePhaseMetrics;
-}
-/**
- * `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';
-  envelope: SolveEnvelope;
-  solveMs: number;
-  errorCount: number;
-  warningCount: number;
-} | {
-  kind: 'timeout';
-  durationMs: number;
-  message: string;
-} | {
-  kind: 'client_abort';
-  durationMs: number;
-} | {
-  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. */
-{
-  kind: 'shed';
-  durationMs: number;
-  reason: 'queue_full' | 'queue_timeout';
-  retryAfterSeconds: number;
-  message: string;
-} | {
-  kind: 'compute_error';
-  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;
-  computeSolveCacheBytes: number;
-}
-interface SolveEngineOptions {
-  limits: SolveEngineLimits;
-  logger?: ILogger;
-  /** Max distinct warm compute servers before the LRU evicts the oldest. Default 16. */
-  maxWarmComputeServers?: number;
-  /** 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. */
-  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.
- */
-type SolveEngineDefinitionSource = Uint8Array | string | DefinitionRef$1 | ByteCacheRef | {
-  versionId: string;
-  load: () => Promise<Uint8Array>;
-};
-interface SolveEngineSolveArgs {
-  server: ResolvedServer;
-  definitionSource: SolveEngineDefinitionSource;
-  /**
-   * 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. */
-  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.
-   */
-  selvaEvents?: SelvaEventTarget;
-}
-interface FrameworkAgnosticResponse {
-  status: number;
-  headers: Record<string, string>;
-  body: string | Uint8Array;
-}
-interface SolveEngineStats {
-  client: SolveCacheStats;
-  definitionBytes: ByteCacheStats;
-  coalescing: {
-    inFlight: number;
-  };
-}
-export declare class SolveEngine {
-  private readonly limits;
-  private readonly clientCache;
-  private readonly byteCache;
-  private readonly singleFlight;
-  constructor(options: SolveEngineOptions);
-  getClient(server: ResolvedServer, opts?: {
-    definitionGuid?: string;
-  }): Promise<CachedClient>;
-  definitionRef(versionId: string, load: () => Promise<Uint8Array>): ByteCacheRef;
-  evictServer(id: string): void;
-  clearSolveCaches(): void;
-  /**
-   * Drop every retained `.gh` byte entry. Safe at any time: entries key on an
-   * immutable version id, so clearing costs a storage re-read and nothing else.
-   */
-  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;
-  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 };
-//# sourceMappingURL=server.d.cts.map

package/dist/shared.cjs

@@ -1 +0,0 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./outcome-DUHQoZqq.cjs");exports.SOLVE_BLOCKED_MARKER=e.i,exports.decodeOutcome=e.t,exports.finalizeResult=e.n,exports.outcomeFromComputeMessages=e.r;

package/dist/shared.d.cts

@@ -1,3 +0,0 @@
-import { a as SOLVE_BLOCKED_MARKER, c as SolveResult, i as outcomeFromComputeMessages, n as decodeOutcome, o as SolveDiagnostic, r as finalizeResult, s as SolveFn, t as SolveOutcome } from "./outcome-DsNmx27P.cjs";
-import { t as SolveInput } from "./solve-input-CUjVGYPC.cjs";
-export { SOLVE_BLOCKED_MARKER, type SolveDiagnostic, type SolveFn, type SolveInput, type SolveOutcome, type SolveResult, decodeOutcome, finalizeResult, outcomeFromComputeMessages };

package/dist/solve-input-CUjVGYPC.d.cts

@@ -1,11 +0,0 @@
-import { SchemaInput } from "@selvajs/schemas";
-/**
- * A schema input carrying the optional numeric bounds tree building clamps to. Only numeric params
- * (sliders) carry them; text or geometry inputs carry none.
- */
-type SolveInput = SchemaInput & {
-  minimum?: number;
-  maximum?: number;
-};
-export { SolveInput as t };
-//# sourceMappingURL=solve-input-CUjVGYPC.d.cts.map