@adonis-agora/durable 0.47.0 → 0.49.0

package/dist/src/errors.d.ts

@@ -6,7 +6,12 @@ import { CONTROL_FLOW_SIGNAL } from './control-flow-signal.js';
  */
 export declare class FatalError extends Error {
     readonly code?: string | undefined;
-    constructor(message: string, code?: string);
+    /** Structured, JSON-serializable detail (e.g. validation issues). It travels with the failure to
+     *  the run's error, a parent's `allSettled` item and an onError handler's input. */
+    readonly details?: unknown;
+    /** Read by the step result builders, so a dispatched step's retry policy honours it too. */
+    readonly retryable = false;
+    constructor(message: string, code?: string, details?: unknown);
 }
 /**
  * Thrown by `start` when a run would exceed its concurrency quota: `active` runs sharing the quota
@@ -61,6 +66,8 @@ export declare class RemoteStepTimeout extends Error {
  * breaking changes (old runs finish on the version they started on).
  */
 export declare class NonDeterminismError extends Error {
+    /** Marks the failure as a broken deploy, which an `onError` route never takes. */
+    readonly code = "non_determinism";
     readonly runId: string;
     readonly seq: number;
     constructor(runId: string, seq: number, expected: string, recorded: string);
@@ -91,17 +98,17 @@ export declare class NestedWorkflowCallError extends FatalError {
  * and the failing ids — the wait-all/fail-fast counterpart to a single child's FatalError. Mirrors
  * the Python SDK's `GatherFailed`.
  */
+/** One failed item of a fan: its input index, the child run id, and its failure. */
+export interface GatherItemFailure {
+    index: number;
+    id: string;
+    error: string;
+    code?: string | undefined;
+    details?: unknown;
+}
 export declare class GatherError extends Error {
-    readonly failures: {
-        index: number;
-        id: string;
-        error: string;
-    }[];
-    constructor(failures: {
-        index: number;
-        id: string;
-        error: string;
-    }[], total?: number);
+    readonly failures: GatherItemFailure[];
+    constructor(failures: GatherItemFailure[], total?: number);
 }
 export declare class WorkflowSuspended extends Error {
     /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
@@ -116,9 +123,20 @@ export declare class WorkflowSuspended extends Error {
     readonly waitSeqs?: number[] | undefined;
     /** Set when awaited children are what the run is waiting on — see {@link FanJoin}. */
     readonly fan?: FanJoin | undefined;
+    /**
+     * The position blocks of the step fans (`ctx.all` over a `@Step`) this suspension waits on. Their
+     * steps are deliberately NOT in {@link waitSeqs}: one settled step must not re-drive the run, only
+     * a fan with no step left `pending` does.
+     */
+    readonly stepFans?: StepFanRange[] | undefined;
     /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
     readonly [CONTROL_FLOW_SIGNAL] = true;
-    constructor(wakeAt?: number, waitSeqs?: number[], fan?: FanJoin);
+    constructor(wakeAt?: number, waitSeqs?: number[], fan?: FanJoin, stepFans?: StepFanRange[]);
+}
+/** The seqs `from..to` (inclusive) of one step fan's position block. */
+export interface StepFanRange {
+    from: number;
+    to: number;
 }
 /**
  * What a run suspended on when it awaits children (`ctx.all`, `ctx.child`). For each group of

package/dist/src/errors.d.ts.map

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

package/dist/src/errors.js

@@ -6,10 +6,16 @@ import { CONTROL_FLOW_SIGNAL } from './control-flow-signal.js';
  */
 export class FatalError extends Error {
     code;
-    constructor(message, code) {
+    /** Structured, JSON-serializable detail (e.g. validation issues). It travels with the failure to
+     *  the run's error, a parent's `allSettled` item and an onError handler's input. */
+    details;
+    /** Read by the step result builders, so a dispatched step's retry policy honours it too. */
+    retryable = false;
+    constructor(message, code, details) {
         super(message);
         this.name = 'FatalError';
         this.code = code;
+        this.details = details;
     }
 }
 /**
@@ -88,6 +94,8 @@ export class RemoteStepTimeout extends Error {
  * breaking changes (old runs finish on the version they started on).
  */
 export class NonDeterminismError extends Error {
+    /** Marks the failure as a broken deploy, which an `onError` route never takes. */
+    code = 'non_determinism';
     runId;
     seq;
     constructor(runId, seq, expected, recorded) {
@@ -124,12 +132,6 @@ export class NestedWorkflowCallError extends FatalError {
         this.step = step;
     }
 }
-/**
- * Thrown by `ctx.all` when one or more parallel child workflows fail. Carries the per-item failures
- * (input index, child run id, error message) and presents an aggregate message summarizing the count
- * and the failing ids — the wait-all/fail-fast counterpart to a single child's FatalError. Mirrors
- * the Python SDK's `GatherFailed`.
- */
 export class GatherError extends Error {
     failures;
     constructor(failures, total) {
@@ -153,14 +155,21 @@ export class WorkflowSuspended extends Error {
     waitSeqs;
     /** Set when awaited children are what the run is waiting on — see {@link FanJoin}. */
     fan;
+    /**
+     * The position blocks of the step fans (`ctx.all` over a `@Step`) this suspension waits on. Their
+     * steps are deliberately NOT in {@link waitSeqs}: one settled step must not re-drive the run, only
+     * a fan with no step left `pending` does.
+     */
+    stepFans;
     /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
     [CONTROL_FLOW_SIGNAL] = true;
-    constructor(wakeAt, waitSeqs, fan) {
+    constructor(wakeAt, waitSeqs, fan, stepFans) {
         super('workflow suspended');
         this.name = 'WorkflowSuspended';
         this.wakeAt = wakeAt;
         this.waitSeqs = waitSeqs;
         this.fan = fan;
+        this.stepFans = stepFans;
     }
 }
 /**

package/dist/src/errors.js.map

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

package/dist/src/fan-join.d.ts

@@ -1,5 +1,5 @@
 import type { FanJoin, FanWait } from './errors.js';
-import type { SignalWaiter } from './interfaces.js';
+import type { SignalWaiter, StepCheckpoint } from './interfaces.js';
 /**
  * Naming shared by `ctx.all` (which mints the ids) and the engine's join barrier (which reads them
  * back off a settling child's waiter). The child id and group are replay anchors: changing either
@@ -10,8 +10,32 @@ import type { SignalWaiter } from './interfaces.js';
  * can wait on one wave at a time.
  */
 export declare function allChildId(runId: string, firstSeq: number, index: number, wave?: number): string;
-/** The fan's `parallelGroup`. A failFast fan is marked so the barrier wakes it on the first failure. */
-export declare function allGroup(firstSeq: number, mode: 'waitAll' | 'failFast'): string;
+/**
+ * The fan's `parallelGroup`: its first seq, its size (so a view can count the children not started
+ * yet), and a failFast mark so the barrier wakes it on the first failure.
+ */
+export declare function allGroup(firstSeq: number, size: number, mode: 'waitAll' | 'failFast'): string;
+/**
+ * The `parallelGroup` of a step fan (`ctx.all` over a `@Step`). It carries the fan's position block,
+ * so the engine's join barrier can tell from any one step's checkpoint which steps it waits on.
+ */
+export declare function stepFanGroup(firstSeq: number, size: number, mode: 'waitAll' | 'failFast'): string;
+/** The position block a {@link stepFanGroup} names, or undefined for any other group. */
+export declare function parseStepFanGroup(group: string | undefined): {
+    firstSeq: number;
+    size: number;
+} | undefined;
+/**
+ * What a fan's `parallelGroup` says about it: a child fan (`all:<seq>[:n<size>][:failFast]`) or a
+ * step fan (`steps:<seq>:<size>[:failFast]`). `size` is absent on a child fan dispatched before the
+ * group carried it.
+ */
+export declare function parseFanGroup(group: string | undefined): {
+    kind: 'all' | 'steps';
+    firstSeq: number;
+    size?: number | undefined;
+    failFast: boolean;
+} | undefined;
 /** The waiter and checkpoint name prefixes shared by a fan's children, or one wave's. */
 export declare function allWait(runId: string, firstSeq: number, wave?: number): FanWait;
 export declare function fanJoin(waits: FanWait[]): FanJoin;
@@ -43,9 +67,10 @@ export declare function allWaves(size: number, concurrency: number | undefined):
 } | undefined;
 /**
  * The parent of a child run whose id the engine minted: a `ctx.all` child
- * (`<parent>.all.<seq>.<i>`, or `.w<k>.<i>` under a `concurrency` limit) or a `ctx.child` /
- * `ctx.startChild` child without an explicit id (`<parent>.child.<seq>`). Undefined for any other
- * run, including a child started with a caller-chosen id.
+ * (`<parent>.all.<seq>.<i>`, or `.w<k>.<i>` under a `concurrency` limit), a `ctx.child` /
+ * `ctx.startChild` child without an explicit id (`<parent>.child.<seq>`), or the onError handler of
+ * a failed run (`<parent>.onError.<attempt>`). Undefined for any other run, including a child started with a
+ * caller-chosen id.
  */
 export declare function parentRunIdOf(runId: string): string | undefined;
 /**
@@ -58,4 +83,9 @@ export declare function fanOfWaiter(waiter: SignalWaiter): {
     waiterPrefix: string;
     failFast: boolean;
 } | undefined;
+/**
+ * The child run ids a parent's child-edge checkpoints point at: an awaited child
+ * (`signal:child:<id>`), a folded group of them, a spawn (`spawn:`). Other checkpoints are skipped.
+ */
+export declare function childIdsOf(checkpoints: StepCheckpoint[]): string[];
 //# sourceMappingURL=fan-join.d.ts.map

package/dist/src/fan-join.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fan-join.d.ts","sourceRoot":"","sources":["../../src/fan-join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhG;AAED,wGAAwG;AACxG,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAE/E;AAED,yFAAyF;AACzF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAG/E;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAEjD;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,CAMvF;AAMD;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAUpD;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/D;AAKD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,GACnB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CASzD"}
+{"version":3,"file":"fan-join.d.ts","sourceRoot":"","sources":["../../src/fan-join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEpE;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhG;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAG7F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAGjG;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAIhD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,GAAG,SAAS,GAEvB;IAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GACzF,SAAS,CAUZ;AAED,yFAAyF;AACzF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAG/E;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAEjD;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,CAMvF;AAMD;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAUpD;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/D;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,GACnB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CASzD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CAQlE"}

package/dist/src/fan-join.js

@@ -10,9 +10,46 @@
 export function allChildId(runId, firstSeq, index, wave) {
     return `${allBase(runId, firstSeq, wave)}${index}`;
 }
-/** The fan's `parallelGroup`. A failFast fan is marked so the barrier wakes it on the first failure. */
-export function allGroup(firstSeq, mode) {
-    return mode === 'failFast' ? `all:${firstSeq}:failFast` : `all:${firstSeq}`;
+/**
+ * The fan's `parallelGroup`: its first seq, its size (so a view can count the children not started
+ * yet), and a failFast mark so the barrier wakes it on the first failure.
+ */
+export function allGroup(firstSeq, size, mode) {
+    const group = `all:${firstSeq}:n${size}`;
+    return mode === 'failFast' ? `${group}:failFast` : group;
+}
+/**
+ * The `parallelGroup` of a step fan (`ctx.all` over a `@Step`). It carries the fan's position block,
+ * so the engine's join barrier can tell from any one step's checkpoint which steps it waits on.
+ */
+export function stepFanGroup(firstSeq, size, mode) {
+    const group = `steps:${firstSeq}:${size}`;
+    return mode === 'failFast' ? `${group}:failFast` : group;
+}
+/** The position block a {@link stepFanGroup} names, or undefined for any other group. */
+export function parseStepFanGroup(group) {
+    const fan = parseFanGroup(group);
+    if (fan?.kind !== 'steps' || fan.size === undefined)
+        return undefined;
+    return { firstSeq: fan.firstSeq, size: fan.size };
+}
+/**
+ * What a fan's `parallelGroup` says about it: a child fan (`all:<seq>[:n<size>][:failFast]`) or a
+ * step fan (`steps:<seq>:<size>[:failFast]`). `size` is absent on a child fan dispatched before the
+ * group carried it.
+ */
+export function parseFanGroup(group) {
+    const m = group ? /^(all|steps):(\d+)(?::n?(\d+))?(:failFast)?$/.exec(group) : null;
+    if (!m)
+        return undefined;
+    if (m[1] === 'steps' && m[3] === undefined)
+        return undefined;
+    return {
+        kind: m[1],
+        firstSeq: Number(m[2]),
+        size: m[3] === undefined ? undefined : Number(m[3]),
+        failFast: m[4] !== undefined,
+    };
 }
 /** The waiter and checkpoint name prefixes shared by a fan's children, or one wave's. */
 export function allWait(runId, firstSeq, wave) {
@@ -63,17 +100,19 @@ export function allWaves(size, concurrency) {
         return { waveSize: 1, maxWaves: 1 };
     return { waveSize: Math.floor(concurrency / 2), maxWaves: 2 };
 }
-const ENGINE_CHILD_ID = /^(.+)\.(?:all\.\d+\.(?:w\d+\.)?\d+|child\.\d+)$/;
+const ENGINE_CHILD_ID = /^(.+)\.(?:all\.\d+\.(?:w\d+\.)?\d+|child\.\d+|onError\.\d+)$/;
 /**
  * The parent of a child run whose id the engine minted: a `ctx.all` child
- * (`<parent>.all.<seq>.<i>`, or `.w<k>.<i>` under a `concurrency` limit) or a `ctx.child` /
- * `ctx.startChild` child without an explicit id (`<parent>.child.<seq>`). Undefined for any other
- * run, including a child started with a caller-chosen id.
+ * (`<parent>.all.<seq>.<i>`, or `.w<k>.<i>` under a `concurrency` limit), a `ctx.child` /
+ * `ctx.startChild` child without an explicit id (`<parent>.child.<seq>`), or the onError handler of
+ * a failed run (`<parent>.onError.<attempt>`). Undefined for any other run, including a child started with a
+ * caller-chosen id.
  */
 export function parentRunIdOf(runId) {
     return ENGINE_CHILD_ID.exec(runId)?.[1];
 }
-const GROUP = /^all:(\d+)(:failFast)?$/;
+// A waiter stored before the group carried the fan's size has no `:n<size>` segment.
+const GROUP = /^all:(\d+)(?::n\d+)?(:failFast)?$/;
 const REST = /^(?:w(\d+)\.)?\d+$/;
 /**
  * The `ctx.all` fan (or, for a fan with a `concurrency` limit, the wave) a waiter belongs to, or
@@ -94,4 +133,20 @@ export function fanOfWaiter(waiter) {
     const waiterPrefix = rest[1] === undefined ? base : `${base}w${rest[1]}.`;
     return { waiterPrefix, failFast: group[2] !== undefined };
 }
+/**
+ * The child run ids a parent's child-edge checkpoints point at: an awaited child
+ * (`signal:child:<id>`), a folded group of them, a spawn (`spawn:`). Other checkpoints are skipped.
+ */
+export function childIdsOf(checkpoints) {
+    const ids = [];
+    for (const cp of checkpoints) {
+        if (cp.name.startsWith('signal:child:'))
+            ids.push(cp.name.slice('signal:child:'.length));
+        if (cp.name.startsWith(FOLDED_PREFIX))
+            ids.push(...foldedChildIds(cp));
+        if (cp.name.startsWith('spawn:') && typeof cp.output === 'string')
+            ids.push(cp.output);
+    }
+    return ids;
+}
 //# sourceMappingURL=fan-join.js.map

package/dist/src/fan-join.js.map

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

package/dist/src/handshake/announced.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The announced workflow registry (design §7.9) — the aggregate answer to "what workflows exist in
+ * this deployment?", built ONLY from what live workers say about themselves: each worker publishes
+ * what it can execute ({@link WorkerDescriptor.registrations}, or bare `workflows` names), and this
+ * module folds those statements together. Every entry is a fact somebody asserted, and the aggregate
+ * is the same on every pod because every pod reads the same published statements. Pure data, no I/O.
+ */
+import type { RawWorkerDescriptor, WorkerDescriptor, WorkflowRegistration } from './descriptor.js';
+/** One live worker's claim about one workflow: the registration plus who announced it. */
+export interface WorkflowAnnouncement extends WorkflowRegistration {
+    /** The announcing worker's instance id. */
+    instanceId: string;
+    /** The announcing worker's runtime — how a Python-served workflow is told from a Node-served one. */
+    runtime: 'node' | 'python';
+}
+/** An axis on which the live announcers of one workflow do not agree. `values` holds every distinct
+ *  DECLARED value (sorted); an announcer that stated nothing on the axis contributes nothing. */
+export interface Disagreement {
+    axis: 'group' | 'origin' | 'requires' | 'onError';
+    values: string[];
+}
+/**
+ * How strong the fleet's claim about a workflow is. The two tiers are NOT interchangeable and a
+ * caller must not read them as the same fact:
+ *
+ * - `'declared'` — at least one live worker published a descriptor naming this workflow. Everything
+ *   populated on the entry was STATED by that worker; everything absent it declined to state.
+ * - `'observed'` — nobody described it. What exists is a live routing token of this name, which is
+ *   precisely the condition `resolveRemoteByConvention` uses to route a call, so the name IS
+ *   reachable. Nothing else is known: no version, no origin, no runtime, and no assurance that the
+ *   worker consuming that token serves a WORKFLOW there rather than a step handler of the same name.
+ *   An entry like this is a live queue, not a promise.
+ */
+export type AnnouncementEvidence = 'declared' | 'observed';
+/** One workflow the live fleet announces, folded across every worker that announced it. */
+export interface AnnouncedWorkflow {
+    /** What kind of claim this entry rests on — see {@link AnnouncementEvidence}. A caller that shows
+     *  a version, an origin or a runtime must check this first: an `'observed'` entry has none of
+     *  them, and the emptiness is a fact about the fleet, not a rendering gap. */
+    evidence: AnnouncementEvidence;
+    /** `name@version`, or the bare `name` when no announcer stated a version. Stable sort key. */
+    key: string;
+    name: string;
+    /** Absent when no announcer stated one — never inferred from another announcer's version. */
+    version?: string;
+    /** Every distinct routing group announced (sorted). Empty = nobody stated one. On an `'observed'`
+     *  entry this is the token the heartbeat was published UNDER — not a claim by anybody, but the
+     *  queue a call would actually land on, which is the one thing an observation does establish. */
+    groups: string[];
+    /** Every distinct declaring package announced (sorted). Empty = nobody stated one. */
+    origins: string[];
+    /** Every distinct capability demand announced, each de-duplicated + sorted. Empty = nobody stated
+     *  one. Two entries here means two workers demand different capabilities for the same version. */
+    requires: string[][];
+    /** Every distinct set of `onError` routes announced, each in canonical order. Empty = nobody stated
+     *  one. Two entries here means the live workers route this workflow's failures differently. */
+    onError: {
+        code?: string;
+        workflow: string;
+    }[][];
+    /** Runtimes of the live announcers (sorted, de-duplicated). EMPTY on an `'observed'` entry: a
+     *  heartbeat does not say what runtime wrote it, and the instance id's shape is a convention, not
+     *  a statement, so it is not read as one. */
+    runtimes: ('node' | 'python')[];
+    /** Instance ids of the live workers announcing it (sorted, de-duplicated). Its length is how many
+     *  workers can currently run this workflow — `1` is a single point of failure, and it is never 0
+     *  (an entry exists only because somebody announced it, or because somebody is beating on it). */
+    instances: string[];
+    /** The axes the announcers differ on, empty when they speak with one voice. A caller that must
+     *  pick a single target has to resolve these itself — the registry refuses to guess. */
+    disagreements: Disagreement[];
+}
+/**
+ * What one descriptor announces. `registrations` is authoritative when present; any `workflows` name
+ * it does not cover is still announced as a bare, unversioned claim, so a worker that describes some
+ * of its workflows richly and others by name alone is reported in full rather than in part.
+ *
+ * A descriptor with neither field announces nothing — including the control plane's own descriptor,
+ * which is a router, not an executor.
+ */
+export declare function announcementsOf(raw: RawWorkerDescriptor | WorkerDescriptor): WorkflowAnnouncement[];
+/**
+ * Fold every live descriptor's announcements into one entry per `name@version`, sorted by key.
+ *
+ * Pure: it holds nothing and caches nothing, so no pod ever carries a growing table of the fleet's
+ * registrations — the caller reads the live descriptors it already knows how to read, folds them
+ * here, and drops the result. The work is O(descriptors × announcements) per call, on demand.
+ *
+ * The same instance announcing the same workflow twice (a worker publishes its descriptor under
+ * every routing token it consumes, so the same bytes arrive several times) folds to ONE announcer:
+ * `instances` is a set, so it counts workers, not keys.
+ */
+export declare function aggregateAnnouncements(descriptors: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): AnnouncedWorkflow[];
+//# sourceMappingURL=announced.d.ts.map

package/dist/src/handshake/announced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"announced.d.ts","sourceRoot":"","sources":["../../../src/handshake/announced.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGnG,0FAA0F;AAC1F,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,qGAAqG;IACrG,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC5B;AAED;iGACiG;AACjG,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IAClD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,UAAU,CAAC;AAE3D,2FAA2F;AAC3F,MAAM,WAAW,iBAAiB;IAChC;;kFAE8E;IAC9E,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;qGAEiG;IACjG,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sFAAsF;IACtF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;sGACkG;IAClG,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;IACrB;mGAC+F;IAC/F,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,EAAE,CAAC;IACjD;;iDAE6C;IAC7C,QAAQ,EAAE,CAAC,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC;IAChC;;sGAEkG;IAClG,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;4FACwF;IACxF,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,mBAAmB,GAAG,gBAAgB,GAC1C,oBAAoB,EAAE,CASxB;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,SAAS,CAAC,mBAAmB,GAAG,gBAAgB,CAAC,EAAE,GAC/D,iBAAiB,EAAE,CAkErB"}

package/dist/src/handshake/announced.js

@@ -0,0 +1,113 @@
+/**
+ * The announced workflow registry (design §7.9) — the aggregate answer to "what workflows exist in
+ * this deployment?", built ONLY from what live workers say about themselves: each worker publishes
+ * what it can execute ({@link WorkerDescriptor.registrations}, or bare `workflows` names), and this
+ * module folds those statements together. Every entry is a fact somebody asserted, and the aggregate
+ * is the same on every pod because every pod reads the same published statements. Pure data, no I/O.
+ */
+import { canonicalRoutes, normalizeDescriptor } from './descriptor.js';
+/**
+ * What one descriptor announces. `registrations` is authoritative when present; any `workflows` name
+ * it does not cover is still announced as a bare, unversioned claim, so a worker that describes some
+ * of its workflows richly and others by name alone is reported in full rather than in part.
+ *
+ * A descriptor with neither field announces nothing — including the control plane's own descriptor,
+ * which is a router, not an executor.
+ */
+export function announcementsOf(raw) {
+    const d = normalizeDescriptor(raw);
+    const identity = { instanceId: d.instanceId, runtime: d.runtime };
+    const announcements = (d.registrations ?? []).map((reg) => ({ ...reg, ...identity }));
+    const covered = new Set(announcements.map((a) => a.name));
+    for (const name of d.workflows) {
+        if (!covered.has(name))
+            announcements.push({ name, ...identity });
+    }
+    return announcements;
+}
+/** `name@version`, or the bare name when unversioned — the identity two announcements are folded on. */
+function announcementKey(a) {
+    return a.version === undefined ? a.name : `${a.name}@${a.version}`;
+}
+/** Sorted, de-duplicated members of `values`, dropping the un-stated ones. */
+function stated(values) {
+    return [...new Set(values.filter((v) => v !== undefined))].sort();
+}
+/**
+ * Fold every live descriptor's announcements into one entry per `name@version`, sorted by key.
+ *
+ * Pure: it holds nothing and caches nothing, so no pod ever carries a growing table of the fleet's
+ * registrations — the caller reads the live descriptors it already knows how to read, folds them
+ * here, and drops the result. The work is O(descriptors × announcements) per call, on demand.
+ *
+ * The same instance announcing the same workflow twice (a worker publishes its descriptor under
+ * every routing token it consumes, so the same bytes arrive several times) folds to ONE announcer:
+ * `instances` is a set, so it counts workers, not keys.
+ */
+export function aggregateAnnouncements(descriptors) {
+    const byKey = new Map();
+    for (const descriptor of descriptors) {
+        for (const announcement of announcementsOf(descriptor)) {
+            const key = announcementKey(announcement);
+            const bucket = byKey.get(key);
+            if (bucket)
+                bucket.push(announcement);
+            else
+                byKey.set(key, [announcement]);
+        }
+    }
+    const out = [];
+    for (const [key, announcements] of byKey) {
+        const groups = stated(announcements.map((a) => a.group));
+        const origins = stated(announcements.map((a) => a.origin));
+        // A capability demand is a SET, so it is compared as its canonical (sorted, de-duplicated) form:
+        // two workers demanding ['saga','signals'] and ['signals','saga'] agree, and must not be reported
+        // as a disagreement over the same demand written two ways.
+        const requiresByJson = new Map();
+        for (const a of announcements) {
+            if (a.requires === undefined)
+                continue;
+            const canonical = [...new Set(a.requires)].sort();
+            requiresByJson.set(JSON.stringify(canonical), canonical);
+        }
+        // Ordered by the same rendering `disagreements` uses, so the two lists read in step.
+        const requires = [...requiresByJson.values()].sort((x, y) => x.join(',').localeCompare(y.join(',')));
+        const routesByJson = new Map();
+        for (const a of announcements) {
+            if (a.onError === undefined)
+                continue;
+            const canonical = canonicalRoutes(a.onError).map((r) => r.code === null ? { workflow: r.workflow } : { code: r.code, workflow: r.workflow });
+            routesByJson.set(JSON.stringify(canonical), canonical);
+        }
+        const onError = [...routesByJson.keys()].sort().map((k) => routesByJson.get(k) ?? []);
+        const disagreements = [];
+        if (groups.length > 1)
+            disagreements.push({ axis: 'group', values: groups });
+        if (origins.length > 1)
+            disagreements.push({ axis: 'origin', values: origins });
+        if (requires.length > 1) {
+            disagreements.push({ axis: 'requires', values: requires.map((r) => r.join(',')) });
+        }
+        if (onError.length > 1) {
+            disagreements.push({ axis: 'onError', values: [...routesByJson.keys()].sort() });
+        }
+        const first = announcements[0];
+        if (!first)
+            continue;
+        out.push({
+            evidence: 'declared',
+            key,
+            name: first.name,
+            ...(first.version !== undefined ? { version: first.version } : {}),
+            groups,
+            origins,
+            requires,
+            onError,
+            runtimes: [...new Set(announcements.map((a) => a.runtime))].sort(),
+            instances: [...new Set(announcements.map((a) => a.instanceId))].sort(),
+            disagreements,
+        });
+    }
+    return out.sort((a, b) => a.key.localeCompare(b.key));
+}
+//# sourceMappingURL=announced.js.map

package/dist/src/handshake/announced.js.map

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