@hotmeshio/hotmesh 0.0.54 → 0.0.56

package/README.md

@@ -19,9 +19,6 @@ HotMesh inverts the relationship to Redis: those functions that once used Redis
 
 HotMesh creates an *ad hoc*, Redis-backed network of functions and organizes them into a unified service mesh. *Any service with access to Redis can join in the network, bypassing the legacy clutter.*
 
-<img src="./docs/img/hotmesh_emergent_properties.png" alt="HotMesh elevates Redis to a Service Mesh, Message Router, Integration Bus, and Business Process Engine." style="max-width:100%;width:600px;">
-
-
 ## Design
 HotMesh uses your existing Redis installation. If you already have an instance available, you have all the infrastructure you'll ever need.
 

package/build/modules/enums.js

@@ -1,9 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_LOGLEVEL = void 0;
-// HOTMESH SYSTEM
 exports.HMSH_LOGLEVEL = process.env.HMSH_LOGLEVEL || 'info';
-// HOTMESH STATUS CODES
 exports.HMSH_CODE_SUCCESS = 200;
 exports.HMSH_CODE_PENDING = 202;
 exports.HMSH_CODE_NOTFOUND = 404;
@@ -11,7 +9,6 @@ exports.HMSH_CODE_INTERRUPT = 410;
 exports.HMSH_CODE_UNKNOWN = 500;
 exports.HMSH_CODE_TIMEOUT = 504;
 exports.HMSH_CODE_UNACKED = 999;
-// DURABLE STATUS CODES
 exports.HMSH_CODE_DURABLE_SLEEP = 588;
 exports.HMSH_CODE_DURABLE_ALL = 589;
 exports.HMSH_CODE_DURABLE_CHILD = 590;
@@ -21,20 +18,15 @@ exports.HMSH_CODE_DURABLE_TIMEOUT = 596;
 exports.HMSH_CODE_DURABLE_MAXED = 597;
 exports.HMSH_CODE_DURABLE_FATAL = 598;
 exports.HMSH_CODE_DURABLE_RETRYABLE = 599;
-// HOTMESH MESSAGES
 exports.HMSH_STATUS_UNKNOWN = 'unknown';
-// QUORUM
-exports.HMSH_QUORUM_ROLLCALL_CYCLES = 12; //max iterations
+exports.HMSH_QUORUM_ROLLCALL_CYCLES = 12;
 exports.HMSH_QUORUM_DELAY_MS = 250;
 exports.HMSH_ACTIVATION_MAX_RETRY = 3;
-// ENGINE
 exports.HMSH_OTT_WAIT_TIME = parseInt(process.env.HMSH_OTT_WAIT_TIME, 10) || 1000;
 exports.HMSH_EXPIRE_JOB_SECONDS = parseInt(process.env.HMSH_EXPIRE_JOB_SECONDS, 10) || 1;
-// STREAM ROUTER
 exports.HMSH_MAX_RETRIES = parseInt(process.env.HMSH_MAX_RETRIES, 10) || 3;
 exports.HMSH_MAX_TIMEOUT_MS = parseInt(process.env.HMSH_MAX_TIMEOUT_MS, 10) || 60000;
 exports.HMSH_GRADUATED_INTERVAL_MS = parseInt(process.env.HMSH_GRADUATED_INTERVAL_MS, 10) || 5000;
-// DURABLE
 exports.HMSH_DURABLE_MAX_ATTEMPTS = 3;
 exports.HMSH_DURABLE_MAX_INTERVAL = '120s';
 exports.HMSH_DURABLE_EXP_BACKOFF = 10;
@@ -44,7 +36,6 @@ exports.HMSH_BLOCK_TIME_MS = process.env.HMSH_BLOCK_TIME_MS ? parseInt(process.e
 exports.HMSH_XCLAIM_DELAY_MS = parseInt(process.env.HMSH_XCLAIM_DELAY_MS, 10) || 1000 * 60;
 exports.HMSH_XCLAIM_COUNT = parseInt(process.env.HMSH_XCLAIM_COUNT, 10) || 3;
 exports.HMSH_XPENDING_COUNT = parseInt(process.env.HMSH_XPENDING_COUNT, 10) || 10;
-// TASK WORKER
 exports.HMSH_EXPIRE_DURATION = parseInt(process.env.HMSH_EXPIRE_DURATION, 10) || 1;
 const BASE_FIDELITY_SECONDS = 5;
 const TEST_FIDELITY_SECONDS = 1;

package/build/modules/key.d.ts

@@ -1,48 +1,10 @@
 import { KeyStoreParams, KeyType } from '../types/hotmesh';
-/**
- * Keys
- *
- * hmsh ->                                            {hash}    hotmesh config {version: "0.0.1", namespace: "hmsh"}
- * hmsh:a:<appid> ->                                  {hash}    app profile { "id": "appid", "version": "2", "versions/1": "GMT", "versions/2": "GMT"}
- * hmsh:<appid>:e:<engineId> ->                       {string}  setnx to ensure only one engine of given id
- * hmsh:<appid>:w: ->                                 {zset}    work items/tasks an engine must do like garbage collect or hook a set of matching records (hookAll)
- * hmsh:<appid>:t: ->                                 {zset}    an ordered set of list (work lists) ids
- * hmsh:<appid>:t:<timeValue?> ->                     {list}    a worklist of `jobId+activityId` items that should be awakened
- * hmsh:<appid>:q: ->                                 {hash}    quorum-wide messages
- * hmsh:<appid>:q:<ngnid> ->                          {hash}    engine-targeted messages (targeted quorum-oriented message)
- * hmsh:<appid>:j:<jobid> ->                          {hash}    job data
- * hmsh:<appid>:j:<jobid>:<activityid>  ->            {hash}    job activity data (a1)
- * hmsh:<appid>:s:<jobkey>:<dateTime> ->              {hash}    job stats (general)
- * hmsh:<appid>:s:<jobkey>:<dateTime>:mdn:<field/path>:<fieldvalue> ->      {zset}    job stats (median)
- * hmsh:<appid>:s:<jobkey>:<dateTime>:index:<field/path>:<fieldvalue> ->    {list}    job stats (index of jobid[])
- * hmsh:<appid>:v:<version>:activities ->             {hash}    schemas [cache]
- * hmsh:<appid>:v:<version>:transitions ->            {hash}    transitions [cache]
- * hmsh:<appid>:v:<version>:subscriptions ->          {hash}    subscriptions [cache]
- * hmsh:<appid>:x: ->                                 {xstream} when an engine is sent or reads a buffered task (engines read from their custom topic)
- * hmsh:<appid>:x:<topic> ->                          {xstream} when a worker is sent or reads a buffered task (workers read from their custom topic)
- * hmsh:<appid>:hooks ->                              {hash}    hook patterns/rules; set at compile time
- * hmsh:<appid>:signals ->                            {hash}    dynamic hook signals (hget/hdel) when resolving (always self-clean); added/removed at runtime
- * hmsh:<appid>:sym:keys: ->                          {hash}    list of symbol ranges and :cursor assigned at version deploy time for job keys
- * hmsh:<appid>:sym:keys:<activityid|$subscribes> ->  {hash}    list of symbols based upon schema enums (initially) and adaptively optimized (later) during runtime; if '$subscribes' is used as the activityid, it is a top-level `job` symbol set (for job keys)
- * hmsh:<appid>:sym:vals: ->                          {hash}    list of symbols for job values across all app versions
- */
 declare const HMNS = "hmsh";
 declare const KEYSEP = ":";
 declare const VALSEP = "::";
 declare const WEBSEP = "::";
 declare const TYPSEP = "::";
 declare class KeyService {
-    /**
-     * returns a key that can be used to access a value in the key/value store
-     * appropriate for the given key type; the keys have an implicit hierarchy
-     * and are used to organize data in the store in a tree-like structure
-     * via the use of colons as separators. The top-level entity is the hmsh manifest.
-     * This file will reveal the full scope of what is on the server (apps, versions, etc)
-     * @param namespace
-     * @param keyType
-     * @param params
-     * @returns {string}
-     */
     static mintKey(namespace: string, keyType: KeyType, params: KeyStoreParams): string;
 }
 export { KeyService, KeyType, KeyStoreParams, HMNS, KEYSEP, TYPSEP, WEBSEP, VALSEP };

package/build/modules/key.js

@@ -3,55 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VALSEP = exports.WEBSEP = exports.TYPSEP = exports.KEYSEP = exports.HMNS = exports.KeyType = exports.KeyService = void 0;
 const hotmesh_1 = require("../types/hotmesh");
 Object.defineProperty(exports, "KeyType", { enumerable: true, get: function () { return hotmesh_1.KeyType; } });
-/**
- * Keys
- *
- * hmsh ->                                            {hash}    hotmesh config {version: "0.0.1", namespace: "hmsh"}
- * hmsh:a:<appid> ->                                  {hash}    app profile { "id": "appid", "version": "2", "versions/1": "GMT", "versions/2": "GMT"}
- * hmsh:<appid>:e:<engineId> ->                       {string}  setnx to ensure only one engine of given id
- * hmsh:<appid>:w: ->                                 {zset}    work items/tasks an engine must do like garbage collect or hook a set of matching records (hookAll)
- * hmsh:<appid>:t: ->                                 {zset}    an ordered set of list (work lists) ids
- * hmsh:<appid>:t:<timeValue?> ->                     {list}    a worklist of `jobId+activityId` items that should be awakened
- * hmsh:<appid>:q: ->                                 {hash}    quorum-wide messages
- * hmsh:<appid>:q:<ngnid> ->                          {hash}    engine-targeted messages (targeted quorum-oriented message)
- * hmsh:<appid>:j:<jobid> ->                          {hash}    job data
- * hmsh:<appid>:j:<jobid>:<activityid>  ->            {hash}    job activity data (a1)
- * hmsh:<appid>:s:<jobkey>:<dateTime> ->              {hash}    job stats (general)
- * hmsh:<appid>:s:<jobkey>:<dateTime>:mdn:<field/path>:<fieldvalue> ->      {zset}    job stats (median)
- * hmsh:<appid>:s:<jobkey>:<dateTime>:index:<field/path>:<fieldvalue> ->    {list}    job stats (index of jobid[])
- * hmsh:<appid>:v:<version>:activities ->             {hash}    schemas [cache]
- * hmsh:<appid>:v:<version>:transitions ->            {hash}    transitions [cache]
- * hmsh:<appid>:v:<version>:subscriptions ->          {hash}    subscriptions [cache]
- * hmsh:<appid>:x: ->                                 {xstream} when an engine is sent or reads a buffered task (engines read from their custom topic)
- * hmsh:<appid>:x:<topic> ->                          {xstream} when a worker is sent or reads a buffered task (workers read from their custom topic)
- * hmsh:<appid>:hooks ->                              {hash}    hook patterns/rules; set at compile time
- * hmsh:<appid>:signals ->                            {hash}    dynamic hook signals (hget/hdel) when resolving (always self-clean); added/removed at runtime
- * hmsh:<appid>:sym:keys: ->                          {hash}    list of symbol ranges and :cursor assigned at version deploy time for job keys
- * hmsh:<appid>:sym:keys:<activityid|$subscribes> ->  {hash}    list of symbols based upon schema enums (initially) and adaptively optimized (later) during runtime; if '$subscribes' is used as the activityid, it is a top-level `job` symbol set (for job keys)
- * hmsh:<appid>:sym:vals: ->                          {hash}    list of symbols for job values across all app versions
- */
 const HMNS = "hmsh";
 exports.HMNS = HMNS;
-const KEYSEP = ':'; //default delimiter for keys 
+const KEYSEP = ':';
 exports.KEYSEP = KEYSEP;
-const VALSEP = '::'; //default delimiter for vals
+const VALSEP = '::';
 exports.VALSEP = VALSEP;
-const WEBSEP = '::'; //default delimiter for webhook vals
+const WEBSEP = '::';
 exports.WEBSEP = WEBSEP;
-const TYPSEP = '::'; //delimiter for ZSET task typing (how should a list be used?)
+const TYPSEP = '::';
 exports.TYPSEP = TYPSEP;
 class KeyService {
-    /**
-     * returns a key that can be used to access a value in the key/value store
-     * appropriate for the given key type; the keys have an implicit hierarchy
-     * and are used to organize data in the store in a tree-like structure
-     * via the use of colons as separators. The top-level entity is the hmsh manifest.
-     * This file will reveal the full scope of what is on the server (apps, versions, etc)
-     * @param namespace
-     * @param keyType
-     * @param params
-     * @returns {string}
-     */
     static mintKey(namespace, keyType, params) {
         switch (keyType) {
             case hotmesh_1.KeyType.HOTMESH:
@@ -83,16 +45,12 @@ class KeyService {
             case hotmesh_1.KeyType.SUBSCRIPTION_PATTERNS:
                 return `${namespace}:${params.appId}:v:${params.appVersion}:transitions`;
             case hotmesh_1.KeyType.HOOKS:
-                //`hooks` provide the pattern to resolve a value
                 return `${namespace}:${params.appId}:hooks`;
             case hotmesh_1.KeyType.SIGNALS:
-                //`signals` provide the registry of resolved values that link back to paused jobs
                 return `${namespace}:${params.appId}:signals`;
             case hotmesh_1.KeyType.SYMKEYS:
-                //`symbol keys` provide the registry of replacement values for job keys
                 return `${namespace}:${params.appId}:sym:keys:${params.activityId || ''}`;
             case hotmesh_1.KeyType.SYMVALS:
-                //`symbol vals` provide the registry of replacement values for job vals
                 return `${namespace}:${params.appId}:sym:vals:`;
             case hotmesh_1.KeyType.STREAMS:
                 return `${namespace}:${params.appId || ''}:x:${params.topic || ''}`;

package/build/modules/utils.d.ts

@@ -22,15 +22,7 @@ export declare function XSleepFor(ms: number): {
 };
 export declare function findTopKey(obj: AppTransitions, input: string): string | null;
 export declare function findSubscriptionForTrigger(obj: AppSubscriptions, value: string): string | null;
-/**
- * Get the subscription topic for the flow to which @activityId belongs.
- * TODO: resolve this value in the compiler...do not call this at runtime
- */
 export declare function getSubscriptionTopic(activityId: string, store: StoreService<RedisClient, RedisMulti>, appVID: AppVID): Promise<string | undefined>;
-/**
- * returns the 12-digit format of the iso timestamp (e.g, 202101010000); returns
- * an empty string if overridden by the user to not segment by time (infinity).
- */
 export declare function getTimeSeries(granularity: string): string;
 export declare function formatISODate(input: Date | string): string;
 export declare function getSymKey(number: number): string;

package/build/modules/utils.js

@@ -21,16 +21,13 @@ async function getSystemHealth() {
     const freeMemory = os_1.default.freemem();
     const usedMemory = totalMemory - freeMemory;
     const cpus = os_1.default.cpus();
-    // CPU load calculation remains unchanged
     const cpuLoad = cpus.map((cpu, i) => {
         const total = Object.values(cpu.times).reduce((acc, tv) => acc + tv, 0);
         const idle = cpu.times.idle;
         const usage = ((total - idle) / total) * 100;
         return { [`CPU ${i} Usage`]: `${usage.toFixed(2)}%` };
     });
-    // Wrap each systeminformation call with safeExecute
     const networkStats = await safeExecute(systeminformation_1.default.networkStats(), []);
-    // Construct the system health object with error handling in mind
     const systemHealth = {
         TotalMemoryGB: `${(totalMemory / 1024 / 1024 / 1024).toFixed(2)} GB`,
         FreeMemoryGB: `${(freeMemory / 1024 / 1024 / 1024).toFixed(2)} GB`,
@@ -77,7 +74,6 @@ function identifyRedisType(redisInstance) {
     return null;
 }
 exports.identifyRedisType = identifyRedisType;
-//todo: the polyfill methods will all be deleted in the `beta` release.
 exports.polyfill = {
     resolveActivityType(activityType) {
         if (activityType === 'activity') {
@@ -98,7 +94,6 @@ function identifyRedisTypeFromClass(redisClass) {
 exports.identifyRedisTypeFromClass = identifyRedisTypeFromClass;
 function matchesStatusCode(code, pattern) {
     if (typeof pattern === 'string') {
-        // Convert '*' wildcard to its regex equivalent (\d)
         const regexPattern = `^${pattern.replace(/\*/g, "\\d")}$`;
         return new RegExp(regexPattern).test(code.toString());
     }
@@ -110,7 +105,6 @@ function matchesStatus(status, targetStatus) {
 }
 exports.matchesStatus = matchesStatus;
 function XSleepFor(ms) {
-    //can be interrupted with `clearTimeout`
     let timerId;
     let promise = new Promise((resolve) => {
         timerId = setTimeout(resolve, ms);
@@ -137,10 +131,6 @@ function findSubscriptionForTrigger(obj, value) {
     return null;
 }
 exports.findSubscriptionForTrigger = findSubscriptionForTrigger;
-/**
- * Get the subscription topic for the flow to which @activityId belongs.
- * TODO: resolve this value in the compiler...do not call this at runtime
- */
 async function getSubscriptionTopic(activityId, store, appVID) {
     const appTransitions = await store.getTransitions(appVID);
     const appSubscriptions = await store.getSubscriptions(appVID);
@@ -149,10 +139,6 @@ async function getSubscriptionTopic(activityId, store, appVID) {
     return topic;
 }
 exports.getSubscriptionTopic = getSubscriptionTopic;
-/**
- * returns the 12-digit format of the iso timestamp (e.g, 202101010000); returns
- * an empty string if overridden by the user to not segment by time (infinity).
- */
 function getTimeSeries(granularity) {
     if (granularity.toString() === 'infinity') {
         return '0';

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.0.54",
+    "version": "0.0.56",
     "description": "Unbreakable Workflows",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -65,11 +65,14 @@
     },
     "keywords": [
         "durable workflow",
-        "hotmesh",
+        "HotMesh",
         "service mesh",
         "workflows",
         "operational data",
-        "redis"
+        "Redis",
+        "OLAP",
+        "OLTP",
+        "HTAP"
     ],
     "author": "luke.birdeau@gmail.com",
     "license": "SEE LICENSE IN LICENSE",
@@ -90,11 +93,15 @@
         "eslint": "^8.36.0",
         "ioredis": "^5.3.2",
         "jest": "^29.5.0",
-        "redis": "^4.6.6",
+        "redis": "^4.6.13",
         "rimraf": "^4.4.1",
         "ts-jest": "^29.0.5",
         "ts-node": "^10.9.1",
         "ts-node-dev": "^2.0.0",
         "typescript": "^5.0.4"
+    },
+    "peerDependencies": {
+        "redis": "^4.0.0",
+        "ioredis": "^4.0.0 || ^5.0.0"
     }
 }

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

@@ -7,9 +7,6 @@ import { JobState, JobStatus } from '../../types/job';
 import { MultiResponseFlags, RedisClient, RedisMulti } from '../../types/redis';
 import { StringAnyType } from '../../types/serializer';
 import { StreamCode, StreamData, StreamStatus } from '../../types/stream';
-/**
- * The base class for all activities
- */
 declare class Activity {
     config: ActivityType;
     data: ActivityData;
@@ -26,15 +23,7 @@ declare class Activity {
     adjacentIndex: number;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
     setLeg(leg: ActivityLeg): void;
-    /**
-     * Upon entering leg 1 of a duplexed activty, verify
-     * all aspects of the entry including job and activty state
-     */
     verifyEntry(): Promise<void>;
-    /**
-     * Upon entering leg 2 of a duplexed activty, verify
-     * all aspects of the re-entry including job and activty state
-     */
     verifyReentry(): Promise<number>;
     processEvent(status?: StreamStatus, code?: StreamCode, type?: 'hook' | 'output'): Promise<void>;
     processPending(telemetry: TelemetryService, type: 'hook' | 'output'): Promise<MultiResponseFlags>;
@@ -46,14 +35,7 @@ declare class Activity {
     mapInputData(): void;
     mapOutputData(): void;
     registerTimeout(): Promise<void>;
-    /**
-     * Any StreamMessage with a status of ERROR is bound to the activity
-     */
     bindActivityError(data: Record<string, unknown>): void;
-    /**
-     * unhandled activity errors (activities that return an ERROR StreamMessage
-     * status and have no adjacent children to transition to) are bound to the job
-     */
     bindJobError(data: Record<string, unknown>): void;
     getTriggerConfig(): Promise<ActivityType>;
     getJobStatus(): null | number;
@@ -68,12 +50,6 @@ declare class Activity {
     bindJobMetadataPaths(): string[];
     bindActivityMetadataPaths(): string[];
     getState(): Promise<void>;
-    /**
-     * if the job is created/deleted/created with the same key,
-     * the 'gid' ensures no stale messages (such as sleep delays)
-     * enter the workstream. Any message with a mismatched gid
-     * belongs to a prior job and can safely be ignored/dropped.
-     */
     assertGenerationalId(jobGID: string, msgGID?: string): void;
     initDimensionalAddress(dad: string): void;
     initSelf(context: StringAnyType): JobState;
@@ -83,10 +59,6 @@ declare class Activity {
     resolveAdjacentDad(): string;
     filterAdjacent(): Promise<StreamData[]>;
     transition(adjacencyList: StreamData[], jobStatus: JobStatus): Promise<string[]>;
-    /**
-     * A job with a vale < -100_000_000 is considered interrupted,
-     * as the interruption event decrements the job status by 1billion.
-     */
     jobWasInterrupted(jobStatus: JobStatus): boolean;
 }
 export { Activity, ActivityType };

package/build/services/activities/activity.js

@@ -10,9 +10,6 @@ const pipe_1 = require("../pipe");
 const serializer_1 = require("../serializer");
 const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
-/**
- * The base class for all activities
- */
 class Activity {
     constructor(config, data, metadata, hook, engine, context) {
         this.status = stream_1.StreamStatus.SUCCESS;
@@ -30,20 +27,12 @@ class Activity {
     setLeg(leg) {
         this.leg = leg;
     }
-    /**
-     * Upon entering leg 1 of a duplexed activty, verify
-     * all aspects of the entry including job and activty state
-     */
     async verifyEntry() {
         this.setLeg(1);
         await this.getState();
         collator_1.CollatorService.assertJobActive(this.context.metadata.js, this.context.metadata.jid, this.metadata.aid);
         await collator_1.CollatorService.notarizeEntry(this);
     }
-    /**
-     * Upon entering leg 2 of a duplexed activty, verify
-     * all aspects of the re-entry including job and activty state
-     */
     async verifyReentry() {
         const guid = this.context.metadata.guid;
         this.setLeg(2);
@@ -51,7 +40,6 @@ class Activity {
         collator_1.CollatorService.assertJobActive(this.context.metadata.js, this.context.metadata.jid, this.metadata.aid);
         return await collator_1.CollatorService.notarizeReentry(this, guid);
     }
-    //********  DUPLEX RE-ENTRY POINT  ********//
     async processEvent(status = stream_1.StreamStatus.SUCCESS, code = 200, type = 'output') {
         this.setLeg(2);
         const jid = this.context.metadata.jid;
@@ -144,7 +132,6 @@ class Activity {
         telemetry.mapActivityAttributes();
         const jobStatus = this.resolveStatus(multiResponse);
         const attrs = { 'app.job.jss': jobStatus };
-        //adjacencyList membership has already been set at this point (according to activity status)
         const messageIds = await this.transition(this.adjacencyList, jobStatus);
         if (messageIds?.length) {
             attrs['app.activity.mids'] = messageIds.join(',');
@@ -167,10 +154,6 @@ class Activity {
             if (output) {
                 for (const key in output) {
                     const f1 = key.indexOf('[');
-                    //keys with array notation suffix `somekey[]` represent
-                    //dynamically-keyed mappings whose `value` must be moved to the output.
-                    //The `value` must be an object with keys appropriate to the
-                    //notation type: `somekey[0] (array)`, `somekey[-] (mark)`, OR `somekey[_] (search)`
                     if (f1 > -1) {
                         const amount = key.substring(f1 + 1).split(']')[0];
                         if (!isNaN(Number(amount))) {
@@ -197,7 +180,6 @@ class Activity {
         }
     }
     mapOutputData() {
-        //activity YAML may include output map data that produces/extends activity output data.
         if (this.config.output?.maps) {
             const mapper = new mapper_1.MapperService(this.config.output.maps, this.context);
             const actOutData = mapper.mapRules();
@@ -207,21 +189,12 @@ class Activity {
         }
     }
     async registerTimeout() {
-        //set timeout in support of hook and/or duplex
     }
-    /**
-     * Any StreamMessage with a status of ERROR is bound to the activity
-     */
     bindActivityError(data) {
         const md = this.context[this.metadata.aid].output.metadata;
         md.err = JSON.stringify(this.data);
-        //(temporary...useful for mapping error parts in the app.yaml)
         md.$error = { ...data, is_stream_error: true };
     }
-    /**
-     * unhandled activity errors (activities that return an ERROR StreamMessage
-     * status and have no adjacent children to transition to) are bound to the job
-     */
     bindJobError(data) {
         this.context.metadata.err = JSON.stringify({ ...data, is_stream_error: true });
     }
@@ -236,7 +209,6 @@ class Activity {
         await this.store.setStatus(amount, this.context.metadata.jid, appId, multi);
     }
     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();
@@ -256,7 +228,6 @@ class Activity {
         const presets = this.authorizeEntry(state);
         this.bindDimensionalAddress(state);
         this.bindActivityState(state);
-        //symbolNames holds symkeys
         const symbolNames = [
             `$${this.config.subscribes}`,
             this.metadata.aid,
@@ -266,7 +237,6 @@ class Activity {
         return await this.store.setState(state, this.getJobStatus(), jobId, symbolNames, dIds, multi);
     }
     bindJobMetadata() {
-        //both legs of the most recently run activity (1 and 2) modify ju (job_updated)
         this.context.metadata.ju = (0, utils_1.formatISODate)(new Date());
     }
     bindActivityMetadata() {
@@ -353,7 +323,6 @@ class Activity {
         telemetry_1.TelemetryService.addTargetTelemetryPaths(consumes, this.config, this.metadata, this.leg);
         let { dad, jid } = this.context.metadata;
         const dIds = collator_1.CollatorService.getDimensionsById([...this.config.ancestors, this.metadata.aid], dad || '');
-        //`state` is a unidimensional hash; context is a tree
         const [state, _status] = await this.store.getState(jid, consumes, dIds);
         this.context = (0, utils_1.restoreHierarchy)(state);
         this.assertGenerationalId(this.context?.metadata?.gid, gid);
@@ -361,12 +330,6 @@ class Activity {
         this.initSelf(this.context);
         this.initPolicies(this.context);
     }
-    /**
-     * if the job is created/deleted/created with the same key,
-     * the 'gid' ensures no stale messages (such as sleep delays)
-     * enter the workstream. Any message with a mismatched gid
-     * belongs to a prior job and can safely be ignored/dropped.
-     */
     assertGenerationalId(jobGID, msgGID) {
         if (msgGID !== jobGID) {
             throw new errors_1.GenerationalError(jobGID, msgGID, this.context?.metadata?.jid ?? '', this.context?.metadata?.aid ?? '', this.context?.metadata?.dad ?? '');
@@ -393,10 +356,9 @@ class Activity {
         if (!self.output.metadata) {
             self.output.metadata = {};
         }
-        //prebind the updated timestamp (mappings need the time)
         self.output.metadata.au = (0, utils_1.formatISODate)(new Date());
         context['$self'] = self;
-        context['$job'] = context; //NEVER call STRINGIFY! (now circular)
+        context['$job'] = context;
         return context;
     }
     initPolicies(context) {
@@ -409,13 +371,11 @@ class Activity {
     resolveDad() {
         let dad = this.metadata.dad;
         if (this.adjacentIndex > 0) {
-            //if adjacent index > 0 the activity is cycling; replace last index with cycle index
             dad = `${dad.substring(0, dad.lastIndexOf(','))},${this.adjacentIndex}`;
         }
         return dad;
     }
     resolveAdjacentDad() {
-        //concat self and child dimension (all children (leg 1) begin life at 0)
         return `${this.resolveDad()}${collator_1.CollatorService.getDimensionalSeed(0)}`;
     }
     ;
@@ -423,7 +383,6 @@ class Activity {
         const adjacencyList = [];
         const transitions = await this.store.getTransitions(await this.engine.getVID());
         const transition = transitions[`.${this.metadata.aid}`];
-        //resolve the dimensional address for adjacent children
         const adjacentDad = this.resolveAdjacentDad();
         if (transition) {
             for (const toActivityId in transition) {
@@ -468,10 +427,6 @@ class Activity {
         }
         return mIds;
     }
-    /**
-     * A job with a vale < -100_000_000 is considered interrupted,
-     * as the interruption event decrements the job status by 1billion.
-     */
     jobWasInterrupted(jobStatus) {
         return jobStatus < -100000000;
     }

package/build/services/activities/await.js

@@ -12,7 +12,6 @@ class Await extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
     }
-    //********  INITIAL ENTRY POINT (A)  ********//
     async process() {
         this.logger.debug('await-process', { jid: this.context.metadata.jid, gid: this.context.metadata.gid, aid: this.metadata.aid });
         let telemetry;
@@ -21,15 +20,12 @@ 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
             const multi = this.store.getMulti();
-            //todo: await this.registerTimeout();
             const messageId = await this.execActivity(multi);
             await collator_1.CollatorService.authorizeReentry(this, multi);
             await this.setState(multi);
             await this.setStatus(0, multi);
             const multiResponse = await multi.exec();
-            //telemetry
             telemetry.mapActivityAttributes();
             const jobStatus = this.resolveStatus(multiResponse);
             telemetry.setActivityAttributes({

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

@@ -7,13 +7,6 @@ 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/services/activities/cycle.js

@@ -10,7 +10,6 @@ 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, gid: this.context.metadata.gid, aid: this.metadata.aid });
         let telemetry;
@@ -19,21 +18,18 @@ 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 multi = this.store.getMulti();
             await this.setState(multi);
-            await this.setStatus(0, multi); //leg 1 never changes job status
+            await this.setStatus(0, multi);
             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;
@@ -62,18 +58,7 @@ class Cycle extends activity_1.Activity {
             this.logger.debug('cycle-process-end', { jid: this.context.metadata.jid, gid: this.context.metadata.gid, 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) {
-        //Cycle activity L1 is a standin for the target ancestor L1.
-        //Input data mapping (mapInputData) allows for the 
-        //next dimensonal thread to execute with different
-        //input data than the current dimensional thread
         this.mapInputData();
         const streamData = {
             metadata: {

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

@@ -6,16 +6,10 @@ import { HookRule } from '../../types/hook';
 import { JobState, JobStatus } from '../../types/job';
 import { RedisMulti } from '../../types/redis';
 import { StreamCode, StreamStatus } from '../../types/stream';
-/**
- * Supports `signal hook`, `time hook`, and `cycle hook` patterns
- */
 declare class Hook extends Activity {
     config: HookActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
     process(): Promise<string>;
-    /**
-     * does this activity use a time-hook or web-hook
-     */
     doesHook(): boolean;
     doHook(telemetry: TelemetryService): Promise<void>;
     doPassThrough(telemetry: TelemetryService): Promise<void>;