@miragon/pulse-engine-core 0.0.0-stage → 0.25.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragon GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @miragon/pulse-engine-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@miragon/pulse-engine-core?style=flat-square)](https://www.npmjs.com/package/@miragon/pulse-engine-core)
+[![CI](https://img.shields.io/github/actions/workflow/status/Miragon/pulse/ci.yml?style=flat-square&label=ci)](https://github.com/Miragon/pulse/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-miragon.github.io%2Fpulse-335DE5?style=flat-square)](https://miragon.github.io/pulse/)
+
+The workflow domain of the Camunda 7 REST API family (Operaton, CIB seven, Camunda 7): where a
+process instance waits and why, how an engine is doing, and what retry and advance would send,
+and the pure engine REST rules every caller of this API needs (dates, filters, sorting, variable
+writes, incident recovery). It runs on an engine port you implement and returns data.
+
+## Who uses it
+
+[pulse-cli](https://www.npmjs.com/package/@miragon/pulse-cli) bundles it: `inspect`, `status`,
+`wait`, `advance` and `retry` run on it and word its results as command lines and CLI errors.
+[@miragon/pulse-engine-connector](https://www.npmjs.com/package/@miragon/pulse-engine-connector)
+runs inspect and status on it over its client, as the MCP tools `engine_inspect_process_instance`
+and `engine_status`.
+Pulse for VS Code bundles it in its C7 adapter: an instance's panel reads the instance through
+`loadInstance` and the root cause of an incident through `rootCause` and `rootCauseLine`.
+It is the shared domain of every Pulse interface to this API family, so an MCP tool and a CLI
+command answer the same question by the same rules.
+
+One port per API family: the vendors differ in runtime configuration, never in this package.
+
+## What it is not
+
+No HTTP, no authentication and no runtime dependency: it imports only its own modules. It names
+no command, flag or tool: next steps are structured (`{ action: "retry", processInstanceId }`),
+errors are `WorkflowError`s with a `reason` (`{ kind: "selection-ambiguous", candidates, more }`),
+and the caller words both. The English texts that describe the engine's state are the package's
+and shared by every caller: the finding messages of the status triage, its truncation notes and
+the summaries of planned writes (`execute job j1`).
+
+## Install
+
+```sh
+npm install @miragon/pulse-engine-core
+```
+
+## The API in brief
+
+- **Port:** `createEnginePort(transport)` turns your `EngineTransport` (send an operation by its
+  REST operation id, read an answer as JSON or text, read an engine failure) into the
+  `EnginePort` the workflows run on, with the shared read rules: pages of 500, a missing resource
+  as undefined, blank texts as undefined. A missing resource is an engine 404 whose exception type
+  is neither `NotFoundException` (no such endpoint, a wrong REST root) nor `QueryParamException`,
+  so your `failure` reading must carry the engine's `engineType`: without it a missing instance
+  fails instead of reading as missing.
+- **Inspect:** `inspectInstance(port, selection, options)` selects an instance by id, by business
+  key or by key with `latest`, and loads its view: wait states with their ids, root-cause
+  incidents, called instances, optionally variables, the history timeline and stacktraces (cut
+  after `MAX_STACKTRACE_LINES` lines).
+- **Status:** `readStatus({ port, now }, options)` triages one engine: findings with severity, the
+  overall status, definitions, incident groups with their root cause, topics, jobs and batches,
+  every cut named in `truncated`.
+- **Plans:** the pure parts of retry (`planRetry`, `retriesWrite`), advance (`chooseWait`,
+  `advanceSteps`) and wait (`parseCondition`, `decide`, `poll`).
+- **Engine REST rules:** the one home of what the engine expects other than what a caller
+  naturally sends: dates (`toEngineDate`, `engineDateInput` in a `DateInputReading`:
+  `OFFSET_REQUIRED` refuses a time without an offset, `UTC_WITHOUT_OFFSET` reads it as UTC;
+  `engineDateMillis`, `latestEngineDate`), true-only and `…Like` filters (`trueOnly`,
+  `complementaryFlags`, `engineLike`, `engineKeyList`, `engineInstanceSearch`), paired sorting
+  (`engineSorting`), variable writes and typing (`toEngineVariable(s)`, `autoTypedValue`),
+  incident recovery (`incidentRecovery`), the raw variable read flag (`RAW_VARIABLES`) and root
+  causes (`rootCause`, and `rootCauseLine`, the line a viewer opens the text at).
+
+```ts
+import { createEnginePort, type EngineTransport, inspectInstance } from "@miragon/pulse-engine-core"
+
+// Your client's answer of one request, read right after it arrived.
+type Answer = { readonly body?: unknown; readonly text?: string }
+
+const transport: EngineTransport<Answer> = {
+  send: (operationId, input) => yourClient.send(operationId, input),
+  json: (answer) => answer.body,
+  text: (answer) => answer.text,
+  failure: (error) =>
+    error instanceof YourHttpError
+      ? { status: error.status, engineType: error.type, engineMessage: error.message }
+      : undefined,
+}
+const port = createEnginePort(transport)
+const view = await inspectInstance(
+  port,
+  { businessKey: "B-1", latest: true },
+  { variables: true, history: false, stacktrace: false },
+)
+```
+
+## Testing helpers
+
+`@miragon/pulse-engine-core/testing` exports the verified workflow fixture, the status fixture,
+wait states of every kind, `fakePort` (a recording port over canned answers that refuses any
+operation without a route) and `fakeClock`. It also exports the rules behind the entry's
+functions that tests reach directly, and `INSPECT_OPERATIONS` and `STATUS_OPERATIONS`, the
+operations each composite sends: a port that maps operations one by one holds its table equal to
+them in a test.

package/dist/activities.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The activity instance trees of the instances of a tree as one index: which activity instance an
+ * execution belongs to, which transition instance (async continuation) waits on it, and the leaf
+ * activity instances. Pure.
+ */
+import { type Rec } from "./records.js";
+export interface ActivityNode {
+    readonly id: string;
+    readonly activityId: string;
+    readonly activityName?: string;
+    readonly activityType?: string;
+    readonly processInstanceId: string;
+    readonly depth: number;
+    /** The process instance itself (root of its activity instance tree). */
+    readonly root: boolean;
+    /** No child activity or transition instances. */
+    readonly leaf: boolean;
+    readonly transition: boolean;
+    readonly executionIds: readonly string[];
+}
+export interface ActivityIndex {
+    readonly nodes: readonly ActivityNode[];
+    byId(id: string | undefined): ActivityNode | undefined;
+    /** The activity instance of an execution: one of `activityId` if possible, else the deepest. */
+    forExecution(executionId: string | undefined, activityId?: string): ActivityNode | undefined;
+    /** The transition instance (async continuation) of an execution. */
+    transition(executionId: string | undefined, activityId?: string): ActivityNode | undefined;
+}
+/** Indexes the activity instance trees (ActivityInstanceDto) of the instances of a tree. */
+export declare function indexActivities(trees: readonly Rec[]): ActivityIndex;
+//# sourceMappingURL=activities.d.ts.map

package/dist/activities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activities.d.ts","sourceRoot":"","sources":["../src/activities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAsB,KAAK,GAAG,EAAgB,MAAM,cAAc,CAAA;AAEzE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IACvC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAA;IACtD,gGAAgG;IAChG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAA;IAC5F,oEAAoE;IACpE,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAA;CAC3F;AAyDD,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,EAAE,GAAG,aAAa,CAmBpE"}

package/dist/activities.js

@@ -0,0 +1,62 @@
+/**
+ * The activity instance trees of the instances of a tree as one index: which activity instance an
+ * execution belongs to, which transition instance (async continuation) waits on it, and the leaf
+ * activity instances. Pure.
+ */
+import { compareText, field, records, str } from "./records.js";
+function strings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function node(instance, position, flags, executionIds) {
+    const name = str(instance, "activityName") ?? str(instance, "name");
+    const type = str(instance, "activityType");
+    return {
+        id: field(instance, "id"),
+        activityId: field(instance, "activityId"),
+        ...(name === undefined ? {} : { activityName: name }),
+        ...(type === undefined ? {} : { activityType: type }),
+        ...position,
+        ...flags,
+        executionIds,
+    };
+}
+function walk(instance, position, nodes) {
+    const children = records(instance.childActivityInstances);
+    const transitions = records(instance.childTransitionInstances);
+    const leaf = children.length === 0 && transitions.length === 0;
+    const flags = { root: position.depth === 0, leaf, transition: false };
+    nodes.push(node(instance, position, flags, strings(instance.executionIds)));
+    const below = { ...position, depth: position.depth + 1 };
+    for (const child of children)
+        walk(child, below, nodes);
+    for (const transition of transitions) {
+        const executionId = str(transition, "executionId");
+        const transitionFlags = { root: false, leaf: false, transition: true };
+        nodes.push(node(transition, below, transitionFlags, executionId === undefined ? [] : [executionId]));
+    }
+}
+/** Deepest first, then by id: a deterministic choice among candidates. */
+function best(candidates, activityId) {
+    const matching = candidates.filter((candidate) => candidate.activityId === activityId);
+    return (matching.length > 0 ? matching : candidates).toSorted((left, right) => right.depth - left.depth || compareText(left.id, right.id))[0];
+}
+/** Indexes the activity instance trees (ActivityInstanceDto) of the instances of a tree. */
+export function indexActivities(trees) {
+    const nodes = [];
+    for (const tree of trees) {
+        const processInstanceId = str(tree, "processInstanceId") ?? field(tree, "id");
+        walk(tree, { processInstanceId, depth: 0 }, nodes);
+    }
+    const containing = (executionId, transition) => executionId === undefined
+        ? []
+        : nodes.filter((candidate) => candidate.transition === transition && candidate.executionIds.includes(executionId));
+    return {
+        nodes,
+        byId: (id) => (id === undefined ? undefined : nodes.find((candidate) => candidate.id === id)),
+        forExecution: (executionId, activityId) => best(containing(executionId, false), activityId),
+        transition: (executionId, activityId) => best(containing(executionId, true), activityId),
+    };
+}
+//# sourceMappingURL=activities.js.map

package/dist/activities.js.map

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

package/dist/advance-plan.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Planning of advance: which wait state to move, which options apply to it, and the requests that
+ * move it. Pure.
+ */
+import type { PlannedWrite } from "./port.js";
+import type { AdvanceInput, InstanceView, WaitState } from "./types.js";
+/** Option combinations, checked before any request. */
+export declare function checkAdvanceInput(input: AdvanceInput): void;
+type ViewInput = Pick<InstanceView<unknown>, "id" | "state" | "waitingAt" | "children" | "truncated">;
+/** The wait state to move: the only advanceable one (of `activityId`). */
+export declare function chooseWait(view: ViewInput, activityId?: string): WaitState;
+/** Options that do not apply to the chosen wait state are refused. */
+export declare function checkOptions(wait: WaitState, input: AdvanceInput): void;
+/** A suspended job is not executed behind the operator's back. */
+export declare function checkSuspended(wait: WaitState): void;
+/** A lock of another worker that has not expired is refused; `worker` is the caller's default. */
+export declare function checkLock(wait: WaitState, input: AdvanceInput, now: number, worker: string): void;
+/** The writes that move the wait state, in order; `worker` locks an external task by default. */
+export declare function advanceSteps(wait: WaitState, input: AdvanceInput, worker: string): PlannedWrite[];
+export {};
+//# sourceMappingURL=advance-plan.d.ts.map

package/dist/advance-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance-plan.d.ts","sourceRoot":"","sources":["../src/advance-plan.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAE7C,OAAO,KAAK,EAAE,YAAY,EAAiB,YAAY,EAAY,SAAS,EAAE,MAAM,YAAY,CAAA;AAmBhG,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAU3D;AAED,KAAK,SAAS,GAAG,IAAI,CACnB,YAAY,CAAC,OAAO,CAAC,EACrB,IAAI,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,CACxD,CAAA;AAgBD,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAgB1E;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAYvE;AAED,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAOpD;AAED,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAWjG;AAqGD,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAYjG"}

package/dist/advance-plan.js

@@ -0,0 +1,192 @@
+/**
+ * Planning of advance: which wait state to move, which options apply to it, and the requests that
+ * move it. Pure.
+ */
+import { WorkflowError } from "./errors.js";
+import { isAdvanceable, isSuspendedJob } from "./next.js";
+import { engineTime } from "./dates.js";
+import { compact } from "./util.js";
+import { waitId } from "./waits.js";
+const LOCK_DURATION_MS = 60_000;
+const TASKS = ["userTask", "externalTask"];
+/** The kinds each option applies to, in the order the options are checked. */
+const OPTION_KINDS = {
+    variables: ["userTask", "externalTask", "message", "signal", "other"],
+    localVariables: ["externalTask"],
+    bpmnError: TASKS,
+    errorMessage: TASKS,
+    fail: ["externalTask"],
+    retries: ["externalTask"],
+    workerId: ["externalTask"],
+};
+/** Option combinations, checked before any request. */
+export function checkAdvanceInput(input) {
+    if (input.bpmnError !== undefined && input.fail !== undefined) {
+        throw new WorkflowError({ kind: "advance-input", rule: "bpmn-error-excludes-fail" });
+    }
+    if (input.errorMessage !== undefined && input.bpmnError === undefined) {
+        throw new WorkflowError({ kind: "advance-input", rule: "error-message-needs-bpmn-error" });
+    }
+    if (input.retries !== undefined && input.fail === undefined) {
+        throw new WorkflowError({ kind: "advance-input", rule: "retries-need-fail" });
+    }
+}
+function nothing(view, activityId) {
+    const firstChildId = view.truncated === true ? view.children[0]?.id : undefined;
+    return new WorkflowError({
+        kind: "advance-nothing",
+        id: view.id,
+        ...compact({ activityId }),
+        waiting: view.waitingAt
+            .filter(isAdvanceable)
+            .map((wait) => ({ activityId: wait.activityId, kind: wait.kind })),
+        conditional: view.waitingAt.some((wait) => wait.kind === "conditional"),
+        ...compact({ firstChildId }),
+    });
+}
+/** The wait state to move: the only advanceable one (of `activityId`). */
+export function chooseWait(view, activityId) {
+    if (view.state !== "ACTIVE" && view.state !== "SUSPENDED") {
+        throw new WorkflowError({ kind: "advance-ended", id: view.id, state: view.state });
+    }
+    if (view.state === "SUSPENDED")
+        throw new WorkflowError({ kind: "advance-suspended", id: view.id });
+    const matching = view.waitingAt.filter((wait) => isAdvanceable(wait) && (activityId === undefined || wait.activityId === activityId));
+    // a suspended job does not count as a place while something else can move (like the next steps)
+    const movable = matching.filter((wait) => !isSuspendedJob(wait));
+    const waits = movable.length > 0 ? movable : matching;
+    const [only, ...others] = waits;
+    if (only === undefined)
+        throw nothing(view, activityId);
+    if (others.length > 0)
+        throw new WorkflowError({ kind: "advance-ambiguous", id: view.id, waits });
+    return only;
+}
+/** Options that do not apply to the chosen wait state are refused. */
+export function checkOptions(wait, input) {
+    for (const [option, kinds] of Object.entries(OPTION_KINDS)) {
+        if (input[option] !== undefined && !kinds.includes(wait.kind)) {
+            throw new WorkflowError({
+                kind: "advance-option-kind",
+                option,
+                appliesTo: kinds,
+                activityId: wait.activityId,
+                waitKind: wait.kind,
+            });
+        }
+    }
+}
+/** A suspended job is not executed behind the operator's back. */
+export function checkSuspended(wait) {
+    if (!isSuspendedJob(wait) || !("jobId" in wait))
+        return;
+    throw new WorkflowError({
+        kind: "advance-job-suspended",
+        jobId: wait.jobId,
+        activityId: wait.activityId,
+    });
+}
+/** A lock of another worker that has not expired is refused; `worker` is the caller's default. */
+export function checkLock(wait, input, now, worker) {
+    if (wait.kind !== "externalTask" || wait.workerId === undefined)
+        return;
+    const own = input.workerId ?? worker;
+    const until = engineTime(wait.lockExpirationTime);
+    if (wait.workerId === own || until === undefined || until <= now)
+        return;
+    throw new WorkflowError({
+        kind: "advance-locked",
+        externalTaskId: wait.externalTaskId,
+        workerId: wait.workerId,
+        ...compact({ lockExpirationTime: wait.lockExpirationTime }),
+    });
+}
+function write(label, operationId, pathArgs, body) {
+    return {
+        label,
+        operationId,
+        input: { pathArgs, query: {}, ...(body === undefined ? {} : { body }) },
+    };
+}
+function variablesOf(input) {
+    return compact({ variables: input.variables, localVariables: input.localVariables });
+}
+function userTaskSteps(taskId, input) {
+    if (input.bpmnError === undefined) {
+        return [
+            write(`complete user task ${taskId}`, "complete", [taskId], compact({ variables: input.variables })),
+        ];
+    }
+    const body = {
+        errorCode: input.bpmnError,
+        ...compact({ errorMessage: input.errorMessage, variables: input.variables }),
+    };
+    return [
+        write(`throw BPMN error ${input.bpmnError} on user task ${taskId}`, "handleBpmnError", [taskId], body),
+    ];
+}
+function externalTaskSteps(id, input, workerId) {
+    const lock = write(`lock external task ${id} as ${workerId}`, "lock", [id], {
+        workerId,
+        lockDuration: LOCK_DURATION_MS,
+    });
+    if (input.bpmnError !== undefined) {
+        const body = {
+            workerId,
+            errorCode: input.bpmnError,
+            ...compact({ errorMessage: input.errorMessage, variables: input.variables }),
+        };
+        return [
+            lock,
+            write(`throw BPMN error ${input.bpmnError} on external task ${id}`, "handleExternalTaskBpmnError", [id], body),
+        ];
+    }
+    if (input.fail !== undefined) {
+        const body = {
+            workerId,
+            errorMessage: input.fail,
+            retries: input.retries ?? 0,
+            retryTimeout: 0,
+            ...variablesOf(input),
+        };
+        return [lock, write(`report a failure of external task ${id}`, "handleFailure", [id], body)];
+    }
+    return [
+        lock,
+        write(`complete external task ${id}`, "completeExternalTaskResource", [id], {
+            workerId,
+            ...variablesOf(input),
+        }),
+    ];
+}
+/** The write of a message, a signal or a receive task (`other`). */
+function eventStep(wait, input) {
+    const variables = compact({ variables: input.variables });
+    if (wait.kind === "message") {
+        const name = wait.eventName ?? "";
+        const label = `trigger message ${name} of execution ${wait.executionId}`;
+        return write(label, "triggerEvent", [wait.executionId, name], variables);
+    }
+    if (wait.kind === "signal") {
+        const name = wait.eventName ?? "";
+        const body = { name, executionId: wait.executionId, ...variables };
+        return write(`send signal ${name} to execution ${wait.executionId}`, "throwSignal", [], body);
+    }
+    const executionId = waitId(wait);
+    return write(`signal execution ${executionId}`, "signalExecution", [executionId], variables);
+}
+/** The writes that move the wait state, in order; `worker` locks an external task by default. */
+export function advanceSteps(wait, input, worker) {
+    switch (wait.kind) {
+        case "userTask":
+            return userTaskSteps(wait.taskId, input);
+        case "externalTask":
+            return externalTaskSteps(wait.externalTaskId, input, input.workerId ?? worker);
+        case "timer":
+        case "asyncContinuation":
+            return [write(`execute job ${wait.jobId}`, "executeJob", [wait.jobId])];
+        default:
+            return [eventStep(wait, input)];
+    }
+}
+//# sourceMappingURL=advance-plan.js.map

package/dist/advance-plan.js.map

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

package/dist/conditions.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Wait conditions: parsing, the requests each condition needs per poll, and the order in which a
+ * poll decides.
+ */
+import type { EnginePort } from "./port.js";
+export type Condition = {
+    readonly kind: "idle" | "ended" | "incident";
+} | {
+    readonly kind: "task";
+    readonly key?: string;
+} | {
+    readonly kind: "activity";
+    readonly id: string;
+};
+export declare function parseCondition(raw: string): Condition;
+export declare function conditionLabel(condition: Condition): string;
+/** The instance as one poll saw it. */
+export interface Probe {
+    readonly id: string;
+    readonly ended: boolean;
+    /** The active tree (empty once the instance ended). */
+    readonly tree: readonly string[];
+    /** The tree was cut: instances beyond the cut are not counted. */
+    readonly truncated?: boolean;
+}
+export interface Measurement {
+    /** Instances of the tree with an incident. */
+    readonly incidents: number;
+    /** Labels of the conditions that hold, other than `incident`, in the given order. */
+    readonly held: readonly string[];
+}
+/**
+ * The jobs the job executor will run: retries left, due, and active. The engine's `executable`
+ * filter checks the suspension of the instance only, not of the job (a suspended job definition
+ * suspends its jobs), hence `active` (verified on all three engines).
+ */
+export declare const EXECUTABLE: {
+    readonly executable: "true";
+    readonly active: "true";
+};
+/**
+ * The counts of one poll: only what the conditions need, then the incident check. The incident
+ * count is read after the condition counts, never in parallel with them: a job that fails for good
+ * loses its last retry and gets its incident in one transaction, so a job count that no longer sees
+ * the job is followed by an incident count that sees the incident. Read in parallel, the incident
+ * count could come from before that transaction and the job count from after it, and the poll
+ * would see neither (a stuck instance reported as idle).
+ */
+export declare function measure(port: EnginePort, probe: Probe, conditions: readonly Condition[], checkIncidents: boolean): Promise<Measurement>;
+export type Verdict = {
+    readonly kind: "held";
+    readonly until: string;
+} | {
+    readonly kind: "incident";
+} | {
+    readonly kind: "ended";
+} | {
+    readonly kind: "pending";
+};
+/**
+ * The decision of a poll: the condition `incident` with an incident, then an incident with fail fast
+ * (a job that failed for good is not executable, so `idle` would otherwise report success for a
+ * stuck instance), then any other condition, then an ended instance.
+ */
+export declare function decide(conditions: readonly Condition[], failOnIncident: boolean, probe: Probe, measurement: Measurement): Verdict;
+//# sourceMappingURL=conditions.d.ts.map

package/dist/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAG3C,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA;AAgBtD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAQrD;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAS3D;AAED,uCAAuC;AACvC,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAsBD;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;CAAkD,CAAA;AA6BzE;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,cAAc,EAAE,OAAO,GACtB,OAAO,CAAC,WAAW,CAAC,CAOtB;AAED,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAEhC;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,cAAc,EAAE,OAAO,EACvB,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,WAAW,GACvB,OAAO,CAOT"}