@femtomc/mu-server 26.2.55 → 26.2.57

package/dist/cron_schedule.js

@@ -0,0 +1,383 @@
+const WEEKDAY_INDEX = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+};
+const DEFAULT_CRON_SEARCH_LIMIT_MINUTES = 366 * 24 * 60 * 2;
+const formatterCache = new Map();
+function defaultNowMs() {
+    return Date.now();
+}
+function isRecord(value) {
+    return typeof value === "object" && value != null && !Array.isArray(value);
+}
+function parseInteger(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            return null;
+        }
+        if (!/^-?\d+$/.test(trimmed)) {
+            return null;
+        }
+        const parsed = Number.parseInt(trimmed, 10);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function parseAbsoluteTimeMs(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (/^-?\d+$/.test(trimmed)) {
+        const parsed = Number.parseInt(trimmed, 10);
+        return Number.isFinite(parsed) ? Math.trunc(parsed) : null;
+    }
+    const explicitTz = /[zZ]$|[+-]\d{2}:?\d{2}$/.test(trimmed);
+    const normalized = explicitTz ? trimmed : `${trimmed}Z`;
+    const parsed = Date.parse(normalized);
+    if (!Number.isFinite(parsed)) {
+        return null;
+    }
+    return Math.trunc(parsed);
+}
+function resolveTimeZone(raw) {
+    if (raw == null) {
+        return null;
+    }
+    if (typeof raw !== "string") {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    try {
+        return new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).resolvedOptions().timeZone;
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeCronValue(value, max, wrapSunday) {
+    if (wrapSunday && value === max) {
+        return 0;
+    }
+    return value;
+}
+function addRangeValues(set, range, opts) {
+    if (range.step <= 0) {
+        return false;
+    }
+    if (range.start < opts.min || range.start > opts.max) {
+        return false;
+    }
+    if (range.end < opts.min || range.end > opts.max) {
+        return false;
+    }
+    if (range.start > range.end) {
+        return false;
+    }
+    for (let value = range.start; value <= range.end; value += range.step) {
+        set.add(normalizeCronValue(value, opts.max, opts.wrapSunday));
+    }
+    return true;
+}
+function parseCronField(rawValue, opts) {
+    if (typeof rawValue !== "string") {
+        return null;
+    }
+    const raw = rawValue.trim();
+    if (!raw) {
+        return null;
+    }
+    const wrapSunday = opts.wrapSunday === true;
+    const values = new Set();
+    const segments = raw.split(",");
+    for (const segmentRaw of segments) {
+        const segment = segmentRaw.trim();
+        if (!segment) {
+            return null;
+        }
+        const slashIndex = segment.indexOf("/");
+        const [base, stepRaw] = slashIndex >= 0
+            ? [segment.slice(0, slashIndex).trim(), segment.slice(slashIndex + 1).trim()]
+            : [segment, ""];
+        const parsedStep = slashIndex >= 0 ? parseInteger(stepRaw) : 1;
+        if (parsedStep == null || parsedStep <= 0) {
+            return null;
+        }
+        if (base === "*" || base.length === 0) {
+            if (!addRangeValues(values, { start: opts.min, end: opts.max, step: parsedStep }, { min: opts.min, max: opts.max, wrapSunday })) {
+                return null;
+            }
+            continue;
+        }
+        const dashIndex = base.indexOf("-");
+        if (dashIndex >= 0) {
+            const startRaw = base.slice(0, dashIndex).trim();
+            const endRaw = base.slice(dashIndex + 1).trim();
+            const start = parseInteger(startRaw);
+            const end = parseInteger(endRaw);
+            if (start == null || end == null) {
+                return null;
+            }
+            if (!addRangeValues(values, { start, end, step: parsedStep }, { min: opts.min, max: opts.max, wrapSunday })) {
+                return null;
+            }
+            continue;
+        }
+        const value = parseInteger(base);
+        if (value == null) {
+            return null;
+        }
+        if (slashIndex >= 0) {
+            if (!addRangeValues(values, { start: value, end: opts.max, step: parsedStep }, { min: opts.min, max: opts.max, wrapSunday })) {
+                return null;
+            }
+            continue;
+        }
+        if (value < opts.min || value > opts.max) {
+            return null;
+        }
+        values.add(normalizeCronValue(value, opts.max, wrapSunday));
+    }
+    const rangeSize = opts.max - opts.min + 1;
+    return {
+        any: values.size >= rangeSize,
+        values,
+    };
+}
+function parseCronExpression(expr) {
+    const trimmed = expr.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const parts = trimmed.split(/\s+/);
+    if (parts.length !== 5) {
+        return null;
+    }
+    const minute = parseCronField(parts[0], { min: 0, max: 59 });
+    const hour = parseCronField(parts[1], { min: 0, max: 23 });
+    const dayOfMonth = parseCronField(parts[2], { min: 1, max: 31 });
+    const month = parseCronField(parts[3], { min: 1, max: 12 });
+    const dayOfWeek = parseCronField(parts[4], { min: 0, max: 7, wrapSunday: true });
+    if (!minute || !hour || !dayOfMonth || !month || !dayOfWeek) {
+        return null;
+    }
+    return {
+        minute,
+        hour,
+        dayOfMonth,
+        month,
+        dayOfWeek,
+    };
+}
+function getFormatter(timeZone) {
+    const cached = formatterCache.get(timeZone);
+    if (cached) {
+        return cached;
+    }
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hour12: false,
+        hourCycle: "h23",
+        weekday: "short",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+    formatterCache.set(timeZone, formatter);
+    return formatter;
+}
+function getCronDateParts(timestampMs, timeZone) {
+    const formatter = getFormatter(timeZone);
+    let minute = -1;
+    let hour = -1;
+    let dayOfMonth = -1;
+    let month = -1;
+    let dayOfWeek = -1;
+    for (const part of formatter.formatToParts(new Date(timestampMs))) {
+        switch (part.type) {
+            case "minute":
+                minute = Number.parseInt(part.value, 10);
+                break;
+            case "hour":
+                hour = Number.parseInt(part.value, 10);
+                if (hour === 24) {
+                    hour = 0;
+                }
+                break;
+            case "day":
+                dayOfMonth = Number.parseInt(part.value, 10);
+                break;
+            case "month":
+                month = Number.parseInt(part.value, 10);
+                break;
+            case "weekday":
+                dayOfWeek = WEEKDAY_INDEX[part.value] ?? -1;
+                break;
+            default:
+                break;
+        }
+    }
+    if (!Number.isInteger(minute) ||
+        !Number.isInteger(hour) ||
+        !Number.isInteger(dayOfMonth) ||
+        !Number.isInteger(month) ||
+        !Number.isInteger(dayOfWeek)) {
+        return null;
+    }
+    return {
+        minute,
+        hour,
+        dayOfMonth,
+        month,
+        dayOfWeek,
+    };
+}
+function fieldMatches(field, value) {
+    if (field.any) {
+        return true;
+    }
+    return field.values.has(value);
+}
+function dayMatches(parsed, parts) {
+    const domMatches = fieldMatches(parsed.dayOfMonth, parts.dayOfMonth);
+    const dowMatches = fieldMatches(parsed.dayOfWeek, parts.dayOfWeek);
+    if (parsed.dayOfMonth.any && parsed.dayOfWeek.any) {
+        return true;
+    }
+    if (parsed.dayOfMonth.any) {
+        return dowMatches;
+    }
+    if (parsed.dayOfWeek.any) {
+        return domMatches;
+    }
+    return domMatches || dowMatches;
+}
+function resolveCronTimeZone(tz) {
+    if (tz) {
+        return tz;
+    }
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+function computeNextCronRunAtMs(parsed, nowMs, timeZone, searchLimitMinutes = DEFAULT_CRON_SEARCH_LIMIT_MINUTES) {
+    const startMinute = Math.floor(nowMs / 60_000) * 60_000 + 60_000;
+    for (let offset = 0; offset < searchLimitMinutes; offset += 1) {
+        const candidate = startMinute + offset * 60_000;
+        const parts = getCronDateParts(candidate, timeZone);
+        if (!parts) {
+            continue;
+        }
+        if (!fieldMatches(parsed.minute, parts.minute)) {
+            continue;
+        }
+        if (!fieldMatches(parsed.hour, parts.hour)) {
+            continue;
+        }
+        if (!fieldMatches(parsed.month, parts.month)) {
+            continue;
+        }
+        if (!dayMatches(parsed, parts)) {
+            continue;
+        }
+        return candidate;
+    }
+    return null;
+}
+export function normalizeCronSchedule(input, opts = {}) {
+    if (!isRecord(input)) {
+        return null;
+    }
+    const nowMs = Math.trunc(opts.nowMs ?? defaultNowMs());
+    const kindRaw = typeof input.kind === "string" ? input.kind.trim().toLowerCase() : "";
+    const inferredKind = kindRaw === "at" || kindRaw === "every" || kindRaw === "cron"
+        ? kindRaw
+        : input.at_ms != null || input.at != null
+            ? "at"
+            : input.every_ms != null || input.everyMs != null
+                ? "every"
+                : input.expr != null
+                    ? "cron"
+                    : "";
+    if (inferredKind === "at") {
+        const atMs = parseAbsoluteTimeMs(input.at_ms ?? input.at);
+        if (atMs == null || atMs <= 0) {
+            return null;
+        }
+        return {
+            kind: "at",
+            at_ms: atMs,
+        };
+    }
+    if (inferredKind === "every") {
+        const everyMs = parseInteger(input.every_ms ?? input.everyMs);
+        if (everyMs == null || everyMs <= 0) {
+            return null;
+        }
+        const anchorRaw = parseInteger(input.anchor_ms ?? input.anchorMs);
+        const fallbackAnchor = Math.trunc(opts.defaultEveryAnchorMs ?? nowMs);
+        const anchorMs = anchorRaw != null && anchorRaw >= 0 ? anchorRaw : Math.max(0, fallbackAnchor);
+        return {
+            kind: "every",
+            every_ms: everyMs,
+            anchor_ms: anchorMs,
+        };
+    }
+    if (inferredKind === "cron") {
+        const expr = typeof input.expr === "string" ? input.expr.trim() : "";
+        if (!expr) {
+            return null;
+        }
+        if (!parseCronExpression(expr)) {
+            return null;
+        }
+        const tzRaw = resolveTimeZone(input.tz);
+        if (input.tz != null && tzRaw == null) {
+            return null;
+        }
+        return {
+            kind: "cron",
+            expr,
+            tz: tzRaw,
+        };
+    }
+    return null;
+}
+export function computeNextScheduleRunAtMs(schedule, nowMsRaw) {
+    const nowMs = Math.trunc(nowMsRaw);
+    if (schedule.kind === "at") {
+        return schedule.at_ms;
+    }
+    if (schedule.kind === "every") {
+        const everyMs = Math.max(1, Math.trunc(schedule.every_ms));
+        const anchorMs = Math.max(0, Math.trunc(schedule.anchor_ms));
+        if (nowMs < anchorMs) {
+            return anchorMs;
+        }
+        const elapsed = nowMs - anchorMs;
+        const steps = Math.floor(elapsed / everyMs) + 1;
+        return anchorMs + steps * everyMs;
+    }
+    const parsed = parseCronExpression(schedule.expr);
+    if (!parsed) {
+        return null;
+    }
+    return computeNextCronRunAtMs(parsed, nowMs, resolveCronTimeZone(schedule.tz));
+}

package/dist/cron_timer.d.ts

@@ -0,0 +1,21 @@
+export type CronTimerSnapshot = {
+    program_id: string;
+    due_at_ms: number;
+};
+export type CronTimerRegistryOpts = {
+    nowMs?: () => number;
+    maxDelayMs?: number;
+};
+export declare class CronTimerRegistry {
+    #private;
+    constructor(opts?: CronTimerRegistryOpts);
+    arm(opts: {
+        programId: string;
+        dueAtMs: number;
+        onDue: () => void | Promise<void>;
+    }): void;
+    disarm(programIdRaw: string): boolean;
+    dueAt(programIdRaw: string): number | null;
+    list(): CronTimerSnapshot[];
+    stop(): void;
+}

package/dist/cron_timer.js

@@ -0,0 +1,109 @@
+const DEFAULT_MAX_DELAY_MS = 60_000;
+function defaultNowMs() {
+    return Date.now();
+}
+export class CronTimerRegistry {
+    #entries = new Map();
+    #nowMs;
+    #maxDelayMs;
+    #token = 0;
+    constructor(opts = {}) {
+        this.#nowMs = opts.nowMs ?? defaultNowMs;
+        this.#maxDelayMs = Math.max(1_000, Math.trunc(opts.maxDelayMs ?? DEFAULT_MAX_DELAY_MS));
+    }
+    #clearTimer(entry) {
+        if (entry.handle) {
+            clearTimeout(entry.handle);
+        }
+        entry.handle = null;
+    }
+    #arm(entry) {
+        this.#clearTimer(entry);
+        const nowMs = Math.trunc(this.#nowMs());
+        const remainingMs = Math.max(0, entry.dueAtMs - nowMs);
+        const delayMs = Math.min(this.#maxDelayMs, remainingMs);
+        const token = ++this.#token;
+        entry.token = token;
+        entry.handle = setTimeout(() => {
+            void this.#onTimer(entry.programId, token);
+        }, delayMs);
+        entry.handle.unref?.();
+    }
+    async #onTimer(programId, token) {
+        const entry = this.#entries.get(programId);
+        if (!entry || entry.token !== token) {
+            return;
+        }
+        const nowMs = Math.trunc(this.#nowMs());
+        if (nowMs < entry.dueAtMs) {
+            this.#arm(entry);
+            return;
+        }
+        this.#clearTimer(entry);
+        try {
+            await entry.onDue();
+        }
+        catch {
+            // Best effort callback execution.
+        }
+    }
+    arm(opts) {
+        const programId = opts.programId.trim();
+        if (!programId) {
+            return;
+        }
+        const dueAtMs = Math.max(0, Math.trunc(opts.dueAtMs));
+        const existing = this.#entries.get(programId);
+        const entry = existing ??
+            {
+                programId,
+                dueAtMs,
+                handle: null,
+                token: 0,
+                onDue: opts.onDue,
+            };
+        entry.dueAtMs = dueAtMs;
+        entry.onDue = opts.onDue;
+        this.#entries.set(programId, entry);
+        this.#arm(entry);
+    }
+    disarm(programIdRaw) {
+        const programId = programIdRaw.trim();
+        if (!programId) {
+            return false;
+        }
+        const entry = this.#entries.get(programId);
+        if (!entry) {
+            return false;
+        }
+        this.#clearTimer(entry);
+        this.#entries.delete(programId);
+        return true;
+    }
+    dueAt(programIdRaw) {
+        const programId = programIdRaw.trim();
+        if (!programId) {
+            return null;
+        }
+        return this.#entries.get(programId)?.dueAtMs ?? null;
+    }
+    list() {
+        return [...this.#entries.values()]
+            .map((entry) => ({
+            program_id: entry.programId,
+            due_at_ms: entry.dueAtMs,
+        }))
+            .sort((a, b) => {
+            if (a.due_at_ms !== b.due_at_ms) {
+                return a.due_at_ms - b.due_at_ms;
+            }
+            return a.program_id.localeCompare(b.program_id);
+        });
+    }
+    stop() {
+        for (const entry of this.#entries.values()) {
+            this.#clearTimer(entry);
+        }
+        this.#entries.clear();
+    }
+}

package/dist/generation_supervisor.d.ts

@@ -0,0 +1,21 @@
+import type { GenerationReloadAttempt, GenerationSupervisorSnapshot, ReloadableGenerationIdentity, ReloadLifecycleReason } from "@femtomc/mu-control-plane";
+export type ControlPlaneGenerationSupervisorOpts = {
+    supervisorId?: string;
+    nowMs?: () => number;
+    initialGeneration?: ReloadableGenerationIdentity | null;
+};
+export type BeginGenerationReloadResult = {
+    attempt: GenerationReloadAttempt;
+    coalesced: boolean;
+};
+export declare class ControlPlaneGenerationSupervisor {
+    #private;
+    constructor(opts?: ControlPlaneGenerationSupervisorOpts);
+    beginReload(reason: ReloadLifecycleReason): BeginGenerationReloadResult;
+    markSwapInstalled(attemptId: string): boolean;
+    rollbackSwapInstalled(attemptId: string): boolean;
+    finishReload(attemptId: string, outcome: "success" | "failure"): boolean;
+    activeGeneration(): ReloadableGenerationIdentity | null;
+    pendingReload(): GenerationReloadAttempt | null;
+    snapshot(): GenerationSupervisorSnapshot;
+}

package/dist/generation_supervisor.js

@@ -0,0 +1,107 @@
+function cloneGeneration(generation) {
+    if (!generation) {
+        return null;
+    }
+    return { ...generation };
+}
+function cloneAttempt(attempt) {
+    if (!attempt) {
+        return null;
+    }
+    return {
+        ...attempt,
+        from_generation: cloneGeneration(attempt.from_generation),
+        to_generation: { ...attempt.to_generation },
+    };
+}
+export class ControlPlaneGenerationSupervisor {
+    #supervisorId;
+    #nowMs;
+    #generationSeq;
+    #attemptSeq = 0;
+    #activeGeneration;
+    #pendingReload = null;
+    #lastReload = null;
+    constructor(opts = {}) {
+        this.#supervisorId = opts.supervisorId?.trim() || "control-plane";
+        this.#nowMs = opts.nowMs ?? Date.now;
+        this.#activeGeneration = cloneGeneration(opts.initialGeneration ?? null);
+        this.#generationSeq = this.#activeGeneration?.generation_seq ?? -1;
+    }
+    #nextGeneration() {
+        const nextSeq = this.#generationSeq + 1;
+        return {
+            generation_id: `${this.#supervisorId}-gen-${nextSeq}`,
+            generation_seq: nextSeq,
+        };
+    }
+    beginReload(reason) {
+        if (this.#pendingReload) {
+            return {
+                attempt: cloneAttempt(this.#pendingReload),
+                coalesced: true,
+            };
+        }
+        this.#attemptSeq += 1;
+        const nowMs = Math.trunc(this.#nowMs());
+        const attempt = {
+            attempt_id: `${this.#supervisorId}-reload-${this.#attemptSeq.toString(36)}`,
+            reason,
+            state: "planned",
+            requested_at_ms: nowMs,
+            swapped_at_ms: null,
+            finished_at_ms: null,
+            from_generation: cloneGeneration(this.#activeGeneration),
+            to_generation: this.#nextGeneration(),
+        };
+        this.#pendingReload = attempt;
+        return {
+            attempt: cloneAttempt(attempt),
+            coalesced: false,
+        };
+    }
+    markSwapInstalled(attemptId) {
+        if (!this.#pendingReload || this.#pendingReload.attempt_id !== attemptId) {
+            return false;
+        }
+        this.#pendingReload.state = "swapped";
+        this.#pendingReload.swapped_at_ms = Math.trunc(this.#nowMs());
+        this.#activeGeneration = { ...this.#pendingReload.to_generation };
+        this.#generationSeq = this.#pendingReload.to_generation.generation_seq;
+        return true;
+    }
+    rollbackSwapInstalled(attemptId) {
+        if (!this.#pendingReload ||
+            this.#pendingReload.attempt_id !== attemptId ||
+            this.#pendingReload.swapped_at_ms == null) {
+            return false;
+        }
+        this.#activeGeneration = cloneGeneration(this.#pendingReload.from_generation);
+        this.#generationSeq = this.#activeGeneration?.generation_seq ?? -1;
+        return true;
+    }
+    finishReload(attemptId, outcome) {
+        if (!this.#pendingReload || this.#pendingReload.attempt_id !== attemptId) {
+            return false;
+        }
+        this.#pendingReload.state = outcome === "success" ? "completed" : "failed";
+        this.#pendingReload.finished_at_ms = Math.trunc(this.#nowMs());
+        this.#lastReload = cloneAttempt(this.#pendingReload);
+        this.#pendingReload = null;
+        return true;
+    }
+    activeGeneration() {
+        return cloneGeneration(this.#activeGeneration);
+    }
+    pendingReload() {
+        return cloneAttempt(this.#pendingReload);
+    }
+    snapshot() {
+        return {
+            supervisor_id: this.#supervisorId,
+            active_generation: cloneGeneration(this.#activeGeneration),
+            pending_reload: cloneAttempt(this.#pendingReload),
+            last_reload: cloneAttempt(this.#lastReload),
+        };
+    }
+}

package/dist/heartbeat_programs.d.ts

@@ -1,5 +1,5 @@
 import type { JsonlStore } from "@femtomc/mu-core";
-import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
+import type { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 export type HeartbeatProgramTarget = {
     kind: "run";
     job_id: string | null;
@@ -8,6 +8,7 @@ export type HeartbeatProgramTarget = {
     kind: "activity";
     activity_id: string;
 };
+export type HeartbeatProgramWakeMode = "immediate" | "next_heartbeat";
 export type HeartbeatProgramSnapshot = {
     v: 1;
     program_id: string;
@@ -15,6 +16,7 @@ export type HeartbeatProgramSnapshot = {
     enabled: boolean;
     every_ms: number;
     reason: string;
+    wake_mode: HeartbeatProgramWakeMode;
     target: HeartbeatProgramTarget;
     metadata: Record<string, unknown>;
     created_at_ms: number;
@@ -45,6 +47,7 @@ export type HeartbeatProgramRegistryOpts = {
         jobId?: string | null;
         rootIssueId?: string | null;
         reason?: string | null;
+        wakeMode?: HeartbeatProgramWakeMode;
     }) => Promise<{
         ok: boolean;
         reason: "not_found" | "not_running" | "missing_target" | null;
@@ -72,6 +75,7 @@ export declare class HeartbeatProgramRegistry {
         target: HeartbeatProgramTarget;
         everyMs?: number;
         reason?: string;
+        wakeMode?: HeartbeatProgramWakeMode;
         enabled?: boolean;
         metadata?: Record<string, unknown>;
     }): Promise<HeartbeatProgramSnapshot>;
@@ -80,6 +84,7 @@ export declare class HeartbeatProgramRegistry {
         title?: string;
         everyMs?: number;
         reason?: string;
+        wakeMode?: HeartbeatProgramWakeMode;
         enabled?: boolean;
         target?: HeartbeatProgramTarget;
         metadata?: Record<string, unknown>;