adispatchd 0.0.0-stage → 0.1.0

package/dist/filters/predicate.js

@@ -0,0 +1,178 @@
+import { parseIsoDate } from './iso-date.js';
+const TRUE = { value: true };
+const FALSE = { value: false };
+function unknown(reason) {
+    return { value: 'unknown', reason };
+}
+function isScalar(v) {
+    return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+/** Strict ISO-8601 (no offset = UTC); anything else is not a date. */
+const parseDate = parseIsoDate;
+/**
+ * Equality of two scalars. Dates (field type `date`) compare as instants.
+ * Returns `unknown` for different JS types.
+ */
+function scalarEquals(actual, expected, fieldType) {
+    if (fieldType === 'date') {
+        const a = parseDate(actual);
+        const b = parseDate(expected);
+        if (a === undefined || b === undefined)
+            return unknown('date value is not ISO-8601');
+        return a === b ? TRUE : FALSE;
+    }
+    if (typeof actual !== typeof expected) {
+        return unknown(`incompatible types: ${typeName(actual)} vs ${typeName(expected)}`);
+    }
+    if (typeof actual === 'number' && (Number.isNaN(actual) || Number.isNaN(expected))) {
+        return unknown('NaN is not comparable');
+    }
+    return actual === expected ? TRUE : FALSE;
+}
+function equals(actual, expected, fieldType) {
+    // `null` is a known absent value (e.g. no milestone): it equals only `null`.
+    if (actual === null || expected === null)
+        return actual === expected ? TRUE : FALSE;
+    const actualIsArray = Array.isArray(actual);
+    const expectedIsArray = Array.isArray(expected);
+    if (actualIsArray !== expectedIsArray) {
+        return unknown(`incompatible types: ${typeName(actual)} vs ${typeName(expected)}`);
+    }
+    if (actualIsArray) {
+        // Arrays (e.g. labels) compare as sets: order and duplicates do not matter.
+        const a = actual;
+        const b = expected;
+        if (!a.every(isScalar) || !b.every(isScalar))
+            return unknown('array contains non-scalar values');
+        const sa = new Set(a);
+        const sb = new Set(b);
+        if (sa.size !== sb.size)
+            return FALSE;
+        for (const x of sa)
+            if (!sb.has(x))
+                return FALSE;
+        return TRUE;
+    }
+    return scalarEquals(actual, expected, fieldType);
+}
+function compareOrder(actual, expected, fieldType) {
+    if (actual === null || expected === null)
+        return unknown('null is not comparable');
+    if (fieldType === 'date') {
+        const a = parseDate(actual);
+        const b = parseDate(expected);
+        if (a === undefined || b === undefined)
+            return unknown('date value is not ISO-8601');
+        return { cmp: Math.sign(a - b) };
+    }
+    if (typeof actual === 'number' && typeof expected === 'number') {
+        if (Number.isNaN(actual) || Number.isNaN(expected))
+            return unknown('NaN is not comparable');
+        return { cmp: Math.sign(actual - expected) };
+    }
+    if (typeof actual === 'string' && typeof expected === 'string') {
+        // Plain code-unit order: deterministic, locale-independent (ISO dates sort correctly).
+        return { cmp: actual < expected ? -1 : actual > expected ? 1 : 0 };
+    }
+    return unknown(`not comparable: ${typeName(actual)} vs ${typeName(expected)}`);
+}
+function contains(actual, expected) {
+    if (expected === null || Array.isArray(expected)) {
+        return unknown(`contains expects a scalar operand, got ${typeName(expected)}`);
+    }
+    if (actual === null)
+        return FALSE;
+    if (Array.isArray(actual)) {
+        const arr = actual;
+        if (arr.length === 0)
+            return FALSE;
+        if (!arr.some((x) => typeof x === typeof expected)) {
+            return unknown(`incompatible types: array of ${typeName(arr[0])} vs ${typeName(expected)}`);
+        }
+        return arr.includes(expected) ? TRUE : FALSE;
+    }
+    if (typeof actual === 'string' && typeof expected === 'string') {
+        return actual.includes(expected) ? TRUE : FALSE;
+    }
+    return unknown(`contains not applicable: ${typeName(actual)} vs ${typeName(expected)}`);
+}
+function inList(actual, expected, fieldType) {
+    if (!Array.isArray(expected))
+        return unknown(`in expects an array operand, got ${typeName(expected)}`);
+    const list = expected;
+    if (actual === null)
+        return FALSE;
+    if (Array.isArray(actual)) {
+        // Array field: true if any element is in the list (non-empty intersection).
+        const arr = actual;
+        if (arr.length === 0 || list.length === 0)
+            return FALSE;
+        if (!arr.some((x) => list.some((y) => typeof y === typeof x))) {
+            return unknown('incompatible types between field array and list');
+        }
+        return arr.some((x) => list.includes(x)) ? TRUE : FALSE;
+    }
+    if (list.length === 0)
+        return FALSE;
+    let sawUnknown = false;
+    let sawComparable = false;
+    for (const candidate of list) {
+        const r = scalarEquals(actual, candidate, fieldType);
+        if (r.value === true)
+            return TRUE;
+        if (r.value === 'unknown')
+            sawUnknown = true;
+        else
+            sawComparable = true;
+    }
+    if (sawComparable)
+        return FALSE;
+    return sawUnknown ? unknown(`incompatible types: ${typeName(actual)} vs list`) : FALSE;
+}
+function lower(value) {
+    if (typeof value === 'string')
+        return value.toLowerCase();
+    if (Array.isArray(value))
+        return value.map((v) => (typeof v === 'string' ? v.toLowerCase() : v));
+    return value;
+}
+/**
+ * Apply `operator` to a known field value and the literal `expected`.
+ * `fieldType` (from the adapter's field definition) enables date semantics;
+ * `options.caseInsensitive` folds the case of all string values first.
+ */
+export function applyOperator(operator, actualValue, expectedValue, fieldType, options = {}) {
+    const actual = options.caseInsensitive ? lower(actualValue) : actualValue;
+    const expected = options.caseInsensitive ? lower(expectedValue) : expectedValue;
+    switch (operator) {
+        case 'equals':
+            return equals(actual, expected, fieldType);
+        case 'not_equals': {
+            const r = equals(actual, expected, fieldType);
+            return r.value === 'unknown' ? r : r.value ? FALSE : TRUE;
+        }
+        case 'contains':
+            return contains(actual, expected);
+        case 'in':
+            return inList(actual, expected, fieldType);
+        case 'greater_than':
+        case 'less_than': {
+            if (Array.isArray(actual) || Array.isArray(expected))
+                return unknown('arrays are not comparable');
+            const r = compareOrder(actual, expected, fieldType);
+            if (!('cmp' in r))
+                return r;
+            return (operator === 'greater_than' ? r.cmp > 0 : r.cmp < 0) ? TRUE : FALSE;
+        }
+        default:
+            return unknown(`unsupported operator: ${String(operator)}`);
+    }
+}
+//# sourceMappingURL=predicate.js.map

package/dist/filters/predicate.js.map

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

package/dist/filters/priority.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Item priority (`item_priority.rules`) and deterministic candidate ordering (Spec §7).
+ */
+import type { FilterNode } from '../core/index.js';
+import { type FieldSource, type FilterTrace } from './evaluate.js';
+/** One `item_priority` rule: first rule whose `when` is true wins. */
+export interface ItemPriorityRule {
+    when: FilterNode;
+    value: number;
+}
+/** `item_priority` block of a workflow. */
+export interface ItemPriorityConfig {
+    rules: readonly ItemPriorityRule[];
+    default: number;
+}
+/** Result of {@link resolveItemPriority}. */
+export interface ItemPriorityResult {
+    priority: number;
+    /** Index of the matching rule, or `null` if the default applied. */
+    matchedRule: number | null;
+    /** One trace per rule; rules after the match are `not_evaluated`. */
+    traces: FilterTrace[];
+}
+/**
+ * Determine an item's priority: the first rule evaluating to `true` wins;
+ * `false` and `unknown` do not match; otherwise `default` (0 if no config).
+ */
+export declare function resolveItemPriority(config: ItemPriorityConfig | undefined | null, source: FieldSource): Promise<ItemPriorityResult>;
+/** Minimal shape needed for ordering scheduling candidates. */
+export interface PrioritizedCandidate {
+    workflowId: string;
+    workflowPriority: number;
+    itemPriority: number;
+    /** Item creation time (ISO-8601); missing values sort after present ones. */
+    createdAt?: string | undefined;
+    /** `sourceItemKey(...)`; absent for item-less (cron/manual) candidates. */
+    itemKey?: string | undefined;
+}
+/**
+ * Locale-independent natural compare: digit runs compare numerically
+ * (`repo:9` < `repo:10`), everything else by code unit; final fallback is a
+ * plain code-unit compare so distinct strings never compare equal.
+ */
+export declare function naturalCompare(a: string, b: string): number;
+/**
+ * Total order for candidates (Spec §7): workflow priority desc → item priority
+ * desc → creation time asc (missing/non-ISO last) → item key asc (natural) → workflow ID asc.
+ */
+export declare function compareCandidates(a: PrioritizedCandidate, b: PrioritizedCandidate): number;
+/** Return a new array sorted by {@link compareCandidates}; input order does not matter. */
+export declare function sortCandidates<T extends PrioritizedCandidate>(candidates: readonly T[]): T[];

package/dist/filters/priority.js

@@ -0,0 +1,91 @@
+import { parseIsoDate } from './iso-date.js';
+import { evaluateFilter, notEvaluatedTrace } from './evaluate.js';
+/**
+ * Determine an item's priority: the first rule evaluating to `true` wins;
+ * `false` and `unknown` do not match; otherwise `default` (0 if no config).
+ */
+export async function resolveItemPriority(config, source) {
+    if (!config)
+        return { priority: 0, matchedRule: null, traces: [] };
+    const traces = [];
+    let matched = null;
+    for (const [i, rule] of config.rules.entries()) {
+        if (matched !== null) {
+            traces.push(notEvaluatedTrace(rule.when));
+            continue;
+        }
+        const r = await evaluateFilter(rule.when, source);
+        traces.push(r.trace);
+        if (r.value === true)
+            matched = i;
+    }
+    return {
+        priority: matched === null ? config.default : config.rules[matched].value,
+        matchedRule: matched,
+        traces,
+    };
+}
+function codeUnitCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Locale-independent natural compare: digit runs compare numerically
+ * (`repo:9` < `repo:10`), everything else by code unit; final fallback is a
+ * plain code-unit compare so distinct strings never compare equal.
+ */
+export function naturalCompare(a, b) {
+    const re = /(\d+)|(\D+)/g;
+    const ta = a.match(re) ?? [];
+    const tb = b.match(re) ?? [];
+    for (let i = 0; i < Math.min(ta.length, tb.length); i++) {
+        const x = ta[i];
+        const y = tb[i];
+        const xd = /^\d/.test(x);
+        const yd = /^\d/.test(y);
+        let c;
+        if (xd && yd) {
+            const xs = x.replace(/^0+(?=\d)/, '');
+            const ys = y.replace(/^0+(?=\d)/, '');
+            c = xs.length - ys.length || codeUnitCompare(xs, ys);
+        }
+        else {
+            c = codeUnitCompare(x, y);
+        }
+        if (c !== 0)
+            return Math.sign(c);
+    }
+    return Math.sign(ta.length - tb.length) || codeUnitCompare(a, b);
+}
+/** Strict ISO-8601 (no offset = UTC); missing or invalid values sort last. */
+function createdAtMs(v) {
+    return parseIsoDate(v);
+}
+/**
+ * Total order for candidates (Spec §7): workflow priority desc → item priority
+ * desc → creation time asc (missing/non-ISO last) → item key asc (natural) → workflow ID asc.
+ */
+export function compareCandidates(a, b) {
+    if (a.workflowPriority !== b.workflowPriority)
+        return b.workflowPriority > a.workflowPriority ? 1 : -1;
+    if (a.itemPriority !== b.itemPriority)
+        return b.itemPriority > a.itemPriority ? 1 : -1;
+    const ca = createdAtMs(a.createdAt);
+    const cb = createdAtMs(b.createdAt);
+    if (ca !== cb) {
+        if (ca === undefined)
+            return 1;
+        if (cb === undefined)
+            return -1;
+        return ca < cb ? -1 : 1;
+    }
+    const ka = a.itemKey ?? '';
+    const kb = b.itemKey ?? '';
+    if (ka !== kb)
+        return naturalCompare(ka, kb);
+    return codeUnitCompare(a.workflowId, b.workflowId);
+}
+/** Return a new array sorted by {@link compareCandidates}; input order does not matter. */
+export function sortCandidates(candidates) {
+    return [...candidates].sort(compareCandidates);
+}
+//# sourceMappingURL=priority.js.map

package/dist/filters/priority.js.map

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

package/dist/filters/pushdown.d.ts

@@ -0,0 +1,12 @@
+import { type FieldDefinition, type FilterNode, type FilterPredicate } from '../core/index.js';
+/** Result of {@link splitForPushdown}. `null` = nothing in that part. */
+export interface PushdownSplit {
+    /** Conjunction the adapter may push into its query (pass as `listCandidates({ filter })`). */
+    pushdown: FilterNode | null;
+    /** Remaining conjunction that must be evaluated locally. */
+    local: FilterNode | null;
+}
+/** True if the adapter declares pushdown support for this predicate. */
+export declare function canPushDown(predicate: FilterPredicate, definitions: readonly FieldDefinition[]): boolean;
+/** Split `filter` into a pushable and a local conjunction. */
+export declare function splitForPushdown(filter: FilterNode | undefined | null, definitions: readonly FieldDefinition[]): PushdownSplit;

package/dist/filters/pushdown.js

@@ -0,0 +1,52 @@
+/**
+ * Conservative pushdown split (Spec §6): which part of a filter the adapter may
+ * evaluate in its external query, and which part stays local.
+ *
+ * Only predicates of a top-level conjunction (`all`, nested `all`s are
+ * flattened) are pushed, and only if the field is declared, cheap, and lists
+ * the operator in `FieldDefinition.pushdown`. `any`/`not` are never pushed.
+ * Since `pushdown AND local ≡ filter`, callers may evaluate just `local` on the
+ * adapter's result — but because adapters may ignore pushed parts, the safe
+ * default (and the `SourceAdapter` contract) is to re-evaluate the full filter.
+ */
+import { isValidNode } from './evaluate.js';
+import { isFilterAll, isFilterPredicate } from '../core/index.js';
+function flattenConjunction(node, out) {
+    // Malformed nodes stay local (where they evaluate to unknown).
+    if (isValidNode(node) && isFilterAll(node))
+        for (const c of node.all)
+            flattenConjunction(c, out);
+    else
+        out.push(node);
+}
+function conjunction(parts) {
+    if (parts.length === 0)
+        return null;
+    if (parts.length === 1)
+        return parts[0];
+    return { all: parts };
+}
+/** True if the adapter declares pushdown support for this predicate. */
+export function canPushDown(predicate, definitions) {
+    const def = definitions.find((d) => d.name === predicate.field);
+    if (!def || def.expensive)
+        return false;
+    return (def.pushdown ?? []).includes(predicate.operator) && def.operators.includes(predicate.operator);
+}
+/** Split `filter` into a pushable and a local conjunction. */
+export function splitForPushdown(filter, definitions) {
+    if (!filter)
+        return { pushdown: null, local: null };
+    const parts = [];
+    flattenConjunction(filter, parts);
+    const pushed = [];
+    const local = [];
+    for (const part of parts) {
+        if (isValidNode(part) && isFilterPredicate(part) && canPushDown(part, definitions))
+            pushed.push(part);
+        else
+            local.push(part);
+    }
+    return { pushdown: conjunction(pushed), local: conjunction(local) };
+}
+//# sourceMappingURL=pushdown.js.map

package/dist/filters/pushdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pushdown.js","sourceRoot":"","sources":["../../src/filters/pushdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAA+D,MAAM,kBAAkB,CAAC;AAU/H,SAAS,kBAAkB,CAAC,IAAgB,EAAE,GAAiB;IAC7D,+DAA+D;IAC/D,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC;QAAE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,GAAG;YAAE,kBAAkB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;;QAC5F,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,WAAW,CAAC,KAAmB;IACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAe,CAAC;IACtD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AACxB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,SAA0B,EAAE,WAAuC;IAC7F,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC;IAChE,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AACzG,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAC9B,MAAqC,EACrC,WAAuC;IAEvC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACpD,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YACjG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC"}

package/dist/filters/shell-check.d.ts

@@ -0,0 +1,110 @@
+import { type Clock, type Logger, type SourceItem, type Timers, type TriValue } from '../core/index.js';
+/** Environment variable holding the path of the check context JSON file. */
+export declare const CHECK_CONTEXT_ENV = "ADISPATCH_CHECK_CONTEXT_FILE";
+/** Variables copied from the controller environment into every check process. */
+export declare const MINIMAL_ENV_KEYS: readonly ['PATH', 'HOME', 'LANG', 'TZ', 'USER', 'LOGNAME', 'TMPDIR'];
+/** Default per-stream output limit in bytes. */
+export declare const DEFAULT_MAX_CHECK_OUTPUT_BYTES: number;
+/** Default grace period between SIGTERM and SIGKILL. */
+export declare const DEFAULT_CHECK_KILL_GRACE_MS = 2000;
+/** One configured shell check (shell filter or condition). */
+export interface ShellCheckSpec {
+    /** Executable (or, with `shell: true`, a shell command string). */
+    command: string;
+    args?: readonly string[];
+    /** Run `command` through `/bin/sh -c`. Only if explicitly configured. */
+    shell?: boolean;
+    /** Timeout in milliseconds. */
+    timeoutMs: number;
+    /** Explicit additional environment variables. */
+    env?: Readonly<Record<string, string>>;
+    /** Working directory (default: the runner's temp directory for this check). */
+    cwd?: string;
+}
+/** Kind of check, part of the context file. */
+export type ShellCheckKind = 'shell_filter' | 'workflow_condition' | 'item_condition';
+/** Content of the file at `ADISPATCH_CHECK_CONTEXT_FILE`. Never contains secrets. */
+export interface ShellCheckContext {
+    schema_version: 1;
+    kind: ShellCheckKind;
+    workflow: {
+        id: string;
+    };
+    /** Present for item-bound checks (shell filter, item conditions). */
+    source?: {
+        id: string;
+        type: string;
+        item_id: string;
+        item_key: string;
+        url: string;
+        item_type: string;
+        created_at?: string;
+        /** Cheap item fields (as in `SourceItem.fields`). */
+        attributes: Record<string, unknown>;
+    };
+}
+/** Build a {@link ShellCheckContext}. `sourceType` is the adapter type (e.g. `github`). */
+export declare function buildCheckContext(kind: ShellCheckKind, workflowId: string, item?: SourceItem, sourceType?: string): ShellCheckContext;
+/** Result of one shell check. */
+export interface ShellCheckResult {
+    value: TriValue;
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    /** Error detail when `value` is `unknown`. */
+    error?: string;
+    stdout: string;
+    stderr: string;
+    /** True if stdout or stderr exceeded the limit and was cut. */
+    outputTruncated: boolean;
+    /** ISO-8601 start time (from the injected clock). */
+    startedAt: string;
+    durationMs: number;
+    /** True if served from the cache ({@link ShellCheckRunner.runCached}). */
+    cached: boolean;
+}
+/** Dependencies/options of {@link ShellCheckRunner}. */
+export interface ShellCheckRunnerOptions {
+    clock?: Clock;
+    timers?: Timers;
+    logger?: Logger;
+    /** Source of the minimal environment (default: `process.env`). */
+    hostEnv?: Readonly<Record<string, string | undefined>>;
+    /** Directory for temporary context files (default: OS temp dir). */
+    tempDir?: string;
+    /** Per-stream output limit in bytes. */
+    maxOutputBytes?: number;
+    /** Grace period between SIGTERM and SIGKILL. */
+    killGraceMs?: number;
+}
+/** Runs shell checks; one instance per orchestrator (holds the workflow-condition cache). */
+export declare class ShellCheckRunner {
+    private readonly clock;
+    private readonly timers;
+    private readonly logger;
+    private readonly hostEnv;
+    private readonly tempDir;
+    private readonly maxOutputBytes;
+    private readonly killGraceMs;
+    private readonly cache;
+    private readonly inflight;
+    constructor(options?: ShellCheckRunnerOptions);
+    /** Environment for a check process (minimal env + explicit env + context file). */
+    buildEnv(spec: ShellCheckSpec, contextFile: string): Record<string, string>;
+    /** Run a check without caching. Never throws. */
+    run(spec: ShellCheckSpec, context: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<ShellCheckResult>;
+    /**
+     * Run a check with a TTL cache under `cacheKey` (e.g. `<workflowId>:condition:<index>`).
+     * Only definitive results (`true`/`false`) are cached; concurrent calls for
+     * the same key share one execution. `ttlMs <= 0` disables caching.
+     */
+    runCached(cacheKey: string, ttlMs: number, spec: ShellCheckSpec, context: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<ShellCheckResult>;
+    /** Drop one cache entry, or all (e.g. after a config reload). */
+    invalidate(cacheKey?: string): void;
+    private failure;
+    private spawnCheck;
+}