Rulvar API reference / @rulvar/rulvar / CoreEvents
Type Alias: CoreEvents
ts
type CoreEvents =
| {
resumed: boolean;
type: "run:start";
workflow: string;
}
| {
acceptanceChildren?: {
child: string;
evidence?: {
floorRequired?: true;
met: boolean;
minEntries: number;
recordedEntries: number;
waivedBySalvage?: true;
};
salvage?: "partial" | "terminal-output";
status: string;
}[];
acceptedArtifactRef?: number;
belowFloorOkChildren?: string[];
childrenAtFailure?: {
belowFloorOkChildren?: string[];
settled: number;
spawned: number;
statusCounts: Record<string, number>;
unsettled?: string[];
};
childStatusCounts?: Record<string, number>;
citationAuditMeta?: Record<string, unknown>;
claimConsistencyMeta?: Record<string, unknown>;
completion?: "complete" | "partial" | "rejected";
degradedReasons?: string[];
deliverableAccepted?: boolean;
envelope: TerminalEnvelope;
rejectedFinishCandidates?: {
callId: string;
chars: number;
failed: {
name: string;
reasons: string[];
}[];
hash: string;
ref?: string;
verdict: "repair" | "rejected";
}[];
resultAvailable?: boolean;
salvagedPartialChildren?: string[];
salvagedTerminalOutputChildren?: string[];
semanticPasses?: {
claimConsistency: {
ran: boolean;
reason?: string;
};
contradictions: {
ran: boolean;
reason?: string;
};
synthesis: {
ran: boolean;
reason?: string;
};
};
semanticTerminalVerdict?: Record<string, unknown>;
settled?: false;
settledReason?: "superseded";
status: "ok" | "error" | "cancelled" | "exhausted" | "suspended";
synthesisSkipped?: boolean | string;
totalUsd: number;
type: "run:end";
usageApprox?: boolean;
}
| {
phase: string;
type: "phase:start";
}
| {
data?: Json;
level: "debug" | "info" | "warn" | "error";
msg: string;
type: "log";
}
| {
committedReserveUsd: number;
remainingUsd: number | null;
spentUsd: number;
type: "budget:update";
}
| {
deadlineAt?: string;
entryRef: number;
key: string;
prompt?: string;
type: "external:waiting";
}
| {
deadlineAt?: string;
entryRef: number;
toolName: string;
type: "approval:pending";
}
| {
scope: string;
type: "child:start";
workflow: string;
}
| {
scope: string;
status: string;
type: "child:end";
workflow: string;
};Defined in: packages/core/dist/index.d.ts
Run lifecycle and core telemetry (M1 subset).
Union Members
Type Literal
ts
{
resumed: boolean;
type: "run:start";
workflow: string;
}Type Literal
ts
{
acceptanceChildren?: {
child: string;
evidence?: {
floorRequired?: true;
met: boolean;
minEntries: number;
recordedEntries: number;
waivedBySalvage?: true;
};
salvage?: "partial" | "terminal-output";
status: string;
}[];
acceptedArtifactRef?: number;
belowFloorOkChildren?: string[];
childrenAtFailure?: {
belowFloorOkChildren?: string[];
settled: number;
spawned: number;
statusCounts: Record<string, number>;
unsettled?: string[];
};
childStatusCounts?: Record<string, number>;
citationAuditMeta?: Record<string, unknown>;
claimConsistencyMeta?: Record<string, unknown>;
completion?: "complete" | "partial" | "rejected";
degradedReasons?: string[];
deliverableAccepted?: boolean;
envelope: TerminalEnvelope;
rejectedFinishCandidates?: {
callId: string;
chars: number;
failed: {
name: string;
reasons: string[];
}[];
hash: string;
ref?: string;
verdict: "repair" | "rejected";
}[];
resultAvailable?: boolean;
salvagedPartialChildren?: string[];
salvagedTerminalOutputChildren?: string[];
semanticPasses?: {
claimConsistency: {
ran: boolean;
reason?: string;
};
contradictions: {
ran: boolean;
reason?: string;
};
synthesis: {
ran: boolean;
reason?: string;
};
};
semanticTerminalVerdict?: Record<string, unknown>;
settled?: false;
settledReason?: "superseded";
status: "ok" | "error" | "cancelled" | "exhausted" | "suspended";
synthesisSkipped?: boolean | string;
totalUsd: number;
type: "run:end";
usageApprox?: boolean;
}| Name | Type | Description | Defined in |
|---|---|---|---|
acceptanceChildren? | { child: string; evidence?: { floorRequired?: true; met: boolean; minEntries: number; recordedEntries: number; waivedBySalvage?: true; }; salvage?: "partial" | "terminal-output"; status: string; }[] | The per-child acceptance roster (RV806): status, salvage arm, and the evidence verdict where the child declared a contract; same lift and posture as the fields above. | packages/core/dist/index.d.ts |
acceptedArtifactRef? | number | The journal seq of the decision recording that acceptance (RV2506); absent whenever deliverableAccepted is not true. | packages/core/dist/index.d.ts |
belowFloorOkChildren? | string[] | Children that settled 'ok' below their declared evidence floor (RV1412); same lift. Under the default their shortfall is a degradation note and the verdict is untouched; under acceptance.requireEvidenceFloor they also counted against the policy. | packages/core/dist/index.d.ts |
childrenAtFailure? | { belowFloorOkChildren?: string[]; settled: number; spawned: number; statusCounts: Record<string, number>; unsettled?: string[]; } | What the children had produced when the run died BEFORE any acceptance verdict (RV2602), lifted on its own rather than with the completion, because it exists for the terminal where there is no completion to lift. Present exactly when children were spawned and no acceptance verdict exists, so it never overlaps the fields above. Frozen at the moment of death, ahead of the RV1903 exit barrier, which is why unsettled can be non-empty. | packages/core/dist/index.d.ts |
childrenAtFailure.belowFloorOkChildren? | string[] | - | packages/core/dist/index.d.ts |
childrenAtFailure.settled | number | - | packages/core/dist/index.d.ts |
childrenAtFailure.spawned | number | - | packages/core/dist/index.d.ts |
childrenAtFailure.statusCounts | Record<string, number> | - | packages/core/dist/index.d.ts |
childrenAtFailure.unsettled? | string[] | - | packages/core/dist/index.d.ts |
childStatusCounts? | Record<string, number> | Settled child statuses by status name, lifted from the same envelope (or typed error data) when it carries a valid record of nonnegative integers. Absent otherwise. | packages/core/dist/index.d.ts |
citationAuditMeta? | Record<string, unknown> | - | packages/core/dist/index.d.ts |
claimConsistencyMeta? | Record<string, unknown> | The claim-consistency pass meta, lifted from the same envelope (or typed error data) when it carries a valid object (RV2203); judgeDeclined rides here on the failed terminals that used to read null while the journal held the verdict. | packages/core/dist/index.d.ts |
completion? | "complete" | "partial" | "rejected" | The semantic completion lift (RV-207 tail): present when the workflow reported semantic completion through the completion envelope contract: an ok/exhausted run whose result value is an object carrying a valid completion literal, or an error run whose typed error data carries one (the orchestrator acceptance path emits both). Transport status says whether the run ran; completion says whether the work is COMPLETE: an accepted degraded run is status: 'ok' with completion: 'partial'. Replay recomputes the same value from the re-executed workflow, so the field is identical live and replayed. Absent when the workflow makes no completion claim. | packages/core/dist/index.d.ts |
degradedReasons? | string[] | Per-child degradation notes, lifted from the same envelope (or typed error data) when it carries a valid string array (the fifth experiment, cycle 75). An empty array is the workflow's claim of zero degradation; absence means no claim. The outcome mirror spreads the SAME lift, so the surfaces cannot disagree. | packages/core/dist/index.d.ts |
deliverableAccepted? | boolean | Whether the artifact this terminal carries was accepted by the declared finish contract, and whether there is one to read at all (RV2506); same lift. deliverableAccepted is absent, never false, when no finish contract was declared. The pair is what status and completion cannot say between them: an accepted child roster over a synthesis that never passed its contract reads status: 'ok', completion: 'complete', deliverableAccepted: false. | packages/core/dist/index.d.ts |
envelope | TerminalEnvelope | The unified terminal envelope (RV1105): every terminal fact in ONE shape, the same object the resolved outcome carries, so an event-only consumer assembles nothing. On the settled paths the sibling fields above stay byte for byte; when settlement did not hold, envelope.settled mirrors the settled: false mark (with settledReason inside for the superseded arc, RV1009). | packages/core/dist/index.d.ts |
rejectedFinishCandidates? | { callId: string; chars: number; failed: { name: string; reasons: string[]; }[]; hash: string; ref?: string; verdict: "repair" | "rejected"; }[] | Every finish candidate the declared contract did NOT accept, in judgement order (RV2507); same lift, absent when there was none. Each row identifies the candidate (callId, hash, chars) and names the validators that rejected it, with ref pointing at the retained bytes where the host asked for them. | packages/core/dist/index.d.ts |
resultAvailable? | boolean | - | packages/core/dist/index.d.ts |
salvagedPartialChildren? | string[] | - | packages/core/dist/index.d.ts |
salvagedTerminalOutputChildren? | string[] | - | packages/core/dist/index.d.ts |
semanticPasses? | { claimConsistency: { ran: boolean; reason?: string; }; contradictions: { ran: boolean; reason?: string; }; synthesis: { ran: boolean; reason?: string; }; } | The explicit semantic pass summaries (RV1906); same lift. Each pass carries {ran, reason?}, so an event-only consumer reads whether contradictions, claim consistency and synthesis actually looked, instead of decoding absence. | packages/core/dist/index.d.ts |
semanticPasses.claimConsistency | { ran: boolean; reason?: string; } | - | packages/core/dist/index.d.ts |
semanticPasses.claimConsistency.ran | boolean | - | packages/core/dist/index.d.ts |
semanticPasses.claimConsistency.reason? | string | - | packages/core/dist/index.d.ts |
semanticPasses.contradictions | { ran: boolean; reason?: string; } | - | packages/core/dist/index.d.ts |
semanticPasses.contradictions.ran | boolean | - | packages/core/dist/index.d.ts |
semanticPasses.contradictions.reason? | string | - | packages/core/dist/index.d.ts |
semanticPasses.synthesis | { ran: boolean; reason?: string; } | - | packages/core/dist/index.d.ts |
semanticPasses.synthesis.ran | boolean | - | packages/core/dist/index.d.ts |
semanticPasses.synthesis.reason? | string | - | packages/core/dist/index.d.ts |
semanticTerminalVerdict? | Record<string, unknown> | The one-word semantic verdict (RV4209), the same lift the outcome carries, declared on the event since RV4403 so an event-only consumer reads it typed on failed terminals too. | packages/core/dist/index.d.ts |
settled? | false | Present and false ONLY when nothing durable records this terminal: a settlement write failed (the run_settle journal append or the terminal RunMeta projection, RV907), or the segment was superseded (settledReason names it, RV1009). The status above is true as computation, but handle.result rejects typed instead of resolving (SettlementError or SupersededError), and an event-only consumer must not treat this terminal as green. After a settlement failure, resuming the run re-settles by replay (no provider call) and the settled terminal carries no field, byte for byte like every ordinary run. Never emitted true. | packages/core/dist/index.d.ts |
settledReason? | "superseded" | Present only beside settled: false, naming WHY the terminal refused green when the reason is not a settlement write fault: 'superseded' means the run_settle append bounced off the store's fence because a successor segment holds the lease and owns settlement (RV1009), and handle.result rejects with the typed SupersededError. A settlement WRITE failure keeps its historical shape (settled: false with no reason) byte for byte. | packages/core/dist/index.d.ts |
status | "ok" | "error" | "cancelled" | "exhausted" | "suspended" | - | packages/core/dist/index.d.ts |
synthesisSkipped? | boolean | string | - | packages/core/dist/index.d.ts |
totalUsd | number | - | packages/core/dist/index.d.ts |
type | "run:end" | - | packages/core/dist/index.d.ts |
usageApprox? | boolean | Present and true when any priced usage folded into totalUsd is approximate (a transport cut, a stream the ceiling severed, or an abort left a turn's usage estimated rather than reported by the provider), so totalUsd is a lower bound estimate, never an exact charge. Absent means every contributing turn reported exact usage. | packages/core/dist/index.d.ts |
Type Literal
ts
{
phase: string;
type: "phase:start";
}Type Literal
ts
{
data?: Json;
level: "debug" | "info" | "warn" | "error";
msg: string;
type: "log";
}Type Literal
ts
{
committedReserveUsd: number;
remainingUsd: number | null;
spentUsd: number;
type: "budget:update";
}Type Literal
ts
{
deadlineAt?: string;
entryRef: number;
key: string;
prompt?: string;
type: "external:waiting";
}Type Literal
ts
{
deadlineAt?: string;
entryRef: number;
toolName: string;
type: "approval:pending";
}Type Literal
ts
{
scope: string;
type: "child:start";
workflow: string;
}Type Literal
ts
{
scope: string;
status: string;
type: "child:end";
workflow: string;
}