@pikku/core 0.12.78 → 0.12.80

package/dist/wirings/workflow/workflow-approval.js

@@ -0,0 +1,114 @@
+import { getDurationInMilliseconds } from '../../time-utils.js';
+import { WorkflowApprovalResolvedError, WorkflowSuspendedException, } from './workflow-errors.js';
+/** The durable step name an approval point is recorded under. */
+export const approvalStepNameFor = (reason) => `__workflow_approval:${reason}`;
+/**
+ * The run-state key holding an approval's decision.
+ *
+ * Hex-encoded because the key is composed from a caller-supplied reason, and
+ * run state is a flat record — an unescaped reason could collide with, or
+ * shadow, another key.
+ */
+export const approvalStateKey = (stepName) => {
+    let hex = '';
+    for (const byte of new TextEncoder().encode(stepName)) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return `__approval_${hex}`;
+};
+/**
+ * Record a decision against an approval point and wake the run.
+ *
+ * A decision arriving for an already-settled approval is refused rather than
+ * overwriting it: the run has moved on, and a second answer would be recorded
+ * against a gate nobody is waiting at.
+ */
+export const recordApprovalDecision = async (store, runId, reason, decision) => {
+    const stepName = approvalStepNameFor(reason);
+    const stateKey = approvalStateKey(stepName);
+    let resolved;
+    try {
+        resolved = await store.getStepState(runId, stepName);
+    }
+    catch {
+        // knowledge: decisions/security/workflow-approval-payloads-are-validated-on-replay-inside-the-workflow.md
+    }
+    if (resolved?.stepId && resolved.status === 'succeeded') {
+        const outcome = resolved.result;
+        throw new WorkflowApprovalResolvedError(reason, outcome?.status ?? 'decided');
+    }
+    const state = await store.getRunState(runId);
+    const record = (state[stateKey] ?? {});
+    await store.updateRunState(runId, stateKey, {
+        ...record,
+        decision,
+        decidedAt: new Date().toISOString(),
+        error: undefined,
+    });
+    await store.resumeWorkflow(runId);
+};
+/**
+ * Evaluate an approval gate on replay.
+ *
+ * The payload is validated here rather than where it was submitted, because the
+ * schema is a value on the workflow and only the workflow has it. A payload
+ * that fails validation is cleared and the run suspends again, so a bad
+ * submission cannot settle the gate.
+ */
+export const evaluateApprovalStep = async (store, runId, reason, approvalStepName, fromStepName, options) => {
+    const insert = () => store.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', { reason, expiry: options.expiry }, undefined, fromStepName);
+    let stepState;
+    try {
+        stepState = await store.getStepState(runId, approvalStepName);
+    }
+    catch {
+        stepState = await insert();
+    }
+    if (!stepState.stepId) {
+        stepState = await insert();
+    }
+    if (stepState.status === 'succeeded') {
+        return stepState.result;
+    }
+    const stateKey = approvalStateKey(approvalStepName);
+    let record = ((await store.getRunState(runId))[stateKey] ?? {});
+    if (stepState.status === 'pending') {
+        await store.setStepRunning(stepState.stepId);
+        if (options.expiry !== undefined && !record.expiresAt) {
+            const expiry = getDurationInMilliseconds(options.expiry);
+            record = {
+                ...record,
+                expiresAt: new Date(Date.now() + expiry).toISOString(),
+            };
+            await store.updateRunState(runId, stateKey, record);
+            await store.scheduleRunWake(runId, expiry);
+        }
+    }
+    if (record.decision !== undefined) {
+        const validation = await options.schema['~standard'].validate(record.decision);
+        if (validation.issues) {
+            await store.updateRunState(runId, stateKey, {
+                ...record,
+                decision: undefined,
+                decidedAt: undefined,
+                error: validation.issues.map((issue) => ({
+                    message: issue.message,
+                    path: issue.path?.map((segment) => typeof segment === 'object' ? segment.key : segment),
+                })),
+            });
+            throw new WorkflowSuspendedException(runId, reason);
+        }
+        const outcome = {
+            status: 'decided',
+            data: validation.value,
+        };
+        await store.setStepResult(stepState.stepId, outcome);
+        return outcome;
+    }
+    if (record.expiresAt && Date.now() >= Date.parse(record.expiresAt)) {
+        const outcome = { status: 'expired' };
+        await store.setStepResult(stepState.stepId, outcome);
+        return outcome;
+    }
+    throw new WorkflowSuspendedException(runId, reason);
+};

package/dist/wirings/workflow/workflow-constants.d.ts

@@ -0,0 +1,26 @@
+export declare const DEFAULT_STEP_RETRIES = 5;
+/** Statuses from which a run never advances again on its own. */
+export declare const WORKFLOW_END_STATES: ReadonlySet<string>;
+/** Statuses a run cannot leave at all. */
+export declare const WORKFLOW_TERMINAL_STATES: ReadonlySet<string>;
+export declare const WORKFLOW_POLL_MIN_MS = 10;
+export declare const WORKFLOW_POLL_FACTOR = 1.6;
+export declare const WORKFLOW_CHILD_POLL_MAX_MS = 500;
+/** Idle window before a `running` run with nothing in flight is treated as stalled. */
+export declare const DEFAULT_STALLED_RUN_MS: number;
+/** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
+export declare const DEFAULT_STALLED_RUN_LIMIT = 100;
+/**
+ * How long a step may sit `pending` before the relay assumes its dispatch was
+ * lost. This is a bet that no healthy queue takes this long to move a job from
+ * `pending` to `running`; set it above the observed p99 of that latency.
+ */
+export declare const DEFAULT_UNDISPATCHED_STEP_MS = 30000;
+/** Steps re-driven per `relayUndispatchedSteps` call, so one tick is bounded. */
+export declare const DEFAULT_UNDISPATCHED_STEP_LIMIT = 100;
+/** First wait before a step already re-dispatched once is re-dispatched again. */
+export declare const REDISPATCH_BACKOFF_MS = 30000;
+/** Ceiling on the doubling backoff, so a permanently stuck step still gets swept. */
+export declare const REDISPATCH_BACKOFF_MAX_MS: number;
+/** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
+export declare const REDISPATCH_BACKOFF_MAX_ENTRIES = 10000;

package/dist/wirings/workflow/workflow-constants.js

@@ -0,0 +1,35 @@
+export const DEFAULT_STEP_RETRIES = 5;
+/** Statuses from which a run never advances again on its own. */
+export const WORKFLOW_END_STATES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+    'suspended',
+]);
+/** Statuses a run cannot leave at all. */
+export const WORKFLOW_TERMINAL_STATES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+]);
+export const WORKFLOW_POLL_MIN_MS = 10;
+export const WORKFLOW_POLL_FACTOR = 1.6;
+export const WORKFLOW_CHILD_POLL_MAX_MS = 500;
+/** Idle window before a `running` run with nothing in flight is treated as stalled. */
+export const DEFAULT_STALLED_RUN_MS = 5 * 60_000;
+/** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
+export const DEFAULT_STALLED_RUN_LIMIT = 100;
+/**
+ * How long a step may sit `pending` before the relay assumes its dispatch was
+ * lost. This is a bet that no healthy queue takes this long to move a job from
+ * `pending` to `running`; set it above the observed p99 of that latency.
+ */
+export const DEFAULT_UNDISPATCHED_STEP_MS = 30_000;
+/** Steps re-driven per `relayUndispatchedSteps` call, so one tick is bounded. */
+export const DEFAULT_UNDISPATCHED_STEP_LIMIT = 100;
+/** First wait before a step already re-dispatched once is re-dispatched again. */
+export const REDISPATCH_BACKOFF_MS = 30_000;
+/** Ceiling on the doubling backoff, so a permanently stuck step still gets swept. */
+export const REDISPATCH_BACKOFF_MAX_MS = 10 * 60_000;
+/** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
+export const REDISPATCH_BACKOFF_MAX_ENTRIES = 10_000;

package/dist/wirings/workflow/workflow-errors.d.ts

@@ -0,0 +1,58 @@
+import { PikkuError } from '../../errors/error-handler.js';
+import type { ApprovalOutcome } from './workflow.types.js';
+/**
+ * Thrown to unwind a run that cannot continue on this tick. Not a failure:
+ * the run resumes from its recorded step state.
+ */
+export declare class WorkflowAsyncException extends Error {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string);
+}
+export declare class WorkflowCancelledException extends Error {
+    readonly runId: string;
+    readonly reason?: string | undefined;
+    constructor(runId: string, reason?: string | undefined);
+}
+export declare class WorkflowSuspendedException extends Error {
+    readonly runId: string;
+    readonly reason: string;
+    constructor(runId: string, reason: string);
+}
+export declare class WorkflowDispatchException extends Error {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class WorkflowNotFoundError extends PikkuError {
+    constructor(name: string);
+}
+export declare class WorkflowRunNotFoundError extends PikkuError {
+    constructor(runId: string);
+}
+export declare class WorkflowRunFailedError extends PikkuError {
+    payload: {
+        message?: string;
+    };
+    constructor(message?: string);
+}
+export declare class WorkflowRunCancelledError extends PikkuError {
+    constructor();
+}
+export declare class WorkflowApprovalResolvedError extends PikkuError {
+    payload: {
+        reason: string;
+        outcome: ApprovalOutcome<unknown>['status'];
+    };
+    constructor(reason: string, outcome: ApprovalOutcome<unknown>['status']);
+}
+export declare class WorkflowStepFunctionMismatchError extends PikkuError {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string);
+}
+export declare class WorkflowStepNameNotString extends Error {
+    constructor(stepName: unknown);
+}

package/dist/wirings/workflow/workflow-errors.js

@@ -0,0 +1,112 @@
+import { PikkuError, addError } from '../../errors/error-handler.js';
+/**
+ * Thrown to unwind a run that cannot continue on this tick. Not a failure:
+ * the run resumes from its recorded step state.
+ */
+export class WorkflowAsyncException extends Error {
+    runId;
+    stepName;
+    constructor(runId, stepName) {
+        super(`Workflow paused at step: ${stepName}`);
+        this.runId = runId;
+        this.stepName = stepName;
+        this.name = 'WorkflowAsyncException';
+    }
+}
+export class WorkflowCancelledException extends Error {
+    runId;
+    reason;
+    constructor(runId, reason) {
+        super(reason || 'Workflow cancelled');
+        this.runId = runId;
+        this.reason = reason;
+        this.name = 'WorkflowCancelledException';
+    }
+}
+export class WorkflowSuspendedException extends Error {
+    runId;
+    reason;
+    constructor(runId, reason) {
+        super(reason || 'Workflow suspended');
+        this.runId = runId;
+        this.reason = reason;
+        this.name = 'WorkflowSuspendedException';
+    }
+}
+export class WorkflowDispatchException extends Error {
+    runId;
+    stepName;
+    constructor(runId, stepName, options) {
+        super(`Failed to dispatch workflow step '${stepName}' (run ${runId})`, options);
+        this.runId = runId;
+        this.stepName = stepName;
+        this.name = 'WorkflowDispatchException';
+    }
+}
+export class WorkflowNotFoundError extends PikkuError {
+    constructor(name) {
+        super(`Workflow not found: ${name}`);
+    }
+}
+addError(WorkflowNotFoundError, {
+    status: 404,
+    message: 'Workflow not found.',
+});
+export class WorkflowRunNotFoundError extends PikkuError {
+    constructor(runId) {
+        super(`Workflow run not found: ${runId}`);
+    }
+}
+addError(WorkflowRunNotFoundError, {
+    status: 404,
+    message: 'Workflow run not found.',
+});
+export class WorkflowRunFailedError extends PikkuError {
+    payload;
+    constructor(message) {
+        super(`Workflow run failed: ${message ?? 'unknown'}`);
+        this.payload = { message };
+    }
+}
+addError(WorkflowRunFailedError, {
+    status: 422,
+    message: 'Workflow run failed.',
+});
+export class WorkflowRunCancelledError extends PikkuError {
+    constructor() {
+        super('Workflow was cancelled');
+    }
+}
+addError(WorkflowRunCancelledError, {
+    status: 409,
+    message: 'Workflow was cancelled.',
+});
+export class WorkflowApprovalResolvedError extends PikkuError {
+    payload;
+    constructor(reason, outcome) {
+        super(`Approval already ${outcome}: ${reason}`);
+        this.payload = { reason, outcome };
+    }
+}
+addError(WorkflowApprovalResolvedError, {
+    status: 409,
+    message: 'Approval has already been resolved.',
+});
+export class WorkflowStepFunctionMismatchError extends PikkuError {
+    runId;
+    stepName;
+    constructor(runId, stepName) {
+        super(`Workflow step '${stepName}' (run ${runId}) was dispatched with a different function`);
+        this.runId = runId;
+        this.stepName = stepName;
+    }
+}
+addError(WorkflowStepFunctionMismatchError, {
+    status: 409,
+    message: 'Workflow step was dispatched with a different function.',
+});
+export class WorkflowStepNameNotString extends Error {
+    constructor(stepName) {
+        super(`Workflow step name must be a string. Received: ${typeof stepName}`);
+    }
+}

package/dist/wirings/workflow/workflow-meta-resolver.d.ts

@@ -0,0 +1,11 @@
+import type { WorkflowRuntimeMeta } from './workflow.types.js';
+export type ResolvedWorkflowMeta = {
+    meta: WorkflowRuntimeMeta;
+    packageName: string | null;
+    resolvedName: string;
+};
+/**
+ * Resolves a workflow name against the root registry, then — for a
+ * `namespace:name` form — against the addon package that claims the namespace.
+ */
+export declare const resolveWorkflowMeta: (name: string) => ResolvedWorkflowMeta | null;

package/dist/wirings/workflow/workflow-meta-resolver.js

@@ -0,0 +1,31 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Resolves a workflow name against the root registry, then — for a
+ * `namespace:name` form — against the addon package that claims the namespace.
+ */
+export const resolveWorkflowMeta = (name) => {
+    const rootMeta = pikkuState(null, 'workflows', 'meta');
+    if (rootMeta[name]) {
+        return { meta: rootMeta[name], packageName: null, resolvedName: name };
+    }
+    const colonIndex = name.indexOf(':');
+    if (colonIndex === -1) {
+        return null;
+    }
+    const namespace = name.substring(0, colonIndex);
+    const localName = name.substring(colonIndex + 1);
+    const addons = pikkuState(null, 'addons', 'packages');
+    const pkgConfig = addons?.get(namespace);
+    if (!pkgConfig) {
+        return null;
+    }
+    const addonMeta = pikkuState(pkgConfig.package, 'workflows', 'meta');
+    if (!addonMeta?.[localName]) {
+        return null;
+    }
+    return {
+        meta: addonMeta[localName],
+        packageName: pkgConfig.package,
+        resolvedName: localName,
+    };
+};

package/dist/wirings/workflow/workflow-queue-routing.d.ts

@@ -0,0 +1,8 @@
+import type { JobGroup, JobOptions } from '../queue/queue.types.js';
+import type { WorkflowServiceConfig, WorkflowStepOptions } from './workflow.types.js';
+export type WorkflowQueueStrategy = 'per-workflow' | 'shared-groups';
+export declare const resolveWorkflowConfig: () => WorkflowServiceConfig;
+export declare const orchestratorQueueName: (strategy: WorkflowQueueStrategy, workflowName?: string) => string;
+export declare const stepWorkerQueueName: (strategy: WorkflowQueueStrategy, rpcName?: string) => string;
+export declare const jobGroupFor: (strategy: WorkflowQueueStrategy, id?: string) => JobGroup | undefined;
+export declare const stepJobOptions: (stepOptions?: WorkflowStepOptions) => JobOptions;

package/dist/wirings/workflow/workflow-queue-routing.js

@@ -0,0 +1,38 @@
+import { getSingletonServices, pikkuState } from '../../pikku-state.js';
+import { getDurationInMilliseconds } from '../../time-utils.js';
+import { DEFAULT_STEP_RETRIES } from './workflow-constants.js';
+const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+export const resolveWorkflowConfig = () => {
+    const workflow = getSingletonServices().config?.workflow;
+    return {
+        retries: workflow?.retries ?? DEFAULT_STEP_RETRIES,
+        retryDelay: workflow?.retryDelay ?? 0,
+        orchestratorQueueName: workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
+        stepWorkerQueueName: workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',
+        sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowSleeper',
+    };
+};
+/**
+ * Falls back to the shared queue whenever the dedicated one was not generated
+ * into queue meta, so a workflow added without a rebuild still runs.
+ */
+const dedicatedQueueName = (prefix, name, strategy, fallback) => {
+    if (!name || strategy === 'shared-groups') {
+        return fallback;
+    }
+    const dedicated = `${prefix}${toKebab(name)}`;
+    return pikkuState(null, 'queue', 'meta')[dedicated] ? dedicated : fallback;
+};
+export const orchestratorQueueName = (strategy, workflowName) => dedicatedQueueName('wf-orchestrator-', workflowName, strategy, resolveWorkflowConfig().orchestratorQueueName);
+export const stepWorkerQueueName = (strategy, rpcName) => dedicatedQueueName('wf-step-', rpcName, strategy, resolveWorkflowConfig().stepWorkerQueueName);
+export const jobGroupFor = (strategy, id) => id && strategy === 'shared-groups' ? { id, tier: id } : undefined;
+export const stepJobOptions = (stepOptions) => {
+    const retries = stepOptions?.retries ?? DEFAULT_STEP_RETRIES;
+    const retryDelay = stepOptions?.retryDelay;
+    const backoff = retryDelay !== undefined && retryDelay !== 'exponential'
+        ? { type: 'fixed', delay: getDurationInMilliseconds(retryDelay) }
+        : retries > 0 || retryDelay === 'exponential'
+            ? 'exponential'
+            : undefined;
+    return { attempts: retries + 1, ...(backoff ? { backoff } : {}) };
+};

package/dist/wirings/workflow/workflow-queue-wiring.d.ts

@@ -0,0 +1,20 @@
+import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
+import type { Logger } from '../../services/logger.js';
+import type { WorkflowQueueStrategy } from './workflow-queue-routing.js';
+export type WorkflowQueueWiringOptions = {
+    strategy: WorkflowQueueStrategy;
+    concurrency: number;
+    groupConcurrency: number | GroupConcurrencyConfig;
+    /**
+     * Resolved only when there is something to warn about: reading the logger
+     * throws while singleton services are uninitialized, and wiring queues before
+     * that point is legitimate.
+     */
+    getLogger: () => Logger | undefined;
+};
+/**
+ * Registers the orchestrator, step-worker and sleeper functions and binds them
+ * to their queues. Idempotent: a queue already carrying a registered function
+ * is left alone.
+ */
+export declare const wireWorkflowQueueWorkers: ({ strategy, concurrency, groupConcurrency, getLogger, }: WorkflowQueueWiringOptions) => void;

package/dist/wirings/workflow/workflow-queue-wiring.js

@@ -0,0 +1,79 @@
+import { addFunction } from '../../function/function-runner.js';
+import { pikkuState } from '../../pikku-state.js';
+import { wireQueueWorker } from '../queue/queue-runner.js';
+import { pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, pikkuWorkflowWorkerFunc, } from './workflow-queue-workers.js';
+const ORCHESTRATOR_QUEUE_PREFIX = 'wf-orchestrator-';
+const STEP_QUEUE_PREFIX = 'wf-step-';
+const helperFunctionMeta = (funcId) => ({
+    pikkuFuncId: funcId,
+    sessionless: true,
+    functionType: 'helper',
+    inputSchemaName: null,
+    outputSchemaName: null,
+});
+/**
+ * Registers the orchestrator, step-worker and sleeper functions and binds them
+ * to their queues. Idempotent: a queue already carrying a registered function
+ * is left alone.
+ */
+export const wireWorkflowQueueWorkers = ({ strategy, concurrency, groupConcurrency, getLogger, }) => {
+    const functions = pikkuState(null, 'function', 'functions');
+    const functionsMeta = pikkuState(null, 'function', 'meta');
+    const queueMeta = pikkuState(null, 'queue', 'meta');
+    const registerWorkflowFunc = (funcId, func, queueName, config) => {
+        if (functions.has(funcId))
+            return;
+        addFunction(funcId, func);
+        if (!queueMeta[queueName]) {
+            queueMeta[queueName] = { pikkuFuncId: funcId, name: queueName };
+        }
+        wireQueueWorker({ name: queueName, func, config });
+        if (!functionsMeta[funcId]) {
+            functionsMeta[funcId] = helperFunctionMeta(funcId);
+        }
+    };
+    const sharedGroups = strategy === 'shared-groups';
+    const sharedQueueConfig = sharedGroups
+        ? { batchSize: concurrency, groupConcurrency }
+        : undefined;
+    registerWorkflowFunc('pikkuWorkflowOrchestrator', { func: pikkuWorkflowOrchestratorFunc }, 'pikku-workflow-orchestrator', sharedQueueConfig);
+    registerWorkflowFunc('pikkuWorkflowStepWorker', { func: pikkuWorkflowWorkerFunc }, 'pikku-workflow-step-worker', sharedQueueConfig);
+    const registerDedicatedQueues = (meta) => {
+        for (const [queueName, entry] of Object.entries(meta)) {
+            if (functions.has(entry.pikkuFuncId))
+                continue;
+            if (queueName.startsWith(ORCHESTRATOR_QUEUE_PREFIX)) {
+                registerWorkflowFunc(entry.pikkuFuncId, { func: pikkuWorkflowOrchestratorFunc }, queueName);
+            }
+            else if (queueName.startsWith(STEP_QUEUE_PREFIX)) {
+                registerWorkflowFunc(entry.pikkuFuncId, { func: pikkuWorkflowWorkerFunc }, queueName);
+            }
+        }
+    };
+    if (!sharedGroups) {
+        registerDedicatedQueues(pikkuState(null, 'queue', 'meta'));
+        const addons = pikkuState(null, 'addons', 'packages');
+        for (const [, addon] of addons ?? []) {
+            const addonQueueMeta = pikkuState(addon.package, 'queue', 'meta');
+            if (addonQueueMeta) {
+                registerDedicatedQueues(addonQueueMeta);
+            }
+        }
+    }
+    warnOnMissingDedicatedQueues(queueMeta, getLogger);
+    if (!functions.has('pikkuWorkflowSleeper')) {
+        addFunction('pikkuWorkflowSleeper', { func: pikkuWorkflowSleeperFunc });
+    }
+    if (!functionsMeta.pikkuWorkflowSleeper) {
+        functionsMeta.pikkuWorkflowSleeper = helperFunctionMeta('pikkuWorkflowSleeper');
+    }
+};
+const warnOnMissingDedicatedQueues = (queueMeta, getLogger) => {
+    const workflowCount = Object.keys(pikkuState(null, 'workflows', 'meta') ?? {}).length;
+    const dedicatedQueues = Object.keys(queueMeta).filter((name) => name.startsWith(ORCHESTRATOR_QUEUE_PREFIX)).length;
+    if (workflowCount > 0 && dedicatedQueues === 0) {
+        getLogger()?.warn?.(`[pikku] ${workflowCount} workflow(s) registered but no per-workflow orchestrator queues were found in queue meta. ` +
+            `All workflows will share a single orchestrator queue, where one slow step blocks every other workflow behind it. ` +
+            `Check that the generated bootstrap imports the queue-workers meta (pikku-queue-workers-wirings-meta.gen.js).`);
+    }
+};

package/dist/wirings/workflow/workflow-recovery.d.ts

@@ -0,0 +1,68 @@
+import type { Logger } from '../../services/logger.js';
+/**
+ * Per-process, advisory record of when a run may next be re-dispatched.
+ *
+ * Keyed by run rather than by step because the run is the unit of re-drive:
+ * `resumeWorkflow` replays the whole run and re-dispatches every step still
+ * owed a job, so holding off a single step while resuming its run would
+ * suppress nothing.
+ *
+ * Losing this on restart costs extra dispatches, never correctness.
+ */
+export declare class RedispatchBackoff {
+    private readonly eligibleAt;
+    private readonly delays;
+    isEligible(runId: string, now: number): boolean;
+    note(runId: string, now: number): void;
+}
+type SweepDeps = {
+    resume: (runId: string) => Promise<void>;
+    logger?: Logger;
+};
+/**
+ * Re-drive runs whose next move was lost, and report which were resumed.
+ *
+ * Arming a step is two writes to two systems — the step row, then the queue or
+ * scheduler job — so a process that dies between them leaves a run that is
+ * `running` with nothing in flight. Nothing notices: the run parks on a step
+ * that will never complete and never error, so it neither finishes nor fails.
+ * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
+ * step's insert and its timer, parking the run permanently.)
+ *
+ * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted step
+ * state, and every settled step is memoized, so resuming a run that was not
+ * actually stuck costs an orchestration pass and changes nothing. That
+ * idempotence is what makes an idle-time heuristic safe here; a run that is
+ * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+ */
+export declare const sweepStalledRuns: (findStalledRunIds: (before: Date, limit: number) => Promise<string[]>, options: {
+    stalledAfterMs?: number;
+    limit?: number;
+} | undefined, deps: SweepDeps) => Promise<{
+    resumed: string[];
+}>;
+/**
+ * Re-drive steps whose dispatch was lost, and report which runs were nudged.
+ *
+ * The step row is the outbox record and this is the relay. Age is the only
+ * signal available — a step `pending` because its dispatch was lost is
+ * indistinguishable from one whose job is merely still queued — so a step past
+ * `undispatchedAfterMs` is re-dispatched regardless, and correctness rests on
+ * the claim in `executeWorkflowStepInner` rather than on the guess being right.
+ * A redundant dispatch costs one queue message: the loser reads `running` and
+ * returns without invoking anything.
+ *
+ * Re-dispatches back off per run (doubling from 30s, capped at 10m) so a
+ * genuine queue backlog is not amplified by a tick that keeps firing at the
+ * steps the backlog is already delaying.
+ */
+export declare const sweepUndispatchedSteps: (findUndispatchedSteps: (before: Date, limit: number) => Promise<Array<{
+    runId: string;
+    stepId: string;
+}>>, backoff: RedispatchBackoff, options: {
+    undispatchedAfterMs?: number;
+    limit?: number;
+} | undefined, deps: SweepDeps) => Promise<{
+    redispatched: string[];
+}>;
+export {};