adispatchd 0.0.0-stage → 0.1.0

package/dist/scheduler/planner.js

@@ -0,0 +1,255 @@
+/**
+ * Candidate discovery and eligibility for source workflows (Spec §7 steps
+ * 1–5), shared by the planning step and the dry-run.
+ *
+ * - Step 1: poll the source with the pushed-down part of the filter and
+ *   evaluate the filter with CHEAP fields only. Strong Kleene logic is
+ *   monotonic, so a cheap `false` is final (item dropped) and a cheap `true`
+ *   is final; only a cheap `unknown` needs the expensive fields (step 5).
+ * - Step 2: de-duplicate by `(source, item, workflow)`.
+ * - Step 3: item priority (same field source → one batch of expensive fields).
+ * - Step 4: active lock / retry block of the workflow+item.
+ * - Step 5 (lazy): workflow conditions (once per step), expensive declarative
+ *   filter, shell filter, item conditions. The dry-run never executes shell
+ *   checks: they are reported as `not_evaluated`.
+ */
+import { errorMessage, } from '../core/index.js';
+import { collectFields, createItemFieldSource, evaluateFilter, resolveItemPriority, splitForPushdown, } from '../filters/index.js';
+import { notEvaluatedCheck, notEvaluatedConditions } from './checks.js';
+/** Field source that treats expensive fields as unknown without resolving them. */
+export function cheapOnly(fields) {
+    return {
+        isExpensive: (f) => fields.isExpensive?.(f) ?? false,
+        fieldType: (f) => fields.fieldType?.(f),
+        isCaseInsensitive: (f) => fields.isCaseInsensitive?.(f) ?? false,
+        resolve(field) {
+            if (fields.isExpensive?.(field))
+                return { known: false, reason: 'expensive field, evaluated later' };
+            return fields.resolve(field);
+        },
+    };
+}
+function emptyDiagnosis(workflow, at, sourceId) {
+    return {
+        workflowId: workflow.id,
+        at,
+        status: 'ok',
+        error: null,
+        sourceId,
+        polled: 0,
+        pushdown: null,
+        conditions: notEvaluatedConditions(workflow, 'workflow_condition'),
+        candidates: [],
+        omittedCandidates: 0,
+        startedRunIds: [],
+    };
+}
+/**
+ * Steps 1–3 for one source workflow: poll, de-duplicate, cheap filter, item
+ * priority. Never throws; source problems end up in the diagnosis
+ * (`status: 'source_error'`) without affecting other workflows.
+ */
+export async function prepareSourceWorkflow(workflow, workflowPriority, options) {
+    if (workflow.trigger.type !== 'source')
+        throw new TypeError(`Workflow ${workflow.id} is not source-triggered`);
+    const sourceId = workflow.trigger.source;
+    const diagnosis = emptyDiagnosis(workflow, options.at, sourceId);
+    const adapter = options.sources(sourceId);
+    if (!adapter) {
+        diagnosis.status = 'source_error';
+        diagnosis.error = `source '${sourceId}' is not available`;
+        return { diagnosis, candidates: [], rejected: [] };
+    }
+    const filter = workflow.filter;
+    const definitions = adapter.fieldDefinitions();
+    let pushdown = null;
+    if (filter)
+        pushdown = splitForPushdown(filter, definitions).pushdown;
+    diagnosis.pushdown = pushdown;
+    let items;
+    try {
+        const key = `${sourceId}\u0000${JSON.stringify(pushdown)}`;
+        let listing = options.listCache?.get(key);
+        if (!listing) {
+            listing = adapter.listCandidates({
+                ...(pushdown ? { filter: pushdown } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            options.listCache?.set(key, listing);
+        }
+        items = await listing;
+    }
+    catch (err) {
+        diagnosis.status = 'source_error';
+        diagnosis.error = `polling source '${sourceId}' failed: ${errorMessage(err)}`;
+        return { diagnosis, candidates: [], rejected: [] };
+    }
+    // Step 2: normalize (source-id, item-id, workflow-id).
+    const unique = new Map();
+    for (const item of items)
+        if (!unique.has(item.key))
+            unique.set(item.key, item);
+    diagnosis.polled = unique.size;
+    const wanted = new Set(filter ? collectFields(filter) : []);
+    for (const rule of workflow.itemPriority?.rules ?? [])
+        for (const f of collectFields(rule.when))
+            wanted.add(f);
+    const wantedFields = [...wanted];
+    const candidates = [];
+    const rejected = [];
+    for (const item of unique.values()) {
+        const fields = createItemFieldSource(item, {
+            definitions,
+            resolveFields: (i, f) => adapter.resolveFields(i, f, options.signal ? { signal: options.signal } : {}),
+            wantedFields,
+        });
+        const cheap = filter ? await evaluateFilter(filter, cheapOnly(fields)) : null;
+        const title = item.fields.title;
+        const diag = {
+            workflowId: workflow.id,
+            sourceId,
+            itemId: item.itemId,
+            itemKey: item.key,
+            url: item.url,
+            title: typeof title === 'string' ? title : null,
+            createdAt: item.createdAt ?? null,
+            workflowPriority,
+            itemPriority: 0,
+            matchedPriorityRule: null,
+            decision: 'filtered',
+            reason: null,
+            filter: cheap?.trace ?? null,
+            shellFilter: null,
+            itemConditions: [],
+            runId: null,
+            blockId: null,
+        };
+        if (cheap?.value === false) {
+            diag.reason = 'declarative filter does not match';
+            rejected.push(diag);
+            continue;
+        }
+        // Step 3: item priority (rules may need expensive fields: same memoized batch).
+        const priority = await resolveItemPriority(workflow.itemPriority, fields);
+        diag.itemPriority = priority.priority;
+        diag.matchedPriorityRule = priority.matchedRule;
+        candidates.push({
+            workflowId: workflow.id,
+            workflowPriority,
+            itemPriority: priority.priority,
+            createdAt: item.createdAt,
+            itemKey: item.key,
+            workflow,
+            adapter,
+            item,
+            fields,
+            cheap,
+            diagnosis: diag,
+        });
+    }
+    return { diagnosis, candidates, rejected };
+}
+/**
+ * Steps 4–5 for one candidate (lock, block, workflow conditions, expensive
+ * filter, shell filter, item conditions). Updates `candidate.diagnosis` with
+ * decision/reason for rejected candidates. Capacity is checked by the caller.
+ */
+export async function checkEligibility(candidate, ctx) {
+    const { workflow, diagnosis: diag } = candidate;
+    const reject = (decision, reason) => {
+        diag.decision = decision;
+        diag.reason = reason;
+        return { eligible: false };
+    };
+    // Step 4: active lock / retry block.
+    const holder = ctx.state.activeRunForItem(workflow.id, candidate.itemKey);
+    if (holder) {
+        diag.runId = holder.id;
+        return reject('locked', `run ${holder.id} of this workflow is active for the item`);
+    }
+    const block = ctx.state.activeBlock(workflow.id, candidate.itemKey);
+    if (block) {
+        diag.blockId = block.id;
+        return reject('blocked', `retry block ${block.id}: ${block.reason}`);
+    }
+    let pending = false;
+    // Step 5a: workflow conditions (once per planning step).
+    if (workflow.conditions.workflow.length > 0) {
+        if (ctx.checks) {
+            const outcome = await ctx.workflowConditions(workflow);
+            if (outcome.value !== true) {
+                const f = outcome.failed;
+                return outcome.value === false
+                    ? reject('condition_failed', `workflow condition ${f?.index ?? '?'} (${f?.command ?? ''}) is false`)
+                    : reject('condition_unknown', `workflow condition ${f?.index ?? '?'} (${f?.command ?? ''}) is unknown: ${f?.error ?? 'check error'}`);
+            }
+        }
+        else {
+            pending = true;
+        }
+    }
+    // Step 5b: expensive declarative filter (only if the cheap pass could not decide).
+    if (workflow.filter && candidate.cheap && candidate.cheap.value !== true) {
+        const full = await evaluateFilter(workflow.filter, candidate.fields);
+        diag.filter = full.trace;
+        if (full.value === false)
+            return reject('filtered', 'declarative filter does not match');
+        if (full.value === 'unknown')
+            return reject('filter_unknown', 'declarative filter is unknown (see trace)');
+    }
+    const target = {
+        item: candidate.item,
+        sourceType: candidate.adapter.type,
+        ...(candidate.adapter.repository !== undefined ? { repository: candidate.adapter.repository } : {}),
+    };
+    // Step 5c: shell filter.
+    if (workflow.shellFilter) {
+        if (ctx.checks) {
+            const sf = await ctx.checks.shellFilter(workflow, workflow.shellFilter, target, ctx.signal);
+            diag.shellFilter = sf;
+            if (sf.value === false)
+                return reject('shell_filter_rejected', 'shell filter exited with 1');
+            if (sf.value !== true)
+                return reject('shell_filter_unknown', `shell filter check error: ${sf.error ?? 'unknown'}`);
+        }
+        else {
+            diag.shellFilter = notEvaluatedCheck('shell_filter', 0, workflow.shellFilter.command);
+            pending = true;
+        }
+    }
+    // Step 5d: item conditions.
+    if (workflow.conditions.item.length > 0) {
+        if (ctx.checks) {
+            const outcome = await ctx.checks.itemConditions(workflow, target, ctx.signal);
+            diag.itemConditions = outcome.checks;
+            if (outcome.value !== true) {
+                const f = outcome.failed;
+                return outcome.value === false
+                    ? reject('condition_failed', `item condition ${f.index} (${f.command}) is false`)
+                    : reject('condition_unknown', `item condition ${f.index} (${f.command}) is unknown: ${f.error ?? 'check error'}`);
+            }
+        }
+        else {
+            diag.itemConditions = notEvaluatedConditions(workflow, 'item_condition');
+            pending = true;
+        }
+    }
+    return { eligible: true, pendingChecks: pending };
+}
+/**
+ * Re-check for the item re-read by the run controller right before `on_start`
+ * (Spec §7 races): the cheap part of the filter on the fresh item. `false`
+ * cancels the run without hooks; `unknown` (expensive fields) does not.
+ */
+export function verifyItemFor(workflow, adapter) {
+    const filter = workflow.filter;
+    if (!filter)
+        return undefined;
+    const definitions = adapter.fieldDefinitions();
+    return async (item) => {
+        const fields = createItemFieldSource(item, { definitions });
+        const result = await evaluateFilter(filter, cheapOnly(fields));
+        return result.value !== false;
+    };
+}
+//# sourceMappingURL=planner.js.map

package/dist/scheduler/planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.js","sourceRoot":"","sources":["../../src/scheduler/planner.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/scheduler.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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 { type Clock, type Logger, type Timers } from '../core/index.js';
+import { type ConfigManager } from '../config/index.js';
+import { ShellCheckRunner } from '../filters/index.js';
+import { type Repositories, type RunRecord } from '../persistence/index.js';
+import type { ControllerStatus, RunHandle, StartRunOptions } from '../runs/index.js';
+import { type SourceLookup } from './planner.js';
+import { type CronWorkflowStatus, type DryRunResult, type PlanningStepReport, type WorkflowPlanningDiagnosis } from './types.js';
+/** The part of the run controller (WI-08) the scheduler needs. */
+export interface SchedulerRunController {
+    readonly status: ControllerStatus;
+    canStartAutomatically(): boolean;
+    canStartManually(): boolean;
+    startRun(run: RunRecord, options?: StartRunOptions): RunHandle;
+}
+/** Dependencies and tuning of the {@link Scheduler}. */
+export interface SchedulerOptions {
+    /** Live configuration incl. runtime overrides (effective values). */
+    config: ConfigManager;
+    repositories: Repositories;
+    controller: SchedulerRunController;
+    /** Source adapters by configured source ID. */
+    sources: SourceLookup;
+    /** Runner for shell filters/conditions (holds the workflow-condition cache). Default: a new one. */
+    shellChecks?: ShellCheckRunner;
+    clock?: Clock;
+    /** Timers for the polling loop and cron (FakeClock in tests). */
+    timers?: Timers;
+    logger?: Logger;
+    /**
+     * A cron slot is still started if it is handled at most this late (timer
+     * latency, short restart); later slots are `skipped_missed`. Default 60 s.
+     */
+    cronMisfireToleranceMs?: number;
+    /** Max. `skipped_missed` records written per catch-up (older ones are only counted). Default 100. */
+    maxRecordedMissedSlots?: number;
+}
+/** Request of {@link Scheduler.startManual}. */
+export interface ManualStartRequest {
+    /** Item reference (URL or ID) – required for source workflows, rejected otherwise. */
+    itemRef?: string;
+    /** Parameter values (validated against the workflow's `parameters`). */
+    parameters?: Readonly<Record<string, unknown>>;
+}
+/** Result of {@link Scheduler.startManual}. */
+export interface ManualStartResult {
+    /** The reserved run (status `reserved` at return time). */
+    run: RunRecord;
+    /** Resolves when the controller finished supervising the run. */
+    done: Promise<RunRecord>;
+}
+/** See module docs. One instance per process, created after the run controller's recovery. */
+export declare class Scheduler {
+    private readonly config;
+    private readonly repos;
+    private readonly controller;
+    private readonly sources;
+    private readonly state;
+    private readonly shellChecks;
+    private readonly checks;
+    private readonly clock;
+    private readonly timers;
+    private readonly logger;
+    private readonly misfireToleranceMs;
+    private readonly maxRecordedMissed;
+    private started;
+    private stopped;
+    private pollTimer;
+    private stepChain;
+    private readonly inflight;
+    private readonly diagnoses;
+    private lastReport;
+    private readonly cron;
+    private unsubscribeConfig;
+    constructor(options: SchedulerOptions);
+    /**
+     * 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(): void;
+    /** Stop polling and cron timers; waits for running planning steps / cron handlers. Idempotent. */
+    stop(): Promise<void>;
+    /** Resolves once no planning step and no cron handler is in flight (tests, shutdown). */
+    whenIdle(): Promise<void>;
+    private track;
+    /** One loop iteration: planning step, then arm the next poll (never overlapping). */
+    private loopStep;
+    private armPoll;
+    private gateReason;
+    private gateInfo;
+    /** Limit check with live effective values (overrides apply immediately). */
+    private capacityProblem;
+    /**
+     * 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(): Promise<PlanningStepReport>;
+    private planningStep;
+    /** Steps 4–7 for one candidate; returns the started run ID. */
+    private considerCandidate;
+    /** Arm/re-arm cron timers for the schedule workflows of the active configuration. */
+    private syncCron;
+    private disarm;
+    private enqueueCron;
+    private armCronTimer;
+    /** Handle all slots in `(lastHandled, now]`: the latest within tolerance fires, the rest are missed. */
+    private processDue;
+    private decideDue;
+    /**
+     * 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).
+     */
+    private recordFiring;
+    /** Decide one due slot: start a run or record why not. */
+    private handleSlot;
+    /** Synchronous checks before a slot may start (enabled, gate, limits, block). */
+    private slotPrecondition;
+    /**
+     * 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
+     */
+    startManual(workflowId: string, request?: ManualStartRequest): Promise<ManualStartResult>;
+    private assertAcceptsManual;
+    /** Dry-run a workflow (no reservation, no actions, no shell checks). @throws UnknownWorkflowError */
+    dryRun(workflowId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DryRunResult>;
+    /** Last planning diagnosis of a source workflow (`undefined` before its first step). */
+    lastDiagnosis(workflowId: string): WorkflowPlanningDiagnosis | undefined;
+    /** Last planning diagnoses of all source workflows, sorted by workflow ID. */
+    listDiagnoses(): WorkflowPlanningDiagnosis[];
+    /** Summary of the last planning step (`null` before the first one). */
+    lastPlanningStep(): PlanningStepReport | null;
+    /** Cron status of all schedule workflows, sorted by workflow ID. */
+    cronStatus(): CronWorkflowStatus[];
+}