@hotmeshio/hotmesh 0.8.0 → 0.9.0

package/build/services/activities/activity.js

@@ -11,7 +11,62 @@ const serializer_1 = require("../serializer");
 const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
 /**
- * The base class for all activities
+ * Base class for all HotMesh activity types. Activities are the execution
+ * units within a YAML-defined workflow graph. Each activity represents a
+ * node in a Directed Acyclic Graph (DAG) that the engine orchestrates.
+ *
+ * ## Activity Categories
+ *
+ * Activities fall into three execution categories:
+ *
+ * - **Category A (Duplex)**: Two-phase activities with Leg 1 (dispatch) and
+ *   Leg 2 (response). Used by `Worker` and `Await`. Leg 1
+ *   publishes a message and waits; Leg 2 handles the response via
+ *   `processEvent` and transitions to adjacent activities.
+ *
+ * - **Category B (Leg1-only with children)**: Single-phase activities that
+ *   execute work and transition to children using the crash-safe
+ *   `executeLeg1StepProtocol`. Used by `Hook` (passthrough mode),
+ *   `Signal`, and `Interrupt` (target mode).
+ *
+ * - **Category C (Leg1-only, no children)**: Terminal activities that
+ *   execute without spawning children. Used by `Interrupt` (self mode).
+ *
+ * ## Shared YAML Configuration
+ *
+ * All activity types support these base properties in the YAML descriptor:
+ *
+ * | Property             | Type    | Description |
+ * |----------------------|---------|-------------|
+ * | `type`               | string  | Activity type: `trigger`, `worker`, `await`, `hook`, `signal`, `interrupt`, `cycle` |
+ * | `title`              | string  | Human-readable label for the activity |
+ * | `input.schema`       | object  | JSON Schema for input validation |
+ * | `input.maps`         | object  | Maps data from other activities into this activity's input |
+ * | `output.schema`      | object  | JSON Schema for output validation |
+ * | `output.maps`        | object  | Maps/transforms the activity's own output data |
+ * | `job.maps`           | object  | Maps activity data to the shared job state |
+ * | `emit`               | boolean | If `true`, emits a message to the graph's `publishes` topic |
+ * | `persist`            | boolean | If `true`, emits the job-completed event while keeping the job active |
+ * | `expire`             | number  | Seconds until the job expires after completion (`-1` = forever) |
+ * | `statusThreshold`    | number  | Custom semaphore threshold for Dynamic Activation Control |
+ * | `cycle`              | boolean | If `true`, leaves Leg 2 open so the activity can be re-entered |
+ *
+ * ## Data Mapping Syntax
+ *
+ * Mapping expressions use curly-brace references to bind data between
+ * activities and the shared job state:
+ *
+ * ```yaml
+ * input:
+ *   maps:
+ *     x: '{t1.output.data.fieldName}'      # reference another activity's output
+ *     y: '{$self.output.data.fieldName}'    # reference own output
+ *     z: '{$job.data.fieldName}'            # reference shared job state
+ *     s: '{$app.settings.configKey}'        # reference app-level settings
+ * ```
+ *
+ * @see {@link https://hotmeshio.github.io/sdk-typescript/docs/quickstart | Quick Start Guide}
+ * @see [Model Driven Development](https://hotmeshio.github.io/sdk-typescript/docs/model_driven_development)
  */
 class Activity {
     constructor(config, data, metadata, hook, engine, context) {
@@ -57,13 +112,15 @@ class Activity {
         }
         catch (error) {
             await collator_1.CollatorService.notarizeEntry(this);
-            //todo: confirm this check is still needed; the edge event cleanup should handle fully
             if (threshold > 0) {
-                if (this.context.metadata.js === threshold) {
-                    //conclude job EXACTLY ONCE
+                if (this.context.metadata.js <= threshold) {
+                    //Dynamic Activation Control: convergent claim — only the
+                    //activity whose HINCRBY reaches exactly 0 runs completion.
                     const status = await this.setStatus(-threshold);
                     if (Number(status) === 0) {
-                        await this.engine.runJobCompletionTasks(this.context);
+                        const txn = this.store.transact();
+                        await this.engine.runJobCompletionTasks(this.context, {}, txn);
+                        await txn.exec();
                     }
                 }
             }
@@ -486,13 +543,10 @@ class Activity {
         const { id: appId } = await this.engine.getVID();
         return await this.store.setStatus(amount, this.context.metadata.jid, appId, transaction);
     }
-    authorizeEntry(state) {
-        //pre-authorize activity state to allow entry for adjacent activities
-        return (this.adjacencyList?.map((streamData) => {
-            const { metadata: { aid }, } = streamData;
-            state[`${aid}/output/metadata/as`] = collator_1.CollatorService.getSeed();
-            return aid;
-        }) ?? []);
+    authorizeEntry(_state) {
+        //seed writes removed: child activities increment from 0 (null field).
+        //FINALIZE (200T) sets pos 1 directly to 2 without needing a 100T base.
+        return [];
     }
     bindDimensionalAddress(state) {
         const dad = this.resolveDad();
@@ -721,31 +775,6 @@ class Activity {
         }
         return false;
     }
-    /**
-     * Transition method for Category C (Leg1-only, no children, no semaphore change)
-     * and Category D (Trigger) activities. NOT used by the Leg2 step protocol.
-     */
-    async transition(adjacencyList, jobStatus) {
-        if (this.jobWasInterrupted(jobStatus)) {
-            return;
-        }
-        let mIds = [];
-        if (this.shouldEmit() ||
-            this.isJobComplete(jobStatus) ||
-            this.shouldPersistJob()) {
-            await this.engine.runJobCompletionTasks(this.context, {
-                emit: !this.isJobComplete(jobStatus) && !this.shouldPersistJob(),
-            });
-        }
-        if (adjacencyList.length && !this.isJobComplete(jobStatus)) {
-            const transaction = this.store.transact();
-            for (const execSignal of adjacencyList) {
-                await this.engine.router?.publishMessage(null, execSignal, transaction);
-            }
-            mIds = (await transaction.exec());
-        }
-        return mIds;
-    }
     /**
      * A job with a vale < -100_000_000 is considered interrupted,
      * as the interruption event decrements the job status by 1billion.

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);

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.notarizeLeg1Completion(this, transaction);
-            (await transaction.exec());
             return this.context.metadata.aid;
         }
         catch (error) {

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

@@ -7,7 +7,145 @@ 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;