Skip to content

refactor(stella-time): one home for the real time sources behind the Sleeper and Clock ports - #6488

Open
macanderson wants to merge 3 commits into
mainfrom
fix/6484-engine-clock-port
Open

refactor(stella-time): one home for the real time sources behind the Sleeper and Clock ports#6488
macanderson wants to merge 3 commits into
mainfrom
fix/6484-engine-clock-port

Conversation

@macanderson

@macanderson macanderson commented Sep 10, 2026

Copy link
Copy Markdown
Owner

What & why

#6486 routed every instant, wait and timeout in stella-core through retry::Sleeper. It left the other half of the same defect in place: the real time sources are copied. A Unix-epoch wall clock lived three times (stella-cli WallClock, stella-runtime HostClock, stella-serve WallClock); a Tokio sleeper twice (stella-cli, stella-serve); and stella-fleet kept a Sleeper trait of its own with a third TokioSleeper. stella-serve may not link stella-cli or stella-runtime, and stella-core may not link the Tokio timer, so the copies had no home.

This PR gives them one, and ships the two test doubles the follow-up sweep will move every test onto.

  • stella-time holds TokioSleeper (the engine's real sleeper and now), WallClock (Unix epoch, for a stamp another process reads) and MonotonicClock (one origin per process, for a span compared as a number; replaces stella-cli's per-construction SystemClock). The copies are deleted; stella-fleet's trait is gone and its monitor takes the engine's, re-exported under the old name. Justified under AGENTS.md § "When a new crate is justified" on two counts: it holds the effects the ports keep out of stella-core, and it sits below stella-serve. Exemplar: tokio / tokio-test.
  • stella_time::test_util ships PausedSleeper and NoopSleeper behind a test-util feature. Nothing takes them yet: the sweep that retires the ~30 per-file copies in stella-core and stella-engine is the stacked follow-up PR, kept separate so each diff stays under Sourcery's review limit and reads as one change.
  • ADR 0042 records the design fix(stella-core): read every instant, wait and timeout through the Sleeper port #6486 merged (why now sits on Sleeper, why the reading is an Instant) and where the sources and doubles live. fix(stella-core): read every instant, wait and timeout through the Sleeper port #6486 closed nothing and wrote no ADR; SCR-002 asks for one.

Refs #6484 — the issue closes with the follow-up sweep, which lands its last two checklist items.

The witness

  • This PR includes a witness test (fails on main, passes here)

crates/stella-time/tests/one_home.rs reads every shipping .rs under crates/*/src (test directories and tests.rs files skipped) and fails on any impl … Sleeper for outside stella-time, and on any struct WallClock | HostClock | SystemClock | MonotonicClock outside it. The impls that stay are named with reasons: two special-shape doubles (the retry tests' recording sleeper, the monitor's advancing sleeper) and five inline test doubles the follow-up sweep retires; a second test fails if a named one disappears, so the list cannot go stale. On main the sleeper test fails on stella-cli/src/runtime.rs and stella-serve/src/remote.rs, and the clock test on stella-cli/src/runtime.rs (SystemClock, WallClock) and stella-runtime/src/wrapper/stamp.rs (HostClock); stella-fleet/src/monitor.rs is on the kept list for its advancing double, so its production TokioSleeper was reachable only through the trait it also deleted. Locally the time crate's 6 + 3 tests pass, and stella-core, stella-engine, stella-serve, stella-runtime, stella-fleet and stella-cli type-check with their tests.

The gate

Fix over file

  • Extra fixes in this PR, each its own commit:
    • The two high-severity Dependabot alerts on main (sharp <0.35.4, GHSA-rgj7-g3m4-5g8c; js-yaml <4.3.2, GHSA-2883-xcg3-v3hh) are both transitive under website/, so website/pnpm-workspace.yaml raises the sharp floor and adds a js-yaml one, the way that file already handles postcss and nanoid; js-yaml takes a caret because a bare floor resolves to 5.x, which fumadocs does not call.
    • dependency-review re-surfaced sharp's fourteen LGPL-3.0 libvips tuples on that bump (not a required check). They are named in allow-dependencies-licenses, which is the immediate remedy issue dependency-review: the @img/sharp-* LGPL exemption cannot converge — the action has no purl globbing, so every new libvips tuple reds the gate #2532 records, with the reasoning in the workflow comment: the docs site is private, imports no next/image, and ships nothing into either license track.
    • AGENTS.md carried two crate counts ("Twenty-nine crates", "The other twenty-four crates") that a new crate makes wrong; both are now phrased without a number.
  • Nothing was deferred beyond the stacked follow-up.

Ground-rule check

  • No I/O added to stella-core; it is untouched except its README
  • No new outbound network calls
  • No new cross-boundary serde types

Deleted tests

Three tests in stella-cli/src/runtime.rs tested the clocks that module no longer defines, and each has a counterpart in stella-time/src/lib.rs:

  • system_clock_starts_near_zero_and_advances_monotonicallythe_monotonic_clock_never_goes_backwards (plus every_monotonic_clock_shares_one_origin, the property the old per-construction clock lacked)
  • default_constructs_a_fresh_clock → gone with the constructor; MonotonicClock is a unit struct
  • wall_clock_reads_epoch_milliseconds_not_a_process_originthe_wall_clock_counts_from_the_unix_epoch

Anything reviewers should know?

  • An earlier head of this branch redesigned the engine's time as u64 readings of Clock. That design lost to fix(stella-core): read every instant, wait and timeout through the Sleeper port #6486 on the merge order and on the merits the ADR states (a double has to answer now and sleep from one timeline), and it was dropped rather than rebased over the merged one.
  • Sourcery declined the earlier, combined head (208k characters of diff against a 150k limit). That is why the test-double sweep is its own PR.
  • stella-cli's runtime module is now three re-exports and one_shot_budget_guard. The SystemClock rename to MonotonicClock reaches fleet_cmd, agent/engine.rs and two test files, and nothing else.

Summary by Sourcery

Centralize real time sources and shared sleeper doubles in stella-time while preserving the existing time ports across all hosts.

New Features:

  • Add the stella-time crate as the shared home for Tokio-backed sleeping, wall-clock timestamps, process-monotonic timing, and reusable test sleeper doubles.

Bug Fixes:

  • Remove duplicated clock and sleeper implementations across host crates and standardize fleet monitoring on the engine's Sleeper port.
  • Raise transitive website dependency floors to address the sharp and js-yaml security advisories.

Enhancements:

  • Add a source-tree witness test that prevents production time-source implementations from being duplicated outside stella-time.
  • Replace per-construction monotonic clocks with a process-wide shared origin and re-export the shared implementations through existing host modules.

Build:

  • Register stella-time in the workspace and add it as a dependency for the affected host crates.

CI:

  • Allow the newly surfaced sharp LGPL libvips dependency tuples in dependency review with documented rationale.

Documentation:

  • Document the shared time-source boundary in the workspace guidance, add ADR 0042, and update the ADR index and crate documentation.

Tests:

  • Add coverage for wall-clock, monotonic-clock, Tokio sleeper, and jitter behavior, plus the stella-time source-layout witness tests.

Chores:

  • Update workspace guidance to avoid stale crate counts.

@github-actions

github-actions Bot commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

SCR-003 DoD check waived by the closes-nothing label — this PR closes no issue by design.

@macanderson
macanderson force-pushed the fix/6484-engine-clock-port branch from 4153a71 to ec31417 Compare September 10, 2026 07:50
@macanderson macanderson changed the title fix(stella-core): read every instant off the Clock port, and give the hosts one time crate refactor(stella-time): one home for the real time sources and the two sleeper doubles Sep 10, 2026
@macanderson
macanderson force-pushed the fix/6484-engine-clock-port branch 2 times, most recently from 4ed693c to 62937eb Compare September 10, 2026 17:48
@macanderson
macanderson marked this pull request as ready for review September 10, 2026 18:11

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @macanderson, your pull request is larger than the review limit of 150,000 diff characters

@macanderson
macanderson force-pushed the fix/6484-engine-clock-port branch from 62937eb to 2d1f68b Compare September 10, 2026 18:34
@macanderson macanderson added the closes-nothing Substantial change that closes no issue by design (SCR-003) label Sep 10, 2026
@macanderson macanderson changed the title refactor(stella-time): one home for the real time sources and the two sleeper doubles refactor(stella-time): one home for the real time sources behind the Sleeper and Clock ports Sep 10, 2026
…Sleeper and Clock ports

#6486 routed every instant, wait and timeout in stella-core through
retry::Sleeper and left the real sources copied: a wall clock in
stella-cli, stella-runtime and stella-serve, a Tokio sleeper in two of
them, and a sleeper trait of stella-fleet's own with a third.

stella-time now holds TokioSleeper, WallClock and MonotonicClock (which
replaces the CLI's per-construction SystemClock), and ships PausedSleeper
and NoopSleeper behind a test-util feature for the test sweep that
follows. The copies are deleted; stella-fleet's monitor takes the
engine's Sleeper. tests/one_home.rs reads the shipping tree and fails on
any other copy. ADR 0042 records the design #6486 merged and where the
sources live.

Refs #6484
@macanderson
macanderson force-pushed the fix/6484-engine-clock-port branch from 2d1f68b to c6af5f7 Compare September 10, 2026 18:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

closes-nothing Substantial change that closes no issue by design (SCR-003)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant