Draft: Proposed clocks improvements

README.md

@@ -71,32 +71,31 @@ default-monotonic-clock: monotonic-clock
 ```
 
 ```rust
-   let start: Instant = monotonic_clock::now(clock);
+   let start: Mark = monotonic_clock::now(clock);
 
    // some stuff
 
-   let stop: Instant = monotonic_clock::now(clock);
+   let stop: Mark = monotonic_clock::now(clock);
 
-   let elapsed: Instant = stop - start;
+   let elapsed: Duration = stop - start;
 ```
 
 
 #### Telling the current human time:
 
 ```rust
-    let the_current_time = wall_clock::now();
+    let the_current_time = system_clock::now();
 
     println!("it has been {} seconds and {} nanoseconds since the Unix epoch!", the_current_time.seconds, the_current_time.nanoseconds);
 ```
 
 #### Retrieving the timezone:
 
 ```rust
-    let datetime: Datetime = wall_clock::now();
-
-    let timezone_display: TimezoneDisplay = timezone::display(datetime);
-
-    println!("the timezone is {}", timezone_display.name);
+    let instant: Instant = system_clock::now();
+    let id = timezone::id();
+    let offset_h = timezone::utc_offset(instant) as f64 / 3600e9;
+    println!("the timezone is {} at UTC{:+}", id, offset_h);
 ```
 
 ### Detailed design discussion
@@ -105,14 +104,14 @@ default-monotonic-clock: monotonic-clock
 
 In POSIX, `clock_gettime` uses a single `timespec` type to represent timestamps
 from all clocks, with two fields: seconds and nanoseconds. However, in applications
-that just need to measure elapsed time, and don't need to care about wall clock
+that just need to measure elapsed time, and don't need to care about absolute
 time, working with seconds and nanoseconds as separate fields adds extra code size
 and complexity. For these use cases, a single 64-bit nanoseconds value, which can
 measure up to about 584 years, is sufficient and simpler.
 
-For wall clock time, it's still useful to have both seconds and nanoseconds, both
+For system time, it's still useful to have both seconds and nanoseconds, both
 to be able to represent dates in the far future, and to reflect the fact that
-code working with wall clock time will often want to treat seconds and fractions
+code working with system time will often want to treat seconds and fractions
 of seconds differently.
 
 And so, this API uses different data types for different types of clocks.

wit-0.3.0-draft/monotonic-clock.wit

@@ -9,35 +9,33 @@ package wasi:[email protected];
 /// successive reads of the clock will produce non-decreasing values.
 @since(version = 0.3.0-rc-2025-08-15)
 interface monotonic-clock {
-    /// An instant in time, in nanoseconds. An instant is relative to an
+    use types.{duration};
+
+    /// A mark on a monotonic clock is a number of nanoseconds since an
     /// unspecified initial value, and can only be compared to instances from
     /// the same monotonic-clock.
     @since(version = 0.3.0-rc-2025-08-15)
-    type instant = u64;
-
-    /// A duration of time, in nanoseconds.
-    @since(version = 0.3.0-rc-2025-08-15)
-    type duration = u64;
+    type mark = u64;
 
     /// Read the current value of the clock.
     ///
     /// The clock is monotonic, therefore calling this function repeatedly will
     /// produce a sequence of non-decreasing values.
     @since(version = 0.3.0-rc-2025-08-15)
-    now: func() -> instant;
+    now: func() -> mark;
 
     /// Query the resolution of the clock. Returns the duration of time
     /// corresponding to a clock tick.
     @since(version = 0.3.0-rc-2025-08-15)
     get-resolution: func() -> duration;
 
-    /// Wait until the specified instant has occurred.
+    /// Wait until the specified mark has occurred.
     @since(version = 0.3.0-rc-2025-08-15)
     wait-until: async func(
-        when: instant,
+        when: mark,
     );
 
-    /// Wait for the specified duration to elapse.
+    /// Wait for the specified duration.
     @since(version = 0.3.0-rc-2025-08-15)
     wait-for: async func(
         how-long: duration,

wit-0.3.0-draft/system-clock.wit

@@ -0,0 +1,51 @@
+package wasi:[email protected];
+/// WASI System Clock is a clock API intended to let users query the current
+/// time. The clock is not necessarily monotonic as it may be reset.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// External references may be reset, so this clock is not necessarily
+/// monotonic, making it unsuitable for measuring elapsed time.
+///
+/// It is intended for reporting the current date and time for humans.
+@since(version = 0.3.0-rc-2025-08-15)
+interface system-clock {
+    use types.{duration};
+
+    /// An "instant", or "exact time", is a point in time without regard to any
+    /// time zone: just the time since a particular external reference point,
+    /// often called an "epoch".
+    ///
+    /// Here, the epoch is 1970-01-01T00:00:00Z, also known as
+    /// [POSIX's Seconds Since the Epoch], also known as [Unix Time].
+    ///
+    /// Note that even if the seconds field is negative, incrementing
+    /// nanoseconds always represents moving forwards in time.
+    /// For example, `{ -1 seconds, 999999999 nanoseconds }` represents the
+    /// instant one nanosecond before the epoch.
+    /// For more on various different ways to represent time, see
+    /// https://tc39.es/proposal-temporal/docs/timezone.html
+    ///
+    /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
+    /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
+    @since(version = 0.3.0-rc-2025-08-15)
+    record instant {
+        seconds: s64,
+        nanoseconds: u32,
+    }
+
+    /// Read the current value of the clock.
+    ///
+    /// This clock is not monotonic, therefore calling this function repeatedly
+    /// will not necessarily produce a sequence of non-decreasing values.
+    ///
+    /// The nanoseconds field of the output is always less than 1000000000.
+    @since(version = 0.3.0-rc-2025-08-15)
+    now: func() -> instant;
+
+    /// Query the resolution of the clock. Returns the smallest duration of time
+    /// that the implementation permits distinguishing.
+    @since(version = 0.3.0-rc-2025-08-15)
+    get-resolution: func() -> duration;
+}

wit-0.3.0-draft/timezone.wit

@@ -3,53 +3,44 @@ package wasi:[email protected];
 @unstable(feature = clocks-timezone)
 interface timezone {
     @unstable(feature = clocks-timezone)
-    use wall-clock.{datetime};
+    use system-clock.{instant};
 
-    /// Return information needed to display the given `datetime`. This includes
-    /// the UTC offset, the time zone name, and a flag indicating whether
-    /// daylight saving time is active.
+    /// Return the IANA identifier of the currently configured timezone. This
+    /// should be an identifier from the IANA Time Zone Database.
     ///
-    /// If the timezone cannot be determined for the given `datetime`, return a
-    /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
-    /// saving time.
+    /// For displaying to a user, the identifier should be converted into a
+    /// localized name by means of an internationalization API.
+    ///
+    /// If the implementation does not expose an actual timezone, or is unable
+    /// to provide mappings from times to deltas between the configured timezone
+    /// and UTC, or determining the current timezone fails, or the timezone does
+    /// not have an IANA identifier, this returns nothing.
     @unstable(feature = clocks-timezone)
-    display: func(when: datetime) -> timezone-display;
+    iana-id: func() -> option<string>;
 
-    /// The same as `display`, but only return the UTC offset.
+    /// The number of nanoseconds difference between UTC time and the local
+    /// time of the currently configured timezone, at the exact time of
+    /// `instant`.
+    ///
+    /// The magnitude of the returned value will always be less than
+    /// 86,400,000,000,000 which is the number of nanoseconds in a day
+    /// (24*60*60*1e9).
+    ///
+    /// If the implementation does not expose an actual timezone, or is unable
+    /// to provide mappings from times to deltas between the configured timezone
+    /// and UTC, or determining the current timezone fails, this returns
+    /// nothing.
     @unstable(feature = clocks-timezone)
-    utc-offset: func(when: datetime) -> s32;
+    utc-offset: func(when: instant) -> option<s64>;
 
-    /// Information useful for displaying the timezone of a specific `datetime`.
+    /// Returns a string that is suitable to assist humans in debugging whether
+    /// any timezone is available, and if so, which. This may be the same string
+    /// as `iana-id`, or a formatted representation of the UTC offset such as
+    /// `-04:00`, or something else.
     ///
-    /// This information may vary within a single `timezone` to reflect daylight
-    /// saving time adjustments.
+    /// WARNING: The returned string should not be consumed mechanically! It may
+    /// change across platforms, hosts, or other implementation details. Parsing
+    /// this string is a major platform-compatibility hazard.
     @unstable(feature = clocks-timezone)
-    record timezone-display {
-        /// The number of seconds difference between UTC time and the local
-        /// time of the timezone.
-        ///
-        /// The returned value will always be less than 86400 which is the
-        /// number of seconds in a day (24*60*60).
-        ///
-        /// In implementations that do not expose an actual time zone, this
-        /// should return 0.
-        utc-offset: s32,
-
-        /// The abbreviated name of the timezone to display to a user. The name
-        /// `UTC` indicates Coordinated Universal Time. Otherwise, this should
-        /// reference local standards for the name of the time zone.
-        ///
-        /// In implementations that do not expose an actual time zone, this
-        /// should be the string `UTC`.
-        ///
-        /// In time zones that do not have an applicable name, a formatted
-        /// representation of the UTC offset may be returned, such as `-04:00`.
-        name: string,
-
-        /// Whether daylight saving time is active.
-        ///
-        /// In implementations that do not expose an actual time zone, this
-        /// should return false.
-        in-daylight-saving-time: bool,
-    }
+    to-debug-string: func() -> string;
 }

wit-0.3.0-draft/types.wit

@@ -0,0 +1,8 @@
+package wasi:clocks@0.3.0-rc-2025-08-15;
+/// This interface common types used throughout wasi:clocks.
+@since(version = 0.3.0-rc-2025-08-15)
+interface types {
+    /// A duration of time, in nanoseconds.
+    @since(version = 0.3.0-rc-2025-08-15)
+    type duration = u64;
+}

wit-0.3.0-draft/world.wit

@@ -5,7 +5,7 @@ world imports {
     @since(version = 0.3.0-rc-2025-08-15)
     import monotonic-clock;
     @since(version = 0.3.0-rc-2025-08-15)
-    import wall-clock;
+    import system-clock;
     @unstable(feature = clocks-timezone)
     import timezone;
 }