feat: publish NIRO Gen5W research overview and reviewed source examples

tests/java/WeatherRefreshGateTest.java

@@ -0,0 +1,59 @@
+import com.chaegeon.niro.WeatherRefreshGate;
+
+public final class WeatherRefreshGateTest {
+    private static void check(boolean condition, String name) {
+        if (!condition) {
+            throw new AssertionError(name);
+        }
+    }
+
+    public static void main(String[] args) {
+        WeatherRefreshGate gate = new WeatherRefreshGate(60000L, 10000L, 2000L);
+        check(gate.admit(100L) == WeatherRefreshGate.Admission.FETCH,
+                "first fetch accepted");
+        check(gate.isRunning(), "running");
+        check(gate.admit(101L) == WeatherRefreshGate.Admission.COALESCE,
+                "in-flight request coalesced");
+        gate.finish(200L, WeatherRefreshGate.Admission.FETCH, true);
+        check(!gate.isRunning(), "finished");
+        check(gate.admit(300L) == WeatherRefreshGate.Admission.REPLAY,
+                "recent successful response replayed");
+        check(gate.replayDelayMillis(300L) == 1900L,
+                "first replay waits until two seconds after fetch callback");
+        check(gate.admit(301L) == WeatherRefreshGate.Admission.COALESCE,
+                "in-flight replay coalesced");
+        gate.finish(400L, WeatherRefreshGate.Admission.REPLAY, true);
+        check(gate.admit(500L) == WeatherRefreshGate.Admission.REPLAY,
+                "second replay admitted without new fetch");
+        check(gate.replayDelayMillis(500L) == 1900L,
+                "subsequent replay is paced from previous callback");
+        gate.finish(501L, WeatherRefreshGate.Admission.REPLAY, true);
+        check(gate.admit(60199L) == WeatherRefreshGate.Admission.REPLAY,
+                "replay does not extend fetch TTL");
+        check(gate.replayDelayMillis(60199L) == 0L,
+                "replay runs immediately after spacing elapsed");
+        gate.finish(60200L, WeatherRefreshGate.Admission.REPLAY, true);
+        check(gate.admit(60200L) == WeatherRefreshGate.Admission.FETCH,
+                "new fetch accepted at original TTL boundary");
+        gate.finish(60300L, WeatherRefreshGate.Admission.FETCH, false);
+        check(gate.admit(60301L) == WeatherRefreshGate.Admission.BACKOFF,
+                "fast failed-fetch retry is throttled");
+        check(!gate.isRunning(), "backoff does not start worker");
+        check(gate.admit(70299L) == WeatherRefreshGate.Admission.BACKOFF,
+                "retry stays throttled until boundary");
+        check(gate.admit(70300L) == WeatherRefreshGate.Admission.FETCH,
+                "failed fetch may retry after ten seconds");
+        gate.finish(70302L, WeatherRefreshGate.Admission.FETCH, true);
+        check(gate.admit(70303L) == WeatherRefreshGate.Admission.REPLAY,
+                "successful response becomes replayable");
+        gate.finish(70304L, WeatherRefreshGate.Admission.REPLAY, false);
+        check(gate.admit(70305L) == WeatherRefreshGate.Admission.BACKOFF,
+                "failed replay invalidates cache and throttles retry");
+        check(gate.admit(80303L) == WeatherRefreshGate.Admission.BACKOFF,
+                "failed replay still throttled before retry boundary");
+        check(gate.admit(80304L) == WeatherRefreshGate.Admission.FETCH,
+                "failed replay retries with fresh fetch after ten seconds");
+        gate.finish(80306L, WeatherRefreshGate.Admission.FETCH, false);
+        System.out.println("result=PASS_WEATHER_REFRESH_GATE");
+    }
+}