rulvar API reference

---

rulvar API reference / @rulvar/core / AdmissionController

Class: AdmissionController

Defined in: packages/core/src/orchestrator/admission.ts:202

Constructors

Constructor

new AdmissionController(options): AdmissionController;

Defined in: packages/core/src/orchestrator/admission.ts:218

Parameters

Parameter	Type	Description
options	{ budget: RunBudget; childBudgetFraction?: number; flatReserveUsd?: number; lineage?: { journalView: () => readonly JournalEntry[]; limits?: | Record<string, unknown> | Partial<EscalationLimits>; }; maxChildrenPerNode?: number; maxDepth?: number; maxTotalSpawns?: number; mintId?: () => string; }	-
options.budget	RunBudget	-
options.childBudgetFraction?	number	-
options.flatReserveUsd?	number	-
options.lineage?	{ journalView: () => readonly JournalEntry[]; limits?: | Record<string, unknown> | Partial<EscalationLimits>; }	The lineage binding (DEF-3): a journal view for the pure counter folds plus the configured limits. Without it the controller mints and embeds lineage but enforces no lineage limits (unit contexts).
options.lineage.journalView	() => readonly JournalEntry[]	-
options.lineage.limits?	| Record<string, unknown> | Partial<EscalationLimits>	-
options.maxChildrenPerNode?	number	-
options.maxDepth?	number	-
options.maxTotalSpawns?	number	Per-orchestrate spawn cap (maxSpawns); engine lifetime cap applies regardless.
options.mintId?	() => string	-

Returns

AdmissionController

Accessors

escalationLimits

Get Signature

get escalationLimits(): EscalationLimits;

Defined in: packages/core/src/orchestrator/admission.ts:269

The validated lineage limits this controller enforces (DEF-3).

Returns

EscalationLimits

---

termination

Get Signature

get termination(): 
  | TerminationAccount
  | undefined;

Defined in: packages/core/src/orchestrator/admission.ts:289

The bound account, when this is a PlanRunner run (DEF-2).

Returns

| TerminationAccount | undefined

Methods

admit()

admit(spec, options?): AdmissionDecision;

Defined in: packages/core/src/orchestrator/admission.ts:382

Evaluates one spawn live, strictly BEFORE its decision entry is appended. On admit the reserve is committed on the whole ancestor account chain atomically with the evaluation; the caller journals the returned decision and only then produces effects (child account, dispatch). On reject nothing is committed and the reject verdict is journaled by the caller so replay re-delivers it without re-evaluation.

Parameters

Parameter	Type
spec	AdmitSpec
options?	{ commitReserve?: boolean; }
options.commitReserve?	boolean

Returns

AdmissionDecision

---

bindTermination()

bindTermination(account): void;

Defined in: packages/core/src/orchestrator/admission.ts:281

Binds the run's TerminationAccount (DEF-2; PlanRunner runs only): from bind time on, every admitted spawn of any origin debits one spawnUnit atomically with its decision entry, and a declared ladder longer than the frozen kMax rejects with ladder_exceeds_frozen. Non-PlanRunner runs never bind an account and keep the engine lifetime cap semantics unchanged.

Parameters

Parameter	Type
account	TerminationAccount

Returns

void

---

evaluateLineage()

evaluateLineage(spec): {
  decision:   | {
     kind: "ok";
     lineage: SpawnLineage;
   }
     | {
     kind: "reject";
     reason: {
        code: "lineage_exhausted" | "lineage_busy";
     };
   };
  statsBefore?: LineageStats;
};

Defined in: packages/core/src/orchestrator/admission.ts:301

The lineage half of admission (DEF-3): folds are computed live STRICTLY BEFORE the carrying decision entry is appended; the caller embeds the returned block in the entry and replay reads it back byte-exact. Enforces the single-live-attempt invariant (lineage_busy) and monotonic attempt consumption (lineage_exhausted); never touches budget or structural limits.

Parameters

Parameter	Type
spec	{ ancestry?: string[]; approach?: string; lineage?: SpawnLineageOpt; name: string; signature?: Partial<ApproachSignatureInputs>; }
spec.ancestry?	string[]
spec.approach?	string
spec.lineage?	SpawnLineageOpt
spec.name	string
spec.signature?	Partial<ApproachSignatureInputs>

Returns

{
  decision:   | {
     kind: "ok";
     lineage: SpawnLineage;
   }
     | {
     kind: "reject";
     reason: {
        code: "lineage_exhausted" | "lineage_busy";
     };
   };
  statsBefore?: LineageStats;
}

Name	Type	Defined in
decision	| { kind: "ok"; lineage: SpawnLineage; } | { kind: "reject"; reason: { code: "lineage_exhausted" | "lineage_busy"; }; }	packages/core/src/orchestrator/admission.ts:308
statsBefore?	LineageStats	packages/core/src/orchestrator/admission.ts:311

---

lineage()

lineage(): LineageIndex | undefined;

Defined in: packages/core/src/orchestrator/admission.ts:261

The lineage counter folds over the run journal (absorbed lazily).

Returns

LineageIndex | undefined

---

recoverChild()

recoverChild(nodeKey): void;

Defined in: packages/core/src/orchestrator/admission.ts:510

Resume roll-forward for an orchestrator child (M6-T07): restores the children-quota counter only. The budget seed already counts settled agent dispatches, and an in-flight child re-commits its reserve through the ctx.agent dispatch path.

Parameters

Parameter	Type
nodeKey	string

Returns

void

---

recoverInFlight()

recoverInFlight(parentAccountScope, verdict): void;

Defined in: packages/core/src/orchestrator/admission.ts:534

Resume roll-forward for an admission whose decision entry exists but whose child has NOT settled: re-applies the recorded reserve and counters without re-evaluating any limit (replay never re-evaluates admission; reserves are recovered, never re-estimated).

Parameters

Parameter	Type
parentAccountScope	string
verdict	AdmitVerdict

Returns

void

---

recoverSettled()

recoverSettled(parentAccountScope): void;

Defined in: packages/core/src/orchestrator/admission.ts:521

Resume roll-forward for a child that already SETTLED before the resume: re-registers the counters (maxChildrenPerNode, the lifetime cap, statsBefore fidelity) without committing any reserve; the spend itself sits in the root ledger seed.

Parameters

Parameter	Type
parentAccountScope	string

Returns

void

---

registerLineageAdmit()

registerLineageAdmit(logicalTaskId): void;

Defined in: packages/core/src/orchestrator/admission.ts:369

Registers a live lineage admit the moment its caller commits to appending the decision entry, closing the single-live-attempt window until the journal absorbs the entry (DEF-3).

Parameters

Parameter	Type
logicalTaskId	string

Returns

void