DateTimeUtil: zone-explicit rendering; Instant-path Inception sentinel

The one home for time rendering had two half-complete paths: the epoch
path carried all four sentinel words but always rendered at the system
default zone (no UTC option, so any non-sentinel time in a generated
artifact was machine-dependent), while the Instant/formatter path
rendered UTC but was missing the Inception sentinel the resolution
overload already had. The sentinel handling now lives in one zone-explicit
method -- format(long, formatter, zone) -- with the zone-implicit
overloads delegating at system default for interactive surfaces and
formatUtc(long) delegating at UTC for generated artifacts.
KonceptExtractor since and retiredAt render through formatUtc, making the
extraction timezone-independent; no visible change today, since every IKE
stamp is the inception sentinel. No scattered special-casing anywhere:
callers keep calling DateTimeUtil.

Refs: IKE-Network/ike-issues#897

Author: kec

common/src/main/java/dev/ikm/tinkar/common/util/time/DateTimeUtil.java

@@ -122,6 +122,36 @@ public static String format(long epochMilliSecond) {
         return format(epochMilliSecond, FORMATTER);
     }
     public static String format(long epochMilliSecond, DateTimeFormatter formatter) {
+        return format(epochMilliSecond, formatter, ZoneId.systemDefault());
+    }
+
+    /**
+     * Formats an epoch time in UTC with the default {@link #FORMATTER} — the form for
+     * generated artifacts, whose text must not depend on the generating machine's zone
+     * (IKE-Network/ike-issues#897). Sentinel times render as their words
+     * ({@code Latest}, {@code Canceled}, {@code Premundane}, {@code Inception}),
+     * identically to every other format path.
+     *
+     * @param epochMilliSecond the epoch time in milliseconds, or a sentinel value
+     * @return the sentinel word, or the UTC-rendered time
+     */
+    public static String formatUtc(long epochMilliSecond) {
+        return format(epochMilliSecond, FORMATTER, ZoneOffset.UTC);
+    }
+
+    /**
+     * Formats an epoch time at an explicit zone — the one method carrying the sentinel
+     * handling for the epoch path; the zone-implicit overloads delegate here at
+     * {@link ZoneId#systemDefault()} (interactive surfaces render local), and
+     * {@link #formatUtc(long)} delegates at UTC (generated artifacts render
+     * machine-independently).
+     *
+     * @param epochMilliSecond the epoch time in milliseconds, or a sentinel value
+     * @param formatter        the date-time formatter to render with
+     * @param zone             the zone to render the instant at
+     * @return the sentinel word, or the time rendered at {@code zone}
+     */
+    public static String format(long epochMilliSecond, DateTimeFormatter formatter, ZoneId zone) {
         if (epochMilliSecond == Long.MAX_VALUE) {
             return LATEST;
         }
@@ -134,9 +164,7 @@ public static String format(long epochMilliSecond, DateTimeFormatter formatter)
         if (epochMilliSecond == PrimitiveData.INCEPTION_EPOCH) {
             return INCEPTION;
         }
-        ZonedDateTime positionTime = ZonedDateTime.ofInstant(Instant.ofEpochMilli(epochMilliSecond), ZoneOffset.UTC);
-        ZonedDateTime inLocalZone = positionTime.withZoneSameInstant(ZoneId.systemDefault());
-        return inLocalZone.format(formatter);
+        return ZonedDateTime.ofInstant(Instant.ofEpochMilli(epochMilliSecond), zone).format(formatter);
     }
     public static String timeNowSimple() {
         return TIME_SIMPLE.format(ZonedDateTime.now());
@@ -251,6 +279,9 @@ public static String format(Instant instant, DateTimeFormatter formatter) {
         if (instant.equals(PrimitiveData.INCEPTION_INSTANT)) {
             return INCEPTION;
         }
+        if (instant.equals(PrimitiveData.INCEPTION_INSTANT)) {
+            return INCEPTION;
+        }
         return formatter.format(instant.atOffset(ZoneOffset.UTC));
     }
     public static String format(Instant instant) {

common/src/test/java/dev/ikm/tinkar/common/util/time/DateTimeUtilTest.java

@@ -51,6 +51,28 @@ void format() {
         assertEquals(INCEPTION, DateTimeUtil.format(PrimitiveData.INCEPTION_EPOCH));
     }
 
+    @Test
+    void zoneExplicitRendering() {
+        // A real time renders differently across zones through the zone-explicit form...
+        long epoch = Instant.parse("2027-03-05T04:30:00Z").toEpochMilli();
+        assertEquals("2027-03-05 04:30",
+                DateTimeUtil.format(epoch, DateTimeUtil.FORMATTER, java.time.ZoneOffset.UTC));
+        assertEquals("2027-03-04 20:30",
+                DateTimeUtil.format(epoch, DateTimeUtil.FORMATTER, java.time.ZoneId.of("America/Los_Angeles")));
+        assertEquals("2027-03-05 04:30", DateTimeUtil.formatUtc(epoch),
+                "formatUtc is the machine-independent form for generated artifacts"
+                        + " (IKE-Network/ike-issues#897)");
+
+        // ...while the sentinel words are zone-invariant on every path.
+        assertEquals(INCEPTION, DateTimeUtil.formatUtc(PrimitiveData.INCEPTION_EPOCH));
+        assertEquals(PREMUNDANE, DateTimeUtil.formatUtc(PrimitiveData.PREMUNDANE_TIME));
+        assertEquals(LATEST, DateTimeUtil.formatUtc(Long.MAX_VALUE));
+        assertEquals(CANCELED, DateTimeUtil.formatUtc(Long.MIN_VALUE));
+        assertEquals(INCEPTION,
+                DateTimeUtil.format(PrimitiveData.INCEPTION_INSTANT, DateTimeUtil.SEC_FORMATTER),
+                "the Instant/formatter path carries the inception sentinel like every other path");
+    }
+
     @Test
     void inceptionEpochIsAMillisecondAfterMidnight() {
         // The .777 offset is deliberate: a real calendar date landing exactly at

entity/src/main/java/dev/ikm/tinkar/entity/builder/KonceptExtractor.java

@@ -239,7 +239,7 @@ public static String extractYaml(Integer narrativePatternNid) {
 
             long since = earliestStampTime(nid);
             if (since != Long.MAX_VALUE) {
-                sb.append("  since: ").append(yaml(DateTimeUtil.format(since))).append('\n');
+                sb.append("  since: ").append(yaml(DateTimeUtil.formatUtc(since))).append('\n');
             }
             List<String> comments = activeComments(nid, calculator);
             if (!comments.isEmpty()) {
@@ -254,7 +254,7 @@ public static String extractYaml(Integer narrativePatternNid) {
                 for (RetiredComment retiredComment : retired) {
                     sb.append("    - text: ").append(yaml(retiredComment.text())).append('\n');
                     sb.append("      retiredAt: ")
-                            .append(yaml(DateTimeUtil.format(retiredComment.retiredAt()))).append('\n');
+                            .append(yaml(DateTimeUtil.formatUtc(retiredComment.retiredAt()))).append('\n');
                 }
             }
             if (narrativePatternNid != null) {