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 com.revetsec.internal.StoreTimeRules;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023
024import javax.annotation.concurrent.Immutable;
025import java.util.Optional;
026
027import static java.util.Objects.requireNonNull;
028
029/**
030 * Immutable factual validation timing and optional timing after known durable acknowledgement.
031 * <p>
032 * Validation time is not physical commit time. Completion acquisition may fail without changing a known commit;
033 * the backend then supplies absent completion. This factory rejects a supplied inconsistent completion instead of
034 * silently dropping it. Neither observation proves authenticity, effect certainty or service-release eligibility.
035 *
036 * @since 1.0.0
037 */
038@Immutable
039@CheckReturnValue
040public final class StoreCommitTiming {
041        private final StoreTimeObservation.@NonNull Healthy validatedTime;
042        private final StoreTimeObservation.@Nullable Healthy completedTime;
043
044        private StoreCommitTiming(StoreTimeObservation.@NonNull Healthy validatedTime,
045                        StoreTimeObservation.@Nullable Healthy completedTime) {
046                this.validatedTime = validatedTime;
047                this.completedTime = completedTime;
048        }
049
050        /**
051         * Validates the supplied observations without authenticating their timing or transaction outcome.
052         *
053         * @param validatedTime the fresh observation under final transaction locks before the mutation decision
054         * @param completedTime a same-admission/generation/profile observation after known durable acknowledgement,
055         *                      no earlier than validation, or {@code null} when unavailable
056         * @return the immutable timing
057         * @throws NullPointerException if {@code validatedTime} is {@code null}
058         * @throws IllegalArgumentException if supplied completion differs in admission, generation or profile,
059         *                                  or precedes validation
060         * @since 1.0.0
061         */
062        public static @NonNull StoreCommitTiming fromTimes(StoreTimeObservation.@NonNull Healthy validatedTime,
063                        StoreTimeObservation.@Nullable Healthy completedTime) {
064                requireNonNull(validatedTime);
065                if (completedTime != null && (!StoreTimeRules.sameProfile(validatedTime, completedTime)
066                                || completedTime.getObservedAt().isBefore(validatedTime.getObservedAt())))
067                        throw new IllegalArgumentException("Inconsistent store commit timing.");
068                return new StoreCommitTiming(validatedTime, completedTime);
069        }
070
071        /**
072         * Returns the observation from final transaction validation.
073         * @return the validation observation
074         * @since 1.0.0
075         */
076        public StoreTimeObservation.@NonNull Healthy getValidatedTime() {
077                return this.validatedTime;
078        }
079
080        /**
081         * Returns the optional post-acknowledgement observation.
082         * @return the optional completion observation
083         * @since 1.0.0
084         */
085        public @NonNull Optional<StoreTimeObservation.@NonNull Healthy> getCompletedTime() {
086                return Optional.ofNullable(this.completedTime);
087        }
088
089        /**
090         * Returns a fixed description that discloses no timing or identities.
091         * @return the redacted description
092         * @since 1.0.0
093         */
094        @Override
095        public @NonNull String toString() {
096                return "StoreCommitTiming{timing=<redacted>}";
097        }
098}