speculate

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

Purpose and behavior

Race 1 to 8 candidates from the checkout’s HEAD, each on its own branch and sandbox, and select the first one validate accepts once its sandbox has closed. Returns every candidate’s outcome, the shared usage and a merge preflight of the winner; it never merges. Invalid options reject with code configuration.

Complete example and detailed rules.

Parameters and properties

optionsRequired
SpeculationOptions<T>
Repository, sandbox provider, candidates, shared budget and validate callback, plus concurrency, cleanup and durability settings.
options.durabilityOptional
SpeculationDurability | undefined
Saves the race through a Transport so it can resume after a crash or a quota stop. Requires a provider with recover; omit it for an in-memory race.
options.cleanupMsOptional
number | undefined
Wait for each sandbox close or resource recovery, and for running candidates after cancellation, default 30000. Past it, cleanup stays pending.
options.observationOptional
ObservationHub | undefined
Parent hub for the events of every candidate, scoped by candidate key; it replaces each request’s own observation.
options.repositoryRequired
string
Host Git checkout. Its HEAD commit when the race first starts is the baseline of every candidate branch.
options.sandboxProviderRequired
SandboxProvider
Provider that allocates each candidate’s sandbox. Durable mode requires one with recover: Docker or Podman in mounted mode.
options.candidatesRequired
readonly SpeculativeCandidate<T>[]
1 to 8 candidates with unique keys, started in list order as concurrency allows.
options.concurrencyOptional
number | undefined
Maximum candidates running at once, 1 to 8, default 2.
options.budgetRequired
WorkflowBudget
Limits shared by all candidates. Each start consumes one of attempts and the limit stops new starts; reaching a usage token limit cancels running candidates. Tokens used inside validate are not counted.
options.signalOptional
AbortSignal | undefined
Aborting it cancels running candidates and ends the race with status aborted.
options.sandboxOptional
Pick<SandboxOptions, "hooks" | "storageQuota" | "limits" | "logging" | "bootstrap" | "conversationHome"> | undefined
Sandbox settings applied to every candidate: hooks, bootstrap, logging, limits, storageQuota and conversationHome.
options.validateRequired
(candidate: SpeculativeValidation<T>) => boolean | Promise<boolean>
Decides whether a finished candidate is acceptable, given its dispatch output and live sandbox; true accepts it. A throw marks the candidate failed.

Returns

Promise<SpeculationResult<T>>

Signature

export declare function speculate<T = undefined>(
  options: SpeculationOptions<T>,
): Promise<SpeculationResult<T>>;