@selvajs/solve 2.0.0-beta.11 → 2.0.0-beta.12

package/README.md

@@ -19,7 +19,7 @@ This package owns everything between those two points. Nothing else.
 | ----------------------- | ----------------------- |
 | A web page with sliders | `@selvajs/solve/client` |
 | An API endpoint         | `@selvajs/solve/server` |
-| Just need the types     | `@selvajs/solve/shared` |
+| Types and verdict logic | `@selvajs/solve/shared` |
 
 There is no `.` export on purpose — see [Why no root export](#why-no-root-export).
 
@@ -157,15 +157,17 @@ if rebuilt per request.
 // $lib/server/compute/engine.server.ts
 import { SolveEngine } from '@selvajs/solve/server';
 
-export const engine = new SolveEngine({ limits: computeLimits, logger });
+export const engine = new SolveEngine({ limits: computeLimits });
 ```
 
 ```ts
 // routes/api/v1/compute/+server.ts
+import { solveInputsFromSchema } from '@selvajs/solve/server';
+
 const outcome = await engine.solve({
 	server: serverConfig, // which Rhino.Compute
 	definitionSource, // the .gh file (bytes, URL, or cached ref)
-	inputs, // the definition's input params
+	inputs: solveInputsFromSchema(storedSchema), // yours, never the request's
 	values, // what the browser sent
 	signal: request.signal, // client disconnects → cancel upstream
 	acceptEncoding: request.headers.get('accept-encoding') ?? ''
@@ -174,6 +176,9 @@ const outcome = await engine.solve({
 return engine.toWebResponse(outcome);
 ```
 
+Read `inputs` from the schema you stored. A request that supplies them picks the ids, types and
+bounds that reach the definition: it can drop a limit or fill a slot your host reserved.
+
 `solve()` doesn't throw for an expected failure. It returns one of these, so you can branch before
 handing it to `toWebResponse`:
 
@@ -197,11 +202,11 @@ return engine.toWebResponse(outcome);
 engine.solve()
    │
    ├─ 1. warm client cache ····· reuse the open Rhino.Compute connection
-   ├─ 2. definition bytes ······ already uploaded? send a pointer, not the .gh
+   ├─ 2. build input tree ······ values → Grasshopper DataTree
    ├─ 3. single-flight ········· 5 users, same inputs → 1 actual solve
-   ├─ 4. build input tree ······ values → Grasshopper DataTree
+   ├─ 4. definition bytes ······ already uploaded? send a pointer, not the .gh
    ├─ 5. SOLVE ················· the only slow step
-   └─ 6. gzip + Server-Timing ·· ready-to-send envelope
+   └─ 6. gzip + Server-Timing ·· one envelope per caller
 ```
 
 Each layer is covered in [`src/server/README.md`](./src/server/README.md).
@@ -244,8 +249,8 @@ solve needs.
 
 ## Why no root export
 
-`server/` uses `node:zlib`, `node:crypto`, and reads compute-server credentials. A `.` barrel
-joining both halves would let a browser bundle pull all of that in by accident.
+`server/` uses `node:zlib` and `undici`, and holds compute-server credentials. A `.` barrel joining
+both halves would let a browser bundle pull all of that in by accident.
 
 ```
       shared/          the types both sides speak
@@ -253,7 +258,8 @@ joining both halves would let a browser bundle pull all of that in by accident.
    client/  server/    never import each other
 ```
 
-Enforced by `no-restricted-imports` and a bundle-boundary test, not by convention.
+Enforced by `no-restricted-imports`, a `tsc` pass per half and a bundle-boundary test, not by
+convention.
 
 ## Not in this package
 
@@ -267,4 +273,4 @@ Enforced by `no-restricted-imports` and a bundle-boundary test, not by conventio
 ## Going deeper
 
 - [`src/client/README.md`](./src/client/README.md) — writing your own driver, the value map, mesh ownership
-- [`src/server/README.md`](./src/server/README.md) — cache layers, coalescing, `runSolvePipeline`
+- [`src/server/README.md`](./src/server/README.md) — cache layers, coalescing, encoding

package/dist/abort-CNJ8Sn4g.js

@@ -0,0 +1,13 @@
+// src/shared/abort.ts
+/** `promise`'s outcome, or a rejection with `signal`'s reason if that fires first. */
+function raceAbort(promise, signal) {
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		if (signal.aborted) onAbort();
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+	});
+}
+export { raceAbort as t };
+
+//# sourceMappingURL=abort-CNJ8Sn4g.js.map

package/dist/abort-CNJ8Sn4g.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-CNJ8Sn4g.js","names":[],"sources":["../src/shared/abort.ts"],"sourcesContent":["/** `promise`'s outcome, or a rejection with `signal`'s reason if that fires first. */\nexport function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {\n\treturn new Promise((resolve, reject) => {\n\t\tconst onAbort = () => reject(signal.reason);\n\t\tif (signal.aborted) onAbort();\n\t\tsignal.addEventListener('abort', onAbort, { once: true });\n\t\tpromise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));\n\t});\n}\n"],"mappings":";;AACA,SAAgB,UAAa,SAAqB,QAAiC;CAClF,OAAO,IAAI,SAAS,SAAS,WAAW;EACvC,MAAM,gBAAgB,OAAO,OAAO,MAAM;EAC1C,IAAI,OAAO,SAAS,QAAQ;EAC5B,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,QAAQ,KAAK,SAAS,MAAM,CAAC,CAAC,cAAc,OAAO,oBAAoB,SAAS,OAAO,CAAC;CACzF,CAAC;AACF"}

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { c as SolveResult, n as decodeOutcome, o as SolveDiagnostic, r as finalizeResult, s as SolveFn, t as SolveOutcome } from "./outcome-DsNmx27P.js";
-import { ProgressPayload, SolveEvent, UISchema } from "@selvajs/schemas";
+import { a as SolveFn, i as SolveDiagnostic, n as decodeOutcome, o as SolveResult, r as finalizeResult, t as SolveOutcome } from "./outcome-Bk9mnMi0.js";
+import { ProgressPayload, SolveEndedKind, SolveEvent, UISchema } from "@selvajs/schemas";
 import { GrasshopperComputeResponse } from "@selvajs/compute/grasshopper";
 /**
  * Transport behind a solve session. `solve()` never returns outputs directly — results
@@ -31,11 +31,12 @@ interface SolveDriver {
    */
   readonly hasQueued?: boolean;
   /**
-   * Drops cached solve results. Optional — only the request/response driver has a
-   * client-side memo to clear. Call on rebuild: a definition swap must not serve a
-   * stale result from the prior definition's input space.
+   * Forgets the current definition: stops its running solve, drops its cached results, and
+   * never reports for it again. The session calls this on rebuild and dispose, where a late
+   * result would land in the wrong definition. Optional: a push transport leaves it out, because
+   * the solve it would stop belongs to the Grasshopper canvas, not to this session.
    */
-  clearCache?(): void;
+  reset?(): void;
   /**
    * Live events from the running solve, when the transport carries them (a WebSocket frame
    * locally, an SSE stream in cloud mode). Returns the unsubscribe. A driver without a live
@@ -69,9 +70,9 @@ interface LiveSolveState {
   readonly diagnostics: readonly SolveDiagnostic[];
   /** The newest `progress` per source. A report without a source is keyed by `''`. */
   readonly progress: ReadonlyMap<string, ProgressPayload>;
-  /** `solveEnded`'s payload once it arrives: `ok`, `blocked`, `aborted` or `error`. */
+  /** `solveEnded`'s payload once it arrives. */
   readonly ended: {
-    readonly kind: string;
+    readonly kind: SolveEndedKind;
   } | null;
   /** Events of kinds this package does not know, oldest first. */
   readonly other: readonly SolveEvent[];
@@ -79,7 +80,6 @@ interface LiveSolveState {
   readonly lastSeq: number;
 }
 export declare const EMPTY_LIVE_SOLVE: LiveSolveState;
-export declare function reduceLiveSolve(state: LiveSolveState, event: SolveEvent): LiveSolveState;
 interface ExternalValueRef {
   scopeKey: string;
   inputId: string;
@@ -105,79 +105,7 @@ export declare function getExternalInputs(schema: UISchema): ExternalInput[];
  * live meshes stay on `session.meshes`.
  */
 type RetainedSolveResult<TSource = unknown> = Omit<SolveResult<never, TSource>, 'meshes'>;
-interface SolveSessionState {
-  values: Record<string, unknown>;
-  error: string;
-  computeErrors: string[];
-  computeWarnings: string[];
-  /**
-   * The same messages with their level, source and `isGate`. What decides whether a solve
-   * interrupts the user; the two string arrays above stay the plain display lists.
-   */
-  diagnostics: SolveDiagnostic[];
-  /**
-   * The last solve was refused by a guard in the definition. Separate from `computeErrors`
-   * being non-empty: a solve can report errors and still return usable outputs, and the UI
-   * needs to tell "solved, with complaints" from "would not solve".
-   */
-  blocked: boolean;
-  /**
-   * The last solve raised messages the user has not acknowledged yet. While true the result
-   * is withheld: `meshes` and the solve's outputs stay at their previous values until
-   * `acknowledge()` releases them.
-   */
-  awaitingAck: boolean;
-  /**
-   * The withheld result, kept whole so `acknowledge()` can apply it without a re-solve.
-   * Null whenever `awaitingAck` is false. A newer solve replaces it: the user is always
-   * confirming the most recent result, never a stale one.
-   */
-  heldResult: SolveResult | null;
-  meshes: unknown[];
-  /** Values changed since the last solve, in manual (instanceSolve === false) mode. */
-  pendingValues: Record<string, unknown>;
-  hasPendingChanges: boolean;
-  hasNeverSolved: boolean;
-  /**
-   * The last result reported, minus its meshes. Null before the first solve.
-   *
-   * Lags `values` by design: nothing updates it on `setValue` or `loadValues`, so between a
-   * value change and the next report it describes the *previous* input set. That is what a
-   * commit gate wants — what is on screen, not what is pending — so `lastResult.values`
-   * disagreeing with `state.values` mid-scrub is the feature, not a bug.
-   */
-  lastResult: RetainedSolveResult | null;
-}
-type ExternalReader = (ref: ExternalValueRef) => unknown | undefined;
-/**
- * Client-sourced inputs are hydrated from `read` and left absent when no stored value
- * exists, so the missing-inputs panel can detect them. Other inputs fall back to their
- * declared default, then the paramType default.
- */
-export declare function buildInitialValues(schema: UISchema, scopeKey: string, read: ExternalReader): Record<string, unknown>;
-/** Manual-solve schemas (instanceSolve === false) start dirty; auto-solve schemas start clean. */
-export declare function makeInitialFlags(instanceSolve: boolean | undefined): {
-  hasPendingChanges: boolean;
-  hasNeverSolved: boolean;
-};
-/** Manual mode defers (records the pending value, raises the dirty flag) instead of solving. */
-export declare function applyValueChange(state: SolveSessionState, id: string, value: unknown, instanceSolve: boolean | undefined): {
-  state: SolveSessionState;
-  shouldSolve: boolean;
-};
-/**
- * Solve outputs live in the same `values` map as inputs (so widgets like dynamic value
- * lists can read them) but must not be echoed back to the driver: a measured 6.4 MB
- * options-list output showed this can re-upload a multi-MB payload no backend reads.
- */
-export declare function pickInputValues(schema: UISchema | undefined, values: Record<string, unknown>): Record<string, unknown>;
-export declare function applySolveResult(state: SolveSessionState, result: SolveResult): SolveSessionState;
 type SolvePhase = 'idle' | 'solving' | 'review' | 'blocked';
-/**
- * One value for what a host should show. Solving wins: a new solve supersedes a held or refused
- * result. `isSolving` is passed in because the driver owns it.
- */
-export declare function solvePhase(state: SolveSessionState, isSolving: boolean): SolvePhase;
 /**
  * How a solve ended, once nothing about it can change any more: a held result counts only
  * after the user accepts or rejects it, and a result a queued solve is about to replace never
@@ -188,7 +116,7 @@ type SolveSettlement = {
   result: RetainedSolveResult;
   diagnostics: SolveDiagnostic[];
 } |
-/** The user rejected a held result; the screen still shows the one before it. */
+/** A held result the user rejected or a newer solve replaced; the screen still shows the one before it. */
 {
   status: 'discarded';
   diagnostics: SolveDiagnostic[];
@@ -262,10 +190,10 @@ interface SolveSession {
   abort(): void;
   readonly meshes: unknown[];
   /**
-   * The last reported result without its meshes — what the viewer is currently showing,
-   * including the `source`/`values` pair a commit path needs. Null before the first solve,
-   * and again after `rebuild()`. Survives `reportError`: a failed solve leaves the last good
-   * geometry on screen, so a host committing what it sees should still see what produced it.
+   * What the viewer is currently showing, including the `source`/`values` pair a commit path
+   * needs. Null before the first solve, and again after `rebuild()`. Survives `reportError`: a
+   * failed solve leaves the last good geometry on screen, so a host committing what it sees
+   * should still see what produced it.
    */
   readonly lastResult: RetainedSolveResult | null;
   readonly hasPendingChanges: boolean;
@@ -282,7 +210,8 @@ interface SolveSession {
   /**
    * The result for the current inputs, solving only when it has to: right away from the result
    * on screen when nothing changed, after the running or held solve when there is one, else
-   * after a new solve. For an action that needs a fresh result, such as an export.
+   * after a new solve. For an action that needs a fresh result, such as an export. Inputs whose
+   * result the user just discarded settle as `discarded` rather than ask them again.
    */
   ensureSolved(): Promise<SolveSettlement>;
   /** Fires once per settled solve, the ones input changes start included. Returns the unsubscribe. */
@@ -298,9 +227,9 @@ interface SolveSession {
   /** For driver-owned state the session only forwards: `isSolving` lives on the driver, so wire this to its `onChange`. */
   notify(): void;
   /**
-   * Stops listening to the driver's live events and drops every subscriber. Call when the
-   * session is discarded: the event source can outlive it (the cloud stream belongs to the tab),
-   * and would otherwise keep feeding a session nobody reads.
+   * Resets the driver, stops listening to its live events and drops every subscriber. Call when
+   * the session is discarded: the event source can outlive it (the cloud stream belongs to the
+   * tab), and would otherwise keep feeding a session nobody reads. Inert afterwards.
    */
   dispose(): void;
 }
@@ -312,9 +241,13 @@ interface SolveSessionArgs {
 export declare function createSolveSession(args: SolveSessionArgs): SolveSession;
 /**
  * Deterministic string key for a set of input values. Sorts object keys at every level so
- * two logically-equal inputs built in different key order collide.
+ * two logically-equal inputs built in different key order collide. Otherwise matches what
+ * `JSON.stringify` sends: `toJSON` is honoured and an `undefined` property is absent, which a
+ * server treats differently from `null`.
+ *
+ * Throws on a `bigint`, as `JSON.stringify` does.
  */
-export declare function stableInputKey(values: Record<string, unknown>): string;
+export declare function stableInputKey(input: unknown): string;
 /**
  * Omit when results are mesh-free or nothing takes ownership of the meshes — the memo then
  * stores and serves them by reference, which is safe only because nothing frees them behind
@@ -326,17 +259,6 @@ interface MeshPolicy<TMesh> {
   /** Must not free anything shared with live content (e.g. materials another object still uses). */
   release(meshes: TMesh[]): void;
 }
-interface SolveMemoOptions<TMesh> {
-  /** Entry cap, not a byte cap. Kept small on purpose: this targets the slider-scrub loop, not a durable cache. */
-  max?: number;
-  meshPolicy?: MeshPolicy<TMesh>;
-}
-interface SolveMemo<TMesh = unknown> {
-  get(values: Record<string, unknown>): SolveResult<TMesh> | undefined;
-  set(values: Record<string, unknown>, result: SolveResult<TMesh>): void;
-  clear(): void;
-}
-export declare function createSolveMemo<TMesh = unknown>(options?: SolveMemoOptions<TMesh>): SolveMemo<TMesh>;
 interface RequestResponseDriverOptions<TMesh> {
   /** How long one solve may take before the client aborts it (ms). Pass the server's `COMPUTE_SOLVE_DEADLINE_MS` so the two agree. */
   solveDeadlineMs: number;
@@ -363,42 +285,16 @@ interface SolveEventStream extends SolveEventSource {
   readonly streamId: string;
   /** The solve the server last reported as started and not yet ended; null between solves. */
   readonly currentSolveId: string | null;
+  /** Final: the stream does not reopen, and a later subscriber hears nothing. */
   close(): void;
 }
 export declare function createSolveEventStream(options: SolveEventStreamOptions): SolveEventStream;
-/**
- * Single-in-flight, latest-wins throttle for any async operation: only one run at a
- * time, a newly triggered value overwrites the single pending slot (no queue), and a
- * stale run can be aborted via `AbortController` or timeout.
- *
- * Framework-free: `isRunning` is a plain getter, not a store. A reactive host must
- * subscribe via `onChange` (see `@selvajs/ui`'s rune adapter) — polling the getter
- * directly reads correct values but won't trigger a re-render.
- */
-interface AsyncThrottleOptions {
-  /**
-   * How long one run may take before it is aborted (ms). Required and deliberately
-   * undefaulted: this is a generic throttle, so it has no basis for guessing what
-   * the caller's work costs. Callers driving a Selva solve pass the deadline the
-   * server enforces (`COMPUTE_SOLVE_DEADLINE_MS`) — a shorter local guess would abort
-   * solves the server would have finished.
-   */
-  runDeadlineMs: number;
-  onChange?: () => void;
-}
-interface AsyncThrottle<T> {
-  trigger: (values: T) => void;
-  readonly isRunning: boolean;
-  readonly hasPending: boolean;
-  cancel: () => void;
-}
-export declare function createAsyncThrottle<T>(run: (values: T, signal: AbortSignal) => Promise<void>, options: AsyncThrottleOptions): AsyncThrottle<T>;
 interface ComputeFetchSolveFnOptions<TMesh = unknown> {
   /** The compute endpoint to POST to, e.g. `/api/compute`. */
   endpoint: string;
   /** Definition URL (or `local:<guid>`) to solve — read per-solve so it can track a route param. */
   definitionUrl: () => string;
-  /** Schema input params, sent as the request body's `inputs`. */
+  /** Schema input params, sent as the request body's `inputs`. A stored definition's server ignores them. */
   inputs: () => Array<{
     id: string;
   }>;
@@ -415,15 +311,18 @@ interface ComputeFetchSolveFnOptions<TMesh = unknown> {
   meshes?: {
     extract: (response: GrasshopperComputeResponse, opts: {
       debug: boolean;
+      signal: AbortSignal;
     }) => TMesh[] | Promise<TMesh[]>;
   };
   /** Gates ALL console telemetry (timing, cache verdicts, whales, heap). Default `false`. */
   debug?: boolean;
-  /** Called on a 429. Default: throws a cooldown-aware Error; the cooldown itself is tracked either way. */
+  /** Called on a 429 and on a solve refused during its cooldown, before the rate-limit Error. */
   onRateLimited?: (retryAfterSeconds: number) => void;
-  /** Called on a 401 or a login-page redirect. Default: throws an actionable "reload to sign in again" Error. */
+  /** Called on a 401 or a login-page redirect, before the "sign in again" Error. */
   onSessionExpired?: () => void;
+  /** Where the server redirects an expired session. Default `/login`. */
+  loginPath?: string;
 }
 export declare function createComputeFetchSolveFn<TMesh = unknown>(opts: ComputeFetchSolveFnOptions<TMesh>): SolveFn<TMesh, GrasshopperComputeResponse>;
-export { type AsyncThrottle, type ComputeFetchSolveFnOptions, type ExternalInput, type ExternalReader, type ExternalValueRef, type LiveSolveState, type MeshPolicy, type RequestResponseDriverOptions, type RetainedSolveResult, type SolveDiagnostic, type SolveDriver, type SolveEventSource, type SolveEventStream, type SolveEventStreamOptions, type SolveFn, type SolveMemo, type SolveMemoOptions, type SolveOutcome, type SolvePhase, type SolveReporter, type SolveResult, type SolveSession, type SolveSessionArgs, type SolveSessionState, type SolveSettlement, decodeOutcome, finalizeResult };
+export { type ComputeFetchSolveFnOptions, type ExternalInput, type ExternalValueRef, type LiveSolveState, type MeshPolicy, type RequestResponseDriverOptions, type RetainedSolveResult, type SolveDiagnostic, type SolveDriver, type SolveEventSource, type SolveEventStream, type SolveEventStreamOptions, type SolveFn, type SolveOutcome, type SolvePhase, type SolveReporter, type SolveResult, type SolveSession, type SolveSessionArgs, type SolveSettlement, decodeOutcome, finalizeResult };
 //# sourceMappingURL=client.d.ts.map