Interface: SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>

Defined in: builders/speculate-capability-builder.ts:26

Fluent sub-builder for a parallel speculative tournament capability ($cap.speculate(toolName, $s => ...)).

Configures $B \ge 2$ isolated tournament branches, optional cross-branch verification, sole-survivor verification, arbiter judgment, and conditional post-arbitration refinement.

Extends

• AstBuilder<SpeculateCapabilityNode<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict>>

Type Parameters

Type Parameter	Default type	Description
TParentIn	unknown	Parent actor input payload type.
TReq	unknown	Validated speculation tool request payload type.
TChildIn	unknown	Branch worker input payload type.
TChildOut	unknown	Branch worker output payload type.
THandle	unknown	Runtime handle type of the active BranchableScope.
TCrossReport	unknown	Cross-verifier report payload type.
TVerdict	unknown	Arbiter agent structured verdict payload type.
TCandidate	unknown	Candidate union element type inferred from the arbiter's input schema.

Methods

arbiter()

Call Signature

arbiter<TArbiterIn, TNewVerdict>(arbiterActor, options?): SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TNewVerdict, ExtractSpeculationCandidate<TArbiterIn>>;

Defined in: builders/speculate-capability-builder.ts:182

Binds the read-only arbiter agent (with an optional decision projector) when the arbiter output already extends SpeculateArbiterDecision.

Infers TCandidate from TArbiterIn so .refineWinnerWhen(...) receives typed candidates, and defaults resolveDecision to the identity projection (verdict) => verdict when omitted.

Type Parameters

Type Parameter	Default type	Description
TArbiterIn	unknown	Arbiter input payload type (used to infer TCandidate).
TNewVerdict extends SpeculateArbiterDecision	SpeculateArbiterDecision	Arbiter structured verdict output type extending SpeculateArbiterDecision.

Parameters

Parameter	Type	Description
arbiterActor	MaybeBuilder<AgentNode<TArbiterIn, TNewVerdict, THandle>>	Read-only arbiter agent.
options?	{ resolveDecision?: (verdict) => SpeculateArbiterDecision; }	Optional pure decision projector.
options.resolveDecision?	(verdict) => SpeculateArbiterDecision	-

Returns

SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TNewVerdict, ExtractSpeculationCandidate<TArbiterIn>>

New immutable speculate builder.

Call Signature

arbiter<TNewVerdict, TArbiterIn>(arbiterActor, options): SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TNewVerdict, ExtractSpeculationCandidate<TArbiterIn>>;

Defined in: builders/speculate-capability-builder.ts:212

Binds the read-only arbiter agent and decision projector for judging candidate branches.

Infers TCandidate from TArbiterIn so .refineWinnerWhen(...) receives typed candidates.

Type Parameters

Type Parameter	Default type	Description
TNewVerdict	-	Arbiter structured verdict output type.
TArbiterIn	unknown	Arbiter input payload type (used to infer TCandidate).

Parameters

Parameter	Type	Description
arbiterActor	MaybeBuilder<AgentNode<TArbiterIn, TNewVerdict, THandle>>	Read-only arbiter agent.
options	{ resolveDecision: (verdict) => SpeculateArbiterDecision; }	Pure decision projector.
options.resolveDecision	(verdict) => SpeculateArbiterDecision	-

Returns

SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TNewVerdict, ExtractSpeculationCandidate<TArbiterIn>>

New immutable speculate builder.

---

branches()

branches(branchCount, mapBranches): SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>;

Defined in: builders/speculate-capability-builder.ts:100

Configures the number of parallel speculative branches ($B \ge 2$) and the branch input mapper.

Throws immediately at builder call time if branchCount < 2 or is not an integer.

Parameters

Parameter	Type	Description
branchCount	number	Number of parallel branches ($B \ge 2$).
mapBranches	(parentInput, req) => readonly TChildIn[]	Synchronous mapper producing $B$ branch inputs.

Returns

SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>

New immutable speculate builder.

---

crossVerifyWith()

crossVerifyWith<TNewCrossReport>(crossVerifier): SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TNewCrossReport, TVerdict, TCandidate>;

Defined in: builders/speculate-capability-builder.ts:125

Binds an optional cross-verifier AST node executed across surviving candidate branches before arbitration.

Narrows TCrossReport to the report type produced by crossVerifier.

Type Parameters

Type Parameter	Description
TNewCrossReport	Cross-verifier report payload type.

Parameters

Parameter	Type	Description
crossVerifier	MaybeBuilder<CrossVerifierASTNode<THandle, Record<string, unknown>, TNewCrossReport>>	Cross-verifier node or builder.

Returns

SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TNewCrossReport, TVerdict, TCandidate>

New immutable speculate builder.

---

refineWinnerWhen()

refineWinnerWhen(
   predicate, 
   refinementExecutable, 
   mapInput
): SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>;

Defined in: builders/speculate-capability-builder.ts:228

Configures an optional post-arbitration refinement pass executed on the winning branch while losing branches remain readable.

Runs refinementExecutable on the winning branch's isolated scope before merging into the parent scope.

Parameters

Parameter	Type	Description
predicate	(verdict) => boolean	Predicate testing whether refinement should run.
refinementExecutable	MaybeBuilder< | AgentNode<TChildIn, TChildOut, THandle> | LoopNode<TChildIn, TChildOut, THandle, string>>	Refinement agent or loop.
mapInput	(parentInput, verdict, candidates) => TChildIn	Refinement input mapper.

Returns

SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>

New immutable speculate builder.

---

requestSchema()

requestSchema<TNewReq>(schema): SpeculateCapabilityBuilder<TParentIn, TNewReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>;

Defined in: builders/speculate-capability-builder.ts:49

Binds the Zod validation schema for the parent agent's speculation tool call arguments.

Resets any previously bound mapBranches callback when the request schema changes.

Type Parameters

Type Parameter	Description
TNewReq	Validated speculation request payload type.

Parameters

Parameter	Type	Description
schema	ZodType<TNewReq>	Zod schema for the speculation request.

Returns

SpeculateCapabilityBuilder<TParentIn, TNewReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>

New immutable speculate builder.

---

toAST()

toAST(): SpeculateCapabilityNode;

Defined in: ast/ast-builder.ts:20

Compiles the current builder configuration into a deeply frozen passive AST node.

Validates required builder invariants at compilation time and returns an immutable plain-object AST representation containing zero execution methods.

Returns

SpeculateCapabilityNode

Deeply frozen passive AST node.

Inherited from

AstBuilder.toAST

---

verifyWinnerWith()

verifyWinnerWith<TEvalIn, TEvalOut, TReceipt>(evaluator, options): SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>;

Defined in: builders/speculate-capability-builder.ts:143

Configures an optional sole-survivor evaluator invoked when 1 branch completes uncontested.

Short-circuits the arbiter when the sole completed branch is accepted by options.acceptWhen.

Type Parameters

Type Parameter	Default type	Description
TEvalIn	-	Evaluator input payload type.
TEvalOut	-	Evaluator output payload type.
TReceipt	TCandidate extends object ? R : unknown	Inspected scope receipt type.

Parameters

Parameter	Type	Description
evaluator	MaybeBuilder<AgentNode<TEvalIn, TEvalOut, THandle>>	Read-only evaluator agent.
options	{ acceptWhen: (evalOut) => boolean; mapInput: (branchInput, branchOutput, scopeReceipt) => TEvalIn; }	Input mapper and acceptance predicate.
options.acceptWhen	(evalOut) => boolean	-
options.mapInput	(branchInput, branchOutput, scopeReceipt) => TEvalIn	-

Returns

SpeculateCapabilityBuilder<TParentIn, TReq, TChildIn, TChildOut, THandle, TCrossReport, TVerdict, TCandidate>

New immutable speculate builder.

---

worker()

worker<TNewChildIn, TNewChildOut>(workerExecutable): SpeculateCapabilityBuilder<TParentIn, TReq, TNewChildIn, TNewChildOut, THandle, TCrossReport, TVerdict, TCandidate>;

Defined in: builders/speculate-capability-builder.ts:74

Binds the worker agent or loop executed in parallel across all tournament branches.

Resets dependent branch mapper, sole-survivor verifier, and winner refinement configs when changed.

Type Parameters

Type Parameter	Description
TNewChildIn	Branch worker input payload type.
TNewChildOut	Branch worker output payload type.

Parameters

Parameter	Type	Description
workerExecutable	MaybeBuilder< | AgentNode<TNewChildIn, TNewChildOut, THandle> | LoopNode<TNewChildIn, TNewChildOut, THandle, string>>	Worker agent or loop.

Returns

SpeculateCapabilityBuilder<TParentIn, TReq, TNewChildIn, TNewChildOut, THandle, TCrossReport, TVerdict, TCandidate>

New immutable speculate builder.