Time & Pacing

The TimePort — one monotonic clock, one wall clock, and the schedulers pacing is built on.

The TimePort is the seam every pacing mechanism in the mobile app is built on: one monotonic clock, one wall clock, and a per-run scheduler for timers and frames.

Quick Start

1. Pick the real adapter at boot

   createWebTime() builds a TimePort over the browser’s clock and frame loop. Pass it as time: to createApp.

   import { createWebTime } from "praisonai-mobile/adapters/web";
   
   const booted = await createApp({
     time: createWebTime(),
     // ...the rest of the platform adapters
   });

2. Read a monotonic instant

   Call time.nowMs() for delay budgets and elapsed measurements. Call time.epochMs() only when a record needs a real timestamp.

   const startedAt = time.nowMs();      // monotonic: for durations
   const writtenAt = time.epochMs();    // wall clock: for records

   This is what production now does — deps.now is not passed on the real device path, so time.epochMs() runs.

3. Poll or paint through a scheduler

   Create one scheduler per run, then use every, setTimer + clearTimer, and requestFrame. Dispose it at teardown.

   const scheduler = time.createScheduler();     // one per run
   const stop = time.every(16, () => coalescer.flush());
   scheduler.requestFrame(() => paint());
   // on teardown
   stop();
   scheduler.clearTimer();

How It Works

The port carries two clocks and a scheduler factory, and each member has one job.

Why Two Clocks

One clock measures durations, the other stamps records, and collapsing them reintroduces the bug the port was carved to prevent.

When the phone’s clock is corrected mid-turn — a common event on a wake from sleep — a wall-clock elapsed measurement can jump backwards. The publish gate’s MAX_HELD_CHARS and the coalescer’s maxDelayMs are both measured against nowMs, so pacing stays sane through a correction. Records that need to be sortable across devices use epochMs.

The app now reads the port, not Date.now()

main.ts now reads the wall clock through TimePort.epochMs and paces the announcer with the monotonic nowMs — until this landed the shipping app read Date.now() for both, and TimePort.epochMs was implemented, conformance-tested, and had zero callers.

Every wall-clock read in main.ts was Date.now(): the chat record’s updated, the chats-screen “now” argument to buildChatList, and — crucially — the nowMs passed to the screen-reader announcer.

// main.ts — the wall clock resolves through the port on the real device path.
const writtenAt = nowEpochMs();       // platform.time.epochMs() in production
const paced = announce(state, chunk, platform.time.nowMs()); // monotonic

The announcer’s rate-limit nowMs - lastStreamAtMs >= ANNOUNCE_INTERVAL_MS is an elapsed comparison — exactly the conflation core/src/ports/time.ts says in as many words must not be fed a wall clock: “Conflating them is how a clock correction mid-stream makes a coalescer wait forever.”

Executable Specification

The port’s first conformance suite runs the same cases against the fake clock and the web adapter, so the two cannot drift.

Common Patterns

The coalescer’s flush tick is a repeating every, stopped at dispose.

const stop = time.every(maxDelayMs, () => coalescer.flush());
// on dispose
stop();

The publish gate arms a one-shot timer and clears it when a frame arrives.

const scheduler = time.createScheduler();
scheduler.setTimer(forcePaint, UNPAINTED_REOPEN_MS);
// on frame arrival
scheduler.clearTimer();

Best Practices

Related