Expose ABI.EncodedInstant as tools SPI. (#1588)

Follow-up to #1587.

Exposes `ABI.EncodedInstant` as SPI along with some conversion helpers
to get a Foundation `Date` or suspending clock instant from an instance
thereof. A value of this type is associated with each event in the event
stream.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Author: grynspan

Sources/Overlays/_Testing_Foundation/Events/Clock+Date.swift

@@ -1,7 +1,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Copyright (c) 2024–2026 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
@@ -12,19 +12,32 @@
 @_spi(Experimental) @_spi(ForToolsIntegrationOnly) public import Testing
 public import Foundation
 
+@_spi(ForToolsIntegrationOnly)
 extension Date {
   /// Initialize this date to the equivalent of the same date on the testing
   /// library's clock.
   ///
   /// - Parameters:
-  ///   - testClockInstant: The equivalent instant on ``Test/Clock``.
+  ///   - instant: The equivalent instant on ``Test/Clock``.
   ///
   /// The resulting instance is equivalent to the wall-clock time represented by
-  /// `testClockInstant`. For precise date/time calculations, convert instances
-  /// of ``Test/Clock/Instant`` to `SuspendingClock.Instant` instead of `Date`.
-  @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
-  public init(_ testClockInstant: Test.Clock.Instant) {
-    self.init(timeIntervalSince1970: testClockInstant.durationSince1970 / .seconds(1))
+  /// `instant`. For precise date/time calculations, convert instances of
+  /// ``Test/Clock/Instant`` to `SuspendingClock.Instant` instead of `Date`.
+  public init(_ instant: Test.Clock.Instant) {
+    self.init(timeIntervalSince1970: instant.durationSince1970 / .seconds(1))
+  }
+
+  /// Initialize this date to equal an instant from the testing library's event
+  /// stream.
+  ///
+  /// - Parameters:
+  ///   - instant: The encoded instant to initialize this instance from.
+  ///
+  /// The resulting instance is equivalent to the wall-clock time represented by
+  /// `instant`. For precise date/time calculations, convert instances of
+  /// ``ABI/EncodedInstant`` to `SuspendingClock.Instant` instead of `Date`.
+  public init?<V>(decoding instant: ABI.EncodedInstant<V>) {
+    self.init(timeIntervalSince1970: instant.since1970)
   }
 }
 #endif

Sources/Testing/ABI/Encoded/ABI.EncodedEvent.swift

@@ -40,7 +40,7 @@ extension ABI {
     var kind: Kind
 
     /// The instant at which the event occurred.
-    var instant: EncodedInstant<V>
+    public var instant: EncodedInstant<V>
 
     /// The issue that occurred, if any.
     ///

Sources/Testing/ABI/Encoded/ABI.EncodedInstant.swift

@@ -1,7 +1,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Copyright (c) 2024–2026 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
@@ -12,29 +12,54 @@ extension ABI {
   /// A type implementing the JSON encoding of ``Test/Clock/Instant`` for the
   /// ABI entry point and event stream output.
   ///
-  /// This type is not part of the public interface of the testing library. It
-  /// assists in converting values to JSON; clients that consume this JSON are
-  /// expected to write their own decoders.
-  struct EncodedInstant<V>: Sendable where V: ABI.Version {
+  /// You can use this type and its conformance to [`Codable`](https://developer.apple.com/documentation/swift/codable),
+  /// when integrating the testing library with development tools. It is not
+  /// part of the testing library's public interface.
+  public struct EncodedInstant<V>: Sendable where V: ABI.Version {
     /// The number of seconds since the system-defined suspending epoch.
     ///
     /// For more information, see [`SuspendingClock`](https://developer.apple.com/documentation/swift/suspendingclock).
     var absolute: Double
 
     /// The number of seconds since the UNIX epoch (1970-01-01 00:00:00 UT).
-    var since1970: Double
+    package var since1970: Double
+  }
+}
+
+// MARK: - Conversion to/from library types
 
-    init(encoding instant: borrowing Test.Clock.Instant) {
-      absolute = instant.suspending.rawValue / .seconds(1)
+extension ABI.EncodedInstant {
+  /// Initialize an instance of this type from the given value.
+  ///
+  /// - Parameters:
+  ///   - instant: The instant to initialize this instance from.
+  public init(encoding instant: borrowing Test.Clock.Instant) {
+    absolute = instant.suspending.rawValue / .seconds(1)
 #if !SWT_NO_UTC_CLOCK
-      since1970 = instant.wall.rawValue / .seconds(1)
+    since1970 = instant.wall.rawValue / .seconds(1)
 #else
-      since1970 = 0
+    since1970 = 0
 #endif
-    }
   }
 }
 
+@_spi(ForToolsIntegrationOnly)
+extension SuspendingClock.Instant {
+  /// Initialize this instant to equal an instant from the testing library's
+  /// event stream.
+  ///
+  /// - Parameters:
+  ///   - instant: The encoded instant to initialize this instance from.
+  ///
+  /// The resulting instance is equivalent to the suspending-clock time
+  /// represented by `instant`.
+  public init?<V>(decoding instant: ABI.EncodedInstant<V>) {
+    self = SuspendingClock().systemEpoch + .seconds(instant.absolute)
+  }
+}
+
+// Date.init(decoding:) is in the Foundation overlay.
+
 // MARK: - Codable
 
 extension ABI.EncodedInstant: Codable {}