nexus-ai-pro 2.4.0 → 2.5.0

package/dist/server/deployments.d.ts

@@ -1,7 +1,7 @@
 import { type Regression, type RegressionMetric, type RunSample } from '../insights/regressions.js';
 import type { EvaluationScore, Evaluator } from '../types/evaluate.js';
-import type { DeploymentChange, DeploymentChangeRecord, DeploymentRecord, ReplicaReport, RevisionChoice, RevisionRequest, ServerAssistant, ServerDeployments, ServerStateStore } from '../types/server.js';
-export type { DeploymentChange, DeploymentChangeRecord, DeploymentRecord, ReplicaReport, RevisionChoice, RevisionReason, RevisionRequest, RunRevision, } from '../types/server.js';
+import type { BucketStrategy, DeploymentChange, DeploymentChangeRecord, DeploymentRecord, ReplicaReport, RevisionChoice, RevisionRequest, RunRecord, ServerAssistant, ServerDeployments, ServerStateStore } from '../types/server.js';
+export type { BucketStrategy, DeploymentChange, DeploymentChangeRecord, DeploymentRecord, ReplicaReport, RevisionChoice, RevisionReason, RevisionRequest, RunRevision, } from '../types/server.js';
 /** Options for `Deployments`. */
 export interface DeploymentsOptions {
     /**
@@ -22,7 +22,12 @@ export interface DeploymentsOptions {
     cacheMs?: number;
     /** History entries kept per deployment. Defaults to 50. */
     historyLimit?: number;
-    /** Receives heartbeat failures, which never stop the server. */
+    /**
+     * How long this replica gathers the runs it finished before writing them to its rollups, in
+     * milliseconds. Defaults to 1 second. Reading rollups through this object writes its own first.
+     */
+    rollupMs?: number;
+    /** Receives heartbeat and rollup write failures, which never stop the server. */
     onError?: (error: unknown) => void;
     /** Replaces the system clock, for tests. */
     now?: () => Date;
@@ -37,12 +42,50 @@ export interface RevisionedAssistantOptions {
     live?: string;
     /** What the assistant is, reported by the assistants endpoint. */
     description?: string;
+    /**
+     * How the deployment places threads, when it is first recorded. Defaults to `fnv1a-v1`. A deployment
+     * already recorded keeps its own; `Deployments.bucketing()` changes it.
+     */
+    bucketStrategy?: BucketStrategy;
+}
+/** One revision's finished runs, as a replica counts them for one deployment version. */
+export interface RevisionRollup {
+    /** Runs counted: succeeded, failed, and cancelled. */
+    runs: number;
+    /** Runs that succeeded or are awaiting input. */
+    succeeded: number;
+    /** Runs that failed or expired. */
+    failed: number;
+    /** Runs that were cancelled, which count neither way. */
+    cancelled: number;
+    /**
+     * Durations of succeeded and failed runs, as counts by bucket. A bucket's key is its index; each is
+     * 5% wider than the one before, so a percentile read from them is within 2.5% of the true one.
+     */
+    latency: Record<string, number>;
+    /** Total recorded cost of succeeded and failed runs, in US dollars. */
+    cost: number;
+    /** How many of those runs recorded a cost. */
+    costed: number;
+}
+/** What one replica counted under one deployment version, as stored in the state store. */
+export interface DeploymentRollup {
+    /** The assistant. */
+    assistant: string;
+    /** The deployment version the runs were routed under. */
+    deployment: number;
+    /** The replica that counted them. */
+    replica: string;
+    /** ISO-8601 time it was last written. */
+    updatedAt: string;
+    /** The counts, per revision. */
+    revisions: Record<string, RevisionRollup>;
 }
 /** What one revision's runs did, from `Deployments.stats()`. */
 export interface RevisionStats {
     /** The revision. */
     revision: string;
-    /** Runs recorded for it, finished or not. */
+    /** Runs recorded for it: finished or not from run records, and finished or cancelled from rollups. */
     runs: number;
     /** Runs that succeeded or are awaiting input. */
     succeeded: number;
@@ -100,12 +143,22 @@ export interface RunEvaluationReport {
 export declare class Deployments implements ServerDeployments {
     private readonly options;
     private readonly state;
+    /** What fresh workers carry, per assistant, read at most every `cacheMs`. */
+    private readonly fleet;
     /** The change in progress per deployment, which the next one waits for. */
     private readonly changing;
     private readonly now;
     private readonly registrations;
     private readonly cache;
     private heartbeat?;
+    /** Runs finished here and not yet written, per assistant and deployment version. */
+    private readonly pending;
+    /** This replica's rollups as last written, so a write needs no read. */
+    private readonly written;
+    private rollupTimer?;
+    private flushing;
+    /** Names this replica's rollups before the server attaches it with its own id. */
+    private readonly unattached;
     constructor(options?: DeploymentsOptions);
     /**
      * Serves an assistant through its revisions, by id: `{ '2026-09-01': v1, '2026-09-30': v2 }`.
@@ -116,6 +169,12 @@ export declare class Deployments implements ServerDeployments {
     assistant(id: string, revisions: Record<string, ServerAssistant>, options?: RevisionedAssistantOptions): ServerAssistant;
     /** Chooses the revision for a run. The server calls it through the assistant; tests may call it directly. */
     route(assistant: string, request: RevisionRequest): Promise<RevisionChoice | undefined>;
+    /**
+     * Whether changes are atomic across replicas: true when the state store has `putIfVersion()`.
+     * Otherwise, changes on this replica apply in order, but two replicas changing one deployment in
+     * the same instant can lose one change.
+     */
+    get atomicChanges(): boolean;
     /** Every deployment: those recorded, and the default of every assistant registered here that has none. */
     list(): Promise<DeploymentRecord[]>;
     /** One assistant's deployment, as recorded, or its default when this process registered it. */
@@ -131,20 +190,24 @@ export declare class Deployments implements ServerDeployments {
      * - `promote` makes a revision live, with all the traffic.
      * - `rollback` sends all traffic back to the live revision when a canary has any; otherwise it
      *   makes the previous live revision live again. `to` names the revision instead.
+     * - `bucketing` changes how new threads are placed in the split, keeping the split itself.
      *
      * `expectedVersion` applies a change only to the version it was decided on, and throws
      * `DEPLOYMENT_CONFLICT` otherwise, so two people — or a person and a canary guard — cannot undo each
      * other without noticing.
      *
      * Changes to one deployment through this object apply one at a time, so two made at once on one
-     * replica both land, in order. The state store has no atomic compare-and-set, so two replicas
-     * changing one deployment in the same instant can still lose one change: make changes from one
+     * replica both land, in order. Across replicas, a state store with `putIfVersion()` makes each
+     * change atomic: a replica that loses a race decides again on the winner's record. Without it, two
+     * replicas changing one deployment in the same instant can lose one change: make changes from one
      * place, or pass `expectedVersion` and retry a conflict.
      */
     change(assistant: string, change: DeploymentChange & {
         expectedVersion?: number;
     }, by?: string): Promise<DeploymentRecord>;
     private applyChange;
+    /** The record a change makes of the stored one, or of the default when none is stored. */
+    private decide;
     /** Sets each revision's share of new runs. */
     split(assistant: string, traffic: Record<string, number>, options?: {
         by?: string;
@@ -166,6 +229,14 @@ export declare class Deployments implements ServerDeployments {
         by?: string;
         reason?: string;
     }): Promise<DeploymentRecord>;
+    /**
+     * Changes how new threads and stateless runs are placed in the split. A thread already on a revision
+     * that takes traffic stays there; new threads are placed by the new strategy.
+     */
+    bucketing(assistant: string, strategy: BucketStrategy, options?: {
+        by?: string;
+        reason?: string;
+    }): Promise<DeploymentRecord>;
     /** Replicas whose heartbeat is fresh, newest first. */
     replicas(): Promise<ReplicaReport[]>;
     /**
@@ -174,19 +245,44 @@ export declare class Deployments implements ServerDeployments {
      * The server calls it from `start()`.
      */
     attach(report: () => ReplicaReport): Promise<void>;
-    /** Stops heartbeating and removes this replica's report. The server calls it from `stop()`. */
+    /**
+     * Writes the runs this replica counted, stops heartbeating, and removes this replica's report. The
+     * server calls it from `stop()`.
+     */
     detach(): Promise<void>;
     /** The revisions this process registered, and those fresh replicas report, for an assistant. */
     revisions(assistant: string): Promise<string[]>;
     /**
-     * What each revision's runs did, from the server's run records in the same store: counts, error
-     * rate, latency percentiles, and mean cost. `since` limits it to runs created from that time, such
-     * as the start of a canary; `limit` bounds how many recent runs are read, 2,000 by default.
+     * What each revision's runs did: counts, error rate, latency percentiles, and mean cost.
+     *
+     * With `deployment`, a version, they come from the rollups of every run routed under it, on every
+     * replica: the whole window a canary guard judges, in one read. Percentiles are then within 2.5%.
+     * Runs in flight are counted when they finish. A version no replica counted, such as one served
+     * only by replicas older than 2.5, falls back to run records.
+     *
+     * Otherwise they come from the server's run records in the same store. `since` limits them to runs
+     * created from that time, such as the start of a canary; `limit` bounds how many recent runs are
+     * read, 2,000 by default.
      */
     stats(assistant: string, options?: {
         since?: string;
         limit?: number;
+        deployment?: number;
     }): Promise<RevisionStats[]>;
+    /**
+     * Every revision's rollup under one deployment version, summed over the replicas that counted its
+     * runs. This replica's runs not yet written are written first.
+     */
+    rollups(assistant: string, deployment: number): Promise<Map<string, RevisionRollup>>;
+    /**
+     * Counts a finished run in this replica's rollup for the deployment version it was routed under.
+     * The server calls it as each run finishes. Counts are written every `rollupMs`, each replica to its
+     * own record, so counting never contends with another replica.
+     */
+    recordRun(run: RunRecord): void;
+    /** Writes the runs this replica counted and has not written yet. Failures go to `onError` and are retried. */
+    flushRollups(): Promise<void>;
+    private writeRollups;
     /**
      * One revision's finished runs since a time, as samples `compareRuns()` reads: a failed or
      * expired run is an error, a cancelled one is left out.
@@ -205,6 +301,8 @@ export declare class Deployments implements ServerDeployments {
     evaluate(assistant: string, options: RunEvaluationOptions): Promise<RunEvaluationReport>;
     /** The deployment the router uses, reusing a recent read. */
     private current;
+    /** The revisions fresh workers that claim queued runs report carrying, read at most every `cacheMs`. */
+    private workerRevisions;
     /** The deployment of a registered assistant before anything is recorded: its live revision, all traffic. */
     private initial;
     private knownRevisions;
@@ -236,6 +334,16 @@ export interface CanaryGuardOptions {
      * promoted. Without steps, a canary that holds up stays where it is until a person promotes it.
      */
     steps?: readonly number[];
+    /**
+     * What a canary is judged on.
+     *
+     * - `runs`, the default, reads run samples: the server's run records since the split last changed,
+     *   the latest 2,000, or those `samples` returns.
+     * - `rollups` reads the counts every replica keeps under the deployment's current version: every run
+     *   since the split last changed, however many, in one read. It judges the error rate, p95 latency,
+     *   and mean cost, not feedback, so it cannot be combined with `samples` or `feedback`.
+     */
+    from?: 'runs' | 'rollups';
     /**
      * Where a revision's runs come from. Defaults to the server's run records. Give it runs from a
      * trace store to judge on feedback scores too, with `feedback` naming the keys.
@@ -257,6 +365,9 @@ export interface CanaryGuardOptions {
      * `minErrorRateIncrease`, `latencyIncrease` with `minLatencyChangeMs`, `costIncrease`, and
      * `minFeedbackDrop`. A real regression rolls back, and noise or a trivial change does not. Without
      * it, the error rate uses a z-test at 95%, and latency and cost use their margins alone.
+     *
+     * From rollups, the error rate is judged by a z-test at this confidence, with
+     * `minErrorRateIncrease`, and latency and cost by their margins.
      */
     confidence?: number;
     /** The smallest rise in the error rate, absolute, that counts under `confidence`. Defaults to 0.02. */
@@ -315,5 +426,9 @@ export interface CanaryGuard {
  * first to act wins, and the rest find the deployment already moved.
  */
 export declare function watchCanaries(options: CanaryGuardOptions): CanaryGuard;
-/** A stable position in [0, 1) for a key: FNV-1a, so the same thread always lands in the same place. */
-export declare function bucket(key: string): number;
+/**
+ * A stable position in [0, 1) for a key, so the same thread always lands in the same place. The
+ * strategy defaults to `fnv1a-v1`, whose positions never change; `hash-v2` spreads sequential keys
+ * evenly too.
+ */
+export declare function bucket(key: string, strategy?: BucketStrategy): number;