Controlled Stop, Cancel, and Kill Switch

Touba distinguishes a normal pause, a governed cancellation, a failure, and a successful end.

This page documents the available controls.

1. Cancel Before the First Dispatch

Terminal

touba run program.air.json \
  --cancel-before-dispatch \
  --output trace

Expected effect:

• the runtime traces run_cancel_requested;
• the first dispatch is refused with dispatch_refused_cancelled;
• the run ends with run_completed.status = "cancelled".

2. Cancel on Pause

Terminal

touba run program.air.json \
  --cancel-on-pause \
  --output trace

This mode is useful for testing a run that stops on:

• human.approve;
• human.review;
• ask.

Expected effect:

• the pause remains visible in the trace;
• no user answer is invented;
• the run ends as cancelled.

3. Define a Global Timeout

Terminal

touba run program.air.json \
  --run-timeout-ms 5000 \
  --output trace

The global timeout is cooperative. It is observed at runtime boundaries.

This means:

• a handler already launched is not abruptly killed by this timeout;
• the runtime refuses the next dispatch;
• the trace contains run_timeout_exceeded, then run_cancel_requested.

Handler timeouts remain declared in the manifest with timeout_ms. They are distinct from the global run timeout.

4. Enable the Kill Switch

Terminal

touba run program.air.json \
  --manifest touba.manifest.json \
  --trigger-event-json '{"trigger_ref":"trigger:examples.daily/DailyRun","event_id":"evt-001","source_kind":"schedule"}' \
  --kill-switch-enabled \
  --output trace

Expected effect:

• the runtime traces kill_switch_enabled;
• cancellation is requested;
• a trigger is refused before executing its target;
• the run ends as cancelled.

The kill switch applies to the host-side execution. Cloud control planes, distributed daemons, and hard process termination are separate platform layers.

5. Read the Trace

Terminal

touba inspect trace.json

Look for these events:

run_cancel_requested
run_timeout_exceeded
kill_switch_enabled
dispatch_refused_cancelled
run_cancelled
run_completed

The expected terminal status is:

{ "status": "cancelled" }

Runtime Contract

This control layer makes stopping observable, explicit, and testable:

• portable cancellation requests;
• traceable refusal before dispatch;
• cooperative timeout handling at runtime boundaries;
• trigger refusal when the kill switch is enabled;
• trace preservation after cancellation.

Portable interruption of an already-running process, cancellation of external effects already produced, distributed control planes, cloud kill switches, and trace deletion policies belong to host and platform operations.