Migrate core temporal models and related entities to java.time.Instant

This comprehensive refactor continues the migration from Joda-Time to java.time (Instant), focusing on core timestamp models, transition properties, and their integration across the codebase.

Key changes:
- Migrated CreateAutoTimestamp and UpdateAutoTimestamp to use Instant internally, providing Joda-Time bridge methods for backward compatibility.
- Updated TimedTransitionProperty to handle Instant-based transition maps and updated corresponding Hibernate UserTypes (TimedTransitionBaseUserType).
- Migrated GracePeriod, BillingBase, BillingEvent, PollMessage, and PendingActionNotificationResponse fields (e.g., expirationTime, eventTime) to Instant.
- Updated Tld and FeatureFlag models to use Instant for claimsPeriodEnd, bsaEnrollStartTime, and status transitions.
- Enhanced CLI tools and parameters (TransitionListParameter, InstantParameter) to support Instant-based input and output.
- Updated EntityYamlUtils with custom Instant serializers/deserializers to maintain format consistency (e.g., .SSSZ precision) required for YAML-based tests.
- Implemented UtcInstantAdapter to ensure JAXB XML serialization maintains millisecond accuracy, matching legacy Joda-Time behavior.
- Resolved Hibernate 6 type mismatches in JPQL and Native queries by ensuring consistent use of Instant for comparisons.
- Updated GEMINI.md with project-specific engineering standards, including the 'one commit per PR' mandate, full-build validation requirement, and commit message style rules.
- Added necessary @JsonIgnore and @JsonProperty annotations to ensure consistent Jackson serialization across models.
- Introduced RegistryTruth with assertAt() helper to simplify cross-type temporal assertions in tests.
- Refactored DateTimeUtils to use strongly-typed toInstant overloads (DateTime, Timestamp, Date, Instant), eliminating the generic Object-based method.
- Cleaned up fully qualified calls to toDateTime and toInstant by adding static imports across 20+ core model and flow files.

Author: CydeWeys

GEMINI.md

@@ -8,9 +8,11 @@ This document outlines foundational mandates, architectural patterns, and projec
 - **Addition:** When adding new symbols, ensure the corresponding import is added.
 - **Removal:** When removing the last usage of a class or symbol from a file (e.g., removing a `@Inject Clock clock;` field), **immediately remove the associated import**. Do not wait for a build failure to identify unused imports.
 - **Checkstyle:** Proactively fix common checkstyle errors (line length > 100, formatting, unused imports) during the initial code write. Do not wait for CI/build failures to address these, as iterative fixes are inefficient.
-- **Verification:** Before finalizing any change, scan the imports section for redundancy.
+- **Verification**: Before finalizing any change, scan the imports section for redundancy.
+- **License Headers**: When creating new files, ensure the license header uses the current year (e.g., 2026). Existing files should retain their original year.
+
+## 2. Time and Precision Handling (java.time Migration)
 
-### 2. Time and Precision Handling (java.time Migration)
 - **Millisecond Precision:** Always truncate `Instant.now()` to milliseconds (using `.truncatedTo(ChronoUnit.MILLIS)`) to maintain consistency with Joda `DateTime` and the PostgreSQL schema (which enforces millisecond precision via JPA converters).
 - **Clock Injection:**
     - Avoid direct calls to `Instant.now()`, `DateTime.now()`, `ZonedDateTime.now()`, or `System.currentTimeMillis()`.
@@ -50,3 +52,51 @@ This document outlines foundational mandates, architectural patterns, and projec
 ## Performance and Efficiency
 - **Turn Minimization:** Aim for "perfect" code in the first iteration. Iterative fixes for checkstyle or compilation errors consume significant context and time.
 - **Context Management:** Use sub-agents for batch refactoring or high-volume output tasks to keep the main session history lean and efficient.
+
+---
+
+# Gemini Engineering Guide: Nomulus Codebase
+
+This document captures high-level architectural patterns, lessons learned from large-scale refactorings (like the Joda-Time to `java.time` migration), and specific instructions to avoid common pitfalls in this environment.
+
+## 🏛 Architecture Overview
+
+- **Transaction Management:** The codebase uses a custom wrapper around JPA. Always use `tm()` (from `TransactionManagerFactory`) to interact with the database.
+- **Dependency Injection:** Dagger 2 is used extensively. If you see "cannot find symbol" errors for classes starting with `Dagger...`, the project is in a state where annotation processing failed. Fix compilation in core models first to restore generated code.
+- **Value Types:** AutoValue and "ImmutableObject" patterns are dominant. Most models follow a `Buildable` pattern with a nested `Builder`.
+- **Temporal Logic:** The project is migrating from Joda-Time to `java.time`.
+  - Core boundaries: `DateTimeUtils.START_OF_TIME_INSTANT` (Unix Epoch) and `END_OF_TIME_INSTANT` (Long.MAX_VALUE / 1000).
+  - Year Arithmetic: Use `DateTimeUtils.leapSafeAddYears()` and `leapSafeSubtractYears()` to handle February 29th logic correctly.
+
+## Source Control
+- **One Commit Per PR:** All changes for a single PR must be squashed into a single commit before merging.
+- **Default to Amend:** Once an initial commit is created for a PR, all subsequent functional changes should be amended into that same commit by default (`git commit --amend --no-edit`). This ensures the PR remains a single, clean unit of work throughout the development lifecycle.
+- **Commit Message Style:** Follow standard Git commit best practices. The subject line (first line) should be concise, capitalized, and **must not end with punctuation** (e.g., a period).
+- **Final Validation:** Always run `git status` as the final step before declaring a task complete to ensure all changes are committed and the working directory is clean.
+- **Commit Verification:** After any commit or amendment, explicitly verify the success of the operation (e.g., using `git status` and reviewing the diff). Never report a Git operation as "done" without having first successfully executed the command and confirmed the repository state.
+- **Diff Review:** Before finalizing a task, review the full diff (e.g., `git diff HEAD^`) to ensure all changes are functional and relevant. Identify and revert any formatting-only changes in files that do not contain functional updates to keep the commit focused.
+
+## Refactoring & Migration Guardrails
+
+
+### 1. Compiler Warnings are Errors (`-Werror`)
+This project treats Error Prone warnings as errors.
+- **`@InlineMeSuggester`**: When creating deprecated Joda-Time bridge methods (e.g., `getTimestamp() -> return toDateTime(getTimestampInstant())`), you **MUST** immediately add `@SuppressWarnings("InlineMeSuggester")`. If you don't, the build will fail.
+- **Repeatable Annotations**: `@SuppressWarnings` is **NOT** repeatable in this environment. If a method or class already has a suppression (e.g., `@SuppressWarnings("unchecked")`), you must merge them:
+  - ❌ `@SuppressWarnings("unchecked") @SuppressWarnings("InlineMeSuggester")`
+  - ✅ `@SuppressWarnings({"unchecked", "InlineMeSuggester"})`
+
+### 2. Resolving Ambiguity
+- **Null Overloads**: Adding an `Instant` overload to a method that previously took `DateTime` will break all `create(null)` calls. You must cast them: `create((Instant) null)`.
+- **Type Erasure**: Methods taking `Optional<DateTime>` and `Optional<Instant>` will clash due to erasure. Use distinct names, e.g., `setAutorenewEndTimeInstant(Optional<Instant> time)`.
+
+### 3. Build Strategy
+- **Surgical Changes**: In large-scale migrations, focus on "leaf" nodes first (Utilities -> Models -> Flows -> Actions).
+- **PR Size**: Minimize PR size by retaining Joda-Time bridge methods for high-level "Action" and "Flow" classes unless a full migration is requested. Reverting changes to DNS and Reporting logic while updating the underlying models is a valid strategy to keep PRs reviewable.
+- **Validation**: Always run `./gradlew build -x test` before attempting to run unit tests. Unit tests will not run if there are compilation errors in any part of the `core` module. Before finalizing a PR, run the entire build using `./gradlew build` to ensure all checks (including tests, checkstyle, and presubmits) pass.
+
+## 🚫 Common Pitfalls to Avoid
+
+- **Do not go in circles with the build:** If you see an `InlineMeSuggester` error, apply the suppression to **ALL** similar methods in that file and related files in one turn. Do not fix them one by one.
+- **Dagger/AutoValue corruption:** If you modify a builder or a component incorrectly, Dagger will fail to generate code, leading to hundreds of "cannot find symbol" errors. If this happens, `git checkout` the last working state of the specific file and re-apply changes more surgically.
+- **`replace` tool context**: When using `replace` on large files (like `Tld.java` or `DomainBase.java`), provide significant surrounding context. These files have many similar method signatures (getters/setters) that can lead to incorrect replacements.

common/src/main/java/google/registry/util/DateTimeUtils.java

@@ -22,6 +22,7 @@
 import java.sql.Date;
 import java.time.Instant;
 import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
 import javax.annotation.Nullable;
 import org.joda.time.DateTime;
 import org.joda.time.DateTimeZone;
@@ -55,6 +56,34 @@ public abstract class DateTimeUtils {
    */
   public static final Instant END_INSTANT = Instant.ofEpochMilli(Long.MAX_VALUE / 1000);
 
+  /**
+   * Standard ISO 8601 formatter with millisecond precision in UTC.
+   *
+   * <p>Example: {@code 2024-03-27T10:15:30.105Z}
+   *
+   * <p>Uses the 'u' symbol for year to support large/negative years in a way compatible with ISO
+   * 8601.
+   */
+  public static final DateTimeFormatter ISO_8601_FORMATTER =
+      DateTimeFormatter.ofPattern("u-MM-dd'T'HH:mm:ss.SSS'Z'").withZone(ZoneOffset.UTC);
+
+  /**
+   * Parses an ISO-8601 string to an {@link Instant}.
+   *
+   * <p>This method is lenient and supports both strings with and without millisecond precision
+   * (e.g. {@code 2024-03-27T10:15:30Z} and {@code 2024-03-27T10:15:30.105Z}). It also supports
+   * large years (e.g. {@code 294247-01-10T04:00:54.775Z}).
+   */
+  public static Instant parseInstant(String timestamp) {
+    try {
+      // Try the standard millisecond precision format first.
+      return Instant.from(ISO_8601_FORMATTER.parse(timestamp));
+    } catch (java.time.format.DateTimeParseException e) {
+      // Fall back to the standard ISO instant parser which handles varied precision.
+      return Instant.parse(timestamp);
+    }
+  }
+
   /** Returns the earliest of a number of given {@link DateTime} instances. */
   public static DateTime earliestOf(DateTime first, DateTime... rest) {
     return earliestDateTimeOf(Lists.asList(first, rest));
@@ -79,15 +108,26 @@ public static Instant earliestOf(Iterable<Instant> instants) {
 
   /** Returns the latest of a number of given {@link DateTime} instances. */
   public static DateTime latestOf(DateTime first, DateTime... rest) {
+    return latestDateTimeOf(Lists.asList(first, rest));
+  }
+
+  /** Returns the latest of a number of given {@link Instant} instances. */
+  public static Instant latestOf(Instant first, Instant... rest) {
     return latestOf(Lists.asList(first, rest));
   }
 
   /** Returns the latest element in a {@link DateTime} iterable. */
-  public static DateTime latestOf(Iterable<DateTime> dates) {
+  public static DateTime latestDateTimeOf(Iterable<DateTime> dates) {
     checkArgument(!Iterables.isEmpty(dates));
     return Ordering.<DateTime>natural().max(dates);
   }
 
+  /** Returns the latest element in a {@link Instant} iterable. */
+  public static Instant latestOf(Iterable<Instant> instants) {
+    checkArgument(!Iterables.isEmpty(instants));
+    return Ordering.<Instant>natural().max(instants);
+  }
+
   /** Returns whether the first {@link DateTime} is equal to or earlier than the second. */
   public static boolean isBeforeOrAt(DateTime timeToCheck, DateTime timeToCompareTo) {
     return !timeToCheck.isAfter(timeToCompareTo);

common/src/testing/java/google/registry/testing/truth/DateTimeSubject.java

@@ -0,0 +1,95 @@
+// Copyright 2026 The Nomulus Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package google.registry.testing.truth;
+
+import static com.google.common.truth.Truth.assertAbout;
+import static google.registry.util.DateTimeUtils.toDateTime;
+
+import com.google.common.truth.ComparableSubject;
+import com.google.common.truth.FailureMetadata;
+import java.time.Instant;
+import javax.annotation.Nullable;
+import org.joda.time.DateTime;
+
+/**
+ * Truth subject for {@link DateTime}.
+ *
+ * <p>This class facilitates easier temporal testing during the migration from Joda-Time to {@link
+ * java.time}. It provides overloads for comparing {@link DateTime} instances against {@link
+ * Instant} instances, reducing the need for manual conversions in test code.
+ */
+public final class DateTimeSubject extends ComparableSubject<DateTime> {
+
+  private final DateTime actual;
+
+  private DateTimeSubject(FailureMetadata failureMetadata, @Nullable DateTime actual) {
+    super(failureMetadata, actual);
+    this.actual = actual;
+  }
+
+  /** Asserts that the actual {@link DateTime} is equal to the expected {@link DateTime}. */
+  public void isAt(@Nullable DateTime expected) {
+    isEqualTo(expected);
+  }
+
+  /**
+   * Asserts that the actual {@link DateTime} is equal to the expected {@link Instant}.
+   *
+   * <p>Conversion is handled via {@link google.registry.util.DateTimeUtils#toDateTime(Instant)}.
+   */
+  public void isAt(@Nullable Instant expected) {
+    isEqualTo(toDateTime(expected));
+  }
+
+  /** Asserts that the actual {@link DateTime} is strictly before the expected {@link Instant}. */
+  public void isBefore(@Nullable Instant expected) {
+    isLessThan(toDateTime(expected));
+  }
+
+  /** Asserts that the actual {@link DateTime} is at or before the expected {@link DateTime}. */
+  public void isAtOrBefore(@Nullable DateTime expected) {
+    isAtMost(expected);
+  }
+
+  /** Asserts that the actual {@link DateTime} is at or before the expected {@link Instant}. */
+  public void isAtOrBefore(@Nullable Instant expected) {
+    isAtMost(toDateTime(expected));
+  }
+
+  /** Asserts that the actual {@link DateTime} is strictly after the expected {@link Instant}. */
+  public void isAfter(@Nullable Instant expected) {
+    isGreaterThan(toDateTime(expected));
+  }
+
+  /** Asserts that the actual {@link DateTime} is at or after the expected {@link DateTime}. */
+  public void isAtOrAfter(@Nullable DateTime expected) {
+    isAtLeast(expected);
+  }
+
+  /** Asserts that the actual {@link DateTime} is at or after the expected {@link Instant}. */
+  public void isAtOrAfter(@Nullable Instant expected) {
+    isAtLeast(toDateTime(expected));
+  }
+
+  /** Static entry point for creating a {@link DateTimeSubject} for the given actual value. */
+  public static DateTimeSubject assertThat(@Nullable DateTime actual) {
+    return assertAbout(DateTimeSubject::new).that(actual);
+  }
+
+  /** Internal factory for Truth. */
+  static Factory<DateTimeSubject, DateTime> dateTimes() {
+    return DateTimeSubject::new;
+  }
+}

common/src/testing/java/google/registry/testing/truth/InstantSubject.java

@@ -0,0 +1,95 @@
+// Copyright 2026 The Nomulus Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package google.registry.testing.truth;
+
+import static com.google.common.truth.Truth.assertAbout;
+import static google.registry.util.DateTimeUtils.toInstant;
+
+import com.google.common.truth.ComparableSubject;
+import com.google.common.truth.FailureMetadata;
+import java.time.Instant;
+import javax.annotation.Nullable;
+import org.joda.time.DateTime;
+
+/**
+ * Truth subject for {@link Instant}.
+ *
+ * <p>This class facilitates easier temporal testing during the migration from Joda-Time to {@link
+ * java.time}. It provides overloads for comparing {@link Instant} instances against {@link
+ * DateTime} instances, reducing the need for manual conversions in test code.
+ */
+public final class InstantSubject extends ComparableSubject<Instant> {
+
+  private final Instant actual;
+
+  private InstantSubject(FailureMetadata failureMetadata, @Nullable Instant actual) {
+    super(failureMetadata, actual);
+    this.actual = actual;
+  }
+
+  /** Asserts that the actual {@link Instant} is equal to the expected {@link Instant}. */
+  public void isAt(@Nullable Instant expected) {
+    isEqualTo(expected);
+  }
+
+  /**
+   * Asserts that the actual {@link Instant} is equal to the expected {@link DateTime}.
+   *
+   * <p>Conversion is handled via {@link google.registry.util.DateTimeUtils#toInstant(DateTime)}.
+   */
+  public void isAt(@Nullable DateTime expected) {
+    isEqualTo(toInstant(expected));
+  }
+
+  /** Asserts that the actual {@link Instant} is strictly before the expected {@link DateTime}. */
+  public void isBefore(@Nullable DateTime expected) {
+    isLessThan(toInstant(expected));
+  }
+
+  /** Asserts that the actual {@link Instant} is at or before the expected {@link Instant}. */
+  public void isAtOrBefore(@Nullable Instant expected) {
+    isAtMost(expected);
+  }
+
+  /** Asserts that the actual {@link Instant} is at or before the expected {@link DateTime}. */
+  public void isAtOrBefore(@Nullable DateTime expected) {
+    isAtMost(toInstant(expected));
+  }
+
+  /** Asserts that the actual {@link Instant} is strictly after the expected {@link DateTime}. */
+  public void isAfter(@Nullable DateTime expected) {
+    isGreaterThan(toInstant(expected));
+  }
+
+  /** Asserts that the actual {@link Instant} is at or after the expected {@link Instant}. */
+  public void isAtOrAfter(@Nullable Instant expected) {
+    isAtLeast(expected);
+  }
+
+  /** Asserts that the actual {@link Instant} is at or after the expected {@link DateTime}. */
+  public void isAtOrAfter(@Nullable DateTime expected) {
+    isAtLeast(toInstant(expected));
+  }
+
+  /** Static entry point for creating an {@link InstantSubject} for the given actual value. */
+  public static InstantSubject assertThat(@Nullable Instant actual) {
+    return assertAbout(InstantSubject::new).that(actual);
+  }
+
+  /** Internal factory for Truth. */
+  static Factory<InstantSubject, Instant> instants() {
+    return InstantSubject::new;
+  }
+}

common/src/testing/java/google/registry/testing/truth/RegistryTruth.java

@@ -0,0 +1,42 @@
+// Copyright 2026 The Nomulus Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package google.registry.testing.truth;
+
+import java.time.Instant;
+import javax.annotation.Nullable;
+import org.joda.time.DateTime;
+
+/**
+ * Central entry point for Nomulus-specific Truth subjects.
+ *
+ * <p>This class provides convenient methods for performing temporal assertions in tests, especially
+ * during the migration from Joda-Time to {@link java.time}.
+ *
+ * <p>Usage: {@code import static google.registry.testing.truth.RegistryTruth.assertAt;}
+ */
+public final class RegistryTruth {
+
+  /** Returns a {@link InstantSubject} for the given {@link Instant}. */
+  public static InstantSubject assertAt(@Nullable Instant actual) {
+    return InstantSubject.assertThat(actual);
+  }
+
+  /** Returns a {@link DateTimeSubject} for the given {@link DateTime}. */
+  public static DateTimeSubject assertAt(@Nullable DateTime actual) {
+    return DateTimeSubject.assertThat(actual);
+  }
+
+  private RegistryTruth() {}
+}

config/presubmits.py

@@ -153,7 +153,7 @@ def fails(self, file):
     PresubmitCheck(
         r".*java\.util\.Date.*",
         "java",
-        {"/node_modules/", "JpaTransactionManagerImpl.java"},
+        {"/node_modules/", "JpaTransactionManagerImpl.java", "DateTimeUtils.java"},
     ):
         "Do not use java.util.Date. Use classes in java.time package instead.",
     PresubmitCheck(