@pikku/core 0.12.130 → 0.12.133

package/dist/wirings/trigger/index.d.ts

@@ -1,7 +1,7 @@
 export { wireTrigger, wireTriggerSource } from './trigger-runner.js';
 export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, declaredTriggerSources, reconcileTriggerSources, enableTriggerSource, disableTriggerSource, reconcileWebhookRegistrations, teardownTriggerSources, subscribedWebhookEvents, } from './webhook-source-runner.js';
 export type { OrphanedWebhookRegistration, WebhookRegistration, WebhookRegistrations, WebhookSourceOutcome, } from './webhook-source-runner.js';
-export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from './webhook-source.types.js';
-export type { CoreTriggerWebhookSource, TriggerEvent, WebhookCheckResult, WebhookLifecycleInput, WebhookReceiveResult, WebhookRequest, WebhookSetupResult, WebhookSourceJob, WebhookSourceMeta, WebhookSourceMethod, WebhookSourcesMeta, WebhookSourceState, WebhookTeardownInput, WebhookTeardownResult, } from './webhook-source.types.js';
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME, webhookSecretCredentialName, } from './webhook-source.types.js';
+export type { CoreTriggerWebhookSource, TriggerEvent, WebhookCheckResult, WebhookLifecycleInput, WebhookReceiveResult, WebhookRequest, WebhookSetupResult, WebhookSourceJob, WebhookSourceMeta, WebhookSourceMethod, WebhookSourcesMeta, WebhookSourceState, WebhookTeardownInput, WebhookTeardownResult, WebhookVerify, } from './webhook-source.types.js';
 export { PikkuTriggerService } from './pikku-trigger-service.js';
 export type { TriggerMeta, TriggerSourceMeta, CorePikkuTriggerFunction, CorePikkuTriggerFunctionConfig, CoreTrigger, } from './trigger.types.js';

package/dist/wirings/trigger/index.js

@@ -1,4 +1,4 @@
 export { wireTrigger, wireTriggerSource } from './trigger-runner.js';
 export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, declaredTriggerSources, reconcileTriggerSources, enableTriggerSource, disableTriggerSource, reconcileWebhookRegistrations, teardownTriggerSources, subscribedWebhookEvents, } from './webhook-source-runner.js';
-export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from './webhook-source.types.js';
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME, webhookSecretCredentialName, } from './webhook-source.types.js';
 export { PikkuTriggerService } from './pikku-trigger-service.js';

package/dist/wirings/trigger/webhook-source-runner.js

@@ -1,6 +1,8 @@
 import { getSingletonServices, pikkuState } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
-import { PikkuMissingMetaError } from '../../errors/errors.js';
+import { PikkuMissingMetaError, UnauthorizedError, } from '../../errors/errors.js';
+import { timingSafeStringEqual, verifyHmacSignature, verifyPublicKeySignature, } from '../../utils/hmac.js';
+import { webhookSecretCredentialName } from './webhook-source.types.js';
 const LIFECYCLE = ['receive', 'check', 'setup', 'teardown'];
 export const wireTriggerWebhookSource = (source) => {
     const meta = pikkuState(null, 'trigger', 'webhookSourceMeta')[source.name];
@@ -59,6 +61,44 @@ const readRequest = async (http) => {
         query,
     };
 };
+const signedWith = async (verify, request, secret, services) => {
+    if (typeof verify === 'function') {
+        return await verify(request, secret, services);
+    }
+    const header = (name, prefix = '') => {
+        const value = request.headers[name.toLowerCase()];
+        return value?.startsWith(prefix) ? value.slice(prefix.length) : undefined;
+    };
+    if ('hmac' in verify) {
+        const { header: name, prefix, algorithm, encoding, secretEncoding } = verify.hmac;
+        return verifyHmacSignature(secret, header(name, prefix), algorithm, request.body, encoding, secretEncoding);
+    }
+    if ('token' in verify) {
+        const token = header(verify.token.header, verify.token.prefix);
+        return !!token && timingSafeStringEqual(token, secret);
+    }
+    const { header: name, ...options } = verify.publicKey;
+    return verifyPublicKeySignature(secret, header(name), request.body, options);
+};
+/**
+ * Whether the request was checked against the source's signing secret. Throws
+ * when it was checked and failed. A source without `verify` checks in its own
+ * `receive`, and a request without a body has nothing signed to check.
+ */
+const verifyRequest = async (source, request, services) => {
+    if (!source?.verify)
+        return true;
+    if (request.body.length === 0)
+        return false;
+    const secret = await services.credentialService?.get(source.credential ?? webhookSecretCredentialName(source.name));
+    if (typeof secret !== 'string' || !secret) {
+        throw new UnauthorizedError(`The ${source.name} webhook source has no signing secret`);
+    }
+    if (!(await signedWith(source.verify, request, secret, services))) {
+        throw new UnauthorizedError(`Invalid ${source.name} webhook signature`);
+    }
+    return true;
+};
 const validateEvents = async (source, events, logger) => {
     const valid = [];
     for (const event of events) {
@@ -91,6 +131,7 @@ export const receiveWebhookSourceRequest = async (sourceName, wire) => {
     }
     const source = pikkuState(null, 'trigger', 'webhookSources').get(sourceName);
     const request = await readRequest(wire.http);
+    const verified = await verifyRequest(source, request, singletonServices);
     const result = meta.receive
         ? await runSourceStep(singletonServices, sourceName, meta.receive, request)
         : {
@@ -112,6 +153,9 @@ export const receiveWebhookSourceRequest = async (sourceName, wire) => {
                 : JSON.stringify(body);
         return new Response(text, { status, headers });
     }
+    if (!verified && result.events.length > 0) {
+        throw new UnauthorizedError(`The ${sourceName} webhook source received events in an unsigned request`);
+    }
     const triggers = pikkuState(null, 'trigger', 'meta');
     const listened = result.events.filter((event) => triggers[triggerName(sourceName, event.name)]);
     const events = await validateEvents(source, listened, singletonServices.logger);

package/dist/wirings/trigger/webhook-source.types.d.ts

@@ -1,6 +1,9 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
+import type { HmacAlgorithm, SecretEncoding } from '../../utils/hmac.js';
 export declare const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = "pikku-incoming-webhooks";
+/** `github` → `githubWebhookSecret`, `microsoft-outlook` → `microsoftOutlookWebhookSecret`. */
+export declare const webhookSecretCredentialName: (source: string) => string;
 /** What every trigger source produces, whichever way it arrives. */
 export type TriggerEvent<Name extends string = string, Data = unknown> = {
     /** The provider's event type; dispatched to the trigger named `<source>:<name>`. Empty dispatches to `<source>`. */
@@ -64,6 +67,38 @@ export type WebhookTeardownInput = {
 export type WebhookTeardownResult = {
     status: 'deleted' | 'absent';
 };
+/**
+ * How a source's requests are signed. The declared forms cover a signature
+ * over the raw body in one header; anything else — a timestamp in the signed
+ * payload, form fields, a URL — is a function that says whether the request is
+ * genuine, using the helpers in `@pikku/core/hmac`.
+ */
+export type WebhookVerify<Services = any> = {
+    hmac: {
+        header: string;
+        /** Stripped from the header before comparing, such as `sha256=`. */
+        prefix?: string;
+        algorithm: HmacAlgorithm;
+        encoding: 'hex' | 'base64';
+        /** How the stored secret is encoded. Defaults to `utf8`. */
+        secretEncoding?: SecretEncoding;
+    };
+}
+/** The provider sends the shared secret itself rather than a signature. */
+ | {
+    token: {
+        header: string;
+        prefix?: string;
+    };
+}
+/** The provider signs with a private key: the stored secret is its public key, as PEM. */
+ | {
+    publicKey: {
+        header: string;
+        algorithm?: string;
+        dsaEncoding?: 'der' | 'ieee-p1363';
+    };
+} | ((request: WebhookRequest, secret: string, services: Services) => boolean | Promise<boolean>);
 type SourceFunction<In, Out> = CorePikkuFunctionConfig<any, any> & {
     func: (services: any, data: In, wire: any) => Promise<Out>;
 };
@@ -76,6 +111,21 @@ export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchem
     route?: string;
     /** What the source can produce. Each event's data is validated against its schema before it is queued. */
     events?: Events;
+    /**
+     * The credential holding the signing secret. Defaults to
+     * {@link webhookSecretCredentialName}. Declaring `verify` declares this
+     * credential too, as a singleton string, so it needs no `defineCredential`.
+     */
+    credential?: string;
+    /** What the secret is and where to find it, shown to whoever has to set it. */
+    credentialDescription?: string;
+    /**
+     * Checked before `receive` on every request with a body. A request is
+     * refused when the credential is not set or the signature does not match.
+     * A request without a body — a HEAD probe, a validation token in the query —
+     * reaches `receive` unchecked, and may be answered but dispatches nothing.
+     */
+    verify?: WebhookVerify;
     /** Omitted: the JSON body is one event dispatched to the trigger named `<name>`. */
     receive?: SourceFunction<WebhookRequest, WebhookReceiveResult>;
     check?: SourceFunction<WebhookLifecycleInput, WebhookCheckResult>;

package/dist/wirings/trigger/webhook-source.types.js

@@ -1 +1,3 @@
 export const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = 'pikku-incoming-webhooks';
+/** `github` → `githubWebhookSecret`, `microsoft-outlook` → `microsoftOutlookWebhookSecret`. */
+export const webhookSecretCredentialName = (source) => `${source.replace(/[-_]+([a-z0-9])/gi, (_, c) => c.toUpperCase())}WebhookSecret`;

package/dist/wirings/workflow/graph/graph-runner.js

@@ -1,5 +1,6 @@
 import { WorkflowAsyncException, WorkflowSuspendedException, } from '../workflow-errors.js';
 import { DEFAULT_STEP_RETRIES } from '../workflow-constants.js';
+import { runningStepLease } from '../workflow-step-lease.js';
 import { pikkuState, getSingletonServices } from '../../../pikku-state.js';
 import { RPCNotFoundError } from '../../rpc/rpc-runner.js';
 export class ChildWorkflowStartedException extends Error {
@@ -563,11 +564,12 @@ async function createGraphResultReader(workflowService, runId, graphName, nodes,
         },
     };
 }
+const graphStepOptions = (nodeConfig) => ({
+    retries: nodeConfig?.retries ?? DEFAULT_STEP_RETRIES,
+    retryDelay: nodeConfig?.retryDelay,
+});
 async function queueGraphNode(workflowService, runId, _graphName, nodeId, rpcName, input, nodeConfig, fromStepName) {
-    const stepOptions = {
-        retries: nodeConfig?.retries ?? DEFAULT_STEP_RETRIES,
-        retryDelay: nodeConfig?.retryDelay,
-    };
+    const stepOptions = graphStepOptions(nodeConfig);
     await workflowService.insertStepState(runId, nodeId, rpcName, input, stepOptions, fromStepName);
     await workflowService.queueStepWorker(runId, nodeId, rpcName, input, stepOptions, fromStepName);
 }
@@ -599,6 +601,32 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
     const triggerInput = currentRun?.input;
     const reader = await createGraphResultReader(workflowService, runId, graphName, nodes, triggerInput, instances);
     const plan = planGraphTransitions(nodes, instances, branchByStep, meta.entryNodeIds ?? [], graphName, reader.fanoutWidths);
+    const resolveNodeInput = async (logical, itemIndex) => {
+        const node = nodes[logical];
+        const referencedNodeIds = extractReferencedNodeIds(node.input).filter((id) => !IGNORED_REFS.has(id));
+        const fetchedResults = await reader.read(referencedNodeIds);
+        const nodeResults = {
+            trigger: triggerInput,
+            ...fetchedResults,
+        };
+        if (itemIndex !== undefined) {
+            nodeResults['$item'] = reader.fanoutItems[logical]?.[itemIndex];
+        }
+        return resolveSerializedInput(node.input, nodeResults);
+    };
+    // A node whose worker died is still `running`, so the plan counts it in
+    // flight and would wait on it forever. Its step already exists: dispatching
+    // it again is enough, and the claim makes that the next attempt.
+    for (const instance of instances) {
+        if (runningStepLease(instance) !== 'lapsed')
+            continue;
+        const logical = remapStepNamesToNodeIds([instance.stepName], nodes, graphName)[0];
+        const node = nodes[logical];
+        if (!node?.rpcName)
+            continue;
+        const itemIndex = splitFanoutInstance(instance.stepName)?.index;
+        await workflowService.queueStepWorker(runId, instance.stepName, node.rpcName, await resolveNodeInput(logical, itemIndex), graphStepOptions(node), instance.fromStepName);
+    }
     if (plan.toFire.length === 0) {
         if (!plan.hasInFlight && !plan.blockedWaiting) {
             await workflowService.updateRunStatus(runId, 'completed');
@@ -609,16 +637,7 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
         const node = nodes[fire.logical];
         if (!node?.rpcName)
             continue;
-        const referencedNodeIds = extractReferencedNodeIds(node.input).filter((id) => !IGNORED_REFS.has(id));
-        const fetchedResults = await reader.read(referencedNodeIds);
-        const nodeResults = {
-            trigger: triggerInput,
-            ...fetchedResults,
-        };
-        if (fire.itemIndex !== undefined) {
-            nodeResults['$item'] = reader.fanoutItems[fire.logical]?.[fire.itemIndex];
-        }
-        const resolvedInput = resolveSerializedInput(node.input, nodeResults);
+        const resolvedInput = await resolveNodeInput(fire.logical, fire.itemIndex);
         await queueGraphNode(workflowService, runId, graphName, fire.instanceKey, node.rpcName, resolvedInput, node, fire.fromStepName);
     }
 }

package/dist/wirings/workflow/index.d.ts

@@ -1,6 +1,7 @@
 export { PikkuWorkflowService } from './pikku-workflow-service.js';
-export { WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, WorkflowStepFunctionMismatchError, } from './workflow-errors.js';
-export { DEFAULT_STEP_RETRIES } from './workflow-constants.js';
+export { WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, WorkflowStepFunctionMismatchError, WorkflowStepLeaseExpiredError, WorkflowStepSupersededError, } from './workflow-errors.js';
+export { DEFAULT_STEP_RETRIES, DEFAULT_STEP_LEASE_MS, isStepLeaseLive, } from './workflow-constants.js';
+export { leaseAttemptsExhausted } from './workflow-step-claim.js';
 export { assertWorkflowRunOwner, WorkflowRunForbiddenError, } from './workflow-run-ownership.js';
 export { WorkflowApprovalForbiddenError } from './workflow-approval-policy.js';
 export { streamWorkflowRunStatus, type WorkflowStatusStreamParams, } from './workflow-status-stream.js';
@@ -14,7 +15,7 @@ export { addWorkflow } from './dsl/workflow-runner.js';
 export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowsRuntimeMeta, } from './workflow.types.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowsRuntimeMeta, } from './workflow.types.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';
 export { createGraph } from './graph/graph-node.js';
 export type { GraphNodeConfig, ForEachConfig, ForEachMode, ItemFn, TemplateFn, } from './graph/workflow-graph.types.js';

package/dist/wirings/workflow/index.js

@@ -1,6 +1,7 @@
 export { PikkuWorkflowService } from './pikku-workflow-service.js';
-export { WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, WorkflowStepFunctionMismatchError, } from './workflow-errors.js';
-export { DEFAULT_STEP_RETRIES } from './workflow-constants.js';
+export { WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, WorkflowStepFunctionMismatchError, WorkflowStepLeaseExpiredError, WorkflowStepSupersededError, } from './workflow-errors.js';
+export { DEFAULT_STEP_RETRIES, DEFAULT_STEP_LEASE_MS, isStepLeaseLive, } from './workflow-constants.js';
+export { leaseAttemptsExhausted } from './workflow-step-claim.js';
 export { assertWorkflowRunOwner, WorkflowRunForbiddenError, } from './workflow-run-ownership.js';
 export { WorkflowApprovalForbiddenError } from './workflow-approval-policy.js';
 export { streamWorkflowRunStatus, } from './workflow-status-stream.js';

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -7,6 +7,7 @@ import type { ScenarioPersonas } from '../../services/personas-service.js';
 import type { PikkuRPC } from '../rpc/rpc-types.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
 import type { WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
+import type { LeaseService } from '../../services/lease-service.js';
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private runExtension?;
     private runContexts;
@@ -16,14 +17,21 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private exitExecution;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
+    /**
+     * Serialises orchestration passes over a run and claims on a step. A service
+     * whose state no other process can reach — in-memory, a Durable Object —
+     * has no competitor to exclude, overrides both locks and passes none.
+     */
+    protected readonly leaseService?: LeaseService;
     protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
     protected readonly queueConcurrency: number;
     protected readonly queueGroupConcurrency: number | GroupConcurrencyConfig;
     constructor(options?: {
         wireQueues?: boolean;
         mirror?: WorkflowRunMirror;
+        leaseService?: LeaseService;
     } & WorkflowQueueOptions);
-    private mirrored;
+    protected mirrored<T>(write: () => Promise<T>, mirror: (mirror: WorkflowRunMirror, written: T) => Promise<void>): Promise<T>;
     wireQueueWorkers(): void;
     protected isInline(runId: string): Promise<boolean>;
     registerInlineRun(runId: string): void;
@@ -51,18 +59,41 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     abstract getStepState(runId: string, stepName: string): Promise<StepState>;
     setStepRunning(stepId: string): Promise<void>;
     protected abstract setStepRunningImpl(stepId: string): Promise<void>;
+    /**
+     * Push the claim on a `running` step forward, so it keeps reading as owned
+     * for another lease.
+     *
+     * Does nothing by default, which leaves a store that records no lease exactly
+     * as it was: its `running` steps are owned until they move on their own, and
+     * a dispatch that dies takes the step with it. A store that overrides this
+     * gains recovery from a lost worker, through both `claimStepForExecution` and
+     * `recoverStalledRuns`.
+     *
+     * `null` releases the lease without ending the step, for a step that is
+     * legitimately `running` with no worker on it — one parked on a child run,
+     * which the child's completion drives rather than a redispatch.
+     * `attempt` fences it to the claim that holds it.
+     *
+     * The lease runs `leaseMs` from now on the store's own clock, so workers
+     * whose clocks disagree still agree on when it lapses. Resolves `false` when
+     * the step is no longer this attempt's to renew.
+     */
+    refreshStepLease(_stepId: string, _leaseMs: number | null, _attempt?: number): Promise<boolean>;
     setStepScheduled(stepId: string): Promise<void>;
     protected abstract setStepScheduledImpl(stepId: string): Promise<void>;
-    setStepResult(stepId: string, result: any): Promise<void>;
-    protected abstract setStepResultImpl(stepId: string, result: any): Promise<void>;
+    /** `attempt` fences it: a newer claim's step throws `WorkflowStepSupersededError`. */
+    setStepResult(stepId: string, result: any, attempt?: number): Promise<void>;
+    protected abstract setStepResultImpl(stepId: string, result: any, attempt?: number): Promise<void>;
     setStepChildRunId(stepId: string, childRunId: string): Promise<void>;
     protected abstract setStepChildRunIdImpl(stepId: string, childRunId: string): Promise<void>;
-    setStepError(stepId: string, error: Error): Promise<void>;
-    protected abstract setStepErrorImpl(stepId: string, error: Error): Promise<void>;
+    setStepError(stepId: string, error: Error, attempt?: number): Promise<void>;
+    protected abstract setStepErrorImpl(stepId: string, error: Error, attempt?: number): Promise<void>;
     createRetryAttempt(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
     protected abstract createRetryAttemptImpl(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
-    abstract withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
-    abstract withStepLock<T>(runId: string, stepName: string, fn: () => Promise<T>): Promise<T>;
+    /** One orchestration pass under the run's lease; never waits (see `holdWorkflowLease`). */
+    withRunLease<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    /** `fn` under one step's lease; never waits (see `holdWorkflowLease`). */
+    withStepLock<T>(runId: string, stepName: string, fn: () => Promise<T>): Promise<T>;
     abstract close(): Promise<void>;
     abstract getCompletedGraphState(runId: string): Promise<{
         completedNodeIds: string[];
@@ -73,6 +104,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         stepName: string;
         status: StepStatus;
         fromStepName?: string;
+        /** Set by a store that records step leases; see `runningStepLease`. */
+        leaseExpiresAt?: Date;
     }>>;
     abstract getNodeResults(runId: string, nodeIds: string[]): Promise<Record<string, any>>;
     setBranchTaken(stepId: string, branchKey: string): Promise<void>;
@@ -89,10 +122,15 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         source: string;
     } | null>;
     resumeWorkflow(runId: string, workflowName?: string): Promise<void>;
+    private enqueueOrchestration;
     /**
      * Ids of runs that are stalled: still `running`, with no step in a state that
-     * something is expected to complete (`running`, `scheduled`, `suspended`),
-     * and no step activity since `before`.
+     * something is expected to complete (`scheduled`, `suspended`, or `running`
+     * under a live lease), and no step activity since `before`.
+     *
+     * A `running` step whose lease has lapsed is the opposite of in flight — the
+     * dispatch that claimed it is gone — so it does not hold its run out of the
+     * sweep.
      *
      * Returns nothing by default so a store that cannot express the query keeps
      * working unchanged; a store that overrides it gains crash recovery through
@@ -175,7 +213,6 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private runWorkflowJobInner;
     private onChildWorkflowCompleted;
     protected onChildWorkflowFailed(childRun: WorkflowRun, error: Error): Promise<void>;
-    private runVersionMismatchFallback;
     executeWorkflowStep(runId: string, stepName: string, rpcName: string, data: any, rpcService: PikkuRPC): Promise<void>;
     /**
      * Take sole ownership of a step before it runs, returning the state to run
@@ -185,18 +222,20 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * believes were dropped, and a queue can redeliver a job it already handed
      * out. This is the one place that keeps a duplicate dispatch from becoming a
      * second execution of a side-effecting step, so it is only as strong as the
-     * exclusion it is built on — and `withStepLock` excludes nothing unless the
-     * store backs it with a real primitive. A store able to express the decision
-     * as one conditional write should override this rather than reach for a lock,
-     * which is what `@pikku/kysely` does with a status-guarded `UPDATE`.
+     * exclusion it is built on: here, the step's lease on the app's
+     * `leaseService`. A store able to express the decision as one conditional
+     * write should override this rather than reach for a lock, which is what
+     * `@pikku/kysely` does with a status-guarded `UPDATE`.
+     *
+     * Ownership is held for `leaseMs` rather than forever. A dispatch that
+     * dies mid-step leaves the step `running` with nothing to complete it, and an
+     * unconditional rejection of `running` would then wedge it beyond the reach
+     * of both this claim and the stalled-run sweep.
      */
-    protected claimStepForExecution(runId: string, stepName: string, rpcName: string): Promise<StepState | null>;
+    protected claimStepForExecution(runId: string, stepName: string, rpcName: string, leaseMs: number): Promise<StepState | null>;
     private executeWorkflowStepInner;
     orchestrateWorkflow(runId: string, rpcService: PikkuRPC): Promise<void>;
-    private verifyQueueService;
     private invokeStepRpc;
-    private runInlineRetryLoop;
-    private runStepCompensation;
     private rpcStep;
     protected inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, data?: any, rpcName?: string | null): Promise<any>;
     private sleepStep;