adispatchd 0.0.0-stage → 0.1.0

package/dist/scheduler/scheduler.js

@@ -0,0 +1,680 @@
+/**
+ * Scheduler (Spec §5.5, §7, §14, §19): polling loop for source workflows,
+ * cron trigger, manual start and dry-run.
+ *
+ * Invariants:
+ * - Planning steps never overlap (serialized chain); the next poll is armed
+ *   only after the previous step finished.
+ * - No persistent candidate queue: every step reads the sources again.
+ * - The final capacity check and the reservation run synchronously (no
+ *   `await` in between), so concurrent cron firings / manual starts in the
+ *   same process cannot overcommit the limits. Active runs of all triggers
+ *   (incl. manual and `recovery_pending`) count towards the limits.
+ * - Automatic starts only when the run controller allows them (ready after
+ *   recovery, not paused, not draining/stopping).
+ * - Cron: at most one run per slot (`cron_firings` primary key + slot lock);
+ *   every handled slot gets exactly one `cron_firings` record; missed slots
+ *   are recorded as `skipped_missed` and never caught up.
+ */
+import { errorMessage, noopLogger, systemClock, systemTimers, } from '../core/index.js';
+import { UnknownWorkflowError, automaticParameterValues } from '../config/index.js';
+import { ShellCheckRunner, sortCandidates } from '../filters/index.js';
+import { BlockedError, LockConflictError, } from '../persistence/index.js';
+import { SchedulerChecks } from './checks.js';
+import { dueSlots, parseCron } from './cron.js';
+import { dryRunWorkflow } from './dry-run.js';
+import { SchedulerError } from './errors.js';
+import { checkEligibility, prepareSourceWorkflow, verifyItemFor } from './planner.js';
+import { repositoryState } from './state.js';
+import { MAX_DIAGNOSED_CANDIDATES, } from './types.js';
+/** Cap of a single timer delay; longer waits are re-armed (also absorbs wall-clock jumps). */
+const MAX_TIMER_DELAY_MS = 60 * 60_000;
+/** Skip decisions recorded only once per series (state change), not per slot. */
+const QUIET_DECISIONS = new Set([
+    'skipped_disabled',
+    'skipped_paused',
+    'skipped_not_ready',
+    'skipped_draining',
+]);
+/** Bound for scanning missed cron slots. */
+const MAX_CRON_SCAN = 100_000;
+/** See module docs. One instance per process, created after the run controller's recovery. */
+export class Scheduler {
+    config;
+    repos;
+    controller;
+    sources;
+    state;
+    shellChecks;
+    checks;
+    clock;
+    timers;
+    logger;
+    misfireToleranceMs;
+    maxRecordedMissed;
+    started = false;
+    stopped = false;
+    pollTimer;
+    stepChain = Promise.resolve();
+    inflight = new Set();
+    diagnoses = new Map();
+    lastReport = null;
+    cron = new Map();
+    unsubscribeConfig;
+    constructor(options) {
+        this.config = options.config;
+        this.repos = options.repositories;
+        this.controller = options.controller;
+        this.sources = options.sources;
+        this.clock = options.clock ?? systemClock;
+        this.timers = options.timers ?? systemTimers;
+        this.logger = (options.logger ?? noopLogger).child({ component: 'scheduler' });
+        this.state = repositoryState(this.repos);
+        // Check timeouts use real timers; the clock drives the condition cache TTL.
+        this.shellChecks = options.shellChecks ?? new ShellCheckRunner({ clock: this.clock, logger: this.logger });
+        this.checks = new SchedulerChecks(this.shellChecks, () => this.clock.now());
+        this.misfireToleranceMs = options.cronMisfireToleranceMs ?? 60_000;
+        this.maxRecordedMissed = options.maxRecordedMissedSlots ?? 100;
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    /**
+     * Start the polling loop (first step immediately) and arm the cron timers
+     * (missed slots since the last persisted firing are recorded as
+     * `skipped_missed`). Call after `RunController.recover()`.
+     */
+    start() {
+        if (this.started || this.stopped)
+            return;
+        this.started = true;
+        this.unsubscribeConfig = this.config.onChange((event) => {
+            if (event.kind !== 'reload')
+                return;
+            // Changed commands/TTLs must not be served from the old cache.
+            this.shellChecks.invalidate();
+            this.syncCron();
+            for (const id of [...this.diagnoses.keys()]) {
+                const wf = event.config.workflows[id];
+                if (!wf || wf.trigger.type !== 'source')
+                    this.diagnoses.delete(id);
+            }
+        });
+        this.syncCron();
+        this.loopStep();
+        this.logger.info('scheduler started', { pollingIntervalMs: this.config.current.global.scheduler.pollingIntervalMs });
+    }
+    /** Stop polling and cron timers; waits for running planning steps / cron handlers. Idempotent. */
+    async stop() {
+        this.stopped = true;
+        if (this.pollTimer)
+            this.timers.clearTimeout(this.pollTimer);
+        this.pollTimer = undefined;
+        for (const state of this.cron.values())
+            this.disarm(state);
+        this.unsubscribeConfig?.();
+        this.unsubscribeConfig = undefined;
+        await this.whenIdle();
+    }
+    /** Resolves once no planning step and no cron handler is in flight (tests, shutdown). */
+    async whenIdle() {
+        while (this.inflight.size > 0)
+            await Promise.allSettled([...this.inflight]);
+    }
+    track(p) {
+        this.inflight.add(p);
+        const remove = () => {
+            this.inflight.delete(p);
+        };
+        p.then(remove, remove);
+        return p;
+    }
+    /** One loop iteration: planning step, then arm the next poll (never overlapping). */
+    loopStep() {
+        this.planOnce()
+            .catch((err) => this.logger.error('planning step failed', { error: errorMessage(err) }))
+            .finally(() => this.armPoll(this.config.current.global.scheduler.pollingIntervalMs));
+    }
+    armPoll(delayMs) {
+        if (this.stopped)
+            return;
+        if (this.pollTimer)
+            this.timers.clearTimeout(this.pollTimer);
+        this.pollTimer = this.timers.setTimeout(() => {
+            this.pollTimer = undefined;
+            this.loopStep();
+        }, delayMs);
+    }
+    // ---------------------------------------------------------------------------
+    // Gate / capacity
+    gateReason() {
+        if (this.controller.canStartAutomatically())
+            return null;
+        const s = this.controller.status;
+        if (!s.ready)
+            return 'not_ready';
+        if (s.draining || s.stopping)
+            return 'draining';
+        if (s.paused)
+            return 'paused';
+        return 'not_ready';
+    }
+    gateInfo() {
+        const reason = this.gateReason();
+        return { canStartAutomatically: reason === null, reason };
+    }
+    /** Limit check with live effective values (overrides apply immediately). */
+    capacityProblem(workflowId) {
+        const globalMax = this.config.maxConcurrent;
+        const globalActive = this.state.countActive();
+        if (globalActive >= globalMax) {
+            return { decision: 'global_limit', reason: `global limit reached (${globalActive}/${globalMax} active)` };
+        }
+        const max = this.config.getWorkflow(workflowId)?.maxConcurrent ?? 1;
+        const active = this.state.countActive(workflowId);
+        if (active >= max)
+            return { decision: 'workflow_limit', reason: `workflow limit reached (${active}/${max} active)` };
+        return null;
+    }
+    // ---------------------------------------------------------------------------
+    // Planning step (Spec §7)
+    /**
+     * Run one planning step for all source workflows. Steps are serialized
+     * (a call during a running step runs after it). Never rejects for source
+     * or check problems – they are part of the diagnosis.
+     */
+    planOnce() {
+        const step = this.stepChain.then(() => this.planningStep());
+        this.stepChain = step.catch(() => undefined);
+        return this.track(step);
+    }
+    async planningStep() {
+        const startedAt = this.clock.now().toISOString();
+        const gate = this.stopped ? 'draining' : this.gateReason();
+        if (gate) {
+            const report = { startedAt, finishedAt: startedAt, skipped: gate, startedRunIds: [], workflows: [] };
+            this.lastReport = report;
+            return report;
+        }
+        const cfg = this.config.current;
+        const workflows = this.config.listWorkflows().filter((w) => w.config.trigger.type === 'source');
+        const listCache = new Map();
+        const conditionMemo = new Map();
+        // Steps 1–3 per workflow in parallel; a failing source only affects its workflows.
+        const prepared = await Promise.all(workflows.map(async (w) => {
+            if (!w.enabled) {
+                const sourceId = w.config.trigger.type === 'source' ? w.config.trigger.source : '';
+                return {
+                    diagnosis: {
+                        workflowId: w.config.id,
+                        at: startedAt,
+                        status: 'disabled',
+                        error: null,
+                        sourceId,
+                        polled: 0,
+                        pushdown: null,
+                        conditions: [],
+                        candidates: [],
+                        omittedCandidates: 0,
+                        startedRunIds: [],
+                    },
+                    candidates: [],
+                    rejected: [],
+                };
+            }
+            // Never rejects: source problems are part of the diagnosis.
+            return prepareSourceWorkflow(w.config, w.priority, { sources: this.sources, at: startedAt, listCache });
+        }));
+        // Step 3: deterministic order across all workflows; steps 4–7 per candidate.
+        const ordered = sortCandidates(prepared.flatMap((p) => p.candidates));
+        const startedRunIds = [];
+        for (const candidate of ordered) {
+            try {
+                const runId = await this.considerCandidate(candidate, cfg, conditionMemo);
+                if (runId)
+                    startedRunIds.push(runId);
+            }
+            catch (err) {
+                candidate.diagnosis.decision = 'start_failed';
+                candidate.diagnosis.reason = errorMessage(err);
+                this.logger.error('candidate failed unexpectedly', { workflowId: candidate.workflowId, item: candidate.itemKey, error: errorMessage(err) });
+            }
+        }
+        // Diagnoses (last planning step per workflow, in memory).
+        const byWorkflow = new Map(prepared.map((p) => [p.diagnosis.workflowId, p]));
+        for (const p of prepared) {
+            const diag = p.diagnosis;
+            const memo = conditionMemo.get(diag.workflowId);
+            if (memo)
+                diag.conditions = (await memo).checks;
+            const all = [...ordered.filter((c) => c.workflowId === diag.workflowId).map((c) => c.diagnosis), ...p.rejected];
+            diag.candidates = all.slice(0, MAX_DIAGNOSED_CANDIDATES);
+            diag.omittedCandidates = all.length - diag.candidates.length;
+            diag.startedRunIds = all.filter((c) => c.decision === 'started' && c.runId).map((c) => c.runId);
+            this.diagnoses.set(diag.workflowId, diag);
+        }
+        for (const id of [...this.diagnoses.keys()])
+            if (!byWorkflow.has(id))
+                this.diagnoses.delete(id);
+        const report = {
+            startedAt,
+            finishedAt: this.clock.now().toISOString(),
+            skipped: null,
+            startedRunIds,
+            workflows: prepared.map((p) => p.diagnosis),
+        };
+        this.lastReport = report;
+        if (startedRunIds.length > 0)
+            this.logger.info('planning step started runs', { runs: startedRunIds });
+        return report;
+    }
+    /** Steps 4–7 for one candidate; returns the started run ID. */
+    async considerCandidate(candidate, cfg, conditionMemo) {
+        const diag = candidate.diagnosis;
+        const set = (decision, reason) => {
+            diag.decision = decision;
+            diag.reason = reason;
+            return null;
+        };
+        // Free slot? (checked first so that a full limit costs no API calls / checks)
+        const early = this.capacityProblem(candidate.workflowId);
+        if (early)
+            return set(early.decision, early.reason);
+        const eligibility = await checkEligibility(candidate, {
+            state: this.state,
+            checks: this.checks,
+            workflowConditions: (wf) => {
+                let memo = conditionMemo.get(wf.id);
+                if (!memo) {
+                    memo = this.checks.workflowConditions(wf);
+                    conditionMemo.set(wf.id, memo);
+                }
+                return memo;
+            },
+        });
+        if (!eligibility.eligible)
+            return null;
+        // --- synchronous section: re-validate and reserve atomically -------------
+        if (this.stopped)
+            return set('gate_closed', 'scheduler is stopping');
+        const gate = this.gateReason();
+        if (gate)
+            return set('gate_closed', `automatic starts not possible: ${gate}`);
+        const eff = this.config.getWorkflow(candidate.workflowId);
+        if (!eff || !eff.enabled || this.config.current.workflowHashes[candidate.workflowId] !== cfg.workflowHashes[candidate.workflowId]) {
+            return set('workflow_unavailable', 'workflow was disabled, removed or changed during the planning step');
+        }
+        const capacity = this.capacityProblem(candidate.workflowId);
+        if (capacity)
+            return set(capacity.decision, capacity.reason);
+        let run;
+        try {
+            run = this.repos.runs.reserve({
+                workflowId: candidate.workflowId,
+                triggerType: 'source',
+                sourceId: candidate.item.sourceId,
+                sourceItemKey: candidate.itemKey,
+                sourceUrl: candidate.item.url,
+                configSnapshot: this.config.snapshotWorkflow(candidate.workflowId),
+                parameters: automaticParameterValues(eff.config),
+                failIfBlocked: true,
+            });
+        }
+        catch (err) {
+            if (err instanceof LockConflictError) {
+                diag.runId = err.holderRunId;
+                return set('locked', `run ${err.holderRunId} of this workflow is active for the item`);
+            }
+            if (err instanceof BlockedError) {
+                diag.blockId = err.blockId;
+                return set('blocked', `retry block ${err.blockId}`);
+            }
+            throw err;
+        }
+        // --- end of synchronous section ------------------------------------------
+        diag.runId = run.id;
+        try {
+            const verifyItem = verifyItemFor(candidate.workflow, candidate.adapter);
+            this.controller.startRun(run, verifyItem ? { verifyItem } : {});
+        }
+        catch (err) {
+            // The controller finalizes a refused reserved run itself (lock released).
+            return set('start_failed', `run ${run.id} could not be started: ${errorMessage(err)}`);
+        }
+        set('started', `run ${run.id} started`);
+        return run.id;
+    }
+    // ---------------------------------------------------------------------------
+    // Cron (Spec §5.5, §7)
+    /** Arm/re-arm cron timers for the schedule workflows of the active configuration. */
+    syncCron() {
+        if (this.stopped)
+            return;
+        const now = this.clock.now();
+        const seen = new Set();
+        for (const wf of Object.values(this.config.current.workflows)) {
+            if (wf.trigger.type !== 'schedule')
+                continue;
+            seen.add(wf.id);
+            const existing = this.cron.get(wf.id);
+            if (existing && existing.expression === wf.trigger.cron && existing.timezone === wf.trigger.timezone)
+                continue;
+            let schedule;
+            try {
+                schedule = parseCron(wf.trigger.cron, wf.trigger.timezone);
+            }
+            catch (err) {
+                this.logger.error('invalid cron expression', { workflowId: wf.id, error: errorMessage(err) });
+                continue;
+            }
+            if (existing)
+                this.disarm(existing);
+            // A changed schedule starts fresh at "now"; a newly seen workflow catches
+            // up from its latest persisted firing (slots missed during downtime).
+            const latest = existing ? null : this.repos.cronFirings.latest(wf.id);
+            const state = {
+                workflowId: wf.id,
+                expression: wf.trigger.cron,
+                timezone: wf.trigger.timezone,
+                schedule,
+                timer: undefined,
+                nextSlot: null,
+                lastHandled: latest ? new Date(latest.scheduledFor) : now,
+                catchUp: latest !== null,
+                quietDecision: latest && QUIET_DECISIONS.has(latest.decision) ? latest.decision : null,
+                chain: Promise.resolve(),
+                lastConditions: [],
+                removed: false,
+            };
+            this.cron.set(wf.id, state);
+            this.enqueueCron(state);
+        }
+        for (const [id, state] of [...this.cron]) {
+            if (seen.has(id))
+                continue;
+            this.disarm(state);
+            state.removed = true;
+            this.cron.delete(id);
+        }
+    }
+    disarm(state) {
+        if (state.timer)
+            this.timers.clearTimeout(state.timer);
+        state.timer = undefined;
+    }
+    enqueueCron(state) {
+        const next = state.chain.then(() => this.processDue(state));
+        state.chain = next.catch((err) => {
+            this.logger.error('cron handling failed', { workflowId: state.workflowId, error: errorMessage(err) });
+        });
+        void this.track(state.chain);
+    }
+    armCronTimer(state) {
+        if (this.stopped || state.removed)
+            return;
+        const now = this.clock.now();
+        const from = state.lastHandled.getTime() > now.getTime() ? state.lastHandled : now;
+        const next = state.schedule.next(from);
+        state.nextSlot = next;
+        if (!next)
+            return;
+        const delay = Math.min(Math.max(0, next.getTime() - now.getTime()), MAX_TIMER_DELAY_MS);
+        state.timer = this.timers.setTimeout(() => {
+            state.timer = undefined;
+            this.enqueueCron(state);
+        }, delay);
+    }
+    /** Handle all slots in `(lastHandled, now]`: the latest within tolerance fires, the rest are missed. */
+    async processDue(state) {
+        if (this.stopped || state.removed)
+            return;
+        this.disarm(state);
+        try {
+            await this.decideDue(state);
+        }
+        finally {
+            // Always re-arm: one failing slot (e.g. a DB error) must not stop the schedule.
+            this.armCronTimer(state);
+        }
+    }
+    async decideDue(state) {
+        const now = this.clock.now();
+        const due = dueSlots(state.schedule, state.lastHandled, now, { keep: this.maxRecordedMissed + 1, maxScan: MAX_CRON_SCAN });
+        const catchUp = state.catchUp;
+        state.catchUp = false;
+        if (due.slots.length > 0) {
+            const latest = due.slots[due.slots.length - 1];
+            const fire = now.getTime() - latest.getTime() <= this.misfireToleranceMs;
+            const missed = fire ? due.slots.slice(0, -1) : due.slots;
+            const notRecorded = due.total - due.slots.length;
+            missed.forEach((slot, i) => {
+                let reason = catchUp
+                    ? state.quietDecision
+                        ? `slot passed while the orchestrator was not running (or while still ${state.quietDecision})`
+                        : 'slot passed while the orchestrator was not running'
+                    : `slot handled ${Math.round((now.getTime() - slot.getTime()) / 1000)}s late (tolerance ${Math.round(this.misfireToleranceMs / 1000)}s)`;
+                if (i === 0 && (notRecorded > 0 || due.scanLimited))
+                    reason += ` (+${due.scanLimited ? 'at least ' : ''}${notRecorded} older missed slot(s) not recorded)`;
+                this.recordFiring(state, slot, 'skipped_missed', reason);
+            });
+            if (missed.length > 0) {
+                this.logger.warn('cron slots missed (not caught up)', { workflowId: state.workflowId, missed: missed.length + notRecorded });
+            }
+            state.lastHandled = latest;
+            if (fire)
+                await this.handleSlot(state, latest);
+        }
+    }
+    /**
+     * Persist a slot decision. Quiet skips (disabled / gate closed) are written
+     * only for the first slot of a series; later slots of the same series only
+     * advance `lastHandled` (no row flood for frequent schedules).
+     */
+    recordFiring(state, slot, decision, reason) {
+        const workflowId = state.workflowId;
+        const quiet = QUIET_DECISIONS.has(decision);
+        if (quiet && state.quietDecision === decision) {
+            this.logger.debug('cron slot (series continues, not recorded)', { workflowId, slot: slot.toISOString(), decision });
+            return;
+        }
+        const text = quiet ? `${reason ?? decision}; further slots are not recorded while this state lasts` : reason;
+        const { inserted } = this.repos.cronFirings.record({ workflowId, scheduledFor: slot, decision, reason: text });
+        state.quietDecision = quiet ? decision : null;
+        if (inserted)
+            this.logger.info('cron slot', { workflowId, slot: slot.toISOString(), decision, reason: text });
+    }
+    /** Decide one due slot: start a run or record why not. */
+    async handleSlot(state, slot) {
+        const workflowId = state.workflowId;
+        if (this.repos.cronFirings.get(workflowId, slot))
+            return; // already handled (e.g. before a restart)
+        const pre = this.slotPrecondition(workflowId);
+        if (pre)
+            return this.recordFiring(state, slot, pre.decision, pre.reason);
+        const eff = this.config.getWorkflow(workflowId);
+        if (eff.config.conditions.workflow.length > 0) {
+            const outcome = await this.checks.workflowConditions(eff.config);
+            state.lastConditions = outcome.checks;
+            if (outcome.value !== true) {
+                const f = outcome.failed;
+                const what = `workflow condition ${f?.index ?? '?'} (${f?.command ?? ''})`;
+                return outcome.value === false
+                    ? this.recordFiring(state, slot, 'skipped_condition', `${what} is false`)
+                    : this.recordFiring(state, slot, 'skipped_condition_unknown', `${what} is unknown: ${f?.error ?? 'check error'}`);
+            }
+            if (this.stopped)
+                return;
+            const again = this.slotPrecondition(workflowId);
+            if (again)
+                return this.recordFiring(state, slot, again.decision, again.reason);
+        }
+        // Synchronous: record + reserve in one transaction (at most one run per slot).
+        let run;
+        try {
+            run = this.repos.transaction(() => {
+                const { inserted } = this.repos.cronFirings.record({ workflowId, scheduledFor: slot, decision: 'started', reason: null });
+                if (!inserted)
+                    return null;
+                const reserved = this.repos.runs.reserve({
+                    workflowId,
+                    triggerType: 'schedule',
+                    scheduledFor: slot,
+                    configSnapshot: this.config.snapshotWorkflow(workflowId),
+                    parameters: automaticParameterValues(eff.config),
+                    failIfBlocked: true,
+                });
+                this.repos.cronFirings.update(workflowId, slot, { runId: reserved.id });
+                return reserved;
+            });
+        }
+        catch (err) {
+            if (err instanceof BlockedError)
+                return this.recordFiring(state, slot, 'skipped_blocked', `retry block ${err.blockId}`);
+            if (err instanceof LockConflictError)
+                return this.recordFiring(state, slot, 'skipped_lock', `slot lock held by run ${err.holderRunId}`);
+            this.logger.error('cron reservation failed', { workflowId, slot: slot.toISOString(), error: errorMessage(err) });
+            return this.recordFiring(state, slot, 'start_failed', errorMessage(err));
+        }
+        if (!run)
+            return;
+        state.quietDecision = null;
+        this.logger.info('cron slot', { workflowId, slot: slot.toISOString(), decision: 'started', runId: run.id });
+        try {
+            this.controller.startRun(run);
+        }
+        catch (err) {
+            this.repos.cronFirings.update(workflowId, slot, { decision: 'start_failed', reason: errorMessage(err) });
+        }
+    }
+    /** Synchronous checks before a slot may start (enabled, gate, limits, block). */
+    slotPrecondition(workflowId) {
+        const eff = this.config.getWorkflow(workflowId);
+        if (!eff || eff.config.trigger.type !== 'schedule')
+            return { decision: 'skipped_disabled', reason: 'workflow no longer scheduled' };
+        if (!eff.enabled)
+            return { decision: 'skipped_disabled', reason: 'workflow is disabled' };
+        const gate = this.stopped ? 'draining' : this.gateReason();
+        if (gate)
+            return { decision: `skipped_${gate}`, reason: `automatic starts not possible (${gate})` };
+        const capacity = this.capacityProblem(workflowId);
+        if (capacity)
+            return { decision: 'skipped_limit', reason: capacity.reason };
+        const block = this.state.activeBlock(workflowId, null);
+        if (block)
+            return { decision: 'skipped_blocked', reason: `retry block ${block.id}: ${block.reason}` };
+        return null;
+    }
+    // ---------------------------------------------------------------------------
+    // Manual start (Spec §5.5, §7)
+    /**
+     * Start a workflow manually. Bypasses filters, conditions, retry blocks,
+     * priorities and limits (and `enabled`/pause), but never the active lock of
+     * the workflow+item (`LockConflictError`, HTTP 409). The run counts towards
+     * the limits of automatic starts.
+     *
+     * @throws UnknownWorkflowError, SchedulerError, LockConflictError
+     */
+    async startManual(workflowId, request = {}) {
+        const eff = this.config.getWorkflow(workflowId);
+        if (!eff)
+            throw new UnknownWorkflowError(workflowId);
+        this.assertAcceptsManual();
+        const workflow = eff.config;
+        const ref = request.itemRef?.trim() ?? '';
+        if (workflow.trigger.type !== 'source' && ref) {
+            throw new SchedulerError('manual_item_not_supported', `Workflow '${workflowId}' (${workflow.trigger.type}) has no source items`);
+        }
+        const params = this.config.validateParameters(workflowId, request.parameters);
+        if (!params.ok) {
+            throw new SchedulerError('invalid_parameters', `Invalid parameters for workflow '${workflowId}'`, { errors: params.errors });
+        }
+        let item = null;
+        if (workflow.trigger.type === 'source') {
+            const sourceId = workflow.trigger.source;
+            if (!ref)
+                throw new SchedulerError('manual_item_required', `Workflow '${workflowId}' needs an item reference (URL or ID)`);
+            const adapter = this.sources(sourceId);
+            if (!adapter)
+                throw new SchedulerError('source_unavailable', `Source '${sourceId}' is not available`, { sourceId });
+            const itemId = adapter.parseItemRef(ref);
+            if (itemId === null) {
+                throw new SchedulerError('manual_item_invalid_ref', `'${ref}' is not an item reference of source '${sourceId}'`, { sourceId, itemRef: ref });
+            }
+            let found;
+            try {
+                found = await adapter.getItem(itemId);
+            }
+            catch (err) {
+                throw new SchedulerError('source_unavailable', `Reading item ${itemId} from '${sourceId}' failed: ${errorMessage(err)}`, { sourceId, itemId }, err);
+            }
+            if (!found)
+                throw new SchedulerError('manual_item_not_found', `Item ${itemId} not found in source '${sourceId}'`, { sourceId, itemId });
+            item = { sourceId, key: found.key, url: found.url };
+        }
+        // Synchronous from here: re-check acceptance, reserve (lock only, no block/limit check), start.
+        this.assertAcceptsManual();
+        const values = params.values;
+        const run = this.repos.runs.reserve({
+            workflowId,
+            triggerType: 'manual',
+            sourceId: item?.sourceId ?? null,
+            sourceItemKey: item?.key ?? null,
+            sourceUrl: item?.url ?? null,
+            configSnapshot: this.config.snapshotWorkflow(workflowId),
+            parameters: Object.keys(values).length > 0 ? values : null,
+            failIfBlocked: false,
+        });
+        this.logger.info('manual run reserved', { workflowId, runId: run.id, item: item?.key ?? null });
+        const handle = this.controller.startRun(run);
+        return { run, done: handle.done };
+    }
+    assertAcceptsManual() {
+        if (this.stopped || !this.controller.canStartManually()) {
+            const s = this.controller.status;
+            const reason = this.stopped ? 'scheduler stopped' : !s.ready ? 'recovery not finished' : 'draining / shutting down';
+            throw new SchedulerError('scheduler_not_accepting', `Manual starts are currently not possible: ${reason}`, { reason });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Dry-run and diagnostics (GUI/API)
+    /** Dry-run a workflow (no reservation, no actions, no shell checks). @throws UnknownWorkflowError */
+    dryRun(workflowId, options = {}) {
+        return dryRunWorkflow({
+            config: this.config,
+            sources: this.sources,
+            state: this.state,
+            clock: this.clock,
+            gate: () => this.gateInfo(),
+            ...(options.signal ? { signal: options.signal } : {}),
+        }, workflowId);
+    }
+    /** Last planning diagnosis of a source workflow (`undefined` before its first step). */
+    lastDiagnosis(workflowId) {
+        return this.diagnoses.get(workflowId);
+    }
+    /** Last planning diagnoses of all source workflows, sorted by workflow ID. */
+    listDiagnoses() {
+        return [...this.diagnoses.values()].sort((a, b) => (a.workflowId < b.workflowId ? -1 : a.workflowId > b.workflowId ? 1 : 0));
+    }
+    /** Summary of the last planning step (`null` before the first one). */
+    lastPlanningStep() {
+        return this.lastReport;
+    }
+    /** Cron status of all schedule workflows, sorted by workflow ID. */
+    cronStatus() {
+        return [...this.cron.values()]
+            .map((s) => {
+            const latest = this.repos.cronFirings.latest(s.workflowId);
+            return {
+                workflowId: s.workflowId,
+                cron: s.expression,
+                timezone: s.timezone,
+                enabled: this.config.getWorkflow(s.workflowId)?.enabled ?? false,
+                nextSlot: s.nextSlot?.toISOString() ?? null,
+                lastFiring: latest,
+                lastConditions: s.lastConditions,
+            };
+        })
+            .sort((a, b) => (a.workflowId < b.workflowId ? -1 : a.workflowId > b.workflowId ? 1 : 0));
+    }
+}
+//# sourceMappingURL=scheduler.js.map