adispatchd 0.0.0-stage → 0.1.0

package/dist/scheduler/cron.js

@@ -0,0 +1,83 @@
+/**
+ * Cron slot computation on top of croner (Spec §5.5, §7, §24.7). Pure
+ * functions; the DST semantics are pinned by tests and documented in
+ * `docs/cron-semantics.md`.
+ */
+import { Cron } from 'croner';
+/**
+ * Parse a cron expression for a time zone (croner syntax, 5 or 6 fields).
+ * @throws Error for invalid expressions/time zones (config validation rejects them earlier).
+ */
+export function parseCron(expression, timezone) {
+    const job = new Cron(expression, { paused: true, timezone });
+    return {
+        expression,
+        timezone,
+        next(after) {
+            // croner works with second precision: a reference inside a second is
+            // treated as that second, so `next` is strictly after `after`.
+            const next = job.nextRun(after);
+            return next && next.getTime() > after.getTime() ? next : null;
+        },
+    };
+}
+/** The next `count` slots strictly after `after`. */
+export function nextSlots(schedule, after, count) {
+    const out = [];
+    let cursor = after;
+    while (out.length < count) {
+        const next = schedule.next(cursor);
+        if (!next)
+            break;
+        out.push(next);
+        cursor = next;
+    }
+    return out;
+}
+/**
+ * All slots in `(after, now]`, keeping only the most recent `keep` of them.
+ * Scanning is bounded by `maxScan`; if hit, scanning restarts closer to
+ * `now` so that the most recent slots are still found.
+ */
+export function dueSlots(schedule, after, now, options) {
+    const keep = Math.max(1, options.keep);
+    let slots = [];
+    let total = 0;
+    let scanned = 0;
+    let cursor = after;
+    let scanLimited = false;
+    for (;;) {
+        const next = schedule.next(cursor);
+        if (!next || next.getTime() > now.getTime())
+            break;
+        slots.push(next);
+        if (slots.length > keep)
+            slots = slots.slice(-keep);
+        total++;
+        cursor = next;
+        if (++scanned >= options.maxScan) {
+            // Too many slots (e.g. a per-second schedule after a long downtime):
+            // jump to a window right before `now` and only collect the latest ones.
+            scanLimited = true;
+            const windowStart = new Date(now.getTime() - estimateWindowMs(schedule, now, keep));
+            if (windowStart.getTime() <= cursor.getTime())
+                continue;
+            cursor = windowStart;
+            slots = [];
+            scanned = 0;
+        }
+    }
+    return { slots, total: Math.max(total, slots.length), scanLimited };
+}
+/** Rough time span that contains about `keep` slots before `now` (doubling search, bounded). */
+function estimateWindowMs(schedule, now, keep) {
+    let span = 60_000;
+    for (let i = 0; i < 40; i++) {
+        const found = nextSlots(schedule, new Date(now.getTime() - span), keep + 1).filter((d) => d.getTime() <= now.getTime());
+        if (found.length >= keep)
+            return span;
+        span *= 2;
+    }
+    return span;
+}
+//# sourceMappingURL=cron.js.map

package/dist/scheduler/cron.js.map

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

package/dist/scheduler/dry-run.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Workflow dry-run (Spec §19): source query, declarative filter analysis
+ * (incl. dependencies), priorities, locks/blocks and capacity – without
+ * workers, lifecycle actions, reservations or shell filters/conditions
+ * (reported as `not_evaluated`). Read-only.
+ *
+ * Differences to a real planning step (documented in the handoff):
+ * - Eligibility is evaluated before capacity, so every candidate shows its
+ *   filter/lock/block status even when the limits are exhausted; capacity is
+ *   then simulated in priority order (`pending_checks` candidates consume a
+ *   slot, assuming their checks pass).
+ * - Eligible candidates of a disabled workflow / with closed controller gate
+ *   are reported as `workflow_unavailable` / `gate_closed`, never `would_start`.
+ * - Only the given workflow is considered; higher-priority workflows that
+ *   would take global slots first are not simulated.
+ */
+import { type Clock } from '../core/index.js';
+import { type ConfigManager } from '../config/index.js';
+import { type SourceLookup } from './planner.js';
+import type { SchedulingState } from './state.js';
+import type { DryRunResult, GateInfo } from './types.js';
+/** Dependencies of {@link dryRunWorkflow}. */
+export interface DryRunDeps {
+    config: ConfigManager;
+    sources: SourceLookup;
+    state: SchedulingState;
+    clock?: Clock;
+    /** Controller gate; omit when no controller runs (local CLI dry-run). */
+    gate?: () => GateInfo;
+    /** Additional notes (e.g. "no database"). */
+    notes?: readonly string[];
+    signal?: AbortSignal;
+}
+/** Number of upcoming cron slots shown. */
+export declare const DRY_RUN_CRON_SLOTS = 5;
+/** Number of recent cron firings shown. */
+export declare const DRY_RUN_RECENT_FIRINGS = 10;
+/**
+ * Dry-run one workflow.
+ * @throws UnknownWorkflowError
+ */
+export declare function dryRunWorkflow(deps: DryRunDeps, workflowId: string): Promise<DryRunResult>;

package/dist/scheduler/dry-run.js

@@ -0,0 +1,167 @@
+/**
+ * Workflow dry-run (Spec §19): source query, declarative filter analysis
+ * (incl. dependencies), priorities, locks/blocks and capacity – without
+ * workers, lifecycle actions, reservations or shell filters/conditions
+ * (reported as `not_evaluated`). Read-only.
+ *
+ * Differences to a real planning step (documented in the handoff):
+ * - Eligibility is evaluated before capacity, so every candidate shows its
+ *   filter/lock/block status even when the limits are exhausted; capacity is
+ *   then simulated in priority order (`pending_checks` candidates consume a
+ *   slot, assuming their checks pass).
+ * - Eligible candidates of a disabled workflow / with closed controller gate
+ *   are reported as `workflow_unavailable` / `gate_closed`, never `would_start`.
+ * - Only the given workflow is considered; higher-priority workflows that
+ *   would take global slots first are not simulated.
+ */
+import { systemClock } from '../core/index.js';
+import { UnknownWorkflowError } from '../config/index.js';
+import { sortCandidates } from '../filters/index.js';
+import { notEvaluatedConditions } from './checks.js';
+import { nextSlots, parseCron } from './cron.js';
+import { checkEligibility, prepareSourceWorkflow } from './planner.js';
+/** Number of upcoming cron slots shown. */
+export const DRY_RUN_CRON_SLOTS = 5;
+/** Number of recent cron firings shown. */
+export const DRY_RUN_RECENT_FIRINGS = 10;
+/**
+ * Dry-run one workflow.
+ * @throws UnknownWorkflowError
+ */
+export async function dryRunWorkflow(deps, workflowId) {
+    const eff = deps.config.getWorkflow(workflowId);
+    if (!eff)
+        throw new UnknownWorkflowError(workflowId);
+    const workflow = eff.config;
+    const now = (deps.clock ?? systemClock).now();
+    const gate = deps.gate ? deps.gate() : null;
+    const notes = [...(deps.notes ?? [])];
+    if (!eff.enabled)
+        notes.push('workflow is disabled: no automatic starts (manual starts remain possible)');
+    if (gate === null)
+        notes.push('controller state unknown (no running instance): pause/drain/readiness not considered');
+    else if (!gate.canStartAutomatically)
+        notes.push(`automatic starts are currently not possible: ${gate.reason ?? 'unknown'}`);
+    notes.push('shell filters and conditions are never executed in a dry-run (not_evaluated)');
+    const globalActive = deps.state.countActive();
+    const workflowActive = deps.state.countActive(workflowId);
+    const capacity = {
+        global: { active: globalActive, max: deps.config.maxConcurrent },
+        workflow: { active: workflowActive, max: eff.maxConcurrent },
+    };
+    const result = {
+        workflowId,
+        name: workflow.name,
+        trigger: workflow.trigger,
+        generatedAt: now.toISOString(),
+        enabled: eff.enabled,
+        workflowPriority: eff.priority,
+        capacity,
+        gate,
+        conditions: notEvaluatedConditions(workflow, 'workflow_condition'),
+        source: null,
+        candidates: [],
+        cron: null,
+        notes,
+        summary: { candidates: 0, wouldStart: 0, pendingChecks: 0, notStartable: 0 },
+    };
+    const trigger = workflow.trigger;
+    if (trigger.type === 'source') {
+        const prepared = await prepareSourceWorkflow(workflow, eff.priority, {
+            sources: deps.sources,
+            at: result.generatedAt,
+            ...(deps.signal ? { signal: deps.signal } : {}),
+        });
+        result.source = {
+            sourceId: trigger.source,
+            polled: prepared.diagnosis.polled,
+            pushdown: prepared.diagnosis.pushdown,
+            error: prepared.diagnosis.error,
+        };
+        let simGlobal = globalActive;
+        let simWorkflow = workflowActive;
+        const ordered = [];
+        for (const candidate of sortCandidates(prepared.candidates)) {
+            const eligibility = await checkEligibility(candidate, {
+                state: deps.state,
+                checks: null,
+                workflowConditions: () => Promise.reject(new Error('shell checks are not executed in a dry-run')),
+                ...(deps.signal ? { signal: deps.signal } : {}),
+            });
+            const diag = candidate.diagnosis;
+            ordered.push(diag);
+            if (!eligibility.eligible)
+                continue;
+            if (!eff.enabled) {
+                diag.decision = 'workflow_unavailable';
+                diag.reason = 'eligible, but the workflow is disabled (no automatic starts)';
+            }
+            else if (gate && !gate.canStartAutomatically) {
+                diag.decision = 'gate_closed';
+                diag.reason = `eligible, but automatic starts are currently not possible (${gate.reason ?? 'unknown'})`;
+            }
+            else if (simGlobal >= capacity.global.max) {
+                diag.decision = 'global_limit';
+                diag.reason = `global limit reached (${simGlobal}/${capacity.global.max}, incl. candidates above)`;
+            }
+            else if (simWorkflow >= capacity.workflow.max) {
+                diag.decision = 'workflow_limit';
+                diag.reason = `workflow limit reached (${simWorkflow}/${capacity.workflow.max}, incl. candidates above)`;
+            }
+            else {
+                simGlobal++;
+                simWorkflow++;
+                diag.decision = eligibility.pendingChecks ? 'pending_checks' : 'would_start';
+                diag.reason = eligibility.pendingChecks
+                    ? 'declaratively eligible; would start if the shell filter/conditions pass'
+                    : 'eligible; would start';
+            }
+        }
+        result.candidates = [...ordered, ...prepared.rejected];
+    }
+    else if (trigger.type === 'schedule') {
+        const schedule = parseCron(trigger.cron, trigger.timezone);
+        const block = deps.state.activeBlock(workflowId, null);
+        let forecast;
+        let reason = null;
+        if (!eff.enabled)
+            forecast = 'skipped_disabled';
+        else if (gate && !gate.canStartAutomatically && gate.reason)
+            forecast = `skipped_${gate.reason}`;
+        else if (globalActive >= capacity.global.max || workflowActive >= capacity.workflow.max) {
+            forecast = 'skipped_limit';
+            reason = `active runs: global ${globalActive}/${capacity.global.max}, workflow ${workflowActive}/${capacity.workflow.max}`;
+        }
+        else if (block) {
+            forecast = 'skipped_blocked';
+            reason = `retry block ${block.id}: ${block.reason}`;
+        }
+        else if (workflow.conditions.workflow.length > 0) {
+            forecast = 'pending_checks';
+            reason = 'would start if the workflow conditions pass';
+        }
+        else
+            forecast = 'would_start';
+        result.cron = {
+            cron: trigger.cron,
+            timezone: trigger.timezone,
+            nextSlots: nextSlots(schedule, now, DRY_RUN_CRON_SLOTS).map((d) => d.toISOString()),
+            nextSlotForecast: forecast,
+            forecastReason: reason,
+            recentFirings: deps.state.recentCronFirings(workflowId, DRY_RUN_RECENT_FIRINGS),
+            blockId: block?.id ?? null,
+        };
+    }
+    else {
+        notes.push('manual workflow: runs only start manually (filters, conditions, blocks and limits do not apply)');
+    }
+    const counted = result.candidates;
+    result.summary = {
+        candidates: counted.length,
+        wouldStart: counted.filter((c) => c.decision === 'would_start').length,
+        pendingChecks: counted.filter((c) => c.decision === 'pending_checks').length,
+        notStartable: counted.filter((c) => c.decision !== 'would_start' && c.decision !== 'pending_checks').length,
+    };
+    return result;
+}
+//# sourceMappingURL=dry-run.js.map

package/dist/scheduler/dry-run.js.map

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

package/dist/scheduler/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Errors of the scheduler's manual start / dry-run API. All extend
+ * {@link OrchestratorError}; WI-10 maps the stable `code` to HTTP:
+ *
+ * | code | HTTP |
+ * |---|---|
+ * | `manual_item_required`, `manual_item_not_supported`, `manual_item_invalid_ref`, `invalid_parameters` | 400 |
+ * | `manual_item_not_found` | 404 |
+ * | `source_unavailable` | 502 |
+ * | `scheduler_not_accepting` | 503 |
+ *
+ * Unknown workflows throw `UnknownWorkflowError` (config, `config_unknown_workflow` → 404);
+ * an active lock throws `LockConflictError` (persistence, `lock_conflict` → 409).
+ */
+import { OrchestratorError } from '../core/index.js';
+/** Codes of {@link SchedulerError}. */
+export type SchedulerErrorCode = 'manual_item_required' | 'manual_item_not_supported' | 'manual_item_invalid_ref' | 'manual_item_not_found' | 'invalid_parameters' | 'source_unavailable' | 'scheduler_not_accepting';
+/** Error of the scheduler API (see module docs for the HTTP mapping). */
+export declare class SchedulerError extends OrchestratorError {
+    readonly code: SchedulerErrorCode;
+    constructor(code: SchedulerErrorCode, message: string, details?: Record<string, unknown>, cause?: unknown);
+}

package/dist/scheduler/errors.js

@@ -0,0 +1,22 @@
+/**
+ * Errors of the scheduler's manual start / dry-run API. All extend
+ * {@link OrchestratorError}; WI-10 maps the stable `code` to HTTP:
+ *
+ * | code | HTTP |
+ * |---|---|
+ * | `manual_item_required`, `manual_item_not_supported`, `manual_item_invalid_ref`, `invalid_parameters` | 400 |
+ * | `manual_item_not_found` | 404 |
+ * | `source_unavailable` | 502 |
+ * | `scheduler_not_accepting` | 503 |
+ *
+ * Unknown workflows throw `UnknownWorkflowError` (config, `config_unknown_workflow` → 404);
+ * an active lock throws `LockConflictError` (persistence, `lock_conflict` → 409).
+ */
+import { OrchestratorError } from '../core/index.js';
+/** Error of the scheduler API (see module docs for the HTTP mapping). */
+export class SchedulerError extends OrchestratorError {
+    constructor(code, message, details, cause) {
+        super(code, message, { ...(details ? { details } : {}), ...(cause !== undefined ? { cause } : {}) });
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/scheduler/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/scheduler/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAYrD,yEAAyE;AACzE,MAAM,OAAO,cAAe,SAAQ,iBAAiB;IAGnD,YAAY,IAAwB,EAAE,OAAe,EAAE,OAAiC,EAAE,KAAe;QACvG,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACvG,CAAC;CACF"}

package/dist/scheduler/format.d.ts

@@ -0,0 +1,3 @@
+import type { DryRunResult } from './types.js';
+/** Render a dry-run result as plain text. */
+export declare function formatDryRun(r: DryRunResult): string;

package/dist/scheduler/format.js

@@ -0,0 +1,73 @@
+function traceLines(trace, indent) {
+    const value = String(trace.value);
+    switch (trace.kind) {
+        case 'all':
+        case 'any':
+            return [`${indent}${trace.kind}: ${value}`, ...trace.children.flatMap((c) => traceLines(c, `${indent}  `))];
+        case 'not':
+            return [`${indent}not: ${value}`, ...traceLines(trace.child, `${indent}  `)];
+        case 'predicate': {
+            const actual = 'actual' in trace && trace.actual !== undefined ? ` (actual ${JSON.stringify(trace.actual)})` : '';
+            const why = trace.reason ? ` – ${trace.reason}` : '';
+            return [`${indent}${trace.field} ${trace.operator} ${JSON.stringify(trace.expected)}: ${value}${actual}${why}`];
+        }
+        case 'invalid':
+            return [`${indent}invalid rule: ${value} – ${trace.reason}`];
+    }
+}
+function checkLine(c) {
+    const what = c.kind === 'shell_filter' ? 'shell filter' : `${c.kind.replace('_', ' ')} ${c.index}`;
+    const value = c.value === 'not_evaluated' ? 'unknown / not evaluated' : String(c.value);
+    return `${what} ${c.command}: ${value}${c.error ? ` – ${c.error}` : ''}`;
+}
+function candidateLines(c, n) {
+    const title = c.title ? ` "${c.title}"` : '';
+    const lines = [
+        `${String(n).padStart(3)}. ${c.itemKey}${title}`,
+        `     priority ${c.workflowPriority}/${c.itemPriority}${c.matchedPriorityRule !== null ? ` (rule ${c.matchedPriorityRule})` : ''}  →  ${c.decision}${c.reason ? `: ${c.reason}` : ''}`,
+        `     ${c.url}`,
+    ];
+    if (c.filter)
+        lines.push('     filter:', ...traceLines(c.filter, '       '));
+    if (c.shellFilter)
+        lines.push(`     ${checkLine(c.shellFilter)}`);
+    for (const ic of c.itemConditions)
+        lines.push(`     ${checkLine(ic)}`);
+    return lines;
+}
+/** Render a dry-run result as plain text. */
+export function formatDryRun(r) {
+    const t = r.trigger;
+    const trigger = t.type === 'source' ? `source ${t.source}` : t.type === 'schedule' ? `schedule '${t.cron}' (${t.timezone})` : 'manual';
+    const lines = [
+        `Dry-run of workflow '${r.workflowId}' (${r.name}) at ${r.generatedAt}`,
+        `  trigger: ${trigger}`,
+        `  enabled: ${r.enabled ? 'yes' : 'no'}, workflow priority: ${r.workflowPriority}`,
+        `  capacity: workflow ${r.capacity.workflow.active}/${r.capacity.workflow.max} active, global ${r.capacity.global.active}/${r.capacity.global.max} active`,
+    ];
+    if (r.gate)
+        lines.push(`  automatic starts: ${r.gate.canStartAutomatically ? 'possible' : `not possible (${r.gate.reason ?? 'unknown'})`}`);
+    for (const c of r.conditions)
+        lines.push(`  ${checkLine(c)}`);
+    if (r.source) {
+        lines.push(`  source ${r.source.sourceId}: ${r.source.polled} item(s) polled${r.source.pushdown ? `, pushdown ${JSON.stringify(r.source.pushdown)}` : ''}`);
+        if (r.source.error)
+            lines.push(`  SOURCE ERROR: ${r.source.error}`);
+        lines.push('', `Candidates (${r.summary.candidates}): ${r.summary.wouldStart} would start, ${r.summary.pendingChecks} pending checks, ${r.summary.notStartable} not startable`);
+        r.candidates.forEach((c, i) => lines.push(...candidateLines(c, i + 1)));
+    }
+    if (r.cron) {
+        lines.push(`  next slots: ${r.cron.nextSlots.join(', ') || '(none)'}`);
+        lines.push(`  next slot: ${r.cron.nextSlotForecast}${r.cron.forecastReason ? ` – ${r.cron.forecastReason}` : ''}`);
+        if (r.cron.recentFirings.length > 0) {
+            lines.push('  recent slots:');
+            for (const f of r.cron.recentFirings) {
+                lines.push(`    ${f.scheduledFor}  ${f.decision}${f.runId ? ` (${f.runId})` : ''}${f.reason ? ` – ${f.reason}` : ''}`);
+            }
+        }
+    }
+    if (r.notes.length > 0)
+        lines.push('', 'Notes:', ...r.notes.map((n) => `  - ${n}`));
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=format.js.map

package/dist/scheduler/format.js.map

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

package/dist/scheduler/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Component `scheduler` – public API (WI-09): polling loop for source
+ * workflows, cron trigger, manual start, dry-run and planning diagnostics.
+ * Other components import from this module only.
+ */
+export { Scheduler, type ManualStartRequest, type ManualStartResult, type SchedulerOptions, type SchedulerRunController, } from './scheduler.js';
+export { dryRunWorkflow, DRY_RUN_CRON_SLOTS, DRY_RUN_RECENT_FIRINGS, type DryRunDeps } from './dry-run.js';
+export { formatDryRun } from './format.js';
+export { SchedulerError, type SchedulerErrorCode } from './errors.js';
+export { repositoryState, emptyState, type SchedulingState } from './state.js';
+export { parseCron, nextSlots, dueSlots, type CronSchedule, type DueSlots } from './cron.js';
+export { cheapOnly, verifyItemFor, type SourceLookup } from './planner.js';
+export * from './types.js';

package/dist/scheduler/index.js

@@ -0,0 +1,14 @@
+/**
+ * Component `scheduler` – public API (WI-09): polling loop for source
+ * workflows, cron trigger, manual start, dry-run and planning diagnostics.
+ * Other components import from this module only.
+ */
+export { Scheduler, } from './scheduler.js';
+export { dryRunWorkflow, DRY_RUN_CRON_SLOTS, DRY_RUN_RECENT_FIRINGS } from './dry-run.js';
+export { formatDryRun } from './format.js';
+export { SchedulerError } from './errors.js';
+export { repositoryState, emptyState } from './state.js';
+export { parseCron, nextSlots, dueSlots } from './cron.js';
+export { cheapOnly, verifyItemFor } from './planner.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/scheduler/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,SAAS,GAKV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,sBAAsB,EAAmB,MAAM,cAAc,CAAC;AAC3G,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAA2B,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAwB,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAoC,MAAM,WAAW,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,aAAa,EAAqB,MAAM,cAAc,CAAC;AAC3E,cAAc,YAAY,CAAC"}

package/dist/scheduler/planner.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 { type SourceAdapter, type SourceItem } from '../core/index.js';
+import type { WorkflowConfig } from '../config/index.js';
+import { type FieldSource, type FilterEvaluation, type PrioritizedCandidate } from '../filters/index.js';
+import { type ChecksOutcome, type SchedulerChecks } from './checks.js';
+import type { SchedulingState } from './state.js';
+import type { CandidateDiagnosis, WorkflowPlanningDiagnosis } from './types.js';
+/** Resolves a configured source ID to its adapter. */
+export type SourceLookup = (sourceId: string) => SourceAdapter | undefined;
+/** A candidate that passed the cheap filter (or whose filter needs expensive fields). */
+export interface PreparedCandidate extends PrioritizedCandidate {
+    itemKey: string;
+    workflow: WorkflowConfig;
+    adapter: SourceAdapter;
+    item: SourceItem;
+    /** Memoizing field source of this planning step (expensive fields fetched at most once). */
+    fields: FieldSource;
+    /** Cheap-only filter evaluation; `null` if the workflow has no filter. */
+    cheap: FilterEvaluation | null;
+    diagnosis: CandidateDiagnosis;
+}
+/** Result of {@link prepareSourceWorkflow}. */
+export interface PreparedWorkflow {
+    diagnosis: WorkflowPlanningDiagnosis;
+    /** Candidates to consider, unsorted. */
+    candidates: PreparedCandidate[];
+    /** Items rejected by the cheap filter (diagnosis only). */
+    rejected: CandidateDiagnosis[];
+}
+/** Field source that treats expensive fields as unknown without resolving them. */
+export declare function cheapOnly(fields: FieldSource): FieldSource;
+/** Cache of `listCandidates` calls within one planning step: `(source, pushdown) → items`. */
+export type ListCache = Map<string, Promise<SourceItem[]>>;
+/**
+ * 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 declare function prepareSourceWorkflow(workflow: WorkflowConfig, workflowPriority: number, options: {
+    sources: SourceLookup;
+    at: string;
+    listCache?: ListCache;
+    signal?: AbortSignal;
+}): Promise<PreparedWorkflow>;
+/** Outcome of {@link checkEligibility}. */
+export type Eligibility = 
+/** Startable now; `pendingChecks` = shell checks were skipped (dry-run). */
+{
+    eligible: true;
+    pendingChecks: boolean;
+} | {
+    eligible: false;
+};
+/** How {@link checkEligibility} treats shell checks. */
+export interface EligibilityContext {
+    state: SchedulingState;
+    /** `null` = dry-run: shell filter and conditions are not executed. */
+    checks: SchedulerChecks | null;
+    /** Workflow conditions of the current step (memoized by the caller); only called in live mode. */
+    workflowConditions(workflow: WorkflowConfig): Promise<ChecksOutcome>;
+    signal?: AbortSignal;
+}
+/**
+ * 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 declare function checkEligibility(candidate: PreparedCandidate, ctx: EligibilityContext): Promise<Eligibility>;
+/**
+ * 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 declare function verifyItemFor(workflow: WorkflowConfig, adapter: SourceAdapter): ((item: SourceItem) => Promise<boolean>) | undefined;