Rulvar API reference

---

Rulvar API reference / @rulvar/core / AdmissionController

Class: AdmissionController

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

Constructors

Constructor

new AdmissionController(options): AdmissionController;

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

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	Controller-lifetime cap on ADMITTED spawns, enforced at this controller's own gate with the 'lifetime' reject reason, for hosts driving an AdmissionController directly. Engine runs do not wire this option: they cap total spawns through the budget (budgetDefaults.lifetimeSpawnCap, the same 'lifetime' reason).
options.mintId?	() => string	-

Returns

AdmissionController

Accessors

escalationLimits

Get Signature

get escalationLimits(): EscalationLimits;

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

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:1021

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:1131

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:1013

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:1033

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:1040
statsBefore?	LineageStats	packages/core/src/orchestrator/admission.ts:1043

---

lineage()

lineage(): LineageIndex | undefined;

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

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

Returns

LineageIndex | undefined

---

projectedDispatchReserveUsd()

projectedDispatchReserveUsd(spec): number;

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

The reserve the DISPATCH layer will actually commit for this spec: the estimate (or the flat default) clamped by the explicit child budget when one exists, because only an explicit budget opens a child-allowance account at dispatch; the childBudgetFraction cap never materializes as an account and must not shrink the projection. The token-count-priced estimate of ctx.agent is unreachable here (async); a divergence there lands as a journaled dispatch rejection instead of a strand. Delegates to the exported dispatchProjectionReserveUsd so the live gate and preflightEstimate share ONE formula (the 1.63.0 experiment review, P0.3).

Parameters

Parameter	Type
spec	Pick<AdmitSpec, "estCostUsd" | "budgetUsd">

Returns

number

---

recoverChild()

recoverChild(nodeKey): void;

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

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:1364

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:1351

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:1101

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