@hotmeshio/hotmesh 0.8.0 → 0.9.0

package/build/services/activities/trigger.d.ts

@@ -1,14 +1,67 @@
 import { EngineService } from '../engine';
 import { ActivityData, ActivityMetadata, ActivityType, TriggerActivity } from '../../types/activity';
-import { JobState, ExtensionType, JobStatus } from '../../types/job';
+import { JobState, ExtensionType } from '../../types/job';
 import { ProviderTransaction } from '../../types/provider';
-import { StringScalarType } from '../../types/serializer';
 import { Activity } from './activity';
+/**
+ * The entry point for every workflow graph. Each graph must have exactly
+ * one `trigger` activity, which executes when the graph's `subscribes`
+ * topic receives a message (via `hotMesh.pub` or `hotMesh.pubsub`).
+ *
+ * The trigger initializes the job, sets its unique ID and key, binds
+ * the incoming payload as the trigger's output data, and transitions
+ * to adjacent activities defined in the `transitions` section.
+ *
+ * ## YAML Configuration
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: order.placed       # the trigger fires when this topic receives a message
+ *       publishes: order.processed     # emitted when the graph completes
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *           entity: '{$self.input.data.entityType}'
+ *           job:
+ *             maps:
+ *               myField: '{$self.output.data.inputField}'
+ *           stats:
+ *             id: '{$self.input.data.workflowId}'
+ *             key: '{$self.input.data.parentId}'
+ *             parent: '{$self.input.data.originJobId}'
+ *             adjacent: '{$self.input.data.parentJobId}'
+ *
+ *         process:
+ *           type: worker
+ *           topic: order.process
+ *
+ *       transitions:
+ *         t1:
+ *           - to: process
+ * ```
+ *
+ * ## Key Behaviors
+ *
+ * - **Job ID Resolution**: If `stats.id` is provided, it resolves via `@pipe`
+ *   expressions against the input data. Otherwise a UUID is generated.
+ * - **Duplicate Detection**: If a job with the same ID already exists,
+ *   a `DuplicateJobError` is thrown (unless it's a crash-recovery scenario).
+ * - **Pending Mode**: When invoked with `{ pending: <seconds> }`, the trigger
+ *   creates the job but does not transition to children until resumed.
+ * - **Crash Recovery**: Uses a 3-step inception protocol with GUID ledger
+ *   to ensure atomic job creation survives process crashes.
+ *
+ * @see {@link TriggerActivity} for the TypeScript interface
+ */
 declare class Trigger extends Activity {
     config: TriggerActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
     process(options?: ExtensionType): Promise<string>;
-    transitionAndLogAdjacent(options: ExtensionType, jobStatus: JobStatus, attrs: StringScalarType): Promise<void>;
     /**
      * `pending` flows will not transition from the trigger to adjacent children until resumed
      */
@@ -31,7 +84,6 @@ declare class Trigger extends Activity {
     getJobStatus(): number;
     resolveJobId(context: Partial<JobState>): string;
     resolveJobKey(context: Partial<JobState>): string;
-    setStateNX(status?: number, entity?: string | undefined): Promise<void>;
     setStats(transaction?: ProviderTransaction): Promise<void>;
 }
 export { Trigger };

package/build/services/activities/trigger.js

@@ -10,6 +10,61 @@ const serializer_1 = require("../serializer");
 const telemetry_1 = require("../telemetry");
 const mapper_1 = require("../mapper");
 const activity_1 = require("./activity");
+/**
+ * The entry point for every workflow graph. Each graph must have exactly
+ * one `trigger` activity, which executes when the graph's `subscribes`
+ * topic receives a message (via `hotMesh.pub` or `hotMesh.pubsub`).
+ *
+ * The trigger initializes the job, sets its unique ID and key, binds
+ * the incoming payload as the trigger's output data, and transitions
+ * to adjacent activities defined in the `transitions` section.
+ *
+ * ## YAML Configuration
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: order.placed       # the trigger fires when this topic receives a message
+ *       publishes: order.processed     # emitted when the graph completes
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *           entity: '{$self.input.data.entityType}'
+ *           job:
+ *             maps:
+ *               myField: '{$self.output.data.inputField}'
+ *           stats:
+ *             id: '{$self.input.data.workflowId}'
+ *             key: '{$self.input.data.parentId}'
+ *             parent: '{$self.input.data.originJobId}'
+ *             adjacent: '{$self.input.data.parentJobId}'
+ *
+ *         process:
+ *           type: worker
+ *           topic: order.process
+ *
+ *       transitions:
+ *         t1:
+ *           - to: process
+ * ```
+ *
+ * ## Key Behaviors
+ *
+ * - **Job ID Resolution**: If `stats.id` is provided, it resolves via `@pipe`
+ *   expressions against the input data. Otherwise a UUID is generated.
+ * - **Duplicate Detection**: If a job with the same ID already exists,
+ *   a `DuplicateJobError` is thrown (unless it's a crash-recovery scenario).
+ * - **Pending Mode**: When invoked with `{ pending: <seconds> }`, the trigger
+ *   creates the job but does not transition to children until resumed.
+ * - **Crash Recovery**: Uses a 3-step inception protocol with GUID ledger
+ *   to ensure atomic job creation survives process crashes.
+ *
+ * @see {@link TriggerActivity} for the TypeScript interface
+ */
 class Trigger extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
@@ -30,40 +85,84 @@ class Trigger extends activity_1.Activity {
             const initialStatus = this.initStatus(options, this.adjacencyList.length);
             //config.entity is a pipe expression; if 'entity' exists, it will resolve
             const resolvedEntity = new mapper_1.MapperService({ entity: this.config.entity }, this.context).mapRules()?.entity;
-            await this.setStateNX(initialStatus, options?.entity || resolvedEntity);
+            const msgGuid = this.context.metadata.guid || (0, utils_1.guid)();
+            this.context.metadata.guid = msgGuid;
+            const { id: appId } = await this.engine.getVID();
+            //═══ Step 1: Inception (atomic job creation + GUID seed) ═══
+            const txn1 = this.store.transact();
+            await this.store.setStateNX(this.context.metadata.jid, appId, initialStatus, options?.entity || resolvedEntity, txn1);
+            await this.store.collateSynthetic(this.context.metadata.jid, msgGuid, collator_1.CollatorService.WEIGHTS.STEP1_WORK, txn1);
+            const results1 = (await txn1.exec());
+            const jobCreated = Number(results1[0]) > 0;
+            const guidValue = Number(results1[1]);
+            if (!jobCreated) {
+                if (guidValue > collator_1.CollatorService.WEIGHTS.STEP1_WORK) {
+                    //crash recovery: GUID was seeded on a prior attempt; resume
+                    this.guidLedger = guidValue;
+                    this.logger.info('trigger-crash-recovery', {
+                        job_id: this.context.metadata.jid,
+                        guid: msgGuid,
+                        guidLedger: guidValue,
+                    });
+                }
+                else {
+                    //true duplicate: another process owns this job
+                    throw new errors_1.DuplicateJobError(this.context.metadata.jid);
+                }
+            }
             await this.setStatus(initialStatus);
             this.bindSearchData(options);
             this.bindMarkerData(options);
-            const transaction = this.store.transact();
-            await this.setState(transaction);
-            await this.setStats(transaction);
-            if (options?.pending) {
-                await this.setExpired(options?.pending, transaction);
+            //═══ Step 2: Work (state + children + GUID Step 2) ═══
+            if (!collator_1.CollatorService.isGuidStep2Done(this.guidLedger)) {
+                const txn2 = this.store.transact();
+                await this.setState(txn2);
+                await this.setStats(txn2);
+                if (options?.pending) {
+                    await this.setExpired(options.pending, txn2);
+                }
+                //publish children (unless pending or job already complete)
+                if (isNaN(options?.pending) && this.adjacencyList.length && initialStatus > 0) {
+                    for (const child of this.adjacencyList) {
+                        await this.engine.router?.publishMessage(null, child, txn2);
+                    }
+                }
+                await collator_1.CollatorService.notarizeStep2(this, msgGuid, txn2);
+                await txn2.exec();
             }
-            await collator_1.CollatorService.notarizeInception(this, this.context.metadata.guid, transaction);
-            await transaction.exec();
+            //best-effort parent notification
             this.execAdjacentParent();
-            telemetry.mapActivityAttributes();
+            //═══ Step 3: Completion (if job immediately complete) ═══
+            //NOTE: runJobCompletionTasks is non-transactional here because
+            //the trigger runs inline within pub(). Subscribers register AFTER
+            //pub() returns, so pub notifications must be fire-and-forget to
+            //avoid a race. The GUID marker commits in its own transaction.
             const jobStatus = Number(this.context.metadata.js);
+            const needsCompletion = this.shouldEmit() ||
+                this.isJobComplete(jobStatus) ||
+                this.shouldPersistJob();
+            if (needsCompletion && !collator_1.CollatorService.isGuidStep3Done(this.guidLedger)) {
+                await this.engine.runJobCompletionTasks(this.context, { emit: !this.isJobComplete(jobStatus) && !this.shouldPersistJob() });
+                //NOTE: notarizeStep3 is fire-and-forget for the trigger.
+                //pubOneTimeSubs (inside runJobCompletionTasks) sends a NOTIFY
+                //that must not be processed until registerJobCallback runs
+                //AFTER pub() returns. An `await` here yields to the event loop,
+                //which could deliver the NOTIFY before the callback is registered.
+                const txn3 = this.store.transact();
+                collator_1.CollatorService.notarizeStep3(this, msgGuid, txn3)
+                    .then(() => txn3.exec())
+                    .catch((err) => this.logger.error('trigger-notarize-step3-error', { error: err }));
+            }
+            //telemetry
+            telemetry.mapActivityAttributes();
             telemetry.setJobAttributes({ 'app.job.jss': jobStatus });
             const attrs = { 'app.job.jss': jobStatus };
-            await this.transitionAndLogAdjacent(options, jobStatus, attrs);
             telemetry.setActivityAttributes(attrs);
             return this.context.metadata.jid;
         }
         catch (error) {
             telemetry?.setActivityError(error.message);
             if (error instanceof errors_1.DuplicateJobError) {
-                //todo: verify baseline in x-AZ rollover
-                await (0, utils_1.sleepFor)(1000);
-                const isOverage = await collator_1.CollatorService.isInceptionOverage(this, this.context.metadata.guid);
-                if (isOverage) {
-                    this.logger.info('trigger-collation-overage', {
-                        job_id: error.jobId,
-                        guid: this.context.metadata.guid,
-                    });
-                    return;
-                }
                 this.logger.error('duplicate-job-error', {
                     job_id: error.jobId,
                     guid: this.context.metadata.guid,
@@ -84,15 +183,6 @@ class Trigger extends activity_1.Activity {
             });
         }
     }
-    async transitionAndLogAdjacent(options = {}, jobStatus, attrs) {
-        //todo: enable resume from pending state
-        if (isNaN(options.pending)) {
-            const messageIds = await this.transition(this.adjacencyList, jobStatus);
-            if (messageIds.length) {
-                attrs['app.activity.mids'] = messageIds.join(',');
-            }
-        }
-    }
     /**
      * `pending` flows will not transition from the trigger to adjacent children until resumed
      */
@@ -231,12 +321,6 @@ class Trigger extends activity_1.Activity {
         const jobKey = this.config.stats?.key;
         return jobKey ? pipe_1.Pipe.resolve(jobKey, context) : '';
     }
-    async setStateNX(status, entity) {
-        const jobId = this.context.metadata.jid;
-        if (!await this.store.setStateNX(jobId, this.engine.appId, status, entity)) {
-            throw new errors_1.DuplicateJobError(jobId);
-        }
-    }
     async setStats(transaction) {
         const md = this.context.metadata;
         if (md.key && this.config.stats?.measures) {

package/build/services/activities/worker.d.ts

@@ -3,6 +3,113 @@ import { ActivityData, ActivityMetadata, ActivityType, WorkerActivity } from '..
 import { JobState } from '../../types/job';
 import { ProviderTransaction } from '../../types/provider';
 import { Activity } from './activity';
+/**
+ * Dispatches work to a registered callback function. The `worker` activity
+ * publishes a message to its configured `topic` stream, where a worker
+ * process picks it up, executes the callback, and returns a response
+ * that the engine captures as the activity's output.
+ *
+ * ## YAML Configuration
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: order.placed
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         a1:
+ *           type: worker
+ *           topic: work.do              # matches the registered worker topic
+ *           input:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 x: { type: string }
+ *             maps:
+ *               x: '{t1.output.data.inputField}'
+ *           output:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 y: { type: string }
+ *           job:
+ *             maps:
+ *               result: '{$self.output.data.y}'
+ *
+ *       transitions:
+ *         t1:
+ *           - to: a1
+ * ```
+ *
+ * ## Worker Registration (JavaScript)
+ *
+ * Workers are registered at initialization time via the `workers` array
+ * in `HotMesh.init`. Each worker binds a `topic` to a `callback` function.
+ *
+ * ```typescript
+ * const hotMesh = await HotMesh.init({
+ *   appId: 'myapp',
+ *   engine: { connection },
+ *   workers: [{
+ *     topic: 'work.do',
+ *     connection,
+ *     callback: async (data: StreamData) => ({
+ *       metadata: { ...data.metadata },
+ *       data: { y: `${data.data.x} transformed` }
+ *     })
+ *   }]
+ * });
+ * ```
+ *
+ * ## Retry Policy
+ *
+ * Retry behavior is configured at the **worker level** (not in YAML) via
+ * the `retryPolicy` option. Failed callbacks are retried with exponential
+ * backoff until `maximumAttempts` is exhausted. The `maximumInterval` caps
+ * the delay between retries.
+ *
+ * ```typescript
+ * const hotMesh = await HotMesh.init({
+ *   appId: 'myapp',
+ *   engine: { connection },
+ *   workers: [{
+ *     topic: 'work.backoff',
+ *     connection,
+ *     retryPolicy: {
+ *       maximumAttempts: 5,          // retry up to 5 times
+ *       backoffCoefficient: 2,       // exponential: 2^0, 2^1, 2^2, ... seconds
+ *       maximumInterval: '30s',      // cap delay at 30 seconds
+ *     },
+ *     callback: async (data: StreamData) => {
+ *       const result = await doWork(data.data);
+ *       return {
+ *         code: 200,
+ *         status: StreamStatus.SUCCESS,
+ *         metadata: { ...data.metadata },
+ *         data: { result },
+ *       } as StreamDataResponse;
+ *     },
+ *   }]
+ * });
+ * ```
+ *
+ * ## Execution Model
+ *
+ * Worker is a **Category A (duplex)** activity:
+ * - **Leg 1** (`process`): Maps input data and publishes a message to the
+ *   worker's topic stream.
+ * - **Leg 2** (`processEvent`, inherited): Receives the worker's response,
+ *   maps output data, and executes the step protocol to transition to
+ *   adjacent activities.
+ *
+ * @see {@link WorkerActivity} for the TypeScript interface
+ */
 declare class Worker extends Activity {
     config: WorkerActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);

package/build/services/activities/worker.js

@@ -7,6 +7,113 @@ const collator_1 = require("../collator");
 const pipe_1 = require("../pipe");
 const telemetry_1 = require("../telemetry");
 const activity_1 = require("./activity");
+/**
+ * Dispatches work to a registered callback function. The `worker` activity
+ * publishes a message to its configured `topic` stream, where a worker
+ * process picks it up, executes the callback, and returns a response
+ * that the engine captures as the activity's output.
+ *
+ * ## YAML Configuration
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: order.placed
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         a1:
+ *           type: worker
+ *           topic: work.do              # matches the registered worker topic
+ *           input:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 x: { type: string }
+ *             maps:
+ *               x: '{t1.output.data.inputField}'
+ *           output:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 y: { type: string }
+ *           job:
+ *             maps:
+ *               result: '{$self.output.data.y}'
+ *
+ *       transitions:
+ *         t1:
+ *           - to: a1
+ * ```
+ *
+ * ## Worker Registration (JavaScript)
+ *
+ * Workers are registered at initialization time via the `workers` array
+ * in `HotMesh.init`. Each worker binds a `topic` to a `callback` function.
+ *
+ * ```typescript
+ * const hotMesh = await HotMesh.init({
+ *   appId: 'myapp',
+ *   engine: { connection },
+ *   workers: [{
+ *     topic: 'work.do',
+ *     connection,
+ *     callback: async (data: StreamData) => ({
+ *       metadata: { ...data.metadata },
+ *       data: { y: `${data.data.x} transformed` }
+ *     })
+ *   }]
+ * });
+ * ```
+ *
+ * ## Retry Policy
+ *
+ * Retry behavior is configured at the **worker level** (not in YAML) via
+ * the `retryPolicy` option. Failed callbacks are retried with exponential
+ * backoff until `maximumAttempts` is exhausted. The `maximumInterval` caps
+ * the delay between retries.
+ *
+ * ```typescript
+ * const hotMesh = await HotMesh.init({
+ *   appId: 'myapp',
+ *   engine: { connection },
+ *   workers: [{
+ *     topic: 'work.backoff',
+ *     connection,
+ *     retryPolicy: {
+ *       maximumAttempts: 5,          // retry up to 5 times
+ *       backoffCoefficient: 2,       // exponential: 2^0, 2^1, 2^2, ... seconds
+ *       maximumInterval: '30s',      // cap delay at 30 seconds
+ *     },
+ *     callback: async (data: StreamData) => {
+ *       const result = await doWork(data.data);
+ *       return {
+ *         code: 200,
+ *         status: StreamStatus.SUCCESS,
+ *         metadata: { ...data.metadata },
+ *         data: { result },
+ *       } as StreamDataResponse;
+ *     },
+ *   }]
+ * });
+ * ```
+ *
+ * ## Execution Model
+ *
+ * Worker is a **Category A (duplex)** activity:
+ * - **Leg 1** (`process`): Maps input data and publishes a message to the
+ *   worker's topic stream.
+ * - **Leg 2** (`processEvent`, inherited): Receives the worker's response,
+ *   maps output data, and executes the step protocol to transition to
+ *   adjacent activities.
+ *
+ * @see {@link WorkerActivity} for the TypeScript interface
+ */
 class Worker extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);

package/build/services/collator/index.d.ts

@@ -91,18 +91,11 @@ declare class CollatorService {
      */
     static notarizeStep3(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
     /**
-     * Finalize: close the activity to new Leg2 GUIDs (+10T).
+     * Finalize: close the activity to new Leg2 GUIDs (+200T).
+     * Sets pos 1 to 2 (finalized).
      * Only for non-cycle activities after final SUCCESS/ERROR.
      */
     static notarizeFinalize(activity: Activity, transaction: ProviderTransaction): Promise<void>;
-    /**
-     * sets the synthetic inception key (in case an overage occurs).
-     */
-    static notarizeInception(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
-    /**
-     * ignore those ID collisions that are due to re-entry overages
-     */
-    static isInceptionOverage(activity: Activity, guid: string): Promise<boolean>;
     /**
      * Check if Step 1 (work done) is complete on the GUID ledger.
      * Position 5 (10B digit) > 0.
@@ -159,15 +152,10 @@ declare class CollatorService {
      *             If pos 3 > 1 and pos 4 == 1, it's a stale/replayed message.
      *
      * Leg2 enter: pos 4 (100B) must be > 0 (Leg1 complete, reentry authorized).
-     *             pos 2 (10T) must be 0 (not finalized) — cycle activities exempt.
+     *             pos 1 (100T) must be < 2 (not finalized) — cycle activities exempt.
      */
     static verifyInteger(amount: number, leg: ActivityDuplex, stage: CollationStage): void;
     static getDimensionsById(ancestors: string[], dad: string): Record<string, string>;
-    /**
-     * All non-trigger activities are assigned a status seed by their parent.
-     * Seed: 100000000000000 (pos 1 = 1, authorized for entry)
-     */
-    static getSeed(): string;
     /**
      * All trigger activities are assigned a status seed in a completed state.
      * Seed: 101100000000001 (authorized, 1 Leg1 entry, Leg1 complete, 1 Leg2 entry)

package/build/services/collator/index.js

@@ -131,7 +131,8 @@ class CollatorService {
         await activity.store.collateSynthetic(jid, guid, this.WEIGHTS.STEP3_CLEANUP, transaction);
     }
     /**
-     * Finalize: close the activity to new Leg2 GUIDs (+10T).
+     * Finalize: close the activity to new Leg2 GUIDs (+200T).
+     * Sets pos 1 to 2 (finalized).
      * Only for non-cycle activities after final SUCCESS/ERROR.
      */
     static async notarizeFinalize(activity, transaction) {
@@ -140,27 +141,6 @@ class CollatorService {
         }
     }
     // ──────────────────────────────────────────────────
-    //  Inception (trigger duplicate detection)
-    // ──────────────────────────────────────────────────
-    /**
-     * sets the synthetic inception key (in case an overage occurs).
-     */
-    static async notarizeInception(activity, guid, transaction) {
-        if (guid) {
-            await activity.store.collateSynthetic(activity.context.metadata.jid, guid, 1000000, transaction);
-        }
-    }
-    /**
-     * ignore those ID collisions that are due to re-entry overages
-     */
-    static async isInceptionOverage(activity, guid) {
-        if (guid) {
-            const amount = await activity.store.collateSynthetic(activity.context.metadata.jid, guid, 1000000);
-            return amount > 1000000;
-        }
-        return false;
-    }
-    // ──────────────────────────────────────────────────
     //  GUID ledger extraction (step-level resume)
     // ──────────────────────────────────────────────────
     /**
@@ -270,7 +250,7 @@ class CollatorService {
      *             If pos 3 > 1 and pos 4 == 1, it's a stale/replayed message.
      *
      * Leg2 enter: pos 4 (100B) must be > 0 (Leg1 complete, reentry authorized).
-     *             pos 2 (10T) must be 0 (not finalized) — cycle activities exempt.
+     *             pos 1 (100T) must be < 2 (not finalized) — cycle activities exempt.
      */
     static verifyInteger(amount, leg, stage) {
         let faultType;
@@ -288,13 +268,13 @@ class CollatorService {
         }
         else if (leg === 2 && stage === 'enter') {
             const leg1Complete = this.getDigitAtPosition(amount, 4);
-            const finalized = this.getDigitAtPosition(amount, 2);
+            const finalized = this.getDigitAtPosition(amount, 1);
             if (leg1Complete === 0) {
                 //Leg1 not complete — reentry not authorized
                 faultType = collator_1.CollationFaultType.FORBIDDEN;
             }
-            else if (finalized > 0) {
-                //activity finalized — no new Leg2 GUIDs accepted
+            else if (finalized >= 2) {
+                //activity finalized (pos 1 = 2) — no new Leg2 GUIDs accepted
                 faultType = collator_1.CollationFaultType.INACTIVE;
             }
         }
@@ -322,13 +302,6 @@ class CollatorService {
     // ──────────────────────────────────────────────────
     //  Seeds
     // ──────────────────────────────────────────────────
-    /**
-     * All non-trigger activities are assigned a status seed by their parent.
-     * Seed: 100000000000000 (pos 1 = 1, authorized for entry)
-     */
-    static getSeed() {
-        return '100000000000000';
-    }
     /**
      * All trigger activities are assigned a status seed in a completed state.
      * Seed: 101100000000001 (authorized, 1 Leg1 entry, Leg1 complete, 1 Leg2 entry)
@@ -405,7 +378,7 @@ CollatorService.targetLength = 15;
  */
 CollatorService.WEIGHTS = {
     AUTH: 100000000000000,
-    FINALIZE: 10000000000000,
+    FINALIZE: 200000000000000,
     LEG1_ENTRY: 1000000000000,
     LEG1_COMPLETE: 100000000000,
     STEP1_WORK: 10000000000,

package/build/services/engine/index.d.ts

@@ -31,11 +31,17 @@ declare class EngineService {
     appId: string;
     guid: string;
     exporter: ExporterService | null;
+    /** @hidden */
     search: SearchService<ProviderClient> | null;
+    /** @hidden */
     store: StoreService<ProviderClient, ProviderTransaction> | null;
+    /** @hidden */
     stream: StreamService<ProviderClient, ProviderTransaction> | null;
+    /** @hidden */
     subscribe: SubService<ProviderClient> | null;
+    /** @hidden */
     router: Router<typeof this.stream> | null;
+    /** @hidden */
     taskService: TaskService | null;
     logger: ILogger;
     cacheMode: CacheMode;
@@ -161,17 +167,27 @@ declare class EngineService {
      */
     scrub(jobId: string): Promise<void>;
     /**
+     * Delivers a signal (data payload) to a paused hook activity,
+     * resuming its Leg 2 execution. The `topic` must match a hook rule
+     * defined in the YAML graph's `hooks` section. The engine locates
+     * the target activity and dimension for reentry based on the hook
+     * rule's match conditions.
+     *
      * @private
      */
-    hook(topic: string, data: JobData, status?: StreamStatus, code?: StreamCode, transaction?: ProviderTransaction): Promise<string>;
+    signal(topic: string, data: JobData, status?: StreamStatus, code?: StreamCode, transaction?: ProviderTransaction): Promise<string>;
     /**
      * @private
      */
     hookTime(jobId: string, gId: string, topicOrActivity: string, type?: WorkListTaskType): Promise<string | void>;
     /**
+     * Fan-out variant of `signal()` that delivers data to **all**
+     * paused workflows matching a search query. Useful for resuming
+     * a batch of workflows waiting on the same external event.
+     *
      * @private
      */
-    hookAll(hookTopic: string, data: JobData, keyResolver: JobStatsInput, queryFacets?: string[]): Promise<string[]>;
+    signalAll(hookTopic: string, data: JobData, keyResolver: JobStatsInput, queryFacets?: string[]): Promise<string[]>;
     /**
      * @private
      */