@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/core/research/tools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent tools for web research: `research.search`, `research.extract`,
+ * `research.deep`, `research.academic`, `research.crawl`.
+ *
+ * `researchToolDefinitions` carries the `ToolDefinition`s the agent loop
+ * advertises; `createResearchToolExecutor` implements agent-core's
+ * `ToolExecutor` and dispatches calls to the orchestrator. Tool outputs are
+ * compact JSON (snippets only) to keep turn context small; full text comes
+ * from `research.extract` / `research.deep`.
+ */
+import type { ToolDefinition, ToolExecutor } from '@boombot/core';
+import type { ResearchOrchestrator } from './orchestrator.js';
+export declare const RESEARCH_SEARCH_TOOL = "research.search";
+export declare const RESEARCH_EXTRACT_TOOL = "research.extract";
+export declare const RESEARCH_DEEP_TOOL = "research.deep";
+export declare const RESEARCH_ACADEMIC_TOOL = "research.academic";
+export declare const RESEARCH_CRAWL_TOOL = "research.crawl";
+/** `ToolDefinition`s to advertise to the agent loop. */
+export declare const researchToolDefinitions: readonly ToolDefinition[];
+export interface ResearchToolExecutorDeps {
+    readonly orchestrator: ResearchOrchestrator;
+}
+/**
+ * Dispatch tool calls to the orchestrator. Unknown tool names and invalid
+ * arguments produce error `ToolResult`s — never throws.
+ */
+export declare function createResearchToolExecutor(deps: ResearchToolExecutorDeps): ToolExecutor;

package/dist/node_modules/@boombot/core/research/tools.js

@@ -0,0 +1,251 @@
+/**
+ * Agent tools for web research: `research.search`, `research.extract`,
+ * `research.deep`, `research.academic`, `research.crawl`.
+ *
+ * `researchToolDefinitions` carries the `ToolDefinition`s the agent loop
+ * advertises; `createResearchToolExecutor` implements agent-core's
+ * `ToolExecutor` and dispatches calls to the orchestrator. Tool outputs are
+ * compact JSON (snippets only) to keep turn context small; full text comes
+ * from `research.extract` / `research.deep`.
+ */
+export const RESEARCH_SEARCH_TOOL = 'research.search';
+export const RESEARCH_EXTRACT_TOOL = 'research.extract';
+export const RESEARCH_DEEP_TOOL = 'research.deep';
+export const RESEARCH_ACADEMIC_TOOL = 'research.academic';
+export const RESEARCH_CRAWL_TOOL = 'research.crawl';
+/** `ToolDefinition`s to advertise to the agent loop. */
+export const researchToolDefinitions = [
+    {
+        name: RESEARCH_SEARCH_TOOL,
+        description: 'Search the public WEB for a query (Wikipedia and DuckDuckGo by default; a paid provider first when one is configured). The fan-out is bounded, so slow engines are dropped rather than made to wait. It does NOT search local files or the project directory — use the local file tools for anything on disk. Returns title/url/snippet per hit.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query.' },
+                limit: {
+                    type: 'integer',
+                    description: 'Max results (default 8, hard max 20).',
+                },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: RESEARCH_EXTRACT_TOOL,
+        description: 'Extract a URL to markdown (main content). Free default backend is Jina Reader; Firecrawl when its key is configured. URLs ending in .pdf/.docx are parsed locally (zero-dependency, quota-guarded) instead of going to a third-party reader. Output is truncated to a safe length; pass "offset" (from a previous result\'s nextOffset) to read the next window of a long page.',
+        parameters: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Full URL to extract.' },
+                offset: {
+                    type: 'integer',
+                    description: 'Character offset into the page (default 0). Use nextOffset from the previous result to continue reading.',
+                },
+            },
+            required: ['url'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: RESEARCH_DEEP_TOOL,
+        description: 'Multi-hop deep research: searches the query, follows up on the top results, then extracts the top pages. Returns results, extracted markdown, and a per-provider source list for claim grounding.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Research question or topic.' },
+                maxHops: {
+                    type: 'integer',
+                    description: 'Search hops 1–3 (default 2).',
+                },
+                maxExtracts: {
+                    type: 'integer',
+                    description: 'URLs to extract 0–5 (default 3).',
+                },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: RESEARCH_ACADEMIC_TOOL,
+        description: 'Search scholarly sources only (arXiv, OpenAlex, Semantic Scholar) for papers and academic metadata. Free, no key needed.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Academic search query.' },
+                limit: {
+                    type: 'integer',
+                    description: 'Max results (default 8, hard max 20).',
+                },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: RESEARCH_CRAWL_TOOL,
+        description: 'Crawl multiple pages of ONE site: extracts the start URL, follows same-site links from the page markdown (depth ≤ 2, hard max 10 pages) and returns compact per-page markdown. Use for site surveys; use research.extract for a single full page.',
+        parameters: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Start URL of the crawl (http/https).' },
+                maxPages: {
+                    type: 'integer',
+                    description: 'Max pages including the start URL (default 5, hard max 10).',
+                },
+                depth: {
+                    type: 'integer',
+                    description: 'Link-follow depth: 1 = start page only, 2 = follow its same-site links once (default 2, hard max 2).',
+                },
+            },
+            required: ['url'],
+            additionalProperties: false,
+        },
+    },
+];
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function errorResult(call, message) {
+    return { callId: call.id, name: call.name, output: message, error: true };
+}
+function okResult(call, output) {
+    return {
+        callId: call.id,
+        name: call.name,
+        output: JSON.stringify(output),
+        error: false,
+    };
+}
+// Per-executor cache: never reuse another configuration or account's results.
+const SEARCH_CACHE_TTL_MS = 60_000;
+const SEARCH_CACHE_MAX_ENTRIES = 50;
+/**
+ * Dispatch tool calls to the orchestrator. Unknown tool names and invalid
+ * arguments produce error `ToolResult`s — never throws.
+ */
+export function createResearchToolExecutor(deps) {
+    const { orchestrator } = deps;
+    const searchCache = new Map();
+    function searchCacheKey(query, limit) {
+        return `${query.trim()}\u0000${limit ?? ''}`;
+    }
+    function readSearchCache(key) {
+        const entry = searchCache.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (Date.now() - entry.at > SEARCH_CACHE_TTL_MS) {
+            searchCache.delete(key);
+            return undefined;
+        }
+        // Re-insert so the oldest untouched entry is the one evicted.
+        searchCache.delete(key);
+        searchCache.set(key, entry);
+        return entry.results;
+    }
+    function writeSearchCache(key, results) {
+        if (results.length === 0)
+            return;
+        searchCache.delete(key);
+        searchCache.set(key, { at: Date.now(), results });
+        while (searchCache.size > SEARCH_CACHE_MAX_ENTRIES) {
+            const oldest = searchCache.keys().next();
+            if (oldest.done === true)
+                break;
+            searchCache.delete(oldest.value);
+        }
+    }
+    return {
+        async execute(call, signal) {
+            const args = call.arguments;
+            try {
+                signal?.throwIfAborted();
+                switch (call.name) {
+                    case RESEARCH_SEARCH_TOOL: {
+                        const query = asString(args['query']);
+                        if (query === undefined || query.trim() === '') {
+                            return errorResult(call, 'research.search: "query" must be a non-empty string.');
+                        }
+                        const limit = asNumber(args['limit']);
+                        const cacheKey = searchCacheKey(query, limit);
+                        // A cancelled turn must not be kept alive by a cache hit.
+                        const cached = signal?.aborted === true ? undefined : readSearchCache(cacheKey);
+                        if (cached !== undefined) {
+                            // `cached` is reported, so a model reading the output knows the
+                            // snippets may be up to a minute old.
+                            return okResult(call, { query, results: cached, cached: true });
+                        }
+                        const results = await orchestrator.search(query, { limit, signal });
+                        signal?.throwIfAborted();
+                        writeSearchCache(cacheKey, results);
+                        return okResult(call, { query, results });
+                    }
+                    case RESEARCH_EXTRACT_TOOL: {
+                        const url = asString(args['url']);
+                        if (url === undefined || url.trim() === '') {
+                            return errorResult(call, 'research.extract: "url" must be a non-empty string.');
+                        }
+                        const offset = asNumber(args['offset']);
+                        if (offset !== undefined && (offset < 0 || !Number.isInteger(offset))) {
+                            return errorResult(call, 'research.extract: "offset" must be a non-negative integer.');
+                        }
+                        const result = await orchestrator.extract(url, signal, offset !== undefined ? { offset } : undefined);
+                        // An offset past the end of the document yields an empty window
+                        // — report it as a readable error instead of empty content.
+                        if (offset !== undefined &&
+                            result.markdown === '' &&
+                            typeof result.totalLength === 'number') {
+                            return errorResult(call, `research.extract: offset ${offset} is beyond the end of the document (${result.totalLength} chars). Use a smaller offset.`);
+                        }
+                        return okResult(call, result);
+                    }
+                    case RESEARCH_DEEP_TOOL: {
+                        const query = asString(args['query']);
+                        if (query === undefined || query.trim() === '') {
+                            return errorResult(call, 'research.deep: "query" must be a non-empty string.');
+                        }
+                        const result = await orchestrator.deep(query, {
+                            maxHops: asNumber(args['maxHops']),
+                            maxExtracts: asNumber(args['maxExtracts']),
+                            signal,
+                        });
+                        return okResult(call, result);
+                    }
+                    case RESEARCH_ACADEMIC_TOOL: {
+                        const query = asString(args['query']);
+                        if (query === undefined || query.trim() === '') {
+                            return errorResult(call, 'research.academic: "query" must be a non-empty string.');
+                        }
+                        const results = await orchestrator.academic(query, {
+                            limit: asNumber(args['limit']),
+                            signal,
+                        });
+                        return okResult(call, { query, results });
+                    }
+                    case RESEARCH_CRAWL_TOOL: {
+                        const url = asString(args['url']);
+                        if (url === undefined || url.trim() === '') {
+                            return errorResult(call, 'research.crawl: "url" must be a non-empty string.');
+                        }
+                        const result = await orchestrator.crawl(url, {
+                            maxPages: asNumber(args['maxPages']),
+                            depth: asNumber(args['depth']),
+                            signal,
+                        });
+                        return okResult(call, result);
+                    }
+                    default:
+                        return errorResult(call, `Unknown research tool: ${call.name}`);
+                }
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                return errorResult(call, `research tool failed: ${detail}`);
+            }
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Public contracts for `@boombot/core`.
+ *
+ * These interfaces are the shared language between this package's skeleton
+ * (config/registry, HTTP helpers) and the provider/orchestrator executors.
+ * Additive-first: fields may be added, never renamed or removed.
+ */
+/** One search hit returned by a {@link ResearchProvider}. */
+export interface SearchResult {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet: string;
+    /** Provider id, e.g. `'wikipedia'`. */
+    readonly source: string;
+    /** ISO 8601 string, when the provider supplies one. */
+    readonly publishedAt?: string;
+}
+/** Full-page extraction returned by an {@link ExtractProvider}. */
+export interface ExtractResult {
+    readonly url: string;
+    readonly title: string;
+    readonly markdown: string;
+    readonly truncated: boolean;
+    /**
+     * Offset this result was served from (0 when the provider ignores
+     * windowing). Additive: older providers may omit it.
+     */
+    readonly offset?: number;
+    /**
+     * Character length of the full extracted document, before windowing.
+     * Present when the provider knows it — lets callers validate `offset`.
+     */
+    readonly totalLength?: number;
+    /**
+     * When more content remains after this window: the offset to pass back
+     * as {@link ExtractOpts.offset} to read the next window. Absent at the
+     * end of the document.
+     */
+    readonly nextOffset?: number;
+}
+/**
+ * Options accepted by {@link ExtractProvider.extract} (third parameter).
+ * Additive-first: providers that ignore `opts` stay valid implementations.
+ */
+export interface ExtractOpts {
+    /**
+     * Character offset into the extracted markdown. The provider fetches the
+     * page again and serves the window `[offset, offset + maxChars)`.
+     * Default 0 (first window). Out-of-range offsets produce an empty
+     * `markdown` with `totalLength` set so callers can report a precise error.
+     */
+    readonly offset?: number;
+}
+/** Options accepted by {@link ResearchProvider.search}. */
+export interface SearchOpts {
+    /** Max results. Default 8, hard max 20 — providers MUST clamp. */
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * A search backend. Free providers are hand-rolled HTTP clients (global
+ * `fetch` only, zero runtime deps); paid providers wrap their APIs.
+ */
+export interface ResearchProvider {
+    /** `'wikipedia' | 'tavily' | ...` — unique across search + extract providers. */
+    readonly id: string;
+    readonly kind: 'free' | 'paid';
+    search(query: string, opts?: SearchOpts): Promise<readonly SearchResult[]>;
+}
+/** A URL → markdown extraction backend (jina-reader, firecrawl, ...). */
+export interface ExtractProvider {
+    readonly id: string;
+    readonly kind: 'free' | 'paid';
+    /**
+     * `opts` is additive: implementations with the old two-parameter shape
+     * remain valid and simply always serve the first window.
+     */
+    extract(url: string, signal?: AbortSignal, opts?: ExtractOpts): Promise<ExtractResult>;
+}
+/**
+ * Runtime configuration. Keys come from env (see `loadResearchConfig`).
+ * Keys are held in memory only — never logged, never serialized.
+ */
+export interface ResearchConfig {
+    readonly tavilyApiKey?: string;
+    readonly exaApiKey?: string;
+    readonly braveApiKey?: string;
+    readonly firecrawlApiKey?: string;
+    readonly defaultMode?: 'auto';
+    /**
+     * Free engines the general fan-out may call, by id (e.g.
+     * `['wikipedia', 'duckduckgo']`). Absent = `DEFAULT_SEARCH_ENGINES`; an
+     * explicit `[]` disables free engines entirely and leaves only the paid
+     * providers that have a key. The scholarly engines are not in the default
+     * set on purpose — they are reachable only through the explicit
+     * `research.academic` tool, so an ordinary search never pays for them.
+     */
+    readonly engines?: readonly string[];
+}
+/** One crawled page in a {@link CrawlResult}. */
+export interface CrawlPage {
+    readonly url: string;
+    readonly title: string;
+    /** Page markdown, truncated to the crawl window (smaller than extract). */
+    readonly markdown: string;
+    readonly truncated: boolean;
+    /** BFS depth: 0 for the start URL. */
+    readonly depth: number;
+}
+/** Options accepted by the crawl engine / `research.crawl`. */
+export interface CrawlOpts {
+    /** Max pages including the start URL. Default 5, hard max 10. */
+    readonly maxPages?: number;
+    /**
+     * Link-follow depth. 1 = start URL only, no link following.
+     * Default 2, hard max 2.
+     */
+    readonly depth?: number;
+    /** Per-page markdown window in characters. Default 2000. */
+    readonly perPageChars?: number;
+    readonly signal?: AbortSignal;
+}
+/** Result of a crawl run. Pages are in BFS completion order. */
+export interface CrawlResult {
+    readonly startUrl: string;
+    readonly pages: readonly CrawlPage[];
+    /** Deepest BFS level that yielded at least one page. */
+    readonly depthReached: number;
+    /** Same-host candidate URLs that failed to extract, capped at 10. */
+    readonly failedUrls: readonly string[];
+    /** True when the run stopped early because `signal` was aborted. */
+    readonly aborted: boolean;
+}

package/dist/node_modules/@boombot/core/research/types.js

@@ -0,0 +1,8 @@
+/**
+ * Public contracts for `@boombot/core`.
+ *
+ * These interfaces are the shared language between this package's skeleton
+ * (config/registry, HTTP helpers) and the provider/orchestrator executors.
+ * Additive-first: fields may be added, never renamed or removed.
+ */
+export {};

package/dist/node_modules/@boombot/core/research/wiring.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One-call gateway wiring for research tools.
+ *
+ * `registerResearchTools` builds the provider instances from config,
+ * resolves the search chain + extract backend, creates the orchestrator,
+ * and registers `research.search` / `research.extract` / `research.deep` /
+ * `research.academic` on any `registerTool`-shaped registry (e.g.
+ * `GatewayToolExecutor`). The gateway calls this once per turn's deps in
+ * `startTurnService`.
+ */
+import type { ToolCall, ToolDefinition, ToolResult } from '@boombot/core';
+import type { ResearchConfig } from './types.js';
+/**
+ * Structural subset of `GatewayToolExecutor` needed for registration —
+ * structural so this package never imports from `gateway`.
+ */
+export interface ResearchToolRegistry {
+    registerTool(definition: ToolDefinition, handler: (call: ToolCall, signal?: AbortSignal) => Promise<ToolResult> | ToolResult): void;
+}
+/**
+ * Build the full research stack from `config` (defaults to env via
+ * `loadResearchConfig`) and register all four tools on `registry`.
+ * Throws when a tool name is already registered (registry's own guard).
+ */
+export declare function registerResearchTools(registry: ResearchToolRegistry, config?: ResearchConfig): void;

package/dist/node_modules/@boombot/core/research/wiring.js

@@ -0,0 +1,51 @@
+/**
+ * One-call gateway wiring for research tools.
+ *
+ * `registerResearchTools` builds the provider instances from config,
+ * resolves the search chain + extract backend, creates the orchestrator,
+ * and registers `research.search` / `research.extract` / `research.deep` /
+ * `research.academic` on any `registerTool`-shaped registry (e.g.
+ * `GatewayToolExecutor`). The gateway calls this once per turn's deps in
+ * `startTurnService`.
+ */
+import { createHash } from 'node:crypto';
+import { loadResearchConfig, resolveAcademicProviders, resolveExtractProvider, resolveSearchProviders, } from './config.js';
+import { createExtractProviders, createSearchProviders } from './factory.js';
+import { ResearchOrchestrator } from './orchestrator.js';
+import { createResearchToolExecutor, researchToolDefinitions } from './tools.js';
+// Reuse the bounded search cache across turns, never across provider configurations.
+const executors = new Map();
+/**
+ * Build the full research stack from `config` (defaults to env via
+ * `loadResearchConfig`) and register all four tools on `registry`.
+ * Throws when a tool name is already registered (registry's own guard).
+ */
+export function registerResearchTools(registry, config = loadResearchConfig()) {
+    const key = createHash('sha256').update(JSON.stringify(config)).digest('hex');
+    let executor = executors.get(key);
+    if (executor === undefined) {
+        const { paid, free } = createSearchProviders(config);
+        const searchChain = resolveSearchProviders(config, { paid, free });
+        // `research.academic` searches the full free pool, not the resolved chain:
+        // the scholarly engines are left out of the default fan-out for latency
+        // (`DEFAULT_SEARCH_ENGINES`), and a caller asking for them by name must
+        // still get them.
+        const academicChain = resolveAcademicProviders({ free });
+        const extractCandidates = createExtractProviders(config);
+        const extractProvider = resolveExtractProvider(config, extractCandidates);
+        const orchestrator = new ResearchOrchestrator({
+            searchChain,
+            academicChain,
+            extractProvider,
+        });
+        executor = createResearchToolExecutor({ orchestrator });
+        const oldest = executors.keys().next();
+        if (executors.size >= 8 && !oldest.done)
+            executors.delete(oldest.value);
+        executors.set(key, executor);
+    }
+    const resolvedExecutor = executor;
+    for (const definition of researchToolDefinitions) {
+        registry.registerTool(definition, (call, signal) => resolvedExecutor.execute(call, signal));
+    }
+}

package/dist/node_modules/@boombot/core/scheduler/cron.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hand-written 5-field cron parser. No regex is applied to user input beyond
+ * one anchored charset check (linear-time, no nested quantifiers), so
+ * evaluation is ReDoS-safe by construction.
+ *
+ * Supported per field: `*`, `*\/step`, `a-b`, `a-b/step`, `n`, and
+ * comma-separated lists thereof.
+ */
+import type { WallParts } from './timezone.js';
+export declare const MAX_CRON_LENGTH = 120;
+export interface CronSchedule {
+    readonly minute: ReadonlySet<number>;
+    readonly hour: ReadonlySet<number>;
+    readonly dayOfMonth: ReadonlySet<number>;
+    readonly month: ReadonlySet<number>;
+    readonly dayOfWeek: ReadonlySet<number>;
+    /** True when the original field was a bare `*` (Vixie DOM/DOW semantics). */
+    readonly dayOfMonthIsStar: boolean;
+    readonly dayOfWeekIsStar: boolean;
+}
+/**
+ * Parse a 5-field cron expression. Throws `SchedulerError`
+ * (`SCHEDULER_INVALID_SPEC`) on any invalid input.
+ */
+export declare function parseCron(expr: string): CronSchedule;
+/** Non-throwing validation wrapper for API boundaries. */
+export declare function validateCronExpression(expr: string): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** True when the wall-clock parts satisfy the schedule. */
+export declare function matchesCron(schedule: CronSchedule, parts: WallParts): boolean;

package/dist/node_modules/@boombot/core/scheduler/cron.js

@@ -0,0 +1,147 @@
+import { invalidSpec } from './types.js';
+export const MAX_CRON_LENGTH = 120;
+/** Anchored charset pre-check: linear, no backtracking risk. */
+const CHARSET_CHECK = /^[0-9*,/\-\s]+$/;
+const FIELDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day of month', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12 },
+    { name: 'day of week', min: 0, max: 7 },
+];
+function fail(reason) {
+    throw invalidSpec(`Invalid cron expression: ${reason}`);
+}
+function parseRangeItem(item, def, values) {
+    // Split off an optional "/step" using a manual scan (no regex).
+    let base = item;
+    let step;
+    const slash = item.indexOf('/');
+    if (slash >= 0) {
+        base = item.slice(0, slash);
+        const stepText = item.slice(slash + 1);
+        if (stepText.length === 0 || !/^[0-9]+$/.test(stepText)) {
+            fail(`bad step in ${def.name} field: "${item}"`);
+        }
+        step = Number(stepText);
+        if (!Number.isSafeInteger(step) || step < 1 || step > def.max) {
+            fail(`step out of range in ${def.name} field: "${item}"`);
+        }
+    }
+    let lo;
+    let hi;
+    if (base === '*') {
+        lo = def.min;
+        hi = def.max;
+    }
+    else {
+        const dash = base.indexOf('-');
+        if (dash >= 0) {
+            const loText = base.slice(0, dash);
+            const hiText = base.slice(dash + 1);
+            if (!/^[0-9]+$/.test(loText) || !/^[0-9]+$/.test(hiText)) {
+                fail(`bad range in ${def.name} field: "${item}"`);
+            }
+            lo = Number(loText);
+            hi = Number(hiText);
+            if (lo > hi)
+                fail(`reversed range in ${def.name} field: "${item}"`);
+        }
+        else {
+            if (!/^[0-9]+$/.test(base))
+                fail(`bad value in ${def.name} field: "${item}"`);
+            lo = Number(base);
+            hi = lo;
+        }
+    }
+    if (lo < def.min || hi > def.max) {
+        fail(`${def.name} value out of range (${def.min}-${def.max}): "${item}"`);
+    }
+    const stepBy = step ?? 1;
+    for (let v = lo; v <= hi; v += stepBy)
+        values.add(v);
+}
+function parseField(fieldText, def, isStar) {
+    const values = new Set();
+    isStar.value = fieldText === '*';
+    const items = fieldText.split(',');
+    for (const item of items) {
+        if (item.length === 0)
+            fail(`empty list item in ${def.name} field`);
+        parseRangeItem(item, def, values);
+    }
+    if (values.size === 0)
+        fail(`empty ${def.name} field`);
+    return values;
+}
+/**
+ * Parse a 5-field cron expression. Throws `SchedulerError`
+ * (`SCHEDULER_INVALID_SPEC`) on any invalid input.
+ */
+export function parseCron(expr) {
+    if (typeof expr !== 'string')
+        fail('expression must be a string');
+    if (expr.length === 0)
+        fail('expression is empty');
+    if (expr.length > MAX_CRON_LENGTH) {
+        fail(`expression exceeds ${MAX_CRON_LENGTH} characters`);
+    }
+    if (!CHARSET_CHECK.test(expr)) {
+        fail('expression contains unsupported characters');
+    }
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        fail(`expected 5 fields, found ${fields.length}`);
+    }
+    const domStar = { value: false };
+    const dowStar = { value: false };
+    const minute = parseField(fields[0], FIELDS[0], { value: false });
+    const hour = parseField(fields[1], FIELDS[1], { value: false });
+    const dayOfMonth = parseField(fields[2], FIELDS[2], domStar);
+    const month = parseField(fields[3], FIELDS[3], { value: false });
+    const rawDow = parseField(fields[4], FIELDS[4], dowStar);
+    // Normalize Sunday 7 -> 0.
+    const dayOfWeek = new Set();
+    for (const d of rawDow)
+        dayOfWeek.add(d === 7 ? 0 : d);
+    return {
+        minute,
+        hour,
+        dayOfMonth,
+        month,
+        dayOfWeek,
+        dayOfMonthIsStar: domStar.value,
+        dayOfWeekIsStar: dowStar.value,
+    };
+}
+/** Non-throwing validation wrapper for API boundaries. */
+export function validateCronExpression(expr) {
+    try {
+        parseCron(expr);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : 'unknown validation failure',
+        };
+    }
+}
+function dayMatches(schedule, parts) {
+    const dom = schedule.dayOfMonth.has(parts.day);
+    const dowMatch = schedule.dayOfWeek.has(parts.weekday);
+    if (schedule.dayOfMonthIsStar && schedule.dayOfWeekIsStar)
+        return true;
+    if (schedule.dayOfMonthIsStar)
+        return dowMatch;
+    if (schedule.dayOfWeekIsStar)
+        return dom;
+    return dom || dowMatch;
+}
+/** True when the wall-clock parts satisfy the schedule. */
+export function matchesCron(schedule, parts) {
+    return (schedule.minute.has(parts.minute) &&
+        schedule.hour.has(parts.hour) &&
+        schedule.month.has(parts.month) &&
+        dayMatches(schedule, parts));
+}