@hotmeshio/hotmesh 0.7.0 → 0.9.0

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

@@ -3,6 +3,107 @@ import { ActivityData, ActivityMetadata, AwaitActivity, ActivityType } from '../
 import { ProviderTransaction } from '../../types/provider';
 import { JobState } from '../../types/job';
 import { Activity } from './activity';
+/**
+ * Invokes another graph (sub-flow) and optionally waits for its completion.
+ * The `await` activity enables compositional workflows where one graph
+ * triggers another by publishing to its `subscribes` topic, creating a
+ * parent-child relationship between flows.
+ *
+ * ## YAML Configuration
+ *
+ * The `topic` in the await activity must match the `subscribes` topic of
+ * the child graph. Both graphs are defined in the same app YAML:
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *
+ *     # ── Parent graph ──────────────────────────────
+ *     - subscribes: order.placed
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *           job:
+ *             maps:
+ *               orderId: '{$self.output.data.id}'
+ *
+ *         a1:
+ *           type: await
+ *           topic: approval.requested  # ◄── targets the child graph's subscribes
+ *           await: true
+ *           input:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 orderId: { type: string }
+ *             maps:
+ *               orderId: '{t1.output.data.id}'
+ *           output:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 approved: { type: boolean }
+ *           job:
+ *             maps:
+ *               approval: '{$self.output.data.approved}'
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: a1
+ *         a1:
+ *           - to: done
+ *
+ *     # ── Child graph (invoked by the await) ────────
+ *     - subscribes: approval.requested  # ◄── matched by the await activity's topic
+ *       publishes: approval.completed
+ *       expire: 60
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *         review:
+ *           type: worker
+ *           topic: approval.review
+ *
+ *       transitions:
+ *         t1:
+ *           - to: review
+ * ```
+ *
+ * ## Fire-and-Forget Mode
+ *
+ * When `await` is explicitly set to `false`, the activity starts the child
+ * flow but does not wait for its completion. The parent flow immediately
+ * continues. The child's `job_id` is returned as the output.
+ *
+ * ```yaml
+ * a1:
+ *   type: await
+ *   topic: background.process
+ *   await: false
+ *   job:
+ *     maps:
+ *       childJobId: '{$self.output.data.job_id}'
+ * ```
+ *
+ * ## Execution Model
+ *
+ * Await is a **Category A (duplex)** activity:
+ * - **Leg 1** (`process`): Maps input data and publishes a
+ *   `StreamDataType.AWAIT` message to the engine stream. The engine
+ *   starts the child flow.
+ * - **Leg 2** (`processEvent`, inherited): Receives the child flow's
+ *   final output, maps output data, and transitions to adjacent activities.
+ *
+ * @see {@link AwaitActivity} for the TypeScript interface
+ */
 declare class Await extends Activity {
     config: AwaitActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);

package/build/services/activities/await.js

@@ -8,6 +8,107 @@ const pipe_1 = require("../pipe");
 const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
 const activity_1 = require("./activity");
+/**
+ * Invokes another graph (sub-flow) and optionally waits for its completion.
+ * The `await` activity enables compositional workflows where one graph
+ * triggers another by publishing to its `subscribes` topic, creating a
+ * parent-child relationship between flows.
+ *
+ * ## YAML Configuration
+ *
+ * The `topic` in the await activity must match the `subscribes` topic of
+ * the child graph. Both graphs are defined in the same app YAML:
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *
+ *     # ── Parent graph ──────────────────────────────
+ *     - subscribes: order.placed
+ *       expire: 120
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *           job:
+ *             maps:
+ *               orderId: '{$self.output.data.id}'
+ *
+ *         a1:
+ *           type: await
+ *           topic: approval.requested  # ◄── targets the child graph's subscribes
+ *           await: true
+ *           input:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 orderId: { type: string }
+ *             maps:
+ *               orderId: '{t1.output.data.id}'
+ *           output:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 approved: { type: boolean }
+ *           job:
+ *             maps:
+ *               approval: '{$self.output.data.approved}'
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: a1
+ *         a1:
+ *           - to: done
+ *
+ *     # ── Child graph (invoked by the await) ────────
+ *     - subscribes: approval.requested  # ◄── matched by the await activity's topic
+ *       publishes: approval.completed
+ *       expire: 60
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *         review:
+ *           type: worker
+ *           topic: approval.review
+ *
+ *       transitions:
+ *         t1:
+ *           - to: review
+ * ```
+ *
+ * ## Fire-and-Forget Mode
+ *
+ * When `await` is explicitly set to `false`, the activity starts the child
+ * flow but does not wait for its completion. The parent flow immediately
+ * continues. The child's `job_id` is returned as the output.
+ *
+ * ```yaml
+ * a1:
+ *   type: await
+ *   topic: background.process
+ *   await: false
+ *   job:
+ *     maps:
+ *       childJobId: '{$self.output.data.job_id}'
+ * ```
+ *
+ * ## Execution Model
+ *
+ * Await is a **Category A (duplex)** activity:
+ * - **Leg 1** (`process`): Maps input data and publishes a
+ *   `StreamDataType.AWAIT` message to the engine stream. The engine
+ *   starts the child flow.
+ * - **Leg 2** (`processEvent`, inherited): Receives the child flow's
+ *   final output, maps output data, and transitions to adjacent activities.
+ *
+ * @see {@link AwaitActivity} for the TypeScript interface
+ */
 class Await extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
@@ -25,11 +126,11 @@ class Await extends activity_1.Activity {
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
             this.mapInputData();
-            //save state and authorize reentry
+            //save state and mark Leg1 complete
             const transaction = this.store.transact();
             //todo: await this.registerTimeout();
             const messageId = await this.execActivity(transaction);
-            await collator_1.CollatorService.authorizeReentry(this, transaction);
+            await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
             await this.setState(transaction);
             await this.setStatus(0, transaction);
             const multiResponse = (await transaction.exec());

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

@@ -3,6 +3,88 @@ import { ActivityData, ActivityMetadata, ActivityType, CycleActivity } from '../
 import { ProviderTransaction } from '../../types/provider';
 import { JobState } from '../../types/job';
 import { Activity } from './activity';
+/**
+ * Re-executes an ancestor activity in a new dimensional thread, enabling
+ * retry loops and iterative patterns without violating the DAG constraint.
+ * The `cycle` activity targets a specific ancestor (typically a
+ * `Hook` with `cycle: true`) and sends execution back to that point.
+ *
+ * Each cycle iteration runs in a fresh **dimensional thread** — individual
+ * activity state is isolated per iteration, while **shared job state**
+ * (`job.maps`) accumulates across iterations. This pattern enables retries,
+ * polling loops, and iterative processing.
+ *
+ * ## YAML Configuration
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: retry.start
+ *       expire: 300
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         pivot:
+ *           type: hook
+ *           cycle: true                    # marks this activity as a cycle target
+ *           output:
+ *             maps:
+ *               retryCount: 0
+ *
+ *         do_work:
+ *           type: worker
+ *           topic: work.do
+ *           output:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 result: { type: string }
+ *
+ *         retry:
+ *           type: cycle
+ *           ancestor: pivot                # re-execute from this activity
+ *           input:
+ *             maps:
+ *               retryCount:                # increment retry counter each cycle
+ *                 '@pipe':
+ *                   - ['{pivot.output.data.retryCount}', 1]
+ *                   - ['{@math.add}']
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: pivot
+ *         pivot:
+ *           - to: do_work
+ *         do_work:
+ *           - to: retry
+ *             conditions:
+ *               code: 500                  # cycle on error
+ *           - to: done
+ * ```
+ *
+ * ## Key Behaviors
+ *
+ * - The `ancestor` field must reference an activity with `cycle: true`.
+ * - The cycle activity's `input.maps` override the ancestor's output data
+ *   for the next iteration, allowing each cycle to pass different values.
+ * - Dimensional isolation ensures parallel cycle iterations don't collide.
+ *
+ * ## Execution Model
+ *
+ * Cycle is a **Category A (Leg 1 only)** activity:
+ * - Maps input data, resolves the re-entry dimensional address, and
+ *   publishes a stream message addressed to the ancestor activity.
+ * - The ancestor re-enters via its Leg 2 path in the new dimension.
+ *
+ * @see {@link CycleActivity} for the TypeScript interface
+ */
 declare class Cycle extends Activity {
     config: CycleActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);

package/build/services/activities/cycle.js

@@ -6,6 +6,88 @@ const utils_1 = require("../../modules/utils");
 const collator_1 = require("../collator");
 const telemetry_1 = require("../telemetry");
 const activity_1 = require("./activity");
+/**
+ * Re-executes an ancestor activity in a new dimensional thread, enabling
+ * retry loops and iterative patterns without violating the DAG constraint.
+ * The `cycle` activity targets a specific ancestor (typically a
+ * `Hook` with `cycle: true`) and sends execution back to that point.
+ *
+ * Each cycle iteration runs in a fresh **dimensional thread** — individual
+ * activity state is isolated per iteration, while **shared job state**
+ * (`job.maps`) accumulates across iterations. This pattern enables retries,
+ * polling loops, and iterative processing.
+ *
+ * ## YAML Configuration
+ *
+ * ```yaml
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: retry.start
+ *       expire: 300
+ *
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *
+ *         pivot:
+ *           type: hook
+ *           cycle: true                    # marks this activity as a cycle target
+ *           output:
+ *             maps:
+ *               retryCount: 0
+ *
+ *         do_work:
+ *           type: worker
+ *           topic: work.do
+ *           output:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 result: { type: string }
+ *
+ *         retry:
+ *           type: cycle
+ *           ancestor: pivot                # re-execute from this activity
+ *           input:
+ *             maps:
+ *               retryCount:                # increment retry counter each cycle
+ *                 '@pipe':
+ *                   - ['{pivot.output.data.retryCount}', 1]
+ *                   - ['{@math.add}']
+ *
+ *         done:
+ *           type: hook
+ *
+ *       transitions:
+ *         t1:
+ *           - to: pivot
+ *         pivot:
+ *           - to: do_work
+ *         do_work:
+ *           - to: retry
+ *             conditions:
+ *               code: 500                  # cycle on error
+ *           - to: done
+ * ```
+ *
+ * ## Key Behaviors
+ *
+ * - The `ancestor` field must reference an activity with `cycle: true`.
+ * - The cycle activity's `input.maps` override the ancestor's output data
+ *   for the next iteration, allowing each cycle to pass different values.
+ * - Dimensional isolation ensures parallel cycle iterations don't collide.
+ *
+ * ## Execution Model
+ *
+ * Cycle is a **Category A (Leg 1 only)** activity:
+ * - Maps input data, resolves the re-entry dimensional address, and
+ *   publishes a stream message addressed to the ancestor activity.
+ * - The ancestor re-enters via its Leg 2 path in the new dimension.
+ *
+ * @see {@link CycleActivity} for the TypeScript interface
+ */
 class Cycle extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
@@ -23,23 +105,19 @@ class Cycle extends activity_1.Activity {
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
             this.mapInputData();
-            //set state/status
-            let transaction = this.store.transact();
+            //set state/status, cycle ancestor, and mark Leg1 complete — single transaction
+            const transaction = this.store.transact();
             await this.setState(transaction);
             await this.setStatus(0, transaction); //leg 1 never changes job status
+            const messageId = await this.cycleAncestorActivity(transaction);
+            await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
             const txResponse = (await transaction.exec());
             telemetry.mapActivityAttributes();
             const jobStatus = this.resolveStatus(txResponse);
-            //cycle the target ancestor
-            transaction = this.store.transact();
-            const messageId = await this.cycleAncestorActivity(transaction);
             telemetry.setActivityAttributes({
                 'app.activity.mid': messageId,
                 'app.job.jss': jobStatus,
             });
-            //exit early (`Cycle` activities only execute Leg 1)
-            await collator_1.CollatorService.notarizeEarlyExit(this, transaction);
-            (await transaction.exec());
             return this.context.metadata.aid;
         }
         catch (error) {

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

@@ -7,12 +7,155 @@ import { ProviderTransaction } from '../../types/provider';
 import { StreamCode, StreamStatus } from '../../types/stream';
 import { Activity } from './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
  */
 declare class Hook extends Activity {
     config: HookActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
     process(): Promise<string>;
+    /**
+     * Static config check: does this activity have a hook or sleep config?
+     * Used for routing before context is loaded.
+     */
+    isConfiguredAsHook(): boolean;
     /**
      * does this activity use a time-hook or web-hook
      */