Add autoscaling policy model and deterministic planner

src/lib/server/autoscaling/planner.ts

@@ -0,0 +1,42 @@
+import type { ScalingDecision, ScalingMember, ScalingPolicy, ScalingSnapshot } from '../../autoscaling.js';
+import { ONLINE_MAX_MS } from '../../server-freshness.js';
+
+export interface EmptyObservation { identity: string; observedAt: number | null; emptySince: number | null; evaluatedAt: number }
+/** Only distinct, continuous evidence can advance an empty interval. */
+export function emptyObservation(member: ScalingMember, previous: EmptyObservation | undefined, now: number): EmptyObservation {
+    const stamp = member.observedAt;
+    const empty = member.state === 'empty' && stamp !== null && stamp <= now && now - stamp <= ONLINE_MAX_MS;
+    const continuous = empty && previous?.identity === member.identity && previous.emptySince !== null
+        && previous.observedAt !== null && stamp >= previous.observedAt && stamp - previous.observedAt <= ONLINE_MAX_MS
+        && now >= previous.evaluatedAt && now - previous.evaluatedAt <= ONLINE_MAX_MS;
+    return { identity: member.identity, observedAt: stamp, emptySince: empty ? continuous ? previous!.emptySince : stamp : null, evaluatedAt: now };
+}
+
+export function planScaling(policy: ScalingPolicy, snapshot: ScalingSnapshot, now: number): ScalingDecision {
+    const { members } = snapshot;
+    const occupied = members.filter(m => m.state === 'occupied').length, empty = members.filter(m => m.state === 'empty').length;
+    const pending = members.filter(m => m.state === 'creating' || m.state === 'removing').length;
+    const unknown = members.filter(m => m.state === 'unknown' || m.state === 'stopped').length;
+    const desired = Math.min(policy.maximum, Math.max(policy.minimum, occupied + policy.spares));
+    const result = (action: ScalingDecision['action'], reason: string, server: string | null = null): ScalingDecision =>
+        ({ action, reason, server, desired, occupied, empty, pending, unknown });
+    if (policy.mode === 'off') return result('wait', policy.pausedReason ?? 'Policy is off.');
+    if (policy.pausedReason) return result('wait', policy.pausedReason);
+    if (snapshot.blockers.length) return result('wait', snapshot.blockers[0]);
+    const blocked = members.find(m => !['occupied', 'empty'].includes(m.state));
+    if (blocked) return result('wait', blocked.blocker ?? `Waiting for ${blocked.name}: ${blocked.state}.`);
+    if (members.some(m => m.observedAt === null || m.observedAt > now || now - m.observedAt > ONLINE_MAX_MS)) return result('wait', 'Waiting for fresh occupancy evidence.');
+    if (policy.nextActionAt > now) return result('wait', 'Action cooldown is active.');
+    if (occupied + empty < desired) {
+        if (snapshot.reservedNames.length >= policy.maximum) return result('wait', 'Maximum lobby reservations reached.');
+        const available = snapshot.keyedNames.filter(name => !snapshot.reservedNames.includes(name)).sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+        return available.length ? result('create', 'Replenish empty lobby capacity.', available[0]) : result('wait', 'No unused lobby identity has a saved key.');
+    }
+    if (occupied + empty > desired && empty > policy.spares && occupied + empty > policy.minimum) {
+        const candidates = members.filter(m => m.state === 'empty' && m.emptySince !== null && m.observedAt! - m.emptySince >= policy.emptyMinutes * 60_000)
+            .sort((a, b) => a.emptySince! - b.emptySince! || a.name.localeCompare(b.name, 'en', { numeric: true }));
+        if (candidates.length) return result('destroy', 'Surplus lobby has remained empty.', candidates[0].name);
+        return result('wait', 'Waiting for a continuous empty interval.');
+    }
+    return result('wait', empty < policy.spares ? 'Maximum reached; the empty spare target cannot be met.' : 'Empty spare target is satisfied.');
+}