001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.revetsec;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import org.jspecify.annotations.NonNull;
021
022import javax.annotation.concurrent.Immutable;
023import java.time.Duration;
024import java.time.Instant;
025
026import static java.util.Objects.requireNonNull;
027
028/**
029 * A backend's immutable time statement, bound to the active data/recovery admission.
030 * <p>
031 * A healthy statement advertises a deployment capability; it is not itself proof of trusted UTC, current
032 * admission, causal worker-clock health or an operation's eligibility. Unavailable time retains only admission
033 * identities and never substitutes worker time or an earlier healthy sample.
034 *
035 * @since 1.0.0
036 */
037@Immutable
038@CheckReturnValue
039public sealed interface StoreTimeObservation
040                permits StoreTimeObservation.Healthy, StoreTimeObservation.Unavailable {
041        /**
042         * Returns the active authority and data/recovery identities.
043         * @return the admission metadata
044         * @since 1.0.0
045         */
046        @NonNull StoreAdmission getAdmission();
047
048        /**
049         * An admitted UTC observation with a fixed generation profile.
050         * <p>
051         * The profile is maximum advance rate 2, maximum worker offset five seconds and a declared UTC-error bound
052         * from zero through 250 milliseconds. Engines must authenticate the root binding and verify the profile,
053         * floors, causal health and original operation budget before using this statement.
054         *
055         * @since 1.0.0
056         */
057        @Immutable
058        @CheckReturnValue
059        final class Healthy implements StoreTimeObservation {
060                private static final @NonNull Duration MAXIMUM_UTC_ERROR = Duration.ofMillis(250);
061                private static final @NonNull Duration MAXIMUM_WORKER_CLOCK_OFFSET = Duration.ofSeconds(5);
062                private final @NonNull StoreAdmission admission;
063                private final @NonNull String clockGeneration;
064                private final @NonNull Instant observedAt;
065                private final @NonNull Duration maximumUtcError;
066
067                private Healthy(@NonNull StoreAdmission admission, @NonNull String clockGeneration,
068                                @NonNull Instant observedAt, @NonNull Duration maximumUtcError) {
069                        this.admission = requireNonNull(admission);
070                        StoreAdmission.validateIdentifier(clockGeneration);
071                        validateInstant(observedAt);
072                        requireNonNull(maximumUtcError);
073                        if (maximumUtcError.isNegative() || maximumUtcError.compareTo(MAXIMUM_UTC_ERROR) > 0)
074                                throw new IllegalArgumentException("Invalid store-time UTC-error bound.");
075                        this.clockGeneration = clockGeneration;
076                        this.observedAt = observedAt;
077                        this.maximumUtcError = maximumUtcError;
078                }
079
080                /**
081                 * Validates a backend's UTC statement without authenticating or admitting it.
082                 *
083                 * @param admission the active authority and data/recovery identities
084                 * @param clockGeneration canonical unpadded Base64URL encoding of exactly 32 bytes
085                 * @param observedAt UTC instant with epoch seconds in 0 through 253402300799, preserving nanoseconds
086                 * @param maximumUtcError the fixed generation's declared bound, zero through 250 milliseconds inclusive
087                 * @return the immutable observation
088                 * @throws NullPointerException if an argument is {@code null}
089                 * @throws IllegalArgumentException if an identifier, instant or error bound is outside the supported profile
090                 * @since 1.0.0
091                 */
092                public static StoreTimeObservation.@NonNull Healthy fromObservation(@NonNull StoreAdmission admission,
093                                @NonNull String clockGeneration, @NonNull Instant observedAt, @NonNull Duration maximumUtcError) {
094                        return new Healthy(admission, clockGeneration, observedAt, maximumUtcError);
095                }
096
097                /**
098                 * Returns the active authority and data/recovery identities.
099                 * @return the admission metadata
100                 * @since 1.0.0
101                 */
102                @Override
103                public @NonNull StoreAdmission getAdmission() {
104                        return this.admission;
105                }
106
107                /**
108                 * Returns the admitted time incarnation's identity.
109                 * @return the canonical clock-generation identifier
110                 * @since 1.0.0
111                 */
112                public @NonNull String getClockGeneration() {
113                        return this.clockGeneration;
114                }
115
116                /**
117                 * Returns the exact UTC observation, without rounding or clamping.
118                 * @return the observed instant
119                 * @since 1.0.0
120                 */
121                public @NonNull Instant getObservedAt() {
122                        return this.observedAt;
123                }
124
125                /**
126                 * Returns the declared UTC-error bound fixed for this generation.
127                 * @return the maximum error
128                 * @since 1.0.0
129                 */
130                public @NonNull Duration getMaximumUtcError() {
131                        return this.maximumUtcError;
132                }
133
134                /**
135                 * Returns the supported maximum UTC advance per measured elapsed second.
136                 * @return the fixed boxed rate, 2
137                 * @since 1.0.0
138                 */
139                public @NonNull Integer getMaximumUtcAdvanceRate() {
140                        return 2;
141                }
142
143                /**
144                 * Returns the supported maximum worker-wall-clock offset, independent of protocol skew.
145                 * @return the fixed five-second bound
146                 * @since 1.0.0
147                 */
148                public @NonNull Duration getMaximumWorkerClockOffset() {
149                        return MAXIMUM_WORKER_CLOCK_OFFSET;
150                }
151
152                /**
153                 * Returns a fixed description that discloses no time, profile or identifier.
154                 * @return the redacted description
155                 * @since 1.0.0
156                 */
157                @Override
158                public @NonNull String toString() {
159                        return "Healthy{observation=<redacted>}";
160                }
161
162                static void validateInstant(@NonNull Instant value) {
163                        requireNonNull(value);
164                        if (value.getEpochSecond() < 0 || value.getEpochSecond() > 253402300799L)
165                                throw new IllegalArgumentException("Invalid store-time instant.");
166                }
167        }
168
169        /**
170         * Time is unavailable while the authority/data admission metadata remains obtainable.
171         *
172         * @since 1.0.0
173         */
174        @Immutable
175        @CheckReturnValue
176        final class Unavailable implements StoreTimeObservation {
177                private final @NonNull StoreAdmission admission;
178
179                private Unavailable(@NonNull StoreAdmission admission) {
180                        this.admission = requireNonNull(admission);
181                }
182
183                /**
184                 * Retains active admission metadata without inventing UTC evidence.
185                 * @param admission the authority and data/recovery identities
186                 * @return the time-unavailable observation
187                 * @throws NullPointerException if {@code admission} is {@code null}
188                 * @since 1.0.0
189                 */
190                public static StoreTimeObservation.@NonNull Unavailable fromAdmission(@NonNull StoreAdmission admission) {
191                        return new Unavailable(admission);
192                }
193
194                /**
195                 * Returns the active authority and data/recovery identities.
196                 * @return the admission metadata
197                 * @since 1.0.0
198                 */
199                @Override
200                public @NonNull StoreAdmission getAdmission() {
201                        return this.admission;
202                }
203
204                /**
205                 * Returns a fixed description that discloses neither identity.
206                 * @return the redacted description
207                 * @since 1.0.0
208                 */
209                @Override
210                public @NonNull String toString() {
211                        return "Unavailable{admission=<redacted>}";
212                }
213        }
214}