nemoris 0.1.0

package/src/runtime/result-normalizer.js

@@ -0,0 +1,183 @@
+import { renderContractOutput } from "./output-contract-validator.js";
+import { estimateCost } from "../utils/usage-cost.js";
+import { extractUsageMetrics } from "../utils/usage-metrics.js";
+
+export function synthesizeDryRun(plan, modelId) {
+  const memoryCount = plan.packet.layers.memory.length;
+  const summary = `Dry-run shadow execution for ${plan.job.id} prepared on ${modelId} with ${memoryCount} relevant memory items.`;
+  const output = [
+    `Job ${plan.job.id} would run on lane ${plan.job.modelLane} using model ${modelId}.`,
+    `Workspace: ${plan.agent.workspaceRoot || "unknown"}.`,
+    `Tools: ${plan.packet.layers.tools.join(", ") || "none"}.`,
+    `Memory items included: ${memoryCount}.`
+  ].join(" ");
+
+  return {
+    summary,
+    output,
+    nextActions: ["switch to provider mode for a real shadow run", "compare with live cron output"]
+  };
+}
+
+export function formatOutputContract(contract) {
+  const lines = [];
+  if (contract.format) lines.push(`- format: ${contract.format}`);
+  if (contract.requiredSections?.length) {
+    lines.push(`- required sections: ${contract.requiredSections.join(", ")}`);
+  }
+  if (contract.styleHints?.length) {
+    lines.push(`- style hints: ${contract.styleHints.join("; ")}`);
+  }
+  if (contract.profile?.sectionStyle) {
+    lines.push(`- section style: ${contract.profile.sectionStyle}`);
+  }
+  if (contract.profile?.requireStatus) {
+    lines.push("- requires status: yes");
+  }
+  return lines.join("\n");
+}
+
+export function formatReportGuidance(reportGuidance) {
+  const lines = [];
+  if (reportGuidance.focus?.length) {
+    lines.push(`- focus: ${reportGuidance.focus.join("; ")}`);
+  }
+  if (reportGuidance.qualityChecks?.length) {
+    lines.push(`- quality checks: ${reportGuidance.qualityChecks.join("; ")}`);
+  }
+  if (reportGuidance.avoid?.length) {
+    lines.push(`- avoid: ${reportGuidance.avoid.join("; ")}`);
+  }
+  return lines.join("\n");
+}
+
+export function normalizeNextActions(nextActions = []) {
+  return (nextActions || [])
+    .map((item) => {
+      if (typeof item === "string") return item.trim();
+      if (item && typeof item === "object") {
+        const action = String(item.action || "").trim();
+        const details = String(item.details || item.summary || "").trim();
+        return [action, details].filter(Boolean).join(": ");
+      }
+      return String(item || "").trim();
+    })
+    .filter(Boolean);
+}
+
+export function hasOnlyShadowImportEvidence(plan) {
+  const memory = plan?.packet?.layers?.memory || [];
+  if (!memory.length) return false;
+  return memory.every((item) => ["shadow_import", "artifact_summary"].includes(item.category));
+}
+
+export function normalizeResultForContract(plan, result, options = {}) {
+  const contract = plan?.packet?.layers?.outputContract || null;
+  if (!contract || options.mode !== "provider") {
+    return {
+      ...result,
+      nextActions: normalizeNextActions(result.nextActions || [])
+    };
+  }
+
+  const originalOutput = result.output;
+  const canonicalOutput = renderContractOutput(contract, originalOutput, {
+    shadowOnlyEvidence: contract.format === "structured_rollup" && hasOnlyShadowImportEvidence(plan),
+    status: result.summary
+  });
+
+  return {
+    ...result,
+    output: canonicalOutput,
+    outputStructured: originalOutput,
+    nextActions: normalizeNextActions(result.nextActions || [])
+  };
+}
+
+export function buildOutputTemplate(contract) {
+  if (!contract) return null;
+  if (contract.profile?.templateLines?.length) {
+    return contract.profile.templateLines.join("\n");
+  }
+
+  if (contract.format === "bulleted_briefing") {
+    return [
+      "Status: <one-line status>",
+      "- Calendar: <brief update or None>",
+      "- Issues: <brief update or None>",
+      "- Weather: <brief update or None>"
+    ].join("\n");
+  }
+
+  if (contract.format === "structured_rollup") {
+    return [
+      "## Inbox",
+      "- <brief update or None>",
+      "",
+      "## Projects",
+      "- <brief update or None>",
+      "",
+      "## Backlog",
+      "- <brief update or None>",
+      "",
+      "## Update",
+      "- <brief update or None>"
+    ].join("\n");
+  }
+
+  return null;
+}
+
+function normalizeProviderResponse(rawResponse, adapter) {
+  if (typeof adapter?.normalizeResponse === "function") {
+    return adapter.normalizeResponse(rawResponse);
+  }
+  return {
+    summary: "Provider returned unnormalized data.",
+    output: rawResponse,
+    nextActions: [],
+    reasoning: null,
+    raw: rawResponse
+  };
+}
+
+export async function normalizeResult({ plan, rawResponse, toolResults = [], usage, options = {} }) {
+  const mode = options.mode || "dry-run";
+  let result = null;
+
+  if (options.pendingApprovalResult) {
+    result = options.pendingApprovalResult;
+  } else if (mode === "dry-run") {
+    result = synthesizeDryRun(plan, options.modelId);
+  } else {
+    result = normalizeProviderResponse(rawResponse, options.adapter);
+    result = normalizeResultForContract(plan, result, { mode });
+  }
+
+  const usageMetrics = usage || extractUsageMetrics(rawResponse || {});
+  const costUsd = options.modelId ? estimateCost(options.modelId, usageMetrics.tokensIn, usageMetrics.tokensOut) : null;
+
+  if (!options.pendingApprovalResult && mode === "provider" && rawResponse && typeof options.logUsage === "function") {
+    try {
+      await options.logUsage({
+        plan,
+        providerId: options.providerId,
+        modelId: options.modelId,
+        usage: usageMetrics,
+        costUsd,
+        rawResponse,
+        toolResults,
+        sessionId: options.sessionId || plan.job.chat_id || "unknown"
+      });
+    } catch (err) {
+      console.error(JSON.stringify({ service: "usage_logging", error: err.message, jobId: plan.job.id }));
+    }
+  }
+
+  return {
+    result,
+    usage: usageMetrics,
+    costUsd,
+    cached: Boolean(usageMetrics.cacheIn || usageMetrics.cacheCreation)
+  };
+}

package/src/runtime/retention.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { listFilesRecursive, readJson, removePath } from "../utils/fs.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function inferTimestampFromPath(filePath) {
+  const base = path.basename(filePath, ".json");
+  const candidate = base.replace(/-/g, ":").replace(/(\d{4}):(\d{2}):(\d{2})T/, "$1-$2-$3T").replace(/:(\d{3})$/, ".$1");
+  const parsed = new Date(candidate);
+  return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+
+function normalizeTimestamp(item) {
+  return item.timestamp || item.receivedAt || inferTimestampFromPath(item.filePath) || "1970-01-01T00:00:00.000Z";
+}
+
+function isJsonFile(filePath) {
+  return filePath.endsWith(".json");
+}
+
+export function buildRetentionPolicy(config = {}, defaults = {}) {
+  return {
+    ttlDays: Number(config.ttlDays ?? defaults.ttlDays ?? 30),
+    maxFilesPerBucket: Number(config.maxFilesPerBucket ?? defaults.maxFilesPerBucket ?? 1000)
+  };
+}
+
+export async function pruneJsonBuckets(rootDir, policy, options = {}) {
+  const now = options.now ? new Date(options.now) : new Date();
+  const ttlCutoff = now.getTime() - policy.ttlDays * DAY_MS;
+  const excluded = new Set((options.excludePaths || []).map((filePath) => path.resolve(filePath)));
+  const files = (await listFilesRecursive(rootDir)).filter((filePath) => isJsonFile(filePath) && !excluded.has(path.resolve(filePath)));
+  const buckets = new Map();
+
+  for (const filePath of files) {
+    const bucket = path.dirname(filePath);
+    if (!buckets.has(bucket)) buckets.set(bucket, []);
+    const data = await readJson(filePath, null);
+    buckets.get(bucket).push({
+      filePath,
+      timestamp: normalizeTimestamp({
+        ...(data || {}),
+        filePath
+      })
+    });
+  }
+
+  const removed = [];
+  for (const entries of buckets.values()) {
+    entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    const keep = new Set();
+
+    for (let index = 0; index < entries.length; index += 1) {
+      const item = entries[index];
+      const expired = new Date(item.timestamp).getTime() < ttlCutoff;
+      const overflow = index >= policy.maxFilesPerBucket;
+      if (!expired && !overflow) {
+        keep.add(item.filePath);
+      }
+    }
+
+    for (const item of entries) {
+      if (keep.has(item.filePath)) continue;
+      await removePath(item.filePath);
+      removed.push(item.filePath);
+    }
+  }
+
+  return {
+    rootDir,
+    removedCount: removed.length,
+    removed
+  };
+}

package/src/runtime/review.js

@@ -0,0 +1,244 @@
+import path from "node:path";
+import { listFilesRecursive, readJson } from "../utils/fs.js";
+import { SchedulerStateStore } from "./scheduler-state.js";
+import { NotificationStore } from "./notification-store.js";
+import { DeliveryStore } from "./delivery-store.js";
+
+function sortDescending(items) {
+  return [...items].sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+
+function inferTimestampFromPath(filePath) {
+  const base = path.basename(filePath, ".json");
+  const candidate = base.replace(/-/g, ":").replace(/(\d{4}):(\d{2}):(\d{2})T/, "$1-$2-$3T").replace(/:(\d{3})$/, ".$1");
+  const parsed = new Date(candidate);
+  return Number.isNaN(parsed.getTime()) ? "1970-01-01T00:00:00.000Z" : parsed.toISOString();
+}
+
+function expandRelatedNotificationFiles(baseFiles, notifications) {
+  const related = new Set(baseFiles);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const item of notifications) {
+      if (!related.has(item.filePath)) continue;
+      for (const generated of item.generatedNotificationFiles || []) {
+        if (related.has(generated)) continue;
+        related.add(generated);
+        changed = true;
+      }
+    }
+  }
+  return related;
+}
+
+function summarizeInteractionState(runData, notifications = [], deliveries = []) {
+  const interaction = runData?.interaction || null;
+  const ackNotification = notifications.find((item) => item.stage === "ack") || null;
+  const completionNotification = notifications.find((item) => item.stage === "completion") || null;
+  const handoffNotification = notifications.find((item) => item.stage === "handoff") || null;
+  const followUpNotification = notifications.find((item) => item.stage === "follow_up") || null;
+  const handoffDelivery = handoffNotification
+    ? deliveries.find((item) => item.notificationFilePath === handoffNotification.filePath) || null
+    : null;
+  const dedupeStatuses = deliveries.map((item) => item.delivery?.status || null);
+  const generatedNotificationFiles = new Set(followUpNotification?.generatedNotificationFiles || []);
+  const followUpDeliveries = deliveries.filter((item) => generatedNotificationFiles.has(item.notificationFilePath));
+  const ackQueued = Boolean(ackNotification);
+  const completionQueued = Boolean(completionNotification);
+  const handoffQueued = Boolean(handoffNotification);
+  const deliveryEvidenceRequired = !interaction?.yield?.required && (ackQueued || completionQueued || handoffQueued);
+  const deliveryReceiptCount = deliveries.length;
+
+  return {
+    ackRequired: interaction?.ack?.required ?? false,
+    ackQueued,
+    completionRequired: interaction?.completion?.required ?? false,
+    completionQueued,
+    handoffRequired: interaction?.handoff?.required ?? false,
+    handoffQueued,
+    yielded: interaction?.yield?.required ?? false,
+    yieldSignal: interaction?.yield?.signal || null,
+    followUpQueued: Boolean(followUpNotification),
+    followUpState: followUpNotification?.followUpState || followUpNotification?.yieldState || null,
+    followUpConsumed: followUpNotification?.status === "consumed" || followUpNotification?.yieldState === "consumed" || followUpNotification?.followUpState === "consumed",
+    followUpTarget: followUpNotification?.targetSurface || interaction?.yield?.targetSurface || null,
+    followUpCompleted: Boolean(followUpDeliveries.length),
+    followUpExpired: followUpNotification?.followUpState === "expired",
+    followUpEscalated: followUpNotification?.followUpState === "escalated",
+    followUpEscalationFilePath: followUpNotification?.escalationNotificationFilePath || null,
+    handoffPendingChoice: handoffNotification?.handoffState === "pending" || handoffNotification?.status === "awaiting_choice",
+    handoffState: handoffNotification?.handoffState || null,
+    handoffExpired: handoffNotification?.handoffState === "expired",
+    handoffEscalated: handoffNotification?.handoffState === "escalated",
+    handoffBlocked: handoffNotification?.handoffState === "blocked" || handoffNotification?.status === "blocked",
+    handoffChosen: Boolean(handoffNotification?.chosenPeer?.peerId),
+    handoffChosenPeerId: handoffNotification?.chosenPeer?.peerId || null,
+    handoffChosenBy: handoffNotification?.chosenBy || null,
+    handoffDelivered: Boolean(handoffDelivery),
+    handoffDeliveryState: handoffDelivery?.delivery?.status || null,
+    handoffReceiptFilePath: handoffDelivery?.filePath || null,
+    handoffBlockedReason: handoffNotification?.blockedReason || null,
+    handoffEscalationFilePath: handoffNotification?.escalationNotificationFilePath || null,
+    deliveryEvidenceRequired,
+    deliveryEvidenceHealthy: !deliveryEvidenceRequired || deliveryReceiptCount > 0,
+    deliveryReceiptCount,
+    deliveryDeduped: dedupeStatuses.includes("duplicate_prevented"),
+    deliveryRetried: deliveries.some((item) => Number(item.attempt) > 1),
+    deliveryUncertain: dedupeStatuses.includes("delivery_uncertain") || dedupeStatuses.includes("uncertain")
+  };
+}
+
+export class RunReviewer {
+  constructor({ stateRoot }) {
+    this.stateRoot = stateRoot;
+    this.runRoot = path.join(stateRoot, "runs");
+    this.schedulerState = new SchedulerStateStore({ rootDir: path.join(stateRoot, "scheduler") });
+    this.notificationStore = new NotificationStore({ rootDir: path.join(stateRoot, "notifications") });
+    this.deliveryStore = new DeliveryStore({ rootDir: path.join(stateRoot, "deliveries") });
+  }
+
+  async listRecentRuns(limit = 10) {
+    const files = (await listFilesRecursive(this.runRoot)).filter((filePath) => filePath.endsWith(".json"));
+    const runs = [];
+
+    const [notifications, deliveries] = await Promise.all([
+      this.notificationStore.listAll(),
+      this.deliveryStore.listAll()
+    ]);
+
+    for (const filePath of files) {
+      const data = await readJson(filePath, null);
+      if (!data) continue;
+      const relatedNotificationFiles = expandRelatedNotificationFiles(data.notificationFiles || [], notifications);
+      const runNotifications = notifications.filter((item) => relatedNotificationFiles.has(item.filePath));
+      const runDeliveries = deliveries.filter((item) => relatedNotificationFiles.has(item.notificationFilePath));
+      const interactionState = summarizeInteractionState(data, runNotifications, runDeliveries);
+      runs.push({
+        filePath,
+        jobId: path.basename(path.dirname(filePath)),
+        timestamp: data.timestamp || inferTimestampFromPath(filePath),
+        mode: data.mode || null,
+        providerId: data.providerId || null,
+        modelId: data.modelId || null,
+        summary: data.result?.summary || data.summary || null,
+        output: data.result?.output || data.output || null,
+        result: data.result || null,
+        plan: data.plan || null,
+        fallback: data.fallback || null,
+        notificationFiles: data.notificationFiles || [],
+        retrievalMeta: data.plan?.packet?.layers?.retrievalMeta || null,
+        retrievedMemory: data.plan?.packet?.layers?.memory || [],
+        interaction: data.interaction || null,
+        completionSignal: data.interaction?.completion?.signal || null,
+        completionTarget: data.interaction?.completion?.target || null,
+        completionMessage: data.interaction?.completion?.message || null,
+        ackQueued: interactionState.ackQueued,
+        completionQueued: interactionState.completionQueued,
+        handoffQueued: interactionState.handoffQueued,
+        handoffSignal: data.interaction?.handoff?.signal || null,
+        handoffTarget: data.interaction?.handoff?.target || null,
+        handoffSuggestionCount: data.interaction?.handoff?.suggestions?.length || 0,
+        yielded: interactionState.yielded,
+        yieldSignal: interactionState.yieldSignal,
+        followUpState: interactionState.followUpState,
+        followUpQueued: interactionState.followUpQueued,
+        followUpConsumed: interactionState.followUpConsumed,
+        followUpTarget: interactionState.followUpTarget,
+        followUpCompleted: interactionState.followUpCompleted,
+        followUpExpired: interactionState.followUpExpired,
+        followUpEscalated: interactionState.followUpEscalated,
+        followUpEscalationFilePath: interactionState.followUpEscalationFilePath,
+        handoffChosenPeerId: interactionState.handoffChosenPeerId,
+        handoffChosenBy: interactionState.handoffChosenBy,
+        handoffDelivered: interactionState.handoffDelivered,
+        handoffDeliveryState: interactionState.handoffDeliveryState,
+        handoffState: interactionState.handoffState,
+        handoffBlockedReason: interactionState.handoffBlockedReason,
+        deliveryEvidenceRequired: interactionState.deliveryEvidenceRequired,
+        deliveryEvidenceHealthy: interactionState.deliveryEvidenceHealthy,
+        deliveryReceiptCount: interactionState.deliveryReceiptCount,
+        deliveryDeduped: interactionState.deliveryDeduped,
+        deliveryRetried: interactionState.deliveryRetried,
+        deliveryUncertain: interactionState.deliveryUncertain,
+        fallbackAllowed: Boolean(data.fallback?.allowed),
+        fallbackAttempted: Boolean(data.fallback?.attempted),
+        fallbackSucceeded: Boolean(data.fallback?.success),
+        fallbackTrigger: data.fallback?.trigger || null,
+        fallbackSourceLane: data.fallback?.sourceLane || null,
+        fallbackFinalSourceLane: data.fallback?.finalSourceLane || null,
+        fallbackFinalProviderId: data.fallback?.finalProviderId || null,
+        fallbackFinalModelId: data.fallback?.finalModelId || null,
+        fallbackBlockedReason: data.fallback?.blockedReason || null,
+        retrievalHealth: data.plan?.packet?.layers?.retrievalMeta?.embeddingHealth || null,
+        retrievalDegradedMode: data.plan?.packet?.layers?.retrievalMeta?.embeddingQueryMode === "lexical_fallback",
+        status: data.result ? "ok" : data.lastStatus || null
+      });
+    }
+
+    return sortDescending(runs).slice(0, limit);
+  }
+
+  async schedulerOverview() {
+    const state = await this.schedulerState.load();
+    return Object.entries(state.jobs || {}).map(([jobId, jobState]) => ({
+      jobId,
+      ...jobState
+    }));
+  }
+
+  async review(limit = 10) {
+    const [recentRuns, scheduler, recentNotifications, recentDeliveries] = await Promise.all([
+      this.listRecentRuns(limit),
+      this.schedulerOverview(),
+      this.notificationStore.listRecent(limit),
+      this.deliveryStore.listRecent(limit)
+    ]);
+    const maintenance = await this.schedulerState.getMeta("maintenance", null);
+    const handoffs = recentNotifications
+      .filter((item) => item.stage === "handoff")
+      .map((item) => {
+        const receipt = recentDeliveries.find((delivery) => delivery.notificationFilePath === item.filePath) || null;
+        return {
+          filePath: item.filePath,
+          jobId: item.jobId,
+          timestamp: item.timestamp,
+          status: item.status,
+          handoffState: item.handoffState || null,
+          signal: item.signal,
+          suggestedPeerCount: item.suggestedPeers?.length || 0,
+          chosenPeerId: item.chosenPeer?.peerId || null,
+          chosenBy: item.chosenBy || null,
+          deliveryStatus: receipt?.delivery?.status || null,
+          receiptFilePath: receipt?.filePath || null,
+          blockedReason: item.blockedReason || null,
+          escalationNotificationFilePath: item.escalationNotificationFilePath || null
+        };
+      });
+    const followUps = recentNotifications
+      .filter((item) => item.stage === "follow_up")
+      .map((item) => ({
+        filePath: item.filePath,
+        jobId: item.jobId,
+        timestamp: item.timestamp,
+        status: item.status,
+        yieldState: item.yieldState || null,
+        followUpState: item.followUpState || null,
+        signal: item.signal || null,
+        targetSurface: item.targetSurface || null,
+        consumedAt: item.consumedAt || null,
+        expiredAt: item.expiredAt || null,
+        escalationNotificationFilePath: item.escalationNotificationFilePath || null,
+        generatedNotificationFiles: item.generatedNotificationFiles || []
+      }));
+    return {
+      scheduler,
+      maintenance,
+      recentRuns,
+      recentNotifications,
+      recentDeliveries,
+      recentHandoffs: handoffs,
+      recentFollowUps: followUps
+    };
+  }
+}

package/src/runtime/route-job.js

@@ -0,0 +1,15 @@
+export async function routeJob({ jobId, mode, orchestrator, executor, skipOrchestrator = false, shadowImport = true, idempotencyKey = null }) {
+  if (orchestrator && !skipOrchestrator) {
+    const route = await orchestrator.route(jobId);
+    if (route.agentId) {
+      const result = await executor.executeJob(jobId, { mode, shadowImport, targetAgent: route.agentId, idempotencyKey });
+      return { ...result, routedVia: "orchestrator", route };
+    }
+    // Escalation — no agent could handle it
+    return { routedVia: "escalation", route, filePath: null, notificationFiles: [] };
+  }
+
+  // Direct execution (backwards-compatible)
+  const result = await executor.executeJob(jobId, { mode, shadowImport, idempotencyKey });
+  return { ...result, routedVia: "direct" };
+}

package/src/runtime/run-store.js

@@ -0,0 +1,38 @@
+import path from "node:path";
+import { ensureDir, writeJson } from "../utils/fs.js";
+import { buildRetentionPolicy, pruneJsonBuckets } from "./retention.js";
+import { createRuntimeId } from "../utils/ids.js";
+
+function stamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+export class RunStore {
+  constructor({ rootDir, retention = {} }) {
+    this.rootDir = rootDir;
+    this.setRetentionPolicy(retention);
+  }
+
+  setRetentionPolicy(retention = {}) {
+    this.retentionPolicy = buildRetentionPolicy(retention, {
+      ttlDays: 30,
+      maxFilesPerBucket: 2000
+    });
+  }
+
+  async saveRun(jobId, run) {
+    const runDir = path.join(this.rootDir, jobId);
+    await ensureDir(runDir);
+    const filePath = path.join(runDir, `${stamp()}.json`);
+    await writeJson(filePath, {
+      runId: run.runId || createRuntimeId("run"),
+      ...run
+    });
+    await pruneJsonBuckets(this.rootDir, this.retentionPolicy);
+    return filePath;
+  }
+
+  async prune(options = {}) {
+    return pruneJsonBuckets(this.rootDir, this.retentionPolicy, options);
+  }
+}

package/src/runtime/schedule.js

@@ -0,0 +1,88 @@
+function pad(value) {
+  return String(value).padStart(2, "0");
+}
+
+function cloneDate(date) {
+  return new Date(date.getTime());
+}
+
+export function parseEveryMinutes(trigger) {
+  const match = /^every:(\d+)(m|h)$/.exec(String(trigger || ""));
+  if (!match) return null;
+  const amount = Number(match[1]);
+  const unit = match[2];
+  return unit === "h" ? amount * 60 : amount;
+}
+
+export function computeNextRun(trigger, now = new Date()) {
+  const everyMinutes = parseEveryMinutes(trigger);
+  if (everyMinutes != null) {
+    return new Date(now.getTime() + everyMinutes * 60 * 1000);
+  }
+
+  if (trigger === "hourly") {
+    const next = cloneDate(now);
+    next.setUTCMinutes(0, 0, 0);
+    next.setUTCHours(next.getUTCHours() + 1);
+    return next;
+  }
+
+  const dailyMatch = /^daily:(\d{2}):(\d{2})$/.exec(String(trigger || ""));
+  if (dailyMatch) {
+    const [, hh, mm] = dailyMatch;
+    const next = cloneDate(now);
+    next.setUTCHours(Number(hh), Number(mm), 0, 0);
+    if (next.getTime() <= now.getTime()) {
+      next.setUTCDate(next.getUTCDate() + 1);
+    }
+    return next;
+  }
+
+  throw new Error(`Unsupported trigger: ${trigger}`);
+}
+
+export function computeRunSlot(trigger, now = new Date()) {
+  const everyMinutes = parseEveryMinutes(trigger);
+  if (everyMinutes != null) {
+    const slotMs = everyMinutes * 60 * 1000;
+    return new Date(Math.floor(now.getTime() / slotMs) * slotMs);
+  }
+
+  if (trigger === "hourly") {
+    const slot = cloneDate(now);
+    slot.setUTCMinutes(0, 0, 0);
+    return slot;
+  }
+
+  const dailyMatch = /^daily:(\d{2}):(\d{2})$/.exec(String(trigger || ""));
+  if (dailyMatch) {
+    const slot = cloneDate(now);
+    slot.setUTCHours(0, 0, 0, 0);
+    return slot;
+  }
+
+  throw new Error(`Unsupported trigger: ${trigger}`);
+}
+
+export function isDue(trigger, lastRunAt, nextRunAt, now = new Date()) {
+  if (nextRunAt) {
+    return new Date(nextRunAt).getTime() <= now.getTime();
+  }
+  if (!lastRunAt) return true;
+  return new Date(lastRunAt).getTime() < computeNextRun(trigger, new Date(lastRunAt)).getTime() &&
+    computeNextRun(trigger, new Date(lastRunAt)).getTime() <= now.getTime();
+}
+
+export function formatRunState(state) {
+  return {
+    lastRunAt: state.lastRunAt || null,
+    nextRunAt: state.nextRunAt || null,
+    lastStatus: state.lastStatus || null,
+    lastRunFile: state.lastRunFile || null,
+    consecutiveFailures: state.consecutiveFailures || 0
+  };
+}
+
+export function iso(date) {
+  return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}T${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}.000Z`;
+}