@smthrs/triggers 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/Scheduler.js

@@ -0,0 +1,734 @@
+/**
+ * Durable, Clock-driven trigger scheduling.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ *
+ * @since 0.1.0
+ */
+import * as Control from "@smthrs/control/Control";
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Metric from "effect/Metric";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Semaphore from "effect/Semaphore";
+import * as ActiveRuns from "./internal/ActiveRuns.js";
+import * as DueOccurrences from "./internal/DueOccurrences.js";
+import { TriggerError } from "./TriggerError.js";
+import { isReservation, reservationOccurrence, TriggerStore } from "./TriggerStore.js";
+/**
+ * Injectable scheduled-run launcher.
+ *
+ * Constructed with {@link makeRunner}, {@link makeNoopRunner}, or
+ * {@link layerNoopRunner}; the tag itself carries no constructors, so there is
+ * one spelling of each and the module's own `make`/`makeNoop` can only mean
+ * the scheduler.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class Runner extends Context.Service()("flows/triggers/Scheduler/Runner") {
+}
+/**
+ * Constructs a scheduled-run launcher.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeRunner = (implementation) => Runner.of(implementation);
+/**
+ * Constructs a launcher that returns the idempotency key as a terminal run.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoopRunner = (overrides = {}) => makeRunner({
+    start: (input) => Effect.succeed(input.idempotencyKey),
+    inspect: () => Effect.succeed("completed"),
+    cancel: () => Effect.void,
+    ...overrides
+});
+/**
+ * Provides the terminal no-op launcher.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoopRunner = (overrides = {}) => Layer.succeed(Runner)(makeNoopRunner(overrides));
+const runnerError = (message, cause) => new TriggerError({
+    code: "runner",
+    message,
+    ...(cause === undefined ? {} : { cause })
+});
+const translateRunnerFailure = (effect, message) => effect.pipe(Effect.mapError((error) => error instanceof TriggerError ? error : runnerError(message, error)), Effect.catchDefect((defect) => Effect.fail(runnerError(message, defect))));
+const invalidOption = (field, requirement) => new TriggerError({
+    code: "invalid_options",
+    message: `${field} must be ${requirement}`,
+    path: field
+});
+const duration = (input, field) => Option.match(Duration.fromInput(input), {
+    onNone: () => Effect.fail(invalidOption(field, "a valid Effect duration")),
+    onSome: (value) => 
+    // Zero polls a CPU-tight loop and an infinite interval never completes,
+    // and `Duration.fromInput` accepts both.
+    Duration.isFinite(value) && Duration.toMillis(value) > 0
+        ? Effect.succeed(value)
+        : Effect.fail(invalidOption(field, "a finite positive duration"))
+});
+const stoppedMessage = (runId, state) => {
+    switch (state) {
+        case "failed":
+            return `Run ${runId} failed`;
+        case "cancelled":
+            return `Run ${runId} was cancelled`;
+        case "missing":
+            return `Run ${runId} is unknown to the runner`;
+    }
+};
+const runIdFromReceipt = (receipt) => {
+    switch (receipt._tag) {
+        case "Accepted":
+        case "AlreadyApplied":
+            return receipt.runId === undefined
+                ? Effect.fail(runnerError(`Control ${receipt._tag} receipt did not include a run id`))
+                : Effect.succeed(receipt.runId);
+        case "Terminal":
+            return Effect.succeed(receipt.runId);
+        case "Conflict":
+            return Effect.fail(runnerError(`Control rejected the scheduled run: ${receipt.message}`));
+    }
+};
+/**
+ * How many times a parked plan is re-offered before the launch is abandoned.
+ *
+ * The delay doubles from one second, so the eighth attempt lands a little over
+ * two minutes in. A plan nobody approves used to be re-offered once a second
+ * for the life of the scope while the launch reservation behind it expired.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const parkedAttempts = 8;
+const runApprovedPlan = (control, plan, key, attempt) => control.run({
+    _tag: "Plan",
+    planId: plan.planId,
+    digest: plan.digest,
+    envelope: plan.envelope,
+    idempotencyKey: key
+}).pipe(Effect.mapError((error) => runnerError("Control could not launch the scheduled run", error)), Effect.flatMap((receipt) => {
+    if (receipt._tag !== "Parked")
+        return runIdFromReceipt(receipt);
+    if (attempt >= parkedAttempts) {
+        return Effect.fail(runnerError(`Control plan ${plan.planId} is still parked awaiting approval after ${attempt} attempts`));
+    }
+    return Effect.logInfo(`A scheduled plan is parked awaiting approval, attempt ${attempt}`).pipe(Effect.andThen(Effect.sleep(Duration.millis(1000 * 2 ** (attempt - 1)))), Effect.andThen(Effect.suspend(() => runApprovedPlan(control, plan, key, attempt + 1))));
+}));
+/**
+ * The statuses that mean a run has stopped for good.
+ *
+ * Liveness is stated as the complement of this set rather than as a list of
+ * live statuses, so a status Control adds later is treated as live until this
+ * package says otherwise. Reading it the other way round is what dropped
+ * `accepted`, the status every run holds between its claim and its first
+ * executed step (`packages/smithers/control/src/ControlLive.ts`).
+ */
+const settledState = (status) => status === "cancelled" || status === "completed" || status === "failed" ? status : undefined;
+/**
+ * Runner layer backed by the authoritative Control plan/run/list/cancel API.
+ *
+ * A parked plan waits for approval and retries the same idempotent run request
+ * a bounded number of times; this adapter never approves it or reconstructs an
+ * execution envelope.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerControlRunner = Layer.effect(Runner, Effect.gen(function* () {
+    const control = yield* Control.Control;
+    return makeRunner({
+        start: (input) => translateRunnerFailure(control.plan(input).pipe(Effect.flatMap((plan) => runApprovedPlan(control, plan, input.idempotencyKey, 1))), "Control could not launch the scheduled run"),
+        inspect: (runId) => translateRunnerFailure(control.list({ _tag: "runs", filters: { runId }, limit: 1 }).pipe(Effect.map((response) => {
+            const run = response._tag === "runs"
+                ? response.items.find((candidate) => candidate.runId === runId)
+                : undefined;
+            if (run === undefined)
+                return "missing";
+            return settledState(run.status) ?? "active";
+        })), `Control could not inspect run ${runId}`),
+        cancel: (runId) => translateRunnerFailure(control.cancel({
+            runId,
+            idempotencyKey: `trigger-cancel:${runId}`
+        }).pipe(Effect.flatMap((receipt) => {
+            switch (receipt._tag) {
+                case "Accepted":
+                case "AlreadyApplied":
+                case "Terminal":
+                    return Effect.void;
+                case "Conflict":
+                    return Effect.fail(runnerError(`Control refused scheduled cancellation: ${receipt.message}`));
+                case "Parked":
+                    return Effect.fail(runnerError(`Control returned a Parked receipt for cancellation of run ${runId}`));
+            }
+        })), `Control could not cancel run ${runId}`)
+    });
+}));
+/**
+ * The heartbeat host name a scheduler records under when its options name
+ * none.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const defaultHost = "local";
+/**
+ * How many triggers one tick processes at the same time when its options name
+ * no `concurrency`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const defaultConcurrency = 4;
+/**
+ * How long settled fire ledger rows are kept when the options name no
+ * `fireRetention`: thirty days.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export const defaultFireRetention = Duration.days(30);
+const pruneEvery = 60 * 60 * 1_000;
+/**
+ * Histogram boundaries, in milliseconds, of `smithers.triggers.tick_duration_ms`
+ * and `smithers.triggers.launch_duration_ms`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export const durationBoundaries = [10, 100, 1_000, 10_000, 60_000, 300_000];
+const firesRecorded = Metric.counter("smithers.triggers.fires");
+const tickDuration = Metric.histogram("smithers.triggers.tick_duration_ms", { boundaries: durationBoundaries });
+const launchDuration = Metric.histogram("smithers.triggers.launch_duration_ms", { boundaries: durationBoundaries });
+const timed = (histogram, effect) => Effect.gen(function* () {
+    const started = yield* Clock.currentTimeMillis;
+    return yield* effect.pipe(Effect.ensuring(Effect.flatMap(Clock.currentTimeMillis, (ended) => Metric.update(histogram, ended - started))));
+});
+const deadline = (effect, limit, what) => Effect.timeoutOrElse(effect, {
+    duration: limit,
+    orElse: () => Effect.fail(new TriggerError({
+        code: "runner_timeout",
+        message: `${what} did not answer within ${Duration.toMillis(limit)} ms`
+    }))
+});
+/**
+ * The live trigger scheduler.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class Scheduler extends Context.Service()("flows/triggers/Scheduler") {
+}
+/** Stable Control request identity for one manual or scheduled occurrence.
+ * @category constructors
+ * @since 0.1.0
+ */
+export const idempotencyKey = (triggerId, occurrence) => `${triggerId}:${new Date(occurrence).toISOString()}`;
+/**
+ * Runs one trigger's work and reports whether it finished.
+ *
+ * A tick walks the due triggers in id order, so an aborting trigger used to
+ * take every trigger after it alphabetically down with it, and the supervisor
+ * above discarded the error unread. The cause is logged where the trigger it
+ * belongs to is still known. Interruption is re-raised: it is the scope
+ * closing, not a trigger failing.
+ */
+const attempted = (annotations, work, effect) => Effect.catchCause(Effect.as(effect, true), (cause) => Cause.hasInterrupts(cause)
+    ? Effect.failCause(cause)
+    : Effect.as(Effect.annotateLogs(Effect.logWarning(`A trigger ${work} failed`, cause), annotations), false));
+const isolate = (annotations, work, effect) => Effect.asVoid(attempted(annotations, work, effect));
+/**
+ * Constructs a scheduler service in the current Scope.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options = {}) => Effect.gen(function* () {
+    const parentScope = yield* Effect.scope;
+    const providedStore = yield* TriggerStore;
+    // Every fire the ledger records is counted by outcome, so a dropped,
+    // skipped, or failed occurrence is visible without reading the ledger.
+    const store = {
+        ...providedStore,
+        recordResult: (result) => providedStore.recordResult(result).pipe(Effect.tap(() => Metric.update(firesRecorded.pipe(Metric.withAttributes({ outcome: result.outcome })), 1)))
+    };
+    const active = yield* ActiveRuns.make;
+    const observedAt = yield* Ref.make(new Map());
+    const semaphore = yield* Semaphore.make(1);
+    const runPollInterval = yield* duration(options.runPollInterval ?? "15 seconds", "runPollInterval");
+    const concurrency = options.concurrency ?? defaultConcurrency;
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        return yield* Effect.fail(invalidOption("concurrency", "a positive integer"));
+    }
+    const startTimeout = yield* duration(options.startTimeout ?? "4 minutes", "startTimeout");
+    const inspectTimeout = yield* duration(options.inspectTimeout ?? "30 seconds", "inspectTimeout");
+    const cancelTimeout = yield* duration(options.cancelTimeout ?? "30 seconds", "cancelTimeout");
+    const fireRetention = yield* duration(options.fireRetention ?? defaultFireRetention, "fireRetention");
+    const lastPrunedAt = yield* Ref.make(undefined);
+    // Every runner call carries a deadline. A runtime that never answers used
+    // to hold the launch, and the tick waiting on it, for the life of the
+    // scope with nothing written down.
+    const provided = yield* Runner;
+    const runner = {
+        start: (input) => deadline(provided.start(input), startTimeout, `Runner.start for ${input.idempotencyKey}`),
+        inspect: (runId) => deadline(provided.inspect(runId), inspectTimeout, `Runner.inspect for run ${runId}`),
+        cancel: (runId) => deadline(provided.cancel(runId), cancelTimeout, `Runner.cancel for run ${runId}`)
+    };
+    // The watermark only moves forward, and only past occurrences this process
+    // finished dispatching. Advancing it before the work is what silently lost
+    // an occurrence whenever a claim or a dispatch failed.
+    const observe = (triggerId, occurrence) => Ref.update(observedAt, (current) => {
+        const existing = current.get(triggerId);
+        if (existing !== undefined && existing >= occurrence)
+            return current;
+        return new Map(current).set(triggerId, occurrence);
+    });
+    // A reservation is not a run: the Runner has never heard of it, and asking
+    // answers "not active" for a launch that is still in flight. Its lease is
+    // the only thing entitled to release it, in either branch.
+    const inspectStored = (runId) => isReservation(runId) ? Effect.succeed("active") : runner.inspect(runId);
+    const occurrenceOf = (triggerId, runId) => {
+        const reserved = reservationOccurrence(runId);
+        if (reserved !== undefined)
+            return Effect.succeed(reserved);
+        return store.activeOccurrence(triggerId, runId).pipe(Effect.map((occurrence) => Option.isSome(occurrence) ? occurrence.value : Number.NEGATIVE_INFINITY));
+    };
+    // Only `completed` is a completed occurrence. A failed, cancelled, or
+    // vanished run used to be recorded as `completed` because the runner
+    // answered only "not active". Recording the result also clears the
+    // matching active run atomically.
+    const recordSettled = (triggerId, occurrence, runId, state) => state === "completed"
+        ? store.recordResult({ triggerId, occurrence, outcome: "completed", runId })
+        : store.recordResult({ triggerId, occurrence, outcome: "failed", runId, error: stoppedMessage(runId, state) });
+    const settleRecovered = (triggerId, occurrence, runId, state) => Number.isFinite(occurrence)
+        ? recordSettled(triggerId, occurrence, runId, state)
+        : store.clearActive(triggerId, runId);
+    // The listed row already answers what the store would: with no run and no
+    // reservation on it, `activeRun` reads an idle lease, writes nothing, and
+    // answers `None`. Asking anyway cost one write transaction per trigger per
+    // tick, on the tick where every trigger is idle.
+    const storedActive = (triggerId, held) => held !== undefined && held.activeRunId === undefined
+        ? Effect.succeed(Option.none())
+        : store.activeRun(triggerId);
+    // Adopts the run the store holds for a trigger that has no local entry:
+    // settle it if it has already stopped, otherwise take the entry for it.
+    const recoverStored = (trigger, runId) => Effect.gen(function* () {
+        const occurrence = yield* occurrenceOf(trigger.id, runId);
+        const state = yield* inspectStored(runId);
+        if (state !== "active") {
+            yield* settleRecovered(trigger.id, occurrence, runId, state);
+            return undefined;
+        }
+        const recovered = { occurrence, runId };
+        yield* active.take(trigger.id, recovered);
+        return recovered;
+    });
+    const resolveActive = (trigger, held) => Effect.gen(function* () {
+        const local = yield* active.get(trigger.id);
+        if (local !== undefined) {
+            // The finalizer detaches the fiber when monitoring ends. An entry
+            // without a fiber was recovered or could no longer be inspected;
+            // only the runtime can say whether that run is still going.
+            if (local.fiber !== undefined)
+                return local;
+            if (!isReservation(local.runId)) {
+                const state = yield* inspectStored(local.runId);
+                if (state === "active")
+                    return local;
+                yield* settleRecovered(trigger.id, local.occurrence, local.runId, state);
+                yield* active.remove(trigger.id, local.occurrence);
+            }
+            else {
+                // A recovered reservation has no monitor that can remove it. Ask
+                // the store on every tick so its lease can expire and re-arm the
+                // occurrence instead of pinning this local cache forever.
+                const stored = yield* storedActive(trigger.id, held);
+                if (Option.isNone(stored)) {
+                    yield* active.remove(trigger.id, local.occurrence);
+                    return undefined;
+                }
+                if (stored.value === local.runId)
+                    return local;
+                yield* active.remove(trigger.id, local.occurrence);
+                return yield* recoverStored(trigger, stored.value);
+            }
+        }
+        const stored = yield* storedActive(trigger.id, held);
+        if (Option.isNone(stored))
+            return undefined;
+        return yield* recoverStored(trigger, stored.value);
+    });
+    const recordFailed = (trigger, occurrence, error, runId) => store.recordResult({
+        triggerId: trigger.id,
+        occurrence,
+        outcome: "failed",
+        error: error.message,
+        runId
+    });
+    // An inspection error is not evidence that a run stopped. Retry three
+    // times, doubling the poll interval up to a minute, then let the next tick
+    // inspect the durable owner again. Interruption must still close the scope.
+    const inspectRun = (triggerId, runId) => Effect.gen(function* () {
+        for (let attempt = 0;; attempt++) {
+            const inspected = yield* runner.inspect(runId).pipe(Effect.map(Option.some), Effect.catchCause((cause) => Cause.hasInterrupts(cause) ?
+                Effect.failCause(cause) :
+                Effect.logWarning("A trigger run inspection failed", cause).pipe(Effect.annotateLogs({ triggerId, runId, attempt: String(attempt + 1) }), Effect.as(Option.none()))));
+            if (Option.isSome(inspected))
+                return inspected;
+            if (attempt === 3) {
+                yield* Effect.logWarning("A trigger run monitor detached after inspection retries").pipe(Effect.annotateLogs({ triggerId, runId }));
+                return Option.none();
+            }
+            yield* Effect.sleep(Math.min(Duration.toMillis(runPollInterval) * 2 ** attempt, 60_000));
+        }
+    });
+    const launch = (trigger, occurrence, reservation, preserveBuffered) => Effect.gen(function* () {
+        // The occurrence takes the entry under its reservation before the
+        // runner hears of it, so every write below is fenced on this launch.
+        yield* active.take(trigger.id, { occurrence, runId: reservation });
+        let runId;
+        let launchRecorded = false;
+        let completed = false;
+        const lifecycle = Effect.gen(function* () {
+            runId = yield* timed(launchDuration, runner.start({
+                flowId: trigger.flowId,
+                input: trigger.input,
+                idempotencyKey: idempotencyKey(trigger.id, occurrence)
+            })).pipe(Effect.withSpan("Scheduler.launch", {
+                attributes: { triggerId: trigger.id, occurrence: new Date(occurrence).toISOString() }
+            }));
+            const startedRunId = runId;
+            yield* active.update(trigger.id, occurrence, (entry) => ({ ...entry, runId: startedRunId }));
+            yield* store.recordResult({
+                triggerId: trigger.id,
+                occurrence,
+                outcome: "launched",
+                runId,
+                reservationId: reservation
+            });
+            launchRecorded = true;
+            let state;
+            while (true) {
+                const inspected = yield* inspectRun(trigger.id, runId);
+                if (Option.isNone(inspected))
+                    return;
+                state = inspected.value;
+                if (state !== "active")
+                    break;
+                yield* Effect.sleep(runPollInterval);
+            }
+            yield* recordSettled(trigger.id, occurrence, runId, state);
+            completed = true;
+        }).pipe(Effect.catch((error) => Effect.gen(function* () {
+            if (launchRecorded) {
+                yield* Effect.logWarning("A trigger run monitor could not persist completion", error).pipe(Effect.annotateLogs({ triggerId: trigger.id, runId: runId }));
+                return;
+            }
+            if (error.code === "stale_owner" && runId !== undefined) {
+                yield* Effect.logWarning("A trigger launch lost its reservation", error).pipe(Effect.annotateLogs({ triggerId: trigger.id, occurrence: String(occurrence) }));
+                const losingRunId = runId;
+                yield* isolate({ triggerId: trigger.id, runId }, "losing run reconciliation", Effect.gen(function* () {
+                    const held = yield* store.inspect(trigger.id);
+                    // An idempotent retry may have committed this same run.
+                    // An unfinished retry of the same occurrence will adopt it.
+                    if (held.activeRunId === losingRunId ||
+                        (held.activeRunId !== undefined && reservationOccurrence(held.activeRunId) === occurrence))
+                        return;
+                    yield* runner.cancel(losingRunId);
+                })).pipe(Effect.ignore);
+                return;
+            }
+            if (preserveBuffered) {
+                // A buffered occurrence was taken off the buffer by the claim
+                // that led here. Re-arm it under this reservation so the next
+                // tick retries it rather than losing it.
+                yield* isolate({ triggerId: trigger.id }, "buffered launch compensation", store.restorePending({ triggerId: trigger.id, occurrence, reservationId: reservation })).pipe(Effect.ignore);
+            }
+            else {
+                // A start that answered too late is ambiguous: the runtime may
+                // hold the run. Keep the occurrence pending exactly as when the
+                // launched result failed to persist, so the next tick retries
+                // under the same idempotency key and the runtime's durable
+                // deduplication answers with the same run.
+                if (runId !== undefined || error.code === "runner_timeout") {
+                    yield* isolate({ triggerId: trigger.id }, "launch compensation", store.restorePending({
+                        triggerId: trigger.id,
+                        occurrence,
+                        reservationId: reservation
+                    })).pipe(Effect.ignore);
+                }
+                else {
+                    yield* recordFailed(trigger, occurrence, error, reservation).pipe(Effect.ignore);
+                }
+            }
+            yield* Effect.logWarning("A trigger launch failed", error).pipe(Effect.annotateLogs({ triggerId: trigger.id, occurrence: String(occurrence) }));
+        })), 
+        // Interrupting this fiber detaches the monitor; it never cancels the
+        // run. The run is durable and outlives this process, so a deploy or
+        // any other scope closure must leave it alone: the next incarnation
+        // re-attaches through `resolveActive`. Cancellation is a deliberate
+        // act and belongs to `cancelActive` alone.
+        Effect.ensuring(Effect.suspend(() => launchRecorded && !completed
+            ? active.update(trigger.id, occurrence, (entry) => ({ ...entry, fiber: undefined }))
+            : active.remove(trigger.id, occurrence))));
+        // The tick does not wait for the launch. The claim already fenced
+        // the occurrence under its reservation, and every failure below is
+        // compensated in the lifecycle itself. A tick that waited held every
+        // other trigger for as long as one plan sat parked or one runner was
+        // slow, and a boundary that passed meanwhile was never claimed.
+        const fiber = yield* Effect.forkIn(Effect.scoped(lifecycle).pipe(Effect.onExit((exit) => exit._tag === "Failure" && !Cause.hasInterrupts(exit.cause)
+            ? Effect.logWarning(launchRecorded ? "A trigger run monitor failed" : "A trigger launch failed", exit.cause).pipe(Effect.annotateLogs({
+                triggerId: trigger.id,
+                occurrence: String(occurrence),
+                runId: runId ?? reservation
+            }))
+            : Effect.void)), parentScope, { startImmediately: true });
+        // The monitor is recorded against the entry this occurrence claimed.
+        // `startImmediately` can finish or detach before the fork returns.
+        // Never attach a finished fiber to an entry awaiting tick recovery.
+        if (fiber.pollUnsafe() === undefined) {
+            yield* active.update(trigger.id, occurrence, (entry) => ({ ...entry, fiber }));
+        }
+    });
+    // Only a claim that named the run it is superseding gets here, so the run
+    // id is known. The monitor, on the other hand, may not exist: the run can
+    // belong to a scheduler this one only knows through the store. Cancelling
+    // is a deliberate act and happens here alone; a reservation has no run for
+    // the runtime to cancel, and an occurrence this process never saw has none
+    // of its own to record the supersession against.
+    const cancelActive = (trigger, prior, replacementOccurrence, replacementReservation, queueReplacement) => Effect.gen(function* () {
+        if (!isReservation(prior.runId)) {
+            yield* runner.cancel(prior.runId).pipe(Effect.catch((error) => {
+                // The claim already replaced the prior run with the new launch
+                // reservation. If cancellation fails, restore that run as active
+                // and queue the replacement so neither side of the hand-off is
+                // lost. Keep its monitor attached: it is still running.
+                const restore = queueReplacement
+                    ? isolate({ triggerId: trigger.id }, "supersede compensation", store.restorePending({
+                        triggerId: trigger.id,
+                        occurrence: replacementOccurrence,
+                        reservationId: replacementReservation
+                    }))
+                    : Effect.void;
+                return restore.pipe(Effect.andThen(Effect.fail(error)));
+            }));
+        }
+        if (Number.isFinite(prior.occurrence) && !isReservation(prior.runId)) {
+            yield* store.recordResult({
+                triggerId: trigger.id,
+                occurrence: prior.occurrence,
+                outcome: "superseded",
+                runId: prior.runId
+            });
+        }
+        // Keep the monitor attached until the terminal write succeeds. If the
+        // store refuses it after cancellation, the monitor can still observe
+        // the stopped run and record a terminal result on its next poll.
+        if (prior.fiber !== undefined)
+            yield* Fiber.interrupt(prior.fiber);
+        yield* active.remove(trigger.id, prior.occurrence);
+    });
+    const dispatchClaimed = (trigger, occurrence, claim, resumeBuffered = false) => Effect.gen(function* () {
+        switch (claim.action) {
+            case "fire":
+                yield* launch(trigger, occurrence, claim.reservationId, resumeBuffered);
+                return;
+            case "skip":
+                yield* store.recordResult({
+                    triggerId: trigger.id,
+                    occurrence,
+                    outcome: "skipped"
+                });
+                return;
+            case "buffer":
+                yield* store.recordResult({
+                    triggerId: trigger.id,
+                    occurrence,
+                    outcome: "buffered"
+                });
+                return;
+            case "supersede": {
+                const superseded = claim.activeRunId;
+                if (superseded !== undefined) {
+                    const local = yield* active.get(trigger.id);
+                    yield* cancelActive(trigger, local !== undefined && local.runId === superseded
+                        ? { ...local, runId: superseded }
+                        : {
+                            occurrence: yield* occurrenceOf(trigger.id, superseded),
+                            runId: superseded
+                        }, occurrence, claim.reservationId, !resumeBuffered);
+                }
+                yield* launch(trigger, occurrence, claim.reservationId, resumeBuffered);
+                return;
+            }
+        }
+    });
+    const claimOnce = (trigger, occurrence) => store.claimFire({
+        triggerId: trigger.id,
+        occurrence,
+        expectedRevision: trigger.revision
+    }).pipe(Effect.flatMap((claim) => claim.claimed ? dispatchClaimed(trigger, occurrence, claim) : Effect.void));
+    // A claim is fenced on the revision its occurrence was computed from. One
+    // refresh and one retry is enough because the next tick reads again.
+    const withRevisionRefresh = (trigger, claim) => claim(trigger).pipe(Effect.catch((error) => error.code !== "revision_mismatch"
+        ? Effect.fail(error)
+        : store.get(trigger.id).pipe(Effect.flatMap((refreshed) => Option.isNone(refreshed) || refreshed.value.revision === trigger.revision
+            ? Effect.fail(error)
+            : claim(refreshed.value)))));
+    // The store reads, claims, and clears a buffer in one transaction. A
+    // dispatch failure happens after that commit, so this process can safely
+    // re-arm the occurrence before it reports the failure.
+    const resumePending = (trigger, held) => 
+    // A listed row holding neither a buffered occurrence nor a run has
+    // nothing for `claimPending` to take: only expiring a reservation
+    // re-arms a pending occurrence, and there is no reservation to expire.
+    held !== undefined && held.pendingAt === undefined && held.activeRunId === undefined
+        ? Effect.void
+        : withRevisionRefresh(trigger, (current) => store.claimPending({
+            triggerId: current.id,
+            expectedRevision: current.revision
+        }).pipe(Effect.flatMap((pending) => {
+            if (Option.isNone(pending))
+                return Effect.void;
+            const occurrence = pending.value.occurrence;
+            const claim = pending.value.claim;
+            if (!claim.claimed)
+                return Effect.void;
+            return dispatchClaimed(current, occurrence, claim, true).pipe(Effect.onError(() => isolate({ triggerId: current.id }, "buffered launch compensation", claim.action === "fire" || claim.action === "supersede"
+                ? store.restorePending({ triggerId: current.id, occurrence, reservationId: claim.reservationId })
+                : store.setPending({ triggerId: current.id, occurrence })).pipe(Effect.ignore)));
+        })));
+    const processTrigger = (trigger, held, refreshed = false) => Effect.gen(function* () {
+        // Each trigger reads the clock itself. One instant captured before the
+        // tick fanned out aged by every launch that finished ahead of it.
+        const now = yield* Clock.currentTimeMillis;
+        const running = yield* resolveActive(trigger, held);
+        // Disable prevents future claims, not recovery of an already active
+        // occurrence (including a plan waiting for a human decision).
+        if (!trigger.enabled)
+            return;
+        if (running === undefined || trigger.overlap === "supersede")
+            yield* resumePending(trigger, held);
+        const observed = (yield* Ref.get(observedAt)).get(trigger.id);
+        const due = yield* DueOccurrences.compute(trigger, now, observed);
+        let dispatched;
+        let interrupted = false;
+        let stale = false;
+        for (const occurrence of due.occurrences) {
+            const settledHere = yield* attempted({ triggerId: trigger.id }, `dispatch of occurrence ${occurrence}`, claimOnce(trigger, occurrence).pipe(Effect.catch((error) => error.code === "revision_mismatch"
+                ? Effect.sync(() => {
+                    stale = true;
+                })
+                : Effect.fail(error))));
+            if (stale)
+                break;
+            if (settledHere && !interrupted)
+                dispatched = occurrence;
+            if (!settledHere)
+                interrupted = true;
+        }
+        if (stale) {
+            // The occurrences were computed from a declaration the store has
+            // since replaced, so the schedule decision is what went stale: a
+            // trigger edited to fire at noon owes nothing for the hourly
+            // boundary its old cron produced. Keep the boundary already
+            // dispatched, re-read once, and decide again from the refreshed cron
+            // and watermark. A second mismatch waits for the next tick, which
+            // reads again anyway. A buffered occurrence is store state rather
+            // than a computed decision, so `resumePending` retries it as is.
+            if (dispatched !== undefined)
+                yield* observe(trigger.id, dispatched);
+            if (refreshed)
+                return;
+            const current = yield* store.get(trigger.id);
+            if (Option.isNone(current) || current.value.revision === trigger.revision)
+                return;
+            // The refreshed declaration comes from the store, not the listing,
+            // so the held snapshot no longer describes it.
+            return yield* processTrigger(current.value, undefined, true);
+        }
+        if (!interrupted)
+            return yield* observe(trigger.id, due.watermark);
+        if (dispatched !== undefined)
+            yield* observe(trigger.id, dispatched);
+    }).pipe(Effect.withSpan("Scheduler.processTrigger", { attributes: { triggerId: trigger.id } }));
+    const host = options.host ?? defaultHost;
+    const runOnce = semaphore.withPermits(1)(Effect.gen(function* () {
+        // The heartbeat is observability, not dispatch: a store that cannot
+        // record it is logged and the tick goes on, so a listing's "nothing is
+        // listening" can never be caused by the row that reports it.
+        yield* isolate({ host }, "heartbeat", store.heartbeat(host));
+        // Nothing else deletes from the fire ledger, so without this it keeps
+        // one row per occurrence forever and every fires listing reads it all.
+        const now = yield* Clock.currentTimeMillis;
+        const last = yield* Ref.get(lastPrunedAt);
+        if (last === undefined || now - last >= pruneEvery) {
+            yield* Ref.set(lastPrunedAt, now);
+            yield* isolate({ host }, "fire ledger prune", Effect.asVoid(store.pruneFires({ olderThan: now - Duration.toMillis(fireRetention) })));
+        }
+        // Every trigger, not only the enabled ones: a disabled trigger can
+        // still hold an active occurrence that has to recover, and the enabled
+        // check below it stops the new claims.
+        const listing = yield* store.list();
+        // Triggers are independent once claimed: the store fences each claim
+        // on its own row. Walking them in series let one launch waiting on a
+        // parked plan hold every trigger after it for the whole wait. A row
+        // the store could not decode is one more isolated failure, so one
+        // corrupt declaration cannot stop the healthy schedules beside it.
+        yield* Effect.forEach(listing, (row) => isolate({ triggerId: row.triggerId }, "tick", Result.isFailure(row.trigger)
+            ? Effect.fail(row.trigger.failure)
+            : processTrigger(row.trigger.success, row)), { concurrency, discard: true });
+    }).pipe((tick) => timed(tickDuration, tick), Effect.withSpan("Scheduler.runOnce", { attributes: { host } })));
+    return Scheduler.of({ runOnce });
+});
+/**
+ * Constructs a scheduler that performs no work.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = () => Scheduler.of({ runOnce: Effect.void });
+/**
+ * Scoped scheduler layer. Its supervisor sleeps only through the Effect Clock,
+ * so scope closure interrupts the poll loop and detaches every run monitor.
+ * Detaching is all it does: the runs themselves are durable and keep going,
+ * and the next incarnation re-attaches to them from the store.
+ *
+ * The loop recovers from the whole cause rather than the typed error alone. A
+ * defect raised anywhere under a tick, which `Effect.catch` by contract leaves
+ * alone, would otherwise kill this fiber and stop every trigger in the process
+ * with nothing written down.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (options = {}) => Layer.effect(Scheduler, Effect.gen(function* () {
+    const scheduler = yield* make(options);
+    const pollInterval = yield* duration(options.pollInterval ?? "1 minute", "pollInterval");
+    yield* Effect.forkScoped(Effect.forever(scheduler.runOnce.pipe(Effect.catchCause((cause) => Cause.hasInterrupts(cause)
+        ? Effect.failCause(cause)
+        : Effect.logWarning("A trigger scheduler tick failed", cause)), Effect.andThen(Effect.sleep(pollInterval)))));
+    return scheduler;
+}));
+/**
+ * Provides an inert scheduler without allocating a supervisor fiber.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = Layer.succeed(Scheduler)(makeNoop());
+//# sourceMappingURL=Scheduler.js.map