Skip to content
v9.1.1
Français

SpeculativeCandidateResult

import type { SpeculativeCandidateResult } from "@elie-laloum/outpost";

Parameters and properties

Section titled “Parameters and properties”
  • keyRequired
    string
    Key of the candidate.
  • commitOptional
    string | undefined
    Candidate HEAD read after validate returned, including commits made during validation. checkSpeculationIntegration() blocks if the branch later moves.
  • attemptOptional
    number | undefined
    One-based attempt number; a replay uses a new branch and consumes another shared attempt.
  • cleanupOptional
    "done" | "pending" | undefined
    done once the sandbox has closed; pending when closing failed or exceeded cleanupMs. A durable race then stays owned, and its next call stops the resource first.
  • resourceIdOptional
    string | undefined
    Resource the provider registered before allocating the sandbox, such as a container name; durable races only. The next call uses it to stop an orphaned sandbox.
  • branchRequired
    string
    Candidate branch: outpost/speculation/<id>/<key>, or …/<key>/<attempt> in a durable race. It stays in the repository.
  • statusRequired
    "failed" | "quota" | "cancelled" | "rejected" | "skipped" | "winner"
    winner; rejected when validate returned false or another candidate won first; failed when allocation, the agent, validate or cleanup threw; quota; cancelled by a winner, a token limit, your signal or a crash; skipped when never started.
  • quotaOptional
    QuotaFault | undefined
    Usage or rate limit that stopped this candidate; durable resumption reruns such candidates as new attempts from the baseline.
  • directoryOptional
    string | undefined
    Host worktree directory of the candidate.
  • retainedDirectoryOptional
    string | undefined
    Worktree kept after the sandbox closed: dirty or detached, failed, with cleanup pending, or in a durable race.
  • resultOptional
    SpeculativeOutput<T> | undefined
    Dispatch output, when the candidate’s dispatch completed.
  • errorOptional
    unknown
    Failure of allocation, dispatch, validate or cleanup; a message string in a restored durable record.

Signature

Section titled “Signature”
export interface SpeculativeCandidateResult<T = undefined> {
  readonly key: string;
  readonly commit?: string;
  readonly attempt?: number;
  readonly cleanup?: "pending" | "done";
  readonly resourceId?: string;
  readonly branch: string;
  readonly status:
    "winner" | "rejected" | "failed" | "quota" | "cancelled" | "skipped";
  /** Usage or rate limit that stopped this candidate. */
  readonly quota?: QuotaFault;
  readonly directory?: string;
  readonly retainedDirectory?: string;
  readonly result?: SpeculativeOutput<T>;
  readonly error?: unknown;
}
Section titled “Related contracts”