Events and the reactive layer

harness.runtime.events

Events: the signals of a run, in one catalog.

An execution’s event (Event) ends every bounded execution and goes to the rules that answer it (on()); one nobody answers ends the unit that ran it and reaches the model (Escalation). A trace record (EVENTS) is what the run writes to its trace (core/trace.py), which the timeline, the overlay, replay and the exported video all draw. A family of records is one kind with an action (library), which record_kind() reads.

Event

class Event

Why an execution ended: its kind (a built-in kind above or a guard’s own action), the source that raised it (a skill, a guard, “shield”, “environment”), details, and the robot step it happened at.

to_dict

def to_dict() -> dict

The event as a plain dict.

input_refusal

def input_refusal(receipt, step)

ExecutionTrace

class ExecutionTrace

What one bounded execution did, and why it ended.

ok

def ok() -> bool

Whether the execution ended nominally (COMPLETED or PREDICATE_SATISFIED).

ticks

def ticks() -> int

Robot steps the execution took.

to_dict

def to_dict() -> dict

The trace as a plain dict, with ok.

Escalation

class Escalation(Exception)
    __init__(trace: ExecutionTrace)

An event no handler resolved. It ends the current program.

ProgramFinished

class ProgramFinished(Exception)
    __init__(summary: str='')

A program called finish(): its own checks say the task is done. The episode ends without another model call.

EpisodeEnded

class EpisodeEnded(Exception)
    __init__(trace: ExecutionTrace)

The environment terminated or truncated the episode during a program.

record_kind

def record_kind(record: dict) -> tuple[str, str | None]

A trace record’s kind and, for a family (library), its action.

step_of

def step_of(start: dict, end: dict, call: str | None=None) -> dict

An execution’s span_start and span_end (lane “skill”) as a step of its skill, in the shape of a skill_step record (core/spans.py step), so a reader takes both alike.

harness.runtime.reactive.rules

How reactive code is called: the conditions of the tree’s nodes (runtime/reactive/tree.py), controllers and until predicates run restricted (no file, network, process or input operation) and within a time budget of the control period.

ReactiveFault

class ReactiveFault(Exception)
    __init__(source: str, reason: str)

Reactive code that failed, identified by source and reason.

NotJudged

class NotJudged(Exception)

The control period’s budget was used up before this reactive function could be called. It was not called: no fault of its own, and its turn comes in the next period.

call_reactive

def call_reactive(source: str, function: Callable, *args, budget_seconds: float, late=None) -> Any

Run one reactive function under the audit restriction and time budget. NotJudged when the period’s budget was used up before it. One that takes more than its budget is a ReactiveFault, unless the caller takes that itself: late(seconds) is then called (the tree of reflexes counts such periods: tree.py), and the result is returned, or, of one that was ended at the hard limit (four times the budget), NotJudged raised.

period

def period(budget_seconds)

One control period: the reactive calls in it share budget_seconds.