src/engine/save.ts

@@ -13,6 +13,10 @@ import { TICK_MS } from './tickLoop';
  * into a validated, versioned, compressed string and back. Saves carry a
  * `version` so future migrations have a hook; for now a version mismatch is
  * rejected cleanly rather than silently coerced.
+ *
+ * Offline credit: `applyOfflineProgress` floors elapsed ms to whole ticks
+ * (same `TICK_MS` as the live loop) and runs `tickGame` that many times.
+ * Elapsed beyond `DEFAULT_MAX_OFFLINE_MS` is not credited.
  */
 
 export const SAVE_VERSION = 1;

src/engine/tickLoop.ts

@@ -6,11 +6,13 @@
  * keeping the sub-tick remainder so results are independent of how the caller
  * chunks calls (determinism — see the test suite).
  *
- * Offline catch-up is the *same* code path: a large `now` delta simply owes many
- * ticks. `maxTicks` caps how many run per call so a huge delta can't lock the
- * thread; the remainder stays in the accumulator and drains on the next call,
- * so no ticks are ever lost. Clamping the *credited* offline window lives in the
- * save layer (T3.3), not here.
+ * Offline catch-up uses this same path: a large `now` delta owes many ticks.
+ * `maxTicks` caps work per `advance()` call; the accumulator retains the
+ * remainder so no ticks are lost across calls.
+ *
+ * The save layer (`save.ts`) separately clamps how much *wall-clock* elapsed
+ * time is credited on load via `DEFAULT_MAX_OFFLINE_MS`. Tick loop batching
+ * and offline credit clamping are independent concerns.
  */
 
 export const TICK_HZ = 10;