@voyantjs/workflows-orchestrator-cloudflare 0.86.0 → 0.88.0

package/README.md

@@ -65,6 +65,10 @@ export class WorkflowRunDO implements DurableObject {
 |---|---|
 | `POST /api/runs` | Trigger a new run. Body: `{ workflowId, workflowVersion, input, tenantMeta, runId? }`. |
 | `GET  /api/runs/:id` | Fetch the current `RunRecord`. |
+| `POST /api/manifests` | Register a workflow manifest for an environment when `manifestStore` is configured. |
+| `GET  /api/manifests/:env` | Fetch the current workflow manifest for an environment. |
+| `GET  /api/schedules/:env` | List manifest schedules with computed `nextRunAt`; when `scheduleStateStore` is configured, rows also include `lastFireAt`, `lastRunId`, `lastError`, `lockedUntil`, and `lastSuccessfulRunAt`. |
+| `POST /api/events` | Route an event through the registered manifest and trigger matching workflows. |
 | `POST /api/runs/:id/resume` | Start a new run from a failed parent run. Body: `{ input?, workflowId?, resumeFromStep?, seedResults?, runId?, tags?, triggeredByUserId? }`. |
 | `POST /api/runs/:id/events` | Inject an `EVENT` waitpoint resolution. |
 | `POST /api/runs/:id/signals` | Inject a `SIGNAL` waitpoint resolution. |

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { type DurableObjectDeps, handleDurableObjectAlarm, handleDurableObjectRe
 export { type CfManifestEnvelope, type CfManifestStore, type CreateKvManifestStoreOptions, createInMemoryKv, createKvManifestStore, type KvNamespaceLike, } from "./manifest-kv-store.js";
 export { createR2Presigner, type PresignArgs, type R2PresignerOptions, } from "./r2-sign.js";
 export { handleGetSchedules, type ScheduleHandlerDeps, type ScheduleListResponse, type ScheduleSummary, } from "./schedule-handler.js";
+export { type CfScheduleStateStore, type CreateKvScheduleStateStoreOptions, createKvScheduleStateStore, type ScheduleStateRecord, } from "./schedule-state-store.js";
 export * from "./types.js";
 export { type DurableObjectNamespaceLike, handleWorkerRequest, type WorkerFetchDeps, } from "./worker.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkCA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,2BAA2B,GAC5B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,KAAK,2BAA2B,EAChC,0BAA0B,GAC3B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,4BAA4B,EAC5B,mCAAmC,GACpC,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,8BAA8B,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,+BAA+B,EACpC,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EACL,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,OAAO,EACL,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkCA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,2BAA2B,GAC5B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,KAAK,2BAA2B,EAChC,0BAA0B,GAC3B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,4BAA4B,EAC5B,mCAAmC,GACpC,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,8BAA8B,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,+BAA+B,EACpC,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EACL,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iCAAiC,EACtC,0BAA0B,EAC1B,KAAK,mBAAmB,GACzB,MAAM,2BAA2B,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,OAAO,EACL,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -40,5 +40,6 @@ export { handleDurableObjectAlarm, handleDurableObjectRequest, } from "./durable
 export { createInMemoryKv, createKvManifestStore, } from "./manifest-kv-store.js";
 export { createR2Presigner, } from "./r2-sign.js";
 export { handleGetSchedules, } from "./schedule-handler.js";
+export { createKvScheduleStateStore, } from "./schedule-state-store.js";
 export * from "./types.js";
 export { handleWorkerRequest, } from "./worker.js";

package/dist/schedule-handler.d.ts

@@ -1,5 +1,6 @@
 import type { ManifestSchedule } from "@voyantjs/workflows/protocol";
 import type { CfManifestStore } from "./manifest-kv-store.js";
+import type { CfScheduleStateStore } from "./schedule-state-store.js";
 export interface ScheduleHandlerDeps {
     manifestStore: CfManifestStore;
     /**
@@ -12,6 +13,11 @@ export interface ScheduleHandlerDeps {
      * UIs can ignore the field.
      */
     schedulesEnabledByEnv?: boolean;
+    /**
+     * Optional state store populated by the runtime scheduler/control plane.
+     * When present, each schedule row includes last-fire/run/error fields.
+     */
+    scheduleStateStore?: CfScheduleStateStore;
     now?: () => number;
     logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
 }
@@ -28,6 +34,18 @@ export interface ScheduleSummary {
      */
     enabled: boolean;
     disabledReason?: "registration_disabled" | "env_filtered";
+    /** Epoch millis of the last scheduler dispatch attempt, when known. */
+    lastFireAt?: number | null;
+    /** Run id produced by the last scheduler dispatch attempt, when known. */
+    lastRunId?: string | null;
+    /** Last scheduler dispatch/lock error, when known. */
+    lastError?: string | null;
+    /** Epoch millis until which this schedule is locked, when known. */
+    lockedUntil?: number | null;
+    /** Epoch millis of the last successful scheduled run, when known. */
+    lastSuccessfulRunAt?: number | null;
+    /** Epoch millis when the persisted scheduler state was last updated. */
+    stateUpdatedAt?: number | null;
 }
 export interface ScheduleListResponse {
     environment: string;

package/dist/schedule-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schedule-handler.d.ts","sourceRoot":"","sources":["../src/schedule-handler.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,8BAA8B,CAAA;AAGtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAI7D,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,eAAe,CAAA;IAC9B;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAChF;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,CAAC,EAAE,uBAAuB,GAAG,cAAc,CAAA;CAC1D;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,IAAI,EAAE,eAAe,EAAE,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAoEnB"}
+{"version":3,"file":"schedule-handler.d.ts","sourceRoot":"","sources":["../src/schedule-handler.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAGpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAuB,MAAM,2BAA2B,CAAA;AAW1F,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,eAAe,CAAA;IAC9B;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,oBAAoB,CAAA;IACzC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAChF;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,CAAC,EAAE,uBAAuB,GAAG,cAAc,CAAA;IACzD,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,IAAI,EAAE,eAAe,EAAE,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAkFnB"}

package/dist/schedule-handler.js

@@ -1,24 +1,19 @@
 // HTTP handler for `/api/schedules/:env`. Reads the registered manifest
 // for the requested environment, projects each workflow's schedule blocks
-// into a flat list, and computes `nextRun` per entry via the same cron /
-// every / at logic the live scheduler uses.
-//
-// Aggregate "lastRun" is intentionally out of scope here — runs in the
-// Cloudflare orchestrator live in per-run Durable Objects, indexed by
-// runId, with no list-by-workflow path. The UI is expected to fetch
-// last-run state separately from the template-side `workflow-runs`
-// admin API (`/v1/admin/workflow-runs?workflowName=…&limit=1`).
+// into a flat list, computes `nextRun` per entry via the same cron / every /
+// at logic the live scheduler uses, and optionally merges persisted scheduler
+// dispatch state when a control plane provides it.
 import { computeNextFire } from "@voyantjs/workflows-orchestrator";
-const ALLOWED_ENVS = new Set(["production", "preview", "development"]);
+const ALLOWED_ENVS = ["production", "preview", "development"];
 /**
  * Handle `GET /api/schedules/:env`. Returns the projected schedule list
  * for the current manifest, or 404 when no manifest is registered.
  */
 export async function handleGetSchedules(environment, deps) {
-    if (!ALLOWED_ENVS.has(environment)) {
+    if (!isAllowedEnvironment(environment)) {
         return json(400, {
             error: "invalid_environment",
-            message: `environment must be one of ${[...ALLOWED_ENVS].join(", ")}`,
+            message: `environment must be one of ${ALLOWED_ENVS.join(", ")}`,
         });
     }
     const envelope = await deps.manifestStore.getCurrent(environment);
@@ -26,11 +21,9 @@ export async function handleGetSchedules(environment, deps) {
         return json(404, { error: "not_found", environment });
     }
     const now = deps.now ? deps.now() : Date.now();
-    const manifest = envelope.manifest;
     const data = [];
-    for (const workflow of manifest.workflows ?? []) {
-        const schedules = Array.isArray(workflow.schedules) ? workflow.schedules : [];
-        schedules.forEach((schedule, index) => {
+    for (const workflow of readManifestWorkflows(envelope.manifest)) {
+        workflow.schedules.forEach((schedule, index) => {
             const scheduleId = `${envelope.versionId}:${workflow.id}:${schedule.name ?? index}`;
             const registrationDisabled = schedule.enabled === false;
             const envFiltered = Array.isArray(schedule.environments)
@@ -67,6 +60,22 @@ export async function handleGetSchedules(environment, deps) {
             });
         });
     }
+    if (deps.scheduleStateStore) {
+        const scheduleIds = data.map((row) => row.scheduleId);
+        let states = new Map();
+        try {
+            states = await deps.scheduleStateStore.getStates(environment, scheduleIds);
+        }
+        catch (err) {
+            deps.logger?.("warn", "schedules: cannot load scheduler state", {
+                environment,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        for (const row of data) {
+            attachState(row, states.get(row.scheduleId));
+        }
+    }
     const response = {
         environment,
         versionId: envelope.versionId,
@@ -77,6 +86,33 @@ export async function handleGetSchedules(environment, deps) {
     };
     return json(200, response);
 }
+function isAllowedEnvironment(value) {
+    return ALLOWED_ENVS.includes(value);
+}
+function readManifestWorkflows(manifest) {
+    const workflows = manifest.workflows;
+    if (!Array.isArray(workflows))
+        return [];
+    return workflows.flatMap((workflow) => {
+        if (!isRecord(workflow) || typeof workflow.id !== "string")
+            return [];
+        const schedules = Array.isArray(workflow.schedules)
+            ? workflow.schedules.filter(isManifestSchedule)
+            : [];
+        return [{ id: workflow.id, schedules }];
+    });
+}
+function isManifestSchedule(value) {
+    return isRecord(value);
+}
+function attachState(row, state) {
+    row.lastFireAt = state?.lastFireAt ?? null;
+    row.lastRunId = state?.lastRunId ?? null;
+    row.lastError = state?.lastError ?? null;
+    row.lockedUntil = state?.lockedUntil ?? null;
+    row.lastSuccessfulRunAt = state?.lastSuccessfulRunAt ?? null;
+    row.stateUpdatedAt = state?.updatedAt ?? null;
+}
 function json(status, body) {
     return new Response(JSON.stringify(body), {
         status,
@@ -88,3 +124,6 @@ function json(status, body) {
         },
     });
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/schedule-state-store.d.ts

@@ -0,0 +1,22 @@
+import type { KvNamespaceLike } from "./manifest-kv-store.js";
+export interface ScheduleStateRecord {
+    scheduleId: string;
+    workflowId?: string;
+    environment?: string;
+    versionId?: string;
+    lastFireAt?: number | null;
+    lastRunId?: string | null;
+    lastError?: string | null;
+    lockedUntil?: number | null;
+    lastSuccessfulRunAt?: number | null;
+    updatedAt?: number | null;
+}
+export interface CfScheduleStateStore {
+    getStates(environment: string, scheduleIds: readonly string[]): Promise<Map<string, ScheduleStateRecord>>;
+    putState(environment: string, state: ScheduleStateRecord): Promise<void>;
+}
+export interface CreateKvScheduleStateStoreOptions {
+    kv: KvNamespaceLike;
+}
+export declare function createKvScheduleStateStore(opts: CreateKvScheduleStateStoreOptions): CfScheduleStateStore;
+//# sourceMappingURL=schedule-state-store.d.ts.map

package/dist/schedule-state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-state-store.d.ts","sourceRoot":"","sources":["../src/schedule-state-store.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,CACP,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAA;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACzE;AAeD,MAAM,WAAW,iCAAiC;IAChD,EAAE,EAAE,eAAe,CAAA;CACpB;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,iCAAiC,GACtC,oBAAoB,CAyBtB"}

package/dist/schedule-state-store.js

@@ -0,0 +1,74 @@
+// KV-backed persisted state for workflow schedule dispatches.
+//
+// The manifest store answers "what schedules are registered?". This store
+// answers "what has the scheduler actually attempted recently?", keyed by
+// the stable schedule id emitted by manifestScheduleSources / schedule-handler.
+export function createKvScheduleStateStore(opts) {
+    const kv = opts.kv;
+    return {
+        async getStates(environment, scheduleIds) {
+            const out = new Map();
+            await Promise.all(scheduleIds.map(async (scheduleId) => {
+                const raw = await kv.get(scheduleStateKey(environment, scheduleId));
+                if (!raw)
+                    return;
+                const parsed = parseScheduleState(raw);
+                if (!parsed || parsed.scheduleId !== scheduleId)
+                    return;
+                out.set(scheduleId, parsed);
+            }));
+            return out;
+        },
+        async putState(environment, state) {
+            await kv.put(scheduleStateKey(environment, state.scheduleId), JSON.stringify(normalizeScheduleState(environment, state)));
+        },
+    };
+}
+function scheduleStateKey(environment, scheduleId) {
+    return `schedule-state:${environment}:${encodeURIComponent(scheduleId)}`;
+}
+function parseScheduleState(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed) || typeof parsed.scheduleId !== "string")
+            return null;
+        const state = {
+            scheduleId: parsed.scheduleId,
+            workflowId: typeof parsed.workflowId === "string" ? parsed.workflowId : undefined,
+            versionId: typeof parsed.versionId === "string" ? parsed.versionId : undefined,
+            lastFireAt: parsed.lastFireAt,
+            lastRunId: parsed.lastRunId,
+            lastError: parsed.lastError,
+            lockedUntil: parsed.lockedUntil,
+            lastSuccessfulRunAt: parsed.lastSuccessfulRunAt,
+            updatedAt: parsed.updatedAt,
+        };
+        return normalizeScheduleState(typeof parsed.environment === "string" ? parsed.environment : undefined, state);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeScheduleState(environment, state) {
+    return {
+        scheduleId: state.scheduleId,
+        ...(typeof state.workflowId === "string" ? { workflowId: state.workflowId } : {}),
+        ...(environment !== undefined ? { environment } : {}),
+        ...(typeof state.versionId === "string" ? { versionId: state.versionId } : {}),
+        lastFireAt: nullableFiniteNumber(state.lastFireAt),
+        lastRunId: nullableString(state.lastRunId),
+        lastError: nullableString(state.lastError),
+        lockedUntil: nullableFiniteNumber(state.lockedUntil),
+        lastSuccessfulRunAt: nullableFiniteNumber(state.lastSuccessfulRunAt),
+        updatedAt: nullableFiniteNumber(state.updatedAt),
+    };
+}
+function nullableFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function nullableString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/worker.d.ts

@@ -1,4 +1,5 @@
 import type { CfManifestStore } from "./manifest-kv-store.js";
+import type { CfScheduleStateStore } from "./schedule-state-store.js";
 /**
  * Minimal shape of a DO namespace. `idFromName` returns an opaque id;
  * `get(id)` returns a stub with `fetch` (matching the CF DO API).
@@ -38,6 +39,11 @@ export interface WorkerFetchDeps<Id = unknown> {
      * When omitted, the schedules response leaves the flag out.
      */
     schedulesEnabledByEnv?: boolean;
+    /**
+     * Optional persisted scheduler execution state read by
+     * `/api/schedules/:env`.
+     */
+    scheduleStateStore?: CfScheduleStateStore;
     /**
      * Tenant metadata stamped on event-triggered runs. Defaults to
      * `{ tenantId: "default", projectId: "default", organizationId: "default" }`.

package/dist/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAS7D;;;;GAIG;AACH,MAAM,WAAW,0BAA0B,CAAC,EAAE,GAAG,OAAO;IACtD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,CAAA;IAC5B,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG;QAAE,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAA;CACxD;AAED,MAAM,WAAW,eAAe,CAAC,EAAE,GAAG,OAAO;IAC3C,KAAK,EAAE,0BAA0B,CAAC,EAAE,CAAC,CAAA;IACrC;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,uBAAuB;IACvB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;IAC1B,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,eAAe,CAAA;IAC/B;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE;QACX,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,cAAc,EAAE,MAAM,CAAA;QACtB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF;AAED,wBAAsB,mBAAmB,CAAC,EAAE,EAC1C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,eAAe,CAAC,EAAE,CAAC,GACxB,OAAO,CAAC,QAAQ,CAAC,CAmNnB"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAQrE;;;;GAIG;AACH,MAAM,WAAW,0BAA0B,CAAC,EAAE,GAAG,OAAO;IACtD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,CAAA;IAC5B,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG;QAAE,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAA;CACxD;AAED,MAAM,WAAW,eAAe,CAAC,EAAE,GAAG,OAAO;IAC3C,KAAK,EAAE,0BAA0B,CAAC,EAAE,CAAC,CAAA;IACrC;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,uBAAuB;IACvB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;IAC1B,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,eAAe,CAAA;IAC/B;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,oBAAoB,CAAA;IACzC;;;;;OAKG;IACH,UAAU,CAAC,EAAE;QACX,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,cAAc,EAAE,MAAM,CAAA;QACtB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF;AAED,wBAAsB,mBAAmB,CAAC,EAAE,EAC1C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,eAAe,CAAC,EAAE,CAAC,GACxB,OAAO,CAAC,QAAQ,CAAC,CA4OnB"}

package/dist/worker.js

@@ -71,6 +71,7 @@ export async function handleWorkerRequest(req, deps) {
             return handleGetSchedules(env, {
                 manifestStore: deps.manifestStore,
                 schedulesEnabledByEnv: deps.schedulesEnabledByEnv,
+                scheduleStateStore: deps.scheduleStateStore,
                 now: deps.now,
                 logger: deps.logger,
             });
@@ -107,7 +108,32 @@ export async function handleWorkerRequest(req, deps) {
             headers: { "content-type": "application/json" },
             body: JSON.stringify({ ...publicPayload, runId }),
         });
-        return forwardToRunDO(runId, forward, deps);
+        const fireAt = deps.now ? deps.now() : Date.now();
+        const scheduleTrigger = getScheduleTrigger(publicPayload);
+        try {
+            const triggerRes = await forwardToRunDO(runId, forward, deps);
+            const runResult = triggerRes.ok ? await safeResponseJson(triggerRes.clone()) : undefined;
+            const runError = triggerRes.ok
+                ? failedRunError(runResult)
+                : `do_returned_${triggerRes.status}`;
+            await recordScheduleDispatch(deps, {
+                scheduleTrigger,
+                runId: triggerRes.ok ? runId : null,
+                fireAt,
+                error: runError,
+                lastSuccessfulRunAt: completedRunAt(runResult),
+            });
+            return triggerRes;
+        }
+        catch (err) {
+            await recordScheduleDispatch(deps, {
+                scheduleTrigger,
+                runId: null,
+                fireAt,
+                error: errMsg(err),
+            });
+            throw err;
+        }
     }
     // Everything below operates on a specific runId.
     const runMatch = url.pathname.match(/^\/api\/runs\/([^/]+)(\/.+)?$/);
@@ -368,6 +394,88 @@ function sanitizePublicTriggerPayload(payload) {
     const { initialJournal: _initialJournal, initialMetadataAppliedCount: _initialMetadataAppliedCount, timeoutMs: _timeoutMs, ...publicPayload } = payload;
     return publicPayload;
 }
+function getScheduleTrigger(payload) {
+    const triggeredBy = payload.triggeredBy;
+    const environment = payload.environment ?? "development";
+    if (typeof triggeredBy !== "object" ||
+        triggeredBy === null ||
+        !("kind" in triggeredBy) ||
+        triggeredBy.kind !== "schedule" ||
+        !("scheduleId" in triggeredBy) ||
+        typeof triggeredBy.scheduleId !== "string" ||
+        triggeredBy.scheduleId.length === 0 ||
+        (environment !== "production" && environment !== "preview" && environment !== "development")) {
+        return null;
+    }
+    return {
+        environment,
+        scheduleId: triggeredBy.scheduleId,
+    };
+}
+async function recordScheduleDispatch(deps, args) {
+    if (!deps.scheduleStateStore || !args.scheduleTrigger)
+        return;
+    try {
+        const existing = (await deps.scheduleStateStore.getStates(args.scheduleTrigger.environment, [
+            args.scheduleTrigger.scheduleId,
+        ])).get(args.scheduleTrigger.scheduleId);
+        await deps.scheduleStateStore.putState(args.scheduleTrigger.environment, {
+            ...existing,
+            scheduleId: args.scheduleTrigger.scheduleId,
+            environment: args.scheduleTrigger.environment,
+            lastFireAt: args.fireAt,
+            lastRunId: args.runId,
+            lastError: args.error,
+            ...(args.lastSuccessfulRunAt !== undefined
+                ? { lastSuccessfulRunAt: args.lastSuccessfulRunAt }
+                : {}),
+            updatedAt: deps.now ? deps.now() : Date.now(),
+        });
+    }
+    catch (err) {
+        deps.logger?.("warn", "schedules: cannot persist scheduler dispatch state", {
+            environment: args.scheduleTrigger.environment,
+            scheduleId: args.scheduleTrigger.scheduleId,
+            error: errMsg(err),
+        });
+    }
+}
+async function safeResponseJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+function completedRunAt(value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        "status" in value &&
+        value.status === "completed" &&
+        "completedAt" in value &&
+        typeof value.completedAt === "number" &&
+        Number.isFinite(value.completedAt)) {
+        return value.completedAt;
+    }
+    return undefined;
+}
+function failedRunError(value) {
+    if (typeof value !== "object" || value === null || !("status" in value))
+        return null;
+    const status = value.status;
+    if (status !== "failed" && status !== "compensation_failed")
+        return null;
+    const error = "error" in value ? value.error : undefined;
+    if (typeof error === "object" &&
+        error !== null &&
+        "message" in error &&
+        typeof error.message === "string" &&
+        error.message.length > 0) {
+        return error.message;
+    }
+    return `run_${status}`;
+}
 function json(status, body) {
     return new Response(JSON.stringify(body), {
         status,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/workflows-orchestrator-cloudflare",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "description": "Cloudflare Worker + Durable Object adapter for @voyantjs/workflows-orchestrator. Dispatches workflow-step requests to tenant Workers via a Workers-for-Platforms dispatch namespace.",
   "license": "Apache-2.0",
   "repository": {
@@ -26,8 +26,8 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@voyantjs/workflows-orchestrator": "0.86.0",
-    "@voyantjs/workflows": "0.86.0"
+    "@voyantjs/workflows-orchestrator": "0.88.0",
+    "@voyantjs/workflows": "0.88.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.15.1",

package/src/index.ts

@@ -83,6 +83,12 @@ export {
   type ScheduleListResponse,
   type ScheduleSummary,
 } from "./schedule-handler.js"
+export {
+  type CfScheduleStateStore,
+  type CreateKvScheduleStateStoreOptions,
+  createKvScheduleStateStore,
+  type ScheduleStateRecord,
+} from "./schedule-state-store.js"
 export * from "./types.js"
 export {
   type DurableObjectNamespaceLike,

package/src/schedule-handler.ts

@@ -1,20 +1,23 @@
 // HTTP handler for `/api/schedules/:env`. Reads the registered manifest
 // for the requested environment, projects each workflow's schedule blocks
-// into a flat list, and computes `nextRun` per entry via the same cron /
-// every / at logic the live scheduler uses.
-//
-// Aggregate "lastRun" is intentionally out of scope here — runs in the
-// Cloudflare orchestrator live in per-run Durable Objects, indexed by
-// runId, with no list-by-workflow path. The UI is expected to fetch
-// last-run state separately from the template-side `workflow-runs`
-// admin API (`/v1/admin/workflow-runs?workflowName=…&limit=1`).
-
-import type { ManifestSchedule, WorkflowManifest } from "@voyantjs/workflows/protocol"
+// into a flat list, computes `nextRun` per entry via the same cron / every /
+// at logic the live scheduler uses, and optionally merges persisted scheduler
+// dispatch state when a control plane provides it.
+
+import type { ManifestSchedule } from "@voyantjs/workflows/protocol"
 import { computeNextFire } from "@voyantjs/workflows-orchestrator"
 
 import type { CfManifestStore } from "./manifest-kv-store.js"
+import type { CfScheduleStateStore, ScheduleStateRecord } from "./schedule-state-store.js"
+
+const ALLOWED_ENVS = ["production", "preview", "development"] as const
 
-const ALLOWED_ENVS = new Set(["production", "preview", "development"])
+type AllowedEnvironment = (typeof ALLOWED_ENVS)[number]
+
+interface ManifestWorkflowScheduleEntry {
+  id: string
+  schedules: ManifestSchedule[]
+}
 
 export interface ScheduleHandlerDeps {
   manifestStore: CfManifestStore
@@ -28,6 +31,11 @@ export interface ScheduleHandlerDeps {
    * UIs can ignore the field.
    */
   schedulesEnabledByEnv?: boolean
+  /**
+   * Optional state store populated by the runtime scheduler/control plane.
+   * When present, each schedule row includes last-fire/run/error fields.
+   */
+  scheduleStateStore?: CfScheduleStateStore
   now?: () => number
   logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void
 }
@@ -45,6 +53,18 @@ export interface ScheduleSummary {
    */
   enabled: boolean
   disabledReason?: "registration_disabled" | "env_filtered"
+  /** Epoch millis of the last scheduler dispatch attempt, when known. */
+  lastFireAt?: number | null
+  /** Run id produced by the last scheduler dispatch attempt, when known. */
+  lastRunId?: string | null
+  /** Last scheduler dispatch/lock error, when known. */
+  lastError?: string | null
+  /** Epoch millis until which this schedule is locked, when known. */
+  lockedUntil?: number | null
+  /** Epoch millis of the last successful scheduled run, when known. */
+  lastSuccessfulRunAt?: number | null
+  /** Epoch millis when the persisted scheduler state was last updated. */
+  stateUpdatedAt?: number | null
 }
 
 export interface ScheduleListResponse {
@@ -62,10 +82,10 @@ export async function handleGetSchedules(
   environment: string,
   deps: ScheduleHandlerDeps,
 ): Promise<Response> {
-  if (!ALLOWED_ENVS.has(environment)) {
+  if (!isAllowedEnvironment(environment)) {
     return json(400, {
       error: "invalid_environment",
-      message: `environment must be one of ${[...ALLOWED_ENVS].join(", ")}`,
+      message: `environment must be one of ${ALLOWED_ENVS.join(", ")}`,
     })
   }
 
@@ -75,16 +95,14 @@ export async function handleGetSchedules(
   }
 
   const now = deps.now ? deps.now() : Date.now()
-  const manifest = envelope.manifest as unknown as WorkflowManifest
   const data: ScheduleSummary[] = []
 
-  for (const workflow of manifest.workflows ?? []) {
-    const schedules = Array.isArray(workflow.schedules) ? workflow.schedules : []
-    schedules.forEach((schedule, index) => {
+  for (const workflow of readManifestWorkflows(envelope.manifest)) {
+    workflow.schedules.forEach((schedule, index) => {
       const scheduleId = `${envelope.versionId}:${workflow.id}:${schedule.name ?? index}`
       const registrationDisabled = schedule.enabled === false
       const envFiltered = Array.isArray(schedule.environments)
-        ? !schedule.environments.includes(environment as never)
+        ? !schedule.environments.includes(environment)
         : false
 
       let nextRunAt: number | null = null
@@ -120,6 +138,22 @@ export async function handleGetSchedules(
     })
   }
 
+  if (deps.scheduleStateStore) {
+    const scheduleIds = data.map((row) => row.scheduleId)
+    let states = new Map<string, ScheduleStateRecord>()
+    try {
+      states = await deps.scheduleStateStore.getStates(environment, scheduleIds)
+    } catch (err) {
+      deps.logger?.("warn", "schedules: cannot load scheduler state", {
+        environment,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+    for (const row of data) {
+      attachState(row, states.get(row.scheduleId))
+    }
+  }
+
   const response: ScheduleListResponse = {
     environment,
     versionId: envelope.versionId,
@@ -131,6 +165,35 @@ export async function handleGetSchedules(
   return json(200, response)
 }
 
+function isAllowedEnvironment(value: string): value is AllowedEnvironment {
+  return ALLOWED_ENVS.includes(value as AllowedEnvironment)
+}
+
+function readManifestWorkflows(manifest: Record<string, unknown>): ManifestWorkflowScheduleEntry[] {
+  const workflows = manifest.workflows
+  if (!Array.isArray(workflows)) return []
+  return workflows.flatMap((workflow): ManifestWorkflowScheduleEntry[] => {
+    if (!isRecord(workflow) || typeof workflow.id !== "string") return []
+    const schedules = Array.isArray(workflow.schedules)
+      ? workflow.schedules.filter(isManifestSchedule)
+      : []
+    return [{ id: workflow.id, schedules }]
+  })
+}
+
+function isManifestSchedule(value: unknown): value is ManifestSchedule {
+  return isRecord(value)
+}
+
+function attachState(row: ScheduleSummary, state: ScheduleStateRecord | undefined): void {
+  row.lastFireAt = state?.lastFireAt ?? null
+  row.lastRunId = state?.lastRunId ?? null
+  row.lastError = state?.lastError ?? null
+  row.lockedUntil = state?.lockedUntil ?? null
+  row.lastSuccessfulRunAt = state?.lastSuccessfulRunAt ?? null
+  row.stateUpdatedAt = state?.updatedAt ?? null
+}
+
 function json(status: number, body: unknown): Response {
   return new Response(JSON.stringify(body), {
     status,
@@ -142,3 +205,7 @@ function json(status: number, body: unknown): Response {
     },
   })
 }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}

package/src/schedule-state-store.ts

@@ -0,0 +1,132 @@
+// KV-backed persisted state for workflow schedule dispatches.
+//
+// The manifest store answers "what schedules are registered?". This store
+// answers "what has the scheduler actually attempted recently?", keyed by
+// the stable schedule id emitted by manifestScheduleSources / schedule-handler.
+
+import type { KvNamespaceLike } from "./manifest-kv-store.js"
+
+export interface ScheduleStateRecord {
+  scheduleId: string
+  workflowId?: string
+  environment?: string
+  versionId?: string
+  lastFireAt?: number | null
+  lastRunId?: string | null
+  lastError?: string | null
+  lockedUntil?: number | null
+  lastSuccessfulRunAt?: number | null
+  updatedAt?: number | null
+}
+
+export interface CfScheduleStateStore {
+  getStates(
+    environment: string,
+    scheduleIds: readonly string[],
+  ): Promise<Map<string, ScheduleStateRecord>>
+  putState(environment: string, state: ScheduleStateRecord): Promise<void>
+}
+
+interface RawScheduleStateRecord {
+  scheduleId: string
+  workflowId?: unknown
+  environment?: unknown
+  versionId?: unknown
+  lastFireAt?: unknown
+  lastRunId?: unknown
+  lastError?: unknown
+  lockedUntil?: unknown
+  lastSuccessfulRunAt?: unknown
+  updatedAt?: unknown
+}
+
+export interface CreateKvScheduleStateStoreOptions {
+  kv: KvNamespaceLike
+}
+
+export function createKvScheduleStateStore(
+  opts: CreateKvScheduleStateStoreOptions,
+): CfScheduleStateStore {
+  const kv = opts.kv
+
+  return {
+    async getStates(environment, scheduleIds) {
+      const out = new Map<string, ScheduleStateRecord>()
+      await Promise.all(
+        scheduleIds.map(async (scheduleId) => {
+          const raw = await kv.get(scheduleStateKey(environment, scheduleId))
+          if (!raw) return
+          const parsed = parseScheduleState(raw)
+          if (!parsed || parsed.scheduleId !== scheduleId) return
+          out.set(scheduleId, parsed)
+        }),
+      )
+      return out
+    },
+
+    async putState(environment, state) {
+      await kv.put(
+        scheduleStateKey(environment, state.scheduleId),
+        JSON.stringify(normalizeScheduleState(environment, state)),
+      )
+    },
+  }
+}
+
+function scheduleStateKey(environment: string, scheduleId: string): string {
+  return `schedule-state:${environment}:${encodeURIComponent(scheduleId)}`
+}
+
+function parseScheduleState(raw: string): ScheduleStateRecord | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (!isRecord(parsed) || typeof parsed.scheduleId !== "string") return null
+    const state: RawScheduleStateRecord = {
+      scheduleId: parsed.scheduleId,
+      workflowId: typeof parsed.workflowId === "string" ? parsed.workflowId : undefined,
+      versionId: typeof parsed.versionId === "string" ? parsed.versionId : undefined,
+      lastFireAt: parsed.lastFireAt,
+      lastRunId: parsed.lastRunId,
+      lastError: parsed.lastError,
+      lockedUntil: parsed.lockedUntil,
+      lastSuccessfulRunAt: parsed.lastSuccessfulRunAt,
+      updatedAt: parsed.updatedAt,
+    }
+    return normalizeScheduleState(
+      typeof parsed.environment === "string" ? parsed.environment : undefined,
+      state,
+    )
+  } catch {
+    return null
+  }
+}
+
+function normalizeScheduleState(
+  environment: string | undefined,
+  state: RawScheduleStateRecord,
+): ScheduleStateRecord {
+  return {
+    scheduleId: state.scheduleId,
+    ...(typeof state.workflowId === "string" ? { workflowId: state.workflowId } : {}),
+    ...(environment !== undefined ? { environment } : {}),
+    ...(typeof state.versionId === "string" ? { versionId: state.versionId } : {}),
+    lastFireAt: nullableFiniteNumber(state.lastFireAt),
+    lastRunId: nullableString(state.lastRunId),
+    lastError: nullableString(state.lastError),
+    lockedUntil: nullableFiniteNumber(state.lockedUntil),
+    lastSuccessfulRunAt: nullableFiniteNumber(state.lastSuccessfulRunAt),
+    updatedAt: nullableFiniteNumber(state.updatedAt),
+  }
+}
+
+function nullableFiniteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null
+}
+
+function nullableString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}

package/src/worker.ts

@@ -23,6 +23,7 @@ import { handleIngestEvent } from "./event-handler.js"
 import { handleGetManifest, handleRegisterManifest } from "./manifest-handler.js"
 import type { CfManifestStore } from "./manifest-kv-store.js"
 import { handleGetSchedules } from "./schedule-handler.js"
+import type { CfScheduleStateStore } from "./schedule-state-store.js"
 
 const DEFAULT_TENANT_META = {
   tenantId: "default",
@@ -68,6 +69,11 @@ export interface WorkerFetchDeps<Id = unknown> {
    * When omitted, the schedules response leaves the flag out.
    */
   schedulesEnabledByEnv?: boolean
+  /**
+   * Optional persisted scheduler execution state read by
+   * `/api/schedules/:env`.
+   */
+  scheduleStateStore?: CfScheduleStateStore
   /**
    * Tenant metadata stamped on event-triggered runs. Defaults to
    * `{ tenantId: "default", projectId: "default", organizationId: "default" }`.
@@ -139,6 +145,7 @@ export async function handleWorkerRequest<Id>(
       return handleGetSchedules(env, {
         manifestStore: deps.manifestStore,
         schedulesEnabledByEnv: deps.schedulesEnabledByEnv,
+        scheduleStateStore: deps.scheduleStateStore,
         now: deps.now,
         logger: deps.logger,
       })
@@ -176,7 +183,31 @@ export async function handleWorkerRequest<Id>(
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ ...publicPayload, runId }),
     })
-    return forwardToRunDO(runId, forward, deps)
+    const fireAt = deps.now ? deps.now() : Date.now()
+    const scheduleTrigger = getScheduleTrigger(publicPayload)
+    try {
+      const triggerRes = await forwardToRunDO(runId, forward, deps)
+      const runResult = triggerRes.ok ? await safeResponseJson(triggerRes.clone()) : undefined
+      const runError = triggerRes.ok
+        ? failedRunError(runResult)
+        : `do_returned_${triggerRes.status}`
+      await recordScheduleDispatch(deps, {
+        scheduleTrigger,
+        runId: triggerRes.ok ? runId : null,
+        fireAt,
+        error: runError,
+        lastSuccessfulRunAt: completedRunAt(runResult),
+      })
+      return triggerRes
+    } catch (err) {
+      await recordScheduleDispatch(deps, {
+        scheduleTrigger,
+        runId: null,
+        fireAt,
+        error: errMsg(err),
+      })
+      throw err
+    }
   }
 
   // Everything below operates on a specific runId.
@@ -501,6 +532,108 @@ function sanitizePublicTriggerPayload(payload: Record<string, unknown>): Record<
   return publicPayload
 }
 
+function getScheduleTrigger(payload: Record<string, unknown>): {
+  environment: "production" | "preview" | "development"
+  scheduleId: string
+} | null {
+  const triggeredBy = payload.triggeredBy
+  const environment = payload.environment ?? "development"
+  if (
+    typeof triggeredBy !== "object" ||
+    triggeredBy === null ||
+    !("kind" in triggeredBy) ||
+    triggeredBy.kind !== "schedule" ||
+    !("scheduleId" in triggeredBy) ||
+    typeof triggeredBy.scheduleId !== "string" ||
+    triggeredBy.scheduleId.length === 0 ||
+    (environment !== "production" && environment !== "preview" && environment !== "development")
+  ) {
+    return null
+  }
+  return {
+    environment,
+    scheduleId: triggeredBy.scheduleId,
+  }
+}
+
+async function recordScheduleDispatch<Id>(
+  deps: WorkerFetchDeps<Id>,
+  args: {
+    scheduleTrigger: ReturnType<typeof getScheduleTrigger>
+    runId: string | null
+    fireAt: number
+    error: string | null
+    lastSuccessfulRunAt?: number
+  },
+): Promise<void> {
+  if (!deps.scheduleStateStore || !args.scheduleTrigger) return
+  try {
+    const existing = (
+      await deps.scheduleStateStore.getStates(args.scheduleTrigger.environment, [
+        args.scheduleTrigger.scheduleId,
+      ])
+    ).get(args.scheduleTrigger.scheduleId)
+    await deps.scheduleStateStore.putState(args.scheduleTrigger.environment, {
+      ...existing,
+      scheduleId: args.scheduleTrigger.scheduleId,
+      environment: args.scheduleTrigger.environment,
+      lastFireAt: args.fireAt,
+      lastRunId: args.runId,
+      lastError: args.error,
+      ...(args.lastSuccessfulRunAt !== undefined
+        ? { lastSuccessfulRunAt: args.lastSuccessfulRunAt }
+        : {}),
+      updatedAt: deps.now ? deps.now() : Date.now(),
+    })
+  } catch (err) {
+    deps.logger?.("warn", "schedules: cannot persist scheduler dispatch state", {
+      environment: args.scheduleTrigger.environment,
+      scheduleId: args.scheduleTrigger.scheduleId,
+      error: errMsg(err),
+    })
+  }
+}
+
+async function safeResponseJson(response: Response): Promise<unknown> {
+  try {
+    return await response.json()
+  } catch {
+    return undefined
+  }
+}
+
+function completedRunAt(value: unknown): number | undefined {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "status" in value &&
+    value.status === "completed" &&
+    "completedAt" in value &&
+    typeof value.completedAt === "number" &&
+    Number.isFinite(value.completedAt)
+  ) {
+    return value.completedAt
+  }
+  return undefined
+}
+
+function failedRunError(value: unknown): string | null {
+  if (typeof value !== "object" || value === null || !("status" in value)) return null
+  const status = value.status
+  if (status !== "failed" && status !== "compensation_failed") return null
+  const error = "error" in value ? value.error : undefined
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof error.message === "string" &&
+    error.message.length > 0
+  ) {
+    return error.message
+  }
+  return `run_${status}`
+}
+
 function json(status: number, body: unknown): Response {
   return new Response(JSON.stringify(body), {
     status,