@femtomc/mu-server 26.2.55 → 26.2.56

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/server.d.ts

@@ -1,16 +1,18 @@
+import { GenerationTelemetryRecorder, type ReloadableGenerationIdentity } from "@femtomc/mu-control-plane";
 import type { EventEnvelope, JsonlStore } from "@femtomc/mu-core";
 import { EventLog } from "@femtomc/mu-core/node";
 import { ForumStore } from "@femtomc/mu-forum";
 import { IssueStore } from "@femtomc/mu-issue";
-import { type MuConfig } from "./config.js";
 import { ControlPlaneActivitySupervisor } from "./activity_supervisor.js";
+import { type MuConfig } from "./config.js";
 import { type ControlPlaneConfig, type ControlPlaneHandle } from "./control_plane.js";
-import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 import { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
+import { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";
 type ControlPlaneReloader = (opts: {
     repoRoot: string;
     previous: ControlPlaneHandle | null;
     config: ControlPlaneConfig;
+    generation: ReloadableGenerationIdentity;
 }) => Promise<ControlPlaneHandle | null>;
 type ConfigReader = (repoRoot: string) => Promise<MuConfig>;
 type ConfigWriter = (repoRoot: string, config: MuConfig) => Promise<string>;
@@ -21,6 +23,7 @@ export type ServerOptions = {
     heartbeatScheduler?: ActivityHeartbeatScheduler;
     activitySupervisor?: ControlPlaneActivitySupervisor;
     controlPlaneReloader?: ControlPlaneReloader;
+    generationTelemetry?: GenerationTelemetryRecorder;
     config?: MuConfig;
     configReader?: ConfigReader;
     configWriter?: ConfigWriter;