@hotmeshio/hotmesh 0.0.7 → 0.0.8

package/build/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.0.7",
+    "version": "0.0.8",
     "description": "Durable Workflows",
     "main": "build/cjs/index.js",
     "module": "build/esm/index.js",
@@ -29,6 +29,7 @@
         "test": "NODE_ENV=test jest --detectOpenHandles --forceExit --verbose",
         "test:hmsh": "NODE_ENV=test jest ./tests/functional/index.test.ts --detectOpenHandles --verbose",
         "test:compile": "NODE_ENV=test jest ./tests/functional/compile/index.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:cycle": "NODE_ENV=test jest ./tests/functional/cycle/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect": "NODE_ENV=test jest ./tests/unit/services/connector/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect:redis": "NODE_ENV=test jest ./tests/unit/services/connector/clients/redis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect:ioredis": "NODE_ENV=test jest ./tests/unit/services/connector/clients/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
@@ -48,6 +49,7 @@
         "test:durable": "NODE_ENV=test jest ./tests/durable/*/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:durable:hello": "NODE_ENV=test jest ./tests/durable/helloworld/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:durable:goodbye": "NODE_ENV=test jest ./tests/durable/goodbye/index.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:durable:retry": "NODE_ENV=test jest ./tests/durable/retry/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:durable:loopactivity": "NODE_ENV=test jest ./tests/durable/loopactivity/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:durable:nested": "NODE_ENV=test jest ./tests/durable/nested/index.test.ts --detectOpenHandles --forceExit --verbose"
     },

package/build/cjs/services/activities/activity.d.ts

@@ -1,6 +1,7 @@
 import { EngineService } from '../engine';
 import { ILogger } from '../logger';
 import { StoreService } from '../store';
+import { TelemetryService } from '../telemetry';
 import { ActivityData, ActivityLeg, ActivityMetadata, ActivityType } from '../../types/activity';
 import { JobState, JobStatus } from '../../types/job';
 import { MultiResponseFlags, RedisClient, RedisMulti } from '../../types/redis';
@@ -31,6 +32,11 @@ declare class Activity {
     processWebHookEvent(): Promise<JobStatus | void>;
     processTimeHookEvent(jobId: string): Promise<JobStatus | void>;
     processHookEvent(jobId: string): Promise<JobStatus | void>;
+    processEvent(status?: StreamStatus, code?: StreamCode): Promise<void>;
+    processPending(telemetry: TelemetryService): Promise<MultiResponseFlags>;
+    processSuccess(telemetry: TelemetryService): Promise<MultiResponseFlags>;
+    processError(telemetry: TelemetryService): Promise<MultiResponseFlags>;
+    transitionAdjacent(multiResponse: MultiResponseFlags, telemetry: TelemetryService): Promise<void>;
     resolveStatus(multiResponse: MultiResponseFlags): number;
     mapJobData(): void;
     mapInputData(): void;

package/build/cjs/services/activities/activity.js

@@ -87,7 +87,7 @@ class Activity {
     setLeg(leg) {
         this.leg = leg;
     }
-    //********  SIGNALER RE-ENTRY POINT (B)  ********//
+    //********  SIGNAL RE-ENTRY POINT  ********//
     doesHook() {
         return !!(this.config.hook?.topic || this.config.sleep);
     }
@@ -125,11 +125,6 @@ class Activity {
         });
         return await this.processHookEvent(jobId);
     }
-    //todo: hooks are currently singletons. but they can support
-    //      dimensional threads like `await` and `worker` do.
-    //      Copy code from those activities to support cyclical
-    //      timehook and eventhook inputs by adding a 'pending'
-    //      flag to hooks that allows for repeated signals
     async processHookEvent(jobId) {
         this.logger.debug('activity-process-hook-event', { jobId });
         let telemetry;
@@ -159,7 +154,6 @@ class Activity {
             return jobStatus;
         }
         catch (error) {
-            console.error('this error?', error);
             this.logger.error('engine-process-hook-event-error', error);
             telemetry.setActivityError(error.message);
             throw error;
@@ -168,6 +162,88 @@ class Activity {
             telemetry.endActivitySpan();
         }
     }
+    //********  DUPLEX RE-ENTRY POINT  ********//
+    async processEvent(status = stream_1.StreamStatus.SUCCESS, code = 200) {
+        this.setLeg(2);
+        const jid = this.context.metadata.jid;
+        const aid = this.metadata.aid;
+        this.status = status;
+        this.code = code;
+        this.logger.debug('activity-process-event', { topic: this.config.subtype, jid, aid, status, code });
+        let telemetry;
+        try {
+            await this.getState();
+            const aState = await collator_1.CollatorService.notarizeReentry(this);
+            this.adjacentIndex = collator_1.CollatorService.getDimensionalIndex(aState);
+            telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
+            let isComplete = collator_1.CollatorService.isActivityComplete(this.context.metadata.js);
+            if (isComplete) {
+                this.logger.warn('activity-process-event-duplicate', { jid, aid });
+                this.logger.debug('activity-process-event-duplicate-resolution', { resolution: 'Increase HotMesh config `reclaimDelay` timeout.' });
+                return;
+            }
+            telemetry.startActivitySpan(this.leg);
+            let multiResponse;
+            if (status === stream_1.StreamStatus.PENDING) {
+                multiResponse = await this.processPending(telemetry);
+            }
+            else if (status === stream_1.StreamStatus.SUCCESS) {
+                multiResponse = await this.processSuccess(telemetry);
+            }
+            else {
+                multiResponse = await this.processError(telemetry);
+            }
+            this.transitionAdjacent(multiResponse, telemetry);
+        }
+        catch (error) {
+            this.logger.error('activity-process-event-error', error);
+            telemetry.setActivityError(error.message);
+            throw error;
+        }
+        finally {
+            telemetry.endActivitySpan();
+            this.logger.debug('activity-process-event-end', { jid, aid });
+        }
+    }
+    async processPending(telemetry) {
+        this.bindActivityData('output');
+        this.adjacencyList = await this.filterAdjacent();
+        this.mapJobData();
+        const multi = this.store.getMulti();
+        await this.setState(multi);
+        await collator_1.CollatorService.notarizeContinuation(this, multi);
+        await this.setStatus(this.adjacencyList.length, multi);
+        return await multi.exec();
+    }
+    async processSuccess(telemetry) {
+        this.bindActivityData('output');
+        this.adjacencyList = await this.filterAdjacent();
+        this.mapJobData();
+        const multi = this.store.getMulti();
+        await this.setState(multi);
+        await collator_1.CollatorService.notarizeCompletion(this, multi);
+        await this.setStatus(this.adjacencyList.length - 1, multi);
+        return await multi.exec();
+    }
+    async processError(telemetry) {
+        this.bindActivityError(this.data);
+        this.adjacencyList = await this.filterAdjacent();
+        const multi = this.store.getMulti();
+        await this.setState(multi);
+        await collator_1.CollatorService.notarizeCompletion(this, multi);
+        await this.setStatus(this.adjacencyList.length - 1, multi);
+        return await multi.exec();
+    }
+    async transitionAdjacent(multiResponse, telemetry) {
+        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);
+    }
     resolveStatus(multiResponse) {
         const activityStatus = multiResponse[multiResponse.length - 1];
         if (Array.isArray(activityStatus)) {

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

@@ -10,7 +10,7 @@ declare class Await extends Activity {
     process(): Promise<string>;
     execActivity(): Promise<string>;
     processEvent(status?: StreamStatus, code?: StreamCode): Promise<void>;
-    processSuccess(adjacencyList: StreamData[]): Promise<MultiResponseFlags>;
-    processError(adjacencyList: StreamData[]): Promise<MultiResponseFlags>;
+    processSuccessResponse(adjacencyList: StreamData[]): Promise<MultiResponseFlags>;
+    processErrorResponse(adjacencyList: StreamData[]): Promise<MultiResponseFlags>;
 }
 export { Await };

package/build/cjs/services/activities/await.js

@@ -22,7 +22,7 @@ class Await extends activity_1.Activity {
             telemetry.startActivitySpan(this.leg);
             this.mapInputData();
             const multi = this.store.getMulti();
-            //await this.registerTimeout();
+            //todo: await this.registerTimeout();
             await collator_1.CollatorService.authorizeReentry(this, multi);
             await this.setState(multi);
             await this.setStatus(0, multi);
@@ -95,12 +95,12 @@ class Await extends activity_1.Activity {
             if (status === stream_1.StreamStatus.SUCCESS) {
                 this.bindActivityData('output');
                 this.adjacencyList = await this.filterAdjacent();
-                multiResponse = await this.processSuccess(this.adjacencyList);
+                multiResponse = await this.processSuccessResponse(this.adjacencyList);
             }
             else {
                 this.bindActivityError(this.data);
                 this.adjacencyList = await this.filterAdjacent();
-                multiResponse = await this.processError(this.adjacencyList);
+                multiResponse = await this.processErrorResponse(this.adjacencyList);
             }
             telemetry.mapActivityAttributes();
             const jobStatus = this.resolveStatus(multiResponse);
@@ -121,7 +121,7 @@ class Await extends activity_1.Activity {
             this.logger.debug('await-resolve-await-end', { jid, aid, status, code });
         }
     }
-    async processSuccess(adjacencyList) {
+    async processSuccessResponse(adjacencyList) {
         this.mapJobData();
         const multi = this.store.getMulti();
         await this.setState(multi);
@@ -129,7 +129,7 @@ class Await extends activity_1.Activity {
         await this.setStatus(adjacencyList.length - 1, multi);
         return await multi.exec();
     }
-    async processError(adjacencyList) {
+    async processErrorResponse(adjacencyList) {
         //todo: if adjacencyList.length == 0, then map to the job output
         //      this method would be added to Base activity class 
         //this.mapJobData();

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

@@ -0,0 +1,19 @@
+import { EngineService } from '../engine';
+import { Activity, ActivityType } from './activity';
+import { ActivityData, ActivityMetadata, CycleActivity } from '../../types/activity';
+import { JobState } from '../../types/job';
+import { RedisMulti } from '../../types/redis';
+declare class Cycle extends Activity {
+    config: CycleActivity;
+    constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
+    process(): Promise<string>;
+    /**
+     * Trigger the target ancestor to execute in a cycle,
+     * without violating the constraints of the DAG. Immutable
+     * `individual activity state` will execute in a new dimensional
+     * thread while `shared job state` can change. This
+     * pattern allows for retries without violating the DAG.
+     */
+    cycleAncestorActivity(multi: RedisMulti): Promise<string>;
+}
+export { Cycle };

package/build/cjs/services/activities/cycle.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cycle = void 0;
+const errors_1 = require("../../modules/errors");
+const collator_1 = require("../collator");
+const activity_1 = require("./activity");
+const telemetry_1 = require("../telemetry");
+class Cycle extends activity_1.Activity {
+    constructor(config, data, metadata, hook, engine, context) {
+        super(config, data, metadata, hook, engine, context);
+    }
+    //********  LEG 1 ENTRY  ********//
+    async process() {
+        this.logger.debug('cycle-process', { jid: this.context.metadata.jid, aid: this.metadata.aid });
+        let telemetry;
+        try {
+            //verify entry is allowed
+            this.setLeg(1);
+            await collator_1.CollatorService.notarizeEntry(this);
+            await this.getState();
+            telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
+            telemetry.startActivitySpan(this.leg);
+            this.mapInputData();
+            //set state/status
+            let multi = this.store.getMulti();
+            await this.setState(multi);
+            await this.setStatus(0, multi); //leg 1 never changes job status
+            const multiResponse = await multi.exec();
+            telemetry.mapActivityAttributes();
+            const jobStatus = this.resolveStatus(multiResponse);
+            //cycle the target ancestor
+            multi = this.store.getMulti();
+            const messageId = await this.cycleAncestorActivity(multi);
+            telemetry.setActivityAttributes({
+                'app.activity.mid': messageId,
+                'app.job.jss': jobStatus
+            });
+            //exit early (`Cycle` activities only execute Leg 1)
+            await collator_1.CollatorService.notarizeEarlyExit(this, multi);
+            await multi.exec();
+            return this.context.metadata.aid;
+        }
+        catch (error) {
+            if (error instanceof errors_1.GetStateError) {
+                this.logger.error('cycle-get-state-error', error);
+            }
+            else {
+                this.logger.error('cycle-process-error', error);
+            }
+            telemetry.setActivityError(error.message);
+            throw error;
+        }
+        finally {
+            telemetry.endActivitySpan();
+            this.logger.debug('cycle-process-end', { jid: this.context.metadata.jid, aid: this.metadata.aid });
+        }
+    }
+    /**
+     * Trigger the target ancestor to execute in a cycle,
+     * without violating the constraints of the DAG. Immutable
+     * `individual activity state` will execute in a new dimensional
+     * thread while `shared job state` can change. This
+     * pattern allows for retries without violating the DAG.
+     */
+    async cycleAncestorActivity(multi) {
+        const streamData = {
+            metadata: {
+                dad: collator_1.CollatorService.resolveReentryDimension(this),
+                jid: this.context.metadata.jid,
+                aid: this.config.ancestor,
+            },
+            data: {} //todo: verify immutability, before enabling: `this.context.data`
+        };
+        return (await this.engine.streamSignaler?.publishMessage(null, streamData, multi));
+    }
+}
+exports.Cycle = Cycle;

package/build/cjs/services/activities/index.d.ts

@@ -1,12 +1,14 @@
 import { Activity } from './activity';
 import { Await } from './await';
-import { Worker } from './worker';
-import { Iterate } from './iterate';
+import { Cycle } from './cycle';
 import { Emit } from './emit';
+import { Iterate } from './iterate';
 import { Trigger } from './trigger';
+import { Worker } from './worker';
 declare const _default: {
     activity: typeof Activity;
     await: typeof Await;
+    cycle: typeof Cycle;
     iterate: typeof Iterate;
     emit: typeof Emit;
     trigger: typeof Trigger;

package/build/cjs/services/activities/index.js

@@ -2,13 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const activity_1 = require("./activity");
 const await_1 = require("./await");
-const worker_1 = require("./worker");
-const iterate_1 = require("./iterate");
+const cycle_1 = require("./cycle");
 const emit_1 = require("./emit");
+const iterate_1 = require("./iterate");
 const trigger_1 = require("./trigger");
+const worker_1 = require("./worker");
 exports.default = {
     activity: activity_1.Activity,
     await: await_1.Await,
+    cycle: cycle_1.Cycle,
     iterate: iterate_1.Iterate,
     emit: emit_1.Emit,
     trigger: trigger_1.Trigger,

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

@@ -2,18 +2,10 @@ import { Activity } from './activity';
 import { EngineService } from '../engine';
 import { ActivityData, ActivityMetadata, ActivityType, WorkerActivity } from '../../types/activity';
 import { JobState } from '../../types/job';
-import { MultiResponseFlags } from '../../types/redis';
-import { StreamCode, StreamStatus } from '../../types/stream';
-import { TelemetryService } from '../telemetry';
 declare class Worker extends Activity {
     config: WorkerActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
     process(): Promise<string>;
     execActivity(): Promise<string>;
-    processEvent(status?: StreamStatus, code?: StreamCode): Promise<void>;
-    processPending(telemetry: TelemetryService): Promise<void>;
-    processSuccess(telemetry: TelemetryService): Promise<void>;
-    processError(telemetry: TelemetryService): Promise<void>;
-    transitionAdjacent(multiResponse: MultiResponseFlags, telemetry: TelemetryService): Promise<void>;
 }
 export { Worker };

package/build/cjs/services/activities/worker.js

@@ -4,7 +4,6 @@ exports.Worker = void 0;
 const errors_1 = require("../../modules/errors");
 const activity_1 = require("./activity");
 const collator_1 = require("../collator");
-const stream_1 = require("../../types/stream");
 const telemetry_1 = require("../telemetry");
 class Worker extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
@@ -22,7 +21,7 @@ class Worker extends activity_1.Activity {
             telemetry.startActivitySpan(this.leg);
             this.mapInputData();
             const multi = this.store.getMulti();
-            //await this.registerTimeout();
+            //todo: await this.registerTimeout();
             await collator_1.CollatorService.authorizeReentry(this, multi);
             await this.setState(multi);
             await this.setStatus(0, multi);
@@ -34,7 +33,6 @@ class Worker extends activity_1.Activity {
                 'app.activity.mid': messageId,
                 'app.job.jss': jobStatus
             });
-            //TODO: UPDATE ACTIVITY STATE (LEG 1 EXIT)
             return this.context.metadata.aid;
         }
         catch (error) {
@@ -42,7 +40,6 @@ class Worker extends activity_1.Activity {
                 this.logger.error('worker-get-state-error', error);
             }
             else {
-                console.error(error);
                 this.logger.error('worker-process-error', error);
             }
             telemetry.setActivityError(error.message);
@@ -72,88 +69,5 @@ class Worker extends activity_1.Activity {
         }
         return (await this.engine.streamSignaler?.publishMessage(this.config.subtype, streamData));
     }
-    //********  SIGNAL RE-ENTRY POINT (DUPLEX LEG 2 of 2)  ********//
-    async processEvent(status = stream_1.StreamStatus.SUCCESS, code = 200) {
-        this.setLeg(2);
-        const jid = this.context.metadata.jid;
-        const aid = this.metadata.aid;
-        this.status = status;
-        this.code = code;
-        this.logger.debug('worker-process-event', { topic: this.config.subtype, jid, aid, status, code });
-        let telemetry;
-        try {
-            await this.getState();
-            const aState = await collator_1.CollatorService.notarizeReentry(this);
-            this.adjacentIndex = collator_1.CollatorService.getDimensionalIndex(aState);
-            telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
-            let isComplete = collator_1.CollatorService.isActivityComplete(this.context.metadata.js);
-            if (isComplete) {
-                this.logger.warn('worker-process-event-duplicate', { jid, aid });
-                this.logger.debug('worker-process-event-duplicate-resolution', { resolution: 'Increase HotMesh config `reclaimDelay` timeout.' });
-                return;
-            }
-            telemetry.startActivitySpan(this.leg);
-            if (status === stream_1.StreamStatus.PENDING) {
-                await this.processPending(telemetry);
-            }
-            else if (status === stream_1.StreamStatus.SUCCESS) {
-                await this.processSuccess(telemetry);
-            }
-            else {
-                await this.processError(telemetry);
-            }
-        }
-        catch (error) {
-            this.logger.error('worker-process-event-error', error);
-            telemetry.setActivityError(error.message);
-            throw error;
-        }
-        finally {
-            telemetry.endActivitySpan();
-            this.logger.debug('worker-process-event-end', { jid, aid });
-        }
-    }
-    async processPending(telemetry) {
-        this.bindActivityData('output');
-        this.adjacencyList = await this.filterAdjacent();
-        this.mapJobData();
-        const multi = this.store.getMulti();
-        await this.setState(multi);
-        await collator_1.CollatorService.notarizeContinuation(this, multi);
-        await this.setStatus(this.adjacencyList.length, multi);
-        const multiResponse = await multi.exec();
-        this.transitionAdjacent(multiResponse, telemetry);
-    }
-    async processSuccess(telemetry) {
-        this.bindActivityData('output');
-        this.adjacencyList = await this.filterAdjacent();
-        this.mapJobData();
-        const multi = this.store.getMulti();
-        await this.setState(multi);
-        await collator_1.CollatorService.notarizeCompletion(this, multi);
-        await this.setStatus(this.adjacencyList.length - 1, multi);
-        const multiResponse = await multi.exec();
-        this.transitionAdjacent(multiResponse, telemetry);
-    }
-    async processError(telemetry) {
-        this.bindActivityError(this.data);
-        this.adjacencyList = await this.filterAdjacent();
-        const multi = this.store.getMulti();
-        await this.setState(multi);
-        await collator_1.CollatorService.notarizeCompletion(this, multi);
-        await this.setStatus(this.adjacencyList.length - 1, multi);
-        const multiResponse = await multi.exec();
-        this.transitionAdjacent(multiResponse, telemetry);
-    }
-    async transitionAdjacent(multiResponse, telemetry) {
-        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);
-    }
 }
 exports.Worker = Worker;

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

@@ -3,11 +3,28 @@ import { CollationStage } from '../../types/collator';
 import { ActivityDuplex } from '../../types/activity';
 import { HotMeshGraph } from '../../types/hotmesh';
 import { Activity } from '../activities/activity';
+import { Cycle } from '../activities/cycle';
 declare class CollatorService {
     static targetLength: number;
-    static getDimensionalAddress(activity: Activity): Record<string, string>;
+    /**
+     * returns the dimensional address (dad) for the target; due
+     * to the nature of the notary system, the dad for leg 2 entry
+     * must target the `0` index while leg 2 exit must target the
+     * current index (0)
+     */
+    static getDimensionalAddress(activity: Activity, isEntry?: boolean): Record<string, string>;
+    /**
+     * resolves the dimensional address for the
+     * ancestor in the graph to go back to. this address
+     * is determined by trimming the last digits from
+     * the `dad` (including the target).
+     * the target activity index is then set to `0`, so that
+     * the origin node can be queried for approval/entry.
+     */
+    static resolveReentryDimension(activity: Cycle): string;
     static notarizeEntry(activity: Activity, multi?: RedisMulti): Promise<number>;
     static authorizeReentry(activity: Activity, multi?: RedisMulti): Promise<number>;
+    static notarizeEarlyExit(activity: Activity, multi?: RedisMulti): Promise<number>;
     static notarizeEarlyCompletion(activity: Activity, multi?: RedisMulti): Promise<number>;
     static notarizeReentry(activity: Activity, multi?: RedisMulti): Promise<number>;
     static notarizeContinuation(activity: Activity, multi?: RedisMulti): Promise<number>;

package/build/cjs/services/collator/index.js

@@ -4,15 +4,36 @@ exports.CollatorService = void 0;
 const errors_1 = require("../../modules/errors");
 const collator_1 = require("../../types/collator");
 class CollatorService {
-    static getDimensionalAddress(activity) {
+    /**
+     * returns the dimensional address (dad) for the target; due
+     * to the nature of the notary system, the dad for leg 2 entry
+     * must target the `0` index while leg 2 exit must target the
+     * current index (0)
+     */
+    static getDimensionalAddress(activity, isEntry = false) {
         let dad = activity.context.metadata.dad || activity.metadata.dad;
-        //todo: unsure about this reset
-        // if (dad && activity.leg === 2) {
-        //   console.log('setting dad index back to 0=>', dad);
-        //   dad = `${dad.substring(0, dad.lastIndexOf(','))},0`;
-        // }
+        if (isEntry && dad && activity.leg === 2) {
+            dad = `${dad.substring(0, dad.lastIndexOf(','))},0`;
+        }
         return CollatorService.getDimensionsById([...activity.config.ancestors, activity.metadata.aid], dad);
     }
+    /**
+     * resolves the dimensional address for the
+     * ancestor in the graph to go back to. this address
+     * is determined by trimming the last digits from
+     * the `dad` (including the target).
+     * the target activity index is then set to `0`, so that
+     * the origin node can be queried for approval/entry.
+     */
+    static resolveReentryDimension(activity) {
+        const targetActivityId = activity.config.ancestor;
+        const ancestors = activity.config.ancestors;
+        const ancestorIndex = ancestors.indexOf(targetActivityId);
+        const dimensions = activity.metadata.dad.split(','); //e.g., `,0,0,1,0`
+        dimensions.length = ancestorIndex + 1;
+        dimensions.push('0');
+        return dimensions.join(',');
+    }
     static async notarizeEntry(activity, multi) {
         //decrement by -100_000_000_000_000
         const amount = await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, -100000000000000, this.getDimensionalAddress(activity), multi);
@@ -27,14 +48,21 @@ class CollatorService {
         //this.verifyInteger(amount, 1, 'exit');
         return amount;
     }
+    static async notarizeEarlyExit(activity, multi) {
+        //decrement the 2nd and 3rd digits to fully deactivate (`cycle` activities use this command to fully exit after leg 1) (should result in `888000000000000`)
+        return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, -11000000000000, this.getDimensionalAddress(activity), multi);
+    }
+    ;
     static async notarizeEarlyCompletion(activity, multi) {
-        //initialize both `possible` (1m) and `actualized` (1) zero dimension, while decrementing the 2nd and 3rd digits to deactivate the activity
-        return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1000001 - 11000000000000, this.getDimensionalAddress(activity), multi);
+        //initialize both `possible` (1m) and `actualized` (1) zero dimension, while decrementing the 2nd
+        //3rd digit is optionally kept open if the activity might be used in a cycle
+        const decrement = activity.config.cycle ? 10000000000000 : 11000000000000;
+        return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1000001 - decrement, this.getDimensionalAddress(activity), multi);
     }
     ;
     static async notarizeReentry(activity, multi) {
         //increment by 1_000_000 (indicates re-entry and is used to drive the 'dimensional address' for adjacent activities (minus 1))
-        const amount = await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1000000, this.getDimensionalAddress(activity), multi);
+        const amount = await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1000000, this.getDimensionalAddress(activity, true), multi);
         this.verifyInteger(amount, 2, 'enter');
         return amount;
     }
@@ -45,8 +73,10 @@ class CollatorService {
     }
     ;
     static async notarizeCompletion(activity, multi) {
-        //close out; actualize leg2 dimension (+1) and decrement the 3rd digit (-1_000_000_000_000)
-        return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1 - 1000000000000, this.getDimensionalAddress(activity), multi);
+        //1) ALWAYS actualize leg2 dimension (+1)
+        //2) IF the activity is used in a cycle, don't close leg 2!
+        const decrement = activity.config.cycle ? 0 : -1000000000000;
+        return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1 - decrement, this.getDimensionalAddress(activity), multi);
     }
     ;
     static getDigitAtIndex(num, targetDigitIndex) {

package/build/cjs/services/durable/factory.js

@@ -29,7 +29,12 @@ const getWorkflowYAML = (topic, version = '1') => {
           type: trigger
           stats:
             id: '{$self.input.data.workflowId}'
+
         a1:
+          type: activity
+          cycle: true
+  
+        w1:
           type: worker
           topic: ${topic}
           input:
@@ -52,9 +57,20 @@ const getWorkflowYAML = (topic, version = '1') => {
           job:
             maps:
               response: '{$self.output.data.response}'
+
+        c1:
+          type: cycle
+          ancestor: a1
       transitions:
         t1:
-          - to: a1`;
+          - to: a1
+        a1:
+          - to: w1
+        w1:
+          - to: c1
+            conditions:
+              code: 500
+`;
 };
 exports.getWorkflowYAML = getWorkflowYAML;
 const getActivityYAML = (topic, version = '1') => {

package/build/cjs/services/durable/worker.d.ts

@@ -5,6 +5,7 @@ export declare class WorkerService {
     static connection: Connection;
     static instances: Map<string, HotMesh | Promise<HotMesh>>;
     workflowRunner: HotMesh;
+    activityRunner: HotMesh;
     static getHotMesh: (worflowTopic: string) => Promise<HotMesh>;
     static activateWorkflow(hotMesh: HotMesh, topic: string, factory: Function): Promise<void>;
     /**