agents-pod 0.3.5 → 0.3.7

package/src/cadence.ts

@@ -0,0 +1,67 @@
+import type { WakeUpEntry } from "./registry.ts";
+
+/**
+ * Cadence: what the wake-up record says about *when* a Pod woke, read the same
+ * way by `status` (one Pod), `doctor` (the fleet's rate) and the daily ceiling
+ * (ADR 0032). One module because the three must agree on what counts, and
+ * because "41 wake-ups in 5 h" was the whole incident and nothing in the store
+ * could say it in one command (issue #35).
+ *
+ * A record written before ADR 0032 carries no `at`: those wake-ups are counted
+ * (they are history) but never timed, and every reader says so rather than
+ * inventing a timestamp.
+ */
+
+export const HOUR_MS = 3_600_000;
+export const DAY_MS = 24 * HOUR_MS;
+
+/** A wake-up entry that knows when it happened — the only kind a rate counts. */
+export interface StampedWakeUp extends WakeUpEntry {
+  at: number;
+}
+
+export function stamped(wakeUps: readonly WakeUpEntry[]): StampedWakeUp[] {
+  return wakeUps.filter(
+    (wake): wake is StampedWakeUp => typeof wake.at === "number" && Number.isFinite(wake.at),
+  );
+}
+
+/**
+ * The stamped wake-ups inside a window ending now (half-open: `(now - ms, now]`).
+ * Every outcome counts, `lost` included: a wake-up whose wrapper died still
+ * spent an attempt, and a flapping machine that is called busy is exactly the
+ * report this is meant to prevent.
+ */
+export function inWindow(
+  wakeUps: readonly WakeUpEntry[],
+  now: number,
+  windowMs: number,
+): StampedWakeUp[] {
+  const from = now - windowMs;
+  return stamped(wakeUps).filter((wake) => wake.at > from && wake.at <= now);
+}
+
+/**
+ * The median interval between consecutive stamped wake-ups, in ms — the one
+ * number that separates "it works when asked" from "it is re-arming itself".
+ * `undefined` when fewer than two wake-ups are timed.
+ */
+export function medianIntervalMs(wakeUps: readonly WakeUpEntry[]): number | undefined {
+  const times = stamped(wakeUps)
+    .map((wake) => wake.at)
+    .sort((left, right) => left - right);
+  if (times.length < 2) return undefined;
+  const gaps: number[] = [];
+  for (let index = 1; index < times.length; index += 1) gaps.push(times[index]! - times[index - 1]!);
+  gaps.sort((left, right) => left - right);
+  const middle = Math.floor(gaps.length / 2);
+  return gaps.length % 2 === 1 ? gaps[middle]! : Math.round((gaps[middle - 1]! + gaps[middle]!) / 2);
+}
+
+/** Ages and intervals are read at a glance, never as an epoch (ADR 0027's habit). */
+export function duration(ms: number): string {
+  if (ms < 1_000) return `${Math.max(0, Math.round(ms))}ms`;
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < HOUR_MS) return `${Math.round(ms / 60_000)}m`;
+  return `${Math.round((ms / HOUR_MS) * 10) / 10}h`;
+}