From 1957e3f1b5fe24cc8b355911be5102c9c5c6593f Mon Sep 17 00:00:00 2001 From: Aman Kumar Date: Fri, 6 Feb 2026 15:06:57 +0530 Subject: [PATCH] docs(api): clarify crash_point() phase semantics - Add explicit safety contract for all phases - Add phase behavior table (Orchestrator/Execution/Verify) - Document that crash counter is not incremented outside Execution Closes #15 --- src/rt.rs | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/src/rt.rs b/src/rt.rs index 07aaeba..7ebd7f2 100644 --- a/src/rt.rs +++ b/src/rt.rs @@ -70,14 +70,20 @@ pub(crate) fn runtime() -> &'static RuntimeConfig { RUNTIME.get_or_init(init_runtime) } -/// A potential crash location in the execution. +/// Marks a potential crash location during test execution. /// -/// When FIRST is active during the "Execution" phase, this function: -/// 1. Increments the global crash counter. -/// 2. If `counter == target`, terminates the process immediately via SIGKILL. -/// 3. Otherwise, returns normally. +/// Calling this function is always safe in all phases. Outside the +/// Execution phase, it is a silent no-op and does not modify internal state. /// -/// When FIRST is inactive (Orchestrator or Verify phase), this is a no-op. +/// # Phase Behavior +/// +/// | Phase | Behavior | +/// |--------------|--------------------------------------------------| +/// | Orchestrator | No-op (silently ignored) | +/// | Execution | Increments counter and may terminate the process | +/// | Verify | No-op (silently ignored) | +/// +/// In non-Execution phases, the crash counter is not incremented. /// /// # Arguments ///