rulvar API reference

---

rulvar API reference / @rulvar/rulvar / OrchestratorExtensionIO

Interface: OrchestratorExtensionIO

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

The per-run IO the extension closes over (engine-owned effects).

Properties

Property	Modifier	Type	Description	Defined in
admission	readonly	AdmissionController	The single admission point for all spawns.	packages/core/dist/index.d.ts
baseScope	readonly	string	The scope the orchestrate call runs in ('' at the top level).	packages/core/dist/index.d.ts
gates	readonly	Record<string, unknown>	The per-engine mechanical gate registry: named pure functions over AgentResult.artifacts. Typed loose at the seam exactly like profiles.	packages/core/dist/index.d.ts
profiles	readonly	Record<string, unknown>	Registered agent profiles advertised to this orchestrate call.	packages/core/dist/index.d.ts
runCeilingUsd?	readonly	number	The run USD ceiling (B0), when one exists.	packages/core/dist/index.d.ts
runId	readonly	string	-	packages/core/dist/index.d.ts

Methods

abandonBranch()

abandonBranch(attempt): Promise<{
  applied: boolean;
  seq: number;
}>;

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

Appends the severing abandon ref-entry over a branch through the ResolutionArbiter (DEF-4/DEF-5).

Parameters

Parameter	Type
attempt	{ authorizedBy: number; logicalTaskId?: string; nodeId?: string; reason: string; retainCheckpoint?: boolean; retainWorktree?: boolean; target: number; }
attempt.authorizedBy	number
attempt.logicalTaskId?	string
attempt.nodeId?	string
attempt.reason	string
attempt.retainCheckpoint?	boolean
attempt.retainWorktree?	boolean
attempt.target	number

Returns

Promise<{ applied: boolean; seq: number; }>

---

append()

append(input): Promise<JournalEntry>;

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

Total-order append; the extension owns its scopes' content keys.

Parameters

Parameter	Type
input	ExtensionAppendInput

Returns

Promise&lt;JournalEntry&gt;

---

cancel()

cancel(handle, reason?): Promise<{
  cancelled: boolean;
  handle: number;
}>;

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

Cancels an in-flight child by handle (AbortSignal).

Parameters

Parameter	Type
handle	number
reason?	string

Returns

Promise<{ cancelled: boolean; handle: number; }>

---

dispatch()

dispatch(
   spec, 
   childScope, 
   identity): Promise<{
  handle: number;
}>;

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

Dispatches one child agent under the EXPLICIT child scope through the ordinary ctx.agent path (semaphore, budget layers, forward matching). Returns the journal-derived handle (the dispatch seq).

Parameters

Parameter	Type
spec	ExtensionDispatchSpec
childScope	string
identity	{ logicalTaskId: string; nodeId: string; }
identity.logicalTaskId	string
identity.nodeId	string

Returns

Promise<{ handle: number; }>

---

emit()

emit(event): void;

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

Telemetry emission into the run event stream.

Parameters

Parameter	Type
event	{ type: string; } & Record<string, unknown>

Returns

void

---

flush()

flush(): Promise<void>;

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

Flushes the serialized append queue before reading back.

Returns

Promise&lt;void&gt;

---

mintId()

mintId(): string;

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

ULID minting for engine-owned identifiers (NodeIds).

Returns

string

---

orchestratorScope()

orchestratorScope(): string;

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

The orchestrator's child scope (agent:<seq>); throws before the loop starts.

Returns

string

---

priceUsd()

priceUsd(servedBy, usage): number | undefined;

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

The engine price fold (journal facts in, USD out).

Parameters

Parameter	Type
servedBy	string | undefined
usage	Usage

Returns

number | undefined

---

random()

random(key?): Promise<number>;

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

A journaled random draw in `0, 1) under the orchestrate scope: the ctx.random primitive, computed once live and replayed by match. The spot-check gate draws HERE, never Math.random.

Parameters

Parameter	Type
key?	string

Returns

Promise&lt;number&gt;

---

registerAlias()

ts registerAlias(donorScope, targetScope): void;

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

Registers a node.link scope-prefix alias for forward matching (DEF-5). Idempotent; rebuilt by fold on resume.

Parameters

Parameter	Type
donorScope	string
targetScope	string

Returns

void

---

settledOf()

settledOf(handle): 
  | AgentResult<unknown>
  | undefined;

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

The settled result of a dispatched child, when it settled.

Parameters

Parameter	Type
handle	number

Returns

| AgentResult&lt;unknown&gt; | undefined

---

snapshot()

snapshot(): readonly JournalEntry[];

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

The pinned journal view backing every pure fold.

Returns

readonly JournalEntry[]