@adonis-agora/durable 0.9.1 → 0.11.0

package/dist/src/worker-runtime/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/naming.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEnG;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEhG;AAED,qGAAqG;AACrG,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/src/worker-runtime/naming.js

@@ -0,0 +1,28 @@
+import { effectivePrefix, routingToken, workerHeartbeatKey } from '../transports/bullmq/naming.js';
+/**
+ * Broker key naming for the store-less {@link import('./worker-runtime.js').WorkerRuntime}'s two-tier
+ * advertisement (design §6.2 / §7.2). Built ON TOP of the wave-1 aviary-compatible
+ * `transports/bullmq/naming` so the worker-liveness + descriptor keys stay byte-identical across the
+ * fleet (a Python worker / NestJS control-plane computes the same names). Pure string builders — no
+ * Redis, no bullmq, no Lucid — so the worker subpath stays lean and the names unit-test in isolation.
+ *
+ * Re-exported here (rather than re-derived) so a caller in the worker subpath never has to reach into
+ * the bullmq transport package for the shared sanitize/prefix/token rules.
+ */
+export { effectivePrefix, routingToken, workerHeartbeatKey };
+/**
+ * `${P}-worker-descriptor:${token}:${instanceId}` — the full {@link WorkerDescriptor} key (design
+ * §6.2). One key per (routing token, instance): the worker publishes its whole descriptor under EACH
+ * routing token it serves, mirroring the per-token `${P}-worker-heartbeat:` liveness key so a
+ * control-plane scanning a token's keyspace finds both the compact heartbeat (with the ETag) and, when
+ * the ETag changed, the rich descriptor to re-read. Neither `token` nor `instanceId` carries a `:`, so
+ * the segments parse unambiguously — identical to {@link workerHeartbeatKey}'s layout.
+ */
+export function workerDescriptorKey(effPrefix, token, instanceId) {
+    return `${effPrefix}-worker-descriptor:${token}:${instanceId}`;
+}
+/** Common prefix of every worker-descriptor key (for a control-plane SCAN over live descriptors). */
+export function workerDescriptorKeyPrefix(effPrefix) {
+    return `${effPrefix}-worker-descriptor:`;
+}
+//# sourceMappingURL=naming.js.map

package/dist/src/worker-runtime/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../../src/worker-runtime/naming.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEnG;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,KAAa,EAAE,UAAkB;IACtF,OAAO,GAAG,SAAS,sBAAsB,KAAK,IAAI,UAAU,EAAE,CAAC;AACjE,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,yBAAyB,CAAC,SAAiB;IACzD,OAAO,GAAG,SAAS,qBAAqB,CAAC;AAC3C,CAAC"}

package/dist/src/worker-runtime/registry.d.ts

@@ -0,0 +1,81 @@
+import type { HeartbeatStatus, WorkerDescriptor } from '../handshake/descriptor.js';
+/**
+ * The advertisement side of the store-less worker handshake (design §7.2): a thin writer the
+ * {@link import('./worker-runtime.js').WorkerRuntime} pushes its descriptor + compact heartbeat
+ * through. Kept behind this interface so the runtime is transport-AND-backend agnostic — a test proves
+ * advertisement against a fake, a real pod passes a {@link RedisWorkerRegistry}, and the runtime itself
+ * imports no Redis client (keeping the worker subpath lean).
+ */
+export interface WorkerRegistry {
+    /**
+     * Publish the FULL {@link WorkerDescriptor} for a routing token+instance (the `${P}-worker-descriptor`
+     * key). Re-called when the descriptor changes (new handler registered) and periodically to refresh
+     * its TTL. The `ttlSeconds` self-expires the key when the worker dies without a clean stop.
+     */
+    advertiseDescriptor(ad: {
+        key: string;
+        descriptor: WorkerDescriptor;
+        ttlSeconds: number;
+    }): Promise<void>;
+    /**
+     * Beat the compact two-tier heartbeat `{ ts, status, descriptorHash }` for a routing token+instance
+     * (the `${P}-worker-heartbeat` key), TTL'd so its absence is the "worker gone" signal. The
+     * `descriptorHash` is the ETag a control-plane watches to know when to re-read the full descriptor.
+     */
+    beat(beat: {
+        key: string;
+        status: HeartbeatStatus;
+        ttlSeconds: number;
+    }): Promise<void>;
+    /** Best-effort removal of this instance's keys on a clean stop (a graceful drain). Optional. */
+    remove?(keys: string[]): Promise<void>;
+    /** Release any owned connection on stop. Optional. */
+    close?(): Promise<void>;
+}
+/**
+ * A registry that advertises nothing — the default when a worker runs without a Redis backend (e.g. an
+ * in-process test transport, or before the tenant provider wires a real one). The runtime still BUILDS
+ * its descriptor + heartbeat (observable via {@link import('./worker-runtime.js').WorkerRuntime.descriptor});
+ * they simply aren't published anywhere.
+ */
+export declare class NoopWorkerRegistry implements WorkerRegistry {
+    advertiseDescriptor(): Promise<void>;
+    beat(): Promise<void>;
+}
+/**
+ * The minimal Redis surface {@link RedisWorkerRegistry} needs — a structural subset satisfied by an
+ * `ioredis` client AND by the bullmq transport's `RedisLike`, so either can be handed in without a hard
+ * `ioredis` import at the worker subpath's module load. `set(...'EX', ttl)` is exactly the SET…EX the
+ * aviary liveness-key scheme uses; `del`/`disconnect` are optional cleanup.
+ */
+export interface DescriptorRedis {
+    set(key: string, value: string, mode: 'EX', ttl: number): Promise<unknown> | unknown;
+    del?(...keys: string[]): Promise<unknown> | unknown;
+    disconnect?(): void;
+}
+/**
+ * Publishes the descriptor + heartbeat to Redis with `SET key value EX ttl` — the byte-compatible
+ * two-tier advertisement (design §7.2) a control-plane (or a Python/NestJS peer) reads off the shared
+ * Redis. The client is injected (never constructed here) so this class stays pure and the worker
+ * subpath pulls in no `ioredis` statically; a caller builds the client once (e.g. from the same
+ * connection its bullmq transport uses) and passes it in.
+ */
+export declare class RedisWorkerRegistry implements WorkerRegistry {
+    #private;
+    constructor(redis: DescriptorRedis, opts?: {
+        ownsConnection?: boolean;
+    });
+    advertiseDescriptor(ad: {
+        key: string;
+        descriptor: WorkerDescriptor;
+        ttlSeconds: number;
+    }): Promise<void>;
+    beat(beat: {
+        key: string;
+        status: HeartbeatStatus;
+        ttlSeconds: number;
+    }): Promise<void>;
+    remove(keys: string[]): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/worker-runtime/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEpF;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,EAAE;QACtB,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,gBAAgB,CAAC;QAC7B,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxF,gGAAgG;IAChG,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,sDAAsD;IACtD,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACjD,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrF,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACpD,UAAU,CAAC,IAAI,IAAI,CAAC;CACrB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,cAAc;;gBAI5C,KAAK,EAAE,eAAe,EAAE,IAAI,GAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAO;IAKrE,mBAAmB,CAAC,EAAE,EAAE;QAC5B,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,gBAAgB,CAAC;QAC7B,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIX,IAAI,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/src/worker-runtime/registry.js

@@ -0,0 +1,44 @@
+/**
+ * A registry that advertises nothing — the default when a worker runs without a Redis backend (e.g. an
+ * in-process test transport, or before the tenant provider wires a real one). The runtime still BUILDS
+ * its descriptor + heartbeat (observable via {@link import('./worker-runtime.js').WorkerRuntime.descriptor});
+ * they simply aren't published anywhere.
+ */
+export class NoopWorkerRegistry {
+    async advertiseDescriptor() {
+        /* no backend — nothing to publish */
+    }
+    async beat() {
+        /* no backend — nothing to publish */
+    }
+}
+/**
+ * Publishes the descriptor + heartbeat to Redis with `SET key value EX ttl` — the byte-compatible
+ * two-tier advertisement (design §7.2) a control-plane (or a Python/NestJS peer) reads off the shared
+ * Redis. The client is injected (never constructed here) so this class stays pure and the worker
+ * subpath pulls in no `ioredis` statically; a caller builds the client once (e.g. from the same
+ * connection its bullmq transport uses) and passes it in.
+ */
+export class RedisWorkerRegistry {
+    #redis;
+    #ownsConnection;
+    constructor(redis, opts = {}) {
+        this.#redis = redis;
+        this.#ownsConnection = opts.ownsConnection ?? false;
+    }
+    async advertiseDescriptor(ad) {
+        await this.#redis.set(ad.key, JSON.stringify(ad.descriptor), 'EX', ad.ttlSeconds);
+    }
+    async beat(beat) {
+        await this.#redis.set(beat.key, JSON.stringify(beat.status), 'EX', beat.ttlSeconds);
+    }
+    async remove(keys) {
+        if (keys.length > 0 && this.#redis.del)
+            await this.#redis.del(...keys);
+    }
+    async close() {
+        if (this.#ownsConnection)
+            this.#redis.disconnect?.();
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/worker-runtime/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/worker-runtime/registry.ts"],"names":[],"mappings":"AAgCA;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IAC7B,KAAK,CAAC,mBAAmB;QACvB,qCAAqC;IACvC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,qCAAqC;IACvC,CAAC;CACF;AAcD;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IACrB,MAAM,CAAkB;IACxB,eAAe,CAAU;IAElC,YAAY,KAAsB,EAAE,OAAqC,EAAE;QACzE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,cAAc,IAAI,KAAK,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAC,EAIzB;QACC,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC;IACpF,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAkE;QAC3E,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACtF,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAc;QACzB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG;YAAE,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,eAAe;YAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;IACvD,CAAC;CACF"}

package/dist/src/worker-runtime/worker-runtime.d.ts

@@ -0,0 +1,155 @@
+import { type WorkerDescriptor } from '../handshake/descriptor.js';
+import type { WorkflowStepEvent } from '../interfaces.js';
+import type { StepHandler } from '../protocol.js';
+import { type WorkflowBody, type WorkflowTurnHandler } from '../workflow-turn.js';
+import { type WorkerRegistry } from './registry.js';
+/**
+ * The bare worker surface the {@link WorkerRuntime} consumes tasks over — exactly `handle(name, fn)`
+ * (the wave-1 BullMQTransport / any `StepServer` satisfies it) plus an optional `close`. Typed this
+ * narrowly (not the full `Transport`) so the store-less runtime depends only on what it uses: the
+ * transport owns the consume→`runStepHandler`→publish-result loop; the runtime wires handlers onto it
+ * and advertises what it serves.
+ */
+export interface WorkerTransport {
+    /** Register a step handler → the transport subscribes `${P}-tasks-<token>` for it and, on a task,
+     *  runs it through the shared `protocol.ts runStepHandler` and publishes the {@link StepResult}. */
+    handle(name: string, fn: StepHandler): void;
+    /** Register a WORKFLOW turn consumer → the transport subscribes the workflow name's
+     *  `${P}-tasks-<token>` queue and, on a `workflow`-shaped job (discriminated by SHAPE, spec §6.3),
+     *  runs `turn(task)` (the replay → decision) and publishes the {@link WorkflowDecision} on
+     *  `${P}-decisions`. OPTIONAL — a transport that can't carry workflow tasks omits it, and the runtime
+     *  then only advertises the workflow name (routing/observability) without executing turns. */
+    handleWorkflow?(name: string, turn: WorkflowTurnHandler): void;
+    /** workflow worker → engine: stream a LOCAL step's lifecycle ({@link WorkflowStepEvent}) mid-turn so a
+     *  long inline turn's steps show live. OPTIONAL — only broker transports carry it; absent = no live
+     *  step streaming (the turn's final decision still records every step). */
+    dispatchStepEvent?(event: WorkflowStepEvent): Promise<void>;
+    /** Release the transport's broker workers/connections on stop. Optional (in-process transports omit it). */
+    close?(): Promise<void>;
+}
+/** Where the runtime narrates its lifecycle. Defaults to a silent logger. */
+export interface WorkerRuntimeLogger {
+    info(message: string): void;
+    error(message: string): void;
+}
+/** SDK identity stamped on the descriptor when the caller doesn't override it (observability only). */
+export declare const WORKER_SDK: {
+    readonly name: "@adonis-agora/durable";
+    readonly version: "0.9.0";
+};
+export interface WorkerRuntimeOptions {
+    /** The broker the worker consumes tasks over (wave-1 `BullMQTransport`, or any `handle`-able server). */
+    transport: WorkerTransport;
+    /** Which tenant/partition this pod serves — suffixes every routing token (`<name>@<partition>`) and
+     *  tags the descriptor. Required (a store-less worker always belongs to a partition). */
+    partition: string;
+    /** Deployment namespace segmenting every key/queue. Absent or `"default"` keeps names byte-identical. */
+    namespace?: string;
+    /** Key prefix namespacing the durable queues/keys. Default `durable`. */
+    prefix?: string;
+    /** Stable per-process id stamped on the liveness/descriptor keys. Default `ts-<host>-<pid>`. MUST
+     *  match the transport's instance id so the two-tier keys correlate. */
+    instanceId?: string;
+    /** SDK identity advertised in the descriptor (observability only; never gates dispatch). */
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    /** Extra advertised features beyond registered handler names (design §7.1 `capabilities`). */
+    capabilities?: string[];
+    /** Descriptor/heartbeat advertiser. Default {@link NoopWorkerRegistry} (descriptor still built +
+     *  observable via {@link WorkerRuntime.descriptor}, just not published). Pass a `RedisWorkerRegistry`
+     *  to advertise on the shared Redis. */
+    registry?: WorkerRegistry;
+    /** Worker-liveness beat cadence (ms). Default 10s (aviary `WORKER_HEARTBEAT_INTERVAL_MS`). */
+    heartbeatIntervalMs?: number;
+    /** TTL (s) on the descriptor + heartbeat keys. Default 35s (aviary `WORKER_HEARTBEAT_TTL_SECONDS`). */
+    ttlSeconds?: number;
+    /** Clock for the heartbeat `ts` (injectable for a deterministic test). Default `Date.now`. */
+    now?: () => number;
+    logger?: WorkerRuntimeLogger;
+    /** Where a background advertisement/beat failure is reported (best-effort — the key just expires). */
+    onError?: (err: unknown) => void;
+}
+/**
+ * A **store-less** worker runtime (design §4): it executes step bodies pulled off the transport and
+ * advertises what it can serve — and has, by construction, NO store field and imports NO Lucid (proven
+ * by the `no-lucid` structural test). It is deliberately NOT a store-optional engine: isolation is a
+ * structural fact, not a runtime `if (this.store)`.
+ *
+ * Responsibilities:
+ * - **Register handlers** — {@link registerStep} (also `handle`, so `step-discovery`'s
+ *   `registerStepsFromDir/Barrel` can target the runtime directly) forwards to `transport.handle`,
+ *   which subscribes `${P}-tasks-<token>` and runs each task through the shared `runStepHandler`,
+ *   publishing the result. Workflow NAMES ({@link registerWorkflowName}) populate the descriptor.
+ * - **Advertise** ({@link start}) — publishes the {@link WorkerDescriptor} to
+ *   `${P}-worker-descriptor:<token>:<instance>` and beats the compact `{ ts, status, descriptorHash }`
+ *   to `${P}-worker-heartbeat:<token>:<instance>` on a schedule (design §7.2 two-tier ETag scheme).
+ *
+ * It holds no store and reads none — every durable decision stays on the control-plane; this object
+ * only runs bodies and says who it is.
+ */
+export declare class WorkerRuntime {
+    #private;
+    constructor(options: WorkerRuntimeOptions);
+    /** Stable id stamped on this instance's liveness/descriptor keys. */
+    get instanceId(): string;
+    /** The step handler names this worker serves (sorted). */
+    get stepNames(): string[];
+    /** The workflow names this worker advertises (sorted). */
+    get workflowNames(): string[];
+    /**
+     * Register a step handler on the transport (which subscribes its `${P}-tasks-<token>` queue and runs
+     * each task through the shared `runStepHandler`) AND record its name for the descriptor. Named
+     * `handle` too so `step-discovery`'s `registerStep`/`registerStepsFromDir`/`registerStepsFromBarrel`
+     * can target the runtime directly (it satisfies their `StepServer`). Re-registering swaps the handler;
+     * if already {@link start}ed, the descriptor is re-advertised so the new name is routable.
+     */
+    handle(name: string, fn: StepHandler): void;
+    /** Alias of {@link handle} reading as intent at a call site that isn't the discovery `StepServer`. */
+    registerStep(name: string, fn: StepHandler): void;
+    /**
+     * Register a runnable WORKFLOW TURN body (`(ctx, input) => output`, written against the worker-side
+     * {@link import('../workflow-turn.js').WorkflowTurnCtx}) AND advertise its name. This is what lets a
+     * store-less TS worker EXECUTE workflow turns for parity with a Python worker (design §4): the
+     * transport subscribes the workflow's `${P}-tasks-<token>` queue and, on a `workflow`-shaped job, the
+     * turn is replayed via the shared {@link runWorkflowTurn} (deterministic history → decision) and the
+     * {@link import('../interfaces.js').WorkflowDecision} published on `${P}-decisions`. The worker never
+     * touches a store — every durable decision stays on the control-plane; this only replays the body.
+     *
+     * NOTE: this is the polyglot TURN surface (the TS twin of the Python `@workflow`), NOT the
+     * store-backed `BaseWorkflow`/`WorkflowCtx` the engine runs in-process — those are a different
+     * authoring surface (they own the store). Re-registering swaps the body; if the transport can't carry
+     * workflow tasks (`handleWorkflow` absent) the name is still advertised, just not executed here.
+     */
+    registerWorkflow(name: string, body: WorkflowBody): void;
+    /**
+     * Advertise a workflow NAME in the descriptor WITHOUT a runnable body (routing + capability
+     * negotiation only, design §7.1) — e.g. this pod routes/observes a workflow another worker executes.
+     * To actually EXECUTE turns here, use {@link registerWorkflow}. If already {@link start}ed,
+     * re-advertises so the name is visible.
+     */
+    registerWorkflowName(name: string): void;
+    /** Advertise many workflow names at once (one re-advertise). */
+    registerWorkflowNames(names: Iterable<string>): void;
+    /**
+     * The worker's current {@link WorkerDescriptor} — the single source of truth for routing, compat and
+     * observability (design §7.1). `workflows`/`steps` are the registered handler names (sorted, a set);
+     * `capabilities` are the configured extra features; `protocol` is the current major with a `[1, N]`
+     * range. Rebuilt on each read so it always reflects what is registered right now.
+     */
+    descriptor(): WorkerDescriptor;
+    /**
+     * Begin advertising: publish the descriptor + do the first heartbeat immediately (so a freshly
+     * started worker is visible without waiting a full interval), then refresh both on the heartbeat
+     * schedule. Idempotent. The interval is `unref`'d so it never keeps the process alive on its own.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop advertising and release resources: clears the beat interval, best-effort removes this
+     * instance's keys (a graceful drain — a watcher sees the worker leave immediately, not on TTL
+     * expiry), then closes the registry's owned connection and the transport. Idempotent.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=worker-runtime.d.ts.map

package/dist/src/worker-runtime/worker-runtime.d.ts.map

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

package/dist/src/worker-runtime/worker-runtime.js

@@ -0,0 +1,265 @@
+import { CURRENT_PROTOCOL_VERSION, heartbeatStatus, } from '../handshake/descriptor.js';
+import { WORKER_HEARTBEAT_INTERVAL_MS, WORKER_HEARTBEAT_TTL_SECONDS, buildInstanceId, } from '../transports/bullmq/serialization.js';
+import { runWorkflowTurn, } from '../workflow-turn.js';
+import { effectivePrefix, routingToken, workerDescriptorKey, workerHeartbeatKey, } from './naming.js';
+import { NoopWorkerRegistry } from './registry.js';
+/** SDK identity stamped on the descriptor when the caller doesn't override it (observability only). */
+export const WORKER_SDK = { name: '@adonis-agora/durable', version: '0.9.0' };
+const SILENT_LOGGER = { info: () => { }, error: () => { } };
+/**
+ * A **store-less** worker runtime (design §4): it executes step bodies pulled off the transport and
+ * advertises what it can serve — and has, by construction, NO store field and imports NO Lucid (proven
+ * by the `no-lucid` structural test). It is deliberately NOT a store-optional engine: isolation is a
+ * structural fact, not a runtime `if (this.store)`.
+ *
+ * Responsibilities:
+ * - **Register handlers** — {@link registerStep} (also `handle`, so `step-discovery`'s
+ *   `registerStepsFromDir/Barrel` can target the runtime directly) forwards to `transport.handle`,
+ *   which subscribes `${P}-tasks-<token>` and runs each task through the shared `runStepHandler`,
+ *   publishing the result. Workflow NAMES ({@link registerWorkflowName}) populate the descriptor.
+ * - **Advertise** ({@link start}) — publishes the {@link WorkerDescriptor} to
+ *   `${P}-worker-descriptor:<token>:<instance>` and beats the compact `{ ts, status, descriptorHash }`
+ *   to `${P}-worker-heartbeat:<token>:<instance>` on a schedule (design §7.2 two-tier ETag scheme).
+ *
+ * It holds no store and reads none — every durable decision stays on the control-plane; this object
+ * only runs bodies and says who it is.
+ */
+export class WorkerRuntime {
+    #transport;
+    #partition;
+    #namespace;
+    #prefix;
+    #instanceId;
+    #sdk;
+    #capabilities;
+    #registry;
+    #heartbeatIntervalMs;
+    #ttlSeconds;
+    #now;
+    #logger;
+    #onError;
+    #steps = new Set();
+    #workflows = new Set();
+    // Worker-side workflow turn bodies, keyed by name — the resolver `runWorkflowTurn` replays against.
+    #workflowBodies = new Map();
+    #startedAt;
+    #beatTimer;
+    #started = false;
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#partition = options.partition;
+        this.#namespace = options.namespace;
+        this.#prefix = options.prefix ?? 'durable';
+        this.#instanceId = options.instanceId ?? buildInstanceId();
+        this.#sdk = options.sdk ?? { ...WORKER_SDK };
+        this.#capabilities = [...(options.capabilities ?? [])];
+        this.#registry = options.registry ?? new NoopWorkerRegistry();
+        this.#heartbeatIntervalMs = options.heartbeatIntervalMs ?? WORKER_HEARTBEAT_INTERVAL_MS;
+        this.#ttlSeconds = options.ttlSeconds ?? WORKER_HEARTBEAT_TTL_SECONDS;
+        this.#now = options.now ?? Date.now;
+        this.#logger = options.logger ?? SILENT_LOGGER;
+        this.#onError = options.onError ?? (() => { });
+        // Process start time — a restart changes it, so the descriptor hash (and thus the ETag) changes.
+        this.#startedAt = this.#now();
+    }
+    /** Stable id stamped on this instance's liveness/descriptor keys. */
+    get instanceId() {
+        return this.#instanceId;
+    }
+    /** The step handler names this worker serves (sorted). */
+    get stepNames() {
+        return [...this.#steps].sort();
+    }
+    /** The workflow names this worker advertises (sorted). */
+    get workflowNames() {
+        return [...this.#workflows].sort();
+    }
+    /**
+     * Register a step handler on the transport (which subscribes its `${P}-tasks-<token>` queue and runs
+     * each task through the shared `runStepHandler`) AND record its name for the descriptor. Named
+     * `handle` too so `step-discovery`'s `registerStep`/`registerStepsFromDir`/`registerStepsFromBarrel`
+     * can target the runtime directly (it satisfies their `StepServer`). Re-registering swaps the handler;
+     * if already {@link start}ed, the descriptor is re-advertised so the new name is routable.
+     */
+    handle(name, fn) {
+        this.#transport.handle(name, fn);
+        const isNew = !this.#steps.has(name);
+        this.#steps.add(name);
+        if (isNew && this.#started)
+            void this.#advertise();
+    }
+    /** Alias of {@link handle} reading as intent at a call site that isn't the discovery `StepServer`. */
+    registerStep(name, fn) {
+        this.handle(name, fn);
+    }
+    /**
+     * Register a runnable WORKFLOW TURN body (`(ctx, input) => output`, written against the worker-side
+     * {@link import('../workflow-turn.js').WorkflowTurnCtx}) AND advertise its name. This is what lets a
+     * store-less TS worker EXECUTE workflow turns for parity with a Python worker (design §4): the
+     * transport subscribes the workflow's `${P}-tasks-<token>` queue and, on a `workflow`-shaped job, the
+     * turn is replayed via the shared {@link runWorkflowTurn} (deterministic history → decision) and the
+     * {@link import('../interfaces.js').WorkflowDecision} published on `${P}-decisions`. The worker never
+     * touches a store — every durable decision stays on the control-plane; this only replays the body.
+     *
+     * NOTE: this is the polyglot TURN surface (the TS twin of the Python `@workflow`), NOT the
+     * store-backed `BaseWorkflow`/`WorkflowCtx` the engine runs in-process — those are a different
+     * authoring surface (they own the store). Re-registering swaps the body; if the transport can't carry
+     * workflow tasks (`handleWorkflow` absent) the name is still advertised, just not executed here.
+     */
+    registerWorkflow(name, body) {
+        const firstBody = !this.#workflowBodies.has(name);
+        this.#workflowBodies.set(name, body);
+        // Wire the transport's turn consumer ONCE per name (the resolver reads the live #workflowBodies map,
+        // so a later re-register is picked up without re-wiring). No-op if the transport can't carry turns.
+        if (firstBody && this.#transport.handleWorkflow) {
+            this.#transport.handleWorkflow(name, (task) => runWorkflowTurn(this.#workflowBodies, task, {
+                partition: this.#partition,
+                ...(this.#transport.dispatchStepEvent
+                    ? { onStep: (event) => void this.#transport.dispatchStepEvent?.(event) }
+                    : {}),
+            }));
+        }
+        const isNew = !this.#workflows.has(name);
+        this.#workflows.add(name);
+        if (isNew && this.#started)
+            void this.#advertise();
+    }
+    /**
+     * Advertise a workflow NAME in the descriptor WITHOUT a runnable body (routing + capability
+     * negotiation only, design §7.1) — e.g. this pod routes/observes a workflow another worker executes.
+     * To actually EXECUTE turns here, use {@link registerWorkflow}. If already {@link start}ed,
+     * re-advertises so the name is visible.
+     */
+    registerWorkflowName(name) {
+        const isNew = !this.#workflows.has(name);
+        this.#workflows.add(name);
+        if (isNew && this.#started)
+            void this.#advertise();
+    }
+    /** Advertise many workflow names at once (one re-advertise). */
+    registerWorkflowNames(names) {
+        let added = false;
+        for (const name of names) {
+            if (!this.#workflows.has(name))
+                added = true;
+            this.#workflows.add(name);
+        }
+        if (added && this.#started)
+            void this.#advertise();
+    }
+    /**
+     * The worker's current {@link WorkerDescriptor} — the single source of truth for routing, compat and
+     * observability (design §7.1). `workflows`/`steps` are the registered handler names (sorted, a set);
+     * `capabilities` are the configured extra features; `protocol` is the current major with a `[1, N]`
+     * range. Rebuilt on each read so it always reflects what is registered right now.
+     */
+    descriptor() {
+        return {
+            instanceId: this.#instanceId,
+            runtime: 'node',
+            sdk: { ...this.#sdk },
+            protocol: { version: CURRENT_PROTOCOL_VERSION, range: [1, CURRENT_PROTOCOL_VERSION] },
+            capabilities: [...this.#capabilities],
+            workflows: [...this.#workflows].sort(),
+            steps: [...this.#steps].sort(),
+            ...(this.#partition ? { partition: this.#partition } : {}),
+            ...(this.#namespace !== undefined ? { namespace: this.#namespace } : {}),
+            startedAt: this.#startedAt,
+        };
+    }
+    /** The `${P}-worker-descriptor:<token>:<instance>` / `${P}-worker-heartbeat:<token>:<instance>` keys
+     *  this worker owns — one per DISTINCT routing token across its registered steps + workflows. */
+    #tokens() {
+        const tokens = new Set();
+        for (const name of this.#steps)
+            tokens.add(routingToken(name, this.#partition));
+        for (const name of this.#workflows)
+            tokens.add(routingToken(name, this.#partition));
+        return [...tokens];
+    }
+    #effPrefix() {
+        return effectivePrefix(this.#prefix, this.#namespace);
+    }
+    /** Publish the full descriptor under every handled token's descriptor key (design §7.2). */
+    async #advertise() {
+        const descriptor = this.descriptor();
+        const effPrefix = this.#effPrefix();
+        try {
+            await Promise.all(this.#tokens().map((token) => this.#registry.advertiseDescriptor({
+                key: workerDescriptorKey(effPrefix, token, this.#instanceId),
+                descriptor,
+                ttlSeconds: this.#ttlSeconds,
+            })));
+        }
+        catch (err) {
+            this.#onError(err);
+        }
+    }
+    /** Beat the compact `{ ts, status, descriptorHash }` under every handled token's heartbeat key. */
+    async #beat(status) {
+        const descriptor = this.descriptor();
+        const beat = heartbeatStatus(descriptor, { ts: this.#now(), status });
+        const effPrefix = this.#effPrefix();
+        try {
+            await Promise.all(this.#tokens().map((token) => this.#registry.beat({
+                key: workerHeartbeatKey(effPrefix, token, this.#instanceId),
+                status: beat,
+                ttlSeconds: this.#ttlSeconds,
+            })));
+        }
+        catch (err) {
+            this.#onError(err);
+        }
+    }
+    /**
+     * Begin advertising: publish the descriptor + do the first heartbeat immediately (so a freshly
+     * started worker is visible without waiting a full interval), then refresh both on the heartbeat
+     * schedule. Idempotent. The interval is `unref`'d so it never keeps the process alive on its own.
+     */
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        await this.#advertise();
+        await this.#beat('up');
+        this.#beatTimer = setInterval(() => {
+            // Re-advertise each cycle too: refreshes the descriptor key's TTL (cheap; the ETag is stable so a
+            // reader still skips the re-read) so it never expires under a live worker.
+            void this.#advertise();
+            void this.#beat('up');
+        }, this.#heartbeatIntervalMs);
+        this.#beatTimer.unref?.();
+        this.#logger.info(`worker-runtime started (instance ${this.#instanceId}, partition ${this.#partition}, ` +
+            `${this.#steps.size} steps, ${this.#workflows.size} workflows)`);
+    }
+    /**
+     * Stop advertising and release resources: clears the beat interval, best-effort removes this
+     * instance's keys (a graceful drain — a watcher sees the worker leave immediately, not on TTL
+     * expiry), then closes the registry's owned connection and the transport. Idempotent.
+     */
+    async stop() {
+        if (!this.#started)
+            return;
+        this.#started = false;
+        if (this.#beatTimer)
+            clearInterval(this.#beatTimer);
+        this.#beatTimer = undefined;
+        if (this.#registry.remove) {
+            const effPrefix = this.#effPrefix();
+            const keys = this.#tokens().flatMap((token) => [
+                workerDescriptorKey(effPrefix, token, this.#instanceId),
+                workerHeartbeatKey(effPrefix, token, this.#instanceId),
+            ]);
+            try {
+                await this.#registry.remove(keys);
+            }
+            catch (err) {
+                this.#onError(err);
+            }
+        }
+        await this.#registry.close?.();
+        await this.#transport.close?.();
+        this.#logger.info(`worker-runtime stopped (instance ${this.#instanceId})`);
+    }
+}
+//# sourceMappingURL=worker-runtime.js.map

package/dist/src/worker-runtime/worker-runtime.js.map

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

package/dist/src/workflow-ctx.d.ts

@@ -62,6 +62,15 @@ export interface CtxHost {
     }): Promise<TOutput>;
     /** Start a child run once, deferred so it can't reentrantly resume a still-running parent. */
     startChild(workflow: string, input: unknown, id: string, priority?: number): void;
+    /**
+     * Best-effort cancel of a child run — deferred for the SAME reason as `startChild` (so ctx code
+     * can't reentrantly mutate engine state while the parent's own step is still executing
+     * synchronously). Plain cancel, no saga undo; used by `ctx.all`'s `failFast` mode to stop the
+     * surviving siblings once one has failed. Cancelling an already-terminal/cancelled run is a no-op
+     * (`engine.cancel`'s own idempotency guard), so a replay that re-issues the same calls is safe.
+     * Optional: hosts that never construct a `ctx.all` failFast call (e.g. test fakes) can omit it.
+     */
+    cancelChild?(childId: string): void;
     /** Shallow-merge `attrs` into the run's `searchAttributes` (see {@link WorkflowCtx.upsertSearchAttributes}). */
     upsertSearchAttributes(runId: string, attrs: SearchAttributes): Promise<void>;
     /** Deliver an op to a durable entity (deferred), optionally with a `reply` token for the result. */