@femtomc/mu-server 26.2.72 → 26.2.74

package/dist/heartbeat_programs.js

@@ -4,43 +4,6 @@ const HEARTBEAT_PROGRAMS_FILENAME = "heartbeats.jsonl";
 function defaultNowMs() {
     return Date.now();
 }
-function normalizeTarget(input) {
-    if (!input || typeof input !== "object" || Array.isArray(input)) {
-        return null;
-    }
-    const record = input;
-    const kind = typeof record.kind === "string" ? record.kind.trim().toLowerCase() : "";
-    if (kind === "run") {
-        const jobId = typeof record.job_id === "string" ? record.job_id.trim() : "";
-        const rootIssueId = typeof record.root_issue_id === "string" ? record.root_issue_id.trim() : "";
-        if (!jobId && !rootIssueId) {
-            return null;
-        }
-        return {
-            kind: "run",
-            job_id: jobId || null,
-            root_issue_id: rootIssueId || null,
-        };
-    }
-    if (kind === "activity") {
-        const activityId = typeof record.activity_id === "string" ? record.activity_id.trim() : "";
-        if (!activityId) {
-            return null;
-        }
-        return {
-            kind: "activity",
-            activity_id: activityId,
-        };
-    }
-    return null;
-}
-function normalizeWakeMode(value) {
-    if (typeof value !== "string") {
-        return "immediate";
-    }
-    const normalized = value.trim().toLowerCase().replaceAll("-", "_");
-    return normalized === "next_heartbeat" ? "next_heartbeat" : "immediate";
-}
 function sanitizeMetadata(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return {};
@@ -54,8 +17,7 @@ function normalizeProgram(row) {
     const record = row;
     const programId = typeof record.program_id === "string" ? record.program_id.trim() : "";
     const title = typeof record.title === "string" ? record.title.trim() : "";
-    const target = normalizeTarget(record.target);
-    if (!programId || !title || !target) {
+    if (!programId || !title) {
         return null;
     }
     const everyMsRaw = record.every_ms;
@@ -70,14 +32,8 @@ function normalizeProgram(row) {
         ? Math.trunc(record.last_triggered_at_ms)
         : null;
     const lastResultRaw = typeof record.last_result === "string" ? record.last_result.trim().toLowerCase() : null;
-    const lastResult = lastResultRaw === "ok" ||
-        lastResultRaw === "not_found" ||
-        lastResultRaw === "not_running" ||
-        lastResultRaw === "failed"
-        ? lastResultRaw
-        : null;
+    const lastResult = lastResultRaw === "ok" || lastResultRaw === "coalesced" || lastResultRaw === "failed" ? lastResultRaw : null;
     const reason = typeof record.reason === "string" && record.reason.trim().length > 0 ? record.reason.trim() : "scheduled";
-    const wakeMode = normalizeWakeMode(record.wake_mode);
     return {
         v: 1,
         program_id: programId,
@@ -85,8 +41,6 @@ function normalizeProgram(row) {
         enabled: record.enabled !== false,
         every_ms: everyMs,
         reason,
-        wake_mode: wakeMode,
-        target,
         metadata: sanitizeMetadata(record.metadata),
         created_at_ms: createdAt,
         updated_at_ms: updatedAt,
@@ -106,16 +60,14 @@ function sortPrograms(programs) {
 export class HeartbeatProgramRegistry {
     #store;
     #heartbeatScheduler;
-    #runHeartbeat;
-    #activityHeartbeat;
+    #dispatchWake;
     #onTickEvent;
     #nowMs;
     #programs = new Map();
     #loaded = null;
     constructor(opts) {
         this.#heartbeatScheduler = opts.heartbeatScheduler;
-        this.#runHeartbeat = opts.runHeartbeat;
-        this.#activityHeartbeat = opts.activityHeartbeat;
+        this.#dispatchWake = opts.dispatchWake;
         this.#onTickEvent = opts.onTickEvent;
         this.#nowMs = opts.nowMs ?? defaultNowMs;
         this.#store =
@@ -128,7 +80,6 @@ export class HeartbeatProgramRegistry {
     #snapshot(program) {
         return {
             ...program,
-            target: program.target.kind === "run" ? { ...program.target } : { ...program.target },
             metadata: { ...program.metadata },
         };
     }
@@ -187,50 +138,38 @@ export class HeartbeatProgramRegistry {
         const nowMs = Math.trunc(this.#nowMs());
         program.last_triggered_at_ms = nowMs;
         program.updated_at_ms = nowMs;
-        let heartbeatResult;
+        let tickResult;
         let eventStatus = "ok";
         let eventReason = heartbeatReason;
-        let eventMessage = `heartbeat program tick: ${program.title}`;
+        let eventMessage = `heartbeat program dispatched wake: ${program.title}`;
         try {
-            const result = program.target.kind === "run"
-                ? await this.#runHeartbeat({
-                    jobId: program.target.job_id,
-                    rootIssueId: program.target.root_issue_id,
-                    reason: heartbeatReason,
-                    wakeMode: program.wake_mode,
-                })
-                : await this.#activityHeartbeat({
-                    activityId: program.target.activity_id,
-                    reason: heartbeatReason,
-                });
-            if (result.ok) {
+            const result = await this.#dispatchWake({
+                programId: program.program_id,
+                title: program.title,
+                reason: heartbeatReason,
+                metadata: { ...program.metadata },
+                triggeredAtMs: nowMs,
+            });
+            if (result.status === "ok") {
                 program.last_result = "ok";
                 program.last_error = null;
-                heartbeatResult = { status: "ran" };
+                tickResult = { status: "ran" };
             }
-            else if (result.reason === "not_running") {
-                program.last_result = "not_running";
+            else if (result.status === "coalesced") {
+                program.last_result = "coalesced";
                 program.last_error = null;
-                eventStatus = "not_running";
-                eventReason = result.reason;
-                eventMessage = `heartbeat program skipped (not running): ${program.title}`;
-                heartbeatResult = { status: "skipped", reason: "not_running" };
-            }
-            else if (result.reason === "not_found") {
-                program.last_result = "not_found";
-                program.last_error = null;
-                eventStatus = "not_found";
-                eventReason = result.reason;
-                eventMessage = `heartbeat program skipped (not found): ${program.title}`;
-                heartbeatResult = { status: "skipped", reason: "not_found" };
+                eventStatus = "coalesced";
+                eventReason = result.reason ?? "coalesced";
+                eventMessage = `heartbeat program coalesced wake: ${program.title}`;
+                tickResult = { status: "skipped", reason: "coalesced" };
             }
             else {
                 program.last_result = "failed";
-                program.last_error = result.reason ?? "heartbeat_program_tick_failed";
+                program.last_error = result.reason;
                 eventStatus = "failed";
-                eventReason = program.last_error;
+                eventReason = result.reason;
                 eventMessage = `heartbeat program failed: ${program.title}`;
-                heartbeatResult = { status: "failed", reason: program.last_error };
+                tickResult = { status: "failed", reason: result.reason };
             }
         }
         catch (err) {
@@ -239,23 +178,7 @@ export class HeartbeatProgramRegistry {
             eventStatus = "failed";
             eventReason = program.last_error;
             eventMessage = `heartbeat program failed: ${program.title}`;
-            heartbeatResult = { status: "failed", reason: program.last_error };
-        }
-        const shouldAutoDisableOnTerminal = program.target.kind === "run" &&
-            program.metadata.auto_disable_on_terminal === true &&
-            heartbeatResult.status === "skipped" &&
-            (heartbeatResult.reason === "not_running" || heartbeatResult.reason === "not_found");
-        if (shouldAutoDisableOnTerminal) {
-            program.enabled = false;
-            program.every_ms = 0;
-            program.updated_at_ms = Math.trunc(this.#nowMs());
-            program.metadata = {
-                ...program.metadata,
-                auto_disabled_at_ms: Math.trunc(this.#nowMs()),
-                auto_disabled_reason: heartbeatResult.status === "skipped" ? (heartbeatResult.reason ?? null) : null,
-            };
-            this.#heartbeatScheduler.unregister(this.#scheduleId(program.program_id));
-            eventMessage = `${eventMessage} (auto-disabled)`;
+            tickResult = { status: "failed", reason: program.last_error };
         }
         await this.#persist();
         await this.#emitTickEvent({
@@ -268,7 +191,7 @@ export class HeartbeatProgramRegistry {
         }).catch(() => {
             // best effort only
         });
-        return heartbeatResult;
+        return tickResult;
     }
     async list(opts = {}) {
         await this.#ensureLoaded();
@@ -278,9 +201,6 @@ export class HeartbeatProgramRegistry {
             if (typeof opts.enabled === "boolean" && program.enabled !== opts.enabled) {
                 return false;
             }
-            if (opts.targetKind && program.target.kind !== opts.targetKind) {
-                return false;
-            }
             return true;
         })
             .slice(0, limit)
@@ -297,10 +217,6 @@ export class HeartbeatProgramRegistry {
         if (!title) {
             throw new Error("heartbeat_program_title_required");
         }
-        const target = normalizeTarget(opts.target);
-        if (!target) {
-            throw new Error("heartbeat_program_invalid_target");
-        }
         const nowMs = Math.trunc(this.#nowMs());
         const program = {
             v: 1,
@@ -311,8 +227,6 @@ export class HeartbeatProgramRegistry {
                 ? Math.max(0, Math.trunc(opts.everyMs))
                 : 15_000,
             reason: opts.reason?.trim() || "scheduled",
-            wake_mode: normalizeWakeMode(opts.wakeMode),
-            target,
             metadata: sanitizeMetadata(opts.metadata),
             created_at_ms: nowMs,
             updated_at_ms: nowMs,
@@ -344,19 +258,9 @@ export class HeartbeatProgramRegistry {
         if (typeof opts.reason === "string") {
             program.reason = opts.reason.trim() || "scheduled";
         }
-        if (typeof opts.wakeMode === "string") {
-            program.wake_mode = normalizeWakeMode(opts.wakeMode);
-        }
         if (typeof opts.enabled === "boolean") {
             program.enabled = opts.enabled;
         }
-        if (opts.target) {
-            const target = normalizeTarget(opts.target);
-            if (!target) {
-                return { ok: false, reason: "invalid_target", program: this.#snapshot(program) };
-            }
-            program.target = target;
-        }
         if (opts.metadata) {
             program.metadata = sanitizeMetadata(opts.metadata);
         }

package/dist/index.d.ts

@@ -7,13 +7,13 @@ export { DEFAULT_INTER_ROOT_QUEUE_POLICY, normalizeInterRootQueuePolicy, ORCHEST
 export type { DurableRunQueueClaimOpts, DurableRunQueueEnqueueOpts, DurableRunQueueOpts, DurableRunQueueSnapshot, DurableRunQueueState, DurableRunQueueTransitionOpts, RunQueueReconcilePlan, } from "./run_queue.js";
 export { DurableRunQueue, queueStatesForRunStatusFilter, reconcileRunQueue, RUN_QUEUE_RECONCILE_INVARIANTS, runQueuePath, runSnapshotFromQueueSnapshot, runStatusFromQueueState, } from "./run_queue.js";
 export { bootstrapControlPlane, detectAdapters } from "./control_plane.js";
-export type { CronProgramLifecycleAction, CronProgramLifecycleEvent, CronProgramOperationResult, CronProgramRegistryOpts, CronProgramSnapshot, CronProgramStatusSnapshot, CronProgramTarget, CronProgramTickEvent, CronProgramWakeMode, } from "./cron_programs.js";
+export type { CronProgramDispatchResult, CronProgramLifecycleAction, CronProgramLifecycleEvent, CronProgramOperationResult, CronProgramRegistryOpts, CronProgramSnapshot, CronProgramStatusSnapshot, CronProgramTickEvent, } from "./cron_programs.js";
 export { CronProgramRegistry } from "./cron_programs.js";
 export type { CronProgramSchedule as CronSchedule, CronProgramSchedule } from "./cron_schedule.js";
 export { computeNextScheduleRunAtMs, normalizeCronSchedule } from "./cron_schedule.js";
 export type { CronTimerRegistryOpts, CronTimerSnapshot } from "./cron_timer.js";
 export { CronTimerRegistry } from "./cron_timer.js";
-export type { HeartbeatProgramOperationResult, HeartbeatProgramRegistryOpts, HeartbeatProgramSnapshot, HeartbeatProgramTarget, HeartbeatProgramTickEvent, HeartbeatProgramWakeMode, } from "./heartbeat_programs.js";
+export type { HeartbeatProgramDispatchResult, HeartbeatProgramOperationResult, HeartbeatProgramRegistryOpts, HeartbeatProgramSnapshot, HeartbeatProgramTickEvent, } from "./heartbeat_programs.js";
 export { HeartbeatProgramRegistry } from "./heartbeat_programs.js";
 export type { ActivityHeartbeatSchedulerOpts, HeartbeatRunResult, HeartbeatTickHandler, } from "./heartbeat_scheduler.js";
 export { ActivityHeartbeatScheduler } from "./heartbeat_scheduler.js";

package/dist/orchestration_queue.d.ts

@@ -0,0 +1,44 @@
+export type OrchestrationQueueState = "queued" | "active" | "waiting_review" | "refining" | "done" | "failed" | "cancelled";
+/**
+ * Inter-root scheduler policy knob for durable queue drain.
+ * - sequential: exactly one active root (`max_active_roots=1`)
+ * - parallel: bounded fanout (`max_active_roots>=1`)
+ */
+export type InterRootQueuePolicy = {
+    mode: "sequential";
+    max_active_roots: 1;
+} | {
+    mode: "parallel";
+    max_active_roots: number;
+};
+export declare const DEFAULT_INTER_ROOT_QUEUE_POLICY: InterRootQueuePolicy;
+export declare function normalizeInterRootQueuePolicy(policy: InterRootQueuePolicy | null | undefined): InterRootQueuePolicy;
+/**
+ * Allowed queue transitions. Queue tests should enforce this table exactly.
+ */
+export declare const ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS: Record<OrchestrationQueueState, readonly OrchestrationQueueState[]>;
+export declare const ORCHESTRATION_QUEUE_INVARIANTS: readonly ["ORCH-QUEUE-001: Queue writes are durable before acknowledging enqueue/start/resume requests.", "ORCH-QUEUE-002: Queue dispatch must claim exactly one active item at a time per root slot.", "ORCH-QUEUE-003: Terminal states (done|failed|cancelled) are immutable.", "ORCH-QUEUE-004: Review path is active -> waiting_review -> (done | refining).", "ORCH-QUEUE-005: Refinement re-enters execution only via refining -> queued.", "ORCH-QUEUE-006: sequential policy permits <=1 active root; parallel permits <=max_active_roots active roots."];
+export type InterRootQueueSnapshot = {
+    queue_id: string;
+    root_issue_id: string | null;
+    state: OrchestrationQueueState;
+    job_id: string | null;
+    created_at_ms: number;
+};
+export type InterRootQueueReconcilePlan = {
+    policy: InterRootQueuePolicy;
+    max_active_roots: number;
+    active_root_count: number;
+    available_root_slots: number;
+    activate_queue_ids: string[];
+    launch_queue_ids: string[];
+};
+export declare const INTER_ROOT_QUEUE_RECONCILE_INVARIANTS: readonly ["ORCH-INTER-ROOT-RECON-001: one queue snapshot + policy yields one deterministic activation/launch plan.", "ORCH-INTER-ROOT-RECON-002: activation order is FIFO (`created_at_ms`, then `queue_id`) with per-root slot dedupe.", "ORCH-INTER-ROOT-RECON-003: sequential policy admits <=1 occupied root; parallel admits <=max_active_roots roots.", "ORCH-INTER-ROOT-RECON-004: launch candidates are active rows without bound job ids, one launch per root slot."];
+/**
+ * Deterministic inter-root queue reconcile primitive.
+ *
+ * Computes queue activation/launch intentions from durable queue state and policy. The caller is
+ * responsible for performing side effects (claim, launch, bind, transition) and reconciling again
+ * against refreshed queue/runtime snapshots.
+ */
+export declare function reconcileInterRootQueue<Row extends InterRootQueueSnapshot>(rows: readonly Row[], policy: InterRootQueuePolicy): InterRootQueueReconcilePlan;

package/dist/orchestration_queue.js

@@ -0,0 +1,111 @@
+export const DEFAULT_INTER_ROOT_QUEUE_POLICY = {
+    mode: "sequential",
+    max_active_roots: 1,
+};
+export function normalizeInterRootQueuePolicy(policy) {
+    if (!policy) {
+        return DEFAULT_INTER_ROOT_QUEUE_POLICY;
+    }
+    if (policy.mode === "parallel") {
+        return {
+            mode: "parallel",
+            max_active_roots: Math.max(1, Math.trunc(policy.max_active_roots)),
+        };
+    }
+    return DEFAULT_INTER_ROOT_QUEUE_POLICY;
+}
+/**
+ * Allowed queue transitions. Queue tests should enforce this table exactly.
+ */
+export const ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS = {
+    queued: ["active", "cancelled"],
+    active: ["waiting_review", "done", "failed", "cancelled"],
+    waiting_review: ["refining", "done", "failed", "cancelled"],
+    refining: ["queued", "failed", "cancelled"],
+    done: [],
+    failed: [],
+    cancelled: [],
+};
+export const ORCHESTRATION_QUEUE_INVARIANTS = [
+    "ORCH-QUEUE-001: Queue writes are durable before acknowledging enqueue/start/resume requests.",
+    "ORCH-QUEUE-002: Queue dispatch must claim exactly one active item at a time per root slot.",
+    "ORCH-QUEUE-003: Terminal states (done|failed|cancelled) are immutable.",
+    "ORCH-QUEUE-004: Review path is active -> waiting_review -> (done | refining).",
+    "ORCH-QUEUE-005: Refinement re-enters execution only via refining -> queued.",
+    "ORCH-QUEUE-006: sequential policy permits <=1 active root; parallel permits <=max_active_roots active roots.",
+];
+const INTER_ROOT_OCCUPIED_STATES = new Set(["active", "waiting_review", "refining"]);
+export const INTER_ROOT_QUEUE_RECONCILE_INVARIANTS = [
+    "ORCH-INTER-ROOT-RECON-001: one queue snapshot + policy yields one deterministic activation/launch plan.",
+    "ORCH-INTER-ROOT-RECON-002: activation order is FIFO (`created_at_ms`, then `queue_id`) with per-root slot dedupe.",
+    "ORCH-INTER-ROOT-RECON-003: sequential policy admits <=1 occupied root; parallel admits <=max_active_roots roots.",
+    "ORCH-INTER-ROOT-RECON-004: launch candidates are active rows without bound job ids, one launch per root slot.",
+];
+function stableCompare(a, b) {
+    if (a.created_at_ms !== b.created_at_ms) {
+        return a.created_at_ms - b.created_at_ms;
+    }
+    return a.queue_id.localeCompare(b.queue_id);
+}
+function normalizeMaxActiveRoots(policy) {
+    if (policy.mode === "parallel") {
+        return Math.max(1, Math.trunc(policy.max_active_roots));
+    }
+    return 1;
+}
+function queueRootSlotKey(row) {
+    return row.root_issue_id ? `root:${row.root_issue_id}` : `queue:${row.queue_id}`;
+}
+/**
+ * Deterministic inter-root queue reconcile primitive.
+ *
+ * Computes queue activation/launch intentions from durable queue state and policy. The caller is
+ * responsible for performing side effects (claim, launch, bind, transition) and reconciling again
+ * against refreshed queue/runtime snapshots.
+ */
+export function reconcileInterRootQueue(rows, policy) {
+    const sorted = [...rows].sort(stableCompare);
+    const maxActiveRoots = normalizeMaxActiveRoots(policy);
+    const occupiedRoots = new Set();
+    const launchRoots = new Set();
+    const launchQueueIds = [];
+    for (const row of sorted) {
+        if (!INTER_ROOT_OCCUPIED_STATES.has(row.state)) {
+            continue;
+        }
+        const slotKey = queueRootSlotKey(row);
+        occupiedRoots.add(slotKey);
+        if (row.state !== "active" || row.job_id != null || launchRoots.has(slotKey)) {
+            continue;
+        }
+        launchRoots.add(slotKey);
+        launchQueueIds.push(row.queue_id);
+    }
+    const availableRootSlots = Math.max(0, maxActiveRoots - occupiedRoots.size);
+    const claimedRoots = new Set();
+    const activateQueueIds = [];
+    if (availableRootSlots > 0) {
+        for (const row of sorted) {
+            if (row.state !== "queued") {
+                continue;
+            }
+            const slotKey = queueRootSlotKey(row);
+            if (occupiedRoots.has(slotKey) || claimedRoots.has(slotKey)) {
+                continue;
+            }
+            claimedRoots.add(slotKey);
+            activateQueueIds.push(row.queue_id);
+            if (activateQueueIds.length >= availableRootSlots) {
+                break;
+            }
+        }
+    }
+    return {
+        policy,
+        max_active_roots: maxActiveRoots,
+        active_root_count: occupiedRoots.size,
+        available_root_slots: availableRootSlots,
+        activate_queue_ids: activateQueueIds,
+        launch_queue_ids: launchQueueIds,
+    };
+}

package/dist/outbound_delivery_router.d.ts

@@ -0,0 +1,12 @@
+import { type Channel, type OutboxDeliveryHandlerResult, type OutboxRecord } from "@femtomc/mu-control-plane";
+export type OutboundDeliveryDriver = {
+    channel: Channel;
+    deliver: (record: OutboxRecord) => Promise<OutboxDeliveryHandlerResult>;
+};
+export declare class OutboundDeliveryRouter {
+    #private;
+    constructor(drivers: readonly OutboundDeliveryDriver[]);
+    supportsChannel(channel: Channel): boolean;
+    supportedChannels(): Channel[];
+    deliver(record: OutboxRecord): Promise<undefined | OutboxDeliveryHandlerResult>;
+}

package/dist/outbound_delivery_router.js

@@ -0,0 +1,29 @@
+import { ChannelSchema, } from "@femtomc/mu-control-plane";
+export class OutboundDeliveryRouter {
+    #driversByChannel = new Map();
+    constructor(drivers) {
+        for (const driver of drivers) {
+            if (this.#driversByChannel.has(driver.channel)) {
+                throw new Error(`duplicate outbound delivery driver: ${driver.channel}`);
+            }
+            this.#driversByChannel.set(driver.channel, driver);
+        }
+    }
+    supportsChannel(channel) {
+        return this.#driversByChannel.has(channel);
+    }
+    supportedChannels() {
+        return [...this.#driversByChannel.keys()].sort((a, b) => a.localeCompare(b));
+    }
+    async deliver(record) {
+        const parsedChannel = ChannelSchema.safeParse(record.envelope.channel);
+        if (!parsedChannel.success) {
+            return undefined;
+        }
+        const driver = this.#driversByChannel.get(parsedChannel.data);
+        if (!driver) {
+            return undefined;
+        }
+        return await driver.deliver(record);
+    }
+}

package/dist/run_queue.d.ts

@@ -1,5 +1,5 @@
 import type { JsonlStore } from "@femtomc/mu-core";
-import { type InterRootQueuePolicy, type InterRootQueueReconcilePlan, type OrchestrationQueueState } from "@femtomc/mu-orchestrator";
+import { type InterRootQueuePolicy, type InterRootQueueReconcilePlan, type OrchestrationQueueState } from "./orchestration_queue.js";
 import type { ControlPlaneRunMode, ControlPlaneRunSnapshot, ControlPlaneRunStatus } from "./run_supervisor.js";
 export type DurableRunQueueState = OrchestrationQueueState;
 export type DurableRunQueueSnapshot = {