Module contract 

The full contract lane, mirroring TS contract.ts: every public free function and type.

Structs

DebugOptions

Options for enable_debug (TS DebugOptions). subsystems selects the registered subsystems to switch on (all of them when omitted); level is the session’s global level (default LogLevel::Debug); channels raises extra channels; sink overrides the installed dev sink (default a level-prefixed text console sink).

DebugState

The debug umbrella’s state (D5): the source module’s subsystem registry, active session and frame counter, held by the caller instead of in module globals. Registration order is kept, as the source Map keeps insertion order.

DebugSubsystemHooks

The wiring a subsystem contributes to a debug session (TS DebugSubsystemHooks): the log channels raised while it is enabled, and its guard enabler and disabler. Every field is optional. disable_guards must be safe after a missing or partially completed enable_guards, so a failed enable can be unwound.

Functions

begin_debug_span

Opens a named timing span only while a debug session is active (TS beginDebugSpan): a running LogTimer to hand to end_debug_span, or None when debug is disabled (nothing is allocated).

create_debug_state

Creates an empty debug state: no registered subsystems and no active session (D5: the source module’s globals, owned by the caller).

disable_debug

Returns Flight to the zero-debug baseline (TS disableDebug): runs the disable-guards binding of every subsystem the session switched on, removes the sink it installed, and restores the log levels it raised. A no-op when debug is not enabled.

enable_debug

Enables a debug session (TS enableDebug). It installs options.sink, raises the global level (default LogLevel::Debug) and the channels of the selected subsystems plus options.channels, then runs each selected subsystem’s guard enabler in order. options.subsystems selects registered subsystems by name (unregistered names are skipped); omitted, every registered subsystem is switched on. A second call while enabled is a no-op.

enable_flight_diagnostics

Enables a debug session with the default options, then the generic render guards for one render state (TS enableFlightDiagnostics), reporting through the same caller-owned log state.

end_debug_span

Closes a span opened by begin_debug_span (TS endDebugSpan), emitting its elapsed-time Debug entry and returning the elapsed milliseconds. A None timer (debug was disabled when the span opened) is a no-op returning -1, the “not measured” sentinel.

initialize_debug_state

Resets a debug state to the source module’s initial values (the construction initializer of create_debug_state).

is_debug_enabled

Whether a debug session is in effect (TS isDebugEnabled).

mark_debug_frame

Emits a frame-boundary marker while a debug session is active (TS markDebugFrame): a Debug entry { frame: label }, or, unlabeled, the next value of the state’s ascending frame counter, which a new session does not reset. A no-op, with no counter advance, when debug is disabled.

measure_debug_span

Times a synchronous function as one span while a debug session is active (TS measureDebugSpan) and returns its result. With debug disabled the function still runs and only the timing is skipped. The span is closed, and its entry emitted, even when the function panics (the source’s throw), and the panic then resumes. clock is read once when the span opens and once when it closes.

register_debug_subsystem

Registers a subsystem’s channels and guard bindings under name (TS registerDebugSubsystem). Last write wins, and a replaced name keeps its registration position, as the source Map does.

unregister_debug_subsystem

Removes a subsystem registration (TS unregisterDebugSubsystem): false when nothing was registered under name. An already active session is not affected.

Type Aliases

DebugGuardBinding

One subsystem guard binding (TS () => void).

DebugStateRef

Shared caller-owned debug state.

DebugSubsystemName

The name of a diagnostic subsystem (TS DebugSubsystemName): an open string union whose seeded built-ins are animation, audio, input, loader, connectivity, particles, render and text. Custom subsystems use a vendor prefix (acme.physics).