@adonis-agora/durable 0.58.3 → 0.60.0

package/dist/src/engine.d.ts

@@ -2,9 +2,11 @@ import { type AdmissionBackend } from './admission.js';
 import { type ConcurrencyConfig, type ConcurrencyQuota } from './concurrency.js';
 import { type EntityConfig } from './entities.js';
 import { type EventBatchConfig } from './event-accumulators.js';
+import { type OnEventEntry } from './events.js';
 import { type AnnouncedWorkflow } from './handshake/announced.js';
 import { type WorkflowDirectory } from './handshake/directory.js';
 import type { ControlPlane, EngineListener, GroupHealth, NamedTransport, RunDispatch, RunDispatcher, RunFacetQuery, RunFacetRow, RunQuery, RunResult, RunScope, RunStatus, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScopedRetentionPolicy, SearchAttributes, SearchAttributesSchema, SignalWaiter, StateStore, StepCheckpoint, StepError, StepInterceptor, Transport, UpdateResult, UpdateValidator, WorkflowCtx, WorkflowExecutor, WorkflowRun } from './interfaces.js';
+import { type LifecycleKind, type RepublishLifecycleResult, type RepublishLifecycleTarget, type WorkflowLifecycleLinks } from './lifecycle-events.js';
 import { type OnErrorRoute } from './on-error.js';
 import { ORIGIN_RESOLVED } from './origin.js';
 import { type StepHandler } from './protocol.js';
@@ -358,6 +360,25 @@ export interface WorkflowEngineDeps {
      * run `runPending` on a worker pod to pick those up; or a broker-backed one for a worker pool.
      */
     runDispatcher?: RunDispatcher | undefined;
+    /**
+     * How many parked workflow bodies this instance keeps in memory between turns (the sticky
+     * continuation cache, see `sticky-continuation.ts`). A run whose body parked here on dispatched
+     * `ctx.step` calls continues from where it stopped when its next turn runs on this instance,
+     * instead of replaying from the top over its whole history: the turn re-reads only the steps it
+     * parked on. Least recently used out first; an evicted run just replays. Default 2000. `0` turns
+     * the cache off (every turn replays).
+     */
+    stickyRuns?: number | undefined;
+    /** How long a parked body may sit idle in the sticky cache before it is dropped. Default 5 min. */
+    stickyIdleMs?: number | undefined;
+    /**
+     * Ask the transports that can ({@link Transport.consumeRepliesFor}, e.g. BullMQ) to send the result
+     * of a dispatched `ctx.step` back to this instance, which holds the body parked on it, rather than
+     * to whichever engine instance takes it off the shared results. With several engine instances,
+     * that is what keeps the sticky continuation hitting. A result whose instance is gone goes to the
+     * shared results and replays elsewhere. Default `true` while the sticky cache is on.
+     */
+    routeReplies?: boolean | undefined;
     /**
      * Capabilities the control-plane itself advertises in its handshake descriptor (design §7.3). The
      * CP is a router, not an executor, so this is rarely needed — leave empty. Never gates which workers
@@ -438,6 +459,16 @@ export declare class WorkflowEngine {
     private readonly maxRecoveryAttempts?;
     private readonly unregisteredWorkflowGraceMs;
     private readonly reconcileMs;
+    /** Parked workflow bodies kept between turns (see {@link WorkflowEngineDeps.stickyRuns}). */
+    private readonly sticky;
+    /** Pending runs claimed by {@link runPending} for the turn about to run them, as read by the claim. */
+    private readonly claimedRuns;
+    /** The continuation each turn executing here runs in, by run id, while the turn runs. */
+    private readonly turnContinuations;
+    /** Whether a transport routes this instance's step results back to it (see `routeReplies`). */
+    private repliesRouted;
+    /** The run row stamp (`updatedAt`, epoch ms) a turn here wrote when it settled `suspended`. */
+    private readonly suspendStamps;
     private readonly heartbeatPersistThrottleMs;
     private readonly timerBatchSize;
     private readonly eventBufferTtlMs;
@@ -481,7 +512,7 @@ export declare class WorkflowEngine {
     private readonly workflows;
     /** The newest registered version per workflow name — used to `start` new runs. */
     private readonly latest;
-    /** Event name → workflow names started when that event is published (see `onEvent`). */
+    /** Event name → subscribing workflow name → that workflow's subscriptions to it. See `onEvent`. */
     private readonly eventTriggers;
     /** Durable-entity subsystem (registers the `__entity` runner; see `registerEntity`). */
     private readonly entities;
@@ -757,7 +788,7 @@ export declare class WorkflowEngine {
         inputSchema?: StandardSchemaV1 | undefined;
         /** Typed/validated `searchAttributes` shape — see `RegisteredWorkflow.searchAttributesSchema`. */
         searchAttributesSchema?: SearchAttributesSchema | undefined;
-        onEvent?: string[] | undefined;
+        onEvent?: OnEventEntry[] | undefined;
         eventBatch?: EventBatchConfig | undefined;
         requires?: string[] | undefined;
         /**
@@ -921,9 +952,336 @@ export declare class WorkflowEngine {
      * that itself goes dead is not routed again — no `dlq:dlq:…` chain.
      */
     private routeDeadLetter;
-    /** Emit a locally-produced lifecycle event: deliver to subscribers AND broadcast it on the
-     *  control plane so other instances (e.g. a dashboard pod) can live-tail this run. */
+    /**
+     * Emit a locally-produced lifecycle event: deliver to subscribers AND broadcast it on the control
+     * plane so other instances (e.g. a dashboard pod) can live-tail this run. A `run.completed` or
+     * `run.failed` also wakes the `ctx.waitForRun` waiters on the run and publishes its lifecycle
+     * event (see {@link publishLifecycle}); `lifecycle: false` marks a `run.completed` that is not a
+     * real completion (a continue-as-new handoff), which publishes no lifecycle event.
+     */
     private emit;
+    /**
+     * Start every workflow subscribed to `name` that takes `payload` (see {@link acceptingSubscription}),
+     * each under `runIdOf(workflow)` and with its subscription's `input` applied; only the ones in
+     * `only` when given. Returns the subscribers reached, with the run each started (none when the
+     * payload went into its debounce/batch accumulator) and whether that run is new, and the ones that
+     * could not be started, with why.
+     *
+     * `remote` names subscribers known only from the fleet's announcements (see
+     * {@link announcedRemoteSubscribers}): each is started by name with the payload as its input, with
+     * no `where` or `input` mapping, unless it is also registered here.
+     */
+    private startSubscribers;
+    /** The workflows registered on this instance that subscribe to `event`. */
+    private localSubscribers;
+    /**
+     * Whether this engine's own subscribers are owed the lifecycle events of `namespace`'s runs: always
+     * for an engine with no namespace (its sweep reads every namespace's runs), else only its own
+     * namespace's. `undefined` asks without a namespace and is always true.
+     */
+    private servesNamespace;
+    /** The workflows registered here that subscribe to `event` and serve `namespace`'s runs. */
+    private localSubscribersFor;
+    /**
+     * The subscribers of `event` this engine starts by name although it has no `onEvent` for them:
+     * announced only by non-Node workers (a Python `@worker.workflow(..., on_workflow_completed=...)`),
+     * and reachable from here, either registered (`registerRemote`) or served by convention on a live
+     * worker group of the same name. A subscriber some Node engine announces is left to that engine,
+     * which applies its own `where` and `input`; one this engine cannot reach stays owed, for an
+     * instance that can. Read from the snapshot {@link announcedSubscribers} keeps. With `namespace`,
+     * only the subscriptions announced for that namespace's runs (see {@link announcedFor}).
+     */
+    private announcedRemoteSubscribers;
+    /**
+     * The subscribers of `event` this engine can deliver to for a run of `namespace`: the ones
+     * registered here that serve it, and the announced ones it starts by name (see
+     * {@link announcedRemoteSubscribers}).
+     */
+    private deliverableSubscribers;
+    /**
+     * Every workflow a run of `workflow` settling as `kind` owes its lifecycle event to: the ones
+     * registered here plus the ones the fleet announces (from a snapshot of the lifecycle subscription
+     * registry and the worker descriptors at most 5s old), sorted.
+     *
+     * With `namespace` (the settled run's), only the subscribers that serve that namespace's runs: the
+     * ones registered here when this engine has no namespace or has that one, the registry rows of
+     * engines in that namespace or with none, and the worker descriptors serving it. What the
+     * terminal status write marks the run owed to.
+     */
+    lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace?: string | undefined): string[];
+    /**
+     * Who starts whom through lifecycle events, for `workflow`: the workflows that start when it
+     * settles, and the workflows whose settling starts it. Built from this engine's registry and the
+     * subscriptions live workers announce (read again when the snapshot is older than 5s); a failed
+     * fleet read leaves the local registry alone. What the dashboard's workflow page shows.
+     *
+     * With `namespace`, only the subscriptions of that namespace: the ones announced by registry runs
+     * and worker descriptors serving it, and this engine's own when it is that namespace's engine (an
+     * engine with no namespace is `default`'s). What a tenant is shown.
+     */
+    workflowLifecycle(workflow: string, opts?: {
+        namespace?: string | undefined;
+    }): Promise<WorkflowLifecycleLinks>;
+    /**
+     * `patch` (a terminal status write of `run`) plus the {@link LIFECYCLE_PENDING_TAG} marker and one
+     * {@link LIFECYCLE_OWED_TAG_PREFIX} tag per subscriber of that ending, and the run's span as a
+     * {@link LIFECYCLE_TRACE_TAG_PREFIX} tag when a run trace provider knows it. Written in the same
+     * update as the status, so a run can never be settled without a record of whom its lifecycle event
+     * is owed to.
+     *
+     * While this instance has no successful read of the fleet's announced subscriptions (none yet, or
+     * the last one failed), it cannot know who else subscribes, so the marker is the pending tag alone:
+     * the run's owed set is unresolved, and the publish that next reads the fleet resolves it (see
+     * {@link publishSettled}). Never waits on that read.
+     */
+    private withLifecycleMarker;
+    /** Answers the traceparent of a run's span in this process; see {@link setRunTraceparent}. */
+    private runTraceparent;
+    /**
+     * Install the function that answers the W3C `traceparent` of a run's span in this process, or
+     * `undefined` to remove it. `attachDurableOtel` installs one. With it, a run some workflow
+     * subscribes to records its traceparent (a {@link LIFECYCLE_TRACE_TAG_PREFIX} tag) with its first
+     * suspend (see {@link withRunTrace}), or else with its terminal write, and the `run.started` of a
+     * run a lifecycle event started carries its source run's as `sourceTraceparent`, so the
+     * subscriber's trace links to the source's whichever process ran either.
+     */
+    setRunTraceparent(provider: ((runId: string) => string | undefined) | undefined): void;
+    /**
+     * `patch` (a suspend write of `run`) plus the run's {@link LIFECYCLE_TRACE_TAG_PREFIX} tag, when a
+     * run trace provider is installed (see {@link setRunTraceparent}), some workflow subscribes to the
+     * run's ending, the provider answers for the run and the run does not carry the tag yet. The first
+     * turn's suspend records the run's root span this way, so a run that settles in a process that
+     * never saw its first turn still links its subscribers' traces; a workflow nobody subscribes to
+     * gets no tag and no extra read or write. The tags are read again before they are written, so a
+     * tag the turn added is kept.
+     */
+    private withRunTrace;
+    /**
+     * `{ sourceTraceparent }` for the `run.started` of `run`, when a lifecycle event started it and a
+     * run trace provider is installed: the source run's recorded traceparent, else this process's.
+     */
+    private sourceTraceOf;
+    /** How many registry rows one page of a read of the lifecycle subscription registry lists. */
+    private static readonly LIFECYCLE_REGISTRY_PAGE_SIZE;
+    /** How long a read of the subscriptions the fleet announces is reused. */
+    private static readonly ANNOUNCED_SUBSCRIPTIONS_TTL_MS;
+    /** The last read of the fleet's announced subscriptions; see {@link announcedSubscribers}. */
+    private announcedSubscriptionsSnapshot;
+    private announcedSubscriptionsRead;
+    /**
+     * The workflows the fleet announces as subscribers of `event`: the live rows of the lifecycle
+     * subscription registry (see {@link LIFECYCLE_REGISTRY_WORKFLOW}) and the live worker descriptors'
+     * `registrations[].subscribes`, from a snapshot refreshed in the background once it is older than
+     * {@link ANNOUNCED_SUBSCRIPTIONS_TTL_MS}. Synchronous, so a terminal status write never waits on
+     * the fleet; before the first read completes it answers with nothing.
+     */
+    private announcedSubscribers;
+    /**
+     * The subscribers of `event` in the current snapshot that serve `namespace`'s runs: announced for
+     * that namespace, or by an engine with no namespace (see {@link LifecycleRegistryEntry}). Every
+     * announced subscriber when `namespace` is undefined. `node` keeps only the ones Node engines
+     * announce (registry rows and Node worker descriptors), which start their own subscribers.
+     */
+    private announcedFor;
+    /**
+     * Read the fleet's announced subscriptions into the snapshot: the registry rows whose heartbeat
+     * is at most {@link LIFECYCLE_REGISTRY_TTL_MS} old (a range of the store's `created_at` index, read
+     * page by page until a short page, so a large fleet is never cut off), and
+     * the worker descriptors on a transport that can read them fleet-wide. Never throws: a failed read
+     * of either leaves an empty snapshot marked not `ok`, which counts as the local registry only and
+     * never orphans a subscriber. Concurrent callers share one read.
+     */
+    private refreshAnnouncedSubscriptions;
+    /** Read the fleet's announced subscriptions again when the snapshot is older than the TTL. */
+    private freshAnnouncedSubscriptions;
+    /** When this engine last wrote its registry row; see {@link heartbeatLifecycleRegistry}. */
+    private lifecycleRegistryBeatAt;
+    /** When this engine last deleted stale registry rows; undefined before its first pass. */
+    private lifecycleRegistryCleanedAt;
+    /** How often an engine with a registry row looks for stale rows to delete. */
+    private static readonly LIFECYCLE_REGISTRY_CLEANUP_MS;
+    /**
+     * This engine's lifecycle registry entry: each workflow registered here that subscribes to an
+     * event, with the events it subscribes to. Undefined when none does.
+     */
+    private lifecycleRegistryEntry;
+    /**
+     * Write this engine's row of the lifecycle subscription registry (see
+     * {@link LIFECYCLE_REGISTRY_WORKFLOW}), at most once per {@link LIFECYCLE_REGISTRY_HEARTBEAT_MS}:
+     * an update of the existing row, or a create when it is missing (first beat, or deleted as stale
+     * after a long pause). Once a minute it also deletes rows whose heartbeat stopped
+     * {@link LIFECYCLE_REGISTRY_STALE_MS} ago: the ones that went stale in the last
+     * {@link LIFECYCLE_REGISTRY_STALE_MS}, a bounded range of the `created_at` index, and on its first
+     * pass every stale row, for the ones left while no engine ran. The row is created tagged
+     * {@link LIFECYCLE_REGISTRY_TAG}, which retention keeps. A no-op for an engine without
+     * subscriptions. Its store calls are marked as heartbeats for observability tools. Never throws.
+     */
+    heartbeatLifecycleRegistry(): Promise<void>;
+    /**
+     * The runs started by `runId` settling (see {@link publishLifecycle}), read from the run's own
+     * tags, so it needs no subscriber registry. Empty for a run that has not settled or started
+     * nobody. Pass the run itself when it is already loaded, to skip reading it again.
+     */
+    triggeredRuns(source: string | WorkflowRun): Promise<string[]>;
+    /** The live path of {@link publishSettled}: right after this instance settled the run. */
+    private publishLifecycle;
+    /**
+     * Take the run lease for this instance's turn, as `tryLockRun` at `nowMs`; when the lease is held
+     * by a lifecycle publish (see {@link withLifecycleLease}), which only ever holds a settled run for
+     * the length of its publish (an explicit retry can land in it), wait for that publish to let go,
+     * at most `leaseMs`.
+     */
+    private lockRunPastLifecyclePublish;
+    /** The waits between attempts to take a settled run's lifecycle lease (see {@link withLifecycleLease}). */
+    private static readonly LIFECYCLE_LEASE_RETRY_MS;
+    /**
+     * Run `fn` holding the run lease of the settled run `runId` under an owner unique to this call, so
+     * every read-start-write of a run's lifecycle tags (live publish, sweeps, heal, republish, on any
+     * instance or twice in this one) runs one at a time. A refused lease is asked for again after each
+     * of {@link LIFECYCLE_LEASE_RETRY_MS}; still refused, resolves `{ acquired: false }` without
+     * running `fn`. The lease is released when `fn` settles, and expires after `leaseMs` if this
+     * process dies first.
+     */
+    private withLifecycleLease;
+    /**
+     * Publish a settled run's lifecycle event (`run.completed:<workflow>` / `run.failed:<workflow>`)
+     * to the subscribers it owes it to that this instance can deliver to (registered here, or announced
+     * and started by name; see {@link deliverableSubscribers}), and settle their part of the marker:
+     * drop each one's {@link LIFECYCLE_OWED_TAG_PREFIX} tag, record each started one as a
+     * `durable:triggered:<workflow>` tag (a coalescing one as `durable:coalesced:<workflow>`), and drop
+     * {@link LIFECYCLE_PENDING_TAG} once no owed tag is left.
+     *
+     * A run marked pending with no owed tag has an unresolved owed set (see
+     * {@link LIFECYCLE_PENDING_TAG}). With a successful read of the fleet's subscriptions it is resolved
+     * here: every subscriber of the ending (see {@link lifecycleSubscribers}) the run's tags do not
+     * record as started or failed becomes owed, and the ones nobody here delivers to keep an owed tag.
+     * Without one, the subscribers registered here are started and the run stays unresolved.
+     *
+     * `republish` publishes to every subscriber of the ending (or only `subscriber`, which must be one),
+     * owed or not: the ones this instance can deliver to are started, and the others are marked owed
+     * again (with the pending tag) for the sweep of an instance that can. `heal` names subscribers of
+     * the ending the run was never marked for (see {@link healLifecycleEvents}): they are owed now, and
+     * the ones this instance delivers to are started.
+     * `nowMs` (the sweep's clock) also drops the owed tag of a subscriber that is neither registered
+     * here nor announced by a live worker once the run settled {@link LIFECYCLE_ORPHAN_MS} ago,
+     * reporting it as `run.trigger_failed`.
+     *
+     * Runs under the run's lifecycle lease (see {@link withLifecycleLease}) and reads the run again
+     * under it, so concurrent publishers never overwrite each other's tags; `busy` when the lease
+     * stayed taken. Idempotent, since every subscriber run id is deterministic and a debounce/batch
+     * accumulator drops an event it already holds. A subscriber whose `where` throws, whose input is
+     * rejected or whose start fails, and an orphan the sweep drops, gets a
+     * {@link LIFECYCLE_TRIGGER_FAILED_TAG_PREFIX} tag in the same tag write, and is not retried until a
+     * republish; the write that records a subscriber reached removes its trigger-failed tag.
+     * A debounce/batch subscriber routed into its accumulator gets a
+     * {@link LIFECYCLE_COALESCED_TAG_PREFIX} tag in the same write instead of a triggered one; a
+     * republish routes it again only when the run also carries its trigger-failed tag.
+     * `run.triggered` and `run.trigger_failed` are emitted only for the subscribers whose triggered,
+     * coalesced or trigger-failed tag this write added. A failure to write the marker leaves it, and
+     * the sweep publishes the run again.
+     */
+    private publishSettled;
+    /** {@link publishSettled} once it holds the run's lifecycle lease and has read `run` under it. */
+    private publishSettledLeased;
+    /**
+     * The subscribers `run` owes its event to that nothing can deliver it to: not in `here` (what
+     * this instance delivers to), announced by no live worker, and owed since
+     * {@link LIFECYCLE_ORPHAN_MS} or longer. Empty while the fleet's announcements cannot be read,
+     * since then nobody is known to be gone.
+     */
+    private orphanedSubscribers;
+    /** How long a settled run's marker is left to the live publish before the sweep takes it over. */
+    private static readonly LIFECYCLE_SWEEP_GRACE_MS;
+    /** How many marked runs one lifecycle sweep reads at most, looking for ones it can act on. */
+    private static readonly LIFECYCLE_SWEEP_SCAN_CAP;
+    /**
+     * Publish the lifecycle event of settled runs still marked {@link LIFECYCLE_PENDING_TAG} to the
+     * subscribers this instance can deliver to that they still owe it to: a run whose settling process
+     * died, or whose marker write failed, before publishing, or whose subscriber is registered only on
+     * other instances. Also writes this instance's row of the lifecycle subscription registry (see
+     * {@link heartbeatLifecycleRegistry}), refreshes the snapshot of the subscriptions the fleet
+     * announces (registry rows and worker descriptors), drops
+     * owed subscribers nothing can deliver to (see {@link orphanedSubscribers}) and wakes the
+     * `ctx.waitForRun` waiters whose run already settled (see {@link sweepRunWaits}).
+     *
+     * Called by the worker poll loop. Reads the marked runs page by page and skips the ones it cannot
+     * act on (every owed subscriber is delivered elsewhere and none is orphaned yet), so runs owed only
+     * to other instances never hide the ones it can publish. Stops once it has published `limit` runs
+     * or read {@link LIFECYCLE_SWEEP_SCAN_CAP} marked runs. A run settled in the last
+     * {@link LIFECYCLE_SWEEP_GRACE_MS} is left to the live publish; a run another publisher holds
+     * (see {@link withLifecycleLease}) is left to the next tick. Then heals the runs settled in the
+     * last {@link LIFECYCLE_HEAL_WINDOW_MS} (see {@link healLifecycleEvents}). Returns how many marked
+     * runs it published plus how many waiters it woke; healed runs are not counted.
+     */
+    sweepLifecycleEvents(nowMs?: number, limit?: number): Promise<number>;
+    /** How many settled runs of one source workflow a heal pass reads at most. */
+    private static readonly LIFECYCLE_HEAL_SCAN_CAP;
+    /**
+     * The (run, subscriber) pairs this engine already healed, with when each entry lapses (epoch ms):
+     * a subscriber whose `where` declines the event leaves no tag, so without it every sweep would
+     * offer it the event again for the whole heal window.
+     */
+    private readonly lifecycleHealed;
+    /**
+     * Deliver lifecycle events the terminal write never marked: for every source workflow some
+     * subscriber in the current snapshot of the fleet's subscriptions (or registered here) listens to,
+     * read its runs settled in the last {@link LIFECYCLE_HEAL_WINDOW_MS} (at most
+     * {@link LIFECYCLE_HEAL_SCAN_CAP}, one listing per workflow) and publish each one to the
+     * subscribers of its ending its tags record as neither owed, started, coalesced nor failed (see
+     * {@link publishSettled}'s `heal`). That covers a subscriber announced just after the run
+     * settled, while the settling instance's snapshot was stale. Each pair is healed at most once per
+     * engine. A run whose owed set is unresolved is left to {@link sweepLifecycleEvents}. Needs a
+     * successful read of the fleet's subscriptions; returns how many runs it published.
+     */
+    private healLifecycleEvents;
+    /**
+     * Up to `limit` settled runs marked {@link LIFECYCLE_PENDING_TAG}, past the sweep grace, that this
+     * instance can act on: a run owing its event to a subscriber it delivers to, a run marked without
+     * owed tags, or a run owing it to a subscriber nothing delivers to past
+     * {@link LIFECYCLE_ORPHAN_MS}. Reads at most {@link LIFECYCLE_SWEEP_SCAN_CAP} marked runs, in
+     * pages, all read before any is acted on, since publishing a run takes it out of the listing.
+     */
+    private lifecycleActionableRuns;
+    /**
+     * Publish settled runs' lifecycle events again, whether or not they are still marked: one run
+     * (`{ runId }`), or a workflow's settled runs (`{ workflow, kind, since, until, limit }`, read in
+     * pages of the store's listing, filtered by when the run settled). `subscriber` restricts it to
+     * one subscribing workflow, which must subscribe to the run's ending (registered here or announced
+     * by a live worker for the run's namespace): otherwise the run is reported in `failed` with
+     * `subscriber <name> does not subscribe to <event>` and nothing is marked. The subscribers
+     * registered on this instance are started; any other (announced by a live worker) is marked owed
+     * again, so the sweep of an instance that registers it starts it, and is not counted in
+     * `started`. The same path as the live publish, so a subscriber whose run already exists is not
+     * started again; a subscriber that debounces or batches is not routed again once the run carries
+     * its coalesced tag, unless it also carries its trigger-failed tag, since an accumulator that
+     * already fired would start the target again. A run another
+     * publisher holds past the lease retries is reported in `failed` with subscriber `*`. A
+     * subscriber registered after the runs settled (more than {@link LIFECYCLE_HEAL_WINDOW_MS} after,
+     * past what the sweep heals) is backfilled this way. A workflow target's `namespace` narrows it to
+     * that namespace; on an engine bound to another namespace it publishes nothing.
+     */
+    republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
+    /**
+     * Wake the `ctx.waitForRun` waiters on `runId`, which just settled, and on the earlier runs of its
+     * continue-as-new chain, with the event of the run that ends the chain (none yet when `runId`
+     * handed off). One waiter listing per settle. Best effort: a waiter missed here (this process dies
+     * first) is woken by {@link sweepRunWaits}. Internal `__` runs have no waiters, so they are
+     * skipped without a read.
+     */
+    private notifyRunWaiters;
+    /** How many waited-on runs one {@link sweepRunWaits} reads at most. */
+    private static readonly RUN_WAIT_SWEEP_SCAN_CAP;
+    /** Where the next {@link sweepRunWaits} starts in the list of waited-on runs. */
+    private runWaitSweepCursor;
+    /**
+     * Wake the `ctx.waitForRun` waiters (up to `limit`) whose run, or the run ending its
+     * continue-as-new chain, has already settled: the recovery for a process that died between
+     * settling a run and waking its waiters. Waiters on runs still in flight are skipped, reading at
+     * most {@link RUN_WAIT_SWEEP_SCAN_CAP} waited-on runs per call; the next call starts where this one
+     * stopped, so waiters on long-running runs never hide the ones that can be woken. Returns how many
+     * it woke.
+     */
+    sweepRunWaits(limit?: number): Promise<number>;
     /** Events waiting for the control-plane publish in flight, in emit order (see {@link broadcastEvents}). */
     private readonly eventsToBroadcast;
     private broadcastingEvents;
@@ -999,6 +1357,21 @@ export declare class WorkflowEngine {
      * instead of the whole history, and carries an `etag` that `options.ifNoneMatch` can match.
      */
     getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
+    /**
+     * What a run detail reads beyond the run row and its checkpoints: the subscribers its lifecycle
+     * event goes to (of its namespace) and where it stands for each, its workflow's lifecycle links,
+     * and the `ctx.waitForRun` waits on either side of it with the other run's status. A few reads per
+     * detail: the run's own waiters while it is suspended, the waiters on it (one prefix read), and
+     * one batched read of every linked run.
+     */
+    private lifecycleDetail;
+    /**
+     * The subscribers registered here that coalesce `run`'s lifecycle event (debounce/batch) and
+     * accept it, each with the accumulator run the event went to: the subscription's `where`, `input`
+     * and `key` applied to the event as `startSubscribers` does. Undefined when the key cannot be
+     * computed. A subscriber whose `where` declines the event is left out.
+     */
+    private coalescedSubscribers;
     /** One page of a summarized fan's members (see `loadFanMembers`), versioned like {@link getRunDetail}. */
     getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
     private detailSource;
@@ -1149,6 +1522,7 @@ export declare class WorkflowEngine {
     /** Drop `gate` once `tail` settles, unless another execution queued behind it meanwhile. */
     private closeGateAfter;
     private resumeRunNow;
+    private resumeLoadedRun;
     /**
      * Deferred re-drive after a suspended settle whose waited checkpoint(s) already settled — the
      * delivery's own resume no-oped against this turn's still-held lease (see the WorkflowSuspended
@@ -1413,6 +1787,12 @@ export declare class WorkflowEngine {
      * {@link resumeDueTimers}.
      */
     runPending(nowMs?: number): Promise<RunResult[]>;
+    /**
+     * Run `claimed` (pending runs this instance just leased, read as locked): every turn starts at
+     * once, and each re-enters the lease taken for it without reading the run again. A run this
+     * instance cannot resume is skipped and logged, as {@link resumeLeased} does; its lease lapses.
+     */
+    private runClaimed;
     /**
      * Resolve once `runId` reaches a settled state — terminal (completed/failed/cancelled/dead) or
      * suspended (handed off to a timer/signal/event). The async counterpart to dispatch: pair it with
@@ -1449,7 +1829,9 @@ export declare class WorkflowEngine {
      *     match the payload satisfies (fan-out, vs `signal`'s point-to-point token).
      *  2. **Starts** a fresh run of every workflow registered with `onEvent: [name]`, passing the
      *     payload as input. Idempotent by `evt:<id>:<workflow>` — pass `opts.id` to dedupe redeliveries
-     *     of the same logical event (default: a fresh uuid, so each publish triggers once).
+     *     of the same logical event (default: a fresh uuid, so each publish triggers once). A workflow
+     *     a non-Node worker announces as subscribing to `name` (a Python `on_event=[...]`) is started
+     *     the same way, by name, when this engine can reach it (see {@link announcedRemoteSubscribers}).
      *
      * Reliable (buffered) delivery — mirrors `signalWithStart`'s reliability contract, so document it
      * exactly: a publish that resumes ≥1 live waiter, OR routes into an `eventBatch` accumulator /
@@ -1804,7 +2186,8 @@ export declare class WorkflowEngine {
      * settled it), so report what is persisted rather than writing over it.
      */
     /**
-     * A run's first execution: `pending` -> `running`. A singleton run not yet admitted is stamped
+     * A run's first execution: `pending` -> `running`, resolving whether it moved it (a run cancelled
+     * or deleted since it was read did not move). A singleton run not yet admitted is stamped
      * {@link SINGLETON_TRACKED_TAG} in the same write, BEFORE it competes for a slot, so a run this
      * replica is about to admit or deny is never mistaken for a holder admitted by a replica older than
      * 0.51 (see `legacySingletonHolders`).
@@ -2109,6 +2492,13 @@ export declare class WorkflowEngine {
      *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
     private dueBlockedRuns;
     private callRemote;
+    /**
+     * {@link callRemote}'s first dispatch of a step, written with
+     * {@link StateStore.insertCheckpointIfAbsent}: resolves whether it wrote the `pending` row and
+     * dispatched. `false` when the position already has a row, or when no live worker can take the
+     * step (the read-first path then decides, so a step that is in fact done is never blocked).
+     */
+    private dispatchIfAbsent;
     /**
      * `ctx.all` over a `@Step`: one durable step per input, dispatched together, joined once. The ctx
      * reserves the whole position block up front, so replay re-derives the same seqs.
@@ -2148,6 +2538,27 @@ export declare class WorkflowEngine {
      * {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable.
      */
     private dispatchRemoteTask;
+    /**
+     * Whether this turn of `run` may run in a sticky continuation (see `sticky-continuation.ts`). Not
+     * while the engine drains, nor with a compensating cancel requested for the run.
+     */
+    private stickyEligible;
+    /**
+     * The continuation this instance parked for `run`, if it is still the run's latest turn: the run
+     * is `suspended` with the very stamp this instance's suspend wrote, on the same body and version.
+     * Any other settle in between (another instance's turn, a retry, a cancel) changed the stamp, and
+     * the run replays instead. Taking it removes it from the cache.
+     */
+    private takeContinuation;
+    /** Keep `cont` (parked, detached) for the run's next turn here, stamped with its suspend write. */
+    private keepContinuation;
+    /**
+     * The checkpoints of the steps `cont` is parked on, as a replay would see them: in one read when
+     * the store batches, and without the input of a step that completed (what
+     * {@link StateStore.getCheckpointsForSettle} leaves out). A step still open or failed is read
+     * whole, since a re-dispatch or a retry sends its input again.
+     */
+    private readParked;
     /** A turn's read of its run's checkpoints: {@link StateStore.listCheckpointsForReplay}, or every
      *  column through {@link StateStore.listCheckpoints} on a store without it. */
     private replayCheckpoints;
@@ -2258,6 +2669,15 @@ export declare class WorkflowEngine {
      * replays every write of the batch, so a second would only replay it again.
      */
     private completeRemoteResults;
+    /**
+     * {@link completeRemoteResults} on a store with {@link StateStore.settleResultsIfPending}: the
+     * results settle their `pending` rows and read them back, with their run's status, in one call,
+     * instead of reading the rows and the run and then writing. An entry that settled nothing (a
+     * redelivery, a step gone, a late result for a finished run) takes the single-result path, which
+     * reads first and re-drives, drops or salvages. A settled `completed` row is also handed to the
+     * run's parked body, if this instance holds one, so its next turn does not read it again.
+     */
+    private settleResultsReturning;
     /**
      * Settle pending steps, each only while its row is still `pending`; per entry, whether it wrote
      * or the error that kept it from writing. Through {@link StateStore.settleCheckpointsIfPending}