rulvar API reference

---

rulvar API reference / @rulvar/testing / TestRunHandle

Interface: TestRunHandle<R>

Defined in: packages/testing/src/test-engine.ts:22

A RunHandle that records its own event stream for the matchers.

Extends

• RunHandle<R>

Type Parameters

Type Parameter
R

Properties

Property	Type	Description	Inherited from	Defined in
events	AsyncIterable<WorkflowEvent>	-	RunHandle.events	packages/core/dist/index.d.ts
eventsSeen	WorkflowEvent[]	Every event emitted by the run, in seq order.	-	packages/testing/src/test-engine.ts:24
result	Promise<RunOutcome<R>>	-	RunHandle.result	packages/core/dist/index.d.ts
runId	string	-	RunHandle.runId	packages/core/dist/index.d.ts

Methods

cancel()

cancel(reason?): Promise<void>;

Defined in: packages/core/dist/index.d.ts

Cooperative cancellation; the run settles 'cancelled' with a complete CostReport.

Parameters

Parameter	Type
reason?	string

Returns

Promise<void>

Inherited from

RunHandle.cancel

---

on()

on<T>(type, cb): () => void;

Defined in: packages/core/dist/index.d.ts

Type Parameters

Type Parameter

T extends | "run:start" | "run:end" | "phase:start" | "log" | "budget:update" | "external:waiting" | "approval:pending" | "child:start" | "child:end" | "agent:queued" | "agent:start" | "agent:end" | "agent:error" | "agent:schema-retry" | "agent:stream" | "tool:start" | "tool:end" | "plan:revised" | "node:parked" | "node:cancelled" | "node:linked" | "orchestrator:woke" | "orchestrator:budget" | "escalation:raised" | "escalation:decided" | "spawn:admitted" | "spawn:rejected" | "verify:failed" | "ledger:op" | "stall:detected" | "guard:oscillation" | "resolution:applied" | "resolution:superseded" | "termination:debit" | "termination:denied" | "termination:config-drift" | "journal:compat"

Parameters

Parameter	Type
type	T
cb	(e) => void

Returns

() => void

Inherited from

RunHandle.on

---

resolveExternal()

resolveExternal(key, value): Promise<ResolutionOutcome>;

Defined in: packages/core/dist/index.d.ts

Resolves an open awaitExternal suspension (DEF-4 signature): applied when this attempt wins the first-closing-wins fold; repeated resolution is defined behavior, not an error. An invalid live payload throws InvalidResolutionError and journals nothing.

Parameters

Parameter	Type
key	string
value	Json

Returns

Promise<ResolutionOutcome>

Inherited from

RunHandle.resolveExternal