@swirls/looms 0.4.0 → 0.5.1

package/dist/runtime/worker-callbacks.js

@@ -20,7 +20,19 @@ function workerStartedEvent(runId, item, attempt, retry, now) {
         origin: WORKER_ORIGIN,
     });
 }
-const IGNORED = { events: [], notices: [] };
+const STALE = {
+    events: [],
+    notices: [],
+    result: { status: 'stale', cancelRequested: false },
+};
+const CANCELLED = {
+    events: [],
+    notices: [],
+    result: { status: 'cancelled', cancelRequested: true },
+};
+function accepted(events, notices = [], cancelRequested = false) {
+    return { events, notices, result: { status: 'accepted', cancelRequested } };
+}
 /**
  * Turn a worker callback into events against the current durable state. Callbacks for another
  * attempt, a settled attempt, or an effect running in process are ignored.
@@ -32,6 +44,12 @@ function planWorkerCallback(input) {
     const isCancellationAcknowledgement = callback.kind === 'cancelled' &&
         execution?.attempt === callback.attempt &&
         execution.status === 'cancel_requested';
+    // A message already handed to a worker cannot be pulled back. Tell it to stop instead.
+    if (execution?.attempt === callback.attempt &&
+        execution.status === 'cancel_requested' &&
+        callback.kind !== 'cancelled') {
+        return Effect.succeed(CANCELLED);
+    }
     if (!execution ||
         execution.attempt !== callback.attempt ||
         (isRunTerminal(state) && !isCancellationAcknowledgement) ||
@@ -40,9 +58,8 @@ function planWorkerCallback(input) {
         execution.status === 'retry_wait' ||
         execution.status === 'timed_out' ||
         execution.status === 'ambiguous' ||
-        (callback.kind === 'cancelled' && !isCancellationAcknowledgement) ||
-        (execution.status === 'cancel_requested' && callback.kind !== 'cancelled')) {
-        return Effect.succeed(IGNORED);
+        (callback.kind === 'cancelled' && !isCancellationAcknowledgement)) {
+        return Effect.succeed(STALE);
     }
     const retry = item ? registry.effects.get(item.effect.type)?.retry : undefined;
     const notice = (type) => ({
@@ -55,55 +72,53 @@ function planWorkerCallback(input) {
     switch (callback.kind) {
         case 'started': {
             return Effect.succeed(item && execution.status === 'dispatched'
-                ? { events: [workerStartedEvent(runId, item, callback.attempt, retry, now)], notices: [] }
-                : IGNORED);
+                ? accepted([workerStartedEvent(runId, item, callback.attempt, retry, now)])
+                : STALE);
         }
         case 'heartbeat': {
             const implicitStart = execution.status === 'dispatched';
             if (!item ||
                 (!implicitStart && execution.status !== 'started' && execution.status !== 'heartbeat')) {
-                return Effect.succeed(IGNORED);
+                return Effect.succeed(STALE);
             }
-            return Effect.succeed({
-                events: [
-                    ...(implicitStart ? [workerStartedEvent(runId, item, callback.attempt, retry, now)] : []),
-                    createEvent(runId, {
-                        type: 'runtime.effect.heartbeat',
-                        payload: {
-                            effectId: item.effectId,
-                            attempt: callback.attempt,
-                            heartbeatAt: now,
-                            deadlineAt: workerDeadline(retry, execution.startedAt ?? now, now),
-                        },
-                        threadId: item.threadId,
-                        origin: WORKER_ORIGIN,
-                    }),
-                ],
-                notices: [notice('effect.heartbeat')],
-            });
+            const recorded = {
+                effectId: item.effectId,
+                attempt: callback.attempt,
+                heartbeatAt: now,
+                deadlineAt: workerDeadline(retry, execution.startedAt ?? now, now),
+            };
+            const payload = callback.details === undefined ? recorded : { ...recorded, details: callback.details };
+            return Effect.succeed(accepted([
+                ...(implicitStart
+                    ? [workerStartedEvent(runId, item, callback.attempt, retry, now)]
+                    : []),
+                createEvent(runId, {
+                    type: 'runtime.effect.heartbeat',
+                    payload,
+                    threadId: item.threadId,
+                    origin: WORKER_ORIGIN,
+                }),
+            ], [notice('effect.heartbeat')]));
         }
         case 'complete': {
             if (!item) {
-                return Effect.succeed(IGNORED);
+                return Effect.succeed(STALE);
             }
-            return Effect.forEach(callback.events, (event) => materializeEffectOutcome(registry.catalogs, runId, item, event)).pipe(Effect.map((outcomes) => ({
-                events: [
-                    ...outcomes,
-                    createEvent(runId, {
-                        type: 'runtime.effect.completed',
-                        payload: { effectId: item.effectId, attempt: callback.attempt },
-                        threadId: item.threadId,
-                        effectId: item.effectId,
-                        causationId: item.causingEventId,
-                        origin: WORKER_ORIGIN,
-                    }),
-                ],
-                notices: [],
-            })));
+            return Effect.forEach(callback.events, (event) => materializeEffectOutcome(registry.catalogs, runId, item, event)).pipe(Effect.map((outcomes) => accepted([
+                ...outcomes,
+                createEvent(runId, {
+                    type: 'runtime.effect.completed',
+                    payload: { effectId: item.effectId, attempt: callback.attempt },
+                    threadId: item.threadId,
+                    effectId: item.effectId,
+                    causationId: item.causingEventId,
+                    origin: WORKER_ORIGIN,
+                }),
+            ])));
         }
         case 'fail': {
             if (!item) {
-                return Effect.succeed(IGNORED);
+                return Effect.succeed(STALE);
             }
             const failure = planAttemptFailure({
                 runId,
@@ -113,36 +128,32 @@ function planWorkerCallback(input) {
                 now,
                 retry,
                 origin: WORKER_ORIGIN,
+                nonRetryable: callback.nonRetryable,
+                retryAfterMs: callback.retryAfterMs,
             });
-            return Effect.succeed({
-                events: [failure.event],
-                notices: failure.retrying
-                    ? [
-                        {
-                            type: 'effect.retry',
-                            runId,
-                            at: now,
-                            effectId: item.effectId,
-                            attempt: callback.attempt,
-                            detail: callback.error,
-                        },
-                    ]
-                    : [],
-            });
+            return Effect.succeed(accepted([failure.event], failure.retrying
+                ? [
+                    {
+                        type: 'effect.retry',
+                        runId,
+                        at: now,
+                        effectId: item.effectId,
+                        attempt: callback.attempt,
+                        detail: callback.error,
+                    },
+                ]
+                : []));
         }
         case 'cancelled': {
-            return Effect.succeed({
-                events: [
-                    createEvent(runId, {
-                        type: 'runtime.effect.cancelled',
-                        payload: { effectId: callback.effectId, attempt: callback.attempt },
-                        threadId: item?.threadId ?? null,
-                        effectId: callback.effectId,
-                        origin: WORKER_ORIGIN,
-                    }),
-                ],
-                notices: [notice('effect.cancellation')],
-            });
+            return Effect.succeed(accepted([
+                createEvent(runId, {
+                    type: 'runtime.effect.cancelled',
+                    payload: { effectId: callback.effectId, attempt: callback.attempt },
+                    threadId: item?.threadId ?? null,
+                    effectId: callback.effectId,
+                    origin: WORKER_ORIGIN,
+                }),
+            ], [notice('effect.cancellation')], true));
         }
         default: {
             const exhaustiveCheck = callback;
@@ -155,13 +166,32 @@ export function createWorkerCallbacks(options) {
     const applyWorkerCallback = (runId, callback) => withRunIngress(runId, Effect.gen(function* () {
         const store = yield* EventStoreTag;
         const now = yield* Clock.currentTimeMillis;
-        const committed = yield* repository.commit(store, runId, (cursor) => planWorkerCallback({ runId, state: cursor.state, callback, registry, now }).pipe(Effect.map((plan) => ({ events: plan.events, value: plan.notices }))));
+        const committed = yield* repository.commit(store, runId, (cursor) => planWorkerCallback({ runId, state: cursor.state, callback, registry, now }).pipe(Effect.map((plan) => ({
+            events: plan.events,
+            value: { notices: plan.notices, result: plan.result },
+        }))));
         if (committed.append) {
-            for (const notice of committed.value) {
+            for (const notice of committed.value.notices) {
                 notifyObserver(options.observer, notice);
             }
         }
-        return committed.cursor.state;
-    })).pipe(Effect.andThen(options.wake(runId)));
-    return { workerCallback: applyWorkerCallback };
+        return committed.value.result;
+    })).pipe(Effect.tap((result) => (result.status === 'stale' ? Effect.void : options.wake(runId))));
+    const workerSecrets = (runId, callback) => Effect.gen(function* () {
+        const store = yield* EventStoreTag;
+        const { state } = yield* repository.loadCursor(store, runId);
+        const execution = state.effectExecutions[callback.effectId];
+        if (execution?.attempt !== callback.attempt || isRunTerminal(state)) {
+            return { status: 'stale' };
+        }
+        if (execution.status === 'cancel_requested') {
+            return { status: 'cancelled' };
+        }
+        if (execution.status !== 'started' && execution.status !== 'heartbeat') {
+            return { status: 'stale' };
+        }
+        const secrets = store.runSecrets ? yield* store.runSecrets.get(runId) : {};
+        return { status: 'accepted', secrets };
+    });
+    return { workerCallback: applyWorkerCallback, workerSecrets };
 }

package/dist/runtime/worker-effect-dispatch.d.ts

@@ -1,11 +1,12 @@
 import { Effect } from 'effect';
-import { type ComposedRegistry, type EffectExecutionRecord, type EventEnvelope, type OutstandingEffect, type RunState } from '@swirls/looms/core';
+import { type ComposedRegistry, type EffectExecutionRecord, type EventEnvelope, type OutstandingEffect, type RetryPolicy, type RunState, type SecretContext } from '@swirls/looms/core';
 import type { EffectWorker, EffectWorkerTask } from './types';
 export interface WorkerEffectDispatchPlan {
     readonly item: OutstandingEffect;
     readonly attempt: number;
     readonly queuedEvent?: EventEnvelope;
     readonly task: EffectWorkerTask;
+    readonly retry: RetryPolicy | undefined;
     readonly scheduleToStartDeadlineAt: number | null;
 }
 /**
@@ -27,10 +28,18 @@ export declare function planWorkerEffects(input: {
     readonly registry: ComposedRegistry;
     readonly worker?: EffectWorker;
     readonly now: number;
+    readonly maxInFlightWorkerEffects?: number;
+    readonly secrets?: SecretContext;
 }): ReadonlyArray<WorkerEffectDispatchPlan>;
 /**
- * Hand a planned attempt to the worker. A rejected dispatch may still have reached the worker, so
- * with a schedule-to-start deadline it is recorded as dispatched and recovered by that timeout;
- * without one it is parked as ambiguous for an operator.
+ * Hand a planned attempt to the worker. When an unacknowledged dispatch rejects, the task may still
+ * have reached the worker, so with a schedule-to-start deadline it is recorded as dispatched and
+ * recovered by that timeout; without one it is parked as ambiguous for an operator. An acknowledged
+ * rejection means nothing was sent, so the attempt fails under the retry policy.
  */
-export declare function dispatchWorkerEffect(runId: string, plan: WorkerEffectDispatchPlan, worker: EffectWorker | undefined): Effect.Effect<EventEnvelope>;
+export declare function dispatchWorkerEffect(runId: string, plan: WorkerEffectDispatchPlan, worker: EffectWorker | undefined, now: number): Effect.Effect<EventEnvelope>;
+/**
+ * An acknowledged transport can lose a message it accepted, for example to a dead-letter queue.
+ * Only a schedule-to-start timeout notices, so every effect such a worker claims needs one.
+ */
+export declare function assertWorkerDeadlines(registry: ComposedRegistry, worker: EffectWorker | undefined): void;

package/dist/runtime/worker-effect-dispatch.js

@@ -1,7 +1,8 @@
 import { Effect, Predicate } from 'effect';
-import { createEvent, isPrimitiveEffect, } from '@swirls/looms/core';
+import { createEvent, deferredUntil, isPrimitiveEffect, } from '@swirls/looms/core';
 import { RuntimeExecutionError } from './errors.js';
 import { workerTask } from './helpers.js';
+import { planAttemptFailure } from './retry-policy.js';
 function workerClaims(worker, runId, item) {
     if (!worker.handles && !worker.canDispatch) {
         return undefined;
@@ -52,25 +53,30 @@ export function isWorkerEffect(input) {
     return worker !== undefined && claim !== false;
 }
 export function planWorkerEffects(input) {
-    return input.state.outstandingEffects
-        .filter((item) => {
-        const execution = input.state.effectExecutions[item.effectId];
-        if (!isWorkerEffect({ ...input, item, execution })) {
+    const workerItems = input.state.outstandingEffects.filter((item) => isWorkerEffect({ ...input, item, execution: input.state.effectExecutions[item.effectId] }));
+    const due = workerItems.filter((item) => {
+        const dueAt = deferredUntil(item.effect);
+        if (dueAt !== undefined && dueAt > input.now + 5) {
             return false;
         }
+        const execution = input.state.effectExecutions[item.effectId];
         return (!execution ||
             execution.status === 'queued' ||
             (execution.status === 'retry_wait' &&
                 execution.nextAttemptAt !== null &&
                 execution.nextAttemptAt <= input.now + 5));
-    })
-        .map((item) => {
+    });
+    return withinInFlightLimit(input, workerItems, due).map((item) => {
         const existing = input.state.effectExecutions[item.effectId];
         const attempt = existing?.status === 'queued' ? existing.attempt : (existing?.attempt ?? 0) + 1;
         const retry = input.registry.effects.get(item.effect.type)?.retry;
+        const scheduleToStartDeadlineAt = retry?.scheduleToStartTimeoutMs
+            ? input.now + retry.scheduleToStartTimeoutMs
+            : null;
         return {
             item,
             attempt,
+            retry,
             queuedEvent: existing?.status === 'queued'
                 ? undefined
                 : createEvent(input.runId, {
@@ -80,19 +86,41 @@ export function planWorkerEffects(input) {
                     causationId: item.causingEventId,
                     origin: { type: 'system' },
                 }),
-            task: workerTask(input.runId, item, attempt),
-            scheduleToStartDeadlineAt: retry?.scheduleToStartTimeoutMs
-                ? input.now + retry.scheduleToStartTimeoutMs
-                : null,
+            task: workerTask(input.runId, item, attempt, {
+                details: existing?.heartbeatDetails,
+                secrets: input.secrets,
+                trace: input.state.startIdentity?.trace,
+                retry,
+                scheduleToStartAt: scheduleToStartDeadlineAt,
+            }),
+            scheduleToStartDeadlineAt,
         };
     });
 }
+const IN_FLIGHT_STATUSES = new Set([
+    'dispatched',
+    'started',
+    'heartbeat',
+    'cancel_requested',
+]);
+function withinInFlightLimit(input, workerItems, due) {
+    const max = input.maxInFlightWorkerEffects;
+    if (max === undefined || max <= 0) {
+        return due;
+    }
+    const inFlight = workerItems.filter((item) => {
+        const status = input.state.effectExecutions[item.effectId]?.status;
+        return status !== undefined && IN_FLIGHT_STATUSES.has(status);
+    }).length;
+    return due.slice(0, Math.max(0, max - inFlight));
+}
 /**
- * Hand a planned attempt to the worker. A rejected dispatch may still have reached the worker, so
- * with a schedule-to-start deadline it is recorded as dispatched and recovered by that timeout;
- * without one it is parked as ambiguous for an operator.
+ * Hand a planned attempt to the worker. When an unacknowledged dispatch rejects, the task may still
+ * have reached the worker, so with a schedule-to-start deadline it is recorded as dispatched and
+ * recovered by that timeout; without one it is parked as ambiguous for an operator. An acknowledged
+ * rejection means nothing was sent, so the attempt fails under the retry policy.
  */
-export function dispatchWorkerEffect(runId, plan, worker) {
+export function dispatchWorkerEffect(runId, plan, worker, now) {
     const dispatched = createEvent(runId, {
         type: 'runtime.effect.dispatched',
         payload: {
@@ -118,9 +146,47 @@ export function dispatchWorkerEffect(runId, plan, worker) {
         try: () => Promise.resolve(worker.dispatch(plan.task)),
         catch: (cause) => new RuntimeExecutionError(cause instanceof Error ? cause.message : String(cause)),
     }).pipe(Effect.match({
-        onFailure: (error) => plan.scheduleToStartDeadlineAt === null
-            ? ambiguous(`worker dispatch outcome is ambiguous: ${error.message}`)
-            : dispatched,
+        onFailure: (error) => {
+            if (worker.dispatchSemantics === 'acknowledged') {
+                return planAttemptFailure({
+                    runId,
+                    item: plan.item,
+                    attempt: plan.attempt,
+                    error: `worker dispatch failed: ${error.message}`,
+                    now,
+                    retry: plan.retry,
+                    origin: { type: 'system' },
+                }).event;
+            }
+            return plan.scheduleToStartDeadlineAt === null
+                ? ambiguous(`worker dispatch outcome is ambiguous: ${error.message}`)
+                : dispatched;
+        },
         onSuccess: () => dispatched,
     }));
 }
+/**
+ * An acknowledged transport can lose a message it accepted, for example to a dead-letter queue.
+ * Only a schedule-to-start timeout notices, so every effect such a worker claims needs one.
+ */
+export function assertWorkerDeadlines(registry, worker) {
+    if (worker?.dispatchSemantics !== 'acknowledged') {
+        return;
+    }
+    const missing = [...registry.effects.values()]
+        .filter((definition) => claimsType(worker, definition) && !definition.retry?.scheduleToStartTimeoutMs)
+        .map((definition) => definition.type);
+    if (missing.length > 0) {
+        throw new Error(`An acknowledged worker claims effects without retry.scheduleToStartTimeoutMs: ${missing.join(', ')}`);
+    }
+}
+function claimsType(worker, definition) {
+    if (definition.execution) {
+        return definition.execution === 'worker';
+    }
+    const { handles } = worker;
+    const handled = Predicate.isFunction(handles)
+        ? handles(definition.type)
+        : (handles?.includes(definition.type) ?? false);
+    return handled || !definition.hasHandler;
+}

package/dist/schedule/debugger/index.d.ts

@@ -0,0 +1,4 @@
+import type { DebuggerPlugin } from '@swirls/looms/debugger';
+import { ScheduleView } from './schedule-view';
+export declare const scheduleDebugger: DebuggerPlugin;
+export { ScheduleView };

package/dist/schedule/debugger/index.js

@@ -0,0 +1,11 @@
+import { scheduleStatus } from '../projections.js';
+import { ScheduleView } from './schedule-view.js';
+import { summarizeScheduleEvent } from './summarize.js';
+export const scheduleDebugger = {
+    name: 'schedule',
+    families: [
+        { family: 'schedule', color: 'oklch(0.72 0.12 210)', summarize: summarizeScheduleEvent },
+    ],
+    projections: [{ name: scheduleStatus.name, component: ScheduleView }],
+};
+export { ScheduleView };

package/dist/schedule/debugger/schedule-view.d.ts

@@ -0,0 +1,3 @@
+export declare function ScheduleView({ runId }: {
+    runId: string;
+}): import("react").JSX.Element;

package/dist/schedule/debugger/schedule-view.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Button, StatusBadge, useDebugger } from '@swirls/looms/debugger';
+import { useProjection, useRunStore } from '@swirls/looms/react';
+import { scheduleStatus } from '../projections.js';
+import { pause, resume, trigger } from '../signals.js';
+import { describeSpec, nextFireAt } from '../specs.js';
+export function ScheduleView({ runId }) {
+    const { client, openRun } = useDebugger();
+    const store = useRunStore(runId);
+    const state = useProjection(store, scheduleStatus);
+    const now = useNow(state.status === 'running' && state.nextAt !== null);
+    if (!state.spec && state.recent.length === 0) {
+        return _jsx("p", { className: "text-muted-foreground text-xs", children: "No schedule yet." });
+    }
+    const upcoming = state.spec ? upcomingFires(state.spec, state.nextAt) : [];
+    const remaining = state.nextAt === null ? null : state.nextAt - now;
+    return (_jsxs("div", { className: "grid gap-3 text-xs", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "min-w-0 flex-1 truncate font-medium", children: state.spec ? describeSpec(state.spec) : 'Schedule' }), _jsx(StatusBadge, { status: state.status })] }), _jsx("p", { className: "text-muted-foreground", children: state.status === 'paused' || state.status === 'retired'
+                    ? 'No alarm is set.'
+                    : remaining === null
+                        ? 'Nothing further is scheduled.'
+                        : `Next fire ${formatRemaining(remaining)}.` }), state.status === 'running' || state.status === 'paused' ? (_jsxs("div", { className: "flex gap-1.5", children: [state.status === 'paused' ? (_jsx(Button, { size: "xs", onClick: () => void client.signal(runId, [resume()]), children: "Resume" })) : (_jsx(Button, { size: "xs", variant: "outline", onClick: () => void client.signal(runId, [pause()]), children: "Pause" })), _jsx(Button, { size: "xs", variant: "outline", onClick: () => void client.signal(runId, [trigger()]), children: "Fire now" })] })) : null, upcoming.length > 0 ? (_jsx("ol", { className: "text-muted-foreground grid gap-1", children: upcoming.map((at) => (_jsx("li", { children: formatInstant(at) }, at))) })) : null, state.recent.length > 0 ? (_jsx("ul", { className: "grid gap-1", children: state.recent.map((item, index) => (_jsxs("li", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-muted-foreground w-14 shrink-0", children: item.outcome === 'fired' ? 'Fired' : 'Skipped' }), item.runId && openRun ? (_jsx("button", { type: "button", className: "truncate text-left underline-offset-2 hover:underline", onClick: () => openRun(item.runId ?? ''), children: item.runId })) : (_jsx("span", { className: "truncate", children: item.reason ?? item.runId ?? 'held' }))] }, `${item.at}-${index}`))) })) : null] }));
+}
+function upcomingFires(spec, nextAt) {
+    if (nextAt === null) {
+        return [];
+    }
+    const times = [nextAt];
+    let cursor = nextAt;
+    while (times.length < 5) {
+        const next = nextFireAt(spec, cursor);
+        if (next === null) {
+            break;
+        }
+        times.push(next);
+        cursor = next;
+    }
+    return times;
+}
+function useNow(active) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        if (!active) {
+            return undefined;
+        }
+        setNow(Date.now());
+        const timer = setInterval(() => setNow(Date.now()), 1_000);
+        return () => clearInterval(timer);
+    }, [active]);
+    return now;
+}
+function formatRemaining(ms) {
+    if (ms <= 0) {
+        return 'is due';
+    }
+    const seconds = Math.ceil(ms / 1_000);
+    if (seconds < 60) {
+        return `in ${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) {
+        return `in ${minutes}m`;
+    }
+    return `in ${Math.floor(minutes / 60)}h`;
+}
+function formatInstant(at) {
+    return new Date(at).toISOString().replace('.000Z', 'Z');
+}

package/dist/schedule/debugger/summarize.d.ts

@@ -0,0 +1,2 @@
+import { type DebuggerEvent, type EventSummary } from '@swirls/looms/debugger';
+export declare function summarizeScheduleEvent(event: DebuggerEvent): EventSummary | undefined;

package/dist/schedule/debugger/summarize.js

@@ -0,0 +1,43 @@
+import { jsonFields, jsonNumberText, jsonText, } from '@swirls/looms/debugger';
+import { describeSpec } from '../specs.js';
+export function summarizeScheduleEvent(event) {
+    const payload = jsonFields(event.payload);
+    switch (event.type) {
+        case 'schedule.planned':
+            return { title: 'fire planned', detail: jsonNumberText(payload.nextAt) };
+        case 'schedule.fired':
+            return {
+                title: payload.manual === true ? 'fired manually' : 'fired',
+                detail: jsonText(payload.runId),
+            };
+        case 'schedule.skipped':
+            return { title: 'fire skipped', detail: jsonText(payload.reason) };
+        case 'schedule.updated':
+            return {
+                title: 'schedule updated',
+                detail: payload.spec === undefined ? undefined : specDetail(payload.spec),
+            };
+        case 'schedule.paused':
+            return { title: 'schedule paused' };
+        case 'schedule.resumed':
+            return { title: 'schedule resumed' };
+        case 'schedule.retired':
+            return { title: 'schedule retired' };
+        case 'schedule.triggered':
+            return { title: 'manual fire requested' };
+        case 'schedule.rejected':
+            return { title: 'update rejected', detail: jsonText(payload.reason) };
+        default:
+            return undefined;
+    }
+}
+function specDetail(value) {
+    if (!isSpec(value)) {
+        return undefined;
+    }
+    return describeSpec(value);
+}
+function isSpec(value) {
+    const fields = jsonFields(value);
+    return fields.type === 'cron' || fields.type === 'every' || fields.type === 'once';
+}

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

@@ -0,0 +1,10 @@
+import { Context, Layer } from 'effect';
+import { type DefinitionStore } from '@swirls/looms/core';
+import type { ScheduleDefinition } from './definitions';
+export type ScheduleDefinitionStore = DefinitionStore<ScheduleDefinition>;
+declare const ScheduleDefinitionsTag_base: Context.ServiceClass<ScheduleDefinitionsTag, "looms/ScheduleDefinitions", ScheduleDefinitionStore>;
+export declare class ScheduleDefinitionsTag extends ScheduleDefinitionsTag_base {
+}
+export declare function makeScheduleDefinitionStore(definitions: ReadonlyArray<ScheduleDefinition>): ScheduleDefinitionStore;
+export declare const ScheduleDefinitionsLive: (definitions: ScheduleDefinitionStore) => Layer.Layer<ScheduleDefinitionsTag, never, never>;
+export {};

package/dist/schedule/definitions-store.js

@@ -0,0 +1,8 @@
+import { Context, Layer } from 'effect';
+import { makeDefinitionStore } from '@swirls/looms/core';
+export class ScheduleDefinitionsTag extends Context.Service()('looms/ScheduleDefinitions') {
+}
+export function makeScheduleDefinitionStore(definitions) {
+    return makeDefinitionStore('schedule', definitions);
+}
+export const ScheduleDefinitionsLive = (definitions) => Layer.succeed(ScheduleDefinitionsTag, definitions);

package/dist/schedule/definitions.d.ts

@@ -0,0 +1,57 @@
+import { Schema } from 'effect';
+import { type DefinitionRef, type JsonValue } from '@swirls/looms/core';
+import { type ScheduleSpec } from './specs';
+export declare const ScheduleMisfireSchema: Schema.Union<readonly [Schema.Literal<"fire-once">, Schema.Literal<"skip">]>;
+export type ScheduleMisfire = Schema.Schema.Type<typeof ScheduleMisfireSchema>;
+export declare const ScheduleOverlapSchema: Schema.Union<readonly [Schema.Literal<"allow">, Schema.Literal<"skip">]>;
+export type ScheduleOverlap = Schema.Schema.Type<typeof ScheduleOverlapSchema>;
+export declare const ScheduleStartSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly spec: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"cron">;
+        readonly expr: Schema.String;
+        readonly tz: Schema.optional<Schema.String>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"every">;
+        readonly everyMs: Schema.Finite;
+        readonly anchor: Schema.optional<Schema.Finite>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"once">;
+        readonly at: Schema.Finite;
+    }>]>>;
+    readonly input: Schema.optional<Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly startAt: Schema.optional<Schema.NullOr<Schema.Finite>>;
+    readonly endAt: Schema.optional<Schema.NullOr<Schema.Finite>>;
+    readonly maxFires: Schema.optional<Schema.NullOr<Schema.Finite>>;
+}>, Schema.Null]>;
+export type ScheduleStart = Schema.Schema.Type<typeof ScheduleStartSchema>;
+/** What a fire effect knows when it builds the target input or asks `beforeFire`. */
+export interface FireContext {
+    readonly at: number;
+    readonly input: JsonValue | null;
+    readonly runId: string;
+    readonly manual: boolean;
+}
+export type BeforeFireResult = 'fire' | {
+    readonly skip: string;
+};
+export interface ScheduleDefinition<TName extends string = string> extends DefinitionRef {
+    readonly kind: 'schedule';
+    readonly name: TName;
+    readonly version: string;
+    readonly description?: string;
+    readonly input?: typeof ScheduleStartSchema;
+    readonly target: DefinitionRef;
+    readonly spec: ScheduleSpec;
+    readonly misfire: ScheduleMisfire;
+    readonly overlap: ScheduleOverlap;
+    readonly fireInput?: (ctx: FireContext) => JsonValue | Promise<JsonValue>;
+    readonly beforeFire?: (ctx: FireContext) => BeforeFireResult | Promise<BeforeFireResult>;
+}
+export type AnyScheduleDefinition = ScheduleDefinition;
+export declare function defineSchedule<TName extends string>(def: Omit<ScheduleDefinition<TName>, 'kind' | 'version' | 'input' | 'misfire' | 'overlap' | 'fireInput'> & {
+    readonly version?: string;
+    readonly misfire?: ScheduleMisfire;
+    readonly overlap?: ScheduleOverlap;
+    /** Builds the target run's input at fire time. Defaults to the stored start input. */
+    readonly input?: (ctx: FireContext) => JsonValue | Promise<JsonValue>;
+}): ScheduleDefinition<TName>;