@hotmeshio/hotmesh 0.7.0 → 0.9.0

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);
@@ -24,11 +131,11 @@ class Worker 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 txResponse = (await transaction.exec());

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

@@ -6,6 +6,23 @@ import { Activity } from '../activities/activity';
 import { Cycle } from '../activities/cycle';
 declare class CollatorService {
     static targetLength: number;
+    /**
+     * Positional weights for the 15-digit activity/GUID ledger.
+     *
+     * Position:  1     2     3    4      5     6    7      8-15
+     * Weight:   100T  10T   1T   100B   10B   1B   100M   10M..1
+     */
+    static WEIGHTS: {
+        AUTH: number;
+        FINALIZE: number;
+        LEG1_ENTRY: number;
+        LEG1_COMPLETE: number;
+        STEP1_WORK: number;
+        STEP2_SPAWN: number;
+        STEP3_CLEANUP: number;
+        LEG2_ENTRY: number;
+        GUID_SNAPSHOT: number;
+    };
     /**
      * Upon re/entry, verify that the job status is active
      */
@@ -26,53 +43,122 @@ declare class CollatorService {
      * the origin node can be queried for approval/entry.
      */
     static resolveReentryDimension(activity: Cycle): string;
+    /**
+     * Leg1 entry: increment attempt counter (+1T).
+     * NOT bundled with Leg1 work — exists only to mark entry.
+     */
     static notarizeEntry(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
-    static authorizeReentry(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
+    /**
+     * Leg1 completion: increment +100B to mark Leg1 complete.
+     * For cycle=true activities, also pre-seeds the Leg2 entry counter (+1)
+     * so the first real Leg2 gets adjacentIndex=1 (new dimension).
+     * MUST be bundled in the same transaction as Leg1 durable work.
+     */
+    static notarizeLeg1Completion(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
+    /**
+     * Leg1 early exit: marks Leg1 complete for activities that
+     * only run Leg1 and fully close (e.g., Cycle).
+     * Increment +100B (Leg1 completion marker).
+     */
     static notarizeEarlyExit(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
+    /**
+     * Leg1 early completion: marks Leg1 complete for Leg1-only
+     * activities that spawn children (e.g., Signal, Hook passthrough,
+     * Interrupt-another). Increment +100B.
+     */
     static notarizeEarlyCompletion(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
     /**
-     * sets the synthetic inception key (in case of an overage occurs).
+     * Leg2 entry: atomically increments the activity ledger (+1) and
+     * seeds the GUID ledger with the ordinal IF NOT EXISTS.
+     * Returns [activityLedger, guidLedger] after the compound operation.
+     */
+    static notarizeLeg2Entry(activity: Activity, guid: string, transaction?: ProviderTransaction): Promise<[number, number]>;
+    /**
+     * Step 1: Mark Leg2 work done (+10B on GUID ledger only).
+     * MUST be bundled with Leg2 durable work writes.
+     */
+    static notarizeStep1(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
+    /**
+     * Step 2: Mark children spawned (+1B on GUID ledger only).
+     * The job semaphore update and GUID job-closed snapshot are handled
+     * by the compound `setStatusAndCollateGuid` primitive, which MUST
+     * be called in the same transaction.
+     */
+    static notarizeStep2(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
+    /**
+     * Step 3: Mark job completion tasks done (+100M on GUID ledger only).
+     * MUST be bundled with job completion durable writes.
+     */
+    static notarizeStep3(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
+    /**
+     * 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 notarizeInception(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
+    static notarizeFinalize(activity: Activity, transaction: ProviderTransaction): Promise<void>;
     /**
-     * ignore those ID collisions that are due to re-entry overages
+     * Check if Step 1 (work done) is complete on the GUID ledger.
+     * Position 5 (10B digit) > 0.
      */
-    static isInceptionOverage(activity: Activity, guid: string): Promise<boolean>;
+    static isGuidStep1Done(guidLedger: number): boolean;
     /**
-     * verifies both the concrete and synthetic keys for the activity; concrete keys
-     * exist in the original model and are effectively the 'real' keys. In reality,
-     * hook activities are atomized during compilation to create a synthetic DAG that
-     * is used to track the status of the graph in a distributed environment. The
-     * synthetic key represents different dimensional realities and is used to
-     * track re-entry overages (it distinguishes between the original and re-entry).
-     * The essential challenge is: is this a re-entry that is purposeful in
-     * order to induce cycles, or is the re-entry due to a failure in the system?
+     * Check if Step 2 (children spawned) is complete on the GUID ledger.
+     * Position 6 (1B digit) > 0.
+     */
+    static isGuidStep2Done(guidLedger: number): boolean;
+    /**
+     * Check if Step 3 (job completion tasks) is complete on the GUID ledger.
+     * Position 7 (100M digit) > 0.
+     */
+    static isGuidStep3Done(guidLedger: number): boolean;
+    /**
+     * Check if this GUID was responsible for closing the job.
+     * Position 4 (100B digit) > 0 (job closed snapshot).
+     */
+    static isGuidJobClosed(guidLedger: number): boolean;
+    /**
+     * Get the attempt count from the GUID ledger (last 8 digits).
+     */
+    static getGuidAttemptCount(guidLedger: number): number;
+    /**
+     * Gets the digit at a 1-indexed position from a 15-digit ledger value.
+     * The value is left-padded to 15 digits before extraction.
+     */
+    static getDigitAtPosition(num: number, position: number): number;
+    /**
+     * @deprecated Use getDigitAtPosition (1-indexed) instead
      */
-    static notarizeReentry(activity: Activity, guid: string, transaction?: ProviderTransaction): Promise<number>;
-    static notarizeContinuation(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
-    static notarizeCompletion(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
     static getDigitAtIndex(num: number, targetDigitIndex: number): number | null;
+    /**
+     * Extracts the dimensional index from the Leg2 entry counter.
+     * Non-cycle activities: first Leg2 → leg2Count=1 → 1-1=0 (same dimension as Leg1).
+     * Cycle activities: first Leg2 → leg2Count=2 (pre-seeded +1) → 2-1=1 (new dimension).
+     */
     static getDimensionalIndex(num: number): number | null;
-    static isDuplicate(num: number, targetDigitIndex: number): boolean;
-    static isInactive(num: number): boolean;
-    static isPrimed(amount: number, leg: ActivityDuplex): boolean;
     /**
-     * During compilation, the graphs are compiled into structures necessary
-     * for distributed processing; these are referred to as 'synthetic DAGs',
-     * because they are not part of the original graph, but are used to track
-     * the status of the graph in a distributed environment. This check ensures
-     * that the 'synthetic key' is not a duplicate. (which is different than
-     * saying the 'key' is not a duplicate)
+     * Verifies the GUID ledger value for step-level resume decisions.
+     * The GUID ledger is seeded with an ordinal position (last 8 digits)
+     * on first entry; step markers drive all resume/reject logic.
+     *
+     * Fully processed: Step 3 done, or Steps 1+2 done without job closure.
+     * Crash recovery: Any incomplete step combination is allowed for resume.
      */
     static verifySyntheticInteger(amount: number): void;
-    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
+     * Verifies the activity ledger value at entry boundaries.
+     *
+     * Leg1 enter: pos 3 (1T digit) must be > 0 after +1T (proves seed exists).
+     *             pos 4 (100B) must be 0 (Leg1 not yet complete).
+     *             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 1 (100T) must be < 2 (not finalized) — cycle activities exempt.
      */
-    static getSeed(): string;
+    static verifyInteger(amount: number, leg: ActivityDuplex, stage: CollationStage): void;
+    static getDimensionsById(ancestors: string[], dad: string): Record<string, string>;
     /**
-     * All trigger activities are assigned a status seed in a completed state
+     * All trigger activities are assigned a status seed in a completed state.
+     * Seed: 101100000000001 (authorized, 1 Leg1 entry, Leg1 complete, 1 Leg2 entry)
      */
     static getTriggerSeed(): string;
     /**