@hotmeshio/hotmesh 0.7.0 → 0.9.0

package/build/services/activities/hook.js

@@ -9,7 +9,145 @@ const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
 const activity_1 = require("./activity");
 /**
- * Supports `signal hook`, `time hook`, and `cycle hook` patterns
+ * A versatile pause/resume activity that supports three distinct patterns:
+ * **time hook** (sleep), **web hook** (external signal), and **passthrough**
+ * (immediate transition with optional data mapping).
+ *
+ * The hook activity is the most flexible activity type. Depending on its
+ * YAML configuration, it operates in one of the following modes:
+ *
+ * ## Time Hook (Sleep)
+ *
+ * Pauses the flow for a specified duration in seconds. The `sleep` value
+ * can be a literal number or a `@pipe` expression for dynamic delays
+ * (e.g., exponential backoff).
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: job.start
+ *       expire: 300
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         delay:
+ *           type: hook
+ *           sleep: 60                        # pause for 60 seconds
+ *           job:
+ *             maps:
+ *               paused_at: '{$self.output.metadata.ac}'
+ *
+ *         resume:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: delay
+ *         delay:
+ *           - to: resume
+ * ```
+ *
+ * ## Web Hook (External Signal)
+ *
+ * Registers a webhook listener on a named topic. The flow pauses until
+ * an external signal is sent to the hook's topic. The signal data becomes
+ * available as `$self.hook.data`. The `hooks` section at the graph level
+ * routes incoming signals to the waiting activity.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: order.placed
+ *       expire: 3600
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         wait_for_approval:
+ *           type: hook
+ *           hook:
+ *             type: object
+ *             properties:
+ *               approved: { type: boolean }
+ *           job:
+ *             maps:
+ *               approved: '{$self.hook.data.approved}'
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: wait_for_approval
+ *         wait_for_approval:
+ *           - to: done
+ *
+ *       hooks:
+ *         order.approval:                    # external topic that delivers the signal
+ *           - to: wait_for_approval
+ *             conditions:
+ *               match:
+ *                 - expected: '{t1.output.data.id}'
+ *                   actual: '{$self.hook.data.id}'
+ * ```
+ *
+ * ## Passthrough (No Hook)
+ *
+ * When neither `sleep` nor `hook` is configured, the hook activity acts
+ * as a passthrough: it maps data and immediately transitions to children.
+ * This is useful for data transformation, convergence points, or as a
+ * cycle pivot (with `cycle: true`).
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: job.start
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         pivot:
+ *           type: hook
+ *           cycle: true                      # enables re-entry from a cycle activity
+ *           output:
+ *             maps:
+ *               retryCount: 0
+ *           job:
+ *             maps:
+ *               counter: '{$self.output.data.retryCount}'
+ *
+ *         do_work:
+ *           type: worker
+ *           topic: work.do
+ *
+ *       transitions:
+ *         t1:
+ *           - to: pivot
+ *         pivot:
+ *           - to: do_work
+ * ```
+ *
+ * ## Execution Model
+ *
+ * - **With `sleep` or `hook`**: Category A (duplex). Leg 1 registers the
+ *   hook and saves state. Leg 2 fires when the timer expires or the
+ *   external signal arrives (via `processTimeHookEvent` or
+ *   `processWebHookEvent`).
+ * - **Without `sleep` or `hook`**: Category B (passthrough). Uses the
+ *   crash-safe `executeLeg1StepProtocol` to map data and transition
+ *   to adjacent activities.
+ *
+ * @see {@link HookActivity} for the TypeScript interface
  */
 class Hook extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
@@ -24,15 +162,21 @@ class Hook extends activity_1.Activity {
         });
         let telemetry;
         try {
-            await this.verifyEntry();
+            //Phase 1: Load state and verify entry (all paths use verifyLeg1Entry
+            //for GUID-ledger-backed crash recovery)
+            const isResume = await this.verifyLeg1Entry();
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
-            if (this.doesHook()) {
-                //sleep and wait to awaken upon a signal
-                await this.doHook(telemetry);
+            //Phase 2: Route based on RUNTIME evaluation (not static config)
+            if (this.isConfiguredAsHook() && this.doesHook()) {
+                //Category A: duplexed hook registration (Leg2 handles completion)
+                if (!isResume) {
+                    await this.doHook(telemetry);
+                }
+                //If resume, Leg1 already ran — Leg2 will handle completion
             }
             else {
-                //end the activity and transition to its children
+                //Category B: passthrough with crash-safe step protocol + GUID ledger
                 await this.doPassThrough(telemetry);
             }
             return this.context.metadata.aid;
@@ -76,6 +220,13 @@ class Hook extends activity_1.Activity {
             });
         }
     }
+    /**
+     * Static config check: does this activity have a hook or sleep config?
+     * Used for routing before context is loaded.
+     */
+    isConfiguredAsHook() {
+        return !!this.config.sleep || !!this.config.hook?.topic;
+    }
     /**
      * does this activity use a time-hook or web-hook
      */
@@ -92,29 +243,19 @@ class Hook extends activity_1.Activity {
         this.mapOutputData();
         this.mapJobData();
         await this.setState(transaction);
-        await collator_1.CollatorService.authorizeReentry(this, transaction);
+        await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
         await this.setStatus(0, transaction);
         await transaction.exec();
         telemetry.mapActivityAttributes();
     }
     async doPassThrough(telemetry) {
-        const transaction = this.store.transact();
-        let multiResponse;
         this.adjacencyList = await this.filterAdjacent();
         this.mapOutputData();
         this.mapJobData();
-        await this.setState(transaction);
-        await collator_1.CollatorService.notarizeEarlyCompletion(this, transaction);
-        await this.setStatus(this.adjacencyList.length - 1, transaction);
-        multiResponse = (await transaction.exec());
+        //Category B: use Leg1 step protocol for crash-safe edge capture
+        await this.executeLeg1StepProtocol(this.adjacencyList.length - 1);
         telemetry.mapActivityAttributes();
-        const jobStatus = this.resolveStatus(multiResponse);
-        const attrs = { 'app.job.jss': jobStatus };
-        const messageIds = await this.transition(this.adjacencyList, jobStatus);
-        if (messageIds.length) {
-            attrs['app.activity.mids'] = messageIds.join(',');
-        }
-        telemetry.setActivityAttributes(attrs);
+        telemetry.setActivityAttributes({});
     }
     async getHookRule(topic) {
         const rules = await this.store.getHookRules();
@@ -126,7 +267,7 @@ class Hook extends activity_1.Activity {
         }
         else if (this.config.sleep) {
             const duration = pipe_1.Pipe.resolve(this.config.sleep, this.context);
-            await this.engine.taskService.registerTimeHook(this.context.metadata.jid, this.context.metadata.gid, `${this.metadata.aid}${this.metadata.dad || ''}`, 'sleep', duration, this.metadata.dad || '');
+            await this.engine.taskService.registerTimeHook(this.context.metadata.jid, this.context.metadata.gid, `${this.metadata.aid}${this.metadata.dad || ''}`, 'sleep', duration, this.metadata.dad || '', transaction);
             return this.context.metadata.jid;
         }
     }

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

@@ -3,6 +3,118 @@ import { TelemetryService } from '../telemetry';
 import { ActivityData, ActivityMetadata, ActivityType, InterruptActivity } from '../../types/activity';
 import { JobInterruptOptions, JobState } from '../../types/job';
 import { Activity } from './activity';
+/**
+ * Terminates a flow by sending an interrupt signal. The `interrupt` activity
+ * can target the current flow (self-interrupt) or any other flow by its
+ * job ID (remote interrupt). Interrupted jobs have their status set to a
+ * value less than -100,000,000, indicating abnormal termination.
+ *
+ * ## YAML Configuration — Self-Interrupt
+ *
+ * When no `target` is specified, the activity interrupts the current flow.
+ * The flow terminates immediately after this activity executes. Use
+ * conditional transitions to route to an interrupt only when needed.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: validation.check
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         validate:
+ *           type: worker
+ *           topic: validate.input
+ *
+ *         cancel:
+ *           type: interrupt
+ *           reason: 'Validation failed'
+ *           throw: true
+ *           code: 410
+ *           job:
+ *             maps:
+ *               cancelled_at: '{$self.output.metadata.ac}'
+ *
+ *         proceed:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: validate
+ *         validate:
+ *           - to: cancel
+ *             conditions:
+ *               code: 422               # interrupt only on validation failure
+ *           - to: proceed
+ * ```
+ *
+ * ## YAML Configuration — Remote Interrupt
+ *
+ * When `target` is specified, the activity interrupts another flow while
+ * the current flow continues to transition to adjacent activities.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: parent.flow
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *           job:
+ *             maps:
+ *               childJobId: '{$self.output.data.childJobId}'
+ *
+ *         stop_child:
+ *           type: interrupt
+ *           topic: child.flow.topic     # topic of the target flow
+ *           target: '{t1.output.data.childJobId}'
+ *           throw: false                # do not throw (silent cancellation)
+ *           descend: true               # also interrupt descendant sub-flows
+ *           job:
+ *             maps:
+ *               interrupted: true
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: stop_child
+ *         stop_child:
+ *           - to: done
+ * ```
+ *
+ * ## Configuration Properties
+ *
+ * | Property   | Type    | Default            | Description |
+ * |------------|---------|--------------------|-------------|
+ * | `target`   | string  | (current job)      | Job ID to interrupt. Supports `@pipe` expressions. |
+ * | `topic`    | string  | (current topic)    | Topic of the target flow |
+ * | `reason`   | string  | `'Job Interrupted'`| Error message attached to the interruption |
+ * | `throw`    | boolean | `true`             | Whether to throw a `JobInterrupted` error |
+ * | `descend`  | boolean | `false`            | Whether to cascade to child/descendant flows |
+ * | `code`     | number  | `410`              | Error code attached to the interruption |
+ * | `stack`    | string  | —                  | Optional stack trace |
+ *
+ * ## Execution Model
+ *
+ * - **Self-interrupt (no `target`)**: Category C. Verifies entry, maps job
+ *   data, sets status to -1, and fires the interrupt. No children.
+ * - **Remote interrupt (with `target`)**: Category B. Fires the interrupt
+ *   best-effort, then uses `executeLeg1StepProtocol` to transition to
+ *   adjacent activities.
+ *
+ * @see {@link InterruptActivity} for the TypeScript interface
+ */
 declare class Interrupt extends Activity {
     config: InterruptActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);

package/build/services/activities/interrupt.js

@@ -6,6 +6,118 @@ const collator_1 = require("../collator");
 const pipe_1 = require("../pipe");
 const telemetry_1 = require("../telemetry");
 const activity_1 = require("./activity");
+/**
+ * Terminates a flow by sending an interrupt signal. The `interrupt` activity
+ * can target the current flow (self-interrupt) or any other flow by its
+ * job ID (remote interrupt). Interrupted jobs have their status set to a
+ * value less than -100,000,000, indicating abnormal termination.
+ *
+ * ## YAML Configuration — Self-Interrupt
+ *
+ * When no `target` is specified, the activity interrupts the current flow.
+ * The flow terminates immediately after this activity executes. Use
+ * conditional transitions to route to an interrupt only when needed.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: validation.check
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         validate:
+ *           type: worker
+ *           topic: validate.input
+ *
+ *         cancel:
+ *           type: interrupt
+ *           reason: 'Validation failed'
+ *           throw: true
+ *           code: 410
+ *           job:
+ *             maps:
+ *               cancelled_at: '{$self.output.metadata.ac}'
+ *
+ *         proceed:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: validate
+ *         validate:
+ *           - to: cancel
+ *             conditions:
+ *               code: 422               # interrupt only on validation failure
+ *           - to: proceed
+ * ```
+ *
+ * ## YAML Configuration — Remote Interrupt
+ *
+ * When `target` is specified, the activity interrupts another flow while
+ * the current flow continues to transition to adjacent activities.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: parent.flow
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *           job:
+ *             maps:
+ *               childJobId: '{$self.output.data.childJobId}'
+ *
+ *         stop_child:
+ *           type: interrupt
+ *           topic: child.flow.topic     # topic of the target flow
+ *           target: '{t1.output.data.childJobId}'
+ *           throw: false                # do not throw (silent cancellation)
+ *           descend: true               # also interrupt descendant sub-flows
+ *           job:
+ *             maps:
+ *               interrupted: true
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: stop_child
+ *         stop_child:
+ *           - to: done
+ * ```
+ *
+ * ## Configuration Properties
+ *
+ * | Property   | Type    | Default            | Description |
+ * |------------|---------|--------------------|-------------|
+ * | `target`   | string  | (current job)      | Job ID to interrupt. Supports `@pipe` expressions. |
+ * | `topic`    | string  | (current topic)    | Topic of the target flow |
+ * | `reason`   | string  | `'Job Interrupted'`| Error message attached to the interruption |
+ * | `throw`    | boolean | `true`             | Whether to throw a `JobInterrupted` error |
+ * | `descend`  | boolean | `false`            | Whether to cascade to child/descendant flows |
+ * | `code`     | number  | `410`              | Error code attached to the interruption |
+ * | `stack`    | string  | —                  | Optional stack trace |
+ *
+ * ## Execution Model
+ *
+ * - **Self-interrupt (no `target`)**: Category C. Verifies entry, maps job
+ *   data, sets status to -1, and fires the interrupt. No children.
+ * - **Remote interrupt (with `target`)**: Category B. Fires the interrupt
+ *   best-effort, then uses `executeLeg1StepProtocol` to transition to
+ *   adjacent activities.
+ *
+ * @see {@link InterruptActivity} for the TypeScript interface
+ */
 class Interrupt extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
@@ -19,13 +131,18 @@ class Interrupt extends activity_1.Activity {
         });
         let telemetry;
         try {
-            await this.verifyEntry();
-            telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
-            telemetry.startActivitySpan(this.leg);
-            if (this.isInterruptingSelf()) {
+            if (!this.config.target) {
+                //Category C: self-interrupt (no children, no semaphore edge risk)
+                await this.verifyEntry();
+                telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
+                telemetry.startActivitySpan(this.leg);
                 await this.interruptSelf(telemetry);
             }
             else {
+                //Category B: interrupt another (spawns children, needs step protocol)
+                await this.verifyLeg1Entry();
+                telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
+                telemetry.startActivitySpan(this.leg);
                 await this.interruptAnother(telemetry);
             }
         }
@@ -69,20 +186,21 @@ class Interrupt extends activity_1.Activity {
         }
     }
     async interruptSelf(telemetry) {
-        // Apply final updates to THIS job's state
         if (this.config.job?.maps) {
             this.mapJobData();
-            await this.setState();
         }
-        // Interrupt THIS job
-        const messageId = await this.interrupt();
-        // Notarize completion and log
+        // Bundle state + Leg1 completion + semaphore in one transaction
         telemetry.mapActivityAttributes();
         const transaction = this.store.transact();
-        await collator_1.CollatorService.notarizeEarlyCompletion(this, transaction);
+        if (this.config.job?.maps) {
+            await this.setState(transaction);
+        }
+        await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
         await this.setStatus(-1, transaction);
         const txResponse = (await transaction.exec());
         const jobStatus = this.resolveStatus(txResponse);
+        // Interrupt fires AFTER proof commits (best-effort)
+        const messageId = await this.interrupt();
         telemetry.setActivityAttributes({
             'app.activity.mid': messageId,
             'app.job.jss': jobStatus,
@@ -90,31 +208,18 @@ class Interrupt extends activity_1.Activity {
         return this.context.metadata.aid;
     }
     async interruptAnother(telemetry) {
-        // Interrupt ANOTHER job
-        const messageId = await this.interrupt();
-        const attrs = { 'app.activity.mid': messageId };
+        // Interrupt ANOTHER job (best-effort, fires before step protocol)
+        await this.interrupt();
         // Apply updates to THIS job's state
-        telemetry.mapActivityAttributes();
         this.adjacencyList = await this.filterAdjacent();
         if (this.config.job?.maps || this.config.output?.maps) {
             this.mapOutputData();
             this.mapJobData();
-            const transaction = this.store.transact();
-            await this.setState(transaction);
-        }
-        // Notarize completion
-        const transaction = this.store.transact();
-        await collator_1.CollatorService.notarizeEarlyCompletion(this, transaction);
-        await this.setStatus(this.adjacencyList.length - 1, transaction);
-        const txResponse = (await transaction.exec());
-        const jobStatus = this.resolveStatus(txResponse);
-        attrs['app.job.jss'] = jobStatus;
-        // Transition next generation and log
-        const messageIds = await this.transition(this.adjacencyList, jobStatus);
-        if (messageIds.length) {
-            attrs['app.activity.mids'] = messageIds.join(',');
         }
-        telemetry.setActivityAttributes(attrs);
+        //Category B: use Leg1 step protocol for crash-safe edge capture
+        await this.executeLeg1StepProtocol(this.adjacencyList.length - 1);
+        telemetry.mapActivityAttributes();
+        telemetry.setActivityAttributes({});
         return this.context.metadata.aid;
     }
     isInterruptingSelf() {

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

@@ -1,7 +1,113 @@
 import { EngineService } from '../engine';
 import { ActivityData, ActivityMetadata, ActivityType, SignalActivity } from '../../types/activity';
 import { JobState } from '../../types/job';
+import { ProviderTransaction } from '../../types/provider';
 import { Activity } from './activity';
+/**
+ * Sends a signal to one or more paused flows, resuming their execution.
+ * The `signal` activity is the counterpart to a `Hook` activity
+ * configured with a webhook listener. It allows any flow to reach into
+ * another flow and deliver data to a waiting hook, regardless of the
+ * relationship between the flows.
+ *
+ * ## YAML Configuration — Signal One
+ *
+ * Resumes a single paused flow by publishing to the hook's topic. Use
+ * `subtype: one` when you know the specific hook topic to signal.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: signal.start
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         resume_hook:
+ *           type: signal
+ *           subtype: one
+ *           topic: my.hook.topic          # the hook's registered topic
+ *           status: success               # optional: success (default) or pending
+ *           code: 200                     # optional: 200 (default) or 202 (keep-alive)
+ *           signal:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 approved: { type: boolean }
+ *             maps:
+ *               approved: true            # data delivered to the hook
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: resume_hook
+ *         resume_hook:
+ *           - to: done
+ * ```
+ *
+ * A `code: 202` signal delivers data but keeps the hook alive for
+ * additional signals. A `code: 200` (default) closes the hook.
+ *
+ * ## YAML Configuration — Signal All
+ *
+ * Resumes all paused flows that share a common job key facet. Use
+ * `subtype: all` for fan-out patterns where multiple waiting flows
+ * should be resumed simultaneously.
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: signal.fan.out
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         resume_all:
+ *           type: signal
+ *           subtype: all
+ *           topic: hook.resume
+ *           key_name: parent_job_id       # index facet name
+ *           key_value: '{$job.metadata.jid}'
+ *           scrub: true                   # clean up indexes after use
+ *           resolver:
+ *             maps:
+ *               data:
+ *                 parent_job_id: '{$job.metadata.jid}'
+ *               scrub: true
+ *           signal:
+ *             maps:
+ *               done: true                # data delivered to all matching hooks
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: resume_all
+ *         resume_all:
+ *           - to: done
+ * ```
+ *
+ * ## Execution Model
+ *
+ * Signal is a **Category B (Leg1-only with children)** activity:
+ * - Bundles the hook signal with the Leg 1 completion marker in a
+ *   single transaction (`hookOne`) or fires best-effort (`hookAll`).
+ * - Executes the crash-safe `executeLeg1StepProtocol` to transition
+ *   to adjacent activities.
+ *
+ * @see {@link SignalActivity} for the TypeScript interface
+ */
 declare class Signal extends Activity {
     config: SignalActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
@@ -9,12 +115,13 @@ declare class Signal extends Activity {
     mapSignalData(): Record<string, any>;
     mapResolverData(): Record<string, any>;
     /**
-     * The signal activity will hook one
+     * The signal activity will hook one. Accepts an optional transaction
+     * so the hook publish can be bundled with the Leg1 completion marker.
      */
-    hookOne(): Promise<string>;
+    signalOne(transaction?: ProviderTransaction): Promise<string>;
     /**
-     * The signal activity will hook all paused jobs that share the same job key.
+     * Signals all paused jobs that share the same job key, resuming their execution.
      */
-    hookAll(): Promise<string[]>;
+    signalAll(): Promise<string[]>;
 }
 export { Signal };