Skip to content

refactor(runtime): make tool launches clockless#268

Merged
jBernavaPrah merged 2 commits into
mainfrom
feat/39-tool-clock-boundary
Jul 16, 2026
Merged

refactor(runtime): make tool launches clockless#268
jBernavaPrah merged 2 commits into
mainfrom
feat/39-tool-clock-boundary

Conversation

@jBernavaPrah

@jBernavaPrah jBernavaPrah commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Refs phoxal/.github#39

Summary

  • give #[phoxal::tool] a clockless type-level launch policy: tool binaries expose neither --clock nor --simulation, ignore PHOXAL_CLOCK, and cannot opt into logical-time execution
  • remove clock injection from normal runner APIs; keep the hidden deterministic test seam restricted to checked graph participants with the clocked launch policy
  • delete the dedicated tool-boundary simulation example/test/documentation and retain hello-rover's neutral default.wbt world with 1 m walls
  • keep joypad, router, and telemetry periodic work on skipped host ticks; publish zero immediately when the selected joypad disconnects
  • move manual-command retention and the 150 ms freshness decision into motion's consumer-local monotonic domain with a bounded newest-wins slot

Why

Tools represent external devices, operator input, networking, and host diagnostics. They do not own robot state transitions and therefore must not join the robot logical clock or Webots step barrier. The previous generic runner and launch surfaces exposed clock selection to every participant and required a runtime participant == "tool" branch to repair that mismatch.

The boundary is now encoded by the participant macro and launch-policy type. Runner code selects behavior through that policy, with no string-based tool special case.

Validation

  • cargo test --workspace --quiet
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo fmt --all -- --check
  • git diff --check
  • focused runner suite: 11 passed
  • focused launch-policy suite: 6 passed
  • trybuild compile/pass suite, including a tool that manually adds the public graph marker
  • actual phoxal-tool-telemetry --help: no clock flag or environment binding
  • actual tool invocations reject both --clock simulation and --simulation
  • Webots R2025a loads examples/hello-rover/worlds/default.wbt headlessly with the 1 m walls

Review

Independent cross-review found a potential bypass through the public graph marker. The deterministic clock seam now additionally requires LaunchPolicy = ClockedParticipantLaunch, and the compile-fail test proves a tool cannot bypass that by manually implementing the marker. The reviewer rechecked the fix and found no remaining code blocker. The one stale API-doc sentence found on the final pass was corrected before commit 12ef9f7.

Delivery order

This is the contract-owning framework change. After merge and the framework release/catalog completes, the CLI follow-up removes obsolete simulation-clock configuration for standard tools and runs mode-parity/clean-room validation. Organization documentation reconciliation follows last.

@jBernavaPrah jBernavaPrah changed the title feat(runtime): keep tools outside logical time refactor(runtime): make tool launches clockless Jul 16, 2026
@jBernavaPrah jBernavaPrah marked this pull request as ready for review July 16, 2026 13:03
@jBernavaPrah jBernavaPrah merged commit ebf981b into main Jul 16, 2026
10 checks passed
@jBernavaPrah jBernavaPrah deleted the feat/39-tool-clock-boundary branch July 16, 2026 13:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant