stormlog.phases.runtime

Runtime phase state tracking and boundary payload emission.

Classes

PhaseBoundary(event_type, context, metadata, ...)	Structured boundary payload emitted into tracker telemetry events.
PhaseHandle(*, scope_id, name, path, ...)	A closeable tracker phase handle returned by enter_phase().
PhaseRecorder()	Per-tracker phase nesting state and boundary payload generation.
PhaseToken(scope_id, session_id, rank, ...)	Opaque runtime token used for strict phase exit semantics.

Exceptions

PhaseProtocolError

Raised when phase handles are closed incorrectly.

class stormlog.phases.runtime.PhaseBoundary(event_type, context, metadata, scope_id, path)

Bases: object

Structured boundary payload emitted into tracker telemetry events.

Parameters:

• event_type (str)

• context (str)

• metadata (dict[str, Any])

• scope_id (str)

• path (tuple[str, ...])

event_type: str

context: str

metadata: dict[str, Any]

scope_id: str

path: tuple[str, ...]

class stormlog.phases.runtime.PhaseHandle(*, scope_id, name, path, close_callback)

Bases: object

A closeable tracker phase handle returned by enter_phase().

Parameters:

• scope_id (str)

• name (str)

• path (tuple[str, ...])

• close_callback (Callable[[], Any])

property phase_path: str

Return the formatted phase path.

property closed: bool

Return True once the handle has been closed.

close()

Close the phase handle once.

Return type:

Any

exception stormlog.phases.runtime.PhaseProtocolError

Bases: RuntimeError

Raised when phase handles are closed incorrectly.

class stormlog.phases.runtime.PhaseRecorder

Bases: object

Per-tracker phase nesting state and boundary payload generation.

reset()

Drop all active phase scopes for a new tracker session.

Return type:

None

enter(*, session_id, rank, name, attrs=None)

Primary runtime API returning both a token and the emitted boundary.

Parameters:

• session_id (str)

• rank (int)

• name (str)

• attrs (Mapping[str, Any] | None)

Return type:

tuple[PhaseToken, PhaseBoundary]

enter_phase(*, session_id, rank, name, metadata=None)

Register one nested phase enter transition.

Parameters:

• session_id (str)

• rank (int)

• name (str)

• metadata (Mapping[str, Any] | None)

Return type:

PhaseBoundary

exit(token)

Primary runtime API for strict token-based exit.

Parameters:

token (PhaseToken)

Return type:

PhaseBoundary

exit_phase(*, session_id, rank, scope_id, thread_id)

Register one nested phase exit transition.

Parameters:

• session_id (str)

• rank (int)

• scope_id (str)

• thread_id (int)

Return type:

PhaseBoundary

class stormlog.phases.runtime.PhaseToken(scope_id, session_id, rank, thread_id, name)

Bases: object

Opaque runtime token used for strict phase exit semantics.

Parameters:

• scope_id (str)

• session_id (str)

• rank (int)

• thread_id (int)

• name (str)

scope_id: str

session_id: str

rank: int

thread_id: int

name: str